go-libp2p-core: github.com/libp2p/go-libp2p-core/network Index | Files

package network

import "github.com/libp2p/go-libp2p-core/network"

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.


Package Files

conn.go context.go errors.go network.go notifee.go stream.go


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

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

    // ReachabilityPrivate indicates that the node is not reachable from the
    // public internet.
    // NOTE: This node may _still_ be reachable via relays.
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.


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.

func GetDialPeerTimeout Uses

func GetDialPeerTimeout(ctx context.Context) time.Duration

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

func GetNoDial Uses

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

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

func WithDialPeerTimeout Uses

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 WithNoDial Uses

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.

type Conn Uses

type Conn interface {


    // NewStream constructs a new Stream over this conn.
    NewStream() (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:


type ConnHandler Uses

type ConnHandler func(Conn)

ConnHandler is the type of function used to listen for connections opened by the remote side.

type ConnMultiaddrs Uses

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 Uses

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 Uses

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

    // CanConnect means recently connected to peer, terminated gracefully

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

type Dialer Uses

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

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 Uses

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.
    // DirOutbound is for when the local peer initiated a connection.

type Network Uses

type Network interface {

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

    // SetConnHandler sets the handler for new connections opened by the
    // remote side. This operation is threadsafe.

    // 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/, /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 Uses

type NoopNotifiee struct{}

func (*NoopNotifiee) ClosedStream Uses

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

func (*NoopNotifiee) Connected Uses

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

func (*NoopNotifiee) Disconnected Uses

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

func (*NoopNotifiee) Listen Uses

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

func (*NoopNotifiee) ListenClose Uses

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

func (*NoopNotifiee) OpenedStream Uses

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

type Notifiee Uses

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 Uses

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 Uses

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

ClosedStream calls ClosedStreamF if it is not null.

func (*NotifyBundle) Connected Uses

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

Connected calls ConnectedF if it is not null.

func (*NotifyBundle) Disconnected Uses

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

Disconnected calls DisconnectedF if it is not null.

func (*NotifyBundle) Listen Uses

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

Listen calls ListenF if it is not null.

func (*NotifyBundle) ListenClose Uses

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

ListenClose calls ListenCloseF if it is not null.

func (*NotifyBundle) OpenedStream Uses

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

OpenedStream calls OpenedStreamF if it is not null.

type Reachability Uses

type Reachability int

Reachability indicates how reachable a node is.

type Stat Uses

type Stat struct {
    Direction Direction
    Extra     map[interface{}]interface{}

Stat stores metadata pertaining to a given Stream/Conn.

type Stream Uses

type Stream interface {

    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 Uses

type StreamHandler func(Stream)

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

Package network imports 11 packages (graph) and is imported by 169 packages. Updated 2020-03-05. Refresh now. Tools for package owners.