nat

Documentation

Index

• Constants
• Variables
• type Mapping
• type NAT
  • func DiscoverNAT() *NAT
  • func (nat *NAT) Close() error
  • func (nat *NAT) ExternalAddrs() []ma.Multiaddr
  • func (nat *NAT) MappedAddrs() map[ma.Multiaddr]ma.Multiaddr
  • func (nat *NAT) Mappings() []Mapping
  • func (nat *NAT) NewMapping(maddr ma.Multiaddr) (Mapping, error)
  • func (nat *NAT) PortMapAddrs(addrs []ma.Multiaddr)
  • func (nat *NAT) Process() goprocess.Process
• type Notifiee
• type Notifier
  • func (n *Notifier) Notify(notifiee Notifiee)
  • func (n *Notifier) StopNotify(notifiee Notifiee)

Constants

const CacheTime = time.Second * 15

CacheTime is the time a mapping will cache an external address for

const MappingDuration = time.Second * 60

MappingDuration is a default port mapping duration. Port mappings are renewed every (MappingDuration / 3)

Variables

var (
	// ErrNoMapping signals no mapping exists for an address
	ErrNoMapping = errors.New("mapping not established")
)

Types

type Mapping

type Mapping interface {
	// NAT returns the NAT object this Mapping belongs to.
	NAT() *NAT

	// Protocol returns the protocol of this port mapping. This is either
	// "tcp" or "udp" as no other protocols are likely to be NAT-supported.
	Protocol() string

	// InternalPort returns the internal device port. Mapping will continue to
	// try to map InternalPort() to an external facing port.
	InternalPort() int

	// ExternalPort returns the external facing port. If the mapping is not
	// established, port will be 0
	ExternalPort() int

	// InternalAddr returns the internal address.
	InternalAddr() ma.Multiaddr

	// ExternalAddr returns the external facing address. If the mapping is not
	// established, addr will be nil, and and ErrNoMapping will be returned.
	ExternalAddr() (addr ma.Multiaddr, err error)

	// Close closes the port mapping
	Close() error
}

Mapping represents a port mapping in a NAT.

type NAT

type NAT struct {
	Notifier
	// contains filtered or unexported fields
}

NAT is an object that manages address port mappings in NATs (Network Address Translators). It is a long-running service that will periodically renew port mappings, and keep an up-to-date list of all the external addresses.

func DiscoverNAT

func DiscoverNAT() *NAT

DiscoverNAT looks for a NAT device in the network and returns an object that can manage port mappings.

func (*NAT) Close

func (nat *NAT) Close() error

Close shuts down all port mappings. NAT can no longer be used.

func (*NAT) ExternalAddrs

func (nat *NAT) ExternalAddrs() []ma.Multiaddr

ExternalAddrs returns a list of addresses that NAT believes have been successfully established. Unsuccessful mappings are omitted, so nat.ExternalAddrs() may return less addresses than nat.InternalAddrs(). To see which addresses are mapped, use nat.MappedAddrs().

This set of mappings _may not_ be correct, as NAT devices are finicky. Consider this with _best effort_ semantics.

func (*NAT) MappedAddrs

func (nat *NAT) MappedAddrs() map[ma.Multiaddr]ma.Multiaddr

MappedAddrs returns address mappings NAT believes have been successfully established. Unsuccessful mappings are nil. This is:

map[internalAddr]externalAddr

This set of mappings _may not_ be correct, as NAT devices are finicky. Consider this with _best effort_ semantics.

func (*NAT) Mappings

func (nat *NAT) Mappings() []Mapping

Mappings returns a slice of all NAT mappings

func (*NAT) NewMapping

func (nat *NAT) NewMapping(maddr ma.Multiaddr) (Mapping, error)

NewMapping attemps to construct a mapping on protocol and internal port It will also periodically renew the mapping until the returned Mapping -- or its parent NAT -- is Closed.

May not succeed, and mappings may change over time; NAT devices may not respect our port requests, and even lie. Clients should not store the mapped results, but rather always poll our object for the latest mappings.

func (*NAT) PortMapAddrs

func (nat *NAT) PortMapAddrs(addrs []ma.Multiaddr)

PortMapAddrs attempts to open (and continue to keep open) port mappings for given addrs. This function blocks until all addresses have been tried. This allows clients to retrieve results immediately after:

nat.PortMapAddrs(addrs)
mapped := nat.ExternalAddrs()

Some may not succeed, and mappings may change over time; NAT devices may not respect our port requests, and even lie. Clients should not store the mapped results, but rather always poll our object for the latest mappings.

func (*NAT) Process

func (nat *NAT) Process() goprocess.Process

Process returns the nat's life-cycle manager, for making it listen to close signals.

type Notifiee

type Notifiee interface {

	// Called every time a successful mapping happens
	// Warning: the port mapping may have changed. If that is the
	// case, both MappingSuccess and MappingChanged are called.
	MappingSuccess(nat *NAT, m Mapping)

	// Called when mapping a port succeeds, but the mapping is
	// with a different port than an earlier success.
	MappingChanged(nat *NAT, m Mapping, oldport int, newport int)

	// Called when a port mapping fails. NAT will continue attempting after
	// the next period. To stop trying, use: mapping.Close(). After this failure,
	// mapping.ExternalPort() will be zero, and nat.ExternalAddrs() will not
	// return the address for this mapping. With luck, the next attempt will
	// succeed, without the client needing to do anything.
	MappingFailed(nat *NAT, m Mapping, oldport int, err error)
}

Notifiee is an interface objects must implement to listen to NAT events.

type Notifier

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

Notifier is an object that assists NAT in notifying listeners. It is implemented using thirdparty/notifier

func (*Notifier) Notify

func (n *Notifier) Notify(notifiee Notifiee)

Notify signs up notifiee to listen to NAT events.

func (*Notifier) StopNotify

func (n *Notifier) StopNotify(notifiee Notifiee)

StopNotify stops signaling events to notifiee.