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

    View Source
    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

          func NewClient(clientFactory func() *http.Client, prefix string) (*Client, error)

            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 NewServer

                func NewServer() *Server

                  NewServer returns a new, initialized, Server.

                  func (*Server) Register

                  func (s *Server) Register(serviceName string, iface interface{}) error

                    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.

                    func (*Server) ServeHTTP

                    func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request)

                      ServeHTTP interprets an HTTP request and, if it represents a valid rpc call, dispatches it onto the appropriate registered method.

                      ServeHTTP implements http.Handler.