component

Documentation

Index

• Variables
• func IpcListen(endpoint string) (net.Listener, error)
• func NewHTTPServer(cors []string, vhosts []string, timeouts rpcTypes.HTTPTimeouts, ...) *http.Server
• func NewWSServer(allowedOrigins []string, srv *rpcTypes.Server) *http.Server
• type BatchElem
• type Client
  • func Dial(rawurl string) (*Client, error)
  • 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 DialIPC(ctx context.Context, endpoint string) (*Client, error)
  • func DialInProc(handler *rpcTypes.Server) *Client
  • func DialStdIO(ctx context.Context) (*Client, error)
  • func DialWebsocket(ctx context.Context, endpoint, origin string) (*Client, error)
  • func (c *Client) BatchCall(b []BatchElem) error
  • func (c *Client) BatchCallContext(ctx context.Context, b []BatchElem) 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()
  • func (c *Client) EthSubscribe(ctx context.Context, channel interface{}, args ...interface{}) (*ClientSubscription, error)
  • func (c *Client) ShhSubscribe(ctx context.Context, channel interface{}, args ...interface{}) (*ClientSubscription, error)
  • func (c *Client) Subscribe(ctx context.Context, namespace string, channel interface{}, ...) (*ClientSubscription, error)
  • func (c *Client) SupportedModules() (map[string]string, error)
• type ClientSubscription
  • func (sub *ClientSubscription) Err() <-chan error
  • func (sub *ClientSubscription) Unsubscribe()
• type RestController
  • func StartRest(apiDesc rpcTypes.RestDescription) *RestController
  • func (controller *RestController) Stop()

Variables

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

var DefaultHTTPTimeouts = rpcTypes.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 IpcListen

func IpcListen(endpoint string) (net.Listener, error)

ipcListen will create a Unix socket on the given endpoint.

func NewHTTPServer

func NewHTTPServer(cors []string, vhosts []string, timeouts rpcTypes.HTTPTimeouts, srv *rpcTypes.Server) *http.Server

NewHTTPServer creates a new HTTP RPC server around an API provider.

Deprecated: Server implements http.Handler

func NewWSServer

func NewWSServer(allowedOrigins []string, srv *rpcTypes.Server) *http.Server

NewWSServer creates a new websocket RPC server around an API provider. Deprecated: use Server.WebsocketHandler

Types

type BatchElem

type BatchElem struct {
	Method string
	Args   []interface{}
	// The result is unmarshaled into this field. Result must be set to a
	// non-nil pointer value of the desired type, otherwise the response will be
	// discarded.
	Result interface{}
	// Error is set if the server returns an error for this request, or if
	// unmarshaling into Result fails. It is not set for I/O errors.
	Error error
}

BatchElem is an element in a batch request.

type Client

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

Client represents a connection to an RPC server.

func Dial

func Dial(rawurl string) (*Client, error)

Dial creates a new client for the given URL.

The currently supported URL schemes are "http", "https", "ws" and "wss". If rawurl is a file name with no URL scheme, a local socket connection is established using UNIX domain sockets on supported platforms and named pipes on Windows. If you want to configure transport options, use DialHTTP, DialWebsocket or DialIPC instead.

For websocket connections, the origin is set to the local host name.

The client reconnects automatically if the connection is lost.

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 DialIPC

func DialIPC(ctx context.Context, endpoint string) (*Client, error)

DialIPC create a new IPC client that connects to the given endpoint. On Unix it assumes the endpoint is the full path to a unix socket, and Windows the endpoint is an identifier for a named pipe.

The context is used for the initial connection establishment. It does not affect subsequent interactions with the client.

func DialInProc

func DialInProc(handler *rpcTypes.Server) *Client

DialInProc attaches an in-process connection to the given RPC server.

func DialStdIO

func DialStdIO(ctx context.Context) (*Client, error)

DialStdIO creates a client on stdin/stdout.

func DialWebsocket

func DialWebsocket(ctx context.Context, endpoint, origin string) (*Client, error)

DialWebsocket creates a new RPC client that communicates with a JSON-RPC server that is listening on the given endpoint.

The context is used for the initial connection establishment. It does not affect subsequent interactions with the client.

func (*Client) BatchCall

func (c *Client) BatchCall(b []BatchElem) error

BatchCall sends all given requests as a single batch and waits for the server to return a response for all of them.

In contrast to Call, BatchCall only returns I/O errors. Any error specific to a request is reported through the Error field of the corresponding BatchElem.

Note that batch calls may not be executed atomically on the server side.

func (*Client) BatchCallContext

func (c *Client) BatchCallContext(ctx context.Context, b []BatchElem) error

BatchCall sends all given requests as a single batch and waits for the server to return a response for all of them. The wait duration is bounded by the context's deadline.

In contrast to CallContext, BatchCallContext only returns errors that have occurred while sending the request. Any error specific to a request is reported through the Error field of the corresponding BatchElem.

Note that batch calls may not be executed atomically on the server side.

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.

func (*Client) EthSubscribe

func (c *Client) EthSubscribe(ctx context.Context, channel interface{}, args ...interface{}) (*ClientSubscription, error)

EthSubscribe registers a subscripion under the "eth" namespace.

func (*Client) ShhSubscribe

func (c *Client) ShhSubscribe(ctx context.Context, channel interface{}, args ...interface{}) (*ClientSubscription, error)

ShhSubscribe registers a subscripion under the "shh" namespace.

func (*Client) Subscribe

func (c *Client) Subscribe(ctx context.Context, namespace string, channel interface{}, args ...interface{}) (*ClientSubscription, error)

Subscribe calls the "<namespace>_subscribe" method with the given arguments, registering a subscription. Server notifications for the subscription are sent to the given channel. The element type of the channel must match the expected type of content returned by the subscription.

The context argument cancels the RPC request that sets up the subscription but has no effect on the subscription after Subscribe has returned.

Slow subscribers will be dropped eventually. Client buffers up to 8000 notifications before considering the subscriber dead. The subscription Err channel will receive ErrSubscriptionQueueOverflow. Use a sufficiently large buffer on the channel or ensure that the channel usually has at least one reader to prevent this issue.

func (*Client) SupportedModules

func (c *Client) SupportedModules() (map[string]string, error)

SupportedModules calls the rpc_modules method, retrieving the list of APIs that are available on the server.

type ClientSubscription

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

A ClientSubscription represents a subscription established through EthSubscribe.

func (*ClientSubscription) Err

func (sub *ClientSubscription) Err() <-chan error

Err returns the subscription error channel. The intended use of Err is to schedule resubscription when the client connection is closed unexpectedly.

The error channel receives a value when the subscription has ended due to an error. The received error is nil if Close has been called on the underlying client and no other error has occurred.

The error channel is closed when Unsubscribe is called on the subscription.

func (*ClientSubscription) Unsubscribe

func (sub *ClientSubscription) Unsubscribe()

Unsubscribe unsubscribes the notification and closes the error channel. It can safely be called more than once.

type RestController

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

func StartRest

func StartRest(apiDesc rpcTypes.RestDescription) *RestController

func (*RestController) Stop

func (controller *RestController) Stop()