Module method 

Traversal methods — one module per NAT-traversal technique behind a common TraversalMethod trait, plus the TraversalKind tag the strategy orders them by.

Each method answers ONE question: “given this peer, can you produce a reachable socket address I can dial (and, for the relayed method, an already-open transport)?” The crate::strategy module owns the ORDER + the racing/sequencing; a method never decides it is “the one”. This keeps every technique small, single-purpose, and independently testable with a mock socket / fake IGD / loopback relay.

Attempt order (first success wins), from the crate DESIGN.md:

1. direct — peer publicly reachable / already port-forwarded
2. upnp — UPnP/IGD port mapping
3. natpmp — NAT-PMP (RFC 6886)
4. pcp — PCP (RFC 6887)
5. hole_punch — relay-coordinated simultaneous-open hole punch: the relay is used ONLY as a signaling/rendezvous channel to exchange candidates + coordinate timing; the DATA path is peer-to-peer DIRECT (relay carries no data → minimal relay bandwidth).
6. relayed — TURN-like relayed transport: the relay carries ALL data (highest relay bandwidth). The genuine LAST resort, tried only after the hole punch (tier 5) fails.

Tiers 5 and 6 are deliberately SEPARATE methods with separate abstractions (hole_punch::HolePunchCoordinator = signaling-only vs relayed::RelayedTransport = data-proxy) and separate TraversalKinds so observability reports exactly which succeeded and the strategy prefers the bandwidth-cheap punch before the bandwidth-heavy TURN.

Modules

direct

Direct method — the peer is already reachable at a known ip:port (publicly routable, or its operator port-forwarded it). No NAT work needed: just hand the strategy the address to dial.

hole_punch

Relay-coordinated hole-punch method (RLY-007) — when both peers are behind NAT, use the relay as a rendezvous to exchange server-reflexive addresses, then attempt a simultaneous open so a DIRECT path forms across both NATs (no relayed traffic).

natpmp

NAT-PMP method (RFC 6886) — ask the local NAT gateway for a port mapping so inbound peer dials reach this node, and learn the gateway’s external IP.

pcp

PCP method (RFC 6887) — the successor to NAT-PMP. Same goal (open an inbound pinhole on the gateway) with a richer, IPv6-capable datagram.

relayed

Relayed-transport method (TURN-like) — the last resort, tier 6.

upnp

UPnP/IGD method — ask the local Internet Gateway Device (via UPnP SSDP discovery + SOAP) to add a port mapping so inbound peer dials reach this node.

Structs

MethodOutcome

What a traversal method yields on success: the dialable candidate addresses for the peer (ordered IPv6-first), plus which technique produced them. The crate::strategy then performs the mTLS dial, trying the candidates IPv6-first with IPv4 fallback (happy-eyeballs, see crate::dialer) — except the relayed method, which returns the already-open relay tunnel.

Enums

TraversalKind

Which traversal technique produced a result — used to order methods, tag failures, and report (observability) which method actually succeeded WITHOUT the caller caring.

Traits

TraversalMethod

A single NAT-traversal technique. Implementors are small + single-purpose and MUST honour the deadline the strategy hands them (they are additionally wrapped in a hard timeout by the strategy, so a hung method can never block connect).