go-libp2p-gorpc: github.com/hsanjuan/go-libp2p-gorpc Index | Files

package rpc

import "github.com/hsanjuan/go-libp2p-gorpc"

Package rpc is heavily inspired by Go standard net/rpc package. It aims to do the same thing, except it uses Libp2p for communication and provides context support for cancelling operations.

A server registers an object, making it visible as a service with the name of the type of the object. After registration, exported methods of the object will be accessible remotely. A server may register multiple objects (services) of different types but it is an error to register multiple objects of the same type.

Only methods that satisfy these criteria will be made available for remote access; other methods will be ignored:

- the method's type is exported.
- the method is exported.
- the method has 3 arguments.
- the method's first argument is a context.
- the method's second are third arguments are both exported (or builtin) types.
- the method's second argument is a pointer.
- the method has return type error.

In effect, the method must look schematically like

func (t *T) MethodName(ctx context.Context, argType T1, replyType *T2) error

where T1 and T2 can be marshaled by encoding/gob.

The method's first argument represents the arguments provided by the caller; the second argument represents the result parameters to be returned to the caller. The method's return value, if non-nil, is passed back as a string that the client sees as if created by errors.New. If an error is returned, the reply parameter may not be sent back to the client.

In order to use this package, a ready-to-go LibP2P Host must be provided to clients and servers, along with a protocol.ID. rpc will add a stream handler for the given protocol. Hosts must be ready to speak to clients, that is, peers must be part of the peerstore along with keys if secio communication is required.

Since version 2.0.0, contexts are supported and honored. On the server side, methods must take a context. A closure or reset of the libp2p stream will trigger a cancellation of the context received by the functions. On the client side, the user can optionally provide a context. Cancelling the client's context will cancel the operation both on the client and on the server side (by closing the associated stream).

Index

Package Files

call.go client.go errors.go server.go stream_wrap.go

func AuthorizeWithMap Uses

func AuthorizeWithMap(p map[peer.ID]map[string]bool) func(pid peer.ID, svc string, method string) bool

AuthorizeWithMap returns an authrorization function that follows the strategy as described in the given map(maps "service.method" of a peer to boolean permission).

func IsAuthorizationError Uses

func IsAuthorizationError(err error) bool

IsAuthorizationError returns whether an error is authorizationError.

func IsClientError Uses

func IsClientError(err error) bool

IsClientError returns whether an error is clientError.

func IsRPCError Uses

func IsRPCError(err error) bool

IsRPCError returns whether an error is either a serverError or clientError.

func IsServerError Uses

func IsServerError(err error) bool

IsServerError returns whether an error is serverError.

type Call Uses

type Call struct {
    Dest  peer.ID
    SvcID ServiceID   // The name of the service and method to call.
    Args  interface{} // The argument to the function (*struct).
    Reply interface{} // The reply from the function (*struct).
    Done  chan *Call  // Strobes when call is complete.

    Error error // After completion, the error status.
    // contains filtered or unexported fields
}

Call represents an active RPC. Calls are used to indicate completion of RPC requests and are returned within the provided channel in the Go() functions.

type Client Uses

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

Client represents an RPC client which can perform calls to a remote (or local, see below) Server.

func NewClient Uses

func NewClient(h host.Host, p protocol.ID, opts ...ClientOption) *Client

NewClient returns a new Client which uses the given LibP2P host and protocol ID, which must match the one used by the server. The Host must be correctly configured to be able to open streams to the server (addresses and keys in Peerstore etc.).

The client returned will not be able to run any local requests if the Server is sharing the same LibP2P host. See NewClientWithServer if this is a usecase.

func NewClientWithServer Uses

func NewClientWithServer(h host.Host, p protocol.ID, s *Server, opts ...ClientOption) *Client

NewClientWithServer takes an additional RPC Server and returns a Client which will perform any requests to itself by using the given Server.Call() directly. It is assumed that Client and Server share the same LibP2P host.

func (*Client) Call Uses

func (c *Client) Call(
    dest peer.ID,
    svcName, svcMethod string,
    args, reply interface{},
) error

Call performs an RPC call to a registered Server service and blocks until completed. If dest is empty ("") or matches the Client's host ID, it will attempt to use the local configured Server when possible.

func (*Client) CallContext Uses

func (c *Client) CallContext(
    ctx context.Context,
    dest peer.ID,
    svcName, svcMethod string,
    args, reply interface{},
) error

CallContext performs a Call() with a user provided context. This gives the user the possibility of cancelling the operation at any point.

func (*Client) Go Uses

func (c *Client) Go(
    dest peer.ID,
    svcName, svcMethod string,
    args, reply interface{},
    done chan *Call,
) error

Go performs an RPC call asynchronously. The associated Call will be placed in the provided channel upon completion, holding any Reply or Errors.

The provided done channel must be nil, or have capacity for 1 element at least, or a panic will be triggered.

If dest is empty ("") or matches the Client's host ID, it will attempt to use the local configured Server when possible.

func (*Client) GoContext Uses

func (c *Client) GoContext(
    ctx context.Context,
    dest peer.ID,
    svcName, svcMethod string,
    args, reply interface{},
    done chan *Call,
) error

GoContext performs a Go() call with the provided context, allowing the user to cancel the operation. See Go() documentation for more information.

The provided done channel must be nil, or have capacity for 1 element at least, or a panic will be triggered.

func (*Client) ID Uses

func (c *Client) ID() peer.ID

ID returns the peer.ID of the host associated with this client.

func (*Client) MultiCall Uses

func (c *Client) MultiCall(
    ctxs []context.Context,
    dests []peer.ID,
    svcName, svcMethod string,
    args interface{},
    replies []interface{},
) []error

MultiCall performs a CallContext() to multiple destinations, using the same service name, method and arguments. It will not return until all calls have done so. The contexts, destinations and replies must match in length and will be used in order (ctxs[i] is used for dests[i] which obtains replies[i] and error[i]).

The calls will be triggered in parallel (with one goroutine for each).

func (*Client) MultiGo Uses

func (c *Client) MultiGo(
    ctxs []context.Context,
    dests []peer.ID,
    svcName, svcMethod string,
    args interface{},
    replies []interface{},
    dones []chan *Call,
) error

MultiGo performs a GoContext() call to multiple destinations, using the same service name, method and arguments. MultiGo will return as right after performing all the calls. See the Go() documentation for more information.

The provided done channels must be nil, or have capacity for 1 element at least, or a panic will be triggered.

The contexts, destinations, replies and done channels must match in length and will be used in order (ctxs[i] is used for dests[i] which obtains replies[i] with dones[i] signalled upon completion).

type ClientOption Uses

type ClientOption func(*Client)

ClientOption allows for functional setting of options on a Client.

func WithClientStatsHandler Uses

func WithClientStatsHandler(h stats.Handler) ClientOption

WithClientStatsHandler provides an implementation of stats.Handler to be used by the Client.

type Response Uses

type Response struct {
    Service ServiceID
    Error   string // error, if any.
    ErrType responseErr
}

Response is a header sent when responding to an RPC request which includes any error that may have happened.

type Server Uses

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

Server is an LibP2P RPC server. It can register services which comply to the limitations outlined in the package description and it will call the relevant methods when receiving requests from a Client.

A server needs a LibP2P host and a protocol, which must match the one used by the client. The LibP2P host must be already correctly configured to be able to handle connections from clients.

func NewServer Uses

func NewServer(h host.Host, p protocol.ID, opts ...ServerOption) *Server

NewServer creates a Server object with the given LibP2P host and protocol.

func (*Server) Call Uses

func (server *Server) Call(call *Call) error

Call allows a server to process a Call directly and act like a client to itself. This is mostly useful because LibP2P does not allow to create streams between a server and a client which share the same host. See NewClientWithServer() for more info.

func (*Server) ID Uses

func (server *Server) ID() peer.ID

ID returns the peer.ID of the host associated with this server.

func (*Server) Register Uses

func (server *Server) Register(rcvr interface{}) error

Register publishes in the server the set of methods of the receiver value that satisfy the following conditions:

- exported method of exported type
- two arguments, both of exported type
- the second argument is a pointer
- one return value, of type error

It returns an error if the receiver is not an exported type or has no suitable methods. It also logs the error using package log. The client accesses each method using a string of the form "Type.Method", where Type is the receiver's concrete type.

func (*Server) RegisterName Uses

func (server *Server) RegisterName(name string, rcvr interface{}) error

RegisterName is like Register but uses the provided name for the type instead of the receiver's concrete type.

type ServerOption Uses

type ServerOption func(*Server)

ServerOption allows for functional setting of options on a Server.

func WithAuthorizeFunc Uses

func WithAuthorizeFunc(a func(pid peer.ID, name string, method string) bool) ServerOption

WithAuthorizeFunc adds authorization strategy(A function defining whether the given peer id is allowed to access given method of the given service) to the server using given authorization function.

func WithServerStatsHandler Uses

func WithServerStatsHandler(h stats.Handler) ServerOption

WithServerStatsHandler providers a implementation of stats.Handler to be used by the Server.

type ServiceID Uses

type ServiceID struct {
    Name   string
    Method string
}

ServiceID is a header sent when performing an RPC request which identifies the service and method being called.

Package rpc imports 18 packages (graph) and is imported by 5 packages. Updated 2019-03-18. Refresh now. Tools for package owners.