server

Documentation

Index

• func DisableLog()
• func UseLogger(logger elalog.Logger)
• type Config
  • func NewDefaultConfig(magic, pver uint32, services uint64, defaultPort uint16, ...) *Config
• type IPeer
• type IServer
  • func NewServer(cfg *Config) (IServer, error)
• type NAT
  • func Discover() (nat NAT, err error)

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 UseLogger

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

Types

type Config

type Config struct {
	// DataDir is the data path to store peer addresses etc.
	DataDir string

	// MagicNumber is the peer-to-peer network ID to connect to.
	MagicNumber uint32

	// ProtocolVersion represent the protocol version you are supporting.
	ProtocolVersion uint32

	// Services represent which services you are supporting.
	Services uint64

	// DNSSeeds defines a list of DNS seeds for the network to discover peers.
	DNSSeeds []string

	// PermanentPeers are the peers need to be connected permanently.
	PermanentPeers []string

	// ListenAddrs are the addresses listen on to accept peer connections.
	ListenAddrs []string

	// ExternalIPs are a list of local addresses we claim to listen on to peers.
	ExternalIPs []string

	// Use UPnP to map our listening port outside of NAT
	Upnp bool

	// DefaultPort defines the default peer-to-peer port for the network.
	DefaultPort uint16

	// Disable listening for incoming connections.
	DisableListen bool

	// DisableRelayTx specifies if the remote peer should be informed to
	// not send inv messages for transactions.
	DisableRelayTx bool

	// Max number of inbound and outbound peers.
	MaxPeers int

	// Disable banning of misbehaving peers.
	DisableBanning bool

	// Maximum allowed ban score before disconnecting and banning misbehaving
	// peers.
	BanThreshold uint32

	// How long to ban misbehaving peers.  Valid time units are {s, m, h}.
	// Minimum 1 second
	BanDuration time.Duration

	// IP networks or IPs that will not be banned. (eg. 192.168.1.0/24 or ::1)
	Whitelists []*net.IPNet

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

	// OnNewPeer will be invoked when a new peer connected.
	OnNewPeer func(IPeer)

	// OnDonePeer will be invoked when a peer disconnected.
	OnDonePeer func(IPeer)

	// MakeEmptyMessage will be invoked to creates a message of the appropriate
	// concrete type based on the command.
	MakeEmptyMessage func(string) (p2p.Message, error)

	// BestHeight will be invoked to get current best height.
	BestHeight func() uint64

	// PingNonce will be invoked to get a nonce when sending a ping message.
	PingNonce func() uint64

	// PongNonce will be invoked to get a nonce when sending a ping message.
	PongNonce func() uint64

	// NAFilter is a network address filter for peers to filter relayed
	// addresses.
	NAFilter p2p.NAFilter
}

Config is a descriptor which specifies the server instance configuration.

func NewDefaultConfig

func NewDefaultConfig(
	magic, pver uint32,
	services uint64,
	defaultPort uint16,
	seeds, listenAddrs []string,
	onNewPeer func(IPeer),
	onDonePeer func(IPeer),
	makeEmptyMessage func(string) (p2p.Message, error),
	bestHeight func() uint64) *Config

NewDefaultConfig returns a new config instance filled by default settings for the server.

type IPeer

type IPeer interface {
	// ToPeer returns the underlying peer instance.
	ToPeer() *peer.Peer

	// AddBanScore increases the persistent and decaying ban score fields by the
	// values passed as parameters. If the resulting score exceeds half of the ban
	// threshold, a warning is logged including the reason provided. Further, if
	// the score is above the ban threshold, the peer will be banned and
	// disconnected.
	AddBanScore(persistent, transient uint32, reason string)

	// BanScore returns the current integer value that represents how close
	// the peer is to being banned.
	BanScore() uint32
}

IPeer represents a peer for the server.

The interface contract requires that all of these methods are safe for concurrent access.

type IServer

type IServer interface {
	// Start begins accepting connections from peers.
	Start()

	// Stop gracefully shuts down the server by stopping and disconnecting all
	// peers and the main listener.
	Stop() error

	// ScheduleShutdown schedules a server shutdown after the specified duration.
	// It also dynamically adjusts how often to warn the server is going down based
	// on remaining duration.
	ScheduleShutdown(duration time.Duration)

	// Connect adds the provided address as a new outbound peer.  The
	// permanent flag indicates whether or not to make the peer persistent
	// and reconnect if the connection is lost.  Attempting to connect to an
	// already existing peer will return an error.
	Connect(addr string, permanent bool) error

	// RemoveByID removes the peer associated with the provided id from the
	// list of persistent peers.  Attempting to remove an id that does not
	// exist will return an error.
	RemoveByID(id uint64) error

	// RemoveByAddr removes the peer associated with the provided address
	// from the list of persistent peers.  Attempting to remove an address
	// that does not exist will return an error.
	RemoveByAddr(addr string) error

	// DisconnectByID disconnects the peer associated with the provided id.
	// This applies to both inbound and outbound peers.  Attempting to
	// remove an id that does not exist will return an error.
	DisconnectByID(id uint64) error

	// DisconnectByAddr disconnects the peer associated with the provided
	// address.  This applies to both inbound and outbound peers.
	// Attempting to remove an address that does not exist will return an
	// error.
	DisconnectByAddr(addr string) error

	// ConnectedCount returns the number of currently connected peers.
	ConnectedCount() int32

	// ConnectedPeers returns an array consisting of all connected peers.
	ConnectedPeers() []IPeer

	// PersistentPeers returns an array consisting of all the persistent
	// peers.
	PersistentPeers() []IPeer

	// BroadcastMessage sends the provided message to all currently
	// connected peers.
	BroadcastMessage(msg p2p.Message, exclPeers ...*serverPeer)
}

IServer represents a server.

The interface contract requires that all of these methods are safe for concurrent access.

func NewServer

func NewServer(cfg *Config) (IServer, error)

NewServer return a server instance that implement the IServer interface.

type NAT

type NAT interface {
	// Get the external address from outside the NAT.
	GetExternalAddress() (addr net.IP, err error)
	// Add a port mapping for protocol ("udp" or "tcp") from external port to
	// internal port with description lasting for timeout.
	AddPortMapping(protocol string, externalPort, internalPort int, description string, timeout int) (mappedExternalPort int, err error)
	// Remove a previously added port mapping from external port to
	// internal port.
	DeletePortMapping(protocol string, externalPort, internalPort int) (err error)
}

NAT is an interface representing a NAT traversal options for example UPNP or NAT-PMP. It provides methods to query and manipulate this traversal to allow access to services.

func Discover

func Discover() (nat NAT, err error)

Discover searches the local network for a UPnP router returning a NAT for the network if so, nil if not.