network

package
v0.12.0 Latest Latest
Warning

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

 Go to latest Published: Dec 2, 2021 License: Apache-2.0, MIT, Apache-2.0, + 1 more Imports: 10 Imported by: 1,016

Documentation

Overview

Package network provides core networking abstractions for libp2p.

The network package provides the high-level Network interface for interacting with other libp2p peers, which is the primary public API for initiating and accepting connections to remote peers.

Index

Constants

View Source 
const MessageSizeMax = 1 << 22 // 4 MB

MessageSizeMax is a soft (recommended) maximum for network messages. One can write more, as the interface is a stream. But it is useful to bunch it up into multiple read/writes when the whole message is a single, large serialized object.

Variables

View Source 
var DialPeerTimeout = 60 * time.Second

DialPeerTimeout is the default timeout for a single call to `DialPeer`. When there are multiple concurrent calls to `DialPeer`, this timeout will apply to each independently.

View Source 
var ErrNoConn = errors.New("no usable connection to peer")

ErrNoConn is returned when attempting to open a stream to a peer with the NoDial option and no usable connection is available.

View Source 
var ErrNoRemoteAddrs = errors.New("no remote addresses")

ErrNoRemoteAddrs is returned when there are no addresses associated with a peer during a dial.

View Source 
var ErrTransientConn = errors.New("transient connection to peer")

ErrTransientConn is returned when attempting to open a stream to a peer with only a transient connection, without specifying the UseTransient option.

View Source 
var GlobalNoopNotifiee = &NoopNotifiee{}

Global noop notifiee. Do not change.

Functions

func GetDialPeerTimeout 

func GetDialPeerTimeout(ctx context.Context) time.Duration

GetDialPeerTimeout returns the current DialPeer timeout (or the default).

func GetForceDirectDial added in v0.7.1 

func GetForceDirectDial(ctx context.Context) (forceDirect bool, reason string)

EXPERIMENTAL GetForceDirectDial returns true if the force direct dial option is set in the context.

func GetNoDial 

func GetNoDial(ctx context.Context) (nodial bool, reason string)

GetNoDial returns true if the no dial option is set in the context.

func GetSimultaneousConnect added in v0.8.5 

func GetSimultaneousConnect(ctx context.Context) (simconnect bool, isClient bool, reason string)

GetSimultaneousConnect returns true if the simultaneous connect option is set in the context. EXPERIMENTAL

func GetUseTransient added in v0.8.2 

func GetUseTransient(ctx context.Context) (usetransient bool, reason string)

GetUseTransient returns true if the use transient option is set in the context.

func WithDialPeerTimeout 

func WithDialPeerTimeout(ctx context.Context, timeout time.Duration) context.Context

WithDialPeerTimeout returns a new context with the DialPeer timeout applied.

This timeout overrides the default DialPeerTimeout and applies per-dial independently.

func WithForceDirectDial added in v0.7.1 

func WithForceDirectDial(ctx context.Context, reason string) context.Context

EXPERIMENTAL WithForceDirectDial constructs a new context with an option that instructs the network to attempt to force a direct connection to a peer via a dial even if a proxied connection to it already exists.

func WithNoDial 

func WithNoDial(ctx context.Context, reason string) context.Context

WithNoDial constructs a new context with an option that instructs the network to not attempt a new dial when opening a stream.

func WithSimultaneousConnect added in v0.8.5 

func WithSimultaneousConnect(ctx context.Context, isClient bool, reason string) context.Context

WithSimultaneousConnect constructs a new context with an option that instructs the transport to apply hole punching logic where applicable. EXPERIMENTAL

func WithUseTransient added in v0.8.2 

func WithUseTransient(ctx context.Context, reason string) context.Context

WithUseTransient constructs a new context with an option that instructs the network that it is acceptable to use a transient connection when opening a new stream.

Types

type Conn 

type Conn interface {
	io.Closer

	ConnSecurity
	ConnMultiaddrs
	ConnStat

	// ID returns an identifier that uniquely identifies this Conn within this
	// host, during this run. Connection IDs may repeat across restarts.
	ID() string

	// NewStream constructs a new Stream over this conn.
	NewStream(context.Context) (Stream, error)

	// GetStreams returns all open streams over this conn.
	GetStreams() []Stream
}

Conn is a connection to a remote peer. It multiplexes streams. Usually there is no need to use a Conn directly, but it may be useful to get information about the peer on the other side: 

stream.Conn().RemotePeer()

type ConnMultiaddrs 

type ConnMultiaddrs interface {
	// LocalMultiaddr returns the local Multiaddr associated
	// with this connection
	LocalMultiaddr() ma.Multiaddr

	// RemoteMultiaddr returns the remote Multiaddr associated
	// with this connection
	RemoteMultiaddr() ma.Multiaddr
}

ConnMultiaddrs is an interface mixin for connection types that provide multiaddr addresses for the endpoints.

type ConnSecurity 

type ConnSecurity interface {
	// LocalPeer returns our peer ID
	LocalPeer() peer.ID

	// LocalPrivateKey returns our private key
	LocalPrivateKey() ic.PrivKey

	// RemotePeer returns the peer ID of the remote peer.
	RemotePeer() peer.ID

	// RemotePublicKey returns the public key of the remote peer.
	RemotePublicKey() ic.PubKey
}

ConnSecurity is the interface that one can mix into a connection interface to give it the security methods.

type ConnStat added in v0.8.2 

type ConnStat interface {
	// Stat stores metadata pertaining to this conn.
	Stat() Stat
}

ConnStat is an interface mixin for connection types that provide connection statistics.

type Connectedness 

type Connectedness int

Connectedness signals the capacity for a connection with a given node. It is used to signal to services and other peers whether a node is reachable. 

const (
	// NotConnected means no connection to peer, and no extra information (default)
	NotConnected Connectedness = iota

	// Connected means has an open, live connection to peer
	Connected

	// CanConnect means recently connected to peer, terminated gracefully
	CanConnect

	// CannotConnect means recently attempted connecting but failed to connect.
	// (should signal "made effort, failed")
	CannotConnect
)

func (Connectedness) String added in v0.5.5 

func (c Connectedness) String() string

type Dialer 

type Dialer interface {
	// Peerstore returns the internal peerstore
	// This is useful to tell the dialer about a new address for a peer.
	// Or use one of the public keys found out over the network.
	Peerstore() peerstore.Peerstore

	// LocalPeer returns the local peer associated with this network
	LocalPeer() peer.ID

	// DialPeer establishes a connection to a given peer
	DialPeer(context.Context, peer.ID) (Conn, error)

	// ClosePeer closes the connection to a given peer
	ClosePeer(peer.ID) error

	// Connectedness returns a state signaling connection capabilities
	Connectedness(peer.ID) Connectedness

	// Peers returns the peers connected
	Peers() []peer.ID

	// Conns returns the connections in this Netowrk
	Conns() []Conn

	// ConnsToPeer returns the connections in this Netowrk for given peer.
	ConnsToPeer(p peer.ID) []Conn

	// Notify/StopNotify register and unregister a notifiee for signals
	Notify(Notifiee)
	StopNotify(Notifiee)
}

Dialer represents a service that can dial out to peers (this is usually just a Network, but other services may not need the whole stack, and thus it becomes easier to mock)

type Direction 

type Direction int

Direction represents which peer in a stream initiated a connection. 

const (
	// DirUnknown is the default direction.
	DirUnknown Direction = iota
	// DirInbound is for when the remote peer initiated a connection.
	DirInbound
	// DirOutbound is for when the local peer initiated a connection.
	DirOutbound
)

func (Direction) String added in v0.5.5 

func (d Direction) String() string

type NATDeviceType added in v0.8.4 

type NATDeviceType int

NATDeviceType indicates the type of the NAT device. 

const (
	// NATDeviceTypeUnknown indicates that the type of the NAT device is unknown.
	NATDeviceTypeUnknown NATDeviceType = iota

	// NATDeviceTypeCone indicates that the NAT device is a Cone NAT.
	// A Cone NAT is a NAT where all outgoing connections from the same source IP address and port are mapped by the NAT device
	// to the same IP address and port irrespective of the destination address.
	// With regards to RFC 3489, this could be either a Full Cone NAT, a Restricted Cone NAT or a
	// Port Restricted Cone NAT. However, we do NOT differentiate between them here and simply classify all such NATs as a Cone NAT.
	// NAT traversal with hole punching is possible with a Cone NAT ONLY if the remote peer is ALSO behind a Cone NAT.
	// If the remote peer is behind a Symmetric NAT, hole punching will fail.
	NATDeviceTypeCone

	// NATDeviceTypeSymmetric indicates that the NAT device is a Symmetric NAT.
	// A Symmetric NAT maps outgoing connections with different destination addresses to different IP addresses and ports,
	// even if they originate from the same source IP address and port.
	// NAT traversal with hole-punching is currently NOT possible in libp2p with Symmetric NATs irrespective of the remote peer's NAT type.
	NATDeviceTypeSymmetric
)

func (NATDeviceType) String added in v0.8.4 

func (r NATDeviceType) String() string

type NATTransportProtocol added in v0.8.4 

type NATTransportProtocol int

NATTransportProtocol is the transport protocol for which the NAT Device Type has been determined. 

const (
	// NATTransportUDP means that the NAT Device Type has been determined for the UDP Protocol.
	NATTransportUDP NATTransportProtocol = iota
	// NATTransportTCP means that the NAT Device Type has been determined for the TCP Protocol.
	NATTransportTCP
)

func (NATTransportProtocol) String added in v0.8.4 

func (n NATTransportProtocol) String() string

type Network 

type Network interface {
	Dialer
	io.Closer

	// SetStreamHandler sets the handler for new streams opened by the
	// remote side. This operation is threadsafe.
	SetStreamHandler(StreamHandler)

	// NewStream returns a new stream to given peer p.
	// If there is no connection to p, attempts to create one.
	NewStream(context.Context, peer.ID) (Stream, error)

	// Listen tells the network to start listening on given multiaddrs.
	Listen(...ma.Multiaddr) error

	// ListenAddresses returns a list of addresses at which this network listens.
	ListenAddresses() []ma.Multiaddr

	// InterfaceListenAddresses returns a list of addresses at which this network
	// listens. It expands "any interface" addresses (/ip4/0.0.0.0, /ip6/::) to
	// use the known local interfaces.
	InterfaceListenAddresses() ([]ma.Multiaddr, error)

	io.Closer
}

Network is the interface used to connect to the outside world. It dials and listens for connections. it uses a Swarm to pool connections (see swarm pkg, and peerstream.Swarm). Connections are encrypted with a TLS-like protocol.

type NoopNotifiee 

type NoopNotifiee struct{}

func (*NoopNotifiee) ClosedStream 

func (nn *NoopNotifiee) ClosedStream(Network, Stream)

func (*NoopNotifiee) Connected 

func (nn *NoopNotifiee) Connected(n Network, c Conn)

func (*NoopNotifiee) Disconnected 

func (nn *NoopNotifiee) Disconnected(n Network, c Conn)

func (*NoopNotifiee) Listen 

func (nn *NoopNotifiee) Listen(n Network, addr ma.Multiaddr)

func (*NoopNotifiee) ListenClose 

func (nn *NoopNotifiee) ListenClose(n Network, addr ma.Multiaddr)

func (*NoopNotifiee) OpenedStream 

func (nn *NoopNotifiee) OpenedStream(Network, Stream)

type Notifiee 

type Notifiee interface {
	Listen(Network, ma.Multiaddr)      // called when network starts listening on an addr
	ListenClose(Network, ma.Multiaddr) // called when network stops listening on an addr
	Connected(Network, Conn)           // called when a connection opened
	Disconnected(Network, Conn)        // called when a connection closed
	OpenedStream(Network, Stream)      // called when a stream opened
	ClosedStream(Network, Stream)      // called when a stream closed

}

Notifiee is an interface for an object wishing to receive notifications from a Network.

type NotifyBundle 

type NotifyBundle struct {
	ListenF      func(Network, ma.Multiaddr)
	ListenCloseF func(Network, ma.Multiaddr)

	ConnectedF    func(Network, Conn)
	DisconnectedF func(Network, Conn)

	OpenedStreamF func(Network, Stream)
	ClosedStreamF func(Network, Stream)
}

NotifyBundle implements Notifiee by calling any of the functions set on it, and nop'ing if they are unset. This is the easy way to register for notifications.

func (*NotifyBundle) ClosedStream 

func (nb *NotifyBundle) ClosedStream(n Network, s Stream)

ClosedStream calls ClosedStreamF if it is not null.

func (*NotifyBundle) Connected 

func (nb *NotifyBundle) Connected(n Network, c Conn)

Connected calls ConnectedF if it is not null.

func (*NotifyBundle) Disconnected 

func (nb *NotifyBundle) Disconnected(n Network, c Conn)

Disconnected calls DisconnectedF if it is not null.

func (*NotifyBundle) Listen 

func (nb *NotifyBundle) Listen(n Network, a ma.Multiaddr)

Listen calls ListenF if it is not null.

func (*NotifyBundle) ListenClose 

func (nb *NotifyBundle) ListenClose(n Network, a ma.Multiaddr)

ListenClose calls ListenCloseF if it is not null.

func (*NotifyBundle) OpenedStream 

func (nb *NotifyBundle) OpenedStream(n Network, s Stream)

OpenedStream calls OpenedStreamF if it is not null.

type Reachability added in v0.4.0 

type Reachability int

Reachability indicates how reachable a node is. 

const (
	// ReachabilityUnknown indicates that the reachability status of the
	// node is unknown.
	ReachabilityUnknown Reachability = iota

	// ReachabilityPublic indicates that the node is reachable from the
	// public internet.
	ReachabilityPublic

	// ReachabilityPrivate indicates that the node is not reachable from the
	// public internet.
	//
	// NOTE: This node may _still_ be reachable via relays.
	ReachabilityPrivate
)

func (Reachability) String added in v0.5.5 

func (r Reachability) String() string

type Stat 

type Stat struct {
	// Direction specifies whether this is an inbound or an outbound connection.
	Direction Direction
	// Opened is the timestamp when this connection was opened.
	Opened time.Time
	// Transient indicates that this connection is transient and may be closed soon.
	Transient bool
	// Extra stores additional metadata about this connection.
	Extra map[interface{}]interface{}
}

Stat stores metadata pertaining to a given Stream/Conn.

type Stream 

type Stream interface {
	mux.MuxedStream

	// ID returns an identifier that uniquely identifies this Stream within this
	// host, during this run. Stream IDs may repeat across restarts.
	ID() string

	Protocol() protocol.ID
	SetProtocol(id protocol.ID)

	// Stat returns metadata pertaining to this stream.
	Stat() Stat

	// Conn returns the connection this stream is part of.
	Conn() Conn
}

Stream represents a bidirectional channel between two agents in a libp2p network. "agent" is as granular as desired, potentially being a "request -> reply" pair, or whole protocols.

Streams are backed by a multiplexer underneath the hood.

type StreamHandler 

type StreamHandler func(Stream)

StreamHandler is the type of function used to listen for streams opened by the remote side.

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.