juju: github.com/juju/juju/rpc Index | Files | Directories

package rpc

import "github.com/juju/juju/rpc"


Package Files

client.go observers.go server.go


var ErrShutdown = errors.New("connection is shut down")

func IsShutdownErr Uses

func IsShutdownErr(err error) bool

type Call Uses

type Call struct {
    Params   interface{}
    Response interface{}
    Error    error
    Done     chan *Call

Call represents an active RPC.

type Codec Uses

type Codec interface {
    // ReadHeader reads a message header into hdr.
    ReadHeader(hdr *Header) error

    // ReadBody reads a message body into the given body value.  The
    // isRequest parameter specifies whether the message being read
    // is a request; if not, it's a response.  The body value will
    // be a non-nil struct pointer, or nil to signify that the body
    // should be read and discarded.
    ReadBody(body interface{}, isRequest bool) error

    // WriteMessage writes a message with the given header and body.
    // The body will always be a struct. It may be called concurrently
    // with ReadHeader and ReadBody, but will not be called
    // concurrently with itself.
    WriteMessage(hdr *Header, body interface{}) error

    // Close closes the codec. It may be called concurrently
    // and should cause the Read methods to unblock.
    Close() error

A Codec implements reading and writing of messages in an RPC session. The RPC code calls WriteMessage to write a message to the connection and calls ReadHeader and ReadBody in pairs to read messages.

type Conn Uses

type Conn struct {
    // contains filtered or unexported fields

Conn represents an RPC endpoint. It can both initiate and receive RPC requests. There may be multiple outstanding Calls associated with a single Client, and a Client may be used by multiple goroutines simultaneously.

func NewConn Uses

func NewConn(codec Codec, factory RecorderFactory) *Conn

NewConn creates a new connection that uses the given codec for transport, but it does not start it. Conn.Start must be called before any requests are sent or received. If recorderFactory is non-nil, it will be called to get a new recorder for every request.

func (*Conn) Call Uses

func (conn *Conn) Call(req Request, params, response interface{}) error

Call invokes the named action on the object of the given type with the given id. The returned values will be stored in response, which should be a pointer. If the action fails remotely, the error will have a cause of type RequestError. The params value may be nil if no parameters are provided; the response value may be nil to indicate that any result should be discarded.

func (*Conn) Close Uses

func (conn *Conn) Close() error

Close closes the connection and its underlying codec; it returns when all requests have been terminated.

If the connection is serving requests, and the root value implements the Killer interface, its Kill method will be called. The codec will then be closed only when all its outstanding server calls have completed.

Calling Close multiple times is not an error.

func (*Conn) Dead Uses

func (conn *Conn) Dead() <-chan struct{}

Dead returns a channel that is closed when the connection has been closed or the underlying transport has received an error. There may still be outstanding requests. Dead must be called after conn.Start has been called.

func (*Conn) Serve Uses

func (conn *Conn) Serve(root interface{}, factory RecorderFactory, transformErrors func(error) error)

Serve serves RPC requests on the connection by invoking methods on root. Note that it does not start the connection running, though it may be called once the connection is already started.

The server executes each client request by calling a method on root to obtain an object to act on; then it invokes an method on that object with the request parameters, possibly returning some result.

Methods on the root value are of the form:

M(id string) (O, error)

where M is an exported name, conventionally naming the object type, id is some identifier for the object and O is the type of the returned object.

Methods defined on O may defined in one of the following forms, where T and R must be struct types.

Method([context.Context]) R
Method([context.Context]) (R, error)
Method([context.Context]) error
Method([context.Context,]T) R
Method([context.Context,]T) (R, error)
Method([context.Context,]T) error

If transformErrors is non-nil, it will be called on all returned non-nil errors, for example to transform the errors into ServerErrors with specified codes. There will be a panic if transformErrors returns nil.

Serve may be called at any time on a connection to change the set of methods being served by the connection. This will have no effect on calls that are currently being services. If root is nil, the connection will serve no methods.

func (*Conn) ServeRoot Uses

func (conn *Conn) ServeRoot(root Root, factory RecorderFactory, transformErrors func(error) error)

ServeRoot is like Serve except that it gives the root object dynamic control over what methods are available instead of using reflection on the type.

The server executes each client request by calling FindMethod to obtain a method to invoke. It invokes that method with the request parameters, possibly returning some result.

The Kill method will be called when the connection is closed.

func (*Conn) Start Uses

func (conn *Conn) Start(ctx context.Context)

Start starts the RPC connection running. It must be called at least once for any RPC connection (client or server side) It has no effect if it has already been called. By default, a connection serves no methods. See Conn.Serve for a description of how to serve methods on a Conn.

The context passed in will be propagated to requests served by the connection.

type ErrorCoder Uses

type ErrorCoder interface {
    ErrorCode() string

ErrorCoder represents any error that has an associated error code. An error code is a short string that represents the kind of an error.

type ErrorInfoProvider Uses

type ErrorInfoProvider interface {
    ErrorInfo() map[string]interface{}

ErrorInfoProvider represents any error that can provide additional error information as a map.

type Header struct {
    // RequestId holds the sequence number of the request.
    // For replies, it holds the sequence number of the request
    // that is being replied to.
    RequestId uint64

    // Request holds the action to invoke.
    Request Request

    // Error holds the error, if any.
    Error string

    // ErrorCode holds the code of the error, if any.
    ErrorCode string

    // ErrorInfo holds an optional set of additional information for an
    // error, if any.
    ErrorInfo map[string]interface{}

    // Version defines the wire format of the request and response structure.
    Version int

Header is a header written before every RPC call. Since RPC requests can be initiated from either side, the header may represent a request from the other side or a response to an outstanding request.

func (*Header) IsRequest Uses

func (hdr *Header) IsRequest() bool

IsRequest returns whether the header represents an RPC request. If it is not a request, it is a response.

type Killer Uses

type Killer interface {

Killer represents a type that can be asked to abort any outstanding requests. The Kill method should return immediately.

type Observer Uses

type Observer interface {

    // ServerRequest informs the Observer of a request made
    // to the Conn. If the request was not recognized or there was
    // an error reading the body, body will be nil.
    // ServerRequest is called just before the server method
    // is invoked.
    ServerRequest(hdr *Header, body interface{})

    // ServerReply informs the RequestNotifier of a reply sent to a
    // server request. The given Request gives details of the call
    // that was made; the given Header and body are the header and
    // body sent as reply.
    // ServerReply is called just before the reply is written.
    ServerReply(req Request, hdr *Header, body interface{})

Observer can be implemented to find out about requests occurring in an RPC conn, for example to print requests for logging purposes. The calls should not block or interact with the Conn object as that can cause delays to the RPC server or deadlock.

type ObserverFactory Uses

type ObserverFactory interface {
    // RPCObserver will return a new Observer usually constructed
    // from the state previously built up in the Observer. The
    // returned instance will be utilized per RPC request.
    RPCObserver() Observer

ObserverFactory is a type which can construct a new Observer.

type ObserverMultiplexer Uses

type ObserverMultiplexer struct {
    // contains filtered or unexported fields

ObserverMultiplexer multiplexes calls to an arbitrary number of Observers.

func NewObserverMultiplexer Uses

func NewObserverMultiplexer(rpcObservers ...Observer) *ObserverMultiplexer

NewObserverMultiplexer returns a new ObserverMultiplexer with the provided RequestNotifiers.

func (*ObserverMultiplexer) ServerReply Uses

func (m *ObserverMultiplexer) ServerReply(req Request, hdr *Header, body interface{})

ServerReply implements Observer.

func (*ObserverMultiplexer) ServerRequest Uses

func (m *ObserverMultiplexer) ServerRequest(hdr *Header, body interface{})

ServerRequest implements Observer.

type Recorder Uses

type Recorder interface {
    HandleRequest(hdr *Header, body interface{}) error
    HandleReply(req Request, replyHdr *Header, body interface{}) error

Recorder represents something the connection uses to record requests and replies. Recording a message can fail (for example for audit logging), and when it does the request should be failed as well.

type RecorderFactory Uses

type RecorderFactory func() Recorder

RecorderFactory is a function that returns a recorder to record details of a single request/response.

type Request Uses

type Request struct {
    // Type holds the type of object to act on.
    Type string

    // Version holds the version of Type we will be acting on
    Version int

    // Id holds the id of the object to act on.
    Id  string

    // Action holds the action to perform on the object.
    Action string

Request represents an RPC to be performed, absent its parameters.

type RequestError Uses

type RequestError struct {
    Message string
    Code    string
    Info    map[string]interface{}

RequestError represents an error returned from an RPC request.

func (*RequestError) Error Uses

func (e *RequestError) Error() string

func (*RequestError) ErrorCode Uses

func (e *RequestError) ErrorCode() string

func (*RequestError) ErrorInfo Uses

func (e *RequestError) ErrorInfo() map[string]interface{}

func (*RequestError) UnmarshalInfo Uses

func (e *RequestError) UnmarshalInfo(to interface{}) error

UnmarshalInfo attempts to unmarshal the information contained in the Info field of a RequestError into an object instance a pointer to which is passed via the to argument. The method will return an error if a non-pointer arg is provided.

type Root Uses

type Root interface {
    FindMethod(rootName string, version int, methodName string) (rpcreflect.MethodCaller, error)

Root represents a type that can be used to lookup a Method and place calls on that method.


jsoncodecThe jsoncodec package provides a JSON codec for the rpc package.

Package rpc imports 10 packages (graph) and is imported by 286 packages. Updated 2019-12-24. Refresh now. Tools for package owners.