p2p

Documentation

Overview

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

Index

• Constants
• Variables
• func Discover(ctx context.Context, addr ma.Multiaddr, f func(ma.Multiaddr) (bool, error)) (bool, error)
• func NewAuroraStreamName(protocol, version, stream string) string
• func NewBlockPeerError(duration time.Duration, err error) error
• func NewConnectionBackoffError(err error, tryAfter time.Time) error
• func NewDisconnectError(err error) error
• 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 Connect
• 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 Service
• type Stream
• type StreamSpec
• type Streamer
• type StreamerDisconnecter
• type StreamerPinger

Constants

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 NewAuroraStreamName

func NewAuroraStreamName(protocol, version, stream string) string

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

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 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 Connect

type Connect interface {
	// Connect to a peer but do not notify topology about the established connection.
	Connect(ctx context.Context, addr ma.Multiaddr) (peer *Peer, err 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 boson.Address, reason string) error
	// 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 boson.Address, duration time.Duration, reason string) error
}

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, boson.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 boson.Address, fullnode bool) error
	AnnounceTo(ctx context.Context, addressee, peer boson.Address, fullnode bool) error
}

type Peer

type Peer struct {
	Address boson.Address `json:"address"`
	Mode    aurora.Model  `json:"mode"`
}

Peer holds information about a Peer.

type Picker

type Picker interface {
	Pick(Peer) bool
}

type PickyNotifier

type PickyNotifier interface {
	Picker
	Notifier
}

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 aurora 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 Service

type Service interface {
	AddProtocol(ProtocolSpec) error
	Connect
	Disconnecter
	Peers() []Peer
	BlocklistedPeers() ([]Peer, error)
	Addresses() ([]ma.Multiaddr, error)
	NATAddresses() ([]net.Addr, 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 boson.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
}