This is a feature-packed release! Read on to learn more about the changes.
New features
Decaying tags in the Connection Manager
This release introduces Decaying Tags in the Connection Manager interfaces. 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 tagβs Interval property), and returns either the new value of the tag, or whether it should be erased altogether.
We do not set values directly on a decaying tag. Rather, we βbumpβ decaying tags by a delta. Doing so 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.
To use Decaying Tags, check if the Connection Manager supports them first via the SupportsDecay
function.
Check the godocs in the connmgr
package for more info.
Connection gating
This release adds interfaces for Connection Gating: middleware components that intercept connections at different stages and decide whether to ALLOW or BLOCK the connection. In contrast to Connection Managers, Connection Gaters are actively consulted throughout the dial/listen pipeline.
Connection Gaters can intercept connections at these stages:
-
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.
See godocs for the ConnectionGater
interface for more info.
Migration/adoption notes
The old filter.Filters
construct is still available, and behind the scenes, go-libp2p translates it to a connmgr.ConnectionGater
that intercepts only address dials, and evaluates them against the Filters.
It is encouraged to transition to using pure ConnectionGater
s, as it gives you more control over the entire lifecycle of a connection. It also allows you to blacklist peers.
The constructor options work this way:
-
ConnectionGater(connmgr.ConnectionGater)
=> sets the connection gater and renders all otherFilter*
options invalid. -
Filters(*filter.Filters)
(deprecated) => converts the passedFilters
to aConnectionGater
, and sets it internally. Cannot be used withConnectionGater(connmgr.ConnectionGater)
. -
FilterAddresses(addrs ...*net.IPNet)
(deprecated) => blocks the supplied subnets in the underlyingFilters
if one has been set, else it creates a newFilters
initializing it with the supplied blocked addresses. Compatible withFilters()
, incompatible withConnectionGater()
.
Identify protocols now exchange signed peer records
For enhanced security, the identify family of protocols now exchange Signed Peer Records: self-certified records that enumerate our addresses. Previously, when third parties propagate addresses about peers they tamper them inflight. With signed peer records, such attacks are no longer possible.
Pubsub and DHT protocols are the main beneficiaries within go-libp2p, but signed peer records are available to the application layer too. They can be queried in the peerstore, by first checking if the underlying implementation supports them via GetCertifiedAddrBook()
.
It is also possible to transmit other types of certified payloads. Check out the godocs of the record
package under go-libp2p-core
for more info.
This release also deraces the identify family of protocols.