basichost

Documentation

Index

• Variables
• type AddrsFactory
• type BasicHost
  • func New(net network.Network, opts ...interface{}) *BasicHost
  • func NewHost(ctx context.Context, net 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) 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) SetStreamHandler(pid protocol.ID, handler network.StreamHandler)
  • func (h *BasicHost) SetStreamHandlerMatch(pid protocol.ID, m func(string) bool, handler network.StreamHandler)
  • func (h *BasicHost) SignalAddressChange()
  • func (h *BasicHost) Start()
• type HostOpts
• type NATManager
  • func NewNATManager(net network.Network) NATManager
• type Option

Variables

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

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

func New(net network.Network, opts ...interface{}) *BasicHost

New constructs and sets up a new *BasicHost with given Network and options. The following options can be passed: * NATPortMap * AddrsFactory * connmgr.ConnManager * madns.Resolver

This function is deprecated in favor of NewHost and HostOpts.

func NewHost

func NewHost(ctx context.Context, net 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) 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) 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(string) 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 {
	// MultistreamMuxer is essential for the *BasicHost and will use a sensible default value if omitted.
	MultistreamMuxer *msmux.MultistreamMuxer

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

	// UserAgent sets the user-agent for the host. Defaults to ClientVersion.
	UserAgent string
}

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

type NATManager

type NATManager interface {

	// Get the NAT device managed by the NAT manager.
	NAT() *inat.NAT

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

	// Close all resources associated with a NAT manager.
	Close() error
}

A simple interface to manage NAT devices.

func NewNATManager

func NewNATManager(net network.Network) NATManager

Create a NAT manager.

type Option

type Option int

Option is a type used to pass in options to the host.

Deprecated in favor of HostOpts and NewHost.

const NATPortMap Option = iota

NATPortMap makes the host attempt to open port-mapping in NAT devices for all its listeners. Pass in this option in the constructor to asynchronously a) find a gateway, b) open port mappings, c) republish port mappings periodically. The NATed addresses are included in the Host's Addrs() list.

This option is deprecated in favor of HostOpts and NewHost.