bigmachine: github.com/grailbio/bigmachine/rpc Index | Files

package rpc

import "github.com/grailbio/bigmachine/rpc"

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

Package Files

client.go fault_injector.go log.go server.go sizereader.go stats.go

Variables

var InjectFailures = false

InjectFailures causes HTTP responses to be randomly terminated. Only for unittesting.

func Flush Uses

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.

type Client Uses

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

A Client invokes remote methods on RPC servers.

func NewClient Uses

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 Uses

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.

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 Uses

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 Uses

func NewServer() *Server

NewServer returns a new, initialized, Server.

func (*Server) Register Uses

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 Uses

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.

Package rpc imports 21 packages (graph) and is imported by 3 packages. Updated 2019-10-14. Refresh now. Tools for package owners.