rpc

package
v0.2202.13 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 30, 2024 License: Apache-2.0 Imports: 21 Imported by: 0

Documentation

Overview

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

Index

Constants

View Source 
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
)
View Source 
const (
	SuccessConnManagerPeerTagValue = 20
	ShuffledBestPeerCount          = 5
)
View Source 
const (
	RequestReadDeadline   = 5 * time.Second
	RequestHandleTimeout  = 60 * time.Second
	ResponseWriteDeadline = 60 * time.Second
)
View Source 
const ModuleName = "p2p/rpc"

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

Variables

View Source 
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 AggregateFunc added in v0.2201.2 

type AggregateFunc func(rsp interface{}, pf PeerFeedback) bool

AggregateFunc returns a result aggregation function.

The function is passed the response and PeerFeedback instance. If the function returns true, the client will continue to call other peers. If it returns false, processing will stop.

type CallMultiOption added in v0.2201.2 

type CallMultiOption func(opts *CallMultiOptions)

CallMultiOption is a per-multicall option setter.

func WithAggregateFn added in v0.2201.2 

func WithAggregateFn(fn AggregateFunc) CallMultiOption

WithAggregateFn configures the response aggregation function to use.

type CallMultiOptions added in v0.2201.2 

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

CallMultiOptions are per-multicall options

type CallOption 

type CallOption func(opts *CallOptions)

CallOption is a per-call option setter.

func WithLimitPeers added in v0.2202.0 

func WithLimitPeers(peers []PeerFeedback) CallOption

WithLimitPeers configures the peers that the call should be limited to.

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 added in v0.2200.3 

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,
		opts ...CallMultiOption,
	) ([]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 added in v0.2200.3 

type ValidationFunc func(pf PeerFeedback) error

ValidationFunc is a call response validation function.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.