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) (str network.Stream, strErr error)
  • func (h *BasicHost) NormalizeMultiaddr(addr ma.Multiaddr) ma.Multiaddr
  • 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. The output is the same as AllAddrs, but processed by AddrsFactory. When used with AutoRelay, and if the host is not publicly reachable, this will only have host's private, relay, and no public addresses.

func (*BasicHost) AllAddrs

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

AllAddrs returns all the addresses the host is listening on except circuit addresses.

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) (str network.Stream, strErr 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. (Thread-safe)

func (*BasicHost) NormalizeMultiaddr

func (h *BasicHost) NormalizeMultiaddr(addr ma.Multiaddr) ma.Multiaddr

NormalizeMultiaddr returns a multiaddr suitable for equality checks. If the multiaddr is a webtransport component, it removes the certhashes.

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)

(Thread-safe)

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 when negotiating
	// protocols for 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

	// 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

	// DisableIdentifyAddressDiscovery disables address discovery using peer provided observed addresses in identify
	DisableIdentifyAddressDiscovery bool
	EnableAutoNATv2                 bool
	AutoNATv2Dialer                 host.Host
}

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

type NATManager

type NATManager interface {
	GetMapping(ma.Multiaddr) ma.Multiaddr
	HasDiscoveredNAT() bool
	io.Closer
}

NATManager is a simple interface to manage NAT devices. It listens Listen and ListenClose notifications from the network.Network, and tries to obtain port mappings for those.

func NewNATManager

func NewNATManager(net network.Network) NATManager

NewNATManager creates a NAT manager.