p2p

Documentation

Overview

Package p2p provides the peer-to-peer abstractions used across different protocols in hop.

Index

• Constants
• Variables
• func Discover(ctx context.Context, addr ma.Multiaddr, f func(ma.Multiaddr) (bool, error)) (bool, error)
• func NewBlockPeerError(duration time.Duration, err error) error
• func NewConnectionBackoffError(err error, tryAfter time.Time) error
• func NewDisconnectError(err error) error
• func NewSwarmStreamName(protocol, version, stream string) string
• func WithBlocklistStreams(dur time.Duration, spec ProtocolSpec)
• func WithDisconnectStreams(spec ProtocolSpec)
• type BlockPeerError
  • func (e *BlockPeerError) Duration() time.Duration
  • func (e *BlockPeerError) Error() string
  • func (e *BlockPeerError) Unwrap() error
• type Blocklister
• type ConnectionBackoffError
  • func (e *ConnectionBackoffError) Error() string
  • func (e *ConnectionBackoffError) TryAfter() time.Time
  • func (e *ConnectionBackoffError) Unwrap() error
• type DebugService
• type DisconnectError
  • func (e *DisconnectError) Error() string
  • func (e *DisconnectError) Unwrap() error
• type Disconnecter
• type Halter
• type HandlerFunc
• type HandlerMiddleware
• type Headers
• type HeadlerFunc
• type IncompatibleStreamError
  • func NewIncompatibleStreamError(err error) *IncompatibleStreamError
  • func (e *IncompatibleStreamError) Error() string
  • func (e *IncompatibleStreamError) Unwrap() error
• type Notifier
• type Peer
• type Picker
• type PickyNotifier
• type Pinger
• type ProtocolSpec
• type ReachabilityStatus
  • func (rs ReachabilityStatus) String() string
• type ReachabilityUpdater
• type ReachableNotifier
• type Reacher
• type Service
• type Stream
• type StreamSpec
• type Streamer
• type StreamerDisconnecter
• type StreamerPinger

Constants

const (
	ReachabilityStatusUnknown = ReachabilityStatus(network.ReachabilityUnknown)
	ReachabilityStatusPublic  = ReachabilityStatus(network.ReachabilityPublic)
	ReachabilityStatusPrivate = ReachabilityStatus(network.ReachabilityPrivate)
)

const (
	DefaultBlocklistTime = 1 * time.Minute
)

const (
	HeaderNameTracingSpanContext = "tracing-span-context"
)

Common header names.

Variables

var (
	// ErrPeerNotFound should be returned by p2p service methods when the requested
	// peer is not found.
	ErrPeerNotFound = errors.New("peer not found")
	// ErrAlreadyConnected is returned if connect was called for already connected node.
	ErrAlreadyConnected = errors.New("already connected")
	// ErrDialLightNode is returned if connect was attempted to a light node.
	ErrDialLightNode = errors.New("target peer is a light node")
)

var ErrUnexpected = errors.New("unexpected request while in light mode")

Functions

func Discover

func Discover(ctx context.Context, addr ma.Multiaddr, f func(ma.Multiaddr) (bool, error)) (bool, error)

func NewBlockPeerError

func NewBlockPeerError(duration time.Duration, err error) error

NewBlockPeerError wraps error and creates a special error that is treated specially by p2p. It causes peer to be disconnected and blocks any new connection for this peer for the provided duration.

func NewConnectionBackoffError

func NewConnectionBackoffError(err error, tryAfter time.Time) error

NewConnectionBackoffError creates new `ConnectionBackoffError` with provided underlying error and `tryAfter` timestamp.

func NewDisconnectError

func NewDisconnectError(err error) error

NewDisconnectError wraps error and creates a special error that is treated specially by p2p. It causes peer to disconnect.

func NewSwarmStreamName

func NewSwarmStreamName(protocol, version, stream string) string

NewSwarmStreamName constructs a libp2p compatible stream name out of protocol name and version and stream name.

func WithBlocklistStreams

func WithBlocklistStreams(dur time.Duration, spec ProtocolSpec)

WithBlocklistStreams will mutate the given spec and replace the handler with a always erroring one.

func WithDisconnectStreams

func WithDisconnectStreams(spec ProtocolSpec)

WithDisconnectStreams will mutate the given spec and replace the handler with a always erroring one.

Types

type BlockPeerError

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

func (*BlockPeerError) Duration

func (e *BlockPeerError) Duration() time.Duration

Duration represents the period for which the peer will be blocked. 0 duration is treated as infinity

func (*BlockPeerError) Error

func (e *BlockPeerError) Error() string

Error implements function of the standard go error interface.

func (*BlockPeerError) Unwrap

func (e *BlockPeerError) Unwrap() error

Unwrap returns an underlying error.

type Blocklister

type Blocklister interface {
	// Blocklist will disconnect a peer and put it on a blocklist (blocking in & out connections) for provided duration
	// Duration 0 is treated as an infinite duration.
	Blocklist(overlay swarm.Address, duration time.Duration, reason string) error
}

type ConnectionBackoffError

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

ConnectionBackoffError indicates that connection calls will not be executed until `tryAfter` timetamp. The reason is provided in the wrappped error.

func (*ConnectionBackoffError) Error

func (e *ConnectionBackoffError) Error() string

Error implements function of the standard go error interface.

func (*ConnectionBackoffError) TryAfter

func (e *ConnectionBackoffError) TryAfter() time.Time

TryAfter returns a tryAfter timetamp.

func (*ConnectionBackoffError) Unwrap

func (e *ConnectionBackoffError) Unwrap() error

Unwrap returns an underlying error.

type DebugService

type DebugService interface {
	Service
	SetWelcomeMessage(val string) error
	GetWelcomeMessage() string
}

DebugService extends the Service with method used for debugging.

type DisconnectError

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

DisconnectError is an error that is specifically handled inside p2p. If returned by specific protocol handler it causes peer disconnect.

func (*DisconnectError) Error

func (e *DisconnectError) Error() string

Error implements function of the standard go error interface.

func (*DisconnectError) Unwrap

func (e *DisconnectError) Unwrap() error

Unwrap returns an underlying error.

type Disconnecter

type Disconnecter interface {
	Disconnect(overlay swarm.Address, reason string) error
	Blocklister
}

type Halter

type Halter interface {
	// Halt new incoming connections while shutting down
	Halt()
}

type HandlerFunc

type HandlerFunc func(context.Context, Peer, Stream) error

HandlerFunc handles a received Stream from a Peer.

type HandlerMiddleware

type HandlerMiddleware func(HandlerFunc) HandlerFunc

HandlerMiddleware decorates a HandlerFunc by returning a new one.

type Headers

type Headers map[string][]byte

Headers represents a collection of p2p header key value pairs.

type HeadlerFunc

type HeadlerFunc func(Headers, swarm.Address) Headers

HeadlerFunc is returning response headers based on the received request headers.

type IncompatibleStreamError

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

IncompatibleStreamError is the error that should be returned by p2p service NewStream method when the stream or its version is not supported.

func NewIncompatibleStreamError

func NewIncompatibleStreamError(err error) *IncompatibleStreamError

NewIncompatibleStreamError wraps the error that is the cause of stream incompatibility with IncompatibleStreamError that it can be detected and returns it.

func (*IncompatibleStreamError) Error

func (e *IncompatibleStreamError) Error() string

Error implements function of the standard go error interface.

func (*IncompatibleStreamError) Unwrap

func (e *IncompatibleStreamError) Unwrap() error

Unwrap returns an underlying error.

type Notifier

type Notifier interface {
	Connected(context.Context, Peer, bool) error
	Disconnected(Peer)
	Announce(ctx context.Context, peer swarm.Address, fullnode bool) error
	AnnounceTo(ctx context.Context, addressee, peer swarm.Address, fullnode bool) error
}

type Peer

type Peer struct {
	Address         swarm.Address
	FullNode        bool
	EthereumAddress []byte
}

Peer holds information about a Peer.

type Picker

type Picker interface {
	Pick(Peer) bool
}

type PickyNotifier

type PickyNotifier interface {
	Picker
	Notifier
	ReachabilityUpdater
	ReachableNotifier
}

PickyNotifier can decide whether a peer should be picked

type Pinger

type Pinger interface {
	Ping(ctx context.Context, addr ma.Multiaddr) (rtt time.Duration, err error)
}

Pinger interface is used to ping a underlay address which is not yet known to the hop node. It uses libp2p's default ping protocol. This is different from the PingPong protocol as this is meant to be used before we know a particular underlay and we can consider it useful

type ProtocolSpec

type ProtocolSpec struct {
	Name          string
	Version       string
	StreamSpecs   []StreamSpec
	ConnectIn     func(context.Context, Peer) error
	ConnectOut    func(context.Context, Peer) error
	DisconnectIn  func(Peer) error
	DisconnectOut func(Peer) error
}

ProtocolSpec defines a collection of Stream specifications with handlers.

type ReachabilityStatus

type ReachabilityStatus network.Reachability

ReachabilityStatus represents the node reachability status.

func (ReachabilityStatus) String

func (rs ReachabilityStatus) String() string

String implements the fmt.Stringer interface.

type ReachabilityUpdater

type ReachabilityUpdater interface {
	UpdateReachability(ReachabilityStatus)
}

type ReachableNotifier

type ReachableNotifier interface {
	Reachable(swarm.Address, ReachabilityStatus)
}

type Reacher

type Reacher interface {
	Connected(swarm.Address, ma.Multiaddr)
	Disconnected(swarm.Address)
}

type Service

type Service interface {
	AddProtocol(ProtocolSpec) error
	// Connect to a peer but do not notify topology about the established connection.
	Connect(ctx context.Context, addr ma.Multiaddr) (address *hop.Address, err error)
	Disconnecter
	Peers() []Peer
	BlocklistedPeers() ([]Peer, error)
	Addresses() ([]ma.Multiaddr, error)
	SetPickyNotifier(PickyNotifier)
	Halter
}

Service provides methods to handle p2p Peers and Protocols.

type Stream

type Stream interface {
	io.ReadWriter
	io.Closer
	ResponseHeaders() Headers
	Headers() Headers
	FullClose() error
	Reset() error
}

Stream represent a bidirectional data Stream.

type StreamSpec

type StreamSpec struct {
	Name    string
	Handler HandlerFunc
	Headler HeadlerFunc
}

StreamSpec defines a Stream handling within the protocol.

type Streamer

type Streamer interface {
	NewStream(ctx context.Context, address swarm.Address, h Headers, protocol, version, stream string) (Stream, error)
}

Streamer is able to create a new Stream.

type StreamerDisconnecter

type StreamerDisconnecter interface {
	Streamer
	Disconnecter
}

type StreamerPinger

type StreamerPinger interface {
	Streamer
	Pinger
}