rpc

Documentation

Index

• Constants
• func BuildJsonHTTPRequest(ctx context.Context, url, method string, parameters ...interface{}) (*http.Request, error)
• func BuildJsonHttpRequestWithBody(ctx context.Context, url string, reqBody []byte) (*http.Request, error)
• type Config
• type DB
• type DBTxManager
  • func (f *DBTxManager) NewDbTxScope(db DB, scopedFn DBTxScopedFn) (interface{}, Error)
• type DBTxScopedFn
• type Error
  • func RPCErrorResponse(code int, message string, err error) (interface{}, Error)
  • func RPCErrorResponseWithData(code int, message string, data *[]byte, err error) (interface{}, Error)
• type ErrorObject
• type Handler
  • func (h *Handler) Handle(req handleRequest) Response
  • func (h *Handler) HandleWs(reqBody []byte, wsConn *websocket.Conn, httpReq *http.Request) ([]byte, error)
• type Option
  • func WithHealthHandler(h http.Handler) Option
  • func WithLogger(zapLogger *zap.SugaredLogger) Option
• type RPCError
  • func NewRPCError(code int, err string, args ...interface{}) *RPCError
  • func NewRPCErrorWithData(code int, err string, data *[]byte, args ...interface{}) *RPCError
  • func (e *RPCError) Error() string
  • func (e *RPCError) ErrorCode() int
  • func (e *RPCError) ErrorData() *[]byte
• type Request
• type Response
  • func JSONRPCCall(url, method string, params ...interface{}) (Response, error)
  • func JSONRPCCallWithContext(ctx context.Context, url, method string, parameters ...interface{}) (Response, error)
  • func NewResponse(req Request, reply []byte, err Error) Response
  • func (s Response) Bytes() ([]byte, error)
• type Server
  • func NewServer(cfg Config, services []Service, opts ...Option) *Server
  • func (s *Server) Start() error
  • func (s *Server) Stop() error
• type Service

Constants

const (
	// DefaultErrorCode rpc default error code
	DefaultErrorCode = -32000
	// RevertedErrorCode error code for reverted txs
	RevertedErrorCode = 3
	// InvalidRequestErrorCode error code for invalid requests
	InvalidRequestErrorCode = -32600
	// NotFoundErrorCode error code for not found objects
	NotFoundErrorCode = -32601
	// InvalidParamsErrorCode error code for invalid parameters
	InvalidParamsErrorCode = -32602
	// ParserErrorCode error code for parsing errors
	ParserErrorCode = -32700
	// AccessDeniedCode error code when requests are denied
	AccessDeniedCode = -32800
)

Functions

func BuildJsonHTTPRequest

func BuildJsonHTTPRequest(ctx context.Context, url, method string, parameters ...interface{}) (*http.Request, error)

BuildJsonHTTPRequest creates JSON RPC http request using provided url, method and parameters

func BuildJsonHttpRequestWithBody

func BuildJsonHttpRequestWithBody(ctx context.Context, url string, reqBody []byte) (*http.Request, error)

BuildJsonHttpRequestWithBody creates JSON RPC http request using provided url and request body

Types

type Config

type Config struct {
	// Host defines the network adapter that will be used to serve the HTTP requests
	Host string `mapstructure:"Host"`

	// Port defines the port to serve the endpoints via HTTP
	Port int `mapstructure:"Port"`

	// ReadTimeout is the HTTP server read timeout
	// check net/http.server.ReadTimeout and net/http.server.ReadHeaderTimeout
	ReadTimeout types.Duration `mapstructure:"ReadTimeout"`

	// WriteTimeout is the HTTP server write timeout
	// check net/http.server.WriteTimeout
	WriteTimeout types.Duration `mapstructure:"WriteTimeout"`

	// MaxRequestsPerIPAndSecond defines how much requests a single IP can
	// send within a single second
	MaxRequestsPerIPAndSecond float64 `mapstructure:"MaxRequestsPerIPAndSecond"`
}

Config represents the configuration of the json rpc

type DB

type DB interface {
	BeginStateTransaction(ctx context.Context) (dbTx, error)
}

DB defines functions that a DB instance should implement

type DBTxManager

type DBTxManager struct{}

DBTxManager allows to do scopped DB txs

func (*DBTxManager) NewDbTxScope

func (f *DBTxManager) NewDbTxScope(db DB, scopedFn DBTxScopedFn) (interface{}, Error)

NewDbTxScope function to initiate DB scopped txs

type DBTxScopedFn

type DBTxScopedFn func(ctx context.Context, dbTx dbTx) (interface{}, Error)

DBTxScopedFn function to do scopped DB txs

type Error

type Error interface {
	Error() string
	ErrorCode() int
	ErrorData() *[]byte
}

Error interface

func RPCErrorResponse

func RPCErrorResponse(code int, message string, err error) (interface{}, Error)

RPCErrorResponse formats error to be returned through RPC

func RPCErrorResponseWithData

func RPCErrorResponseWithData(code int, message string, data *[]byte, err error) (interface{}, Error)

RPCErrorResponseWithData formats error to be returned through RPC

type ErrorObject

type ErrorObject struct {
	Code    int             `json:"code"`
	Message string          `json:"message"`
	Data    *types.ArgBytes `json:"data,omitempty"`
}

ErrorObject is a jsonrpc error

type Handler

type Handler struct {
	// contains filtered or unexported fields
}

Handler manage services to handle jsonrpc requests

Services are public structures containing public methods matching the name of the jsonrpc method.

Services must be registered with a prefix to identify the service and its methods, for example a service registered with a prefix `eth` will have all the public methods exposed as eth_<methodName> through the json rpc server.

Go public methods requires the first char of its name to be in uppercase, but the exposition of the method will consider it to lower case, for example a method `func MyMethod()` provided by the service registered with `eth` prefix will be triggered when the method eth_myMethod is specified

the public methods must follow the conventions: - return interface{}, rpcError - if the method depend on a Web Socket connection, it must be the first parameters as f(*websocket.Conn) - parameter types must match the type of the data provided for the method

check the `eth.go` file for more example on how the methods are implemented

func (*Handler) Handle

func (h *Handler) Handle(req handleRequest) Response

Handle is the function that knows which and how a function should be executed when a JSON RPC request is received

func (*Handler) HandleWs

func (h *Handler) HandleWs(reqBody []byte, wsConn *websocket.Conn, httpReq *http.Request) ([]byte, error)

HandleWs handle websocket requests

type Option

type Option func(*Server)

func WithHealthHandler

func WithHealthHandler(h http.Handler) Option

func WithLogger

func WithLogger(zapLogger *zap.SugaredLogger) Option

type RPCError

type RPCError struct {
	// contains filtered or unexported fields
}

RPCError represents an error returned by a JSON RPC endpoint.

func NewRPCError

func NewRPCError(code int, err string, args ...interface{}) *RPCError

NewRPCError creates a new error instance to be returned by the RPC endpoints

func NewRPCErrorWithData

func NewRPCErrorWithData(code int, err string, data *[]byte, args ...interface{}) *RPCError

NewRPCErrorWithData creates a new error instance with data to be returned by the RPC endpoints

func (*RPCError) Error

func (e *RPCError) Error() string

Error returns the error message.

func (*RPCError) ErrorCode

func (e *RPCError) ErrorCode() int

ErrorCode returns the error code.

func (*RPCError) ErrorData

func (e *RPCError) ErrorData() *[]byte

ErrorData returns the error data.

type Request

type Request struct {
	JSONRPC string          `json:"jsonrpc"`
	ID      interface{}     `json:"id"`
	Method  string          `json:"method"`
	Params  json.RawMessage `json:"params,omitempty"`
}

Request is a jsonrpc request

type Response

type Response struct {
	JSONRPC string          `json:"jsonrpc"`
	ID      interface{}     `json:"id"`
	Result  json.RawMessage `json:"result"`
	Error   *ErrorObject    `json:"error"`
}

Response is a jsonrpc success response

func JSONRPCCall

func JSONRPCCall(url, method string, params ...interface{}) (Response, error)

JSONRPCCall calls JSONRPCCallWithContext with the default context

func JSONRPCCallWithContext

func JSONRPCCallWithContext(ctx context.Context, url, method string, parameters ...interface{}) (Response, error)

JSONRPCCallWithContext executes a 2.0 JSON RPC HTTP Post Request to the provided URL with the provided method and parameters, which is compatible with the Ethereum JSON RPC Server.

func NewResponse

func NewResponse(req Request, reply []byte, err Error) Response

NewResponse returns Success/Error response object

func (Response) Bytes

func (s Response) Bytes() ([]byte, error)

Bytes return the serialized response

type Server

type Server struct {
	// contains filtered or unexported fields
}

Server is an API backend to handle RPC requests

func NewServer

func NewServer(
	cfg Config,
	services []Service,
	opts ...Option,
) *Server

NewServer returns the JsonRPC server

func (*Server) Start

func (s *Server) Start() error

Start initializes the JSON RPC server to listen for request

func (*Server) Stop

func (s *Server) Stop() error

Stop shutdown the rpc server

type Service

type Service struct {
	Name    string
	Service interface{}
}

Service implementation of a service an it's name