rpc

package
v0.5.8 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jul 15, 2020 License: Apache-2.0 Imports: 21 Imported by: 1

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL