birpc

README

Bi-directional RPC library for Go, including JSON-over-WebSocket

Go library for RPC where the endpoints are peers that can both call methods on the other party. This, in combination with the included wetsock library, allows writing interactive web applications that get live notifications from the server, using JSON over WebSocket.

See a browser-to-browser chat example for a quick overview.

Use the Go import path

github.com/tv42/birpc

Documentation at http://godoc.org/github.com/tv42/birpc

Documentation

Overview

Package birpc provides access to the exported methods of an object across a network or other I/O connection. It considers the client and server peers, allowing each to call methods on the other.

Any transport can be used, by providing a suitable Codec. Codecs are provided for:

• wetsock: JSON over WebSocket (over HTTP(S))
• jsonmsg: JSON over any io.ReadWriteCloser (for example, a TCP connection)

This package was inspired by net/rpc, but is intended for more interactive applications. In particular, the wetsock transport, combined with some Javascript, makes creating interactive web applications easy. See examples/chat for a concrete example.

The RPC methods registered may take extra arguments, in addition to the usual request and response. These will be filled by birpc and the codec (see FillArgser), when possible. The following are some of the types that will be filled:

• *birpc.Endpoint: the Endpoint this method call was received on
• *websocket.Conn (as in go.net/websocket): the WebSocket this method call was received on (when using wetsock)

The types Error, Message and FillArgser are only needed if you're implementing a new Codec.

Index

• type Codec
• type Endpoint
  • func NewEndpoint(codec Codec, registry *Registry) *Endpoint
  • func (e *Endpoint) Call(function string, args interface{}, reply interface{}) 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
  • func (e Error) GoString() string
• type FillArgser
• type Message
• type Registry
  • func NewRegistry() *Registry
  • func (r *Registry) RegisterService(object interface{})

Types

type Codec

type Codec interface {
	ReadMessage(*Message) error

	// WriteMessage may be called concurrently. Codecs need to
	// protect themselves.
	WriteMessage(*Message) error

	UnmarshalArgs(msg *Message, args interface{}) error
	UnmarshalResult(msg *Message, result interface{}) error

	io.Closer
}

A Codec reads messages from the peer, and writes messages to the peer.

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 NewEndpoint

func NewEndpoint(codec Codec, 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 (*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) 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"`
}

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

func (Error) Error

func (e Error) Error() string

func (Error) GoString

func (e Error) GoString() string

type FillArgser

type FillArgser interface {
	FillArgs([]reflect.Value) error
}

FillArgser is an optional interface that a Codec may implement, in order to provide extra information to the RPC methods.

The Codec should loop over the values, and fill whatever types it recognizes.

A typical use would be allowing the RPC method to see the underlying connection, to retrieve the IP address of the peer.

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 example, 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 birpc and the codec in use.

The methods should have return type error.