wsrpc: Index | Files

package wsrpc

import ""

Package wsrpc provides a partial implementation of a JSON-RPC 2.0 websocket client. Inspired by net/rpc, clients call methods by their name with arguments and return values marshaled by encoding/json. The client may be used to create convenience calls with types specific to an application.

Receiving notifications is supported but it is up to the caller to unmarshal the JSON-RPC parameters into meaningful data.

This package currently does not implement JSON-RPC 2.0 request batching or keyed request parameters when performing calls.


Package Files


type Client Uses

type Client struct {
    // contains filtered or unexported fields

Client implements JSON-RPC calls and notifications over a websocket.

func Dial Uses

func Dial(ctx context.Context, addr string, opts ...Option) (*Client, error)

Dial establishes an RPC client connection to the server described by addr. Addr must be the URL of the websocket, e.g., "wss://[::1]:9109/ws".

func (*Client) Call Uses

func (c *Client) Call(ctx context.Context, method string, result interface{}, args ...interface{}) (err error)

Call performs the JSON-RPC described by method with positional parameters passed through args. Result should point to an object to unmarshal the result, or equal nil to discard the result.

func (*Client) Close Uses

func (c *Client) Close() error

Close closes the underlying websocket connection.

func (*Client) Done Uses

func (c *Client) Done() <-chan struct{}

Done returns a channel that is closed after the client's final error is set.

func (*Client) Err Uses

func (c *Client) Err() error

Err blocks until the client has shutdown and returns the final error.

func (*Client) String Uses

func (c *Client) String() string

String returns the dialed websocket URL.

type DialFunc Uses

type DialFunc func(ctx context.Context, network, address string) (net.Conn, error)

DialFunc dials a network connection. Custom dialers may utilize a proxy or set connection timeouts.

type Error Uses

type Error struct {
    Code    int64           `json:"code"`
    Message string          `json:"message"`
    Data    json.RawMessage `json:"data,omitempty"`

Error represents a JSON-RPC error object.

func (*Error) Error Uses

func (e *Error) Error() string

type Notifier Uses

type Notifier interface {
    Notify(method string, params json.RawMessage) error

Notifier handles JSON-RPC notifications. Method defines the type of notification and params describes the arguments (positional or keyed) if any were included in the Request object.

Notify is never called concurrently and is called with notifications in the order received. Blocking in Notify only blocks other Notify calls and does not prevent the Client from receiving further buffered notifications and processing calls.

If Notify returns an error, the client is closed and no more notifications are processed. If this is the first error observed by the client, it will be returned by Err.

If Notifier implements io.Closer, Close is called following the final notification.

type Option Uses

type Option func(*options)

Option modifies the behavior of Dial.

func WithBasicAuth Uses

func WithBasicAuth(user, pass string) Option

WithBasicAuth enables basic access authentication using the user and password.

func WithDial Uses

func WithDial(dial DialFunc) Option

WithDial specifies a custom dial function.

func WithNotifier Uses

func WithNotifier(n Notifier) Option

WithNotifier specifies a Notifier to handle received JSON-RPC notifications. Notifications may continue to be processed after the client has closed. Notifications are dropped by Client if a Notifier is not configured.

func WithPingPeriod Uses

func WithPingPeriod(period time.Duration) Option

WithPingPeriod specifies a duration between pings sent on a timer. A pong message not received within this period (plus a tolerance) causes connection termination. A period of 0 disables the mechanism.

The default value is one minute.

func WithTLSConfig Uses

func WithTLSConfig(tls *tls.Config) Option

WithTLSConfig specifies a TLS config when connecting to a secure websocket (wss) server. If unspecified, the default TLS config will be used.

Package wsrpc imports 13 packages (graph). Updated 2019-09-11. Refresh now. Tools for package owners.