ethrpc

Documentation

Index

• Constants
• Variables
• func IsTemporaryError(err error) bool
• func RegisterApis(apis []API, modules []string, srv *Server, exposeAll bool) error
• type API
• type Client
  • func DialContext(ctx context.Context, rawurl string) (*Client, error)
  • func DialHTTP(endpoint string) (*Client, error)
  • func DialHTTPWithClient(endpoint string, client *http.Client) (*Client, error)
  • func (c *Client) Call(result interface{}, method string, args ...interface{}) error
  • func (c *Client) CallContext(ctx context.Context, result interface{}, method string, args ...interface{}) error
  • func (c *Client) Close()
• type ClientSubscription
• type Conn
• type ConnRemoteAddr
• type DataError
• type Error
• type Gauge
• type HTTPError
  • func (err HTTPError) Error() string
• type HTTPTimeouts
• type ID
• type Notifier
• type RPCService
• type Server
  • func NewServer(local common.Endpoint) (*Server, error)
  • func (s *Server) Closer() error
  • func (s *Server) Initializer() error
  • func (s *Server) RegisterName(name string, receiver interface{}) error
  • func (s *Server) ServeCodec(codec ServerCodec)
  • func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request)
  • func (s *Server) ServeListener(l net.Listener) error
  • func (s *Server) Starter() error
  • func (s *Server) Stop()
  • func (s *Server) String() string
• type ServerCodec
  • func NewCodec(conn Conn) ServerCodec
  • func NewFuncCodec(conn deadlineCloser, encode, decode func(v interface{}) error) ServerCodec
• type Subscription

Constants

const MetadataApi = "rpc"

Variables

var (
	ErrClientQuit                = errors.New("client is closed")
	ErrSubscriptionQueueOverflow = errors.New("subscription queue overflow")
	ErrNoResult                  = errors.New("no result in JSON-RPC response")
)

var (
	ErrSubscriptionNotFound     = errors.New("subscription not found")
	ErrNotificationsUnsupported = errors.New("notifications not supported")
)

var DefaultHTTPTimeouts = HTTPTimeouts{
	ReadTimeout:  30 * time.Second,
	WriteTimeout: 30 * time.Second,
	IdleTimeout:  120 * time.Second,
}

DefaultHTTPTimeouts represents the default timeout values used if further configuration is not provided.

Functions

func IsTemporaryError

func IsTemporaryError(err error) bool

IsTemporaryError checks whether the given error should be considered temporary.

func RegisterApis

func RegisterApis(apis []API, modules []string, srv *Server, exposeAll bool) error

RegisterApis checks the given modules' availability, generates an allowlist based on the allowed modules, and then registers all of the APIs exposed by the services.

Types

type API

type API struct {
	Namespace string      // namespace under which the rpc methods of Service are exposed
	Version   string      // api version for DApp's
	Service   interface{} // receiver instance which holds the methods
	Public    bool        // indication if the methods must be considered safe for public use
}

API describes the set of methods offered over the RPC interface

type Client

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

Client represents a connection to an RPC server.

func DialContext

func DialContext(ctx context.Context, rawurl string) (*Client, error)

DialContext creates a new RPC client, just like Dial.

The context is used to cancel or time out the initial connection establishment. It does not affect subsequent interactions with the client.

func DialHTTP

func DialHTTP(endpoint string) (*Client, error)

DialHTTP creates a new RPC client that connects to an RPC server over HTTP.

func DialHTTPWithClient

func DialHTTPWithClient(endpoint string, client *http.Client) (*Client, error)

DialHTTPWithClient creates a new RPC client that connects to an RPC server over HTTP using the provided HTTP Client.

func (*Client) Call

func (c *Client) Call(result interface{}, 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.

func (*Client) CallContext

func (c *Client) CallContext(ctx context.Context, result interface{}, 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.

func (*Client) Close

func (c *Client) Close()

Close closes the client, aborting any in-flight requests.

type ClientSubscription

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

ClientSubscription is a subscription established through the Client's Subscribe or EthSubscribe methods.

type Conn

type Conn interface {
	io.ReadWriteCloser
	SetWriteDeadline(time.Time) error
}

Conn is a subset of the methods of net.Conn which are sufficient for ServerCodec.

type ConnRemoteAddr

type ConnRemoteAddr interface {
	RemoteAddr() string
}

ConnRemoteAddr wraps the RemoteAddr operation, which returns a description of the peer address of a connection. If a Conn also implements ConnRemoteAddr, this description is used in log messages.

type DataError

type DataError interface {
	Error() string          // returns the message
	ErrorData() interface{} // returns the error data
}

A DataError contains some data in addition to the error message.

type Error

type Error interface {
	Error() string  // returns the message
	ErrorCode() int // returns the code
}

Error wraps RPC errors, which contain an error code in addition to the message.

type Gauge

type Gauge interface {
	Snapshot() Gauge
	Update(int64)
	Dec(int64)
	Inc(int64)
	Value() int64
}

type HTTPError

type HTTPError struct {
	StatusCode int
	Status     string
	Body       []byte
}

HTTPError is returned by client operations when the HTTP status code of the response is not a 2xx status.

func (HTTPError) Error

func (err HTTPError) Error() string

type HTTPTimeouts

type HTTPTimeouts struct {
	// ReadTimeout is the maximum duration for reading the entire
	// request, including the body.
	//
	// Because ReadTimeout does not let Handlers make per-request
	// decisions on each request body's acceptable deadline or
	// upload rate, most users will prefer to use
	// ReadHeaderTimeout. It is valid to use them both.
	ReadTimeout time.Duration

	// WriteTimeout is the maximum duration before timing out
	// writes of the response. It is reset whenever a new
	// request's header is read. Like ReadTimeout, it does not
	// let Handlers make decisions on a per-request basis.
	WriteTimeout time.Duration

	// IdleTimeout is the maximum amount of time to wait for the
	// next request when keep-alives are enabled. If IdleTimeout
	// is zero, the value of ReadTimeout is used. If both are
	// zero, ReadHeaderTimeout is used.
	IdleTimeout time.Duration
}

HTTPTimeouts represents the configuration params for the HTTP RPC server.

type ID

type ID string

ID defines a pseudo random number that is used to identify RPC subscriptions.

type Notifier

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

Notifier is tied to a RPC connection that supports subscriptions. Server callbacks use the notifier to send notifications.

type RPCService

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

RPCService gives meta information about the server. e.g. gives information about the loaded modules.

type Server

type Server struct {
	common.AbstractService
	// contains filtered or unexported fields
}

Server is an RPC server.

func NewServer

func NewServer(local common.Endpoint) (*Server, error)

NewServer creates a new server instance with no registered handlers.

func (*Server) Closer

func (s *Server) Closer() error

func (*Server) Initializer

func (s *Server) Initializer() error

func (*Server) RegisterName

func (s *Server) RegisterName(name string, receiver interface{}) error

RegisterName creates a service for the given receiver type under the given name. When no methods on the given receiver match the criteria to be either a RPC method or a subscription an error is returned. Otherwise a new service is created and added to the service collection this server provides to clients.

func (*Server) ServeCodec

func (s *Server) ServeCodec(codec ServerCodec)

ServeCodec reads incoming requests from codec, calls the appropriate callback and writes the response back using the given codec. It will block until the codec is closed or the server is stopped. In either case the codec is closed.

Note that codec options are no longer supported.

func (*Server) ServeHTTP

func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP serves JSON-RPC requests over HTTP.

func (*Server) ServeListener

func (s *Server) ServeListener(l net.Listener) error

ServeListener accepts connections on l, serving JSON-RPC on them.

func (*Server) Starter

func (s *Server) Starter() error

func (*Server) Stop

func (s *Server) Stop()

Stop stops reading new requests, waits for stopPendingRequestTimeout to allow pending requests to finish, then closes all codecs which will cancel pending requests and subscriptions.

func (*Server) String

func (s *Server) String() string

type ServerCodec

type ServerCodec interface {
	// contains filtered or unexported methods
}

func NewCodec

func NewCodec(conn Conn) ServerCodec

NewCodec creates a codec on the given connection. If conn implements ConnRemoteAddr, log messages will use it to include the remote address of the connection.

func NewFuncCodec

func NewFuncCodec(conn deadlineCloser, encode, decode func(v interface{}) error) ServerCodec

NewFuncCodec creates a codec which uses the given functions to read and write. If conn implements ConnRemoteAddr, log messages will use it to include the remote address of the connection.

type Subscription

type Subscription struct {
	ID ID
	// contains filtered or unexported fields
}

A Subscription is created by a notifier and tied to that notifier. The client can use this subscription to wait for an unsubscribe request for the client, see Err().