From 9df117748eaf712afed3757204ddd9580025e8cb Mon Sep 17 00:00:00 2001 From: Alex Dupre Date: Mon, 15 Jul 2019 21:04:06 +0200 Subject: [PATCH 01/45] docs: fix consensus spec formatting (#3804) --- docs/spec/consensus/consensus.md | 50 ++++++++++++++++++-------------- 1 file changed, 28 insertions(+), 22 deletions(-) diff --git a/docs/spec/consensus/consensus.md b/docs/spec/consensus/consensus.md index ec6659c96..7b424dc6b 100644 --- a/docs/spec/consensus/consensus.md +++ b/docs/spec/consensus/consensus.md @@ -73,11 +73,11 @@ parameters over each successive round. |(When +2/3 Precommits for block found) | v | +--------------------------------------------------------------------+ - | Commit | - | | - | * Set CommitTime = now; | - | * Wait for block, then stage/save/commit block; | - +--------------------------------------------------------------------+ +| Commit | +| | +| * Set CommitTime = now; | +| * Wait for block, then stage/save/commit block; | ++--------------------------------------------------------------------+ ``` # Background Gossip @@ -131,13 +131,15 @@ liveness property. ### Propose Step (height:H,round:R) -Upon entering `Propose`: - The designated proposer proposes a block at -`(H,R)`. +Upon entering `Propose`: +- The designated proposer proposes a block at `(H,R)`. -The `Propose` step ends: - After `timeoutProposeR` after entering -`Propose`. --> goto `Prevote(H,R)` - After receiving proposal block -and all prevotes at `PoLC-Round`. --> goto `Prevote(H,R)` - After -[common exit conditions](#common-exit-conditions) +The `Propose` step ends: +- After `timeoutProposeR` after entering `Propose`. --> goto + `Prevote(H,R)` +- After receiving proposal block and all prevotes at `PoLC-Round`. --> + goto `Prevote(H,R)` +- After [common exit conditions](#common-exit-conditions) ### Prevote Step (height:H,round:R) @@ -152,10 +154,12 @@ Upon entering `Prevote`, each validator broadcasts its prevote vote. - Else, if the proposal is invalid or wasn't received on time, it prevotes ``. -The `Prevote` step ends: - After +2/3 prevotes for a particular block or -``. -->; goto `Precommit(H,R)` - After `timeoutPrevote` after -receiving any +2/3 prevotes. --> goto `Precommit(H,R)` - After -[common exit conditions](#common-exit-conditions) +The `Prevote` step ends: +- After +2/3 prevotes for a particular block or ``. -->; goto + `Precommit(H,R)` +- After `timeoutPrevote` after receiving any +2/3 prevotes. --> goto + `Precommit(H,R)` +- After [common exit conditions](#common-exit-conditions) ### Precommit Step (height:H,round:R) @@ -163,17 +167,19 @@ Upon entering `Precommit`, each validator broadcasts its precommit vote. - If the validator has a PoLC at `(H,R)` for a particular block `B`, it (re)locks (or changes lock to) and precommits `B` and sets - `LastLockRound = R`. - Else, if the validator has a PoLC at `(H,R)` for - ``, it unlocks and precommits ``. - Else, it keeps the lock - unchanged and precommits ``. + `LastLockRound = R`. +- Else, if the validator has a PoLC at `(H,R)` for ``, it unlocks + and precommits ``. +- Else, it keeps the lock unchanged and precommits ``. A precommit for `` means "I didn’t see a PoLC for this round, but I did get +2/3 prevotes and waited a bit". -The Precommit step ends: - After +2/3 precommits for ``. --> -goto `Propose(H,R+1)` - After `timeoutPrecommit` after receiving any -+2/3 precommits. --> goto `Propose(H,R+1)` - After [common exit -conditions](#common-exit-conditions) +The Precommit step ends: +- After +2/3 precommits for ``. --> goto `Propose(H,R+1)` +- After `timeoutPrecommit` after receiving any +2/3 precommits. --> goto + `Propose(H,R+1)` +- After [common exit conditions](#common-exit-conditions) ### Common exit conditions From 9867a65de7f912498636ad58f2d1f29912fe79dd Mon Sep 17 00:00:00 2001 From: Roman Useinov Date: Wed, 17 Jul 2019 06:37:27 +0200 Subject: [PATCH 02/45] abci/server: recover from app panics in socket server (#3809) fixes #3800 --- CHANGELOG_PENDING.md | 1 + abci/server/socket_server.go | 12 +++++++++++- 2 files changed, 12 insertions(+), 1 deletion(-) diff --git a/CHANGELOG_PENDING.md b/CHANGELOG_PENDING.md index fd5c4b27e..41400d892 100644 --- a/CHANGELOG_PENDING.md +++ b/CHANGELOG_PENDING.md @@ -18,5 +18,6 @@ program](https://hackerone.com/tendermint). ### FEATURES: ### IMPROVEMENTS: +- [abci] \#3809 Recover from application panics in `server/socket_server.go` to allow socket cleanup (@ruseinov) ### BUG FIXES: diff --git a/abci/server/socket_server.go b/abci/server/socket_server.go index 96cb844b7..82ce610ed 100644 --- a/abci/server/socket_server.go +++ b/abci/server/socket_server.go @@ -146,6 +146,16 @@ func (s *SocketServer) waitForClose(closeConn chan error, connID int) { func (s *SocketServer) handleRequests(closeConn chan error, conn net.Conn, responses chan<- *types.Response) { var count int var bufReader = bufio.NewReader(conn) + + defer func() { + // make sure to recover from any app-related panics to allow proper socket cleanup + r := recover() + if r != nil { + closeConn <- fmt.Errorf("recovered from panic: %v", r) + s.appMtx.Unlock() + } + }() + for { var req = &types.Request{} @@ -154,7 +164,7 @@ func (s *SocketServer) handleRequests(closeConn chan error, conn net.Conn, respo if err == io.EOF { closeConn <- err } else { - closeConn <- fmt.Errorf("Error reading message: %v", err.Error()) + closeConn <- fmt.Errorf("error reading message: %v", err) } return } From 8da43508f8405ea77db51ece2615f5f9338002b6 Mon Sep 17 00:00:00 2001 From: Marko Date: Wed, 17 Jul 2019 09:49:01 +0200 Subject: [PATCH 03/45] abci/client: fix DATA RACE in gRPC client (#3798) * Remove go func {}() closes #357 - Remove go func(){}() that caused race condiditon - To reproduce - add -race in make file to `install_abci` - Remove `CGO_ENABLED=0` & add -race to `install` Signed-off-by: Marko Baricevic * remove -race * fix data race also, reorder callbacks similarly to socket client --- abci/client/grpc_client.go | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/abci/client/grpc_client.go b/abci/client/grpc_client.go index 23d790550..8c444abc5 100644 --- a/abci/client/grpc_client.go +++ b/abci/client/grpc_client.go @@ -228,18 +228,22 @@ func (cli *grpcClient) finishAsyncCall(req *types.Request, res *types.Response) reqres.Done() // Release waiters reqres.SetDone() // so reqRes.SetCallback will run the callback - // go routine for callbacks + // goroutine for callbacks go func() { - // Notify reqRes listener if set - if cb := reqres.GetCallback(); cb != nil { - cb(res) - } + cli.mtx.Lock() + defer cli.mtx.Unlock() // Notify client listener if set if cli.resCb != nil { cli.resCb(reqres.Request, res) } + + // Notify reqRes listener if set + if cb := reqres.GetCallback(); cb != nil { + cb(res) + } }() + return reqres } From c264db339e526658a01375da10dbb14b013ce3de Mon Sep 17 00:00:00 2001 From: Anton Kaliaev Date: Thu, 18 Jul 2019 15:15:14 +0400 Subject: [PATCH 04/45] docs: "Writing a built-in Tendermint Core application in Go" guide (#3608) * docs: go built-in guide * fix package imports, add badger db, simplify Query * newTendermint function * working example * finish the first guide * add one more note * add the second Golang guide - external ABCI app * fix typos --- docs/guides/go-built-in.md | 630 +++++++++++++++++++++++++++++++++++++ docs/guides/go.md | 514 ++++++++++++++++++++++++++++++ 2 files changed, 1144 insertions(+) create mode 100644 docs/guides/go-built-in.md create mode 100644 docs/guides/go.md diff --git a/docs/guides/go-built-in.md b/docs/guides/go-built-in.md new file mode 100644 index 000000000..a0c76c9e9 --- /dev/null +++ b/docs/guides/go-built-in.md @@ -0,0 +1,630 @@ +# 1 Guide Assumptions + +This guide is designed for beginners who want to get started with a Tendermint +Core application from scratch. It does not assume that you have any prior +experience with Tendermint Core. + +Tendermint Core is Byzantine Fault Tolerant (BFT) middleware that takes a state +transition machine - written in any programming language - and securely +replicates it on many machines. + +Although Tendermint Core is written in the Golang programming language, prior +knowledge of it is not required for this guide. You can learn it as we go due +to it's simplicity. However, you may want to go through [Learn X in Y minutes +Where X=Go](https://learnxinyminutes.com/docs/go/) first to familiarize +yourself with the syntax. + +By following along with this guide, you'll create a Tendermint Core project +called kvstore, a (very) simple distributed BFT key-value store. + +# 1 Creating a built-in application in Go + +Running your application inside the same process as Tendermint Core will give +you the best possible performance. + +For other languages, your application have to communicate with Tendermint Core +through a TCP, Unix domain socket or gRPC. + +## 1.1 Installing Go + +Please refer to [the official guide for installing +Go](https://golang.org/doc/install). + +Verify that you have the latest version of Go installed: + +```sh +$ go version +go version go1.12.7 darwin/amd64 +``` + +Make sure you have `$GOPATH` environment variable set: + +```sh +$ echo $GOPATH +/Users/melekes/go +``` + +## 1.2 Creating a new Go project + +We'll start by creating a new Go project. + +```sh +$ mkdir -p $GOPATH/src/github.com/me/kvstore +$ cd $GOPATH/src/github.com/me/kvstore +``` + +Inside the example directory create a `main.go` file with the following content: + +```go +package main + +import ( + "fmt" +) + +func main() { + fmt.Println("Hello, Tendermint Core") +} +``` + +When run, this should print "Hello, Tendermint Core" to the standard output. + +```sh +$ go run main.go +Hello, Tendermint Core +``` + +## 1.3 Writing a Tendermint Core application + +Tendermint Core communicates with the application through the Application +BlockChain Interface (ABCI). All message types are defined in the [protobuf +file](https://github.com/tendermint/tendermint/blob/develop/abci/types/types.proto). +This allows Tendermint Core to run applications written in any programming +language. + +Create a file called `app.go` with the following content: + +```go +package main + +import ( + abcitypes "github.com/tendermint/tendermint/abci/types" +) + +type KVStoreApplication struct {} + +var _ abcitypes.Application = (*KVStoreApplication)(nil) + +func NewKVStoreApplication() *KVStoreApplication { + return &KVStoreApplication{} +} + +func (KVStoreApplication) Info(req abcitypes.RequestInfo) abcitypes.ResponseInfo { + return abcitypes.ResponseInfo{} +} + +func (KVStoreApplication) SetOption(req abcitypes.RequestSetOption) abcitypes.ResponseSetOption { + return abcitypes.ResponseSetOption{} +} + +func (KVStoreApplication) DeliverTx(req abcitypes.RequestDeliverTx) abcitypes.ResponseDeliverTx { + return abcitypes.ResponseDeliverTx{Code: 0} +} + +func (KVStoreApplication) CheckTx(req abcitypes.RequestCheckTx) abcitypes.ResponseCheckTx { + return abcitypes.ResponseCheckTx{Code: 0} +} + +func (KVStoreApplication) Commit() abcitypes.ResponseCommit { + return abcitypes.ResponseCommit{} +} + +func (KVStoreApplication) Query(req abcitypes.RequestQuery) abcitypes.ResponseQuery { + return abcitypes.ResponseQuery{Code: 0} +} + +func (KVStoreApplication) InitChain(req abcitypes.RequestInitChain) abcitypes.ResponseInitChain { + return abcitypes.ResponseInitChain{} +} + +func (KVStoreApplication) BeginBlock(req abcitypes.RequestBeginBlock) abcitypes.ResponseBeginBlock { + return abcitypes.ResponseBeginBlock{} +} + +func (KVStoreApplication) EndBlock(req abcitypes.RequestEndBlock) abcitypes.ResponseEndBlock { + return abcitypes.ResponseEndBlock{} +} +``` + +Now I will go through each method explaining when it's called and adding +required business logic. + +### 1.3.1 CheckTx + +When a new transaction is added to the Tendermint Core, it will ask the +application to check it (validate the format, signatures, etc.). + +```go +func (app *KVStoreApplication) isValid(tx []byte) (code uint32) { + // check format + parts := bytes.Split(tx, []byte("=")) + if len(parts) != 2 { + return 1 + } + + key, value := parts[0], parts[1] + + // check if the same key=value already exists + err := app.db.View(func(txn *badger.Txn) error { + item, err := txn.Get(key) + if err != nil && err != badger.ErrKeyNotFound { + return err + } + if err == nil { + return item.Value(func(val []byte) error { + if bytes.Equal(val, value) { + code = 2 + } + return nil + }) + } + return nil + }) + if err != nil { + panic(err) + } + + return code +} + +func (app *KVStoreApplication) CheckTx(req abcitypes.RequestCheckTx) abcitypes.ResponseCheckTx { + code := app.isValid(req.Tx) + return abcitypes.ResponseCheckTx{Code: code, GasWanted: 1} +} +``` + +Don't worry if this does not compile yet. + +If the transaction does not have a form of `{bytes}={bytes}`, we return `1` +code. When the same key=value already exist (same key and value), we return `2` +code. For others, we return a zero code indicating that they are valid. + +Note that anything with non-zero code will be considered invalid (`-1`, `100`, +etc.) by Tendermint Core. + +Valid transactions will eventually be committed given they are not too big and +have enough gas. To learn more about gas, check out ["the +specification"](https://tendermint.com/docs/spec/abci/apps.html#gas). + +For the underlying key-value store we'll use +[badger](https://github.com/dgraph-io/badger), which is an embeddable, +persistent and fast key-value (KV) database. + +```go +import "github.com/dgraph-io/badger" + +type KVStoreApplication struct { + db *badger.DB + currentBatch *badger.Txn +} + +func NewKVStoreApplication(db *badger.DB) *KVStoreApplication { + return &KVStoreApplication{ + db: db, + } +} +``` + +### 1.3.2 BeginBlock -> DeliverTx -> EndBlock -> Commit + +When Tendermint Core has decided on the block, it's transfered to the +application in 3 parts: `BeginBlock`, one `DeliverTx` per transaction and +`EndBlock` in the end. DeliverTx are being transfered asynchronously, but the +responses are expected to come in order. + +``` +func (app *KVStoreApplication) BeginBlock(req abcitypes.RequestBeginBlock) abcitypes.ResponseBeginBlock { + app.currentBatch = app.db.NewTransaction(true) + return abcitypes.ResponseBeginBlock{} +} + +``` + +Here we create a batch, which will store block's transactions. + +```go +func (app *KVStoreApplication) DeliverTx(req abcitypes.RequestDeliverTx) abcitypes.ResponseDeliverTx { + code := app.isValid(req.Tx) + if code != 0 { + return abcitypes.ResponseDeliverTx{Code: code} + } + + parts := bytes.Split(req.Tx, []byte("=")) + key, value := parts[0], parts[1] + + err := app.currentBatch.Set(key, value) + if err != nil { + panic(err) + } + + return abcitypes.ResponseDeliverTx{Code: 0} +} +``` + +If the transaction is badly formatted or the same key=value already exist, we +again return the non-zero code. Otherwise, we add it to the current batch. + +In the current design, a block can include incorrect transactions (those who +passed CheckTx, but failed DeliverTx or transactions included by the proposer +directly). This is done for performance reasons. + +Note we can't commit transactions inside the `DeliverTx` because in such case +`Query`, which may be called in parallel, will return inconsistent data (i.e. +it will report that some value already exist even when the actual block was not +yet committed). + +`Commit` instructs the application to persist the new state. + +```go +func (app *KVStoreApplication) Commit() abcitypes.ResponseCommit { + app.currentBatch.Commit() + return abcitypes.ResponseCommit{Data: []byte{}} +} +``` + +### 1.3.3 Query + +Now, when the client wants to know whenever a particular key/value exist, it +will call Tendermint Core RPC `/abci_query` endpoint, which in turn will call +the application's `Query` method. + +Applications are free to provide their own APIs. But by using Tendermint Core +as a proxy, clients (including [light client +package](https://godoc.org/github.com/tendermint/tendermint/lite)) can leverage +the unified API across different applications. Plus they won't have to call the +otherwise separate Tendermint Core API for additional proofs. + +Note we don't include a proof here. + +```go +func (app *KVStoreApplication) Query(reqQuery abcitypes.RequestQuery) (resQuery abcitypes.ResponseQuery) { + resQuery.Key = reqQuery.Data + err := app.db.View(func(txn *badger.Txn) error { + item, err := txn.Get(reqQuery.Data) + if err != nil && err != badger.ErrKeyNotFound { + return err + } + if err == badger.ErrKeyNotFound { + resQuery.Log = "does not exist" + } else { + return item.Value(func(val []byte) error { + resQuery.Log = "exists" + resQuery.Value = val + return nil + }) + } + return nil + }) + if err != nil { + panic(err) + } + return +} +``` + +The complete specification can be found +[here](https://tendermint.com/docs/spec/abci/). + +## 1.4 Starting an application and a Tendermint Core instance in the same process + +Put the following code into the "main.go" file: + +```go +package main + +import ( + "flag" + "fmt" + "os" + "os/signal" + "path/filepath" + "syscall" + + "github.com/dgraph-io/badger" + "github.com/pkg/errors" + "github.com/spf13/viper" + + abci "github.com/tendermint/tendermint/abci/types" + cfg "github.com/tendermint/tendermint/config" + tmflags "github.com/tendermint/tendermint/libs/cli/flags" + "github.com/tendermint/tendermint/libs/log" + nm "github.com/tendermint/tendermint/node" + "github.com/tendermint/tendermint/p2p" + "github.com/tendermint/tendermint/privval" + "github.com/tendermint/tendermint/proxy" +) + +var configFile string + +func init() { + flag.StringVar(&configFile, "config", "$HOME/.tendermint/config/config.toml", "Path to config.toml") +} + +func main() { + db, err := badger.Open(badger.DefaultOptions("/tmp/badger")) + if err != nil { + fmt.Fprintf(os.Stderr, "failed to open badger db: %v", err) + os.Exit(1) + } + defer db.Close() + app := NewKVStoreApplication(db) + + flag.Parse() + + node, err := newTendermint(app, configFile) + if err != nil { + fmt.Fprintf(os.Stderr, "%v", err) + os.Exit(2) + } + + node.Start() + defer func() { + node.Stop() + node.Wait() + }() + + c := make(chan os.Signal, 1) + signal.Notify(c, os.Interrupt, syscall.SIGTERM) + <-c + os.Exit(0) +} + +func newTendermint(app abci.Application, configFile string) (*nm.Node, error) { + // read config + config := cfg.DefaultConfig() + config.RootDir = filepath.Dir(filepath.Dir(configFile)) + viper.SetConfigFile(configFile) + if err := viper.ReadInConfig(); err != nil { + return nil, errors.Wrap(err, "viper failed to read config file") + } + if err := viper.Unmarshal(config); err != nil { + return nil, errors.Wrap(err, "viper failed to unmarshal config") + } + if err := config.ValidateBasic(); err != nil { + return nil, errors.Wrap(err, "config is invalid") + } + + // create logger + logger := log.NewTMLogger(log.NewSyncWriter(os.Stdout)) + var err error + logger, err = tmflags.ParseLogLevel(config.LogLevel, logger, cfg.DefaultLogLevel()) + if err != nil { + return nil, errors.Wrap(err, "failed to parse log level") + } + + // read private validator + pv := privval.LoadFilePV( + config.PrivValidatorKeyFile(), + config.PrivValidatorStateFile(), + ) + + // read node key + nodeKey, err := p2p.LoadNodeKey(config.NodeKeyFile()) + if err != nil { + return nil, errors.Wrap(err, "failed to load node's key") + } + + // create node + node, err := nm.NewNode( + config, + pv, + nodeKey, + proxy.NewLocalClientCreator(app), + nm.DefaultGenesisDocProviderFunc(config), + nm.DefaultDBProvider, + nm.DefaultMetricsProvider(config.Instrumentation), + logger) + if err != nil { + return nil, errors.Wrap(err, "failed to create new Tendermint node") + } + + return node, nil +} +``` + +This is a huge blob of code, so let's break it down into pieces. + +First, we initialize the Badger database and create an app instance: + +```go +db, err := badger.Open(badger.DefaultOptions("/tmp/badger")) +if err != nil { + fmt.Fprintf(os.Stderr, "failed to open badger db: %v", err) + os.Exit(1) +} +defer db.Close() +app := NewKVStoreApplication(db) +``` + +Then we use it to create a Tendermint Core `Node` instance: + +```go +flag.Parse() + +node, err := newTendermint(app, configFile) +if err != nil { + fmt.Fprintf(os.Stderr, "%v", err) + os.Exit(2) +} + +... + +// create node +node, err := nm.NewNode( + config, + pv, + nodeKey, + proxy.NewLocalClientCreator(app), + nm.DefaultGenesisDocProviderFunc(config), + nm.DefaultDBProvider, + nm.DefaultMetricsProvider(config.Instrumentation), + logger) +if err != nil { + return nil, errors.Wrap(err, "failed to create new Tendermint node") +} +``` + +`NewNode` requires a few things including a configuration file, a private +validator, a node key and a few others in order to construct the full node. + +Note we use `proxy.NewLocalClientCreator` here to create a local client instead +of one communicating through a socket or gRPC. + +[viper](https://github.com/spf13/viper) is being used for reading the config, +which we will generate later using the `tendermint init` command. + +```go +config := cfg.DefaultConfig() +config.RootDir = filepath.Dir(filepath.Dir(configFile)) +viper.SetConfigFile(configFile) +if err := viper.ReadInConfig(); err != nil { + return nil, errors.Wrap(err, "viper failed to read config file") +} +if err := viper.Unmarshal(config); err != nil { + return nil, errors.Wrap(err, "viper failed to unmarshal config") +} +if err := config.ValidateBasic(); err != nil { + return nil, errors.Wrap(err, "config is invalid") +} +``` + +We use `FilePV`, which is a private validator (i.e. thing which signs consensus +messages). Normally, you would use `SignerRemote` to connect to an external +[HSM](https://kb.certus.one/hsm.html). + +```go +pv := privval.LoadFilePV( + config.PrivValidatorKeyFile(), + config.PrivValidatorStateFile(), +) + +``` + +`nodeKey` is needed to identify the node in a p2p network. + +```go +nodeKey, err := p2p.LoadNodeKey(config.NodeKeyFile()) +if err != nil { + return nil, errors.Wrap(err, "failed to load node's key") +} +``` + +As for the logger, we use the build-in library, which provides a nice +abstraction over [go-kit's +logger](https://github.com/go-kit/kit/tree/master/log). + +```go +logger := log.NewTMLogger(log.NewSyncWriter(os.Stdout)) +var err error +logger, err = tmflags.ParseLogLevel(config.LogLevel, logger, cfg.DefaultLogLevel()) +if err != nil { + return nil, errors.Wrap(err, "failed to parse log level") +} +``` + +Finally, we start the node and add some signal handling to gracefully stop it +upon receiving SIGTERM or Ctrl-C. + +```go +node.Start() +defer func() { + node.Stop() + node.Wait() +}() + +c := make(chan os.Signal, 1) +signal.Notify(c, os.Interrupt, syscall.SIGTERM) +<-c +os.Exit(0) +``` + +## 1.5 Getting Up and Running + +We are going to use [Go modules](https://github.com/golang/go/wiki/Modules) for +dependency management. + +```sh +$ export GO111MODULE=on +$ go mod init github.com/me/example +$ go build +``` + +This should build the binary. + +To create a default configuration, nodeKey and private validator files, let's +execute `tendermint init`. But before we do that, we will need to install +Tendermint Core. + +```sh +$ rm -rf /tmp/example +$ cd $GOPATH/src/github.com/tendermint/tendermint +$ make install +$ TMHOME="/tmp/example" tendermint init + +I[2019-07-16|18:40:36.480] Generated private validator module=main keyFile=/tmp/example/config/priv_validator_key.json stateFile=/tmp/example2/data/priv_validator_state.json +I[2019-07-16|18:40:36.481] Generated node key module=main path=/tmp/example/config/node_key.json +I[2019-07-16|18:40:36.482] Generated genesis file module=main path=/tmp/example/config/genesis.json +``` + +We are ready to start our application: + +```sh +$ ./example -config "/tmp/example/config/config.toml" + +badger 2019/07/16 18:42:25 INFO: All 0 tables opened in 0s +badger 2019/07/16 18:42:25 INFO: Replaying file id: 0 at offset: 0 +badger 2019/07/16 18:42:25 INFO: Replay took: 695.227s +E[2019-07-16|18:42:25.818] Couldn't connect to any seeds module=p2p +I[2019-07-16|18:42:26.853] Executed block module=state height=1 validTxs=0 invalidTxs=0 +I[2019-07-16|18:42:26.865] Committed state module=state height=1 txs=0 appHash= +``` + +Now open another tab in your terminal and try sending a transaction: + +```sh +$ curl -s 'localhost:26657/broadcast_tx_commit?tx="tendermint=rocks"' +{ + "jsonrpc": "2.0", + "id": "", + "result": { + "check_tx": { + "gasWanted": "1" + }, + "deliver_tx": {}, + "hash": "1B3C5A1093DB952C331B1749A21DCCBB0F6C7F4E0055CD04D16346472FC60EC6", + "height": "128" + } +} +``` + +Response should contain the height where this transaction was committed. + +Now let's check if the given key now exists and its value: + +``` +$ curl -s 'localhost:26657/abci_query?data="tendermint"' +{ + "jsonrpc": "2.0", + "id": "", + "result": { + "response": { + "log": "exists", + "key": "dGVuZGVybWludA==", + "value": "cm9ja3M=" + } + } +} +``` + +"dGVuZGVybWludA==" and "cm9ja3M=" are the base64-encoding of the ASCII of +"tendermint" and "rocks" accordingly. diff --git a/docs/guides/go.md b/docs/guides/go.md new file mode 100644 index 000000000..abda07955 --- /dev/null +++ b/docs/guides/go.md @@ -0,0 +1,514 @@ +# 1 Guide Assumptions + +This guide is designed for beginners who want to get started with a Tendermint +Core application from scratch. It does not assume that you have any prior +experience with Tendermint Core. + +Tendermint Core is Byzantine Fault Tolerant (BFT) middleware that takes a state +transition machine - written in any programming language - and securely +replicates it on many machines. + +Although Tendermint Core is written in the Golang programming language, prior +knowledge of it is not required for this guide. You can learn it as we go due +to it's simplicity. However, you may want to go through [Learn X in Y minutes +Where X=Go](https://learnxinyminutes.com/docs/go/) first to familiarize +yourself with the syntax. + +By following along with this guide, you'll create a Tendermint Core project +called kvstore, a (very) simple distributed BFT key-value store. + +# 1 Creating an application in Go + +To get maximum performance it is better to run your application alongside +Tendermint Core. [Cosmos SDK](https://github.com/cosmos/cosmos-sdk) is written +this way. Please refer to [Writing a built-in Tendermint Core application in +Go](./go-built-in.md) guide for details. + +Having a separate application might give you better security guarantees as two +processes would be communicating via established binary protocol. Tendermint +Core will not have access to application's state. + +## 1.1 Installing Go + +Please refer to [the official guide for installing +Go](https://golang.org/doc/install). + +Verify that you have the latest version of Go installed: + +```sh +$ go version +go version go1.12.7 darwin/amd64 +``` + +Make sure you have `$GOPATH` environment variable set: + +```sh +$ echo $GOPATH +/Users/melekes/go +``` + +## 1.2 Creating a new Go project + +We'll start by creating a new Go project. + +```sh +$ mkdir -p $GOPATH/src/github.com/me/kvstore +$ cd $GOPATH/src/github.com/me/kvstore +``` + +Inside the example directory create a `main.go` file with the following content: + +```go +package main + +import ( + "fmt" +) + +func main() { + fmt.Println("Hello, Tendermint Core") +} +``` + +When run, this should print "Hello, Tendermint Core" to the standard output. + +```sh +$ go run main.go +Hello, Tendermint Core +``` + +## 1.3 Writing a Tendermint Core application + +Tendermint Core communicates with the application through the Application +BlockChain Interface (ABCI). All message types are defined in the [protobuf +file](https://github.com/tendermint/tendermint/blob/develop/abci/types/types.proto). +This allows Tendermint Core to run applications written in any programming +language. + +Create a file called `app.go` with the following content: + +```go +package main + +import ( + abcitypes "github.com/tendermint/tendermint/abci/types" +) + +type KVStoreApplication struct {} + +var _ abcitypes.Application = (*KVStoreApplication)(nil) + +func NewKVStoreApplication() *KVStoreApplication { + return &KVStoreApplication{} +} + +func (KVStoreApplication) Info(req abcitypes.RequestInfo) abcitypes.ResponseInfo { + return abcitypes.ResponseInfo{} +} + +func (KVStoreApplication) SetOption(req abcitypes.RequestSetOption) abcitypes.ResponseSetOption { + return abcitypes.ResponseSetOption{} +} + +func (KVStoreApplication) DeliverTx(req abcitypes.RequestDeliverTx) abcitypes.ResponseDeliverTx { + return abcitypes.ResponseDeliverTx{Code: 0} +} + +func (KVStoreApplication) CheckTx(req abcitypes.RequestCheckTx) abcitypes.ResponseCheckTx { + return abcitypes.ResponseCheckTx{Code: 0} +} + +func (KVStoreApplication) Commit() abcitypes.ResponseCommit { + return abcitypes.ResponseCommit{} +} + +func (KVStoreApplication) Query(req abcitypes.RequestQuery) abcitypes.ResponseQuery { + return abcitypes.ResponseQuery{Code: 0} +} + +func (KVStoreApplication) InitChain(req abcitypes.RequestInitChain) abcitypes.ResponseInitChain { + return abcitypes.ResponseInitChain{} +} + +func (KVStoreApplication) BeginBlock(req abcitypes.RequestBeginBlock) abcitypes.ResponseBeginBlock { + return abcitypes.ResponseBeginBlock{} +} + +func (KVStoreApplication) EndBlock(req abcitypes.RequestEndBlock) abcitypes.ResponseEndBlock { + return abcitypes.ResponseEndBlock{} +} +``` + +Now I will go through each method explaining when it's called and adding +required business logic. + +### 1.3.1 CheckTx + +When a new transaction is added to the Tendermint Core, it will ask the +application to check it (validate the format, signatures, etc.). + +```go +func (app *KVStoreApplication) isValid(tx []byte) (code uint32) { + // check format + parts := bytes.Split(tx, []byte("=")) + if len(parts) != 2 { + return 1 + } + + key, value := parts[0], parts[1] + + // check if the same key=value already exists + err := app.db.View(func(txn *badger.Txn) error { + item, err := txn.Get(key) + if err != nil && err != badger.ErrKeyNotFound { + return err + } + if err == nil { + return item.Value(func(val []byte) error { + if bytes.Equal(val, value) { + code = 2 + } + return nil + }) + } + return nil + }) + if err != nil { + panic(err) + } + + return code +} + +func (app *KVStoreApplication) CheckTx(req abcitypes.RequestCheckTx) abcitypes.ResponseCheckTx { + code := app.isValid(req.Tx) + return abcitypes.ResponseCheckTx{Code: code, GasWanted: 1} +} +``` + +Don't worry if this does not compile yet. + +If the transaction does not have a form of `{bytes}={bytes}`, we return `1` +code. When the same key=value already exist (same key and value), we return `2` +code. For others, we return a zero code indicating that they are valid. + +Note that anything with non-zero code will be considered invalid (`-1`, `100`, +etc.) by Tendermint Core. + +Valid transactions will eventually be committed given they are not too big and +have enough gas. To learn more about gas, check out ["the +specification"](https://tendermint.com/docs/spec/abci/apps.html#gas). + +For the underlying key-value store we'll use +[badger](https://github.com/dgraph-io/badger), which is an embeddable, +persistent and fast key-value (KV) database. + +```go +import "github.com/dgraph-io/badger" + +type KVStoreApplication struct { + db *badger.DB + currentBatch *badger.Txn +} + +func NewKVStoreApplication(db *badger.DB) *KVStoreApplication { + return &KVStoreApplication{ + db: db, + } +} +``` + +### 1.3.2 BeginBlock -> DeliverTx -> EndBlock -> Commit + +When Tendermint Core has decided on the block, it's transfered to the +application in 3 parts: `BeginBlock`, one `DeliverTx` per transaction and +`EndBlock` in the end. DeliverTx are being transfered asynchronously, but the +responses are expected to come in order. + +``` +func (app *KVStoreApplication) BeginBlock(req abcitypes.RequestBeginBlock) abcitypes.ResponseBeginBlock { + app.currentBatch = app.db.NewTransaction(true) + return abcitypes.ResponseBeginBlock{} +} + +``` + +Here we create a batch, which will store block's transactions. + +```go +func (app *KVStoreApplication) DeliverTx(req abcitypes.RequestDeliverTx) abcitypes.ResponseDeliverTx { + code := app.isValid(req.Tx) + if code != 0 { + return abcitypes.ResponseDeliverTx{Code: code} + } + + parts := bytes.Split(req.Tx, []byte("=")) + key, value := parts[0], parts[1] + + err := app.currentBatch.Set(key, value) + if err != nil { + panic(err) + } + + return abcitypes.ResponseDeliverTx{Code: 0} +} +``` + +If the transaction is badly formatted or the same key=value already exist, we +again return the non-zero code. Otherwise, we add it to the current batch. + +In the current design, a block can include incorrect transactions (those who +passed CheckTx, but failed DeliverTx or transactions included by the proposer +directly). This is done for performance reasons. + +Note we can't commit transactions inside the `DeliverTx` because in such case +`Query`, which may be called in parallel, will return inconsistent data (i.e. +it will report that some value already exist even when the actual block was not +yet committed). + +`Commit` instructs the application to persist the new state. + +```go +func (app *KVStoreApplication) Commit() abcitypes.ResponseCommit { + app.currentBatch.Commit() + return abcitypes.ResponseCommit{Data: []byte{}} +} +``` + +### 1.3.3 Query + +Now, when the client wants to know whenever a particular key/value exist, it +will call Tendermint Core RPC `/abci_query` endpoint, which in turn will call +the application's `Query` method. + +Applications are free to provide their own APIs. But by using Tendermint Core +as a proxy, clients (including [light client +package](https://godoc.org/github.com/tendermint/tendermint/lite)) can leverage +the unified API across different applications. Plus they won't have to call the +otherwise separate Tendermint Core API for additional proofs. + +Note we don't include a proof here. + +```go +func (app *KVStoreApplication) Query(reqQuery abcitypes.RequestQuery) (resQuery abcitypes.ResponseQuery) { + resQuery.Key = reqQuery.Data + err := app.db.View(func(txn *badger.Txn) error { + item, err := txn.Get(reqQuery.Data) + if err != nil && err != badger.ErrKeyNotFound { + return err + } + if err == badger.ErrKeyNotFound { + resQuery.Log = "does not exist" + } else { + return item.Value(func(val []byte) error { + resQuery.Log = "exists" + resQuery.Value = val + return nil + }) + } + return nil + }) + if err != nil { + panic(err) + } + return +} +``` + +The complete specification can be found +[here](https://tendermint.com/docs/spec/abci/). + +## 1.4 Starting an application and a Tendermint Core instances + +Put the following code into the "main.go" file: + +```go +package main + +import ( + "flag" + "fmt" + "os" + "os/signal" + "syscall" + + "github.com/dgraph-io/badger" + + abciserver "github.com/tendermint/tendermint/abci/server" + "github.com/tendermint/tendermint/libs/log" +) + +var socketAddr string + +func init() { + flag.StringVar(&socketAddr, "socket-addr", "unix://example.sock", "Unix domain socket address") +} + +func main() { + db, err := badger.Open(badger.DefaultOptions("/tmp/badger")) + if err != nil { + fmt.Fprintf(os.Stderr, "failed to open badger db: %v", err) + os.Exit(1) + } + defer db.Close() + app := NewKVStoreApplication(db) + + flag.Parse() + + logger := log.NewTMLogger(log.NewSyncWriter(os.Stdout)) + + server := abciserver.NewSocketServer(socketAddr, app) + server.SetLogger(logger) + if err := server.Start(); err != nil { + fmt.Fprintf(os.Stderr, "error starting socket server: %v", err) + os.Exit(1) + } + defer server.Stop() + + c := make(chan os.Signal, 1) + signal.Notify(c, os.Interrupt, syscall.SIGTERM) + <-c + os.Exit(0) +} +``` + +This is a huge blob of code, so let's break it down into pieces. + +First, we initialize the Badger database and create an app instance: + +```go +db, err := badger.Open(badger.DefaultOptions("/tmp/badger")) +if err != nil { + fmt.Fprintf(os.Stderr, "failed to open badger db: %v", err) + os.Exit(1) +} +defer db.Close() +app := NewKVStoreApplication(db) +``` + +Then we start the ABCI server and add some signal handling to gracefully stop +it upon receiving SIGTERM or Ctrl-C. Tendermint Core will act as a client, +which connects to our server and send us transactions and other messages. + +```go +server := abciserver.NewSocketServer(socketAddr, app) +server.SetLogger(logger) +if err := server.Start(); err != nil { + fmt.Fprintf(os.Stderr, "error starting socket server: %v", err) + os.Exit(1) +} +defer server.Stop() + +c := make(chan os.Signal, 1) +signal.Notify(c, os.Interrupt, syscall.SIGTERM) +<-c +os.Exit(0) +``` + +## 1.5 Getting Up and Running + +We are going to use [Go modules](https://github.com/golang/go/wiki/Modules) for +dependency management. + +```sh +$ export GO111MODULE=on +$ go mod init github.com/me/example +$ go build +``` + +This should build the binary. + +To create a default configuration, nodeKey and private validator files, let's +execute `tendermint init`. But before we do that, we will need to install +Tendermint Core. + +```sh +$ rm -rf /tmp/example +$ cd $GOPATH/src/github.com/tendermint/tendermint +$ make install +$ TMHOME="/tmp/example" tendermint init + +I[2019-07-16|18:20:36.480] Generated private validator module=main keyFile=/tmp/example/config/priv_validator_key.json stateFile=/tmp/example2/data/priv_validator_state.json +I[2019-07-16|18:20:36.481] Generated node key module=main path=/tmp/example/config/node_key.json +I[2019-07-16|18:20:36.482] Generated genesis file module=main path=/tmp/example/config/genesis.json +``` + +Feel free to explore the generated files, which can be found at +`/tmp/example/config` directory. Documentation on the config can be found +[here](https://tendermint.com/docs/tendermint-core/configuration.html). + +We are ready to start our application: + +```sh +$ rm example.sock +$ ./example + +badger 2019/07/16 18:25:11 INFO: All 0 tables opened in 0s +badger 2019/07/16 18:25:11 INFO: Replaying file id: 0 at offset: 0 +badger 2019/07/16 18:25:11 INFO: Replay took: 300.4s +I[2019-07-16|18:25:11.523] Starting ABCIServer impl=ABCIServ +``` + +Then we need to start Tendermint Core and point it to our application. Staying +within the application directory execute: + +```sh +$ TMHOME="/tmp/example" tendermint node --proxy_app=unix://example.sock + +I[2019-07-16|18:26:20.362] Version info module=main software=0.32.1 block=10 p2p=7 +I[2019-07-16|18:26:20.383] Starting Node module=main impl=Node +E[2019-07-16|18:26:20.392] Couldn't connect to any seeds module=p2p +I[2019-07-16|18:26:20.394] Started node module=main nodeInfo="{ProtocolVersion:{P2P:7 Block:10 App:0} ID_:8dab80770ae8e295d4ce905d86af78c4ff634b79 ListenAddr:tcp://0.0.0.0:26656 Network:test-chain-nIO96P Version:0.32.1 Channels:4020212223303800 Moniker:app48.fun-box.ru Other:{TxIndex:on RPCAddress:tcp://127.0.0.1:26657}}" +I[2019-07-16|18:26:21.440] Executed block module=state height=1 validTxs=0 invalidTxs=0 +I[2019-07-16|18:26:21.446] Committed state module=state height=1 txs=0 appHash= +``` + +This should start the full node and connect to our ABCI application. + +``` +I[2019-07-16|18:25:11.525] Waiting for new connection... +I[2019-07-16|18:26:20.329] Accepted a new connection +I[2019-07-16|18:26:20.329] Waiting for new connection... +I[2019-07-16|18:26:20.330] Accepted a new connection +I[2019-07-16|18:26:20.330] Waiting for new connection... +I[2019-07-16|18:26:20.330] Accepted a new connection +``` + +Now open another tab in your terminal and try sending a transaction: + +```sh +$ curl -s 'localhost:26657/broadcast_tx_commit?tx="tendermint=rocks"' +{ + "jsonrpc": "2.0", + "id": "", + "result": { + "check_tx": { + "gasWanted": "1" + }, + "deliver_tx": {}, + "hash": "CDD3C6DFA0A08CAEDF546F9938A2EEC232209C24AA0E4201194E0AFB78A2C2BB", + "height": "33" +} +``` + +Response should contain the height where this transaction was committed. + +Now let's check if the given key now exists and its value: + +``` +$ curl -s 'localhost:26657/abci_query?data="tendermint"' +{ + "jsonrpc": "2.0", + "id": "", + "result": { + "response": { + "log": "exists", + "key": "dGVuZGVybWludA==", + "value": "cm9ja3My" + } + } +} +``` + +"dGVuZGVybWludA==" and "cm9ja3M=" are the base64-encoding of the ASCII of +"tendermint" and "rocks" accordingly. From 7041001fb60c53195af87950bff807a409c60dd7 Mon Sep 17 00:00:00 2001 From: Marko Date: Fri, 19 Jul 2019 07:54:45 +0200 Subject: [PATCH 05/45] libs: Remove db from tendermint in favor of tendermint/tm-cmn (#3811) * Remove db from tendemrint in favor of tendermint/tm-cmn - remove db from `libs` - update dependancy, there have been no breaking changes in the updated deps - https://github.com/grpc/grpc-go/releases - https://github.com/golang/protobuf/releases Signed-off-by: Marko Baricevic * changelog add * gofmt * more gofmt --- CHANGELOG_PENDING.md | 2 + abci/example/kvstore/kvstore.go | 2 +- abci/example/kvstore/persistent_kvstore.go | 2 +- blockchain/reactor_test.go | 2 +- blockchain/store.go | 2 +- blockchain/store_test.go | 5 +- consensus/common_test.go | 2 +- consensus/mempool_test.go | 2 +- consensus/reactor_test.go | 2 +- consensus/replay.go | 2 +- consensus/replay_file.go | 2 +- consensus/replay_test.go | 2 +- consensus/wal_generator.go | 2 +- evidence/pool.go | 2 +- evidence/pool_test.go | 2 +- evidence/reactor_test.go | 2 +- evidence/store.go | 2 +- evidence/store_test.go | 2 +- go.mod | 19 +- go.sum | 42 +- libs/db/backend_test.go | 223 ----- libs/db/boltdb.go | 349 -------- libs/db/boltdb_test.go | 37 - libs/db/c_level_db.go | 325 -------- libs/db/c_level_db_test.go | 110 --- libs/db/common_test.go | 256 ------ libs/db/db.go | 70 -- libs/db/db_test.go | 194 ----- libs/db/fsdb.go | 270 ------ libs/db/go_level_db.go | 333 -------- libs/db/go_level_db_test.go | 45 - libs/db/mem_batch.go | 74 -- libs/db/mem_db.go | 255 ------ libs/db/prefix_db.go | 336 -------- libs/db/prefix_db_test.go | 192 ----- libs/db/remotedb/doc.go | 37 - libs/db/remotedb/grpcdb/client.go | 22 - libs/db/remotedb/grpcdb/doc.go | 32 - libs/db/remotedb/grpcdb/example_test.go | 52 -- libs/db/remotedb/grpcdb/server.go | 200 ----- libs/db/remotedb/proto/defs.pb.go | 914 --------------------- libs/db/remotedb/proto/defs.proto | 71 -- libs/db/remotedb/remotedb.go | 266 ------ libs/db/remotedb/remotedb_test.go | 123 --- libs/db/remotedb/test.crt | 25 - libs/db/remotedb/test.key | 27 - libs/db/types.go | 136 --- libs/db/util.go | 45 - libs/db/util_test.go | 104 --- lite/dbprovider.go | 2 +- lite/dynamic_verifier_test.go | 2 +- lite/provider_test.go | 2 +- lite/proxy/verifier.go | 2 +- node/node.go | 2 +- node/node_test.go | 2 +- p2p/trust/store.go | 2 +- p2p/trust/store_test.go | 2 +- rpc/core/pipe.go | 2 +- state/execution.go | 2 +- state/export_test.go | 2 +- state/helpers_test.go | 2 +- state/state_test.go | 2 +- state/store.go | 2 +- state/store_test.go | 2 +- state/tx_filter_test.go | 2 +- state/txindex/indexer_service_test.go | 2 +- state/txindex/kv/kv.go | 2 +- state/txindex/kv/kv_test.go | 2 +- state/validation.go | 2 +- 69 files changed, 79 insertions(+), 5184 deletions(-) delete mode 100644 libs/db/backend_test.go delete mode 100644 libs/db/boltdb.go delete mode 100644 libs/db/boltdb_test.go delete mode 100644 libs/db/c_level_db.go delete mode 100644 libs/db/c_level_db_test.go delete mode 100644 libs/db/common_test.go delete mode 100644 libs/db/db.go delete mode 100644 libs/db/db_test.go delete mode 100644 libs/db/fsdb.go delete mode 100644 libs/db/go_level_db.go delete mode 100644 libs/db/go_level_db_test.go delete mode 100644 libs/db/mem_batch.go delete mode 100644 libs/db/mem_db.go delete mode 100644 libs/db/prefix_db.go delete mode 100644 libs/db/prefix_db_test.go delete mode 100644 libs/db/remotedb/doc.go delete mode 100644 libs/db/remotedb/grpcdb/client.go delete mode 100644 libs/db/remotedb/grpcdb/doc.go delete mode 100644 libs/db/remotedb/grpcdb/example_test.go delete mode 100644 libs/db/remotedb/grpcdb/server.go delete mode 100644 libs/db/remotedb/proto/defs.pb.go delete mode 100644 libs/db/remotedb/proto/defs.proto delete mode 100644 libs/db/remotedb/remotedb.go delete mode 100644 libs/db/remotedb/remotedb_test.go delete mode 100644 libs/db/remotedb/test.crt delete mode 100644 libs/db/remotedb/test.key delete mode 100644 libs/db/types.go delete mode 100644 libs/db/util.go delete mode 100644 libs/db/util_test.go diff --git a/CHANGELOG_PENDING.md b/CHANGELOG_PENDING.md index 41400d892..e62bf1079 100644 --- a/CHANGELOG_PENDING.md +++ b/CHANGELOG_PENDING.md @@ -14,10 +14,12 @@ program](https://hackerone.com/tendermint). - Apps - Go API +- [libs] \#3811 Remove `db` from libs in favor of `https://github.com/tendermint/tm-cmn` ### FEATURES: ### IMPROVEMENTS: + - [abci] \#3809 Recover from application panics in `server/socket_server.go` to allow socket cleanup (@ruseinov) ### BUG FIXES: diff --git a/abci/example/kvstore/kvstore.go b/abci/example/kvstore/kvstore.go index 82d404c76..71d0620e1 100644 --- a/abci/example/kvstore/kvstore.go +++ b/abci/example/kvstore/kvstore.go @@ -9,8 +9,8 @@ import ( "github.com/tendermint/tendermint/abci/example/code" "github.com/tendermint/tendermint/abci/types" cmn "github.com/tendermint/tendermint/libs/common" - dbm "github.com/tendermint/tendermint/libs/db" "github.com/tendermint/tendermint/version" + dbm "github.com/tendermint/tm-cmn/db" ) var ( diff --git a/abci/example/kvstore/persistent_kvstore.go b/abci/example/kvstore/persistent_kvstore.go index ba0b53896..68269dceb 100644 --- a/abci/example/kvstore/persistent_kvstore.go +++ b/abci/example/kvstore/persistent_kvstore.go @@ -9,8 +9,8 @@ import ( "github.com/tendermint/tendermint/abci/example/code" "github.com/tendermint/tendermint/abci/types" - dbm "github.com/tendermint/tendermint/libs/db" "github.com/tendermint/tendermint/libs/log" + dbm "github.com/tendermint/tm-cmn/db" ) const ( diff --git a/blockchain/reactor_test.go b/blockchain/reactor_test.go index b5137bb2a..4f2588055 100644 --- a/blockchain/reactor_test.go +++ b/blockchain/reactor_test.go @@ -11,7 +11,6 @@ import ( abci "github.com/tendermint/tendermint/abci/types" cfg "github.com/tendermint/tendermint/config" cmn "github.com/tendermint/tendermint/libs/common" - dbm "github.com/tendermint/tendermint/libs/db" "github.com/tendermint/tendermint/libs/log" "github.com/tendermint/tendermint/mock" "github.com/tendermint/tendermint/p2p" @@ -19,6 +18,7 @@ import ( sm "github.com/tendermint/tendermint/state" "github.com/tendermint/tendermint/types" tmtime "github.com/tendermint/tendermint/types/time" + dbm "github.com/tendermint/tm-cmn/db" ) var config *cfg.Config diff --git a/blockchain/store.go b/blockchain/store.go index b7f4e07c8..fcdc03b99 100644 --- a/blockchain/store.go +++ b/blockchain/store.go @@ -5,7 +5,7 @@ import ( "sync" cmn "github.com/tendermint/tendermint/libs/common" - dbm "github.com/tendermint/tendermint/libs/db" + dbm "github.com/tendermint/tm-cmn/db" "github.com/tendermint/tendermint/types" ) diff --git a/blockchain/store_test.go b/blockchain/store_test.go index bd30bc6d2..7e94814d7 100644 --- a/blockchain/store_test.go +++ b/blockchain/store_test.go @@ -11,10 +11,11 @@ import ( "github.com/stretchr/testify/assert" "github.com/stretchr/testify/require" + "github.com/tendermint/tm-cmn/db" + dbm "github.com/tendermint/tm-cmn/db" + cfg "github.com/tendermint/tendermint/config" cmn "github.com/tendermint/tendermint/libs/common" - "github.com/tendermint/tendermint/libs/db" - dbm "github.com/tendermint/tendermint/libs/db" "github.com/tendermint/tendermint/libs/log" sm "github.com/tendermint/tendermint/state" diff --git a/consensus/common_test.go b/consensus/common_test.go index 29db524ec..839db08d7 100644 --- a/consensus/common_test.go +++ b/consensus/common_test.go @@ -24,7 +24,6 @@ import ( cfg "github.com/tendermint/tendermint/config" cstypes "github.com/tendermint/tendermint/consensus/types" cmn "github.com/tendermint/tendermint/libs/common" - dbm "github.com/tendermint/tendermint/libs/db" "github.com/tendermint/tendermint/libs/log" tmpubsub "github.com/tendermint/tendermint/libs/pubsub" mempl "github.com/tendermint/tendermint/mempool" @@ -33,6 +32,7 @@ import ( sm "github.com/tendermint/tendermint/state" "github.com/tendermint/tendermint/types" tmtime "github.com/tendermint/tendermint/types/time" + dbm "github.com/tendermint/tm-cmn/db" ) const ( diff --git a/consensus/mempool_test.go b/consensus/mempool_test.go index d9feef9b4..de0179869 100644 --- a/consensus/mempool_test.go +++ b/consensus/mempool_test.go @@ -11,10 +11,10 @@ import ( "github.com/tendermint/tendermint/abci/example/code" abci "github.com/tendermint/tendermint/abci/types" - dbm "github.com/tendermint/tendermint/libs/db" mempl "github.com/tendermint/tendermint/mempool" sm "github.com/tendermint/tendermint/state" "github.com/tendermint/tendermint/types" + dbm "github.com/tendermint/tm-cmn/db" ) // for testing diff --git a/consensus/reactor_test.go b/consensus/reactor_test.go index b237da6b5..30d9307a2 100644 --- a/consensus/reactor_test.go +++ b/consensus/reactor_test.go @@ -19,13 +19,13 @@ import ( abci "github.com/tendermint/tendermint/abci/types" bc "github.com/tendermint/tendermint/blockchain" cfg "github.com/tendermint/tendermint/config" - dbm "github.com/tendermint/tendermint/libs/db" "github.com/tendermint/tendermint/libs/log" mempl "github.com/tendermint/tendermint/mempool" "github.com/tendermint/tendermint/p2p" "github.com/tendermint/tendermint/p2p/mock" sm "github.com/tendermint/tendermint/state" "github.com/tendermint/tendermint/types" + dbm "github.com/tendermint/tm-cmn/db" ) //---------------------------------------------- diff --git a/consensus/replay.go b/consensus/replay.go index 2c4377ffa..a55fd80c5 100644 --- a/consensus/replay.go +++ b/consensus/replay.go @@ -13,8 +13,8 @@ import ( abci "github.com/tendermint/tendermint/abci/types" //auto "github.com/tendermint/tendermint/libs/autofile" + dbm "github.com/tendermint/tm-cmn/db" - dbm "github.com/tendermint/tendermint/libs/db" "github.com/tendermint/tendermint/libs/log" "github.com/tendermint/tendermint/mock" "github.com/tendermint/tendermint/proxy" diff --git a/consensus/replay_file.go b/consensus/replay_file.go index 5bb73484e..17404de8e 100644 --- a/consensus/replay_file.go +++ b/consensus/replay_file.go @@ -10,11 +10,11 @@ import ( "strings" "github.com/pkg/errors" + dbm "github.com/tendermint/tm-cmn/db" bc "github.com/tendermint/tendermint/blockchain" cfg "github.com/tendermint/tendermint/config" cmn "github.com/tendermint/tendermint/libs/common" - dbm "github.com/tendermint/tendermint/libs/db" "github.com/tendermint/tendermint/libs/log" "github.com/tendermint/tendermint/mock" "github.com/tendermint/tendermint/proxy" diff --git a/consensus/replay_test.go b/consensus/replay_test.go index bbb5b6678..3a0f9024a 100644 --- a/consensus/replay_test.go +++ b/consensus/replay_test.go @@ -22,7 +22,6 @@ import ( cfg "github.com/tendermint/tendermint/config" "github.com/tendermint/tendermint/crypto" cmn "github.com/tendermint/tendermint/libs/common" - dbm "github.com/tendermint/tendermint/libs/db" "github.com/tendermint/tendermint/libs/log" "github.com/tendermint/tendermint/mock" "github.com/tendermint/tendermint/privval" @@ -31,6 +30,7 @@ import ( "github.com/tendermint/tendermint/types" tmtime "github.com/tendermint/tendermint/types/time" "github.com/tendermint/tendermint/version" + dbm "github.com/tendermint/tm-cmn/db" ) func TestMain(m *testing.M) { diff --git a/consensus/wal_generator.go b/consensus/wal_generator.go index 2faff27b5..c96fd66e8 100644 --- a/consensus/wal_generator.go +++ b/consensus/wal_generator.go @@ -15,13 +15,13 @@ import ( bc "github.com/tendermint/tendermint/blockchain" cfg "github.com/tendermint/tendermint/config" cmn "github.com/tendermint/tendermint/libs/common" - "github.com/tendermint/tendermint/libs/db" "github.com/tendermint/tendermint/libs/log" "github.com/tendermint/tendermint/mock" "github.com/tendermint/tendermint/privval" "github.com/tendermint/tendermint/proxy" sm "github.com/tendermint/tendermint/state" "github.com/tendermint/tendermint/types" + "github.com/tendermint/tm-cmn/db" ) // WALGenerateNBlocks generates a consensus WAL. It does this by spinning up a diff --git a/evidence/pool.go b/evidence/pool.go index 18ccb3344..c3603730b 100644 --- a/evidence/pool.go +++ b/evidence/pool.go @@ -5,8 +5,8 @@ import ( "sync" clist "github.com/tendermint/tendermint/libs/clist" - dbm "github.com/tendermint/tendermint/libs/db" "github.com/tendermint/tendermint/libs/log" + dbm "github.com/tendermint/tm-cmn/db" sm "github.com/tendermint/tendermint/state" "github.com/tendermint/tendermint/types" diff --git a/evidence/pool_test.go b/evidence/pool_test.go index 13bc45563..65f970303 100644 --- a/evidence/pool_test.go +++ b/evidence/pool_test.go @@ -7,10 +7,10 @@ import ( "github.com/stretchr/testify/assert" - dbm "github.com/tendermint/tendermint/libs/db" sm "github.com/tendermint/tendermint/state" "github.com/tendermint/tendermint/types" tmtime "github.com/tendermint/tendermint/types/time" + dbm "github.com/tendermint/tm-cmn/db" ) func TestMain(m *testing.M) { diff --git a/evidence/reactor_test.go b/evidence/reactor_test.go index 635e9553f..e9c05b4d5 100644 --- a/evidence/reactor_test.go +++ b/evidence/reactor_test.go @@ -11,10 +11,10 @@ import ( cfg "github.com/tendermint/tendermint/config" "github.com/tendermint/tendermint/crypto/secp256k1" - dbm "github.com/tendermint/tendermint/libs/db" "github.com/tendermint/tendermint/libs/log" "github.com/tendermint/tendermint/p2p" "github.com/tendermint/tendermint/types" + dbm "github.com/tendermint/tm-cmn/db" ) // evidenceLogger is a TestingLogger which uses a different diff --git a/evidence/store.go b/evidence/store.go index 464d6138e..a809f1474 100644 --- a/evidence/store.go +++ b/evidence/store.go @@ -3,8 +3,8 @@ package evidence import ( "fmt" - dbm "github.com/tendermint/tendermint/libs/db" "github.com/tendermint/tendermint/types" + dbm "github.com/tendermint/tm-cmn/db" ) /* diff --git a/evidence/store_test.go b/evidence/store_test.go index 5a7a8bd36..a4d3dc4b9 100644 --- a/evidence/store_test.go +++ b/evidence/store_test.go @@ -4,8 +4,8 @@ import ( "testing" "github.com/stretchr/testify/assert" - dbm "github.com/tendermint/tendermint/libs/db" "github.com/tendermint/tendermint/types" + dbm "github.com/tendermint/tm-cmn/db" ) //------------------------------------------- diff --git a/go.mod b/go.mod index 948cf9887..6b6d94c21 100644 --- a/go.mod +++ b/go.mod @@ -3,30 +3,26 @@ module github.com/tendermint/tendermint go 1.12 require ( - github.com/BurntSushi/toml v0.3.1 // indirect github.com/VividCortex/gohistogram v1.0.0 // indirect github.com/beorn7/perks v0.0.0-20180321164747-3a771d992973 // indirect github.com/btcsuite/btcd v0.0.0-20190115013929-ed77733ec07d github.com/btcsuite/btcutil v0.0.0-20180706230648-ab6388e0c60a - github.com/etcd-io/bbolt v1.3.2 github.com/fortytw2/leaktest v1.2.0 github.com/go-kit/kit v0.6.0 github.com/go-logfmt/logfmt v0.3.0 github.com/go-stack/stack v1.8.0 // indirect github.com/gogo/protobuf v1.2.1 - github.com/golang/glog v0.0.0-20160126235308-23def4e6c14b // indirect - github.com/golang/protobuf v1.3.0 + github.com/golang/protobuf v1.3.2 github.com/google/gofuzz v1.0.0 // indirect github.com/gorilla/websocket v1.2.0 github.com/hashicorp/hcl v1.0.0 // indirect github.com/inconshreveable/mousetrap v1.0.0 // indirect - github.com/jmhodges/levigo v1.0.0 github.com/kr/logfmt v0.0.0-20140226030751-b84e30acd515 // indirect github.com/magiconair/properties v1.8.0 github.com/matttproud/golang_protobuf_extensions v1.0.1 // indirect github.com/mitchellh/mapstructure v1.1.2 // indirect github.com/pelletier/go-toml v1.2.0 // indirect - github.com/pkg/errors v0.8.0 + github.com/pkg/errors v0.8.1 github.com/prometheus/client_golang v0.9.1 github.com/prometheus/client_model v0.0.0-20180712105110-5c3871d89910 // indirect github.com/prometheus/common v0.0.0-20181020173914-7e9e6cabbd39 // indirect @@ -39,12 +35,11 @@ require ( github.com/spf13/jwalterweatherman v1.0.0 // indirect github.com/spf13/pflag v1.0.3 // indirect github.com/spf13/viper v1.0.0 - github.com/stretchr/testify v1.2.2 - github.com/syndtr/goleveldb v1.0.1-0.20190318030020-c3a204f8e965 + github.com/stretchr/testify v1.3.0 github.com/tendermint/go-amino v0.14.1 - go.etcd.io/bbolt v1.3.3 // indirect - golang.org/x/crypto v0.0.0-20190228161510-8dd112bcdc25 - golang.org/x/net v0.0.0-20180906233101-161cd47e91fd + github.com/tendermint/tm-cmn v0.0.0-20190716080004-dfcde30d5acb + golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2 + golang.org/x/net v0.0.0-20190628185345-da137c7871d7 google.golang.org/genproto v0.0.0-20181029155118-b69ba1387ce2 // indirect - google.golang.org/grpc v1.13.0 + google.golang.org/grpc v1.22.0 ) diff --git a/go.sum b/go.sum index 14091bbc0..418e8e6eb 100644 --- a/go.sum +++ b/go.sum @@ -1,3 +1,4 @@ +cloud.google.com/go v0.26.0/go.mod h1:aQUYkXzVsufM+DwF1aE+0xfcU+56JwCaLick0ClmMTw= github.com/BurntSushi/toml v0.3.1 h1:WXkYYl6Yr3qBf1K79EBnL4mak0OimBfB0XUf9Vl28OQ= github.com/BurntSushi/toml v0.3.1/go.mod h1:xHWCNGjB5oqiDr8zfno3MHue2Ht5sIBksp03qcyfWMU= github.com/VividCortex/gohistogram v1.0.0 h1:6+hBz+qvs0JOrrNhhmR7lFxo5sINxBCGXrdtl/UvroE= @@ -15,11 +16,13 @@ github.com/btcsuite/goleveldb v0.0.0-20160330041536-7834afc9e8cd/go.mod h1:F+uVa github.com/btcsuite/snappy-go v0.0.0-20151229074030-0bdef8d06723/go.mod h1:8woku9dyThutzjeg+3xrA5iCpBRH8XEEg3lh6TiUghc= github.com/btcsuite/websocket v0.0.0-20150119174127-31079b680792/go.mod h1:ghJtEyQwv5/p4Mg4C0fgbePVuGr935/5ddU9Z3TmDRY= github.com/btcsuite/winsvc v1.0.0/go.mod h1:jsenWakMcC0zFBFurPLEAyrnc/teJEM1O46fmI40EZs= +github.com/client9/misspell v0.3.4/go.mod h1:qj6jICC3Q7zFZvVWo7KLAzC3yx5G7kyvSDkc90ppPyw= github.com/davecgh/go-spew v0.0.0-20171005155431-ecdeabc65495/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38= +github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38= github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c= github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38= -github.com/etcd-io/bbolt v1.3.2 h1:RLRQ0TKLX7DlBRXAJHvbmXL17Q3KNnTBtZ9B6Qo+/Y0= -github.com/etcd-io/bbolt v1.3.2/go.mod h1:ZF2nL25h33cCyBtcyWeZ2/I3HQOfTP+0PIEvHjkjCrw= +github.com/etcd-io/bbolt v1.3.3 h1:gSJmxrs37LgTqR/oyJBWok6k6SvXEUerFTbltIhXkBM= +github.com/etcd-io/bbolt v1.3.3/go.mod h1:ZF2nL25h33cCyBtcyWeZ2/I3HQOfTP+0PIEvHjkjCrw= github.com/fortytw2/leaktest v1.2.0 h1:cj6GCiwJDH7l3tMHLjZDo0QqPtrXJiWSI9JgpeQKw+Q= github.com/fortytw2/leaktest v1.2.0/go.mod h1:jDsjWgpAGjm2CA7WthBh/CdZYEPF31XHquHwclZch5g= github.com/fsnotify/fsnotify v1.4.7 h1:IXs+QLmnXW2CcXuY+8Mzv/fWEsPGWxqefPtCP5CnV9I= @@ -34,13 +37,14 @@ github.com/gogo/protobuf v1.2.1 h1:/s5zKNz0uPFCZ5hddgPdo2TK2TVrUNMn0OOX8/aZMTE= github.com/gogo/protobuf v1.2.1/go.mod h1:hp+jE20tsWTFYpLwKvXlhS1hjn+gTNwPg2I6zVXpSg4= github.com/golang/glog v0.0.0-20160126235308-23def4e6c14b h1:VKtxabqXZkF25pY9ekfRL6a582T4P37/31XEstQ5p58= github.com/golang/glog v0.0.0-20160126235308-23def4e6c14b/go.mod h1:SBH7ygxi8pfUlaOkMMuAQtPIUF8ecWP5IEl/CR7VP2Q= +github.com/golang/mock v1.1.1/go.mod h1:oTYuIxOrZwtPieC+H1uAHpcLFnEyAGVDL/k47Jfbm0A= github.com/golang/protobuf v1.2.0/go.mod h1:6lQm79b+lXiMfvg/cZm0SGofjICqVBUtrP5yJMmIC1U= -github.com/golang/protobuf v1.3.0 h1:kbxbvI4Un1LUWKxufD+BiE6AEExYYgkQLQmLFqA1LFk= github.com/golang/protobuf v1.3.0/go.mod h1:Qd/q+1AKNOZr9uGQzbzCmRO6sUih6GTPZv6a1/R87v0= -github.com/golang/snappy v0.0.0-20180518054509-2e65f85255db h1:woRePGFeVFfLKN/pOkfl+p/TAqKOfFu+7KPlMVpok/w= -github.com/golang/snappy v0.0.0-20180518054509-2e65f85255db/go.mod h1:/XxbfmMg8lxefKM7IXC3fBNl/7bRcc72aCRzEWrmP2Q= +github.com/golang/protobuf v1.3.2 h1:6nsPYzhq5kReh6QImI3k5qWzO4PEbvbIW2cwSfR/6xs= +github.com/golang/protobuf v1.3.2/go.mod h1:6lQm79b+lXiMfvg/cZm0SGofjICqVBUtrP5yJMmIC1U= github.com/golang/snappy v0.0.1 h1:Qgr9rKW7uDUkrbSmQeiDsGa8SjGyCOGtuasMWwvp2P4= github.com/golang/snappy v0.0.1/go.mod h1:/XxbfmMg8lxefKM7IXC3fBNl/7bRcc72aCRzEWrmP2Q= +github.com/google/go-cmp v0.2.0/go.mod h1:oXzfMopK8JAjlY9xF4vHSVASa0yLyX7SntLO5aqRK0M= github.com/google/gofuzz v1.0.0 h1:A8PeW59pxE9IoFRqBp37U+mSNaQoZ46F1f0f863XSXw= github.com/google/gofuzz v1.0.0/go.mod h1:dBl0BpW6vV/+mYPU4Po3pmUjxk6FQPldtuIdl/M65Eg= github.com/gorilla/websocket v1.2.0 h1:VJtLvh6VQym50czpZzx07z/kw9EgAxI3x1ZB8taTMQQ= @@ -73,8 +77,9 @@ github.com/onsi/gomega v1.4.3 h1:RE1xgDvH7imwFD45h+u2SgIfERHlS2yNG4DObb5BSKU= github.com/onsi/gomega v1.4.3/go.mod h1:ex+gbHU/CVuBBDIJjb2X0qEXbFg53c61hWP/1CpauHY= github.com/pelletier/go-toml v1.2.0 h1:T5zMGML61Wp+FlcbWjRDT7yAxhJNAiPPLOFECq181zc= github.com/pelletier/go-toml v1.2.0/go.mod h1:5z9KED0ma1S8pY6P1sdut58dfprrGBbd/94hg7ilaic= -github.com/pkg/errors v0.8.0 h1:WdK/asTD0HN+q6hsWO3/vpuAkAr+tw6aNJNDFFf0+qw= github.com/pkg/errors v0.8.0/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0= +github.com/pkg/errors v0.8.1 h1:iURUrRGxPUNPdy5/HRSm+Yj6okJ6UtLINN0Q9M4+h3I= +github.com/pkg/errors v0.8.1/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0= github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM= github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4= github.com/prometheus/client_golang v0.9.1 h1:K47Rk0v/fkEfwfQet2KWhscE0cJzjgCCDBG2KHZoVno= @@ -101,35 +106,49 @@ github.com/spf13/pflag v1.0.3 h1:zPAT6CGy6wXeQ7NtTnaTerfKOsV6V6F8agHXFiazDkg= github.com/spf13/pflag v1.0.3/go.mod h1:DYY7MBk1bdzusC3SYhjObp+wFpr4gzcvqqNjLnInEg4= github.com/spf13/viper v1.0.0 h1:RUA/ghS2i64rlnn4ydTfblY8Og8QzcPtCcHvgMn+w/I= github.com/spf13/viper v1.0.0/go.mod h1:A8kyI5cUJhb8N+3pkfONlcEcZbueH6nhAm0Fq7SrnBM= +github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME= github.com/stretchr/testify v1.2.2 h1:bSDNvY7ZPG5RlJ8otE/7V6gMiyenm9RtJ7IUVIAoJ1w= github.com/stretchr/testify v1.2.2/go.mod h1:a8OnRcib4nhh0OaRAV+Yts87kKdq0PP7pXfy6kDkUVs= -github.com/syndtr/goleveldb v0.0.0-20181012014443-6b91fda63f2e h1:91EeXI4y4ShkyzkMqZ7QP/ZTIqwXp3RuDu5WFzxcFAs= -github.com/syndtr/goleveldb v0.0.0-20181012014443-6b91fda63f2e/go.mod h1:Z4AUp2Km+PwemOoO/VB5AOx9XSsIItzFjoJlOSiYmn0= -github.com/syndtr/goleveldb v1.0.0 h1:fBdIW9lB4Iz0n9khmH8w27SJ3QEJ7+IgjPEwGSZiFdE= +github.com/stretchr/testify v1.3.0 h1:TivCn/peBQ7UY8ooIcPgZFpTNSz0Q2U6UrFlUfqbe0Q= +github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UVUgZn+9EI= github.com/syndtr/goleveldb v1.0.1-0.20190318030020-c3a204f8e965 h1:1oFLiOyVl+W7bnBzGhf7BbIv9loSFQcieWWYIjLqcAw= github.com/syndtr/goleveldb v1.0.1-0.20190318030020-c3a204f8e965/go.mod h1:9OrXJhf154huy1nPWmuSrkgjPUtUNhA+Zmy+6AESzuA= github.com/tendermint/go-amino v0.14.1 h1:o2WudxNfdLNBwMyl2dqOJxiro5rfrEaU0Ugs6offJMk= github.com/tendermint/go-amino v0.14.1/go.mod h1:i/UKE5Uocn+argJJBb12qTZsCDBcAYMbR92AaJVmKso= +github.com/tendermint/tm-cmn v0.0.0-20190716080004-dfcde30d5acb h1:t/HdvqJc9e1iJDl+hf8wQKfOo40aen+Rkqh4AwEaNsI= +github.com/tendermint/tm-cmn v0.0.0-20190716080004-dfcde30d5acb/go.mod h1:SLI3Mc+gRrorRsAXJArnHz4xmAdJT8O7Ns0NL4HslXE= go.etcd.io/bbolt v1.3.3 h1:MUGmc65QhB3pIlaQ5bB4LwqSj6GIonVJXpZiaKNyaKk= go.etcd.io/bbolt v1.3.3/go.mod h1:IbVyRI1SCnLcuJnV2u8VeU0CEYM7e686BmAb1XKL+uU= golang.org/x/crypto v0.0.0-20170930174604-9419663f5a44/go.mod h1:6SG95UA2DQfeDnfUPMdvaQW0Q7yPrPDi9nlGo2tz2b4= -golang.org/x/crypto v0.0.0-20190228161510-8dd112bcdc25 h1:jsG6UpNLt9iAsb0S2AGW28DveNzzgmbXR+ENoPjUeIU= golang.org/x/crypto v0.0.0-20190228161510-8dd112bcdc25/go.mod h1:djNgcEr1/C05ACkg1iLfiJU5Ep61QUkGW8qpdssI0+w= +golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2 h1:VklqNMn3ovrHsnt90PveolxSbWFaJdECFbxSq0Mqo2M= +golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2/go.mod h1:djNgcEr1/C05ACkg1iLfiJU5Ep61QUkGW8qpdssI0+w= +golang.org/x/lint v0.0.0-20190313153728-d0100b6bd8b3/go.mod h1:6SW0HCj/g11FgYtHlgUYUwCkIfeOF89ocIRzGO/8vkc= golang.org/x/net v0.0.0-20180906233101-161cd47e91fd h1:nTDtHvHSdCn1m6ITfMRqtOd/9+7a3s8RBNOZ3eYZzJA= golang.org/x/net v0.0.0-20180906233101-161cd47e91fd/go.mod h1:mL1N/T3taQHkDXs73rZJwtUhF3w3ftmwwsq0BUmARs4= +golang.org/x/net v0.0.0-20190311183353-d8887717615a/go.mod h1:t9HGtf8HONx5eT2rtn7q6eTqICYqUVnKs3thJo3Qplg= +golang.org/x/net v0.0.0-20190628185345-da137c7871d7 h1:rTIdg5QFRR7XCaK4LCjBiPbx8j4DQRpdYMnGn/bJUEU= +golang.org/x/net v0.0.0-20190628185345-da137c7871d7/go.mod h1:z5CRVTTTmAJ677TzLLGU+0bjPO0LkuOLi4/5GtJWs/s= +golang.org/x/oauth2 v0.0.0-20180821212333-d2e6202438be/go.mod h1:N/0e6XlmueqKjAGxoOufVs8QHGRruUQn6yWY3a++T0U= golang.org/x/sync v0.0.0-20180314180146-1d60e4601c6f h1:wMNYb4v58l5UBM7MYRLPG6ZhfOqbKu7X5eyFl8ZhKvA= golang.org/x/sync v0.0.0-20180314180146-1d60e4601c6f/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM= +golang.org/x/sync v0.0.0-20190423024810-112230192c58/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM= golang.org/x/sys v0.0.0-20180909124046-d0be0721c37e/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY= golang.org/x/sys v0.0.0-20190215142949-d0b11bdaac8a h1:1BGLXjeY4akVXGgbC9HugT3Jv3hCI0z56oJR5vAMgBU= golang.org/x/sys v0.0.0-20190215142949-d0b11bdaac8a/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY= golang.org/x/text v0.3.0 h1:g61tztE5qeGQ89tm6NTjjM9VPIm088od1l6aSorWRWg= golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ= golang.org/x/tools v0.0.0-20180221164845-07fd8470d635/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ= +golang.org/x/tools v0.0.0-20190311212946-11955173bddd/go.mod h1:LCzVGOaR6xXOjkQ3onu1FJEFr0SW1gC7cKk1uF8kGRs= +golang.org/x/tools v0.0.0-20190524140312-2c0ae7006135/go.mod h1:RgjU9mgBXZiqYHBnxXauZ1Gv1EHHAz9KjViQ78xBX0Q= +google.golang.org/appengine v1.1.0/go.mod h1:EbEs0AVv82hx2wNQdGPgUI5lhzA/G0D9YwlJXL52JkM= +google.golang.org/genproto v0.0.0-20180817151627-c66870c02cf8/go.mod h1:JiN7NxoALGmiZfu7CAH4rXhgtRTLTxftemlI0sWmxmc= google.golang.org/genproto v0.0.0-20180831171423-11092d34479b/go.mod h1:JiN7NxoALGmiZfu7CAH4rXhgtRTLTxftemlI0sWmxmc= google.golang.org/genproto v0.0.0-20181029155118-b69ba1387ce2 h1:67iHsV9djwGdZpdZNbLuQj6FOzCaZe3w+vhLjn5AcFA= google.golang.org/genproto v0.0.0-20181029155118-b69ba1387ce2/go.mod h1:JiN7NxoALGmiZfu7CAH4rXhgtRTLTxftemlI0sWmxmc= -google.golang.org/grpc v1.13.0 h1:bHIbVsCwmvbArgCJmLdgOdHFXlKqTOVjbibbS19cXHc= google.golang.org/grpc v1.13.0/go.mod h1:yo6s7OP7yaDglbqo1J04qKzAhqBH6lvTonzMVmEdcZw= +google.golang.org/grpc v1.22.0 h1:J0UbZOIrCAl+fpTOf8YLs4dJo8L/owV4LYVtAXQoPkw= +google.golang.org/grpc v1.22.0/go.mod h1:Y5yQAOtifL1yxbo5wqy6BxZv8vAUGQwXBOALyacEbxg= gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM= gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0= gopkg.in/fsnotify.v1 v1.4.7 h1:xOHLXZwVvI9hhs+cLKq5+I5onOuwQLhQwiu63xxlHs4= @@ -138,3 +157,4 @@ gopkg.in/tomb.v1 v1.0.0-20141024135613-dd632973f1e7 h1:uRGJdciOHaEIrze2W8Q3AKkep gopkg.in/tomb.v1 v1.0.0-20141024135613-dd632973f1e7/go.mod h1:dt/ZhP58zS4L8KSrWDmTeBkI65Dw0HsyUHuEVlX15mw= gopkg.in/yaml.v2 v2.2.1 h1:mUhvW9EsL+naU5Q3cakzfE91YhliOondGd6ZrsDBHQE= gopkg.in/yaml.v2 v2.2.1/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI= +honnef.co/go/tools v0.0.0-20190523083050-ea95bdfd59fc/go.mod h1:rf3lG4BRIbNafJWhAfAdb/ePZxsR/4RtNHQocxwk9r4= diff --git a/libs/db/backend_test.go b/libs/db/backend_test.go deleted file mode 100644 index d755a6f27..000000000 --- a/libs/db/backend_test.go +++ /dev/null @@ -1,223 +0,0 @@ -package db - -import ( - "fmt" - "io/ioutil" - "os" - "path/filepath" - "testing" - - "github.com/stretchr/testify/assert" - "github.com/stretchr/testify/require" - - cmn "github.com/tendermint/tendermint/libs/common" -) - -func cleanupDBDir(dir, name string) { - err := os.RemoveAll(filepath.Join(dir, name) + ".db") - if err != nil { - panic(err) - } -} - -func testBackendGetSetDelete(t *testing.T, backend DBBackendType) { - // Default - dirname, err := ioutil.TempDir("", fmt.Sprintf("test_backend_%s_", backend)) - require.Nil(t, err) - db := NewDB("testdb", backend, dirname) - defer cleanupDBDir(dirname, "testdb") - - // A nonexistent key should return nil, even if the key is empty - require.Nil(t, db.Get([]byte(""))) - - // A nonexistent key should return nil, even if the key is nil - require.Nil(t, db.Get(nil)) - - // A nonexistent key should return nil. - key := []byte("abc") - require.Nil(t, db.Get(key)) - - // Set empty value. - db.Set(key, []byte("")) - require.NotNil(t, db.Get(key)) - require.Empty(t, db.Get(key)) - - // Set nil value. - db.Set(key, nil) - require.NotNil(t, db.Get(key)) - require.Empty(t, db.Get(key)) - - // Delete. - db.Delete(key) - require.Nil(t, db.Get(key)) -} - -func TestBackendsGetSetDelete(t *testing.T) { - for dbType := range backends { - testBackendGetSetDelete(t, dbType) - } -} - -func withDB(t *testing.T, creator dbCreator, fn func(DB)) { - name := fmt.Sprintf("test_%x", cmn.RandStr(12)) - dir := os.TempDir() - db, err := creator(name, dir) - require.Nil(t, err) - defer cleanupDBDir(dir, name) - fn(db) - db.Close() -} - -func TestBackendsNilKeys(t *testing.T) { - - // Test all backends. - for dbType, creator := range backends { - withDB(t, creator, func(db DB) { - t.Run(fmt.Sprintf("Testing %s", dbType), func(t *testing.T) { - - // Nil keys are treated as the empty key for most operations. - expect := func(key, value []byte) { - if len(key) == 0 { // nil or empty - assert.Equal(t, db.Get(nil), db.Get([]byte(""))) - assert.Equal(t, db.Has(nil), db.Has([]byte(""))) - } - assert.Equal(t, db.Get(key), value) - assert.Equal(t, db.Has(key), value != nil) - } - - // Not set - expect(nil, nil) - - // Set nil value - db.Set(nil, nil) - expect(nil, []byte("")) - - // Set empty value - db.Set(nil, []byte("")) - expect(nil, []byte("")) - - // Set nil, Delete nil - db.Set(nil, []byte("abc")) - expect(nil, []byte("abc")) - db.Delete(nil) - expect(nil, nil) - - // Set nil, Delete empty - db.Set(nil, []byte("abc")) - expect(nil, []byte("abc")) - db.Delete([]byte("")) - expect(nil, nil) - - // Set empty, Delete nil - db.Set([]byte(""), []byte("abc")) - expect(nil, []byte("abc")) - db.Delete(nil) - expect(nil, nil) - - // Set empty, Delete empty - db.Set([]byte(""), []byte("abc")) - expect(nil, []byte("abc")) - db.Delete([]byte("")) - expect(nil, nil) - - // SetSync nil, DeleteSync nil - db.SetSync(nil, []byte("abc")) - expect(nil, []byte("abc")) - db.DeleteSync(nil) - expect(nil, nil) - - // SetSync nil, DeleteSync empty - db.SetSync(nil, []byte("abc")) - expect(nil, []byte("abc")) - db.DeleteSync([]byte("")) - expect(nil, nil) - - // SetSync empty, DeleteSync nil - db.SetSync([]byte(""), []byte("abc")) - expect(nil, []byte("abc")) - db.DeleteSync(nil) - expect(nil, nil) - - // SetSync empty, DeleteSync empty - db.SetSync([]byte(""), []byte("abc")) - expect(nil, []byte("abc")) - db.DeleteSync([]byte("")) - expect(nil, nil) - }) - }) - } -} - -func TestGoLevelDBBackend(t *testing.T) { - name := fmt.Sprintf("test_%x", cmn.RandStr(12)) - db := NewDB(name, GoLevelDBBackend, "") - defer cleanupDBDir("", name) - - _, ok := db.(*GoLevelDB) - assert.True(t, ok) -} - -func TestDBIterator(t *testing.T) { - for dbType := range backends { - t.Run(fmt.Sprintf("%v", dbType), func(t *testing.T) { - testDBIterator(t, dbType) - }) - } -} - -func testDBIterator(t *testing.T, backend DBBackendType) { - name := fmt.Sprintf("test_%x", cmn.RandStr(12)) - dir := os.TempDir() - db := NewDB(name, backend, dir) - defer cleanupDBDir(dir, name) - - for i := 0; i < 10; i++ { - if i != 6 { // but skip 6. - db.Set(int642Bytes(int64(i)), nil) - } - } - - verifyIterator(t, db.Iterator(nil, nil), []int64{0, 1, 2, 3, 4, 5, 7, 8, 9}, "forward iterator") - verifyIterator(t, db.ReverseIterator(nil, nil), []int64{9, 8, 7, 5, 4, 3, 2, 1, 0}, "reverse iterator") - - verifyIterator(t, db.Iterator(nil, int642Bytes(0)), []int64(nil), "forward iterator to 0") - verifyIterator(t, db.ReverseIterator(int642Bytes(10), nil), []int64(nil), "reverse iterator from 10 (ex)") - - verifyIterator(t, db.Iterator(int642Bytes(0), nil), []int64{0, 1, 2, 3, 4, 5, 7, 8, 9}, "forward iterator from 0") - verifyIterator(t, db.Iterator(int642Bytes(1), nil), []int64{1, 2, 3, 4, 5, 7, 8, 9}, "forward iterator from 1") - verifyIterator(t, db.ReverseIterator(nil, int642Bytes(10)), []int64{9, 8, 7, 5, 4, 3, 2, 1, 0}, "reverse iterator from 10 (ex)") - verifyIterator(t, db.ReverseIterator(nil, int642Bytes(9)), []int64{8, 7, 5, 4, 3, 2, 1, 0}, "reverse iterator from 9 (ex)") - verifyIterator(t, db.ReverseIterator(nil, int642Bytes(8)), []int64{7, 5, 4, 3, 2, 1, 0}, "reverse iterator from 8 (ex)") - - verifyIterator(t, db.Iterator(int642Bytes(5), int642Bytes(6)), []int64{5}, "forward iterator from 5 to 6") - verifyIterator(t, db.Iterator(int642Bytes(5), int642Bytes(7)), []int64{5}, "forward iterator from 5 to 7") - verifyIterator(t, db.Iterator(int642Bytes(5), int642Bytes(8)), []int64{5, 7}, "forward iterator from 5 to 8") - verifyIterator(t, db.Iterator(int642Bytes(6), int642Bytes(7)), []int64(nil), "forward iterator from 6 to 7") - verifyIterator(t, db.Iterator(int642Bytes(6), int642Bytes(8)), []int64{7}, "forward iterator from 6 to 8") - verifyIterator(t, db.Iterator(int642Bytes(7), int642Bytes(8)), []int64{7}, "forward iterator from 7 to 8") - - verifyIterator(t, db.ReverseIterator(int642Bytes(4), int642Bytes(5)), []int64{4}, "reverse iterator from 5 (ex) to 4") - verifyIterator(t, db.ReverseIterator(int642Bytes(4), int642Bytes(6)), []int64{5, 4}, "reverse iterator from 6 (ex) to 4") - verifyIterator(t, db.ReverseIterator(int642Bytes(4), int642Bytes(7)), []int64{5, 4}, "reverse iterator from 7 (ex) to 4") - verifyIterator(t, db.ReverseIterator(int642Bytes(5), int642Bytes(6)), []int64{5}, "reverse iterator from 6 (ex) to 5") - verifyIterator(t, db.ReverseIterator(int642Bytes(5), int642Bytes(7)), []int64{5}, "reverse iterator from 7 (ex) to 5") - verifyIterator(t, db.ReverseIterator(int642Bytes(6), int642Bytes(7)), []int64(nil), "reverse iterator from 7 (ex) to 6") - - verifyIterator(t, db.Iterator(int642Bytes(0), int642Bytes(1)), []int64{0}, "forward iterator from 0 to 1") - verifyIterator(t, db.ReverseIterator(int642Bytes(8), int642Bytes(9)), []int64{8}, "reverse iterator from 9 (ex) to 8") - - verifyIterator(t, db.Iterator(int642Bytes(2), int642Bytes(4)), []int64{2, 3}, "forward iterator from 2 to 4") - verifyIterator(t, db.Iterator(int642Bytes(4), int642Bytes(2)), []int64(nil), "forward iterator from 4 to 2") - verifyIterator(t, db.ReverseIterator(int642Bytes(2), int642Bytes(4)), []int64{3, 2}, "reverse iterator from 4 (ex) to 2") - verifyIterator(t, db.ReverseIterator(int642Bytes(4), int642Bytes(2)), []int64(nil), "reverse iterator from 2 (ex) to 4") - -} - -func verifyIterator(t *testing.T, itr Iterator, expected []int64, msg string) { - var list []int64 - for itr.Valid() { - list = append(list, bytes2Int64(itr.Key())) - itr.Next() - } - assert.Equal(t, expected, list, msg) -} diff --git a/libs/db/boltdb.go b/libs/db/boltdb.go deleted file mode 100644 index 30501dd82..000000000 --- a/libs/db/boltdb.go +++ /dev/null @@ -1,349 +0,0 @@ -// +build boltdb - -package db - -import ( - "bytes" - "errors" - "fmt" - "os" - "path/filepath" - - "github.com/etcd-io/bbolt" -) - -var bucket = []byte("tm") - -func init() { - registerDBCreator(BoltDBBackend, func(name, dir string) (DB, error) { - return NewBoltDB(name, dir) - }, false) -} - -// BoltDB is a wrapper around etcd's fork of bolt -// (https://github.com/etcd-io/bbolt). -// -// NOTE: All operations (including Set, Delete) are synchronous by default. One -// can globally turn it off by using NoSync config option (not recommended). -// -// A single bucket ([]byte("tm")) is used per a database instance. This could -// lead to performance issues when/if there will be lots of keys. -type BoltDB struct { - db *bbolt.DB -} - -// NewBoltDB returns a BoltDB with default options. -func NewBoltDB(name, dir string) (DB, error) { - return NewBoltDBWithOpts(name, dir, bbolt.DefaultOptions) -} - -// NewBoltDBWithOpts allows you to supply *bbolt.Options. ReadOnly: true is not -// supported because NewBoltDBWithOpts creates a global bucket. -func NewBoltDBWithOpts(name string, dir string, opts *bbolt.Options) (DB, error) { - if opts.ReadOnly { - return nil, errors.New("ReadOnly: true is not supported") - } - - dbPath := filepath.Join(dir, name+".db") - db, err := bbolt.Open(dbPath, os.ModePerm, opts) - if err != nil { - return nil, err - } - - // create a global bucket - err = db.Update(func(tx *bbolt.Tx) error { - _, err := tx.CreateBucketIfNotExists(bucket) - return err - }) - if err != nil { - return nil, err - } - - return &BoltDB{db: db}, nil -} - -func (bdb *BoltDB) Get(key []byte) (value []byte) { - key = nonEmptyKey(nonNilBytes(key)) - err := bdb.db.View(func(tx *bbolt.Tx) error { - b := tx.Bucket(bucket) - if v := b.Get(key); v != nil { - value = append([]byte{}, v...) - } - return nil - }) - if err != nil { - panic(err) - } - return -} - -func (bdb *BoltDB) Has(key []byte) bool { - return bdb.Get(key) != nil -} - -func (bdb *BoltDB) Set(key, value []byte) { - key = nonEmptyKey(nonNilBytes(key)) - value = nonNilBytes(value) - err := bdb.db.Update(func(tx *bbolt.Tx) error { - b := tx.Bucket(bucket) - return b.Put(key, value) - }) - if err != nil { - panic(err) - } -} - -func (bdb *BoltDB) SetSync(key, value []byte) { - bdb.Set(key, value) -} - -func (bdb *BoltDB) Delete(key []byte) { - key = nonEmptyKey(nonNilBytes(key)) - err := bdb.db.Update(func(tx *bbolt.Tx) error { - return tx.Bucket(bucket).Delete(key) - }) - if err != nil { - panic(err) - } -} - -func (bdb *BoltDB) DeleteSync(key []byte) { - bdb.Delete(key) -} - -func (bdb *BoltDB) Close() { - bdb.db.Close() -} - -func (bdb *BoltDB) Print() { - stats := bdb.db.Stats() - fmt.Printf("%v\n", stats) - - err := bdb.db.View(func(tx *bbolt.Tx) error { - tx.Bucket(bucket).ForEach(func(k, v []byte) error { - fmt.Printf("[%X]:\t[%X]\n", k, v) - return nil - }) - return nil - }) - if err != nil { - panic(err) - } -} - -func (bdb *BoltDB) Stats() map[string]string { - stats := bdb.db.Stats() - m := make(map[string]string) - - // Freelist stats - m["FreePageN"] = fmt.Sprintf("%v", stats.FreePageN) - m["PendingPageN"] = fmt.Sprintf("%v", stats.PendingPageN) - m["FreeAlloc"] = fmt.Sprintf("%v", stats.FreeAlloc) - m["FreelistInuse"] = fmt.Sprintf("%v", stats.FreelistInuse) - - // Transaction stats - m["TxN"] = fmt.Sprintf("%v", stats.TxN) - m["OpenTxN"] = fmt.Sprintf("%v", stats.OpenTxN) - - return m -} - -// boltDBBatch stores key values in sync.Map and dumps them to the underlying -// DB upon Write call. -type boltDBBatch struct { - db *BoltDB - ops []operation -} - -// NewBatch returns a new batch. -func (bdb *BoltDB) NewBatch() Batch { - return &boltDBBatch{ - ops: nil, - db: bdb, - } -} - -// It is safe to modify the contents of the argument after Set returns but not -// before. -func (bdb *boltDBBatch) Set(key, value []byte) { - bdb.ops = append(bdb.ops, operation{opTypeSet, key, value}) -} - -// It is safe to modify the contents of the argument after Delete returns but -// not before. -func (bdb *boltDBBatch) Delete(key []byte) { - bdb.ops = append(bdb.ops, operation{opTypeDelete, key, nil}) -} - -// NOTE: the operation is synchronous (see BoltDB for reasons) -func (bdb *boltDBBatch) Write() { - err := bdb.db.db.Batch(func(tx *bbolt.Tx) error { - b := tx.Bucket(bucket) - for _, op := range bdb.ops { - key := nonEmptyKey(nonNilBytes(op.key)) - switch op.opType { - case opTypeSet: - if putErr := b.Put(key, op.value); putErr != nil { - return putErr - } - case opTypeDelete: - if delErr := b.Delete(key); delErr != nil { - return delErr - } - } - } - return nil - }) - if err != nil { - panic(err) - } -} - -func (bdb *boltDBBatch) WriteSync() { - bdb.Write() -} - -func (bdb *boltDBBatch) Close() {} - -// WARNING: Any concurrent writes or reads will block until the iterator is -// closed. -func (bdb *BoltDB) Iterator(start, end []byte) Iterator { - tx, err := bdb.db.Begin(false) - if err != nil { - panic(err) - } - return newBoltDBIterator(tx, start, end, false) -} - -// WARNING: Any concurrent writes or reads will block until the iterator is -// closed. -func (bdb *BoltDB) ReverseIterator(start, end []byte) Iterator { - tx, err := bdb.db.Begin(false) - if err != nil { - panic(err) - } - return newBoltDBIterator(tx, start, end, true) -} - -// boltDBIterator allows you to iterate on range of keys/values given some -// start / end keys (nil & nil will result in doing full scan). -type boltDBIterator struct { - tx *bbolt.Tx - - itr *bbolt.Cursor - start []byte - end []byte - - currentKey []byte - currentValue []byte - - isInvalid bool - isReverse bool -} - -func newBoltDBIterator(tx *bbolt.Tx, start, end []byte, isReverse bool) *boltDBIterator { - itr := tx.Bucket(bucket).Cursor() - - var ck, cv []byte - if isReverse { - if end == nil { - ck, cv = itr.Last() - } else { - _, _ = itr.Seek(end) // after key - ck, cv = itr.Prev() // return to end key - } - } else { - if start == nil { - ck, cv = itr.First() - } else { - ck, cv = itr.Seek(start) - } - } - - return &boltDBIterator{ - tx: tx, - itr: itr, - start: start, - end: end, - currentKey: ck, - currentValue: cv, - isReverse: isReverse, - isInvalid: false, - } -} - -func (itr *boltDBIterator) Domain() ([]byte, []byte) { - return itr.start, itr.end -} - -func (itr *boltDBIterator) Valid() bool { - if itr.isInvalid { - return false - } - - // iterated to the end of the cursor - if len(itr.currentKey) == 0 { - itr.isInvalid = true - return false - } - - if itr.isReverse { - if itr.start != nil && bytes.Compare(itr.currentKey, itr.start) < 0 { - itr.isInvalid = true - return false - } - } else { - if itr.end != nil && bytes.Compare(itr.end, itr.currentKey) <= 0 { - itr.isInvalid = true - return false - } - } - - // Valid - return true -} - -func (itr *boltDBIterator) Next() { - itr.assertIsValid() - if itr.isReverse { - itr.currentKey, itr.currentValue = itr.itr.Prev() - } else { - itr.currentKey, itr.currentValue = itr.itr.Next() - } -} - -func (itr *boltDBIterator) Key() []byte { - itr.assertIsValid() - return append([]byte{}, itr.currentKey...) -} - -func (itr *boltDBIterator) Value() []byte { - itr.assertIsValid() - var value []byte - if itr.currentValue != nil { - value = append([]byte{}, itr.currentValue...) - } - return value -} - -func (itr *boltDBIterator) Close() { - err := itr.tx.Rollback() - if err != nil { - panic(err) - } -} - -func (itr *boltDBIterator) assertIsValid() { - if !itr.Valid() { - panic("Boltdb-iterator is invalid") - } -} - -// nonEmptyKey returns a []byte("nil") if key is empty. -// WARNING: this may collude with "nil" user key! -func nonEmptyKey(key []byte) []byte { - if len(key) == 0 { - return []byte("nil") - } - return key -} diff --git a/libs/db/boltdb_test.go b/libs/db/boltdb_test.go deleted file mode 100644 index 416a8fd03..000000000 --- a/libs/db/boltdb_test.go +++ /dev/null @@ -1,37 +0,0 @@ -// +build boltdb - -package db - -import ( - "fmt" - "os" - "testing" - - "github.com/stretchr/testify/require" - - cmn "github.com/tendermint/tendermint/libs/common" -) - -func TestBoltDBNewBoltDB(t *testing.T) { - name := fmt.Sprintf("test_%x", cmn.RandStr(12)) - dir := os.TempDir() - defer cleanupDBDir(dir, name) - - db, err := NewBoltDB(name, dir) - require.NoError(t, err) - db.Close() -} - -func BenchmarkBoltDBRandomReadsWrites(b *testing.B) { - name := fmt.Sprintf("test_%x", cmn.RandStr(12)) - db, err := NewBoltDB(name, "") - if err != nil { - b.Fatal(err) - } - defer func() { - db.Close() - cleanupDBDir("", name) - }() - - benchmarkRandomReadsWrites(b, db) -} diff --git a/libs/db/c_level_db.go b/libs/db/c_level_db.go deleted file mode 100644 index 7538166b2..000000000 --- a/libs/db/c_level_db.go +++ /dev/null @@ -1,325 +0,0 @@ -// +build cleveldb - -package db - -import ( - "bytes" - "fmt" - "path/filepath" - - "github.com/jmhodges/levigo" -) - -func init() { - dbCreator := func(name string, dir string) (DB, error) { - return NewCLevelDB(name, dir) - } - registerDBCreator(CLevelDBBackend, dbCreator, false) -} - -var _ DB = (*CLevelDB)(nil) - -type CLevelDB struct { - db *levigo.DB - ro *levigo.ReadOptions - wo *levigo.WriteOptions - woSync *levigo.WriteOptions -} - -func NewCLevelDB(name string, dir string) (*CLevelDB, error) { - dbPath := filepath.Join(dir, name+".db") - - opts := levigo.NewOptions() - opts.SetCache(levigo.NewLRUCache(1 << 30)) - opts.SetCreateIfMissing(true) - db, err := levigo.Open(dbPath, opts) - if err != nil { - return nil, err - } - ro := levigo.NewReadOptions() - wo := levigo.NewWriteOptions() - woSync := levigo.NewWriteOptions() - woSync.SetSync(true) - database := &CLevelDB{ - db: db, - ro: ro, - wo: wo, - woSync: woSync, - } - return database, nil -} - -// Implements DB. -func (db *CLevelDB) Get(key []byte) []byte { - key = nonNilBytes(key) - res, err := db.db.Get(db.ro, key) - if err != nil { - panic(err) - } - return res -} - -// Implements DB. -func (db *CLevelDB) Has(key []byte) bool { - return db.Get(key) != nil -} - -// Implements DB. -func (db *CLevelDB) Set(key []byte, value []byte) { - key = nonNilBytes(key) - value = nonNilBytes(value) - err := db.db.Put(db.wo, key, value) - if err != nil { - panic(err) - } -} - -// Implements DB. -func (db *CLevelDB) SetSync(key []byte, value []byte) { - key = nonNilBytes(key) - value = nonNilBytes(value) - err := db.db.Put(db.woSync, key, value) - if err != nil { - panic(err) - } -} - -// Implements DB. -func (db *CLevelDB) Delete(key []byte) { - key = nonNilBytes(key) - err := db.db.Delete(db.wo, key) - if err != nil { - panic(err) - } -} - -// Implements DB. -func (db *CLevelDB) DeleteSync(key []byte) { - key = nonNilBytes(key) - err := db.db.Delete(db.woSync, key) - if err != nil { - panic(err) - } -} - -func (db *CLevelDB) DB() *levigo.DB { - return db.db -} - -// Implements DB. -func (db *CLevelDB) Close() { - db.db.Close() - db.ro.Close() - db.wo.Close() - db.woSync.Close() -} - -// Implements DB. -func (db *CLevelDB) Print() { - itr := db.Iterator(nil, nil) - defer itr.Close() - for ; itr.Valid(); itr.Next() { - key := itr.Key() - value := itr.Value() - fmt.Printf("[%X]:\t[%X]\n", key, value) - } -} - -// Implements DB. -func (db *CLevelDB) Stats() map[string]string { - keys := []string{ - "leveldb.aliveiters", - "leveldb.alivesnaps", - "leveldb.blockpool", - "leveldb.cachedblock", - "leveldb.num-files-at-level{n}", - "leveldb.openedtables", - "leveldb.sstables", - "leveldb.stats", - } - - stats := make(map[string]string, len(keys)) - for _, key := range keys { - str := db.db.PropertyValue(key) - stats[key] = str - } - return stats -} - -//---------------------------------------- -// Batch - -// Implements DB. -func (db *CLevelDB) NewBatch() Batch { - batch := levigo.NewWriteBatch() - return &cLevelDBBatch{db, batch} -} - -type cLevelDBBatch struct { - db *CLevelDB - batch *levigo.WriteBatch -} - -// Implements Batch. -func (mBatch *cLevelDBBatch) Set(key, value []byte) { - mBatch.batch.Put(key, value) -} - -// Implements Batch. -func (mBatch *cLevelDBBatch) Delete(key []byte) { - mBatch.batch.Delete(key) -} - -// Implements Batch. -func (mBatch *cLevelDBBatch) Write() { - err := mBatch.db.db.Write(mBatch.db.wo, mBatch.batch) - if err != nil { - panic(err) - } -} - -// Implements Batch. -func (mBatch *cLevelDBBatch) WriteSync() { - err := mBatch.db.db.Write(mBatch.db.woSync, mBatch.batch) - if err != nil { - panic(err) - } -} - -// Implements Batch. -func (mBatch *cLevelDBBatch) Close() { - mBatch.batch.Close() -} - -//---------------------------------------- -// Iterator -// NOTE This is almost identical to db/go_level_db.Iterator -// Before creating a third version, refactor. - -func (db *CLevelDB) Iterator(start, end []byte) Iterator { - itr := db.db.NewIterator(db.ro) - return newCLevelDBIterator(itr, start, end, false) -} - -func (db *CLevelDB) ReverseIterator(start, end []byte) Iterator { - itr := db.db.NewIterator(db.ro) - return newCLevelDBIterator(itr, start, end, true) -} - -var _ Iterator = (*cLevelDBIterator)(nil) - -type cLevelDBIterator struct { - source *levigo.Iterator - start, end []byte - isReverse bool - isInvalid bool -} - -func newCLevelDBIterator(source *levigo.Iterator, start, end []byte, isReverse bool) *cLevelDBIterator { - if isReverse { - if end == nil { - source.SeekToLast() - } else { - source.Seek(end) - if source.Valid() { - eoakey := source.Key() // end or after key - if bytes.Compare(end, eoakey) <= 0 { - source.Prev() - } - } else { - source.SeekToLast() - } - } - } else { - if start == nil { - source.SeekToFirst() - } else { - source.Seek(start) - } - } - return &cLevelDBIterator{ - source: source, - start: start, - end: end, - isReverse: isReverse, - isInvalid: false, - } -} - -func (itr cLevelDBIterator) Domain() ([]byte, []byte) { - return itr.start, itr.end -} - -func (itr cLevelDBIterator) Valid() bool { - - // Once invalid, forever invalid. - if itr.isInvalid { - return false - } - - // Panic on DB error. No way to recover. - itr.assertNoError() - - // If source is invalid, invalid. - if !itr.source.Valid() { - itr.isInvalid = true - return false - } - - // If key is end or past it, invalid. - var start = itr.start - var end = itr.end - var key = itr.source.Key() - if itr.isReverse { - if start != nil && bytes.Compare(key, start) < 0 { - itr.isInvalid = true - return false - } - } else { - if end != nil && bytes.Compare(end, key) <= 0 { - itr.isInvalid = true - return false - } - } - - // It's valid. - return true -} - -func (itr cLevelDBIterator) Key() []byte { - itr.assertNoError() - itr.assertIsValid() - return itr.source.Key() -} - -func (itr cLevelDBIterator) Value() []byte { - itr.assertNoError() - itr.assertIsValid() - return itr.source.Value() -} - -func (itr cLevelDBIterator) Next() { - itr.assertNoError() - itr.assertIsValid() - if itr.isReverse { - itr.source.Prev() - } else { - itr.source.Next() - } -} - -func (itr cLevelDBIterator) Close() { - itr.source.Close() -} - -func (itr cLevelDBIterator) assertNoError() { - if err := itr.source.GetError(); err != nil { - panic(err) - } -} - -func (itr cLevelDBIterator) assertIsValid() { - if !itr.Valid() { - panic("cLevelDBIterator is invalid") - } -} diff --git a/libs/db/c_level_db_test.go b/libs/db/c_level_db_test.go deleted file mode 100644 index 1c10fcdef..000000000 --- a/libs/db/c_level_db_test.go +++ /dev/null @@ -1,110 +0,0 @@ -// +build cleveldb - -package db - -import ( - "bytes" - "fmt" - "os" - "testing" - - "github.com/stretchr/testify/assert" - - cmn "github.com/tendermint/tendermint/libs/common" -) - -func BenchmarkRandomReadsWrites2(b *testing.B) { - b.StopTimer() - - numItems := int64(1000000) - internal := map[int64]int64{} - for i := 0; i < int(numItems); i++ { - internal[int64(i)] = int64(0) - } - db, err := NewCLevelDB(fmt.Sprintf("test_%x", cmn.RandStr(12)), "") - if err != nil { - b.Fatal(err.Error()) - return - } - - fmt.Println("ok, starting") - b.StartTimer() - - for i := 0; i < b.N; i++ { - // Write something - { - idx := (int64(cmn.RandInt()) % numItems) - internal[idx]++ - val := internal[idx] - idxBytes := int642Bytes(int64(idx)) - valBytes := int642Bytes(int64(val)) - //fmt.Printf("Set %X -> %X\n", idxBytes, valBytes) - db.Set( - idxBytes, - valBytes, - ) - } - // Read something - { - idx := (int64(cmn.RandInt()) % numItems) - val := internal[idx] - idxBytes := int642Bytes(int64(idx)) - valBytes := db.Get(idxBytes) - //fmt.Printf("Get %X -> %X\n", idxBytes, valBytes) - if val == 0 { - if !bytes.Equal(valBytes, nil) { - b.Errorf("Expected %v for %v, got %X", - nil, idx, valBytes) - break - } - } else { - if len(valBytes) != 8 { - b.Errorf("Expected length 8 for %v, got %X", - idx, valBytes) - break - } - valGot := bytes2Int64(valBytes) - if val != valGot { - b.Errorf("Expected %v for %v, got %v", - val, idx, valGot) - break - } - } - } - } - - db.Close() -} - -/* -func int642Bytes(i int64) []byte { - buf := make([]byte, 8) - binary.BigEndian.PutUint64(buf, uint64(i)) - return buf -} - -func bytes2Int64(buf []byte) int64 { - return int64(binary.BigEndian.Uint64(buf)) -} -*/ - -func TestCLevelDBBackend(t *testing.T) { - name := fmt.Sprintf("test_%x", cmn.RandStr(12)) - // Can't use "" (current directory) or "./" here because levigo.Open returns: - // "Error initializing DB: IO error: test_XXX.db: Invalid argument" - dir := os.TempDir() - db := NewDB(name, CLevelDBBackend, dir) - defer cleanupDBDir(dir, name) - - _, ok := db.(*CLevelDB) - assert.True(t, ok) -} - -func TestCLevelDBStats(t *testing.T) { - name := fmt.Sprintf("test_%x", cmn.RandStr(12)) - dir := os.TempDir() - db := NewDB(name, CLevelDBBackend, dir) - defer cleanupDBDir(dir, name) - - assert.NotEmpty(t, db.Stats()) -} diff --git a/libs/db/common_test.go b/libs/db/common_test.go deleted file mode 100644 index 64a86979c..000000000 --- a/libs/db/common_test.go +++ /dev/null @@ -1,256 +0,0 @@ -package db - -import ( - "bytes" - "encoding/binary" - "fmt" - "io/ioutil" - "sync" - "testing" - - "github.com/stretchr/testify/assert" - "github.com/stretchr/testify/require" - cmn "github.com/tendermint/tendermint/libs/common" -) - -//---------------------------------------- -// Helper functions. - -func checkValue(t *testing.T, db DB, key []byte, valueWanted []byte) { - valueGot := db.Get(key) - assert.Equal(t, valueWanted, valueGot) -} - -func checkValid(t *testing.T, itr Iterator, expected bool) { - valid := itr.Valid() - require.Equal(t, expected, valid) -} - -func checkNext(t *testing.T, itr Iterator, expected bool) { - itr.Next() - valid := itr.Valid() - require.Equal(t, expected, valid) -} - -func checkNextPanics(t *testing.T, itr Iterator) { - assert.Panics(t, func() { itr.Next() }, "checkNextPanics expected panic but didn't") -} - -func checkDomain(t *testing.T, itr Iterator, start, end []byte) { - ds, de := itr.Domain() - assert.Equal(t, start, ds, "checkDomain domain start incorrect") - assert.Equal(t, end, de, "checkDomain domain end incorrect") -} - -func checkItem(t *testing.T, itr Iterator, key []byte, value []byte) { - k, v := itr.Key(), itr.Value() - assert.Exactly(t, key, k) - assert.Exactly(t, value, v) -} - -func checkInvalid(t *testing.T, itr Iterator) { - checkValid(t, itr, false) - checkKeyPanics(t, itr) - checkValuePanics(t, itr) - checkNextPanics(t, itr) -} - -func checkKeyPanics(t *testing.T, itr Iterator) { - assert.Panics(t, func() { itr.Key() }, "checkKeyPanics expected panic but didn't") -} - -func checkValuePanics(t *testing.T, itr Iterator) { - assert.Panics(t, func() { itr.Value() }, "checkValuePanics expected panic but didn't") -} - -func newTempDB(t *testing.T, backend DBBackendType) (db DB, dbDir string) { - dirname, err := ioutil.TempDir("", "db_common_test") - require.Nil(t, err) - return NewDB("testdb", backend, dirname), dirname -} - -//---------------------------------------- -// mockDB - -// NOTE: not actually goroutine safe. -// If you want something goroutine safe, maybe you just want a MemDB. -type mockDB struct { - mtx sync.Mutex - calls map[string]int -} - -func newMockDB() *mockDB { - return &mockDB{ - calls: make(map[string]int), - } -} - -func (mdb *mockDB) Mutex() *sync.Mutex { - return &(mdb.mtx) -} - -func (mdb *mockDB) Get([]byte) []byte { - mdb.calls["Get"]++ - return nil -} - -func (mdb *mockDB) Has([]byte) bool { - mdb.calls["Has"]++ - return false -} - -func (mdb *mockDB) Set([]byte, []byte) { - mdb.calls["Set"]++ -} - -func (mdb *mockDB) SetSync([]byte, []byte) { - mdb.calls["SetSync"]++ -} - -func (mdb *mockDB) SetNoLock([]byte, []byte) { - mdb.calls["SetNoLock"]++ -} - -func (mdb *mockDB) SetNoLockSync([]byte, []byte) { - mdb.calls["SetNoLockSync"]++ -} - -func (mdb *mockDB) Delete([]byte) { - mdb.calls["Delete"]++ -} - -func (mdb *mockDB) DeleteSync([]byte) { - mdb.calls["DeleteSync"]++ -} - -func (mdb *mockDB) DeleteNoLock([]byte) { - mdb.calls["DeleteNoLock"]++ -} - -func (mdb *mockDB) DeleteNoLockSync([]byte) { - mdb.calls["DeleteNoLockSync"]++ -} - -func (mdb *mockDB) Iterator(start, end []byte) Iterator { - mdb.calls["Iterator"]++ - return &mockIterator{} -} - -func (mdb *mockDB) ReverseIterator(start, end []byte) Iterator { - mdb.calls["ReverseIterator"]++ - return &mockIterator{} -} - -func (mdb *mockDB) Close() { - mdb.calls["Close"]++ -} - -func (mdb *mockDB) NewBatch() Batch { - mdb.calls["NewBatch"]++ - return &memBatch{db: mdb} -} - -func (mdb *mockDB) Print() { - mdb.calls["Print"]++ - fmt.Printf("mockDB{%v}", mdb.Stats()) -} - -func (mdb *mockDB) Stats() map[string]string { - mdb.calls["Stats"]++ - - res := make(map[string]string) - for key, count := range mdb.calls { - res[key] = fmt.Sprintf("%d", count) - } - return res -} - -//---------------------------------------- -// mockIterator - -type mockIterator struct{} - -func (mockIterator) Domain() (start []byte, end []byte) { - return nil, nil -} - -func (mockIterator) Valid() bool { - return false -} - -func (mockIterator) Next() { -} - -func (mockIterator) Key() []byte { - return nil -} - -func (mockIterator) Value() []byte { - return nil -} - -func (mockIterator) Close() { -} - -func benchmarkRandomReadsWrites(b *testing.B, db DB) { - b.StopTimer() - - // create dummy data - const numItems = int64(1000000) - internal := map[int64]int64{} - for i := 0; i < int(numItems); i++ { - internal[int64(i)] = int64(0) - } - - // fmt.Println("ok, starting") - b.StartTimer() - - for i := 0; i < b.N; i++ { - // Write something - { - idx := int64(cmn.RandInt()) % numItems - internal[idx]++ - val := internal[idx] - idxBytes := int642Bytes(int64(idx)) - valBytes := int642Bytes(int64(val)) - //fmt.Printf("Set %X -> %X\n", idxBytes, valBytes) - db.Set(idxBytes, valBytes) - } - - // Read something - { - idx := int64(cmn.RandInt()) % numItems - valExp := internal[idx] - idxBytes := int642Bytes(int64(idx)) - valBytes := db.Get(idxBytes) - //fmt.Printf("Get %X -> %X\n", idxBytes, valBytes) - if valExp == 0 { - if !bytes.Equal(valBytes, nil) { - b.Errorf("Expected %v for %v, got %X", nil, idx, valBytes) - break - } - } else { - if len(valBytes) != 8 { - b.Errorf("Expected length 8 for %v, got %X", idx, valBytes) - break - } - valGot := bytes2Int64(valBytes) - if valExp != valGot { - b.Errorf("Expected %v for %v, got %v", valExp, idx, valGot) - break - } - } - } - - } -} - -func int642Bytes(i int64) []byte { - buf := make([]byte, 8) - binary.BigEndian.PutUint64(buf, uint64(i)) - return buf -} - -func bytes2Int64(buf []byte) int64 { - return int64(binary.BigEndian.Uint64(buf)) -} diff --git a/libs/db/db.go b/libs/db/db.go deleted file mode 100644 index d88df398c..000000000 --- a/libs/db/db.go +++ /dev/null @@ -1,70 +0,0 @@ -package db - -import ( - "fmt" - "strings" -) - -type DBBackendType string - -// These are valid backend types. -const ( - // GoLevelDBBackend represents goleveldb (github.com/syndtr/goleveldb - most - // popular implementation) - // - pure go - // - stable - GoLevelDBBackend DBBackendType = "goleveldb" - // CLevelDBBackend represents cleveldb (uses levigo wrapper) - // - fast - // - requires gcc - // - use cleveldb build tag (go build -tags cleveldb) - CLevelDBBackend DBBackendType = "cleveldb" - // MemDBBackend represents in-memoty key value store, which is mostly used - // for testing. - MemDBBackend DBBackendType = "memdb" - // FSDBBackend represents filesystem database - // - EXPERIMENTAL - // - slow - FSDBBackend DBBackendType = "fsdb" - // BoltDBBackend represents bolt (uses etcd's fork of bolt - - // github.com/etcd-io/bbolt) - // - EXPERIMENTAL - // - may be faster is some use-cases (random reads - indexer) - // - use boltdb build tag (go build -tags boltdb) - BoltDBBackend DBBackendType = "boltdb" -) - -type dbCreator func(name string, dir string) (DB, error) - -var backends = map[DBBackendType]dbCreator{} - -func registerDBCreator(backend DBBackendType, creator dbCreator, force bool) { - _, ok := backends[backend] - if !force && ok { - return - } - backends[backend] = creator -} - -// NewDB creates a new database of type backend with the given name. -// NOTE: function panics if: -// - backend is unknown (not registered) -// - creator function, provided during registration, returns error -func NewDB(name string, backend DBBackendType, dir string) DB { - dbCreator, ok := backends[backend] - if !ok { - keys := make([]string, len(backends)) - i := 0 - for k := range backends { - keys[i] = string(k) - i++ - } - panic(fmt.Sprintf("Unknown db_backend %s, expected either %s", backend, strings.Join(keys, " or "))) - } - - db, err := dbCreator(name, dir) - if err != nil { - panic(fmt.Sprintf("Error initializing DB: %v", err)) - } - return db -} diff --git a/libs/db/db_test.go b/libs/db/db_test.go deleted file mode 100644 index 22b781f95..000000000 --- a/libs/db/db_test.go +++ /dev/null @@ -1,194 +0,0 @@ -package db - -import ( - "fmt" - "os" - "testing" - - "github.com/stretchr/testify/assert" -) - -func TestDBIteratorSingleKey(t *testing.T) { - for backend := range backends { - t.Run(fmt.Sprintf("Backend %s", backend), func(t *testing.T) { - db, dir := newTempDB(t, backend) - defer os.RemoveAll(dir) - - db.SetSync(bz("1"), bz("value_1")) - itr := db.Iterator(nil, nil) - - checkValid(t, itr, true) - checkNext(t, itr, false) - checkValid(t, itr, false) - checkNextPanics(t, itr) - - // Once invalid... - checkInvalid(t, itr) - }) - } -} - -func TestDBIteratorTwoKeys(t *testing.T) { - for backend := range backends { - t.Run(fmt.Sprintf("Backend %s", backend), func(t *testing.T) { - db, dir := newTempDB(t, backend) - defer os.RemoveAll(dir) - - db.SetSync(bz("1"), bz("value_1")) - db.SetSync(bz("2"), bz("value_1")) - - { // Fail by calling Next too much - itr := db.Iterator(nil, nil) - checkValid(t, itr, true) - - checkNext(t, itr, true) - checkValid(t, itr, true) - - checkNext(t, itr, false) - checkValid(t, itr, false) - - checkNextPanics(t, itr) - - // Once invalid... - checkInvalid(t, itr) - } - }) - } -} - -func TestDBIteratorMany(t *testing.T) { - for backend := range backends { - t.Run(fmt.Sprintf("Backend %s", backend), func(t *testing.T) { - db, dir := newTempDB(t, backend) - defer os.RemoveAll(dir) - - keys := make([][]byte, 100) - for i := 0; i < 100; i++ { - keys[i] = []byte{byte(i)} - } - - value := []byte{5} - for _, k := range keys { - db.Set(k, value) - } - - itr := db.Iterator(nil, nil) - defer itr.Close() - for ; itr.Valid(); itr.Next() { - assert.Equal(t, db.Get(itr.Key()), itr.Value()) - } - }) - } -} - -func TestDBIteratorEmpty(t *testing.T) { - for backend := range backends { - t.Run(fmt.Sprintf("Backend %s", backend), func(t *testing.T) { - db, dir := newTempDB(t, backend) - defer os.RemoveAll(dir) - - itr := db.Iterator(nil, nil) - - checkInvalid(t, itr) - }) - } -} - -func TestDBIteratorEmptyBeginAfter(t *testing.T) { - for backend := range backends { - t.Run(fmt.Sprintf("Backend %s", backend), func(t *testing.T) { - db, dir := newTempDB(t, backend) - defer os.RemoveAll(dir) - - itr := db.Iterator(bz("1"), nil) - - checkInvalid(t, itr) - }) - } -} - -func TestDBIteratorNonemptyBeginAfter(t *testing.T) { - for backend := range backends { - t.Run(fmt.Sprintf("Backend %s", backend), func(t *testing.T) { - db, dir := newTempDB(t, backend) - defer os.RemoveAll(dir) - - db.SetSync(bz("1"), bz("value_1")) - itr := db.Iterator(bz("2"), nil) - - checkInvalid(t, itr) - }) - } -} - -func TestDBBatchWrite(t *testing.T) { - testCases := []struct { - modify func(batch Batch) - calls map[string]int - }{ - 0: { - func(batch Batch) { - batch.Set(bz("1"), bz("1")) - batch.Set(bz("2"), bz("2")) - batch.Delete(bz("3")) - batch.Set(bz("4"), bz("4")) - batch.Write() - }, - map[string]int{ - "Set": 0, "SetSync": 0, "SetNoLock": 3, "SetNoLockSync": 0, - "Delete": 0, "DeleteSync": 0, "DeleteNoLock": 1, "DeleteNoLockSync": 0, - }, - }, - 1: { - func(batch Batch) { - batch.Set(bz("1"), bz("1")) - batch.Set(bz("2"), bz("2")) - batch.Set(bz("4"), bz("4")) - batch.Delete(bz("3")) - batch.Write() - }, - map[string]int{ - "Set": 0, "SetSync": 0, "SetNoLock": 3, "SetNoLockSync": 0, - "Delete": 0, "DeleteSync": 0, "DeleteNoLock": 1, "DeleteNoLockSync": 0, - }, - }, - 2: { - func(batch Batch) { - batch.Set(bz("1"), bz("1")) - batch.Set(bz("2"), bz("2")) - batch.Delete(bz("3")) - batch.Set(bz("4"), bz("4")) - batch.WriteSync() - }, - map[string]int{ - "Set": 0, "SetSync": 0, "SetNoLock": 2, "SetNoLockSync": 1, - "Delete": 0, "DeleteSync": 0, "DeleteNoLock": 1, "DeleteNoLockSync": 0, - }, - }, - 3: { - func(batch Batch) { - batch.Set(bz("1"), bz("1")) - batch.Set(bz("2"), bz("2")) - batch.Set(bz("4"), bz("4")) - batch.Delete(bz("3")) - batch.WriteSync() - }, - map[string]int{ - "Set": 0, "SetSync": 0, "SetNoLock": 3, "SetNoLockSync": 0, - "Delete": 0, "DeleteSync": 0, "DeleteNoLock": 0, "DeleteNoLockSync": 1, - }, - }, - } - - for i, tc := range testCases { - mdb := newMockDB() - batch := mdb.NewBatch() - - tc.modify(batch) - - for call, exp := range tc.calls { - got := mdb.calls[call] - assert.Equal(t, exp, got, "#%v - key: %s", i, call) - } - } -} diff --git a/libs/db/fsdb.go b/libs/db/fsdb.go deleted file mode 100644 index ca8eefe94..000000000 --- a/libs/db/fsdb.go +++ /dev/null @@ -1,270 +0,0 @@ -package db - -import ( - "fmt" - "io/ioutil" - "net/url" - "os" - "path/filepath" - "sort" - "sync" - - "github.com/pkg/errors" - - cmn "github.com/tendermint/tendermint/libs/common" -) - -const ( - keyPerm = os.FileMode(0600) - dirPerm = os.FileMode(0700) -) - -func init() { - registerDBCreator(FSDBBackend, func(name, dir string) (DB, error) { - dbPath := filepath.Join(dir, name+".db") - return NewFSDB(dbPath), nil - }, false) -} - -var _ DB = (*FSDB)(nil) - -// It's slow. -type FSDB struct { - mtx sync.Mutex - dir string -} - -func NewFSDB(dir string) *FSDB { - err := os.MkdirAll(dir, dirPerm) - if err != nil { - panic(errors.Wrap(err, "Creating FSDB dir "+dir)) - } - database := &FSDB{ - dir: dir, - } - return database -} - -func (db *FSDB) Get(key []byte) []byte { - db.mtx.Lock() - defer db.mtx.Unlock() - key = escapeKey(key) - - path := db.nameToPath(key) - value, err := read(path) - if os.IsNotExist(err) { - return nil - } else if err != nil { - panic(errors.Wrapf(err, "Getting key %s (0x%X)", string(key), key)) - } - return value -} - -func (db *FSDB) Has(key []byte) bool { - db.mtx.Lock() - defer db.mtx.Unlock() - key = escapeKey(key) - - path := db.nameToPath(key) - return cmn.FileExists(path) -} - -func (db *FSDB) Set(key []byte, value []byte) { - db.mtx.Lock() - defer db.mtx.Unlock() - - db.SetNoLock(key, value) -} - -func (db *FSDB) SetSync(key []byte, value []byte) { - db.mtx.Lock() - defer db.mtx.Unlock() - - db.SetNoLock(key, value) -} - -// NOTE: Implements atomicSetDeleter. -func (db *FSDB) SetNoLock(key []byte, value []byte) { - key = escapeKey(key) - value = nonNilBytes(value) - path := db.nameToPath(key) - err := write(path, value) - if err != nil { - panic(errors.Wrapf(err, "Setting key %s (0x%X)", string(key), key)) - } -} - -func (db *FSDB) Delete(key []byte) { - db.mtx.Lock() - defer db.mtx.Unlock() - - db.DeleteNoLock(key) -} - -func (db *FSDB) DeleteSync(key []byte) { - db.mtx.Lock() - defer db.mtx.Unlock() - - db.DeleteNoLock(key) -} - -// NOTE: Implements atomicSetDeleter. -func (db *FSDB) DeleteNoLock(key []byte) { - key = escapeKey(key) - path := db.nameToPath(key) - err := remove(path) - if os.IsNotExist(err) { - return - } else if err != nil { - panic(errors.Wrapf(err, "Removing key %s (0x%X)", string(key), key)) - } -} - -func (db *FSDB) Close() { - // Nothing to do. -} - -func (db *FSDB) Print() { - db.mtx.Lock() - defer db.mtx.Unlock() - - panic("FSDB.Print not yet implemented") -} - -func (db *FSDB) Stats() map[string]string { - db.mtx.Lock() - defer db.mtx.Unlock() - - panic("FSDB.Stats not yet implemented") -} - -func (db *FSDB) NewBatch() Batch { - db.mtx.Lock() - defer db.mtx.Unlock() - - // Not sure we would ever want to try... - // It doesn't seem easy for general filesystems. - panic("FSDB.NewBatch not yet implemented") -} - -func (db *FSDB) Mutex() *sync.Mutex { - return &(db.mtx) -} - -func (db *FSDB) Iterator(start, end []byte) Iterator { - return db.MakeIterator(start, end, false) -} - -func (db *FSDB) MakeIterator(start, end []byte, isReversed bool) Iterator { - db.mtx.Lock() - defer db.mtx.Unlock() - - // We need a copy of all of the keys. - // Not the best, but probably not a bottleneck depending. - keys, err := list(db.dir, start, end) - if err != nil { - panic(errors.Wrapf(err, "Listing keys in %s", db.dir)) - } - if isReversed { - sort.Sort(sort.Reverse(sort.StringSlice(keys))) - } else { - sort.Strings(keys) - } - return newMemDBIterator(db, keys, start, end) -} - -func (db *FSDB) ReverseIterator(start, end []byte) Iterator { - return db.MakeIterator(start, end, true) -} - -func (db *FSDB) nameToPath(name []byte) string { - n := url.PathEscape(string(name)) - return filepath.Join(db.dir, n) -} - -// Read some bytes to a file. -// CONTRACT: returns os errors directly without wrapping. -func read(path string) ([]byte, error) { - f, err := os.Open(path) - if err != nil { - return nil, err - } - defer f.Close() - - d, err := ioutil.ReadAll(f) - if err != nil { - return nil, err - } - return d, nil -} - -// Write some bytes from a file. -// CONTRACT: returns os errors directly without wrapping. -func write(path string, d []byte) error { - f, err := os.OpenFile(path, os.O_CREATE|os.O_WRONLY, keyPerm) - if err != nil { - return err - } - defer f.Close() - // fInfo, err := f.Stat() - // if err != nil { - // return err - // } - // if fInfo.Mode() != keyPerm { - // return tmerrors.NewErrPermissionsChanged(f.Name(), keyPerm, fInfo.Mode()) - // } - _, err = f.Write(d) - if err != nil { - return err - } - err = f.Sync() - return err -} - -// Remove a file. -// CONTRACT: returns os errors directly without wrapping. -func remove(path string) error { - return os.Remove(path) -} - -// List keys in a directory, stripping of escape sequences and dir portions. -// CONTRACT: returns os errors directly without wrapping. -func list(dirPath string, start, end []byte) ([]string, error) { - dir, err := os.Open(dirPath) - if err != nil { - return nil, err - } - defer dir.Close() - - names, err := dir.Readdirnames(0) - if err != nil { - return nil, err - } - var keys []string - for _, name := range names { - n, err := url.PathUnescape(name) - if err != nil { - return nil, fmt.Errorf("Failed to unescape %s while listing", name) - } - key := unescapeKey([]byte(n)) - if IsKeyInDomain(key, start, end) { - keys = append(keys, string(key)) - } - } - return keys, nil -} - -// To support empty or nil keys, while the file system doesn't allow empty -// filenames. -func escapeKey(key []byte) []byte { - return []byte("k_" + string(key)) -} -func unescapeKey(escKey []byte) []byte { - if len(escKey) < 2 { - panic(fmt.Sprintf("Invalid esc key: %x", escKey)) - } - if string(escKey[:2]) != "k_" { - panic(fmt.Sprintf("Invalid esc key: %x", escKey)) - } - return escKey[2:] -} diff --git a/libs/db/go_level_db.go b/libs/db/go_level_db.go deleted file mode 100644 index 8c20ccdde..000000000 --- a/libs/db/go_level_db.go +++ /dev/null @@ -1,333 +0,0 @@ -package db - -import ( - "bytes" - "fmt" - "path/filepath" - - "github.com/syndtr/goleveldb/leveldb" - "github.com/syndtr/goleveldb/leveldb/errors" - "github.com/syndtr/goleveldb/leveldb/iterator" - "github.com/syndtr/goleveldb/leveldb/opt" -) - -func init() { - dbCreator := func(name string, dir string) (DB, error) { - return NewGoLevelDB(name, dir) - } - registerDBCreator(GoLevelDBBackend, dbCreator, false) -} - -var _ DB = (*GoLevelDB)(nil) - -type GoLevelDB struct { - db *leveldb.DB -} - -func NewGoLevelDB(name string, dir string) (*GoLevelDB, error) { - return NewGoLevelDBWithOpts(name, dir, nil) -} - -func NewGoLevelDBWithOpts(name string, dir string, o *opt.Options) (*GoLevelDB, error) { - dbPath := filepath.Join(dir, name+".db") - db, err := leveldb.OpenFile(dbPath, o) - if err != nil { - return nil, err - } - database := &GoLevelDB{ - db: db, - } - return database, nil -} - -// Implements DB. -func (db *GoLevelDB) Get(key []byte) []byte { - key = nonNilBytes(key) - res, err := db.db.Get(key, nil) - if err != nil { - if err == errors.ErrNotFound { - return nil - } - panic(err) - } - return res -} - -// Implements DB. -func (db *GoLevelDB) Has(key []byte) bool { - return db.Get(key) != nil -} - -// Implements DB. -func (db *GoLevelDB) Set(key []byte, value []byte) { - key = nonNilBytes(key) - value = nonNilBytes(value) - err := db.db.Put(key, value, nil) - if err != nil { - panic(err) - } -} - -// Implements DB. -func (db *GoLevelDB) SetSync(key []byte, value []byte) { - key = nonNilBytes(key) - value = nonNilBytes(value) - err := db.db.Put(key, value, &opt.WriteOptions{Sync: true}) - if err != nil { - panic(err) - } -} - -// Implements DB. -func (db *GoLevelDB) Delete(key []byte) { - key = nonNilBytes(key) - err := db.db.Delete(key, nil) - if err != nil { - panic(err) - } -} - -// Implements DB. -func (db *GoLevelDB) DeleteSync(key []byte) { - key = nonNilBytes(key) - err := db.db.Delete(key, &opt.WriteOptions{Sync: true}) - if err != nil { - panic(err) - } -} - -func (db *GoLevelDB) DB() *leveldb.DB { - return db.db -} - -// Implements DB. -func (db *GoLevelDB) Close() { - db.db.Close() -} - -// Implements DB. -func (db *GoLevelDB) Print() { - str, _ := db.db.GetProperty("leveldb.stats") - fmt.Printf("%v\n", str) - - itr := db.db.NewIterator(nil, nil) - for itr.Next() { - key := itr.Key() - value := itr.Value() - fmt.Printf("[%X]:\t[%X]\n", key, value) - } -} - -// Implements DB. -func (db *GoLevelDB) Stats() map[string]string { - keys := []string{ - "leveldb.num-files-at-level{n}", - "leveldb.stats", - "leveldb.sstables", - "leveldb.blockpool", - "leveldb.cachedblock", - "leveldb.openedtables", - "leveldb.alivesnaps", - "leveldb.aliveiters", - } - - stats := make(map[string]string) - for _, key := range keys { - str, err := db.db.GetProperty(key) - if err == nil { - stats[key] = str - } - } - return stats -} - -//---------------------------------------- -// Batch - -// Implements DB. -func (db *GoLevelDB) NewBatch() Batch { - batch := new(leveldb.Batch) - return &goLevelDBBatch{db, batch} -} - -type goLevelDBBatch struct { - db *GoLevelDB - batch *leveldb.Batch -} - -// Implements Batch. -func (mBatch *goLevelDBBatch) Set(key, value []byte) { - mBatch.batch.Put(key, value) -} - -// Implements Batch. -func (mBatch *goLevelDBBatch) Delete(key []byte) { - mBatch.batch.Delete(key) -} - -// Implements Batch. -func (mBatch *goLevelDBBatch) Write() { - err := mBatch.db.db.Write(mBatch.batch, &opt.WriteOptions{Sync: false}) - if err != nil { - panic(err) - } -} - -// Implements Batch. -func (mBatch *goLevelDBBatch) WriteSync() { - err := mBatch.db.db.Write(mBatch.batch, &opt.WriteOptions{Sync: true}) - if err != nil { - panic(err) - } -} - -// Implements Batch. -// Close is no-op for goLevelDBBatch. -func (mBatch *goLevelDBBatch) Close() {} - -//---------------------------------------- -// Iterator -// NOTE This is almost identical to db/c_level_db.Iterator -// Before creating a third version, refactor. - -// Implements DB. -func (db *GoLevelDB) Iterator(start, end []byte) Iterator { - itr := db.db.NewIterator(nil, nil) - return newGoLevelDBIterator(itr, start, end, false) -} - -// Implements DB. -func (db *GoLevelDB) ReverseIterator(start, end []byte) Iterator { - itr := db.db.NewIterator(nil, nil) - return newGoLevelDBIterator(itr, start, end, true) -} - -type goLevelDBIterator struct { - source iterator.Iterator - start []byte - end []byte - isReverse bool - isInvalid bool -} - -var _ Iterator = (*goLevelDBIterator)(nil) - -func newGoLevelDBIterator(source iterator.Iterator, start, end []byte, isReverse bool) *goLevelDBIterator { - if isReverse { - if end == nil { - source.Last() - } else { - valid := source.Seek(end) - if valid { - eoakey := source.Key() // end or after key - if bytes.Compare(end, eoakey) <= 0 { - source.Prev() - } - } else { - source.Last() - } - } - } else { - if start == nil { - source.First() - } else { - source.Seek(start) - } - } - return &goLevelDBIterator{ - source: source, - start: start, - end: end, - isReverse: isReverse, - isInvalid: false, - } -} - -// Implements Iterator. -func (itr *goLevelDBIterator) Domain() ([]byte, []byte) { - return itr.start, itr.end -} - -// Implements Iterator. -func (itr *goLevelDBIterator) Valid() bool { - - // Once invalid, forever invalid. - if itr.isInvalid { - return false - } - - // Panic on DB error. No way to recover. - itr.assertNoError() - - // If source is invalid, invalid. - if !itr.source.Valid() { - itr.isInvalid = true - return false - } - - // If key is end or past it, invalid. - var start = itr.start - var end = itr.end - var key = itr.source.Key() - - if itr.isReverse { - if start != nil && bytes.Compare(key, start) < 0 { - itr.isInvalid = true - return false - } - } else { - if end != nil && bytes.Compare(end, key) <= 0 { - itr.isInvalid = true - return false - } - } - - // Valid - return true -} - -// Implements Iterator. -func (itr *goLevelDBIterator) Key() []byte { - // Key returns a copy of the current key. - // See https://github.com/syndtr/goleveldb/blob/52c212e6c196a1404ea59592d3f1c227c9f034b2/leveldb/iterator/iter.go#L88 - itr.assertNoError() - itr.assertIsValid() - return cp(itr.source.Key()) -} - -// Implements Iterator. -func (itr *goLevelDBIterator) Value() []byte { - // Value returns a copy of the current value. - // See https://github.com/syndtr/goleveldb/blob/52c212e6c196a1404ea59592d3f1c227c9f034b2/leveldb/iterator/iter.go#L88 - itr.assertNoError() - itr.assertIsValid() - return cp(itr.source.Value()) -} - -// Implements Iterator. -func (itr *goLevelDBIterator) Next() { - itr.assertNoError() - itr.assertIsValid() - if itr.isReverse { - itr.source.Prev() - } else { - itr.source.Next() - } -} - -// Implements Iterator. -func (itr *goLevelDBIterator) Close() { - itr.source.Release() -} - -func (itr *goLevelDBIterator) assertNoError() { - if err := itr.source.Error(); err != nil { - panic(err) - } -} - -func (itr goLevelDBIterator) assertIsValid() { - if !itr.Valid() { - panic("goLevelDBIterator is invalid") - } -} diff --git a/libs/db/go_level_db_test.go b/libs/db/go_level_db_test.go deleted file mode 100644 index f781a2b3d..000000000 --- a/libs/db/go_level_db_test.go +++ /dev/null @@ -1,45 +0,0 @@ -package db - -import ( - "fmt" - "testing" - - "github.com/stretchr/testify/require" - "github.com/syndtr/goleveldb/leveldb/opt" - - cmn "github.com/tendermint/tendermint/libs/common" -) - -func TestGoLevelDBNewGoLevelDB(t *testing.T) { - name := fmt.Sprintf("test_%x", cmn.RandStr(12)) - defer cleanupDBDir("", name) - - // Test we can't open the db twice for writing - wr1, err := NewGoLevelDB(name, "") - require.Nil(t, err) - _, err = NewGoLevelDB(name, "") - require.NotNil(t, err) - wr1.Close() // Close the db to release the lock - - // Test we can open the db twice for reading only - ro1, err := NewGoLevelDBWithOpts(name, "", &opt.Options{ReadOnly: true}) - defer ro1.Close() - require.Nil(t, err) - ro2, err := NewGoLevelDBWithOpts(name, "", &opt.Options{ReadOnly: true}) - defer ro2.Close() - require.Nil(t, err) -} - -func BenchmarkGoLevelDBRandomReadsWrites(b *testing.B) { - name := fmt.Sprintf("test_%x", cmn.RandStr(12)) - db, err := NewGoLevelDB(name, "") - if err != nil { - b.Fatal(err) - } - defer func() { - db.Close() - cleanupDBDir("", name) - }() - - benchmarkRandomReadsWrites(b, db) -} diff --git a/libs/db/mem_batch.go b/libs/db/mem_batch.go deleted file mode 100644 index 2ce765786..000000000 --- a/libs/db/mem_batch.go +++ /dev/null @@ -1,74 +0,0 @@ -package db - -import "sync" - -type atomicSetDeleter interface { - Mutex() *sync.Mutex - SetNoLock(key, value []byte) - SetNoLockSync(key, value []byte) - DeleteNoLock(key []byte) - DeleteNoLockSync(key []byte) -} - -type memBatch struct { - db atomicSetDeleter - ops []operation -} - -type opType int - -const ( - opTypeSet opType = 1 - opTypeDelete opType = 2 -) - -type operation struct { - opType - key []byte - value []byte -} - -func (mBatch *memBatch) Set(key, value []byte) { - mBatch.ops = append(mBatch.ops, operation{opTypeSet, key, value}) -} - -func (mBatch *memBatch) Delete(key []byte) { - mBatch.ops = append(mBatch.ops, operation{opTypeDelete, key, nil}) -} - -func (mBatch *memBatch) Write() { - mBatch.write(false) -} - -func (mBatch *memBatch) WriteSync() { - mBatch.write(true) -} - -func (mBatch *memBatch) Close() { - mBatch.ops = nil -} - -func (mBatch *memBatch) write(doSync bool) { - if mtx := mBatch.db.Mutex(); mtx != nil { - mtx.Lock() - defer mtx.Unlock() - } - - for i, op := range mBatch.ops { - if doSync && i == (len(mBatch.ops)-1) { - switch op.opType { - case opTypeSet: - mBatch.db.SetNoLockSync(op.key, op.value) - case opTypeDelete: - mBatch.db.DeleteNoLockSync(op.key) - } - break // we're done. - } - switch op.opType { - case opTypeSet: - mBatch.db.SetNoLock(op.key, op.value) - case opTypeDelete: - mBatch.db.DeleteNoLock(op.key) - } - } -} diff --git a/libs/db/mem_db.go b/libs/db/mem_db.go deleted file mode 100644 index fc567577d..000000000 --- a/libs/db/mem_db.go +++ /dev/null @@ -1,255 +0,0 @@ -package db - -import ( - "fmt" - "sort" - "sync" -) - -func init() { - registerDBCreator(MemDBBackend, func(name, dir string) (DB, error) { - return NewMemDB(), nil - }, false) -} - -var _ DB = (*MemDB)(nil) - -type MemDB struct { - mtx sync.Mutex - db map[string][]byte -} - -func NewMemDB() *MemDB { - database := &MemDB{ - db: make(map[string][]byte), - } - return database -} - -// Implements atomicSetDeleter. -func (db *MemDB) Mutex() *sync.Mutex { - return &(db.mtx) -} - -// Implements DB. -func (db *MemDB) Get(key []byte) []byte { - db.mtx.Lock() - defer db.mtx.Unlock() - key = nonNilBytes(key) - - value := db.db[string(key)] - return value -} - -// Implements DB. -func (db *MemDB) Has(key []byte) bool { - db.mtx.Lock() - defer db.mtx.Unlock() - key = nonNilBytes(key) - - _, ok := db.db[string(key)] - return ok -} - -// Implements DB. -func (db *MemDB) Set(key []byte, value []byte) { - db.mtx.Lock() - defer db.mtx.Unlock() - - db.SetNoLock(key, value) -} - -// Implements DB. -func (db *MemDB) SetSync(key []byte, value []byte) { - db.mtx.Lock() - defer db.mtx.Unlock() - - db.SetNoLock(key, value) -} - -// Implements atomicSetDeleter. -func (db *MemDB) SetNoLock(key []byte, value []byte) { - db.SetNoLockSync(key, value) -} - -// Implements atomicSetDeleter. -func (db *MemDB) SetNoLockSync(key []byte, value []byte) { - key = nonNilBytes(key) - value = nonNilBytes(value) - - db.db[string(key)] = value -} - -// Implements DB. -func (db *MemDB) Delete(key []byte) { - db.mtx.Lock() - defer db.mtx.Unlock() - - db.DeleteNoLock(key) -} - -// Implements DB. -func (db *MemDB) DeleteSync(key []byte) { - db.mtx.Lock() - defer db.mtx.Unlock() - - db.DeleteNoLock(key) -} - -// Implements atomicSetDeleter. -func (db *MemDB) DeleteNoLock(key []byte) { - db.DeleteNoLockSync(key) -} - -// Implements atomicSetDeleter. -func (db *MemDB) DeleteNoLockSync(key []byte) { - key = nonNilBytes(key) - - delete(db.db, string(key)) -} - -// Implements DB. -func (db *MemDB) Close() { - // Close is a noop since for an in-memory - // database, we don't have a destination - // to flush contents to nor do we want - // any data loss on invoking Close() - // See the discussion in https://github.com/tendermint/tendermint/libs/pull/56 -} - -// Implements DB. -func (db *MemDB) Print() { - db.mtx.Lock() - defer db.mtx.Unlock() - - for key, value := range db.db { - fmt.Printf("[%X]:\t[%X]\n", []byte(key), value) - } -} - -// Implements DB. -func (db *MemDB) Stats() map[string]string { - db.mtx.Lock() - defer db.mtx.Unlock() - - stats := make(map[string]string) - stats["database.type"] = "memDB" - stats["database.size"] = fmt.Sprintf("%d", len(db.db)) - return stats -} - -// Implements DB. -func (db *MemDB) NewBatch() Batch { - db.mtx.Lock() - defer db.mtx.Unlock() - - return &memBatch{db, nil} -} - -//---------------------------------------- -// Iterator - -// Implements DB. -func (db *MemDB) Iterator(start, end []byte) Iterator { - db.mtx.Lock() - defer db.mtx.Unlock() - - keys := db.getSortedKeys(start, end, false) - return newMemDBIterator(db, keys, start, end) -} - -// Implements DB. -func (db *MemDB) ReverseIterator(start, end []byte) Iterator { - db.mtx.Lock() - defer db.mtx.Unlock() - - keys := db.getSortedKeys(start, end, true) - return newMemDBIterator(db, keys, start, end) -} - -// We need a copy of all of the keys. -// Not the best, but probably not a bottleneck depending. -type memDBIterator struct { - db DB - cur int - keys []string - start []byte - end []byte -} - -var _ Iterator = (*memDBIterator)(nil) - -// Keys is expected to be in reverse order for reverse iterators. -func newMemDBIterator(db DB, keys []string, start, end []byte) *memDBIterator { - return &memDBIterator{ - db: db, - cur: 0, - keys: keys, - start: start, - end: end, - } -} - -// Implements Iterator. -func (itr *memDBIterator) Domain() ([]byte, []byte) { - return itr.start, itr.end -} - -// Implements Iterator. -func (itr *memDBIterator) Valid() bool { - return 0 <= itr.cur && itr.cur < len(itr.keys) -} - -// Implements Iterator. -func (itr *memDBIterator) Next() { - itr.assertIsValid() - itr.cur++ -} - -// Implements Iterator. -func (itr *memDBIterator) Key() []byte { - itr.assertIsValid() - return []byte(itr.keys[itr.cur]) -} - -// Implements Iterator. -func (itr *memDBIterator) Value() []byte { - itr.assertIsValid() - key := []byte(itr.keys[itr.cur]) - return itr.db.Get(key) -} - -// Implements Iterator. -func (itr *memDBIterator) Close() { - itr.keys = nil - itr.db = nil -} - -func (itr *memDBIterator) assertIsValid() { - if !itr.Valid() { - panic("memDBIterator is invalid") - } -} - -//---------------------------------------- -// Misc. - -func (db *MemDB) getSortedKeys(start, end []byte, reverse bool) []string { - keys := []string{} - for key := range db.db { - inDomain := IsKeyInDomain([]byte(key), start, end) - if inDomain { - keys = append(keys, key) - } - } - sort.Strings(keys) - if reverse { - nkeys := len(keys) - for i := 0; i < nkeys/2; i++ { - temp := keys[i] - keys[i] = keys[nkeys-i-1] - keys[nkeys-i-1] = temp - } - } - return keys -} diff --git a/libs/db/prefix_db.go b/libs/db/prefix_db.go deleted file mode 100644 index 0dd06ef9d..000000000 --- a/libs/db/prefix_db.go +++ /dev/null @@ -1,336 +0,0 @@ -package db - -import ( - "bytes" - "fmt" - "sync" -) - -// IteratePrefix is a convenience function for iterating over a key domain -// restricted by prefix. -func IteratePrefix(db DB, prefix []byte) Iterator { - var start, end []byte - if len(prefix) == 0 { - start = nil - end = nil - } else { - start = cp(prefix) - end = cpIncr(prefix) - } - return db.Iterator(start, end) -} - -/* -TODO: Make test, maybe rename. -// Like IteratePrefix but the iterator strips the prefix from the keys. -func IteratePrefixStripped(db DB, prefix []byte) Iterator { - start, end := ... - return newPrefixIterator(prefix, start, end, IteratePrefix(db, prefix)) -} -*/ - -//---------------------------------------- -// prefixDB - -type prefixDB struct { - mtx sync.Mutex - prefix []byte - db DB -} - -// NewPrefixDB lets you namespace multiple DBs within a single DB. -func NewPrefixDB(db DB, prefix []byte) *prefixDB { - return &prefixDB{ - prefix: prefix, - db: db, - } -} - -// Implements atomicSetDeleter. -func (pdb *prefixDB) Mutex() *sync.Mutex { - return &(pdb.mtx) -} - -// Implements DB. -func (pdb *prefixDB) Get(key []byte) []byte { - pdb.mtx.Lock() - defer pdb.mtx.Unlock() - - pkey := pdb.prefixed(key) - value := pdb.db.Get(pkey) - return value -} - -// Implements DB. -func (pdb *prefixDB) Has(key []byte) bool { - pdb.mtx.Lock() - defer pdb.mtx.Unlock() - - return pdb.db.Has(pdb.prefixed(key)) -} - -// Implements DB. -func (pdb *prefixDB) Set(key []byte, value []byte) { - pdb.mtx.Lock() - defer pdb.mtx.Unlock() - - pkey := pdb.prefixed(key) - pdb.db.Set(pkey, value) -} - -// Implements DB. -func (pdb *prefixDB) SetSync(key []byte, value []byte) { - pdb.mtx.Lock() - defer pdb.mtx.Unlock() - - pdb.db.SetSync(pdb.prefixed(key), value) -} - -// Implements DB. -func (pdb *prefixDB) Delete(key []byte) { - pdb.mtx.Lock() - defer pdb.mtx.Unlock() - - pdb.db.Delete(pdb.prefixed(key)) -} - -// Implements DB. -func (pdb *prefixDB) DeleteSync(key []byte) { - pdb.mtx.Lock() - defer pdb.mtx.Unlock() - - pdb.db.DeleteSync(pdb.prefixed(key)) -} - -// Implements DB. -func (pdb *prefixDB) Iterator(start, end []byte) Iterator { - pdb.mtx.Lock() - defer pdb.mtx.Unlock() - - var pstart, pend []byte - pstart = append(cp(pdb.prefix), start...) - if end == nil { - pend = cpIncr(pdb.prefix) - } else { - pend = append(cp(pdb.prefix), end...) - } - return newPrefixIterator( - pdb.prefix, - start, - end, - pdb.db.Iterator( - pstart, - pend, - ), - ) -} - -// Implements DB. -func (pdb *prefixDB) ReverseIterator(start, end []byte) Iterator { - pdb.mtx.Lock() - defer pdb.mtx.Unlock() - - var pstart, pend []byte - pstart = append(cp(pdb.prefix), start...) - if end == nil { - pend = cpIncr(pdb.prefix) - } else { - pend = append(cp(pdb.prefix), end...) - } - ritr := pdb.db.ReverseIterator(pstart, pend) - return newPrefixIterator( - pdb.prefix, - start, - end, - ritr, - ) -} - -// Implements DB. -// Panics if the underlying DB is not an -// atomicSetDeleter. -func (pdb *prefixDB) NewBatch() Batch { - pdb.mtx.Lock() - defer pdb.mtx.Unlock() - - return newPrefixBatch(pdb.prefix, pdb.db.NewBatch()) -} - -/* NOTE: Uncomment to use memBatch instead of prefixBatch -// Implements atomicSetDeleter. -func (pdb *prefixDB) SetNoLock(key []byte, value []byte) { - pdb.db.(atomicSetDeleter).SetNoLock(pdb.prefixed(key), value) -} - -// Implements atomicSetDeleter. -func (pdb *prefixDB) SetNoLockSync(key []byte, value []byte) { - pdb.db.(atomicSetDeleter).SetNoLockSync(pdb.prefixed(key), value) -} - -// Implements atomicSetDeleter. -func (pdb *prefixDB) DeleteNoLock(key []byte) { - pdb.db.(atomicSetDeleter).DeleteNoLock(pdb.prefixed(key)) -} - -// Implements atomicSetDeleter. -func (pdb *prefixDB) DeleteNoLockSync(key []byte) { - pdb.db.(atomicSetDeleter).DeleteNoLockSync(pdb.prefixed(key)) -} -*/ - -// Implements DB. -func (pdb *prefixDB) Close() { - pdb.mtx.Lock() - defer pdb.mtx.Unlock() - - pdb.db.Close() -} - -// Implements DB. -func (pdb *prefixDB) Print() { - fmt.Printf("prefix: %X\n", pdb.prefix) - - itr := pdb.Iterator(nil, nil) - defer itr.Close() - for ; itr.Valid(); itr.Next() { - key := itr.Key() - value := itr.Value() - fmt.Printf("[%X]:\t[%X]\n", key, value) - } -} - -// Implements DB. -func (pdb *prefixDB) Stats() map[string]string { - stats := make(map[string]string) - stats["prefixdb.prefix.string"] = string(pdb.prefix) - stats["prefixdb.prefix.hex"] = fmt.Sprintf("%X", pdb.prefix) - source := pdb.db.Stats() - for key, value := range source { - stats["prefixdb.source."+key] = value - } - return stats -} - -func (pdb *prefixDB) prefixed(key []byte) []byte { - return append(cp(pdb.prefix), key...) -} - -//---------------------------------------- -// prefixBatch - -type prefixBatch struct { - prefix []byte - source Batch -} - -func newPrefixBatch(prefix []byte, source Batch) prefixBatch { - return prefixBatch{ - prefix: prefix, - source: source, - } -} - -func (pb prefixBatch) Set(key, value []byte) { - pkey := append(cp(pb.prefix), key...) - pb.source.Set(pkey, value) -} - -func (pb prefixBatch) Delete(key []byte) { - pkey := append(cp(pb.prefix), key...) - pb.source.Delete(pkey) -} - -func (pb prefixBatch) Write() { - pb.source.Write() -} - -func (pb prefixBatch) WriteSync() { - pb.source.WriteSync() -} - -func (pb prefixBatch) Close() { - pb.source.Close() -} - -//---------------------------------------- -// prefixIterator - -var _ Iterator = (*prefixIterator)(nil) - -// Strips prefix while iterating from Iterator. -type prefixIterator struct { - prefix []byte - start []byte - end []byte - source Iterator - valid bool -} - -func newPrefixIterator(prefix, start, end []byte, source Iterator) *prefixIterator { - if !source.Valid() || !bytes.HasPrefix(source.Key(), prefix) { - return &prefixIterator{ - prefix: prefix, - start: start, - end: end, - source: source, - valid: false, - } - } else { - return &prefixIterator{ - prefix: prefix, - start: start, - end: end, - source: source, - valid: true, - } - } -} - -func (itr *prefixIterator) Domain() (start []byte, end []byte) { - return itr.start, itr.end -} - -func (itr *prefixIterator) Valid() bool { - return itr.valid && itr.source.Valid() -} - -func (itr *prefixIterator) Next() { - if !itr.valid { - panic("prefixIterator invalid, cannot call Next()") - } - itr.source.Next() - if !itr.source.Valid() || !bytes.HasPrefix(itr.source.Key(), itr.prefix) { - itr.valid = false - return - } -} - -func (itr *prefixIterator) Key() (key []byte) { - if !itr.valid { - panic("prefixIterator invalid, cannot call Key()") - } - return stripPrefix(itr.source.Key(), itr.prefix) -} - -func (itr *prefixIterator) Value() (value []byte) { - if !itr.valid { - panic("prefixIterator invalid, cannot call Value()") - } - return itr.source.Value() -} - -func (itr *prefixIterator) Close() { - itr.source.Close() -} - -//---------------------------------------- - -func stripPrefix(key []byte, prefix []byte) (stripped []byte) { - if len(key) < len(prefix) { - panic("should not happen") - } - if !bytes.Equal(key[:len(prefix)], prefix) { - panic("should not happne") - } - return key[len(prefix):] -} diff --git a/libs/db/prefix_db_test.go b/libs/db/prefix_db_test.go deleted file mode 100644 index e3e37c7d1..000000000 --- a/libs/db/prefix_db_test.go +++ /dev/null @@ -1,192 +0,0 @@ -package db - -import "testing" - -func mockDBWithStuff() DB { - db := NewMemDB() - // Under "key" prefix - db.Set(bz("key"), bz("value")) - db.Set(bz("key1"), bz("value1")) - db.Set(bz("key2"), bz("value2")) - db.Set(bz("key3"), bz("value3")) - db.Set(bz("something"), bz("else")) - db.Set(bz(""), bz("")) - db.Set(bz("k"), bz("val")) - db.Set(bz("ke"), bz("valu")) - db.Set(bz("kee"), bz("valuu")) - return db -} - -func TestPrefixDBSimple(t *testing.T) { - db := mockDBWithStuff() - pdb := NewPrefixDB(db, bz("key")) - - checkValue(t, pdb, bz("key"), nil) - checkValue(t, pdb, bz(""), bz("value")) - checkValue(t, pdb, bz("key1"), nil) - checkValue(t, pdb, bz("1"), bz("value1")) - checkValue(t, pdb, bz("key2"), nil) - checkValue(t, pdb, bz("2"), bz("value2")) - checkValue(t, pdb, bz("key3"), nil) - checkValue(t, pdb, bz("3"), bz("value3")) - checkValue(t, pdb, bz("something"), nil) - checkValue(t, pdb, bz("k"), nil) - checkValue(t, pdb, bz("ke"), nil) - checkValue(t, pdb, bz("kee"), nil) -} - -func TestPrefixDBIterator1(t *testing.T) { - db := mockDBWithStuff() - pdb := NewPrefixDB(db, bz("key")) - - itr := pdb.Iterator(nil, nil) - checkDomain(t, itr, nil, nil) - checkItem(t, itr, bz(""), bz("value")) - checkNext(t, itr, true) - checkItem(t, itr, bz("1"), bz("value1")) - checkNext(t, itr, true) - checkItem(t, itr, bz("2"), bz("value2")) - checkNext(t, itr, true) - checkItem(t, itr, bz("3"), bz("value3")) - checkNext(t, itr, false) - checkInvalid(t, itr) - itr.Close() -} - -func TestPrefixDBIterator2(t *testing.T) { - db := mockDBWithStuff() - pdb := NewPrefixDB(db, bz("key")) - - itr := pdb.Iterator(nil, bz("")) - checkDomain(t, itr, nil, bz("")) - checkInvalid(t, itr) - itr.Close() -} - -func TestPrefixDBIterator3(t *testing.T) { - db := mockDBWithStuff() - pdb := NewPrefixDB(db, bz("key")) - - itr := pdb.Iterator(bz(""), nil) - checkDomain(t, itr, bz(""), nil) - checkItem(t, itr, bz(""), bz("value")) - checkNext(t, itr, true) - checkItem(t, itr, bz("1"), bz("value1")) - checkNext(t, itr, true) - checkItem(t, itr, bz("2"), bz("value2")) - checkNext(t, itr, true) - checkItem(t, itr, bz("3"), bz("value3")) - checkNext(t, itr, false) - checkInvalid(t, itr) - itr.Close() -} - -func TestPrefixDBIterator4(t *testing.T) { - db := mockDBWithStuff() - pdb := NewPrefixDB(db, bz("key")) - - itr := pdb.Iterator(bz(""), bz("")) - checkDomain(t, itr, bz(""), bz("")) - checkInvalid(t, itr) - itr.Close() -} - -func TestPrefixDBReverseIterator1(t *testing.T) { - db := mockDBWithStuff() - pdb := NewPrefixDB(db, bz("key")) - - itr := pdb.ReverseIterator(nil, nil) - checkDomain(t, itr, nil, nil) - checkItem(t, itr, bz("3"), bz("value3")) - checkNext(t, itr, true) - checkItem(t, itr, bz("2"), bz("value2")) - checkNext(t, itr, true) - checkItem(t, itr, bz("1"), bz("value1")) - checkNext(t, itr, true) - checkItem(t, itr, bz(""), bz("value")) - checkNext(t, itr, false) - checkInvalid(t, itr) - itr.Close() -} - -func TestPrefixDBReverseIterator2(t *testing.T) { - db := mockDBWithStuff() - pdb := NewPrefixDB(db, bz("key")) - - itr := pdb.ReverseIterator(bz(""), nil) - checkDomain(t, itr, bz(""), nil) - checkItem(t, itr, bz("3"), bz("value3")) - checkNext(t, itr, true) - checkItem(t, itr, bz("2"), bz("value2")) - checkNext(t, itr, true) - checkItem(t, itr, bz("1"), bz("value1")) - checkNext(t, itr, true) - checkItem(t, itr, bz(""), bz("value")) - checkNext(t, itr, false) - checkInvalid(t, itr) - itr.Close() -} - -func TestPrefixDBReverseIterator3(t *testing.T) { - db := mockDBWithStuff() - pdb := NewPrefixDB(db, bz("key")) - - itr := pdb.ReverseIterator(nil, bz("")) - checkDomain(t, itr, nil, bz("")) - checkInvalid(t, itr) - itr.Close() -} - -func TestPrefixDBReverseIterator4(t *testing.T) { - db := mockDBWithStuff() - pdb := NewPrefixDB(db, bz("key")) - - itr := pdb.ReverseIterator(bz(""), bz("")) - checkDomain(t, itr, bz(""), bz("")) - checkInvalid(t, itr) - itr.Close() -} - -func TestPrefixDBReverseIterator5(t *testing.T) { - db := mockDBWithStuff() - pdb := NewPrefixDB(db, bz("key")) - - itr := pdb.ReverseIterator(bz("1"), nil) - checkDomain(t, itr, bz("1"), nil) - checkItem(t, itr, bz("3"), bz("value3")) - checkNext(t, itr, true) - checkItem(t, itr, bz("2"), bz("value2")) - checkNext(t, itr, true) - checkItem(t, itr, bz("1"), bz("value1")) - checkNext(t, itr, false) - checkInvalid(t, itr) - itr.Close() -} - -func TestPrefixDBReverseIterator6(t *testing.T) { - db := mockDBWithStuff() - pdb := NewPrefixDB(db, bz("key")) - - itr := pdb.ReverseIterator(bz("2"), nil) - checkDomain(t, itr, bz("2"), nil) - checkItem(t, itr, bz("3"), bz("value3")) - checkNext(t, itr, true) - checkItem(t, itr, bz("2"), bz("value2")) - checkNext(t, itr, false) - checkInvalid(t, itr) - itr.Close() -} - -func TestPrefixDBReverseIterator7(t *testing.T) { - db := mockDBWithStuff() - pdb := NewPrefixDB(db, bz("key")) - - itr := pdb.ReverseIterator(nil, bz("2")) - checkDomain(t, itr, nil, bz("2")) - checkItem(t, itr, bz("1"), bz("value1")) - checkNext(t, itr, true) - checkItem(t, itr, bz(""), bz("value")) - checkNext(t, itr, false) - checkInvalid(t, itr) - itr.Close() -} diff --git a/libs/db/remotedb/doc.go b/libs/db/remotedb/doc.go deleted file mode 100644 index 93d9c8a29..000000000 --- a/libs/db/remotedb/doc.go +++ /dev/null @@ -1,37 +0,0 @@ -/* -remotedb is a package for connecting to distributed Tendermint db.DB -instances. The purpose is to detach difficult deployments such as -CLevelDB that requires gcc or perhaps for databases that require -custom configurations such as extra disk space. It also eases -the burden and cost of deployment of dependencies for databases -to be used by Tendermint developers. Most importantly it is built -over the high performant gRPC transport. - -remotedb's RemoteDB implements db.DB so can be used normally -like other databases. One just has to explicitly connect to the -remote database with a client setup such as: - - client, err := remotedb.NewRemoteDB(addr, cert) - // Make sure to invoke InitRemote! - if err := client.InitRemote(&remotedb.Init{Name: "test-remote-db", Type: "leveldb"}); err != nil { - log.Fatalf("Failed to initialize the remote db") - } - - client.Set(key1, value) - gv1 := client.SetSync(k2, v2) - - client.Delete(k1) - gv2 := client.Get(k1) - - for itr := client.Iterator(k1, k9); itr.Valid(); itr.Next() { - ik, iv := itr.Key(), itr.Value() - ds, de := itr.Domain() - } - - stats := client.Stats() - - if !client.Has(dk1) { - client.SetSync(dk1, dv1) - } -*/ -package remotedb diff --git a/libs/db/remotedb/grpcdb/client.go b/libs/db/remotedb/grpcdb/client.go deleted file mode 100644 index b3c69ff23..000000000 --- a/libs/db/remotedb/grpcdb/client.go +++ /dev/null @@ -1,22 +0,0 @@ -package grpcdb - -import ( - "google.golang.org/grpc" - "google.golang.org/grpc/credentials" - - protodb "github.com/tendermint/tendermint/libs/db/remotedb/proto" -) - -// NewClient creates a gRPC client connected to the bound gRPC server at serverAddr. -// Use kind to set the level of security to either Secure or Insecure. -func NewClient(serverAddr, serverCert string) (protodb.DBClient, error) { - creds, err := credentials.NewClientTLSFromFile(serverCert, "") - if err != nil { - return nil, err - } - cc, err := grpc.Dial(serverAddr, grpc.WithTransportCredentials(creds)) - if err != nil { - return nil, err - } - return protodb.NewDBClient(cc), nil -} diff --git a/libs/db/remotedb/grpcdb/doc.go b/libs/db/remotedb/grpcdb/doc.go deleted file mode 100644 index 0d8e380ce..000000000 --- a/libs/db/remotedb/grpcdb/doc.go +++ /dev/null @@ -1,32 +0,0 @@ -/* -grpcdb is the distribution of Tendermint's db.DB instances using -the gRPC transport to decouple local db.DB usages from applications, -to using them over a network in a highly performant manner. - -grpcdb allows users to initialize a database's server like -they would locally and invoke the respective methods of db.DB. - -Most users shouldn't use this package, but should instead use -remotedb. Only the lower level users and database server deployers -should use it, for functionality such as: - - ln, err := net.Listen("tcp", "0.0.0.0:0") - srv := grpcdb.NewServer() - defer srv.Stop() - go func() { - if err := srv.Serve(ln); err != nil { - t.Fatalf("BindServer: %v", err) - } - }() - -or - addr := ":8998" - cert := "server.crt" - key := "server.key" - go func() { - if err := grpcdb.ListenAndServe(addr, cert, key); err != nil { - log.Fatalf("BindServer: %v", err) - } - }() -*/ -package grpcdb diff --git a/libs/db/remotedb/grpcdb/example_test.go b/libs/db/remotedb/grpcdb/example_test.go deleted file mode 100644 index eba0d6914..000000000 --- a/libs/db/remotedb/grpcdb/example_test.go +++ /dev/null @@ -1,52 +0,0 @@ -package grpcdb_test - -import ( - "bytes" - "context" - "log" - - grpcdb "github.com/tendermint/tendermint/libs/db/remotedb/grpcdb" - protodb "github.com/tendermint/tendermint/libs/db/remotedb/proto" -) - -func Example() { - addr := ":8998" - cert := "server.crt" - key := "server.key" - go func() { - if err := grpcdb.ListenAndServe(addr, cert, key); err != nil { - log.Fatalf("BindServer: %v", err) - } - }() - - client, err := grpcdb.NewClient(addr, cert) - if err != nil { - log.Fatalf("Failed to create grpcDB client: %v", err) - } - - ctx := context.Background() - // 1. Initialize the DB - in := &protodb.Init{ - Type: "leveldb", - Name: "grpc-uno-test", - Dir: ".", - } - if _, err := client.Init(ctx, in); err != nil { - log.Fatalf("Init error: %v", err) - } - - // 2. Now it can be used! - query1 := &protodb.Entity{Key: []byte("Project"), Value: []byte("Tmlibs-on-gRPC")} - if _, err := client.SetSync(ctx, query1); err != nil { - log.Fatalf("SetSync err: %v", err) - } - - query2 := &protodb.Entity{Key: []byte("Project")} - read, err := client.Get(ctx, query2) - if err != nil { - log.Fatalf("Get err: %v", err) - } - if g, w := read.Value, []byte("Tmlibs-on-gRPC"); !bytes.Equal(g, w) { - log.Fatalf("got= (%q ==> % X)\nwant=(%q ==> % X)", g, g, w, w) - } -} diff --git a/libs/db/remotedb/grpcdb/server.go b/libs/db/remotedb/grpcdb/server.go deleted file mode 100644 index a032292b3..000000000 --- a/libs/db/remotedb/grpcdb/server.go +++ /dev/null @@ -1,200 +0,0 @@ -package grpcdb - -import ( - "context" - "net" - "sync" - "time" - - "google.golang.org/grpc" - "google.golang.org/grpc/credentials" - - "github.com/tendermint/tendermint/libs/db" - protodb "github.com/tendermint/tendermint/libs/db/remotedb/proto" -) - -// ListenAndServe is a blocking function that sets up a gRPC based -// server at the address supplied, with the gRPC options passed in. -// Normally in usage, invoke it in a goroutine like you would for http.ListenAndServe. -func ListenAndServe(addr, cert, key string, opts ...grpc.ServerOption) error { - ln, err := net.Listen("tcp", addr) - if err != nil { - return err - } - srv, err := NewServer(cert, key, opts...) - if err != nil { - return err - } - return srv.Serve(ln) -} - -func NewServer(cert, key string, opts ...grpc.ServerOption) (*grpc.Server, error) { - creds, err := credentials.NewServerTLSFromFile(cert, key) - if err != nil { - return nil, err - } - opts = append(opts, grpc.Creds(creds)) - srv := grpc.NewServer(opts...) - protodb.RegisterDBServer(srv, new(server)) - return srv, nil -} - -type server struct { - mu sync.Mutex - db db.DB -} - -var _ protodb.DBServer = (*server)(nil) - -// Init initializes the server's database. Only one type of database -// can be initialized per server. -// -// Dir is the directory on the file system in which the DB will be stored(if backed by disk) (TODO: remove) -// -// Name is representative filesystem entry's basepath -// -// Type can be either one of: -// * cleveldb (if built with gcc enabled) -// * fsdb -// * memdB -// * leveldb -// See https://godoc.org/github.com/tendermint/tendermint/libs/db#DBBackendType -func (s *server) Init(ctx context.Context, in *protodb.Init) (*protodb.Entity, error) { - s.mu.Lock() - defer s.mu.Unlock() - - s.db = db.NewDB(in.Name, db.DBBackendType(in.Type), in.Dir) - return &protodb.Entity{CreatedAt: time.Now().Unix()}, nil -} - -func (s *server) Delete(ctx context.Context, in *protodb.Entity) (*protodb.Nothing, error) { - s.db.Delete(in.Key) - return nothing, nil -} - -var nothing = new(protodb.Nothing) - -func (s *server) DeleteSync(ctx context.Context, in *protodb.Entity) (*protodb.Nothing, error) { - s.db.DeleteSync(in.Key) - return nothing, nil -} - -func (s *server) Get(ctx context.Context, in *protodb.Entity) (*protodb.Entity, error) { - value := s.db.Get(in.Key) - return &protodb.Entity{Value: value}, nil -} - -func (s *server) GetStream(ds protodb.DB_GetStreamServer) error { - // Receive routine - responsesChan := make(chan *protodb.Entity) - go func() { - defer close(responsesChan) - ctx := context.Background() - for { - in, err := ds.Recv() - if err != nil { - responsesChan <- &protodb.Entity{Err: err.Error()} - return - } - out, err := s.Get(ctx, in) - if err != nil { - if out == nil { - out = new(protodb.Entity) - out.Key = in.Key - } - out.Err = err.Error() - responsesChan <- out - return - } - - // Otherwise continue on - responsesChan <- out - } - }() - - // Send routine, block until we return - for out := range responsesChan { - if err := ds.Send(out); err != nil { - return err - } - } - return nil -} - -func (s *server) Has(ctx context.Context, in *protodb.Entity) (*protodb.Entity, error) { - exists := s.db.Has(in.Key) - return &protodb.Entity{Exists: exists}, nil -} - -func (s *server) Set(ctx context.Context, in *protodb.Entity) (*protodb.Nothing, error) { - s.db.Set(in.Key, in.Value) - return nothing, nil -} - -func (s *server) SetSync(ctx context.Context, in *protodb.Entity) (*protodb.Nothing, error) { - s.db.SetSync(in.Key, in.Value) - return nothing, nil -} - -func (s *server) Iterator(query *protodb.Entity, dis protodb.DB_IteratorServer) error { - it := s.db.Iterator(query.Start, query.End) - defer it.Close() - return s.handleIterator(it, dis.Send) -} - -func (s *server) handleIterator(it db.Iterator, sendFunc func(*protodb.Iterator) error) error { - for it.Valid() { - start, end := it.Domain() - out := &protodb.Iterator{ - Domain: &protodb.Domain{Start: start, End: end}, - Valid: it.Valid(), - Key: it.Key(), - Value: it.Value(), - } - if err := sendFunc(out); err != nil { - return err - } - - // Finally move the iterator forward - it.Next() - } - return nil -} - -func (s *server) ReverseIterator(query *protodb.Entity, dis protodb.DB_ReverseIteratorServer) error { - it := s.db.ReverseIterator(query.Start, query.End) - defer it.Close() - return s.handleIterator(it, dis.Send) -} - -func (s *server) Stats(context.Context, *protodb.Nothing) (*protodb.Stats, error) { - stats := s.db.Stats() - return &protodb.Stats{Data: stats, TimeAt: time.Now().Unix()}, nil -} - -func (s *server) BatchWrite(c context.Context, b *protodb.Batch) (*protodb.Nothing, error) { - return s.batchWrite(c, b, false) -} - -func (s *server) BatchWriteSync(c context.Context, b *protodb.Batch) (*protodb.Nothing, error) { - return s.batchWrite(c, b, true) -} - -func (s *server) batchWrite(c context.Context, b *protodb.Batch, sync bool) (*protodb.Nothing, error) { - bat := s.db.NewBatch() - defer bat.Close() - for _, op := range b.Ops { - switch op.Type { - case protodb.Operation_SET: - bat.Set(op.Entity.Key, op.Entity.Value) - case protodb.Operation_DELETE: - bat.Delete(op.Entity.Key) - } - } - if sync { - bat.WriteSync() - } else { - bat.Write() - } - return nothing, nil -} diff --git a/libs/db/remotedb/proto/defs.pb.go b/libs/db/remotedb/proto/defs.pb.go deleted file mode 100644 index 4d9f0b272..000000000 --- a/libs/db/remotedb/proto/defs.pb.go +++ /dev/null @@ -1,914 +0,0 @@ -// Code generated by protoc-gen-go. DO NOT EDIT. -// source: defs.proto - -/* -Package protodb is a generated protocol buffer package. - -It is generated from these files: - defs.proto - -It has these top-level messages: - Batch - Operation - Entity - Nothing - Domain - Iterator - Stats - Init -*/ -package protodb - -import proto "github.com/golang/protobuf/proto" -import fmt "fmt" -import math "math" - -import ( - context "golang.org/x/net/context" - grpc "google.golang.org/grpc" -) - -// Reference imports to suppress errors if they are not otherwise used. -var _ = proto.Marshal -var _ = fmt.Errorf -var _ = math.Inf - -// This is a compile-time assertion to ensure that this generated file -// is compatible with the proto package it is being compiled against. -// A compilation error at this line likely means your copy of the -// proto package needs to be updated. -const _ = proto.ProtoPackageIsVersion2 // please upgrade the proto package - -type Operation_Type int32 - -const ( - Operation_SET Operation_Type = 0 - Operation_DELETE Operation_Type = 1 -) - -var Operation_Type_name = map[int32]string{ - 0: "SET", - 1: "DELETE", -} -var Operation_Type_value = map[string]int32{ - "SET": 0, - "DELETE": 1, -} - -func (x Operation_Type) String() string { - return proto.EnumName(Operation_Type_name, int32(x)) -} -func (Operation_Type) EnumDescriptor() ([]byte, []int) { return fileDescriptor0, []int{1, 0} } - -type Batch struct { - Ops []*Operation `protobuf:"bytes,1,rep,name=ops" json:"ops,omitempty"` -} - -func (m *Batch) Reset() { *m = Batch{} } -func (m *Batch) String() string { return proto.CompactTextString(m) } -func (*Batch) ProtoMessage() {} -func (*Batch) Descriptor() ([]byte, []int) { return fileDescriptor0, []int{0} } - -func (m *Batch) GetOps() []*Operation { - if m != nil { - return m.Ops - } - return nil -} - -type Operation struct { - Entity *Entity `protobuf:"bytes,1,opt,name=entity" json:"entity,omitempty"` - Type Operation_Type `protobuf:"varint,2,opt,name=type,enum=protodb.Operation_Type" json:"type,omitempty"` -} - -func (m *Operation) Reset() { *m = Operation{} } -func (m *Operation) String() string { return proto.CompactTextString(m) } -func (*Operation) ProtoMessage() {} -func (*Operation) Descriptor() ([]byte, []int) { return fileDescriptor0, []int{1} } - -func (m *Operation) GetEntity() *Entity { - if m != nil { - return m.Entity - } - return nil -} - -func (m *Operation) GetType() Operation_Type { - if m != nil { - return m.Type - } - return Operation_SET -} - -type Entity struct { - Id int32 `protobuf:"varint,1,opt,name=id" json:"id,omitempty"` - Key []byte `protobuf:"bytes,2,opt,name=key,proto3" json:"key,omitempty"` - Value []byte `protobuf:"bytes,3,opt,name=value,proto3" json:"value,omitempty"` - Exists bool `protobuf:"varint,4,opt,name=exists" json:"exists,omitempty"` - Start []byte `protobuf:"bytes,5,opt,name=start,proto3" json:"start,omitempty"` - End []byte `protobuf:"bytes,6,opt,name=end,proto3" json:"end,omitempty"` - Err string `protobuf:"bytes,7,opt,name=err" json:"err,omitempty"` - CreatedAt int64 `protobuf:"varint,8,opt,name=created_at,json=createdAt" json:"created_at,omitempty"` -} - -func (m *Entity) Reset() { *m = Entity{} } -func (m *Entity) String() string { return proto.CompactTextString(m) } -func (*Entity) ProtoMessage() {} -func (*Entity) Descriptor() ([]byte, []int) { return fileDescriptor0, []int{2} } - -func (m *Entity) GetId() int32 { - if m != nil { - return m.Id - } - return 0 -} - -func (m *Entity) GetKey() []byte { - if m != nil { - return m.Key - } - return nil -} - -func (m *Entity) GetValue() []byte { - if m != nil { - return m.Value - } - return nil -} - -func (m *Entity) GetExists() bool { - if m != nil { - return m.Exists - } - return false -} - -func (m *Entity) GetStart() []byte { - if m != nil { - return m.Start - } - return nil -} - -func (m *Entity) GetEnd() []byte { - if m != nil { - return m.End - } - return nil -} - -func (m *Entity) GetErr() string { - if m != nil { - return m.Err - } - return "" -} - -func (m *Entity) GetCreatedAt() int64 { - if m != nil { - return m.CreatedAt - } - return 0 -} - -type Nothing struct { -} - -func (m *Nothing) Reset() { *m = Nothing{} } -func (m *Nothing) String() string { return proto.CompactTextString(m) } -func (*Nothing) ProtoMessage() {} -func (*Nothing) Descriptor() ([]byte, []int) { return fileDescriptor0, []int{3} } - -type Domain struct { - Start []byte `protobuf:"bytes,1,opt,name=start,proto3" json:"start,omitempty"` - End []byte `protobuf:"bytes,2,opt,name=end,proto3" json:"end,omitempty"` -} - -func (m *Domain) Reset() { *m = Domain{} } -func (m *Domain) String() string { return proto.CompactTextString(m) } -func (*Domain) ProtoMessage() {} -func (*Domain) Descriptor() ([]byte, []int) { return fileDescriptor0, []int{4} } - -func (m *Domain) GetStart() []byte { - if m != nil { - return m.Start - } - return nil -} - -func (m *Domain) GetEnd() []byte { - if m != nil { - return m.End - } - return nil -} - -type Iterator struct { - Domain *Domain `protobuf:"bytes,1,opt,name=domain" json:"domain,omitempty"` - Valid bool `protobuf:"varint,2,opt,name=valid" json:"valid,omitempty"` - Key []byte `protobuf:"bytes,3,opt,name=key,proto3" json:"key,omitempty"` - Value []byte `protobuf:"bytes,4,opt,name=value,proto3" json:"value,omitempty"` -} - -func (m *Iterator) Reset() { *m = Iterator{} } -func (m *Iterator) String() string { return proto.CompactTextString(m) } -func (*Iterator) ProtoMessage() {} -func (*Iterator) Descriptor() ([]byte, []int) { return fileDescriptor0, []int{5} } - -func (m *Iterator) GetDomain() *Domain { - if m != nil { - return m.Domain - } - return nil -} - -func (m *Iterator) GetValid() bool { - if m != nil { - return m.Valid - } - return false -} - -func (m *Iterator) GetKey() []byte { - if m != nil { - return m.Key - } - return nil -} - -func (m *Iterator) GetValue() []byte { - if m != nil { - return m.Value - } - return nil -} - -type Stats struct { - Data map[string]string `protobuf:"bytes,1,rep,name=data" json:"data,omitempty" protobuf_key:"bytes,1,opt,name=key" protobuf_val:"bytes,2,opt,name=value"` - TimeAt int64 `protobuf:"varint,2,opt,name=time_at,json=timeAt" json:"time_at,omitempty"` -} - -func (m *Stats) Reset() { *m = Stats{} } -func (m *Stats) String() string { return proto.CompactTextString(m) } -func (*Stats) ProtoMessage() {} -func (*Stats) Descriptor() ([]byte, []int) { return fileDescriptor0, []int{6} } - -func (m *Stats) GetData() map[string]string { - if m != nil { - return m.Data - } - return nil -} - -func (m *Stats) GetTimeAt() int64 { - if m != nil { - return m.TimeAt - } - return 0 -} - -type Init struct { - Type string `protobuf:"bytes,1,opt,name=Type" json:"Type,omitempty"` - Name string `protobuf:"bytes,2,opt,name=Name" json:"Name,omitempty"` - Dir string `protobuf:"bytes,3,opt,name=Dir" json:"Dir,omitempty"` -} - -func (m *Init) Reset() { *m = Init{} } -func (m *Init) String() string { return proto.CompactTextString(m) } -func (*Init) ProtoMessage() {} -func (*Init) Descriptor() ([]byte, []int) { return fileDescriptor0, []int{7} } - -func (m *Init) GetType() string { - if m != nil { - return m.Type - } - return "" -} - -func (m *Init) GetName() string { - if m != nil { - return m.Name - } - return "" -} - -func (m *Init) GetDir() string { - if m != nil { - return m.Dir - } - return "" -} - -func init() { - proto.RegisterType((*Batch)(nil), "protodb.Batch") - proto.RegisterType((*Operation)(nil), "protodb.Operation") - proto.RegisterType((*Entity)(nil), "protodb.Entity") - proto.RegisterType((*Nothing)(nil), "protodb.Nothing") - proto.RegisterType((*Domain)(nil), "protodb.Domain") - proto.RegisterType((*Iterator)(nil), "protodb.Iterator") - proto.RegisterType((*Stats)(nil), "protodb.Stats") - proto.RegisterType((*Init)(nil), "protodb.Init") - proto.RegisterEnum("protodb.Operation_Type", Operation_Type_name, Operation_Type_value) -} - -// Reference imports to suppress errors if they are not otherwise used. -var _ context.Context -var _ grpc.ClientConn - -// This is a compile-time assertion to ensure that this generated file -// is compatible with the grpc package it is being compiled against. -const _ = grpc.SupportPackageIsVersion4 - -// Client API for DB service - -type DBClient interface { - Init(ctx context.Context, in *Init, opts ...grpc.CallOption) (*Entity, error) - Get(ctx context.Context, in *Entity, opts ...grpc.CallOption) (*Entity, error) - GetStream(ctx context.Context, opts ...grpc.CallOption) (DB_GetStreamClient, error) - Has(ctx context.Context, in *Entity, opts ...grpc.CallOption) (*Entity, error) - Set(ctx context.Context, in *Entity, opts ...grpc.CallOption) (*Nothing, error) - SetSync(ctx context.Context, in *Entity, opts ...grpc.CallOption) (*Nothing, error) - Delete(ctx context.Context, in *Entity, opts ...grpc.CallOption) (*Nothing, error) - DeleteSync(ctx context.Context, in *Entity, opts ...grpc.CallOption) (*Nothing, error) - Iterator(ctx context.Context, in *Entity, opts ...grpc.CallOption) (DB_IteratorClient, error) - ReverseIterator(ctx context.Context, in *Entity, opts ...grpc.CallOption) (DB_ReverseIteratorClient, error) - // rpc print(Nothing) returns (Entity) {} - Stats(ctx context.Context, in *Nothing, opts ...grpc.CallOption) (*Stats, error) - BatchWrite(ctx context.Context, in *Batch, opts ...grpc.CallOption) (*Nothing, error) - BatchWriteSync(ctx context.Context, in *Batch, opts ...grpc.CallOption) (*Nothing, error) -} - -type dBClient struct { - cc *grpc.ClientConn -} - -func NewDBClient(cc *grpc.ClientConn) DBClient { - return &dBClient{cc} -} - -func (c *dBClient) Init(ctx context.Context, in *Init, opts ...grpc.CallOption) (*Entity, error) { - out := new(Entity) - err := grpc.Invoke(ctx, "/protodb.DB/init", in, out, c.cc, opts...) - if err != nil { - return nil, err - } - return out, nil -} - -func (c *dBClient) Get(ctx context.Context, in *Entity, opts ...grpc.CallOption) (*Entity, error) { - out := new(Entity) - err := grpc.Invoke(ctx, "/protodb.DB/get", in, out, c.cc, opts...) - if err != nil { - return nil, err - } - return out, nil -} - -func (c *dBClient) GetStream(ctx context.Context, opts ...grpc.CallOption) (DB_GetStreamClient, error) { - stream, err := grpc.NewClientStream(ctx, &_DB_serviceDesc.Streams[0], c.cc, "/protodb.DB/getStream", opts...) - if err != nil { - return nil, err - } - x := &dBGetStreamClient{stream} - return x, nil -} - -type DB_GetStreamClient interface { - Send(*Entity) error - Recv() (*Entity, error) - grpc.ClientStream -} - -type dBGetStreamClient struct { - grpc.ClientStream -} - -func (x *dBGetStreamClient) Send(m *Entity) error { - return x.ClientStream.SendMsg(m) -} - -func (x *dBGetStreamClient) Recv() (*Entity, error) { - m := new(Entity) - if err := x.ClientStream.RecvMsg(m); err != nil { - return nil, err - } - return m, nil -} - -func (c *dBClient) Has(ctx context.Context, in *Entity, opts ...grpc.CallOption) (*Entity, error) { - out := new(Entity) - err := grpc.Invoke(ctx, "/protodb.DB/has", in, out, c.cc, opts...) - if err != nil { - return nil, err - } - return out, nil -} - -func (c *dBClient) Set(ctx context.Context, in *Entity, opts ...grpc.CallOption) (*Nothing, error) { - out := new(Nothing) - err := grpc.Invoke(ctx, "/protodb.DB/set", in, out, c.cc, opts...) - if err != nil { - return nil, err - } - return out, nil -} - -func (c *dBClient) SetSync(ctx context.Context, in *Entity, opts ...grpc.CallOption) (*Nothing, error) { - out := new(Nothing) - err := grpc.Invoke(ctx, "/protodb.DB/setSync", in, out, c.cc, opts...) - if err != nil { - return nil, err - } - return out, nil -} - -func (c *dBClient) Delete(ctx context.Context, in *Entity, opts ...grpc.CallOption) (*Nothing, error) { - out := new(Nothing) - err := grpc.Invoke(ctx, "/protodb.DB/delete", in, out, c.cc, opts...) - if err != nil { - return nil, err - } - return out, nil -} - -func (c *dBClient) DeleteSync(ctx context.Context, in *Entity, opts ...grpc.CallOption) (*Nothing, error) { - out := new(Nothing) - err := grpc.Invoke(ctx, "/protodb.DB/deleteSync", in, out, c.cc, opts...) - if err != nil { - return nil, err - } - return out, nil -} - -func (c *dBClient) Iterator(ctx context.Context, in *Entity, opts ...grpc.CallOption) (DB_IteratorClient, error) { - stream, err := grpc.NewClientStream(ctx, &_DB_serviceDesc.Streams[1], c.cc, "/protodb.DB/iterator", opts...) - if err != nil { - return nil, err - } - x := &dBIteratorClient{stream} - if err := x.ClientStream.SendMsg(in); err != nil { - return nil, err - } - if err := x.ClientStream.CloseSend(); err != nil { - return nil, err - } - return x, nil -} - -type DB_IteratorClient interface { - Recv() (*Iterator, error) - grpc.ClientStream -} - -type dBIteratorClient struct { - grpc.ClientStream -} - -func (x *dBIteratorClient) Recv() (*Iterator, error) { - m := new(Iterator) - if err := x.ClientStream.RecvMsg(m); err != nil { - return nil, err - } - return m, nil -} - -func (c *dBClient) ReverseIterator(ctx context.Context, in *Entity, opts ...grpc.CallOption) (DB_ReverseIteratorClient, error) { - stream, err := grpc.NewClientStream(ctx, &_DB_serviceDesc.Streams[2], c.cc, "/protodb.DB/reverseIterator", opts...) - if err != nil { - return nil, err - } - x := &dBReverseIteratorClient{stream} - if err := x.ClientStream.SendMsg(in); err != nil { - return nil, err - } - if err := x.ClientStream.CloseSend(); err != nil { - return nil, err - } - return x, nil -} - -type DB_ReverseIteratorClient interface { - Recv() (*Iterator, error) - grpc.ClientStream -} - -type dBReverseIteratorClient struct { - grpc.ClientStream -} - -func (x *dBReverseIteratorClient) Recv() (*Iterator, error) { - m := new(Iterator) - if err := x.ClientStream.RecvMsg(m); err != nil { - return nil, err - } - return m, nil -} - -func (c *dBClient) Stats(ctx context.Context, in *Nothing, opts ...grpc.CallOption) (*Stats, error) { - out := new(Stats) - err := grpc.Invoke(ctx, "/protodb.DB/stats", in, out, c.cc, opts...) - if err != nil { - return nil, err - } - return out, nil -} - -func (c *dBClient) BatchWrite(ctx context.Context, in *Batch, opts ...grpc.CallOption) (*Nothing, error) { - out := new(Nothing) - err := grpc.Invoke(ctx, "/protodb.DB/batchWrite", in, out, c.cc, opts...) - if err != nil { - return nil, err - } - return out, nil -} - -func (c *dBClient) BatchWriteSync(ctx context.Context, in *Batch, opts ...grpc.CallOption) (*Nothing, error) { - out := new(Nothing) - err := grpc.Invoke(ctx, "/protodb.DB/batchWriteSync", in, out, c.cc, opts...) - if err != nil { - return nil, err - } - return out, nil -} - -// Server API for DB service - -type DBServer interface { - Init(context.Context, *Init) (*Entity, error) - Get(context.Context, *Entity) (*Entity, error) - GetStream(DB_GetStreamServer) error - Has(context.Context, *Entity) (*Entity, error) - Set(context.Context, *Entity) (*Nothing, error) - SetSync(context.Context, *Entity) (*Nothing, error) - Delete(context.Context, *Entity) (*Nothing, error) - DeleteSync(context.Context, *Entity) (*Nothing, error) - Iterator(*Entity, DB_IteratorServer) error - ReverseIterator(*Entity, DB_ReverseIteratorServer) error - // rpc print(Nothing) returns (Entity) {} - Stats(context.Context, *Nothing) (*Stats, error) - BatchWrite(context.Context, *Batch) (*Nothing, error) - BatchWriteSync(context.Context, *Batch) (*Nothing, error) -} - -func RegisterDBServer(s *grpc.Server, srv DBServer) { - s.RegisterService(&_DB_serviceDesc, srv) -} - -func _DB_Init_Handler(srv interface{}, ctx context.Context, dec func(interface{}) error, interceptor grpc.UnaryServerInterceptor) (interface{}, error) { - in := new(Init) - if err := dec(in); err != nil { - return nil, err - } - if interceptor == nil { - return srv.(DBServer).Init(ctx, in) - } - info := &grpc.UnaryServerInfo{ - Server: srv, - FullMethod: "/protodb.DB/Init", - } - handler := func(ctx context.Context, req interface{}) (interface{}, error) { - return srv.(DBServer).Init(ctx, req.(*Init)) - } - return interceptor(ctx, in, info, handler) -} - -func _DB_Get_Handler(srv interface{}, ctx context.Context, dec func(interface{}) error, interceptor grpc.UnaryServerInterceptor) (interface{}, error) { - in := new(Entity) - if err := dec(in); err != nil { - return nil, err - } - if interceptor == nil { - return srv.(DBServer).Get(ctx, in) - } - info := &grpc.UnaryServerInfo{ - Server: srv, - FullMethod: "/protodb.DB/Get", - } - handler := func(ctx context.Context, req interface{}) (interface{}, error) { - return srv.(DBServer).Get(ctx, req.(*Entity)) - } - return interceptor(ctx, in, info, handler) -} - -func _DB_GetStream_Handler(srv interface{}, stream grpc.ServerStream) error { - return srv.(DBServer).GetStream(&dBGetStreamServer{stream}) -} - -type DB_GetStreamServer interface { - Send(*Entity) error - Recv() (*Entity, error) - grpc.ServerStream -} - -type dBGetStreamServer struct { - grpc.ServerStream -} - -func (x *dBGetStreamServer) Send(m *Entity) error { - return x.ServerStream.SendMsg(m) -} - -func (x *dBGetStreamServer) Recv() (*Entity, error) { - m := new(Entity) - if err := x.ServerStream.RecvMsg(m); err != nil { - return nil, err - } - return m, nil -} - -func _DB_Has_Handler(srv interface{}, ctx context.Context, dec func(interface{}) error, interceptor grpc.UnaryServerInterceptor) (interface{}, error) { - in := new(Entity) - if err := dec(in); err != nil { - return nil, err - } - if interceptor == nil { - return srv.(DBServer).Has(ctx, in) - } - info := &grpc.UnaryServerInfo{ - Server: srv, - FullMethod: "/protodb.DB/Has", - } - handler := func(ctx context.Context, req interface{}) (interface{}, error) { - return srv.(DBServer).Has(ctx, req.(*Entity)) - } - return interceptor(ctx, in, info, handler) -} - -func _DB_Set_Handler(srv interface{}, ctx context.Context, dec func(interface{}) error, interceptor grpc.UnaryServerInterceptor) (interface{}, error) { - in := new(Entity) - if err := dec(in); err != nil { - return nil, err - } - if interceptor == nil { - return srv.(DBServer).Set(ctx, in) - } - info := &grpc.UnaryServerInfo{ - Server: srv, - FullMethod: "/protodb.DB/Set", - } - handler := func(ctx context.Context, req interface{}) (interface{}, error) { - return srv.(DBServer).Set(ctx, req.(*Entity)) - } - return interceptor(ctx, in, info, handler) -} - -func _DB_SetSync_Handler(srv interface{}, ctx context.Context, dec func(interface{}) error, interceptor grpc.UnaryServerInterceptor) (interface{}, error) { - in := new(Entity) - if err := dec(in); err != nil { - return nil, err - } - if interceptor == nil { - return srv.(DBServer).SetSync(ctx, in) - } - info := &grpc.UnaryServerInfo{ - Server: srv, - FullMethod: "/protodb.DB/SetSync", - } - handler := func(ctx context.Context, req interface{}) (interface{}, error) { - return srv.(DBServer).SetSync(ctx, req.(*Entity)) - } - return interceptor(ctx, in, info, handler) -} - -func _DB_Delete_Handler(srv interface{}, ctx context.Context, dec func(interface{}) error, interceptor grpc.UnaryServerInterceptor) (interface{}, error) { - in := new(Entity) - if err := dec(in); err != nil { - return nil, err - } - if interceptor == nil { - return srv.(DBServer).Delete(ctx, in) - } - info := &grpc.UnaryServerInfo{ - Server: srv, - FullMethod: "/protodb.DB/Delete", - } - handler := func(ctx context.Context, req interface{}) (interface{}, error) { - return srv.(DBServer).Delete(ctx, req.(*Entity)) - } - return interceptor(ctx, in, info, handler) -} - -func _DB_DeleteSync_Handler(srv interface{}, ctx context.Context, dec func(interface{}) error, interceptor grpc.UnaryServerInterceptor) (interface{}, error) { - in := new(Entity) - if err := dec(in); err != nil { - return nil, err - } - if interceptor == nil { - return srv.(DBServer).DeleteSync(ctx, in) - } - info := &grpc.UnaryServerInfo{ - Server: srv, - FullMethod: "/protodb.DB/DeleteSync", - } - handler := func(ctx context.Context, req interface{}) (interface{}, error) { - return srv.(DBServer).DeleteSync(ctx, req.(*Entity)) - } - return interceptor(ctx, in, info, handler) -} - -func _DB_Iterator_Handler(srv interface{}, stream grpc.ServerStream) error { - m := new(Entity) - if err := stream.RecvMsg(m); err != nil { - return err - } - return srv.(DBServer).Iterator(m, &dBIteratorServer{stream}) -} - -type DB_IteratorServer interface { - Send(*Iterator) error - grpc.ServerStream -} - -type dBIteratorServer struct { - grpc.ServerStream -} - -func (x *dBIteratorServer) Send(m *Iterator) error { - return x.ServerStream.SendMsg(m) -} - -func _DB_ReverseIterator_Handler(srv interface{}, stream grpc.ServerStream) error { - m := new(Entity) - if err := stream.RecvMsg(m); err != nil { - return err - } - return srv.(DBServer).ReverseIterator(m, &dBReverseIteratorServer{stream}) -} - -type DB_ReverseIteratorServer interface { - Send(*Iterator) error - grpc.ServerStream -} - -type dBReverseIteratorServer struct { - grpc.ServerStream -} - -func (x *dBReverseIteratorServer) Send(m *Iterator) error { - return x.ServerStream.SendMsg(m) -} - -func _DB_Stats_Handler(srv interface{}, ctx context.Context, dec func(interface{}) error, interceptor grpc.UnaryServerInterceptor) (interface{}, error) { - in := new(Nothing) - if err := dec(in); err != nil { - return nil, err - } - if interceptor == nil { - return srv.(DBServer).Stats(ctx, in) - } - info := &grpc.UnaryServerInfo{ - Server: srv, - FullMethod: "/protodb.DB/Stats", - } - handler := func(ctx context.Context, req interface{}) (interface{}, error) { - return srv.(DBServer).Stats(ctx, req.(*Nothing)) - } - return interceptor(ctx, in, info, handler) -} - -func _DB_BatchWrite_Handler(srv interface{}, ctx context.Context, dec func(interface{}) error, interceptor grpc.UnaryServerInterceptor) (interface{}, error) { - in := new(Batch) - if err := dec(in); err != nil { - return nil, err - } - if interceptor == nil { - return srv.(DBServer).BatchWrite(ctx, in) - } - info := &grpc.UnaryServerInfo{ - Server: srv, - FullMethod: "/protodb.DB/BatchWrite", - } - handler := func(ctx context.Context, req interface{}) (interface{}, error) { - return srv.(DBServer).BatchWrite(ctx, req.(*Batch)) - } - return interceptor(ctx, in, info, handler) -} - -func _DB_BatchWriteSync_Handler(srv interface{}, ctx context.Context, dec func(interface{}) error, interceptor grpc.UnaryServerInterceptor) (interface{}, error) { - in := new(Batch) - if err := dec(in); err != nil { - return nil, err - } - if interceptor == nil { - return srv.(DBServer).BatchWriteSync(ctx, in) - } - info := &grpc.UnaryServerInfo{ - Server: srv, - FullMethod: "/protodb.DB/BatchWriteSync", - } - handler := func(ctx context.Context, req interface{}) (interface{}, error) { - return srv.(DBServer).BatchWriteSync(ctx, req.(*Batch)) - } - return interceptor(ctx, in, info, handler) -} - -var _DB_serviceDesc = grpc.ServiceDesc{ - ServiceName: "protodb.DB", - HandlerType: (*DBServer)(nil), - Methods: []grpc.MethodDesc{ - { - MethodName: "init", - Handler: _DB_Init_Handler, - }, - { - MethodName: "get", - Handler: _DB_Get_Handler, - }, - { - MethodName: "has", - Handler: _DB_Has_Handler, - }, - { - MethodName: "set", - Handler: _DB_Set_Handler, - }, - { - MethodName: "setSync", - Handler: _DB_SetSync_Handler, - }, - { - MethodName: "delete", - Handler: _DB_Delete_Handler, - }, - { - MethodName: "deleteSync", - Handler: _DB_DeleteSync_Handler, - }, - { - MethodName: "stats", - Handler: _DB_Stats_Handler, - }, - { - MethodName: "batchWrite", - Handler: _DB_BatchWrite_Handler, - }, - { - MethodName: "batchWriteSync", - Handler: _DB_BatchWriteSync_Handler, - }, - }, - Streams: []grpc.StreamDesc{ - { - StreamName: "getStream", - Handler: _DB_GetStream_Handler, - ServerStreams: true, - ClientStreams: true, - }, - { - StreamName: "iterator", - Handler: _DB_Iterator_Handler, - ServerStreams: true, - }, - { - StreamName: "reverseIterator", - Handler: _DB_ReverseIterator_Handler, - ServerStreams: true, - }, - }, - Metadata: "defs.proto", -} - -func init() { proto.RegisterFile("defs.proto", fileDescriptor0) } - -var fileDescriptor0 = []byte{ - // 606 bytes of a gzipped FileDescriptorProto - 0x1f, 0x8b, 0x08, 0x00, 0x00, 0x00, 0x00, 0x00, 0x02, 0xff, 0x94, 0x54, 0x4f, 0x6f, 0xd3, 0x4e, - 0x10, 0xcd, 0xda, 0x8e, 0x13, 0x4f, 0x7f, 0xbf, 0x34, 0x8c, 0x10, 0xb5, 0x8a, 0x90, 0x22, 0x0b, - 0x09, 0x43, 0x69, 0x14, 0x52, 0x24, 0xfe, 0x9c, 0x68, 0x95, 0x1c, 0x2a, 0xa1, 0x22, 0x39, 0x95, - 0x38, 0xa2, 0x6d, 0x3d, 0x34, 0x2b, 0x1a, 0x3b, 0xac, 0x87, 0x8a, 0x5c, 0xb8, 0xf2, 0x79, 0xf8, - 0x7c, 0x5c, 0xd0, 0xae, 0x1d, 0x87, 0x36, 0x39, 0x84, 0x53, 0x76, 0x66, 0xde, 0x7b, 0xb3, 0xf3, - 0x32, 0x5e, 0x80, 0x94, 0x3e, 0x17, 0xfd, 0xb9, 0xce, 0x39, 0xc7, 0x96, 0xfd, 0x49, 0x2f, 0xa2, - 0x43, 0x68, 0x9e, 0x48, 0xbe, 0x9c, 0xe2, 0x63, 0x70, 0xf3, 0x79, 0x11, 0x8a, 0x9e, 0x1b, 0xef, - 0x0c, 0xb1, 0x5f, 0xd5, 0xfb, 0x1f, 0xe6, 0xa4, 0x25, 0xab, 0x3c, 0x4b, 0x4c, 0x39, 0xfa, 0x01, - 0x41, 0x9d, 0xc1, 0x27, 0xe0, 0x53, 0xc6, 0x8a, 0x17, 0xa1, 0xe8, 0x89, 0x78, 0x67, 0xb8, 0x5b, - 0xb3, 0xc6, 0x36, 0x9d, 0x54, 0x65, 0x3c, 0x00, 0x8f, 0x17, 0x73, 0x0a, 0x9d, 0x9e, 0x88, 0x3b, - 0xc3, 0xbd, 0x75, 0xf1, 0xfe, 0xf9, 0x62, 0x4e, 0x89, 0x05, 0x45, 0x0f, 0xc1, 0x33, 0x11, 0xb6, - 0xc0, 0x9d, 0x8c, 0xcf, 0xbb, 0x0d, 0x04, 0xf0, 0x47, 0xe3, 0xf7, 0xe3, 0xf3, 0x71, 0x57, 0x44, - 0xbf, 0x04, 0xf8, 0xa5, 0x38, 0x76, 0xc0, 0x51, 0xa9, 0xed, 0xdc, 0x4c, 0x1c, 0x95, 0x62, 0x17, - 0xdc, 0x2f, 0xb4, 0xb0, 0x3d, 0xfe, 0x4b, 0xcc, 0x11, 0xef, 0x43, 0xf3, 0x46, 0x5e, 0x7f, 0xa3, - 0xd0, 0xb5, 0xb9, 0x32, 0xc0, 0x07, 0xe0, 0xd3, 0x77, 0x55, 0x70, 0x11, 0x7a, 0x3d, 0x11, 0xb7, - 0x93, 0x2a, 0x32, 0xe8, 0x82, 0xa5, 0xe6, 0xb0, 0x59, 0xa2, 0x6d, 0x60, 0x54, 0x29, 0x4b, 0x43, - 0xbf, 0x54, 0xa5, 0xcc, 0xf6, 0x21, 0xad, 0xc3, 0x56, 0x4f, 0xc4, 0x41, 0x62, 0x8e, 0xf8, 0x08, - 0xe0, 0x52, 0x93, 0x64, 0x4a, 0x3f, 0x49, 0x0e, 0xdb, 0x3d, 0x11, 0xbb, 0x49, 0x50, 0x65, 0x8e, - 0x39, 0x0a, 0xa0, 0x75, 0x96, 0xf3, 0x54, 0x65, 0x57, 0xd1, 0x00, 0xfc, 0x51, 0x3e, 0x93, 0x2a, - 0x5b, 0x75, 0x13, 0x1b, 0xba, 0x39, 0x75, 0xb7, 0xe8, 0x2b, 0xb4, 0x4f, 0xd9, 0xb8, 0x94, 0x6b, - 0xe3, 0x77, 0x6a, 0xd9, 0x6b, 0x7e, 0x97, 0xa2, 0x49, 0x55, 0xae, 0x06, 0x57, 0xa5, 0x50, 0x3b, - 0x29, 0x83, 0xa5, 0x41, 0xee, 0x06, 0x83, 0xbc, 0xbf, 0x0c, 0x8a, 0x7e, 0x0a, 0x68, 0x4e, 0x58, - 0x72, 0x81, 0xcf, 0xc1, 0x4b, 0x25, 0xcb, 0x6a, 0x29, 0xc2, 0xba, 0x9d, 0xad, 0xf6, 0x47, 0x92, - 0xe5, 0x38, 0x63, 0xbd, 0x48, 0x2c, 0x0a, 0xf7, 0xa0, 0xc5, 0x6a, 0x46, 0xc6, 0x03, 0xc7, 0x7a, - 0xe0, 0x9b, 0xf0, 0x98, 0xf7, 0x5f, 0x41, 0x50, 0x63, 0x97, 0xb7, 0x10, 0xa5, 0x7d, 0xb7, 0x6e, - 0xe1, 0xd8, 0x5c, 0x19, 0xbc, 0x75, 0x5e, 0x8b, 0xe8, 0x1d, 0x78, 0xa7, 0x99, 0x62, 0xc4, 0x72, - 0x25, 0x2a, 0x52, 0xb9, 0x1e, 0x08, 0xde, 0x99, 0x9c, 0x2d, 0x49, 0xf6, 0x6c, 0xb4, 0x47, 0x4a, - 0xdb, 0x09, 0x83, 0xc4, 0x1c, 0x87, 0xbf, 0x3d, 0x70, 0x46, 0x27, 0x18, 0x83, 0xa7, 0x8c, 0xd0, - 0xff, 0xf5, 0x08, 0x46, 0x77, 0xff, 0xee, 0xc2, 0x46, 0x0d, 0x7c, 0x0a, 0xee, 0x15, 0x31, 0xde, - 0xad, 0x6c, 0x82, 0x1e, 0x41, 0x70, 0x45, 0x3c, 0x61, 0x4d, 0x72, 0xb6, 0x0d, 0x21, 0x16, 0x03, - 0x61, 0xf4, 0xa7, 0xb2, 0xd8, 0x4a, 0xff, 0x19, 0xb8, 0xc5, 0xa6, 0xab, 0x74, 0xeb, 0xc4, 0x72, - 0xad, 0x1a, 0xd8, 0x87, 0x56, 0x41, 0x3c, 0x59, 0x64, 0x97, 0xdb, 0xe1, 0x0f, 0xc1, 0x4f, 0xe9, - 0x9a, 0x98, 0xb6, 0x83, 0xbf, 0x30, 0x8f, 0x87, 0x81, 0x6f, 0xdf, 0x61, 0x08, 0x6d, 0xb5, 0x5c, - 0xdc, 0x35, 0xc2, 0xbd, 0xd5, 0xff, 0x50, 0x61, 0xa2, 0xc6, 0x40, 0xe0, 0x1b, 0xd8, 0xd5, 0x74, - 0x43, 0xba, 0xa0, 0xd3, 0x7f, 0xa5, 0x1e, 0xd8, 0xef, 0x89, 0x0b, 0x5c, 0xbb, 0xcb, 0x7e, 0xe7, - 0xf6, 0xde, 0x46, 0x0d, 0x1c, 0x00, 0x5c, 0x98, 0x47, 0xef, 0xa3, 0x56, 0x4c, 0xb8, 0xaa, 0xdb, - 0x97, 0x70, 0xe3, 0x34, 0x2f, 0xa1, 0xb3, 0x62, 0x58, 0x13, 0xb6, 0x60, 0x5d, 0xf8, 0x36, 0x75, - 0xf4, 0x27, 0x00, 0x00, 0xff, 0xff, 0x95, 0xf4, 0xe3, 0x82, 0x7a, 0x05, 0x00, 0x00, -} diff --git a/libs/db/remotedb/proto/defs.proto b/libs/db/remotedb/proto/defs.proto deleted file mode 100644 index 70471f234..000000000 --- a/libs/db/remotedb/proto/defs.proto +++ /dev/null @@ -1,71 +0,0 @@ -syntax = "proto3"; - -package protodb; - -message Batch { - repeated Operation ops = 1; -} - -message Operation { - Entity entity = 1; - enum Type { - SET = 0; - DELETE = 1; - } - Type type = 2; -} - -message Entity { - int32 id = 1; - bytes key = 2; - bytes value = 3; - bool exists = 4; - bytes start = 5; - bytes end = 6; - string err = 7; - int64 created_at = 8; -} - -message Nothing { -} - -message Domain { - bytes start = 1; - bytes end = 2; -} - -message Iterator { - Domain domain = 1; - bool valid = 2; - bytes key = 3; - bytes value = 4; -} - -message Stats { - map data = 1; - int64 time_at = 2; -} - -message Init { - string Type = 1; - string Name = 2; - string Dir = 3; -} - -service DB { - rpc init(Init) returns (Entity) {} - rpc get(Entity) returns (Entity) {} - rpc getStream(stream Entity) returns (stream Entity) {} - - rpc has(Entity) returns (Entity) {} - rpc set(Entity) returns (Nothing) {} - rpc setSync(Entity) returns (Nothing) {} - rpc delete(Entity) returns (Nothing) {} - rpc deleteSync(Entity) returns (Nothing) {} - rpc iterator(Entity) returns (stream Iterator) {} - rpc reverseIterator(Entity) returns (stream Iterator) {} - // rpc print(Nothing) returns (Entity) {} - rpc stats(Nothing) returns (Stats) {} - rpc batchWrite(Batch) returns (Nothing) {} - rpc batchWriteSync(Batch) returns (Nothing) {} -} diff --git a/libs/db/remotedb/remotedb.go b/libs/db/remotedb/remotedb.go deleted file mode 100644 index c70d54b9e..000000000 --- a/libs/db/remotedb/remotedb.go +++ /dev/null @@ -1,266 +0,0 @@ -package remotedb - -import ( - "context" - "fmt" - - "github.com/tendermint/tendermint/libs/db" - "github.com/tendermint/tendermint/libs/db/remotedb/grpcdb" - protodb "github.com/tendermint/tendermint/libs/db/remotedb/proto" -) - -type RemoteDB struct { - ctx context.Context - dc protodb.DBClient -} - -func NewRemoteDB(serverAddr string, serverKey string) (*RemoteDB, error) { - return newRemoteDB(grpcdb.NewClient(serverAddr, serverKey)) -} - -func newRemoteDB(gdc protodb.DBClient, err error) (*RemoteDB, error) { - if err != nil { - return nil, err - } - return &RemoteDB{dc: gdc, ctx: context.Background()}, nil -} - -type Init struct { - Dir string - Name string - Type string -} - -func (rd *RemoteDB) InitRemote(in *Init) error { - _, err := rd.dc.Init(rd.ctx, &protodb.Init{Dir: in.Dir, Type: in.Type, Name: in.Name}) - return err -} - -var _ db.DB = (*RemoteDB)(nil) - -// Close is a noop currently -func (rd *RemoteDB) Close() { -} - -func (rd *RemoteDB) Delete(key []byte) { - if _, err := rd.dc.Delete(rd.ctx, &protodb.Entity{Key: key}); err != nil { - panic(fmt.Sprintf("RemoteDB.Delete: %v", err)) - } -} - -func (rd *RemoteDB) DeleteSync(key []byte) { - if _, err := rd.dc.DeleteSync(rd.ctx, &protodb.Entity{Key: key}); err != nil { - panic(fmt.Sprintf("RemoteDB.DeleteSync: %v", err)) - } -} - -func (rd *RemoteDB) Set(key, value []byte) { - if _, err := rd.dc.Set(rd.ctx, &protodb.Entity{Key: key, Value: value}); err != nil { - panic(fmt.Sprintf("RemoteDB.Set: %v", err)) - } -} - -func (rd *RemoteDB) SetSync(key, value []byte) { - if _, err := rd.dc.SetSync(rd.ctx, &protodb.Entity{Key: key, Value: value}); err != nil { - panic(fmt.Sprintf("RemoteDB.SetSync: %v", err)) - } -} - -func (rd *RemoteDB) Get(key []byte) []byte { - res, err := rd.dc.Get(rd.ctx, &protodb.Entity{Key: key}) - if err != nil { - panic(fmt.Sprintf("RemoteDB.Get error: %v", err)) - } - return res.Value -} - -func (rd *RemoteDB) Has(key []byte) bool { - res, err := rd.dc.Has(rd.ctx, &protodb.Entity{Key: key}) - if err != nil { - panic(fmt.Sprintf("RemoteDB.Has error: %v", err)) - } - return res.Exists -} - -func (rd *RemoteDB) ReverseIterator(start, end []byte) db.Iterator { - dic, err := rd.dc.ReverseIterator(rd.ctx, &protodb.Entity{Start: start, End: end}) - if err != nil { - panic(fmt.Sprintf("RemoteDB.Iterator error: %v", err)) - } - return makeReverseIterator(dic) -} - -func (rd *RemoteDB) NewBatch() db.Batch { - return &batch{ - db: rd, - ops: nil, - } -} - -// TODO: Implement Print when db.DB implements a method -// to print to a string and not db.Print to stdout. -func (rd *RemoteDB) Print() { - panic("Unimplemented") -} - -func (rd *RemoteDB) Stats() map[string]string { - stats, err := rd.dc.Stats(rd.ctx, &protodb.Nothing{}) - if err != nil { - panic(fmt.Sprintf("RemoteDB.Stats error: %v", err)) - } - if stats == nil { - return nil - } - return stats.Data -} - -func (rd *RemoteDB) Iterator(start, end []byte) db.Iterator { - dic, err := rd.dc.Iterator(rd.ctx, &protodb.Entity{Start: start, End: end}) - if err != nil { - panic(fmt.Sprintf("RemoteDB.Iterator error: %v", err)) - } - return makeIterator(dic) -} - -func makeIterator(dic protodb.DB_IteratorClient) db.Iterator { - return &iterator{dic: dic} -} - -func makeReverseIterator(dric protodb.DB_ReverseIteratorClient) db.Iterator { - return &reverseIterator{dric: dric} -} - -type reverseIterator struct { - dric protodb.DB_ReverseIteratorClient - cur *protodb.Iterator -} - -var _ db.Iterator = (*iterator)(nil) - -func (rItr *reverseIterator) Valid() bool { - return rItr.cur != nil && rItr.cur.Valid -} - -func (rItr *reverseIterator) Domain() (start, end []byte) { - if rItr.cur == nil || rItr.cur.Domain == nil { - return nil, nil - } - return rItr.cur.Domain.Start, rItr.cur.Domain.End -} - -// Next advances the current reverseIterator -func (rItr *reverseIterator) Next() { - var err error - rItr.cur, err = rItr.dric.Recv() - if err != nil { - panic(fmt.Sprintf("RemoteDB.ReverseIterator.Next error: %v", err)) - } -} - -func (rItr *reverseIterator) Key() []byte { - if rItr.cur == nil { - return nil - } - return rItr.cur.Key -} - -func (rItr *reverseIterator) Value() []byte { - if rItr.cur == nil { - return nil - } - return rItr.cur.Value -} - -func (rItr *reverseIterator) Close() { -} - -// iterator implements the db.Iterator by retrieving -// streamed iterators from the remote backend as -// needed. It is NOT safe for concurrent usage, -// matching the behavior of other iterators. -type iterator struct { - dic protodb.DB_IteratorClient - cur *protodb.Iterator -} - -var _ db.Iterator = (*iterator)(nil) - -func (itr *iterator) Valid() bool { - return itr.cur != nil && itr.cur.Valid -} - -func (itr *iterator) Domain() (start, end []byte) { - if itr.cur == nil || itr.cur.Domain == nil { - return nil, nil - } - return itr.cur.Domain.Start, itr.cur.Domain.End -} - -// Next advances the current iterator -func (itr *iterator) Next() { - var err error - itr.cur, err = itr.dic.Recv() - if err != nil { - panic(fmt.Sprintf("RemoteDB.Iterator.Next error: %v", err)) - } -} - -func (itr *iterator) Key() []byte { - if itr.cur == nil { - return nil - } - return itr.cur.Key -} - -func (itr *iterator) Value() []byte { - if itr.cur == nil { - return nil - } - return itr.cur.Value -} - -func (itr *iterator) Close() { - err := itr.dic.CloseSend() - if err != nil { - panic(fmt.Sprintf("Error closing iterator: %v", err)) - } -} - -type batch struct { - db *RemoteDB - ops []*protodb.Operation -} - -var _ db.Batch = (*batch)(nil) - -func (bat *batch) Set(key, value []byte) { - op := &protodb.Operation{ - Entity: &protodb.Entity{Key: key, Value: value}, - Type: protodb.Operation_SET, - } - bat.ops = append(bat.ops, op) -} - -func (bat *batch) Delete(key []byte) { - op := &protodb.Operation{ - Entity: &protodb.Entity{Key: key}, - Type: protodb.Operation_DELETE, - } - bat.ops = append(bat.ops, op) -} - -func (bat *batch) Write() { - if _, err := bat.db.dc.BatchWrite(bat.db.ctx, &protodb.Batch{Ops: bat.ops}); err != nil { - panic(fmt.Sprintf("RemoteDB.BatchWrite: %v", err)) - } -} - -func (bat *batch) WriteSync() { - if _, err := bat.db.dc.BatchWriteSync(bat.db.ctx, &protodb.Batch{Ops: bat.ops}); err != nil { - panic(fmt.Sprintf("RemoteDB.BatchWriteSync: %v", err)) - } -} - -func (bat *batch) Close() { - bat.ops = nil -} diff --git a/libs/db/remotedb/remotedb_test.go b/libs/db/remotedb/remotedb_test.go deleted file mode 100644 index 43a022461..000000000 --- a/libs/db/remotedb/remotedb_test.go +++ /dev/null @@ -1,123 +0,0 @@ -package remotedb_test - -import ( - "net" - "os" - "testing" - - "github.com/stretchr/testify/require" - - "github.com/tendermint/tendermint/libs/db/remotedb" - "github.com/tendermint/tendermint/libs/db/remotedb/grpcdb" -) - -func TestRemoteDB(t *testing.T) { - cert := "test.crt" - key := "test.key" - ln, err := net.Listen("tcp", "localhost:0") - require.Nil(t, err, "expecting a port to have been assigned on which we can listen") - srv, err := grpcdb.NewServer(cert, key) - require.Nil(t, err) - defer srv.Stop() - go func() { - if err := srv.Serve(ln); err != nil { - t.Fatalf("BindServer: %v", err) - } - }() - - client, err := remotedb.NewRemoteDB(ln.Addr().String(), cert) - require.Nil(t, err, "expecting a successful client creation") - dbName := "test-remote-db" - require.Nil(t, client.InitRemote(&remotedb.Init{Name: dbName, Type: "goleveldb"})) - defer func() { - err := os.RemoveAll(dbName + ".db") - if err != nil { - panic(err) - } - }() - - k1 := []byte("key-1") - v1 := client.Get(k1) - require.Equal(t, 0, len(v1), "expecting no key1 to have been stored, got %X (%s)", v1, v1) - vv1 := []byte("value-1") - client.Set(k1, vv1) - gv1 := client.Get(k1) - require.Equal(t, gv1, vv1) - - // Simple iteration - itr := client.Iterator(nil, nil) - itr.Next() - require.Equal(t, itr.Key(), []byte("key-1")) - require.Equal(t, itr.Value(), []byte("value-1")) - require.Panics(t, itr.Next) - itr.Close() - - // Set some more keys - k2 := []byte("key-2") - v2 := []byte("value-2") - client.SetSync(k2, v2) - has := client.Has(k2) - require.True(t, has) - gv2 := client.Get(k2) - require.Equal(t, gv2, v2) - - // More iteration - itr = client.Iterator(nil, nil) - itr.Next() - require.Equal(t, itr.Key(), []byte("key-1")) - require.Equal(t, itr.Value(), []byte("value-1")) - itr.Next() - require.Equal(t, itr.Key(), []byte("key-2")) - require.Equal(t, itr.Value(), []byte("value-2")) - require.Panics(t, itr.Next) - itr.Close() - - // Deletion - client.Delete(k1) - client.DeleteSync(k2) - gv1 = client.Get(k1) - gv2 = client.Get(k2) - require.Equal(t, len(gv2), 0, "after deletion, not expecting the key to exist anymore") - require.Equal(t, len(gv1), 0, "after deletion, not expecting the key to exist anymore") - - // Batch tests - set - k3 := []byte("key-3") - k4 := []byte("key-4") - k5 := []byte("key-5") - v3 := []byte("value-3") - v4 := []byte("value-4") - v5 := []byte("value-5") - bat := client.NewBatch() - bat.Set(k3, v3) - bat.Set(k4, v4) - rv3 := client.Get(k3) - require.Equal(t, 0, len(rv3), "expecting no k3 to have been stored") - rv4 := client.Get(k4) - require.Equal(t, 0, len(rv4), "expecting no k4 to have been stored") - bat.Write() - rv3 = client.Get(k3) - require.Equal(t, rv3, v3, "expecting k3 to have been stored") - rv4 = client.Get(k4) - require.Equal(t, rv4, v4, "expecting k4 to have been stored") - - // Batch tests - deletion - bat = client.NewBatch() - bat.Delete(k4) - bat.Delete(k3) - bat.WriteSync() - rv3 = client.Get(k3) - require.Equal(t, 0, len(rv3), "expecting k3 to have been deleted") - rv4 = client.Get(k4) - require.Equal(t, 0, len(rv4), "expecting k4 to have been deleted") - - // Batch tests - set and delete - bat = client.NewBatch() - bat.Set(k4, v4) - bat.Set(k5, v5) - bat.Delete(k4) - bat.WriteSync() - rv4 = client.Get(k4) - require.Equal(t, 0, len(rv4), "expecting k4 to have been deleted") - rv5 := client.Get(k5) - require.Equal(t, rv5, v5, "expecting k5 to have been stored") -} diff --git a/libs/db/remotedb/test.crt b/libs/db/remotedb/test.crt deleted file mode 100644 index 1090e73d7..000000000 --- a/libs/db/remotedb/test.crt +++ /dev/null @@ -1,25 +0,0 @@ ------BEGIN CERTIFICATE----- -MIIEOjCCAiKgAwIBAgIQYO+jRR0Sbs+WzU/hj2aoxzANBgkqhkiG9w0BAQsFADAZ -MRcwFQYDVQQDEw50ZW5kZXJtaW50LmNvbTAeFw0xOTA2MDIxMTAyMDdaFw0yMDEy -MDIxMTAyMDRaMBMxETAPBgNVBAMTCHJlbW90ZWRiMIIBIjANBgkqhkiG9w0BAQEF -AAOCAQ8AMIIBCgKCAQEAt7YkYMJ5X5X3MT1tWG1KFO3uyZl962fInl+43xVESydp -qYYHYei7b3T8c/3Ww6f3aKkkCHrvPtqHZjU6o+wp/AQMNlyUoyRN89+6Oj67u2C7 -iZjzAJ+Pk87jMaStubvmZ9J+uk4op4rv5Rt4ns/Kg70RaMvqYR8tGqPcy3o8fWS+ -hCbuwAS8b65yp+AgbnThDEBUnieN3OFLfDV//45qw2OlqlM/gHOVT2JMRbl14Y7x -tW3/Xe+lsB7B3+OC6NQ2Nu7DEA1X+TBNyItIGnQH6DwK2ZBRtyQEk26FAWVj8fHd -A5I4+RcGWXz4T6gJmDZN7+47WHO0ProjARbUV0GIuQIDAQABo4GDMIGAMA4GA1Ud -DwEB/wQEAwIDuDAdBgNVHSUEFjAUBggrBgEFBQcDAQYIKwYBBQUHAwIwHQYDVR0O -BBYEFOA8wzCYhoZmy0WHgnv/0efijUMKMB8GA1UdIwQYMBaAFNSTPe743aIx7rIp -vn5HV3gJ4z1hMA8GA1UdEQQIMAaHBH8AAAEwDQYJKoZIhvcNAQELBQADggIBAKZf -EVo0i9nMZv6ZJjbmAlMfo5FH41/oBYC8pyGAnJKl42raXKJAbl45h80iGn3vNggf -7HJjN+znAHDFYjIwK2IV2WhHPyxK6uk+FA5uBR/aAPcw+zhRfXUMYdhNHr6KBlZZ -bvD7Iq4UALg+XFQz/fQkIi7QvTBwkYyPNA2+a/TGf6myMp26hoz73DQXklqm6Zle -myPs1Vp9bTgOv/3l64BMUV37FZ2TyiisBkV1qPEoDxT7Fbi8G1K8gMDLd0wu0jvX -nz96nk30TDnZewV1fhkMJVKKGiLbaIgHcu1lWsWJZ0tdc+MF7R9bLBO5T0cTDgNy -V8/51g+Cxu5SSHKjFkT0vBBONhjPmRqzJpxOQfHjiv8mmHwwiaNNy2VkJHj5GHer -64r67fQTSqAifzgwAbXYK+ObUbx4PnHvSYSF5dbcR1Oj6UTVtGAgdmN2Y03AIc1B -CiaojcMVuMRz/SvmPWl34GBvvT5/h9VCpHEB3vV6bQxJb5U1fLyo4GABA2Ic3DHr -kV5p7CZI06UNbyQyFtnEb5XoXywRa4Df7FzDIv3HL13MtyXrYrJqC1eAbn+3jGdh -bQa510mWYAlQQmzHSf/SLKott4QKR3SmhOGqGKNvquAYJ9XLdYdsPmKKGH6iGUD8 -n7yEi0KMD/BHsPQNNLatsR2SxqGDeLhbLR0w2hig ------END CERTIFICATE----- diff --git a/libs/db/remotedb/test.key b/libs/db/remotedb/test.key deleted file mode 100644 index b30bf809a..000000000 --- a/libs/db/remotedb/test.key +++ /dev/null @@ -1,27 +0,0 @@ ------BEGIN RSA PRIVATE KEY----- -MIIEpQIBAAKCAQEAt7YkYMJ5X5X3MT1tWG1KFO3uyZl962fInl+43xVESydpqYYH -Yei7b3T8c/3Ww6f3aKkkCHrvPtqHZjU6o+wp/AQMNlyUoyRN89+6Oj67u2C7iZjz -AJ+Pk87jMaStubvmZ9J+uk4op4rv5Rt4ns/Kg70RaMvqYR8tGqPcy3o8fWS+hCbu -wAS8b65yp+AgbnThDEBUnieN3OFLfDV//45qw2OlqlM/gHOVT2JMRbl14Y7xtW3/ -Xe+lsB7B3+OC6NQ2Nu7DEA1X+TBNyItIGnQH6DwK2ZBRtyQEk26FAWVj8fHdA5I4 -+RcGWXz4T6gJmDZN7+47WHO0ProjARbUV0GIuQIDAQABAoIBAQCEVFAZ3puc7aIU -NuIXqwmMz+KMFuMr+SL6aYr6LhB2bhpfQSr6LLEu1L6wMm1LnCbLneJVtW+1/6U+ -SyNFRmzrmmLNmZx7c0AvZb14DQ4fJ8uOjryje0vptUHT1YJJ4n5R1L7yJjCElsC8 -cDBPfO+sOzlaGmBmuxU7NkNp0k/WJc1Wnn5WFCKKk8BCH1AUKvn/vwbRV4zl/Be7 -ApywPUouV+GJlTAG5KLb15CWKSqFNJxUJ6K7NnmfDoy7muUUv8MtrTn59XTH4qK7 -p/3A8tdNpR/RpEJ8+y3kS9CDZBVnsk0j0ptT//jdt1vSsylXxrf7vjLnyguRZZ5H -Vwe2POotAoGBAOY1UaFjtIz2G5qromaUtrPb5EPWRU8fiLtUXUDKG8KqNAqsGbDz -Stw1mVFyyuaFMReO18djCvcja1xxF3TZbdpV1k7RfcpEZXiFzBAPgeEGdA3Tc3V2 -byuJQthWamCBxF/7OGUmH/E/kH0pv5g9+eIitK/CUC2YUhCnubhchGAXAoGBAMxL -O7mnPqDJ2PqxVip/lL6VnchtF1bx1aDNr83rVTf+BEsOgCIFoDEBIVKDnhXlaJu7 -8JN4la/esytq4j3nM1cl6mjvw2ixYmwQtKiDuNiyb88hhQ+nxVsbIpYxtbhsj+u5 -hOrMN6jKd0GVWsYpdNvY/dXZG1MXhbWwExjRAY+vAoGBAKBu3jHUU5q9VWWIYciN -sXpNL5qbNHg86MRsugSSFaCnj1c0sz7ffvdSn0Pk9USL5Defw/9fpd+wHn0xD4DO -msFDevQ5CSoyWmkRDbLPq9sP7UdJariczkMQCLbOGpqhNSMS6C2N0UsG2oJv2ueV -oZUYTMYEbG4qLl8PFN5IE7UHAoGAGwEq4OyZm7lyxBii8jUxHUw7sh2xgx2uhnYJ -8idUeXVLbfx5tYWW2kNy+yxIvk432LYsI+JBryC6AFg9lb81CyUI6lwfMXyZLP28 -U7Ytvf9ARloA88PSk6tvk/j4M2uuTpOUXVEnXll9EB9FA4LBXro9O4JaWU53rz+a -FqKyGSMCgYEAuYCGC+Fz7lIa0aE4tT9mwczQequxGYsL41KR/4pDO3t9QsnzunLY -fvCFhteBOstwTBBdfBaKIwSp3zI2QtA4K0Jx9SAJ9q0ft2ciB9ukUFBhC9+TqzXg -gSz3XpRtI8PhwAxZgCnov+NPQV8IxvD4ZgnnEiRBHrYnSEsaMLoVnkw= ------END RSA PRIVATE KEY----- diff --git a/libs/db/types.go b/libs/db/types.go deleted file mode 100644 index 30f8afd18..000000000 --- a/libs/db/types.go +++ /dev/null @@ -1,136 +0,0 @@ -package db - -// DBs are goroutine safe. -type DB interface { - - // Get returns nil iff key doesn't exist. - // A nil key is interpreted as an empty byteslice. - // CONTRACT: key, value readonly []byte - Get([]byte) []byte - - // Has checks if a key exists. - // A nil key is interpreted as an empty byteslice. - // CONTRACT: key, value readonly []byte - Has(key []byte) bool - - // Set sets the key. - // A nil key is interpreted as an empty byteslice. - // CONTRACT: key, value readonly []byte - Set([]byte, []byte) - SetSync([]byte, []byte) - - // Delete deletes the key. - // A nil key is interpreted as an empty byteslice. - // CONTRACT: key readonly []byte - Delete([]byte) - DeleteSync([]byte) - - // Iterate over a domain of keys in ascending order. End is exclusive. - // Start must be less than end, or the Iterator is invalid. - // A nil start is interpreted as an empty byteslice. - // If end is nil, iterates up to the last item (inclusive). - // CONTRACT: No writes may happen within a domain while an iterator exists over it. - // CONTRACT: start, end readonly []byte - Iterator(start, end []byte) Iterator - - // Iterate over a domain of keys in descending order. End is exclusive. - // Start must be less than end, or the Iterator is invalid. - // If start is nil, iterates up to the first/least item (inclusive). - // If end is nil, iterates from the last/greatest item (inclusive). - // CONTRACT: No writes may happen within a domain while an iterator exists over it. - // CONTRACT: start, end readonly []byte - ReverseIterator(start, end []byte) Iterator - - // Closes the connection. - Close() - - // Creates a batch for atomic updates. - NewBatch() Batch - - // For debugging - Print() - - // Stats returns a map of property values for all keys and the size of the cache. - Stats() map[string]string -} - -//---------------------------------------- -// Batch - -// Batch Close must be called when the program no longer needs the object. -type Batch interface { - SetDeleter - Write() - WriteSync() - Close() -} - -type SetDeleter interface { - Set(key, value []byte) // CONTRACT: key, value readonly []byte - Delete(key []byte) // CONTRACT: key readonly []byte -} - -//---------------------------------------- -// Iterator - -/* - Usage: - - var itr Iterator = ... - defer itr.Close() - - for ; itr.Valid(); itr.Next() { - k, v := itr.Key(); itr.Value() - // ... - } -*/ -type Iterator interface { - - // The start & end (exclusive) limits to iterate over. - // If end < start, then the Iterator goes in reverse order. - // - // A domain of ([]byte{12, 13}, []byte{12, 14}) will iterate - // over anything with the prefix []byte{12, 13}. - // - // The smallest key is the empty byte array []byte{} - see BeginningKey(). - // The largest key is the nil byte array []byte(nil) - see EndingKey(). - // CONTRACT: start, end readonly []byte - Domain() (start []byte, end []byte) - - // Valid returns whether the current position is valid. - // Once invalid, an Iterator is forever invalid. - Valid() bool - - // Next moves the iterator to the next sequential key in the database, as - // defined by order of iteration. - // - // If Valid returns false, this method will panic. - Next() - - // Key returns the key of the cursor. - // If Valid returns false, this method will panic. - // CONTRACT: key readonly []byte - Key() (key []byte) - - // Value returns the value of the cursor. - // If Valid returns false, this method will panic. - // CONTRACT: value readonly []byte - Value() (value []byte) - - // Close releases the Iterator. - Close() -} - -// For testing convenience. -func bz(s string) []byte { - return []byte(s) -} - -// We defensively turn nil keys or values into []byte{} for -// most operations. -func nonNilBytes(bz []byte) []byte { - if bz == nil { - return []byte{} - } - return bz -} diff --git a/libs/db/util.go b/libs/db/util.go deleted file mode 100644 index e927c3548..000000000 --- a/libs/db/util.go +++ /dev/null @@ -1,45 +0,0 @@ -package db - -import ( - "bytes" -) - -func cp(bz []byte) (ret []byte) { - ret = make([]byte, len(bz)) - copy(ret, bz) - return ret -} - -// Returns a slice of the same length (big endian) -// except incremented by one. -// Returns nil on overflow (e.g. if bz bytes are all 0xFF) -// CONTRACT: len(bz) > 0 -func cpIncr(bz []byte) (ret []byte) { - if len(bz) == 0 { - panic("cpIncr expects non-zero bz length") - } - ret = cp(bz) - for i := len(bz) - 1; i >= 0; i-- { - if ret[i] < byte(0xFF) { - ret[i]++ - return - } - ret[i] = byte(0x00) - if i == 0 { - // Overflow - return nil - } - } - return nil -} - -// See DB interface documentation for more information. -func IsKeyInDomain(key, start, end []byte) bool { - if bytes.Compare(key, start) < 0 { - return false - } - if end != nil && bytes.Compare(end, key) <= 0 { - return false - } - return true -} diff --git a/libs/db/util_test.go b/libs/db/util_test.go deleted file mode 100644 index 39a02160c..000000000 --- a/libs/db/util_test.go +++ /dev/null @@ -1,104 +0,0 @@ -package db - -import ( - "fmt" - "os" - "testing" -) - -// Empty iterator for empty db. -func TestPrefixIteratorNoMatchNil(t *testing.T) { - for backend := range backends { - t.Run(fmt.Sprintf("Prefix w/ backend %s", backend), func(t *testing.T) { - db, dir := newTempDB(t, backend) - defer os.RemoveAll(dir) - itr := IteratePrefix(db, []byte("2")) - - checkInvalid(t, itr) - }) - } -} - -// Empty iterator for db populated after iterator created. -func TestPrefixIteratorNoMatch1(t *testing.T) { - for backend := range backends { - if backend == BoltDBBackend { - t.Log("bolt does not support concurrent writes while iterating") - continue - } - - t.Run(fmt.Sprintf("Prefix w/ backend %s", backend), func(t *testing.T) { - db, dir := newTempDB(t, backend) - defer os.RemoveAll(dir) - itr := IteratePrefix(db, []byte("2")) - db.SetSync(bz("1"), bz("value_1")) - - checkInvalid(t, itr) - }) - } -} - -// Empty iterator for prefix starting after db entry. -func TestPrefixIteratorNoMatch2(t *testing.T) { - for backend := range backends { - t.Run(fmt.Sprintf("Prefix w/ backend %s", backend), func(t *testing.T) { - db, dir := newTempDB(t, backend) - defer os.RemoveAll(dir) - db.SetSync(bz("3"), bz("value_3")) - itr := IteratePrefix(db, []byte("4")) - - checkInvalid(t, itr) - }) - } -} - -// Iterator with single val for db with single val, starting from that val. -func TestPrefixIteratorMatch1(t *testing.T) { - for backend := range backends { - t.Run(fmt.Sprintf("Prefix w/ backend %s", backend), func(t *testing.T) { - db, dir := newTempDB(t, backend) - defer os.RemoveAll(dir) - db.SetSync(bz("2"), bz("value_2")) - itr := IteratePrefix(db, bz("2")) - - checkValid(t, itr, true) - checkItem(t, itr, bz("2"), bz("value_2")) - checkNext(t, itr, false) - - // Once invalid... - checkInvalid(t, itr) - }) - } -} - -// Iterator with prefix iterates over everything with same prefix. -func TestPrefixIteratorMatches1N(t *testing.T) { - for backend := range backends { - t.Run(fmt.Sprintf("Prefix w/ backend %s", backend), func(t *testing.T) { - db, dir := newTempDB(t, backend) - defer os.RemoveAll(dir) - - // prefixed - db.SetSync(bz("a/1"), bz("value_1")) - db.SetSync(bz("a/3"), bz("value_3")) - - // not - db.SetSync(bz("b/3"), bz("value_3")) - db.SetSync(bz("a-3"), bz("value_3")) - db.SetSync(bz("a.3"), bz("value_3")) - db.SetSync(bz("abcdefg"), bz("value_3")) - itr := IteratePrefix(db, bz("a/")) - - checkValid(t, itr, true) - checkItem(t, itr, bz("a/1"), bz("value_1")) - checkNext(t, itr, true) - checkItem(t, itr, bz("a/3"), bz("value_3")) - - // Bad! - checkNext(t, itr, false) - - //Once invalid... - checkInvalid(t, itr) - }) - } -} diff --git a/lite/dbprovider.go b/lite/dbprovider.go index 4e76e3657..79f34610c 100644 --- a/lite/dbprovider.go +++ b/lite/dbprovider.go @@ -7,10 +7,10 @@ import ( amino "github.com/tendermint/go-amino" cryptoAmino "github.com/tendermint/tendermint/crypto/encoding/amino" - dbm "github.com/tendermint/tendermint/libs/db" log "github.com/tendermint/tendermint/libs/log" lerr "github.com/tendermint/tendermint/lite/errors" "github.com/tendermint/tendermint/types" + dbm "github.com/tendermint/tm-cmn/db" ) var _ PersistentProvider = (*DBProvider)(nil) diff --git a/lite/dynamic_verifier_test.go b/lite/dynamic_verifier_test.go index e85cb7de0..ab8f94413 100644 --- a/lite/dynamic_verifier_test.go +++ b/lite/dynamic_verifier_test.go @@ -8,9 +8,9 @@ import ( "github.com/stretchr/testify/assert" "github.com/stretchr/testify/require" - dbm "github.com/tendermint/tendermint/libs/db" log "github.com/tendermint/tendermint/libs/log" "github.com/tendermint/tendermint/types" + dbm "github.com/tendermint/tm-cmn/db" ) func TestInquirerValidPath(t *testing.T) { diff --git a/lite/provider_test.go b/lite/provider_test.go index 94b467de8..63ae3ad38 100644 --- a/lite/provider_test.go +++ b/lite/provider_test.go @@ -7,10 +7,10 @@ import ( "github.com/stretchr/testify/assert" "github.com/stretchr/testify/require" - dbm "github.com/tendermint/tendermint/libs/db" log "github.com/tendermint/tendermint/libs/log" lerr "github.com/tendermint/tendermint/lite/errors" "github.com/tendermint/tendermint/types" + dbm "github.com/tendermint/tm-cmn/db" ) // missingProvider doesn't store anything, always a miss. diff --git a/lite/proxy/verifier.go b/lite/proxy/verifier.go index 429c54b2d..ac76d42aa 100644 --- a/lite/proxy/verifier.go +++ b/lite/proxy/verifier.go @@ -2,10 +2,10 @@ package proxy import ( cmn "github.com/tendermint/tendermint/libs/common" - dbm "github.com/tendermint/tendermint/libs/db" log "github.com/tendermint/tendermint/libs/log" "github.com/tendermint/tendermint/lite" lclient "github.com/tendermint/tendermint/lite/client" + dbm "github.com/tendermint/tm-cmn/db" ) func NewVerifier(chainID, rootDir string, client lclient.SignStatusClient, logger log.Logger, cacheSize int) (*lite.DynamicVerifier, error) { diff --git a/node/node.go b/node/node.go index 9beb0669f..73c7ed008 100644 --- a/node/node.go +++ b/node/node.go @@ -26,7 +26,6 @@ import ( "github.com/tendermint/tendermint/crypto/ed25519" "github.com/tendermint/tendermint/evidence" cmn "github.com/tendermint/tendermint/libs/common" - dbm "github.com/tendermint/tendermint/libs/db" "github.com/tendermint/tendermint/libs/log" tmpubsub "github.com/tendermint/tendermint/libs/pubsub" mempl "github.com/tendermint/tendermint/mempool" @@ -45,6 +44,7 @@ import ( "github.com/tendermint/tendermint/types" tmtime "github.com/tendermint/tendermint/types/time" "github.com/tendermint/tendermint/version" + dbm "github.com/tendermint/tm-cmn/db" ) // CustomReactorNamePrefix is a prefix for all custom reactors to prevent diff --git a/node/node_test.go b/node/node_test.go index 841a04686..0a0f8156a 100644 --- a/node/node_test.go +++ b/node/node_test.go @@ -17,7 +17,6 @@ import ( "github.com/tendermint/tendermint/crypto/ed25519" "github.com/tendermint/tendermint/evidence" cmn "github.com/tendermint/tendermint/libs/common" - dbm "github.com/tendermint/tendermint/libs/db" "github.com/tendermint/tendermint/libs/log" mempl "github.com/tendermint/tendermint/mempool" "github.com/tendermint/tendermint/p2p" @@ -28,6 +27,7 @@ import ( "github.com/tendermint/tendermint/types" tmtime "github.com/tendermint/tendermint/types/time" "github.com/tendermint/tendermint/version" + dbm "github.com/tendermint/tm-cmn/db" ) func TestNodeStartStop(t *testing.T) { diff --git a/p2p/trust/store.go b/p2p/trust/store.go index fc1ad399e..2b12f6957 100644 --- a/p2p/trust/store.go +++ b/p2p/trust/store.go @@ -10,7 +10,7 @@ import ( "time" cmn "github.com/tendermint/tendermint/libs/common" - dbm "github.com/tendermint/tendermint/libs/db" + dbm "github.com/tendermint/tm-cmn/db" ) const defaultStorePeriodicSaveInterval = 1 * time.Minute diff --git a/p2p/trust/store_test.go b/p2p/trust/store_test.go index e1bea8636..0efb6a7cf 100644 --- a/p2p/trust/store_test.go +++ b/p2p/trust/store_test.go @@ -10,8 +10,8 @@ import ( "testing" "github.com/stretchr/testify/assert" - dbm "github.com/tendermint/tendermint/libs/db" "github.com/tendermint/tendermint/libs/log" + dbm "github.com/tendermint/tm-cmn/db" ) func TestTrustMetricStoreSaveLoad(t *testing.T) { diff --git a/rpc/core/pipe.go b/rpc/core/pipe.go index 28a492e6f..a0fc7b9bb 100644 --- a/rpc/core/pipe.go +++ b/rpc/core/pipe.go @@ -6,7 +6,6 @@ import ( cfg "github.com/tendermint/tendermint/config" "github.com/tendermint/tendermint/consensus" "github.com/tendermint/tendermint/crypto" - dbm "github.com/tendermint/tendermint/libs/db" "github.com/tendermint/tendermint/libs/log" mempl "github.com/tendermint/tendermint/mempool" "github.com/tendermint/tendermint/p2p" @@ -14,6 +13,7 @@ import ( sm "github.com/tendermint/tendermint/state" "github.com/tendermint/tendermint/state/txindex" "github.com/tendermint/tendermint/types" + dbm "github.com/tendermint/tm-cmn/db" ) const ( diff --git a/state/execution.go b/state/execution.go index fd75b2959..45affacf6 100644 --- a/state/execution.go +++ b/state/execution.go @@ -5,12 +5,12 @@ import ( "time" abci "github.com/tendermint/tendermint/abci/types" - dbm "github.com/tendermint/tendermint/libs/db" "github.com/tendermint/tendermint/libs/fail" "github.com/tendermint/tendermint/libs/log" mempl "github.com/tendermint/tendermint/mempool" "github.com/tendermint/tendermint/proxy" "github.com/tendermint/tendermint/types" + dbm "github.com/tendermint/tm-cmn/db" ) //----------------------------------------------------------------------------- diff --git a/state/export_test.go b/state/export_test.go index af7f5cc23..a1428c1b3 100644 --- a/state/export_test.go +++ b/state/export_test.go @@ -2,8 +2,8 @@ package state import ( abci "github.com/tendermint/tendermint/abci/types" - dbm "github.com/tendermint/tendermint/libs/db" "github.com/tendermint/tendermint/types" + dbm "github.com/tendermint/tm-cmn/db" ) // diff --git a/state/helpers_test.go b/state/helpers_test.go index e8cb27585..bd2a4e5ec 100644 --- a/state/helpers_test.go +++ b/state/helpers_test.go @@ -7,11 +7,11 @@ import ( abci "github.com/tendermint/tendermint/abci/types" "github.com/tendermint/tendermint/crypto" "github.com/tendermint/tendermint/crypto/ed25519" - dbm "github.com/tendermint/tendermint/libs/db" "github.com/tendermint/tendermint/proxy" sm "github.com/tendermint/tendermint/state" "github.com/tendermint/tendermint/types" tmtime "github.com/tendermint/tendermint/types/time" + dbm "github.com/tendermint/tm-cmn/db" ) type paramsChangeTestCase struct { diff --git a/state/state_test.go b/state/state_test.go index a0f7a4a2a..29f76e27c 100644 --- a/state/state_test.go +++ b/state/state_test.go @@ -13,8 +13,8 @@ import ( abci "github.com/tendermint/tendermint/abci/types" "github.com/tendermint/tendermint/crypto/ed25519" cmn "github.com/tendermint/tendermint/libs/common" - dbm "github.com/tendermint/tendermint/libs/db" sm "github.com/tendermint/tendermint/state" + dbm "github.com/tendermint/tm-cmn/db" cfg "github.com/tendermint/tendermint/config" "github.com/tendermint/tendermint/types" diff --git a/state/store.go b/state/store.go index f0bb9e142..21494212c 100644 --- a/state/store.go +++ b/state/store.go @@ -5,8 +5,8 @@ import ( abci "github.com/tendermint/tendermint/abci/types" cmn "github.com/tendermint/tendermint/libs/common" - dbm "github.com/tendermint/tendermint/libs/db" "github.com/tendermint/tendermint/types" + dbm "github.com/tendermint/tm-cmn/db" ) const ( diff --git a/state/store_test.go b/state/store_test.go index 0cf217722..696252518 100644 --- a/state/store_test.go +++ b/state/store_test.go @@ -9,9 +9,9 @@ import ( "github.com/stretchr/testify/require" cfg "github.com/tendermint/tendermint/config" - dbm "github.com/tendermint/tendermint/libs/db" sm "github.com/tendermint/tendermint/state" "github.com/tendermint/tendermint/types" + dbm "github.com/tendermint/tm-cmn/db" ) func TestStoreLoadValidators(t *testing.T) { diff --git a/state/tx_filter_test.go b/state/tx_filter_test.go index bd3243168..c7b9fb536 100644 --- a/state/tx_filter_test.go +++ b/state/tx_filter_test.go @@ -8,9 +8,9 @@ import ( "github.com/stretchr/testify/require" cmn "github.com/tendermint/tendermint/libs/common" - dbm "github.com/tendermint/tendermint/libs/db" sm "github.com/tendermint/tendermint/state" "github.com/tendermint/tendermint/types" + dbm "github.com/tendermint/tm-cmn/db" ) func TestTxFilter(t *testing.T) { diff --git a/state/txindex/indexer_service_test.go b/state/txindex/indexer_service_test.go index 079f9cec2..9c9ad5476 100644 --- a/state/txindex/indexer_service_test.go +++ b/state/txindex/indexer_service_test.go @@ -8,11 +8,11 @@ import ( "github.com/stretchr/testify/require" abci "github.com/tendermint/tendermint/abci/types" - "github.com/tendermint/tendermint/libs/db" "github.com/tendermint/tendermint/libs/log" "github.com/tendermint/tendermint/state/txindex" "github.com/tendermint/tendermint/state/txindex/kv" "github.com/tendermint/tendermint/types" + "github.com/tendermint/tm-cmn/db" ) func TestIndexerServiceIndexesBlocks(t *testing.T) { diff --git a/state/txindex/kv/kv.go b/state/txindex/kv/kv.go index 053d26a71..16c7b5957 100644 --- a/state/txindex/kv/kv.go +++ b/state/txindex/kv/kv.go @@ -12,10 +12,10 @@ import ( "github.com/pkg/errors" cmn "github.com/tendermint/tendermint/libs/common" - dbm "github.com/tendermint/tendermint/libs/db" "github.com/tendermint/tendermint/libs/pubsub/query" "github.com/tendermint/tendermint/state/txindex" "github.com/tendermint/tendermint/types" + dbm "github.com/tendermint/tm-cmn/db" ) const ( diff --git a/state/txindex/kv/kv_test.go b/state/txindex/kv/kv_test.go index cacfaad01..cec84de7f 100644 --- a/state/txindex/kv/kv_test.go +++ b/state/txindex/kv/kv_test.go @@ -10,7 +10,7 @@ import ( "github.com/stretchr/testify/require" abci "github.com/tendermint/tendermint/abci/types" cmn "github.com/tendermint/tendermint/libs/common" - db "github.com/tendermint/tendermint/libs/db" + db "github.com/tendermint/tm-cmn/db" "github.com/tendermint/tendermint/libs/pubsub/query" "github.com/tendermint/tendermint/state/txindex" diff --git a/state/validation.go b/state/validation.go index 1d365e90c..27b90806d 100644 --- a/state/validation.go +++ b/state/validation.go @@ -6,8 +6,8 @@ import ( "fmt" "github.com/tendermint/tendermint/crypto" - dbm "github.com/tendermint/tendermint/libs/db" "github.com/tendermint/tendermint/types" + dbm "github.com/tendermint/tm-cmn/db" ) //----------------------------------------------------- From 073cd1125e3543580d56052dd478dae97efa5cb7 Mon Sep 17 00:00:00 2001 From: Marko Date: Fri, 19 Jul 2019 19:29:33 +0200 Subject: [PATCH 06/45] docs: add A TOC to the Readme.md of ADR Section (#3820) * ADR TOC in readme.md * Added A TOC to the Readme.md of ADR Section - Added table of contents to the Readme of the architecture section. - Easier to traverse and when you know what is there. - If the Adr's become viewable online it would help guide the user Signed-off-by: Marko Baricevic * add tm-cmn to subprojects * normalize word --- README.md | 40 ++++++++++++++++++------------------- docs/architecture/README.md | 38 +++++++++++++++++++++++++++++++++++ 2 files changed, 57 insertions(+), 21 deletions(-) diff --git a/README.md b/README.md index 994ca63b2..3ea9d5de4 100644 --- a/README.md +++ b/README.md @@ -1,23 +1,21 @@ # Tendermint + ![banner](docs/tendermint-core-image.jpg) [Byzantine-Fault Tolerant](https://en.wikipedia.org/wiki/Byzantine_fault_tolerance) [State Machines](https://en.wikipedia.org/wiki/State_machine_replication). -Or [Blockchain](https://en.wikipedia.org/wiki/Blockchain_(database)), for short. +Or [Blockchain](), for short. [![version](https://img.shields.io/github/tag/tendermint/tendermint.svg)](https://github.com/tendermint/tendermint/releases/latest) -[![API Reference]( -https://camo.githubusercontent.com/915b7be44ada53c290eb157634330494ebe3e30a/68747470733a2f2f676f646f632e6f72672f6769746875622e636f6d2f676f6c616e672f6764646f3f7374617475732e737667 -)](https://godoc.org/github.com/tendermint/tendermint) +[![API Reference](https://camo.githubusercontent.com/915b7be44ada53c290eb157634330494ebe3e30a/68747470733a2f2f676f646f632e6f72672f6769746875622e636f6d2f676f6c616e672f6764646f3f7374617475732e737667)](https://godoc.org/github.com/tendermint/tendermint) [![Go version](https://img.shields.io/badge/go-1.12.0-blue.svg)](https://github.com/moovweb/gvm) [![riot.im](https://img.shields.io/badge/riot.im-JOIN%20CHAT-green.svg)](https://riot.im/app/#/room/#tendermint:matrix.org) [![license](https://img.shields.io/github/license/tendermint/tendermint.svg)](https://github.com/tendermint/tendermint/blob/master/LICENSE) [![](https://tokei.rs/b1/github/tendermint/tendermint?category=lines)](https://github.com/tendermint/tendermint) - -Branch | Tests | Coverage -----------|-------|---------- -master | [![CircleCI](https://circleci.com/gh/tendermint/tendermint/tree/master.svg?style=shield)](https://circleci.com/gh/tendermint/tendermint/tree/master) | [![codecov](https://codecov.io/gh/tendermint/tendermint/branch/master/graph/badge.svg)](https://codecov.io/gh/tendermint/tendermint) +| Branch | Tests | Coverage | +| ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | +| master | [![CircleCI](https://circleci.com/gh/tendermint/tendermint/tree/master.svg?style=shield)](https://circleci.com/gh/tendermint/tendermint/tree/master) | [![codecov](https://codecov.io/gh/tendermint/tendermint/branch/master/graph/badge.svg)](https://codecov.io/gh/tendermint/tendermint) | Tendermint Core is Byzantine Fault Tolerant (BFT) middleware that takes a state transition machine - written in any programming language - and securely replicates it on many machines. @@ -49,9 +47,9 @@ For examples of the kinds of bugs we're looking for, see [SECURITY.md](SECURITY. ## Minimum requirements -Requirement|Notes ----|--- -Go version | Go1.11.4 or higher +| Requirement | Notes | +| ----------- | ------------------ | +| Go version | Go1.11.4 or higher | ## Documentation @@ -145,20 +143,20 @@ Additional documentation is found [here](/docs/tools). ### Sub-projects -* [Amino](http://github.com/tendermint/go-amino), reflection-based proto3, with +- [Amino](http://github.com/tendermint/go-amino), reflection-based proto3, with interfaces -* [IAVL](http://github.com/tendermint/iavl), Merkleized IAVL+ Tree implementation +- [IAVL](http://github.com/tendermint/iavl), Merkleized IAVL+ Tree implementation +- [Tm-cmn](http://github.com/tendermint/tm-cmn), Commonly used libs across Tendermint & Cosmos repos ### Applications -* [Cosmos SDK](http://github.com/cosmos/cosmos-sdk); a cryptocurrency application framework -* [Ethermint](http://github.com/cosmos/ethermint); Ethereum on Tendermint -* [Many more](https://tendermint.com/ecosystem) +- [Cosmos SDK](http://github.com/cosmos/cosmos-sdk); a cryptocurrency application framework +- [Ethermint](http://github.com/cosmos/ethermint); Ethereum on Tendermint +- [Many more](https://tendermint.com/ecosystem) ### Research -* [The latest gossip on BFT consensus](https://arxiv.org/abs/1807.04938) -* [Master's Thesis on Tendermint](https://atrium.lib.uoguelph.ca/xmlui/handle/10214/9769) -* [Original Whitepaper](https://tendermint.com/static/docs/tendermint.pdf) -* [Blog](https://blog.cosmos.network/tendermint/home) - +- [The latest gossip on BFT consensus](https://arxiv.org/abs/1807.04938) +- [Master's Thesis on Tendermint](https://atrium.lib.uoguelph.ca/xmlui/handle/10214/9769) +- [Original Whitepaper](https://tendermint.com/static/docs/tendermint.pdf) +- [Blog](https://blog.cosmos.network/tendermint/home) diff --git a/docs/architecture/README.md b/docs/architecture/README.md index 1cfc7ddce..0ff6682ac 100644 --- a/docs/architecture/README.md +++ b/docs/architecture/README.md @@ -20,3 +20,41 @@ it stands today. If recorded decisions turned out to be lacking, convene a discussion, record the new decisions here, and then modify the code to match. Note the context/background should be written in the present tense. + +### Table of Contents: + +- [ADR-001-Logging](./adr-001-logging.md) +- [ADR-002-Event-Subscription](./adr-002-event-subscription.md) +- [ADR-003-ABCI-APP-RPC](./adr-003-abci-app-rpc.md) +- [ADR-004-Historical-Validators](./adr-004-historical-validators.md) +- [ADR-005-Consensus-Params](./adr-005-consensus-params.md) +- [ADR-006-Trust-Metric](./adr-006-trust-metric.md) +- [ADR-007-Trust-Metric-Usage](./adr-007-trust-metric-usage.md) +- [ADR-008-Priv-Validator](./adr-008-priv-validator.md) +- [ADR-009-ABCI-Design](./adr-009-abci-design.md) +- [ADR-010-Crypto-Changes](./adr-010-crypto-changes.md) +- [ADR-011-Monitoring](./adr-011-monitoring.md) +- [ADR-012-Peer-Transport](./adr-012-peer-transport.md) +- [ADR-013-Symmetric-Crypto](./adr-013-symmetric-crypto.md) +- [ADR-014-Secp-Malleability](./adr-014-secp-malleability.md) +- [ADR-015-Crypto-Encoding](./adr-015-crypto-encoding.md) +- [ADR-016-Protocol-Versions](./adr-016-protocol-versions.md) +- [ADR-017-Chain-Versions](./adr-017-chain-versions.md) +- [ADR-018-ABCI-Validators](./adr-018-abci-validators.md) +- [ADR-019-Multisigs](./adr-019-multisigs.md) +- [ADR-020-Block-Size](./adr-020-block-size.md) +- [ADR-021-ABCI-Events](./adr-021-abci-events.md) +- [ADR-022-ABCI-Errors](./adr-022-abci-errors.md) +- [ADR-023-ABCI-Propose-tx](./adr-023-ABCI-propose-tx.md) +- [ADR-024-Sign-Bytes](./adr-024-sign-bytes.md) +- [ADR-025-Commit](./adr-025-commit.md) +- [ADR-026-General-Merkle-Proof](./adr-026-general-merkle-proof.md) +- [ADR-029-Check-Tx-Consensus](./adr-029-check-tx-consensus.md) +- [ADR-030-Consensus-Refactor](./adr-030-consensus-refactor.md) +- [ADR-033-Pubsub](./adr-033-pubsub.md) +- [ADR-034-Priv-Validator-File-Structure](./adr-034-priv-validator-file-structure.md) +- [ADR-035-Documentation](./adr-035-documentation.md) +- [ADR-037-Deliver-Block](./adr-037-deliver-block.md) +- [ADR-039-Peer-Behaviour](./adr-039-peer-behaviour.md) +- [ADR-041-Proposer-Selection-via-ABCI](./adr-041-proposer-selection-via-abci.md) +- [ADR-043-Blockchain-RiRi-Org](./adr-043-blockchain-riri-org.md) From 5d7e22a53cdb8c3dd5b6c574ed73d3af8ece820a Mon Sep 17 00:00:00 2001 From: Jun Kimura Date: Sat, 20 Jul 2019 16:44:42 +0900 Subject: [PATCH 07/45] rpc: make max_body_bytes and max_header_bytes configurable (#3818) * rpc: make max_body_bytes and max_header_bytes configurable * update changelog pending --- CHANGELOG_PENDING.md | 1 + config/config.go | 15 +++++++++++++++ config/toml.go | 6 ++++++ docs/tendermint-core/configuration.md | 6 ++++++ node/node.go | 25 ++++++++++++++----------- rpc/lib/server/handlers.go | 13 ++++++++++++- rpc/lib/server/http_server.go | 24 +++++++++++------------- 7 files changed, 65 insertions(+), 25 deletions(-) diff --git a/CHANGELOG_PENDING.md b/CHANGELOG_PENDING.md index e62bf1079..066e702f2 100644 --- a/CHANGELOG_PENDING.md +++ b/CHANGELOG_PENDING.md @@ -21,5 +21,6 @@ program](https://hackerone.com/tendermint). ### IMPROVEMENTS: - [abci] \#3809 Recover from application panics in `server/socket_server.go` to allow socket cleanup (@ruseinov) +- [rpc] \#3818 Make `max_body_bytes` and `max_header_bytes` configurable ### BUG FIXES: diff --git a/config/config.go b/config/config.go index 32e37f3e1..6a3cb8ce8 100644 --- a/config/config.go +++ b/config/config.go @@ -351,6 +351,12 @@ type RPCConfig struct { // See https://github.com/tendermint/tendermint/issues/3435 TimeoutBroadcastTxCommit time.Duration `mapstructure:"timeout_broadcast_tx_commit"` + // Maximum size of request body, in bytes + MaxBodyBytes int64 `mapstructure:"max_body_bytes"` + + // Maximum size of request header, in bytes + MaxHeaderBytes int `mapstructure:"max_header_bytes"` + // The path to a file containing certificate that is used to create the HTTPS server. // Migth be either absolute path or path related to tendermint's config directory. // @@ -385,6 +391,9 @@ func DefaultRPCConfig() *RPCConfig { MaxSubscriptionsPerClient: 5, TimeoutBroadcastTxCommit: 10 * time.Second, + MaxBodyBytes: int64(1000000), // 1MB + MaxHeaderBytes: 1 << 20, // same as the net/http default + TLSCertFile: "", TLSKeyFile: "", } @@ -417,6 +426,12 @@ func (cfg *RPCConfig) ValidateBasic() error { if cfg.TimeoutBroadcastTxCommit < 0 { return errors.New("timeout_broadcast_tx_commit can't be negative") } + if cfg.MaxBodyBytes < 0 { + return errors.New("max_body_bytes can't be negative") + } + if cfg.MaxHeaderBytes < 0 { + return errors.New("max_header_bytes can't be negative") + } return nil } diff --git a/config/toml.go b/config/toml.go index 09117a0fb..1cafc9c2d 100644 --- a/config/toml.go +++ b/config/toml.go @@ -192,6 +192,12 @@ max_subscriptions_per_client = {{ .RPC.MaxSubscriptionsPerClient }} # See https://github.com/tendermint/tendermint/issues/3435 timeout_broadcast_tx_commit = "{{ .RPC.TimeoutBroadcastTxCommit }}" +# Maximum size of request body, in bytes +max_body_bytes = {{ .RPC.MaxBodyBytes }} + +# Maximum size of request header, in bytes +max_header_bytes = {{ .RPC.MaxHeaderBytes }} + # The path to a file containing certificate that is used to create the HTTPS server. # Migth be either absolute path or path related to tendermint's config directory. # If the certificate is signed by a certificate authority, diff --git a/docs/tendermint-core/configuration.md b/docs/tendermint-core/configuration.md index b9f784596..026a75374 100644 --- a/docs/tendermint-core/configuration.md +++ b/docs/tendermint-core/configuration.md @@ -138,6 +138,12 @@ max_subscriptions_per_client = 5 # See https://github.com/tendermint/tendermint/issues/3435 timeout_broadcast_tx_commit = "10s" +# Maximum size of request body, in bytes +max_body_bytes = {{ .RPC.MaxBodyBytes }} + +# Maximum size of request header, in bytes +max_header_bytes = {{ .RPC.MaxHeaderBytes }} + # The path to a file containing certificate that is used to create the HTTPS server. # Migth be either absolute path or path related to tendermint's config directory. # If the certificate is signed by a certificate authority, diff --git a/node/node.go b/node/node.go index 73c7ed008..9a481e601 100644 --- a/node/node.go +++ b/node/node.go @@ -820,6 +820,17 @@ func (n *Node) startRPC() ([]net.Listener, error) { rpccore.AddUnsafeRoutes() } + config := rpcserver.DefaultConfig() + config.MaxBodyBytes = n.config.RPC.MaxBodyBytes + config.MaxHeaderBytes = n.config.RPC.MaxHeaderBytes + config.MaxOpenConnections = n.config.RPC.MaxOpenConnections + // If necessary adjust global WriteTimeout to ensure it's greater than + // TimeoutBroadcastTxCommit. + // See https://github.com/tendermint/tendermint/issues/3435 + if config.WriteTimeout <= n.config.RPC.TimeoutBroadcastTxCommit { + config.WriteTimeout = n.config.RPC.TimeoutBroadcastTxCommit + 1*time.Second + } + // we may expose the rpc over both a unix and tcp socket listeners := make([]net.Listener, len(listenAddrs)) for i, listenAddr := range listenAddrs { @@ -832,20 +843,12 @@ func (n *Node) startRPC() ([]net.Listener, error) { if err != nil && err != tmpubsub.ErrSubscriptionNotFound { wmLogger.Error("Failed to unsubscribe addr from events", "addr", remoteAddr, "err", err) } - })) + }), + rpcserver.ReadLimit(config.MaxBodyBytes), + ) wm.SetLogger(wmLogger) mux.HandleFunc("/websocket", wm.WebsocketHandler) rpcserver.RegisterRPCFuncs(mux, rpccore.Routes, coreCodec, rpcLogger) - - config := rpcserver.DefaultConfig() - config.MaxOpenConnections = n.config.RPC.MaxOpenConnections - // If necessary adjust global WriteTimeout to ensure it's greater than - // TimeoutBroadcastTxCommit. - // See https://github.com/tendermint/tendermint/issues/3435 - if config.WriteTimeout <= n.config.RPC.TimeoutBroadcastTxCommit { - config.WriteTimeout = n.config.RPC.TimeoutBroadcastTxCommit + 1*time.Second - } - listener, err := rpcserver.Listen( listenAddr, config, diff --git a/rpc/lib/server/handlers.go b/rpc/lib/server/handlers.go index c1c1ebf1a..434ee8916 100644 --- a/rpc/lib/server/handlers.go +++ b/rpc/lib/server/handlers.go @@ -448,6 +448,9 @@ type wsConnection struct { // Send pings to server with this period. Must be less than readWait, but greater than zero. pingPeriod time.Duration + // Maximum message size. + readLimit int64 + // callback which is called upon disconnect onDisconnect func(remoteAddr string) @@ -467,7 +470,6 @@ func NewWSConnection( cdc *amino.Codec, options ...func(*wsConnection), ) *wsConnection { - baseConn.SetReadLimit(maxBodyBytes) wsc := &wsConnection{ remoteAddr: baseConn.RemoteAddr().String(), baseConn: baseConn, @@ -481,6 +483,7 @@ func NewWSConnection( for _, option := range options { option(wsc) } + wsc.baseConn.SetReadLimit(wsc.readLimit) wsc.BaseService = *cmn.NewBaseService(nil, "wsConnection", wsc) return wsc } @@ -525,6 +528,14 @@ func PingPeriod(pingPeriod time.Duration) func(*wsConnection) { } } +// ReadLimit sets the maximum size for reading message. +// It should only be used in the constructor - not Goroutine-safe. +func ReadLimit(readLimit int64) func(*wsConnection) { + return func(wsc *wsConnection) { + wsc.readLimit = readLimit + } +} + // OnStart implements cmn.Service by starting the read and write routines. It // blocks until the connection closes. func (wsc *wsConnection) OnStart() error { diff --git a/rpc/lib/server/http_server.go b/rpc/lib/server/http_server.go index 7825605eb..c97739bd2 100644 --- a/rpc/lib/server/http_server.go +++ b/rpc/lib/server/http_server.go @@ -26,6 +26,11 @@ type Config struct { ReadTimeout time.Duration // mirrors http.Server#WriteTimeout WriteTimeout time.Duration + // MaxBodyBytes controls the maximum number of bytes the + // server will read parsing the request body. + MaxBodyBytes int64 + // mirrors http.Server#MaxHeaderBytes + MaxHeaderBytes int } // DefaultConfig returns a default configuration. @@ -34,28 +39,21 @@ func DefaultConfig() *Config { MaxOpenConnections: 0, // unlimited ReadTimeout: 10 * time.Second, WriteTimeout: 10 * time.Second, + MaxBodyBytes: int64(1000000), // 1MB + MaxHeaderBytes: 1 << 20, // same as the net/http default } } -const ( - // maxBodyBytes controls the maximum number of bytes the - // server will read parsing the request body. - maxBodyBytes = int64(1000000) // 1MB - - // same as the net/http default - maxHeaderBytes = 1 << 20 -) - // StartHTTPServer takes a listener and starts an HTTP server with the given handler. // It wraps handler with RecoverAndLogHandler. // NOTE: This function blocks - you may want to call it in a go-routine. func StartHTTPServer(listener net.Listener, handler http.Handler, logger log.Logger, config *Config) error { logger.Info(fmt.Sprintf("Starting RPC HTTP server on %s", listener.Addr())) s := &http.Server{ - Handler: RecoverAndLogHandler(maxBytesHandler{h: handler, n: maxBodyBytes}, logger), + Handler: RecoverAndLogHandler(maxBytesHandler{h: handler, n: config.MaxBodyBytes}, logger), ReadTimeout: config.ReadTimeout, WriteTimeout: config.WriteTimeout, - MaxHeaderBytes: maxHeaderBytes, + MaxHeaderBytes: config.MaxHeaderBytes, } err := s.Serve(listener) logger.Info("RPC HTTP server stopped", "err", err) @@ -75,10 +73,10 @@ func StartHTTPAndTLSServer( logger.Info(fmt.Sprintf("Starting RPC HTTPS server on %s (cert: %q, key: %q)", listener.Addr(), certFile, keyFile)) s := &http.Server{ - Handler: RecoverAndLogHandler(maxBytesHandler{h: handler, n: maxBodyBytes}, logger), + Handler: RecoverAndLogHandler(maxBytesHandler{h: handler, n: config.MaxBodyBytes}, logger), ReadTimeout: config.ReadTimeout, WriteTimeout: config.WriteTimeout, - MaxHeaderBytes: maxHeaderBytes, + MaxHeaderBytes: config.MaxHeaderBytes, } err := s.ServeTLS(listener, certFile, keyFile) From 17b69d4d5639ed1376d3973d833bde46291206bc Mon Sep 17 00:00:00 2001 From: zjubfd <296179868@qq.com> Date: Mon, 22 Jul 2019 15:37:41 +0800 Subject: [PATCH 08/45] p2p/conn: Add Bufferpool (#3664) * use byte buffer pool to decreass allocs * wrap to put buffer in defer * wapper defer * add dependency * remove Gopkg,* * add change log --- CHANGELOG_PENDING.md | 1 + go.mod | 1 + go.sum | 2 + p2p/conn/secret_connection.go | 95 +++++++++++++++++------------- p2p/conn/secret_connection_test.go | 61 ++++++++++++++++++- 5 files changed, 117 insertions(+), 43 deletions(-) diff --git a/CHANGELOG_PENDING.md b/CHANGELOG_PENDING.md index 066e702f2..290d70818 100644 --- a/CHANGELOG_PENDING.md +++ b/CHANGELOG_PENDING.md @@ -22,5 +22,6 @@ program](https://hackerone.com/tendermint). - [abci] \#3809 Recover from application panics in `server/socket_server.go` to allow socket cleanup (@ruseinov) - [rpc] \#3818 Make `max_body_bytes` and `max_header_bytes` configurable +- [p2p] \#3664 p2p/conn: reuse buffer when write/read from secret connection ### BUG FIXES: diff --git a/go.mod b/go.mod index 6b6d94c21..617883cb8 100644 --- a/go.mod +++ b/go.mod @@ -18,6 +18,7 @@ require ( github.com/hashicorp/hcl v1.0.0 // indirect github.com/inconshreveable/mousetrap v1.0.0 // indirect github.com/kr/logfmt v0.0.0-20140226030751-b84e30acd515 // indirect + github.com/libp2p/go-buffer-pool v0.0.1 github.com/magiconair/properties v1.8.0 github.com/matttproud/golang_protobuf_extensions v1.0.1 // indirect github.com/mitchellh/mapstructure v1.1.2 // indirect diff --git a/go.sum b/go.sum index 418e8e6eb..7f1334f79 100644 --- a/go.sum +++ b/go.sum @@ -64,6 +64,8 @@ github.com/kisielk/gotool v1.0.0/go.mod h1:XhKaO+MFFWcvkIS/tQcRk01m1F5IRFswLeQ+o github.com/kkdai/bstream v0.0.0-20161212061736-f391b8402d23/go.mod h1:J+Gs4SYgM6CZQHDETBtE9HaSEkGmuNXF86RwHhHUvq4= github.com/kr/logfmt v0.0.0-20140226030751-b84e30acd515 h1:T+h1c/A9Gawja4Y9mFVWj2vyii2bbUNDw3kt9VxK2EY= github.com/kr/logfmt v0.0.0-20140226030751-b84e30acd515/go.mod h1:+0opPa2QZZtGFBFZlji/RkVcI2GknAs/DXo4wKdlNEc= +github.com/libp2p/go-buffer-pool v0.0.1 h1:9Rrn/H46cXjaA2HQ5Y8lyhOS1NhTkZ4yuEs2r3Eechg= +github.com/libp2p/go-buffer-pool v0.0.1/go.mod h1:xtyIz9PMobb13WaxR6Zo1Pd1zXJKYg0a8KiIvDp3TzQ= github.com/magiconair/properties v1.8.0 h1:LLgXmsheXeRoUOBOjtwPQCWIYqM/LU1ayDtDePerRcY= github.com/magiconair/properties v1.8.0/go.mod h1:PppfXfuXeibc/6YijjN8zIbojt8czPbwD3XqdrwzmxQ= github.com/matttproud/golang_protobuf_extensions v1.0.1 h1:4hp9jkHxhMHkqkrB3Ix0jegS5sx/RkqARlsWZ6pIwiU= diff --git a/p2p/conn/secret_connection.go b/p2p/conn/secret_connection.go index 7f76ac800..a4489f475 100644 --- a/p2p/conn/secret_connection.go +++ b/p2p/conn/secret_connection.go @@ -2,6 +2,7 @@ package conn import ( "bytes" + "crypto/cipher" crand "crypto/rand" "crypto/sha256" "crypto/subtle" @@ -17,6 +18,7 @@ import ( "golang.org/x/crypto/curve25519" "golang.org/x/crypto/nacl/box" + pool "github.com/libp2p/go-buffer-pool" "github.com/tendermint/tendermint/crypto" cmn "github.com/tendermint/tendermint/libs/common" "golang.org/x/crypto/hkdf" @@ -47,10 +49,11 @@ var ( type SecretConnection struct { // immutable - recvSecret *[aeadKeySize]byte - sendSecret *[aeadKeySize]byte - remPubKey crypto.PubKey - conn io.ReadWriteCloser + recvAead cipher.AEAD + sendAead cipher.AEAD + + remPubKey crypto.PubKey + conn io.ReadWriteCloser // net.Conn must be thread safe: // https://golang.org/pkg/net/#Conn. @@ -102,14 +105,22 @@ func MakeSecretConnection(conn io.ReadWriteCloser, locPrivKey crypto.PrivKey) (* // generate the secret used for receiving, sending, challenge via hkdf-sha2 on dhSecret recvSecret, sendSecret, challenge := deriveSecretAndChallenge(dhSecret, locIsLeast) + sendAead, err := chacha20poly1305.New(sendSecret[:]) + if err != nil { + return nil, errors.New("Invalid send SecretConnection Key") + } + recvAead, err := chacha20poly1305.New(recvSecret[:]) + if err != nil { + return nil, errors.New("Invalid receive SecretConnection Key") + } // Construct SecretConnection. sc := &SecretConnection{ conn: conn, recvBuffer: nil, recvNonce: new([aeadNonceSize]byte), sendNonce: new([aeadNonceSize]byte), - recvSecret: recvSecret, - sendSecret: sendSecret, + recvAead: recvAead, + sendAead: sendAead, } // Sign the challenge bytes for authentication. @@ -143,35 +154,39 @@ func (sc *SecretConnection) Write(data []byte) (n int, err error) { defer sc.sendMtx.Unlock() for 0 < len(data) { - var frame = make([]byte, totalFrameSize) - var chunk []byte - if dataMaxSize < len(data) { - chunk = data[:dataMaxSize] - data = data[dataMaxSize:] - } else { - chunk = data - data = nil - } - chunkLength := len(chunk) - binary.LittleEndian.PutUint32(frame, uint32(chunkLength)) - copy(frame[dataLenSize:], chunk) + if err := func() error { + var sealedFrame = pool.Get(aeadSizeOverhead + totalFrameSize) + var frame = pool.Get(totalFrameSize) + defer func() { + pool.Put(sealedFrame) + pool.Put(frame) + }() + var chunk []byte + if dataMaxSize < len(data) { + chunk = data[:dataMaxSize] + data = data[dataMaxSize:] + } else { + chunk = data + data = nil + } + chunkLength := len(chunk) + binary.LittleEndian.PutUint32(frame, uint32(chunkLength)) + copy(frame[dataLenSize:], chunk) - aead, err := chacha20poly1305.New(sc.sendSecret[:]) - if err != nil { - return n, errors.New("Invalid SecretConnection Key") - } + // encrypt the frame + sc.sendAead.Seal(sealedFrame[:0], sc.sendNonce[:], frame, nil) + incrNonce(sc.sendNonce) + // end encryption - // encrypt the frame - var sealedFrame = make([]byte, aeadSizeOverhead+totalFrameSize) - aead.Seal(sealedFrame[:0], sc.sendNonce[:], frame, nil) - incrNonce(sc.sendNonce) - // end encryption - - _, err = sc.conn.Write(sealedFrame) - if err != nil { + _, err = sc.conn.Write(sealedFrame) + if err != nil { + return err + } + n += len(chunk) + return nil + }(); err != nil { return n, err } - n += len(chunk) } return } @@ -189,21 +204,18 @@ func (sc *SecretConnection) Read(data []byte) (n int, err error) { } // read off the conn - sealedFrame := make([]byte, totalFrameSize+aeadSizeOverhead) + var sealedFrame = pool.Get(aeadSizeOverhead + totalFrameSize) + defer pool.Put(sealedFrame) _, err = io.ReadFull(sc.conn, sealedFrame) if err != nil { return } - aead, err := chacha20poly1305.New(sc.recvSecret[:]) - if err != nil { - return n, errors.New("Invalid SecretConnection Key") - } - // decrypt the frame. // reads and updates the sc.recvNonce - var frame = make([]byte, totalFrameSize) - _, err = aead.Open(frame[:0], sc.recvNonce[:], sealedFrame, nil) + var frame = pool.Get(totalFrameSize) + defer pool.Put(frame) + _, err = sc.recvAead.Open(frame[:0], sc.recvNonce[:], sealedFrame, nil) if err != nil { return n, errors.New("Failed to decrypt SecretConnection") } @@ -218,7 +230,10 @@ func (sc *SecretConnection) Read(data []byte) (n int, err error) { } var chunk = frame[dataLenSize : dataLenSize+chunkLength] n = copy(data, chunk) - sc.recvBuffer = chunk[n:] + if n < len(chunk) { + sc.recvBuffer = make([]byte, len(chunk)-n) + copy(sc.recvBuffer, chunk[n:]) + } return } diff --git a/p2p/conn/secret_connection_test.go b/p2p/conn/secret_connection_test.go index 7e264e913..76982ed97 100644 --- a/p2p/conn/secret_connection_test.go +++ b/p2p/conn/secret_connection_test.go @@ -383,10 +383,23 @@ func createGoldenTestVectors(t *testing.T) string { return data } -func BenchmarkSecretConnection(b *testing.B) { +func BenchmarkWriteSecretConnection(b *testing.B) { b.StopTimer() + b.ReportAllocs() fooSecConn, barSecConn := makeSecretConnPair(b) - fooWriteText := cmn.RandStr(dataMaxSize) + randomMsgSizes := []int{ + dataMaxSize / 10, + dataMaxSize / 3, + dataMaxSize / 2, + dataMaxSize, + dataMaxSize * 3 / 2, + dataMaxSize * 2, + dataMaxSize * 7 / 2, + } + fooWriteBytes := make([][]byte, 0, len(randomMsgSizes)) + for _, size := range randomMsgSizes { + fooWriteBytes = append(fooWriteBytes, cmn.RandBytes(size)) + } // Consume reads from bar's reader go func() { readBuffer := make([]byte, dataMaxSize) @@ -402,7 +415,8 @@ func BenchmarkSecretConnection(b *testing.B) { b.StartTimer() for i := 0; i < b.N; i++ { - _, err := fooSecConn.Write([]byte(fooWriteText)) + idx := cmn.RandIntn(len(fooWriteBytes)) + _, err := fooSecConn.Write(fooWriteBytes[idx]) if err != nil { b.Fatalf("Failed to write to fooSecConn: %v", err) } @@ -414,3 +428,44 @@ func BenchmarkSecretConnection(b *testing.B) { } //barSecConn.Close() race condition } + +func BenchmarkReadSecretConnection(b *testing.B) { + b.StopTimer() + b.ReportAllocs() + fooSecConn, barSecConn := makeSecretConnPair(b) + randomMsgSizes := []int{ + dataMaxSize / 10, + dataMaxSize / 3, + dataMaxSize / 2, + dataMaxSize, + dataMaxSize * 3 / 2, + dataMaxSize * 2, + dataMaxSize * 7 / 2, + } + fooWriteBytes := make([][]byte, 0, len(randomMsgSizes)) + for _, size := range randomMsgSizes { + fooWriteBytes = append(fooWriteBytes, cmn.RandBytes(size)) + } + go func() { + for i := 0; i < b.N; i++ { + idx := cmn.RandIntn(len(fooWriteBytes)) + _, err := fooSecConn.Write(fooWriteBytes[idx]) + if err != nil { + b.Fatalf("Failed to write to fooSecConn: %v, %v,%v", err, i, b.N) + } + } + }() + + b.StartTimer() + for i := 0; i < b.N; i++ { + readBuffer := make([]byte, dataMaxSize) + _, err := barSecConn.Read(readBuffer) + + if err == io.EOF { + return + } else if err != nil { + b.Fatalf("Failed to read from barSecConn: %v", err) + } + } + b.StopTimer() +} From 5ed39fd0b37c7599dc13bda6be565d9c3dbb03f0 Mon Sep 17 00:00:00 2001 From: Anton Kaliaev Date: Mon, 22 Jul 2019 12:15:29 +0400 Subject: [PATCH 09/45] rpc: /broadcast_evidence (#3481) * implement broadcast_duplicate_vote endpoint * fix test_cover * address comments * address comments * Update abci/example/kvstore/persistent_kvstore.go Co-Authored-By: mossid * Update rpc/client/main_test.go Co-Authored-By: mossid * address comments in progress * reformat the code * make linter happy * make tests pass * replace BroadcastDuplicateVote with BroadcastEvidence * fix test * fix endpoint name * improve doc * fix TestBroadcastEvidenceDuplicateVote * Update rpc/core/evidence.go Co-Authored-By: Thane Thomson * add changelog entry * fix TestBroadcastEvidenceDuplicateVote --- CHANGELOG_PENDING.md | 3 +- abci/example/kvstore/kvstore.go | 1 + abci/example/kvstore/persistent_kvstore.go | 45 ++++++- rpc/client/amino.go | 12 ++ rpc/client/httpclient.go | 9 ++ rpc/client/interface.go | 52 ++++---- rpc/client/localclient.go | 4 + rpc/client/main_test.go | 7 +- rpc/client/mock/client.go | 5 + rpc/client/rpc_test.go | 144 +++++++++++++++++++++ rpc/core/evidence.go | 39 ++++++ rpc/core/routes.go | 5 +- rpc/core/types/responses.go | 5 + 13 files changed, 302 insertions(+), 29 deletions(-) create mode 100644 rpc/client/amino.go create mode 100644 rpc/core/evidence.go diff --git a/CHANGELOG_PENDING.md b/CHANGELOG_PENDING.md index 290d70818..84bd10ce9 100644 --- a/CHANGELOG_PENDING.md +++ b/CHANGELOG_PENDING.md @@ -14,13 +14,14 @@ program](https://hackerone.com/tendermint). - Apps - Go API -- [libs] \#3811 Remove `db` from libs in favor of `https://github.com/tendermint/tm-cmn` + - [libs] \#3811 Remove `db` from libs in favor of `https://github.com/tendermint/tm-cmn` ### FEATURES: ### IMPROVEMENTS: - [abci] \#3809 Recover from application panics in `server/socket_server.go` to allow socket cleanup (@ruseinov) +- [rpc] \#2252 Add `/broadcast_evidence` endpoint to submit double signing and other types of evidence - [rpc] \#3818 Make `max_body_bytes` and `max_header_bytes` configurable - [p2p] \#3664 p2p/conn: reuse buffer when write/read from secret connection diff --git a/abci/example/kvstore/kvstore.go b/abci/example/kvstore/kvstore.go index 71d0620e1..feb81b35c 100644 --- a/abci/example/kvstore/kvstore.go +++ b/abci/example/kvstore/kvstore.go @@ -115,6 +115,7 @@ func (app *KVStoreApplication) Commit() types.ResponseCommit { return types.ResponseCommit{Data: appHash} } +// Returns an associated value or nil if missing. func (app *KVStoreApplication) Query(reqQuery types.RequestQuery) (resQuery types.ResponseQuery) { if reqQuery.Prove { value := app.state.db.Get(prefixKey(reqQuery.Data)) diff --git a/abci/example/kvstore/persistent_kvstore.go b/abci/example/kvstore/persistent_kvstore.go index 68269dceb..308100b6a 100644 --- a/abci/example/kvstore/persistent_kvstore.go +++ b/abci/example/kvstore/persistent_kvstore.go @@ -9,7 +9,9 @@ import ( "github.com/tendermint/tendermint/abci/example/code" "github.com/tendermint/tendermint/abci/types" + "github.com/tendermint/tendermint/crypto/ed25519" "github.com/tendermint/tendermint/libs/log" + tmtypes "github.com/tendermint/tendermint/types" dbm "github.com/tendermint/tm-cmn/db" ) @@ -27,6 +29,8 @@ type PersistentKVStoreApplication struct { // validator set ValUpdates []types.ValidatorUpdate + valAddrToPubKeyMap map[string]types.PubKey + logger log.Logger } @@ -40,8 +44,9 @@ func NewPersistentKVStoreApplication(dbDir string) *PersistentKVStoreApplication state := loadState(db) return &PersistentKVStoreApplication{ - app: &KVStoreApplication{state: state}, - logger: log.NewNopLogger(), + app: &KVStoreApplication{state: state}, + valAddrToPubKeyMap: make(map[string]types.PubKey), + logger: log.NewNopLogger(), } } @@ -83,8 +88,20 @@ func (app *PersistentKVStoreApplication) Commit() types.ResponseCommit { return app.app.Commit() } -func (app *PersistentKVStoreApplication) Query(reqQuery types.RequestQuery) types.ResponseQuery { - return app.app.Query(reqQuery) +// When path=/val and data={validator address}, returns the validator update (types.ValidatorUpdate) varint encoded. +// For any other path, returns an associated value or nil if missing. +func (app *PersistentKVStoreApplication) Query(reqQuery types.RequestQuery) (resQuery types.ResponseQuery) { + switch reqQuery.Path { + case "/val": + key := []byte("val:" + string(reqQuery.Data)) + value := app.app.state.db.Get(key) + + resQuery.Key = reqQuery.Data + resQuery.Value = value + return + default: + return app.app.Query(reqQuery) + } } // Save the validators in the merkle tree @@ -102,6 +119,20 @@ func (app *PersistentKVStoreApplication) InitChain(req types.RequestInitChain) t func (app *PersistentKVStoreApplication) BeginBlock(req types.RequestBeginBlock) types.ResponseBeginBlock { // reset valset changes app.ValUpdates = make([]types.ValidatorUpdate, 0) + + for _, ev := range req.ByzantineValidators { + switch ev.Type { + case tmtypes.ABCIEvidenceTypeDuplicateVote: + // decrease voting power by 1 + if ev.TotalVotingPower == 0 { + continue + } + app.updateValidator(types.ValidatorUpdate{ + PubKey: app.valAddrToPubKeyMap[string(ev.Validator.Address)], + Power: ev.TotalVotingPower - 1, + }) + } + } return types.ResponseBeginBlock{} } @@ -174,6 +205,10 @@ func (app *PersistentKVStoreApplication) execValidatorTx(tx []byte) types.Respon // add, update, or remove a validator func (app *PersistentKVStoreApplication) updateValidator(v types.ValidatorUpdate) types.ResponseDeliverTx { key := []byte("val:" + string(v.PubKey.Data)) + + pubkey := ed25519.PubKeyEd25519{} + copy(pubkey[:], v.PubKey.Data) + if v.Power == 0 { // remove validator if !app.app.state.db.Has(key) { @@ -183,6 +218,7 @@ func (app *PersistentKVStoreApplication) updateValidator(v types.ValidatorUpdate Log: fmt.Sprintf("Cannot remove non-existent validator %s", pubStr)} } app.app.state.db.Delete(key) + delete(app.valAddrToPubKeyMap, string(pubkey.Address())) } else { // add or update validator value := bytes.NewBuffer(make([]byte, 0)) @@ -192,6 +228,7 @@ func (app *PersistentKVStoreApplication) updateValidator(v types.ValidatorUpdate Log: fmt.Sprintf("Error encoding validator: %v", err)} } app.app.state.db.Set(key, value.Bytes()) + app.valAddrToPubKeyMap[string(pubkey.Address())] = v.PubKey } // we only update the changes array if we successfully updated the tree diff --git a/rpc/client/amino.go b/rpc/client/amino.go new file mode 100644 index 000000000..ef1a00ec4 --- /dev/null +++ b/rpc/client/amino.go @@ -0,0 +1,12 @@ +package client + +import ( + amino "github.com/tendermint/go-amino" + "github.com/tendermint/tendermint/types" +) + +var cdc = amino.NewCodec() + +func init() { + types.RegisterEvidences(cdc) +} diff --git a/rpc/client/httpclient.go b/rpc/client/httpclient.go index 3fd13da37..85f065b61 100644 --- a/rpc/client/httpclient.go +++ b/rpc/client/httpclient.go @@ -333,6 +333,15 @@ func (c *baseRPCClient) Validators(height *int64) (*ctypes.ResultValidators, err return result, nil } +func (c *baseRPCClient) BroadcastEvidence(ev types.Evidence) (*ctypes.ResultBroadcastEvidence, error) { + result := new(ctypes.ResultBroadcastEvidence) + _, err := c.caller.Call("broadcast_evidence", map[string]interface{}{"evidence": ev}, result) + if err != nil { + return nil, errors.Wrap(err, "BroadcastEvidence") + } + return result, nil +} + //----------------------------------------------------------------------------- // WSEvents diff --git a/rpc/client/interface.go b/rpc/client/interface.go index 8f9ed9372..383e0b480 100644 --- a/rpc/client/interface.go +++ b/rpc/client/interface.go @@ -28,9 +28,24 @@ import ( "github.com/tendermint/tendermint/types" ) -// ABCIClient groups together the functionality that principally -// affects the ABCI app. In many cases this will be all we want, -// so we can accept an interface which is easier to mock +// Client wraps most important rpc calls a client would make if you want to +// listen for events, test if it also implements events.EventSwitch. +type Client interface { + cmn.Service + ABCIClient + EventsClient + HistoryClient + NetworkClient + SignClient + StatusClient + EvidenceClient +} + +// ABCIClient groups together the functionality that principally affects the +// ABCI app. +// +// In many cases this will be all we want, so we can accept an interface which +// is easier to mock. type ABCIClient interface { // Reading from abci app ABCIInfo() (*ctypes.ResultABCIInfo, error) @@ -44,8 +59,8 @@ type ABCIClient interface { BroadcastTxSync(tx types.Tx) (*ctypes.ResultBroadcastTx, error) } -// SignClient groups together the interfaces need to get valid -// signatures and prove anything about the chain +// SignClient groups together the functionality needed to get valid signatures +// and prove anything about the chain. type SignClient interface { Block(height *int64) (*ctypes.ResultBlock, error) BlockResults(height *int64) (*ctypes.ResultBlockResults, error) @@ -55,32 +70,19 @@ type SignClient interface { TxSearch(query string, prove bool, page, perPage int) (*ctypes.ResultTxSearch, error) } -// HistoryClient shows us data from genesis to now in large chunks. +// HistoryClient provides access to data from genesis to now in large chunks. type HistoryClient interface { Genesis() (*ctypes.ResultGenesis, error) BlockchainInfo(minHeight, maxHeight int64) (*ctypes.ResultBlockchainInfo, error) } +// StatusClient provides access to general chain info. type StatusClient interface { - // General chain info Status() (*ctypes.ResultStatus, error) } -// Client wraps most important rpc calls a client would make -// if you want to listen for events, test if it also -// implements events.EventSwitch -type Client interface { - cmn.Service - ABCIClient - EventsClient - HistoryClient - NetworkClient - SignClient - StatusClient -} - -// NetworkClient is general info about the network state. May not -// be needed usually. +// NetworkClient is general info about the network state. May not be needed +// usually. type NetworkClient interface { NetInfo() (*ctypes.ResultNetInfo, error) DumpConsensusState() (*ctypes.ResultDumpConsensusState, error) @@ -110,3 +112,9 @@ type MempoolClient interface { UnconfirmedTxs(limit int) (*ctypes.ResultUnconfirmedTxs, error) NumUnconfirmedTxs() (*ctypes.ResultUnconfirmedTxs, error) } + +// EvidenceClient is used for submitting an evidence of the malicious +// behaviour. +type EvidenceClient interface { + BroadcastEvidence(ev types.Evidence) (*ctypes.ResultBroadcastEvidence, error) +} diff --git a/rpc/client/localclient.go b/rpc/client/localclient.go index 161f44fdf..3c3a1dcc6 100644 --- a/rpc/client/localclient.go +++ b/rpc/client/localclient.go @@ -157,6 +157,10 @@ func (c *Local) TxSearch(query string, prove bool, page, perPage int) (*ctypes.R return core.TxSearch(c.ctx, query, prove, page, perPage) } +func (c *Local) BroadcastEvidence(ev types.Evidence) (*ctypes.ResultBroadcastEvidence, error) { + return core.BroadcastEvidence(c.ctx, ev) +} + func (c *Local) Subscribe(ctx context.Context, subscriber, query string, outCapacity ...int) (out <-chan ctypes.ResultEvent, err error) { q, err := tmquery.New(query) if err != nil { diff --git a/rpc/client/main_test.go b/rpc/client/main_test.go index 6ec7b7b0e..d600b32f8 100644 --- a/rpc/client/main_test.go +++ b/rpc/client/main_test.go @@ -1,6 +1,7 @@ package client_test import ( + "io/ioutil" "os" "testing" @@ -13,7 +14,11 @@ var node *nm.Node func TestMain(m *testing.M) { // start a tendermint node (and kvstore) in the background to test against - app := kvstore.NewKVStoreApplication() + dir, err := ioutil.TempDir("/tmp", "rpc-client-test") + if err != nil { + panic(err) + } + app := kvstore.NewPersistentKVStoreApplication(dir) node = rpctest.StartTendermint(app) code := m.Run() diff --git a/rpc/client/mock/client.go b/rpc/client/mock/client.go index c2e19b6d4..3ec40d6cc 100644 --- a/rpc/client/mock/client.go +++ b/rpc/client/mock/client.go @@ -36,6 +36,7 @@ type Client struct { client.HistoryClient client.StatusClient client.EventsClient + client.EvidenceClient cmn.Service } @@ -147,3 +148,7 @@ func (c Client) Commit(height *int64) (*ctypes.ResultCommit, error) { func (c Client) Validators(height *int64) (*ctypes.ResultValidators, error) { return core.Validators(&rpctypes.Context{}, height) } + +func (c Client) BroadcastEvidence(ev types.Evidence) (*ctypes.ResultBroadcastEvidence, error) { + return core.BroadcastEvidence(&rpctypes.Context{}, ev) +} diff --git a/rpc/client/rpc_test.go b/rpc/client/rpc_test.go index a1a48abc4..de5e18f11 100644 --- a/rpc/client/rpc_test.go +++ b/rpc/client/rpc_test.go @@ -1,7 +1,9 @@ package client_test import ( + "bytes" "fmt" + "math/rand" "net/http" "strings" "sync" @@ -12,7 +14,10 @@ import ( abci "github.com/tendermint/tendermint/abci/types" + "github.com/tendermint/tendermint/crypto/ed25519" + "github.com/tendermint/tendermint/crypto/tmhash" cmn "github.com/tendermint/tendermint/libs/common" + "github.com/tendermint/tendermint/privval" "github.com/tendermint/tendermint/rpc/client" ctypes "github.com/tendermint/tendermint/rpc/core/types" rpctest "github.com/tendermint/tendermint/rpc/test" @@ -446,6 +451,145 @@ func TestTxSearch(t *testing.T) { } } +func deepcpVote(vote *types.Vote) (res *types.Vote) { + res = &types.Vote{ + ValidatorAddress: make([]byte, len(vote.ValidatorAddress)), + ValidatorIndex: vote.ValidatorIndex, + Height: vote.Height, + Round: vote.Round, + Type: vote.Type, + BlockID: types.BlockID{ + Hash: make([]byte, len(vote.BlockID.Hash)), + PartsHeader: vote.BlockID.PartsHeader, + }, + Signature: make([]byte, len(vote.Signature)), + } + copy(res.ValidatorAddress, vote.ValidatorAddress) + copy(res.BlockID.Hash, vote.BlockID.Hash) + copy(res.Signature, vote.Signature) + return +} + +func newEvidence(t *testing.T, val *privval.FilePV, vote *types.Vote, vote2 *types.Vote, chainID string) types.DuplicateVoteEvidence { + var err error + vote2_ := deepcpVote(vote2) + vote2_.Signature, err = val.Key.PrivKey.Sign(vote2_.SignBytes(chainID)) + require.NoError(t, err) + + return types.DuplicateVoteEvidence{ + PubKey: val.Key.PubKey, + VoteA: vote, + VoteB: vote2_, + } +} + +func makeEvidences(t *testing.T, val *privval.FilePV, chainID string) (ev types.DuplicateVoteEvidence, fakes []types.DuplicateVoteEvidence) { + vote := &types.Vote{ + ValidatorAddress: val.Key.Address, + ValidatorIndex: 0, + Height: 1, + Round: 0, + Type: types.PrevoteType, + BlockID: types.BlockID{ + Hash: tmhash.Sum([]byte("blockhash")), + PartsHeader: types.PartSetHeader{ + Total: 1000, + Hash: tmhash.Sum([]byte("partset")), + }, + }, + } + + var err error + vote.Signature, err = val.Key.PrivKey.Sign(vote.SignBytes(chainID)) + require.NoError(t, err) + + vote2 := deepcpVote(vote) + vote2.BlockID.Hash = tmhash.Sum([]byte("blockhash2")) + + ev = newEvidence(t, val, vote, vote2, chainID) + + fakes = make([]types.DuplicateVoteEvidence, 42) + + // different address + vote2 = deepcpVote(vote) + for i := 0; i < 10; i++ { + rand.Read(vote2.ValidatorAddress) // nolint: gosec + fakes[i] = newEvidence(t, val, vote, vote2, chainID) + } + // different index + vote2 = deepcpVote(vote) + for i := 10; i < 20; i++ { + vote2.ValidatorIndex = rand.Int()%100 + 1 // nolint: gosec + fakes[i] = newEvidence(t, val, vote, vote2, chainID) + } + // different height + vote2 = deepcpVote(vote) + for i := 20; i < 30; i++ { + vote2.Height = rand.Int63()%1000 + 100 // nolint: gosec + fakes[i] = newEvidence(t, val, vote, vote2, chainID) + } + // different round + vote2 = deepcpVote(vote) + for i := 30; i < 40; i++ { + vote2.Round = rand.Int()%10 + 1 // nolint: gosec + fakes[i] = newEvidence(t, val, vote, vote2, chainID) + } + // different type + vote2 = deepcpVote(vote) + vote2.Type = types.PrecommitType + fakes[40] = newEvidence(t, val, vote, vote2, chainID) + // exactly same vote + vote2 = deepcpVote(vote) + fakes[41] = newEvidence(t, val, vote, vote2, chainID) + return +} + +func TestBroadcastEvidenceDuplicateVote(t *testing.T) { + config := rpctest.GetConfig() + chainID := config.ChainID() + pvKeyFile := config.PrivValidatorKeyFile() + pvKeyStateFile := config.PrivValidatorStateFile() + pv := privval.LoadOrGenFilePV(pvKeyFile, pvKeyStateFile) + + ev, fakes := makeEvidences(t, pv, chainID) + + t.Logf("evidence %v", ev) + + for i, c := range GetClients() { + t.Logf("client %d", i) + + result, err := c.BroadcastEvidence(&types.DuplicateVoteEvidence{PubKey: ev.PubKey, VoteA: ev.VoteA, VoteB: ev.VoteB}) + require.Nil(t, err) + require.Equal(t, ev.Hash(), result.Hash, "Invalid response, result %+v", result) + + status, err := c.Status() + require.NoError(t, err) + client.WaitForHeight(c, status.SyncInfo.LatestBlockHeight+2, nil) + + ed25519pub := ev.PubKey.(ed25519.PubKeyEd25519) + rawpub := ed25519pub[:] + result2, err := c.ABCIQuery("/val", rawpub) + require.Nil(t, err, "Error querying evidence, err %v", err) + qres := result2.Response + require.True(t, qres.IsOK(), "Response not OK") + + var v abci.ValidatorUpdate + err = abci.ReadMessage(bytes.NewReader(qres.Value), &v) + require.NoError(t, err, "Error reading query result, value %v", qres.Value) + + require.EqualValues(t, rawpub, v.PubKey.Data, "Stored PubKey not equal with expected, value %v", string(qres.Value)) + require.Equal(t, int64(9), v.Power, "Stored Power not equal with expected, value %v", string(qres.Value)) + + for _, fake := range fakes { + _, err := c.BroadcastEvidence(&types.DuplicateVoteEvidence{ + PubKey: fake.PubKey, + VoteA: fake.VoteA, + VoteB: fake.VoteB}) + require.Error(t, err, "Broadcasting fake evidence succeed: %s", fake.String()) + } + } +} + func TestBatchedJSONRPCCalls(t *testing.T) { c := getHTTPClient() testBatchedJSONRPCCalls(t, c) diff --git a/rpc/core/evidence.go b/rpc/core/evidence.go new file mode 100644 index 000000000..b2dfd097f --- /dev/null +++ b/rpc/core/evidence.go @@ -0,0 +1,39 @@ +package core + +import ( + ctypes "github.com/tendermint/tendermint/rpc/core/types" + rpctypes "github.com/tendermint/tendermint/rpc/lib/types" + "github.com/tendermint/tendermint/types" +) + +// Broadcast evidence of the misbehavior. +// +// ```shell +// curl 'localhost:26657/broadcast_evidence?evidence={amino-encoded DuplicateVoteEvidence}' +// ``` +// +// ```go +// client := client.NewHTTP("tcp://0.0.0.0:26657", "/websocket") +// err := client.Start() +// if err != nil { +// // handle error +// } +// defer client.Stop() +// res, err := client.BroadcastEvidence(&types.DuplicateVoteEvidence{PubKey: ev.PubKey, VoteA: ev.VoteA, VoteB: ev.VoteB}) +// ``` +// +// > The above command returns JSON structured like this: +// +// ```json +// ``` +// +// | Parameter | Type | Default | Required | Description | +// |-----------+----------------+---------+----------+-----------------------------| +// | evidence | types.Evidence | nil | true | Amino-encoded JSON evidence | +func BroadcastEvidence(ctx *rpctypes.Context, ev types.Evidence) (*ctypes.ResultBroadcastEvidence, error) { + err := evidencePool.AddEvidence(ev) + if err != nil { + return nil, err + } + return &ctypes.ResultBroadcastEvidence{Hash: ev.Hash()}, nil +} diff --git a/rpc/core/routes.go b/rpc/core/routes.go index 736ded607..df7cef905 100644 --- a/rpc/core/routes.go +++ b/rpc/core/routes.go @@ -30,7 +30,7 @@ var Routes = map[string]*rpc.RPCFunc{ "unconfirmed_txs": rpc.NewRPCFunc(UnconfirmedTxs, "limit"), "num_unconfirmed_txs": rpc.NewRPCFunc(NumUnconfirmedTxs, ""), - // broadcast API + // tx broadcast API "broadcast_tx_commit": rpc.NewRPCFunc(BroadcastTxCommit, "tx"), "broadcast_tx_sync": rpc.NewRPCFunc(BroadcastTxSync, "tx"), "broadcast_tx_async": rpc.NewRPCFunc(BroadcastTxAsync, "tx"), @@ -38,6 +38,9 @@ var Routes = map[string]*rpc.RPCFunc{ // abci API "abci_query": rpc.NewRPCFunc(ABCIQuery, "path,data,height,prove"), "abci_info": rpc.NewRPCFunc(ABCIInfo, ""), + + // evidence API + "broadcast_evidence": rpc.NewRPCFunc(BroadcastEvidence, "evidence"), } func AddUnsafeRoutes() { diff --git a/rpc/core/types/responses.go b/rpc/core/types/responses.go index f1ae16a39..f8a9476f3 100644 --- a/rpc/core/types/responses.go +++ b/rpc/core/types/responses.go @@ -194,6 +194,11 @@ type ResultABCIQuery struct { Response abci.ResponseQuery `json:"response"` } +// Result of broadcasting evidence +type ResultBroadcastEvidence struct { + Hash []byte `json:"hash"` +} + // empty results type ( ResultUnsafeFlushMempool struct{} From df6df61ea93152d8abc82f0aee82c22ca624f8f8 Mon Sep 17 00:00:00 2001 From: Jun Kimura Date: Tue, 23 Jul 2019 00:17:10 +0900 Subject: [PATCH 10/45] mempool: make max_msg_bytes configurable (#3826) * mempool: make max_msg_bytes configurable * apply suggestions from code review * update changelog pending * apply suggestions from code review again --- CHANGELOG_PENDING.md | 1 + config/config.go | 5 +++++ config/toml.go | 3 +++ docs/tendermint-core/configuration.md | 3 +++ mempool/clist_mempool.go | 7 ++++--- mempool/clist_mempool_test.go | 5 ++++- mempool/errors.go | 13 ++++++++++--- mempool/reactor.go | 17 +++++++++++------ 8 files changed, 41 insertions(+), 13 deletions(-) diff --git a/CHANGELOG_PENDING.md b/CHANGELOG_PENDING.md index 84bd10ce9..721a376c7 100644 --- a/CHANGELOG_PENDING.md +++ b/CHANGELOG_PENDING.md @@ -24,5 +24,6 @@ program](https://hackerone.com/tendermint). - [rpc] \#2252 Add `/broadcast_evidence` endpoint to submit double signing and other types of evidence - [rpc] \#3818 Make `max_body_bytes` and `max_header_bytes` configurable - [p2p] \#3664 p2p/conn: reuse buffer when write/read from secret connection +- [mempool] \#3826 Make `max_msg_bytes` configurable ### BUG FIXES: diff --git a/config/config.go b/config/config.go index 6a3cb8ce8..73c704681 100644 --- a/config/config.go +++ b/config/config.go @@ -631,6 +631,7 @@ type MempoolConfig struct { Size int `mapstructure:"size"` MaxTxsBytes int64 `mapstructure:"max_txs_bytes"` CacheSize int `mapstructure:"cache_size"` + MaxMsgBytes int `mapstructure:"max_msg_bytes"` } // DefaultMempoolConfig returns a default configuration for the Tendermint mempool @@ -644,6 +645,7 @@ func DefaultMempoolConfig() *MempoolConfig { Size: 5000, MaxTxsBytes: 1024 * 1024 * 1024, // 1GB CacheSize: 10000, + MaxMsgBytes: 1024 * 1024, // 1MB } } @@ -676,6 +678,9 @@ func (cfg *MempoolConfig) ValidateBasic() error { if cfg.CacheSize < 0 { return errors.New("cache_size can't be negative") } + if cfg.MaxMsgBytes < 0 { + return errors.New("max_msg_bytes can't be negative") + } return nil } diff --git a/config/toml.go b/config/toml.go index 1cafc9c2d..58da57975 100644 --- a/config/toml.go +++ b/config/toml.go @@ -294,6 +294,9 @@ max_txs_bytes = {{ .Mempool.MaxTxsBytes }} # Size of the cache (used to filter transactions we saw earlier) in transactions cache_size = {{ .Mempool.CacheSize }} +# Limit the size of TxMessage +max_msg_bytes = {{ .Mempool.MaxMsgBytes }} + ##### consensus configuration options ##### [consensus] diff --git a/docs/tendermint-core/configuration.md b/docs/tendermint-core/configuration.md index 026a75374..ff502a222 100644 --- a/docs/tendermint-core/configuration.md +++ b/docs/tendermint-core/configuration.md @@ -240,6 +240,9 @@ max_txs_bytes = 1073741824 # Size of the cache (used to filter transactions we saw earlier) in transactions cache_size = 10000 +# Limit the size of TxMessage +max_msg_bytes = 1048576 + ##### consensus configuration options ##### [consensus] diff --git a/mempool/clist_mempool.go b/mempool/clist_mempool.go index 4042e9b4b..81123cb63 100644 --- a/mempool/clist_mempool.go +++ b/mempool/clist_mempool.go @@ -220,9 +220,10 @@ func (mem *CListMempool) CheckTxWithInfo(tx types.Tx, cb func(*abci.Response), t var ( memSize = mem.Size() txsBytes = mem.TxsBytes() + txSize = len(tx) ) if memSize >= mem.config.Size || - int64(len(tx))+txsBytes > mem.config.MaxTxsBytes { + int64(txSize)+txsBytes > mem.config.MaxTxsBytes { return ErrMempoolIsFull{ memSize, mem.config.Size, txsBytes, mem.config.MaxTxsBytes} @@ -231,8 +232,8 @@ func (mem *CListMempool) CheckTxWithInfo(tx types.Tx, cb func(*abci.Response), t // The size of the corresponding amino-encoded TxMessage // can't be larger than the maxMsgSize, otherwise we can't // relay it to peers. - if len(tx) > maxTxSize { - return ErrTxTooLarge + if max := calcMaxTxSize(mem.config.MaxMsgBytes); txSize > max { + return ErrTxTooLarge{max, txSize} } if mem.preCheck != nil { diff --git a/mempool/clist_mempool_test.go b/mempool/clist_mempool_test.go index 90d0ed1ae..e2ebca925 100644 --- a/mempool/clist_mempool_test.go +++ b/mempool/clist_mempool_test.go @@ -426,6 +426,9 @@ func TestMempoolMaxMsgSize(t *testing.T) { mempl, cleanup := newMempoolWithApp(cc) defer cleanup() + maxMsgSize := mempl.config.MaxMsgBytes + maxTxSize := calcMaxTxSize(mempl.config.MaxMsgBytes) + testCases := []struct { len int err bool @@ -462,7 +465,7 @@ func TestMempoolMaxMsgSize(t *testing.T) { require.NoError(t, err, caseString) } else { require.True(t, len(encoded) > maxMsgSize, caseString) - require.Equal(t, err, ErrTxTooLarge, caseString) + require.Equal(t, err, ErrTxTooLarge{maxTxSize, testCase.len}, caseString) } } diff --git a/mempool/errors.go b/mempool/errors.go index ac2a9b3c2..c5140bdf0 100644 --- a/mempool/errors.go +++ b/mempool/errors.go @@ -9,11 +9,18 @@ import ( var ( // ErrTxInCache is returned to the client if we saw tx earlier ErrTxInCache = errors.New("Tx already exists in cache") - - // ErrTxTooLarge means the tx is too big to be sent in a message to other peers - ErrTxTooLarge = fmt.Errorf("Tx too large. Max size is %d", maxTxSize) ) +// ErrTxTooLarge means the tx is too big to be sent in a message to other peers +type ErrTxTooLarge struct { + max int + actual int +} + +func (e ErrTxTooLarge) Error() string { + return fmt.Sprintf("Tx too large. Max size is %d, but got %d", e.max, e.actual) +} + // ErrMempoolIsFull means Tendermint & an application can't handle that much load type ErrMempoolIsFull struct { numTxs int diff --git a/mempool/reactor.go b/mempool/reactor.go index 65ccd7dfd..0ca273401 100644 --- a/mempool/reactor.go +++ b/mempool/reactor.go @@ -19,8 +19,7 @@ import ( const ( MempoolChannel = byte(0x30) - maxMsgSize = 1048576 // 1MB TODO make it configurable - maxTxSize = maxMsgSize - 8 // account for amino overhead of TxMessage + aminoOverheadForTxMessage = 8 peerCatchupSleepIntervalMS = 100 // If peer is behind, sleep this amount @@ -156,7 +155,7 @@ func (memR *Reactor) RemovePeer(peer p2p.Peer, reason interface{}) { // Receive implements Reactor. // It adds any received transactions to the mempool. func (memR *Reactor) Receive(chID byte, src p2p.Peer, msgBytes []byte) { - msg, err := decodeMsg(msgBytes) + msg, err := memR.decodeMsg(msgBytes) if err != nil { memR.Logger.Error("Error decoding message", "src", src, "chId", chID, "msg", msg, "err", err, "bytes", msgBytes) memR.Switch.StopPeerForError(src, err) @@ -263,9 +262,9 @@ func RegisterMempoolMessages(cdc *amino.Codec) { cdc.RegisterConcrete(&TxMessage{}, "tendermint/mempool/TxMessage", nil) } -func decodeMsg(bz []byte) (msg MempoolMessage, err error) { - if len(bz) > maxMsgSize { - return msg, fmt.Errorf("Msg exceeds max size (%d > %d)", len(bz), maxMsgSize) +func (memR *Reactor) decodeMsg(bz []byte) (msg MempoolMessage, err error) { + if l := len(bz); l > memR.config.MaxMsgBytes { + return msg, ErrTxTooLarge{memR.config.MaxMsgBytes, l} } err = cdc.UnmarshalBinaryBare(bz, &msg) return @@ -282,3 +281,9 @@ type TxMessage struct { func (m *TxMessage) String() string { return fmt.Sprintf("[TxMessage %v]", m.Tx) } + +// calcMaxTxSize returns the max size of Tx +// account for amino overhead of TxMessage +func calcMaxTxSize(maxMsgSize int) int { + return maxMsgSize - aminoOverheadForTxMessage +} From e89991c445c94ec10ed05c74500a10e04713c162 Mon Sep 17 00:00:00 2001 From: Anton Kaliaev Date: Tue, 23 Jul 2019 12:25:59 +0400 Subject: [PATCH 11/45] =?UTF-8?q?rpc:=20return=20err=20if=20page=20is=20in?= =?UTF-8?q?correct=20(less=20than=200=20or=20greater=20than=20tot=E2=80=A6?= =?UTF-8?q?=20(#3825)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * rpc: return err if page is incorrect (less than 0 or greater than total pages) Fixes #3813 * fix rpc_test --- CHANGELOG_PENDING.md | 2 ++ rpc/core/pipe.go | 20 +++++++++++++------- rpc/core/pipe_test.go | 42 ++++++++++++++++++++++++------------------ rpc/core/tx.go | 5 ++++- 4 files changed, 43 insertions(+), 26 deletions(-) diff --git a/CHANGELOG_PENDING.md b/CHANGELOG_PENDING.md index 721a376c7..ad8e60d35 100644 --- a/CHANGELOG_PENDING.md +++ b/CHANGELOG_PENDING.md @@ -27,3 +27,5 @@ program](https://hackerone.com/tendermint). - [mempool] \#3826 Make `max_msg_bytes` configurable ### BUG FIXES: + +- [rpc] \#3813 Return err if page is incorrect (less than 0 or greater than total pages) diff --git a/rpc/core/pipe.go b/rpc/core/pipe.go index a0fc7b9bb..9581b89d7 100644 --- a/rpc/core/pipe.go +++ b/rpc/core/pipe.go @@ -1,6 +1,7 @@ package core import ( + "fmt" "time" cfg "github.com/tendermint/tendermint/config" @@ -145,19 +146,24 @@ func SetConfig(c cfg.RPCConfig) { config = c } -func validatePage(page, perPage, totalCount int) int { +func validatePage(page, perPage, totalCount int) (int, error) { if perPage < 1 { - return 1 + panic(fmt.Sprintf("zero or negative perPage: %d", perPage)) + } + + if page == 0 { + return 1, nil // default } pages := ((totalCount - 1) / perPage) + 1 - if page < 1 { - page = 1 - } else if page > pages { - page = pages + if pages == 0 { + pages = 1 // one page (even if it's empty) + } + if page < 0 || page > pages { + return 1, fmt.Errorf("page should be within [0, %d] range, given %d", pages, page) } - return page + return page, nil } func validatePerPage(perPage int) int { diff --git a/rpc/core/pipe_test.go b/rpc/core/pipe_test.go index 19ed11fcc..93aff3e58 100644 --- a/rpc/core/pipe_test.go +++ b/rpc/core/pipe_test.go @@ -14,33 +14,39 @@ func TestPaginationPage(t *testing.T) { perPage int page int newPage int + expErr bool }{ - {0, 0, 1, 1}, + {0, 10, 1, 1, false}, - {0, 10, 0, 1}, - {0, 10, 1, 1}, - {0, 10, 2, 1}, + {0, 10, 0, 1, false}, + {0, 10, 1, 1, false}, + {0, 10, 2, 0, true}, - {5, 10, -1, 1}, - {5, 10, 0, 1}, - {5, 10, 1, 1}, - {5, 10, 2, 1}, - {5, 10, 2, 1}, + {5, 10, -1, 0, true}, + {5, 10, 0, 1, false}, + {5, 10, 1, 1, false}, + {5, 10, 2, 0, true}, + {5, 10, 2, 0, true}, - {5, 5, 1, 1}, - {5, 5, 2, 1}, - {5, 5, 3, 1}, + {5, 5, 1, 1, false}, + {5, 5, 2, 0, true}, + {5, 5, 3, 0, true}, - {5, 3, 2, 2}, - {5, 3, 3, 2}, + {5, 3, 2, 2, false}, + {5, 3, 3, 0, true}, - {5, 2, 2, 2}, - {5, 2, 3, 3}, - {5, 2, 4, 3}, + {5, 2, 2, 2, false}, + {5, 2, 3, 3, false}, + {5, 2, 4, 0, true}, } for _, c := range cases { - p := validatePage(c.page, c.perPage, c.totalCount) + p, err := validatePage(c.page, c.perPage, c.totalCount) + if c.expErr { + assert.Error(t, err) + continue + } + assert.Equal(t, c.newPage, p, fmt.Sprintf("%v", c)) } diff --git a/rpc/core/tx.go b/rpc/core/tx.go index 575553f85..dba457c30 100644 --- a/rpc/core/tx.go +++ b/rpc/core/tx.go @@ -202,7 +202,10 @@ func TxSearch(ctx *rpctypes.Context, query string, prove bool, page, perPage int totalCount := len(results) perPage = validatePerPage(perPage) - page = validatePage(page, perPage, totalCount) + page, err = validatePage(page, perPage, totalCount) + if err != nil { + return nil, err + } skipCount := validateSkipCount(page, perPage) apiResults := make([]*ctypes.ResultTx, cmn.MinInt(perPage, totalCount-skipCount)) From abc30821f4f49014ed48cce5b86ee890211aeb02 Mon Sep 17 00:00:00 2001 From: Anca Zamfir Date: Tue, 23 Jul 2019 10:58:52 +0200 Subject: [PATCH 12/45] blockchain: Reorg reactor (#3561) * go routines in blockchain reactor * Added reference to the go routine diagram * Initial commit * cleanup * Undo testing_logger change, committed by mistake * Fix the test loggers * pulled some fsm code into pool.go * added pool tests * changes to the design added block requests under peer moved the request trigger in the reactor poolRoutine, triggered now by a ticker in general moved everything required for making block requests smarter in the poolRoutine added a simple map of heights to keep track of what will need to be requested next added a few more tests * send errors to FSM in a different channel than blocks send errors (RemovePeer) from switch on a different channel than the one receiving blocks renamed channels added more pool tests * more pool tests * lint errors * more tests * more tests * switch fast sync to new implementation * fixed data race in tests * cleanup * finished fsm tests * address golangci comments :) * address golangci comments :) * Added timeout on next block needed to advance * updating docs and cleanup * fix issue in test from previous cleanup * cleanup * Added termination scenarios, tests and more cleanup * small fixes to adr, comments and cleanup * Fix bug in sendRequest() If we tried to send a request to a peer not present in the switch, a missing continue statement caused the request to be blackholed in a peer that was removed and never retried. While this bug was manifesting, the reactor kept asking for other blocks that would be stored and never consumed. Added the number of unconsumed blocks in the math for requesting blocks ahead of current processing height so eventually there will be no more blocks requested until the already received ones are consumed. * remove bpPeer's didTimeout field * Use distinct err codes for peer timeout and FSM timeouts * Don't allow peers to update with lower height * review comments from Ethan and Zarko * some cleanup, renaming, comments * Move block execution in separate goroutine * Remove pool's numPending * review comments * fix lint, remove old blockchain reactor and duplicates in fsm tests * small reorg around peer after review comments * add the reactor spec * verify block only once * review comments * change to int for max number of pending requests * cleanup and godoc * Add configuration flag fast sync version * golangci fixes * fix config template * move both reactor versions under blockchain * cleanup, golint, renaming stuff * updated documentation, fixed more golint warnings * integrate with behavior package * sync with master * gofmt * add changelog_pending entry * move to improvments * suggestion to changelog entry --- CHANGELOG_PENDING.md | 1 + blockchain/{ => v0}/pool.go | 17 +- blockchain/{ => v0}/pool_test.go | 2 +- blockchain/{ => v0}/reactor.go | 12 +- blockchain/{ => v0}/reactor_test.go | 6 +- blockchain/{ => v0}/wire.go | 2 +- blockchain/v1/peer.go | 209 ++++ blockchain/v1/peer_test.go | 278 ++++++ blockchain/v1/pool.go | 369 +++++++ blockchain/v1/pool_test.go | 650 ++++++++++++ blockchain/v1/reactor.go | 620 ++++++++++++ blockchain/v1/reactor_fsm.go | 450 +++++++++ blockchain/v1/reactor_fsm_test.go | 938 ++++++++++++++++++ blockchain/v1/reactor_test.go | 337 +++++++ blockchain/v1/wire.go | 13 + cmd/tendermint/commands/run_node.go | 2 +- config/config.go | 44 +- config/toml.go | 10 +- consensus/common_test.go | 4 +- consensus/reactor_test.go | 4 +- consensus/replay_file.go | 4 +- consensus/wal_generator.go | 5 +- .../bcv1/img/bc-reactor-new-datastructs.png | Bin 0 -> 44461 bytes .../bcv1/img/bc-reactor-new-fsm.png | Bin 0 -> 42091 bytes .../bcv1/img/bc-reactor-new-goroutines.png | Bin 0 -> 140946 bytes docs/spec/reactors/block_sync/bcv1/impl-v1.md | 237 +++++ .../block_sync/img/bc-reactor-routines.png | Bin 0 -> 271695 bytes docs/spec/reactors/block_sync/impl.md | 13 +- docs/tendermint-core/configuration.md | 8 + go.sum | 5 - node/node.go | 60 +- {blockchain => store}/store.go | 3 +- {blockchain => store}/store_test.go | 14 +- store/wire.go | 12 + 34 files changed, 4275 insertions(+), 54 deletions(-) rename blockchain/{ => v0}/pool.go (96%) rename blockchain/{ => v0}/pool_test.go (99%) rename blockchain/{ => v0}/reactor.go (97%) rename blockchain/{ => v0}/reactor_test.go (98%) rename blockchain/{ => v0}/wire.go (91%) create mode 100644 blockchain/v1/peer.go create mode 100644 blockchain/v1/peer_test.go create mode 100644 blockchain/v1/pool.go create mode 100644 blockchain/v1/pool_test.go create mode 100644 blockchain/v1/reactor.go create mode 100644 blockchain/v1/reactor_fsm.go create mode 100644 blockchain/v1/reactor_fsm_test.go create mode 100644 blockchain/v1/reactor_test.go create mode 100644 blockchain/v1/wire.go create mode 100644 docs/spec/reactors/block_sync/bcv1/img/bc-reactor-new-datastructs.png create mode 100644 docs/spec/reactors/block_sync/bcv1/img/bc-reactor-new-fsm.png create mode 100644 docs/spec/reactors/block_sync/bcv1/img/bc-reactor-new-goroutines.png create mode 100644 docs/spec/reactors/block_sync/bcv1/impl-v1.md create mode 100644 docs/spec/reactors/block_sync/img/bc-reactor-routines.png rename {blockchain => store}/store.go (98%) rename {blockchain => store}/store_test.go (97%) create mode 100644 store/wire.go diff --git a/CHANGELOG_PENDING.md b/CHANGELOG_PENDING.md index ad8e60d35..c57b6b82e 100644 --- a/CHANGELOG_PENDING.md +++ b/CHANGELOG_PENDING.md @@ -25,6 +25,7 @@ program](https://hackerone.com/tendermint). - [rpc] \#3818 Make `max_body_bytes` and `max_header_bytes` configurable - [p2p] \#3664 p2p/conn: reuse buffer when write/read from secret connection - [mempool] \#3826 Make `max_msg_bytes` configurable +- [blockchain] \#3561 Add early version of the new blockchain reactor, which is supposed to be more modular and testable compared to the old version. To try it, you'll have to change `version` in the config file, [here](https://github.com/tendermint/tendermint/blob/master/config/toml.go#L303) NOTE: It's not ready for a production yet. For further information, see [ADR-40](https://github.com/tendermint/tendermint/blob/master/docs/architecture/adr-040-blockchain-reactor-refactor.md) & [ADR-43](https://github.com/tendermint/tendermint/blob/master/docs/architecture/adr-043-blockchain-riri-org.md) ### BUG FIXES: diff --git a/blockchain/pool.go b/blockchain/v0/pool.go similarity index 96% rename from blockchain/pool.go rename to blockchain/v0/pool.go index c842c0d13..bd570f216 100644 --- a/blockchain/pool.go +++ b/blockchain/v0/pool.go @@ -1,4 +1,4 @@ -package blockchain +package v0 import ( "errors" @@ -59,6 +59,7 @@ var peerTimeout = 15 * time.Second // not const so we can override with tests are not at peer limits, we can probably switch to consensus reactor */ +// BlockPool keeps track of the fast sync peers, block requests and block responses. type BlockPool struct { cmn.BaseService startTime time.Time @@ -184,6 +185,7 @@ func (pool *BlockPool) IsCaughtUp() bool { return isCaughtUp } +// PeekTwoBlocks returns blocks at pool.height and pool.height+1. // We need to see the second block's Commit to validate the first block. // So we peek two blocks at a time. // The caller will verify the commit. @@ -200,7 +202,7 @@ func (pool *BlockPool) PeekTwoBlocks() (first *types.Block, second *types.Block) return } -// Pop the first block at pool.height +// PopRequest pops the first block at pool.height. // It must have been validated by 'second'.Commit from PeekTwoBlocks(). func (pool *BlockPool) PopRequest() { pool.mtx.Lock() @@ -220,7 +222,7 @@ func (pool *BlockPool) PopRequest() { } } -// Invalidates the block at pool.height, +// RedoRequest invalidates the block at pool.height, // Remove the peer and redo request from others. // Returns the ID of the removed peer. func (pool *BlockPool) RedoRequest(height int64) p2p.ID { @@ -236,6 +238,7 @@ func (pool *BlockPool) RedoRequest(height int64) p2p.ID { return peerID } +// AddBlock validates that the block comes from the peer it was expected from and calls the requester to store it. // TODO: ensure that blocks come in order for each peer. func (pool *BlockPool) AddBlock(peerID p2p.ID, block *types.Block, blockSize int) { pool.mtx.Lock() @@ -565,9 +568,9 @@ func (bpr *bpRequester) reset() { // Tells bpRequester to pick another peer and try again. // NOTE: Nonblocking, and does nothing if another redo // was already requested. -func (bpr *bpRequester) redo(peerId p2p.ID) { +func (bpr *bpRequester) redo(peerID p2p.ID) { select { - case bpr.redoCh <- peerId: + case bpr.redoCh <- peerID: default: } } @@ -622,8 +625,8 @@ OUTER_LOOP: } } -//------------------------------------- - +// BlockRequest stores a block request identified by the block Height and the PeerID responsible for +// delivering the block type BlockRequest struct { Height int64 PeerID p2p.ID diff --git a/blockchain/pool_test.go b/blockchain/v0/pool_test.go similarity index 99% rename from blockchain/pool_test.go rename to blockchain/v0/pool_test.go index 01d7dba20..d741d59df 100644 --- a/blockchain/pool_test.go +++ b/blockchain/v0/pool_test.go @@ -1,4 +1,4 @@ -package blockchain +package v0 import ( "fmt" diff --git a/blockchain/reactor.go b/blockchain/v0/reactor.go similarity index 97% rename from blockchain/reactor.go rename to blockchain/v0/reactor.go index 139393778..5d38471dc 100644 --- a/blockchain/reactor.go +++ b/blockchain/v0/reactor.go @@ -1,4 +1,4 @@ -package blockchain +package v0 import ( "errors" @@ -11,6 +11,7 @@ import ( "github.com/tendermint/tendermint/libs/log" "github.com/tendermint/tendermint/p2p" sm "github.com/tendermint/tendermint/state" + "github.com/tendermint/tendermint/store" "github.com/tendermint/tendermint/types" ) @@ -60,7 +61,7 @@ type BlockchainReactor struct { initialState sm.State blockExec *sm.BlockExecutor - store *BlockStore + store *store.BlockStore pool *BlockPool fastSync bool @@ -69,7 +70,7 @@ type BlockchainReactor struct { } // NewBlockchainReactor returns new reactor instance. -func NewBlockchainReactor(state sm.State, blockExec *sm.BlockExecutor, store *BlockStore, +func NewBlockchainReactor(state sm.State, blockExec *sm.BlockExecutor, store *store.BlockStore, fastSync bool) *BlockchainReactor { if state.LastBlockHeight != store.Height() { @@ -378,6 +379,7 @@ type BlockchainMessage interface { ValidateBasic() error } +// RegisterBlockchainMessages registers the fast sync messages for amino encoding. func RegisterBlockchainMessages(cdc *amino.Codec) { cdc.RegisterInterface((*BlockchainMessage)(nil), nil) cdc.RegisterConcrete(&bcBlockRequestMessage{}, "tendermint/blockchain/BlockRequest", nil) @@ -425,8 +427,8 @@ func (m *bcNoBlockResponseMessage) ValidateBasic() error { return nil } -func (brm *bcNoBlockResponseMessage) String() string { - return fmt.Sprintf("[bcNoBlockResponseMessage %d]", brm.Height) +func (m *bcNoBlockResponseMessage) String() string { + return fmt.Sprintf("[bcNoBlockResponseMessage %d]", m.Height) } //------------------------------------- diff --git a/blockchain/reactor_test.go b/blockchain/v0/reactor_test.go similarity index 98% rename from blockchain/reactor_test.go rename to blockchain/v0/reactor_test.go index 4f2588055..29de5b193 100644 --- a/blockchain/reactor_test.go +++ b/blockchain/v0/reactor_test.go @@ -1,4 +1,4 @@ -package blockchain +package v0 import ( "os" @@ -6,6 +6,8 @@ import ( "testing" "time" + "github.com/tendermint/tendermint/store" + "github.com/stretchr/testify/assert" abci "github.com/tendermint/tendermint/abci/types" @@ -81,7 +83,7 @@ func newBlockchainReactor(logger log.Logger, genDoc *types.GenesisDoc, privVals blockDB := dbm.NewMemDB() stateDB := dbm.NewMemDB() - blockStore := NewBlockStore(blockDB) + blockStore := store.NewBlockStore(blockDB) state, err := sm.LoadStateFromDBOrGenesisDoc(stateDB, genDoc) if err != nil { diff --git a/blockchain/wire.go b/blockchain/v0/wire.go similarity index 91% rename from blockchain/wire.go rename to blockchain/v0/wire.go index 487fbe2bc..4494f41aa 100644 --- a/blockchain/wire.go +++ b/blockchain/v0/wire.go @@ -1,4 +1,4 @@ -package blockchain +package v0 import ( amino "github.com/tendermint/go-amino" diff --git a/blockchain/v1/peer.go b/blockchain/v1/peer.go new file mode 100644 index 000000000..02b1b4fc1 --- /dev/null +++ b/blockchain/v1/peer.go @@ -0,0 +1,209 @@ +package v1 + +import ( + "fmt" + "math" + "time" + + flow "github.com/tendermint/tendermint/libs/flowrate" + "github.com/tendermint/tendermint/libs/log" + "github.com/tendermint/tendermint/p2p" + "github.com/tendermint/tendermint/types" +) + +//-------- +// Peer + +// BpPeerParams stores the peer parameters that are used when creating a peer. +type BpPeerParams struct { + timeout time.Duration + minRecvRate int64 + sampleRate time.Duration + windowSize time.Duration +} + +// BpPeer is the datastructure associated with a fast sync peer. +type BpPeer struct { + logger log.Logger + ID p2p.ID + + Height int64 // the peer reported height + NumPendingBlockRequests int // number of requests still waiting for block responses + blocks map[int64]*types.Block // blocks received or expected to be received from this peer + blockResponseTimer *time.Timer + recvMonitor *flow.Monitor + params *BpPeerParams // parameters for timer and monitor + + onErr func(err error, peerID p2p.ID) // function to call on error +} + +// NewBpPeer creates a new peer. +func NewBpPeer( + peerID p2p.ID, height int64, onErr func(err error, peerID p2p.ID), params *BpPeerParams) *BpPeer { + + if params == nil { + params = BpPeerDefaultParams() + } + return &BpPeer{ + ID: peerID, + Height: height, + blocks: make(map[int64]*types.Block, maxRequestsPerPeer), + logger: log.NewNopLogger(), + onErr: onErr, + params: params, + } +} + +// String returns a string representation of a peer. +func (peer *BpPeer) String() string { + return fmt.Sprintf("peer: %v height: %v pending: %v", peer.ID, peer.Height, peer.NumPendingBlockRequests) +} + +// SetLogger sets the logger of the peer. +func (peer *BpPeer) SetLogger(l log.Logger) { + peer.logger = l +} + +// Cleanup performs cleanup of the peer, removes blocks, requests, stops timer and monitor. +func (peer *BpPeer) Cleanup() { + if peer.blockResponseTimer != nil { + peer.blockResponseTimer.Stop() + } + if peer.NumPendingBlockRequests != 0 { + peer.logger.Info("peer with pending requests is being cleaned", "peer", peer.ID) + } + if len(peer.blocks)-peer.NumPendingBlockRequests != 0 { + peer.logger.Info("peer with pending blocks is being cleaned", "peer", peer.ID) + } + for h := range peer.blocks { + delete(peer.blocks, h) + } + peer.NumPendingBlockRequests = 0 + peer.recvMonitor = nil +} + +// BlockAtHeight returns the block at a given height if available and errMissingBlock otherwise. +func (peer *BpPeer) BlockAtHeight(height int64) (*types.Block, error) { + block, ok := peer.blocks[height] + if !ok { + return nil, errMissingBlock + } + if block == nil { + return nil, errMissingBlock + } + return peer.blocks[height], nil +} + +// AddBlock adds a block at peer level. Block must be non-nil and recvSize a positive integer +// The peer must have a pending request for this block. +func (peer *BpPeer) AddBlock(block *types.Block, recvSize int) error { + if block == nil || recvSize < 0 { + panic("bad parameters") + } + existingBlock, ok := peer.blocks[block.Height] + if !ok { + peer.logger.Error("unsolicited block", "blockHeight", block.Height, "peer", peer.ID) + return errMissingBlock + } + if existingBlock != nil { + peer.logger.Error("already have a block for height", "height", block.Height) + return errDuplicateBlock + } + if peer.NumPendingBlockRequests == 0 { + panic("peer does not have pending requests") + } + peer.blocks[block.Height] = block + peer.NumPendingBlockRequests-- + if peer.NumPendingBlockRequests == 0 { + peer.stopMonitor() + peer.stopBlockResponseTimer() + } else { + peer.recvMonitor.Update(recvSize) + peer.resetBlockResponseTimer() + } + return nil +} + +// RemoveBlock removes the block of given height +func (peer *BpPeer) RemoveBlock(height int64) { + delete(peer.blocks, height) +} + +// RequestSent records that a request was sent, and starts the peer timer and monitor if needed. +func (peer *BpPeer) RequestSent(height int64) { + peer.blocks[height] = nil + + if peer.NumPendingBlockRequests == 0 { + peer.startMonitor() + peer.resetBlockResponseTimer() + } + peer.NumPendingBlockRequests++ +} + +// CheckRate verifies that the response rate of the peer is acceptable (higher than the minimum allowed). +func (peer *BpPeer) CheckRate() error { + if peer.NumPendingBlockRequests == 0 { + return nil + } + curRate := peer.recvMonitor.Status().CurRate + // curRate can be 0 on start + if curRate != 0 && curRate < peer.params.minRecvRate { + err := errSlowPeer + peer.logger.Error("SendTimeout", "peer", peer, + "reason", err, + "curRate", fmt.Sprintf("%d KB/s", curRate/1024), + "minRate", fmt.Sprintf("%d KB/s", peer.params.minRecvRate/1024)) + return err + } + return nil +} + +func (peer *BpPeer) onTimeout() { + peer.onErr(errNoPeerResponse, peer.ID) +} + +func (peer *BpPeer) stopMonitor() { + peer.recvMonitor.Done() + peer.recvMonitor = nil +} + +func (peer *BpPeer) startMonitor() { + peer.recvMonitor = flow.New(peer.params.sampleRate, peer.params.windowSize) + initialValue := float64(peer.params.minRecvRate) * math.E + peer.recvMonitor.SetREMA(initialValue) +} + +func (peer *BpPeer) resetBlockResponseTimer() { + if peer.blockResponseTimer == nil { + peer.blockResponseTimer = time.AfterFunc(peer.params.timeout, peer.onTimeout) + } else { + peer.blockResponseTimer.Reset(peer.params.timeout) + } +} + +func (peer *BpPeer) stopBlockResponseTimer() bool { + if peer.blockResponseTimer == nil { + return false + } + return peer.blockResponseTimer.Stop() +} + +// BpPeerDefaultParams returns the default peer parameters. +func BpPeerDefaultParams() *BpPeerParams { + return &BpPeerParams{ + // Timeout for a peer to respond to a block request. + timeout: 15 * time.Second, + + // Minimum recv rate to ensure we're receiving blocks from a peer fast + // enough. If a peer is not sending data at at least that rate, we + // consider them to have timedout and we disconnect. + // + // Assuming a DSL connection (not a good choice) 128 Kbps (upload) ~ 15 KB/s, + // sending data across atlantic ~ 7.5 KB/s. + minRecvRate: int64(7680), + + // Monitor parameters + sampleRate: time.Second, + windowSize: 40 * time.Second, + } +} diff --git a/blockchain/v1/peer_test.go b/blockchain/v1/peer_test.go new file mode 100644 index 000000000..3c19e4efd --- /dev/null +++ b/blockchain/v1/peer_test.go @@ -0,0 +1,278 @@ +package v1 + +import ( + "sync" + "testing" + "time" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + + cmn "github.com/tendermint/tendermint/libs/common" + "github.com/tendermint/tendermint/libs/log" + "github.com/tendermint/tendermint/p2p" + "github.com/tendermint/tendermint/types" +) + +func TestPeerMonitor(t *testing.T) { + peer := NewBpPeer( + p2p.ID(cmn.RandStr(12)), 10, + func(err error, _ p2p.ID) {}, + nil) + peer.SetLogger(log.TestingLogger()) + peer.startMonitor() + assert.NotNil(t, peer.recvMonitor) + peer.stopMonitor() + assert.Nil(t, peer.recvMonitor) +} + +func TestPeerResetBlockResponseTimer(t *testing.T) { + var ( + numErrFuncCalls int // number of calls to the errFunc + lastErr error // last generated error + peerTestMtx sync.Mutex // modifications of ^^ variables are also done from timer handler goroutine + ) + params := &BpPeerParams{timeout: 2 * time.Millisecond} + + peer := NewBpPeer( + p2p.ID(cmn.RandStr(12)), 10, + func(err error, _ p2p.ID) { + peerTestMtx.Lock() + defer peerTestMtx.Unlock() + lastErr = err + numErrFuncCalls++ + }, + params) + + peer.SetLogger(log.TestingLogger()) + checkByStoppingPeerTimer(t, peer, false) + + // initial reset call with peer having a nil timer + peer.resetBlockResponseTimer() + assert.NotNil(t, peer.blockResponseTimer) + // make sure timer is running and stop it + checkByStoppingPeerTimer(t, peer, true) + + // reset with running timer + peer.resetBlockResponseTimer() + time.Sleep(time.Millisecond) + peer.resetBlockResponseTimer() + assert.NotNil(t, peer.blockResponseTimer) + + // let the timer expire and ... + time.Sleep(3 * time.Millisecond) + // ... check timer is not running + checkByStoppingPeerTimer(t, peer, false) + + peerTestMtx.Lock() + // ... check errNoPeerResponse has been sent + assert.Equal(t, 1, numErrFuncCalls) + assert.Equal(t, lastErr, errNoPeerResponse) + peerTestMtx.Unlock() +} + +func TestPeerRequestSent(t *testing.T) { + params := &BpPeerParams{timeout: 2 * time.Millisecond} + + peer := NewBpPeer( + p2p.ID(cmn.RandStr(12)), 10, + func(err error, _ p2p.ID) {}, + params) + + peer.SetLogger(log.TestingLogger()) + + peer.RequestSent(1) + assert.NotNil(t, peer.recvMonitor) + assert.NotNil(t, peer.blockResponseTimer) + assert.Equal(t, 1, peer.NumPendingBlockRequests) + + peer.RequestSent(1) + assert.NotNil(t, peer.recvMonitor) + assert.NotNil(t, peer.blockResponseTimer) + assert.Equal(t, 2, peer.NumPendingBlockRequests) +} + +func TestPeerGetAndRemoveBlock(t *testing.T) { + peer := NewBpPeer( + p2p.ID(cmn.RandStr(12)), 100, + func(err error, _ p2p.ID) {}, + nil) + + // Change peer height + peer.Height = int64(10) + assert.Equal(t, int64(10), peer.Height) + + // request some blocks and receive few of them + for i := 1; i <= 10; i++ { + peer.RequestSent(int64(i)) + if i > 5 { + // only receive blocks 1..5 + continue + } + _ = peer.AddBlock(makeSmallBlock(i), 10) + } + + tests := []struct { + name string + height int64 + wantErr error + blockPresent bool + }{ + {"no request", 100, errMissingBlock, false}, + {"no block", 6, errMissingBlock, false}, + {"block 1 present", 1, nil, true}, + {"block max present", 5, nil, true}, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + // try to get the block + b, err := peer.BlockAtHeight(tt.height) + assert.Equal(t, tt.wantErr, err) + assert.Equal(t, tt.blockPresent, b != nil) + + // remove the block + peer.RemoveBlock(tt.height) + _, err = peer.BlockAtHeight(tt.height) + assert.Equal(t, errMissingBlock, err) + }) + } +} + +func TestPeerAddBlock(t *testing.T) { + peer := NewBpPeer( + p2p.ID(cmn.RandStr(12)), 100, + func(err error, _ p2p.ID) {}, + nil) + + // request some blocks, receive one + for i := 1; i <= 10; i++ { + peer.RequestSent(int64(i)) + if i == 5 { + // receive block 5 + _ = peer.AddBlock(makeSmallBlock(i), 10) + } + } + + tests := []struct { + name string + height int64 + wantErr error + blockPresent bool + }{ + {"no request", 50, errMissingBlock, false}, + {"duplicate block", 5, errDuplicateBlock, true}, + {"block 1 successfully received", 1, nil, true}, + {"block max successfully received", 10, nil, true}, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + // try to get the block + err := peer.AddBlock(makeSmallBlock(int(tt.height)), 10) + assert.Equal(t, tt.wantErr, err) + _, err = peer.BlockAtHeight(tt.height) + assert.Equal(t, tt.blockPresent, err == nil) + }) + } +} + +func TestPeerOnErrFuncCalledDueToExpiration(t *testing.T) { + + params := &BpPeerParams{timeout: 2 * time.Millisecond} + var ( + numErrFuncCalls int // number of calls to the onErr function + lastErr error // last generated error + peerTestMtx sync.Mutex // modifications of ^^ variables are also done from timer handler goroutine + ) + + peer := NewBpPeer( + p2p.ID(cmn.RandStr(12)), 10, + func(err error, _ p2p.ID) { + peerTestMtx.Lock() + defer peerTestMtx.Unlock() + lastErr = err + numErrFuncCalls++ + }, + params) + + peer.SetLogger(log.TestingLogger()) + + peer.RequestSent(1) + time.Sleep(4 * time.Millisecond) + // timer should have expired by now, check that the on error function was called + peerTestMtx.Lock() + assert.Equal(t, 1, numErrFuncCalls) + assert.Equal(t, errNoPeerResponse, lastErr) + peerTestMtx.Unlock() +} + +func TestPeerCheckRate(t *testing.T) { + params := &BpPeerParams{ + timeout: time.Second, + minRecvRate: int64(100), // 100 bytes/sec exponential moving average + } + peer := NewBpPeer( + p2p.ID(cmn.RandStr(12)), 10, + func(err error, _ p2p.ID) {}, + params) + peer.SetLogger(log.TestingLogger()) + + require.Nil(t, peer.CheckRate()) + + for i := 0; i < 40; i++ { + peer.RequestSent(int64(i)) + } + + // monitor starts with a higher rEMA (~ 2*minRecvRate), wait for it to go down + time.Sleep(900 * time.Millisecond) + + // normal peer - send a bit more than 100 bytes/sec, > 10 bytes/100msec, check peer is not considered slow + for i := 0; i < 10; i++ { + _ = peer.AddBlock(makeSmallBlock(i), 11) + time.Sleep(100 * time.Millisecond) + require.Nil(t, peer.CheckRate()) + } + + // slow peer - send a bit less than 10 bytes/100msec + for i := 10; i < 20; i++ { + _ = peer.AddBlock(makeSmallBlock(i), 9) + time.Sleep(100 * time.Millisecond) + } + // check peer is considered slow + assert.Equal(t, errSlowPeer, peer.CheckRate()) +} + +func TestPeerCleanup(t *testing.T) { + params := &BpPeerParams{timeout: 2 * time.Millisecond} + + peer := NewBpPeer( + p2p.ID(cmn.RandStr(12)), 10, + func(err error, _ p2p.ID) {}, + params) + peer.SetLogger(log.TestingLogger()) + + assert.Nil(t, peer.blockResponseTimer) + peer.RequestSent(1) + assert.NotNil(t, peer.blockResponseTimer) + + peer.Cleanup() + checkByStoppingPeerTimer(t, peer, false) +} + +// Check if peer timer is running or not (a running timer can be successfully stopped). +// Note: stops the timer. +func checkByStoppingPeerTimer(t *testing.T, peer *BpPeer, running bool) { + assert.NotPanics(t, func() { + stopped := peer.stopBlockResponseTimer() + if running { + assert.True(t, stopped) + } else { + assert.False(t, stopped) + } + }) +} + +func makeSmallBlock(height int) *types.Block { + return types.MakeBlock(int64(height), []types.Tx{types.Tx("foo")}, nil, nil) +} diff --git a/blockchain/v1/pool.go b/blockchain/v1/pool.go new file mode 100644 index 000000000..5de741305 --- /dev/null +++ b/blockchain/v1/pool.go @@ -0,0 +1,369 @@ +package v1 + +import ( + "sort" + + "github.com/tendermint/tendermint/libs/log" + "github.com/tendermint/tendermint/p2p" + "github.com/tendermint/tendermint/types" +) + +// BlockPool keeps track of the fast sync peers, block requests and block responses. +type BlockPool struct { + logger log.Logger + // Set of peers that have sent status responses, with height bigger than pool.Height + peers map[p2p.ID]*BpPeer + // Set of block heights and the corresponding peers from where a block response is expected or has been received. + blocks map[int64]p2p.ID + + plannedRequests map[int64]struct{} // list of blocks to be assigned peers for blockRequest + nextRequestHeight int64 // next height to be added to plannedRequests + + Height int64 // height of next block to execute + MaxPeerHeight int64 // maximum height of all peers + toBcR bcReactor +} + +// NewBlockPool creates a new BlockPool. +func NewBlockPool(height int64, toBcR bcReactor) *BlockPool { + return &BlockPool{ + Height: height, + MaxPeerHeight: 0, + peers: make(map[p2p.ID]*BpPeer), + blocks: make(map[int64]p2p.ID), + plannedRequests: make(map[int64]struct{}), + nextRequestHeight: height, + toBcR: toBcR, + } +} + +// SetLogger sets the logger of the pool. +func (pool *BlockPool) SetLogger(l log.Logger) { + pool.logger = l +} + +// ReachedMaxHeight check if the pool has reached the maximum peer height. +func (pool *BlockPool) ReachedMaxHeight() bool { + return pool.Height >= pool.MaxPeerHeight +} + +func (pool *BlockPool) rescheduleRequest(peerID p2p.ID, height int64) { + pool.logger.Info("reschedule requests made to peer for height ", "peerID", peerID, "height", height) + pool.plannedRequests[height] = struct{}{} + delete(pool.blocks, height) + pool.peers[peerID].RemoveBlock(height) +} + +// Updates the pool's max height. If no peers are left MaxPeerHeight is set to 0. +func (pool *BlockPool) updateMaxPeerHeight() { + var newMax int64 + for _, peer := range pool.peers { + peerHeight := peer.Height + if peerHeight > newMax { + newMax = peerHeight + } + } + pool.MaxPeerHeight = newMax +} + +// UpdatePeer adds a new peer or updates an existing peer with a new height. +// If a peer is short it is not added. +func (pool *BlockPool) UpdatePeer(peerID p2p.ID, height int64) error { + + peer := pool.peers[peerID] + + if peer == nil { + if height < pool.Height { + pool.logger.Info("Peer height too small", + "peer", peerID, "height", height, "fsm_height", pool.Height) + return errPeerTooShort + } + // Add new peer. + peer = NewBpPeer(peerID, height, pool.toBcR.sendPeerError, nil) + peer.SetLogger(pool.logger.With("peer", peerID)) + pool.peers[peerID] = peer + pool.logger.Info("added peer", "peerID", peerID, "height", height, "num_peers", len(pool.peers)) + } else { + // Check if peer is lowering its height. This is not allowed. + if height < peer.Height { + pool.RemovePeer(peerID, errPeerLowersItsHeight) + return errPeerLowersItsHeight + } + // Update existing peer. + peer.Height = height + } + + // Update the pool's MaxPeerHeight if needed. + pool.updateMaxPeerHeight() + + return nil +} + +// Cleans and deletes the peer. Recomputes the max peer height. +func (pool *BlockPool) deletePeer(peer *BpPeer) { + if peer == nil { + return + } + peer.Cleanup() + delete(pool.peers, peer.ID) + + if peer.Height == pool.MaxPeerHeight { + pool.updateMaxPeerHeight() + } +} + +// RemovePeer removes the blocks and requests from the peer, reschedules them and deletes the peer. +func (pool *BlockPool) RemovePeer(peerID p2p.ID, err error) { + peer := pool.peers[peerID] + if peer == nil { + return + } + pool.logger.Info("removing peer", "peerID", peerID, "error", err) + + // Reschedule the block requests made to the peer, or received and not processed yet. + // Note that some of the requests may be removed further down. + for h := range pool.peers[peerID].blocks { + pool.rescheduleRequest(peerID, h) + } + + oldMaxPeerHeight := pool.MaxPeerHeight + // Delete the peer. This operation may result in the pool's MaxPeerHeight being lowered. + pool.deletePeer(peer) + + // Check if the pool's MaxPeerHeight has been lowered. + // This may happen if the tallest peer has been removed. + if oldMaxPeerHeight > pool.MaxPeerHeight { + // Remove any planned requests for heights over the new MaxPeerHeight. + for h := range pool.plannedRequests { + if h > pool.MaxPeerHeight { + delete(pool.plannedRequests, h) + } + } + // Adjust the nextRequestHeight to the new max plus one. + if pool.nextRequestHeight > pool.MaxPeerHeight { + pool.nextRequestHeight = pool.MaxPeerHeight + 1 + } + } +} + +func (pool *BlockPool) removeShortPeers() { + for _, peer := range pool.peers { + if peer.Height < pool.Height { + pool.RemovePeer(peer.ID, nil) + } + } +} + +func (pool *BlockPool) removeBadPeers() { + pool.removeShortPeers() + for _, peer := range pool.peers { + if err := peer.CheckRate(); err != nil { + pool.RemovePeer(peer.ID, err) + pool.toBcR.sendPeerError(err, peer.ID) + } + } +} + +// MakeNextRequests creates more requests if the block pool is running low. +func (pool *BlockPool) MakeNextRequests(maxNumRequests int) { + heights := pool.makeRequestBatch(maxNumRequests) + if len(heights) != 0 { + pool.logger.Info("makeNextRequests will make following requests", + "number", len(heights), "heights", heights) + } + + for _, height := range heights { + h := int64(height) + if !pool.sendRequest(h) { + // If a good peer was not found for sending the request at height h then return, + // as it shouldn't be possible to find a peer for h+1. + return + } + delete(pool.plannedRequests, h) + } +} + +// Makes a batch of requests sorted by height such that the block pool has up to maxNumRequests entries. +func (pool *BlockPool) makeRequestBatch(maxNumRequests int) []int { + pool.removeBadPeers() + // At this point pool.requests may include heights for requests to be redone due to removal of peers: + // - peers timed out or were removed by switch + // - FSM timed out on waiting to advance the block execution due to missing blocks at h or h+1 + // Determine the number of requests needed by subtracting the number of requests already made from the maximum + // allowed + numNeeded := int(maxNumRequests) - len(pool.blocks) + for len(pool.plannedRequests) < numNeeded { + if pool.nextRequestHeight > pool.MaxPeerHeight { + break + } + pool.plannedRequests[pool.nextRequestHeight] = struct{}{} + pool.nextRequestHeight++ + } + + heights := make([]int, 0, len(pool.plannedRequests)) + for k := range pool.plannedRequests { + heights = append(heights, int(k)) + } + sort.Ints(heights) + return heights +} + +func (pool *BlockPool) sendRequest(height int64) bool { + for _, peer := range pool.peers { + if peer.NumPendingBlockRequests >= maxRequestsPerPeer { + continue + } + if peer.Height < height { + continue + } + + err := pool.toBcR.sendBlockRequest(peer.ID, height) + if err == errNilPeerForBlockRequest { + // Switch does not have this peer, remove it and continue to look for another peer. + pool.logger.Error("switch does not have peer..removing peer selected for height", "peer", + peer.ID, "height", height) + pool.RemovePeer(peer.ID, err) + continue + } + + if err == errSendQueueFull { + pool.logger.Error("peer queue is full", "peer", peer.ID, "height", height) + continue + } + + pool.logger.Info("assigned request to peer", "peer", peer.ID, "height", height) + + pool.blocks[height] = peer.ID + peer.RequestSent(height) + + return true + } + pool.logger.Error("could not find peer to send request for block at height", "height", height) + return false +} + +// AddBlock validates that the block comes from the peer it was expected from and stores it in the 'blocks' map. +func (pool *BlockPool) AddBlock(peerID p2p.ID, block *types.Block, blockSize int) error { + peer, ok := pool.peers[peerID] + if !ok { + pool.logger.Error("block from unknown peer", "height", block.Height, "peer", peerID) + return errBadDataFromPeer + } + if wantPeerID, ok := pool.blocks[block.Height]; ok && wantPeerID != peerID { + pool.logger.Error("block received from wrong peer", "height", block.Height, + "peer", peerID, "expected_peer", wantPeerID) + return errBadDataFromPeer + } + + return peer.AddBlock(block, blockSize) +} + +// BlockData stores the peer responsible to deliver a block and the actual block if delivered. +type BlockData struct { + block *types.Block + peer *BpPeer +} + +// BlockAndPeerAtHeight retrieves the block and delivery peer at specified height. +// Returns errMissingBlock if a block was not found +func (pool *BlockPool) BlockAndPeerAtHeight(height int64) (bData *BlockData, err error) { + peerID := pool.blocks[height] + peer := pool.peers[peerID] + if peer == nil { + return nil, errMissingBlock + } + + block, err := peer.BlockAtHeight(height) + if err != nil { + return nil, err + } + + return &BlockData{peer: peer, block: block}, nil + +} + +// FirstTwoBlocksAndPeers returns the blocks and the delivery peers at pool's height H and H+1. +func (pool *BlockPool) FirstTwoBlocksAndPeers() (first, second *BlockData, err error) { + first, err = pool.BlockAndPeerAtHeight(pool.Height) + second, err2 := pool.BlockAndPeerAtHeight(pool.Height + 1) + if err == nil { + err = err2 + } + return +} + +// InvalidateFirstTwoBlocks removes the peers that sent us the first two blocks, blocks are removed by RemovePeer(). +func (pool *BlockPool) InvalidateFirstTwoBlocks(err error) { + first, err1 := pool.BlockAndPeerAtHeight(pool.Height) + second, err2 := pool.BlockAndPeerAtHeight(pool.Height + 1) + + if err1 == nil { + pool.RemovePeer(first.peer.ID, err) + } + if err2 == nil { + pool.RemovePeer(second.peer.ID, err) + } +} + +// ProcessedCurrentHeightBlock performs cleanup after a block is processed. It removes block at pool height and +// the peers that are now short. +func (pool *BlockPool) ProcessedCurrentHeightBlock() { + peerID, peerOk := pool.blocks[pool.Height] + if peerOk { + pool.peers[peerID].RemoveBlock(pool.Height) + } + delete(pool.blocks, pool.Height) + pool.logger.Debug("removed block at height", "height", pool.Height) + pool.Height++ + pool.removeShortPeers() +} + +// RemovePeerAtCurrentHeights checks if a block at pool's height H exists and if not, it removes the +// delivery peer and returns. If a block at height H exists then the check and peer removal is done for H+1. +// This function is called when the FSM is not able to make progress for some time. +// This happens if either the block H or H+1 have not been delivered. +func (pool *BlockPool) RemovePeerAtCurrentHeights(err error) { + peerID := pool.blocks[pool.Height] + peer, ok := pool.peers[peerID] + if ok { + if _, err := peer.BlockAtHeight(pool.Height); err != nil { + pool.logger.Info("remove peer that hasn't sent block at pool.Height", + "peer", peerID, "height", pool.Height) + pool.RemovePeer(peerID, err) + return + } + } + peerID = pool.blocks[pool.Height+1] + peer, ok = pool.peers[peerID] + if ok { + if _, err := peer.BlockAtHeight(pool.Height + 1); err != nil { + pool.logger.Info("remove peer that hasn't sent block at pool.Height+1", + "peer", peerID, "height", pool.Height+1) + pool.RemovePeer(peerID, err) + return + } + } +} + +// Cleanup performs pool and peer cleanup +func (pool *BlockPool) Cleanup() { + for id, peer := range pool.peers { + peer.Cleanup() + delete(pool.peers, id) + } + pool.plannedRequests = make(map[int64]struct{}) + pool.blocks = make(map[int64]p2p.ID) + pool.nextRequestHeight = 0 + pool.Height = 0 + pool.MaxPeerHeight = 0 +} + +// NumPeers returns the number of peers in the pool +func (pool *BlockPool) NumPeers() int { + return len(pool.peers) +} + +// NeedsBlocks returns true if more blocks are required. +func (pool *BlockPool) NeedsBlocks() bool { + return len(pool.blocks) < maxNumRequests +} diff --git a/blockchain/v1/pool_test.go b/blockchain/v1/pool_test.go new file mode 100644 index 000000000..72758d3b1 --- /dev/null +++ b/blockchain/v1/pool_test.go @@ -0,0 +1,650 @@ +package v1 + +import ( + "testing" + "time" + + "github.com/stretchr/testify/assert" + + "github.com/tendermint/tendermint/libs/log" + "github.com/tendermint/tendermint/p2p" + "github.com/tendermint/tendermint/types" +) + +type testPeer struct { + id p2p.ID + height int64 +} + +type testBcR struct { + logger log.Logger +} + +type testValues struct { + numRequestsSent int +} + +var testResults testValues + +func resetPoolTestResults() { + testResults.numRequestsSent = 0 +} + +func (testR *testBcR) sendPeerError(err error, peerID p2p.ID) { +} + +func (testR *testBcR) sendStatusRequest() { +} + +func (testR *testBcR) sendBlockRequest(peerID p2p.ID, height int64) error { + testResults.numRequestsSent++ + return nil +} + +func (testR *testBcR) resetStateTimer(name string, timer **time.Timer, timeout time.Duration) { +} + +func (testR *testBcR) switchToConsensus() { + +} + +func newTestBcR() *testBcR { + testBcR := &testBcR{logger: log.TestingLogger()} + return testBcR +} + +type tPBlocks struct { + id p2p.ID + create bool +} + +// Makes a block pool with specified current height, list of peers, block requests and block responses +func makeBlockPool(bcr *testBcR, height int64, peers []BpPeer, blocks map[int64]tPBlocks) *BlockPool { + bPool := NewBlockPool(height, bcr) + bPool.SetLogger(bcr.logger) + + txs := []types.Tx{types.Tx("foo"), types.Tx("bar")} + + var maxH int64 + for _, p := range peers { + if p.Height > maxH { + maxH = p.Height + } + bPool.peers[p.ID] = NewBpPeer(p.ID, p.Height, bcr.sendPeerError, nil) + bPool.peers[p.ID].SetLogger(bcr.logger) + + } + bPool.MaxPeerHeight = maxH + for h, p := range blocks { + bPool.blocks[h] = p.id + bPool.peers[p.id].RequestSent(int64(h)) + if p.create { + // simulate that a block at height h has been received + _ = bPool.peers[p.id].AddBlock(types.MakeBlock(int64(h), txs, nil, nil), 100) + } + } + return bPool +} + +func assertPeerSetsEquivalent(t *testing.T, set1 map[p2p.ID]*BpPeer, set2 map[p2p.ID]*BpPeer) { + assert.Equal(t, len(set1), len(set2)) + for peerID, peer1 := range set1 { + peer2 := set2[peerID] + assert.NotNil(t, peer2) + assert.Equal(t, peer1.NumPendingBlockRequests, peer2.NumPendingBlockRequests) + assert.Equal(t, peer1.Height, peer2.Height) + assert.Equal(t, len(peer1.blocks), len(peer2.blocks)) + for h, block1 := range peer1.blocks { + block2 := peer2.blocks[h] + // block1 and block2 could be nil if a request was made but no block was received + assert.Equal(t, block1, block2) + } + } +} + +func assertBlockPoolEquivalent(t *testing.T, poolWanted, pool *BlockPool) { + assert.Equal(t, poolWanted.blocks, pool.blocks) + assertPeerSetsEquivalent(t, poolWanted.peers, pool.peers) + assert.Equal(t, poolWanted.MaxPeerHeight, pool.MaxPeerHeight) + assert.Equal(t, poolWanted.Height, pool.Height) + +} + +func TestBlockPoolUpdatePeer(t *testing.T) { + testBcR := newTestBcR() + + tests := []struct { + name string + pool *BlockPool + args testPeer + poolWanted *BlockPool + errWanted error + }{ + { + name: "add a first short peer", + pool: makeBlockPool(testBcR, 100, []BpPeer{}, map[int64]tPBlocks{}), + args: testPeer{"P1", 50}, + errWanted: errPeerTooShort, + poolWanted: makeBlockPool(testBcR, 100, []BpPeer{}, map[int64]tPBlocks{}), + }, + { + name: "add a first good peer", + pool: makeBlockPool(testBcR, 100, []BpPeer{}, map[int64]tPBlocks{}), + args: testPeer{"P1", 101}, + poolWanted: makeBlockPool(testBcR, 100, []BpPeer{{ID: "P1", Height: 101}}, map[int64]tPBlocks{}), + }, + { + name: "increase the height of P1 from 120 to 123", + pool: makeBlockPool(testBcR, 100, []BpPeer{{ID: "P1", Height: 120}}, map[int64]tPBlocks{}), + args: testPeer{"P1", 123}, + poolWanted: makeBlockPool(testBcR, 100, []BpPeer{{ID: "P1", Height: 123}}, map[int64]tPBlocks{}), + }, + { + name: "decrease the height of P1 from 120 to 110", + pool: makeBlockPool(testBcR, 100, []BpPeer{{ID: "P1", Height: 120}}, map[int64]tPBlocks{}), + args: testPeer{"P1", 110}, + errWanted: errPeerLowersItsHeight, + poolWanted: makeBlockPool(testBcR, 100, []BpPeer{}, map[int64]tPBlocks{}), + }, + { + name: "decrease the height of P1 from 105 to 102 with blocks", + pool: makeBlockPool(testBcR, 100, []BpPeer{{ID: "P1", Height: 105}}, + map[int64]tPBlocks{ + 100: {"P1", true}, 101: {"P1", true}, 102: {"P1", true}}), + args: testPeer{"P1", 102}, + errWanted: errPeerLowersItsHeight, + poolWanted: makeBlockPool(testBcR, 100, []BpPeer{}, + map[int64]tPBlocks{}), + }, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + pool := tt.pool + err := pool.UpdatePeer(tt.args.id, tt.args.height) + assert.Equal(t, tt.errWanted, err) + assert.Equal(t, tt.poolWanted.blocks, tt.pool.blocks) + assertPeerSetsEquivalent(t, tt.poolWanted.peers, tt.pool.peers) + assert.Equal(t, tt.poolWanted.MaxPeerHeight, tt.pool.MaxPeerHeight) + }) + } +} + +func TestBlockPoolRemovePeer(t *testing.T) { + testBcR := newTestBcR() + + type args struct { + peerID p2p.ID + err error + } + + tests := []struct { + name string + pool *BlockPool + args args + poolWanted *BlockPool + }{ + { + name: "attempt to delete non-existing peer", + pool: makeBlockPool(testBcR, 100, []BpPeer{{ID: "P1", Height: 120}}, map[int64]tPBlocks{}), + args: args{"P99", nil}, + poolWanted: makeBlockPool(testBcR, 100, []BpPeer{{ID: "P1", Height: 120}}, map[int64]tPBlocks{}), + }, + { + name: "delete the only peer without blocks", + pool: makeBlockPool(testBcR, 100, []BpPeer{{ID: "P1", Height: 120}}, map[int64]tPBlocks{}), + args: args{"P1", nil}, + poolWanted: makeBlockPool(testBcR, 100, []BpPeer{}, map[int64]tPBlocks{}), + }, + { + name: "delete the shortest of two peers without blocks", + pool: makeBlockPool(testBcR, 100, []BpPeer{{ID: "P1", Height: 100}, {ID: "P2", Height: 120}}, map[int64]tPBlocks{}), + args: args{"P1", nil}, + poolWanted: makeBlockPool(testBcR, 100, []BpPeer{{ID: "P2", Height: 120}}, map[int64]tPBlocks{}), + }, + { + name: "delete the tallest of two peers without blocks", + pool: makeBlockPool(testBcR, 100, []BpPeer{{ID: "P1", Height: 100}, {ID: "P2", Height: 120}}, map[int64]tPBlocks{}), + args: args{"P2", nil}, + poolWanted: makeBlockPool(testBcR, 100, []BpPeer{{ID: "P1", Height: 100}}, map[int64]tPBlocks{}), + }, + { + name: "delete the only peer with block requests sent and blocks received", + pool: makeBlockPool(testBcR, 100, []BpPeer{{ID: "P1", Height: 120}}, + map[int64]tPBlocks{100: {"P1", true}, 101: {"P1", false}}), + args: args{"P1", nil}, + poolWanted: makeBlockPool(testBcR, 100, []BpPeer{}, map[int64]tPBlocks{}), + }, + { + name: "delete the shortest of two peers with block requests sent and blocks received", + pool: makeBlockPool(testBcR, 100, []BpPeer{{ID: "P1", Height: 120}, {ID: "P2", Height: 200}}, + map[int64]tPBlocks{100: {"P1", true}, 101: {"P1", false}}), + args: args{"P1", nil}, + poolWanted: makeBlockPool(testBcR, 100, []BpPeer{{ID: "P2", Height: 200}}, map[int64]tPBlocks{}), + }, + { + name: "delete the tallest of two peers with block requests sent and blocks received", + pool: makeBlockPool(testBcR, 100, []BpPeer{{ID: "P1", Height: 120}, {ID: "P2", Height: 110}}, + map[int64]tPBlocks{100: {"P1", true}, 101: {"P1", false}}), + args: args{"P1", nil}, + poolWanted: makeBlockPool(testBcR, 100, []BpPeer{{ID: "P2", Height: 110}}, map[int64]tPBlocks{}), + }, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + tt.pool.RemovePeer(tt.args.peerID, tt.args.err) + assertBlockPoolEquivalent(t, tt.poolWanted, tt.pool) + }) + } +} + +func TestBlockPoolRemoveShortPeers(t *testing.T) { + testBcR := newTestBcR() + + tests := []struct { + name string + pool *BlockPool + poolWanted *BlockPool + }{ + { + name: "no short peers", + pool: makeBlockPool(testBcR, 100, + []BpPeer{{ID: "P1", Height: 100}, {ID: "P2", Height: 110}, {ID: "P3", Height: 120}}, map[int64]tPBlocks{}), + poolWanted: makeBlockPool(testBcR, 100, + []BpPeer{{ID: "P1", Height: 100}, {ID: "P2", Height: 110}, {ID: "P3", Height: 120}}, map[int64]tPBlocks{}), + }, + + { + name: "one short peer", + pool: makeBlockPool(testBcR, 100, + []BpPeer{{ID: "P1", Height: 100}, {ID: "P2", Height: 90}, {ID: "P3", Height: 120}}, map[int64]tPBlocks{}), + poolWanted: makeBlockPool(testBcR, 100, + []BpPeer{{ID: "P1", Height: 100}, {ID: "P3", Height: 120}}, map[int64]tPBlocks{}), + }, + + { + name: "all short peers", + pool: makeBlockPool(testBcR, 100, + []BpPeer{{ID: "P1", Height: 90}, {ID: "P2", Height: 91}, {ID: "P3", Height: 92}}, map[int64]tPBlocks{}), + poolWanted: makeBlockPool(testBcR, 100, []BpPeer{}, map[int64]tPBlocks{}), + }, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + pool := tt.pool + pool.removeShortPeers() + assertBlockPoolEquivalent(t, tt.poolWanted, tt.pool) + }) + } +} + +func TestBlockPoolSendRequestBatch(t *testing.T) { + type testPeerResult struct { + id p2p.ID + numPendingBlockRequests int + } + + testBcR := newTestBcR() + + tests := []struct { + name string + pool *BlockPool + maxRequestsPerPeer int + expRequests map[int64]bool + expPeerResults []testPeerResult + expnumPendingBlockRequests int + }{ + { + name: "one peer - send up to maxRequestsPerPeer block requests", + pool: makeBlockPool(testBcR, 10, []BpPeer{{ID: "P1", Height: 100}}, map[int64]tPBlocks{}), + maxRequestsPerPeer: 2, + expRequests: map[int64]bool{10: true, 11: true}, + expPeerResults: []testPeerResult{{id: "P1", numPendingBlockRequests: 2}}, + expnumPendingBlockRequests: 2, + }, + { + name: "n peers - send n*maxRequestsPerPeer block requests", + pool: makeBlockPool(testBcR, 10, []BpPeer{{ID: "P1", Height: 100}, {ID: "P2", Height: 100}}, map[int64]tPBlocks{}), + maxRequestsPerPeer: 2, + expRequests: map[int64]bool{10: true, 11: true}, + expPeerResults: []testPeerResult{ + {id: "P1", numPendingBlockRequests: 2}, + {id: "P2", numPendingBlockRequests: 2}}, + expnumPendingBlockRequests: 4, + }, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + resetPoolTestResults() + + var pool = tt.pool + maxRequestsPerPeer = tt.maxRequestsPerPeer + pool.MakeNextRequests(10) + assert.Equal(t, testResults.numRequestsSent, maxRequestsPerPeer*len(pool.peers)) + + for _, tPeer := range tt.expPeerResults { + var peer = pool.peers[tPeer.id] + assert.NotNil(t, peer) + assert.Equal(t, tPeer.numPendingBlockRequests, peer.NumPendingBlockRequests) + } + assert.Equal(t, testResults.numRequestsSent, maxRequestsPerPeer*len(pool.peers)) + + }) + } +} + +func TestBlockPoolAddBlock(t *testing.T) { + testBcR := newTestBcR() + txs := []types.Tx{types.Tx("foo"), types.Tx("bar")} + + type args struct { + peerID p2p.ID + block *types.Block + blockSize int + } + tests := []struct { + name string + pool *BlockPool + args args + poolWanted *BlockPool + errWanted error + }{ + {name: "block from unknown peer", + pool: makeBlockPool(testBcR, 10, []BpPeer{{ID: "P1", Height: 100}}, map[int64]tPBlocks{}), + args: args{ + peerID: "P2", + block: types.MakeBlock(int64(10), txs, nil, nil), + blockSize: 100, + }, + poolWanted: makeBlockPool(testBcR, 10, []BpPeer{{ID: "P1", Height: 100}}, map[int64]tPBlocks{}), + errWanted: errBadDataFromPeer, + }, + {name: "unexpected block 11 from known peer - waiting for 10", + pool: makeBlockPool(testBcR, 10, + []BpPeer{{ID: "P1", Height: 100}}, + map[int64]tPBlocks{10: {"P1", false}}), + args: args{ + peerID: "P1", + block: types.MakeBlock(int64(11), txs, nil, nil), + blockSize: 100, + }, + poolWanted: makeBlockPool(testBcR, 10, + []BpPeer{{ID: "P1", Height: 100}}, + map[int64]tPBlocks{10: {"P1", false}}), + errWanted: errMissingBlock, + }, + {name: "unexpected block 10 from known peer - already have 10", + pool: makeBlockPool(testBcR, 10, + []BpPeer{{ID: "P1", Height: 100}}, + map[int64]tPBlocks{10: {"P1", true}, 11: {"P1", false}}), + args: args{ + peerID: "P1", + block: types.MakeBlock(int64(10), txs, nil, nil), + blockSize: 100, + }, + poolWanted: makeBlockPool(testBcR, 10, + []BpPeer{{ID: "P1", Height: 100}}, + map[int64]tPBlocks{10: {"P1", true}, 11: {"P1", false}}), + errWanted: errDuplicateBlock, + }, + {name: "unexpected block 10 from known peer P2 - expected 10 to come from P1", + pool: makeBlockPool(testBcR, 10, + []BpPeer{{ID: "P1", Height: 100}, {ID: "P2", Height: 100}}, + map[int64]tPBlocks{10: {"P1", false}}), + args: args{ + peerID: "P2", + block: types.MakeBlock(int64(10), txs, nil, nil), + blockSize: 100, + }, + poolWanted: makeBlockPool(testBcR, 10, + []BpPeer{{ID: "P1", Height: 100}, {ID: "P2", Height: 100}}, + map[int64]tPBlocks{10: {"P1", false}}), + errWanted: errBadDataFromPeer, + }, + {name: "expected block from known peer", + pool: makeBlockPool(testBcR, 10, + []BpPeer{{ID: "P1", Height: 100}}, + map[int64]tPBlocks{10: {"P1", false}}), + args: args{ + peerID: "P1", + block: types.MakeBlock(int64(10), txs, nil, nil), + blockSize: 100, + }, + poolWanted: makeBlockPool(testBcR, 10, + []BpPeer{{ID: "P1", Height: 100}}, + map[int64]tPBlocks{10: {"P1", true}}), + errWanted: nil, + }, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + err := tt.pool.AddBlock(tt.args.peerID, tt.args.block, tt.args.blockSize) + assert.Equal(t, tt.errWanted, err) + assertBlockPoolEquivalent(t, tt.poolWanted, tt.pool) + }) + } +} + +func TestBlockPoolFirstTwoBlocksAndPeers(t *testing.T) { + testBcR := newTestBcR() + + tests := []struct { + name string + pool *BlockPool + firstWanted int64 + secondWanted int64 + errWanted error + }{ + { + name: "both blocks missing", + pool: makeBlockPool(testBcR, 10, + []BpPeer{{ID: "P1", Height: 100}, {ID: "P2", Height: 100}}, + map[int64]tPBlocks{15: {"P1", true}, 16: {"P2", true}}), + errWanted: errMissingBlock, + }, + { + name: "second block missing", + pool: makeBlockPool(testBcR, 15, + []BpPeer{{ID: "P1", Height: 100}, {ID: "P2", Height: 100}}, + map[int64]tPBlocks{15: {"P1", true}, 18: {"P2", true}}), + firstWanted: 15, + errWanted: errMissingBlock, + }, + { + name: "first block missing", + pool: makeBlockPool(testBcR, 15, + []BpPeer{{ID: "P1", Height: 100}, {ID: "P2", Height: 100}}, + map[int64]tPBlocks{16: {"P2", true}, 18: {"P2", true}}), + secondWanted: 16, + errWanted: errMissingBlock, + }, + { + name: "both blocks present", + pool: makeBlockPool(testBcR, 10, + []BpPeer{{ID: "P1", Height: 100}, {ID: "P2", Height: 100}}, + map[int64]tPBlocks{10: {"P1", true}, 11: {"P2", true}}), + firstWanted: 10, + secondWanted: 11, + }, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + pool := tt.pool + gotFirst, gotSecond, err := pool.FirstTwoBlocksAndPeers() + assert.Equal(t, tt.errWanted, err) + + if tt.firstWanted != 0 { + peer := pool.blocks[tt.firstWanted] + block := pool.peers[peer].blocks[tt.firstWanted] + assert.Equal(t, block, gotFirst.block, + "BlockPool.FirstTwoBlocksAndPeers() gotFirst = %v, want %v", + tt.firstWanted, gotFirst.block.Height) + } + + if tt.secondWanted != 0 { + peer := pool.blocks[tt.secondWanted] + block := pool.peers[peer].blocks[tt.secondWanted] + assert.Equal(t, block, gotSecond.block, + "BlockPool.FirstTwoBlocksAndPeers() gotFirst = %v, want %v", + tt.secondWanted, gotSecond.block.Height) + } + }) + } +} + +func TestBlockPoolInvalidateFirstTwoBlocks(t *testing.T) { + testBcR := newTestBcR() + + tests := []struct { + name string + pool *BlockPool + poolWanted *BlockPool + }{ + { + name: "both blocks missing", + pool: makeBlockPool(testBcR, 10, + []BpPeer{{ID: "P1", Height: 100}, {ID: "P2", Height: 100}}, + map[int64]tPBlocks{15: {"P1", true}, 16: {"P2", true}}), + poolWanted: makeBlockPool(testBcR, 10, + []BpPeer{{ID: "P1", Height: 100}, {ID: "P2", Height: 100}}, + map[int64]tPBlocks{15: {"P1", true}, 16: {"P2", true}}), + }, + { + name: "second block missing", + pool: makeBlockPool(testBcR, 15, + []BpPeer{{ID: "P1", Height: 100}, {ID: "P2", Height: 100}}, + map[int64]tPBlocks{15: {"P1", true}, 18: {"P2", true}}), + poolWanted: makeBlockPool(testBcR, 15, + []BpPeer{{ID: "P2", Height: 100}}, + map[int64]tPBlocks{18: {"P2", true}}), + }, + { + name: "first block missing", + pool: makeBlockPool(testBcR, 15, + []BpPeer{{ID: "P1", Height: 100}, {ID: "P2", Height: 100}}, + map[int64]tPBlocks{18: {"P1", true}, 16: {"P2", true}}), + poolWanted: makeBlockPool(testBcR, 15, + []BpPeer{{ID: "P1", Height: 100}}, + map[int64]tPBlocks{18: {"P1", true}}), + }, + { + name: "both blocks present", + pool: makeBlockPool(testBcR, 10, + []BpPeer{{ID: "P1", Height: 100}, {ID: "P2", Height: 100}}, + map[int64]tPBlocks{10: {"P1", true}, 11: {"P2", true}}), + poolWanted: makeBlockPool(testBcR, 10, + []BpPeer{}, + map[int64]tPBlocks{}), + }, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + tt.pool.InvalidateFirstTwoBlocks(errNoPeerResponse) + assertBlockPoolEquivalent(t, tt.poolWanted, tt.pool) + }) + } +} + +func TestProcessedCurrentHeightBlock(t *testing.T) { + testBcR := newTestBcR() + + tests := []struct { + name string + pool *BlockPool + poolWanted *BlockPool + }{ + { + name: "one peer", + pool: makeBlockPool(testBcR, 100, []BpPeer{{ID: "P1", Height: 120}}, + map[int64]tPBlocks{100: {"P1", true}, 101: {"P1", true}}), + poolWanted: makeBlockPool(testBcR, 101, []BpPeer{{ID: "P1", Height: 120}}, + map[int64]tPBlocks{101: {"P1", true}}), + }, + { + name: "multiple peers", + pool: makeBlockPool(testBcR, 100, + []BpPeer{{ID: "P1", Height: 120}, {ID: "P2", Height: 120}, {ID: "P3", Height: 130}}, + map[int64]tPBlocks{ + 100: {"P1", true}, 104: {"P1", true}, 105: {"P1", false}, + 101: {"P2", true}, 103: {"P2", false}, + 102: {"P3", true}, 106: {"P3", true}}), + poolWanted: makeBlockPool(testBcR, 101, + []BpPeer{{ID: "P1", Height: 120}, {ID: "P2", Height: 120}, {ID: "P3", Height: 130}}, + map[int64]tPBlocks{ + 104: {"P1", true}, 105: {"P1", false}, + 101: {"P2", true}, 103: {"P2", false}, + 102: {"P3", true}, 106: {"P3", true}}), + }, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + tt.pool.ProcessedCurrentHeightBlock() + assertBlockPoolEquivalent(t, tt.poolWanted, tt.pool) + }) + } +} + +func TestRemovePeerAtCurrentHeight(t *testing.T) { + testBcR := newTestBcR() + + tests := []struct { + name string + pool *BlockPool + poolWanted *BlockPool + }{ + { + name: "one peer, remove peer for block at H", + pool: makeBlockPool(testBcR, 100, []BpPeer{{ID: "P1", Height: 120}}, + map[int64]tPBlocks{100: {"P1", false}, 101: {"P1", true}}), + poolWanted: makeBlockPool(testBcR, 100, []BpPeer{}, map[int64]tPBlocks{}), + }, + { + name: "one peer, remove peer for block at H+1", + pool: makeBlockPool(testBcR, 100, []BpPeer{{ID: "P1", Height: 120}}, + map[int64]tPBlocks{100: {"P1", true}, 101: {"P1", false}}), + poolWanted: makeBlockPool(testBcR, 100, []BpPeer{}, map[int64]tPBlocks{}), + }, + { + name: "multiple peers, remove peer for block at H", + pool: makeBlockPool(testBcR, 100, + []BpPeer{{ID: "P1", Height: 120}, {ID: "P2", Height: 120}, {ID: "P3", Height: 130}}, + map[int64]tPBlocks{ + 100: {"P1", false}, 104: {"P1", true}, 105: {"P1", false}, + 101: {"P2", true}, 103: {"P2", false}, + 102: {"P3", true}, 106: {"P3", true}}), + poolWanted: makeBlockPool(testBcR, 100, + []BpPeer{{ID: "P2", Height: 120}, {ID: "P3", Height: 130}}, + map[int64]tPBlocks{ + 101: {"P2", true}, 103: {"P2", false}, + 102: {"P3", true}, 106: {"P3", true}}), + }, + { + name: "multiple peers, remove peer for block at H+1", + pool: makeBlockPool(testBcR, 100, + []BpPeer{{ID: "P1", Height: 120}, {ID: "P2", Height: 120}, {ID: "P3", Height: 130}}, + map[int64]tPBlocks{ + 100: {"P1", true}, 104: {"P1", true}, 105: {"P1", false}, + 101: {"P2", false}, 103: {"P2", false}, + 102: {"P3", true}, 106: {"P3", true}}), + poolWanted: makeBlockPool(testBcR, 100, + []BpPeer{{ID: "P1", Height: 120}, {ID: "P3", Height: 130}}, + map[int64]tPBlocks{ + 100: {"P1", true}, 104: {"P1", true}, 105: {"P1", false}, + 102: {"P3", true}, 106: {"P3", true}}), + }, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + tt.pool.RemovePeerAtCurrentHeights(errNoPeerResponse) + assertBlockPoolEquivalent(t, tt.poolWanted, tt.pool) + }) + } +} diff --git a/blockchain/v1/reactor.go b/blockchain/v1/reactor.go new file mode 100644 index 000000000..2f95cebaf --- /dev/null +++ b/blockchain/v1/reactor.go @@ -0,0 +1,620 @@ +package v1 + +import ( + "errors" + "fmt" + "reflect" + "time" + + amino "github.com/tendermint/go-amino" + "github.com/tendermint/tendermint/behaviour" + "github.com/tendermint/tendermint/libs/log" + "github.com/tendermint/tendermint/p2p" + sm "github.com/tendermint/tendermint/state" + "github.com/tendermint/tendermint/store" + "github.com/tendermint/tendermint/types" +) + +const ( + // BlockchainChannel is a channel for blocks and status updates (`BlockStore` height) + BlockchainChannel = byte(0x40) + trySyncIntervalMS = 10 + trySendIntervalMS = 10 + + // ask for best height every 10s + statusUpdateIntervalSeconds = 10 + + // NOTE: keep up to date with bcBlockResponseMessage + bcBlockResponseMessagePrefixSize = 4 + bcBlockResponseMessageFieldKeySize = 1 + maxMsgSize = types.MaxBlockSizeBytes + + bcBlockResponseMessagePrefixSize + + bcBlockResponseMessageFieldKeySize +) + +var ( + // Maximum number of requests that can be pending per peer, i.e. for which requests have been sent but blocks + // have not been received. + maxRequestsPerPeer = 20 + // Maximum number of block requests for the reactor, pending or for which blocks have been received. + maxNumRequests = 64 +) + +type consensusReactor interface { + // for when we switch from blockchain reactor and fast sync to + // the consensus machine + SwitchToConsensus(sm.State, int) +} + +// BlockchainReactor handles long-term catchup syncing. +type BlockchainReactor struct { + p2p.BaseReactor + + initialState sm.State // immutable + state sm.State + + blockExec *sm.BlockExecutor + store *store.BlockStore + + fastSync bool + + fsm *BcReactorFSM + blocksSynced int + + // Receive goroutine forwards messages to this channel to be processed in the context of the poolRoutine. + messagesForFSMCh chan bcReactorMessage + + // Switch goroutine may send RemovePeer to the blockchain reactor. This is an error message that is relayed + // to this channel to be processed in the context of the poolRoutine. + errorsForFSMCh chan bcReactorMessage + + // This channel is used by the FSM and indirectly the block pool to report errors to the blockchain reactor and + // the switch. + eventsFromFSMCh chan bcFsmMessage + + swReporter *behaviour.SwitchReporter +} + +// NewBlockchainReactor returns new reactor instance. +func NewBlockchainReactor(state sm.State, blockExec *sm.BlockExecutor, store *store.BlockStore, + fastSync bool) *BlockchainReactor { + + if state.LastBlockHeight != store.Height() { + panic(fmt.Sprintf("state (%v) and store (%v) height mismatch", state.LastBlockHeight, + store.Height())) + } + + const capacity = 1000 + eventsFromFSMCh := make(chan bcFsmMessage, capacity) + messagesForFSMCh := make(chan bcReactorMessage, capacity) + errorsForFSMCh := make(chan bcReactorMessage, capacity) + + startHeight := store.Height() + 1 + bcR := &BlockchainReactor{ + initialState: state, + state: state, + blockExec: blockExec, + fastSync: fastSync, + store: store, + messagesForFSMCh: messagesForFSMCh, + eventsFromFSMCh: eventsFromFSMCh, + errorsForFSMCh: errorsForFSMCh, + } + fsm := NewFSM(startHeight, bcR) + bcR.fsm = fsm + bcR.BaseReactor = *p2p.NewBaseReactor("BlockchainReactor", bcR) + //bcR.swReporter = behaviour.NewSwitcReporter(bcR.BaseReactor.Switch) + + return bcR +} + +// bcReactorMessage is used by the reactor to send messages to the FSM. +type bcReactorMessage struct { + event bReactorEvent + data bReactorEventData +} + +type bFsmEvent uint + +const ( + // message type events + peerErrorEv = iota + 1 + syncFinishedEv +) + +type bFsmEventData struct { + peerID p2p.ID + err error +} + +// bcFsmMessage is used by the FSM to send messages to the reactor +type bcFsmMessage struct { + event bFsmEvent + data bFsmEventData +} + +// SetLogger implements cmn.Service by setting the logger on reactor and pool. +func (bcR *BlockchainReactor) SetLogger(l log.Logger) { + bcR.BaseService.Logger = l + bcR.fsm.SetLogger(l) +} + +// OnStart implements cmn.Service. +func (bcR *BlockchainReactor) OnStart() error { + bcR.swReporter = behaviour.NewSwitcReporter(bcR.BaseReactor.Switch) + if bcR.fastSync { + go bcR.poolRoutine() + } + return nil +} + +// OnStop implements cmn.Service. +func (bcR *BlockchainReactor) OnStop() { + _ = bcR.Stop() +} + +// GetChannels implements Reactor +func (bcR *BlockchainReactor) GetChannels() []*p2p.ChannelDescriptor { + return []*p2p.ChannelDescriptor{ + { + ID: BlockchainChannel, + Priority: 10, + SendQueueCapacity: 2000, + RecvBufferCapacity: 50 * 4096, + RecvMessageCapacity: maxMsgSize, + }, + } +} + +// AddPeer implements Reactor by sending our state to peer. +func (bcR *BlockchainReactor) AddPeer(peer p2p.Peer) { + msgBytes := cdc.MustMarshalBinaryBare(&bcStatusResponseMessage{bcR.store.Height()}) + if !peer.Send(BlockchainChannel, msgBytes) { + // doing nothing, will try later in `poolRoutine` + } + // peer is added to the pool once we receive the first + // bcStatusResponseMessage from the peer and call pool.updatePeer() +} + +// sendBlockToPeer loads a block and sends it to the requesting peer. +// If the block doesn't exist a bcNoBlockResponseMessage is sent. +// If all nodes are honest, no node should be requesting for a block that doesn't exist. +func (bcR *BlockchainReactor) sendBlockToPeer(msg *bcBlockRequestMessage, + src p2p.Peer) (queued bool) { + + block := bcR.store.LoadBlock(msg.Height) + if block != nil { + msgBytes := cdc.MustMarshalBinaryBare(&bcBlockResponseMessage{Block: block}) + return src.TrySend(BlockchainChannel, msgBytes) + } + + bcR.Logger.Info("peer asking for a block we don't have", "src", src, "height", msg.Height) + + msgBytes := cdc.MustMarshalBinaryBare(&bcNoBlockResponseMessage{Height: msg.Height}) + return src.TrySend(BlockchainChannel, msgBytes) +} + +func (bcR *BlockchainReactor) sendStatusResponseToPeer(msg *bcStatusRequestMessage, src p2p.Peer) (queued bool) { + msgBytes := cdc.MustMarshalBinaryBare(&bcStatusResponseMessage{bcR.store.Height()}) + return src.TrySend(BlockchainChannel, msgBytes) +} + +// RemovePeer implements Reactor by removing peer from the pool. +func (bcR *BlockchainReactor) RemovePeer(peer p2p.Peer, reason interface{}) { + msgData := bcReactorMessage{ + event: peerRemoveEv, + data: bReactorEventData{ + peerID: peer.ID(), + err: errSwitchRemovesPeer, + }, + } + bcR.errorsForFSMCh <- msgData +} + +// Receive implements Reactor by handling 4 types of messages (look below). +func (bcR *BlockchainReactor) Receive(chID byte, src p2p.Peer, msgBytes []byte) { + msg, err := decodeMsg(msgBytes) + if err != nil { + bcR.Logger.Error("error decoding message", + "src", src, "chId", chID, "msg", msg, "err", err, "bytes", msgBytes) + _ = bcR.swReporter.Report(behaviour.BadMessage(src.ID(), err.Error())) + return + } + + if err = msg.ValidateBasic(); err != nil { + bcR.Logger.Error("peer sent us invalid msg", "peer", src, "msg", msg, "err", err) + _ = bcR.swReporter.Report(behaviour.BadMessage(src.ID(), err.Error())) + return + } + + bcR.Logger.Debug("Receive", "src", src, "chID", chID, "msg", msg) + + switch msg := msg.(type) { + case *bcBlockRequestMessage: + if queued := bcR.sendBlockToPeer(msg, src); !queued { + // Unfortunately not queued since the queue is full. + bcR.Logger.Error("Could not send block message to peer", "src", src, "height", msg.Height) + } + + case *bcStatusRequestMessage: + // Send peer our state. + if queued := bcR.sendStatusResponseToPeer(msg, src); !queued { + // Unfortunately not queued since the queue is full. + bcR.Logger.Error("Could not send status message to peer", "src", src) + } + + case *bcBlockResponseMessage: + msgForFSM := bcReactorMessage{ + event: blockResponseEv, + data: bReactorEventData{ + peerID: src.ID(), + height: msg.Block.Height, + block: msg.Block, + length: len(msgBytes), + }, + } + bcR.Logger.Info("Received", "src", src, "height", msg.Block.Height) + bcR.messagesForFSMCh <- msgForFSM + + case *bcStatusResponseMessage: + // Got a peer status. Unverified. + msgForFSM := bcReactorMessage{ + event: statusResponseEv, + data: bReactorEventData{ + peerID: src.ID(), + height: msg.Height, + length: len(msgBytes), + }, + } + bcR.messagesForFSMCh <- msgForFSM + + default: + bcR.Logger.Error(fmt.Sprintf("unknown message type %v", reflect.TypeOf(msg))) + } +} + +// processBlocksRoutine processes blocks until signlaed to stop over the stopProcessing channel +func (bcR *BlockchainReactor) processBlocksRoutine(stopProcessing chan struct{}) { + + processReceivedBlockTicker := time.NewTicker(trySyncIntervalMS * time.Millisecond) + doProcessBlockCh := make(chan struct{}, 1) + + lastHundred := time.Now() + lastRate := 0.0 + +ForLoop: + for { + select { + case <-stopProcessing: + bcR.Logger.Info("finishing block execution") + break ForLoop + case <-processReceivedBlockTicker.C: // try to execute blocks + select { + case doProcessBlockCh <- struct{}{}: + default: + } + case <-doProcessBlockCh: + for { + err := bcR.processBlock() + if err == errMissingBlock { + break + } + // Notify FSM of block processing result. + msgForFSM := bcReactorMessage{ + event: processedBlockEv, + data: bReactorEventData{ + err: err, + }, + } + _ = bcR.fsm.Handle(&msgForFSM) + + if err != nil { + break + } + + bcR.blocksSynced++ + if bcR.blocksSynced%100 == 0 { + lastRate = 0.9*lastRate + 0.1*(100/time.Since(lastHundred).Seconds()) + height, maxPeerHeight := bcR.fsm.Status() + bcR.Logger.Info("Fast Sync Rate", "height", height, + "max_peer_height", maxPeerHeight, "blocks/s", lastRate) + lastHundred = time.Now() + } + } + } + } +} + +// poolRoutine receives and handles messages from the Receive() routine and from the FSM. +func (bcR *BlockchainReactor) poolRoutine() { + + bcR.fsm.Start() + + sendBlockRequestTicker := time.NewTicker(trySendIntervalMS * time.Millisecond) + statusUpdateTicker := time.NewTicker(statusUpdateIntervalSeconds * time.Second) + + stopProcessing := make(chan struct{}, 1) + go bcR.processBlocksRoutine(stopProcessing) + +ForLoop: + for { + select { + + case <-sendBlockRequestTicker.C: + if !bcR.fsm.NeedsBlocks() { + continue + } + _ = bcR.fsm.Handle(&bcReactorMessage{ + event: makeRequestsEv, + data: bReactorEventData{ + maxNumRequests: maxNumRequests}}) + + case <-statusUpdateTicker.C: + // Ask for status updates. + go bcR.sendStatusRequest() + + case msg := <-bcR.messagesForFSMCh: + // Sent from the Receive() routine when status (statusResponseEv) and + // block (blockResponseEv) response events are received + _ = bcR.fsm.Handle(&msg) + + case msg := <-bcR.errorsForFSMCh: + // Sent from the switch.RemovePeer() routine (RemovePeerEv) and + // FSM state timer expiry routine (stateTimeoutEv). + _ = bcR.fsm.Handle(&msg) + + case msg := <-bcR.eventsFromFSMCh: + switch msg.event { + case syncFinishedEv: + stopProcessing <- struct{}{} + // Sent from the FSM when it enters finished state. + break ForLoop + case peerErrorEv: + // Sent from the FSM when it detects peer error + bcR.reportPeerErrorToSwitch(msg.data.err, msg.data.peerID) + if msg.data.err == errNoPeerResponse { + // Sent from the peer timeout handler routine + _ = bcR.fsm.Handle(&bcReactorMessage{ + event: peerRemoveEv, + data: bReactorEventData{ + peerID: msg.data.peerID, + err: msg.data.err, + }, + }) + } else { + // For slow peers, or errors due to blocks received from wrong peer + // the FSM had already removed the peers + } + default: + bcR.Logger.Error("Event from FSM not supported", "type", msg.event) + } + + case <-bcR.Quit(): + break ForLoop + } + } +} + +func (bcR *BlockchainReactor) reportPeerErrorToSwitch(err error, peerID p2p.ID) { + peer := bcR.Switch.Peers().Get(peerID) + if peer != nil { + _ = bcR.swReporter.Report(behaviour.BadMessage(peerID, err.Error())) + } +} + +func (bcR *BlockchainReactor) processBlock() error { + + first, second, err := bcR.fsm.FirstTwoBlocks() + if err != nil { + // We need both to sync the first block. + return err + } + + chainID := bcR.initialState.ChainID + + firstParts := first.MakePartSet(types.BlockPartSizeBytes) + firstPartsHeader := firstParts.Header() + firstID := types.BlockID{Hash: first.Hash(), PartsHeader: firstPartsHeader} + // Finally, verify the first block using the second's commit + // NOTE: we can probably make this more efficient, but note that calling + // first.Hash() doesn't verify the tx contents, so MakePartSet() is + // currently necessary. + err = bcR.state.Validators.VerifyCommit(chainID, firstID, first.Height, second.LastCommit) + if err != nil { + bcR.Logger.Error("error during commit verification", "err", err, + "first", first.Height, "second", second.Height) + return errBlockVerificationFailure + } + + bcR.store.SaveBlock(first, firstParts, second.LastCommit) + + bcR.state, err = bcR.blockExec.ApplyBlock(bcR.state, firstID, first) + if err != nil { + panic(fmt.Sprintf("failed to process committed block (%d:%X): %v", first.Height, first.Hash(), err)) + } + + return nil +} + +// Implements bcRNotifier +// sendStatusRequest broadcasts `BlockStore` height. +func (bcR *BlockchainReactor) sendStatusRequest() { + msgBytes := cdc.MustMarshalBinaryBare(&bcStatusRequestMessage{bcR.store.Height()}) + bcR.Switch.Broadcast(BlockchainChannel, msgBytes) +} + +// Implements bcRNotifier +// BlockRequest sends `BlockRequest` height. +func (bcR *BlockchainReactor) sendBlockRequest(peerID p2p.ID, height int64) error { + peer := bcR.Switch.Peers().Get(peerID) + if peer == nil { + return errNilPeerForBlockRequest + } + + msgBytes := cdc.MustMarshalBinaryBare(&bcBlockRequestMessage{height}) + queued := peer.TrySend(BlockchainChannel, msgBytes) + if !queued { + return errSendQueueFull + } + return nil +} + +// Implements bcRNotifier +func (bcR *BlockchainReactor) switchToConsensus() { + conR, ok := bcR.Switch.Reactor("CONSENSUS").(consensusReactor) + if ok { + conR.SwitchToConsensus(bcR.state, bcR.blocksSynced) + bcR.eventsFromFSMCh <- bcFsmMessage{event: syncFinishedEv} + } else { + // Should only happen during testing. + } +} + +// Implements bcRNotifier +// Called by FSM and pool: +// - pool calls when it detects slow peer or when peer times out +// - FSM calls when: +// - adding a block (addBlock) fails +// - reactor processing of a block reports failure and FSM sends back the peers of first and second blocks +func (bcR *BlockchainReactor) sendPeerError(err error, peerID p2p.ID) { + bcR.Logger.Info("sendPeerError:", "peer", peerID, "error", err) + msgData := bcFsmMessage{ + event: peerErrorEv, + data: bFsmEventData{ + peerID: peerID, + err: err, + }, + } + bcR.eventsFromFSMCh <- msgData +} + +// Implements bcRNotifier +func (bcR *BlockchainReactor) resetStateTimer(name string, timer **time.Timer, timeout time.Duration) { + if timer == nil { + panic("nil timer pointer parameter") + } + if *timer == nil { + *timer = time.AfterFunc(timeout, func() { + msg := bcReactorMessage{ + event: stateTimeoutEv, + data: bReactorEventData{ + stateName: name, + }, + } + bcR.errorsForFSMCh <- msg + }) + } else { + (*timer).Reset(timeout) + } +} + +//----------------------------------------------------------------------------- +// Messages + +// BlockchainMessage is a generic message for this reactor. +type BlockchainMessage interface { + ValidateBasic() error +} + +// RegisterBlockchainMessages registers the fast sync messages for amino encoding. +func RegisterBlockchainMessages(cdc *amino.Codec) { + cdc.RegisterInterface((*BlockchainMessage)(nil), nil) + cdc.RegisterConcrete(&bcBlockRequestMessage{}, "tendermint/blockchain/BlockRequest", nil) + cdc.RegisterConcrete(&bcBlockResponseMessage{}, "tendermint/blockchain/BlockResponse", nil) + cdc.RegisterConcrete(&bcNoBlockResponseMessage{}, "tendermint/blockchain/NoBlockResponse", nil) + cdc.RegisterConcrete(&bcStatusResponseMessage{}, "tendermint/blockchain/StatusResponse", nil) + cdc.RegisterConcrete(&bcStatusRequestMessage{}, "tendermint/blockchain/StatusRequest", nil) +} + +func decodeMsg(bz []byte) (msg BlockchainMessage, err error) { + if len(bz) > maxMsgSize { + return msg, fmt.Errorf("msg exceeds max size (%d > %d)", len(bz), maxMsgSize) + } + err = cdc.UnmarshalBinaryBare(bz, &msg) + return +} + +//------------------------------------- + +type bcBlockRequestMessage struct { + Height int64 +} + +// ValidateBasic performs basic validation. +func (m *bcBlockRequestMessage) ValidateBasic() error { + if m.Height < 0 { + return errors.New("negative Height") + } + return nil +} + +func (m *bcBlockRequestMessage) String() string { + return fmt.Sprintf("[bcBlockRequestMessage %v]", m.Height) +} + +type bcNoBlockResponseMessage struct { + Height int64 +} + +// ValidateBasic performs basic validation. +func (m *bcNoBlockResponseMessage) ValidateBasic() error { + if m.Height < 0 { + return errors.New("negative Height") + } + return nil +} + +func (m *bcNoBlockResponseMessage) String() string { + return fmt.Sprintf("[bcNoBlockResponseMessage %d]", m.Height) +} + +//------------------------------------- + +type bcBlockResponseMessage struct { + Block *types.Block +} + +// ValidateBasic performs basic validation. +func (m *bcBlockResponseMessage) ValidateBasic() error { + return m.Block.ValidateBasic() +} + +func (m *bcBlockResponseMessage) String() string { + return fmt.Sprintf("[bcBlockResponseMessage %v]", m.Block.Height) +} + +//------------------------------------- + +type bcStatusRequestMessage struct { + Height int64 +} + +// ValidateBasic performs basic validation. +func (m *bcStatusRequestMessage) ValidateBasic() error { + if m.Height < 0 { + return errors.New("negative Height") + } + return nil +} + +func (m *bcStatusRequestMessage) String() string { + return fmt.Sprintf("[bcStatusRequestMessage %v]", m.Height) +} + +//------------------------------------- + +type bcStatusResponseMessage struct { + Height int64 +} + +// ValidateBasic performs basic validation. +func (m *bcStatusResponseMessage) ValidateBasic() error { + if m.Height < 0 { + return errors.New("negative Height") + } + return nil +} + +func (m *bcStatusResponseMessage) String() string { + return fmt.Sprintf("[bcStatusResponseMessage %v]", m.Height) +} diff --git a/blockchain/v1/reactor_fsm.go b/blockchain/v1/reactor_fsm.go new file mode 100644 index 000000000..4bfef64ea --- /dev/null +++ b/blockchain/v1/reactor_fsm.go @@ -0,0 +1,450 @@ +package v1 + +import ( + "errors" + "fmt" + "sync" + "time" + + "github.com/tendermint/tendermint/libs/log" + "github.com/tendermint/tendermint/p2p" + "github.com/tendermint/tendermint/types" +) + +// Blockchain Reactor State +type bcReactorFSMState struct { + name string + + // called when transitioning out of current state + handle func(*BcReactorFSM, bReactorEvent, bReactorEventData) (next *bcReactorFSMState, err error) + // called when entering the state + enter func(fsm *BcReactorFSM) + + // timeout to ensure FSM is not stuck in a state forever + // the timer is owned and run by the fsm instance + timeout time.Duration +} + +func (s *bcReactorFSMState) String() string { + return s.name +} + +// BcReactorFSM is the datastructure for the Blockchain Reactor State Machine +type BcReactorFSM struct { + logger log.Logger + mtx sync.Mutex + + startTime time.Time + + state *bcReactorFSMState + stateTimer *time.Timer + pool *BlockPool + + // interface used to call the Blockchain reactor to send StatusRequest, BlockRequest, reporting errors, etc. + toBcR bcReactor +} + +// NewFSM creates a new reactor FSM. +func NewFSM(height int64, toBcR bcReactor) *BcReactorFSM { + return &BcReactorFSM{ + state: unknown, + startTime: time.Now(), + pool: NewBlockPool(height, toBcR), + toBcR: toBcR, + } +} + +// bReactorEventData is part of the message sent by the reactor to the FSM and used by the state handlers. +type bReactorEventData struct { + peerID p2p.ID + err error // for peer error: timeout, slow; for processed block event if error occurred + height int64 // for status response; for processed block event + block *types.Block // for block response + stateName string // for state timeout events + length int // for block response event, length of received block, used to detect slow peers + maxNumRequests int // for request needed event, maximum number of pending requests +} + +// Blockchain Reactor Events (the input to the state machine) +type bReactorEvent uint + +const ( + // message type events + startFSMEv = iota + 1 + statusResponseEv + blockResponseEv + processedBlockEv + makeRequestsEv + stopFSMEv + + // other events + peerRemoveEv = iota + 256 + stateTimeoutEv +) + +func (msg *bcReactorMessage) String() string { + var dataStr string + + switch msg.event { + case startFSMEv: + dataStr = "" + case statusResponseEv: + dataStr = fmt.Sprintf("peer=%v height=%v", msg.data.peerID, msg.data.height) + case blockResponseEv: + dataStr = fmt.Sprintf("peer=%v block.height=%v length=%v", + msg.data.peerID, msg.data.block.Height, msg.data.length) + case processedBlockEv: + dataStr = fmt.Sprintf("error=%v", msg.data.err) + case makeRequestsEv: + dataStr = "" + case stopFSMEv: + dataStr = "" + case peerRemoveEv: + dataStr = fmt.Sprintf("peer: %v is being removed by the switch", msg.data.peerID) + case stateTimeoutEv: + dataStr = fmt.Sprintf("state=%v", msg.data.stateName) + default: + dataStr = fmt.Sprintf("cannot interpret message data") + } + + return fmt.Sprintf("%v: %v", msg.event, dataStr) +} + +func (ev bReactorEvent) String() string { + switch ev { + case startFSMEv: + return "startFSMEv" + case statusResponseEv: + return "statusResponseEv" + case blockResponseEv: + return "blockResponseEv" + case processedBlockEv: + return "processedBlockEv" + case makeRequestsEv: + return "makeRequestsEv" + case stopFSMEv: + return "stopFSMEv" + case peerRemoveEv: + return "peerRemoveEv" + case stateTimeoutEv: + return "stateTimeoutEv" + default: + return "event unknown" + } + +} + +// states +var ( + unknown *bcReactorFSMState + waitForPeer *bcReactorFSMState + waitForBlock *bcReactorFSMState + finished *bcReactorFSMState +) + +// timeouts for state timers +const ( + waitForPeerTimeout = 3 * time.Second + waitForBlockAtCurrentHeightTimeout = 10 * time.Second +) + +// errors +var ( + // internal to the package + errNoErrorFinished = errors.New("fast sync is finished") + errInvalidEvent = errors.New("invalid event in current state") + errMissingBlock = errors.New("missing blocks") + errNilPeerForBlockRequest = errors.New("peer for block request does not exist in the switch") + errSendQueueFull = errors.New("block request not made, send-queue is full") + errPeerTooShort = errors.New("peer height too low, old peer removed/ new peer not added") + errSwitchRemovesPeer = errors.New("switch is removing peer") + errTimeoutEventWrongState = errors.New("timeout event for a state different than the current one") + errNoTallerPeer = errors.New("fast sync timed out on waiting for a peer taller than this node") + + // reported eventually to the switch + errPeerLowersItsHeight = errors.New("fast sync peer reports a height lower than previous") // handle return + errNoPeerResponseForCurrentHeights = errors.New("fast sync timed out on peer block response for current heights") // handle return + errNoPeerResponse = errors.New("fast sync timed out on peer block response") // xx + errBadDataFromPeer = errors.New("fast sync received block from wrong peer or block is bad") // xx + errDuplicateBlock = errors.New("fast sync received duplicate block from peer") + errBlockVerificationFailure = errors.New("fast sync block verification failure") // xx + errSlowPeer = errors.New("fast sync peer is not sending us data fast enough") // xx + +) + +func init() { + unknown = &bcReactorFSMState{ + name: "unknown", + handle: func(fsm *BcReactorFSM, ev bReactorEvent, data bReactorEventData) (*bcReactorFSMState, error) { + switch ev { + case startFSMEv: + // Broadcast Status message. Currently doesn't return non-nil error. + fsm.toBcR.sendStatusRequest() + return waitForPeer, nil + + case stopFSMEv: + return finished, errNoErrorFinished + + default: + return unknown, errInvalidEvent + } + }, + } + + waitForPeer = &bcReactorFSMState{ + name: "waitForPeer", + timeout: waitForPeerTimeout, + enter: func(fsm *BcReactorFSM) { + // Stop when leaving the state. + fsm.resetStateTimer() + }, + handle: func(fsm *BcReactorFSM, ev bReactorEvent, data bReactorEventData) (*bcReactorFSMState, error) { + switch ev { + case stateTimeoutEv: + if data.stateName != "waitForPeer" { + fsm.logger.Error("received a state timeout event for different state", + "state", data.stateName) + return waitForPeer, errTimeoutEventWrongState + } + // There was no statusResponse received from any peer. + // Should we send status request again? + return finished, errNoTallerPeer + + case statusResponseEv: + if err := fsm.pool.UpdatePeer(data.peerID, data.height); err != nil { + if fsm.pool.NumPeers() == 0 { + return waitForPeer, err + } + } + if fsm.stateTimer != nil { + fsm.stateTimer.Stop() + } + return waitForBlock, nil + + case stopFSMEv: + if fsm.stateTimer != nil { + fsm.stateTimer.Stop() + } + return finished, errNoErrorFinished + + default: + return waitForPeer, errInvalidEvent + } + }, + } + + waitForBlock = &bcReactorFSMState{ + name: "waitForBlock", + timeout: waitForBlockAtCurrentHeightTimeout, + enter: func(fsm *BcReactorFSM) { + // Stop when leaving the state. + fsm.resetStateTimer() + }, + handle: func(fsm *BcReactorFSM, ev bReactorEvent, data bReactorEventData) (*bcReactorFSMState, error) { + switch ev { + + case statusResponseEv: + err := fsm.pool.UpdatePeer(data.peerID, data.height) + if fsm.pool.NumPeers() == 0 { + return waitForPeer, err + } + if fsm.pool.ReachedMaxHeight() { + return finished, err + } + return waitForBlock, err + + case blockResponseEv: + fsm.logger.Debug("blockResponseEv", "H", data.block.Height) + err := fsm.pool.AddBlock(data.peerID, data.block, data.length) + if err != nil { + // A block was received that was unsolicited, from unexpected peer, or that we already have it. + // Ignore block, remove peer and send error to switch. + fsm.pool.RemovePeer(data.peerID, err) + fsm.toBcR.sendPeerError(err, data.peerID) + } + if fsm.pool.NumPeers() == 0 { + return waitForPeer, err + } + return waitForBlock, err + + case processedBlockEv: + if data.err != nil { + first, second, _ := fsm.pool.FirstTwoBlocksAndPeers() + fsm.logger.Error("error processing block", "err", data.err, + "first", first.block.Height, "second", second.block.Height) + fsm.logger.Error("send peer error for", "peer", first.peer.ID) + fsm.toBcR.sendPeerError(data.err, first.peer.ID) + fsm.logger.Error("send peer error for", "peer", second.peer.ID) + fsm.toBcR.sendPeerError(data.err, second.peer.ID) + // Remove the first two blocks. This will also remove the peers + fsm.pool.InvalidateFirstTwoBlocks(data.err) + } else { + fsm.pool.ProcessedCurrentHeightBlock() + // Since we advanced one block reset the state timer + fsm.resetStateTimer() + } + + // Both cases above may result in achieving maximum height. + if fsm.pool.ReachedMaxHeight() { + return finished, nil + } + + return waitForBlock, data.err + + case peerRemoveEv: + // This event is sent by the switch to remove disconnected and errored peers. + fsm.pool.RemovePeer(data.peerID, data.err) + if fsm.pool.NumPeers() == 0 { + return waitForPeer, nil + } + if fsm.pool.ReachedMaxHeight() { + return finished, nil + } + return waitForBlock, nil + + case makeRequestsEv: + fsm.makeNextRequests(data.maxNumRequests) + return waitForBlock, nil + + case stateTimeoutEv: + if data.stateName != "waitForBlock" { + fsm.logger.Error("received a state timeout event for different state", + "state", data.stateName) + return waitForBlock, errTimeoutEventWrongState + } + // We haven't received the block at current height or height+1. Remove peer. + fsm.pool.RemovePeerAtCurrentHeights(errNoPeerResponseForCurrentHeights) + fsm.resetStateTimer() + if fsm.pool.NumPeers() == 0 { + return waitForPeer, errNoPeerResponseForCurrentHeights + } + if fsm.pool.ReachedMaxHeight() { + return finished, nil + } + return waitForBlock, errNoPeerResponseForCurrentHeights + + case stopFSMEv: + if fsm.stateTimer != nil { + fsm.stateTimer.Stop() + } + return finished, errNoErrorFinished + + default: + return waitForBlock, errInvalidEvent + } + }, + } + + finished = &bcReactorFSMState{ + name: "finished", + enter: func(fsm *BcReactorFSM) { + fsm.logger.Info("Time to switch to consensus reactor!", "height", fsm.pool.Height) + fsm.toBcR.switchToConsensus() + fsm.cleanup() + }, + handle: func(fsm *BcReactorFSM, ev bReactorEvent, data bReactorEventData) (*bcReactorFSMState, error) { + return finished, nil + }, + } +} + +// Interface used by FSM for sending Block and Status requests, +// informing of peer errors and state timeouts +// Implemented by BlockchainReactor and tests +type bcReactor interface { + sendStatusRequest() + sendBlockRequest(peerID p2p.ID, height int64) error + sendPeerError(err error, peerID p2p.ID) + resetStateTimer(name string, timer **time.Timer, timeout time.Duration) + switchToConsensus() +} + +// SetLogger sets the FSM logger. +func (fsm *BcReactorFSM) SetLogger(l log.Logger) { + fsm.logger = l + fsm.pool.SetLogger(l) +} + +// Start starts the FSM. +func (fsm *BcReactorFSM) Start() { + _ = fsm.Handle(&bcReactorMessage{event: startFSMEv}) +} + +// Handle processes messages and events sent to the FSM. +func (fsm *BcReactorFSM) Handle(msg *bcReactorMessage) error { + fsm.mtx.Lock() + defer fsm.mtx.Unlock() + fsm.logger.Debug("FSM received", "event", msg, "state", fsm.state) + + if fsm.state == nil { + fsm.state = unknown + } + next, err := fsm.state.handle(fsm, msg.event, msg.data) + if err != nil { + fsm.logger.Error("FSM event handler returned", "err", err, + "state", fsm.state, "event", msg.event) + } + + oldState := fsm.state.name + fsm.transition(next) + if oldState != fsm.state.name { + fsm.logger.Info("FSM changed state", "new_state", fsm.state) + } + return err +} + +func (fsm *BcReactorFSM) transition(next *bcReactorFSMState) { + if next == nil { + return + } + if fsm.state != next { + fsm.state = next + if next.enter != nil { + next.enter(fsm) + } + } +} + +// Called when entering an FSM state in order to detect lack of progress in the state machine. +// Note the use of the 'bcr' interface to facilitate testing without timer expiring. +func (fsm *BcReactorFSM) resetStateTimer() { + fsm.toBcR.resetStateTimer(fsm.state.name, &fsm.stateTimer, fsm.state.timeout) +} + +func (fsm *BcReactorFSM) isCaughtUp() bool { + return fsm.state == finished +} + +func (fsm *BcReactorFSM) makeNextRequests(maxNumRequests int) { + fsm.pool.MakeNextRequests(maxNumRequests) +} + +func (fsm *BcReactorFSM) cleanup() { + fsm.pool.Cleanup() +} + +// NeedsBlocks checks if more block requests are required. +func (fsm *BcReactorFSM) NeedsBlocks() bool { + fsm.mtx.Lock() + defer fsm.mtx.Unlock() + return fsm.state.name == "waitForBlock" && fsm.pool.NeedsBlocks() +} + +// FirstTwoBlocks returns the two blocks at pool height and height+1 +func (fsm *BcReactorFSM) FirstTwoBlocks() (first, second *types.Block, err error) { + fsm.mtx.Lock() + defer fsm.mtx.Unlock() + firstBP, secondBP, err := fsm.pool.FirstTwoBlocksAndPeers() + if err == nil { + first = firstBP.block + second = secondBP.block + } + return +} + +// Status returns the pool's height and the maximum peer height. +func (fsm *BcReactorFSM) Status() (height, maxPeerHeight int64) { + fsm.mtx.Lock() + defer fsm.mtx.Unlock() + return fsm.pool.Height, fsm.pool.MaxPeerHeight +} diff --git a/blockchain/v1/reactor_fsm_test.go b/blockchain/v1/reactor_fsm_test.go new file mode 100644 index 000000000..54e177f25 --- /dev/null +++ b/blockchain/v1/reactor_fsm_test.go @@ -0,0 +1,938 @@ +package v1 + +import ( + "fmt" + "testing" + "time" + + "github.com/stretchr/testify/assert" + cmn "github.com/tendermint/tendermint/libs/common" + "github.com/tendermint/tendermint/libs/log" + "github.com/tendermint/tendermint/p2p" + "github.com/tendermint/tendermint/types" +) + +type lastBlockRequestT struct { + peerID p2p.ID + height int64 +} + +type lastPeerErrorT struct { + peerID p2p.ID + err error +} + +// reactor for FSM testing +type testReactor struct { + logger log.Logger + fsm *BcReactorFSM + numStatusRequests int + numBlockRequests int + lastBlockRequest lastBlockRequestT + lastPeerError lastPeerErrorT + stateTimerStarts map[string]int +} + +func sendEventToFSM(fsm *BcReactorFSM, ev bReactorEvent, data bReactorEventData) error { + return fsm.Handle(&bcReactorMessage{event: ev, data: data}) +} + +type fsmStepTestValues struct { + currentState string + event bReactorEvent + data bReactorEventData + + wantErr error + wantState string + wantStatusReqSent bool + wantReqIncreased bool + wantNewBlocks []int64 + wantRemovedPeers []p2p.ID +} + +// --------------------------------------------------------------------------- +// helper test function for different FSM events, state and expected behavior +func sStopFSMEv(current, expected string) fsmStepTestValues { + return fsmStepTestValues{ + currentState: current, + event: stopFSMEv, + wantState: expected, + wantErr: errNoErrorFinished} +} + +func sUnknownFSMEv(current string) fsmStepTestValues { + return fsmStepTestValues{ + currentState: current, + event: 1234, + wantState: current, + wantErr: errInvalidEvent} +} + +func sStartFSMEv() fsmStepTestValues { + return fsmStepTestValues{ + currentState: "unknown", + event: startFSMEv, + wantState: "waitForPeer", + wantStatusReqSent: true} +} + +func sStateTimeoutEv(current, expected string, timedoutState string, wantErr error) fsmStepTestValues { + return fsmStepTestValues{ + currentState: current, + event: stateTimeoutEv, + data: bReactorEventData{ + stateName: timedoutState, + }, + wantState: expected, + wantErr: wantErr, + } +} + +func sProcessedBlockEv(current, expected string, reactorError error) fsmStepTestValues { + return fsmStepTestValues{ + currentState: current, + event: processedBlockEv, + data: bReactorEventData{ + err: reactorError, + }, + wantState: expected, + wantErr: reactorError, + } +} + +func sStatusEv(current, expected string, peerID p2p.ID, height int64, err error) fsmStepTestValues { + return fsmStepTestValues{ + currentState: current, + event: statusResponseEv, + data: bReactorEventData{peerID: peerID, height: height}, + wantState: expected, + wantErr: err} +} + +func sMakeRequestsEv(current, expected string, maxPendingRequests int) fsmStepTestValues { + return fsmStepTestValues{ + currentState: current, + event: makeRequestsEv, + data: bReactorEventData{maxNumRequests: maxPendingRequests}, + wantState: expected, + wantReqIncreased: true, + } +} + +func sMakeRequestsEvErrored(current, expected string, + maxPendingRequests int, err error, peersRemoved []p2p.ID) fsmStepTestValues { + return fsmStepTestValues{ + currentState: current, + event: makeRequestsEv, + data: bReactorEventData{maxNumRequests: maxPendingRequests}, + wantState: expected, + wantErr: err, + wantRemovedPeers: peersRemoved, + wantReqIncreased: true, + } +} + +func sBlockRespEv(current, expected string, peerID p2p.ID, height int64, prevBlocks []int64) fsmStepTestValues { + txs := []types.Tx{types.Tx("foo"), types.Tx("bar")} + return fsmStepTestValues{ + currentState: current, + event: blockResponseEv, + data: bReactorEventData{ + peerID: peerID, + height: height, + block: types.MakeBlock(int64(height), txs, nil, nil), + length: 100}, + wantState: expected, + wantNewBlocks: append(prevBlocks, height), + } +} + +func sBlockRespEvErrored(current, expected string, + peerID p2p.ID, height int64, prevBlocks []int64, wantErr error, peersRemoved []p2p.ID) fsmStepTestValues { + txs := []types.Tx{types.Tx("foo"), types.Tx("bar")} + + return fsmStepTestValues{ + currentState: current, + event: blockResponseEv, + data: bReactorEventData{ + peerID: peerID, + height: height, + block: types.MakeBlock(int64(height), txs, nil, nil), + length: 100}, + wantState: expected, + wantErr: wantErr, + wantRemovedPeers: peersRemoved, + wantNewBlocks: prevBlocks, + } +} + +func sPeerRemoveEv(current, expected string, peerID p2p.ID, err error, peersRemoved []p2p.ID) fsmStepTestValues { + return fsmStepTestValues{ + currentState: current, + event: peerRemoveEv, + data: bReactorEventData{ + peerID: peerID, + err: err, + }, + wantState: expected, + wantRemovedPeers: peersRemoved, + } +} + +// -------------------------------------------- + +func newTestReactor(height int64) *testReactor { + testBcR := &testReactor{logger: log.TestingLogger(), stateTimerStarts: make(map[string]int)} + testBcR.fsm = NewFSM(height, testBcR) + testBcR.fsm.SetLogger(testBcR.logger) + return testBcR +} + +func fixBlockResponseEvStep(step *fsmStepTestValues, testBcR *testReactor) { + // There is currently no good way to know to which peer a block request was sent. + // So in some cases where it does not matter, before we simulate a block response + // we cheat and look where it is expected from. + if step.event == blockResponseEv { + height := step.data.height + peerID, ok := testBcR.fsm.pool.blocks[height] + if ok { + step.data.peerID = peerID + } + } +} + +type testFields struct { + name string + startingHeight int64 + maxRequestsPerPeer int + maxPendingRequests int + steps []fsmStepTestValues +} + +func executeFSMTests(t *testing.T, tests []testFields, matchRespToReq bool) { + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + // Create test reactor + testBcR := newTestReactor(tt.startingHeight) + + if tt.maxRequestsPerPeer != 0 { + maxRequestsPerPeer = tt.maxRequestsPerPeer + } + + for _, step := range tt.steps { + assert.Equal(t, step.currentState, testBcR.fsm.state.name) + + var heightBefore int64 + if step.event == processedBlockEv && step.data.err == errBlockVerificationFailure { + heightBefore = testBcR.fsm.pool.Height + } + oldNumStatusRequests := testBcR.numStatusRequests + oldNumBlockRequests := testBcR.numBlockRequests + if matchRespToReq { + fixBlockResponseEvStep(&step, testBcR) + } + + fsmErr := sendEventToFSM(testBcR.fsm, step.event, step.data) + assert.Equal(t, step.wantErr, fsmErr) + + if step.wantStatusReqSent { + assert.Equal(t, oldNumStatusRequests+1, testBcR.numStatusRequests) + } else { + assert.Equal(t, oldNumStatusRequests, testBcR.numStatusRequests) + } + + if step.wantReqIncreased { + assert.True(t, oldNumBlockRequests < testBcR.numBlockRequests) + } else { + assert.Equal(t, oldNumBlockRequests, testBcR.numBlockRequests) + } + + for _, height := range step.wantNewBlocks { + _, err := testBcR.fsm.pool.BlockAndPeerAtHeight(height) + assert.Nil(t, err) + } + if step.event == processedBlockEv && step.data.err == errBlockVerificationFailure { + heightAfter := testBcR.fsm.pool.Height + assert.Equal(t, heightBefore, heightAfter) + firstAfter, err1 := testBcR.fsm.pool.BlockAndPeerAtHeight(testBcR.fsm.pool.Height) + secondAfter, err2 := testBcR.fsm.pool.BlockAndPeerAtHeight(testBcR.fsm.pool.Height + 1) + assert.NotNil(t, err1) + assert.NotNil(t, err2) + assert.Nil(t, firstAfter) + assert.Nil(t, secondAfter) + } + + assert.Equal(t, step.wantState, testBcR.fsm.state.name) + + if step.wantState == "finished" { + assert.True(t, testBcR.fsm.isCaughtUp()) + } + } + }) + } +} + +func TestFSMBasic(t *testing.T) { + tests := []testFields{ + { + name: "one block, one peer - TS2", + startingHeight: 1, + maxRequestsPerPeer: 2, + steps: []fsmStepTestValues{ + sStartFSMEv(), + sStatusEv("waitForPeer", "waitForBlock", "P1", 2, nil), + sMakeRequestsEv("waitForBlock", "waitForBlock", maxNumRequests), + sBlockRespEv("waitForBlock", "waitForBlock", "P1", 1, []int64{}), + sBlockRespEv("waitForBlock", "waitForBlock", "P2", 2, []int64{1}), + sProcessedBlockEv("waitForBlock", "finished", nil), + }, + }, + { + name: "multi block, multi peer - TS2", + startingHeight: 1, + maxRequestsPerPeer: 2, + steps: []fsmStepTestValues{ + sStartFSMEv(), + sStatusEv("waitForPeer", "waitForBlock", "P1", 4, nil), + sStatusEv("waitForBlock", "waitForBlock", "P2", 4, nil), + sMakeRequestsEv("waitForBlock", "waitForBlock", maxNumRequests), + + sBlockRespEv("waitForBlock", "waitForBlock", "P1", 1, []int64{}), + sBlockRespEv("waitForBlock", "waitForBlock", "P1", 2, []int64{1}), + sBlockRespEv("waitForBlock", "waitForBlock", "P2", 3, []int64{1, 2}), + sBlockRespEv("waitForBlock", "waitForBlock", "P2", 4, []int64{1, 2, 3}), + + sProcessedBlockEv("waitForBlock", "waitForBlock", nil), + sProcessedBlockEv("waitForBlock", "waitForBlock", nil), + sProcessedBlockEv("waitForBlock", "finished", nil), + }, + }, + } + + executeFSMTests(t, tests, true) +} + +func TestFSMBlockVerificationFailure(t *testing.T) { + tests := []testFields{ + { + name: "block verification failure - TS2 variant", + startingHeight: 1, + maxRequestsPerPeer: 3, + steps: []fsmStepTestValues{ + sStartFSMEv(), + + // add P1 and get blocks 1-3 from it + sStatusEv("waitForPeer", "waitForBlock", "P1", 3, nil), + sMakeRequestsEv("waitForBlock", "waitForBlock", maxNumRequests), + sBlockRespEv("waitForBlock", "waitForBlock", "P1", 1, []int64{}), + sBlockRespEv("waitForBlock", "waitForBlock", "P1", 2, []int64{1}), + sBlockRespEv("waitForBlock", "waitForBlock", "P1", 3, []int64{1, 2}), + + // add P2 + sStatusEv("waitForBlock", "waitForBlock", "P2", 3, nil), + + // process block failure, should remove P1 and all blocks + sProcessedBlockEv("waitForBlock", "waitForBlock", errBlockVerificationFailure), + + // get blocks 1-3 from P2 + sMakeRequestsEv("waitForBlock", "waitForBlock", maxNumRequests), + sBlockRespEv("waitForBlock", "waitForBlock", "P2", 1, []int64{}), + sBlockRespEv("waitForBlock", "waitForBlock", "P2", 2, []int64{1}), + sBlockRespEv("waitForBlock", "waitForBlock", "P2", 3, []int64{1, 2}), + + // finish after processing blocks 1 and 2 + sProcessedBlockEv("waitForBlock", "waitForBlock", nil), + sProcessedBlockEv("waitForBlock", "finished", nil), + }, + }, + } + + executeFSMTests(t, tests, false) +} + +func TestFSMBadBlockFromPeer(t *testing.T) { + tests := []testFields{ + { + name: "block we haven't asked for", + startingHeight: 1, + maxRequestsPerPeer: 3, + steps: []fsmStepTestValues{ + sStartFSMEv(), + // add P1 and ask for blocks 1-3 + sStatusEv("waitForPeer", "waitForBlock", "P1", 300, nil), + sMakeRequestsEv("waitForBlock", "waitForBlock", maxNumRequests), + + // blockResponseEv for height 100 should cause an error + sBlockRespEvErrored("waitForBlock", "waitForPeer", + "P1", 100, []int64{}, errMissingBlock, []p2p.ID{}), + }, + }, + { + name: "block we already have", + startingHeight: 1, + maxRequestsPerPeer: 3, + steps: []fsmStepTestValues{ + sStartFSMEv(), + // add P1 and get block 1 + sStatusEv("waitForPeer", "waitForBlock", "P1", 100, nil), + sMakeRequestsEv("waitForBlock", "waitForBlock", maxNumRequests), + sBlockRespEv("waitForBlock", "waitForBlock", + "P1", 1, []int64{}), + + // Get block 1 again. Since peer is removed together with block 1, + // the blocks present in the pool should be {} + sBlockRespEvErrored("waitForBlock", "waitForPeer", + "P1", 1, []int64{}, errDuplicateBlock, []p2p.ID{"P1"}), + }, + }, + { + name: "block from unknown peer", + startingHeight: 1, + maxRequestsPerPeer: 3, + steps: []fsmStepTestValues{ + sStartFSMEv(), + // add P1 and get block 1 + sStatusEv("waitForPeer", "waitForBlock", "P1", 3, nil), + + // get block 1 from unknown peer P2 + sMakeRequestsEv("waitForBlock", "waitForBlock", maxNumRequests), + sBlockRespEvErrored("waitForBlock", "waitForBlock", + "P2", 1, []int64{}, errBadDataFromPeer, []p2p.ID{"P2"}), + }, + }, + { + name: "block from wrong peer", + startingHeight: 1, + maxRequestsPerPeer: 3, + steps: []fsmStepTestValues{ + sStartFSMEv(), + // add P1, make requests for blocks 1-3 to P1 + sStatusEv("waitForPeer", "waitForBlock", "P1", 3, nil), + sMakeRequestsEv("waitForBlock", "waitForBlock", maxNumRequests), + + // add P2 + sStatusEv("waitForBlock", "waitForBlock", "P2", 3, nil), + + // receive block 1 from P2 + sBlockRespEvErrored("waitForBlock", "waitForBlock", + "P2", 1, []int64{}, errBadDataFromPeer, []p2p.ID{"P2"}), + }, + }, + } + + executeFSMTests(t, tests, false) +} + +func TestFSMBlockAtCurrentHeightDoesNotArriveInTime(t *testing.T) { + tests := []testFields{ + { + name: "block at current height undelivered - TS5", + startingHeight: 1, + maxRequestsPerPeer: 3, + steps: []fsmStepTestValues{ + sStartFSMEv(), + // add P1, get blocks 1 and 2, process block 1 + sStatusEv("waitForPeer", "waitForBlock", "P1", 3, nil), + sMakeRequestsEv("waitForBlock", "waitForBlock", maxNumRequests), + sBlockRespEv("waitForBlock", "waitForBlock", + "P1", 1, []int64{}), + sBlockRespEv("waitForBlock", "waitForBlock", + "P1", 2, []int64{1}), + sProcessedBlockEv("waitForBlock", "waitForBlock", nil), + + // add P2 + sStatusEv("waitForBlock", "waitForBlock", "P2", 3, nil), + + // timeout on block 3, P1 should be removed + sStateTimeoutEv("waitForBlock", "waitForBlock", "waitForBlock", errNoPeerResponseForCurrentHeights), + + // make requests and finish by receiving blocks 2 and 3 from P2 + sMakeRequestsEv("waitForBlock", "waitForBlock", maxNumRequests), + sBlockRespEv("waitForBlock", "waitForBlock", "P2", 2, []int64{}), + sBlockRespEv("waitForBlock", "waitForBlock", "P2", 3, []int64{2}), + sProcessedBlockEv("waitForBlock", "finished", nil), + }, + }, + { + name: "block at current height undelivered, at maxPeerHeight after peer removal - TS3", + startingHeight: 1, + maxRequestsPerPeer: 3, + steps: []fsmStepTestValues{ + sStartFSMEv(), + // add P1, request blocks 1-3 from P1 + sStatusEv("waitForPeer", "waitForBlock", "P1", 3, nil), + sMakeRequestsEv("waitForBlock", "waitForBlock", maxNumRequests), + + // add P2 (tallest) + sStatusEv("waitForBlock", "waitForBlock", "P2", 30, nil), + sMakeRequestsEv("waitForBlock", "waitForBlock", maxNumRequests), + + // receive blocks 1-3 from P1 + sBlockRespEv("waitForBlock", "waitForBlock", "P1", 1, []int64{}), + sBlockRespEv("waitForBlock", "waitForBlock", "P1", 2, []int64{1}), + sBlockRespEv("waitForBlock", "waitForBlock", "P1", 3, []int64{1, 2}), + + // process blocks at heights 1 and 2 + sProcessedBlockEv("waitForBlock", "waitForBlock", nil), + sProcessedBlockEv("waitForBlock", "waitForBlock", nil), + + // timeout on block at height 4 + sStateTimeoutEv("waitForBlock", "finished", "waitForBlock", nil), + }, + }, + } + + executeFSMTests(t, tests, true) +} + +func TestFSMPeerRelatedEvents(t *testing.T) { + tests := []testFields{ + { + name: "peer remove event with no blocks", + startingHeight: 1, + steps: []fsmStepTestValues{ + sStartFSMEv(), + // add P1, P2, P3 + sStatusEv("waitForPeer", "waitForBlock", "P1", 3, nil), + sStatusEv("waitForBlock", "waitForBlock", "P2", 3, nil), + sStatusEv("waitForBlock", "waitForBlock", "P3", 3, nil), + + // switch removes P2 + sPeerRemoveEv("waitForBlock", "waitForBlock", "P2", errSwitchRemovesPeer, []p2p.ID{"P2"}), + }, + }, + { + name: "only peer removed while in waitForBlock state", + startingHeight: 100, + steps: []fsmStepTestValues{ + sStartFSMEv(), + // add P1 + sStatusEv("waitForPeer", "waitForBlock", "P1", 200, nil), + + // switch removes P1 + sPeerRemoveEv("waitForBlock", "waitForPeer", "P1", errSwitchRemovesPeer, []p2p.ID{"P1"}), + }, + }, + { + name: "highest peer removed while in waitForBlock state, node reaches maxPeerHeight - TS4 ", + startingHeight: 100, + maxRequestsPerPeer: 3, + steps: []fsmStepTestValues{ + sStartFSMEv(), + // add P1 and make requests + sStatusEv("waitForPeer", "waitForBlock", "P1", 101, nil), + sMakeRequestsEv("waitForBlock", "waitForBlock", maxNumRequests), + // add P2 + sStatusEv("waitForBlock", "waitForBlock", "P2", 200, nil), + + // get blocks 100 and 101 from P1 and process block at height 100 + sBlockRespEv("waitForBlock", "waitForBlock", "P1", 100, []int64{}), + sBlockRespEv("waitForBlock", "waitForBlock", "P1", 101, []int64{100}), + sProcessedBlockEv("waitForBlock", "waitForBlock", nil), + + // switch removes peer P1, should be finished + sPeerRemoveEv("waitForBlock", "finished", "P2", errSwitchRemovesPeer, []p2p.ID{"P2"}), + }, + }, + { + name: "highest peer lowers its height in waitForBlock state, node reaches maxPeerHeight - TS4", + startingHeight: 100, + maxRequestsPerPeer: 3, + steps: []fsmStepTestValues{ + sStartFSMEv(), + // add P1 and make requests + sStatusEv("waitForPeer", "waitForBlock", "P1", 101, nil), + sMakeRequestsEv("waitForBlock", "waitForBlock", maxNumRequests), + + // add P2 + sStatusEv("waitForBlock", "waitForBlock", "P2", 200, nil), + + // get blocks 100 and 101 from P1 + sBlockRespEv("waitForBlock", "waitForBlock", "P1", 100, []int64{}), + sBlockRespEv("waitForBlock", "waitForBlock", "P1", 101, []int64{100}), + + // processed block at heights 100 + sProcessedBlockEv("waitForBlock", "waitForBlock", nil), + + // P2 becomes short + sStatusEv("waitForBlock", "finished", "P2", 100, errPeerLowersItsHeight), + }, + }, + { + name: "new short peer while in waitForPeer state", + startingHeight: 100, + steps: []fsmStepTestValues{ + sStartFSMEv(), + sStatusEv("waitForPeer", "waitForPeer", "P1", 3, errPeerTooShort), + }, + }, + { + name: "new short peer while in waitForBlock state", + startingHeight: 100, + steps: []fsmStepTestValues{ + sStartFSMEv(), + sStatusEv("waitForPeer", "waitForBlock", "P1", 200, nil), + sStatusEv("waitForBlock", "waitForBlock", "P2", 3, errPeerTooShort), + }, + }, + { + name: "only peer updated with low height while in waitForBlock state", + startingHeight: 100, + steps: []fsmStepTestValues{ + sStartFSMEv(), + sStatusEv("waitForPeer", "waitForBlock", "P1", 200, nil), + sStatusEv("waitForBlock", "waitForPeer", "P1", 3, errPeerLowersItsHeight), + }, + }, + { + name: "peer does not exist in the switch", + startingHeight: 9999999, + maxRequestsPerPeer: 3, + steps: []fsmStepTestValues{ + sStartFSMEv(), + // add P1 + sStatusEv("waitForPeer", "waitForBlock", "P1", 20000000, nil), + // send request for block 9999999 + // Note: For this block request the "switch missing the peer" error is simulated, + // see implementation of bcReactor interface, sendBlockRequest(), in this file. + sMakeRequestsEvErrored("waitForBlock", "waitForBlock", + maxNumRequests, nil, []p2p.ID{"P1"}), + }, + }, + } + + executeFSMTests(t, tests, true) +} + +func TestFSMStopFSM(t *testing.T) { + tests := []testFields{ + { + name: "stopFSMEv in unknown", + steps: []fsmStepTestValues{ + sStopFSMEv("unknown", "finished"), + }, + }, + { + name: "stopFSMEv in waitForPeer", + startingHeight: 1, + steps: []fsmStepTestValues{ + sStartFSMEv(), + sStopFSMEv("waitForPeer", "finished"), + }, + }, + { + name: "stopFSMEv in waitForBlock", + startingHeight: 1, + steps: []fsmStepTestValues{ + sStartFSMEv(), + sStatusEv("waitForPeer", "waitForBlock", "P1", 3, nil), + sStopFSMEv("waitForBlock", "finished"), + }, + }, + } + + executeFSMTests(t, tests, false) +} + +func TestFSMUnknownElements(t *testing.T) { + tests := []testFields{ + { + name: "unknown event for state unknown", + steps: []fsmStepTestValues{ + sUnknownFSMEv("unknown"), + }, + }, + { + name: "unknown event for state waitForPeer", + steps: []fsmStepTestValues{ + sStartFSMEv(), + sUnknownFSMEv("waitForPeer"), + }, + }, + { + name: "unknown event for state waitForBlock", + startingHeight: 1, + steps: []fsmStepTestValues{ + sStartFSMEv(), + sStatusEv("waitForPeer", "waitForBlock", "P1", 3, nil), + sUnknownFSMEv("waitForBlock"), + }, + }, + } + + executeFSMTests(t, tests, false) +} + +func TestFSMPeerStateTimeoutEvent(t *testing.T) { + tests := []testFields{ + { + name: "timeout event for state waitForPeer while in state waitForPeer - TS1", + startingHeight: 1, + maxRequestsPerPeer: 3, + steps: []fsmStepTestValues{ + sStartFSMEv(), + sStateTimeoutEv("waitForPeer", "finished", "waitForPeer", errNoTallerPeer), + }, + }, + { + name: "timeout event for state waitForPeer while in a state != waitForPeer", + startingHeight: 1, + maxRequestsPerPeer: 3, + steps: []fsmStepTestValues{ + sStartFSMEv(), + sStateTimeoutEv("waitForPeer", "waitForPeer", "waitForBlock", errTimeoutEventWrongState), + }, + }, + { + name: "timeout event for state waitForBlock while in state waitForBlock ", + startingHeight: 1, + maxRequestsPerPeer: 3, + steps: []fsmStepTestValues{ + sStartFSMEv(), + sStatusEv("waitForPeer", "waitForBlock", "P1", 3, nil), + sMakeRequestsEv("waitForBlock", "waitForBlock", maxNumRequests), + sStateTimeoutEv("waitForBlock", "waitForPeer", "waitForBlock", errNoPeerResponseForCurrentHeights), + }, + }, + { + name: "timeout event for state waitForBlock while in a state != waitForBlock", + startingHeight: 1, + maxRequestsPerPeer: 3, + steps: []fsmStepTestValues{ + sStartFSMEv(), + sStatusEv("waitForPeer", "waitForBlock", "P1", 3, nil), + sMakeRequestsEv("waitForBlock", "waitForBlock", maxNumRequests), + sStateTimeoutEv("waitForBlock", "waitForBlock", "waitForPeer", errTimeoutEventWrongState), + }, + }, + { + name: "timeout event for state waitForBlock with multiple peers", + startingHeight: 1, + maxRequestsPerPeer: 3, + steps: []fsmStepTestValues{ + sStartFSMEv(), + sStatusEv("waitForPeer", "waitForBlock", "P1", 3, nil), + sMakeRequestsEv("waitForBlock", "waitForBlock", maxNumRequests), + sStatusEv("waitForBlock", "waitForBlock", "P2", 3, nil), + sStateTimeoutEv("waitForBlock", "waitForBlock", "waitForBlock", errNoPeerResponseForCurrentHeights), + }, + }, + } + + executeFSMTests(t, tests, false) +} + +func makeCorrectTransitionSequence(startingHeight int64, numBlocks int64, numPeers int, randomPeerHeights bool, + maxRequestsPerPeer int, maxPendingRequests int) testFields { + + // Generate numPeers peers with random or numBlocks heights according to the randomPeerHeights flag. + peerHeights := make([]int64, numPeers) + for i := 0; i < numPeers; i++ { + if i == 0 { + peerHeights[0] = numBlocks + continue + } + if randomPeerHeights { + peerHeights[i] = int64(cmn.MaxInt(cmn.RandIntn(int(numBlocks)), int(startingHeight)+1)) + } else { + peerHeights[i] = numBlocks + } + } + + // Approximate the slice capacity to save time for appends. + testSteps := make([]fsmStepTestValues, 0, 3*numBlocks+int64(numPeers)) + + testName := fmt.Sprintf("%v-blocks %v-startingHeight %v-peers %v-maxRequestsPerPeer %v-maxNumRequests", + numBlocks, startingHeight, numPeers, maxRequestsPerPeer, maxPendingRequests) + + // Add startFSMEv step. + testSteps = append(testSteps, sStartFSMEv()) + + // For each peer, add statusResponseEv step. + for i := 0; i < numPeers; i++ { + peerName := fmt.Sprintf("P%d", i) + if i == 0 { + testSteps = append( + testSteps, + sStatusEv("waitForPeer", "waitForBlock", p2p.ID(peerName), peerHeights[i], nil)) + } else { + testSteps = append(testSteps, + sStatusEv("waitForBlock", "waitForBlock", p2p.ID(peerName), peerHeights[i], nil)) + } + } + + height := startingHeight + numBlocksReceived := 0 + prevBlocks := make([]int64, 0, maxPendingRequests) + +forLoop: + for i := 0; i < int(numBlocks); i++ { + + // Add the makeRequestEv step periodically. + if i%int(maxRequestsPerPeer) == 0 { + testSteps = append( + testSteps, + sMakeRequestsEv("waitForBlock", "waitForBlock", maxNumRequests), + ) + } + + // Add the blockRespEv step + testSteps = append( + testSteps, + sBlockRespEv("waitForBlock", "waitForBlock", + "P0", height, prevBlocks)) + prevBlocks = append(prevBlocks, height) + height++ + numBlocksReceived++ + + // Add the processedBlockEv step periodically. + if numBlocksReceived >= int(maxRequestsPerPeer) || height >= numBlocks { + for j := int(height) - numBlocksReceived; j < int(height); j++ { + if j >= int(numBlocks) { + // This is the last block that is processed, we should be in "finished" state. + testSteps = append( + testSteps, + sProcessedBlockEv("waitForBlock", "finished", nil)) + break forLoop + } + testSteps = append( + testSteps, + sProcessedBlockEv("waitForBlock", "waitForBlock", nil)) + } + numBlocksReceived = 0 + prevBlocks = make([]int64, 0, maxPendingRequests) + } + } + + return testFields{ + name: testName, + startingHeight: startingHeight, + maxRequestsPerPeer: maxRequestsPerPeer, + maxPendingRequests: maxPendingRequests, + steps: testSteps, + } +} + +const ( + maxStartingHeightTest = 100 + maxRequestsPerPeerTest = 20 + maxTotalPendingRequestsTest = 600 + maxNumPeersTest = 1000 + maxNumBlocksInChainTest = 10000 //should be smaller than 9999999 +) + +func makeCorrectTransitionSequenceWithRandomParameters() testFields { + // Generate a starting height for fast sync. + startingHeight := int64(cmn.RandIntn(maxStartingHeightTest) + 1) + + // Generate the number of requests per peer. + maxRequestsPerPeer := cmn.RandIntn(maxRequestsPerPeerTest) + 1 + + // Generate the maximum number of total pending requests, >= maxRequestsPerPeer. + maxPendingRequests := cmn.RandIntn(maxTotalPendingRequestsTest-int(maxRequestsPerPeer)) + maxRequestsPerPeer + + // Generate the number of blocks to be synced. + numBlocks := int64(cmn.RandIntn(maxNumBlocksInChainTest)) + startingHeight + + // Generate a number of peers. + numPeers := cmn.RandIntn(maxNumPeersTest) + 1 + + return makeCorrectTransitionSequence(startingHeight, numBlocks, numPeers, true, maxRequestsPerPeer, maxPendingRequests) +} + +func shouldApplyProcessedBlockEvStep(step *fsmStepTestValues, testBcR *testReactor) bool { + if step.event == processedBlockEv { + _, err := testBcR.fsm.pool.BlockAndPeerAtHeight(testBcR.fsm.pool.Height) + if err == errMissingBlock { + return false + } + _, err = testBcR.fsm.pool.BlockAndPeerAtHeight(testBcR.fsm.pool.Height + 1) + if err == errMissingBlock { + return false + } + } + return true +} + +func TestFSMCorrectTransitionSequences(t *testing.T) { + + tests := []testFields{ + makeCorrectTransitionSequence(1, 100, 10, true, 10, 40), + makeCorrectTransitionSequenceWithRandomParameters(), + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + // Create test reactor + testBcR := newTestReactor(tt.startingHeight) + + if tt.maxRequestsPerPeer != 0 { + maxRequestsPerPeer = tt.maxRequestsPerPeer + } + + for _, step := range tt.steps { + assert.Equal(t, step.currentState, testBcR.fsm.state.name) + + oldNumStatusRequests := testBcR.numStatusRequests + fixBlockResponseEvStep(&step, testBcR) + if !shouldApplyProcessedBlockEvStep(&step, testBcR) { + continue + } + + fsmErr := sendEventToFSM(testBcR.fsm, step.event, step.data) + assert.Equal(t, step.wantErr, fsmErr) + + if step.wantStatusReqSent { + assert.Equal(t, oldNumStatusRequests+1, testBcR.numStatusRequests) + } else { + assert.Equal(t, oldNumStatusRequests, testBcR.numStatusRequests) + } + + assert.Equal(t, step.wantState, testBcR.fsm.state.name) + if step.wantState == "finished" { + assert.True(t, testBcR.fsm.isCaughtUp()) + } + } + + }) + } +} + +// ---------------------------------------- +// implements the bcRNotifier +func (testR *testReactor) sendPeerError(err error, peerID p2p.ID) { + testR.logger.Info("Reactor received sendPeerError call from FSM", "peer", peerID, "err", err) + testR.lastPeerError.peerID = peerID + testR.lastPeerError.err = err +} + +func (testR *testReactor) sendStatusRequest() { + testR.logger.Info("Reactor received sendStatusRequest call from FSM") + testR.numStatusRequests++ +} + +func (testR *testReactor) sendBlockRequest(peerID p2p.ID, height int64) error { + testR.logger.Info("Reactor received sendBlockRequest call from FSM", "peer", peerID, "height", height) + testR.numBlockRequests++ + testR.lastBlockRequest.peerID = peerID + testR.lastBlockRequest.height = height + if height == 9999999 { + // simulate switch does not have peer + return errNilPeerForBlockRequest + } + return nil +} + +func (testR *testReactor) resetStateTimer(name string, timer **time.Timer, timeout time.Duration) { + testR.logger.Info("Reactor received resetStateTimer call from FSM", "state", name, "timeout", timeout) + if _, ok := testR.stateTimerStarts[name]; !ok { + testR.stateTimerStarts[name] = 1 + } else { + testR.stateTimerStarts[name]++ + } +} + +func (testR *testReactor) switchToConsensus() { +} + +// ---------------------------------------- diff --git a/blockchain/v1/reactor_test.go b/blockchain/v1/reactor_test.go new file mode 100644 index 000000000..b5965a2af --- /dev/null +++ b/blockchain/v1/reactor_test.go @@ -0,0 +1,337 @@ +package v1 + +import ( + "fmt" + "os" + "sort" + "sync" + "testing" + "time" + + "github.com/stretchr/testify/assert" + abci "github.com/tendermint/tendermint/abci/types" + cfg "github.com/tendermint/tendermint/config" + cmn "github.com/tendermint/tendermint/libs/common" + "github.com/tendermint/tendermint/libs/log" + "github.com/tendermint/tendermint/mock" + "github.com/tendermint/tendermint/p2p" + "github.com/tendermint/tendermint/proxy" + sm "github.com/tendermint/tendermint/state" + "github.com/tendermint/tendermint/store" + "github.com/tendermint/tendermint/types" + tmtime "github.com/tendermint/tendermint/types/time" + dbm "github.com/tendermint/tm-cmn/db" +) + +var config *cfg.Config + +func randGenesisDoc(numValidators int, randPower bool, minPower int64) (*types.GenesisDoc, []types.PrivValidator) { + validators := make([]types.GenesisValidator, numValidators) + privValidators := make([]types.PrivValidator, numValidators) + for i := 0; i < numValidators; i++ { + val, privVal := types.RandValidator(randPower, minPower) + validators[i] = types.GenesisValidator{ + PubKey: val.PubKey, + Power: val.VotingPower, + } + privValidators[i] = privVal + } + sort.Sort(types.PrivValidatorsByAddress(privValidators)) + + return &types.GenesisDoc{ + GenesisTime: tmtime.Now(), + ChainID: config.ChainID(), + Validators: validators, + }, privValidators +} + +func makeVote(header *types.Header, blockID types.BlockID, valset *types.ValidatorSet, privVal types.PrivValidator) *types.Vote { + addr := privVal.GetPubKey().Address() + idx, _ := valset.GetByAddress(addr) + vote := &types.Vote{ + ValidatorAddress: addr, + ValidatorIndex: idx, + Height: header.Height, + Round: 1, + Timestamp: tmtime.Now(), + Type: types.PrecommitType, + BlockID: blockID, + } + + _ = privVal.SignVote(header.ChainID, vote) + + return vote +} + +type BlockchainReactorPair struct { + bcR *BlockchainReactor + conR *consensusReactorTest +} + +func newBlockchainReactor(logger log.Logger, genDoc *types.GenesisDoc, privVals []types.PrivValidator, maxBlockHeight int64) *BlockchainReactor { + if len(privVals) != 1 { + panic("only support one validator") + } + + app := &testApp{} + cc := proxy.NewLocalClientCreator(app) + proxyApp := proxy.NewAppConns(cc) + err := proxyApp.Start() + if err != nil { + panic(cmn.ErrorWrap(err, "error start app")) + } + + blockDB := dbm.NewMemDB() + stateDB := dbm.NewMemDB() + blockStore := store.NewBlockStore(blockDB) + + state, err := sm.LoadStateFromDBOrGenesisDoc(stateDB, genDoc) + if err != nil { + panic(cmn.ErrorWrap(err, "error constructing state from genesis file")) + } + + // Make the BlockchainReactor itself. + // NOTE we have to create and commit the blocks first because + // pool.height is determined from the store. + fastSync := true + db := dbm.NewMemDB() + blockExec := sm.NewBlockExecutor(db, log.TestingLogger(), proxyApp.Consensus(), + mock.Mempool{}, sm.MockEvidencePool{}) + sm.SaveState(db, state) + + // let's add some blocks in + for blockHeight := int64(1); blockHeight <= maxBlockHeight; blockHeight++ { + lastCommit := types.NewCommit(types.BlockID{}, nil) + if blockHeight > 1 { + lastBlockMeta := blockStore.LoadBlockMeta(blockHeight - 1) + lastBlock := blockStore.LoadBlock(blockHeight - 1) + + vote := makeVote(&lastBlock.Header, lastBlockMeta.BlockID, state.Validators, privVals[0]).CommitSig() + lastCommit = types.NewCommit(lastBlockMeta.BlockID, []*types.CommitSig{vote}) + } + + thisBlock := makeBlock(blockHeight, state, lastCommit) + + thisParts := thisBlock.MakePartSet(types.BlockPartSizeBytes) + blockID := types.BlockID{Hash: thisBlock.Hash(), PartsHeader: thisParts.Header()} + + state, err = blockExec.ApplyBlock(state, blockID, thisBlock) + if err != nil { + panic(cmn.ErrorWrap(err, "error apply block")) + } + + blockStore.SaveBlock(thisBlock, thisParts, lastCommit) + } + + bcReactor := NewBlockchainReactor(state.Copy(), blockExec, blockStore, fastSync) + bcReactor.SetLogger(logger.With("module", "blockchain")) + + return bcReactor +} + +func newBlockchainReactorPair(logger log.Logger, genDoc *types.GenesisDoc, privVals []types.PrivValidator, maxBlockHeight int64) BlockchainReactorPair { + + consensusReactor := &consensusReactorTest{} + consensusReactor.BaseReactor = *p2p.NewBaseReactor("Consensus reactor", consensusReactor) + + return BlockchainReactorPair{ + newBlockchainReactor(logger, genDoc, privVals, maxBlockHeight), + consensusReactor} +} + +type consensusReactorTest struct { + p2p.BaseReactor // BaseService + p2p.Switch + switchedToConsensus bool + mtx sync.Mutex +} + +func (conR *consensusReactorTest) SwitchToConsensus(state sm.State, blocksSynced int) { + conR.mtx.Lock() + defer conR.mtx.Unlock() + conR.switchedToConsensus = true +} + +func TestFastSyncNoBlockResponse(t *testing.T) { + + config = cfg.ResetTestRoot("blockchain_new_reactor_test") + defer os.RemoveAll(config.RootDir) + genDoc, privVals := randGenesisDoc(1, false, 30) + + maxBlockHeight := int64(65) + + reactorPairs := make([]BlockchainReactorPair, 2) + + logger := log.TestingLogger() + reactorPairs[0] = newBlockchainReactorPair(logger, genDoc, privVals, maxBlockHeight) + reactorPairs[1] = newBlockchainReactorPair(logger, genDoc, privVals, 0) + + p2p.MakeConnectedSwitches(config.P2P, 2, func(i int, s *p2p.Switch) *p2p.Switch { + s.AddReactor("BLOCKCHAIN", reactorPairs[i].bcR) + s.AddReactor("CONSENSUS", reactorPairs[i].conR) + moduleName := fmt.Sprintf("blockchain-%v", i) + reactorPairs[i].bcR.SetLogger(logger.With("module", moduleName)) + + return s + + }, p2p.Connect2Switches) + + defer func() { + for _, r := range reactorPairs { + _ = r.bcR.Stop() + _ = r.conR.Stop() + } + }() + + tests := []struct { + height int64 + existent bool + }{ + {maxBlockHeight + 2, false}, + {10, true}, + {1, true}, + {maxBlockHeight + 100, false}, + } + + for { + time.Sleep(10 * time.Millisecond) + reactorPairs[1].conR.mtx.Lock() + if reactorPairs[1].conR.switchedToConsensus { + reactorPairs[1].conR.mtx.Unlock() + break + } + reactorPairs[1].conR.mtx.Unlock() + } + + assert.Equal(t, maxBlockHeight, reactorPairs[0].bcR.store.Height()) + + for _, tt := range tests { + block := reactorPairs[1].bcR.store.LoadBlock(tt.height) + if tt.existent { + assert.True(t, block != nil) + } else { + assert.True(t, block == nil) + } + } +} + +// NOTE: This is too hard to test without +// an easy way to add test peer to switch +// or without significant refactoring of the module. +// Alternatively we could actually dial a TCP conn but +// that seems extreme. +func TestFastSyncBadBlockStopsPeer(t *testing.T) { + numNodes := 4 + maxBlockHeight := int64(148) + + config = cfg.ResetTestRoot("blockchain_reactor_test") + defer os.RemoveAll(config.RootDir) + genDoc, privVals := randGenesisDoc(1, false, 30) + + otherChain := newBlockchainReactorPair(log.TestingLogger(), genDoc, privVals, maxBlockHeight) + defer func() { + _ = otherChain.bcR.Stop() + _ = otherChain.conR.Stop() + }() + + reactorPairs := make([]BlockchainReactorPair, numNodes) + logger := make([]log.Logger, numNodes) + + for i := 0; i < numNodes; i++ { + logger[i] = log.TestingLogger() + height := int64(0) + if i == 0 { + height = maxBlockHeight + } + reactorPairs[i] = newBlockchainReactorPair(logger[i], genDoc, privVals, height) + } + + switches := p2p.MakeConnectedSwitches(config.P2P, numNodes, func(i int, s *p2p.Switch) *p2p.Switch { + reactorPairs[i].conR.mtx.Lock() + s.AddReactor("BLOCKCHAIN", reactorPairs[i].bcR) + s.AddReactor("CONSENSUS", reactorPairs[i].conR) + moduleName := fmt.Sprintf("blockchain-%v", i) + reactorPairs[i].bcR.SetLogger(logger[i].With("module", moduleName)) + reactorPairs[i].conR.mtx.Unlock() + return s + + }, p2p.Connect2Switches) + + defer func() { + for _, r := range reactorPairs { + _ = r.bcR.Stop() + _ = r.conR.Stop() + } + }() + +outerFor: + for { + time.Sleep(10 * time.Millisecond) + for i := 0; i < numNodes; i++ { + reactorPairs[i].conR.mtx.Lock() + if !reactorPairs[i].conR.switchedToConsensus { + reactorPairs[i].conR.mtx.Unlock() + continue outerFor + } + reactorPairs[i].conR.mtx.Unlock() + } + break + } + + //at this time, reactors[0-3] is the newest + assert.Equal(t, numNodes-1, reactorPairs[1].bcR.Switch.Peers().Size()) + + //mark last reactorPair as an invalid peer + reactorPairs[numNodes-1].bcR.store = otherChain.bcR.store + + lastLogger := log.TestingLogger() + lastReactorPair := newBlockchainReactorPair(lastLogger, genDoc, privVals, 0) + reactorPairs = append(reactorPairs, lastReactorPair) + + switches = append(switches, p2p.MakeConnectedSwitches(config.P2P, 1, func(i int, s *p2p.Switch) *p2p.Switch { + s.AddReactor("BLOCKCHAIN", reactorPairs[len(reactorPairs)-1].bcR) + s.AddReactor("CONSENSUS", reactorPairs[len(reactorPairs)-1].conR) + moduleName := fmt.Sprintf("blockchain-%v", len(reactorPairs)-1) + reactorPairs[len(reactorPairs)-1].bcR.SetLogger(lastLogger.With("module", moduleName)) + return s + + }, p2p.Connect2Switches)...) + + for i := 0; i < len(reactorPairs)-1; i++ { + p2p.Connect2Switches(switches, i, len(reactorPairs)-1) + } + + for { + time.Sleep(1 * time.Second) + lastReactorPair.conR.mtx.Lock() + if lastReactorPair.conR.switchedToConsensus { + lastReactorPair.conR.mtx.Unlock() + break + } + lastReactorPair.conR.mtx.Unlock() + + if lastReactorPair.bcR.Switch.Peers().Size() == 0 { + break + } + } + + assert.True(t, lastReactorPair.bcR.Switch.Peers().Size() < len(reactorPairs)-1) +} + +//---------------------------------------------- +// utility funcs + +func makeTxs(height int64) (txs []types.Tx) { + for i := 0; i < 10; i++ { + txs = append(txs, types.Tx([]byte{byte(height), byte(i)})) + } + return txs +} + +func makeBlock(height int64, state sm.State, lastCommit *types.Commit) *types.Block { + block, _ := state.MakeBlock(height, makeTxs(height), lastCommit, nil, state.Validators.GetProposer().Address) + return block +} + +type testApp struct { + abci.BaseApplication +} diff --git a/blockchain/v1/wire.go b/blockchain/v1/wire.go new file mode 100644 index 000000000..786584435 --- /dev/null +++ b/blockchain/v1/wire.go @@ -0,0 +1,13 @@ +package v1 + +import ( + amino "github.com/tendermint/go-amino" + "github.com/tendermint/tendermint/types" +) + +var cdc = amino.NewCodec() + +func init() { + RegisterBlockchainMessages(cdc) + types.RegisterBlockAmino(cdc) +} diff --git a/cmd/tendermint/commands/run_node.go b/cmd/tendermint/commands/run_node.go index fa63b4944..70de9aba7 100644 --- a/cmd/tendermint/commands/run_node.go +++ b/cmd/tendermint/commands/run_node.go @@ -19,7 +19,7 @@ func AddNodeFlags(cmd *cobra.Command) { cmd.Flags().String("priv_validator_laddr", config.PrivValidatorListenAddr, "Socket address to listen on for connections from external priv_validator process") // node flags - cmd.Flags().Bool("fast_sync", config.FastSync, "Fast blockchain syncing") + cmd.Flags().Bool("fast_sync", config.FastSyncMode, "Fast blockchain syncing") // abci flags cmd.Flags().String("proxy_app", config.ProxyApp, "Proxy app address, or one of: 'kvstore', 'persistent_kvstore', 'counter', 'counter_serial' or 'noop' for local testing.") diff --git a/config/config.go b/config/config.go index 73c704681..b00702ce6 100644 --- a/config/config.go +++ b/config/config.go @@ -64,6 +64,7 @@ type Config struct { RPC *RPCConfig `mapstructure:"rpc"` P2P *P2PConfig `mapstructure:"p2p"` Mempool *MempoolConfig `mapstructure:"mempool"` + FastSync *FastSyncConfig `mapstructure:"fastsync"` Consensus *ConsensusConfig `mapstructure:"consensus"` TxIndex *TxIndexConfig `mapstructure:"tx_index"` Instrumentation *InstrumentationConfig `mapstructure:"instrumentation"` @@ -76,6 +77,7 @@ func DefaultConfig() *Config { RPC: DefaultRPCConfig(), P2P: DefaultP2PConfig(), Mempool: DefaultMempoolConfig(), + FastSync: DefaultFastSyncConfig(), Consensus: DefaultConsensusConfig(), TxIndex: DefaultTxIndexConfig(), Instrumentation: DefaultInstrumentationConfig(), @@ -89,6 +91,7 @@ func TestConfig() *Config { RPC: TestRPCConfig(), P2P: TestP2PConfig(), Mempool: TestMempoolConfig(), + FastSync: TestFastSyncConfig(), Consensus: TestConsensusConfig(), TxIndex: TestTxIndexConfig(), Instrumentation: TestInstrumentationConfig(), @@ -120,6 +123,9 @@ func (cfg *Config) ValidateBasic() error { if err := cfg.Mempool.ValidateBasic(); err != nil { return errors.Wrap(err, "Error in [mempool] section") } + if err := cfg.FastSync.ValidateBasic(); err != nil { + return errors.Wrap(err, "Error in [fastsync] section") + } if err := cfg.Consensus.ValidateBasic(); err != nil { return errors.Wrap(err, "Error in [consensus] section") } @@ -151,7 +157,7 @@ type BaseConfig struct { // If this node is many blocks behind the tip of the chain, FastSync // allows them to catchup quickly by downloading blocks in parallel // and verifying their commits - FastSync bool `mapstructure:"fast_sync"` + FastSyncMode bool `mapstructure:"fast_sync"` // Database backend: goleveldb | cleveldb | boltdb // * goleveldb (github.com/syndtr/goleveldb - most popular implementation) @@ -216,7 +222,7 @@ func DefaultBaseConfig() BaseConfig { LogLevel: DefaultPackageLogLevels(), LogFormat: LogFormatPlain, ProfListenAddress: "", - FastSync: true, + FastSyncMode: true, FilterPeers: false, DBBackend: "goleveldb", DBPath: "data", @@ -228,7 +234,7 @@ func TestBaseConfig() BaseConfig { cfg := DefaultBaseConfig() cfg.chainID = "tendermint_test" cfg.ProxyApp = "kvstore" - cfg.FastSync = false + cfg.FastSyncMode = false cfg.DBBackend = "memdb" return cfg } @@ -684,6 +690,38 @@ func (cfg *MempoolConfig) ValidateBasic() error { return nil } +//----------------------------------------------------------------------------- +// FastSyncConfig + +// FastSyncConfig defines the configuration for the Tendermint fast sync service +type FastSyncConfig struct { + Version string `mapstructure:"version"` +} + +// DefaultFastSyncConfig returns a default configuration for the fast sync service +func DefaultFastSyncConfig() *FastSyncConfig { + return &FastSyncConfig{ + Version: "v0", + } +} + +// TestFastSyncConfig returns a default configuration for the fast sync. +func TestFastSyncConfig() *FastSyncConfig { + return DefaultFastSyncConfig() +} + +// ValidateBasic performs basic validation. +func (cfg *FastSyncConfig) ValidateBasic() error { + switch cfg.Version { + case "v0": + return nil + case "v1": + return nil + default: + return fmt.Errorf("unknown fastsync version %s", cfg.Version) + } +} + //----------------------------------------------------------------------------- // ConsensusConfig diff --git a/config/toml.go b/config/toml.go index 58da57975..5679a1caf 100644 --- a/config/toml.go +++ b/config/toml.go @@ -79,7 +79,7 @@ moniker = "{{ .BaseConfig.Moniker }}" # If this node is many blocks behind the tip of the chain, FastSync # allows them to catchup quickly by downloading blocks in parallel # and verifying their commits -fast_sync = {{ .BaseConfig.FastSync }} +fast_sync = {{ .BaseConfig.FastSyncMode }} # Database backend: goleveldb | cleveldb | boltdb # * goleveldb (github.com/syndtr/goleveldb - most popular implementation) @@ -294,6 +294,14 @@ max_txs_bytes = {{ .Mempool.MaxTxsBytes }} # Size of the cache (used to filter transactions we saw earlier) in transactions cache_size = {{ .Mempool.CacheSize }} +##### fast sync configuration options ##### +[fastsync] + +# Fast Sync version to use: +# 1) "v0" (default) - the legacy fast sync implementation +# 2) "v1" - refactor of v0 version for better testability +version = "{{ .FastSync.Version }}" + # Limit the size of TxMessage max_msg_bytes = {{ .Mempool.MaxMsgBytes }} diff --git a/consensus/common_test.go b/consensus/common_test.go index 839db08d7..21eb9f532 100644 --- a/consensus/common_test.go +++ b/consensus/common_test.go @@ -20,7 +20,6 @@ import ( "github.com/tendermint/tendermint/abci/example/counter" "github.com/tendermint/tendermint/abci/example/kvstore" abci "github.com/tendermint/tendermint/abci/types" - bc "github.com/tendermint/tendermint/blockchain" cfg "github.com/tendermint/tendermint/config" cstypes "github.com/tendermint/tendermint/consensus/types" cmn "github.com/tendermint/tendermint/libs/common" @@ -30,6 +29,7 @@ import ( "github.com/tendermint/tendermint/p2p" "github.com/tendermint/tendermint/privval" sm "github.com/tendermint/tendermint/state" + "github.com/tendermint/tendermint/store" "github.com/tendermint/tendermint/types" tmtime "github.com/tendermint/tendermint/types/time" dbm "github.com/tendermint/tm-cmn/db" @@ -280,7 +280,7 @@ func newConsensusStateWithConfig(thisConfig *cfg.Config, state sm.State, pv type func newConsensusStateWithConfigAndBlockStore(thisConfig *cfg.Config, state sm.State, pv types.PrivValidator, app abci.Application, blockDB dbm.DB) *ConsensusState { // Get BlockStore - blockStore := bc.NewBlockStore(blockDB) + blockStore := store.NewBlockStore(blockDB) // one for mempool, one for consensus mtx := new(sync.Mutex) diff --git a/consensus/reactor_test.go b/consensus/reactor_test.go index 30d9307a2..612fde7f6 100644 --- a/consensus/reactor_test.go +++ b/consensus/reactor_test.go @@ -17,13 +17,13 @@ import ( abcicli "github.com/tendermint/tendermint/abci/client" "github.com/tendermint/tendermint/abci/example/kvstore" abci "github.com/tendermint/tendermint/abci/types" - bc "github.com/tendermint/tendermint/blockchain" cfg "github.com/tendermint/tendermint/config" "github.com/tendermint/tendermint/libs/log" mempl "github.com/tendermint/tendermint/mempool" "github.com/tendermint/tendermint/p2p" "github.com/tendermint/tendermint/p2p/mock" sm "github.com/tendermint/tendermint/state" + "github.com/tendermint/tendermint/store" "github.com/tendermint/tendermint/types" dbm "github.com/tendermint/tm-cmn/db" ) @@ -133,7 +133,7 @@ func TestReactorWithEvidence(t *testing.T) { // css[i] = newConsensusStateWithConfig(thisConfig, state, privVals[i], app) blockDB := dbm.NewMemDB() - blockStore := bc.NewBlockStore(blockDB) + blockStore := store.NewBlockStore(blockDB) // one for mempool, one for consensus mtx := new(sync.Mutex) diff --git a/consensus/replay_file.go b/consensus/replay_file.go index 17404de8e..e686262d6 100644 --- a/consensus/replay_file.go +++ b/consensus/replay_file.go @@ -12,13 +12,13 @@ import ( "github.com/pkg/errors" dbm "github.com/tendermint/tm-cmn/db" - bc "github.com/tendermint/tendermint/blockchain" cfg "github.com/tendermint/tendermint/config" cmn "github.com/tendermint/tendermint/libs/common" "github.com/tendermint/tendermint/libs/log" "github.com/tendermint/tendermint/mock" "github.com/tendermint/tendermint/proxy" sm "github.com/tendermint/tendermint/state" + "github.com/tendermint/tendermint/store" "github.com/tendermint/tendermint/types" ) @@ -280,7 +280,7 @@ func newConsensusStateForReplay(config cfg.BaseConfig, csConfig *cfg.ConsensusCo dbType := dbm.DBBackendType(config.DBBackend) // Get BlockStore blockStoreDB := dbm.NewDB("blockstore", dbType, config.DBDir()) - blockStore := bc.NewBlockStore(blockStoreDB) + blockStore := store.NewBlockStore(blockStoreDB) // Get State stateDB := dbm.NewDB("state", dbType, config.DBDir()) diff --git a/consensus/wal_generator.go b/consensus/wal_generator.go index c96fd66e8..3f0608262 100644 --- a/consensus/wal_generator.go +++ b/consensus/wal_generator.go @@ -12,7 +12,6 @@ import ( "github.com/pkg/errors" "github.com/tendermint/tendermint/abci/example/kvstore" - bc "github.com/tendermint/tendermint/blockchain" cfg "github.com/tendermint/tendermint/config" cmn "github.com/tendermint/tendermint/libs/common" "github.com/tendermint/tendermint/libs/log" @@ -20,6 +19,7 @@ import ( "github.com/tendermint/tendermint/privval" "github.com/tendermint/tendermint/proxy" sm "github.com/tendermint/tendermint/state" + "github.com/tendermint/tendermint/store" "github.com/tendermint/tendermint/types" "github.com/tendermint/tm-cmn/db" ) @@ -55,7 +55,8 @@ func WALGenerateNBlocks(t *testing.T, wr io.Writer, numBlocks int) (err error) { } state.Version.Consensus.App = kvstore.ProtocolVersion sm.SaveState(stateDB, state) - blockStore := bc.NewBlockStore(blockStoreDB) + blockStore := store.NewBlockStore(blockStoreDB) + proxyApp := proxy.NewAppConns(proxy.NewLocalClientCreator(app)) proxyApp.SetLogger(logger.With("module", "proxy")) if err := proxyApp.Start(); err != nil { diff --git a/docs/spec/reactors/block_sync/bcv1/img/bc-reactor-new-datastructs.png b/docs/spec/reactors/block_sync/bcv1/img/bc-reactor-new-datastructs.png new file mode 100644 index 0000000000000000000000000000000000000000..1a92871a5bcebf2f88658623b82c6e49b9cd25bc GIT binary patch literal 44461 zcmeFYbDw3)(m%M%wr$(CZKKP!ZQC}wY}W(c4{$nv<3r1Bpc0nxW@AG3!{OsNt|6I_np^m?;W1IEv`@Z<4xz;9_On^JOE{1 z6KIgECVT*`UoGR}PBeagg5+2{0JI#y>;TG6+bX$>g^v%bn7QPi?%oE(T4S#%JNEK; z^{IBqrHh0Epu{~giHpb$y@hhQZv-3E1thqZ>-lTd8e}09R8xw=h<5m9shD@TXC<3! zF(07doyFej03cD(Wip@vrra2O@wri>h4V_S$Ic!;DP?z^4NIE1DQ$(k3^X*}Sv*SY zQXeuoKl(;w(?(4iluLQL(y)l0u0?}nSE4?hc|O`qOruVmPK$$+$YCQyTh8x$O-&%A zGV^h<*~fTiV?JTaB0-FfGw5#RbBy7qC?vT#SXe#cR6P7-Epv3u?r~w7NJ?)yhISa!H5+=Dxw$?|VF;cu<{ z9EA!vd*yuX+S$zPFi&9K%cg_b!UzNNqR;MIPdW!!G=K@xpJmUOKmtOs0kalOBZJ*q zIA$-QV5EdFsDaq?;&aJR^@1190Q!EA8cxKJK#K%G8h~9AL`x7dEl|yXj}n;70A~%1 zT99oG0X~Ri7t;bHcbB#uvNp)i0cH~dnGrfK*zp=(Rv0lPyc`iuIoO3zWE{6K6f*(m z5C%*nQ4u%=v{cwf61FCYU64$XN)>2X5N>{MUh0(A1q(aixA4$B<~{ZcCmwd@@111nNxCD*-10)HBd$c$bkC7SA})aRAi7h|xwC-VDx+ zd`BSGXpC{MQH7>lHP;H()bOaWO2bsW*c!79UMrY4kT(oZlyCUZUW(%=r-Uwm9wPMV^IA~iWn z5<^m?gu{ecEB;b6j__{$V*Kc^_)zB1@Kz!UcqC?DPD>O?rB(5qN-w1=g+rBkIpSPM zuH;y`O%bR3q#U7wz{G+%jae2eZdyB2I#WIKf|h&kSi1kTX?C= zb7`#^t{J2mrddfWr>KEgg-NeL^d`b6f4@B`Xwj!sv-C(hRk|#NbTXnbky(XH#k1;` z>1bmzU$t44SFN2oTQy6ywyIlWS@DnJQ6+j6d)2n`dx^Nlo!XS*M(xV?2SL1IyYKjg zy|TXfFJON#u%oc)v29|FVvVsMSq0L;<_h96(#h88+nMY&>c!**<~8Gm za4+=&`;Pja`?B?N0L~3g1YQM;4fh)h84fGVGOP>E8+Hc=3ugq&meq>I%c|OHnst`L zjuoG|FsnWLFylwoChJHhvn-43W7b3VfZ2nYrCF-k>a?LVgmd1r{#~Hwny38T)1B1` zoVFq@FWoIIHeDE9DqS!g4DAN(H*G9UGHu(o^M)5ITl-u~-~N~0*dVzAxj?z_8EYLD zomSh@UvfN^x%pe#U2a_(cQYr>Cs*12V|iu-Mtuvt8z0fZ#liE16Nb|Z{Y(=Lla2|6 z^jaPJ{C!{p+?k7}CL zW`{uscMs_&3MAqY4iknGc`mdyB#gmoCAk!8cl3~dVnAw-xQ>{N7)xYNtRnUPlT3$#vaX7>O5XR*@4qGSWSkXfWV{FNj@7R9OCd@$%KGLYr^@Ft zCS#^-W{FM6Omh!uu34T=np&FD%@H7{!Nh>2;+$t|a~us5>g7Qr(W8Glqb-bUA}Pftnb(M4n@B2lQm*EyJY_10%in?!|-4rk}GuKCV) z?7jWyn|;atYyG|@L&c|bxU;1C@XqYvm_}gjP4Q#sM_LM`@9KU1K|^3^0O*esiUcQ zRi3L$$Bp6j=pAS%+)Fqvtci6fZg;%AE*g55@QG{Y&|+O?rQt}&1(O(&$bZkdzx!n@ zG}al<633Ct$g8w0Y)xess;$u+*H+ph^%LbMggkiO>u;ULDJc*43j4?(<>lfZ z!gu@TzHpT<0Yjidkj}T@xp@8K!SWU!}4137AEe)1%Q8`95~QEf79AV_01RrWs_CLBC(CVY zZ%c1zVsB(h?_ulk72pB@ydKD^iA?VZdS zn7FvO7#Nuun3?ImIOv=`?OY5!=M_U$epw&CBpVGt3XISu^em00;u4M1@p6fG%^v zG}WYV#y)?P;)tfCDJu#qA=xw_qIQ8e&$L*_wg{~1uiEMHto;6MX9KD#-1&Mt!@F4nSpNS4;g%_CJ&aU_s{p-2F`|i2zUmlz*(Ls{I$=UleG- z#DBW~TPT6}t1n3Z?|4pF+kb;Q*ZRWp~3r0aE027ME%Bhk4%YlDUzKn(aUnU^} z{r|=y{eO65$1zOxFzB>H=I7^&rju@|&47=l(#Oh`ilKW@Np(Ww+BKOesh^QF;tnNc zgK9_Q3d&9U+An0DQGkdQn?a*gfp)n+dwYAubVMd=G@)$P>I)@rDb}fxr^WK5lqTZa zjYuVokX`8PfW_!uNA$i;=0hR|7Lf^(3yMu;JCXeF#Wx}yfEr*lqLBHe{NF3}YuWzA z4=uQG`+f7j9=I>MU;{GcA{!uom6e7Cgv#;^*&a)ai;^0eF!@(IPgCBGfBUtCe zq^OfL_TdqjqGH0USxU^kYKb{uax!WMb_$GA@`>S`oCGGYh}dK#l}1q>^>hphGBGJ< z@=)T?#Kfe4P%&ha13MtOL$;6;op8)VQW1dla^r+fdwgJ9MeeiS2S*e?mb~1_<08`?e(T20xPw z?uq=juYy`ciq)SVByaMA>+4##j!rIu2k2YZyCS%A?z0XAu$euVU0P)lPdAnyzH4=Y zjtUMHtW--MVxo05SGi~g&3?&R^~fnMqzKipp~ zsISVyl>Pc-6Xq4~kEb6zyxM~Awa@V9uKkg&SJ9_Vw zbeum&x?Wz~ID4Nzf}>-jL`6-SOUK%vESPnUkPgW<~G~}^J(-ekV5vm z7;L*JfdJ=BneWXTh!p<10K$ZO=W|j(hPP5r@$mB>!(ZK&L)iCs)xljS97ZRht4V`o z6vITk#K>6t1ilX_4Y0>P0)8LxsieXj|I8%eGH8?<5MuHw2WwDA2N$(kL#QCuyrMFS zK$5P)m3E+4+-$i<9sW71Rh;h${_Wh`EP>z>xP1AyKK@FchPaKJsU*(LnVT7Br5bIv zx1KB9#ziA0ZwHVkKETb9GHnz>$#Vr{w`J#yKNfO_(bXfZb`e z8^ZrPnBb=;o7k4uAEmKUZg7S-jiO!43#@u}XQ3KxJB$6rfHBmmpL8Tds3JeT2Wss2 z+E*&$DykmtqE?&kUgzi4NVD0jRmVb>b-Mtb6UU1kOIp!Dud52f_ofg?9`B^u?6qT4 znltCFjK(uSy|{C6^u|s)82Ylcn-{Dj7o3SdjZAGpyuH0Y4lL}4UY@3#V@feRuDI#H zc>}kxzdJt7E8SaJ&7uXmr&iPK&6Y|;7)y@?L#!IuSkn24t^y-dR=TIOb3Q!4mmg_k z_`bNF^c3-nHZ%m9RAcfX&R+T|*VXc5c|Z0K^;>*+Zuj{*TDkl?sz}Hdj8p`Ce`yuQ zTj8=@XyxE1r75-@GwYDfyx*e_Q~1O&vklwdTu;7cRUaWR9^Lm9rahL=231QwZg+S_ z_F``y?udSThG$Rj|8qdYXtj;*g2RGP%PxY1?qL{j;!f^{UFMAwx1V>)_ac{h^d={!-t|+PGW=+Wk_v^{$>2zSSO8~b zu&pY+-9p)suicYcSMP!mtQu^#=P6)CpT8Tp-f128X{5^NDiS7xuM%N{jY zc)h{h3K+-RdAD-1zW&n+e;+CImp@4h6WV9R6u+QMkrolyT9!#A) z<5(|MzWv#|Fc7SQ*XC#o_WaYz>GT`WZIu-PT%}WNiD#|K*mlr2#h8qhOs!T>n-h8i z(q(Y!v`}s*9tT!b6mePCNEU4kV~nH3kL>TZ^!?G^;=pds+Y=Tu*ls2#5gRKAVS4Oy zoBxg93|Zd?b|5!fC}EXD+?2!>SCbuIA1^E_Noqn=|LDQ&8SBiVkrA4)fmPzEsvCe0BAR<$+w1|8r$m6-s^LoeShLZHycx~(nmlO&LAc&%l$3UhEGgW&ZM#q! zjlBr}1yWDj!{7?b%xK6gmDxD>E=BI$>8Nl}S!tCypx1~PKa8wcE4-ney*5C;7o=b+ zkFV!bcai)3#YF;z14G|(kC$r+ar@1DiQJ{!Iw+=DRn_&+aD$9{z4aaU{rMr(r_M>e z$1=PW_D}AW@_`jFh8z|MCfe|@R5;SP)9(hLQRjGM^s&U*HOk5hf8NxO3e8DGPQg)D0bXgUI(YrXh!HTxaMfRq9*D~D*UeRy<=TvFkWY^4^Vsj$ zaAQRT3D902@KUE^$j*8+6%5<{@*^Hbe|2(QKGCJmZ*&~#$k|cj@k(5_iCn2Zk&1tY zRil1a7V70qq@m>-=6boU`OYB>OpD4SQ^mA>3%iEtGtSE!5O}pKy68{z;j|@>uj#rE zif*CTb|r{5?0XOVe4q~$3^lfluW&XKLd1#FAZl=^wu|BN?b?g<0oF@h{NSM zxaGxn9Q!cRldR@={sTqiZuAcS_Gs{uxxvqB0oBG=4tO};`JqbY z^H#jbP@XtrRUU@Z+O2pXy`KZ3L?9gBLI;XhuZp&OoG5XPZmFGgiI5!)R?#;F{4*Zq zm-#uDJQkCZ`bR4mwX=SuwF5bDnHQ9-8$H1bJ!Gt`6mR`;!{#tVUHBM|Y zJVHdvkN<+swr4Y&(xYx$@4nC6d@*G63PL~#FnjU^)(J=&QY+tvK6uR?zIUZ)uzIv? zu3Lqza+mEN#)>XLI}X1X5XLpS5JEjvMZ~xV)=_5|-RsdF!LdR*avU1nuQ$-=j zWX45DcoXrLw)@R^#b2RMnQfT}80g*4AnD4Y*uy*x~wK{e%j@CF$;+`?uVDU^u8^Ebk?7kQ z>laptcb&J%IE#gL3Y+s}h_f!Kg08h=vtA9UrRIqjR6}5+-VhW~0f{=Qp083cKb;yO z;ZnhpRn-GoK&3WCZHnNOnn?d&$(jZb; zOp8FGgTY#E6ZhkXs-}8Hv}Y5=pkS^_Ie-PnTeXS(^zp#o;foy3SN2 z94rVB7@W786WFzsRZ+Uf7fA*Apzb85(U_|#aTB16N;bv5&=ZWtit+;3De3QuiVGp3 zEnr_8J_N*4l%z2au-2+olqXA>u!0)UZS_n_W~Sn=td@c-KBIh!C+{w&RP|-gufZ z{a(4I^wUCl^>dqEK3`GyHz}sC;{$ zlP|&w_y(4|IFStC05Mqbkk6ZwPNvWTN%_7~)c8*}|8Mv$FrQQqx?cgf@ zn^eGxM2Qp~AcMk4O@l=EFAzl03zE0PAEyxN5_QgoqO2fbvNcsnpXPBCVgKY!EhFSk zgFt2$Eh#ZIG%Su^XUcrE4s9AOtrsy+S@H`uQC_o9HTfUZq`&}lyVoza3@LNoe8UJP zG&3S9YG{Tc5OZ+@VtuU7CsR?K8=vpq7)P-FS5_*Rq@<*vb{Ha41>D}A#e=EGEfH{O z%opxhT0KzS{y(PoKO!mqU=iAZ|MMgnZ?8X+xWRywml4<;qR0y!6X58{)_so<#=8+( zr9V??P-b^MySNQhqgO@9LIzI5jvMg#iWoozXh0%re?DbX4s9$qu??ms_wsov;9$5} z698?z%)yWtvtl%9g0bU-%B_w2{-;tJo_1z7j9#>094Y}=@o=0<^+N|iJHiQS3Y+5U0{qqX6Hy)> z;M~R(M8%en@Dy9W8%j{r3IIbEfYK&UD2_D1@om>q@uA|9S^9Lbl9C@c($K{%WK7J*UsMl_cOt1;} zwzJdjhjBhT>T%1B8I^@rki@50S6vP4tCy==y0~g84eWdrJFQq;#2csQ1#Aps3dz=- zVb9Ey*h7s<0^<1Y%Bk8SW~kMA7$F$>1%(SnTESDp{?C(iT?J)AD!#YbLdmb?$>qsz zWe=gz6$R-zjsAx@Jry;I4nkj0UkPm+PS0uWZ0dT>`D1~tO>C%gfO8HVMZg4s)fLXb zN)`Sm`8gycPpolx-0grIZPlQp1d{!FHPA1-tYpHibkM(?4N)&({x4^R`>RASJbXz^ zAI-KI)h0r!bAS(zM29{}!X73l(r~R-9|N3gR81zvg_V?ucyhS8o9&|y4^_t}ri2Oz z&yCn@Hlg8gPLfeQQ38$ra*HXj%;w*5Fk;|7SwgDq#at#h6lm0r8fKvK_Fii0-NR?? zFcl*brOB5)sLTe^dH-{yK$!_TjhDkzn}ve&oKBMoR-*h@fc2%8D6rJzKWdZY1jW_a z!+ZQE=xI{pAm5~cn~8qal}K6s?=y}-WcdQoSwJ_87lJWL@!JB_(ltLRv^d(-2|-vM zVjwSM37IG{wH(-yYs#Gm_3g{|w=Grjx!eEIW z-m2_O#F&u{`+81WGDj!y!#swcK5!)A&F0>rCvK$P9iHM%{>(QDPr!c$eK-3xFu~@3tdnL=@i7pGk;-UX;@)d` z3WPKs-5(X|-(NJ7e?2P!L>cjRluG}cDhFJlM5NjGN*Z>e2rvr1+P#-E?1ct2HYVhy zOvZr-=RpTBvO(j(=Z-*r2OPSPdUILM^C1Ctp4-Z~aug8*g-Hl!CXE`X0a|BJYb~B^ zdH#|CVS#WjudPE9wme9`K0#k+^~JhIYdPIr2x@n{!3$$}tyV4q$Y;-=9-ruV<2)j( zI4X-qK-g%vf$dcYvpzUTxHJN1X&5u7 zBnBP4w(fpydgX_T5PUw^zC_-k>IBjm|E#Z)Ji&%qp!Rl4CitENv6I?dM0b0JkH<%$ zHBN3Jy*}c~jLf}}8{3Q)GXY+0_kipgAaeMe5KJyKPHn7#@e*cPT2)40QH{-*RiX6R zUk=WzPH!DY?LRoEfdEC{bcd^3!grT@S!h|2=k51>D6um7#}yIW;%X5|c_rHLRSdK? zKy0(S4CfZ1I3J1G)89h*xnq7OtM@lZS#xS#6nmfihLo8k?Oqfo{7E2_PCKwa61{E? z)%xzvk}W8ncST?*4XSR-6*XOrD*Ny&6jBYP*^If>;-?92uY(>c#}l|6nCZY$aB|NL z=O-_D`lS?(Q6vpphB?G^+9G>5ZOVza!i(InD4KlE5vb6%KXzk79?i7-pBJ z(ZSAL0a1Eb#J%h(B?YmHK8RZyT7k|sau_rcrxz9UpIka5Z1l)5IjjBib(yyx-U~)0 zo6^`oT3}$qqT;*5kcXI@u_CL}@jl#mn`eh7I< zi_<^zxSYb;RJIG!(VKxSd z_%j#n?24v&hqK;W4jdlks(@x$@epbzkkkJS9x(pVw{Y?mu`MO8IlVhNI=#wQc}%1o??a@IH~ z2^|U6Z5EoM7Cm-rEYILlFYj;s%?P?V5$AVfI^eJrF(}eqe_MzT{`80ue_4r@YyJ8v zF3_9x6`qOAGst#7+^pqnqvvnQ33-@t+cg?QNpzcsIhr4pndl}9VQhW}d zLj9GJec|^Ontez<;cz1z?`aV)*YF@8n!s9Qbd2;I4IM%7LB+~U&I_H53t#zNKC!|6JR;SU@7|s> z_TVXHGXXo~(Hfw-G?Ho5)jEjDzeaHIfa-LG0$^DI#rT6me7A{kT%9F#e5X{c*zwP{ zg9obxnASSx8rywnG87%~M@1NwZ6et8ri95&a@FA`Y)OnDMgF4#DS?Ez6oJgK+`x6= zFUD{BDDY|LiU}%UZIYPK%=;Yx{w>--Sno$mX_KqT?^+$V#SC9zZ3N^~pHE=;UM8af z%&*WvSyA!f-SeR~Oul-QA9oiECZ&5HJrd)J%3+;RfSa2e8#j%J(;we0l=MpKQN9rq z+JfG`cA!Fq-@3s$-cOs7Qj`e`DP^v&MveBw>9-G{&zlP6;m!DNZ=qmmF)OO0DwH^j z-3|UKqgz)4ce+IFQ~AUDOwbfmgxr`+nRKf{PL>|fZRJ`0(+_n*Y9b*~B_OG2JYcA5 zjr0bj-9OcvPNeG2bp*$_*w2SIA512W>cE)|Ywj=bt@+*1bgkQ#bBjzKK-QEN8lz1I zG@?-TeI#WK_3QGq-uqX7Vfec;z|t>fPc=Hm9|J>G81dAxlEuza}C@HN4s(j?_Z3q@p4`91*eM^?^g1rWPXqO}EkwId}!aeej%` z%;|T9ceyr7I)}eKIyJ8ed!>n?fX^$a2pwHj3PeM9kOUDfEeZ-P8PGWc1}Zl2_s+c| zAqd|?UMuoi*l<}5Ri9hNN|e152)vVCuNn>y4?lV^7LSDeVktpy7ydm8jpmksgoLD5 zrLMAa(*3#*T!s>rn1~3dp`qc8f|L}L!){a1s?vfF5hGm%J|;HS(ApY?jZI17*4lEh zX^?`@F#os2B+sOX&tQt0@qOxO>k=JGDm8RZsbDx zH(^1kRm>h9w!I~3Xy4dRTb@`62H=6Y$4N#We>0~s*K^k&hltbDyd$%d+fZ`WnnHP6 za26KjOv#2=-I7OcyOYCBCv_P|fv}ghv;|~CZUM#%i^;|}r|UGwGy%CSP#e!O&C%&; zaoDaOBZ_C*R$uR0;DpRXc=q7OP+M0oD`=C$b#_lDFar96B_nGvR5X4ys((rzzOlla ztCQw0oxVmR9twfpk`RhQ>og_xWE#f_Hdd1)fQgZjJI$e~L*0og2l9qiJ$(%6uqbDOf zs=CdZTXkfRp zJCRJW)@TZIRa#XQeZE|EHyOzZs|OP==q1cryY1J{JTAP})#f8kO>N^w9=ByCzW*cE zynb17U}_vzm3buzHG~C%-;N#9%ib z5#zwQFse^-VV~3Bf%n}d(~&L<28HmGgy(RU;Xe77hK5*Z$X?%M@coX=zA8O%JMqYq zupa28m46IAVX-Vk=0d&=(evT*&%!Z24uX(-6L0*vhZNv+*N>Ah*Es12i;A^1@<5@0 zoz>7^Vj5h+3U2k6R#EMhwaFAfpc9u5>$T8(N5FW!i^##6O{LL5L_z{mQBi5O+sdlx zoA?&^%-Bo6s{1-oMRa{`@aa;Qg%gtF95H8aIH%(4o-`V zf)Pin5Z7fb1^3Ei&7u;Nc%zbrIqJPUwXo*dl9(@g9Uv|?BB&(-Lv7=ZPER*M#4}CL z$fq)XX{#ksZN#_9+4K_azldeCkOAxM7$LqBB56(m=j>LZi@k6Os`Z=fw&jgO? zX~O`_4F5WmmojB2&-?L-o8kG61F{M(k+RZpK^C74jnD)Jz9|E=tc;w9i4CUn=eeYe zl(3Btw96k?Qk5}Fs>p~)nV_^de9+r!MlD(R^*tpl%gbSFEU|K`CE?+HbovjxL1@S0 zeM?y*Xu#v(bOb_w1&hL3S83oOUus%T#8U}sdAVgh-W2Lu(GsjaczfR|UGhWlRE*5fb zbZzXMK;VlEA1}+OknA3b5qg^B-0%2UAZQQ0s%rbfGzJ5E7v0@XhRln~hm?E zD8`M%*q-dnCr1|OL>t2zW)@>*!<%-OTD|rVaglZQ>9<$qoT2z{@9*!9&$p(2A^A9G zC+J6M>|=EJ=-H&DrKLCIGOM+E#^1?rZ8S2m>l+%VY}Ke6j{cmj;P8K=$&JAVe|aGc z-r18&c<)^vY-j2_!jh4f0@>qh$3nn)E}%I z5v0Xmhhw@_tj7l#Ee@(d(J4O&XY#KNS97B^lx7wGa~|2u&Bs*Cl>Kt>5qz`LBkNaG3`yo+Wu20Bwh0(&>b2Lt7S4R2Ji6K=oAU{K_C-*t{Hy&5? z!TeC8g_n2CjUJ-WLm~vD$bDEY{y!ayOodG}ej5*njjNvnA%EP7B&9@r&UrFcZUq}Z zMMxWv=)Lts|D9XL6- zVZr7~B9FHo-n;>^aOBV9VDb5z;W|^j239m*5Sk^l+y6l(v)s5cFxNkRBx-0*X+#m6 zh?#w@-3o|(4kt<`KKOc*0d|Sq?r`bIO>_?xZnpHO-a8Jq9eO7arO^Hi@Ogs3-a_BP=rqO`QoUuEUPz!!@s6#%VS%&W3#i-L6;68u8W}R{zZ#P30)J@oxs8E=_1%IfpR(EmTYd%)%HbgpXTO$_8 zoNhCN^`!MvCQ~-Amga%tA)I;3Guud`i!FbAFXm5{i?V~u*w+jmGhF)1z936$zwW!w z;~AXoAK@&?R5Ey|T13-|jrqF+;WSeMO54Cb`S?yRbLz z9{KpYy8%EmwJP>MGcCrhV1 z1&HXwu^h_He%MRouO{)ME7%bP6M}&~ET5XqKyY-fge0<~u~P_!g~>Jj^#)GROpwrV z;T5IiNe2Qw@g1lhq0cJH`(0PP_NFb9v3S2W8a5}Ie+P}20vzK)idHoS3kDZUnxPy%`^@N$8To{7_uIYJ`8oZMkAT8z&FYQ zDJmiL7b$t)b9q4~o7s+jc4D!-YWve_HGFwOtI>oW`N_9yHF`NPk*WwBWpTO}HQ}E>xIML`h1Ice zZ8IkSEFBX!*t3Mt;IQG(XjvV$=H8jXWlE5i!yj@jW1Ttkri#1PqltSEUFE~i+z^oY z-E_t(GW3F0aYz(t>O(u=ce49Y+?>nIo2fkhjPFn5fsnm%+y@+B`^&+Pu1U_#c6B#w z=zSB-;srj>w_L#se19Dh?53k6WY2CgD6r*& zc3|WrCnq0PbO*uW>h>hu-+~J(t1=m{?@C0(P-_js)q;F|f58Tyz-;Z;Mx~u!6Iw2jktequ+GA z-d7Og@fPj&gsk%;F{mg5H`m|*<@XIcpW!ah1F_!hbjER%(!%6$2Ctr~ILRbvvxMoe zM``!}ecu>x-`H!Y0Q;kY8A7sFaAiw_23DQab985%BLSsW->qBO6{U15ZfPpn-=Qb#9%5c zQ~++zpwQj!3L`{tu+TWC*<4G(yvo$rj6Q*%EaD~&RM}ulrMAYSb~)T=qBn!LlI7I? zz6;gpa>;1?ld&A8{aGoo8yiPwa6}!UZhN@coq-_d!8`tgUyiV@02-(E61qsgmz&3D z;^#Cf+L}}s(OzQtq|HWZ-z_n(&l97+1G@Qxa+;j(aJT>Q9pZiQK5lSZx+Y{LbZXIc5=6Xr@Sn%Ae(gpJS9L-gnkKDU^P)upn<1@Y z2SMNr4SOaT6~cZXe0|;X2cxmUb#+$^3hBtS9iZ$sYXQ%9Cm3EpQmxQWm^%ATAdOcG!HfH(V&zEGVz z9w^seKU-7@7?1sJ#^bXAz5?7)M5dseD1^~rEdK2)AFCMsgRax=BaeM8u;{TTJ{mbm zm`^w;?PLw(s^tGvZ#=1iip#%3upJIHc(3}Mvi}O{K;iy$Se(ljFmJMQpYL!sKY#mV z6l3QYf_JTNZXW*nEa?d=P_0V+rVHZz|KjSOqvPtr{&6^&*tV0#Zfvu$%|?xF+i4qX zV%xTphK+68{!Q=adA{#j@1L1u;iwc3_bi*C8tmm1lof^-vPtIJQ_O^s@DTg9 z{h`Q?3}uX~$ORe8HOy&I=DooJc55aPxdrA_y?!eq{M%ix>6X&FQY8 z@$ic}zw-lZTdd(2W{6A+21*O}iph8x5%*q7lq!toR$mO0*5jkBo<~ZAjPoLy$U0(R z%7U?*FUDO)D}-ak9O-xr&``W^YpZP(cdoVSi!F!+nHA5`S_JFp_6MvFPl~AX!K}5u z;?5n|4s_bqqkb@8MlW0rmrUB(cn|o&DzS=dEPc~z#ElrFXg6N2$ZfgfhMjuvW3e44 z+ZrOT;C>@iM>InvHw}(0#}*FfGf5)+A5Qzt31DSqwbbd&Rd6l7X^4CagR$3ye7@Su zY|!Bm7>aAgmW&V2&Kw zON@R@fIFG62f2ZSbC{&jDt~)VdlQ7eqJKmHJ37cGwlx!K?O-JcaF%@8`g70bkwzTk z=v=ftHXwkz*)8zElp3RU%E|q;S*Y$;{&agK7c!UaSd(-@=ucmZv(#%b4FCP=D7vvT9XNV(q##mGXhl(strMFti!(hwDGaF!;50T_FIj}F zW=Lf+fJ7>r4?dU>Ey3g;J>BBLIh1TXrxcx)u$<$F(QwX{N)-9=Q|Kn!`nP+ea>@RT zlnc$TI^?p&D(Fux<2N#X?D_I~D}E@S?=XIY|J&}c`5__&b#9@xQ$q#7i2DB*nYtr{ zfBc|R$mSot6u*uBRq)*p4P1c?0TFS}0)o4qK~;6mFwtrIOTF)*PNrZR(eZWU6Dkl= z41upDqrRV@_3T&w_KYieS!S6UF0S z+0(mx-U>nIN!@Qp9^7)w|Lw#3Uw@MXwWSI1op}wXW{$fu!^7n8*J#HM>dgTjI^@1M z+_d5UrWG?tw~I9ybD{2-gKEWy(>v$rkXHS)D#Pwc;PBO{^YbXCSrUt-158NdZ)J^; z(k^fv4u`O8(pO-2EyhBf@<)Aq&~*JJi;I;OI4afcbxdZrnho82bvVvyQtiQ>^N4Or z{~I!+aWzGN?E%{dO>tMdIpAHA|Ml0J`) zu&A9A7D=A`-Uzl%eJN`8V(T9y?*31g2@;t0xYDgQT0j0SRl3U~?fC;15*m745B~mg zA6!&quKZoMhW~rgHGwKv*Twhgo_ykTuRYlNSdWEyy_x`DCqC_l2b(d$R$o4stI2bb z&4>WZf2S?SwOfd^x*cJWSwEmC4JO&u76yuv%pBP=dNGogrED4hvyvuUUy4~&qm~f) z;ss}aeowhw@RdUoGxlb@G;uhtGrY!imubzPE?C5wGhf2?{-7%Dg8=H&ARzoWjn>;-OH_-I%hXC$aF^e1*a_O^11o+i*}z_n&lN+0zKDtj zx-l>(*(;k(gw`Zy9uKz*Mk^8wZ_OApVCH0_NO`7VZkcI_h|S9H|BGrm0L^Lxi9*n@ zpga-rng5#wFptdEoh*E;5Sszc?RJKnE#w~uI^W4pV;<~f;h7MhlwCb)!sJS_aMK29 zg$>&!OaCo&AJx^%y)`T(KucR2%S|KEj|?4DoKX@I5nY3vtHHV>@^SwOqyB%kd>;`~ zT3Wcr%S{;fBh1!W#h$)C00cB*PdbP7)x-JftRYz$I4JxINr2S5z&@#;|0(j!euKG> z*;ujQ(PrEs6l<*UfcJ+X?P9g>4!8E#|C>5MS_ugP`4*Cky>J4AsX$$OKuy7!fCU0- za1d%>o$%J#a=qnJ4cXq_QA0u9bT)7?Q1whsPOiq4o{u*A-@>TK1Ym-d+PIau^uoeA zZjX3{P<_W_;0`4Rm<9B-yI+!0P(V;nOAJUcu4R|r(-wSMg;-BSeROgt*3 zj&`sl;~KR_kRUM)HAtTNQka<%_t7xCw>FMz#e@4M)XVFF23fBaVuU{56!=lY`PV#r zq;UHv+uw1R8EkByF4rGeHGQCvLQOpnDGD?gJnxZ%6zYnpap7q=JBh}}Uc(+pLUqaSxKq#WYfQ9LYc|(r)d&7xYKwS6HqGW~t^t zKkgPY^T5{7kPxHCi*=9t6Rd7i+2J@MV@pe|ttZT@SGYB=E5gTjgWk$Efiqk9!?XCK z9$j26FOniAEwJzyP27cgt_K!R&zeWY3O>AOtGTc(5PmuR{+RM)Kd&Z7GK0m6Er>hY z3ia`Pi_#G@)q|;M%8<%Q%*clXVldLRIGqvIGTU>VUB%?^xbOiKd=2hQpYLE=h*h^j zAn`j%REB23{pq6VY=Mkcn+t7`A~0Js0r2eT=uhEo7|CFIF`8FVq7hJ$k{JQ7FJr6LOux9VIcKib0fp@DNn zk0TP-3tp{pE{n5GK*T-$)kQx6VJBv&%=!OQ;Q{MYNbk;|E$90tton1v zAtrdbp&#w^EyD3RdwN$cb5Zb9pFO`PDvRBEi2mb=%}8E9OPz4*f5!6hwtb1E{;;~3Y>Wx zZ;Q_x3skO@+U@zo2oOR%X4gOZv39l*w*gEy#bL3)1Zc8!mtyfc)2ZppkVKkX<|OQ7&V1z zZ-0NMFr#E_Z*aQqs~X+X&LbMd^lC9vl_6}1hNr1oa&(yOZX9m!+i7~~uIqOiC&l_A z(}$zLlD|3hA1~gFUXM1B!-{X+?Q%i{fqYxm2NP)>zsB@GUrw1pohQTJujt+1QkdRK zdr^q_X(%}IexQPrgB+@BpBXpsB7WjI4d_bPCSzN6s8qwEbF&!bEAt^v={!~OA4GpT zm;kjiC7ZVV_^T(qRwwLtB>YgCC>p|gN;E@L?+9%G&hO)HB5&!*Z##pFQufRSop5Zg zx`jzbwJCfwbVR4_MDz|kiAk6<1M7Ge)oT((EC^|7q634}J6omY+%7NpiI`BhE8{S> z>1{aN^2RsTcULxHM`~pJzQy@*rO^0O#UxL19Dg%Ub;yICJ@0LH12Bqfs>60xwJ za#n_rm%NTJfBjY^t0oNy3bO3>36~V)R-eKsJr<>*p$lYGHkw48Qt(^(QEO~%sAsoK zRBDB%WL`&=VT*s)_|<2s{;tK{!}Tu?8S_-nfDsJ|$G6ncshE!IN2$w=&ShV_Th0r< z!>KfX2kN0;6ae{j_HC?y)5Yrk`T3*(&`wes0!`sj8p2O3`z;?3Yx#ARWMqW41{qi~ zm;5`nu1sgLI?o%Ar=;|7`_oK1GCoQDVn%&5_>92X`gE%E$eRq6+vR|6!A>ZsWXZ$L zBZ;A`PCxKR{bX0UD%O(P*XM1*R#vAf=L%A#0UVVt{g{ASlQaq#ZBOvT?rZb?MCc1u zT&9O-~Iz|QyEQ@Pc%U@?&bzgB~Zi;Ek98vQMs##ZFC%1TBbAD^f& zrhSzP$i00DbG%S(*h#l^KAGS3rN}5KDc=W)YU+Q?(|w4mM^dl9sQ{XZ1&77D7jf6S zDb6YoM%}VvZ*T%}-&L4)2Ap)T;n)##^TAV7eSA3wKrTGOEKu<;+A}^Ly*Vu`BXgYb z^-JVkQik(kHFhE14ES4_tFM^10D!(gG>*tztOL zdI0Ib&&qMfL1xHvXvL6d)>o8!gmsYWs_Q7#anut6N5Vpd4v1)p5?sZ;U*^3AEuS*ToBUuVpV5Y{$Og!h;uK<0TZeP z`c)!!OQkAhZO2S%#q6u8hqGmhhdgUIG9|TezW0+8r!3zKQX(huobRX!!OERhO6=G~ zM+GIOK~4u=ET&^8Me-TbpnKM{2LEnmRtw_nwRCh2bbUDTe~h4}3M-SM___^2^Bhx5 z*IOtW1nyzVxVqkpf*YwcQl*!^$M&SUBre$i^N`F|DUvfl;?s5JUThb>_S{Wi>C7!>n%L*H8V4;+UCh}9gVoZe5vo?pL60nZqy=dP)r zx1v7e5Cl@xIYHoSgbcMV2e>1Nxhmt` z>%tsNUz<>X+ytXMhb=<%v=&j{hfLeybMjZ5V71=5{2f{jK(Zzfd_Sk*?x6vtJs+u$QRQb*#U3e456l5de{Z@UquDb*j|B?OLq92`rpwf4^;+ZN;}d{Y z|KAj2jHa~vv)O=pn@#>fQwsFy#T^AnH3{rc0A`MG99D^5YaRb!Q-h!Q4rblM!@~_9 z)hxM*mF;-SpGAWQrQ9I?&Ckg!zTZ34XEJl^v4lM6v#J2QA?lpV!K|3- zAqF%k8sWf93Q|TNn#yvDcSAZPDA^B{nyf4$WD>y`tGS~6O!(RYOr;#*CO0sK8?}LR z3Zd~cc|PQ!v?gD&Sg3~DMl7z69haZmPlcgH>Yyw7da-76NNdwTex!4O^mlh3pn!K1 z|M=iww9M|?p8?rm2pHr6P$u0(`<+tvt%o$4&rEYamHFR&=#i4HKRq7L!GJU($$VfW z{%@=rRUpxEzSKB9w2VAi*t6;hd9TPWA4 z>;vgK_Y@g)nrvv}b^odp%Skl@^wwmWv*ltz%N$A8zZp@LcS9sM^gMdLq$b}Q8Kr(QV0I_jAKo`!Yf2i zM2V#|TVEkATxP}5&z-hHvpV+Q`nya}G*?Z+JHX9VO^-0pO@e_I10249Ea53pKRx#3 z<^FW3!3raeh>t2<(D#KMM6GYc;Sq%3H@R3)=752_fniRMRFFf_B=CT%>oMfzZ+3Y{#Kwtc z(m~AqiagtIFd5vTT%$=Chdh|fimvW@k*!kSk@p9g016a(bTe?%ttl18E}tn4Fb@X^ z1|y{+GzWL)PlZDyDL>BBOvg7kO42mhEXg>jB=t~4WAGy)F*XOxnKV$6vuU1Qpvd^i zvJ)psimS+f`Mc}rUMP_&3!{kzpwo{7|2_FvatH5A6^1vd*!g;@qKKxuRmX^GUTh3r zN;$cNogXJKDmu~CgQok77%C_Uk@d6GRjfPa(wi9#H7ViYQepL@HvCp(ELDyP#uqlR zq@Az~odhf{M@p@PvzTkMEIBH!s?5o5U0OBw=wI;wI9OZI8B>M$?XJOieR zV}`C!=!}G`$)22c%`rXvpf2OJ!*A51dk)Rmi6xe|=gIzT9+qqy_RP#9<4kq-oM1Vl zdOe~tb-;^mDst{Voq#(Hi)Em>)8sh(Tj>vko)gsofE7Zj43I7=9*d$s2(6SexIDj; zswUE^u6E=H(Q4 zMMr2@n91kIJFZr}ha;IHdk`BHOuELi^d z*VlA%h8@VeU8!M;tC;pXkmLLK%Y$B zHX*h2dCoE*1#M(>h`dBygx}R@PP-DT7c;Z|qyKb`$)?2%u23MLWyHuwz!How19@Nq zP2a(z*X6IB0J8J2dtbk^lq0i7o0Tz)Fv3I@A+1uEkEe9BgKRz6yXQV_I)`*2zKqz% z?@kmWz&F;psb3^TyZtJ0EXq>bOTb6v4NAvtMT}JKkeyt2NZFJIDGy8OsF2;=-|NTJ z--IMci9wH12WAL3Uy|IY{cp1}0U&8-R z3}JDcYV_uZPhIbPAhFx2s3Y$wS7VsRoRD1tS0Cw{KAlO_$LEuG|Jp4QPJL(v@!sQ` z?g!R8FzU$uX6aTX4M%8cZ#M;HKbnLoS~K|p0k7GJ&%~4gL$o&cA7P`06T=sCi!7JJ zg}9w>m~xHobmm8k+|pL2^VyH~b)| zhq)$>MTzdhWi1W%{TneE^K~p;U!g#d@Rf)_d}0z;bN_(y`j#<}9k4tx1jPo;iP`)q z{I~&8>$L>)^g6~UzE>Jme=60haGs z(eSB*9PwV62!B5`zG|uMtxT1t;bw>f`7GFa8L`1L3Ix=h8K@#Ca9!PRiIxjk!N_NW zht8Z^V)0U1?oRYnezP#FGsYu_TKtuH-;aE*tVvuxK481DRuC>*%dYqH#Fh@Qg4|-Q zO_WpMm$sf^%z?h4Hzq|%hQkZtu65h!v^xj#gkC>$&+t4OK zTSn}!eO~7P5xf$qNKXz?02~GtYBs=weV&W=cLDqPr>eQ#U%q7W>lis+GHG+7_}t(UX=F=@_x*zSFi@-! z8o>UXsEU8==8fXJ*JJst5c+s3A}I22hZycC>!W?b`-=>vyv$E3vBrQC2B#!E4A}JJ zfQ#0=94<4A&sU1ZPMzzFjB_?}!c+L*4iJ>p%dnfh1av`jGk))&Tlf{>u@C!#cbFbCQT&u1GyI0KWe?~ z3D0cU=Yq_cnC06dDcBI-V zybI{)==6x{)M?qMtkja*S|c2vhr8JIot!%rRJ5yES=SClG=#x%!52{WY{oTw_sITN zhcltl?EJ(LQS7YUns()Hc9xjmc~%A&(W-ewSLlwAn(uRadOuSq{8$uvZ&a7qTK(g{ zV;lj`hmzIbij$6$JqH96qthVegys10*gqg|(Fn=<5pT4)EhTO>_1%P;Z2hfrC@18} z$(kFI_`Iv{XK`+tGz0CJI;-uD|;hBVQ;nyTfe#~UoaN`Sm zoPETChIXIRv_x&*hcEQ)3PR+AFPm_#)yuaCe=jMzyyQY!6Q`=W=YHm01ecHlu12TA zU4SgAe@nsmzZbA#=5FYd#=L=WE`mZO+!ULW4Dd0!hup;;jMJU zhLOt}V|?lTy}iV750O9{szLdBDig}@?wT-5+UY%m%iwVuZ`EJq=?$c5NwXy*DZ6Tp zUXi%3+2x$&y+kRy3O31)RUNO(OP2?V*I7+0(;Ef{q7-KaYpc7plK3Q@Ck-nah|qu5 zNT+62@m-MULILN>QQaH`s5l+^6w4n$v#Oj;WVYYM$T8wDZqTJfL_}a=<(J}=naO38{Vs>Fmdj)k@YCAz7oN-~&s9`6v_z}T=(#bIfE|ukc1cq61jOnjG zxKz#II;*7ic(RSjvmW~-fNNppjl8}$$D_KGCoU=Hoj<4PN^jZg075|GI%Cfp=zPE* z=?Sk5_~&Sc3(L02?yKz3)BYA6gg1_Ql3hDdSMcBw5&Zep&LkC6NWPLaCzk3Ra8Fm* zG5`Vp)*JxiN2rNRqNo>Ip1u3iXKPB+*NK#)K^WvY zy)rF*E#oQZnCyK5wfh>)w`16xTBw;m8w0Iv%FP{t4Z$Jx-%%> z)RH!73NhoZ&@{MR+$vcmsr~94{Pb8V6sXeELWm_;WOsDh%+x#I)=(vx8yxdq4`zWRrh;`&X$a4X-~x#;y)dZ;2umMVXpdCf+jU zH-D`l3Yg2Cd}S4CPE2PU+psKL6%qohu*zv#-M5FzscO7swny0l zFuk<72D78ZnhGW#o*Z@;&u~>c*CR19&Mc<8cs}1hV2vs9w>B@^$(Wuf+vEj;65R42 zj0*eG_seTeIw%z?Nsu(_jed?Qwh)u?g5}{1Gp<4{fsZ^;8G-+A!w!$ZQrkO5A}Cpi zl9DGDt2nFv?9~WAvaNU1n&%_%C;Ie4L!$)^$c{KH+VNz~cwt&u32(evEtFp*MeHMJ z4fFAFYybB+7Z2m}%9Vy`&5yBIy-8C0*<#}@bg<6YJr^Ef=$4$gBwJE0+Nafo~_K<>GS%<&vue4Cc9N3|ajL=3E%FdN-{d0}GjqeM2Qok3 zyjWTYYPGLHzF%k5&Vk_^{Zomym5<*w)W=uv*fyli6dY+bXQ$x}AWUR2IZEL0B8y}N z-jelSX?enDB2$Yuc4uxq_3hO6eWwsj+o+jy>j=V~tFxatZu*9S@2e7*qW^V0Yn}(; z?USL(REDAg1StxQ*^x;tPXo;A{c%J(#!m&MPqTDFyiFxhczS4Z(~4g9FQ~K}tt(NT#ahgU`oRY_`-~F^K8xacdmSB8*^02nP;sTy zp_;R7QhOC%dGxnka7&Mv+1)>8h{P|DNWMJR+KM&=4<2WP`Xn30T0>5vk_m&wwjKui zt`g}R>+bCTU(coNb7D_@0EK};Ai_`+lQ7^V+XDBYQWj~O&}Qtn){PxtJ-pC2b;?RL zVGvopnB4cP%Wg*|2ve6ajC|k!^d-viz94$7PCI}oz{U>DToDvcNbCQDC~ee+@`WE@ zBM9V03X>ZTCIatFR?_Qp#I#C zA!Sf_Y>4}`=AxcN&9Gu<0DCGZ5vB*oh05YqBE~L?B3j+ygbZSPrh9iLbt;a3QrnYN zWWJHTDC)-@WapztQ+={y)ce|It>NqoJ(IjNlmuO5r5oSi+~(r1Lp?IT1vaKsUSG!5 z;_B*md}BS;l(S1l+2zU<_pMcmOzUKmeR_}PA@~gNUbD90y~UK51e6j?4lmfA)}D!~ z##o&NqF&!P#ERwt^70?fdi5Fj9H2hWJ~vkvRTGn8mMM)mRc)4&cy0?pn46It!2j(U zrcATiPENu^8BS?nxHi%d32mykg?gFHemK5&T_SbSTx(ax7NWm z(G6MRr_R07@VY{_{;=GhnYnq`4i>%1JUc66NpvGOG@;&_Ql$;tos}kvzd=i2I5^sq z%^Pe(^&a%AkHoaL3#OmYJ4)Zqt?B(;wnG#9d~&|{^Xv${-7JM3e11!`X;j-GqXA(O zLOSV}6>R-g4iT*D+1^s?_#8Ldz$C+a)Z^6rXBZ^3`x{Os0pxxu*R?B#F(e}VWQkWv zGl%OF-xB@ko$_oXr3MeDV2bOswDWxbB#E1CuP z&A79Nh5NtR>tC#^5YM5Z1w+1Fo8v|O=C66IG(^L9KnY}KDtH}V<7Cc^+IuU;rP^U# z$ROI<<6J8Sz2h8Qa4YUVTfM2!gkbA(y~eV%VH>{|7_ra^lyTv~>>rQIn%I8T7ox;CcED`j22xvt*#C&zpc7@~=yB3M|}= z6Z4s`O(iYrV4J{>R$O%*SPYNfnys_HYCLqrbQ!0xIKO;FL>}DiKQYA4Psq>3nO52M zzwHvsxHcp;#Q&XTv(f;^%F3#3{tFxH_UdZHiB|>CCjCvPBIcCksDLLG7KBVAfuOeU z5WMvTU{FqB0Xl`~^x^5GR9_*{Y7a(sO{!^IB2%OJYT>WxAfxAb=S>8iEi70yTez#E zqOlZV8Bnp0!abaIxp|hxa!pN5jg9R9-HU-Wt}a29uCqwq9@04@5F;7Gl(e?4gl`Z* z#)scg*y!1wI|@^!I$h(ZSWoAgoYGI09OQ^Lun72>w{DGN_nfVYDQ{dI0z<9%Cm0xV zlEv_ zpx?A2>`k^GBJCQYPMyvrHyJzuo)@3@{G2!3J-b|GalLR-tJDHtB<|>Qr(euXcINiF zKS4+_NxD9}plrbX3Nc7ty|q%ln96@3RiQJD^S;^gp$%Nnq5lWAg0}ND2vacPx9$A} z`csn1i0&g4F_^yTQU}@F6;|+K3EN-bNm_S|TC+Oe^AiqtzFuG_-ym1)y%#nH3m6tn z;3D-%r6p8P;`6y4>lZyaMg)ez=Fg7TM*O~#*tdZ-=Xmi~{Vy7@;IlypQtI(M{0L|3 zkXdjj>ikf7_7Uu?{IUN=8v^xhk6foYyY$cFQy1|1?4^1~3kewhXsp|TjU9=_2XT=t z$5A;}jnY>uDa7!uQ*eKVuG5@ZOIfUHrG~O+w+kB1PwcJtD_)T1ba+c}egC$rIy>*zzN^+SOpaP* z`VCL9$-HuB3nyI1qaTVK;Q}NI6Jh^eX*{dl%oj|Tnx1Z}qJ5P3ulnp(Sf%OYl?7@X z-j2N+Eku|hc&0G@IxetzeLmN-4RnOENFr9hKXVoCc}wOB;CNk+5mi}*Wj6*;7F8Nm zT0hKB_>2CFR;K@+4Ob`7?BBC#^ib0%={B(lktB{@1`ROvEJ!#zk~cseOuZpLX9e21 z!u;qTqj35a*Wi8f6q0ce!j`K7$p(+@Ak`c9&O*NiqdF8XIq%Ci$RJ`>yiYxwz~%Zy6l3mJlt~c}(OsYJ#!qvu zI>(X_kSV5jo}c(<;6}>}J1%SP_L0B^-$b^3c(ni7&{6GX{>J?#`_IA0E46B_zXpn3 zw^t{$wJIkhG@A7kFD_-Vu-(O4b(WNC)(ukK3a+_P@B`@*2&fs=@Pfo^>WDqE*3md- z%Tb-hcKKGtB9;dAkUqrvgR_l%%I&+PE+zUZaYw$pG=BaCeF1Tmv$7F~|DptqEGSAy zaB$Io1Bd^vwzW1{`P3TIj{6%#`(LCPsTBf1o*~*K?oZSwPocpk&u@;@H{d?O9Bdl} z9e)->6wmb{+lWwwiW&X%^Z|`gI>y&1w=<6jiVgO2fOG0ekx`%D+wN8bRgjcxrPOAO zmyJgp_~8S8?qV)EO^+M?&Yi3kGPWUqLYu7@_kQ-7>%q@{+1XCUDd%DoHEXY0qB2Jd z`o@^ro+!MCKlAi`HXe7mk%~WsIY@ook7jiZ9q7}9{JU5Vlk2FqhBg(ZX*Pjup1wk_ z1FBP~2E%cq>qF8p7rr%KlEcerWX(ABRYsLN$uGuNHKU)}pO62=kbpa>C49JC(j+4V zV#2^iBEd@8hxMwH>-W!iL&Mb|UWkL8^4`knVhyp(ht9BEd4gQg#dy}8PIDR(2a>W? z?-}bJTue*O1fl>nEYBPHz|ahTDJ7d(gco~*#o<~e^CHh?lT@Hk)3EOzABxy%SAfO&3ei zv8Viw_l6iTsqNslC$hV~QKqi|>$8_#{wTHc2$C_$euXuMl#)5fgX?r-aVKah&Zi&S zqBa}1TzwO_#c2yeK*nv)BYt>IyXcoe|Kxl>b{jf1w+x5pSq`7Kdqt1?qe8t&t8Yyv zDTk6EVGY*3cZ_&*{7R4PUZ+zS5Avrga?ydpQmYy3*&w25f6?Sn=_&J;N|h$v;=YZF zUp+$vhWlimoTH|m&SP|{@iEp1?-iJJXLr9{ISjYk9r;^TW?xHapVO3Fg-|nsbUuWU zVIJcJ&^o9Od3&kFfvC^ta#wD^o16QSdSIPD0^#uu&EW~viT)1NBIRD-H~tpi<5s{FqWhx0wHk%|tY6;-qU+ z!F!E)u<<7S7HZY9I%7EsS=gKFxyALdcjfk3c0o+_4=mPFEA|kGkZxQ=cb8SS50u%V zf7Yn8Q~e@7m+eNYLTozpWiLxoM}m&C-(m+LVld5+9h5T=_*{rs^fHj?5|bVaZ?j(G zq?i4-wF(w?bJ_NOIjNQebnj@BUix56{Eb*RN_v0owU$lhEJTD4qQ#~EHU?f` zF;{lqiUL~<1%m zo3ZhEW?;A)tK%yuc6Mq_b7deTZl$^v#{{WnY_cA)KRn=ElDPWY|D$)s^s@jotx`%w zM^z(B`qcOJGr~4?e3tqX28B4${-cnvFyrq1_0be05#*%}aLMoXeRZ>axi%pOKlV7B z%;J>+M(!Da3xbby+K#6yg9;rMUhu`Jo%cvCb5YUtR!gC$Z>c&Kms~i1goWZ*^qBtGQ;j5Q<)##+^Y(& z{fB_eenJ?8E1Keq(K`B?|X@lR=O5 zQd%|l?0qJ?GabJ4K3ZCTS+_S-BND z=wge>Bq3#5cs{GSfDdk0G~k;X49N98*mPZqc6CJzUELL-#phk|Qh@YhuleU~;?Uc- zen0js2zk~C@#1aJl{c~N?BA*BbwN_kO<6@{ajOL8=Gd_06G^N*A zteuJyvDJJ3DXRVhgn1N&JBl5*8!4e1nZi9ceZylH-+#}OVFyF|MgIOl?Xy;ihV1({ahLM{9uYi|@HrpKG{F;?J5eG64xbMUr=%L!#U<>+QgXB5^r$swB^_ zwOCli7xwT9J(XAY0%(EX?cR(Ph!Gg(OJ!cw90Xn)iWZ#kxg|9 z9k{y}AyvhTg;(Nin5Ya;vN;9$ ztaLn_XOu3@)CjDYK~L@Q$kyOXk^cUVVwE7BQj+JvkDr-~-0;2yNE~6OGF; zhuWIq3nJ%QlX19;H&3EA{`jFnqRo7B!P5f%uN@Xq=%JZt)e5PuS%f$R5Q ztX3;^S^7bCdIV~R&pzhagRE5`eGddAWPx6#f~;wiG{v=r`Ite0G+KlGCNXGoz?huN z(C8q*2apg=kfNUdKj;T;Qa~i_4Nl|WQe?dmIwthD+J&L)c)G3YYwHBTpCH(=?(J(c zUl=kl%;fp}nqdT6*DnpW7)11zo_eYsvml2usL`lYa(HRF_DXx^aQmWk&i| zV&_=2S|-}FK@%fiv-~l{AW3vxfD;KGGefo8C!hT~7(>Q*H4cnds`oW@q1}a5pBbtV z^n#gLP``5AC6Bm$6f?G%(Uv*XC{`e1FzCRY9qWwD2u;F*k7P&pr^=o>Qsm;|y1U#Y z0ZFI@isaIM%^V>Dzy0Gh3X#Tt{L2{sS|s_N*+y;yqD&NZ8wT>7zYaAs6Ax;g>db_e zg|xPyHMuI0!3Y^HF|x3z%-V6Do{pbsH)J=NFRE#-O@J6CNvHd4aJlX2cRuBS^I=6Y z75d$m7U3Y%AI6Tu_StEWG`li_?0I9PGF;$FHBoVX<@lPua;o8ZYf|(7wfB_`T{cg+ zbV!JFgMxH-Nr;5Blt_0scxKjXv=BLLRlmJxs3%31l~W+_f|{S)8`iPFsI4L$H;$gJV8a(Q0@> zpgXNRM{k_$U|V!;pxIGSe)f2p$4QToe44qS_Akav38tRCpiY+lnMIYjZFQy8B|5g6 zn3Ob7pv7OuxM)QGr9BG7x^>6-1_mN&;iarEv)rgTYQDvlw|u)K=gnr+NzTB43f@E= zm4^Q;f0ZSl!Xz(Bh)p@0HvdHp8Xa2k^-#&;ZHHRg`PT#?ai1h0uIh#DgTtlY4>T+6 z2;w=ila>YMWVl^@>Z;uX303Hungncnww7Mb%{rH3Y%P5*TTr@)cZk`BpCAMmtqF)TnpA;xgr{)uSct5B=@!6_<;Z6PzCZ;WNhXwgea-7 ztl9lRgEu)|L24Dc4t=U>eHsy|p-b<8*epfA2v5*=N|`mePbF zBx7zy=gux1L>AVyQTsaP=xS$^ z^~If5Ehbew5jP8(bFoct0N6>J?_vK5YkK{qI}9cVX$e$7i7MgUiLCmBNa~u@?F!HR z4U@ajD2Qw{uc^Ox`kBdEtPy%)YRaMnj&&5C3^1?}e z=;@ULA)LQCC*l*FKPmxC4wi19<>A_ZTKVg^hu=CCNkJr1GswsI7U{1@Q39Jf9Boqf z$1jZC@d9S#YtY1-?RC#;IU*t=4%2=piEvU*^OSV4kj04-6LBqZ14d$gsJ2Nq2E1FN zFSaCAf3bnY>zQiK34+U?pjHhAs1GVCDH(XhHXzc;s9xFt;-k}iBO{~WKsb=O^=R~e zGZgkFrqk8ehXDw3a)NJM?_ow0k>*cgRQ^1Z8s}w!=J(eQt!)N~!o{+E!FQ_~f&)Ru z0bxYkgqh=`qoX#?&h7ac6{sI|jM;5L+^<>|O^Fdlxyu$5zD7uq!0j1QAV>3ViF0jg zI)pHJDZc|%z-}^%%p%)(l_(!jYDKL_!&zoOg zfz(2?F&gfdFJHpJ!QmTCgqA6QF)X@@H2;o)18tVZqobpPZ%&()xSMVXQrK+{R(h06 zUFbLg3@9os@cxd;{*5jzFm-Q^n(E)4qpCK6ymBHANT{j|-Q3=fc6LJ9;)Mxlg?~X{ zN%;mf@Ev|7sF#^9>@RnTcRj8v>edrpwiu%u-1#hbigr+-aAMz=r|y_tp5GZcuf&?bHQ?;DM*SS)XKLVqs+jDBJ6N z1ejINWfXSnh)@U=&JYi?S=rp2;)Q}D4|)DfM7f*5ceLDeAl>EcFh}G-#@ZOvL`OnH zleM;K_5Z&ah6oNM`#-?M)GzufsT5%~Q$3=4YD7t4R-O)0M2#qeA2ol2P3bo2_8)`n9XEr<(^`(OJ480xQtKKh8@Rn7u`!j?W zn*7iN5$lK7$LrtLkXl4lW&Zs6Gfgpv4eymmF}PeP7?gayBcB|!w6ruFJUl_3-DBzK z7Er$)Em}vMEjTo^Thd0%-w09oe@=4(++?YlFK9(nDs__ta>MlT)a*lHAhx60){yS@ zzY642aGAWjJJVGL{TH7J0?|qM4EqI!KD~0v3y(;)BT&M3f(p&yRKvaF#E9oNm8DOY zr)9+ZY>*Jv2zPD*?}HyX-GL_utIOL|T#h%CLE(MgNB^Z1hEE-9~Wlh;~l)O>p1i zUk)+TXy-^7=f-Zk6gY9=Pi9l?uk@e@2??E=R8ws7rhfW_1yc4D(w@RUS&g*+WP(V( zT23M@_veRR(D0cF*U(2_iCEf0jc_z_F{2sPbtBjcgxtiKG{LpJ$azN_l~jPoz;DFB zGzWI~WY6HqO2omZ6^zuxIsZK9yB+WX70rR>j7p~$nhOJXlY)n5JQbanksU~2^^oG) zza&EQPHzofSjQ^lDA-snEoF&im93+7ghJ(g{MAGGD1nY2>g>p9 zHHVsqqBy8W-wci^TKsAa+b3gaHttoLV`qY5*j*+P?LYb)AQi7hs1|C zm_878OD!#q!y3dLx{6_F7It>Gml&-&;B@RkVBl^L=tka=v%~B?s7FE$6*o;Kdz8UZ zF}1f>?6PvMo}d|6iAx-9x6!{=gaHTV*QvL(TX@NFZjPg`uUOx5zH!CtU_F4{Zbiws zU*@!8LNjVd{GNEi@5H`q-gOUt^6(T}S~aijV^r>o5;cLZ+3<^J_tCQ+cfQ8kY&~ zmSg*U153W7C$AMy98UFl7qRqP;2;eFJKQa2Z`(f(Vz}Mke$ra>c&fizbI}aPYR1i{ zHz@(ixO{D@>M;|UAfg5$H3$VktoPh*h>Ky$)@fs8^%3zH&DX$N?Mva7)V_`iQqT7< zl_aPr1!}D1l>f`y{Yh=$hc_=L3}DHc$XDjIFvexLkG z^MrF7QX9S#t4HNGu>hajfrF|t1&&5wkquMp201LE(#^aveOVxop9bvq4kCa zVOOc)!*&Jjj?6iN<&h-LTPXK}d4)-%k@bOC$hsTh#_}Ld z--zhs9O5t5`pu@8>%poei~BYQPw=@5vHCIyp&LUtj-5>WRU3sbw2`_ARW4&?uI3(Gu8*OUnk# zKX5@4AqsDm#LpOWaT-NYl&4BOihM+)_8peH6|Ks_o)qs4X0=fK5ky00*v{1_ z%ate5IRi)aeRhq6U5}3Mm^73Q{~CI)8VS62+pM0H-RPJbPScD)Pq@l(Gg z15x*q(o$?@)^_2uxTJ((=xiX!op2l14!DBw5(Z*E!v9q}CKyb3ePk?2L>bg z#ziqQbkCBiJ=9_^EA{^DI=H%D%=#fvDWS2A?|{2=qZ0pFTehA_!b$f-qhhOIYBa$@ z?KIbrXj*0(eU3@0h4$f&x?gk0umP9gNR@ zS(}4Lh4JrBWGa-drA5j{55$l{OWNarIjIDL#3yh1LfR}gUgL}F0kanK%7XW~GiUR= zOasx^q>uUn?voKd%5`2@*xBhzxOTo5G?#K++1qu8qyQFW8X6m4 z0hN5LvbSR8aX~;p2MlS3;vWST;FBp_W}NdkH!5;7!;X20>-lG?_RygnVbY?obl1#Bp;5_PYh0-1iO)wDFyb(0KLgQX=Qj?X(bb z_4H`N8j_tqr)jUfk%+*tT1FrZJSV@ow}BtdgZGF#8Gg;<;(W-9y!-lci{GwyRvMo8 zXMcs&;9(3CQvnhxs#mTBsV@!#AD>ok+juZ4ho677NYO;zb^^MC)OqEvd_JU$;7&;ZDRwf2uC;NMNlAJ-0&>aM zKw=F5y?-gIGQ}V03}y|x9Cvi-_zt708jXaE&Sr|!)ZB~~ue0B6HC^fb&8Uk?sP&Qq z?2II=f7Y#rlqxKTTU1^wVrXb6SMapDi)my?d^kqq?50@?mgt{bKTQM$ynd0xFa})9 z7lw;^F(sRIJ>AYvJ3Jqog^*k%kmj#;h<3XMDJEGw$<)HuMQaQu`}Iy%gHk{!bk5wa z(GF=WUp5h!^#p7gSLwEMCXxPU2dJA|Pk_~%q^vPtI?#ogEY(y)ZneuW;qly5pcwZ71u&Q$WDr!8vA|e?&w4eT1?TgWESuBgK(Pyl^f9XXe z|8$AtXs>5-5&?Gw_e_$nhoi)T#OwTcC&PRslU8Afftxf+MIGZ+K z*LlKoS@MSy(5p6$FfFX8Pauhs@&m?+8OrEh7LG2eh_CW0uNI$U80TxFQCpNyvfJYw5|5*Vhj))9hamm(E_1AUXJD@u z3~wjflm8;MsD>x2X-ArRA>ss!8FTzr7c<8{XWes7FiwLfNbf0Yyn9OnMH&8c%KL=DC;_XHq&&Y; zk&JuD!VPBv-xXD#KOn(kj6GU)3W~*F5bo`T0&_>?*3+g+wzzOlT+O zxW=OligELmLF6}Y@JlZcqj97sBxN+zancj9&P|?W2 z?nUexzM4AWHnOm?a-^E$_z?+RHKf#Hj0s%l#Ey|y_py25Xkxfoa{m}*6l%RnIJw-P z+*2KxWhorTMjc8(oOej?;V~s%A@L!( zUYoUqvH{3>7pf(L#>vhX(6iT;@F@F7ify8cF`+Ozf?T?5Oc z#aah)osckJ4r`A=##+J;3onYk72}9{%m#nl#$tW(frYcgtLm_=FuB71KIuY9^if$= zqM+;3T3B5_zN3%5X3WO6Cch=+mlwgx0#Ba2_$-AJ$*d#T>iU-C^;9|9$X6B7D!ZT^ z^)>pe=@=_qkI(jG2o|?GhVV8v3(k<<7pDW}5!L!=5D_hiLR6DCb0M9h7M#O_W_!TA ze6+H%`2)7%;&e_Rzv2h*zoi;}|M*7wy5}9Zt2HNFbH5mL&AZ+<;?Em@x{QL*3vtiBM2#byOkTUGeC`&`Fc^^sM&wtWzN7gLk~rmI474f45+9 zcak5Vu?r$P^DP>u>OilrT=y*Sz3O=}wr*4=kkcyUejsO_<@lzzyBpidX)qqve*(2^ zqbMbX%*V$^q1MH=S(yQErRkw?Rnd!Ak8kgPG#G?mr>N<7Fr&1gn6#=7YkbzWCcz_Q zEcz`-NuRS?-hpe4er`$cE$S%<2f%==Uy%%PTAh2Ndi#@^aw&pgAiApYDQencv@5WT zuvxdq-ZgKafp^z-4Z-t5I9k>^qv%aX^WwA*UOZjgf}%-_dL?l? zC+x>I2W@D|x!N=2j?uVKAt50{ZrUh#Of4NBD2|fDG1+txg^}~S`Tpn@c7Y8*9_=1m zLa;v{@s%NHl&8qpZfhYbp7cz~LFkd5>S#CD66lyUpUeupFGT#+7$aJ<7;a!vy85{l zg3f>+d{CiH&2Ms1bFEnwDy8z3Ff$csKH?y!|1f?Gh^J+ENTwrNr4a~*^U5P)gTI}o z10@C!N^34SPkmr8vIg^12+42)G3Hog(KmSB!JSc1Q7u#VK4|m~3=NHLmRu0Me7f|u zj1HYHicW0Zifqo?%=c`u%Ckv5djlyi?h2N#Tl3xe0p8;L;La|el;5}lSzZDklm&P4 zaP(ubr{eD9`3L6lQ8?Xf3KgIbY+5yG3fFY~Ta5zgiEl>i3Uml>V*udq3@&iq&JUHT z$f-#;FG&astHz-vq=Clr>Vcs1?yIr;#cvv&V+RW-p@| zElu|a^hve`yXAOd(Lv`F(J2bP@r9?bFx1x1pGR$r6u9i5unqQ`!?m;ufyh{vvHxKy z3f#4m?*b05H6Fxp$+p+aw)cMx{Zb^s%^>=--o8J>UKUPBz|X7%FXNr7<8-lgXw}?X z|8cMLao0oAc{qXUH~8$=ZvqE|UW-*dDxfu=%5LXrfuHVAR+8|0INC@WloA}TZf+cF zyPNGhO4_huF;%K(-_-m4hs3})M-5+W$DuE>pq5s+_WnohGcAb6joTwV<}fPJbaAKp zBbwUpoP!%~4wXzDbo;zK82NPo%A@hxTzZ9U&G(~XbQA@-|d+EOyI_QYRVN9z7=idyi3(p1L>nXOuP(ou97uB@-+mdvSD2 zzJZCLmM5)?aKFAhu00(KVJJ<~dh)o>@JfW9~z?DKKS>V;2io)wN zAgjl}n6&o@++c4&AJ#K9Aw+BAgwG8*n{a0XxT5AVHS=& zbT3Z!ipt7H+@3_ndk49=ACO(@e;zEFy+xumjrkC*_7_7L<3tnL4+u!%>G`LW{plz* zONt+`H&f0whR9!2Q0SUl!P|#ilkOjg8&5V@#+vROHeg31??9O{uj#Gs_VAl(R=s`M?0&Jm zlJ1D)NeZZU+D;mrjNT`39gFmADl_E19(*NDG{pdfj9ILPI>FM4PNy{4lu$c*no@-o z&_~7M(;kAt9FDFB*Bdt>YgL%+CcR5Np7$&-iHqDmlfC@%_s)Pyg#mI>EZCJQt2b8t zrk8MD)tCcYNB<0iXbh8<&mpJN*7(wdjZQf5Tc%2AQvLN(pg!DPUAUw<_CTpKaXe}8 z;IJ6LH0C2rr;w$fdwV9N|L!V)ah-%3(Fk~1(9Iceqi(hJd$qK?TMKV_cxnRm6r8NJ z2iJ=sDP*-e^}@?^DkX_ly1L|P7DuVS!QmnN0-|mkBuykimxb%|n zhn_Lc#x6_Ve>`1e%!zFLR!Q%`I;RW1h1kKZD3DNJNoPp zn~+K_*Nbh#=iqk?d#r4CzhkLwxJ(#p;Y0dDL(2zsHvMb+3@vQVI#{2S^g6DmD~6fX zWmnhLR9;_KUS570JoP8)k1CS()DKhsz=Z2&UANgde@wKGb`KYxoYcJuB1B6tq*V8B z-X5<=I401Ake_$B+@t&bKmK&+I8!V4$9`f~>!DV02iz8FvaIXMpVA!tq_&K|qv6qhG${m^e0 z7{9E`OmELtg^3AWLDAFGyPr)gIm}&9x2^UiGB!{{@zz|by}4B!?25d`>Za6ATAvAE zDY;Ds`IQGpF$Lfzxq(6!f?Z`Fac9-5ZJ^D&ZaX;G>?|gmD@V_psIk}k5w69upzDhk)qj4(GelMC#^rFCA7MoE8;WNF8 zSbkd%o92+c=Vj1$thUDMGP3fmX+OmK+Y23Our!Qqr_#))c1q=d#{anXg}q;6R64KF zq?68y520)68dxCG6A`%v%S*FTwokUH3P58pk4;WBv-&a*A|Sx&uEeBtm7K;VBxJaT zsPedO(WsZ11^glr?DUUklQsbHwhj0ien#oHM)j8{k!FX`>fyv0LwvJ5r~HKPH()&> zV|LY4U%ntABm1l8;|@6>h{XSFZ)$p)<;qr^NDI)h_ceEP{2e-)!oUA{igQi;1P-wR zrl@Zfp-hU=A2(<3q*YpAx*CV5HO4{ni?LQI37aAja|yremL(fe)Ly7Ch_$9Lg~Ro} z`;nnoYLyyyLzTIu`%sRn>PJ0IKO`GM1wRgs+~5N0q@BAU|fAhnp1R()Fgb6A)*>HEm0P6+Ge}nxu zVJ{!JZXD&8s()n;zMrs~GB%T&>v}1Jm?p7fJSkRJ-A$ClY`Ia-?T=U#y%$}R_GGhG z#6ckn`U-G}6s)ZEM#KM-#tY{Ajj_wWQR`pQEIEP6+qt2Xc-+wtOjnW$Y%Uw>_CIz_ z1@a0M;B21Kh&}r2FakMCY@q)~J)4++2dcWcL`=^%<&pifQuvR6nh~hJHUAFO@$+US zzi^E&Z&z|dj0hRf-w=QLUrGsE;eiyS8gpE^$UbOEP2HAzD)r&S|kmIYENIubmo=izny91 zyhOdQ$CmO~{to2z5p1%8-Db)5KPw8x0@pTM+1`7%hybQV19DHH9#;r%-ue&0%u{)8 onCAcg@c+~BH!%G_Vw?HvP9qfA+H&jyDDXWOlY3V1RM+SK0IW+DN&o-= literal 0 HcmV?d00001 diff --git a/docs/spec/reactors/block_sync/bcv1/img/bc-reactor-new-fsm.png b/docs/spec/reactors/block_sync/bcv1/img/bc-reactor-new-fsm.png new file mode 100644 index 0000000000000000000000000000000000000000..87d6fad931c46840ac2f47243e10f9b7978046af GIT binary patch literal 42091 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 S9i>1)ezKCEC91^?gZ>}K2PIPg literal 0 HcmV?d00001 diff --git a/docs/spec/reactors/block_sync/bcv1/img/bc-reactor-new-goroutines.png b/docs/spec/reactors/block_sync/bcv1/img/bc-reactor-new-goroutines.png new file mode 100644 index 0000000000000000000000000000000000000000..ee853ea935cb2d7adf35d63fcf576b9df305e0f4 GIT binary patch literal 140946 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
vg`M)Wq8{7?F**9ln|l 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 E57oWiU;qFB literal 0 HcmV?d00001 diff --git a/docs/spec/reactors/block_sync/bcv1/impl-v1.md b/docs/spec/reactors/block_sync/bcv1/impl-v1.md new file mode 100644 index 000000000..0ffaaea69 --- /dev/null +++ b/docs/spec/reactors/block_sync/bcv1/impl-v1.md @@ -0,0 +1,237 @@ +# Blockchain Reactor v1 + +### Data Structures +The data structures used are illustrated below. + +![Data Structures](img/bc-reactor-new-datastructs.png) + +#### BlockchainReactor +- is a `p2p.BaseReactor`. +- has a `store.BlockStore` for persistence. +- executes blocks using an `sm.BlockExecutor`. +- starts the FSM and the `poolRoutine()`. +- relays the fast-sync responses and switch messages to the FSM. +- handles errors from the FSM and when necessarily reports them to the switch. +- implements the blockchain reactor interface used by the FSM to send requests, errors to the switch and state timer resets. +- registers all the concrete types and interfaces for serialisation. + +```go +type BlockchainReactor struct { + p2p.BaseReactor + + initialState sm.State // immutable + state sm.State + + blockExec *sm.BlockExecutor + store *store.BlockStore + + fastSync bool + + fsm *BcReactorFSM + blocksSynced int + + // Receive goroutine forwards messages to this channel to be processed in the context of the poolRoutine. + messagesForFSMCh chan bcReactorMessage + + // Switch goroutine may send RemovePeer to the blockchain reactor. This is an error message that is relayed + // to this channel to be processed in the context of the poolRoutine. + errorsForFSMCh chan bcReactorMessage + + // This channel is used by the FSM and indirectly the block pool to report errors to the blockchain reactor and + // the switch. + eventsFromFSMCh chan bcFsmMessage +} +``` + +#### BcReactorFSM +- implements a simple finite state machine. +- has a state and a state timer. +- has a `BlockPool` to keep track of block requests sent to peers and blocks received from peers. +- uses an interface to send status requests, block requests and reporting errors. The interface is implemented by the `BlockchainReactor` and tests. + +```go +type BcReactorFSM struct { + logger log.Logger + mtx sync.Mutex + + startTime time.Time + + state *bcReactorFSMState + stateTimer *time.Timer + pool *BlockPool + + // interface used to call the Blockchain reactor to send StatusRequest, BlockRequest, reporting errors, etc. + toBcR bcReactor +} +``` + +#### BlockPool +- maintains a peer set, implemented as a map of peer ID to `BpPeer`. +- maintains a set of requests made to peers, implemented as a map of block request heights to peer IDs. +- maintains a list of future block requests needed to advance the fast-sync. This is a list of block heights. +- keeps track of the maximum height of the peers in the set. +- uses an interface to send requests and report errors to the reactor (via FSM). + +```go +type BlockPool struct { + logger log.Logger + // Set of peers that have sent status responses, with height bigger than pool.Height + peers map[p2p.ID]*BpPeer + // Set of block heights and the corresponding peers from where a block response is expected or has been received. + blocks map[int64]p2p.ID + + plannedRequests map[int64]struct{} // list of blocks to be assigned peers for blockRequest + nextRequestHeight int64 // next height to be added to plannedRequests + + Height int64 // height of next block to execute + MaxPeerHeight int64 // maximum height of all peers + toBcR bcReactor +} +``` +Some reasons for the `BlockPool` data structure content: +1. If a peer is removed by the switch fast access is required to the peer and the block requests made to that peer in order to redo them. +2. When block verification fails fast access is required from the block height to the peer and the block requests made to that peer in order to redo them. +3. The `BlockchainReactor` main routine decides when the block pool is running low and asks the `BlockPool` (via FSM) to make more requests. The `BlockPool` creates a list of requests and triggers the sending of the block requests (via the interface). The reason it maintains a list of requests is the redo operations that may occur during error handling. These are redone when the `BlockchainReactor` requires more blocks. + +#### BpPeer +- keeps track of a single peer, with height bigger than the initial height. +- maintains the block requests made to the peer and the blocks received from the peer until they are executed. +- monitors the peer speed when there are pending requests. +- it has an active timer when pending requests are present and reports error on timeout. + +```go +type BpPeer struct { + logger log.Logger + ID p2p.ID + + Height int64 // the peer reported height + NumPendingBlockRequests int // number of requests still waiting for block responses + blocks map[int64]*types.Block // blocks received or expected to be received from this peer + blockResponseTimer *time.Timer + recvMonitor *flow.Monitor + params *BpPeerParams // parameters for timer and monitor + + onErr func(err error, peerID p2p.ID) // function to call on error +} +``` + +### Concurrency Model + +The diagram below shows the goroutines (depicted by the gray blocks), timers (shown on the left with their values) and channels (colored rectangles). The FSM box shows some of the functionality and it is not a separate goroutine. + +The interface used by the FSM is shown in light red with the `IF` block. This is used to: +- send block requests +- report peer errors to the switch - this results in the reactor calling `switch.StopPeerForError()` and, if triggered by the peer timeout routine, a `removePeerEv` is sent to the FSM and action is taken from the context of the `poolRoutine()` +- ask the reactor to reset the state timers. The timers are owned by the FSM while the timeout routine is defined by the reactor. This was done in order to avoid running timers in tests and will change in the next revision. + +There are two main goroutines implemented by the blockchain reactor. All I/O operations are performed from the `poolRoutine()` context while the CPU intensive operations related to the block execution are performed from the context of the `executeBlocksRoutine()`. All goroutines are detailed in the next sections. + +![Go Routines Diagram](img/bc-reactor-new-goroutines.png) + +#### Receive() +Fast-sync messages from peers are received by this goroutine. It performs basic validation and: +- in helper mode (i.e. for request message) it replies immediately. This is different than the proposal in adr-040 that specifies having the FSM handling these. +- forwards response messages to the `poolRoutine()`. + +#### poolRoutine() +(named kept as in the previous reactor). +It starts the `executeBlocksRoutine()` and the FSM. It then waits in a loop for events. These are received from the following channels: +- `sendBlockRequestTicker.C` - every 10msec the reactor asks FSM to make more block requests up to a maximum. Note: currently this value is constant but could be changed based on low/ high watermark thresholds for the number of blocks received and waiting to be processed, the number of blockResponse messages waiting in messagesForFSMCh, etc. +- `statusUpdateTicker.C` - every 10 seconds the reactor broadcasts status requests to peers. While adr-040 specifies this to run within the FSM, at this point this functionality is kept in the reactor. +- `messagesForFSMCh` - the `Receive()` goroutine sends status and block response messages to this channel and the reactor calls FSM to handle them. +- `errorsForFSMCh` - this channel receives the following events: + - peer remove - when the switch removes a peer + - sate timeout event - when FSM state timers trigger + The reactor forwards this messages to the FSM. +- `eventsFromFSMCh` - there are two type of events sent over this channel: + - `syncFinishedEv` - triggered when FSM enters `finished` state and calls the switchToConsensus() interface function. + - `peerErrorEv`- peer timer expiry goroutine sends this event over the channel for processing from poolRoutine() context. + +#### executeBlocksRoutine() +Started by the `poolRoutine()`, it retrieves blocks from the pool and executes them: +- `processReceivedBlockTicker.C` - a ticker event is received over the channel every 10msec and its handling results in a signal being sent to the doProcessBlockCh channel. +- doProcessBlockCh - events are received on this channel as described as above and upon processing blocks are retrieved from the pool and executed. + + +### FSM + +![fsm](img/bc-reactor-new-fsm.png) + +#### States +##### init (aka unknown) +The FSM is created in `unknown` state. When started, by the reactor (`startFSMEv`), it broadcasts Status requests and transitions to `waitForPeer` state. + +##### waitForPeer +In this state, the FSM waits for a Status responses from a "tall" peer. A timer is running in this state to allow the FSM to finish if there are no useful peers. + +If the timer expires, it moves to `finished` state and calls the reactor to switch to consensus. +If a Status response is received from a peer within the timeout, the FSM transitions to `waitForBlock` state. + +##### waitForBlock +In this state the FSM makes Block requests (triggered by a ticker in reactor) and waits for Block responses. There is a timer running in this state to detect if a peer is not sending the block at current processing height. If the timer expires, the FSM removes the peer where the request was sent and all requests made to that peer are redone. + +As blocks are received they are stored by the pool. Block execution is independently performed by the reactor and the result reported to the FSM: +- if there are no errors, the FSM increases the pool height and resets the state timer. +- if there are errors, the peers that delivered the two blocks (at height and height+1) are removed and the requests redone. + +In this state the FSM may receive peer remove events in any of the following scenarios: +- the switch is removing a peer +- a peer is penalized because it has not responded to some block requests for a long time +- a peer is penalized for being slow + +When processing of the last block (the one with height equal to the highest peer height minus one) is successful, the FSM transitions to `finished` state. +If after a peer update or removal the pool height is same as maxPeerHeight, the FSM transitions to `finished` state. + +##### finished +When entering this state, the FSM calls the reactor to switch to consensus and performs cleanup. + +#### Events + +The following events are handled by the FSM: + +```go +const ( + startFSMEv = iota + 1 + statusResponseEv + blockResponseEv + processedBlockEv + makeRequestsEv + stopFSMEv + peerRemoveEv = iota + 256 + stateTimeoutEv +) +``` + +### Examples of Scenarios and Termination Handling +A few scenarios are covered in this section together with the current/ proposed handling. +In general, the scenarios involving faulty peers are made worse by the fact that they may quickly be re-added. + +#### 1. No Tall Peers + +S: In this scenario a node is started and while there are status responses received, none of the peers are at a height higher than this node. + +H: The FSM times out in `waitForPeer` state, moves to `finished` state where it calls the reactor to switch to consensus. + +#### 2. Typical Fast Sync + +S: A node fast syncs blocks from honest peers and eventually downloads and executes the penultimate block. + +H: The FSM in `waitForBlock` state will receive the processedBlockEv from the reactor and detect that the termination height is achieved. + +#### 3. Peer Claims Big Height but no Blocks + +S: In this scenario a faulty peer claims a big height (for which there are no blocks). + +H: The requests for the non-existing block will timeout, the peer removed and the pool's `MaxPeerHeight` updated. FSM checks if the termination height is achieved when peers are removed. + +#### 4. Highest Peer Removed or Updated to Short + +S: The fast sync node is caught up with all peers except one tall peer. The tall peer is removed or it sends status response with low height. + +H: FSM checks termination condition on peer removal and updates. + +#### 5. Block At Current Height Delayed + +S: A peer can block the progress of fast sync by delaying indefinitely the block response for the current processing height (h1). + +H: Currently, given h1 < h2, there is no enforcement at peer level that the response for h1 should be received before h2. So a peer will timeout only after delivering all blocks except h1. However the `waitForBlock` state timer fires if the block for current processing height is not received within a timeout. The peer is removed and the requests to that peer (including the one for current height) redone. diff --git a/docs/spec/reactors/block_sync/img/bc-reactor-routines.png b/docs/spec/reactors/block_sync/img/bc-reactor-routines.png new file mode 100644 index 0000000000000000000000000000000000000000..3f574a79b1ad304e7c03cfdb717c4f9aa600359a GIT binary patch literal 271695 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 z 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 Date: Tue, 23 Jul 2019 15:35:36 +0200 Subject: [PATCH 13/45] Renamed wire.go to codec.go (#3827) * Renamed wire.go to codec.go - Wire was the previous name of amino - Codec describes the file better than `wire` & `amino` Signed-off-by: Marko Baricevic * ide error * rename amino.go to codec.go --- blockchain/v0/{wire.go => codec.go} | 0 blockchain/v1/{wire.go => codec.go} | 0 cmd/tendermint/commands/{wire.go => codec.go} | 0 consensus/{wire.go => codec.go} | 0 consensus/types/{wire.go => codec.go} | 0 crypto/merkle/{wire.go => codec.go} | 0 crypto/multisig/{wire.go => codec.go} | 0 evidence/{wire.go => codec.go} | 0 mempool/{wire.go => codec.go} | 0 node/{wire.go => codec.go} | 0 p2p/{wire.go => codec.go} | 0 p2p/conn/{wire.go => codec.go} | 0 p2p/pex/{wire.go => codec.go} | 0 privval/{wire.go => codec.go} | 0 rpc/client/{amino.go => codec.go} | 0 rpc/core/types/{wire.go => codec.go} | 0 state/{wire.go => codec.go} | 0 state/txindex/kv/{wire.go => codec.go} | 0 store/{wire.go => codec.go} | 0 tools/tm-monitor/{wire.go => codec.go} | 0 tools/tm-monitor/monitor/{wire.go => codec.go} | 0 types/{wire.go => codec.go} | 0 22 files changed, 0 insertions(+), 0 deletions(-) rename blockchain/v0/{wire.go => codec.go} (100%) rename blockchain/v1/{wire.go => codec.go} (100%) rename cmd/tendermint/commands/{wire.go => codec.go} (100%) rename consensus/{wire.go => codec.go} (100%) rename consensus/types/{wire.go => codec.go} (100%) rename crypto/merkle/{wire.go => codec.go} (100%) rename crypto/multisig/{wire.go => codec.go} (100%) rename evidence/{wire.go => codec.go} (100%) rename mempool/{wire.go => codec.go} (100%) rename node/{wire.go => codec.go} (100%) rename p2p/{wire.go => codec.go} (100%) rename p2p/conn/{wire.go => codec.go} (100%) rename p2p/pex/{wire.go => codec.go} (100%) rename privval/{wire.go => codec.go} (100%) rename rpc/client/{amino.go => codec.go} (100%) rename rpc/core/types/{wire.go => codec.go} (100%) rename state/{wire.go => codec.go} (100%) rename state/txindex/kv/{wire.go => codec.go} (100%) rename store/{wire.go => codec.go} (100%) rename tools/tm-monitor/{wire.go => codec.go} (100%) rename tools/tm-monitor/monitor/{wire.go => codec.go} (100%) rename types/{wire.go => codec.go} (100%) diff --git a/blockchain/v0/wire.go b/blockchain/v0/codec.go similarity index 100% rename from blockchain/v0/wire.go rename to blockchain/v0/codec.go diff --git a/blockchain/v1/wire.go b/blockchain/v1/codec.go similarity index 100% rename from blockchain/v1/wire.go rename to blockchain/v1/codec.go diff --git a/cmd/tendermint/commands/wire.go b/cmd/tendermint/commands/codec.go similarity index 100% rename from cmd/tendermint/commands/wire.go rename to cmd/tendermint/commands/codec.go diff --git a/consensus/wire.go b/consensus/codec.go similarity index 100% rename from consensus/wire.go rename to consensus/codec.go diff --git a/consensus/types/wire.go b/consensus/types/codec.go similarity index 100% rename from consensus/types/wire.go rename to consensus/types/codec.go diff --git a/crypto/merkle/wire.go b/crypto/merkle/codec.go similarity index 100% rename from crypto/merkle/wire.go rename to crypto/merkle/codec.go diff --git a/crypto/multisig/wire.go b/crypto/multisig/codec.go similarity index 100% rename from crypto/multisig/wire.go rename to crypto/multisig/codec.go diff --git a/evidence/wire.go b/evidence/codec.go similarity index 100% rename from evidence/wire.go rename to evidence/codec.go diff --git a/mempool/wire.go b/mempool/codec.go similarity index 100% rename from mempool/wire.go rename to mempool/codec.go diff --git a/node/wire.go b/node/codec.go similarity index 100% rename from node/wire.go rename to node/codec.go diff --git a/p2p/wire.go b/p2p/codec.go similarity index 100% rename from p2p/wire.go rename to p2p/codec.go diff --git a/p2p/conn/wire.go b/p2p/conn/codec.go similarity index 100% rename from p2p/conn/wire.go rename to p2p/conn/codec.go diff --git a/p2p/pex/wire.go b/p2p/pex/codec.go similarity index 100% rename from p2p/pex/wire.go rename to p2p/pex/codec.go diff --git a/privval/wire.go b/privval/codec.go similarity index 100% rename from privval/wire.go rename to privval/codec.go diff --git a/rpc/client/amino.go b/rpc/client/codec.go similarity index 100% rename from rpc/client/amino.go rename to rpc/client/codec.go diff --git a/rpc/core/types/wire.go b/rpc/core/types/codec.go similarity index 100% rename from rpc/core/types/wire.go rename to rpc/core/types/codec.go diff --git a/state/wire.go b/state/codec.go similarity index 100% rename from state/wire.go rename to state/codec.go diff --git a/state/txindex/kv/wire.go b/state/txindex/kv/codec.go similarity index 100% rename from state/txindex/kv/wire.go rename to state/txindex/kv/codec.go diff --git a/store/wire.go b/store/codec.go similarity index 100% rename from store/wire.go rename to store/codec.go diff --git a/tools/tm-monitor/wire.go b/tools/tm-monitor/codec.go similarity index 100% rename from tools/tm-monitor/wire.go rename to tools/tm-monitor/codec.go diff --git a/tools/tm-monitor/monitor/wire.go b/tools/tm-monitor/monitor/codec.go similarity index 100% rename from tools/tm-monitor/monitor/wire.go rename to tools/tm-monitor/monitor/codec.go diff --git a/types/wire.go b/types/codec.go similarity index 100% rename from types/wire.go rename to types/codec.go From 0335add4379b9131016b746f242328ca248d93ff Mon Sep 17 00:00:00 2001 From: Anton Kaliaev Date: Wed, 24 Jul 2019 23:05:00 +0400 Subject: [PATCH 14/45] docs: add guides to docs (#3830) --- docs/.vuepress/config.js | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index 9adfc5953..70b404c42 100644 --- a/docs/.vuepress/config.js +++ b/docs/.vuepress/config.js @@ -34,6 +34,14 @@ module.exports = { "/introduction/what-is-tendermint" ] }, + { + title: "Guides", + collapsable: false, + children: [ + "/guides/go-built-in", + "/guides/go" + ] + }, { title: "Apps", collapsable: false, From ff9e08a32f2bf35246a733611897e9e7f34a80b4 Mon Sep 17 00:00:00 2001 From: Marko Date: Thu, 25 Jul 2019 07:35:30 +0200 Subject: [PATCH 15/45] add staticcheck linting (#3828) cleanup to add linter grpc change: https://godoc.org/google.golang.org/grpc#WithContextDialer https://godoc.org/google.golang.org/grpc#WithDialer grpc/grpc-go#2627 prometheous change: due to UninstrumentedHandler, being deprecated in the future empty branch = empty if or else statement didn't delete them entirely but commented couldn't find a reason to have them could not replicate the issue #3406 but if want to keep it commented then we should comment out the if statement as well --- .golangci.yml | 1 - abci/client/grpc_client.go | 32 +++++++++++------------ abci/example/example_test.go | 4 +-- blockchain/v0/reactor.go | 20 ++++++-------- blockchain/v1/reactor.go | 18 +++++++------ consensus/mempool_test.go | 12 ++++++--- consensus/reactor_test.go | 2 +- consensus/state.go | 21 ++++++++------- consensus/state_test.go | 6 ----- go.sum | 1 + libs/common/async.go | 10 ++++--- libs/common/async_test.go | 5 ++-- libs/pubsub/pubsub_test.go | 4 +-- lite/proxy/query_test.go | 4 +-- mempool/clist_mempool.go | 10 +++---- p2p/conn/connection_test.go | 3 ++- p2p/conn/secret_connection_test.go | 12 ++++++--- p2p/switch_test.go | 4 +-- privval/signer_validator_endpoint_test.go | 3 ++- rpc/grpc/client_server.go | 6 ++--- rpc/lib/client/ws_client.go | 18 +++++++------ rpc/lib/client/ws_client_test.go | 3 ++- state/state_test.go | 4 +-- tools/tm-monitor/mock/eventmeter.go | 2 +- types/genesis_test.go | 2 +- types/validator_set.go | 14 +++++----- 26 files changed, 116 insertions(+), 105 deletions(-) diff --git a/.golangci.yml b/.golangci.yml index 6adbbd9da..b07ec3a46 100644 --- a/.golangci.yml +++ b/.golangci.yml @@ -8,7 +8,6 @@ linters: - golint - maligned - errcheck - - staticcheck - interfacer - unconvert - goconst diff --git a/abci/client/grpc_client.go b/abci/client/grpc_client.go index 8c444abc5..e326055fb 100644 --- a/abci/client/grpc_client.go +++ b/abci/client/grpc_client.go @@ -6,8 +6,8 @@ import ( "sync" "time" - context "golang.org/x/net/context" - grpc "google.golang.org/grpc" + "golang.org/x/net/context" + "google.golang.org/grpc" "github.com/tendermint/tendermint/abci/types" cmn "github.com/tendermint/tendermint/libs/common" @@ -39,7 +39,7 @@ func NewGRPCClient(addr string, mustConnect bool) *grpcClient { return cli } -func dialerFunc(addr string, timeout time.Duration) (net.Conn, error) { +func dialerFunc(ctx context.Context, addr string) (net.Conn, error) { return cmn.Connect(addr) } @@ -49,7 +49,7 @@ func (cli *grpcClient) OnStart() error { } RETRY_LOOP: for { - conn, err := grpc.Dial(cli.addr, grpc.WithInsecure(), grpc.WithDialer(dialerFunc)) + conn, err := grpc.Dial(cli.addr, grpc.WithInsecure(), grpc.WithContextDialer(dialerFunc)) if err != nil { if cli.mustConnect { return err @@ -65,7 +65,7 @@ RETRY_LOOP: ENSURE_CONNECTED: for { - _, err := client.Echo(context.Background(), &types.RequestEcho{Message: "hello"}, grpc.FailFast(true)) + _, err := client.Echo(context.Background(), &types.RequestEcho{Message: "hello"}, grpc.WaitForReady(true)) if err == nil { break ENSURE_CONNECTED } @@ -125,7 +125,7 @@ func (cli *grpcClient) SetResponseCallback(resCb Callback) { func (cli *grpcClient) EchoAsync(msg string) *ReqRes { req := types.ToRequestEcho(msg) - res, err := cli.client.Echo(context.Background(), req.GetEcho(), grpc.FailFast(true)) + res, err := cli.client.Echo(context.Background(), req.GetEcho(), grpc.WaitForReady(true)) if err != nil { cli.StopForError(err) } @@ -134,7 +134,7 @@ func (cli *grpcClient) EchoAsync(msg string) *ReqRes { func (cli *grpcClient) FlushAsync() *ReqRes { req := types.ToRequestFlush() - res, err := cli.client.Flush(context.Background(), req.GetFlush(), grpc.FailFast(true)) + res, err := cli.client.Flush(context.Background(), req.GetFlush(), grpc.WaitForReady(true)) if err != nil { cli.StopForError(err) } @@ -143,7 +143,7 @@ func (cli *grpcClient) FlushAsync() *ReqRes { func (cli *grpcClient) InfoAsync(params types.RequestInfo) *ReqRes { req := types.ToRequestInfo(params) - res, err := cli.client.Info(context.Background(), req.GetInfo(), grpc.FailFast(true)) + res, err := cli.client.Info(context.Background(), req.GetInfo(), grpc.WaitForReady(true)) if err != nil { cli.StopForError(err) } @@ -152,7 +152,7 @@ func (cli *grpcClient) InfoAsync(params types.RequestInfo) *ReqRes { func (cli *grpcClient) SetOptionAsync(params types.RequestSetOption) *ReqRes { req := types.ToRequestSetOption(params) - res, err := cli.client.SetOption(context.Background(), req.GetSetOption(), grpc.FailFast(true)) + res, err := cli.client.SetOption(context.Background(), req.GetSetOption(), grpc.WaitForReady(true)) if err != nil { cli.StopForError(err) } @@ -161,7 +161,7 @@ func (cli *grpcClient) SetOptionAsync(params types.RequestSetOption) *ReqRes { func (cli *grpcClient) DeliverTxAsync(params types.RequestDeliverTx) *ReqRes { req := types.ToRequestDeliverTx(params) - res, err := cli.client.DeliverTx(context.Background(), req.GetDeliverTx(), grpc.FailFast(true)) + res, err := cli.client.DeliverTx(context.Background(), req.GetDeliverTx(), grpc.WaitForReady(true)) if err != nil { cli.StopForError(err) } @@ -170,7 +170,7 @@ func (cli *grpcClient) DeliverTxAsync(params types.RequestDeliverTx) *ReqRes { func (cli *grpcClient) CheckTxAsync(params types.RequestCheckTx) *ReqRes { req := types.ToRequestCheckTx(params) - res, err := cli.client.CheckTx(context.Background(), req.GetCheckTx(), grpc.FailFast(true)) + res, err := cli.client.CheckTx(context.Background(), req.GetCheckTx(), grpc.WaitForReady(true)) if err != nil { cli.StopForError(err) } @@ -179,7 +179,7 @@ func (cli *grpcClient) CheckTxAsync(params types.RequestCheckTx) *ReqRes { func (cli *grpcClient) QueryAsync(params types.RequestQuery) *ReqRes { req := types.ToRequestQuery(params) - res, err := cli.client.Query(context.Background(), req.GetQuery(), grpc.FailFast(true)) + res, err := cli.client.Query(context.Background(), req.GetQuery(), grpc.WaitForReady(true)) if err != nil { cli.StopForError(err) } @@ -188,7 +188,7 @@ func (cli *grpcClient) QueryAsync(params types.RequestQuery) *ReqRes { func (cli *grpcClient) CommitAsync() *ReqRes { req := types.ToRequestCommit() - res, err := cli.client.Commit(context.Background(), req.GetCommit(), grpc.FailFast(true)) + res, err := cli.client.Commit(context.Background(), req.GetCommit(), grpc.WaitForReady(true)) if err != nil { cli.StopForError(err) } @@ -197,7 +197,7 @@ func (cli *grpcClient) CommitAsync() *ReqRes { func (cli *grpcClient) InitChainAsync(params types.RequestInitChain) *ReqRes { req := types.ToRequestInitChain(params) - res, err := cli.client.InitChain(context.Background(), req.GetInitChain(), grpc.FailFast(true)) + res, err := cli.client.InitChain(context.Background(), req.GetInitChain(), grpc.WaitForReady(true)) if err != nil { cli.StopForError(err) } @@ -206,7 +206,7 @@ func (cli *grpcClient) InitChainAsync(params types.RequestInitChain) *ReqRes { func (cli *grpcClient) BeginBlockAsync(params types.RequestBeginBlock) *ReqRes { req := types.ToRequestBeginBlock(params) - res, err := cli.client.BeginBlock(context.Background(), req.GetBeginBlock(), grpc.FailFast(true)) + res, err := cli.client.BeginBlock(context.Background(), req.GetBeginBlock(), grpc.WaitForReady(true)) if err != nil { cli.StopForError(err) } @@ -215,7 +215,7 @@ func (cli *grpcClient) BeginBlockAsync(params types.RequestBeginBlock) *ReqRes { func (cli *grpcClient) EndBlockAsync(params types.RequestEndBlock) *ReqRes { req := types.ToRequestEndBlock(params) - res, err := cli.client.EndBlock(context.Background(), req.GetEndBlock(), grpc.FailFast(true)) + res, err := cli.client.EndBlock(context.Background(), req.GetEndBlock(), grpc.WaitForReady(true)) if err != nil { cli.StopForError(err) } diff --git a/abci/example/example_test.go b/abci/example/example_test.go index 6282f3a44..74510700b 100644 --- a/abci/example/example_test.go +++ b/abci/example/example_test.go @@ -107,7 +107,7 @@ func testStream(t *testing.T, app types.Application) { //------------------------- // test grpc -func dialerFunc(addr string, timeout time.Duration) (net.Conn, error) { +func dialerFunc(ctx context.Context, addr string) (net.Conn, error) { return cmn.Connect(addr) } @@ -123,7 +123,7 @@ func testGRPCSync(t *testing.T, app *types.GRPCApplication) { defer server.Stop() // Connect to the socket - conn, err := grpc.Dial("unix://test.sock", grpc.WithInsecure(), grpc.WithDialer(dialerFunc)) + conn, err := grpc.Dial("unix://test.sock", grpc.WithInsecure(), grpc.WithContextDialer(dialerFunc)) if err != nil { t.Fatalf("Error dialing GRPC server: %v", err.Error()) } diff --git a/blockchain/v0/reactor.go b/blockchain/v0/reactor.go index 5d38471dc..574ef3f29 100644 --- a/blockchain/v0/reactor.go +++ b/blockchain/v0/reactor.go @@ -141,9 +141,9 @@ func (bcR *BlockchainReactor) GetChannels() []*p2p.ChannelDescriptor { // AddPeer implements Reactor by sending our state to peer. func (bcR *BlockchainReactor) AddPeer(peer p2p.Peer) { msgBytes := cdc.MustMarshalBinaryBare(&bcStatusResponseMessage{bcR.store.Height()}) - if !peer.Send(BlockchainChannel, msgBytes) { - // doing nothing, will try later in `poolRoutine` - } + peer.Send(BlockchainChannel, msgBytes) + // it's OK if send fails. will try later in poolRoutine + // peer is added to the pool once we receive the first // bcStatusResponseMessage from the peer and call pool.SetPeerHeight } @@ -191,18 +191,13 @@ func (bcR *BlockchainReactor) Receive(chID byte, src p2p.Peer, msgBytes []byte) switch msg := msg.(type) { case *bcBlockRequestMessage: - if queued := bcR.respondToPeer(msg, src); !queued { - // Unfortunately not queued since the queue is full. - } + bcR.respondToPeer(msg, src) case *bcBlockResponseMessage: bcR.pool.AddBlock(src.ID(), msg.Block, len(msgBytes)) case *bcStatusRequestMessage: // Send peer our state. msgBytes := cdc.MustMarshalBinaryBare(&bcStatusResponseMessage{bcR.store.Height()}) - queued := src.TrySend(BlockchainChannel, msgBytes) - if !queued { - // sorry - } + src.TrySend(BlockchainChannel, msgBytes) case *bcStatusResponseMessage: // Got a peer status. Unverified. bcR.pool.SetPeerHeight(src.ID(), msg.Height) @@ -274,9 +269,10 @@ FOR_LOOP: conR, ok := bcR.Switch.Reactor("CONSENSUS").(consensusReactor) if ok { conR.SwitchToConsensus(state, blocksSynced) - } else { - // should only happen during testing } + // else { + // should only happen during testing + // } break FOR_LOOP } diff --git a/blockchain/v1/reactor.go b/blockchain/v1/reactor.go index 2f95cebaf..480b87f34 100644 --- a/blockchain/v1/reactor.go +++ b/blockchain/v1/reactor.go @@ -169,9 +169,9 @@ func (bcR *BlockchainReactor) GetChannels() []*p2p.ChannelDescriptor { // AddPeer implements Reactor by sending our state to peer. func (bcR *BlockchainReactor) AddPeer(peer p2p.Peer) { msgBytes := cdc.MustMarshalBinaryBare(&bcStatusResponseMessage{bcR.store.Height()}) - if !peer.Send(BlockchainChannel, msgBytes) { - // doing nothing, will try later in `poolRoutine` - } + peer.Send(BlockchainChannel, msgBytes) + // it's OK if send fails. will try later in poolRoutine + // peer is added to the pool once we receive the first // bcStatusResponseMessage from the peer and call pool.updatePeer() } @@ -381,10 +381,11 @@ ForLoop: err: msg.data.err, }, }) - } else { - // For slow peers, or errors due to blocks received from wrong peer - // the FSM had already removed the peers } + // else { + // For slow peers, or errors due to blocks received from wrong peer + // the FSM had already removed the peers + // } default: bcR.Logger.Error("Event from FSM not supported", "type", msg.event) } @@ -465,9 +466,10 @@ func (bcR *BlockchainReactor) switchToConsensus() { if ok { conR.SwitchToConsensus(bcR.state, bcR.blocksSynced) bcR.eventsFromFSMCh <- bcFsmMessage{event: syncFinishedEv} - } else { - // Should only happen during testing. } + // else { + // Should only happen during testing. + // } } // Implements bcRNotifier diff --git a/consensus/mempool_test.go b/consensus/mempool_test.go index de0179869..94f7340c2 100644 --- a/consensus/mempool_test.go +++ b/consensus/mempool_test.go @@ -155,12 +155,14 @@ func TestMempoolRmBadTx(t *testing.T) { // and the tx should get removed from the pool err := assertMempool(cs.txNotifier).CheckTx(txBytes, func(r *abci.Response) { if r.GetCheckTx().Code != code.CodeTypeBadNonce { - t.Fatalf("expected checktx to return bad nonce, got %v", r) + t.Errorf("expected checktx to return bad nonce, got %v", r) + return } checkTxRespCh <- struct{}{} }) if err != nil { - t.Fatalf("Error after CheckTx: %v", err) + t.Errorf("Error after CheckTx: %v", err) + return } // check for the tx @@ -180,7 +182,8 @@ func TestMempoolRmBadTx(t *testing.T) { case <-checkTxRespCh: // success case <-ticker: - t.Fatalf("Timed out waiting for tx to return") + t.Errorf("Timed out waiting for tx to return") + return } // Wait until the tx is removed @@ -189,7 +192,8 @@ func TestMempoolRmBadTx(t *testing.T) { case <-emptyMempoolCh: // success case <-ticker: - t.Fatalf("Timed out waiting for tx to be removed") + t.Errorf("Timed out waiting for tx to be removed") + return } } diff --git a/consensus/reactor_test.go b/consensus/reactor_test.go index 612fde7f6..af6a62568 100644 --- a/consensus/reactor_test.go +++ b/consensus/reactor_test.go @@ -235,7 +235,7 @@ func TestReactorCreatesBlockWhenEmptyBlocksFalse(t *testing.T) { // send a tx if err := assertMempool(css[3].txNotifier).CheckTx([]byte{1, 2, 3}, nil); err != nil { - //t.Fatal(err) + t.Error(err) } // wait till everyone makes the first new block diff --git a/consensus/state.go b/consensus/state.go index 1f6bad9ab..0a48b0525 100644 --- a/consensus/state.go +++ b/consensus/state.go @@ -690,13 +690,13 @@ func (cs *ConsensusState) handleMsg(mi msgInfo) { cs.statsMsgQueue <- mi } - if err == ErrAddingVote { - // TODO: punish peer - // We probably don't want to stop the peer here. The vote does not - // necessarily comes from a malicious peer but can be just broadcasted by - // a typical peer. - // https://github.com/tendermint/tendermint/issues/1281 - } + // if err == ErrAddingVote { + // TODO: punish peer + // We probably don't want to stop the peer here. The vote does not + // necessarily comes from a malicious peer but can be just broadcasted by + // a typical peer. + // https://github.com/tendermint/tendermint/issues/1281 + // } // NOTE: the vote is broadcast to peers by the reactor listening // for vote events @@ -709,7 +709,7 @@ func (cs *ConsensusState) handleMsg(mi msgInfo) { return } - if err != nil { + if err != nil { // nolint:staticcheck // Causes TestReactorValidatorSetChanges to timeout // https://github.com/tendermint/tendermint/issues/3406 // cs.Logger.Error("Error with msg", "height", cs.Height, "round", cs.Round, @@ -1227,9 +1227,10 @@ func (cs *ConsensusState) enterCommit(height int64, commitRound int) { cs.ProposalBlockParts = types.NewPartSetFromHeader(blockID.PartsHeader) cs.eventBus.PublishEventValidBlock(cs.RoundStateEvent()) cs.evsw.FireEvent(types.EventValidBlock, &cs.RoundState) - } else { - // We just need to keep waiting. } + // else { + // We just need to keep waiting. + // } } } diff --git a/consensus/state_test.go b/consensus/state_test.go index 93ef0d4cb..1888e4057 100644 --- a/consensus/state_test.go +++ b/consensus/state_test.go @@ -621,8 +621,6 @@ func TestStateLockPOLUnlock(t *testing.T) { // the proposed block should now be locked and our precommit added validatePrecommit(t, cs1, round, round, vss[0], theBlockHash, theBlockHash) - rs = cs1.GetRoundState() - // add precommits from the rest signAddVotes(cs1, types.PrecommitType, nil, types.PartSetHeader{}, vs2, vs4) signAddVotes(cs1, types.PrecommitType, theBlockHash, theBlockParts, vs3) @@ -1317,8 +1315,6 @@ func TestStartNextHeightCorrectly(t *testing.T) { // the proposed block should now be locked and our precommit added validatePrecommit(t, cs1, round, round, vss[0], theBlockHash, theBlockHash) - rs = cs1.GetRoundState() - // add precommits signAddVotes(cs1, types.PrecommitType, nil, types.PartSetHeader{}, vs2) signAddVotes(cs1, types.PrecommitType, theBlockHash, theBlockParts, vs3) @@ -1370,8 +1366,6 @@ func TestResetTimeoutPrecommitUponNewHeight(t *testing.T) { ensurePrecommit(voteCh, height, round) validatePrecommit(t, cs1, round, round, vss[0], theBlockHash, theBlockHash) - rs = cs1.GetRoundState() - // add precommits signAddVotes(cs1, types.PrecommitType, nil, types.PartSetHeader{}, vs2) signAddVotes(cs1, types.PrecommitType, theBlockHash, theBlockParts, vs3) diff --git a/go.sum b/go.sum index 23f548f0c..9766e4f70 100644 --- a/go.sum +++ b/go.sum @@ -84,6 +84,7 @@ github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZb github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4= github.com/prometheus/client_golang v0.9.1 h1:K47Rk0v/fkEfwfQet2KWhscE0cJzjgCCDBG2KHZoVno= github.com/prometheus/client_golang v0.9.1/go.mod h1:7SWBe2y4D6OKWSNQJUaRYU/AaXPKyh/dDVn+NZz0KFw= +github.com/prometheus/client_golang v1.0.0 h1:vrDKnkGzuGvhNAL56c7DBz29ZL+KxnoR0x7enabFceM= github.com/prometheus/client_model v0.0.0-20180712105110-5c3871d89910 h1:idejC8f05m9MGOsuEi1ATq9shN03HrxNkD/luQvxCv8= github.com/prometheus/client_model v0.0.0-20180712105110-5c3871d89910/go.mod h1:MbSGuTsp3dbXC40dX6PRTWyKYBIrTGTE9sqQNg2J8bo= github.com/prometheus/common v0.0.0-20181020173914-7e9e6cabbd39 h1:Cto4X6SVMWRPBkJ/3YHn1iDGDGc/Z+sW+AEMKHMVvN4= diff --git a/libs/common/async.go b/libs/common/async.go index e3293ab4c..326b97248 100644 --- a/libs/common/async.go +++ b/libs/common/async.go @@ -61,9 +61,10 @@ func (trs *TaskResultSet) Reap() *TaskResultSet { TaskResult: result, OK: true, } - } else { - // We already wrote it. } + // else { + // We already wrote it. + // } default: // Do nothing. } @@ -83,9 +84,10 @@ func (trs *TaskResultSet) Wait() *TaskResultSet { TaskResult: result, OK: true, } - } else { - // We already wrote it. } + // else { + // We already wrote it. + // } } return trs } diff --git a/libs/common/async_test.go b/libs/common/async_test.go index f565b4bd3..c19ffc86f 100644 --- a/libs/common/async_test.go +++ b/libs/common/async_test.go @@ -40,9 +40,10 @@ func TestParallel(t *testing.T) { } else if !assert.Equal(t, -1*i, taskResult.Value.(int)) { assert.Fail(t, "Task should have returned %v but got %v", -1*i, taskResult.Value.(int)) failedTasks++ - } else { - // Good! } + // else { + // Good! + // } } assert.Equal(t, failedTasks, 0, "No task should have failed") assert.Nil(t, trs.FirstError(), "There should be no errors") diff --git a/libs/pubsub/pubsub_test.go b/libs/pubsub/pubsub_test.go index d5f61dc07..5a2baa14f 100644 --- a/libs/pubsub/pubsub_test.go +++ b/libs/pubsub/pubsub_test.go @@ -273,11 +273,11 @@ func TestResubscribe(t *testing.T) { defer s.Stop() ctx := context.Background() - subscription, err := s.Subscribe(ctx, clientID, query.Empty{}) + _, err := s.Subscribe(ctx, clientID, query.Empty{}) require.NoError(t, err) err = s.Unsubscribe(ctx, clientID, query.Empty{}) require.NoError(t, err) - subscription, err = s.Subscribe(ctx, clientID, query.Empty{}) + subscription, err := s.Subscribe(ctx, clientID, query.Empty{}) require.NoError(t, err) err = s.Publish(ctx, "Cable") diff --git a/lite/proxy/query_test.go b/lite/proxy/query_test.go index db2b6e46c..d92a486ea 100644 --- a/lite/proxy/query_test.go +++ b/lite/proxy/query_test.go @@ -143,13 +143,13 @@ func TestTxProofs(t *testing.T) { // First let's make sure a bogus transaction hash returns a valid non-existence proof. key := types.Tx([]byte("bogus")).Hash() - res, err := cl.Tx(key, true) + _, err = cl.Tx(key, true) require.NotNil(err) require.Contains(err.Error(), "not found") // Now let's check with the real tx root hash. key = types.Tx(tx).Hash() - res, err = cl.Tx(key, true) + res, err := cl.Tx(key, true) require.NoError(err, "%#v", err) require.NotNil(res) keyHash := merkle.SimpleHashFromByteSlices([][]byte{key}) diff --git a/mempool/clist_mempool.go b/mempool/clist_mempool.go index 81123cb63..fc4591d29 100644 --- a/mempool/clist_mempool.go +++ b/mempool/clist_mempool.go @@ -250,11 +250,11 @@ func (mem *CListMempool) CheckTxWithInfo(tx types.Tx, cb func(*abci.Response), t // so we only record the sender for txs still in the mempool. if e, ok := mem.txsMap.Load(txKey(tx)); ok { memTx := e.(*clist.CElement).Value.(*mempoolTx) - if _, loaded := memTx.senders.LoadOrStore(txInfo.SenderID, true); loaded { - // TODO: consider punishing peer for dups, - // its non-trivial since invalid txs can become valid, - // but they can spam the same tx with little cost to them atm. - } + memTx.senders.LoadOrStore(txInfo.SenderID, true) + // TODO: consider punishing peer for dups, + // its non-trivial since invalid txs can become valid, + // but they can spam the same tx with little cost to them atm. + } return ErrTxInCache diff --git a/p2p/conn/connection_test.go b/p2p/conn/connection_test.go index 283b00ebe..91e3e2099 100644 --- a/p2p/conn/connection_test.go +++ b/p2p/conn/connection_test.go @@ -57,7 +57,8 @@ func TestMConnectionSendFlushStop(t *testing.T) { msgB := make([]byte, aminoMsgLength) _, err := server.Read(msgB) if err != nil { - t.Fatal(err) + t.Error(err) + return } errCh <- err }() diff --git a/p2p/conn/secret_connection_test.go b/p2p/conn/secret_connection_test.go index 76982ed97..9ab9695a3 100644 --- a/p2p/conn/secret_connection_test.go +++ b/p2p/conn/secret_connection_test.go @@ -192,7 +192,8 @@ func writeLots(t *testing.T, wg *sync.WaitGroup, conn net.Conn, txt string, n in for i := 0; i < n; i++ { _, err := conn.Write([]byte(txt)) if err != nil { - t.Fatalf("Failed to write to fooSecConn: %v", err) + t.Errorf("Failed to write to fooSecConn: %v", err) + return } } } @@ -408,7 +409,8 @@ func BenchmarkWriteSecretConnection(b *testing.B) { if err == io.EOF { return } else if err != nil { - b.Fatalf("Failed to read from barSecConn: %v", err) + b.Errorf("Failed to read from barSecConn: %v", err) + return } } }() @@ -418,7 +420,8 @@ func BenchmarkWriteSecretConnection(b *testing.B) { idx := cmn.RandIntn(len(fooWriteBytes)) _, err := fooSecConn.Write(fooWriteBytes[idx]) if err != nil { - b.Fatalf("Failed to write to fooSecConn: %v", err) + b.Errorf("Failed to write to fooSecConn: %v", err) + return } } b.StopTimer() @@ -451,7 +454,8 @@ func BenchmarkReadSecretConnection(b *testing.B) { idx := cmn.RandIntn(len(fooWriteBytes)) _, err := fooSecConn.Write(fooWriteBytes[idx]) if err != nil { - b.Fatalf("Failed to write to fooSecConn: %v, %v,%v", err, i, b.N) + b.Errorf("Failed to write to fooSecConn: %v, %v,%v", err, i, b.N) + return } } }() diff --git a/p2p/switch_test.go b/p2p/switch_test.go index aa5ca78bf..0879acc2d 100644 --- a/p2p/switch_test.go +++ b/p2p/switch_test.go @@ -16,7 +16,7 @@ import ( "testing" "time" - stdprometheus "github.com/prometheus/client_golang/prometheus" + "github.com/prometheus/client_golang/prometheus/promhttp" "github.com/stretchr/testify/assert" "github.com/stretchr/testify/require" @@ -348,7 +348,7 @@ func TestSwitchStopsNonPersistentPeerOnError(t *testing.T) { } func TestSwitchStopPeerForError(t *testing.T) { - s := httptest.NewServer(stdprometheus.UninstrumentedHandler()) + s := httptest.NewServer(promhttp.Handler()) defer s.Close() scrapeMetrics := func() string { diff --git a/privval/signer_validator_endpoint_test.go b/privval/signer_validator_endpoint_test.go index bf4c29930..611e743c9 100644 --- a/privval/signer_validator_endpoint_test.go +++ b/privval/signer_validator_endpoint_test.go @@ -331,9 +331,10 @@ func TestErrUnexpectedResponse(t *testing.T) { // we do not want to Start() the remote signer here and instead use the connection to // reply with intentionally wrong replies below: rsConn, err := serviceEndpoint.connect() - defer rsConn.Close() require.NoError(t, err) require.NotNil(t, rsConn) + defer rsConn.Close() + // send over public key to get the remote signer running: go testReadWriteResponse(t, &PubKeyResponse{}, rsConn) <-readyCh diff --git a/rpc/grpc/client_server.go b/rpc/grpc/client_server.go index 922016dd5..d02120e10 100644 --- a/rpc/grpc/client_server.go +++ b/rpc/grpc/client_server.go @@ -2,8 +2,8 @@ package core_grpc import ( "net" - "time" + "golang.org/x/net/context" "google.golang.org/grpc" cmn "github.com/tendermint/tendermint/libs/common" @@ -26,13 +26,13 @@ func StartGRPCServer(ln net.Listener) error { // StartGRPCClient dials the gRPC server using protoAddr and returns a new // BroadcastAPIClient. func StartGRPCClient(protoAddr string) BroadcastAPIClient { - conn, err := grpc.Dial(protoAddr, grpc.WithInsecure(), grpc.WithDialer(dialerFunc)) + conn, err := grpc.Dial(protoAddr, grpc.WithInsecure(), grpc.WithContextDialer(dialerFunc)) if err != nil { panic(err) } return NewBroadcastAPIClient(conn) } -func dialerFunc(addr string, timeout time.Duration) (net.Conn, error) { +func dialerFunc(ctx context.Context, addr string) (net.Conn, error) { return cmn.Connect(addr) } diff --git a/rpc/lib/client/ws_client.go b/rpc/lib/client/ws_client.go index e3b559569..05180c753 100644 --- a/rpc/lib/client/ws_client.go +++ b/rpc/lib/client/ws_client.go @@ -369,10 +369,11 @@ func (c *WSClient) writeRoutine() { defer func() { ticker.Stop() - if err := c.conn.Close(); err != nil { - // ignore error; it will trigger in tests - // likely because it's closing an already closed connection - } + c.conn.Close() + // err != nil { + // ignore error; it will trigger in tests + // likely because it's closing an already closed connection + // } c.wg.Done() }() @@ -421,10 +422,11 @@ func (c *WSClient) writeRoutine() { // executing all reads from this goroutine. func (c *WSClient) readRoutine() { defer func() { - if err := c.conn.Close(); err != nil { - // ignore error; it will trigger in tests - // likely because it's closing an already closed connection - } + c.conn.Close() + // err != nil { + // ignore error; it will trigger in tests + // likely because it's closing an already closed connection + // } c.wg.Done() }() diff --git a/rpc/lib/client/ws_client_test.go b/rpc/lib/client/ws_client_test.go index e902fe21a..4f2cc9ada 100644 --- a/rpc/lib/client/ws_client_test.go +++ b/rpc/lib/client/ws_client_test.go @@ -212,7 +212,8 @@ func callWgDoneOnResult(t *testing.T, c *WSClient, wg *sync.WaitGroup) { select { case resp := <-c.ResponsesCh: if resp.Error != nil { - t.Fatalf("unexpected error: %v", resp.Error) + t.Errorf("unexpected error: %v", resp.Error) + return } if resp.Result != nil { wg.Done() diff --git a/state/state_test.go b/state/state_test.go index 29f76e27c..0512fbf38 100644 --- a/state/state_test.go +++ b/state/state_test.go @@ -185,11 +185,11 @@ func TestValidatorSimpleSaveLoad(t *testing.T) { assert := assert.New(t) // Can't load anything for height 0. - v, err := sm.LoadValidators(stateDB, 0) + _, err := sm.LoadValidators(stateDB, 0) assert.IsType(sm.ErrNoValSetForHeight{}, err, "expected err at height 0") // Should be able to load for height 1. - v, err = sm.LoadValidators(stateDB, 1) + v, err := sm.LoadValidators(stateDB, 1) assert.Nil(err, "expected no err at height 1") assert.Equal(v.Hash(), state.Validators.Hash(), "expected validator hashes to match") diff --git a/tools/tm-monitor/mock/eventmeter.go b/tools/tm-monitor/mock/eventmeter.go index 7bbedc7fa..7119c4399 100644 --- a/tools/tm-monitor/mock/eventmeter.go +++ b/tools/tm-monitor/mock/eventmeter.go @@ -54,7 +54,7 @@ func (c *RpcClient) Call(method string, params map[string]interface{}, result in } rv, rt := reflect.ValueOf(result), reflect.TypeOf(result) - rv, rt = rv.Elem(), rt.Elem() + rv, _ = rv.Elem(), rt.Elem() rv.Set(reflect.ValueOf(s)) return s, nil diff --git a/types/genesis_test.go b/types/genesis_test.go index f977513e7..33bdd34c1 100644 --- a/types/genesis_test.go +++ b/types/genesis_test.go @@ -68,7 +68,7 @@ func TestGenesisGood(t *testing.T) { genDoc.ConsensusParams.Block.MaxBytes = 0 genDocBytes, err = cdc.MarshalJSON(genDoc) assert.NoError(t, err, "error marshalling genDoc") - genDoc, err = GenesisDocFromJSON(genDocBytes) + _, err = GenesisDocFromJSON(genDocBytes) assert.Error(t, err, "expected error for genDoc json with block size of 0") // Genesis doc from raw json diff --git a/types/validator_set.go b/types/validator_set.go index 65358714d..2078e7a95 100644 --- a/types/validator_set.go +++ b/types/validator_set.go @@ -619,10 +619,11 @@ func (vals *ValidatorSet) VerifyCommit(chainID string, blockID BlockID, height i // Good precommit! if blockID.Equals(precommit.BlockID) { talliedVotingPower += val.VotingPower - } else { - // It's OK that the BlockID doesn't match. We include stray - // precommits to measure validator availability. } + // else { + // It's OK that the BlockID doesn't match. We include stray + // precommits to measure validator availability. + // } } if talliedVotingPower > vals.TotalVotingPower()*2/3 { @@ -703,10 +704,11 @@ func (vals *ValidatorSet) VerifyFutureCommit(newSet *ValidatorSet, chainID strin // Good precommit! if blockID.Equals(precommit.BlockID) { oldVotingPower += val.VotingPower - } else { - // It's OK that the BlockID doesn't match. We include stray - // precommits to measure validator availability. } + // else { + // It's OK that the BlockID doesn't match. We include stray + // precommits to measure validator availability. + // } } if oldVotingPower <= oldVals.TotalVotingPower()*2/3 { From 58c3e590b48924d6361770267b16b62938a7d8e3 Mon Sep 17 00:00:00 2001 From: Marko Date: Thu, 25 Jul 2019 10:13:19 +0200 Subject: [PATCH 16/45] types: move MakeVote / MakeBlock functions (#3819) to the types package Paritally Fixes #3584 --- blockchain/v0/reactor_test.go | 26 ++++++----------------- consensus/replay_test.go | 24 +++------------------ state/helpers_test.go | 20 +----------------- state/validation_test.go | 4 ++-- types/block.go | 19 ----------------- types/test_util.go | 40 +++++++++++++++++++++++++++++++++-- 6 files changed, 50 insertions(+), 83 deletions(-) diff --git a/blockchain/v0/reactor_test.go b/blockchain/v0/reactor_test.go index 29de5b193..08ec66cda 100644 --- a/blockchain/v0/reactor_test.go +++ b/blockchain/v0/reactor_test.go @@ -45,24 +45,6 @@ func randGenesisDoc(numValidators int, randPower bool, minPower int64) (*types.G }, privValidators } -func makeVote(header *types.Header, blockID types.BlockID, valset *types.ValidatorSet, privVal types.PrivValidator) *types.Vote { - addr := privVal.GetPubKey().Address() - idx, _ := valset.GetByAddress(addr) - vote := &types.Vote{ - ValidatorAddress: addr, - ValidatorIndex: idx, - Height: header.Height, - Round: 1, - Timestamp: tmtime.Now(), - Type: types.PrecommitType, - BlockID: blockID, - } - - privVal.SignVote(header.ChainID, vote) - - return vote -} - type BlockchainReactorPair struct { reactor *BlockchainReactor app proxy.AppConns @@ -106,8 +88,12 @@ func newBlockchainReactor(logger log.Logger, genDoc *types.GenesisDoc, privVals lastBlockMeta := blockStore.LoadBlockMeta(blockHeight - 1) lastBlock := blockStore.LoadBlock(blockHeight - 1) - vote := makeVote(&lastBlock.Header, lastBlockMeta.BlockID, state.Validators, privVals[0]).CommitSig() - lastCommit = types.NewCommit(lastBlockMeta.BlockID, []*types.CommitSig{vote}) + vote, err := types.MakeVote(lastBlock.Header.Height, lastBlockMeta.BlockID, state.Validators, privVals[0], lastBlock.Header.ChainID) + if err != nil { + panic(err) + } + voteCommitSig := vote.CommitSig() + lastCommit = types.NewCommit(lastBlockMeta.BlockID, []*types.CommitSig{voteCommitSig}) } thisBlock := makeBlock(blockHeight, state, lastCommit) diff --git a/consensus/replay_test.go b/consensus/replay_test.go index 3a0f9024a..c3ded97cb 100644 --- a/consensus/replay_test.go +++ b/consensus/replay_test.go @@ -28,7 +28,6 @@ import ( "github.com/tendermint/tendermint/proxy" sm "github.com/tendermint/tendermint/state" "github.com/tendermint/tendermint/types" - tmtime "github.com/tendermint/tendermint/types/time" "github.com/tendermint/tendermint/version" dbm "github.com/tendermint/tm-cmn/db" ) @@ -849,31 +848,14 @@ func makeBlocks(n int, state *sm.State, privVal types.PrivValidator) []*types.Bl return blocks } -func makeVote(header *types.Header, blockID types.BlockID, valset *types.ValidatorSet, privVal types.PrivValidator) *types.Vote { - addr := privVal.GetPubKey().Address() - idx, _ := valset.GetByAddress(addr) - vote := &types.Vote{ - ValidatorAddress: addr, - ValidatorIndex: idx, - Height: header.Height, - Round: 1, - Timestamp: tmtime.Now(), - Type: types.PrecommitType, - BlockID: blockID, - } - - privVal.SignVote(header.ChainID, vote) - - return vote -} - func makeBlock(state sm.State, lastBlock *types.Block, lastBlockMeta *types.BlockMeta, privVal types.PrivValidator, height int64) (*types.Block, *types.PartSet) { lastCommit := types.NewCommit(types.BlockID{}, nil) if height > 1 { - vote := makeVote(&lastBlock.Header, lastBlockMeta.BlockID, state.Validators, privVal).CommitSig() - lastCommit = types.NewCommit(lastBlockMeta.BlockID, []*types.CommitSig{vote}) + vote, _ := types.MakeVote(lastBlock.Header.Height, lastBlockMeta.BlockID, state.Validators, privVal, lastBlock.Header.ChainID) + voteCommitSig := vote.CommitSig() + lastCommit = types.NewCommit(lastBlockMeta.BlockID, []*types.CommitSig{voteCommitSig}) } return state.MakeBlock(height, []types.Tx{}, lastCommit, nil, state.Validators.GetProposer().Address) diff --git a/state/helpers_test.go b/state/helpers_test.go index bd2a4e5ec..7e26f039b 100644 --- a/state/helpers_test.go +++ b/state/helpers_test.go @@ -69,29 +69,11 @@ func makeAndApplyGoodBlock(state sm.State, height int64, lastCommit *types.Commi return state, blockID, nil } -func makeVote(height int64, blockID types.BlockID, valSet *types.ValidatorSet, privVal types.PrivValidator) (*types.Vote, error) { - addr := privVal.GetPubKey().Address() - idx, _ := valSet.GetByAddress(addr) - vote := &types.Vote{ - ValidatorAddress: addr, - ValidatorIndex: idx, - Height: height, - Round: 0, - Timestamp: tmtime.Now(), - Type: types.PrecommitType, - BlockID: blockID, - } - if err := privVal.SignVote(chainID, vote); err != nil { - return nil, err - } - return vote, nil -} - func makeValidCommit(height int64, blockID types.BlockID, vals *types.ValidatorSet, privVals map[string]types.PrivValidator) (*types.Commit, error) { sigs := make([]*types.CommitSig, 0) for i := 0; i < vals.Size(); i++ { _, val := vals.GetByIndex(i) - vote, err := makeVote(height, blockID, vals, privVals[val.Address.String()]) + vote, err := types.MakeVote(height, blockID, vals, privVals[val.Address.String()], chainID) if err != nil { return nil, err } diff --git a/state/validation_test.go b/state/validation_test.go index c53cf0102..c0dd6e569 100644 --- a/state/validation_test.go +++ b/state/validation_test.go @@ -101,7 +101,7 @@ func TestValidateBlockCommit(t *testing.T) { #2589: ensure state.LastValidators.VerifyCommit fails here */ // should be height-1 instead of height - wrongHeightVote, err := makeVote(height, state.LastBlockID, state.Validators, privVals[proposerAddr.String()]) + wrongHeightVote, err := types.MakeVote(height, state.LastBlockID, state.Validators, privVals[proposerAddr.String()], chainID) require.NoError(t, err, "height %d", height) wrongHeightCommit := types.NewCommit(state.LastBlockID, []*types.CommitSig{wrongHeightVote.CommitSig()}) block, _ := state.MakeBlock(height, makeTxs(height), wrongHeightCommit, nil, proposerAddr) @@ -129,7 +129,7 @@ func TestValidateBlockCommit(t *testing.T) { /* wrongPrecommitsCommit is fine except for the extra bad precommit */ - goodVote, err := makeVote(height, blockID, state.Validators, privVals[proposerAddr.String()]) + goodVote, err := types.MakeVote(height, blockID, state.Validators, privVals[proposerAddr.String()], chainID) require.NoError(t, err, "height %d", height) badVote := &types.Vote{ ValidatorAddress: badPrivVal.GetPubKey().Address(), diff --git a/types/block.go b/types/block.go index 55709ad60..5dc0ff6a7 100644 --- a/types/block.go +++ b/types/block.go @@ -41,25 +41,6 @@ type Block struct { LastCommit *Commit `json:"last_commit"` } -// MakeBlock returns a new block with an empty header, except what can be -// computed from itself. -// It populates the same set of fields validated by ValidateBasic. -func MakeBlock(height int64, txs []Tx, lastCommit *Commit, evidence []Evidence) *Block { - block := &Block{ - Header: Header{ - Height: height, - NumTxs: int64(len(txs)), - }, - Data: Data{ - Txs: txs, - }, - Evidence: EvidenceData{Evidence: evidence}, - LastCommit: lastCommit, - } - block.fillHeader() - return block -} - // ValidateBasic performs basic validation that doesn't involve state data. // It checks the internal consistency of the block. // Further validation is done using state#ValidateBlock. diff --git a/types/test_util.go b/types/test_util.go index 18e472148..d226fd99e 100644 --- a/types/test_util.go +++ b/types/test_util.go @@ -5,8 +5,7 @@ import ( ) func MakeCommit(blockID BlockID, height int64, round int, - voteSet *VoteSet, - validators []PrivValidator) (*Commit, error) { + voteSet *VoteSet, validators []PrivValidator) (*Commit, error) { // all sign for i := 0; i < len(validators); i++ { @@ -37,3 +36,40 @@ func signAddVote(privVal PrivValidator, vote *Vote, voteSet *VoteSet) (signed bo } return voteSet.AddVote(vote) } + +func MakeVote(height int64, blockID BlockID, valSet *ValidatorSet, privVal PrivValidator, chainID string) (*Vote, error) { + addr := privVal.GetPubKey().Address() + idx, _ := valSet.GetByAddress(addr) + vote := &Vote{ + ValidatorAddress: addr, + ValidatorIndex: idx, + Height: height, + Round: 0, + Timestamp: tmtime.Now(), + Type: PrecommitType, + BlockID: blockID, + } + if err := privVal.SignVote(chainID, vote); err != nil { + return nil, err + } + return vote, nil +} + +// MakeBlock returns a new block with an empty header, except what can be +// computed from itself. +// It populates the same set of fields validated by ValidateBasic. +func MakeBlock(height int64, txs []Tx, lastCommit *Commit, evidence []Evidence) *Block { + block := &Block{ + Header: Header{ + Height: height, + NumTxs: int64(len(txs)), + }, + Data: Data{ + Txs: txs, + }, + Evidence: EvidenceData{Evidence: evidence}, + LastCommit: lastCommit, + } + block.fillHeader() + return block +} From 55066ceaadd2a5bf1bc69d28f4be66f403de14d4 Mon Sep 17 00:00:00 2001 From: Anton Kaliaev Date: Thu, 25 Jul 2019 15:06:18 +0400 Subject: [PATCH 17/45] p2p: Fix error logging for connection stop (#3824) * p2p: fix false-positive error logging when stopping connections This changeset fixes two types of false-positive errors occurring during connection shutdown. The first occurs when the process invokes FlushStop() or Stop() on a connection. While the previous behavior did properly wait for the sendRoutine to finish, it did not notify the recvRoutine that the connection was shutting down. This would cause the recvRouting to receive and error when reading and log this error. The changeset fixes this by notifying the recvRoutine that the connection is shutting down. The second occurs when the connection is terminated (gracefully) by the other side. The recvRoutine would get an EOF error during the read, log it, and stop the connection with an error. The changeset detects EOF and gracefully shuts down the connection. * bring back the comment about flushing * add changelog entry * listen for quitRecvRoutine too * we have to call stopForError Otherwise peer won't be removed from the peer set and maybe readded later. --- CHANGELOG_PENDING.md | 1 + p2p/conn/connection.go | 32 ++++++++++++++++++++++++++++---- 2 files changed, 29 insertions(+), 4 deletions(-) diff --git a/CHANGELOG_PENDING.md b/CHANGELOG_PENDING.md index c57b6b82e..e05213fc7 100644 --- a/CHANGELOG_PENDING.md +++ b/CHANGELOG_PENDING.md @@ -29,4 +29,5 @@ program](https://hackerone.com/tendermint). ### BUG FIXES: +- [p2p] [\#3644](https://github.com/tendermint/tendermint/pull/3644) Fix error logging for connection stop (@defunctzombie) - [rpc] \#3813 Return err if page is incorrect (less than 0 or greater than total pages) diff --git a/p2p/conn/connection.go b/p2p/conn/connection.go index ee29fc85c..a206af542 100644 --- a/p2p/conn/connection.go +++ b/p2p/conn/connection.go @@ -90,6 +90,9 @@ type MConnection struct { quitSendRoutine chan struct{} doneSendRoutine chan struct{} + // Closing quitRecvRouting will cause the recvRouting to eventually quit. + quitRecvRoutine chan struct{} + // used to ensure FlushStop and OnStop // are safe to call concurrently. stopMtx sync.Mutex @@ -206,6 +209,7 @@ func (c *MConnection) OnStart() error { c.chStatsTimer = time.NewTicker(updateStats) c.quitSendRoutine = make(chan struct{}) c.doneSendRoutine = make(chan struct{}) + c.quitRecvRoutine = make(chan struct{}) go c.sendRoutine() go c.recvRoutine() return nil @@ -220,7 +224,14 @@ func (c *MConnection) stopServices() (alreadyStopped bool) { select { case <-c.quitSendRoutine: - // already quit via FlushStop or OnStop + // already quit + return true + default: + } + + select { + case <-c.quitRecvRoutine: + // already quit return true default: } @@ -230,6 +241,8 @@ func (c *MConnection) stopServices() (alreadyStopped bool) { c.pingTimer.Stop() c.chStatsTimer.Stop() + // inform the recvRouting that we are shutting down + close(c.quitRecvRoutine) close(c.quitSendRoutine) return false } @@ -250,8 +263,6 @@ func (c *MConnection) FlushStop() { <-c.doneSendRoutine // Send and flush all pending msgs. - // By now, IsRunning == false, - // so any concurrent attempts to send will fail. // Since sendRoutine has exited, we can call this // safely eof := c.sendSomePacketMsgs() @@ -550,9 +561,22 @@ FOR_LOOP: var err error _n, err = cdc.UnmarshalBinaryLengthPrefixedReader(c.bufConnReader, &packet, int64(c._maxPacketMsgSize)) c.recvMonitor.Update(int(_n)) + if err != nil { + // stopServices was invoked and we are shutting down + // receiving is excpected to fail since we will close the connection + select { + case <-c.quitRecvRoutine: + break FOR_LOOP + default: + } + if c.IsRunning() { - c.Logger.Error("Connection failed @ recvRoutine (reading byte)", "conn", c, "err", err) + if err == io.EOF { + c.Logger.Info("Connection is closed @ recvRoutine (likely by the other side)", "conn", c) + } else { + c.Logger.Error("Connection failed @ recvRoutine (reading byte)", "conn", c, "err", err) + } c.stopForError(err) } break FOR_LOOP From 6d4f18aa8c8f53f4bf7143bb68d64baf2099ac8d Mon Sep 17 00:00:00 2001 From: folex <0xdxdy@gmail.com> Date: Thu, 25 Jul 2019 14:58:14 +0300 Subject: [PATCH 18/45] p2p: Do not write 'Couldn't connect to any seeds' if there are no seeds (#3834) * Do not write 'Couldn't connect to any seeds' if there are no seeds * changelog * remove privValUpgrade * Fix typo in changelog * Update CHANGELOG_PENDING.md Co-Authored-By: Marko I'm setting up all peers dynamically by calling dial_peers, so p2p.seeds in configs is empty, and I'm seeing error log a lot in logs. --- CHANGELOG_PENDING.md | 1 + p2p/pex/pex_reactor.go | 5 ++++- 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/CHANGELOG_PENDING.md b/CHANGELOG_PENDING.md index e05213fc7..9e229eb2f 100644 --- a/CHANGELOG_PENDING.md +++ b/CHANGELOG_PENDING.md @@ -20,6 +20,7 @@ program](https://hackerone.com/tendermint). ### IMPROVEMENTS: +- [p2p] \#3834 Do not write 'Couldn't connect to any seeds' error log if there are no seeds in config file - [abci] \#3809 Recover from application panics in `server/socket_server.go` to allow socket cleanup (@ruseinov) - [rpc] \#2252 Add `/broadcast_evidence` endpoint to submit double signing and other types of evidence - [rpc] \#3818 Make `max_body_bytes` and `max_header_bytes` configurable diff --git a/p2p/pex/pex_reactor.go b/p2p/pex/pex_reactor.go index 557e7ca75..55cde5a35 100644 --- a/p2p/pex/pex_reactor.go +++ b/p2p/pex/pex_reactor.go @@ -594,7 +594,10 @@ func (r *PEXReactor) dialSeeds() { } r.Switch.Logger.Error("Error dialing seed", "err", err, "seed", seedAddr) } - r.Switch.Logger.Error("Couldn't connect to any seeds") + // do not write error message if there were no seeds specified in config + if len(r.seedAddrs) > 0 { + r.Switch.Logger.Error("Couldn't connect to any seeds") + } } // AttemptsToDial returns the number of attempts to dial specific address. It From 5f6617db7a0b34fea58b3eb9c421f85eb0a310fd Mon Sep 17 00:00:00 2001 From: Anton Kaliaev Date: Thu, 25 Jul 2019 20:39:39 +0400 Subject: [PATCH 19/45] docs: add a footer to guides (#3835) --- docs/guides/go-built-in.md | 13 +++++++++++-- docs/guides/go.md | 13 +++++++++++-- 2 files changed, 22 insertions(+), 4 deletions(-) diff --git a/docs/guides/go-built-in.md b/docs/guides/go-built-in.md index a0c76c9e9..705022c90 100644 --- a/docs/guides/go-built-in.md +++ b/docs/guides/go-built-in.md @@ -1,4 +1,6 @@ -# 1 Guide Assumptions +# Creating a built-in application in Go + +## Guide assumptions This guide is designed for beginners who want to get started with a Tendermint Core application from scratch. It does not assume that you have any prior @@ -17,7 +19,7 @@ yourself with the syntax. By following along with this guide, you'll create a Tendermint Core project called kvstore, a (very) simple distributed BFT key-value store. -# 1 Creating a built-in application in Go +## Built-in app vs external app Running your application inside the same process as Tendermint Core will give you the best possible performance. @@ -628,3 +630,10 @@ $ curl -s 'localhost:26657/abci_query?data="tendermint"' "dGVuZGVybWludA==" and "cm9ja3M=" are the base64-encoding of the ASCII of "tendermint" and "rocks" accordingly. + +## Outro + +I hope everything went smoothly and your first, but hopefully not the last, +Tendermint Core application is up and running. If not, please [open an issue on +Github](https://github.com/tendermint/tendermint/issues/new/choose). To dig +deeper, read [the docs](https://tendermint.com/docs/). diff --git a/docs/guides/go.md b/docs/guides/go.md index abda07955..ada84adfc 100644 --- a/docs/guides/go.md +++ b/docs/guides/go.md @@ -1,4 +1,6 @@ -# 1 Guide Assumptions +# Creating an application in Go + +## Guide Assumptions This guide is designed for beginners who want to get started with a Tendermint Core application from scratch. It does not assume that you have any prior @@ -17,7 +19,7 @@ yourself with the syntax. By following along with this guide, you'll create a Tendermint Core project called kvstore, a (very) simple distributed BFT key-value store. -# 1 Creating an application in Go +## Built-in app vs external app To get maximum performance it is better to run your application alongside Tendermint Core. [Cosmos SDK](https://github.com/cosmos/cosmos-sdk) is written @@ -512,3 +514,10 @@ $ curl -s 'localhost:26657/abci_query?data="tendermint"' "dGVuZGVybWludA==" and "cm9ja3M=" are the base64-encoding of the ASCII of "tendermint" and "rocks" accordingly. + +## Outro + +I hope everything went smoothly and your first, but hopefully not the last, +Tendermint Core application is up and running. If not, please [open an issue on +Github](https://github.com/tendermint/tendermint/issues/new/choose). To dig +deeper, read [the docs](https://tendermint.com/docs/). From 53fdcfd7e908b50497316a0be67d414d9de7f43e Mon Sep 17 00:00:00 2001 From: Ivan Kushmantsev Date: Mon, 29 Jul 2019 21:48:11 +0400 Subject: [PATCH 20/45] docs: "Writing a Tendermint Core application in Kotlin (gRPC)" guide (#3838) * add abci grpc kotlin guide * Update docs/guides/kotlin.md Co-Authored-By: Anton Kaliaev * Update docs/guides/kotlin.md Co-Authored-By: Anton Kaliaev * Update docs/guides/kotlin.md Co-Authored-By: Anton Kaliaev * Update kotlin.md --- docs/guides/kotlin.md | 575 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 575 insertions(+) create mode 100644 docs/guides/kotlin.md diff --git a/docs/guides/kotlin.md b/docs/guides/kotlin.md new file mode 100644 index 000000000..8f462bd61 --- /dev/null +++ b/docs/guides/kotlin.md @@ -0,0 +1,575 @@ +# Creating an application in Kotlin + +## Guide Assumptions + +This guide is designed for beginners who want to get started with a Tendermint +Core application from scratch. It does not assume that you have any prior +experience with Tendermint Core. + +Tendermint Core is Byzantine Fault Tolerant (BFT) middleware that takes a state +transition machine (your application) - written in any programming language - and securely +replicates it on many machines. + +By following along with this guide, you'll create a Tendermint Core project +called kvstore, a (very) simple distributed BFT key-value store. The application (which should +implementing the blockchain interface (ABCI)) will be written in Kotlin. + +This guide assumes that you are not new to JVM world. If you are new please see [JVM Minimal Survival Guide](https://hadihariri.com/2013/12/29/jvm-minimal-survival-guide-for-the-dotnet-developer/#java-the-language-java-the-ecosystem-java-the-jvm) and [Gradle Docs](https://docs.gradle.org/current/userguide/userguide.html). + +## Built-in app vs external app + +If you use Golang, you can run your app and Tendermint Core in the same process to get maximum performance. +[Cosmos SDK](https://github.com/cosmos/cosmos-sdk) is written this way. +Please refer to [Writing a built-in Tendermint Core application in Go](./go-built-in.md) guide for details. + +If you choose another language, like we did in this guide, you have to write a separate app using +either plain socket or gRPC. This guide will show you how to build external applicationg +using RPC server. + +Having a separate application might give you better security guarantees as two +processes would be communicating via established binary protocol. Tendermint +Core will not have access to application's state. + +## 1.1 Installing Java and Gradle + +Please refer to [the Oracle's guide for installing JDK](https://www.oracle.com/technetwork/java/javase/downloads/index.html). + +Verify that you have installed Java successully: + +```sh +$ java -version +java version "1.8.0_162" +Java(TM) SE Runtime Environment (build 1.8.0_162-b12) +Java HotSpot(TM) 64-Bit Server VM (build 25.162-b12, mixed mode) +``` + +You can choose any version of Java higher or equal to 8. +In my case it is Java SE Development Kit 8. + +Make sure you have `$JAVA_HOME` environment variable set: + +```sh +$ echo $JAVA_HOME +/Library/Java/JavaVirtualMachines/jdk1.8.0_162.jdk/Contents/Home +``` + +For Gradle installation, please refer to [their official guide](https://gradle.org/install/). + +## 1.2 Creating a new Kotlin project + +We'll start by creating a new Gradle project. + +```sh +$ export KVSTORE_HOME=~/kvstore +$ mkdir $KVSTORE_HOME +$ cd $KVSTORE_HOME +``` + +Inside the example directory run: +```sh +gradle init --dsl groovy --package io.example --project-name example --type kotlin-application +``` +That Gradle command will create project structure for you: +```sh +$ tree +. +|-- build.gradle +|-- gradle +| `-- wrapper +| |-- gradle-wrapper.jar +| `-- gradle-wrapper.properties +|-- gradlew +|-- gradlew.bat +|-- settings.gradle +`-- src + |-- main + | |-- kotlin + | | `-- io + | | `-- example + | | `-- App.kt + | `-- resources + `-- test + |-- kotlin + | `-- io + | `-- example + | `-- AppTest.kt + `-- resources +``` + +When run, this should print "Hello world." to the standard output. + +```sh +$ ./gradlew run +> Task :run +Hello world. +``` + +## 1.3 Writing a Tendermint Core application + +Tendermint Core communicates with the application through the Application +BlockChain Interface (ABCI). All message types are defined in the [protobuf +file](https://github.com/tendermint/tendermint/blob/develop/abci/types/types.proto). +This allows Tendermint Core to run applications written in any programming +language. + +### 1.3.1 Compile .proto files + +Add folowing to the top of `build.gradle`: +```groovy +buildscript { + repositories { + mavenCentral() + } + dependencies { + classpath 'com.google.protobuf:protobuf-gradle-plugin:0.8.8' + } +} +``` + +Enable protobuf plugin in `plugins` section of `build.gradle`: +```groovy +plugins { + id 'com.google.protobuf' version '0.8.8' +} +``` + +Add following to `build.gradle`: +```groovy +protobuf { + protoc { + artifact = "com.google.protobuf:protoc:3.7.1" + } + plugins { + grpc { + artifact = 'io.grpc:protoc-gen-grpc-java:1.22.1' + } + } + generateProtoTasks { + all()*.plugins { + grpc {} + } + } +} +``` + +Now your project is ready to compile `*.proto` files. + + +Copy necessary .proto files to your project: +```sh +mkdir -p \ + $KVSTORE_HOME/src/main/proto/github.com/tendermint/tendermint/abci/types \ + $KVSTORE_HOME/src/main/proto/github.com/tendermint/tendermint/crypto/merkle \ + $KVSTORE_HOME/src/main/proto/github.com/tendermint/tendermint/libs/common \ + $KVSTORE_HOME/src/main/proto/github.com/gogo/protobuf/gogoproto + +cp $GOPATH/src/github.com/tendermint/tendermint/abci/types/types.proto \ + $KVSTORE_HOME/src/main/proto/github.com/tendermint/tendermint/abci/types/types.proto +cp $GOPATH/src/github.com/tendermint/tendermint/crypto/merkle/merkle.proto \ + $KVSTORE_HOME/src/main/proto/github.com/tendermint/tendermint/crypto/merkle/merkle.proto +cp $GOPATH/src/github.com/tendermint/tendermint/libs/common/types.proto \ + $KVSTORE_HOME/src/main/proto/github.com/tendermint/tendermint/libs/common/types.proto +cp $GOPATH/src/github.com/gogo/protobuf/gogoproto/gogo.proto \ + $KVSTORE_HOME/src/main/proto/github.com/gogo/protobuf/gogoproto/gogo.proto +``` + +Add dependency to `build.gradle`: +```groovy +dependencies { + implementation 'io.grpc:grpc-protobuf:1.22.1' + implementation 'io.grpc:grpc-netty-shaded:1.22.1' + implementation 'io.grpc:grpc-stub:1.22.1' +} +``` + +To generate all protobuf-type classes run: +```sh +./gradlew generateProto +``` +It will produce java classes to `build/generated/`: +```sh +$ tree build/generated/ +build/generated/ +`-- source + `-- proto + `-- main + |-- grpc + | `-- types + | `-- ABCIApplicationGrpc.java + `-- java + |-- com + | `-- google + | `-- protobuf + | `-- GoGoProtos.java + |-- common + | `-- Types.java + |-- merkle + | `-- Merkle.java + `-- types + `-- Types.java +``` + +### 1.3.2 Implementing ABCI + +As you can see there is a generated file `$KVSTORE_HOME/build/generated/source/proto/main/grpc/types/ABCIApplicationGrpc.java`. +which contains an abstract class `ABCIApplicationImplBase`. This class fully describes the ABCI interface. +All you need is implement this interface. + +Create file `$KVSTORE_HOME/src/main/kotlin/io/example/KVStoreApp.kt` with following context: +```kotlin +package io.example + +import io.grpc.stub.StreamObserver +import types.ABCIApplicationGrpc +import types.Types.* + +class KVStoreApp : ABCIApplicationGrpc.ABCIApplicationImplBase() { + + // methods implementation + +} +``` + +Now I will go through each method of `ABCIApplicationImplBase` explaining when it's called and adding +required business logic. + +### 1.3.3 CheckTx + +When a new transaction is added to the Tendermint Core, it will ask the +application to check it (validate the format, signatures, etc.). + +```kotlin +override fun checkTx(req: RequestCheckTx, responseObserver: StreamObserver) { + val code = req.tx.validate() + val resp = ResponseCheckTx.newBuilder() + .setCode(code) + .setGasWanted(1) + .build() + responseObserver.onNext(resp) + responseObserver.onCompleted() +} + +private fun ByteString.validate(): Int { + val parts = this.split('=') + if (parts.size != 2) { + return 1 + } + val key = parts[0] + val value = parts[1] + + // check if the same key=value already exists + val stored = getPersistedValue(key) + if (stored != null && stored.contentEquals(value)) { + return 2 + } + + return 0 +} + +private fun ByteString.split(separator: Char): List { + val arr = this.toByteArray() + val i = (0 until this.size()).firstOrNull { arr[it] == separator.toByte() } + ?: return emptyList() + return listOf( + this.substring(0, i).toByteArray(), + this.substring(i + 1).toByteArray() + ) +} +``` + +Don't worry if this does not compile yet. + +If the transaction does not have a form of `{bytes}={bytes}`, we return `1` +code. When the same key=value already exist (same key and value), we return `2` +code. For others, we return a zero code indicating that they are valid. + +Note that anything with non-zero code will be considered invalid (`-1`, `100`, +etc.) by Tendermint Core. + +Valid transactions will eventually be committed given they are not too big and +have enough gas. To learn more about gas, check out ["the +specification"](https://tendermint.com/docs/spec/abci/apps.html#gas). + +For the underlying key-value store we'll use +[JetBrains Xodus](https://github.com/JetBrains/xodus), which is a transactional schema-less embedded high-performance database written in Java. + +`build.gradle`: +```groovy +dependencies { + implementation "org.jetbrains.xodus:xodus-environment:1.3.91" +} +``` + +```kotlin +... +import jetbrains.exodus.ArrayByteIterable +import jetbrains.exodus.env.Environment +import jetbrains.exodus.env.Store +import jetbrains.exodus.env.StoreConfig +import jetbrains.exodus.env.Transaction + +class KVStoreApp( + private val env: Environment +) : ABCIApplicationGrpc.ABCIApplicationImplBase() { + + private var txn: Transaction? = null + private var store: Store? = null + + ... +} +``` + +### 1.3.4 BeginBlock -> DeliverTx -> EndBlock -> Commit + +When Tendermint Core has decided on the block, it's transfered to the +application in 3 parts: `BeginBlock`, one `DeliverTx` per transaction and +`EndBlock` in the end. DeliverTx are being transfered asynchronously, but the +responses are expected to come in order. + +```kotlin +override fun beginBlock(req: RequestBeginBlock, responseObserver: StreamObserver) { + txn = env.beginTransaction() + store = env.openStore("store", StoreConfig.WITHOUT_DUPLICATES, txn!!) + val resp = ResponseBeginBlock.newBuilder().build() + responseObserver.onNext(resp) + responseObserver.onCompleted() +} +``` +Here we start new transaction, which will store block's transactions, and open corresponding store. + +```kotlin +override fun deliverTx(req: RequestDeliverTx, responseObserver: StreamObserver) { + val code = req.tx.validate() + if (code == 0) { + val parts = req.tx.split('=') + val key = ArrayByteIterable(parts[0]) + val value = ArrayByteIterable(parts[1]) + store!!.put(txn!!, key, value) + } + val resp = ResponseDeliverTx.newBuilder() + .setCode(code) + .build() + responseObserver.onNext(resp) + responseObserver.onCompleted() +} +``` + +If the transaction is badly formatted or the same key=value already exist, we +again return the non-zero code. Otherwise, we add it to the storage. + +In the current design, a block can include incorrect transactions (those who +passed CheckTx, but failed DeliverTx or transactions included by the proposer +directly). This is done for performance reasons. + +Note we can't commit transactions inside the `DeliverTx` because in such case +`Query`, which may be called in parallel, will return inconsistent data (i.e. +it will report that some value already exist even when the actual block was not +yet committed). + +`Commit` instructs the application to persist the new state. + +```kotlin +override fun commit(req: RequestCommit, responseObserver: StreamObserver) { + txn!!.commit() + val resp = ResponseCommit.newBuilder() + .setData(ByteString.copyFrom(ByteArray(8))) + .build() + responseObserver.onNext(resp) + responseObserver.onCompleted() +} +``` + +### 1.3.5 Query + +Now, when the client wants to know whenever a particular key/value exist, it +will call Tendermint Core RPC `/abci_query` endpoint, which in turn will call +the application's `Query` method. + +Applications are free to provide their own APIs. But by using Tendermint Core +as a proxy, clients (including [light client +package](https://godoc.org/github.com/tendermint/tendermint/lite)) can leverage +the unified API across different applications. Plus they won't have to call the +otherwise separate Tendermint Core API for additional proofs. + +Note we don't include a proof here. + +```kotlin +override fun query(req: RequestQuery, responseObserver: StreamObserver) { + val k = req.data.toByteArray() + val v = getPersistedValue(k) + val builder = ResponseQuery.newBuilder() + if (v == null) { + builder.log = "does not exist" + } else { + builder.log = "exists" + builder.key = ByteString.copyFrom(k) + builder.value = ByteString.copyFrom(v) + } + responseObserver.onNext(builder.build()) + responseObserver.onCompleted() +} + +private fun getPersistedValue(k: ByteArray): ByteArray? { + return env.computeInReadonlyTransaction { txn -> + val store = env.openStore("store", StoreConfig.WITHOUT_DUPLICATES, txn) + store.get(txn, ArrayByteIterable(k))?.bytesUnsafe + } +} +``` + +The complete specification can be found +[here](https://tendermint.com/docs/spec/abci/). + +## 1.4 Starting an application and a Tendermint Core instances + +Put the following code into the `$KVSTORE_HOME/src/main/kotlin/io/example/App.kt` file: + +```kotlin +package io.example + +import jetbrains.exodus.env.Environments + +fun main() { + Environments.newInstance("tmp/storage").use { env -> + val app = KVStoreApp(env) + val server = GrpcServer(app, 26658) + server.start() + server.blockUntilShutdown() + } +} +``` + +It is the entry point of the application. +Here we create special object `Environment` which knows where to store state of the application. +Then we create and srart gRPC server to handle Tendermint's requests. + +Create file `$KVSTORE_HOME/src/main/kotlin/io/example/GrpcServer.kt`: +```kotlin +package io.example + +import io.grpc.BindableService +import io.grpc.ServerBuilder + +class GrpcServer( + private val service: BindableService, + private val port: Int +) { + private val server = ServerBuilder + .forPort(port) + .addService(service) + .build() + + fun start() { + server.start() + println("gRPC server started, listening on $port") + Runtime.getRuntime().addShutdownHook(object : Thread() { + override fun run() { + println("shutting down gRPC server since JVM is shutting down") + this@GrpcServer.stop() + println("server shut down") + } + }) + } + + fun stop() { + server.shutdown() + } + + /** + * Await termination on the main thread since the grpc library uses daemon threads. + */ + fun blockUntilShutdown() { + server.awaitTermination() + } + +} +``` + +## 1.5 Getting Up and Running + +To create a default configuration, nodeKey and private validator files, let's +execute `tendermint init`. But before we do that, we will need to install +Tendermint Core. + +```sh +$ rm -rf /tmp/example +$ cd $GOPATH/src/github.com/tendermint/tendermint +$ make install +$ TMHOME="/tmp/example" tendermint init + +I[2019-07-16|18:20:36.480] Generated private validator module=main keyFile=/tmp/example/config/priv_validator_key.json stateFile=/tmp/example2/data/priv_validator_state.json +I[2019-07-16|18:20:36.481] Generated node key module=main path=/tmp/example/config/node_key.json +I[2019-07-16|18:20:36.482] Generated genesis file module=main path=/tmp/example/config/genesis.json +``` + +Feel free to explore the generated files, which can be found at +`/tmp/example/config` directory. Documentation on the config can be found +[here](https://tendermint.com/docs/tendermint-core/configuration.html). + +We are ready to start our application: + +```sh +./gradlew run + +gRPC server started, listening on 26658 +``` + +Then we need to start Tendermint Core and point it to our application. Staying +within the application directory execute: + +```sh +$ TMHOME="/tmp/example" tendermint node --abci grpc --proxy_app tcp://127.0.0.1:26658 + +I[2019-07-28|15:44:53.632] Version info module=main software=0.32.1 block=10 p2p=7 +I[2019-07-28|15:44:53.677] Starting Node module=main impl=Node +I[2019-07-28|15:44:53.681] Started node module=main nodeInfo="{ProtocolVersion:{P2P:7 Block:10 App:0} ID_:7639e2841ccd47d5ae0f5aad3011b14049d3f452 ListenAddr:tcp://0.0.0.0:26656 Network:test-chain-Nhl3zk Version:0.32.1 Channels:4020212223303800 Moniker:Ivans-MacBook-Pro.local Other:{TxIndex:on RPCAddress:tcp://127.0.0.1:26657}}" +I[2019-07-28|15:44:54.801] Executed block module=state height=8 validTxs=0 invalidTxs=0 +I[2019-07-28|15:44:54.814] Committed state module=state height=8 txs=0 appHash=0000000000000000 +``` + +Now open another tab in your terminal and try sending a transaction: + +```sh +$ curl -s 'localhost:26657/broadcast_tx_commit?tx="tendermint=rocks"' +{ + "jsonrpc": "2.0", + "id": "", + "result": { + "check_tx": { + "gasWanted": "1" + }, + "deliver_tx": {}, + "hash": "CDD3C6DFA0A08CAEDF546F9938A2EEC232209C24AA0E4201194E0AFB78A2C2BB", + "height": "33" +} +``` + +Response should contain the height where this transaction was committed. + +Now let's check if the given key now exists and its value: + +```sh +$ curl -s 'localhost:26657/abci_query?data="tendermint"' +{ + "jsonrpc": "2.0", + "id": "", + "result": { + "response": { + "log": "exists", + "key": "dGVuZGVybWludA==", + "value": "cm9ja3My" + } + } +} +``` + +`dGVuZGVybWludA==` and `cm9ja3M=` are the base64-encoding of the ASCII of `tendermint` and `rocks` accordingly. + +## Outro + +I hope everything went smoothly and your first, but hopefully not the last, +Tendermint Core application is up and running. If not, please [open an issue on +Github](https://github.com/tendermint/tendermint/issues/new/choose). To dig +deeper, read [the docs](https://tendermint.com/docs/). + +The full source code of this example project can be found [here](https://github.com/climber73/tendermint-abci-grpc-kotlin). From 5c9d6d839e2ff890d7efdc171539a3161adc8184 Mon Sep 17 00:00:00 2001 From: Anton Kaliaev Date: Tue, 30 Jul 2019 17:08:11 +0400 Subject: [PATCH 21/45] node: allow replacing existing p2p.Reactor(s) (#3846) * node: allow replacing existing p2p.Reactor(s) using [`CustomReactors` option](https://godoc.org/github.com/tendermint/tendermint/node#CustomReactors). Warning: beware of accidental name clashes. Here is the list of existing reactors: MEMPOOL, BLOCKCHAIN, CONSENSUS, EVIDENCE, PEX. * check the absence of "CUSTOM" prefix * merge 2 tests * add doc.go to node package --- CHANGELOG_PENDING.md | 4 ++++ node/doc.go | 40 ++++++++++++++++++++++++++++++++++++++++ node/node.go | 23 +++++++++++++++++------ node/node_test.go | 7 ++++++- p2p/switch.go | 23 +++++++++++++++++++---- 5 files changed, 86 insertions(+), 11 deletions(-) create mode 100644 node/doc.go diff --git a/CHANGELOG_PENDING.md b/CHANGELOG_PENDING.md index 9e229eb2f..9d65efbe5 100644 --- a/CHANGELOG_PENDING.md +++ b/CHANGELOG_PENDING.md @@ -17,6 +17,10 @@ program](https://hackerone.com/tendermint). - [libs] \#3811 Remove `db` from libs in favor of `https://github.com/tendermint/tm-cmn` ### FEATURES: +- [node] Allow replacing existing p2p.Reactor(s) using [`CustomReactors` + option](https://godoc.org/github.com/tendermint/tendermint/node#CustomReactors). + Warning: beware of accidental name clashes. Here is the list of existing + reactors: MEMPOOL, BLOCKCHAIN, CONSENSUS, EVIDENCE, PEX. ### IMPROVEMENTS: diff --git a/node/doc.go b/node/doc.go new file mode 100644 index 000000000..08f3fa258 --- /dev/null +++ b/node/doc.go @@ -0,0 +1,40 @@ +/* +Package node is the main entry point, where the Node struct, which +represents a full node, is defined. + +Adding new p2p.Reactor(s) + +To add a new p2p.Reactor, use the CustomReactors option: + + node, err := NewNode( + config, + privVal, + nodeKey, + clientCreator, + genesisDocProvider, + dbProvider, + metricsProvider, + logger, + CustomReactors(map[string]p2p.Reactor{"CUSTOM": customReactor}), + ) + +Replacing existing p2p.Reactor(s) + +To replace the built-in p2p.Reactor, use the CustomReactors option: + + node, err := NewNode( + config, + privVal, + nodeKey, + clientCreator, + genesisDocProvider, + dbProvider, + metricsProvider, + logger, + CustomReactors(map[string]p2p.Reactor{"BLOCKCHAIN": customBlockchainReactor}), + ) + +The list of existing reactors can be found in CustomReactors documentation. + +*/ +package node diff --git a/node/node.go b/node/node.go index 60ba8e6d8..9060cf04b 100644 --- a/node/node.go +++ b/node/node.go @@ -48,10 +48,6 @@ import ( dbm "github.com/tendermint/tm-cmn/db" ) -// CustomReactorNamePrefix is a prefix for all custom reactors to prevent -// clashes with built-in reactors. -const CustomReactorNamePrefix = "CUSTOM_" - //------------------------------------------------------------------------------ // DBContext specifies config information for loading a new DB. @@ -144,11 +140,26 @@ func DefaultMetricsProvider(config *cfg.InstrumentationConfig) MetricsProvider { // Option sets a parameter for the node. type Option func(*Node) -// CustomReactors allows you to add custom reactors to the node's Switch. +// CustomReactors allows you to add custom reactors (name -> p2p.Reactor) to +// the node's Switch. +// +// WARNING: using any name from the below list of the existing reactors will +// result in replacing it with the custom one. +// +// - MEMPOOL +// - BLOCKCHAIN +// - CONSENSUS +// - EVIDENCE +// - PEX func CustomReactors(reactors map[string]p2p.Reactor) Option { return func(n *Node) { for name, reactor := range reactors { - n.sw.AddReactor(CustomReactorNamePrefix+name, reactor) + if existingReactor := n.sw.Reactor(name); existingReactor != nil { + n.sw.Logger.Info("Replacing existing reactor with a custom one", + "name", name, "existing", existingReactor, "custom", reactor) + n.sw.RemoveReactor(name, existingReactor) + } + n.sw.AddReactor(name, reactor) } } } diff --git a/node/node_test.go b/node/node_test.go index 0a0f8156a..669209f1a 100644 --- a/node/node_test.go +++ b/node/node_test.go @@ -288,6 +288,7 @@ func TestNodeNewNodeCustomReactors(t *testing.T) { defer os.RemoveAll(config.RootDir) cr := p2pmock.NewReactor() + customBlockchainReactor := p2pmock.NewReactor() nodeKey, err := p2p.LoadOrGenNodeKey(config.NodeKeyFile()) require.NoError(t, err) @@ -300,7 +301,7 @@ func TestNodeNewNodeCustomReactors(t *testing.T) { DefaultDBProvider, DefaultMetricsProvider(config.Instrumentation), log.TestingLogger(), - CustomReactors(map[string]p2p.Reactor{"FOO": cr}), + CustomReactors(map[string]p2p.Reactor{"FOO": cr, "BLOCKCHAIN": customBlockchainReactor}), ) require.NoError(t, err) @@ -309,6 +310,10 @@ func TestNodeNewNodeCustomReactors(t *testing.T) { defer n.Stop() assert.True(t, cr.IsRunning()) + assert.Equal(t, cr, n.Switch().Reactor("FOO")) + + assert.True(t, customBlockchainReactor.IsRunning()) + assert.Equal(t, customBlockchainReactor, n.Switch().Reactor("BLOCKCHAIN")) } func state(nVals int, height int64) (sm.State, dbm.DB) { diff --git a/p2p/switch.go b/p2p/switch.go index 7e681d67c..66c2f9e4a 100644 --- a/p2p/switch.go +++ b/p2p/switch.go @@ -152,11 +152,9 @@ func WithMetrics(metrics *Metrics) SwitchOption { // AddReactor adds the given reactor to the switch. // NOTE: Not goroutine safe. func (sw *Switch) AddReactor(name string, reactor Reactor) Reactor { - // Validate the reactor. - // No two reactors can share the same channel. - reactorChannels := reactor.GetChannels() - for _, chDesc := range reactorChannels { + for _, chDesc := range reactor.GetChannels() { chID := chDesc.ID + // No two reactors can share the same channel. if sw.reactorsByCh[chID] != nil { panic(fmt.Sprintf("Channel %X has multiple reactors %v & %v", chID, sw.reactorsByCh[chID], reactor)) } @@ -168,6 +166,23 @@ func (sw *Switch) AddReactor(name string, reactor Reactor) Reactor { return reactor } +// RemoveReactor removes the given Reactor from the Switch. +// NOTE: Not goroutine safe. +func (sw *Switch) RemoveReactor(name string, reactor Reactor) { + for _, chDesc := range reactor.GetChannels() { + // remove channel description + for i := 0; i < len(sw.chDescs); i++ { + if chDesc.ID == sw.chDescs[i].ID { + sw.chDescs = append(sw.chDescs[:i], sw.chDescs[i+1:]...) + break + } + } + delete(sw.reactorsByCh, chDesc.ID) + } + delete(sw.reactors, name) + reactor.SetSwitch(nil) +} + // Reactors returns a map of reactors registered on the switch. // NOTE: Not goroutine safe. func (sw *Switch) Reactors() map[string]Reactor { From 513a32a6e3920b4be4a7b2ee24807e72de46bfe5 Mon Sep 17 00:00:00 2001 From: Marko Date: Tue, 30 Jul 2019 16:13:35 +0200 Subject: [PATCH 22/45] gocritic (1/2) (#3836) Add gocritic as a linter The linting is not complete, but should i complete in this PR or in a following. 23 files have been touched so it may be better to do in a following PR Commits: * Add gocritic to linting - Added gocritic to linting Signed-off-by: Marko Baricevic * gocritic * pr comments * remove switch in cmdBatch --- abci/cmd/abci-cli/abci-cli.go | 50 +++++--------------- abci/example/kvstore/persistent_kvstore.go | 3 +- abci/server/socket_server.go | 7 +-- cmd/tendermint/commands/root_test.go | 2 +- consensus/mempool_test.go | 4 +- consensus/reactor_test.go | 12 ++--- consensus/replay.go | 6 +-- consensus/replay_file.go | 6 +-- consensus/state.go | 6 +-- consensus/state_test.go | 36 +++++++------- crypto/ed25519/ed25519.go | 4 +- crypto/internal/benchmarking/bench.go | 4 +- crypto/secp256k1/internal/secp256k1/curve.go | 1 + libs/cli/helper.go | 2 +- libs/common/random_test.go | 8 ++-- libs/common/string.go | 7 +-- mempool/reactor_test.go | 8 ++-- p2p/node_info_test.go | 2 +- p2p/pex/addrbook.go | 6 +-- rpc/lib/server/handlers.go | 10 ++-- state/state_test.go | 18 +++---- types/genesis.go | 6 +-- types/validator_set.go | 4 +- 23 files changed, 89 insertions(+), 123 deletions(-) diff --git a/abci/cmd/abci-cli/abci-cli.go b/abci/cmd/abci-cli/abci-cli.go index cd0a6fd1f..5f0685107 100644 --- a/abci/cmd/abci-cli/abci-cli.go +++ b/abci/cmd/abci-cli/abci-cli.go @@ -174,9 +174,7 @@ where example.file looks something like: info `, Args: cobra.ExactArgs(0), - RunE: func(cmd *cobra.Command, args []string) error { - return cmdBatch(cmd, args) - }, + RunE: cmdBatch, } var consoleCmd = &cobra.Command{ @@ -189,9 +187,7 @@ without opening a new connection each time `, Args: cobra.ExactArgs(0), ValidArgs: []string{"echo", "info", "set_option", "deliver_tx", "check_tx", "commit", "query"}, - RunE: func(cmd *cobra.Command, args []string) error { - return cmdConsole(cmd, args) - }, + RunE: cmdConsole, } var echoCmd = &cobra.Command{ @@ -199,27 +195,21 @@ var echoCmd = &cobra.Command{ Short: "have the application echo a message", Long: "have the application echo a message", Args: cobra.ExactArgs(1), - RunE: func(cmd *cobra.Command, args []string) error { - return cmdEcho(cmd, args) - }, + RunE: cmdEcho, } var infoCmd = &cobra.Command{ Use: "info", Short: "get some info about the application", Long: "get some info about the application", Args: cobra.ExactArgs(0), - RunE: func(cmd *cobra.Command, args []string) error { - return cmdInfo(cmd, args) - }, + RunE: cmdInfo, } var setOptionCmd = &cobra.Command{ Use: "set_option", Short: "set an option on the application", Long: "set an option on the application", Args: cobra.ExactArgs(2), - RunE: func(cmd *cobra.Command, args []string) error { - return cmdSetOption(cmd, args) - }, + RunE: cmdSetOption, } var deliverTxCmd = &cobra.Command{ @@ -227,9 +217,7 @@ var deliverTxCmd = &cobra.Command{ Short: "deliver a new transaction to the application", Long: "deliver a new transaction to the application", Args: cobra.ExactArgs(1), - RunE: func(cmd *cobra.Command, args []string) error { - return cmdDeliverTx(cmd, args) - }, + RunE: cmdDeliverTx, } var checkTxCmd = &cobra.Command{ @@ -237,9 +225,7 @@ var checkTxCmd = &cobra.Command{ Short: "validate a transaction", Long: "validate a transaction", Args: cobra.ExactArgs(1), - RunE: func(cmd *cobra.Command, args []string) error { - return cmdCheckTx(cmd, args) - }, + RunE: cmdCheckTx, } var commitCmd = &cobra.Command{ @@ -247,9 +233,7 @@ var commitCmd = &cobra.Command{ Short: "commit the application state and return the Merkle root hash", Long: "commit the application state and return the Merkle root hash", Args: cobra.ExactArgs(0), - RunE: func(cmd *cobra.Command, args []string) error { - return cmdCommit(cmd, args) - }, + RunE: cmdCommit, } var versionCmd = &cobra.Command{ @@ -268,9 +252,7 @@ var queryCmd = &cobra.Command{ Short: "query the application state", Long: "query the application state", Args: cobra.ExactArgs(1), - RunE: func(cmd *cobra.Command, args []string) error { - return cmdQuery(cmd, args) - }, + RunE: cmdQuery, } var counterCmd = &cobra.Command{ @@ -278,9 +260,7 @@ var counterCmd = &cobra.Command{ Short: "ABCI demo example", Long: "ABCI demo example", Args: cobra.ExactArgs(0), - RunE: func(cmd *cobra.Command, args []string) error { - return cmdCounter(cmd, args) - }, + RunE: cmdCounter, } var kvstoreCmd = &cobra.Command{ @@ -288,9 +268,7 @@ var kvstoreCmd = &cobra.Command{ Short: "ABCI demo example", Long: "ABCI demo example", Args: cobra.ExactArgs(0), - RunE: func(cmd *cobra.Command, args []string) error { - return cmdKVStore(cmd, args) - }, + RunE: cmdKVStore, } var testCmd = &cobra.Command{ @@ -298,9 +276,7 @@ var testCmd = &cobra.Command{ Short: "run integration tests", Long: "run integration tests", Args: cobra.ExactArgs(0), - RunE: func(cmd *cobra.Command, args []string) error { - return cmdTest(cmd, args) - }, + RunE: cmdTest, } // Generates new Args array based off of previous call args to maintain flag persistence @@ -419,7 +395,7 @@ func muxOnCommands(cmd *cobra.Command, pArgs []string) error { } // otherwise, we need to skip the next one too - i += 1 + i++ continue } diff --git a/abci/example/kvstore/persistent_kvstore.go b/abci/example/kvstore/persistent_kvstore.go index 308100b6a..4f84cd3e9 100644 --- a/abci/example/kvstore/persistent_kvstore.go +++ b/abci/example/kvstore/persistent_kvstore.go @@ -121,8 +121,7 @@ func (app *PersistentKVStoreApplication) BeginBlock(req types.RequestBeginBlock) app.ValUpdates = make([]types.ValidatorUpdate, 0) for _, ev := range req.ByzantineValidators { - switch ev.Type { - case tmtypes.ABCIEvidenceTypeDuplicateVote: + if ev.Type == tmtypes.ABCIEvidenceTypeDuplicateVote { // decrease voting power by 1 if ev.TotalVotingPower == 0 { continue diff --git a/abci/server/socket_server.go b/abci/server/socket_server.go index 82ce610ed..3e1d775d7 100644 --- a/abci/server/socket_server.go +++ b/abci/server/socket_server.go @@ -127,11 +127,12 @@ func (s *SocketServer) acceptConnectionsRoutine() { func (s *SocketServer) waitForClose(closeConn chan error, connID int) { err := <-closeConn - if err == io.EOF { + switch { + case err == io.EOF: s.Logger.Error("Connection was closed by client") - } else if err != nil { + case err != nil: s.Logger.Error("Connection error", "error", err) - } else { + default: // never happens s.Logger.Error("Connection was closed.") } diff --git a/cmd/tendermint/commands/root_test.go b/cmd/tendermint/commands/root_test.go index 892a49b74..229385af9 100644 --- a/cmd/tendermint/commands/root_test.go +++ b/cmd/tendermint/commands/root_test.go @@ -165,7 +165,7 @@ func TestRootConfig(t *testing.T) { func WriteConfigVals(dir string, vals map[string]string) error { data := "" for k, v := range vals { - data = data + fmt.Sprintf("%s = \"%s\"\n", k, v) + data += fmt.Sprintf("%s = \"%s\"\n", k, v) } cfile := filepath.Join(dir, "config.toml") return ioutil.WriteFile(cfile, []byte(data), 0666) diff --git a/consensus/mempool_test.go b/consensus/mempool_test.go index 94f7340c2..f4df1aca1 100644 --- a/consensus/mempool_test.go +++ b/consensus/mempool_test.go @@ -82,14 +82,14 @@ func TestMempoolProgressInHigherRound(t *testing.T) { ensureNewRound(newRoundCh, height, round) // first round at first height ensureNewEventOnChannel(newBlockCh) // first block gets committed - height = height + 1 // moving to the next height + height++ // moving to the next height round = 0 ensureNewRound(newRoundCh, height, round) // first round at next height deliverTxsRange(cs, 0, 1) // we deliver txs, but dont set a proposal so we get the next round ensureNewTimeout(timeoutCh, height, round, cs.config.TimeoutPropose.Nanoseconds()) - round = round + 1 // moving to the next round + round++ // moving to the next round ensureNewRound(newRoundCh, height, round) // wait for the next round ensureNewEventOnChannel(newBlockCh) // now we can commit the block } diff --git a/consensus/reactor_test.go b/consensus/reactor_test.go index af6a62568..6697efdb8 100644 --- a/consensus/reactor_test.go +++ b/consensus/reactor_test.go @@ -31,15 +31,15 @@ import ( //---------------------------------------------- // in-process testnets -func startConsensusNet(t *testing.T, css []*ConsensusState, N int) ( +func startConsensusNet(t *testing.T, css []*ConsensusState, n int) ( []*ConsensusReactor, []types.Subscription, []*types.EventBus, ) { - reactors := make([]*ConsensusReactor, N) + reactors := make([]*ConsensusReactor, n) blocksSubs := make([]types.Subscription, 0) - eventBuses := make([]*types.EventBus, N) - for i := 0; i < N; i++ { + eventBuses := make([]*types.EventBus, n) + for i := 0; i < n; i++ { /*logger, err := tmflags.ParseLogLevel("consensus:info,*:error", logger, "info") if err != nil { t.Fatal(err)}*/ reactors[i] = NewConsensusReactor(css[i], true) // so we dont start the consensus states @@ -58,7 +58,7 @@ func startConsensusNet(t *testing.T, css []*ConsensusState, N int) ( } } // make connected switches and start all reactors - p2p.MakeConnectedSwitches(config.P2P, N, func(i int, s *p2p.Switch) *p2p.Switch { + p2p.MakeConnectedSwitches(config.P2P, n, func(i int, s *p2p.Switch) *p2p.Switch { s.AddReactor("CONSENSUS", reactors[i]) s.SetLogger(reactors[i].conS.Logger.With("module", "p2p")) return s @@ -68,7 +68,7 @@ func startConsensusNet(t *testing.T, css []*ConsensusState, N int) ( // If we started the state machines before everyone was connected, // we'd block when the cs fires NewBlockEvent and the peers are trying to start their reactors // TODO: is this still true with new pubsub? - for i := 0; i < N; i++ { + for i := 0; i < n; i++ { s := reactors[i].conS.GetState() reactors[i].SwitchToConsensus(s, 0) } diff --git a/consensus/replay.go b/consensus/replay.go index a55fd80c5..797593585 100644 --- a/consensus/replay.go +++ b/consensus/replay.go @@ -320,11 +320,9 @@ func (h *Handshaker) ReplayBlocks( } state.Validators = types.NewValidatorSet(vals) state.NextValidators = types.NewValidatorSet(vals) - } else { + } else if len(h.genDoc.Validators) == 0 { // If validator set is not set in genesis and still empty after InitChain, exit. - if len(h.genDoc.Validators) == 0 { - return nil, fmt.Errorf("validator set is nil in genesis and still empty after InitChain") - } + return nil, fmt.Errorf("validator set is nil in genesis and still empty after InitChain") } if res.ConsensusParams != nil { diff --git a/consensus/replay_file.go b/consensus/replay_file.go index e686262d6..00a18c218 100644 --- a/consensus/replay_file.go +++ b/consensus/replay_file.go @@ -231,10 +231,8 @@ func (pb *playback) replayConsoleLoop() int { fmt.Println("back takes an integer argument") } else if i > pb.count { fmt.Printf("argument to back must not be larger than the current count (%d)\n", pb.count) - } else { - if err := pb.replayReset(i, newStepSub); err != nil { - pb.cs.Logger.Error("Replay reset error", "err", err) - } + } else if err := pb.replayReset(i, newStepSub); err != nil { + pb.cs.Logger.Error("Replay reset error", "err", err) } } diff --git a/consensus/state.go b/consensus/state.go index 0a48b0525..fe6fefd42 100644 --- a/consensus/state.go +++ b/consensus/state.go @@ -924,10 +924,8 @@ func (cs *ConsensusState) defaultDecideProposal(height int64, round int) { } cs.Logger.Info("Signed proposal", "height", height, "round", round, "proposal", proposal) cs.Logger.Debug(fmt.Sprintf("Signed proposal block: %v", block)) - } else { - if !cs.replayMode { - cs.Logger.Error("enterPropose: Error signing proposal", "height", height, "round", round, "err", err) - } + } else if !cs.replayMode { + cs.Logger.Error("enterPropose: Error signing proposal", "height", height, "round", round, "err", err) } } diff --git a/consensus/state_test.go b/consensus/state_test.go index 1888e4057..8409f2235 100644 --- a/consensus/state_test.go +++ b/consensus/state_test.go @@ -181,7 +181,7 @@ func TestStateBadProposal(t *testing.T) { propBlock, _ := cs1.createProposalBlock() //changeProposer(t, cs1, vs2) // make the second validator the proposer by incrementing round - round = round + 1 + round++ incrementRound(vss[1:]...) // make the block bad by tampering with statehash @@ -374,7 +374,7 @@ func TestStateLockNoPOL(t *testing.T) { /// - round = round + 1 // moving to the next round + round++ // moving to the next round ensureNewRound(newRoundCh, height, round) t.Log("#### ONTO ROUND 1") /* @@ -418,7 +418,7 @@ func TestStateLockNoPOL(t *testing.T) { // then we enterPrecommitWait and timeout into NewRound ensureNewTimeout(timeoutWaitCh, height, round, cs1.config.Precommit(round).Nanoseconds()) - round = round + 1 // entering new round + round++ // entering new round ensureNewRound(newRoundCh, height, round) t.Log("#### ONTO ROUND 2") /* @@ -460,7 +460,7 @@ func TestStateLockNoPOL(t *testing.T) { incrementRound(vs2) - round = round + 1 // entering new round + round++ // entering new round ensureNewRound(newRoundCh, height, round) t.Log("#### ONTO ROUND 3") /* @@ -544,7 +544,7 @@ func TestStateLockPOLRelock(t *testing.T) { // timeout to new round ensureNewTimeout(timeoutWaitCh, height, round, cs1.config.Precommit(round).Nanoseconds()) - round = round + 1 // moving to the next round + round++ // moving to the next round //XXX: this isnt guaranteed to get there before the timeoutPropose ... if err := cs1.SetProposalAndBlock(prop, propBlock, propBlockParts, "some peer"); err != nil { t.Fatal(err) @@ -635,7 +635,7 @@ func TestStateLockPOLUnlock(t *testing.T) { lockedBlockHash := rs.LockedBlock.Hash() incrementRound(vs2, vs3, vs4) - round = round + 1 // moving to the next round + round++ // moving to the next round ensureNewRound(newRoundCh, height, round) t.Log("#### ONTO ROUND 1") @@ -718,7 +718,7 @@ func TestStateLockPOLSafety1(t *testing.T) { incrementRound(vs2, vs3, vs4) - round = round + 1 // moving to the next round + round++ // moving to the next round ensureNewRound(newRoundCh, height, round) //XXX: this isnt guaranteed to get there before the timeoutPropose ... @@ -755,7 +755,7 @@ func TestStateLockPOLSafety1(t *testing.T) { ensureNewTimeout(timeoutWaitCh, height, round, cs1.config.Precommit(round).Nanoseconds()) incrementRound(vs2, vs3, vs4) - round = round + 1 // moving to the next round + round++ // moving to the next round ensureNewRound(newRoundCh, height, round) @@ -821,7 +821,7 @@ func TestStateLockPOLSafety2(t *testing.T) { incrementRound(vs2, vs3, vs4) - round = round + 1 // moving to the next round + round++ // moving to the next round t.Log("### ONTO Round 1") // jump in at round 1 startTestRound(cs1, height, round) @@ -850,7 +850,7 @@ func TestStateLockPOLSafety2(t *testing.T) { // timeout of precommit wait to new round ensureNewTimeout(timeoutWaitCh, height, round, cs1.config.Precommit(round).Nanoseconds()) - round = round + 1 // moving to the next round + round++ // moving to the next round // in round 2 we see the polkad block from round 0 newProp := types.NewProposal(height, round, 0, propBlockID0) if err := vs3.SignProposal(config.ChainID(), newProp); err != nil { @@ -920,7 +920,7 @@ func TestProposeValidBlock(t *testing.T) { ensureNewTimeout(timeoutWaitCh, height, round, cs1.config.Precommit(round).Nanoseconds()) incrementRound(vs2, vs3, vs4) - round = round + 1 // moving to the next round + round++ // moving to the next round ensureNewRound(newRoundCh, height, round) @@ -945,14 +945,14 @@ func TestProposeValidBlock(t *testing.T) { signAddVotes(cs1, types.PrecommitType, nil, types.PartSetHeader{}, vs2, vs3, vs4) - round = round + 2 // moving to the next round + round += 2 // moving to the next round ensureNewRound(newRoundCh, height, round) t.Log("### ONTO ROUND 3") ensureNewTimeout(timeoutWaitCh, height, round, cs1.config.Precommit(round).Nanoseconds()) - round = round + 1 // moving to the next round + round++ // moving to the next round ensureNewRound(newRoundCh, height, round) @@ -1044,7 +1044,7 @@ func TestSetValidBlockOnDelayedProposal(t *testing.T) { voteCh := subscribeToVoter(cs1, addr) proposalCh := subscribe(cs1.eventBus, types.EventQueryCompleteProposal) - round = round + 1 // move to round in which P0 is not proposer + round++ // move to round in which P0 is not proposer incrementRound(vs2, vs3, vs4) startTestRound(cs1, cs1.Height, round) @@ -1123,7 +1123,7 @@ func TestWaitingTimeoutProposeOnNewRound(t *testing.T) { incrementRound(vss[1:]...) signAddVotes(cs1, types.PrevoteType, nil, types.PartSetHeader{}, vs2, vs3, vs4) - round = round + 1 // moving to the next round + round++ // moving to the next round ensureNewRound(newRoundCh, height, round) rs := cs1.GetRoundState() @@ -1157,7 +1157,7 @@ func TestRoundSkipOnNilPolkaFromHigherRound(t *testing.T) { incrementRound(vss[1:]...) signAddVotes(cs1, types.PrecommitType, nil, types.PartSetHeader{}, vs2, vs3, vs4) - round = round + 1 // moving to the next round + round++ // moving to the next round ensureNewRound(newRoundCh, height, round) ensurePrecommit(voteCh, height, round) @@ -1165,7 +1165,7 @@ func TestRoundSkipOnNilPolkaFromHigherRound(t *testing.T) { ensureNewTimeout(timeoutWaitCh, height, round, cs1.config.Precommit(round).Nanoseconds()) - round = round + 1 // moving to the next round + round++ // moving to the next round ensureNewRound(newRoundCh, height, round) } @@ -1511,7 +1511,7 @@ func TestStateHalt1(t *testing.T) { // timeout to new round ensureNewTimeout(timeoutWaitCh, height, round, cs1.config.Precommit(round).Nanoseconds()) - round = round + 1 // moving to the next round + round++ // moving to the next round ensureNewRound(newRoundCh, height, round) rs = cs1.GetRoundState() diff --git a/crypto/ed25519/ed25519.go b/crypto/ed25519/ed25519.go index bc60838d5..8947608ae 100644 --- a/crypto/ed25519/ed25519.go +++ b/crypto/ed25519/ed25519.go @@ -54,7 +54,7 @@ func (privKey PrivKeyEd25519) Bytes() []byte { // incorrect signature. func (privKey PrivKeyEd25519) Sign(msg []byte) ([]byte, error) { signatureBytes := ed25519.Sign(privKey[:], msg) - return signatureBytes[:], nil + return signatureBytes, nil } // PubKey gets the corresponding public key from the private key. @@ -100,7 +100,7 @@ func GenPrivKey() PrivKeyEd25519 { // genPrivKey generates a new ed25519 private key using the provided reader. func genPrivKey(rand io.Reader) PrivKeyEd25519 { seed := make([]byte, 32) - _, err := io.ReadFull(rand, seed[:]) + _, err := io.ReadFull(rand, seed) if err != nil { panic(err) } diff --git a/crypto/internal/benchmarking/bench.go b/crypto/internal/benchmarking/bench.go index c988de48e..43ab312f0 100644 --- a/crypto/internal/benchmarking/bench.go +++ b/crypto/internal/benchmarking/bench.go @@ -24,10 +24,10 @@ func (zeroReader) Read(buf []byte) (int, error) { // BenchmarkKeyGeneration benchmarks the given key generation algorithm using // a dummy reader. -func BenchmarkKeyGeneration(b *testing.B, GenerateKey func(reader io.Reader) crypto.PrivKey) { +func BenchmarkKeyGeneration(b *testing.B, generateKey func(reader io.Reader) crypto.PrivKey) { var zero zeroReader for i := 0; i < b.N; i++ { - GenerateKey(zero) + generateKey(zero) } } diff --git a/crypto/secp256k1/internal/secp256k1/curve.go b/crypto/secp256k1/internal/secp256k1/curve.go index 5409ee1d2..df87200f2 100644 --- a/crypto/secp256k1/internal/secp256k1/curve.go +++ b/crypto/secp256k1/internal/secp256k1/curve.go @@ -30,6 +30,7 @@ // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +// nolint:gocritic package secp256k1 import ( diff --git a/libs/cli/helper.go b/libs/cli/helper.go index 878cf26e5..6bf23750c 100644 --- a/libs/cli/helper.go +++ b/libs/cli/helper.go @@ -14,7 +14,7 @@ import ( func WriteConfigVals(dir string, vals map[string]string) error { data := "" for k, v := range vals { - data = data + fmt.Sprintf("%s = \"%s\"\n", k, v) + data += fmt.Sprintf("%s = \"%s\"\n", k, v) } cfile := filepath.Join(dir, "config.toml") return ioutil.WriteFile(cfile, []byte(data), 0666) diff --git a/libs/common/random_test.go b/libs/common/random_test.go index c59a577b8..74dcc04b4 100644 --- a/libs/common/random_test.go +++ b/libs/common/random_test.go @@ -45,11 +45,9 @@ func TestDeterminism(t *testing.T) { output := testThemAll() if i == 0 { firstOutput = output - } else { - if firstOutput != output { - t.Errorf("Run #%d's output was different from first run.\nfirst: %v\nlast: %v", - i, firstOutput, output) - } + } else if firstOutput != output { + t.Errorf("Run #%d's output was different from first run.\nfirst: %v\nlast: %v", + i, firstOutput, output) } } } diff --git a/libs/common/string.go b/libs/common/string.go index ddf350b10..4f8a8f20d 100644 --- a/libs/common/string.go +++ b/libs/common/string.go @@ -51,11 +51,12 @@ func IsASCIIText(s string) bool { func ASCIITrim(s string) string { r := make([]byte, 0, len(s)) for _, b := range []byte(s) { - if b == 32 { + switch { + case b == 32: continue // skip space - } else if 32 < b && b <= 126 { + case 32 < b && b <= 126: r = append(r, b) - } else { + default: panic(fmt.Sprintf("non-ASCII (non-tab) char 0x%X", b)) } } diff --git a/mempool/reactor_test.go b/mempool/reactor_test.go index 94c0d1900..dff4c0d68 100644 --- a/mempool/reactor_test.go +++ b/mempool/reactor_test.go @@ -42,10 +42,10 @@ func mempoolLogger() log.Logger { } // connect N mempool reactors through N switches -func makeAndConnectReactors(config *cfg.Config, N int) []*Reactor { - reactors := make([]*Reactor, N) +func makeAndConnectReactors(config *cfg.Config, n int) []*Reactor { + reactors := make([]*Reactor, n) logger := mempoolLogger() - for i := 0; i < N; i++ { + for i := 0; i < n; i++ { app := kvstore.NewKVStoreApplication() cc := proxy.NewLocalClientCreator(app) mempool, cleanup := newMempoolWithApp(cc) @@ -55,7 +55,7 @@ func makeAndConnectReactors(config *cfg.Config, N int) []*Reactor { reactors[i].SetLogger(logger.With("validator", i)) } - p2p.MakeConnectedSwitches(config.P2P, N, func(i int, s *p2p.Switch) *p2p.Switch { + p2p.MakeConnectedSwitches(config.P2P, n, func(i int, s *p2p.Switch) *p2p.Switch { s.AddReactor("MEMPOOL", reactors[i]) return s diff --git a/p2p/node_info_test.go b/p2p/node_info_test.go index 19567d2bf..9ed80b28b 100644 --- a/p2p/node_info_test.go +++ b/p2p/node_info_test.go @@ -19,7 +19,7 @@ func TestNodeInfoValidate(t *testing.T) { channels[i] = byte(i) } dupChannels := make([]byte, 5) - copy(dupChannels[:], channels[:5]) + copy(dupChannels, channels[:5]) dupChannels = append(dupChannels, testCh) nonAscii := "¢§µ" diff --git a/p2p/pex/addrbook.go b/p2p/pex/addrbook.go index cfe2569ba..27bcef9e8 100644 --- a/p2p/pex/addrbook.go +++ b/p2p/pex/addrbook.go @@ -178,11 +178,11 @@ func (a *addrBook) OurAddress(addr *p2p.NetAddress) bool { return ok } -func (a *addrBook) AddPrivateIDs(IDs []string) { +func (a *addrBook) AddPrivateIDs(ids []string) { a.mtx.Lock() defer a.mtx.Unlock() - for _, id := range IDs { + for _, id := range ids { a.privateIDs[p2p.ID(id)] = struct{}{} } } @@ -643,7 +643,7 @@ func (a *addrBook) randomPickAddresses(bucketType byte, num int) []*p2p.NetAddre } total := 0 for _, bucket := range buckets { - total = total + len(bucket) + total += len(bucket) } addresses := make([]*knownAddress, 0, total) for _, bucket := range buckets { diff --git a/rpc/lib/server/handlers.go b/rpc/lib/server/handlers.go index 434ee8916..78bc7b259 100644 --- a/rpc/lib/server/handlers.go +++ b/rpc/lib/server/handlers.go @@ -735,12 +735,10 @@ func (wsc *wsConnection) writeRoutine() { jsonBytes, err := json.MarshalIndent(msg, "", " ") if err != nil { wsc.Logger.Error("Failed to marshal RPCResponse to JSON", "err", err) - } else { - if err = wsc.writeMessageWithDeadline(websocket.TextMessage, jsonBytes); err != nil { - wsc.Logger.Error("Failed to write response", "err", err) - wsc.Stop() - return - } + } else if err = wsc.writeMessageWithDeadline(websocket.TextMessage, jsonBytes); err != nil { + wsc.Logger.Error("Failed to write response", "err", err) + wsc.Stop() + return } case <-wsc.Quit(): return diff --git a/state/state_test.go b/state/state_test.go index 0512fbf38..ac3b4db9f 100644 --- a/state/state_test.go +++ b/state/state_test.go @@ -440,13 +440,13 @@ func TestProposerPriorityDoesNotGetResetToZero(t *testing.T) { // 3. Center - with avg, resulting val2:-61, val1:62 avg := big.NewInt(0).Add(big.NewInt(wantVal1Prio), big.NewInt(wantVal2Prio)) avg.Div(avg, big.NewInt(2)) - wantVal2Prio = wantVal2Prio - avg.Int64() // -61 - wantVal1Prio = wantVal1Prio - avg.Int64() // 62 + wantVal2Prio -= avg.Int64() // -61 + wantVal1Prio -= avg.Int64() // 62 // 4. Steps from IncrementProposerPriority - wantVal1Prio = wantVal1Prio + val1VotingPower // 72 - wantVal2Prio = wantVal2Prio + val2VotingPower // 39 - wantVal1Prio = wantVal1Prio - totalPowerAfter // -38 as val1 is proposer + wantVal1Prio += val1VotingPower // 72 + wantVal2Prio += val2VotingPower // 39 + wantVal1Prio -= totalPowerAfter // -38 as val1 is proposer assert.Equal(t, wantVal1Prio, updatedVal1.ProposerPriority) assert.Equal(t, wantVal2Prio, addedVal2.ProposerPriority) @@ -563,9 +563,9 @@ func TestProposerPriorityProposerAlternates(t *testing.T) { expectedVal2Prio := v2PrioWhenAddedVal2 - avg.Int64() // -11 expectedVal1Prio := oldVal1.ProposerPriority - avg.Int64() // 11 // 4. Increment - expectedVal2Prio = expectedVal2Prio + val2VotingPower // -11 + 10 = -1 - expectedVal1Prio = expectedVal1Prio + val1VotingPower // 11 + 10 == 21 - expectedVal1Prio = expectedVal1Prio - totalPower // 1, val1 proposer + expectedVal2Prio += val2VotingPower // -11 + 10 = -1 + expectedVal1Prio += val1VotingPower // 11 + 10 == 21 + expectedVal1Prio -= totalPower // 1, val1 proposer assert.EqualValues(t, expectedVal1Prio, updatedVal1.ProposerPriority) assert.EqualValues(t, expectedVal2Prio, updatedVal2.ProposerPriority, "unexpected proposer priority for validator: %v", updatedVal2) @@ -589,7 +589,7 @@ func TestProposerPriorityProposerAlternates(t *testing.T) { // Increment expectedVal2Prio2 := expectedVal2Prio + val2VotingPower // -1 + 10 = 9 expectedVal1Prio2 := expectedVal1Prio + val1VotingPower // 1 + 10 == 11 - expectedVal1Prio2 = expectedVal1Prio2 - totalPower // -9, val1 proposer + expectedVal1Prio2 -= totalPower // -9, val1 proposer assert.EqualValues(t, expectedVal1Prio2, updatedVal1.ProposerPriority, "unexpected proposer priority for validator: %v", updatedVal2) assert.EqualValues(t, expectedVal2Prio2, updatedVal2.ProposerPriority, "unexpected proposer priority for validator: %v", updatedVal2) diff --git a/types/genesis.go b/types/genesis.go index 54b81e9e2..de59fc87e 100644 --- a/types/genesis.go +++ b/types/genesis.go @@ -72,10 +72,8 @@ func (genDoc *GenesisDoc) ValidateAndComplete() error { if genDoc.ConsensusParams == nil { genDoc.ConsensusParams = DefaultConsensusParams() - } else { - if err := genDoc.ConsensusParams.Validate(); err != nil { - return err - } + } else if err := genDoc.ConsensusParams.Validate(); err != nil { + return err } for i, v := range genDoc.Validators { diff --git a/types/validator_set.go b/types/validator_set.go index 2078e7a95..33636d092 100644 --- a/types/validator_set.go +++ b/types/validator_set.go @@ -121,7 +121,7 @@ func (vals *ValidatorSet) RescalePriorities(diffMax int64) { ratio := (diff + diffMax - 1) / diffMax if diff > diffMax { for _, val := range vals.Validators { - val.ProposerPriority = val.ProposerPriority / ratio + val.ProposerPriority /= ratio } } } @@ -525,7 +525,7 @@ func (vals *ValidatorSet) applyRemovals(deletes []*Validator) { // The 'allowDeletes' flag is set to false by NewValidatorSet() and to true by UpdateWithChangeSet(). func (vals *ValidatorSet) updateWithChangeSet(changes []*Validator, allowDeletes bool) error { - if len(changes) <= 0 { + if len(changes) == 0 { return nil } From 8025d402e273564d6659ae6153264952131a2322 Mon Sep 17 00:00:00 2001 From: Marko Date: Wed, 31 Jul 2019 11:34:17 +0200 Subject: [PATCH 23/45] tm-cmn to tm-db (#3850) * tm-cmn to tm-db * go.mod changes * go.mod changes * more go.mod * fix tm-db * ci fix, pending change --- CHANGELOG_PENDING.md | 5 +++-- abci/example/kvstore/kvstore.go | 2 +- abci/example/kvstore/persistent_kvstore.go | 2 +- blockchain/v0/reactor_test.go | 2 +- blockchain/v1/reactor_test.go | 2 +- consensus/common_test.go | 2 +- consensus/mempool_test.go | 2 +- consensus/reactor_test.go | 2 +- consensus/replay.go | 2 +- consensus/replay_file.go | 2 +- consensus/replay_test.go | 2 +- consensus/wal_generator.go | 2 +- evidence/pool.go | 2 +- evidence/pool_test.go | 2 +- evidence/reactor_test.go | 2 +- evidence/store.go | 2 +- evidence/store_test.go | 2 +- go.mod | 3 +-- go.sum | 5 ++--- lite/dbprovider.go | 2 +- lite/dynamic_verifier_test.go | 2 +- lite/provider_test.go | 2 +- lite/proxy/verifier.go | 2 +- node/node.go | 2 +- node/node_test.go | 2 +- p2p/trust/store.go | 2 +- p2p/trust/store_test.go | 2 +- rpc/core/pipe.go | 2 +- state/execution.go | 2 +- state/export_test.go | 2 +- state/helpers_test.go | 2 +- state/state_test.go | 2 +- state/store.go | 2 +- state/store_test.go | 2 +- state/tx_filter_test.go | 2 +- state/txindex/indexer_service_test.go | 2 +- state/txindex/kv/kv.go | 2 +- state/txindex/kv/kv_test.go | 2 +- state/validation.go | 2 +- store/store.go | 2 +- store/store_test.go | 4 ++-- 41 files changed, 45 insertions(+), 46 deletions(-) diff --git a/CHANGELOG_PENDING.md b/CHANGELOG_PENDING.md index 9d65efbe5..8d72dedb9 100644 --- a/CHANGELOG_PENDING.md +++ b/CHANGELOG_PENDING.md @@ -14,9 +14,10 @@ program](https://hackerone.com/tendermint). - Apps - Go API - - [libs] \#3811 Remove `db` from libs in favor of `https://github.com/tendermint/tm-cmn` + - [libs] \#3811 Remove `db` from libs in favor of `https://github.com/tendermint/tm-db` ### FEATURES: + - [node] Allow replacing existing p2p.Reactor(s) using [`CustomReactors` option](https://godoc.org/github.com/tendermint/tendermint/node#CustomReactors). Warning: beware of accidental name clashes. Here is the list of existing @@ -34,5 +35,5 @@ program](https://hackerone.com/tendermint). ### BUG FIXES: -- [p2p] [\#3644](https://github.com/tendermint/tendermint/pull/3644) Fix error logging for connection stop (@defunctzombie) +- [p2p][\#3644](https://github.com/tendermint/tendermint/pull/3644) Fix error logging for connection stop (@defunctzombie) - [rpc] \#3813 Return err if page is incorrect (less than 0 or greater than total pages) diff --git a/abci/example/kvstore/kvstore.go b/abci/example/kvstore/kvstore.go index feb81b35c..6eb4a1247 100644 --- a/abci/example/kvstore/kvstore.go +++ b/abci/example/kvstore/kvstore.go @@ -10,7 +10,7 @@ import ( "github.com/tendermint/tendermint/abci/types" cmn "github.com/tendermint/tendermint/libs/common" "github.com/tendermint/tendermint/version" - dbm "github.com/tendermint/tm-cmn/db" + dbm "github.com/tendermint/tm-db" ) var ( diff --git a/abci/example/kvstore/persistent_kvstore.go b/abci/example/kvstore/persistent_kvstore.go index 4f84cd3e9..eb2514a69 100644 --- a/abci/example/kvstore/persistent_kvstore.go +++ b/abci/example/kvstore/persistent_kvstore.go @@ -12,7 +12,7 @@ import ( "github.com/tendermint/tendermint/crypto/ed25519" "github.com/tendermint/tendermint/libs/log" tmtypes "github.com/tendermint/tendermint/types" - dbm "github.com/tendermint/tm-cmn/db" + dbm "github.com/tendermint/tm-db" ) const ( diff --git a/blockchain/v0/reactor_test.go b/blockchain/v0/reactor_test.go index 08ec66cda..c1c33593c 100644 --- a/blockchain/v0/reactor_test.go +++ b/blockchain/v0/reactor_test.go @@ -20,7 +20,7 @@ import ( sm "github.com/tendermint/tendermint/state" "github.com/tendermint/tendermint/types" tmtime "github.com/tendermint/tendermint/types/time" - dbm "github.com/tendermint/tm-cmn/db" + dbm "github.com/tendermint/tm-db" ) var config *cfg.Config diff --git a/blockchain/v1/reactor_test.go b/blockchain/v1/reactor_test.go index b5965a2af..1e334c700 100644 --- a/blockchain/v1/reactor_test.go +++ b/blockchain/v1/reactor_test.go @@ -20,7 +20,7 @@ import ( "github.com/tendermint/tendermint/store" "github.com/tendermint/tendermint/types" tmtime "github.com/tendermint/tendermint/types/time" - dbm "github.com/tendermint/tm-cmn/db" + dbm "github.com/tendermint/tm-db" ) var config *cfg.Config diff --git a/consensus/common_test.go b/consensus/common_test.go index 21eb9f532..61d29d849 100644 --- a/consensus/common_test.go +++ b/consensus/common_test.go @@ -32,7 +32,7 @@ import ( "github.com/tendermint/tendermint/store" "github.com/tendermint/tendermint/types" tmtime "github.com/tendermint/tendermint/types/time" - dbm "github.com/tendermint/tm-cmn/db" + dbm "github.com/tendermint/tm-db" ) const ( diff --git a/consensus/mempool_test.go b/consensus/mempool_test.go index f4df1aca1..c1d4f69a7 100644 --- a/consensus/mempool_test.go +++ b/consensus/mempool_test.go @@ -14,7 +14,7 @@ import ( mempl "github.com/tendermint/tendermint/mempool" sm "github.com/tendermint/tendermint/state" "github.com/tendermint/tendermint/types" - dbm "github.com/tendermint/tm-cmn/db" + dbm "github.com/tendermint/tm-db" ) // for testing diff --git a/consensus/reactor_test.go b/consensus/reactor_test.go index 6697efdb8..aa205487f 100644 --- a/consensus/reactor_test.go +++ b/consensus/reactor_test.go @@ -25,7 +25,7 @@ import ( sm "github.com/tendermint/tendermint/state" "github.com/tendermint/tendermint/store" "github.com/tendermint/tendermint/types" - dbm "github.com/tendermint/tm-cmn/db" + dbm "github.com/tendermint/tm-db" ) //---------------------------------------------- diff --git a/consensus/replay.go b/consensus/replay.go index 797593585..433c19407 100644 --- a/consensus/replay.go +++ b/consensus/replay.go @@ -13,7 +13,7 @@ import ( abci "github.com/tendermint/tendermint/abci/types" //auto "github.com/tendermint/tendermint/libs/autofile" - dbm "github.com/tendermint/tm-cmn/db" + dbm "github.com/tendermint/tm-db" "github.com/tendermint/tendermint/libs/log" "github.com/tendermint/tendermint/mock" diff --git a/consensus/replay_file.go b/consensus/replay_file.go index 00a18c218..2c0f8a327 100644 --- a/consensus/replay_file.go +++ b/consensus/replay_file.go @@ -10,7 +10,7 @@ import ( "strings" "github.com/pkg/errors" - dbm "github.com/tendermint/tm-cmn/db" + dbm "github.com/tendermint/tm-db" cfg "github.com/tendermint/tendermint/config" cmn "github.com/tendermint/tendermint/libs/common" diff --git a/consensus/replay_test.go b/consensus/replay_test.go index c3ded97cb..20ecb64d9 100644 --- a/consensus/replay_test.go +++ b/consensus/replay_test.go @@ -29,7 +29,7 @@ import ( sm "github.com/tendermint/tendermint/state" "github.com/tendermint/tendermint/types" "github.com/tendermint/tendermint/version" - dbm "github.com/tendermint/tm-cmn/db" + dbm "github.com/tendermint/tm-db" ) func TestMain(m *testing.M) { diff --git a/consensus/wal_generator.go b/consensus/wal_generator.go index 3f0608262..8b5bbc2f0 100644 --- a/consensus/wal_generator.go +++ b/consensus/wal_generator.go @@ -21,7 +21,7 @@ import ( sm "github.com/tendermint/tendermint/state" "github.com/tendermint/tendermint/store" "github.com/tendermint/tendermint/types" - "github.com/tendermint/tm-cmn/db" + db "github.com/tendermint/tm-db" ) // WALGenerateNBlocks generates a consensus WAL. It does this by spinning up a diff --git a/evidence/pool.go b/evidence/pool.go index c3603730b..66b35ef98 100644 --- a/evidence/pool.go +++ b/evidence/pool.go @@ -6,7 +6,7 @@ import ( clist "github.com/tendermint/tendermint/libs/clist" "github.com/tendermint/tendermint/libs/log" - dbm "github.com/tendermint/tm-cmn/db" + dbm "github.com/tendermint/tm-db" sm "github.com/tendermint/tendermint/state" "github.com/tendermint/tendermint/types" diff --git a/evidence/pool_test.go b/evidence/pool_test.go index 65f970303..0e35ea29d 100644 --- a/evidence/pool_test.go +++ b/evidence/pool_test.go @@ -10,7 +10,7 @@ import ( sm "github.com/tendermint/tendermint/state" "github.com/tendermint/tendermint/types" tmtime "github.com/tendermint/tendermint/types/time" - dbm "github.com/tendermint/tm-cmn/db" + dbm "github.com/tendermint/tm-db" ) func TestMain(m *testing.M) { diff --git a/evidence/reactor_test.go b/evidence/reactor_test.go index e9c05b4d5..9603e6680 100644 --- a/evidence/reactor_test.go +++ b/evidence/reactor_test.go @@ -14,7 +14,7 @@ import ( "github.com/tendermint/tendermint/libs/log" "github.com/tendermint/tendermint/p2p" "github.com/tendermint/tendermint/types" - dbm "github.com/tendermint/tm-cmn/db" + dbm "github.com/tendermint/tm-db" ) // evidenceLogger is a TestingLogger which uses a different diff --git a/evidence/store.go b/evidence/store.go index a809f1474..29054abe3 100644 --- a/evidence/store.go +++ b/evidence/store.go @@ -4,7 +4,7 @@ import ( "fmt" "github.com/tendermint/tendermint/types" - dbm "github.com/tendermint/tm-cmn/db" + dbm "github.com/tendermint/tm-db" ) /* diff --git a/evidence/store_test.go b/evidence/store_test.go index a4d3dc4b9..e3603ef5a 100644 --- a/evidence/store_test.go +++ b/evidence/store_test.go @@ -5,7 +5,7 @@ import ( "github.com/stretchr/testify/assert" "github.com/tendermint/tendermint/types" - dbm "github.com/tendermint/tm-cmn/db" + dbm "github.com/tendermint/tm-db" ) //------------------------------------------- diff --git a/go.mod b/go.mod index 617883cb8..09eb5b581 100644 --- a/go.mod +++ b/go.mod @@ -38,9 +38,8 @@ require ( github.com/spf13/viper v1.0.0 github.com/stretchr/testify v1.3.0 github.com/tendermint/go-amino v0.14.1 - github.com/tendermint/tm-cmn v0.0.0-20190716080004-dfcde30d5acb + github.com/tendermint/tm-db v0.0.0-20190731085305-94017c88bf1d golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2 golang.org/x/net v0.0.0-20190628185345-da137c7871d7 - google.golang.org/genproto v0.0.0-20181029155118-b69ba1387ce2 // indirect google.golang.org/grpc v1.22.0 ) diff --git a/go.sum b/go.sum index 9766e4f70..e7a7e6566 100644 --- a/go.sum +++ b/go.sum @@ -84,7 +84,6 @@ github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZb github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4= github.com/prometheus/client_golang v0.9.1 h1:K47Rk0v/fkEfwfQet2KWhscE0cJzjgCCDBG2KHZoVno= github.com/prometheus/client_golang v0.9.1/go.mod h1:7SWBe2y4D6OKWSNQJUaRYU/AaXPKyh/dDVn+NZz0KFw= -github.com/prometheus/client_golang v1.0.0 h1:vrDKnkGzuGvhNAL56c7DBz29ZL+KxnoR0x7enabFceM= github.com/prometheus/client_model v0.0.0-20180712105110-5c3871d89910 h1:idejC8f05m9MGOsuEi1ATq9shN03HrxNkD/luQvxCv8= github.com/prometheus/client_model v0.0.0-20180712105110-5c3871d89910/go.mod h1:MbSGuTsp3dbXC40dX6PRTWyKYBIrTGTE9sqQNg2J8bo= github.com/prometheus/common v0.0.0-20181020173914-7e9e6cabbd39 h1:Cto4X6SVMWRPBkJ/3YHn1iDGDGc/Z+sW+AEMKHMVvN4= @@ -116,8 +115,8 @@ github.com/syndtr/goleveldb v1.0.1-0.20190318030020-c3a204f8e965 h1:1oFLiOyVl+W7 github.com/syndtr/goleveldb v1.0.1-0.20190318030020-c3a204f8e965/go.mod h1:9OrXJhf154huy1nPWmuSrkgjPUtUNhA+Zmy+6AESzuA= github.com/tendermint/go-amino v0.14.1 h1:o2WudxNfdLNBwMyl2dqOJxiro5rfrEaU0Ugs6offJMk= github.com/tendermint/go-amino v0.14.1/go.mod h1:i/UKE5Uocn+argJJBb12qTZsCDBcAYMbR92AaJVmKso= -github.com/tendermint/tm-cmn v0.0.0-20190716080004-dfcde30d5acb h1:t/HdvqJc9e1iJDl+hf8wQKfOo40aen+Rkqh4AwEaNsI= -github.com/tendermint/tm-cmn v0.0.0-20190716080004-dfcde30d5acb/go.mod h1:SLI3Mc+gRrorRsAXJArnHz4xmAdJT8O7Ns0NL4HslXE= +github.com/tendermint/tm-db v0.0.0-20190731085305-94017c88bf1d h1:yCHL2COLGLNfb4sA9AlzIHpapb8UATvAQyJulS6Eg6Q= +github.com/tendermint/tm-db v0.0.0-20190731085305-94017c88bf1d/go.mod h1:0cPKWu2Mou3IlxecH+MEUSYc1Ch537alLe6CpFrKzgw= go.etcd.io/bbolt v1.3.3 h1:MUGmc65QhB3pIlaQ5bB4LwqSj6GIonVJXpZiaKNyaKk= go.etcd.io/bbolt v1.3.3/go.mod h1:IbVyRI1SCnLcuJnV2u8VeU0CEYM7e686BmAb1XKL+uU= golang.org/x/crypto v0.0.0-20170930174604-9419663f5a44/go.mod h1:6SG95UA2DQfeDnfUPMdvaQW0Q7yPrPDi9nlGo2tz2b4= diff --git a/lite/dbprovider.go b/lite/dbprovider.go index 79f34610c..bbde7ef8c 100644 --- a/lite/dbprovider.go +++ b/lite/dbprovider.go @@ -10,7 +10,7 @@ import ( log "github.com/tendermint/tendermint/libs/log" lerr "github.com/tendermint/tendermint/lite/errors" "github.com/tendermint/tendermint/types" - dbm "github.com/tendermint/tm-cmn/db" + dbm "github.com/tendermint/tm-db" ) var _ PersistentProvider = (*DBProvider)(nil) diff --git a/lite/dynamic_verifier_test.go b/lite/dynamic_verifier_test.go index ab8f94413..c95fee9ec 100644 --- a/lite/dynamic_verifier_test.go +++ b/lite/dynamic_verifier_test.go @@ -10,7 +10,7 @@ import ( log "github.com/tendermint/tendermint/libs/log" "github.com/tendermint/tendermint/types" - dbm "github.com/tendermint/tm-cmn/db" + dbm "github.com/tendermint/tm-db" ) func TestInquirerValidPath(t *testing.T) { diff --git a/lite/provider_test.go b/lite/provider_test.go index 63ae3ad38..98fff8cb4 100644 --- a/lite/provider_test.go +++ b/lite/provider_test.go @@ -10,7 +10,7 @@ import ( log "github.com/tendermint/tendermint/libs/log" lerr "github.com/tendermint/tendermint/lite/errors" "github.com/tendermint/tendermint/types" - dbm "github.com/tendermint/tm-cmn/db" + dbm "github.com/tendermint/tm-db" ) // missingProvider doesn't store anything, always a miss. diff --git a/lite/proxy/verifier.go b/lite/proxy/verifier.go index ac76d42aa..2119a7aee 100644 --- a/lite/proxy/verifier.go +++ b/lite/proxy/verifier.go @@ -5,7 +5,7 @@ import ( log "github.com/tendermint/tendermint/libs/log" "github.com/tendermint/tendermint/lite" lclient "github.com/tendermint/tendermint/lite/client" - dbm "github.com/tendermint/tm-cmn/db" + dbm "github.com/tendermint/tm-db" ) func NewVerifier(chainID, rootDir string, client lclient.SignStatusClient, logger log.Logger, cacheSize int) (*lite.DynamicVerifier, error) { diff --git a/node/node.go b/node/node.go index 9060cf04b..2884787dc 100644 --- a/node/node.go +++ b/node/node.go @@ -45,7 +45,7 @@ import ( "github.com/tendermint/tendermint/types" tmtime "github.com/tendermint/tendermint/types/time" "github.com/tendermint/tendermint/version" - dbm "github.com/tendermint/tm-cmn/db" + dbm "github.com/tendermint/tm-db" ) //------------------------------------------------------------------------------ diff --git a/node/node_test.go b/node/node_test.go index 669209f1a..f031c13a9 100644 --- a/node/node_test.go +++ b/node/node_test.go @@ -27,7 +27,7 @@ import ( "github.com/tendermint/tendermint/types" tmtime "github.com/tendermint/tendermint/types/time" "github.com/tendermint/tendermint/version" - dbm "github.com/tendermint/tm-cmn/db" + dbm "github.com/tendermint/tm-db" ) func TestNodeStartStop(t *testing.T) { diff --git a/p2p/trust/store.go b/p2p/trust/store.go index 2b12f6957..b0324a1a7 100644 --- a/p2p/trust/store.go +++ b/p2p/trust/store.go @@ -10,7 +10,7 @@ import ( "time" cmn "github.com/tendermint/tendermint/libs/common" - dbm "github.com/tendermint/tm-cmn/db" + dbm "github.com/tendermint/tm-db" ) const defaultStorePeriodicSaveInterval = 1 * time.Minute diff --git a/p2p/trust/store_test.go b/p2p/trust/store_test.go index 0efb6a7cf..d6498d823 100644 --- a/p2p/trust/store_test.go +++ b/p2p/trust/store_test.go @@ -11,7 +11,7 @@ import ( "github.com/stretchr/testify/assert" "github.com/tendermint/tendermint/libs/log" - dbm "github.com/tendermint/tm-cmn/db" + dbm "github.com/tendermint/tm-db" ) func TestTrustMetricStoreSaveLoad(t *testing.T) { diff --git a/rpc/core/pipe.go b/rpc/core/pipe.go index 9581b89d7..19abf62f6 100644 --- a/rpc/core/pipe.go +++ b/rpc/core/pipe.go @@ -14,7 +14,7 @@ import ( sm "github.com/tendermint/tendermint/state" "github.com/tendermint/tendermint/state/txindex" "github.com/tendermint/tendermint/types" - dbm "github.com/tendermint/tm-cmn/db" + dbm "github.com/tendermint/tm-db" ) const ( diff --git a/state/execution.go b/state/execution.go index 45affacf6..600d339b5 100644 --- a/state/execution.go +++ b/state/execution.go @@ -10,7 +10,7 @@ import ( mempl "github.com/tendermint/tendermint/mempool" "github.com/tendermint/tendermint/proxy" "github.com/tendermint/tendermint/types" - dbm "github.com/tendermint/tm-cmn/db" + dbm "github.com/tendermint/tm-db" ) //----------------------------------------------------------------------------- diff --git a/state/export_test.go b/state/export_test.go index a1428c1b3..823eb4251 100644 --- a/state/export_test.go +++ b/state/export_test.go @@ -3,7 +3,7 @@ package state import ( abci "github.com/tendermint/tendermint/abci/types" "github.com/tendermint/tendermint/types" - dbm "github.com/tendermint/tm-cmn/db" + dbm "github.com/tendermint/tm-db" ) // diff --git a/state/helpers_test.go b/state/helpers_test.go index 7e26f039b..d6589c574 100644 --- a/state/helpers_test.go +++ b/state/helpers_test.go @@ -11,7 +11,7 @@ import ( sm "github.com/tendermint/tendermint/state" "github.com/tendermint/tendermint/types" tmtime "github.com/tendermint/tendermint/types/time" - dbm "github.com/tendermint/tm-cmn/db" + dbm "github.com/tendermint/tm-db" ) type paramsChangeTestCase struct { diff --git a/state/state_test.go b/state/state_test.go index ac3b4db9f..062e62bb5 100644 --- a/state/state_test.go +++ b/state/state_test.go @@ -14,7 +14,7 @@ import ( "github.com/tendermint/tendermint/crypto/ed25519" cmn "github.com/tendermint/tendermint/libs/common" sm "github.com/tendermint/tendermint/state" - dbm "github.com/tendermint/tm-cmn/db" + dbm "github.com/tendermint/tm-db" cfg "github.com/tendermint/tendermint/config" "github.com/tendermint/tendermint/types" diff --git a/state/store.go b/state/store.go index 21494212c..4f47ace5f 100644 --- a/state/store.go +++ b/state/store.go @@ -6,7 +6,7 @@ import ( abci "github.com/tendermint/tendermint/abci/types" cmn "github.com/tendermint/tendermint/libs/common" "github.com/tendermint/tendermint/types" - dbm "github.com/tendermint/tm-cmn/db" + dbm "github.com/tendermint/tm-db" ) const ( diff --git a/state/store_test.go b/state/store_test.go index 696252518..4549e8f89 100644 --- a/state/store_test.go +++ b/state/store_test.go @@ -11,7 +11,7 @@ import ( cfg "github.com/tendermint/tendermint/config" sm "github.com/tendermint/tendermint/state" "github.com/tendermint/tendermint/types" - dbm "github.com/tendermint/tm-cmn/db" + dbm "github.com/tendermint/tm-db" ) func TestStoreLoadValidators(t *testing.T) { diff --git a/state/tx_filter_test.go b/state/tx_filter_test.go index c7b9fb536..21c4daf14 100644 --- a/state/tx_filter_test.go +++ b/state/tx_filter_test.go @@ -10,7 +10,7 @@ import ( cmn "github.com/tendermint/tendermint/libs/common" sm "github.com/tendermint/tendermint/state" "github.com/tendermint/tendermint/types" - dbm "github.com/tendermint/tm-cmn/db" + dbm "github.com/tendermint/tm-db" ) func TestTxFilter(t *testing.T) { diff --git a/state/txindex/indexer_service_test.go b/state/txindex/indexer_service_test.go index 9c9ad5476..277304c45 100644 --- a/state/txindex/indexer_service_test.go +++ b/state/txindex/indexer_service_test.go @@ -12,7 +12,7 @@ import ( "github.com/tendermint/tendermint/state/txindex" "github.com/tendermint/tendermint/state/txindex/kv" "github.com/tendermint/tendermint/types" - "github.com/tendermint/tm-cmn/db" + db "github.com/tendermint/tm-db" ) func TestIndexerServiceIndexesBlocks(t *testing.T) { diff --git a/state/txindex/kv/kv.go b/state/txindex/kv/kv.go index 16c7b5957..4551aa9c9 100644 --- a/state/txindex/kv/kv.go +++ b/state/txindex/kv/kv.go @@ -15,7 +15,7 @@ import ( "github.com/tendermint/tendermint/libs/pubsub/query" "github.com/tendermint/tendermint/state/txindex" "github.com/tendermint/tendermint/types" - dbm "github.com/tendermint/tm-cmn/db" + dbm "github.com/tendermint/tm-db" ) const ( diff --git a/state/txindex/kv/kv_test.go b/state/txindex/kv/kv_test.go index cec84de7f..1175ae2f0 100644 --- a/state/txindex/kv/kv_test.go +++ b/state/txindex/kv/kv_test.go @@ -10,7 +10,7 @@ import ( "github.com/stretchr/testify/require" abci "github.com/tendermint/tendermint/abci/types" cmn "github.com/tendermint/tendermint/libs/common" - db "github.com/tendermint/tm-cmn/db" + db "github.com/tendermint/tm-db" "github.com/tendermint/tendermint/libs/pubsub/query" "github.com/tendermint/tendermint/state/txindex" diff --git a/state/validation.go b/state/validation.go index 27b90806d..f2218f15c 100644 --- a/state/validation.go +++ b/state/validation.go @@ -7,7 +7,7 @@ import ( "github.com/tendermint/tendermint/crypto" "github.com/tendermint/tendermint/types" - dbm "github.com/tendermint/tm-cmn/db" + dbm "github.com/tendermint/tm-db" ) //----------------------------------------------------- diff --git a/store/store.go b/store/store.go index 76dcdff8d..73c9ad010 100644 --- a/store/store.go +++ b/store/store.go @@ -5,7 +5,7 @@ import ( "sync" cmn "github.com/tendermint/tendermint/libs/common" - dbm "github.com/tendermint/tm-cmn/db" + dbm "github.com/tendermint/tm-db" "github.com/tendermint/tendermint/types" ) diff --git a/store/store_test.go b/store/store_test.go index ebd6e6900..2d83aecc1 100644 --- a/store/store_test.go +++ b/store/store_test.go @@ -11,8 +11,8 @@ import ( "github.com/stretchr/testify/assert" "github.com/stretchr/testify/require" - "github.com/tendermint/tm-cmn/db" - dbm "github.com/tendermint/tm-cmn/db" + db "github.com/tendermint/tm-db" + dbm "github.com/tendermint/tm-db" cfg "github.com/tendermint/tendermint/config" cmn "github.com/tendermint/tendermint/libs/common" From d56fb6ed229e931fdf20a384b98f07af58211fc7 Mon Sep 17 00:00:00 2001 From: Marko Date: Wed, 31 Jul 2019 16:17:09 +0200 Subject: [PATCH 24/45] version tmdb (#3854) --- go.mod | 2 +- go.sum | 2 ++ 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/go.mod b/go.mod index 09eb5b581..92a732a89 100644 --- a/go.mod +++ b/go.mod @@ -38,7 +38,7 @@ require ( github.com/spf13/viper v1.0.0 github.com/stretchr/testify v1.3.0 github.com/tendermint/go-amino v0.14.1 - github.com/tendermint/tm-db v0.0.0-20190731085305-94017c88bf1d + github.com/tendermint/tm-db v0.1.1 golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2 golang.org/x/net v0.0.0-20190628185345-da137c7871d7 google.golang.org/grpc v1.22.0 diff --git a/go.sum b/go.sum index e7a7e6566..6d748bbf5 100644 --- a/go.sum +++ b/go.sum @@ -117,6 +117,8 @@ github.com/tendermint/go-amino v0.14.1 h1:o2WudxNfdLNBwMyl2dqOJxiro5rfrEaU0Ugs6o github.com/tendermint/go-amino v0.14.1/go.mod h1:i/UKE5Uocn+argJJBb12qTZsCDBcAYMbR92AaJVmKso= github.com/tendermint/tm-db v0.0.0-20190731085305-94017c88bf1d h1:yCHL2COLGLNfb4sA9AlzIHpapb8UATvAQyJulS6Eg6Q= github.com/tendermint/tm-db v0.0.0-20190731085305-94017c88bf1d/go.mod h1:0cPKWu2Mou3IlxecH+MEUSYc1Ch537alLe6CpFrKzgw= +github.com/tendermint/tm-db v0.1.1 h1:G3Xezy3sOk9+ekhjZ/kjArYIs1SmwV+1OUgNkj7RgV0= +github.com/tendermint/tm-db v0.1.1/go.mod h1:0cPKWu2Mou3IlxecH+MEUSYc1Ch537alLe6CpFrKzgw= go.etcd.io/bbolt v1.3.3 h1:MUGmc65QhB3pIlaQ5bB4LwqSj6GIonVJXpZiaKNyaKk= go.etcd.io/bbolt v1.3.3/go.mod h1:IbVyRI1SCnLcuJnV2u8VeU0CEYM7e686BmAb1XKL+uU= golang.org/x/crypto v0.0.0-20170930174604-9419663f5a44/go.mod h1:6SG95UA2DQfeDnfUPMdvaQW0Q7yPrPDi9nlGo2tz2b4= From aacc71dc2956c5f8bc5b3bdced454691fa489266 Mon Sep 17 00:00:00 2001 From: Alexander Bezobchuk Date: Wed, 31 Jul 2019 08:01:55 -0700 Subject: [PATCH 25/45] txindexer: Refactor Tx Search Aggregation (#3851) - Replace the previous intersect call, which was called at each query condition, with a map intersection. - Replace fmt.Sprintf with string() closes: #3076 Benchmarks ``` Old goos: darwin goarch: amd64 pkg: github.com/tendermint/tendermint/state/txindex/kv BenchmarkTxSearch-4 200 103641206 ns/op 7998416 B/op 71171 allocs/op PASS ok github.com/tendermint/tendermint/state/txindex/kv 26.019s New goos: darwin goarch: amd64 pkg: github.com/tendermint/tendermint/state/txindex/kv BenchmarkTxSearch-4 1000 38615024 ns/op 13515226 B/op 166460 allocs/op PASS ok github.com/tendermint/tendermint/state/txindex/kv 53.618s ``` ~62% performance improvement Commits: * Refactor tx search * Add pending changelog entry * Add tx search benchmarking * remove intermediate hashes list also reset timer in BenchmarkTxSearch and fix other benchmark * fix import * Add test cases * Fix searching * Replace fmt.Sprintf with string * Update state/txindex/kv/kv.go Co-Authored-By: Anton Kaliaev * Rename params * Cleanup * Check error in benchmarks --- CHANGELOG_PENDING.md | 1 + state/txindex/kv/kv.go | 143 +++++++++++++++++++++--------- state/txindex/kv/kv_bench_test.go | 72 +++++++++++++++ state/txindex/kv/kv_test.go | 12 ++- 4 files changed, 185 insertions(+), 43 deletions(-) create mode 100644 state/txindex/kv/kv_bench_test.go diff --git a/CHANGELOG_PENDING.md b/CHANGELOG_PENDING.md index 8d72dedb9..6a57dd9d9 100644 --- a/CHANGELOG_PENDING.md +++ b/CHANGELOG_PENDING.md @@ -32,6 +32,7 @@ program](https://hackerone.com/tendermint). - [p2p] \#3664 p2p/conn: reuse buffer when write/read from secret connection - [mempool] \#3826 Make `max_msg_bytes` configurable - [blockchain] \#3561 Add early version of the new blockchain reactor, which is supposed to be more modular and testable compared to the old version. To try it, you'll have to change `version` in the config file, [here](https://github.com/tendermint/tendermint/blob/master/config/toml.go#L303) NOTE: It's not ready for a production yet. For further information, see [ADR-40](https://github.com/tendermint/tendermint/blob/master/docs/architecture/adr-040-blockchain-reactor-refactor.md) & [ADR-43](https://github.com/tendermint/tendermint/blob/master/docs/architecture/adr-043-blockchain-riri-org.md) +- [rpc] \#3076 Improve transaction search performance ### BUG FIXES: diff --git a/state/txindex/kv/kv.go b/state/txindex/kv/kv.go index 4551aa9c9..89d8868a0 100644 --- a/state/txindex/kv/kv.go +++ b/state/txindex/kv/kv.go @@ -11,11 +11,12 @@ import ( "github.com/pkg/errors" + dbm "github.com/tendermint/tm-db" + cmn "github.com/tendermint/tendermint/libs/common" "github.com/tendermint/tendermint/libs/pubsub/query" "github.com/tendermint/tendermint/state/txindex" "github.com/tendermint/tendermint/types" - dbm "github.com/tendermint/tm-db" ) const ( @@ -163,8 +164,8 @@ func (txi *TxIndex) indexEvents(result *types.TxResult, hash []byte, store dbm.S // both lower and upper bounds, so we are not performing a full scan. Results // from querying indexes are then intersected and returned to the caller. func (txi *TxIndex) Search(q *query.Query) ([]*types.TxResult, error) { - var hashes [][]byte var hashesInitialized bool + filteredHashes := make(map[string][]byte) // get a list of conditions (like "tx.height > 5") conditions := q.Conditions() @@ -193,10 +194,16 @@ func (txi *TxIndex) Search(q *query.Query) ([]*types.TxResult, error) { for _, r := range ranges { if !hashesInitialized { - hashes = txi.matchRange(r, startKey(r.key)) + filteredHashes = txi.matchRange(r, startKey(r.key), filteredHashes, true) hashesInitialized = true + + // Ignore any remaining conditions if the first condition resulted + // in no matches (assuming implicit AND operand). + if len(filteredHashes) == 0 { + break + } } else { - hashes = intersect(hashes, txi.matchRange(r, startKey(r.key))) + filteredHashes = txi.matchRange(r, startKey(r.key), filteredHashes, false) } } } @@ -211,21 +218,26 @@ func (txi *TxIndex) Search(q *query.Query) ([]*types.TxResult, error) { } if !hashesInitialized { - hashes = txi.match(c, startKeyForCondition(c, height)) + filteredHashes = txi.match(c, startKeyForCondition(c, height), filteredHashes, true) hashesInitialized = true + + // Ignore any remaining conditions if the first condition resulted + // in no matches (assuming implicit AND operand). + if len(filteredHashes) == 0 { + break + } } else { - hashes = intersect(hashes, txi.match(c, startKeyForCondition(c, height))) + filteredHashes = txi.match(c, startKeyForCondition(c, height), filteredHashes, false) } } - results := make([]*types.TxResult, len(hashes)) - i := 0 - for _, h := range hashes { - results[i], err = txi.Get(h) + results := make([]*types.TxResult, 0, len(filteredHashes)) + for _, h := range filteredHashes { + res, err := txi.Get(h) if err != nil { return nil, errors.Wrapf(err, "failed to get Tx{%X}", h) } - i++ + results = append(results, res) } // sort by height & index by default @@ -353,63 +365,115 @@ func isRangeOperation(op query.Operator) bool { } } -func (txi *TxIndex) match(c query.Condition, startKeyBz []byte) (hashes [][]byte) { +// match returns all matching txs by hash that meet a given condition and start +// key. An already filtered result (filteredHashes) is provided such that any +// non-intersecting matches are removed. +// +// NOTE: filteredHashes may be empty if no previous condition has matched. +func (txi *TxIndex) match(c query.Condition, startKeyBz []byte, filteredHashes map[string][]byte, firstRun bool) map[string][]byte { + // A previous match was attempted but resulted in no matches, so we return + // no matches (assuming AND operand). + if !firstRun && len(filteredHashes) == 0 { + return filteredHashes + } + + tmpHashes := make(map[string][]byte) + if c.Op == query.OpEqual { it := dbm.IteratePrefix(txi.store, startKeyBz) defer it.Close() + for ; it.Valid(); it.Next() { - hashes = append(hashes, it.Value()) + tmpHashes[string(it.Value())] = it.Value() } + } else if c.Op == query.OpContains { // XXX: startKey does not apply here. // For example, if startKey = "account.owner/an/" and search query = "account.owner CONTAINS an" // we can't iterate with prefix "account.owner/an/" because we might miss keys like "account.owner/Ulan/" it := dbm.IteratePrefix(txi.store, startKey(c.Tag)) defer it.Close() + for ; it.Valid(); it.Next() { if !isTagKey(it.Key()) { continue } + if strings.Contains(extractValueFromKey(it.Key()), c.Operand.(string)) { - hashes = append(hashes, it.Value()) + tmpHashes[string(it.Value())] = it.Value() } } } else { panic("other operators should be handled already") } - return + + if len(tmpHashes) == 0 || firstRun { + // Either: + // + // 1. Regardless if a previous match was attempted, which may have had + // results, but no match was found for the current condition, then we + // return no matches (assuming AND operand). + // + // 2. A previous match was not attempted, so we return all results. + return tmpHashes + } + + // Remove/reduce matches in filteredHashes that were not found in this + // match (tmpHashes). + for k := range filteredHashes { + if tmpHashes[k] == nil { + delete(filteredHashes, k) + } + } + + return filteredHashes } -func (txi *TxIndex) matchRange(r queryRange, startKey []byte) (hashes [][]byte) { - // create a map to prevent duplicates - hashesMap := make(map[string][]byte) +// matchRange returns all matching txs by hash that meet a given queryRange and +// start key. An already filtered result (filteredHashes) is provided such that +// any non-intersecting matches are removed. +// +// NOTE: filteredHashes may be empty if no previous condition has matched. +func (txi *TxIndex) matchRange(r queryRange, startKey []byte, filteredHashes map[string][]byte, firstRun bool) map[string][]byte { + // A previous match was attempted but resulted in no matches, so we return + // no matches (assuming AND operand). + if !firstRun && len(filteredHashes) == 0 { + return filteredHashes + } + tmpHashes := make(map[string][]byte) lowerBound := r.lowerBoundValue() upperBound := r.upperBoundValue() it := dbm.IteratePrefix(txi.store, startKey) defer it.Close() + LOOP: for ; it.Valid(); it.Next() { if !isTagKey(it.Key()) { continue } + switch r.AnyBound().(type) { case int64: v, err := strconv.ParseInt(extractValueFromKey(it.Key()), 10, 64) if err != nil { continue LOOP } + include := true if lowerBound != nil && v < lowerBound.(int64) { include = false } + if upperBound != nil && v > upperBound.(int64) { include = false } + if include { - hashesMap[fmt.Sprintf("%X", it.Value())] = it.Value() + tmpHashes[string(it.Value())] = it.Value() } + // XXX: passing time in a ABCI Tags is not yet implemented // case time.Time: // v := strconv.ParseInt(extractValueFromKey(it.Key()), 10, 64) @@ -418,13 +482,27 @@ LOOP: // } } } - hashes = make([][]byte, len(hashesMap)) - i := 0 - for _, h := range hashesMap { - hashes[i] = h - i++ + + if len(tmpHashes) == 0 || firstRun { + // Either: + // + // 1. Regardless if a previous match was attempted, which may have had + // results, but no match was found for the current condition, then we + // return no matches (assuming AND operand). + // + // 2. A previous match was not attempted, so we return all results. + return tmpHashes } - return + + // Remove/reduce matches in filteredHashes that were not found in this + // match (tmpHashes). + for k := range filteredHashes { + if tmpHashes[k] == nil { + delete(filteredHashes, k) + } + } + + return filteredHashes } /////////////////////////////////////////////////////////////////////////////// @@ -471,18 +549,3 @@ func startKey(fields ...interface{}) []byte { } return b.Bytes() } - -/////////////////////////////////////////////////////////////////////////////// -// Utils - -func intersect(as, bs [][]byte) [][]byte { - i := make([][]byte, 0, cmn.MinInt(len(as), len(bs))) - for _, a := range as { - for _, b := range bs { - if bytes.Equal(a, b) { - i = append(i, a) - } - } - } - return i -} diff --git a/state/txindex/kv/kv_bench_test.go b/state/txindex/kv/kv_bench_test.go new file mode 100644 index 000000000..9c3442a01 --- /dev/null +++ b/state/txindex/kv/kv_bench_test.go @@ -0,0 +1,72 @@ +package kv + +import ( + "crypto/rand" + "fmt" + "io/ioutil" + "testing" + + abci "github.com/tendermint/tendermint/abci/types" + cmn "github.com/tendermint/tendermint/libs/common" + "github.com/tendermint/tendermint/libs/pubsub/query" + "github.com/tendermint/tendermint/types" + dbm "github.com/tendermint/tm-db" +) + +func BenchmarkTxSearch(b *testing.B) { + dbDir, err := ioutil.TempDir("", "benchmark_tx_search_test") + if err != nil { + b.Errorf("failed to create temporary directory: %s", err) + } + + db, err := dbm.NewGoLevelDB("benchmark_tx_search_test", dbDir) + if err != nil { + b.Errorf("failed to create database: %s", err) + } + + allowedTags := []string{"transfer.address", "transfer.amount"} + indexer := NewTxIndex(db, IndexTags(allowedTags)) + + for i := 0; i < 35000; i++ { + events := []abci.Event{ + { + Type: "transfer", + Attributes: []cmn.KVPair{ + {Key: []byte("address"), Value: []byte(fmt.Sprintf("address_%d", i%100))}, + {Key: []byte("amount"), Value: []byte("50")}, + }, + }, + } + + txBz := make([]byte, 8) + if _, err := rand.Read(txBz); err != nil { + b.Errorf("failed produce random bytes: %s", err) + } + + txResult := &types.TxResult{ + Height: int64(i), + Index: 0, + Tx: types.Tx(string(txBz)), + Result: abci.ResponseDeliverTx{ + Data: []byte{0}, + Code: abci.CodeTypeOK, + Log: "", + Events: events, + }, + } + + if err := indexer.Index(txResult); err != nil { + b.Errorf("failed to index tx: %s", err) + } + } + + txQuery := query.MustParse("transfer.address = 'address_43' AND transfer.amount = 50") + + b.ResetTimer() + + for i := 0; i < b.N; i++ { + if _, err := indexer.Search(txQuery); err != nil { + b.Errorf("failed to query for txs: %s", err) + } + } +} diff --git a/state/txindex/kv/kv_test.go b/state/txindex/kv/kv_test.go index 1175ae2f0..a0c833e49 100644 --- a/state/txindex/kv/kv_test.go +++ b/state/txindex/kv/kv_test.go @@ -8,10 +8,11 @@ import ( "github.com/stretchr/testify/assert" "github.com/stretchr/testify/require" - abci "github.com/tendermint/tendermint/abci/types" - cmn "github.com/tendermint/tendermint/libs/common" + db "github.com/tendermint/tm-db" + abci "github.com/tendermint/tendermint/abci/types" + cmn "github.com/tendermint/tendermint/libs/common" "github.com/tendermint/tendermint/libs/pubsub/query" "github.com/tendermint/tendermint/state/txindex" "github.com/tendermint/tendermint/types" @@ -89,6 +90,11 @@ func TestTxSearch(t *testing.T) { {"account.number = 1 AND account.owner = 'Ivan'", 1}, // search by exact match (two tags) {"account.number = 1 AND account.owner = 'Vlad'", 0}, + {"account.owner = 'Vlad' AND account.number = 1", 0}, + {"account.number >= 1 AND account.owner = 'Vlad'", 0}, + {"account.owner = 'Vlad' AND account.number >= 1", 0}, + {"account.number <= 0", 0}, + {"account.number <= 0 AND account.owner = 'Ivan'", 0}, // search using a prefix of the stored value {"account.owner = 'Iv'", 0}, // search by range @@ -310,7 +316,7 @@ func benchmarkTxIndex(txsCount int64, b *testing.B) { } defer os.RemoveAll(dir) // nolint: errcheck - store := db.NewDB("tx_index", "leveldb", dir) + store := db.NewDB("tx_index", "goleveldb", dir) indexer := NewTxIndex(store) batch := txindex.NewBatch(txsCount) From 15878dc80ccec03f32086415fbfea4b66164150c Mon Sep 17 00:00:00 2001 From: Marko Baricevic Date: Wed, 31 Jul 2019 17:30:11 +0200 Subject: [PATCH 26/45] release for v0.32.2 --- CHANGELOG.md | 42 ++++++++++++++++++++++++++++++++++++++++-- CHANGELOG_PENDING.md | 20 +------------------- version/version.go | 2 +- 3 files changed, 42 insertions(+), 22 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index cf2879c75..b34025213 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,10 +1,48 @@ # Changelog +## v0.32.2 + +*July 31, 2019* + +Special thanks to external contributors on this release: +@ruseinov, @bluele, @guagualvcha + +Friendly reminder, we have a [bug bounty +program](https://hackerone.com/tendermint). + +### BREAKING CHANGES: + +- Go API + - [libs] [\#3811](https://github.com/tendermint/tendermint/issues/3811) Remove `db` from libs in favor of `https://github.com/tendermint/tm-db` + +### FEATURES: + +- [node] Allow replacing existing p2p.Reactor(s) using [`CustomReactors` + option](https://godoc.org/github.com/tendermint/tendermint/node#CustomReactors). + Warning: beware of accidental name clashes. Here is the list of existing + reactors: MEMPOOL, BLOCKCHAIN, CONSENSUS, EVIDENCE, PEX. + +### IMPROVEMENTS: + +- [p2p] [\#3834](https://github.com/tendermint/tendermint/issues/3834) Do not write 'Couldn't connect to any seeds' error log if there are no seeds in config file +- [abci] [\#3809](https://github.com/tendermint/tendermint/issues/3809) Recover from application panics in `server/socket_server.go` to allow socket cleanup (@ruseinov) +- [rpc] [\#2252](https://github.com/tendermint/tendermint/issues/2252) Add `/broadcast_evidence` endpoint to submit double signing and other types of evidence +- [rpc] [\#3818](https://github.com/tendermint/tendermint/issues/3818) Make `max_body_bytes` and `max_header_bytes` configurable(@bluele) +- [p2p] [\#3664](https://github.com/tendermint/tendermint/issues/3664) p2p/conn: reuse buffer when write/read from secret connection(@guagualvcha) +- [mempool] [\#3826](https://github.com/tendermint/tendermint/issues/3826) Make `max_msg_bytes` configurable(@bluele) +- [blockchain] [\#3561](https://github.com/tendermint/tendermint/issues/3561) Add early version of the new blockchain reactor, which is supposed to be more modular and testable compared to the old version. To try it, you'll have to change `version` in the config file, [here](https://github.com/tendermint/tendermint/blob/master/config/toml.go#L303) NOTE: It's not ready for a production yet. For further information, see [ADR-40](https://github.com/tendermint/tendermint/blob/master/docs/architecture/adr-040-blockchain-reactor-refactor.md) & [ADR-43](https://github.com/tendermint/tendermint/blob/master/docs/architecture/adr-043-blockchain-riri-org.md) +- [rpc] [\#3076](https://github.com/tendermint/tendermint/issues/3076) Improve transaction search performance + +### BUG FIXES: + +- [p2p] [\#3644](https://github.com/tendermint/tendermint/issues/3644) Fix error logging for connection stop (@defunctzombie) +- [rpc] [\#3813](https://github.com/tendermint/tendermint/issues/3813) Return err if page is incorrect (less than 0 or greater than total pages) + ## v0.32.1 *July 15, 2019* -Special thanks to external contributors on this release: +Special thanks to external contributors on this release: @ParthDesai, @climber73, @jim380, @ashleyvega This release contains a minor enhancement to the ABCI and some breaking changes to our libs folder, namely: @@ -26,7 +64,7 @@ program](https://hackerone.com/tendermint). ### FEATURES: -- [node] Add variadic argument to `NewNode` to support functional options, allowing the Node to be more easily customized. +- [node] Add variadic argument to `NewNode` to support functional options, allowing the Node to be more easily customized. - [node][\#3730](https://github.com/tendermint/tendermint/pull/3730) Add `CustomReactors` option to `NewNode` allowing caller to pass custom reactors to run inside Tendermint node (@ParthDesai) - [abci] [\#2127](https://github.com/tendermint/tendermint/issues/2127)RequestCheckTx has a new field, `CheckTxType`, which can take values of `CheckTxType_New` and `CheckTxType_Recheck`, indicating whether this is a new tx being checked for the first time or whether this tx is being rechecked after a block commit. This allows applications to skip certain expensive operations, like signature checking, if they've already been done once. see [docs](https://github.com/tendermint/tendermint/blob/eddb433d7c082efbeaf8974413a36641519ee895/docs/spec/abci/apps.md#mempool-connection) diff --git a/CHANGELOG_PENDING.md b/CHANGELOG_PENDING.md index 6a57dd9d9..64c17b4bd 100644 --- a/CHANGELOG_PENDING.md +++ b/CHANGELOG_PENDING.md @@ -1,4 +1,4 @@ -## v0.32.2 +## v0.32.3 \*\* @@ -14,27 +14,9 @@ program](https://hackerone.com/tendermint). - Apps - Go API - - [libs] \#3811 Remove `db` from libs in favor of `https://github.com/tendermint/tm-db` ### FEATURES: -- [node] Allow replacing existing p2p.Reactor(s) using [`CustomReactors` - option](https://godoc.org/github.com/tendermint/tendermint/node#CustomReactors). - Warning: beware of accidental name clashes. Here is the list of existing - reactors: MEMPOOL, BLOCKCHAIN, CONSENSUS, EVIDENCE, PEX. - ### IMPROVEMENTS: -- [p2p] \#3834 Do not write 'Couldn't connect to any seeds' error log if there are no seeds in config file -- [abci] \#3809 Recover from application panics in `server/socket_server.go` to allow socket cleanup (@ruseinov) -- [rpc] \#2252 Add `/broadcast_evidence` endpoint to submit double signing and other types of evidence -- [rpc] \#3818 Make `max_body_bytes` and `max_header_bytes` configurable -- [p2p] \#3664 p2p/conn: reuse buffer when write/read from secret connection -- [mempool] \#3826 Make `max_msg_bytes` configurable -- [blockchain] \#3561 Add early version of the new blockchain reactor, which is supposed to be more modular and testable compared to the old version. To try it, you'll have to change `version` in the config file, [here](https://github.com/tendermint/tendermint/blob/master/config/toml.go#L303) NOTE: It's not ready for a production yet. For further information, see [ADR-40](https://github.com/tendermint/tendermint/blob/master/docs/architecture/adr-040-blockchain-reactor-refactor.md) & [ADR-43](https://github.com/tendermint/tendermint/blob/master/docs/architecture/adr-043-blockchain-riri-org.md) -- [rpc] \#3076 Improve transaction search performance - ### BUG FIXES: - -- [p2p][\#3644](https://github.com/tendermint/tendermint/pull/3644) Fix error logging for connection stop (@defunctzombie) -- [rpc] \#3813 Return err if page is incorrect (less than 0 or greater than total pages) diff --git a/version/version.go b/version/version.go index 91b0ab410..9fb7c7869 100644 --- a/version/version.go +++ b/version/version.go @@ -20,7 +20,7 @@ const ( // Must be a string because scripts like dist.sh read this file. // XXX: Don't change the name of this variable or you will break // automation :) - TMCoreSemVer = "0.32.1" + TMCoreSemVer = "0.32.2" // ABCISemVer is the semantic version of the ABCI library ABCISemVer = "0.16.1" From 76f3db06b8dbbfe5d6c4d0f4a6131b58ed36869d Mon Sep 17 00:00:00 2001 From: Marko Date: Thu, 1 Aug 2019 18:33:27 +0200 Subject: [PATCH 27/45] Merge PR #3860: Update log v0.32.2 * changelog updates * pr comments --- CHANGELOG.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index b34025213..398250d33 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -17,20 +17,20 @@ program](https://hackerone.com/tendermint). ### FEATURES: -- [node] Allow replacing existing p2p.Reactor(s) using [`CustomReactors` +- [node] [\#3846](https://github.com/tendermint/tendermint/pull/3846) Allow replacing existing p2p.Reactor(s) using [`CustomReactors` option](https://godoc.org/github.com/tendermint/tendermint/node#CustomReactors). Warning: beware of accidental name clashes. Here is the list of existing reactors: MEMPOOL, BLOCKCHAIN, CONSENSUS, EVIDENCE, PEX. +- [p2p] [\#3834](https://github.com/tendermint/tendermint/issues/3834) Do not write 'Couldn't connect to any seeds' error log if there are no seeds in config file +- [rpc] [\#3818](https://github.com/tendermint/tendermint/issues/3818) Make `max_body_bytes` and `max_header_bytes` configurable(@bluele) +- [mempool] [\#3826](https://github.com/tendermint/tendermint/issues/3826) Make `max_msg_bytes` configurable(@bluele) +- [blockchain] [\#3561](https://github.com/tendermint/tendermint/issues/3561) Add early version of the new blockchain reactor, which is supposed to be more modular and testable compared to the old version. To try it, you'll have to change `version` in the config file, [here](https://github.com/tendermint/tendermint/blob/master/config/toml.go#L303) NOTE: It's not ready for a production yet. For further information, see [ADR-40](https://github.com/tendermint/tendermint/blob/master/docs/architecture/adr-040-blockchain-reactor-refactor.md) & [ADR-43](https://github.com/tendermint/tendermint/blob/master/docs/architecture/adr-043-blockchain-riri-org.md) ### IMPROVEMENTS: -- [p2p] [\#3834](https://github.com/tendermint/tendermint/issues/3834) Do not write 'Couldn't connect to any seeds' error log if there are no seeds in config file - [abci] [\#3809](https://github.com/tendermint/tendermint/issues/3809) Recover from application panics in `server/socket_server.go` to allow socket cleanup (@ruseinov) - [rpc] [\#2252](https://github.com/tendermint/tendermint/issues/2252) Add `/broadcast_evidence` endpoint to submit double signing and other types of evidence -- [rpc] [\#3818](https://github.com/tendermint/tendermint/issues/3818) Make `max_body_bytes` and `max_header_bytes` configurable(@bluele) - [p2p] [\#3664](https://github.com/tendermint/tendermint/issues/3664) p2p/conn: reuse buffer when write/read from secret connection(@guagualvcha) -- [mempool] [\#3826](https://github.com/tendermint/tendermint/issues/3826) Make `max_msg_bytes` configurable(@bluele) -- [blockchain] [\#3561](https://github.com/tendermint/tendermint/issues/3561) Add early version of the new blockchain reactor, which is supposed to be more modular and testable compared to the old version. To try it, you'll have to change `version` in the config file, [here](https://github.com/tendermint/tendermint/blob/master/config/toml.go#L303) NOTE: It's not ready for a production yet. For further information, see [ADR-40](https://github.com/tendermint/tendermint/blob/master/docs/architecture/adr-040-blockchain-reactor-refactor.md) & [ADR-43](https://github.com/tendermint/tendermint/blob/master/docs/architecture/adr-043-blockchain-riri-org.md) - [rpc] [\#3076](https://github.com/tendermint/tendermint/issues/3076) Improve transaction search performance ### BUG FIXES: From 0354ea87f7793000e58a592375e79477dd294e2f Mon Sep 17 00:00:00 2001 From: Zaki Manian Date: Fri, 20 Sep 2019 09:37:49 -0700 Subject: [PATCH 28/45] Fix for panic in signature verification if a peer sends a nil public key. --- p2p/conn/secret_connection.go | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/p2p/conn/secret_connection.go b/p2p/conn/secret_connection.go index c8e450f5b..3e953d0c5 100644 --- a/p2p/conn/secret_connection.go +++ b/p2p/conn/secret_connection.go @@ -133,6 +133,11 @@ func MakeSecretConnection(conn io.ReadWriteCloser, locPrivKey crypto.PrivKey) (* } remPubKey, remSignature := authSigMsg.Key, authSigMsg.Sig + + if remPubKey == nil { + return nil, errors.New("Peer sent a nil public key") + } + if !remPubKey.VerifyBytes(challenge[:], remSignature) { return nil, errors.New("Challenge verification failed") } From d06286916d843717b14f6a0f01f84cbc02dc565e Mon Sep 17 00:00:00 2001 From: Zaki Manian Date: Thu, 26 Sep 2019 08:49:42 -0700 Subject: [PATCH 29/45] update version.go --- version/version.go | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/version/version.go b/version/version.go index b342d6b21..b31eb8895 100644 --- a/version/version.go +++ b/version/version.go @@ -20,7 +20,7 @@ const ( // Must be a string because scripts like dist.sh read this file. // XXX: Don't change the name of this variable or you will break // automation :) - TMCoreSemVer = "0.32.4" + TMCoreSemVer = "0.32.5" // ABCISemVer is the semantic version of the ABCI library ABCISemVer = "0.16.1" From d6ea1ed96fdf3fcfc60375cbb7f370e08b6cda58 Mon Sep 17 00:00:00 2001 From: Zaki Manian Date: Thu, 26 Sep 2019 09:08:42 -0700 Subject: [PATCH 30/45] Changelog update --- CHANGELOG.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 7aa703bbe..7d96f9569 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,13 @@ # Changelog +## v0.32.5 + +### Security + +[p2p] [TODO](hxxp://githublink) Fix for panic on nil public key send to a peer. + + + ## v0.32.4 *September 19, 2019* From b08f6550249283dff47d100df70cb5a19027e326 Mon Sep 17 00:00:00 2001 From: Zaki Manian Date: Fri, 27 Sep 2019 18:31:27 -0700 Subject: [PATCH 31/45] Update CHANGELOG.md Co-Authored-By: Anton Kaliaev --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 7d96f9569..48ed63855 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,7 +4,7 @@ ### Security -[p2p] [TODO](hxxp://githublink) Fix for panic on nil public key send to a peer. +- [p2p] [TODO](hxxp://githublink) Fix for panic on nil public key send to a peer From 0f111b3c5c1ac559858a4c33c4aeac6c4240d464 Mon Sep 17 00:00:00 2001 From: Anton Kaliaev Date: Mon, 30 Sep 2019 13:43:50 -0700 Subject: [PATCH 32/45] update changelog --- CHANGELOG.md | 22 ++++++++++++++++------ CHANGELOG_PENDING.md | 2 +- 2 files changed, 17 insertions(+), 7 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 48ed63855..c680928e2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,12 +2,22 @@ ## v0.32.5 -### Security +*September 30, 2019* + +This release fixes a major security vulnerability found in the `p2p` package. +All clients are recommended to upgrade. See [TODO](hxxp://githublink) for +details. + +Special thanks to [fudongbai](https://hackerone.com/fudongbai) for discovering +and reporting this issue. + +Friendly reminder, we have a [bug bounty +program](https://hackerone.com/tendermint). + +### SECURITY: - [p2p] [TODO](hxxp://githublink) Fix for panic on nil public key send to a peer - - ## v0.32.4 *September 19, 2019* @@ -30,9 +40,9 @@ program](https://hackerone.com/tendermint). - [deps] [\#3951](https://github.com/tendermint/tendermint/pull/3951) bump github.com/stretchr/testify from 1.3.0 to 1.4.0 - [deps] [\#3945](https://github.com/tendermint/tendermint/pull/3945) bump github.com/gorilla/websocket from 1.2.0 to 1.4.1 - [deps] [\#3948](https://github.com/tendermint/tendermint/pull/3948) bump github.com/libp2p/go-buffer-pool from 0.0.1 to 0.0.2 -- [deps] [\#3943](https://github.com/tendermint/tendermint/pull/3943) bump github.com/fortytw2/leaktest from 1.2.0 to 1.3.0 -- [deps] [\#3939](https://github.com/tendermint/tendermint/pull/3939) bump github.com/rs/cors from 1.6.0 to 1.7.0 -- [deps] [\#3937](https://github.com/tendermint/tendermint/pull/3937) bump github.com/magiconair/properties from 1.8.0 to 1.8.1 +- [deps] [\#3943](https://github.com/tendermint/tendermint/pull/3943) bump github.com/fortytw2/leaktest from 1.2.0 to 1.3.0 +- [deps] [\#3939](https://github.com/tendermint/tendermint/pull/3939) bump github.com/rs/cors from 1.6.0 to 1.7.0 +- [deps] [\#3937](https://github.com/tendermint/tendermint/pull/3937) bump github.com/magiconair/properties from 1.8.0 to 1.8.1 - [deps] [\#3947](https://github.com/tendermint/tendermint/pull/3947) update gogo/protobuf version from v1.2.1 to v1.3.0 - [deps] [\#4001](https://github.com/tendermint/tendermint/pull/4001) bump github.com/tendermint/tm-db from 0.1.1 to 0.2.0 diff --git a/CHANGELOG_PENDING.md b/CHANGELOG_PENDING.md index 043c66c7e..578c0bc1a 100644 --- a/CHANGELOG_PENDING.md +++ b/CHANGELOG_PENDING.md @@ -1,4 +1,4 @@ -## v0.32.5 +## v0.32.6 \*\* From ab62fd977f3baa7087fb0fd8c5f2c8d38fe11642 Mon Sep 17 00:00:00 2001 From: Anton Kaliaev Date: Tue, 8 Oct 2019 12:52:28 -0500 Subject: [PATCH 33/45] p2p: only allow ed25519 pubkeys when connecting also, recover from any possible failures in acceptPeers Refs #4030 --- crypto/multisig/threshold_pubkey.go | 5 +++ p2p/conn/secret_connection.go | 19 ++++++------ p2p/conn/secret_connection_test.go | 47 +++++++++++++++++++++++++++++ p2p/transport.go | 19 ++++++++++++ 4 files changed, 81 insertions(+), 9 deletions(-) diff --git a/crypto/multisig/threshold_pubkey.go b/crypto/multisig/threshold_pubkey.go index 234d420f1..36e2dc2dd 100644 --- a/crypto/multisig/threshold_pubkey.go +++ b/crypto/multisig/threshold_pubkey.go @@ -21,6 +21,11 @@ func NewPubKeyMultisigThreshold(k int, pubkeys []crypto.PubKey) crypto.PubKey { if len(pubkeys) < k { panic("threshold k of n multisignature: len(pubkeys) < k") } + for _, pubkey := range pubkeys { + if pubkey == nil { + panic("nil pubkey") + } + } return PubKeyMultisigThreshold{uint(k), pubkeys} } diff --git a/p2p/conn/secret_connection.go b/p2p/conn/secret_connection.go index 3e953d0c5..6f8c855dd 100644 --- a/p2p/conn/secret_connection.go +++ b/p2p/conn/secret_connection.go @@ -7,21 +7,22 @@ import ( "crypto/sha256" "crypto/subtle" "encoding/binary" - "errors" "io" "math" "net" "sync" "time" + pool "github.com/libp2p/go-buffer-pool" + "github.com/pkg/errors" "golang.org/x/crypto/chacha20poly1305" "golang.org/x/crypto/curve25519" + "golang.org/x/crypto/hkdf" "golang.org/x/crypto/nacl/box" - pool "github.com/libp2p/go-buffer-pool" "github.com/tendermint/tendermint/crypto" + "github.com/tendermint/tendermint/crypto/ed25519" cmn "github.com/tendermint/tendermint/libs/common" - "golang.org/x/crypto/hkdf" ) // 4 + 1024 == 1028 total frame size @@ -107,11 +108,11 @@ func MakeSecretConnection(conn io.ReadWriteCloser, locPrivKey crypto.PrivKey) (* sendAead, err := chacha20poly1305.New(sendSecret[:]) if err != nil { - return nil, errors.New("Invalid send SecretConnection Key") + return nil, errors.New("invalid send SecretConnection Key") } recvAead, err := chacha20poly1305.New(recvSecret[:]) if err != nil { - return nil, errors.New("Invalid receive SecretConnection Key") + return nil, errors.New("invalid receive SecretConnection Key") } // Construct SecretConnection. sc := &SecretConnection{ @@ -134,12 +135,12 @@ func MakeSecretConnection(conn io.ReadWriteCloser, locPrivKey crypto.PrivKey) (* remPubKey, remSignature := authSigMsg.Key, authSigMsg.Sig - if remPubKey == nil { - return nil, errors.New("Peer sent a nil public key") + if _, ok := remPubKey.(ed25519.PubKeyEd25519); !ok { + return nil, errors.Errorf("expected ed25519 pubkey, got %T", remPubKey) } if !remPubKey.VerifyBytes(challenge[:], remSignature) { - return nil, errors.New("Challenge verification failed") + return nil, errors.New("challenge verification failed") } // We've authorized. @@ -222,7 +223,7 @@ func (sc *SecretConnection) Read(data []byte) (n int, err error) { defer pool.Put(frame) _, err = sc.recvAead.Open(frame[:0], sc.recvNonce[:], sealedFrame, nil) if err != nil { - return n, errors.New("Failed to decrypt SecretConnection") + return n, errors.New("failed to decrypt SecretConnection") } incrNonce(sc.recvNonce) // end decryption diff --git a/p2p/conn/secret_connection_test.go b/p2p/conn/secret_connection_test.go index 0b7cc00c3..188bf04d5 100644 --- a/p2p/conn/secret_connection_test.go +++ b/p2p/conn/secret_connection_test.go @@ -17,7 +17,9 @@ import ( "github.com/stretchr/testify/assert" "github.com/stretchr/testify/require" + "github.com/tendermint/tendermint/crypto" "github.com/tendermint/tendermint/crypto/ed25519" + "github.com/tendermint/tendermint/crypto/secp256k1" cmn "github.com/tendermint/tendermint/libs/common" ) @@ -366,6 +368,51 @@ func TestDeriveSecretsAndChallengeGolden(t *testing.T) { } } +type privKeyWithNilPubKey struct { + orig crypto.PrivKey +} + +func (pk privKeyWithNilPubKey) Bytes() []byte { return pk.orig.Bytes() } +func (pk privKeyWithNilPubKey) Sign(msg []byte) ([]byte, error) { return pk.orig.Sign(msg) } +func (pk privKeyWithNilPubKey) PubKey() crypto.PubKey { return nil } +func (pk privKeyWithNilPubKey) Equals(pk2 crypto.PrivKey) bool { return pk.orig.Equals(pk2) } + +func TestNilPubkey(t *testing.T) { + var fooConn, barConn = makeKVStoreConnPair() + var fooPrvKey = ed25519.GenPrivKey() + var barPrvKey = privKeyWithNilPubKey{ed25519.GenPrivKey()} + + go func() { + _, err := MakeSecretConnection(barConn, barPrvKey) + assert.NoError(t, err) + }() + + assert.NotPanics(t, func() { + _, err := MakeSecretConnection(fooConn, fooPrvKey) + if assert.Error(t, err) { + assert.Equal(t, "expected ed25519 pubkey, got ", err.Error()) + } + }) +} + +func TestNonEd25519Pubkey(t *testing.T) { + var fooConn, barConn = makeKVStoreConnPair() + var fooPrvKey = ed25519.GenPrivKey() + var barPrvKey = secp256k1.GenPrivKey() + + go func() { + _, err := MakeSecretConnection(barConn, barPrvKey) + assert.NoError(t, err) + }() + + assert.NotPanics(t, func() { + _, err := MakeSecretConnection(fooConn, fooPrvKey) + if assert.Error(t, err) { + assert.Equal(t, "expected ed25519 pubkey, got secp256k1.PubKeySecp256k1", err.Error()) + } + }) +} + // Creates the data for a test vector file. // The file format is: // Hex(diffie_hellman_secret), loc_is_least, Hex(recvSecret), Hex(sendSecret), Hex(challenge) diff --git a/p2p/transport.go b/p2p/transport.go index 8d6ea236e..95c646ac0 100644 --- a/p2p/transport.go +++ b/p2p/transport.go @@ -6,6 +6,8 @@ import ( "net" "time" + "github.com/pkg/errors" + "github.com/tendermint/tendermint/crypto" "github.com/tendermint/tendermint/p2p/conn" ) @@ -270,6 +272,23 @@ func (mt *MultiplexTransport) acceptPeers() { // // [0] https://en.wikipedia.org/wiki/Head-of-line_blocking go func(c net.Conn) { + defer func() { + if r := recover(); r != nil { + err := ErrRejected{ + conn: c, + err: errors.Errorf("recovered from panic: %v", r), + isAuthFailure: true, + } + select { + case mt.acceptc <- accept{err: err}: + case <-mt.closec: + // Give up if the transport was closed. + _ = c.Close() + return + } + } + }() + var ( nodeInfo NodeInfo secretConn *conn.SecretConnection From 88946fd6d83609e6122f000b0f937cdef1ee1fb1 Mon Sep 17 00:00:00 2001 From: Anton Kaliaev Date: Tue, 8 Oct 2019 13:38:37 -0500 Subject: [PATCH 34/45] update changelog and bump version to v0.32.6 --- CHANGELOG.md | 23 +++++++++++++++++++++++ CHANGELOG_PENDING.md | 2 +- version/version.go | 2 +- 3 files changed, 25 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index c680928e2..dcda86602 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,28 @@ # Changelog +## v0.32.6 + +*October XXX, 2019* + +The previous patch was insufficient because the attacker could still find a way +to submit a `nil` pubkey by constructing a `PubKeyMultisigThreshold` pubkey +with `nil` subpubkeys for example. + +This release provides multiple fixes, which include recovering from panics when +accepting new peers and only allowing `ed25519` pubkeys. + +**All clients are recommended to upgrade** + +Special thanks to [fudongbai](https://hackerone.com/fudongbai) for pointing +this out. + +Friendly reminder, we have a [bug bounty +program](https://hackerone.com/tendermint). + +### SECURITY: + +- [p2p] [\#4030](https://github.com/tendermint/tendermint/issues/4030) Only allow ed25519 pubkeys when connecting + ## v0.32.5 *September 30, 2019* diff --git a/CHANGELOG_PENDING.md b/CHANGELOG_PENDING.md index 578c0bc1a..0068a82fe 100644 --- a/CHANGELOG_PENDING.md +++ b/CHANGELOG_PENDING.md @@ -1,4 +1,4 @@ -## v0.32.6 +## v0.32.7 \*\* diff --git a/version/version.go b/version/version.go index b31eb8895..42ec287ab 100644 --- a/version/version.go +++ b/version/version.go @@ -20,7 +20,7 @@ const ( // Must be a string because scripts like dist.sh read this file. // XXX: Don't change the name of this variable or you will break // automation :) - TMCoreSemVer = "0.32.5" + TMCoreSemVer = "0.32.6" // ABCISemVer is the semantic version of the ABCI library ABCISemVer = "0.16.1" From c4ba93a1e6d62b480adb178bb0f9c8d5c6f67717 Mon Sep 17 00:00:00 2001 From: Anton Kaliaev Date: Tue, 8 Oct 2019 13:49:12 -0500 Subject: [PATCH 35/45] set the date to today --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index dcda86602..10e0f8c7a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,7 +2,7 @@ ## v0.32.6 -*October XXX, 2019* +*October 8, 2019* The previous patch was insufficient because the attacker could still find a way to submit a `nil` pubkey by constructing a `PubKeyMultisigThreshold` pubkey From 470a23f9b4042efcc452c8b38fa1805f00c5351b Mon Sep 17 00:00:00 2001 From: Anton Kaliaev Date: Wed, 16 Oct 2019 15:26:36 -0500 Subject: [PATCH 36/45] cs: panic only when WAL#WriteSync fails - modify WAL#Write and WAL#WriteSync to return an error --- consensus/replay_test.go | 19 ++++++++-------- consensus/state.go | 10 +++++++-- consensus/wal.go | 44 +++++++++++++++++++++++--------------- consensus/wal_generator.go | 12 ++++++----- consensus/wal_test.go | 28 +++++++++++++++++++----- 5 files changed, 75 insertions(+), 38 deletions(-) diff --git a/consensus/replay_test.go b/consensus/replay_test.go index b308e4946..04d0f1eb5 100644 --- a/consensus/replay_test.go +++ b/consensus/replay_test.go @@ -228,15 +228,15 @@ func (e ReachedHeightToStopError) Error() string { // Write simulate WAL's crashing by sending an error to the panicCh and then // exiting the cs.receiveRoutine. -func (w *crashingWAL) Write(m WALMessage) { +func (w *crashingWAL) Write(m WALMessage) error { if endMsg, ok := m.(EndHeightMessage); ok { if endMsg.Height == w.heightToStop { w.panicCh <- ReachedHeightToStopError{endMsg.Height} runtime.Goexit() - } else { - w.next.Write(m) + return nil } - return + + return w.next.Write(m) } if w.msgIndex > w.lastPanickedForMsgIndex { @@ -244,14 +244,15 @@ func (w *crashingWAL) Write(m WALMessage) { _, file, line, _ := runtime.Caller(1) w.panicCh <- WALWriteError{fmt.Sprintf("failed to write %T to WAL (fileline: %s:%d)", m, file, line)} runtime.Goexit() - } else { - w.msgIndex++ - w.next.Write(m) + return nil } + + w.msgIndex++ + return w.next.Write(m) } -func (w *crashingWAL) WriteSync(m WALMessage) { - w.Write(m) +func (w *crashingWAL) WriteSync(m WALMessage) error { + return w.Write(m) } func (w *crashingWAL) FlushAndSync() error { return w.next.FlushAndSync() } diff --git a/consensus/state.go b/consensus/state.go index 50b5981e6..da8710056 100644 --- a/consensus/state.go +++ b/consensus/state.go @@ -632,7 +632,10 @@ func (cs *ConsensusState) receiveRoutine(maxSteps int) { // may generate internal events (votes, complete proposals, 2/3 majorities) cs.handleMsg(mi) case mi = <-cs.internalMsgQueue: - cs.wal.WriteSync(mi) // NOTE: fsync + err := cs.wal.WriteSync(mi) // NOTE: fsync + if err != nil { + panic(fmt.Sprintf("Failed to write %v msg to consensus wal due to %v. Check your FS and restart the node", mi, err)) + } if _, ok := mi.Msg.(*VoteMessage); ok { // we actually want to simulate failing during @@ -1329,7 +1332,10 @@ func (cs *ConsensusState) finalizeCommit(height int64) { // Either way, the ConsensusState should not be resumed until we // successfully call ApplyBlock (ie. later here, or in Handshake after // restart). - cs.wal.WriteSync(EndHeightMessage{height}) // NOTE: fsync + me := EndHeightMessage{height} + if err := cs.wal.WriteSync(me); err != nil { // NOTE: fsync + panic(fmt.Sprintf("Failed to write %v msg to consensus wal due to %v. Check your FS and restart the node", me, err)) + } fail.Fail() // XXX diff --git a/consensus/wal.go b/consensus/wal.go index c63c6b940..373f01a16 100644 --- a/consensus/wal.go +++ b/consensus/wal.go @@ -29,8 +29,9 @@ const ( //-------------------------------------------------------- // types and functions for savings consensus messages +// TimedWALMessage wraps WALMessage and adds Time for debugging purposes. type TimedWALMessage struct { - Time time.Time `json:"time"` // for debugging purposes + Time time.Time `json:"time"` Msg WALMessage `json:"msg"` } @@ -55,8 +56,8 @@ func RegisterWALMessages(cdc *amino.Codec) { // WAL is an interface for any write-ahead logger. type WAL interface { - Write(WALMessage) - WriteSync(WALMessage) + Write(WALMessage) error + WriteSync(WALMessage) error FlushAndSync() error SearchForEndHeight(height int64, options *WALSearchOptions) (rd io.ReadCloser, found bool, err error) @@ -174,29 +175,39 @@ func (wal *baseWAL) Wait() { // Write is called in newStep and for each receive on the // peerMsgQueue and the timeoutTicker. // NOTE: does not call fsync() -func (wal *baseWAL) Write(msg WALMessage) { +func (wal *baseWAL) Write(msg WALMessage) error { if wal == nil { - return + return nil } - // Write the wal message if err := wal.enc.Encode(&TimedWALMessage{tmtime.Now(), msg}); err != nil { - panic(fmt.Sprintf("Error writing msg to consensus wal: %v \n\nMessage: %v", err, msg)) + wal.Logger.Error("Error writing msg to consensus wal. WARNING: recover may not be possible for the current height", + "err", err, "msg", msg) + return err } + + return nil } // WriteSync is called when we receive a msg from ourselves // so that we write to disk before sending signed messages. // NOTE: calls fsync() -func (wal *baseWAL) WriteSync(msg WALMessage) { +func (wal *baseWAL) WriteSync(msg WALMessage) error { if wal == nil { - return + return nil } - wal.Write(msg) - if err := wal.FlushAndSync(); err != nil { - panic(fmt.Sprintf("Error flushing consensus wal buf to file. Error: %v \n", err)) + if err := wal.Write(msg); err != nil { + return err } + + if err := wal.FlushAndSync(); err != nil { + wal.Logger.Error("WriteSync failed to flush consensus wal. WARNING: may result in creating alternative proposals / votes for the current height iff the node restarted", + "err", err) + return err + } + + return nil } // WALSearchOptions are optional arguments to SearchForEndHeight. @@ -285,7 +296,7 @@ func (enc *WALEncoder) Encode(v *TimedWALMessage) error { crc := crc32.Checksum(data, crc32c) length := uint32(len(data)) if length > maxMsgSizeBytes { - return fmt.Errorf("Msg is too big: %d bytes, max: %d bytes", length, maxMsgSizeBytes) + return fmt.Errorf("msg is too big: %d bytes, max: %d bytes", length, maxMsgSizeBytes) } totalLength := 8 + int(length) @@ -295,7 +306,6 @@ func (enc *WALEncoder) Encode(v *TimedWALMessage) error { copy(msg[8:], data) _, err := enc.wr.Write(msg) - return err } @@ -383,9 +393,9 @@ type nilWAL struct{} var _ WAL = nilWAL{} -func (nilWAL) Write(m WALMessage) {} -func (nilWAL) WriteSync(m WALMessage) {} -func (nilWAL) FlushAndSync() error { return nil } +func (nilWAL) Write(m WALMessage) error { return nil } +func (nilWAL) WriteSync(m WALMessage) error { return nil } +func (nilWAL) FlushAndSync() error { return nil } func (nilWAL) SearchForEndHeight(height int64, options *WALSearchOptions) (rd io.ReadCloser, found bool, err error) { return nil, false, nil } diff --git a/consensus/wal_generator.go b/consensus/wal_generator.go index 8b5bbc2f0..35b205778 100644 --- a/consensus/wal_generator.go +++ b/consensus/wal_generator.go @@ -168,10 +168,10 @@ func newByteBufferWAL(logger log.Logger, enc *WALEncoder, nBlocks int64, signalS // Save writes message to the internal buffer except when heightToStop is // reached, in which case it will signal the caller via signalWhenStopsTo and // skip writing. -func (w *byteBufferWAL) Write(m WALMessage) { +func (w *byteBufferWAL) Write(m WALMessage) error { if w.stopped { w.logger.Debug("WAL already stopped. Not writing message", "msg", m) - return + return nil } if endMsg, ok := m.(EndHeightMessage); ok { @@ -180,7 +180,7 @@ func (w *byteBufferWAL) Write(m WALMessage) { w.logger.Debug("Stopping WAL at height", "height", endMsg.Height) w.signalWhenStopsTo <- struct{}{} w.stopped = true - return + return nil } } @@ -189,10 +189,12 @@ func (w *byteBufferWAL) Write(m WALMessage) { if err != nil { panic(fmt.Sprintf("failed to encode the msg %v", m)) } + + return nil } -func (w *byteBufferWAL) WriteSync(m WALMessage) { - w.Write(m) +func (w *byteBufferWAL) WriteSync(m WALMessage) error { + return w.Write(m) } func (w *byteBufferWAL) FlushAndSync() error { return nil } diff --git a/consensus/wal_test.go b/consensus/wal_test.go index 82d912f3a..c4acc50c7 100644 --- a/consensus/wal_test.go +++ b/consensus/wal_test.go @@ -11,14 +11,15 @@ import ( "testing" "time" + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + "github.com/tendermint/tendermint/consensus/types" + "github.com/tendermint/tendermint/crypto/merkle" "github.com/tendermint/tendermint/libs/autofile" "github.com/tendermint/tendermint/libs/log" tmtypes "github.com/tendermint/tendermint/types" tmtime "github.com/tendermint/tendermint/types/time" - - "github.com/stretchr/testify/assert" - "github.com/stretchr/testify/require" ) const ( @@ -103,7 +104,7 @@ func TestWALEncoderDecoder(t *testing.T) { } } -func TestWALWritePanicsIfMsgIsTooBig(t *testing.T) { +func TestWALWrite(t *testing.T) { walDir, err := ioutil.TempDir("", "wal") require.NoError(t, err) defer os.RemoveAll(walDir) @@ -120,7 +121,24 @@ func TestWALWritePanicsIfMsgIsTooBig(t *testing.T) { wal.Wait() }() - assert.Panics(t, func() { wal.Write(make([]byte, maxMsgSizeBytes+1)) }) + // 1) Write returns an error if msg is too big + msg := &BlockPartMessage{ + Height: 1, + Round: 1, + Part: &tmtypes.Part{ + Index: 1, + Bytes: make([]byte, 1), + Proof: merkle.SimpleProof{ + Total: 1, + Index: 1, + LeafHash: make([]byte, maxMsgSizeBytes-30), + }, + }, + } + err = wal.Write(msg) + if assert.Error(t, err) { + assert.Equal(t, "msg is too big: 1048593 bytes, max: 1048576 bytes", err.Error()) + } } func TestWALSearchForEndHeight(t *testing.T) { From c207fa6eff7abcaebfd394c32e2194d73d661bbd Mon Sep 17 00:00:00 2001 From: Anton Kaliaev Date: Wed, 16 Oct 2019 18:00:39 -0500 Subject: [PATCH 37/45] types: validate Part#Proof add ValidateBasic to crypto/merkle/SimpleProof --- consensus/reactor_test.go | 2 ++ crypto/merkle/simple_proof.go | 29 +++++++++++++++++++++++ crypto/merkle/simple_proof_test.go | 38 ++++++++++++++++++++++++++++++ types/part_set.go | 7 ++++-- types/part_set_test.go | 8 +++++++ 5 files changed, 82 insertions(+), 2 deletions(-) create mode 100644 crypto/merkle/simple_proof_test.go diff --git a/consensus/reactor_test.go b/consensus/reactor_test.go index 168f07924..f06d2824a 100644 --- a/consensus/reactor_test.go +++ b/consensus/reactor_test.go @@ -19,6 +19,7 @@ import ( abci "github.com/tendermint/tendermint/abci/types" cfg "github.com/tendermint/tendermint/config" cstypes "github.com/tendermint/tendermint/consensus/types" + "github.com/tendermint/tendermint/crypto/tmhash" cmn "github.com/tendermint/tendermint/libs/common" "github.com/tendermint/tendermint/libs/log" mempl "github.com/tendermint/tendermint/mempool" @@ -732,6 +733,7 @@ func TestProposalPOLMessageValidateBasic(t *testing.T) { func TestBlockPartMessageValidateBasic(t *testing.T) { testPart := new(types.Part) + testPart.Proof.LeafHash = tmhash.Sum([]byte("leaf")) testCases := []struct { testName string messageHeight int64 diff --git a/crypto/merkle/simple_proof.go b/crypto/merkle/simple_proof.go index da32157db..8bd2570f4 100644 --- a/crypto/merkle/simple_proof.go +++ b/crypto/merkle/simple_proof.go @@ -5,6 +5,12 @@ import ( "fmt" "github.com/pkg/errors" + "github.com/tendermint/tendermint/crypto/tmhash" +) + +const ( + // given maxMsgSizeBytes in consensus wal is 1MB + maxAunts = 30000 ) // SimpleProof represents a simple Merkle proof. @@ -108,6 +114,29 @@ func (sp *SimpleProof) StringIndented(indent string) string { indent) } +// ValidateBasic performs basic validation. +// NOTE: it expects LeafHash and Aunts of tmhash.Size size. +func (sp *SimpleProof) ValidateBasic() error { + if sp.Total < 0 { + return errors.New("negative Total") + } + if sp.Index < 0 { + return errors.New("negative Index") + } + if len(sp.LeafHash) != tmhash.Size { + return errors.Errorf("expected LeafHash size to be %d, got %d", tmhash.Size, len(sp.LeafHash)) + } + if len(sp.Aunts) > maxAunts { + return errors.Errorf("expected no more than %d aunts, got %d", maxAunts, len(sp.Aunts)) + } + for i, auntHash := range sp.Aunts { + if len(auntHash) != tmhash.Size { + return errors.Errorf("expected Aunts#%d size to be %d, got %d", i, tmhash.Size, len(auntHash)) + } + } + return nil +} + // Use the leafHash and innerHashes to get the root merkle hash. // If the length of the innerHashes slice isn't exactly correct, the result is nil. // Recursive impl. diff --git a/crypto/merkle/simple_proof_test.go b/crypto/merkle/simple_proof_test.go new file mode 100644 index 000000000..521bf4a35 --- /dev/null +++ b/crypto/merkle/simple_proof_test.go @@ -0,0 +1,38 @@ +package merkle + +import ( + "testing" + + "github.com/stretchr/testify/assert" +) + +func TestSimpleProofValidateBasic(t *testing.T) { + testCases := []struct { + testName string + malleateProof func(*SimpleProof) + errStr string + }{ + {"Good", func(sp *SimpleProof) {}, ""}, + {"Negative Total", func(sp *SimpleProof) { sp.Total = -1 }, "negative Total"}, + {"Negative Index", func(sp *SimpleProof) { sp.Index = -1 }, "negative Index"}, + {"Invalid LeafHash", func(sp *SimpleProof) { sp.LeafHash = make([]byte, 10) }, "expected LeafHash size to be 32, got 10"}, + {"Too many Aunts", func(sp *SimpleProof) { sp.Aunts = make([][]byte, maxAunts+1) }, "expected no more than 30000 aunts, got 30001"}, + {"Invalid Aunt", func(sp *SimpleProof) { sp.Aunts[0] = make([]byte, 10) }, "expected Aunts#0 size to be 32, got 10"}, + } + + for _, tc := range testCases { + tc := tc + t.Run(tc.testName, func(t *testing.T) { + _, proofs := SimpleProofsFromByteSlices([][]byte{ + []byte("apple"), + []byte("watermelon"), + []byte("kiwi"), + }) + tc.malleateProof(proofs[0]) + err := proofs[0].ValidateBasic() + if tc.errStr != "" { + assert.Contains(t, err.Error(), tc.errStr) + } + }) + } +} diff --git a/types/part_set.go b/types/part_set.go index 389db7a0b..ecac027f9 100644 --- a/types/part_set.go +++ b/types/part_set.go @@ -26,10 +26,13 @@ type Part struct { // ValidateBasic performs basic validation. func (part *Part) ValidateBasic() error { if part.Index < 0 { - return errors.New("Negative Index") + return errors.New("negative Index") } if len(part.Bytes) > BlockPartSizeBytes { - return fmt.Errorf("Too big (max: %d)", BlockPartSizeBytes) + return errors.Errorf("too big: %d bytes, max: %d", len(part.Bytes), BlockPartSizeBytes) + } + if err := part.Proof.ValidateBasic(); err != nil { + return errors.Wrap(err, "wrong Proof") } return nil } diff --git a/types/part_set_test.go b/types/part_set_test.go index 37aacea75..706c8cae4 100644 --- a/types/part_set_test.go +++ b/types/part_set_test.go @@ -7,6 +7,7 @@ import ( "github.com/stretchr/testify/assert" "github.com/stretchr/testify/require" + "github.com/tendermint/tendermint/crypto/merkle" cmn "github.com/tendermint/tendermint/libs/common" ) @@ -115,6 +116,13 @@ func TestPartValidateBasic(t *testing.T) { {"Good Part", func(pt *Part) {}, false}, {"Negative index", func(pt *Part) { pt.Index = -1 }, true}, {"Too big part", func(pt *Part) { pt.Bytes = make([]byte, BlockPartSizeBytes+1) }, true}, + {"Too big proof", func(pt *Part) { + pt.Proof = merkle.SimpleProof{ + Total: 1, + Index: 1, + LeafHash: make([]byte, 1024*1024), + } + }, true}, } for _, tc := range testCases { From c38dbdb64056e8a35117d0ef719d6d68d80d83e4 Mon Sep 17 00:00:00 2001 From: Anton Kaliaev Date: Wed, 16 Oct 2019 19:34:49 -0500 Subject: [PATCH 38/45] cs: limit max bit array size and block parts count --- consensus/reactor.go | 9 +++++++++ types/params.go | 3 +++ types/vote_set.go | 6 ++++++ 3 files changed, 18 insertions(+) diff --git a/consensus/reactor.go b/consensus/reactor.go index dc3514b21..e0ad61abd 100644 --- a/consensus/reactor.go +++ b/consensus/reactor.go @@ -1458,6 +1458,9 @@ func (m *NewValidBlockMessage) ValidateBasic() error { m.BlockParts.Size(), m.BlockPartsHeader.Total) } + if m.BlockParts.Size() > types.MaxBlockPartsCount { + return errors.Errorf("BlockParts bit array is too big: %d, max: %d", m.BlockParts.Size(), types.MaxBlockPartsCount) + } return nil } @@ -1504,6 +1507,9 @@ func (m *ProposalPOLMessage) ValidateBasic() error { if m.ProposalPOL.Size() == 0 { return errors.New("Empty ProposalPOL bit array") } + if m.ProposalPOL.Size() > types.MaxVotesCount { + return errors.Errorf("ProposalPOL bit array is too big: %d, max: %d", m.ProposalPOL.Size(), types.MaxVotesCount) + } return nil } @@ -1647,6 +1653,9 @@ func (m *VoteSetBitsMessage) ValidateBasic() error { return fmt.Errorf("Wrong BlockID: %v", err) } // NOTE: Votes.Size() can be zero if the node does not have any + if m.Votes.Size() > types.MaxVotesCount { + return fmt.Errorf("Votes bit array is too big: %d, max: %d", m.Votes.Size(), types.MaxVotesCount) + } return nil } diff --git a/types/params.go b/types/params.go index c9ab4aaf7..834178f73 100644 --- a/types/params.go +++ b/types/params.go @@ -14,6 +14,9 @@ const ( // BlockPartSizeBytes is the size of one block part. BlockPartSizeBytes = 65536 // 64kB + + // MaxBlockPartsCount is the maximum count of block parts. + MaxBlockPartsCount = MaxBlockSizeBytes / BlockPartSizeBytes ) // ConsensusParams contains consensus critical parameters that determine the diff --git a/types/vote_set.go b/types/vote_set.go index 56dd9a13c..0d7a5c579 100644 --- a/types/vote_set.go +++ b/types/vote_set.go @@ -11,6 +11,12 @@ import ( cmn "github.com/tendermint/tendermint/libs/common" ) +const ( + // MaxVotesCount is the maximum votes count. Used in ValidateBasic funcs for + // protection against DOS attacks. + MaxVotesCount = 10000 +) + // UNSTABLE // XXX: duplicate of p2p.ID to avoid dependence between packages. // Perhaps we can have a minimal types package containing this (and other things?) From 564d6a203a4787f13e331d8de10df12d019b0d45 Mon Sep 17 00:00:00 2001 From: Anton Kaliaev Date: Wed, 16 Oct 2019 20:47:48 -0500 Subject: [PATCH 39/45] cs: test new limits --- consensus/reactor.go | 3 + consensus/reactor_test.go | 154 ++++++++++++++++++++------------------ 2 files changed, 84 insertions(+), 73 deletions(-) diff --git a/consensus/reactor.go b/consensus/reactor.go index e0ad61abd..a24981dec 100644 --- a/consensus/reactor.go +++ b/consensus/reactor.go @@ -1453,6 +1453,9 @@ func (m *NewValidBlockMessage) ValidateBasic() error { if err := m.BlockPartsHeader.ValidateBasic(); err != nil { return fmt.Errorf("Wrong BlockPartsHeader: %v", err) } + if m.BlockParts.Size() == 0 { + return errors.New("Empty BlockParts") + } if m.BlockParts.Size() != m.BlockPartsHeader.Total { return fmt.Errorf("BlockParts bit array size %d not equal to BlockPartsHeader.Total %d", m.BlockParts.Size(), diff --git a/consensus/reactor_test.go b/consensus/reactor_test.go index f06d2824a..39147f5c9 100644 --- a/consensus/reactor_test.go +++ b/consensus/reactor_test.go @@ -672,61 +672,75 @@ func TestNewRoundStepMessageValidateBasic(t *testing.T) { } func TestNewValidBlockMessageValidateBasic(t *testing.T) { - testBitArray := cmn.NewBitArray(1) testCases := []struct { - testName string - messageHeight int64 - messageRound int - messageBlockParts *cmn.BitArray - expectErr bool + malleateFn func(*NewValidBlockMessage) + expErr string }{ - {"Valid Message", 0, 0, testBitArray, false}, - {"Invalid Message", -1, 0, testBitArray, true}, - {"Invalid Message", 0, -1, testBitArray, true}, - {"Invalid Message", 0, 0, cmn.NewBitArray(0), true}, + {func(msg *NewValidBlockMessage) {}, ""}, + {func(msg *NewValidBlockMessage) { msg.Height = -1 }, "Negative Height"}, + {func(msg *NewValidBlockMessage) { msg.Round = -1 }, "Negative Round"}, + { + func(msg *NewValidBlockMessage) { msg.BlockPartsHeader.Total = 2 }, + "BlockParts bit array size 1 not equal to BlockPartsHeader.Total 2", + }, + { + func(msg *NewValidBlockMessage) { msg.BlockPartsHeader.Total = 0; msg.BlockParts = cmn.NewBitArray(0) }, + "Empty BlockParts", + }, + { + func(msg *NewValidBlockMessage) { msg.BlockParts = cmn.NewBitArray(types.MaxBlockPartsCount + 1) }, + "BlockParts bit array size 1601 not equal to BlockPartsHeader.Total 1", + }, } - for _, tc := range testCases { + for i, tc := range testCases { tc := tc - t.Run(tc.testName, func(t *testing.T) { - message := NewValidBlockMessage{ - Height: tc.messageHeight, - Round: tc.messageRound, - BlockParts: tc.messageBlockParts, + t.Run(fmt.Sprintf("#%d", i), func(t *testing.T) { + msg := &NewValidBlockMessage{ + Height: 1, + Round: 0, + BlockPartsHeader: types.PartSetHeader{ + Total: 1, + }, + BlockParts: cmn.NewBitArray(1), } - message.BlockPartsHeader.Total = 1 - - assert.Equal(t, tc.expectErr, message.ValidateBasic() != nil, "Validate Basic had an unexpected result") + tc.malleateFn(msg) + err := msg.ValidateBasic() + if tc.expErr != "" && assert.Error(t, err) { + assert.Contains(t, err.Error(), tc.expErr) + } }) } } func TestProposalPOLMessageValidateBasic(t *testing.T) { - testBitArray := cmn.NewBitArray(1) testCases := []struct { - testName string - messageHeight int64 - messageProposalPOLRound int - messageProposalPOL *cmn.BitArray - expectErr bool + malleateFn func(*ProposalPOLMessage) + expErr string }{ - {"Valid Message", 0, 0, testBitArray, false}, - {"Invalid Message", -1, 0, testBitArray, true}, - {"Invalid Message", 0, -1, testBitArray, true}, - {"Invalid Message", 0, 0, cmn.NewBitArray(0), true}, + {func(msg *ProposalPOLMessage) {}, ""}, + {func(msg *ProposalPOLMessage) { msg.Height = -1 }, "Negative Height"}, + {func(msg *ProposalPOLMessage) { msg.ProposalPOLRound = -1 }, "Negative ProposalPOLRound"}, + {func(msg *ProposalPOLMessage) { msg.ProposalPOL = cmn.NewBitArray(0) }, "Empty ProposalPOL bit array"}, + {func(msg *ProposalPOLMessage) { msg.ProposalPOL = cmn.NewBitArray(types.MaxVotesCount + 1) }, + "ProposalPOL bit array is too big: 10001, max: 10000"}, } - for _, tc := range testCases { + for i, tc := range testCases { tc := tc - t.Run(tc.testName, func(t *testing.T) { - message := ProposalPOLMessage{ - Height: tc.messageHeight, - ProposalPOLRound: tc.messageProposalPOLRound, - ProposalPOL: tc.messageProposalPOL, + t.Run(fmt.Sprintf("#%d", i), func(t *testing.T) { + msg := &ProposalPOLMessage{ + Height: 1, + ProposalPOLRound: 1, + ProposalPOL: cmn.NewBitArray(1), } - assert.Equal(t, tc.expectErr, message.ValidateBasic() != nil, "Validate Basic had an unexpected result") + tc.malleateFn(msg) + err := msg.ValidateBasic() + if tc.expErr != "" && assert.Error(t, err) { + assert.Contains(t, err.Error(), tc.expErr) + } }) } } @@ -847,49 +861,43 @@ func TestVoteSetMaj23MessageValidateBasic(t *testing.T) { } func TestVoteSetBitsMessageValidateBasic(t *testing.T) { - const ( - validSignedMsgType types.SignedMsgType = 0x01 - invalidSignedMsgType types.SignedMsgType = 0x03 - ) - - validBlockID := types.BlockID{} - invalidBlockID := types.BlockID{ - Hash: cmn.HexBytes{}, - PartsHeader: types.PartSetHeader{ - Total: -1, - Hash: cmn.HexBytes{}, - }, - } - testBitArray := cmn.NewBitArray(1) - - testCases := []struct { - testName string - messageHeight int64 - messageRound int - messageType types.SignedMsgType - messageBlockID types.BlockID - messageVotes *cmn.BitArray - expectErr bool + testCases := []struct { // nolint: maligned + malleateFn func(*VoteSetBitsMessage) + expErr string }{ - {"Valid Message", 0, 0, validSignedMsgType, validBlockID, testBitArray, false}, - {"Invalid Message", -1, 0, validSignedMsgType, validBlockID, testBitArray, true}, - {"Invalid Message", 0, -1, validSignedMsgType, validBlockID, testBitArray, true}, - {"Invalid Message", 0, 0, invalidSignedMsgType, validBlockID, testBitArray, true}, - {"Invalid Message", 0, 0, validSignedMsgType, invalidBlockID, testBitArray, true}, + {func(msg *VoteSetBitsMessage) {}, ""}, + {func(msg *VoteSetBitsMessage) { msg.Height = -1 }, "Negative Height"}, + {func(msg *VoteSetBitsMessage) { msg.Round = -1 }, "Negative Round"}, + {func(msg *VoteSetBitsMessage) { msg.Type = 0x03 }, "Invalid Type"}, + {func(msg *VoteSetBitsMessage) { + msg.BlockID = types.BlockID{ + Hash: cmn.HexBytes{}, + PartsHeader: types.PartSetHeader{ + Total: -1, + Hash: cmn.HexBytes{}, + }, + } + }, "Wrong BlockID: Wrong PartsHeader: Negative Total"}, + {func(msg *VoteSetBitsMessage) { msg.Votes = cmn.NewBitArray(types.MaxVotesCount + 1) }, + "Votes bit array is too big: 10001, max: 10000"}, } - for _, tc := range testCases { + for i, tc := range testCases { tc := tc - t.Run(tc.testName, func(t *testing.T) { - message := VoteSetBitsMessage{ - Height: tc.messageHeight, - Round: tc.messageRound, - Type: tc.messageType, - // Votes: tc.messageVotes, - BlockID: tc.messageBlockID, + t.Run(fmt.Sprintf("#%d", i), func(t *testing.T) { + msg := &VoteSetBitsMessage{ + Height: 1, + Round: 0, + Type: 0x01, + Votes: cmn.NewBitArray(1), + BlockID: types.BlockID{}, } - assert.Equal(t, tc.expectErr, message.ValidateBasic() != nil, "Validate Basic had an unexpected result") + tc.malleateFn(msg) + err := msg.ValidateBasic() + if tc.expErr != "" && assert.Error(t, err) { + assert.Contains(t, err.Error(), tc.expErr) + } }) } } From 714948505b2450fc525ca05d7bdbdc2cc3e3f433 Mon Sep 17 00:00:00 2001 From: Anton Kaliaev Date: Wed, 16 Oct 2019 20:57:13 -0500 Subject: [PATCH 40/45] cs: only assert important stuff --- consensus/wal_test.go | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/consensus/wal_test.go b/consensus/wal_test.go index c4acc50c7..6871f534d 100644 --- a/consensus/wal_test.go +++ b/consensus/wal_test.go @@ -137,7 +137,7 @@ func TestWALWrite(t *testing.T) { } err = wal.Write(msg) if assert.Error(t, err) { - assert.Equal(t, "msg is too big: 1048593 bytes, max: 1048576 bytes", err.Error()) + assert.Contains(t, err.Error(), "msg is too big") } } From b5cad43b2624a308071eb384f91515df2aa617a0 Mon Sep 17 00:00:00 2001 From: Anton Kaliaev Date: Thu, 17 Oct 2019 17:28:41 -0500 Subject: [PATCH 41/45] update changelog and bump version to 0.32.7 --- CHANGELOG.md | 27 +++++++++++++++++++++++++++ CHANGELOG_PENDING.md | 2 +- version/version.go | 2 +- 3 files changed, 29 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 10e0f8c7a..dbb60a3a1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,32 @@ # Changelog +## v0.32.7 + +*October 18, 2019* + +This security release fixes a vulnerability found in the `consensus` package, +where an attacker could construct a `BlockPartMessage` message in such a way +that it will lead to consensus failure. A few similar issues have been +identified and fixed here. + +**All clients are recommended to upgrade** + +Special thanks to [elvishacker](https://hackerone.com/elvishacker) for finding +and reporting this. + +Friendly reminder, we have a [bug bounty +program](https://hackerone.com/tendermint). + +### BREAKING CHANGES: + +- Go API + - [consensus] Modify `WAL#Write` and `WAL#WriteSync` to return an error if + they fail to write a message + +### SECURITY: + +- [consensus] Validate incoming messages more throughly + ## v0.32.6 *October 8, 2019* diff --git a/CHANGELOG_PENDING.md b/CHANGELOG_PENDING.md index 0068a82fe..126633cfe 100644 --- a/CHANGELOG_PENDING.md +++ b/CHANGELOG_PENDING.md @@ -1,4 +1,4 @@ -## v0.32.7 +## v0.32.8 \*\* diff --git a/version/version.go b/version/version.go index 42ec287ab..35d4516d2 100644 --- a/version/version.go +++ b/version/version.go @@ -20,7 +20,7 @@ const ( // Must be a string because scripts like dist.sh read this file. // XXX: Don't change the name of this variable or you will break // automation :) - TMCoreSemVer = "0.32.6" + TMCoreSemVer = "0.32.7" // ABCISemVer is the semantic version of the ABCI library ABCISemVer = "0.16.1" From 7ec2dff6fd435210d1f4320acd588a2f9543bed4 Mon Sep 17 00:00:00 2001 From: Anton Kaliaev Date: Sat, 19 Oct 2019 12:26:05 -0500 Subject: [PATCH 42/45] fixes after Ethan's review --- consensus/state.go | 6 ++--- consensus/wal.go | 2 +- crypto/merkle/simple_proof.go | 6 ++--- docs/spec/blockchain/encoding.md | 2 ++ .../reactors/consensus/consensus-reactor.md | 27 +++++++++++++------ scripts/wal2json/main.go | 4 +-- types/params.go | 2 +- 7 files changed, 31 insertions(+), 18 deletions(-) diff --git a/consensus/state.go b/consensus/state.go index da8710056..110c2529c 100644 --- a/consensus/state.go +++ b/consensus/state.go @@ -1332,9 +1332,9 @@ func (cs *ConsensusState) finalizeCommit(height int64) { // Either way, the ConsensusState should not be resumed until we // successfully call ApplyBlock (ie. later here, or in Handshake after // restart). - me := EndHeightMessage{height} - if err := cs.wal.WriteSync(me); err != nil { // NOTE: fsync - panic(fmt.Sprintf("Failed to write %v msg to consensus wal due to %v. Check your FS and restart the node", me, err)) + endMsg := EndHeightMessage{height} + if err := cs.wal.WriteSync(endMsg); err != nil { // NOTE: fsync + panic(fmt.Sprintf("Failed to write %v msg to consensus wal due to %v. Check your FS and restart the node", endMsg, err)) } fail.Fail() // XXX diff --git a/consensus/wal.go b/consensus/wal.go index 373f01a16..9cdb3c3f0 100644 --- a/consensus/wal.go +++ b/consensus/wal.go @@ -20,7 +20,7 @@ import ( const ( // must be greater than types.BlockPartSizeBytes + a few bytes - maxMsgSizeBytes = 1024 * 1024 // 1MB + maxMsgSizeBytes = types.BlockPartSizeBytes * 2 // how often the WAL should be sync'd during period sync'ing walDefaultFlushInterval = 2 * time.Second diff --git a/crypto/merkle/simple_proof.go b/crypto/merkle/simple_proof.go index 8bd2570f4..93b6f9fea 100644 --- a/crypto/merkle/simple_proof.go +++ b/crypto/merkle/simple_proof.go @@ -9,8 +9,7 @@ import ( ) const ( - // given maxMsgSizeBytes in consensus wal is 1MB - maxAunts = 30000 + maxAunts = 100 ) // SimpleProof represents a simple Merkle proof. @@ -115,7 +114,8 @@ func (sp *SimpleProof) StringIndented(indent string) string { } // ValidateBasic performs basic validation. -// NOTE: it expects LeafHash and Aunts of tmhash.Size size. +// NOTE: - it expects LeafHash and Aunts of tmhash.Size size +// - it expects no more than 100 aunts func (sp *SimpleProof) ValidateBasic() error { if sp.Total < 0 { return errors.New("negative Total") diff --git a/docs/spec/blockchain/encoding.md b/docs/spec/blockchain/encoding.md index 170e91605..a171020b0 100644 --- a/docs/spec/blockchain/encoding.md +++ b/docs/spec/blockchain/encoding.md @@ -288,6 +288,8 @@ func computeHashFromAunts(index, total int, leafHash []byte, innerHashes [][]byt } ``` +The number of aunts is limited to 100 (`maxAunts`) to protect the node against DOS attacks. + ### IAVL+ Tree Because Tendermint only uses a Simple Merkle Tree, application developers are expect to use their own Merkle tree in their applications. For example, the IAVL+ Tree - an immutable self-balancing binary tree for persisting application state is used by the [Cosmos SDK](https://github.com/cosmos/cosmos-sdk/blob/master/docs/clients/lite/specification.md) diff --git a/docs/spec/reactors/consensus/consensus-reactor.md b/docs/spec/reactors/consensus/consensus-reactor.md index 47c6949a7..0f74c5f88 100644 --- a/docs/spec/reactors/consensus/consensus-reactor.md +++ b/docs/spec/reactors/consensus/consensus-reactor.md @@ -96,11 +96,13 @@ type PeerRoundState struct { ## Receive method of Consensus reactor -The entry point of the Consensus reactor is a receive method. When a message is received from a peer p, -normally the peer round state is updated correspondingly, and some messages -are passed for further processing, for example to ConsensusState service. We now specify the processing of messages -in the receive method of Consensus reactor for each message type. In the following message handler, `rs` and `prs` denote -`RoundState` and `PeerRoundState`, respectively. +The entry point of the Consensus reactor is a receive method. When a message is +received from a peer p, normally the peer round state is updated +correspondingly, and some messages are passed for further processing, for +example to ConsensusState service. We now specify the processing of messages in +the receive method of Consensus reactor for each message type. In the following +message handler, `rs` and `prs` denote `RoundState` and `PeerRoundState`, +respectively. ### NewRoundStepMessage handler @@ -134,13 +136,16 @@ handleMessage(msg): ``` handleMessage(msg): if prs.Height != msg.Height then return - + if prs.Round != msg.Round && !msg.IsCommit then return - + prs.ProposalBlockPartsHeader = msg.BlockPartsHeader prs.ProposalBlockParts = msg.BlockParts ``` +The number of block parts is limited to 1601 (`types.MaxBlockPartsCount`) to +protect the node against DOS attacks. + ### HasVoteMessage handler ``` @@ -179,6 +184,9 @@ handleMessage(msg): prs.ProposalPOL = msg.ProposalPOL ``` +The number of votes is limited to 10000 (`types.MaxVotesCount`) to protect the +node against DOS attacks. + ### BlockPartMessage handler ``` @@ -203,6 +211,9 @@ handleMessage(msg): Update prs for the bit-array of votes peer claims to have for the msg.BlockID ``` +The number of votes is limited to 10000 (`types.MaxVotesCount`) to protect the +node against DOS attacks. + ## Gossip Data Routine It is used to send the following messages to the peer: `BlockPartMessage`, `ProposalMessage` and @@ -338,7 +349,7 @@ BlockID has seen +2/3 votes. This routine is based on the local RoundState (`rs` ## Broadcast routine -The Broadcast routine subscribes to an internal event bus to receive new round steps and votes messages, and broadcasts messages to peers upon receiving those +The Broadcast routine subscribes to an internal event bus to receive new round steps and votes messages, and broadcasts messages to peers upon receiving those events. It broadcasts `NewRoundStepMessage` or `CommitStepMessage` upon new round state event. Note that broadcasting these messages does not depend on the PeerRoundState; it is sent on the StateChannel. diff --git a/scripts/wal2json/main.go b/scripts/wal2json/main.go index ee90ecaa4..96aadd146 100644 --- a/scripts/wal2json/main.go +++ b/scripts/wal2json/main.go @@ -56,8 +56,8 @@ func main() { _, err = os.Stdout.Write([]byte("\n")) } if err == nil { - if end, ok := msg.Msg.(cs.EndHeightMessage); ok { - _, err = os.Stdout.Write([]byte(fmt.Sprintf("ENDHEIGHT %d\n", end.Height))) // nolint: errcheck, gas + if endMsg, ok := msg.Msg.(cs.EndHeightMessage); ok { + _, err = os.Stdout.Write([]byte(fmt.Sprintf("ENDHEIGHT %d\n", endMsg.Height))) // nolint: errcheck, gas } } if err != nil { diff --git a/types/params.go b/types/params.go index 834178f73..61c1d2da6 100644 --- a/types/params.go +++ b/types/params.go @@ -16,7 +16,7 @@ const ( BlockPartSizeBytes = 65536 // 64kB // MaxBlockPartsCount is the maximum count of block parts. - MaxBlockPartsCount = MaxBlockSizeBytes / BlockPartSizeBytes + MaxBlockPartsCount = (MaxBlockSizeBytes / BlockPartSizeBytes) + 1 ) // ConsensusParams contains consensus critical parameters that determine the From c013501f45d6fe9c0b4fdd62818b21477a29bc28 Mon Sep 17 00:00:00 2001 From: Anton Kaliaev Date: Wed, 23 Oct 2019 17:16:41 -0500 Subject: [PATCH 43/45] align max wal msg and max consensus msg sizes --- consensus/wal.go | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/consensus/wal.go b/consensus/wal.go index 9cdb3c3f0..f393955dc 100644 --- a/consensus/wal.go +++ b/consensus/wal.go @@ -19,8 +19,8 @@ import ( ) const ( - // must be greater than types.BlockPartSizeBytes + a few bytes - maxMsgSizeBytes = types.BlockPartSizeBytes * 2 + // amino overhead + time.Time + max consensus msg size + maxMsgSizeBytes = maxMsgSize + 24 // how often the WAL should be sync'd during period sync'ing walDefaultFlushInterval = 2 * time.Second From 7ffd3fff433cc5d8d55fd850bb3d414def6ac6cd Mon Sep 17 00:00:00 2001 From: Anton Kaliaev Date: Wed, 23 Oct 2019 17:33:47 -0500 Subject: [PATCH 44/45] fix tests --- consensus/reactor_test.go | 2 +- crypto/merkle/simple_proof_test.go | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/consensus/reactor_test.go b/consensus/reactor_test.go index 39147f5c9..1ebc91002 100644 --- a/consensus/reactor_test.go +++ b/consensus/reactor_test.go @@ -689,7 +689,7 @@ func TestNewValidBlockMessageValidateBasic(t *testing.T) { }, { func(msg *NewValidBlockMessage) { msg.BlockParts = cmn.NewBitArray(types.MaxBlockPartsCount + 1) }, - "BlockParts bit array size 1601 not equal to BlockPartsHeader.Total 1", + "BlockParts bit array size 1602 not equal to BlockPartsHeader.Total 1", }, } diff --git a/crypto/merkle/simple_proof_test.go b/crypto/merkle/simple_proof_test.go index 521bf4a35..1175ce3cc 100644 --- a/crypto/merkle/simple_proof_test.go +++ b/crypto/merkle/simple_proof_test.go @@ -16,7 +16,7 @@ func TestSimpleProofValidateBasic(t *testing.T) { {"Negative Total", func(sp *SimpleProof) { sp.Total = -1 }, "negative Total"}, {"Negative Index", func(sp *SimpleProof) { sp.Index = -1 }, "negative Index"}, {"Invalid LeafHash", func(sp *SimpleProof) { sp.LeafHash = make([]byte, 10) }, "expected LeafHash size to be 32, got 10"}, - {"Too many Aunts", func(sp *SimpleProof) { sp.Aunts = make([][]byte, maxAunts+1) }, "expected no more than 30000 aunts, got 30001"}, + {"Too many Aunts", func(sp *SimpleProof) { sp.Aunts = make([][]byte, maxAunts+1) }, "expected no more than 101 aunts, got 101"}, {"Invalid Aunt", func(sp *SimpleProof) { sp.Aunts[0] = make([]byte, 10) }, "expected Aunts#0 size to be 32, got 10"}, } From 7b67ee408bb198574863f6acec6f3c791a4c0385 Mon Sep 17 00:00:00 2001 From: Anton Kaliaev Date: Wed, 23 Oct 2019 18:03:09 -0500 Subject: [PATCH 45/45] fix test --- crypto/merkle/simple_proof_test.go | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/crypto/merkle/simple_proof_test.go b/crypto/merkle/simple_proof_test.go index 1175ce3cc..1a517905b 100644 --- a/crypto/merkle/simple_proof_test.go +++ b/crypto/merkle/simple_proof_test.go @@ -16,7 +16,7 @@ func TestSimpleProofValidateBasic(t *testing.T) { {"Negative Total", func(sp *SimpleProof) { sp.Total = -1 }, "negative Total"}, {"Negative Index", func(sp *SimpleProof) { sp.Index = -1 }, "negative Index"}, {"Invalid LeafHash", func(sp *SimpleProof) { sp.LeafHash = make([]byte, 10) }, "expected LeafHash size to be 32, got 10"}, - {"Too many Aunts", func(sp *SimpleProof) { sp.Aunts = make([][]byte, maxAunts+1) }, "expected no more than 101 aunts, got 101"}, + {"Too many Aunts", func(sp *SimpleProof) { sp.Aunts = make([][]byte, maxAunts+1) }, "expected no more than 100 aunts, got 101"}, {"Invalid Aunt", func(sp *SimpleProof) { sp.Aunts[0] = make([]byte, 10) }, "expected Aunts#0 size to be 32, got 10"}, }