addrmgr

Documentation

Overview

Package addrmgr implements concurrency safe Decred address manager.

Address Manager Overview

In order maintain the peer-to-peer Decred network, there needs to be a source of addresses to connect to as nodes come and go. The Decred protocol provides the getaddr and addr messages to allow peers to communicate known addresses with each other. However, there needs to a mechanism to store those results and select peers from them. It is also important to note that remote peers can't be trusted to send valid peers nor attempt to provide you with only peers they control with malicious intent.

With that in mind, this package provides a concurrency safe address manager for caching and selecting peers in a non-deterministic manner. The general idea is the caller adds addresses to the address manager and notifies it when addresses are connected, known good, and attempted. The caller also requests addresses as it needs them.

The address manager internally segregates the addresses into groups and non-deterministically selects groups in a cryptographically random manner. This reduce the chances multiple addresses from the same nets are selected which generally helps provide greater peer diversity, and perhaps more importantly, drastically reduces the chances an attacker is able to coerce your peer into only connecting to nodes they control.

The address manager also understands routability and Tor addresses and tries hard to only return routable addresses. In addition, it uses the information provided by the caller about connected, known good, and attempted addresses to periodically purge peers which no longer appear to be good peers as well as bias the selection toward known good peers. The general idea is to make a best effort at only providing usable addresses.

Index

• Constants
• func DisableLog()
• func GroupKey(na *wire.NetAddress) string
• func IsRoutable(na *wire.NetAddress) bool
• func NetAddressKey(na *wire.NetAddress) string
• func UseLogger(logger slog.Logger)
• type AddrManager
  • func New(dataDir string, lookupFunc func(string) ([]net.IP, error)) *AddrManager
  • func (a *AddrManager) AddAddress(addr, srcAddr *wire.NetAddress)
  • func (a *AddrManager) AddAddresses(addrs []*wire.NetAddress, srcAddr *wire.NetAddress)
  • func (a *AddrManager) AddLocalAddress(na *wire.NetAddress, priority AddressPriority) error
  • func (a *AddrManager) AddressCache() []*wire.NetAddress
  • func (a *AddrManager) Attempt(addr *wire.NetAddress)
  • func (a *AddrManager) Connected(addr *wire.NetAddress)
  • func (a *AddrManager) DeserializeNetAddress(addr string) (*wire.NetAddress, error)
  • func (a *AddrManager) FetchLocalAddresses() []LocalAddr
  • func (a *AddrManager) GetAddress() *KnownAddress
  • func (a *AddrManager) GetBestLocalAddress(remoteAddr *wire.NetAddress) *wire.NetAddress
  • func (a *AddrManager) Good(addr *wire.NetAddress)
  • func (a *AddrManager) HasLocalAddress(na *wire.NetAddress) bool
  • func (a *AddrManager) HostToNetAddress(host string, port uint16, services wire.ServiceFlag) (*wire.NetAddress, error)
  • func (a *AddrManager) IsPeerNaValid(localAddr, remoteAddr *wire.NetAddress) bool
  • func (a *AddrManager) LocalAddresses() []LocalAddr
  • func (a *AddrManager) NeedMoreAddresses() bool
  • func (a *AddrManager) SetServices(addr *wire.NetAddress, services wire.ServiceFlag)
  • func (a *AddrManager) Start()
  • func (a *AddrManager) Stop() error
  • func (a *AddrManager) ValidatePeerNa(localAddr, remoteAddr *wire.NetAddress) (bool, int)
• type AddressPriority
• type KnownAddress
  • func (ka *KnownAddress) LastAttempt() time.Time
  • func (ka *KnownAddress) NetAddress() *wire.NetAddress
• type LocalAddr
• type NetworkAddress

Constants

const (
	// Unreachable represents a publicly unreachable connection state
	// between two addresses.
	Unreachable = 0

	// Default represents the default connection state between
	// two addresses.
	Default = iota

	// Teredo represents a connection state between two RFC4380 addresses.
	Teredo

	// Ipv6Weak represents a weak IPV6 connection state between two
	// addresses.
	Ipv6Weak

	// Ipv4 represents an IPV4 connection state between two addresses.
	Ipv4

	// Ipv6Strong represents a connection state between two IPV6 addresses.
	Ipv6Strong

	// Private represents a connection state connect between two Tor addresses.
	Private
)

const PeersFilename = "peers.json"

PeersFilename is the default filename to store serialized peers.

Functions

func DisableLog

func DisableLog()

DisableLog disables all library log output. Logging output is disabled by default until UseLogger is called.

Deprecated: Use UseLogger(slog.Disabled) instead.

func GroupKey

func GroupKey(na *wire.NetAddress) string

GroupKey returns a string representing the network group an address is part of. This is the /16 for IPv4, the /32 (/36 for he.net) for IPv6, the string "local" for a local address, the string "tor:key" where key is the /4 of the onion address for Tor address, and the string "unroutable" for an unroutable address.

func IsRoutable

func IsRoutable(na *wire.NetAddress) bool

IsRoutable returns whether or not the passed address is routable over the public internet. This is true as long as the address is valid and is not in any reserved ranges.

func NetAddressKey

func NetAddressKey(na *wire.NetAddress) string

NetAddressKey returns a string key in the form of ip:port for IPv4 addresses or [ip]:port for IPv6 addresses.

func UseLogger

func UseLogger(logger slog.Logger)

UseLogger uses a specified Logger to output package logging info. This should be used in preference to SetLogWriter if the caller is also using slog.

Types

type AddrManager

type AddrManager struct {
	// contains filtered or unexported fields
}

AddrManager provides a concurrency safe address manager for caching potential peers on the Decred network.

func New

func New(dataDir string, lookupFunc func(string) ([]net.IP, error)) *AddrManager

New returns a new Decred address manager. Use Start to begin processing asynchronous address updates. The address manager uses lookupFunc for necessary DNS lookups.

func (*AddrManager) AddAddress

func (a *AddrManager) AddAddress(addr, srcAddr *wire.NetAddress)

AddAddress adds a new address to the address manager. It enforces a max number of addresses and silently ignores duplicate addresses. It is safe for concurrent access.

func (*AddrManager) AddAddresses

func (a *AddrManager) AddAddresses(addrs []*wire.NetAddress, srcAddr *wire.NetAddress)

AddAddresses adds new addresses to the address manager. It enforces a max number of addresses and silently ignores duplicate addresses. It is safe for concurrent access.

func (*AddrManager) AddLocalAddress

func (a *AddrManager) AddLocalAddress(na *wire.NetAddress, priority AddressPriority) error

AddLocalAddress adds na to the list of known local addresses to advertise with the given priority.

func (*AddrManager) AddressCache

func (a *AddrManager) AddressCache() []*wire.NetAddress

AddressCache returns the current address cache. It must be treated as read-only (but since it is a copy now, this is not as dangerous).

func (*AddrManager) Attempt

func (a *AddrManager) Attempt(addr *wire.NetAddress)

Attempt increases the given address' attempt counter and updates the last attempt time.

func (*AddrManager) Connected

func (a *AddrManager) Connected(addr *wire.NetAddress)

Connected Marks the given address as currently connected and working at the current time. The address must already be known to AddrManager else it will be ignored.

func (*AddrManager) DeserializeNetAddress

func (a *AddrManager) DeserializeNetAddress(addr string) (*wire.NetAddress, error)

DeserializeNetAddress converts a given address string to a *wire.NetAddress

func (*AddrManager) FetchLocalAddresses

func (a *AddrManager) FetchLocalAddresses() []LocalAddr

FetchLocalAddresses fetches a summary of local addresses information for the getnetworkinfo rpc.

Deprecated: This will be removed in the next major version bump. Use LocalAddresses instead.

func (*AddrManager) GetAddress

func (a *AddrManager) GetAddress() *KnownAddress

GetAddress returns a single address that should be routable. It picks a random one from the possible addresses with preference given to ones that have not been used recently and should not pick 'close' addresses consecutively.

func (*AddrManager) GetBestLocalAddress

func (a *AddrManager) GetBestLocalAddress(remoteAddr *wire.NetAddress) *wire.NetAddress

GetBestLocalAddress returns the most appropriate local address to use for the given remote address.

func (*AddrManager) Good

func (a *AddrManager) Good(addr *wire.NetAddress)

Good marks the given address as good. To be called after a successful connection and version exchange. If the address is unknown to the address manager it will be ignored.

func (*AddrManager) HasLocalAddress

func (a *AddrManager) HasLocalAddress(na *wire.NetAddress) bool

HasLocalAddress asserts if the manager has the provided local address.

func (*AddrManager) HostToNetAddress

func (a *AddrManager) HostToNetAddress(host string, port uint16, services wire.ServiceFlag) (*wire.NetAddress, error)

HostToNetAddress returns a netaddress given a host address. If the address is a Tor .onion address this will be taken care of. Else if the host is not an IP address it will be resolved (via Tor if required).

func (*AddrManager) IsPeerNaValid

func (a *AddrManager) IsPeerNaValid(localAddr, remoteAddr *wire.NetAddress) bool

IsPeerNaValid asserts if the provided local address is routable and reachabile from the peer that suggested it.

Deprecated: This will be removed in the next major version bump. Use ValidatePeerNa instead.

func (*AddrManager) LocalAddresses

func (a *AddrManager) LocalAddresses() []LocalAddr

LocalAddresses returns a summary of local addresses information for the getnetworkinfo rpc.

This function is safe for concurrent access.

func (*AddrManager) NeedMoreAddresses

func (a *AddrManager) NeedMoreAddresses() bool

NeedMoreAddresses returns whether or not the address manager needs more addresses.

func (*AddrManager) SetServices

func (a *AddrManager) SetServices(addr *wire.NetAddress, services wire.ServiceFlag)

SetServices sets the services for the given address to the provided value.

func (*AddrManager) Start

func (a *AddrManager) Start()

Start begins the core address handler which manages a pool of known addresses, timeouts, and interval based writes.

func (*AddrManager) Stop

func (a *AddrManager) Stop() error

Stop gracefully shuts down the address manager by stopping the main handler.

func (*AddrManager) ValidatePeerNa

func (a *AddrManager) ValidatePeerNa(localAddr, remoteAddr *wire.NetAddress) (bool, int)

ValidatePeerNa returns the validity and reachability of the provided local address based on its routablility and reachability from the peer that suggested it.

type AddressPriority

type AddressPriority int

AddressPriority type is used to describe the hierarchy of local address discovery methods.

const (
	// InterfacePrio signifies the address is on a local interface
	InterfacePrio AddressPriority = iota

	// BoundPrio signifies the address has been explicitly bounded to.
	BoundPrio

	// UpnpPrio signifies the address was obtained from UPnP.
	UpnpPrio

	// HTTPPrio signifies the address was obtained from an external HTTP service.
	HTTPPrio

	// ManualPrio signifies the address was provided by --externalip.
	ManualPrio
)

type KnownAddress

type KnownAddress struct {
	// contains filtered or unexported fields
}

KnownAddress tracks information about a known network address that is used to determine how viable an address is.

func (*KnownAddress) LastAttempt

func (ka *KnownAddress) LastAttempt() time.Time

LastAttempt returns the last time the known address was attempted.

func (*KnownAddress) NetAddress

func (ka *KnownAddress) NetAddress() *wire.NetAddress

NetAddress returns the underlying wire.NetAddress associated with the known address.

type LocalAddr

type LocalAddr struct {
	Address string
	Port    uint16
	Score   int32
}

LocalAddr represents network address information for a local address.

type NetworkAddress

type NetworkAddress int

NetworkAddress type is used to classify a network address.

const (
	LocalAddress NetworkAddress = iota
	IPv4Address
	IPv6Address
	OnionAddress
)