autonat

README

go-libp2p-autonat

Ambient NAT discovery

This package provides an ambient NAT autodiscovery service. It allows peers to figure out their NAT dialability situation by using test dial backs through peers providing the AutoNAT service.

Documentation

See https://godoc.org/github.com/libp2p/go-libp2p-autonat

Contribute

Feel free to join in. All welcome. Open an issue!

This repository falls under the IPFS Code of Conduct.

License

MIT

---

Documentation

Index

• Constants
• func IsDialError(e error) bool
• func IsDialRefused(e error) bool
• type AddrFunc
• type AmbientAutoNAT
  • func (as *AmbientAutoNAT) ClosedStream(net network.Network, s network.Stream)
  • func (as *AmbientAutoNAT) Connected(net network.Network, c network.Conn)
  • func (as *AmbientAutoNAT) Disconnected(net network.Network, c network.Conn)
  • func (as *AmbientAutoNAT) Listen(net network.Network, a ma.Multiaddr)
  • func (as *AmbientAutoNAT) ListenClose(net network.Network, a ma.Multiaddr)
  • func (as *AmbientAutoNAT) OpenedStream(net network.Network, s network.Stream)
  • func (as *AmbientAutoNAT) PublicAddr() (ma.Multiaddr, error)
  • func (as *AmbientAutoNAT) Status() network.Reachability
• type AutoNAT
  • func New(ctx context.Context, h host.Host, options ...Option) (AutoNAT, error)
• type AutoNATError
  • func (e AutoNATError) Error() string
  • func (e AutoNATError) IsDialError() bool
  • func (e AutoNATError) IsDialRefused() bool
• type Client
  • func NewAutoNATClient(h host.Host, addrFunc AddrFunc) Client
• type Option
  • func EnableService(dialer network.Network) Option
  • func UsingAddresses(addrFunc AddrFunc) Option
  • func WithPeerThrottling(amount int) Option
  • func WithReachability(reachability network.Reachability) Option
  • func WithSchedule(retryInterval, refreshInterval time.Duration) Option
  • func WithThrottling(amount int, interval time.Duration) Option
  • func WithoutStartupDelay() Option
  • func WithoutThrottling() Option
• type StaticAutoNAT
  • func (s *StaticAutoNAT) PublicAddr() (ma.Multiaddr, error)
  • func (s *StaticAutoNAT) Status() network.Reachability

Constants

const AutoNATProto = "/libp2p/autonat/1.0.0"

Functions

func IsDialError

func IsDialError(e error) bool

IsDialError returns true if the AutoNAT peer signalled an error dialing back

func IsDialRefused

func IsDialRefused(e error) bool

IsDialRefused returns true if the AutoNAT peer signalled refusal to dial back

Types

type AddrFunc

type AddrFunc func() []ma.Multiaddr

AddrFunc is a function returning the candidate addresses for the local host.

type AmbientAutoNAT

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

AmbientAutoNAT is the implementation of ambient NAT autodiscovery

func (*AmbientAutoNAT) ClosedStream

func (as *AmbientAutoNAT) ClosedStream(net network.Network, s network.Stream)

func (*AmbientAutoNAT) Connected

func (as *AmbientAutoNAT) Connected(net network.Network, c network.Conn)

func (*AmbientAutoNAT) Disconnected

func (as *AmbientAutoNAT) Disconnected(net network.Network, c network.Conn)

func (*AmbientAutoNAT) Listen

func (as *AmbientAutoNAT) Listen(net network.Network, a ma.Multiaddr)

func (*AmbientAutoNAT) ListenClose

func (as *AmbientAutoNAT) ListenClose(net network.Network, a ma.Multiaddr)

func (*AmbientAutoNAT) OpenedStream

func (as *AmbientAutoNAT) OpenedStream(net network.Network, s network.Stream)

func (*AmbientAutoNAT) PublicAddr

func (as *AmbientAutoNAT) PublicAddr() (ma.Multiaddr, error)

PublicAddr returns the publicly connectable Multiaddr of this node if one is known.

func (*AmbientAutoNAT) Status

func (as *AmbientAutoNAT) Status() network.Reachability

Status returns the AutoNAT observed reachability status.

type AutoNAT

type AutoNAT interface {
	// Status returns the current NAT status
	Status() network.Reachability
	// PublicAddr returns the public dial address when NAT status is public and an
	// error otherwise
	PublicAddr() (ma.Multiaddr, error)
}

AutoNAT is the interface for NAT autodiscovery

func New

func New(ctx context.Context, h host.Host, options ...Option) (AutoNAT, error)

New creates a new NAT autodiscovery system attached to a host

type AutoNATError

type AutoNATError struct {
	Status pb.Message_ResponseStatus
	Text   string
}

AutoNATError is the class of errors signalled by AutoNAT services

func (AutoNATError) Error

func (e AutoNATError) Error() string

func (AutoNATError) IsDialError

func (e AutoNATError) IsDialError() bool

func (AutoNATError) IsDialRefused

func (e AutoNATError) IsDialRefused() bool

type Client

type Client interface {
	// DialBack requests from a peer providing AutoNAT services to test dial back
	// and report the address on a successful connection.
	DialBack(ctx context.Context, p peer.ID) (ma.Multiaddr, error)
}

Client is a stateless client interface to AutoNAT peers

func NewAutoNATClient

func NewAutoNATClient(h host.Host, addrFunc AddrFunc) Client

NewAutoNATClient creates a fresh instance of an AutoNATClient If addrFunc is nil, h.Addrs will be used

type Option

type Option func(*config) error

Option is an Autonat option for configuration

func EnableService

func EnableService(dialer network.Network) Option

EnableService specifies that AutoNAT should be allowed to run a NAT service to help other peers determine their own NAT status. The provided Network should not be the default network/dialer of the host passed to `New`, as the NAT system will need to make parallel connections, and as such will modify both the associated peerstore and terminate connections of this dialer. The dialer provided should be compatible (TCP/UDP) however with the transports of the libp2p network.

func UsingAddresses

func UsingAddresses(addrFunc AddrFunc) Option

UsingAddresses allows overriding which Addresses the AutoNAT client believes are "its own". Useful for testing, or for more exotic port-forwarding scenarios where the host may be listening on different ports than it wants to externally advertise or verify connectability on.

func WithPeerThrottling

func WithPeerThrottling(amount int) Option

WithPeerThrottling specifies a limit for the maximum number of IP checks this node will provide to an individual peer in each `interval`.

func WithReachability

func WithReachability(reachability network.Reachability) Option

WithReachability overrides autonat to simply report an over-ridden reachability status.

func WithSchedule

func WithSchedule(retryInterval, refreshInterval time.Duration) Option

WithSchedule configures how agressively probes will be made to verify the address of the host. retryInterval indicates how often probes should be made when the host lacks confident about its address, while refresh interval is the schedule of periodic probes when the host believes it knows its steady-state reachability.

func WithThrottling

func WithThrottling(amount int, interval time.Duration) Option

WithThrottling specifies how many peers (`amount`) it is willing to help ever `interval` amount of time when acting as a server.

func WithoutStartupDelay

func WithoutStartupDelay() Option

WithoutStartupDelay removes the initial delay the NAT subsystem typically uses as a buffer for ensuring that connectivity and guesses as to the hosts local interfaces have settled down during startup.

func WithoutThrottling

func WithoutThrottling() Option

WithoutThrottling indicates that this autonat service should not place restrictions on how many peers it is willing to help when acting as a server.

type StaticAutoNAT

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

func (*StaticAutoNAT) PublicAddr

func (s *StaticAutoNAT) PublicAddr() (ma.Multiaddr, error)

func (*StaticAutoNAT) Status

func (s *StaticAutoNAT) Status() network.Reachability