ws_rpc

README

Websocket JSON-RPC implementation for Go

Code base github.com/tv42/birpc

Documentation

Index

• type Endpoint
  • func NewClient(urlStr string, header http.Header) (*Endpoint, error)
  • func NewEndpoint(conn *websocket.Conn, registry *Registry) *Endpoint
  • func NewServer(conn *websocket.Conn, registry *Registry) *Endpoint
  • func (e *Endpoint) Call(function string, args interface{}, reply interface{}) error
  • func (e *Endpoint) Close() error
  • func (e *Endpoint) Go(function string, args interface{}, reply interface{}, done chan *rpc.Call) *rpc.Call
  • func (e *Endpoint) Serve() error
• type Error
  • func (e Error) Error() string
• type Message
• type Registry
  • func NewRegistry() *Registry
  • func (r *Registry) RegisterService(object interface{})

Types

type Endpoint

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

Endpoint manages the state for one connection (via a Codec) and the pending calls on it, both incoming and outgoing.

func NewClient

func NewClient(urlStr string, header http.Header) (*Endpoint, error)

func NewEndpoint

func NewEndpoint(conn *websocket.Conn, registry *Registry) *Endpoint

NewEndpoint creates a new endpoint that uses codec to talk to a peer. To actually process messages, call endpoint.Serve; this is done so you can capture errors. Registry can be nil to serve no callables from this peer.

func NewServer

func NewServer(conn *websocket.Conn, registry *Registry) *Endpoint

func (*Endpoint) Call

func (e *Endpoint) Call(function string, args interface{}, reply interface{}) error

Call invokes the named function, waits for it to complete, and returns its error status. See net/rpc Client.Call

func (*Endpoint) Close

func (e *Endpoint) Close() error

func (*Endpoint) Go

func (e *Endpoint) Go(function string, args interface{}, reply interface{}, done chan *rpc.Call) *rpc.Call

Go invokes the function asynchronously. See net/rpc Client.Go.

func (*Endpoint) Serve

func (e *Endpoint) Serve() error

Serve messages from this connection. Serve blocks, serving the connection until the client disconnects, or there is an error.

type Error

type Error struct {
	Msg string `json:"msg,omitempty"`

	Code int64 `json:"code"`

	Data json.RawMessage `json:data,omitempty`
}

Error is the on-wire description of an error that occurred while serving the method call.

func (Error) Error

func (e Error) Error() string

type Message

type Message struct {
	// 0 or omitted for untagged request (untagged response is illegal).
	ID uint64 `json:"id,string,omitempty"`

	// Name of the function to call. If set, this is a request; if
	// unset, this is a response.
	Func string `json:"fn,omitempty"`

	// Arguments for the RPC call. Only valid for a request.
	Args interface{} `json:"args,omitempty"`

	// Result of the function call. A response will always have
	// either Result or Error set. Only valid for a response.
	Result interface{} `json:"result,omitempty"`

	// Information on how the call failed. Only valid for a
	// response. Must be present if Result is omitted.
	Error *Error `json:"error,omitempty"`
}

Message is the on-wire description of a method call or result.

Examples:

{"id":"1","fn":"Arith.Add","args":{"A":1,"B":1}}
{"id":"1","result":{"C":2}}

or

{"id":"1","error":{"msg":"Math is hard, let's go shopping"}}

type Registry

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

Registry is a collection of services have methods that can be called remotely. Each method has a name in the format SERVICE.METHOD.

A single Registry is intended to be used with multiple Endpoints. This separation exists as registering services can be a slow operation.

func NewRegistry

func NewRegistry() *Registry

NewRegistry creates a new Registry.

func (*Registry) RegisterService

func (r *Registry) RegisterService(object interface{})

RegisterService registers all exported methods of service, allowing them to be called remotely. The name of the methods will be of the format SERVICE.METHOD, where SERVICE is the type name or the object passed in, and METHOD is the name of each method.

The methods are expect to have at least two arguments, referred to as args and reply. Reply should be a pointer type, and the method should fill it with the result. The types used are limited only by the codec needing to be able to marshal them for transport. For examples, for wetsock the args and reply must marshal to JSON.

Rest of the arguments are filled on best-effort basis, if their types are known to ws_rpc and the codec in use.

The methods should have return type error.