rpc

README

rpc

Package rpc - JSON-RPC client with custom routing.

Download:

go get github.com/status-im/status-go/rpc

---

Package rpc - JSON-RPC client with custom routing.

Package rpc implements status-go JSON-RPC client and handles requests to different endpoints: upstream or local node.

Every JSON-RPC request coming from either JS code or any other part of status-go should use this package to be handled and routed properly.

Routing rules are following:

• if Upstream is disabled, everything is routed to local ethereum-go node
• otherwise, some requests (from the list, see below) are routed to upstream, others - locally.

List of methods to be routed is currently available here: https://docs.google.com/spreadsheets/d/1N1nuzVN5tXoDmzkBLeC9_mwIlVH8DGF7YD2XwxA8BAE/edit#gid=0

Note, upon creation of a new client, it ok to be offline - client will keep trying to reconnect in background.

---

Automatically generated by autoreadme on 2017.09.18

Documentation

Overview

Package rpc - JSON-RPC client with custom routing.

Package rpc implements status-go JSON-RPC client and handles requests to different endpoints: upstream or local node.

Every JSON-RPC request coming from either JS code or any other part of status-go should use this package to be handled and routed properly.

Routing rules are following:

- if Upstream is disabled, everything is routed to local ethereum-go node - otherwise, some requests (from the list, see below) are routed to upstream, others - locally.

List of methods to be routed is currently available here: https://docs.google.com/spreadsheets/d/1N1nuzVN5tXoDmzkBLeC9_mwIlVH8DGF7YD2XwxA8BAE/edit#gid=0

Note, upon creation of a new client, it ok to be offline - client will keep trying to reconnect in background.

Index

• Constants
• Variables
• func BlockedMethods() []string
• type Client
  • func NewClient(client *gethrpc.Client, upstreamChainID uint64, ...) (*Client, error)
  • func (c *Client) AbstractEthClient(chainID common.ChainID) (chain.BatchCallClient, error)
  • func (c *Client) Call(result interface{}, chainID uint64, method string, args ...interface{}) error
  • func (c *Client) CallContext(ctx context.Context, result interface{}, chainID uint64, method string, ...) error
  • func (c *Client) CallContextIgnoringLocalHandlers(ctx context.Context, result interface{}, chainID uint64, method string, ...) error
  • func (c *Client) CallRaw(body string) string
  • func (c *Client) EthClient(chainID uint64) (chain.ClientInterface, error)
  • func (c *Client) EthClients(chainIDs []uint64) (map[uint64]chain.ClientInterface, error)
  • func (c *Client) RegisterHandler(method string, handler Handler)
  • func (c *Client) SetClient(chainID uint64, client chain.ClientInterface)
  • func (c *Client) SetWalletNotifier(notifier func(chainID uint64, message string))
  • func (c *Client) UnregisterHandler(method string)
  • func (c *Client) UpdateUpstreamURL(url string) error
• type ClientInterface
• type Handler

Constants

const (
	// DefaultCallTimeout is a default timeout for an RPC call
	DefaultCallTimeout = time.Minute
)

Variables

var (
	ErrMethodNotFound = fmt.Errorf("The method does not exist/is not available")
)

List of RPC client errors.

Functions

func BlockedMethods

func BlockedMethods() []string

BlockedMethods returns a list of methods that are not allowed to be called. A copy of a slice is returned in order to prevent from changing it from outside.

Types

type Client

type Client struct {
	sync.RWMutex

	UpstreamChainID uint64

	NetworkManager *network.Manager
	// contains filtered or unexported fields
}

Client represents RPC client with custom routing scheme. It automatically decides where RPC call goes - Upstream or Local node.

func NewClient

func NewClient(client *gethrpc.Client, upstreamChainID uint64, upstream params.UpstreamRPCConfig, networks []params.Network, db *sql.DB) (*Client, error)

NewClient initializes Client and tries to connect to both, upstream and local node.

Client is safe for concurrent use and will automatically reconnect to the server if connection is lost.

func (*Client) AbstractEthClient

func (c *Client) AbstractEthClient(chainID common.ChainID) (chain.BatchCallClient, error)

AbstractEthClient returns a partial abstraction used by new components for testing purposes

func (*Client) Call

func (c *Client) Call(result interface{}, chainID uint64, method string, args ...interface{}) error

Call performs a JSON-RPC call with the given arguments and unmarshals into result if no error occurred.

The result must be a pointer so that package json can unmarshal into it. You can also pass nil, in which case the result is ignored.

It uses custom routing scheme for calls.

func (*Client) CallContext

func (c *Client) CallContext(ctx context.Context, result interface{}, chainID uint64, method string, args ...interface{}) error

CallContext performs a JSON-RPC call with the given arguments. If the context is canceled before the call has successfully returned, CallContext returns immediately.

The result must be a pointer so that package json can unmarshal into it. You can also pass nil, in which case the result is ignored.

It uses custom routing scheme for calls. If there are any local handlers registered for this call, they will handle it.

func (*Client) CallContextIgnoringLocalHandlers

func (c *Client) CallContextIgnoringLocalHandlers(ctx context.Context, result interface{}, chainID uint64, method string, args ...interface{}) error

CallContextIgnoringLocalHandlers performs a JSON-RPC call with the given arguments.

If there are local handlers registered for this call, they would be ignored. It is useful if the call is happening from within a local handler itself. Upstream calls routing will be used anyway.

func (*Client) CallRaw

func (c *Client) CallRaw(body string) string

CallRaw performs a JSON-RPC call with already crafted JSON-RPC body. It returns string in JSON format with response (successul or error).

func (*Client) EthClient

func (c *Client) EthClient(chainID uint64) (chain.ClientInterface, error)

Ethclient returns ethclient.Client per chain

func (*Client) EthClients

func (c *Client) EthClients(chainIDs []uint64) (map[uint64]chain.ClientInterface, error)

func (*Client) RegisterHandler

func (c *Client) RegisterHandler(method string, handler Handler)

RegisterHandler registers local handler for specific RPC method.

If method is registered, it will be executed with given handler and never routed to the upstream or local servers.

func (*Client) SetClient

func (c *Client) SetClient(chainID uint64, client chain.ClientInterface)

SetClient strictly for testing purposes

func (*Client) SetWalletNotifier

func (c *Client) SetWalletNotifier(notifier func(chainID uint64, message string))

func (*Client) UnregisterHandler

func (c *Client) UnregisterHandler(method string)

UnregisterHandler removes a previously registered handler.

func (*Client) UpdateUpstreamURL

func (c *Client) UpdateUpstreamURL(url string) error

UpdateUpstreamURL changes the upstream RPC client URL, if the upstream is enabled.

type ClientInterface

type ClientInterface interface {
	AbstractEthClient(chainID common.ChainID) (chain.BatchCallClient, error)
}

type Handler

type Handler func(context.Context, uint64, ...interface{}) (interface{}, error)

Handler defines handler for RPC methods.