package nat

Import Path
	github.com/libp2p/go-libp2p/p2p/net/nat (on go.dev)

Dependency Relation
	imports 10 packages, and imported by one package

Involved Source Files

	    nat.go
Package-Level Type Names (only one)

	/* sort by: alphabet | popularity */
	 type NAT (struct)
		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.
		
		Locking strategy:
		  - natmu: Protects nat instance and rediscovery state (nat, consecutiveFailures, rediscovering)
		  - mappingmu: Protects port mappings table and closed flag (mappings, closed)
		  - Lock ordering: When both locks are needed, always acquire mappingmu before natmu
		    to prevent deadlocks
		  - We use separate mutexes because the NAT instance may change (e.g., when router
		    restarts and UPnP port changes), but the port mappings must persist and be
		    re-applied across all instances. This separation allows the mappings table to
		    remain stable while the underlying NAT device changes.

		Methods (total 4)
			(*NAT) AddMapping(ctx context.Context, protocol string, port int) error
				AddMapping attempts to construct a mapping on protocol and internal port.
				It blocks until a mapping was established. Once added, it periodically renews the mapping.
				
				May not succeed, and mappings may change over time;
				NAT devices may not respect our port requests, and even lie.

			(*NAT) Close() error
				Close shuts down all port mappings. NAT can no longer be used.

			(*NAT) GetMapping(protocol string, port int) (addr netip.AddrPort, found bool)
			(*NAT) RemoveMapping(ctx context.Context, protocol string, port int) error
				RemoveMapping removes a port mapping.
				It blocks until the NAT has removed the mapping.

		Implements (at least 2)
			*NAT : github.com/prometheus/common/expfmt.Closer
			*NAT : io.Closer
		As Outputs Of (at least one exported)
			func DiscoverNAT(ctx context.Context) (*NAT, error)


Package-Level Functions (only one)

	 func DiscoverNAT(ctx context.Context) (*NAT, error)
		DiscoverNAT looks for a NAT device in the network and returns an object that can manage port mappings.


Package-Level Variables (only one)

	  var ErrNoMapping error
		ErrNoMapping signals no mapping exists for an address


Package-Level Constants (total 3)

	const CacheTime time.Duration = 15000000000
		CacheTime is the time a mapping will cache an external address for

	const DiscoveryTimeout time.Duration = 10000000000
		DiscoveryTimeout is the maximum time to wait for NAT discovery.
		This is based on the underlying UPnP and NAT-PMP/PCP protocols:
		  - SSDP (UPnP discovery) waits 5 seconds for responses
		  - NAT-PMP uses exponential backoff starting at 250ms, up to 9 retries
		    (total ~32 seconds if exhausted, but typically responds in 1-2 seconds)
		  - PCP follows similar timing to NAT-PMP
		  - 10 seconds covers common cases while failing fast when no NAT exists

	const MappingDuration time.Duration = 60000000000
		MappingDuration is a default port mapping duration.
		Port mappings are renewed every (MappingDuration / 3)

The pages are generated with Golds v0.8.2. (GOOS=linux GOARCH=amd64)
Golds is a Go 101 project developed by Tapir Liu.
PR and bug reports are welcome and can be submitted to the issue list.
Please follow @zigo_101 (reachable from the left QR code) to get the latest news of Golds.