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 is published as a GX module. Use GX to import it as a dependency. Alternatively, you can download it and run:
make deps
Usage
Documentation for this module is maintained in Godoc
Contribute
PRs accepted.
Small note: If editing the README, please conform to the standard-readme specification.
License
MIT
Documentation
¶
Overview ¶
Package rpc is heavily inspired by Go standard net/rpc package. It aims to do the same function, except it uses Libp2p for communication.
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 two arguments, 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(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 will 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.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
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).
Error error // After completion, the error status.
Done chan *Call // Strobes when call is complete.
}
Call represents an active RPC. Calls are used to indicate completion of RPC requests and are returned within the provided channel in the Go() and Call() 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 ¶
func (c *Client) Call(dest peer.ID, svcName string, svcMethod string, args interface{}, 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) Go ¶
func (c *Client) Go(dest peer.ID, svcName string, svcMethod string, args interface{}, 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.
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.
Source Files