basichost

Documentation

Index

• Variables
• type AddrsFactory
• type BasicHost
  • func NewHost(n network.Network, opts *HostOpts) (*BasicHost, error)
  • func (h *BasicHost) Addrs() []ma.Multiaddr
  • func (h *BasicHost) AllAddrs() []ma.Multiaddr
  • func (h *BasicHost) Close() error
  • func (h *BasicHost) ConnManager() connmgr.ConnManager
  • func (h *BasicHost) Connect(ctx context.Context, pi peer.AddrInfo) error
  • func (h *BasicHost) EventBus() event.Bus
  • func (h *BasicHost) GetAutoNat() autonat.AutoNAT
  • func (h *BasicHost) ID() peer.ID
  • func (h *BasicHost) IDService() identify.IDService
  • func (h *BasicHost) Mux() protocol.Switch
  • func (h *BasicHost) Network() network.Network
  • func (h *BasicHost) NewStream(ctx context.Context, p peer.ID, pids ...protocol.ID) (network.Stream, error)
  • func (h *BasicHost) Peerstore() peerstore.Peerstore
  • func (h *BasicHost) RemoveStreamHandler(pid protocol.ID)
  • func (h *BasicHost) SetAutoNat(a autonat.AutoNAT)
  • func (h *BasicHost) SetStreamHandler(pid protocol.ID, handler network.StreamHandler)
  • func (h *BasicHost) SetStreamHandlerMatch(pid protocol.ID, m func(protocol.ID) bool, handler network.StreamHandler)
  • func (h *BasicHost) SignalAddressChange()
  • func (h *BasicHost) Start()
• type HostOpts
• type NATManager
  • func NewNATManager(net network.Network) NATManager

Variables

var (
	// DefaultNegotiationTimeout is the default value for HostOpts.NegotiationTimeout.
	DefaultNegotiationTimeout = 10 * time.Second

	// DefaultAddrsFactory is the default value for HostOpts.AddrsFactory.
	DefaultAddrsFactory = func(addrs []ma.Multiaddr) []ma.Multiaddr { return addrs }
)

Types

type AddrsFactory

type AddrsFactory func([]ma.Multiaddr) []ma.Multiaddr

AddrsFactory functions can be passed to New in order to override addresses returned by Addrs.

type BasicHost

type BasicHost struct {
	AddrsFactory AddrsFactory
	// contains filtered or unexported fields
}

BasicHost is the basic implementation of the host.Host interface. This particular host implementation:

• uses a protocol muxer to mux per-protocol streams
• uses an identity service to send + receive node information
• uses a nat service to establish NAT port mappings

func NewHost

func NewHost(n network.Network, opts *HostOpts) (*BasicHost, error)

NewHost constructs a new *BasicHost and activates it by attaching its stream and connection handlers to the given inet.Network.

func (*BasicHost) Addrs

func (h *BasicHost) Addrs() []ma.Multiaddr

Addrs returns listening addresses that are safe to announce to the network. The output is the same as AllAddrs, but processed by AddrsFactory.

func (*BasicHost) AllAddrs

func (h *BasicHost) AllAddrs() []ma.Multiaddr

AllAddrs returns all the addresses of BasicHost at this moment in time. It's ok to not include addresses if they're not available to be used now.

func (*BasicHost) Close

func (h *BasicHost) Close() error

Close shuts down the Host's services (network, etc).

func (*BasicHost) ConnManager

func (h *BasicHost) ConnManager() connmgr.ConnManager

func (*BasicHost) Connect

func (h *BasicHost) Connect(ctx context.Context, pi peer.AddrInfo) error

Connect ensures there is a connection between this host and the peer with given peer.ID. If there is not an active connection, Connect will issue a h.Network.Dial, and block until a connection is open, or an error is returned. Connect will absorb the addresses in pi into its internal peerstore. It will also resolve any /dns4, /dns6, and /dnsaddr addresses.

func (*BasicHost) EventBus

func (h *BasicHost) EventBus() event.Bus

func (*BasicHost) GetAutoNat

func (h *BasicHost) GetAutoNat() autonat.AutoNAT

GetAutoNat returns the host's AutoNAT service, if AutoNAT is enabled.

func (*BasicHost) ID

func (h *BasicHost) ID() peer.ID

ID returns the (local) peer.ID associated with this Host

func (*BasicHost) IDService

func (h *BasicHost) IDService() identify.IDService

IDService returns

func (*BasicHost) Mux

func (h *BasicHost) Mux() protocol.Switch

Mux returns the Mux multiplexing incoming streams to protocol handlers

func (*BasicHost) Network

func (h *BasicHost) Network() network.Network

Network returns the Network interface of the Host

func (*BasicHost) NewStream

func (h *BasicHost) NewStream(ctx context.Context, p peer.ID, pids ...protocol.ID) (network.Stream, error)

NewStream opens a new stream to given peer p, and writes a p2p/protocol header with given protocol.ID. If there is no connection to p, attempts to create one. If ProtocolID is "", writes no header. (Threadsafe)

func (*BasicHost) Peerstore

func (h *BasicHost) Peerstore() peerstore.Peerstore

Peerstore returns the Host's repository of Peer Addresses and Keys.

func (*BasicHost) RemoveStreamHandler

func (h *BasicHost) RemoveStreamHandler(pid protocol.ID)

RemoveStreamHandler returns ..

func (*BasicHost) SetAutoNat

func (h *BasicHost) SetAutoNat(a autonat.AutoNAT)

SetAutoNat sets the autonat service for the host.

func (*BasicHost) SetStreamHandler

func (h *BasicHost) SetStreamHandler(pid protocol.ID, handler network.StreamHandler)

SetStreamHandler sets the protocol handler on the Host's Mux. This is equivalent to:

host.Mux().SetHandler(proto, handler)

(Threadsafe)

func (*BasicHost) SetStreamHandlerMatch

func (h *BasicHost) SetStreamHandlerMatch(pid protocol.ID, m func(protocol.ID) bool, handler network.StreamHandler)

SetStreamHandlerMatch sets the protocol handler on the Host's Mux using a matching function to do protocol comparisons

func (*BasicHost) SignalAddressChange

func (h *BasicHost) SignalAddressChange()

SignalAddressChange signals to the host that it needs to determine whether our listen addresses have recently changed. Warning: this interface is unstable and may disappear in the future.

func (*BasicHost) Start

func (h *BasicHost) Start()

Start starts background tasks in the host

type HostOpts

type HostOpts struct {
	// EventBus sets the event bus. Will construct a new event bus if omitted.
	EventBus event.Bus

	// MultistreamMuxer is essential for the *BasicHost and will use a sensible default value if omitted.
	MultistreamMuxer *msmux.MultistreamMuxer[protocol.ID]

	// NegotiationTimeout determines the read and write timeouts on streams.
	// If 0 or omitted, it will use DefaultNegotiationTimeout.
	// If below 0, timeouts on streams will be deactivated.
	NegotiationTimeout time.Duration

	// AddrsFactory holds a function which can be used to override or filter the result of Addrs.
	// If omitted, there's no override or filtering, and the results of Addrs and AllAddrs are the same.
	AddrsFactory AddrsFactory

	// MultiaddrResolves holds the go-multiaddr-dns.Resolver used for resolving
	// /dns4, /dns6, and /dnsaddr addresses before trying to connect to a peer.
	MultiaddrResolver *madns.Resolver

	// NATManager takes care of setting NAT port mappings, and discovering external addresses.
	// If omitted, this will simply be disabled.
	NATManager func(network.Network) NATManager

	// ConnManager is a libp2p connection manager
	ConnManager connmgr.ConnManager

	// EnablePing indicates whether to instantiate the ping service
	EnablePing bool

	// EnableRelayService enables the circuit v2 relay (if we're publicly reachable).
	EnableRelayService bool
	// RelayServiceOpts are options for the circuit v2 relay.
	RelayServiceOpts []relayv2.Option

	// UserAgent sets the user-agent for the host.
	UserAgent string

	// ProtocolVersion sets the protocol version for the host.
	ProtocolVersion string

	// DisableSignedPeerRecord disables the generation of Signed Peer Records on this host.
	DisableSignedPeerRecord bool

	// EnableHolePunching enables the peer to initiate/respond to hole punching attempts for NAT traversal.
	EnableHolePunching bool
	// HolePunchingOptions are options for the hole punching service
	HolePunchingOptions []holepunch.Option

	// EnableMetrics enables the metrics subsystems
	EnableMetrics bool
	// PrometheusRegisterer is the PrometheusRegisterer used for metrics
	PrometheusRegisterer prometheus.Registerer
}

HostOpts holds options that can be passed to NewHost in order to customize construction of the *BasicHost.

type NATManager

type NATManager interface {
	// NAT gets the NAT device managed by the NAT manager.
	NAT() *inat.NAT

	// Ready receives a notification when the NAT device is ready for use.
	Ready() <-chan struct{}

	io.Closer
}

NATManager is a simple interface to manage NAT devices.

func NewNATManager

func NewNATManager(net network.Network) NATManager

NewNATManager creates a NAT manager.