Involved Source Filesdecay.gogater.go Package connmgr provides connection tracking and management interfaces for libp2p.
The ConnManager interface exported from this package allows libp2p to enforce an
upper bound on the total number of open connections. To avoid service disruptions,
connections can be tagged with metadata and optionally "protected" to ensure that
essential connections are not arbitrarily cut.null.gopresets.go
ConnectionGater can be implemented by a type that supports active
inbound or outbound connection gating.
ConnectionGaters are active, whereas ConnManagers tend to be passive.
A ConnectionGater will be consulted during different states in the lifecycle
of a connection being established/upgraded. Specific functions will be called
throughout the process, to allow you to intercept the connection at that stage.
InterceptPeerDial is called on an imminent outbound peer dial request, prior
to the addresses of that peer being available/resolved. Blocking connections
at this stage is typical for blacklisting scenarios.
InterceptAddrDial is called on an imminent outbound dial to a peer on a
particular address. Blocking connections at this stage is typical for
address filtering.
InterceptAccept is called as soon as a transport listener receives an
inbound connection request, before any upgrade takes place. Transports who
accept already secure and/or multiplexed connections (e.g. possibly QUIC)
MUST call this method regardless, for correctness/consistency.
InterceptSecured is called for both inbound and outbound connections,
after a security handshake has taken place and we've authenticated the peer.
InterceptUpgraded is called for inbound and outbound connections, after
libp2p has finished upgrading the connection entirely to a secure,
multiplexed channel.
This interface can be used to implement *strict/active* connection management
policies, such as hard limiting of connections once a maximum count has been
reached, maintaining a peer blacklist, or limiting connections by transport
quotas.
EXPERIMENTAL: a DISCONNECT protocol/message will be supported in the future.
This allows gaters and other components to communicate the intention behind
a connection closure, to curtail potential reconnection attempts.
For now, InterceptUpgraded can return a non-zero DisconnectReason when
blocking a connection, but this interface is likely to change in the future
as we solidify this feature. The reason why only this method can handle
DisconnectReasons is that we require stream multiplexing capability to open a
control protocol stream to transmit the message. InterceptAccept tests whether an incipient inbound connection is allowed.
This is called by the upgrader, or by the transport directly (e.g. QUIC,
Bluetooth), straight after it has accepted a connection from its socket. InterceptAddrDial tests whether we're permitted to dial the specified
multiaddr for the given peer.
This is called by the network.Network implementation after it has
resolved the peer's addrs, and prior to dialling each. InterceptPeerDial tests whether we're permitted to Dial the specified peer.
This is called by the network.Network implementation when dialling a peer. InterceptSecured tests whether a given connection, now authenticated,
is allowed.
This is called by the upgrader, after it has performed the security
handshake, and before it negotiates the muxer, or by the directly by the
transport, at the exact same checkpoint. InterceptUpgraded tests whether a fully capable connection is allowed.
At this point, the connection a multiplexer has been selected.
When rejecting a connection, the gater can return a DisconnectReason.
Refer to the godoc on the ConnectionGater type for more information.
NOTE: the go-libp2p implementation currently IGNORES the disconnect reason.
func github.com/libp2p/go-libp2p.ConnectionGater(cg ConnectionGater) libp2p.Option
func github.com/libp2p/go-libp2p/p2p/net/swarm.WithConnectionGater(gater ConnectionGater) swarm.Option
func github.com/libp2p/go-libp2p/p2p/net/upgrader.New(security []sec.SecureTransport, muxers []upgrader.StreamMuxer, psk ipnet.PSK, rcmgr network.ResourceManager, connGater 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 ConnectionGater, rcmgr network.ResourceManager) (tpt.Transport, error)
func github.com/libp2p/go-libp2p/p2p/transport/webrtc.New(privKey ic.PrivKey, psk pnet.PSK, gater ConnectionGater, rcmgr network.ResourceManager, listenUDP libp2pwebrtc.ListenUDPFn, opts ...libp2pwebrtc.Option) (*libp2pwebrtc.WebRTCTransport, error)
func github.com/libp2p/go-libp2p/p2p/transport/webtransport.New(key ic.PrivKey, psk pnet.PSK, connManager *quicreuse.ConnManager, gater ConnectionGater, rcmgr network.ResourceManager, opts ...libp2pwebtransport.Option) (tpt.Transport, error)
ConnManager tracks connections to peers, and allows consumers to associate
metadata with each peer.
It enables connections to be trimmed based on implementation-defined
heuristics. The ConnManager allows libp2p to enforce an upper bound on the
total number of open connections.
ConnManagers supporting decaying tags implement Decayer. Use the
SupportsDecay function to safely cast an instance to Decayer, if supported. CheckLimit will return an error if the connection manager's internal
connection limit exceeds the provided system limit. Close closes the connection manager and stops background processes. GetTagInfo returns the metadata associated with the peer,
or nil if no metadata has been recorded for the peer. IsProtected returns true if the peer is protected for some tag; if the tag is the empty string
then it will return true if the peer is protected for any tag Notifee returns an implementation that can be called back to inform of
opened and closed connections. Protect protects a peer from having its connection(s) pruned.
Tagging allows different parts of the system to manage protections without interfering with one another.
Calls to Protect() with the same tag are idempotent. They are not refcounted, so after multiple calls
to Protect() with the same tag, a single Unprotect() call bearing the same tag will revoke the protection. TagPeer tags a peer with a string, associating a weight with the tag. TrimOpenConns terminates open connections based on an implementation-defined
heuristic. Unprotect removes a protection that may have been placed on a peer, under the specified tag.
The return value indicates whether the peer continues to be protected after this call, by way of a different tag.
See notes on Protect() for more info. UntagPeer removes the tagged value from the peer. UpsertTag updates an existing tag or inserts a new one.
The connection manager calls the upsert function supplying the current
value of the tag (or zero if inexistent). The return value is used as
the new value of the tag.NullConnMgr
*github.com/libp2p/go-libp2p/p2p/net/connmgr.BasicConnMgr
ConnManager : github.com/prometheus/common/expfmt.Closer
ConnManager : io.Closer
func github.com/libp2p/go-libp2p/core/host.Host.ConnManager() ConnManager
func github.com/libp2p/go-libp2p/p2p/host/basic.(*BasicHost).ConnManager() ConnManager
func github.com/libp2p/go-libp2p/p2p/host/blank.(*BlankHost).ConnManager() ConnManager
func github.com/libp2p/go-libp2p/p2p/host/routed.(*RoutedHost).ConnManager() ConnManager
func SupportsDecay(mgr ConnManager) (Decayer, bool)
func github.com/libp2p/go-libp2p.ConnectionManager(connman ConnManager) libp2p.Option
func github.com/libp2p/go-libp2p/p2p/host/blank.WithConnectionManager(cmgr ConnManager) blankhost.Option
Decayer is implemented by connection managers supporting decaying tags. A
decaying tag is one whose value automatically decays over time.
The actual application of the decay behaviour is encapsulated in a
user-provided decaying function (DecayFn). The function is called on every
tick (determined by the interval parameter), and returns either the new value
of the tag, or whether it should be erased altogether.
We do not set values on a decaying tag. Rather, we "bump" decaying tags by a
delta. This calls the BumpFn with the old value and the delta, to determine
the new value.
Such a pluggable design affords a great deal of flexibility and versatility.
Behaviours that are straightforward to implement include:
- Decay a tag by -1, or by half its current value, on every tick.
- Every time a value is bumped, sum it to its current value.
- Exponentially boost a score with every bump.
- Sum the incoming score, but keep it within min, max bounds.
Commonly used DecayFns and BumpFns are provided in this package.( Decayer) Close() error RegisterDecayingTag creates and registers a new decaying tag, if and only
if a tag with the supplied name doesn't exist yet. Otherwise, an error is
returned.
The caller provides the interval at which the tag is refreshed, as well
as the decay function and the bump function. Refer to godocs on DecayFn
and BumpFn for more info.
*github.com/libp2p/go-libp2p/p2p/net/connmgr.BasicConnMgr
Decayer : github.com/prometheus/common/expfmt.Closer
Decayer : io.Closer
func SupportsDecay(mgr ConnManager) (Decayer, bool)
DecayingTag represents a decaying tag. The tag is a long-lived general
object, used to operate on tag values for peers. Bump applies a delta to a tag value, calling its bump function. The bump
will be applied asynchronously, and a non-nil error indicates a fault
when queuing. Close closes a decaying tag. The Decayer will stop tracking this tag,
and the state of all peers in the Connection Manager holding this tag
will be updated.
The deletion is performed asynchronously.
Once deleted, a tag should not be used, and further calls to Bump/Remove
will error.
Duplicate calls to Remove will not return errors, but a failure to queue
the first actual removal, will (e.g. when the system is backlogged). Interval is the effective interval at which this tag will tick. Upon
registration, the desired interval may be overwritten depending on the
decayer's resolution, and this method allows you to obtain the effective
interval. Name returns the name of the tag. Remove removes a decaying tag from a peer. The removal will be applied
asynchronously, and a non-nil error indicates a fault when queuing.
DecayingTag : github.com/polarsignals/frostdb/query/logicalplan.Named
DecayingTag : github.com/prometheus/common/expfmt.Closer
DecayingTag : io.Closer
func Decayer.RegisterDecayingTag(name string, interval time.Duration, decayFn DecayFn, bumpFn BumpFn) (DecayingTag, error)
DecayingValue represents a value for a decaying tag. Added is the timestamp when this value was added for the first time for
a tag and a peer. LastVisit is the timestamp of the last visit. Peer is the peer ID to whom this value is associated. Tag points to the tag this value belongs to. Value is the current value of the tag.
GetConnLimiter provides access to a component's total connection limit. GetConnLimit returns the total connection limit of the implementing component.
func ConnManager.CheckLimit(l GetConnLimiter) error
func NullConnMgr.CheckLimit(_ GetConnLimiter) error
func github.com/libp2p/go-libp2p/p2p/net/connmgr.(*BasicConnMgr).CheckLimit(systemLimit GetConnLimiter) error
BumpOverwrite replaces the current value of the tag with the incoming one.
BumpSumBounded keeps summing the incoming score, keeping it within a
[min, max] range.
BumpSumUnbounded adds the incoming value to the peer's score.
DecayExpireWhenInactive expires a tag after a certain period of no bumps.
DecayFixed subtracts from by the provided minuend, and deletes the tag when
first reaching 0 or negative.
DecayLinear applies a fractional coefficient to the value of the current tag,
rounding down via math.Floor. It erases the tag when the result is zero.
DecayNone applies no decay.
SupportsDecay evaluates if the provided ConnManager supports decay, and if
so, it returns the Decayer object. Refer to godocs on Decayer for more info.
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.
