client

Documentation

Overview

package client provides a general purpose interface (Client) for connecting to a tendermint node, as well as higher-level functionality.

The main implementation for production code is client.HTTP, which connects via http to the jsonrpc interface of the tendermint node.

For connecting to a node running in the same process (eg. when compiling the abci app in the same process), you can use the client.Local implementation.

For mocking out server responses during testing to see behavior for arbitrary return values, use the mock package.

In addition to the Client interface, which should be used externally for maximum flexibility and testability, and two implementations, this package also provides helper functions that work on any Client implementation.

Index

• func DefaultWaitStrategy(delta int) (abort error)
• func WaitForHeight(c StatusClient, h int, waiter Waiter) error
• func WaitForOneEvent(evsw types.EventSwitch, evtTyp string, timeout time.Duration) (types.TMEventData, error)
• type ABCIClient
• type Client
• type HTTP
  • func NewHTTP(remote, wsEndpoint string) *HTTP
  • func (c *HTTP) ABCIInfo() (*ctypes.ResultABCIInfo, error)
  • func (c *HTTP) ABCIQuery(path string, data []byte, prove bool) (*ctypes.ResultABCIQuery, error)
  • func (c *HTTP) Block(height int) (*ctypes.ResultBlock, error)
  • func (c *HTTP) BlockchainInfo(minHeight, maxHeight int) (*ctypes.ResultBlockchainInfo, error)
  • func (c *HTTP) BroadcastTxAsync(tx types.Tx) (*ctypes.ResultBroadcastTx, error)
  • func (c *HTTP) BroadcastTxCommit(tx types.Tx) (*ctypes.ResultBroadcastTxCommit, error)
  • func (c *HTTP) BroadcastTxSync(tx types.Tx) (*ctypes.ResultBroadcastTx, error)
  • func (c *HTTP) Commit(height int) (*ctypes.ResultCommit, error)
  • func (c *HTTP) DumpConsensusState() (*ctypes.ResultDumpConsensusState, error)
  • func (c *HTTP) Genesis() (*ctypes.ResultGenesis, error)
  • func (c *HTTP) NetInfo() (*ctypes.ResultNetInfo, error)
  • func (c *HTTP) Status() (*ctypes.ResultStatus, error)
  • func (c *HTTP) Tx(hash []byte, prove bool) (*ctypes.ResultTx, error)
  • func (c *HTTP) Validators() (*ctypes.ResultValidators, error)
• type HistoryClient
• type Local
  • func NewLocal(node *nm.Node) Local
  • func (c Local) ABCIInfo() (*ctypes.ResultABCIInfo, error)
  • func (c Local) ABCIQuery(path string, data []byte, prove bool) (*ctypes.ResultABCIQuery, error)
  • func (c Local) Block(height int) (*ctypes.ResultBlock, error)
  • func (c Local) BlockchainInfo(minHeight, maxHeight int) (*ctypes.ResultBlockchainInfo, error)
  • func (c Local) BroadcastTxAsync(tx types.Tx) (*ctypes.ResultBroadcastTx, error)
  • func (c Local) BroadcastTxCommit(tx types.Tx) (*ctypes.ResultBroadcastTxCommit, error)
  • func (c Local) BroadcastTxSync(tx types.Tx) (*ctypes.ResultBroadcastTx, error)
  • func (c Local) Commit(height int) (*ctypes.ResultCommit, error)
  • func (c Local) DialSeeds(seeds []string) (*ctypes.ResultDialSeeds, error)
  • func (c Local) DumpConsensusState() (*ctypes.ResultDumpConsensusState, error)
  • func (c Local) Genesis() (*ctypes.ResultGenesis, error)
  • func (c Local) NetInfo() (*ctypes.ResultNetInfo, error)
  • func (c Local) Status() (*ctypes.ResultStatus, error)
  • func (c Local) Tx(hash []byte, prove bool) (*ctypes.ResultTx, error)
  • func (c Local) Validators() (*ctypes.ResultValidators, error)
• type NetworkClient
• type SignClient
• type StatusClient
• type WSEvents
  • func (w *WSEvents) AddListenerForEvent(listenerID, event string, cb events.EventCallback)
  • func (w *WSEvents) RemoveListener(listenerID string)
  • func (w *WSEvents) RemoveListenerForEvent(event string, listenerID string)
  • func (w *WSEvents) Start() (bool, error)
  • func (w *WSEvents) Stop() bool
• type Waiter

Functions

func DefaultWaitStrategy

func DefaultWaitStrategy(delta int) (abort error)

DefaultWaitStrategy is the standard backoff algorithm, but you can plug in another one

func WaitForHeight

func WaitForHeight(c StatusClient, h int, waiter Waiter) error

Wait for height will poll status at reasonable intervals until the block at the given height is available.

If waiter is nil, we use DefaultWaitStrategy, but you can also provide your own implementation

func WaitForOneEvent

func WaitForOneEvent(evsw types.EventSwitch,
	evtTyp string, timeout time.Duration) (types.TMEventData, error)

WaitForOneEvent subscribes to a websocket event for the given event time and returns upon receiving it one time, or when the timeout duration has expired.

This handles subscribing and unsubscribing under the hood

Types

type ABCIClient

type ABCIClient interface {
	// reading from abci app
	ABCIInfo() (*ctypes.ResultABCIInfo, error)
	ABCIQuery(path string, data []byte, prove bool) (*ctypes.ResultABCIQuery, error)

	// writing to abci app
	BroadcastTxCommit(tx types.Tx) (*ctypes.ResultBroadcastTxCommit, error)
	BroadcastTxAsync(tx types.Tx) (*ctypes.ResultBroadcastTx, error)
	BroadcastTxSync(tx types.Tx) (*ctypes.ResultBroadcastTx, error)
}

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 Client

type Client interface {
	ABCIClient
	SignClient
	HistoryClient
	StatusClient

	// this Client is reactive, you can subscribe to any TMEventData
	// type, given the proper string. see tendermint/types/events.go
	types.EventSwitch
}

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 HTTP

type HTTP struct {
	*WSEvents
	// contains filtered or unexported fields
}

HTTP is a Client implementation that communicates with a tendermint node over json rpc and websockets.

This is the main implementation you probably want to use in production code. There are other implementations when calling the tendermint node in-process (local), or when you want to mock out the server for test code (mock).

func NewHTTP

func NewHTTP(remote, wsEndpoint string) *HTTP

New takes a remote endpoint in the form tcp://<host>:<port> and the websocket path (which always seems to be "/websocket")

func (*HTTP) ABCIInfo

func (c *HTTP) ABCIInfo() (*ctypes.ResultABCIInfo, error)

func (*HTTP) ABCIQuery

func (c *HTTP) ABCIQuery(path string, data []byte, prove bool) (*ctypes.ResultABCIQuery, error)

func (*HTTP) Block

func (c *HTTP) Block(height int) (*ctypes.ResultBlock, error)

func (*HTTP) BlockchainInfo

func (c *HTTP) BlockchainInfo(minHeight, maxHeight int) (*ctypes.ResultBlockchainInfo, error)

func (*HTTP) BroadcastTxAsync

func (c *HTTP) BroadcastTxAsync(tx types.Tx) (*ctypes.ResultBroadcastTx, error)

func (*HTTP) BroadcastTxCommit

func (c *HTTP) BroadcastTxCommit(tx types.Tx) (*ctypes.ResultBroadcastTxCommit, error)

func (*HTTP) BroadcastTxSync

func (c *HTTP) BroadcastTxSync(tx types.Tx) (*ctypes.ResultBroadcastTx, error)

func (*HTTP) Commit

func (c *HTTP) Commit(height int) (*ctypes.ResultCommit, error)

func (*HTTP) DumpConsensusState

func (c *HTTP) DumpConsensusState() (*ctypes.ResultDumpConsensusState, error)

func (*HTTP) Genesis

func (c *HTTP) Genesis() (*ctypes.ResultGenesis, error)

func (*HTTP) NetInfo

func (c *HTTP) NetInfo() (*ctypes.ResultNetInfo, error)

func (*HTTP) Status

func (c *HTTP) Status() (*ctypes.ResultStatus, error)

func (*HTTP) Tx

func (c *HTTP) Tx(hash []byte, prove bool) (*ctypes.ResultTx, error)

func (*HTTP) Validators

func (c *HTTP) Validators() (*ctypes.ResultValidators, error)

type HistoryClient

type HistoryClient interface {
	Genesis() (*ctypes.ResultGenesis, error)
	BlockchainInfo(minHeight, maxHeight int) (*ctypes.ResultBlockchainInfo, error)
}

HistoryClient shows us data from genesis to now in large chunks.

type Local

type Local struct {
	types.EventSwitch
	// contains filtered or unexported fields
}

Local is a Client implementation that directly executes the rpc functions on a given node, without going through HTTP or GRPC

This implementation is useful for:

* Running tests against a node in-process without the overhead of going through an http server * Communication between an ABCI app and tendermin core when they are compiled in process.

For real clients, you probably want to use client.HTTP. For more powerful control during testing, you probably want the "client/mock" package.

func NewLocal

func NewLocal(node *nm.Node) Local

NewLocal configures a client that calls the Node directly.

Note that given how rpc/core works with package singletons, that you can only have one node per process. So make sure test cases don't run in parallel, or try to simulate an entire network in one process...

func (Local) ABCIInfo

func (c Local) ABCIInfo() (*ctypes.ResultABCIInfo, error)

func (Local) ABCIQuery

func (c Local) ABCIQuery(path string, data []byte, prove bool) (*ctypes.ResultABCIQuery, error)

func (Local) Block

func (c Local) Block(height int) (*ctypes.ResultBlock, error)

func (Local) BlockchainInfo

func (c Local) BlockchainInfo(minHeight, maxHeight int) (*ctypes.ResultBlockchainInfo, error)

func (Local) BroadcastTxAsync

func (c Local) BroadcastTxAsync(tx types.Tx) (*ctypes.ResultBroadcastTx, error)

func (Local) BroadcastTxCommit

func (c Local) BroadcastTxCommit(tx types.Tx) (*ctypes.ResultBroadcastTxCommit, error)

func (Local) BroadcastTxSync

func (c Local) BroadcastTxSync(tx types.Tx) (*ctypes.ResultBroadcastTx, error)

func (Local) Commit

func (c Local) Commit(height int) (*ctypes.ResultCommit, error)

func (Local) DialSeeds

func (c Local) DialSeeds(seeds []string) (*ctypes.ResultDialSeeds, error)

func (Local) DumpConsensusState

func (c Local) DumpConsensusState() (*ctypes.ResultDumpConsensusState, error)

func (Local) Genesis

func (c Local) Genesis() (*ctypes.ResultGenesis, error)

func (Local) NetInfo

func (c Local) NetInfo() (*ctypes.ResultNetInfo, error)

func (Local) Status

func (c Local) Status() (*ctypes.ResultStatus, error)

func (Local) Tx

func (c Local) Tx(hash []byte, prove bool) (*ctypes.ResultTx, error)

func (Local) Validators

func (c Local) Validators() (*ctypes.ResultValidators, error)

type NetworkClient

type NetworkClient interface {
	NetInfo() (*ctypes.ResultNetInfo, error)
	DumpConsensusState() (*ctypes.ResultDumpConsensusState, error)
}

NetworkClient is general info about the network state. May not be needed usually.

Not included in the Client interface, but generally implemented by concrete implementations.

type SignClient

type SignClient interface {
	Block(height int) (*ctypes.ResultBlock, error)
	Commit(height int) (*ctypes.ResultCommit, error)
	Validators() (*ctypes.ResultValidators, error)
	Tx(hash []byte, prove bool) (*ctypes.ResultTx, error)
}

SignClient groups together the interfaces need to get valid signatures and prove anything about the chain

type StatusClient

type StatusClient interface {
	// general chain info
	Status() (*ctypes.ResultStatus, error)
}

type WSEvents

type WSEvents struct {
	types.EventSwitch
	// contains filtered or unexported fields
}

func (*WSEvents) AddListenerForEvent

func (w *WSEvents) AddListenerForEvent(listenerID, event string, cb events.EventCallback)

* TODO: more intelligent subscriptions! *

func (*WSEvents) RemoveListener

func (w *WSEvents) RemoveListener(listenerID string)

func (*WSEvents) RemoveListenerForEvent

func (w *WSEvents) RemoveListenerForEvent(event string, listenerID string)

func (*WSEvents) Start

func (w *WSEvents) Start() (bool, error)

Start is the only way I could think the extend OnStart from events.eventSwitch. If only it wasn't private... BaseService.Start -> eventSwitch.OnStart -> WSEvents.Start

func (*WSEvents) Stop

func (w *WSEvents) Stop() bool

Stop wraps the BaseService/eventSwitch actions as Start does

type Waiter

type Waiter func(delta int) (abort error)

Waiter is informed of current height, decided whether to quit early