README
¶
go-libp2p-gorpc
Simple Go RPC for LibP2P.
go-libp2p-gorpc provides RPC support on top of LibP2P in the same way that net/rpc does on HTTP.
Table of Contents
Install
This module can be installed with go get:
> go get github.com/libp2p/go-libp2p-gorpc
This repo is gomod-compatible, and users of
go 1.11 and later with modules enabled will automatically pull the latest tagged release
by referencing this package. Upgrades to future releases can be managed using go get,
or by editing your go.mod file as described by the gomod documentation.
Usage
Documentation for this module is maintained in Godoc
There are also examples inside the examples directory
Contribute
PRs accepted.
Small note: If editing the README, please conform to the standard-readme specification.
License
MIT
The last gx published version of this module was: 1.1.4: QmcJCApoEsCJJap2iS1os9GFX5EuRrfuPeZdjCopz2SyPm
Documentation
¶
Overview ¶
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 ¶
- func AuthorizeWithMap(p map[peer.ID]map[string]bool) func(pid peer.ID, svc string, method string) bool
- func IsAuthorizationError(err error) bool
- func IsClientError(err error) bool
- func IsRPCError(err error) bool
- func IsServerError(err error) bool
- type Call
- type Client
- func (c *Client) Call(dest peer.ID, svcName, svcMethod string, args, reply interface{}) error
- func (c *Client) CallContext(ctx context.Context, dest peer.ID, svcName, svcMethod string, ...) error
- func (c *Client) Go(dest peer.ID, svcName, svcMethod string, args, reply interface{}, ...) error
- func (c *Client) GoContext(ctx context.Context, dest peer.ID, svcName, svcMethod string, ...) error
- func (c *Client) ID() peer.ID
- func (c *Client) MultiCall(ctxs []context.Context, dests []peer.ID, svcName, svcMethod string, ...) []error
- func (c *Client) MultiGo(ctxs []context.Context, dests []peer.ID, svcName, svcMethod string, ...) error
- type ClientOption
- type Response
- type Server
- type ServerOption
- type ServiceID
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AuthorizeWithMap ¶
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 ¶
IsAuthorizationError returns whether an error is authorizationError.
func IsClientError ¶
IsClientError returns whether an error is clientError.
func IsRPCError ¶
IsRPCError returns whether an error is either a serverError or clientError.
func IsServerError ¶
IsServerError returns whether an error is serverError.
Types ¶
type Call ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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) MultiCall ¶
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 ¶
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 ¶
type ClientOption func(*Client)
ClientOption allows for functional setting of options on a Client.
func WithClientStatsHandler ¶
func WithClientStatsHandler(h stats.Handler) ClientOption
WithClientStatsHandler provides an implementation of stats.Handler to be used by the Client.
type Response ¶
Response is a header sent when responding to an RPC request which includes any error that may have happened.
type Server ¶
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 (*Server) Call ¶
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) Register ¶
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 ¶
RegisterName is like Register but uses the provided name for the type instead of the receiver's concrete type.
type ServerOption ¶
type ServerOption func(*Server)
ServerOption allows for functional setting of options on a Server.
func WithAuthorizeFunc ¶
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 ¶
func WithServerStatsHandler(h stats.Handler) ServerOption
WithServerStatsHandler providers a implementation of stats.Handler to be used by the Server.
Source Files
Directories