Documentation
¶
Overview ¶
Package rpc implements a simple RPC system for Go methods. Rpc can dispatch methods on any Go value of the form:
Func(ctx context.Context, arg argType, reply *replyType) error
By default, the values are Gob-encoded, with the following exceptions:
- if argType is io.Reader, a direct byte stream is provided
- if replyType is io.ReadCloser, a direct byte stream is provided
In the future, the package will also support custom codecs, so that, for example, if the argument or reply is generated by a protocol buffer, then protocol buffer encoding is used automatically.
Every value is registered with a name. This name is used by the client to specify the object on which to dispatch methods.
Rpc uses HTTP as its transport protocol: the RPC server implements an HTTP handler, and exports an HTTP endpoint for each method that is served. Similarly, the RPC client composes a HTTP client and constructs the appropriate URLs on dispatch.
Each method registered by a server receives its own URL endpoint: Service.Method. Calls to a method are performed as HTTP POST requests to that method's endpoint. The HTTP body contains a gob-encoded (package encoding/gob) stream of data interpreted as the method's argument. In the case where the method's argument is an io.Reader, the body instead passed through. The reply body contains the reply, also gob-encoded, except when the reply has type io.ReadCloser in which case the body is passed through and streamed end-to-end.
On successful invocation, HTTP code 200 is returned. When a method invocation returns an error, HTTP code 590 is returned. In this case, the error message is gob-encoded as the reply body.
At the moment, a new gob encoder is created for each call. This is inefficient for small requests and replies. Future work includes maintaining long-running gob codecs to avoid these inefficiences.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var InjectFailures = false
InjectFailures causes HTTP responses to be randomly terminated. Only for unittesting.
Functions ¶
func Flush ¶
func Flush(rc io.ReadCloser) io.ReadCloser
Flush wraps the provided ReadCloser to instruct the rpc server to flush after every write. This is useful when the reply stream should be interactive -- no guarantees are otherwise provided about buffering.
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
A Client invokes remote methods on RPC servers.
func NewClient ¶
NewClient creates a new RPC client. clientFactory is called to create a new http.Client object. It may be called repeatedly and concurrently. prefix is prepended to the service method when constructing an URL.
func (*Client) Call ¶
func (c *Client) Call(ctx context.Context, addr, serviceMethod string, arg, reply interface{}) (err error)
Call invokes a method on the server named by the provided address. The method syntax is "Service.Method": Service is the name of the registered service; Method names the method to invoke.
The argument and reply are encoded in accordance with the description of the package docs.
If the argument is an io.Reader, it is streamed directly to the server method. In this case, Call does not return until the data are fully streamed. If the reply is an *io.ReadCloser, the reply is streamed directly from the server method. In this case, Call returns once the stream is available, and the client is responsible for fully reading the data and closing the reader. If an error occurs while the response is streamed, the returned io.ReadCloser errors on read.
If the argument is a (func () io.Reader), it is called to get a reader streamed directly to the server method as above. This is mostly useful when using Call in a retry loop, as you often want to create a new reader for each call, as opposed to continuing from whatever unknown state remains from previously attempted calls.
Remote errors are decoded into *errors.Error and returned. (Non-*errors.Error errors are converted by the server.) The RPC client does not pass on errors of kind errors.Net; these are converted to errors.Other. This way, any error of the kind errors.Net is guaranteed to originate from the immediate call; they are never from the application.
type Server ¶
type Server struct {
// contains filtered or unexported fields
}
A Server dispatches methods on collection of registered objects. Its dispatch rules are described in the package docs. Server implements http.Handler and can be served by any HTTP server.
func (*Server) Register ¶
Register registers the provided interface under the given name. Exported and eligible methods on iface, according to the rules described in the package docs, are invoked by this server when calls are received from a client. A server dispatches methods concurrently.
Register is a noop the a service with the provided name has already been registered.
Source Files