connmgr

README

connmgr

Package connmgr implements a generic Bitcoin network connection manager.

Overview

Connection Manager handles all the general connection concerns such as maintaining a set number of outbound connections, sourcing peers, banning, limiting max connections, tor lookup, etc.

The package provides a generic connection manager which is able to accept connection requests from a source or a set of given addresses, dial them and notify the caller on connections. The main intended use is to initialize a pool of active connections and maintain them to remain connected to the P2P network.

In addition the connection manager provides the following utilities:

• Notifications on connections or disconnections
• Handle failures and retry new addresses from the source
• Connect only to specified addresses
• Permanent connections with increasing backoff retry timers
• Disconnect or Remove an established connection

Installation and Updating

$ go get -u github.com/btcsuite/btcd/connmgr

License

Package connmgr is licensed under the copyfree ISC License.

Documentation

Overview

Package connmgr implements a generic Bitcoin network connection manager.

Connection Manager Overview

Connection Manager handles all the general connection concerns such as maintaining a set number of outbound connections, sourcing peers, banning, limiting max connections, tor lookup, etc.

Index

• Constants
• Variables
• func DisableLog()
• func SeedFromDNS(chainParams *chaincfg.Params, reqServices wire.ServiceFlag, ...)
• func TorLookupIP(host, proxy string) ([]net.IP, error)
• func UseLogger(logger btclog.Logger)
• type Config
• type ConnManager
  • func New(cfg *Config) (*ConnManager, error)
  • func (cm *ConnManager) Connect(c *ConnReq)
  • func (cm *ConnManager) Disconnect(id uint64)
  • func (cm *ConnManager) NewConnReq()
  • func (cm *ConnManager) Remove(id uint64)
  • func (cm *ConnManager) Start()
  • func (cm *ConnManager) Stop()
  • func (cm *ConnManager) Wait()
• type ConnReq
  • func (c *ConnReq) ID() uint64
  • func (c *ConnReq) State() ConnState
  • func (c *ConnReq) String() string
• type ConnState
• type DynamicBanScore
  • func (s *DynamicBanScore) Increase(persistent, transient uint32) uint32
  • func (s *DynamicBanScore) Int() uint32
  • func (s *DynamicBanScore) Reset()
  • func (s *DynamicBanScore) String() string
• type LookupFunc
• type OnSeed

Constants

const (
	// Halflife defines the time (in seconds) by which the transient part
	// of the ban score decays to one half of it's original value.
	Halflife = 60

	// Lifetime defines the maximum age of the transient part of the ban
	// score to be considered a non-zero score (in seconds).
	Lifetime = 1800
)

Variables

var (
	// ErrTorInvalidAddressResponse indicates an invalid address was
	// returned by the Tor DNS resolver.
	ErrTorInvalidAddressResponse = errors.New("invalid address response")

	// ErrTorInvalidProxyResponse indicates the Tor proxy returned a
	// response in an unexpected format.
	ErrTorInvalidProxyResponse = errors.New("invalid proxy response")

	// ErrTorUnrecognizedAuthMethod indicates the authentication method
	// provided is not recognized.
	ErrTorUnrecognizedAuthMethod = errors.New("invalid proxy authentication method")
)

var (
	//ErrDialNil is used to indicate that Dial cannot be nil in the configuration.
	ErrDialNil = errors.New("Config: Dial cannot be nil")
)

Functions

func DisableLog

func DisableLog()

DisableLog disables all library log output. Logging output is disabled by default until either UseLogger or SetLogWriter are called.

func SeedFromDNS

func SeedFromDNS(chainParams *chaincfg.Params, reqServices wire.ServiceFlag,
	lookupFn LookupFunc, seedFn OnSeed)

SeedFromDNS uses DNS seeding to populate the address manager with peers.

func TorLookupIP

func TorLookupIP(host, proxy string) ([]net.IP, error)

TorLookupIP uses Tor to resolve DNS via the SOCKS extension they provide for resolution over the Tor network. Tor itself doesn't support ipv6 so this doesn't either.

func UseLogger

func UseLogger(logger btclog.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 btclog.

Types

type Config

type Config struct {
	// Listeners defines a slice of listeners for which the connection
	// manager will take ownership of and accept connections.  When a
	// connection is accepted, the OnAccept handler will be invoked with the
	// connection.  Since the connection manager takes ownership of these
	// listeners, they will be closed when the connection manager is
	// stopped.
	//
	// This field will not have any effect if the OnAccept field is not
	// also specified.  It may be nil if the caller does not wish to listen
	// for incoming connections.
	Listeners []net.Listener

	// OnAccept is a callback that is fired when an inbound connection is
	// accepted.  It is the caller's responsibility to close the connection.
	// Failure to close the connection will result in the connection manager
	// believing the connection is still active and thus have undesirable
	// side effects such as still counting toward maximum connection limits.
	//
	// This field will not have any effect if the Listeners field is not
	// also specified since there couldn't possibly be any accepted
	// connections in that case.
	OnAccept func(net.Conn)

	// TargetOutbound is the number of outbound network connections to
	// maintain. Defaults to 8.
	TargetOutbound uint32

	// RetryDuration is the duration to wait before retrying connection
	// requests. Defaults to 5s.
	RetryDuration time.Duration

	// OnConnection is a callback that is fired when a new outbound
	// connection is established.
	OnConnection func(*ConnReq, net.Conn)

	// OnDisconnection is a callback that is fired when an outbound
	// connection is disconnected.
	OnDisconnection func(*ConnReq)

	// GetNewAddress is a way to get an address to make a network connection
	// to.  If nil, no new connections will be made automatically.
	GetNewAddress func() (net.Addr, error)

	// Dial connects to the address on the named network. It cannot be nil.
	Dial func(net.Addr) (net.Conn, error)
}

Config holds the configuration options related to the connection manager.

type ConnManager

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

ConnManager provides a manager to handle network connections.

func New

func New(cfg *Config) (*ConnManager, error)

New returns a new connection manager. Use Start to start connecting to the network.

func (*ConnManager) Connect

func (cm *ConnManager) Connect(c *ConnReq)

Connect assigns an id and dials a connection to the address of the connection request.

func (*ConnManager) Disconnect

func (cm *ConnManager) Disconnect(id uint64)

Disconnect disconnects the connection corresponding to the given connection id. If permanent, the connection will be retried with an increasing backoff duration.

func (*ConnManager) NewConnReq

func (cm *ConnManager) NewConnReq()

NewConnReq creates a new connection request and connects to the corresponding address.

func (*ConnManager) Remove

func (cm *ConnManager) Remove(id uint64)

Remove removes the connection corresponding to the given connection id from known connections.

NOTE: This method can also be used to cancel a lingering connection attempt that hasn't yet succeeded.

func (*ConnManager) Start

func (cm *ConnManager) Start()

Start launches the connection manager and begins connecting to the network.

func (*ConnManager) Stop

func (cm *ConnManager) Stop()

Stop gracefully shuts down the connection manager.

func (*ConnManager) Wait

func (cm *ConnManager) Wait()

Wait blocks until the connection manager halts gracefully.

type ConnReq

type ConnReq struct {
	Addr      net.Addr
	Permanent bool
	// contains filtered or unexported fields
}

ConnReq is the connection request to a network address. If permanent, the connection will be retried on disconnection.

func (*ConnReq) ID

func (c *ConnReq) ID() uint64

ID returns a unique identifier for the connection request.

func (*ConnReq) State

func (c *ConnReq) State() ConnState

State is the connection state of the requested connection.

func (*ConnReq) String

func (c *ConnReq) String() string

String returns a human-readable string for the connection request.

type ConnState

type ConnState uint8

ConnState represents the state of the requested connection.

const (
	ConnPending ConnState = iota
	ConnFailing
	ConnCanceled
	ConnEstablished
	ConnDisconnected
)

ConnState can be either pending, established, disconnected or failed. When a new connection is requested, it is attempted and categorized as established or failed depending on the connection result. An established connection which was disconnected is categorized as disconnected.

type DynamicBanScore

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

DynamicBanScore provides dynamic ban scores consisting of a persistent and a decaying component. The persistent score could be utilized to create simple additive banning policies similar to those found in other bitcoin node implementations.

The decaying score enables the creation of evasive logic which handles misbehaving peers (especially application layer DoS attacks) gracefully by disconnecting and banning peers attempting various kinds of flooding. DynamicBanScore allows these two approaches to be used in tandem.

Zero value: Values of type DynamicBanScore are immediately ready for use upon declaration.

func (*DynamicBanScore) Increase

func (s *DynamicBanScore) Increase(persistent, transient uint32) uint32

Increase increases both the persistent and decaying scores by the values passed as parameters. The resulting score is returned.

This function is safe for concurrent access.

func (*DynamicBanScore) Int

func (s *DynamicBanScore) Int() uint32

Int returns the current ban score, the sum of the persistent and decaying scores.

This function is safe for concurrent access.

func (*DynamicBanScore) Reset

func (s *DynamicBanScore) Reset()

Reset set both persistent and decaying scores to zero.

This function is safe for concurrent access.

func (*DynamicBanScore) String

func (s *DynamicBanScore) String() string

String returns the ban score as a human-readable string.

type LookupFunc

type LookupFunc func(string) ([]net.IP, error)

LookupFunc is the signature of the DNS lookup function.

type OnSeed

type OnSeed func(addrs []*wire.NetAddressV2)

OnSeed is the signature of the callback function which is invoked when DNS seeding is succesfull.