Documentation
¶
Overview ¶
Deprecated: This package has moved into go-libp2p as a sub-package: github.com/libp2p/go-libp2p/core/connmgr.
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.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type BumpFn ¶ added in v0.5.5
BumpFn applies a delta onto an existing score, and returns the new score.
Non-trivial bump functions include exponential boosting, moving averages, ceilings, etc. Deprecated: use github.com/libp2p/go-libp2p/core/connmgr.BumpFn instead
func BumpOverwrite ¶ added in v0.5.5
func BumpOverwrite() BumpFn
BumpOverwrite replaces the current value of the tag with the incoming one. Deprecated: use github.com/libp2p/go-libp2p/core/connmgr.BumpOverwrite instead
func BumpSumBounded ¶ added in v0.5.5
BumpSumBounded keeps summing the incoming score, keeping it within a [min, max] range. Deprecated: use github.com/libp2p/go-libp2p/core/connmgr.BumpSumBounded instead
func BumpSumUnbounded ¶ added in v0.5.5
func BumpSumUnbounded() BumpFn
BumpSumUnbounded adds the incoming value to the peer's score. Deprecated: use github.com/libp2p/go-libp2p/core/connmgr.BumpSumUnbounded instead
type ConnManager ¶
type ConnManager = connmgr.ConnManager
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. Deprecated: use github.com/libp2p/go-libp2p/core/connmgr.ConnManager instead
type ConnectionGater ¶ added in v0.5.4
type ConnectionGater = connmgr.ConnectionGater
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. Deprecated: use github.com/libp2p/go-libp2p/core/connmgr.ConnectionGater instead
type DecayFn ¶ added in v0.5.5
DecayFn applies a decay to the peer's score. The implementation must call DecayFn at the interval supplied when registering the tag.
It receives a copy of the decaying value, and returns the score after applying the decay, as well as a flag to signal if the tag should be erased. Deprecated: use github.com/libp2p/go-libp2p/core/connmgr.DecayFn instead
func DecayExpireWhenInactive ¶ added in v0.5.5
DecayExpireWhenInactive expires a tag after a certain period of no bumps. Deprecated: use github.com/libp2p/go-libp2p/core/connmgr.DecayExpireWhenInactive instead
func DecayFixed ¶ added in v0.5.5
DecayFixed subtracts from by the provided minuend, and deletes the tag when first reaching 0 or negative. Deprecated: use github.com/libp2p/go-libp2p/core/connmgr.DecayFixed instead
func DecayLinear ¶ added in v0.5.5
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. Deprecated: use github.com/libp2p/go-libp2p/core/connmgr.DecayLinear instead
type Decayer ¶ added in v0.5.5
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. Deprecated: use github.com/libp2p/go-libp2p/core/connmgr.Decayer instead
func SupportsDecay ¶ added in v0.5.5
func SupportsDecay(mgr ConnManager) (Decayer, bool)
SupportsDecay evaluates if the provided ConnManager supports decay, and if so, it returns the Decayer object. Refer to godocs on Decayer for more info. Deprecated: use github.com/libp2p/go-libp2p/core/connmgr.SupportsDecay instead
type DecayingTag ¶ added in v0.5.5
type DecayingTag = connmgr.DecayingTag
DecayingTag represents a decaying tag. The tag is a long-lived general object, used to operate on tag values for peers. Deprecated: use github.com/libp2p/go-libp2p/core/connmgr.DecayingTag instead
type DecayingValue ¶ added in v0.5.5
type DecayingValue = connmgr.DecayingValue
DecayingValue represents a value for a decaying tag. Deprecated: use github.com/libp2p/go-libp2p/core/connmgr.DecayingValue instead
type NullConnMgr ¶
type NullConnMgr = connmgr.NullConnMgr
NullConnMgr is a ConnMgr that provides no functionality. Deprecated: use github.com/libp2p/go-libp2p/core/connmgr.NullConnMgr instead
Source Files