README

wsrpc

Module github.com/jrick/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 module currently does not implement JSON-RPC 2.0 request batching or keyed request parameters when performing calls.

CLI

A command line tool is provided to perform individual websocket JSON-RPCs against a server.

A JSON array must be used to pass parameters in a method call.

$ wsrpc -h
usage: wsrpc address [flags] method [arg]
  -c string
        Root certificate PEM file
  -p string
        Password
  -u string
        User
$ wsrpc wss://dcrd0.i.zettaport.com:9109/ws -c dcrd0.pem -u jrick -p sekrit getinfo
{
  "version": 1050000,
  "protocolversion": 6,
  "blocks": 324795,
  "timeoffset": 0,
  "connections": 65,
  "proxy": "",
  "difficulty": 19920803496.64989,
  "testnet": false,
  "relayfee": 0.0001,
  "errors": ""
}
$ wsrpc wss://dcrd0.i.zettaport.com:9109/ws -c dcrd0.pem -u jrick -p sekrit getblockhash '[324795]'
"0000000000000000235b1210221d412c428237175dbb0aef202277d1706b9312"

The wsrpc-agent tool can be optionally used to manage persistent connections. Usage of the agent is similar to ssh-agent. The agent can exec a command, running only so long as the command continues to run, or by daemonizing and using eval to set the environment of the Bourne shell:

$ wsrpc-agent -h
usage (exec):   wsrpc-agent cmd [args...]
usage (daemon): eval $(wsrpc-agent)

Once running, wsrpc will use the WSRPCAGENT_SOCK and WSRPCAGENT_AUTH environment variables to perform IPC with the agent. TLS and RPC authentication flags only apply to the initial connection.

$ eval `wsrpc-agent`
Agent listening on /tmp/wsrpc732266934/agent.19981
$ wsrpc wss://dcrd0.i.zettaport.com:9109/ws -c dcrd0.pem -u jrick -p sekrit getblockhash '[324795]'
"0000000000000000235b1210221d412c428237175dbb0aef202277d1706b9312"
$ wsrpc wss://dcrd0.i.zettaport.com:9109/ws getblockhash '[324795]'
"0000000000000000235b1210221d412c428237175dbb0aef202277d1706b9312"

License

wsrpc is licensed under the permissive ISC License.

Expand ▾ Collapse ▴

Documentation

Overview

    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.

    Index

    Constants

    This section is empty.

    Variables

    This section is empty.

    Functions

    This section is empty.

    Types

    type Client 

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

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

      func Dial 

      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) Address 

        func (c *Client) Address() string

          Address returns the dialed network address.

          func (*Client) Call 

          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 

            func (c *Client) Close() error

              Close closes the underlying websocket connection.

              func (*Client) Err 

              func (c *Client) Err() error

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

                type DialFunc 

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

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

                  type Error 

                  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 

                    func (e *Error) Error() string

                    type Notification 

                    type Notification struct {
	Method string
	Params json.RawMessage
}

                      Notification represents a JSON-RPC notification. Method defines the type of notification and Params describes the arguments (positional or keyed) if any were included in the Request object.

                      type Notifier 

                      type Notifier chan Notification

                        Notifier is a channel of received JSON-RPC notifications. Notifications are sent in the order received. Notifier is closed after the client connection is broken. Notifications may be read from the channel after client disconnect if there is enough backpressure.

                        type Option 

                        type Option func(*options)

                          Option modifies the behavior of Dial.

                          func WithBasicAuth 

                          func WithBasicAuth(user, pass string) Option

                            WithBasicAuth enables basic access authentication using the user and password.

                            func WithDial 

                            func WithDial(dial DialFunc) Option

                              WithDial specifies a custom dial function.

                              func WithNotifier 

                              func WithNotifier(n Notifier) Option

                                WithNotifier specifies a channel to read received JSON-RPC notifications. The channel is closed when no futher notifications will be sent. Notifications may be read from the channel after the client has closed.

                                func WithTLSConfig 

                                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.

                                  Source Files

                                  View all

                                  Directories

                                  Path Synopsis
                                  cmd
                                  wsrpc
                                  wsrpc-agent