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 github.com/gorilla/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 ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
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 ¶
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 ¶
Call invokes the named function, waits for it to complete, and returns its error status. See net/rpc Client.Call
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.
type FillArgser ¶
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 (*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.
Source Files
Directories