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
- Variables
- func GetDialPeerTimeout(ctx context.Context) time.Duration
- func GetForceDirectDial(ctx context.Context) (forceDirect bool, reason string)
- func GetNoDial(ctx context.Context) (nodial bool, reason string)
- func WithDialPeerTimeout(ctx context.Context, timeout time.Duration) context.Context
- func WithForceDirectDial(ctx context.Context, reason string) context.Context
- func WithNoDial(ctx context.Context, reason string) context.Context
- type Conn
- type ConnHandler
- type ConnMultiaddrs
- type ConnSecurity
- type Connectedness
- type Dialer
- type Direction
- type Network
- type NoopNotifiee
- func (nn *NoopNotifiee) ClosedStream(Network, Stream)
- func (nn *NoopNotifiee) Connected(n Network, c Conn)
- func (nn *NoopNotifiee) Disconnected(n Network, c Conn)
- func (nn *NoopNotifiee) Listen(n Network, addr ma.Multiaddr)
- func (nn *NoopNotifiee) ListenClose(n Network, addr ma.Multiaddr)
- func (nn *NoopNotifiee) OpenedStream(Network, Stream)
- type Notifiee
- type NotifyBundle
- func (nb *NotifyBundle) ClosedStream(n Network, s Stream)
- func (nb *NotifyBundle) Connected(n Network, c Conn)
- func (nb *NotifyBundle) Disconnected(n Network, c Conn)
- func (nb *NotifyBundle) Listen(n Network, a ma.Multiaddr)
- func (nb *NotifyBundle) ListenClose(n Network, a ma.Multiaddr)
- func (nb *NotifyBundle) OpenedStream(n Network, s Stream)
- type Reachability
- type Stat
- type Stream
- type StreamHandler
Constants ¶
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 ¶
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.
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.
var ErrNoRemoteAddrs = errors.New("no remote addresses")
ErrNoRemoteAddrs is returned when there are no addresses associated with a peer during a dial.
var GlobalNoopNotifiee = &NoopNotifiee{}
Global noop notifiee. Do not change.
Functions ¶
func GetDialPeerTimeout ¶
GetDialPeerTimeout returns the current DialPeer timeout (or the default).
func GetForceDirectDial ¶ added in v0.7.1
EXPERIMENTAL GetForceDirectDial returns true if the force direct dial option is set in the context.
func WithDialPeerTimeout ¶
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
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.
Types ¶
type Conn ¶
type Conn interface { io.Closer ConnSecurity ConnMultiaddrs // 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 // Stat stores metadata pertaining to this conn. Stat() Stat }
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 ConnHandler ¶
type ConnHandler func(Conn)
ConnHandler is the type of function used to listen for connections opened by the remote side.
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 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.
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) // SetConnHandler sets the handler for new connections opened by the // remote side. This operation is threadsafe. SetConnHandler(ConnHandler) // 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) // Process returns the network's Process Process() goprocess.Process }
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) 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 // 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.