rpc

Documentation

Overview

Package rpc provides tools for building simple RPC protocols via libp2p.

Index

• Constants
• Variables
• func NewRuntimeProtocolID(runtimeID common.Namespace, protocolID string, version version.Version) protocol.ID
• func PeerIDFromContext(ctx context.Context) (core.PeerID, bool)
• func WithPeerID(parent context.Context, peerID core.PeerID) context.Context
• type CallOption
  • func WithMaxRetries(maxRetries uint64) CallOption
  • func WithRetryInterval(retryInterval time.Duration) CallOption
  • func WithValidationFn(fn ValidationFunc) CallOption
• type CallOptions
• type Client
  • func NewClient(p2p P2P, runtimeID common.Namespace, protocolID string, ...) Client
• type ClientOption
  • func WithPeerFilter(filter PeerFilter) ClientOption
  • func WithStickyPeers(enabled bool) ClientOption
• type ClientOptions
• type Error
  • func (e Error) String() string
• type P2P
• type PeerFeedback
  • func NewNopPeerFeedback() PeerFeedback
• type PeerFilter
• type PeerManager
  • func NewPeerManager(p2p P2P, protocolID protocol.ID, stickyPeers bool) PeerManager
• type Request
• type Response
• type Server
  • func NewServer(runtimeID common.Namespace, protocolID string, version version.Version, ...) Server
• type Service
• type ValidationFunc

Constants

const (
	// RequestWriteDeadline is the maximum amount of time that can be spent on writing a request.
	RequestWriteDeadline = 5 * time.Second
	// DefaultCallRetryInterval is the default call retry interval for calls which explicitly enable
	// retries by setting the WithMaxRetries option to a non-zero value. It can be overridden by
	// using the WithRetryInterval call option.
	DefaultCallRetryInterval = 1 * time.Second
)

const (
	SuccessConnManagerPeerTagValue = 20
	ShuffledBestPeerCount          = 5
)

const (
	RequestReadDeadline   = 5 * time.Second
	RequestHandleTimeout  = 60 * time.Second
	ResponseWriteDeadline = 60 * time.Second
)

const ModuleName = "p2p/rpc"

ModuleName is a unique module name for the P2P RPC module.

Variables

var (
	// ErrMethodNotSupported is an error raised when a given method is not supported.
	ErrMethodNotSupported = errors.New(ModuleName, 1, "rpc: method not supported")

	// ErrBadRequest is an error raised when a given request is malformed.
	ErrBadRequest = errors.New(ModuleName, 2, "rpc: bad request")
)

Functions

func NewRuntimeProtocolID

func NewRuntimeProtocolID(runtimeID common.Namespace, protocolID string, version version.Version) protocol.ID

NewRuntimeProtocolID generates a protocol identifier for a protocol supported for a specific runtime. This makes it so that one doesn't need additional checks to ensure that a peer supports the given protocol for the given runtime.

func PeerIDFromContext

func PeerIDFromContext(ctx context.Context) (core.PeerID, bool)

PeerIDFromContext looks up the peer ID value in the given context.

func WithPeerID

func WithPeerID(parent context.Context, peerID core.PeerID) context.Context

WithPeerID creates a new context with the peer ID value set.

Types

type CallOption

type CallOption func(opts *CallOptions)

CallOption is a per-call option setter.

func WithMaxRetries

func WithMaxRetries(maxRetries uint64) CallOption

WithMaxRetries configures the maximum number of retries to use for the call.

func WithRetryInterval

func WithRetryInterval(retryInterval time.Duration) CallOption

WithRetryInterval configures the retry interval to use for the call.

func WithValidationFn

func WithValidationFn(fn ValidationFunc) CallOption

WithValidationFn configures the response validation function to use for the call.

When the function is called, the decoded response value will be set.

type CallOptions

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

CallOptions are per-call options.

type Client

type Client interface {
	PeerManager

	// Call attempts to route the given RPC method call to one of the peers that supports the
	// protocol based on past experience with the peers.
	//
	// On success it returns a PeerFeedback instance that should be used by the caller to provide
	// deferred feedback on whether the peer is any good or not. This will help guide later choices
	// when routing calls.
	Call(
		ctx context.Context,
		method string,
		body, rsp interface{},
		maxPeerResponseTime time.Duration,
		opts ...CallOption,
	) (PeerFeedback, error)

	// CallMulti routes the given RPC method call to multiple peers that support the protocol based
	// on past experience with the peers.
	//
	// It returns all successfully retrieved results and their corresponding PeerFeedback instances.
	CallMulti(
		ctx context.Context,
		method string,
		body, rspTyp interface{},
		maxPeerResponseTime time.Duration,
		maxParallelRequests uint,
	) ([]interface{}, []PeerFeedback, error)
}

Client is an RPC client for a given protocol.

func NewClient

func NewClient(p2p P2P, runtimeID common.Namespace, protocolID string, version version.Version, opts ...ClientOption) Client

NewClient creates a new RPC client for the given protocol.

type ClientOption

type ClientOption func(opts *ClientOptions)

ClientOption is a client option setter.

func WithPeerFilter

func WithPeerFilter(filter PeerFilter) ClientOption

WithPeerFilter configures peer filtering.

When set, only peers accepted by the filter will be used for calls.

func WithStickyPeers

func WithStickyPeers(enabled bool) ClientOption

WithStickyPeers configures the sticky peers feature.

When enabled, the last successful peer will be stuck and will be reused on subsequent calls until the peer is deemed bad by the received peer feedback.

type ClientOptions

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

ClientOptions are client options.

type Error

type Error struct {
	Module  string `json:"module,omitempty"`
	Code    uint32 `json:"code,omitempty"`
	Message string `json:"message,omitempty"`
}

Error is a message body representing an error.

func (Error) String

func (e Error) String() string

String returns a string representation of this error.

type P2P

type P2P interface {
	// BlockPeer blocks a specific peer from being used by the local node.
	BlockPeer(peerID core.PeerID)

	// GetHost returns the P2P host.
	GetHost() core.Host
}

P2P is a P2P interface that the RPC protocols need.

type PeerFeedback

type PeerFeedback interface {
	// RecordSuccess records a successful protocol interaction with the given peer.
	RecordSuccess()

	// RecordFailure records an unsuccessful protocol interaction with the given peer.
	RecordFailure()

	// RecordBadPeer records a malicious protocol interaction with the given peer.
	//
	// The peer will be ignored during peer selection.
	RecordBadPeer()
}

PeerFeedback is an interface for providing deferred peer feedback after an outcome is known.

func NewNopPeerFeedback

func NewNopPeerFeedback() PeerFeedback

NewNopPeerFeedback creates a no-op peer feedback instance.

type PeerFilter

type PeerFilter interface {
	// IsPeerAcceptable checks whether the given peer should be used.
	IsPeerAcceptable(peerID core.PeerID) bool
}

PeerFilter is a peer filtering interface.

type PeerManager

type PeerManager interface {
	// AddPeer tries to add the given peer to the peer manager.
	//
	// Peer is only added in case it supports the specified protocol.
	AddPeer(peerID core.PeerID)

	// RemovePeer unconditionally removes the peer from the peer manager.
	RemovePeer(peerID core.PeerID)

	// RecordSuccess records a successful protocol interaction with the given peer.
	RecordSuccess(peerID core.PeerID, latency time.Duration)

	// RecordFailure records an unsuccessful protocol interaction with the given peer.
	RecordFailure(peerID core.PeerID, latency time.Duration)

	// RecordBadPeer records a malicious protocol interaction with the given peer.
	//
	// The peer will be ignored during peer selection.
	RecordBadPeer(peerID core.PeerID)

	// GetBestPeers returns a set of peers sorted by the probability that they will be able to
	// answer our requests the fastest with some randomization.
	GetBestPeers() []core.PeerID
}

PeerManager is an interface for keeping track of peer statistics in order to guide peer selection when performing RPC requests.

func NewPeerManager

func NewPeerManager(p2p P2P, protocolID protocol.ID, stickyPeers bool) PeerManager

NewPeerManager creates a new peer manager for the given protocol.

type Request

type Request struct {
	// Method is the name of the method.
	Method string `json:"method"`
	// Body is the method-specific body.
	Body cbor.RawMessage `json:"body"`
}

Request is a request sent by the client.

type Response

type Response struct {
	// Ok is the method-specific response in case of success.
	Ok cbor.RawMessage `json:"ok,omitempty"`
	// Error is an error response in case of failure.
	Error *Error `json:"error,omitempty"`
}

Response is a response to a previously sent request.

type Server

type Server interface {
	// Protocol returns the unique protocol identifier.
	Protocol() protocol.ID

	// HandleStream handles an incoming stream.
	HandleStream(stream network.Stream)
}

Server is an RPC server for the given protocol.

func NewServer

func NewServer(runtimeID common.Namespace, protocolID string, version version.Version, srv Service) Server

NewServer creates a new RPC server for the given protocol.

type Service

type Service interface {
	// HandleRequest handles an incoming RPC request.
	HandleRequest(ctx context.Context, method string, body cbor.RawMessage) (interface{}, error)
}

Service is an RPC service implementation.

type ValidationFunc

type ValidationFunc func(pf PeerFeedback) error

ValidationFunc is a call response validation function.