Documentation ¶
Index ¶
- Constants
- Variables
- func DefaultDialRanker(addrs []ma.Multiaddr) []network.AddrDelay
- func NoDelayDialRanker(addrs []ma.Multiaddr) []network.AddrDelay
- type Clock
- type Conn
- func (c *Conn) Close() error
- func (c *Conn) ConnState() network.ConnectionState
- func (c *Conn) GetStreams() []network.Stream
- func (c *Conn) ID() string
- func (c *Conn) IsClosed() bool
- func (c *Conn) LocalMultiaddr() ma.Multiaddr
- func (c *Conn) LocalPeer() peer.ID
- func (c *Conn) NewStream(ctx context.Context) (network.Stream, error)
- func (c *Conn) RemoteMultiaddr() ma.Multiaddr
- func (c *Conn) RemotePeer() peer.ID
- func (c *Conn) RemotePublicKey() ic.PubKey
- func (c *Conn) Scope() network.ConnScope
- func (c *Conn) Stat() network.ConnStats
- func (c *Conn) String() string
- type DialBackoff
- type DialError
- type InstantTimer
- type MetricsTracer
- type MetricsTracerOption
- type Option
- func WithConnectionGater(gater connmgr.ConnectionGater) Option
- func WithDialRanker(d network.DialRanker) Option
- func WithDialTimeout(t time.Duration) Option
- func WithDialTimeoutLocal(t time.Duration) Option
- func WithIPv6BlackHoleConfig(enabled bool, n, min int) Option
- func WithMetrics(reporter metrics.Reporter) Option
- func WithMetricsTracer(t MetricsTracer) Option
- func WithMultiaddrResolver(maResolver *madns.Resolver) Option
- func WithResourceManager(m network.ResourceManager) Option
- func WithUDPBlackHoleConfig(enabled bool, n, min int) Option
- type RealClock
- type RealTimer
- type Stream
- func (s *Stream) Close() error
- func (s *Stream) CloseRead() error
- func (s *Stream) CloseWrite() error
- func (s *Stream) Conn() network.Conn
- func (s *Stream) ID() string
- func (s *Stream) Protocol() protocol.ID
- func (s *Stream) Read(p []byte) (int, error)
- func (s *Stream) Reset() error
- func (s *Stream) Scope() network.StreamScope
- func (s *Stream) SetDeadline(t time.Time) error
- func (s *Stream) SetProtocol(p protocol.ID) error
- func (s *Stream) SetReadDeadline(t time.Time) error
- func (s *Stream) SetWriteDeadline(t time.Time) error
- func (s *Stream) Stat() network.Stats
- func (s *Stream) String() string
- func (s *Stream) Write(p []byte) (int, error)
- type Swarm
- func (s *Swarm) AddListenAddr(a ma.Multiaddr) error
- func (s *Swarm) AddTransport(t transport.Transport) error
- func (s *Swarm) Backoff() *DialBackoff
- func (s *Swarm) Close() error
- func (s *Swarm) ClosePeer(p peer.ID) error
- func (s *Swarm) Connectedness(p peer.ID) network.Connectedness
- func (s *Swarm) Conns() []network.Conn
- func (s *Swarm) ConnsToPeer(p peer.ID) []network.Conn
- func (s *Swarm) DialPeer(ctx context.Context, p peer.ID) (network.Conn, error)
- func (s *Swarm) InterfaceListenAddresses() ([]ma.Multiaddr, error)
- func (s *Swarm) Listen(addrs ...ma.Multiaddr) error
- func (s *Swarm) ListenAddresses() []ma.Multiaddr
- func (s *Swarm) ListenClose(addrs ...ma.Multiaddr)
- func (s *Swarm) LocalPeer() peer.ID
- func (s *Swarm) NewStream(ctx context.Context, p peer.ID) (network.Stream, error)
- func (s *Swarm) Notify(f network.Notifiee)
- func (s *Swarm) Peers() []peer.ID
- func (s *Swarm) Peerstore() peerstore.Peerstore
- func (s *Swarm) ResourceManager() network.ResourceManager
- func (s *Swarm) SetStreamHandler(handler network.StreamHandler)
- func (s *Swarm) StopNotify(f network.Notifiee)
- func (s *Swarm) StreamHandler() network.StreamHandler
- func (s *Swarm) String() string
- func (s *Swarm) TransportForDialing(a ma.Multiaddr) transport.Transport
- func (s *Swarm) TransportForListening(a ma.Multiaddr) transport.Transport
- type TransportError
Constants ¶
const ( // duration by which TCP dials are delayed relative to the last QUIC dial PublicTCPDelay = 250 * time.Millisecond PrivateTCPDelay = 30 * time.Millisecond // duration by which QUIC dials are delayed relative to previous QUIC dial PublicQUICDelay = 250 * time.Millisecond PrivateQUICDelay = 30 * time.Millisecond // RelayDelay is the duration by which relay dials are delayed relative to direct addresses RelayDelay = 500 * time.Millisecond )
The 250ms value is from happy eyeballs RFC 8305. This is a rough estimate of 1 RTT
const ConcurrentFdDials = 160
ConcurrentFdDials is the number of concurrent outbound dials over transports that consume file descriptors
const DialAttempts = 1
DialAttempts governs how many times a goroutine will try to dial a given peer. Note: this is down to one, as we have _too many dials_ atm. To add back in, add loop back in Dial(.)
Variables ¶
var ( // ErrDialBackoff is returned by the backoff code when a given peer has // been dialed too frequently ErrDialBackoff = errors.New("dial backoff") // ErrDialRefusedBlackHole is returned when we are in a black holed environment ErrDialRefusedBlackHole = errors.New("dial refused because of black hole") // ErrDialToSelf is returned if we attempt to dial our own peer ErrDialToSelf = errors.New("dial to self attempted") // ErrNoTransport is returned when we don't know a transport for the // given multiaddr. ErrNoTransport = errors.New("no transport for protocol") // ErrAllDialsFailed is returned when connecting to a peer has ultimately failed ErrAllDialsFailed = errors.New("all dials failed") // ErrNoAddresses is returned when we fail to find any addresses for a // peer we're trying to dial. ErrNoAddresses = errors.New("no addresses") // ErrNoGoodAddresses is returned when we find addresses for a peer but // can't use any of them. ErrNoGoodAddresses = errors.New("no good addresses") // ErrGaterDisallowedConnection is returned when the gater prevents us from // forming a connection with a peer. ErrGaterDisallowedConnection = errors.New("gater disallows connection to peer") )
var BackoffBase = time.Second * 5
BackoffBase is the base amount of time to backoff (default: 5s).
var BackoffCoef = time.Second
BackoffCoef is the backoff coefficient (default: 1s).
var BackoffMax = time.Minute * 5
BackoffMax is the maximum backoff time (default: 5m).
var DefaultPerPeerRateLimit = 8
DefaultPerPeerRateLimit is the number of concurrent outbound dials to make per peer
var ErrAddrFiltered = errors.New("address filtered")
ErrAddrFiltered is returned when trying to register a connection to a filtered address. You shouldn't see this error unless some underlying transport is misbehaving.
var ErrConnClosed = errors.New("connection closed")
ErrConnClosed is returned when operating on a closed connection.
var ErrDialTimeout = errors.New("dial timed out")
ErrDialTimeout is returned when one a dial times out due to the global timeout
var ErrQUICDraft29 errQUICDraft29
ErrQUICDraft29 wraps ErrNoTransport and provide a more meaningful error message
var ErrSwarmClosed = errors.New("swarm closed")
ErrSwarmClosed is returned when one attempts to operate on a closed swarm.
Functions ¶
func DefaultDialRanker ¶
DefaultDialRanker determines the ranking of outgoing connection attempts.
Addresses are grouped into three distinct groups:
- private addresses (localhost and local networks (RFC 1918))
- public addresses
- relay addresses
Within each group, the addresses are ranked according to the ranking logic described below. We then dial addresses according to this ranking, with short timeouts applied between dial attempts. This ranking logic dramatically reduces the number of simultaneous dial attempts, while introducing no additional latency in the vast majority of cases.
Private and public address groups are dialed in parallel. Dialing relay addresses is delayed by 500 ms, if we have any non-relay alternatives.
Within each group (private, public, relay addresses) we apply the following ranking logic:
- If both IPv6 QUIC and IPv4 QUIC addresses are present, we do a Happy Eyeballs RFC 8305 style ranking. First dial the IPv6 QUIC address with the lowest port. After this we dial the IPv4 QUIC address with the lowest port delayed by 250ms (PublicQUICDelay) for public addresses, and 30ms (PrivateQUICDelay) for local addresses. After this we dial all the rest of the addresses delayed by 250ms (PublicQUICDelay) for public addresses, and 30ms (PrivateQUICDelay) for local addresses.
- If only one of QUIC IPv6 or QUIC IPv4 addresses are present, dial the QUIC address with the lowest port first. After this we dial the rest of the QUIC addresses delayed by 250ms (PublicQUICDelay) for public addresses, and 30ms (PrivateQUICDelay) for local addresses.
- If a QUIC or WebTransport address is present, TCP addresses dials are delayed relative to the last QUIC dial: We prefer to end up with a QUIC connection. For public addresses, the delay introduced is 250ms (PublicTCPDelay), and for private addresses 30ms (PrivateTCPDelay).
- For the TCP addresses we follow a strategy similar to QUIC with an optimisation for handling the long TCP handshake time described in 6. If both IPv6 TCP and IPv4 TCP addresses are present, we do a Happy Eyeballs style ranking. First dial the IPv6 TCP address with the lowest port. After this, dial the IPv4 TCP address with the lowest port delayed by 250ms (PublicTCPDelay) for public addresses, and 30ms (PrivateTCPDelay) for local addresses. After this we dial all the rest of the addresses delayed by 250ms (PublicTCPDelay) for public addresses, and 30ms (PrivateTCPDelay) for local addresses.
- If only one of TCP IPv6 or TCP IPv4 addresses are present, dial the TCP address with the lowest port first. After this we dial the rest of the TCP addresses delayed by 250ms (PublicTCPDelay) for public addresses, and 30ms (PrivateTCPDelay) for local addresses.
- When a TCP socket is connected and awaiting security and muxer upgrade, we stop new dials for 2*PrivateTCPDelay to allow for the upgrade to complete.
We dial lowest ports first as they are more likely to be the listen port.
Types ¶
type Clock ¶
type Clock interface { Now() time.Time Since(t time.Time) time.Duration InstantTimer(when time.Time) InstantTimer }
Clock is a clock that can create timers that trigger at some instant rather than some duration
type Conn ¶
type Conn struct {
// contains filtered or unexported fields
}
Conn is the connection type used by swarm. In general, you won't use this type directly.
func (*Conn) Close ¶
Close closes this connection.
Note: This method won't wait for the close notifications to finish as that would create a deadlock when called from an open notification (because all open notifications must finish before we can fire off the close notifications).
func (*Conn) ConnState ¶
func (c *Conn) ConnState() network.ConnectionState
ConnState is the security connection state. including early data result. Empty if not supported.
func (*Conn) GetStreams ¶
GetStreams returns the streams associated with this connection.
func (*Conn) LocalMultiaddr ¶
LocalMultiaddr is the Multiaddr on this side
func (*Conn) RemoteMultiaddr ¶
RemoteMultiaddr is the Multiaddr on the remote side
func (*Conn) RemotePeer ¶
RemotePeer is the Peer on the remote side
func (*Conn) RemotePublicKey ¶
RemotePublicKey is the public key of the peer on the remote side
type DialBackoff ¶
type DialBackoff struct {
// contains filtered or unexported fields
}
DialBackoff is a type for tracking peer dial backoffs. Dialbackoff is used to avoid over-dialing the same, dead peers. Whenever we totally time out on all addresses of a peer, we add the addresses to DialBackoff. Then, whenever we attempt to dial the peer again, we check each address for backoff. If it's on backoff, we don't dial the address and exit promptly. If a dial is successful, the peer and all its addresses are removed from backoff.
* It's safe to use its zero value. * It's thread-safe. * It's *not* safe to move this type after using.
func (*DialBackoff) AddBackoff ¶
func (db *DialBackoff) AddBackoff(p peer.ID, addr ma.Multiaddr)
AddBackoff adds peer's address to backoff.
Backoff is not exponential, it's quadratic and computed according to the following formula:
BackoffBase + BakoffCoef * PriorBackoffs^2
Where PriorBackoffs is the number of previous backoffs.
func (*DialBackoff) Backoff ¶
Backoff returns whether the client should backoff from dialing peer p at address addr
func (*DialBackoff) Clear ¶
func (db *DialBackoff) Clear(p peer.ID)
Clear removes a backoff record. Clients should call this after a successful Dial.
type DialError ¶
type DialError struct { Peer peer.ID DialErrors []TransportError Cause error Skipped int }
DialError is the error type returned when dialing.
type InstantTimer ¶
InstantTimer is a timer that triggers at some instant rather than some duration
type MetricsTracer ¶
type MetricsTracer interface { OpenedConnection(network.Direction, crypto.PubKey, network.ConnectionState, ma.Multiaddr) ClosedConnection(network.Direction, time.Duration, network.ConnectionState, ma.Multiaddr) CompletedHandshake(time.Duration, network.ConnectionState, ma.Multiaddr) FailedDialing(ma.Multiaddr, error, error) DialCompleted(success bool, totalDials int) DialRankingDelay(d time.Duration) UpdatedBlackHoleFilterState(name string, state blackHoleState, nextProbeAfter int, successFraction float64) }
func NewMetricsTracer ¶
func NewMetricsTracer(opts ...MetricsTracerOption) MetricsTracer
type MetricsTracerOption ¶
type MetricsTracerOption func(*metricsTracerSetting)
func WithRegisterer ¶
func WithRegisterer(reg prometheus.Registerer) MetricsTracerOption
type Option ¶
func WithConnectionGater ¶
func WithConnectionGater(gater connmgr.ConnectionGater) Option
WithConnectionGater sets a connection gater
func WithDialRanker ¶
func WithDialRanker(d network.DialRanker) Option
WithDialRanker configures swarm to use d as the DialRanker
func WithDialTimeout ¶
func WithDialTimeoutLocal ¶
func WithIPv6BlackHoleConfig ¶
WithIPv6BlackHoleConfig configures swarm to use c as the config for IPv6 black hole detection n is the size of the sliding window used to evaluate black hole state min is the minimum number of successes out of n required to not block requests
func WithMetrics ¶
WithMetrics sets a metrics reporter
func WithMetricsTracer ¶
func WithMetricsTracer(t MetricsTracer) Option
func WithMultiaddrResolver ¶
WithMultiaddrResolver sets a custom multiaddress resolver
func WithResourceManager ¶
func WithResourceManager(m network.ResourceManager) Option
func WithUDPBlackHoleConfig ¶
WithUDPBlackHoleConfig configures swarm to use c as the config for UDP black hole detection n is the size of the sliding window used to evaluate black hole state min is the minimum number of successes out of n required to not block requests
type RealClock ¶
type RealClock struct{}
func (RealClock) InstantTimer ¶
func (RealClock) InstantTimer(when time.Time) InstantTimer
type Stream ¶
type Stream struct {
// contains filtered or unexported fields
}
Stream is the stream type used by swarm. In general, you won't use this type directly.
func (*Stream) Close ¶
Close closes the stream, closing both ends and freeing all associated resources.
func (*Stream) CloseRead ¶
CloseRead closes the stream for reading. This function does not free resources, call Close or Reset when done with the stream.
func (*Stream) CloseWrite ¶
CloseWrite closes the stream for writing, flushing all data and sending an EOF. This function does not free resources, call Close or Reset when done with the stream.
func (*Stream) Reset ¶
Reset resets the stream, signaling an error on both ends and freeing all associated resources.
func (*Stream) Scope ¶
func (s *Stream) Scope() network.StreamScope
func (*Stream) SetDeadline ¶
SetDeadline sets the read and write deadlines for this stream.
func (*Stream) SetProtocol ¶
SetProtocol sets the protocol for this stream.
This doesn't actually *do* anything other than record the fact that we're speaking the given protocol over this stream. It's still up to the user to negotiate the protocol. This is usually done by the Host.
func (*Stream) SetReadDeadline ¶
SetReadDeadline sets the read deadline for this stream.
func (*Stream) SetWriteDeadline ¶
SetWriteDeadline sets the write deadline for this stream.
type Swarm ¶
type Swarm struct {
// contains filtered or unexported fields
}
Swarm is a connection muxer, allowing connections to other peers to be opened and closed, while still using the same Chan for all communication. The Chan sends/receives Messages, which note the destination or source Peer.
func NewSwarm ¶
func NewSwarm(local peer.ID, peers peerstore.Peerstore, eventBus event.Bus, opts ...Option) (*Swarm, error)
NewSwarm constructs a Swarm.
func (*Swarm) AddListenAddr ¶
AddListenAddr tells the swarm to listen on a single address. Unlike Listen, this method does not attempt to filter out bad addresses.
func (*Swarm) AddTransport ¶
AddTransport adds a transport to this swarm.
Satisfies the Network interface from go-libp2p-transport.
func (*Swarm) Backoff ¶
func (s *Swarm) Backoff() *DialBackoff
Backoff returns the DialBackoff object for this swarm.
func (*Swarm) Connectedness ¶
func (s *Swarm) Connectedness(p peer.ID) network.Connectedness
Connectedness returns our "connectedness" state with the given peer.
To check if we have an open connection, use `s.Connectedness(p) == network.Connected`.
func (*Swarm) ConnsToPeer ¶
ConnsToPeer returns all the live connections to peer.
func (*Swarm) DialPeer ¶
DialPeer connects to a peer. Use network.WithForceDirectDial to force a direct connection.
The idea is that the client of Swarm does not need to know what network the connection will happen over. Swarm can use whichever it choses. This allows us to use various transport protocols, do NAT traversal/relay, etc. to achieve connection.
func (*Swarm) InterfaceListenAddresses ¶
InterfaceListenAddresses returns a list of addresses at which this swarm listens. It expands "any interface" addresses (/ip4/0.0.0.0, /ip6/::) to use the known local interfaces.
func (*Swarm) Listen ¶
Listen sets up listeners for all of the given addresses. It returns as long as we successfully listen on at least *one* address.
func (*Swarm) ListenAddresses ¶
ListenAddresses returns a list of addresses at which this swarm listens.
func (*Swarm) ListenClose ¶
ListenClose stop and delete listeners for all of the given addresses. If an any address belongs to one of the addreses a Listener provides, then the Listener will close for *all* addresses it provides. For example if you close and address with `/quic`, then the QUIC listener will close and also close any `/quic-v1` address.
func (*Swarm) NewStream ¶
NewStream creates a new stream on any available connection to peer, dialing if necessary. Use network.WithUseTransient to open a stream over a transient(relayed) connection.
func (*Swarm) ResourceManager ¶
func (s *Swarm) ResourceManager() network.ResourceManager
func (*Swarm) SetStreamHandler ¶
func (s *Swarm) SetStreamHandler(handler network.StreamHandler)
SetStreamHandler assigns the handler for new streams.
func (*Swarm) StopNotify ¶
StopNotify unregisters Notifiee fromr receiving signals
func (*Swarm) StreamHandler ¶
func (s *Swarm) StreamHandler() network.StreamHandler
StreamHandler gets the handler for new streams.
func (*Swarm) TransportForDialing ¶
TransportForDialing retrieves the appropriate transport for dialing the given multiaddr.
type TransportError ¶
TransportError is the error returned when dialing a specific address.
func (*TransportError) Error ¶
func (e *TransportError) Error() string
func (*TransportError) Unwrap ¶
func (e *TransportError) Unwrap() error