Involved Source Filesconn.gocontext.goerrors.gomux.gonattype.go 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.notifee.gorcmgr.gostream.go
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()( Conn) Close() error CloseWithError closes the connection with errCode. The errCode is sent to the
peer on a best effort basis. For transports that do not support sending error
codes on connection close, the behavior is identical to calling Close. ConnState returns information about the connection state. GetStreams returns all open streams over this conn. ID returns an identifier that uniquely identifies this Conn within this
host, during this run. Connection IDs may repeat across restarts. IsClosed returns whether a connection is fully closed, so it can
be garbage collected. LocalMultiaddr returns the local Multiaddr associated
with this connection LocalPeer returns our peer ID NewStream constructs a new Stream over this conn. RemoteMultiaddr returns the remote Multiaddr associated
with this connection RemotePeer returns the peer ID of the remote peer. RemotePublicKey returns the public key of the remote peer. Scope returns the user view of this connection's resource scope Stat stores metadata pertaining to this conn.
*github.com/libp2p/go-libp2p/p2p/net/swarm.Conn
Conn : ConnMultiaddrs
Conn : ConnScoper
Conn : ConnSecurity
Conn : ConnStat
Conn : github.com/prometheus/common/expfmt.Closer
Conn : io.Closer
func Dialer.Conns() []Conn
func Dialer.ConnsToPeer(p peer.ID) []Conn
func Dialer.DialPeer(context.Context, peer.ID) (Conn, error)
func Network.Conns() []Conn
func Network.ConnsToPeer(p peer.ID) []Conn
func Network.DialPeer(context.Context, peer.ID) (Conn, error)
func Stream.Conn() Conn
func github.com/libp2p/go-libp2p/core/transport.TransportNetwork.Conns() []Conn
func github.com/libp2p/go-libp2p/core/transport.TransportNetwork.ConnsToPeer(p peer.ID) []Conn
func github.com/libp2p/go-libp2p/core/transport.TransportNetwork.DialPeer(context.Context, peer.ID) (Conn, error)
func github.com/libp2p/go-libp2p/p2p/net/swarm.(*Stream).Conn() Conn
func github.com/libp2p/go-libp2p/p2p/net/swarm.(*Swarm).Conns() []Conn
func github.com/libp2p/go-libp2p/p2p/net/swarm.(*Swarm).ConnsToPeer(p peer.ID) []Conn
func github.com/libp2p/go-libp2p/p2p/net/swarm.(*Swarm).DialPeer(ctx context.Context, p peer.ID) (Conn, error)
func (*NoopNotifiee).Connected(_ Network, _ Conn)
func (*NoopNotifiee).Disconnected(_ Network, _ Conn)
func Notifiee.Connected(Network, Conn)
func Notifiee.Disconnected(Network, Conn)
func (*NotifyBundle).Connected(n Network, c Conn)
func (*NotifyBundle).Disconnected(n Network, c Conn)
func github.com/libp2p/go-libp2p/core/connmgr.ConnectionGater.InterceptUpgraded(Conn) (allow bool, reason control.DisconnectReason)
func github.com/libp2p/go-libp2p/p2p/host/autonat.(*AmbientAutoNAT).Connected(_ Network, c Conn)
func github.com/libp2p/go-libp2p/p2p/host/autonat.(*AmbientAutoNAT).Disconnected(_ Network, _ Conn)
func github.com/libp2p/go-libp2p/p2p/protocol/identify.IDService.IdentifyConn(Conn)
func github.com/libp2p/go-libp2p/p2p/protocol/identify.IDService.IdentifyWait(Conn) <-chan struct{}
ConnectionState holds information about the connection. The security protocol used on this connection (if any). For example: /tls/1.0.0 The stream multiplexer used on this connection (if any). For example: /yamux/1.0.0 the transport used on this connection. For example: tcp indicates whether StreamMultiplexer was selected using inlined muxer negotiation
func Conn.ConnState() ConnectionState
func ConnSecurity.ConnState() ConnectionState
func github.com/libp2p/go-libp2p/core/sec.SecureConn.ConnState() ConnectionState
func github.com/libp2p/go-libp2p/core/sec/insecure.(*Conn).ConnState() ConnectionState
func github.com/libp2p/go-libp2p/core/transport.CapableConn.ConnState() ConnectionState
func github.com/libp2p/go-libp2p/p2p/net/swarm.(*Conn).ConnState() ConnectionState
func github.com/libp2p/go-libp2p/p2p/net/swarm.MetricsTracer.ClosedConnection(Direction, time.Duration, ConnectionState, ma.Multiaddr)
func github.com/libp2p/go-libp2p/p2p/net/swarm.MetricsTracer.CompletedHandshake(time.Duration, ConnectionState, ma.Multiaddr)
func github.com/libp2p/go-libp2p/p2p/net/swarm.MetricsTracer.OpenedConnection(Direction, crypto.PubKey, ConnectionState, ma.Multiaddr)
ConnManagementScope is the low level interface for connection resource scopes.
This interface is used by the low level components of the system who create and own
the span of a connection scope. BeginSpan creates a new span scope rooted at this scope Done ends the span and releases associated resources. PeerScope returns the peer scope associated with this connection.
It returns nil if the connection is not yet associated with any peer. ReleaseMemory explicitly releases memory previously reserved with ReserveMemory ReserveMemory reserves memory/buffer space in the scope; the unit is bytes.
If ReserveMemory returns an error, then no memory was reserved and the caller should handle
the failure condition.
The priority argument indicates the priority of the memory reservation. A reservation
will fail if the available memory is less than (1+prio)/256 of the scope limit, providing
a mechanism to gracefully handle optional reservations that might overload the system.
For instance, a muxer growing a window buffer will use a low priority and only grow the buffer
if there is no memory pressure in the system.
There are 4 predefined priority levels, Low, Medium, High and Always,
capturing common patterns, but the user is free to use any granularity applicable to his case. SetPeer sets the peer for a previously unassociated connection Stat retrieves current resource usage for the scope.
*NullScope
ConnManagementScope : ConnScope
ConnManagementScope : ResourceScope
ConnManagementScope : ResourceScopeSpan
ConnManagementScope : github.com/libp2p/go-yamux/v5.MemoryManager
func UnwrapConnManagementScope(ctx context.Context) (ConnManagementScope, error)
func (*NullResourceManager).OpenConnection(_ Direction, _ bool, _ multiaddr.Multiaddr) (ConnManagementScope, error)
func ResourceManager.OpenConnection(dir Direction, usefd bool, endpoint multiaddr.Multiaddr) (ConnManagementScope, error)
func github.com/libp2p/go-libp2p/core/transport.GatedMaListener.Accept() (manet.Conn, ConnManagementScope, error)
func WithConnManagementScope(ctx context.Context, scope ConnManagementScope) context.Context
func github.com/libp2p/go-libp2p/core/transport.Upgrader.Upgrade(ctx context.Context, t transport.Transport, maconn manet.Conn, dir Direction, p peer.ID, scope ConnManagementScope) (transport.CapableConn, error)
ConnMultiaddrs is an interface mixin for connection types that provide multiaddr
addresses for the endpoints. LocalMultiaddr returns the local Multiaddr associated
with this connection RemoteMultiaddr returns the remote Multiaddr associated
with this connectionConn(interface)
github.com/libp2p/go-libp2p/core/transport.CapableConn(interface)
*github.com/libp2p/go-libp2p/p2p/net/swarm.Conn
*github.com/libp2p/go-libp2p/p2p/protocol/circuitv2/client.Conn
github.com/libp2p/go-libp2p/p2p/transport/tcpreuse/internal/sampledconn.ManetTCPConnInterface(interface)
*github.com/libp2p/go-libp2p/p2p/transport/websocket.Conn
github.com/multiformats/go-multiaddr/net.Conn(interface)
func github.com/libp2p/go-libp2p/core/connmgr.ConnectionGater.InterceptAccept(ConnMultiaddrs) (allow bool)
func github.com/libp2p/go-libp2p/core/connmgr.ConnectionGater.InterceptSecured(Direction, peer.ID, ConnMultiaddrs) (allow bool)
func github.com/libp2p/go-libp2p/p2p/protocol/holepunch.MetricsTracer.HolePunchFinished(side string, attemptNum int, theirAddrs []ma.Multiaddr, ourAddr []ma.Multiaddr, directConn ConnMultiaddrs)
ConnScope is the user view of a connection scope BeginSpan creates a new span scope rooted at this scope ReleaseMemory explicitly releases memory previously reserved with ReserveMemory ReserveMemory reserves memory/buffer space in the scope; the unit is bytes.
If ReserveMemory returns an error, then no memory was reserved and the caller should handle
the failure condition.
The priority argument indicates the priority of the memory reservation. A reservation
will fail if the available memory is less than (1+prio)/256 of the scope limit, providing
a mechanism to gracefully handle optional reservations that might overload the system.
For instance, a muxer growing a window buffer will use a low priority and only grow the buffer
if there is no memory pressure in the system.
There are 4 predefined priority levels, Low, Medium, High and Always,
capturing common patterns, but the user is free to use any granularity applicable to his case. Stat retrieves current resource usage for the scope.ConnManagementScope(interface)
*NullScopePeerScope(interface)ProtocolScope(interface)ResourceScope(interface)ResourceScopeSpan(interface)ServiceScope(interface)StreamManagementScope(interface)StreamScope(interface)
ConnScope : ResourceScope
func Conn.Scope() ConnScope
func ConnScoper.Scope() ConnScope
func github.com/libp2p/go-libp2p/core/transport.CapableConn.Scope() ConnScope
func github.com/libp2p/go-libp2p/p2p/net/swarm.(*Conn).Scope() ConnScope
ConnScoper is the interface that one can mix into a connection interface to give it a resource
management scope Scope returns the user view of this connection's resource scopeConn(interface)
github.com/libp2p/go-libp2p/core/transport.CapableConn(interface)
*github.com/libp2p/go-libp2p/p2p/net/swarm.Conn
ConnSecurity is the interface that one can mix into a connection interface to
give it the security methods. ConnState returns information about the connection state. LocalPeer returns our peer ID RemotePeer returns the peer ID of the remote peer. RemotePublicKey returns the public key of the remote peer.Conn(interface)
github.com/libp2p/go-libp2p/core/sec.SecureConn(interface)
*github.com/libp2p/go-libp2p/core/sec/insecure.Conn
github.com/libp2p/go-libp2p/core/transport.CapableConn(interface)
*github.com/libp2p/go-libp2p/p2p/net/swarm.Conn
ConnStat is an interface mixin for connection types that provide connection statistics. Stat stores metadata pertaining to this conn.Conn(interface)
*github.com/libp2p/go-libp2p/p2p/net/swarm.Conn
*github.com/libp2p/go-libp2p/p2p/protocol/circuitv2/client.Conn
ConnStats stores metadata pertaining to a given Conn. NumStreams is the number of streams on the connection.StatsStats Direction specifies whether this is an inbound or an outbound connection. Extra stores additional metadata about this connection. Limited indicates that this connection is Limited. It maybe limited by
bytes or time. In practice, this is a connection formed over a circuit v2
relay. Opened is the timestamp when this connection was opened.
func Conn.Stat() ConnStats
func ConnStat.Stat() ConnStats
func github.com/libp2p/go-libp2p/p2p/net/swarm.(*Conn).Stat() ConnStats
func github.com/libp2p/go-libp2p/p2p/protocol/circuitv2/client.(*Conn).Stat() ConnStats
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) CanDial returns whether the dialer can dial peer p at addr ClosePeer closes the connection to a given peer Connectedness returns a state signaling connection capabilities Conns returns the connections in this Network ConnsToPeer returns the connections in this Network for given peer. DialPeer establishes a connection to a given peer LocalPeer returns the local peer associated with this network Notify/StopNotify register and unregister a notifiee for signals Peers returns the peers connected 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.( Dialer) StopNotify(Notifiee)Network(interface)
github.com/libp2p/go-libp2p/core/transport.TransportNetwork(interface)
*github.com/libp2p/go-libp2p/p2p/net/swarm.Swarm
DialRanker provides a schedule of dialing the provided addresses
func github.com/libp2p/go-libp2p.DialRanker(d DialRanker) libp2p.Option
func github.com/libp2p/go-libp2p/p2p/net/swarm.WithDialRanker(d DialRanker) swarm.Option
ResolveDNSAddr resolves the first /dnsaddr component in a multiaddr.
Recurisvely resolves DNSADDRs up to the recursion limit ResolveDNSComponent resolves the first /{dns,dns4,dns6} component in a multiaddr.
github.com/libp2p/go-libp2p/p2p/net/swarm.ResolverFromMaDNS
func github.com/libp2p/go-libp2p.MultiaddrResolver(rslv MultiaddrDNSResolver) libp2p.Option
func github.com/libp2p/go-libp2p/p2p/net/swarm.WithMultiaddrResolver(resolver MultiaddrDNSResolver) swarm.Option
Multiplexer wraps a net.Conn with a stream multiplexing
implementation and returns a MuxedConn that supports opening
multiple streams over the underlying net.Conn NewConn constructs a new connection
*github.com/libp2p/go-libp2p/p2p/muxer/yamux.Transport
func github.com/libp2p/go-libp2p.Muxer(name string, muxer Multiplexer) libp2p.Option
MuxedConn represents a connection to a remote peer that has been
extended to support stream multiplexing.
A MuxedConn allows a single net.Conn connection to carry many logically
independent bidirectional streams of binary data.
Together with network.ConnSecurity, MuxedConn is a component of the
transport.CapableConn interface, which represents a "raw" network
connection that has been "upgraded" to support the libp2p capabilities
of secure communication and stream multiplexing. AcceptStream accepts a stream opened by the other side.( MuxedConn) Close() error CloseWithError closes the connection with errCode. The errCode is sent
to the peer. IsClosed returns whether a connection is fully closed, so it can
be garbage collected. OpenStream creates a new stream.
github.com/libp2p/go-libp2p/core/transport.CapableConn(interface)
MuxedConn : github.com/prometheus/common/expfmt.Closer
MuxedConn : io.Closer
func Multiplexer.NewConn(c net.Conn, isServer bool, scope PeerScope) (MuxedConn, error)
func github.com/libp2p/go-libp2p/p2p/muxer/yamux.NewMuxedConn(m *yamux.Session) MuxedConn
func github.com/libp2p/go-libp2p/p2p/muxer/yamux.(*Transport).NewConn(nc net.Conn, isServer bool, scope PeerScope) (MuxedConn, error)
MuxedStream is a bidirectional io pipe within a connection.( MuxedStream) Close() error CloseRead closes the stream for reading but leaves it open for
writing.
When CloseRead is called, all in-progress Read calls are interrupted with a non-EOF error and
no further calls to Read will succeed.
The handling of new incoming data on the stream after calling this function is implementation defined.
CloseRead does not free the stream, users must still call Close or
Reset. CloseWrite closes the stream for writing but leaves it open for
reading.
CloseWrite does not free the stream, users must still call Close or
Reset.( MuxedStream) Read(p []byte) (n int, err error) Reset closes both ends of the stream. Use this to tell the remote
side to hang up and go away. ResetWithError aborts both ends of the stream with `errCode`. `errCode` is sent
to the peer on a best effort basis. For transports that do not support sending
error codes to remote peer, the behavior is identical to calling Reset( MuxedStream) SetDeadline(time.Time) error( MuxedStream) SetReadDeadline(time.Time) error( MuxedStream) SetWriteDeadline(time.Time) error( MuxedStream) Write([]byte) (int, error)Stream(interface)
*github.com/libp2p/go-libp2p/p2p/net/swarm.Stream
MuxedStream : github.com/miekg/dns.Writer
MuxedStream : github.com/pion/datachannel.ReadDeadliner
MuxedStream : github.com/pion/datachannel.WriteDeadliner
MuxedStream : github.com/pion/stun.Connection
MuxedStream : github.com/pion/stun/v3.Connection
MuxedStream : github.com/prometheus/common/expfmt.Closer
MuxedStream : internal/bisect.Writer
MuxedStream : io.Closer
MuxedStream : io.ReadCloser
MuxedStream : io.Reader
MuxedStream : io.ReadWriteCloser
MuxedStream : io.ReadWriter
MuxedStream : io.WriteCloser
MuxedStream : io.Writer
func MuxedConn.AcceptStream() (MuxedStream, error)
func MuxedConn.OpenStream(context.Context) (MuxedStream, error)
func github.com/libp2p/go-libp2p/core/transport.CapableConn.AcceptStream() (MuxedStream, error)
func github.com/libp2p/go-libp2p/core/transport.CapableConn.OpenStream(context.Context) (MuxedStream, error)
NATTransportProtocol is the transport protocol for which the NAT Device Type has been determined.( NATTransportProtocol) String() string
NATTransportProtocol : expvar.Var
NATTransportProtocol : fmt.Stringer
const NATTransportTCP
const NATTransportUDP
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. CanDial returns whether the dialer can dial peer p at addr( Network) Close() error ClosePeer closes the connection to a given peer Connectedness returns a state signaling connection capabilities Conns returns the connections in this Network ConnsToPeer returns the connections in this Network for given peer. DialPeer establishes a connection to a given peer 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. Listen tells the network to start listening on given multiaddrs. ListenAddresses returns a list of addresses at which this network listens. LocalPeer returns the local peer associated with this network NewStream returns a new stream to given peer p.
If there is no connection to p, attempts to create one. Notify/StopNotify register and unregister a notifiee for signals Peers returns the peers connected 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. ResourceManager returns the ResourceManager associated with this network SetStreamHandler sets the handler for new streams opened by the
remote side. This operation is thread-safe.( Network) StopNotify(Notifiee)
github.com/libp2p/go-libp2p/core/transport.TransportNetwork(interface)
*github.com/libp2p/go-libp2p/p2p/net/swarm.Swarm
Network : Dialer
Network : github.com/prometheus/common/expfmt.Closer
Network : io.Closer
func github.com/libp2p/go-libp2p/core/host.Host.Network() Network
func github.com/libp2p/go-libp2p/p2p/host/basic.(*BasicHost).Network() Network
func github.com/libp2p/go-libp2p/p2p/host/blank.(*BlankHost).Network() Network
func github.com/libp2p/go-libp2p/p2p/host/routed.(*RoutedHost).Network() Network
func (*NoopNotifiee).Connected(_ Network, _ Conn)
func (*NoopNotifiee).Disconnected(_ Network, _ Conn)
func (*NoopNotifiee).Listen(_ Network, _ ma.Multiaddr)
func (*NoopNotifiee).ListenClose(_ Network, _ ma.Multiaddr)
func Notifiee.Connected(Network, Conn)
func Notifiee.Disconnected(Network, Conn)
func Notifiee.Listen(Network, ma.Multiaddr)
func Notifiee.ListenClose(Network, ma.Multiaddr)
func (*NotifyBundle).Connected(n Network, c Conn)
func (*NotifyBundle).Disconnected(n Network, c Conn)
func (*NotifyBundle).Listen(n Network, a ma.Multiaddr)
func (*NotifyBundle).ListenClose(n Network, a ma.Multiaddr)
func github.com/libp2p/go-libp2p/p2p/host/autonat.EnableService(dialer Network) autonat.Option
func github.com/libp2p/go-libp2p/p2p/host/autonat.(*AmbientAutoNAT).Connected(_ Network, c Conn)
func github.com/libp2p/go-libp2p/p2p/host/autonat.(*AmbientAutoNAT).Disconnected(_ Network, _ Conn)
func github.com/libp2p/go-libp2p/p2p/host/autonat.(*AmbientAutoNAT).Listen(_ Network, _ ma.Multiaddr)
func github.com/libp2p/go-libp2p/p2p/host/autonat.(*AmbientAutoNAT).ListenClose(_ Network, _ ma.Multiaddr)
func github.com/libp2p/go-libp2p/p2p/host/basic.NewHost(n Network, opts *basichost.HostOpts) (*basichost.BasicHost, error)
func github.com/libp2p/go-libp2p/p2p/host/basic.NewNATManager(net Network) basichost.NATManager
func github.com/libp2p/go-libp2p/p2p/host/blank.NewBlankHost(n Network, options ...blankhost.Option) *blankhost.BlankHost
func github.com/libp2p/go-libp2p/p2p/host/pstoremanager.NewPeerstoreManager(pstore peerstore.Peerstore, eventBus event.Bus, network Network, opts ...pstoremanager.Option) (*pstoremanager.PeerstoreManager, error)
Notifiee is an interface for an object wishing to receive
notifications from a Network. // called when a connection opened // called when a connection closed // called when network starts listening on an addr // called when network stops listening on an addr
*NoopNotifiee
*NotifyBundle
*github.com/libp2p/go-libp2p/p2p/host/autonat.AmbientAutoNAT
func github.com/libp2p/go-libp2p/core/connmgr.ConnManager.Notifee() Notifiee
func github.com/libp2p/go-libp2p/core/connmgr.NullConnMgr.Notifee() Notifiee
func github.com/libp2p/go-libp2p/p2p/net/connmgr.(*BasicConnMgr).Notifee() Notifiee
func Dialer.Notify(Notifiee)
func Dialer.StopNotify(Notifiee)
func Network.Notify(Notifiee)
func Network.StopNotify(Notifiee)
func github.com/libp2p/go-libp2p/core/transport.TransportNetwork.Notify(Notifiee)
func github.com/libp2p/go-libp2p/core/transport.TransportNetwork.StopNotify(Notifiee)
func github.com/libp2p/go-libp2p/p2p/net/swarm.(*Swarm).Notify(f Notifiee)
func github.com/libp2p/go-libp2p/p2p/net/swarm.(*Swarm).StopNotify(f Notifiee)
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.ConnectedFfunc(Network, Conn)DisconnectedFfunc(Network, Conn)ListenCloseFfunc(Network, ma.Multiaddr)ListenFfunc(Network, ma.Multiaddr) Connected calls ConnectedF if it is not null. Disconnected calls DisconnectedF if it is not null. Listen calls ListenF if it is not null. ListenClose calls ListenCloseF if it is not null.
*NotifyBundle : Notifiee
PeerScope is the interface for peer resource scopes. BeginSpan creates a new span scope rooted at this scope Peer returns the peer ID for this scope ReleaseMemory explicitly releases memory previously reserved with ReserveMemory ReserveMemory reserves memory/buffer space in the scope; the unit is bytes.
If ReserveMemory returns an error, then no memory was reserved and the caller should handle
the failure condition.
The priority argument indicates the priority of the memory reservation. A reservation
will fail if the available memory is less than (1+prio)/256 of the scope limit, providing
a mechanism to gracefully handle optional reservations that might overload the system.
For instance, a muxer growing a window buffer will use a low priority and only grow the buffer
if there is no memory pressure in the system.
There are 4 predefined priority levels, Low, Medium, High and Always,
capturing common patterns, but the user is free to use any granularity applicable to his case. Stat retrieves current resource usage for the scope.
*NullScope
PeerScope : ConnScope
PeerScope : ResourceScope
func ConnManagementScope.PeerScope() PeerScope
func (*NullScope).PeerScope() PeerScope
func StreamManagementScope.PeerScope() PeerScope
func Multiplexer.NewConn(c net.Conn, isServer bool, scope PeerScope) (MuxedConn, error)
func github.com/libp2p/go-libp2p/p2p/muxer/yamux.(*Transport).NewConn(nc net.Conn, isServer bool, scope PeerScope) (MuxedConn, error)
ProtocolScope is the interface for protocol resource scopes. BeginSpan creates a new span scope rooted at this scope Protocol returns the protocol for this scope ReleaseMemory explicitly releases memory previously reserved with ReserveMemory ReserveMemory reserves memory/buffer space in the scope; the unit is bytes.
If ReserveMemory returns an error, then no memory was reserved and the caller should handle
the failure condition.
The priority argument indicates the priority of the memory reservation. A reservation
will fail if the available memory is less than (1+prio)/256 of the scope limit, providing
a mechanism to gracefully handle optional reservations that might overload the system.
For instance, a muxer growing a window buffer will use a low priority and only grow the buffer
if there is no memory pressure in the system.
There are 4 predefined priority levels, Low, Medium, High and Always,
capturing common patterns, but the user is free to use any granularity applicable to his case. Stat retrieves current resource usage for the scope.
*NullScope
ProtocolScope : ConnScope
ProtocolScope : ResourceScope
func (*NullScope).ProtocolScope() ProtocolScope
func StreamManagementScope.ProtocolScope() ProtocolScope
ResourceManager is the interface to the network resource management subsystem.
The ResourceManager tracks and accounts for resource usage in the stack, from the internals
to the application, and provides a mechanism to limit resource usage according to a user
configurable policy.
Resource Management through the ResourceManager is based on the concept of Resource
Management Scopes, whereby resource usage is constrained by a DAG of scopes,
The following diagram illustrates the structure of the resource constraint DAG:
System
+------------> Transient.............+................+
| . .
+------------> Service------------- . ----------+ .
| . | .
+-------------> Protocol----------- . ----------+ .
| . | .
+--------------> Peer \ | .
+------------> Connection | .
| \ \
+---------------------------> Stream
The basic resources accounted by the ResourceManager include memory, streams, connections,
and file descriptors. These account for both space and time used by
the stack, as each resource has a direct effect on the system
availability and performance.
The modus operandi of the resource manager is to restrict resource usage at the time of
reservation. When a component of the stack needs to use a resource, it reserves it in the
appropriate scope. The resource manager gates the reservation against the scope applicable
limits; if the limit is exceeded, then an error (wrapping ErrResourceLimitExceeded) and it
is up the component to act accordingly. At the lower levels of the stack, this will normally
signal a failure of some sorts, like failing to opening a stream or a connection, which will
propagate to the programmer. Some components may be able to handle resource reservation failure
more gracefully; for instance a muxer trying to grow a buffer for a window change, will simply
retain the existing window size and continue to operate normally albeit with some degraded
throughput.
All resources reserved in some scope are released when the scope is closed. For low level
scopes, mainly Connection and Stream scopes, this happens when the connection or stream is
closed.
Service programmers will typically use the resource manager to reserve memory
for their subsystem.
This happens with two avenues: the programmer can attach a stream to a service, whereby
resources reserved by the stream are automatically accounted in the service budget; or the
programmer may directly interact with the service scope, by using ViewService through the
resource manager interface.
Application programmers can also directly reserve memory in some applicable scope. In order
to facilitate control flow delimited resource accounting, all scopes defined in the system
allow for the user to create spans. Spans are temporary scopes rooted at some
other scope and release their resources when the programmer is done with them. Span
scopes can form trees, with nested spans.
Typical Usage:
- Low level components of the system (transports, muxers) all have access to the resource
manager and create connection and stream scopes through it. These scopes are accessible
to the user, albeit with a narrower interface, through Conn and Stream objects who have
a Scope method.
- Services typically center around streams, where the programmer can attach streams to a
particular service. They can also directly reserve memory for a service by accessing the
service scope using the ResourceManager interface.
- Applications that want to account for their network resource usage can reserve memory,
typically using a span, directly in the System or a Service scope; they can also
opt to use appropriate stream scopes for streams that they create or own.
User Serviceable Parts: the user has the option to specify their own implementation of the
interface. We provide a canonical implementation in the go-libp2p-resource-manager package.
The user of that package can specify limits for the various scopes, which can be static
or dynamic.
WARNING The ResourceManager interface is considered experimental and subject to change
in subsequent releases. Close closes the resource manager OpenConnection creates a new connection scope not yet associated with any peer; the connection
is scoped at the transient scope.
The caller owns the returned scope and is responsible for calling Done in order to signify
the end of the scope's span. OpenStream creates a new stream scope, initially unnegotiated.
An unnegotiated stream will be initially unattached to any protocol scope
and constrained by the transient scope.
The caller owns the returned scope and is responsible for calling Done in order to signify
the end of th scope's span. VerifySourceAddress tells the transport to verify the source address for an incoming connection
before gating the connection with OpenConnection. ViewPeer views the resource management scope for a specific peer. ViewProtocol views the resource management scope for a specific protocol. ViewService retrieves a service-specific scope. ViewSystem views the system-wide resource scope.
The system scope is the top level scope that accounts for global
resource usage at all levels of the system. This scope constrains all
other scopes and institutes global hard limits. ViewTransient views the transient (DMZ) resource scope.
The transient scope accounts for resources that are in the process of
full establishment. For instance, a new connection prior to the
handshake does not belong to any peer, but it still needs to be
constrained as this opens an avenue for attacks in transient resource
usage. Similarly, a stream that has not negotiated a protocol yet is
constrained by the transient scope.
*NullResourceManager
ResourceManager : ResourceScopeViewer
ResourceManager : github.com/prometheus/common/expfmt.Closer
ResourceManager : io.Closer
func Network.ResourceManager() ResourceManager
func github.com/libp2p/go-libp2p/core/transport.TransportNetwork.ResourceManager() ResourceManager
func github.com/libp2p/go-libp2p/p2p/host/resource-manager.NewResourceManager(limits rcmgr.Limiter, opts ...rcmgr.Option) (ResourceManager, error)
func github.com/libp2p/go-libp2p/p2p/net/swarm.(*Swarm).ResourceManager() ResourceManager
func github.com/libp2p/go-libp2p.ResourceManager(rcmgr ResourceManager) libp2p.Option
func github.com/libp2p/go-libp2p/p2p/host/resource-manager.GetAllowlist(rcmgr ResourceManager) *rcmgr.Allowlist
func github.com/libp2p/go-libp2p/p2p/net/swarm.WithResourceManager(m ResourceManager) swarm.Option
func github.com/libp2p/go-libp2p/p2p/net/upgrader.New(security []sec.SecureTransport, muxers []upgrader.StreamMuxer, psk ipnet.PSK, rcmgr ResourceManager, connGater connmgr.ConnectionGater, opts ...upgrader.Option) (transport.Upgrader, error)
func github.com/libp2p/go-libp2p/p2p/transport/quic.NewTransport(key ic.PrivKey, connManager *quicreuse.ConnManager, psk pnet.PSK, gater connmgr.ConnectionGater, rcmgr ResourceManager) (tpt.Transport, error)
func github.com/libp2p/go-libp2p/p2p/transport/tcp.NewTCPTransport(upgrader transport.Upgrader, rcmgr ResourceManager, sharedTCP *tcpreuse.ConnMgr, opts ...tcp.Option) (*tcp.TcpTransport, error)
func github.com/libp2p/go-libp2p/p2p/transport/webrtc.New(privKey ic.PrivKey, psk pnet.PSK, gater connmgr.ConnectionGater, rcmgr ResourceManager, listenUDP libp2pwebrtc.ListenUDPFn, opts ...libp2pwebrtc.Option) (*libp2pwebrtc.WebRTCTransport, error)
func github.com/libp2p/go-libp2p/p2p/transport/websocket.New(u transport.Upgrader, rcmgr ResourceManager, sharedTCP *tcpreuse.ConnMgr, opts ...websocket.Option) (*websocket.WebsocketTransport, error)
func github.com/libp2p/go-libp2p/p2p/transport/webtransport.New(key ic.PrivKey, psk pnet.PSK, connManager *quicreuse.ConnManager, gater connmgr.ConnectionGater, rcmgr ResourceManager, opts ...libp2pwebtransport.Option) (tpt.Transport, error)
func github.com/pancsta/asyncmachine-go/pkg/pubsub/uds.NewUDSTransport(upgrader transport.Upgrader, rcmgr ResourceManager, opts ...func(*uds.UdsTransport) error) (*uds.UdsTransport, error)
ResourceScope is the interface for all scopes. BeginSpan creates a new span scope rooted at this scope ReleaseMemory explicitly releases memory previously reserved with ReserveMemory ReserveMemory reserves memory/buffer space in the scope; the unit is bytes.
If ReserveMemory returns an error, then no memory was reserved and the caller should handle
the failure condition.
The priority argument indicates the priority of the memory reservation. A reservation
will fail if the available memory is less than (1+prio)/256 of the scope limit, providing
a mechanism to gracefully handle optional reservations that might overload the system.
For instance, a muxer growing a window buffer will use a low priority and only grow the buffer
if there is no memory pressure in the system.
There are 4 predefined priority levels, Low, Medium, High and Always,
capturing common patterns, but the user is free to use any granularity applicable to his case. Stat retrieves current resource usage for the scope.ConnManagementScope(interface)ConnScope(interface)
*NullScopePeerScope(interface)ProtocolScope(interface)ResourceScopeSpan(interface)ServiceScope(interface)StreamManagementScope(interface)StreamScope(interface)
ResourceScope : ConnScope
ResourceScopeSpan is a ResourceScope with a delimited span.
Span scopes are control flow delimited and release all their associated resources
when the programmer calls Done.
Example:
s, err := someScope.BeginSpan()
if err != nil { ... }
defer s.Done()
if err := s.ReserveMemory(...); err != nil { ... }
// ... use memory BeginSpan creates a new span scope rooted at this scope Done ends the span and releases associated resources. ReleaseMemory explicitly releases memory previously reserved with ReserveMemory ReserveMemory reserves memory/buffer space in the scope; the unit is bytes.
If ReserveMemory returns an error, then no memory was reserved and the caller should handle
the failure condition.
The priority argument indicates the priority of the memory reservation. A reservation
will fail if the available memory is less than (1+prio)/256 of the scope limit, providing
a mechanism to gracefully handle optional reservations that might overload the system.
For instance, a muxer growing a window buffer will use a low priority and only grow the buffer
if there is no memory pressure in the system.
There are 4 predefined priority levels, Low, Medium, High and Always,
capturing common patterns, but the user is free to use any granularity applicable to his case. Stat retrieves current resource usage for the scope.ConnManagementScope(interface)
*NullScopeStreamManagementScope(interface)
ResourceScopeSpan : ConnScope
ResourceScopeSpan : ResourceScope
ResourceScopeSpan : github.com/libp2p/go-yamux/v5.MemoryManager
func ConnManagementScope.BeginSpan() (ResourceScopeSpan, error)
func ConnScope.BeginSpan() (ResourceScopeSpan, error)
func (*NullScope).BeginSpan() (ResourceScopeSpan, error)
func PeerScope.BeginSpan() (ResourceScopeSpan, error)
func ProtocolScope.BeginSpan() (ResourceScopeSpan, error)
func ResourceScope.BeginSpan() (ResourceScopeSpan, error)
func ResourceScopeSpan.BeginSpan() (ResourceScopeSpan, error)
func ServiceScope.BeginSpan() (ResourceScopeSpan, error)
func StreamManagementScope.BeginSpan() (ResourceScopeSpan, error)
func StreamScope.BeginSpan() (ResourceScopeSpan, error)
ResourceScopeViewer is a mixin interface providing view methods for accessing top level
scopes. ViewPeer views the resource management scope for a specific peer. ViewProtocol views the resource management scope for a specific protocol. ViewService retrieves a service-specific scope. ViewSystem views the system-wide resource scope.
The system scope is the top level scope that accounts for global
resource usage at all levels of the system. This scope constrains all
other scopes and institutes global hard limits. ViewTransient views the transient (DMZ) resource scope.
The transient scope accounts for resources that are in the process of
full establishment. For instance, a new connection prior to the
handshake does not belong to any peer, but it still needs to be
constrained as this opens an avenue for attacks in transient resource
usage. Similarly, a stream that has not negotiated a protocol yet is
constrained by the transient scope.
*NullResourceManagerResourceManager(interface)
ServiceScope is the interface for service resource scopes BeginSpan creates a new span scope rooted at this scope Name returns the name of this service ReleaseMemory explicitly releases memory previously reserved with ReserveMemory ReserveMemory reserves memory/buffer space in the scope; the unit is bytes.
If ReserveMemory returns an error, then no memory was reserved and the caller should handle
the failure condition.
The priority argument indicates the priority of the memory reservation. A reservation
will fail if the available memory is less than (1+prio)/256 of the scope limit, providing
a mechanism to gracefully handle optional reservations that might overload the system.
For instance, a muxer growing a window buffer will use a low priority and only grow the buffer
if there is no memory pressure in the system.
There are 4 predefined priority levels, Low, Medium, High and Always,
capturing common patterns, but the user is free to use any granularity applicable to his case. Stat retrieves current resource usage for the scope.
*NullScope
ServiceScope : ConnScope
ServiceScope : ResourceScope
ServiceScope : github.com/polarsignals/frostdb/query/logicalplan.Named
func (*NullScope).ServiceScope() ServiceScope
func StreamManagementScope.ServiceScope() ServiceScope
Stats stores metadata pertaining to a given Stream / Conn. Direction specifies whether this is an inbound or an outbound connection. Extra stores additional metadata about this connection. Limited indicates that this connection is Limited. It maybe limited by
bytes or time. In practice, this is a connection formed over a circuit v2
relay. Opened is the timestamp when this connection was opened.
func Stream.Stat() Stats
func github.com/libp2p/go-libp2p/p2p/net/swarm.(*Stream).Stat() Stats
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.( Stream) Close() error CloseRead closes the stream for reading but leaves it open for
writing.
When CloseRead is called, all in-progress Read calls are interrupted with a non-EOF error and
no further calls to Read will succeed.
The handling of new incoming data on the stream after calling this function is implementation defined.
CloseRead does not free the stream, users must still call Close or
Reset. CloseWrite closes the stream for writing but leaves it open for
reading.
CloseWrite does not free the stream, users must still call Close or
Reset. Conn returns the connection this stream is part of. ID returns an identifier that uniquely identifies this Stream within this
host, during this run. Stream IDs may repeat across restarts.( Stream) Protocol() protocol.ID( Stream) Read(p []byte) (n int, err error) Reset closes both ends of the stream. Use this to tell the remote
side to hang up and go away. ResetWithError aborts both ends of the stream with `errCode`. `errCode` is sent
to the peer on a best effort basis. For transports that do not support sending
error codes to remote peer, the behavior is identical to calling Reset Scope returns the user's view of this stream's resource scope( Stream) SetDeadline(time.Time) error( Stream) SetProtocol(id protocol.ID) error( Stream) SetReadDeadline(time.Time) error( Stream) SetWriteDeadline(time.Time) error Stat returns metadata pertaining to this stream.( Stream) Write([]byte) (int, error)
*github.com/libp2p/go-libp2p/p2p/net/swarm.Stream
Stream : MuxedStream
Stream : github.com/miekg/dns.Writer
Stream : github.com/pion/datachannel.ReadDeadliner
Stream : github.com/pion/datachannel.WriteDeadliner
Stream : github.com/pion/stun.Connection
Stream : github.com/pion/stun/v3.Connection
Stream : github.com/prometheus/common/expfmt.Closer
Stream : internal/bisect.Writer
Stream : io.Closer
Stream : io.ReadCloser
Stream : io.Reader
Stream : io.ReadWriteCloser
Stream : io.ReadWriter
Stream : io.WriteCloser
Stream : io.Writer
func Conn.GetStreams() []Stream
func Conn.NewStream(context.Context) (Stream, error)
func Network.NewStream(context.Context, peer.ID) (Stream, error)
func github.com/libp2p/go-libp2p/core/host.Host.NewStream(ctx context.Context, p peer.ID, pids ...protocol.ID) (Stream, error)
func github.com/libp2p/go-libp2p/core/transport.TransportNetwork.NewStream(context.Context, peer.ID) (Stream, error)
func github.com/libp2p/go-libp2p/p2p/host/basic.(*BasicHost).NewStream(ctx context.Context, p peer.ID, pids ...protocol.ID) (str Stream, strErr error)
func github.com/libp2p/go-libp2p/p2p/host/blank.(*BlankHost).NewStream(ctx context.Context, p peer.ID, protos ...protocol.ID) (Stream, error)
func github.com/libp2p/go-libp2p/p2p/host/routed.(*RoutedHost).NewStream(ctx context.Context, p peer.ID, pids ...protocol.ID) (Stream, error)
func github.com/libp2p/go-libp2p/p2p/net/swarm.(*Conn).GetStreams() []Stream
func github.com/libp2p/go-libp2p/p2p/net/swarm.(*Conn).NewStream(ctx context.Context) (Stream, error)
func github.com/libp2p/go-libp2p/p2p/net/swarm.(*Swarm).NewStream(ctx context.Context, p peer.ID) (Stream, error)
func github.com/libp2p/go-libp2p/p2p/protocol/ping.(*PingService).PingHandler(s Stream)
StreamManagementScope is the interface for stream resource scopes.
This interface is used by the low level components of the system who create and own
the span of a stream scope. BeginSpan creates a new span scope rooted at this scope Done ends the span and releases associated resources. PeerScope returns the peer resource scope associated with this stream. ProtocolScope returns the protocol resource scope associated with this stream.
It returns nil if the stream is not associated with any protocol scope. ReleaseMemory explicitly releases memory previously reserved with ReserveMemory ReserveMemory reserves memory/buffer space in the scope; the unit is bytes.
If ReserveMemory returns an error, then no memory was reserved and the caller should handle
the failure condition.
The priority argument indicates the priority of the memory reservation. A reservation
will fail if the available memory is less than (1+prio)/256 of the scope limit, providing
a mechanism to gracefully handle optional reservations that might overload the system.
For instance, a muxer growing a window buffer will use a low priority and only grow the buffer
if there is no memory pressure in the system.
There are 4 predefined priority levels, Low, Medium, High and Always,
capturing common patterns, but the user is free to use any granularity applicable to his case. ServiceScope returns the service owning the stream, if any. SetProtocol sets the protocol for a previously unnegotiated stream SetService sets the service owning this stream. Stat retrieves current resource usage for the scope.
*NullScope
StreamManagementScope : ConnScope
StreamManagementScope : ResourceScope
StreamManagementScope : ResourceScopeSpan
StreamManagementScope : StreamScope
StreamManagementScope : github.com/libp2p/go-yamux/v5.MemoryManager
func (*NullResourceManager).OpenStream(_ peer.ID, _ Direction) (StreamManagementScope, error)
func ResourceManager.OpenStream(p peer.ID, dir Direction) (StreamManagementScope, error)
StreamScope is the user view of a StreamScope. BeginSpan creates a new span scope rooted at this scope ReleaseMemory explicitly releases memory previously reserved with ReserveMemory ReserveMemory reserves memory/buffer space in the scope; the unit is bytes.
If ReserveMemory returns an error, then no memory was reserved and the caller should handle
the failure condition.
The priority argument indicates the priority of the memory reservation. A reservation
will fail if the available memory is less than (1+prio)/256 of the scope limit, providing
a mechanism to gracefully handle optional reservations that might overload the system.
For instance, a muxer growing a window buffer will use a low priority and only grow the buffer
if there is no memory pressure in the system.
There are 4 predefined priority levels, Low, Medium, High and Always,
capturing common patterns, but the user is free to use any granularity applicable to his case. SetService sets the service owning this stream. Stat retrieves current resource usage for the scope.
*NullScopeStreamManagementScope(interface)
StreamScope : ConnScope
StreamScope : ResourceScope
func Stream.Scope() StreamScope
func github.com/libp2p/go-libp2p/p2p/net/swarm.(*Stream).Scope() StreamScope
Package-Level Functions (total 14)
GetAllowLimitedConn returns true if the allow limited conn option is set in the context.
GetDialPeerTimeout returns the current DialPeer timeout (or the default).
EXPERIMENTAL
GetForceDirectDial returns true if the force direct dial option is set in the context.
GetNoDial returns true if the no dial option is set in the context.
GetSimultaneousConnect returns true if the simultaneous connect option is set in the context.
EXPERIMENTAL
GetUseTransient returns true if the use transient option is set in the context.
Deprecated: Use GetAllowLimitedConn instead.
WithAllowLimitedConn constructs a new context with an option that instructs
the network that it is acceptable to use a limited connection when opening a
new stream.
WithDialPeerTimeout returns a new context with the DialPeer timeout applied.
This timeout overrides the default DialPeerTimeout and applies per-dial
independently.
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.
WithNoDial constructs a new context with an option that instructs the network
to not attempt a new dial when opening a stream.
WithSimultaneousConnect constructs a new context with an option that instructs the transport
to apply hole punching logic where applicable.
EXPERIMENTAL
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.
Deprecated: Use WithAllowLimitedConn instead.
Package-Level Variables (total 9)
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.
ErrLimitedConn is returned when attempting to open a stream to a peer with only a conn
connection, without specifying the AllowLimitedConn option.
ErrNoConn is returned when attempting to open a stream to a peer with the NoDial
option and no usable connection is available.
ErrNoRemoteAddrs is returned when there are no addresses associated with a peer during a dial.
ErrReset is returned when reading or writing on a reset stream.
ErrResourceLimitExceeded is returned when attempting to perform an operation that would
exceed system resource limits.
ErrResourceScopeClosed is returned when attempting to reserve resources in a closed resource
scope.
ErrTransientConn is returned when attempting to open a stream to a peer with only a transient
connection, without specifying the UseTransient option.
Deprecated: Use ErrLimitedConn instead.
Global noop notifiee. Do not change.
Package-Level Constants (total 41)
Deprecated: CanConnect is deprecated and will be removed in a future release.
CanConnect means recently connected to peer, terminated gracefully
Deprecated: CannotConnect is deprecated and will be removed in a future release.
CannotConnect means recently attempted connecting but failed to connect.
(should signal "made effort, failed")
DirInbound is for when the remote peer initiated a connection.
DirOutbound is for when the local peer initiated a connection.
DirUnknown is the default direction.
Limited means we have a transient connection to the peer, but aren't fully connected.
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.
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.
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.
NATDeviceTypeUnknown indicates that the type of the NAT device is unknown.
NATTransportTCP means that the NAT Device Type has been determined for the TCP Protocol.
NATTransportUDP means that the NAT Device Type has been determined for the UDP Protocol.
NotConnected means no connection to peer, and no extra information (default)
ReachabilityPrivate indicates that the node is not reachable from the
public internet.
NOTE: This node may _still_ be reachable via relays.
ReachabilityPublic indicates that the node is reachable from the
public internet.
ReachabilityUnknown indicates that the reachability status of the
node is unknown.
ReservationPriorityAlways is a reservation priority that indicates a reservation if there is
enough memory, regardless of scope utilization.
ReservationPriorityHigh is a reservation priority that indicates a reservation if the scope
memory utilization is at 80% or less.
ReservationPriorityLow is a reservation priority that indicates a reservation if the scope
memory utilization is at 40% or less.
Reservation PriorityMedium is a reservation priority that indicates a reservation if the scope
memory utilization is at 60% or less.
The pages are generated with Goldsv0.8.2. (GOOS=linux GOARCH=amd64)
Golds is a Go 101 project developed by Tapir Liu.
PR and bug reports are welcome and can be submitted to the issue list.
Please follow @zigo_101 (reachable from the left QR code) to get the latest news of Golds.
