release: v0.32.0

[jacderida]

Summary

• Merges RC branch rc-2026.4.1 into main for the v0.32.0 release
• Includes all PRs merged to the RC branch (refactor: remove dead connect_dual_stack and try_connect_family methods #36–feat: increase ACK timeout size budget from 1ms/KB to 4ms/KB #58), with PR fix: increase handshake channel capacity from 32 to 1024 #59 reverted (revert: undo PR #59 handshake channel capacity increase #60)
• Version bumped to 0.32.0 with updated Cargo.lock

Key changes

• NAT traversal fixes for large-scale testnets (990+ nodes)
• PUNCH_ME_NOW_NACK coordinator signalling
• Quality-aware coordinator selection with RTT weighting
• Lock-free ConnectionRouter with atomic selection stats
• UPnP IGD port mapping for NAT traversal
• Tightened network timeouts for faster connection establishment
• Relay session improvements (cleanup, rotation, health monitoring)
• ACK timeout size budget increase (1ms/KB → 4ms/KB)

Test plan

• CI passes
• Tag v0.32.0 after merge

🤖 Generated with Claude Code

Greptile Summary

This release PR merges the rc-2026.4.1 branch into main for v0.32.0, incorporating a large batch of NAT traversal improvements: UPnP IGD port mapping, a lock-free ConnectionRouter, Tier-4 coordinator back-pressure via RelaySlotTable, PUNCH_ME_NOW_NACK signalling for faster coordinator rotation, quality-aware DHT-referrer coordinator selection, tightened connection timeouts, and relay session lifecycle improvements.

• P1 — broken test: src/connection_strategy.rs::test_default_config asserts holepunch_timeout = 8s and relay_timeout = 10s, but the Default impl in this PR sets them to 3s and 5s. CI will fail until one side is corrected.
• P2 — stale NACK accumulation: a NACK not consumed before try_hole_punch is cancelled by the outer timeout lingers in nack_set and may prematurely abort the next coordinator rotation for the same target.
• P2 — rate-limit relaxation: max_coordination_per_window was raised 60× (5 → 300/min per connection); the RelaySlotTable provides the real back-pressure, but the per-connection guard is now largely inert.

Confidence Score: 4/5

Safe to merge after fixing the test mismatch in connection_strategy.rs; all other findings are P2.

One P1 finding — the test_default_config assertions diverge from the Default impl and will break CI. The remaining comments are P2 quality/hardening concerns that do not block correctness.

src/connection_strategy.rs — test_default_config will fail due to holepunch_timeout/relay_timeout mismatch between Default impl and assertions.

Important Files Changed

Filename	Overview
src/connection_strategy.rs	Tightened strategy timeouts and added transition_to_next_relay; but test_default_config asserts 8s/10s for holepunch/relay while the Default impl produces 3s/5s — this test will fail.
src/upnp.rs	New best-effort UPnP IGD port-mapping service; cleanly feature-gated, validates external IP for public routability before surfacing as a candidate, and gracefully degrades when no gateway is present.
src/relay_slot_table.rs	New node-wide Tier-4 back-pressure table for coordinator relay sessions; keyed by (initiator_addr, target_peer_id), amortized inline sweep, released on connection Drop — well-tested.
src/connection_router.rs	Refactored to lock-free interior mutability: RouterStats now uses AtomicU64, constrained transport uses OnceLock, and all public methods take &self.
src/p2p_endpoint.rs	Major additions: quality-aware coordinator rotation, per-target DashMap for peer IDs and preferred coordinators, NACK fast-exit path, relay timeout, and reachability tracking; stale NACK accumulation across rotations is a minor edge case.
src/connection/nat_traversal.rs	Adds RelaySlotTable integration into BootstrapCoordinator, Drop impl for slot release, and PortMapped candidate source; max_coordination_per_window raised 60× from 5→300 deserves review.
src/frame/nat_traversal_unified.rs	New PunchMeNowNack frame (0x3d7e99) with clean encode/decode and correct SIZE_BOUND constant.
src/node.rs	Replaced speculative has_public_ip with freshness-aware can_receive_direct based on actual inbound connection evidence and DIRECT_REACHABILITY_TTL.
src/reachability.rs	New module providing ReachabilityScope, TraversalMethod, and socket_addr_scope helpers; cleanly separates address classification from node-level policy.
src/masque/relay_server.rs	Added spawn_cleanup_task with Weak-reference lifecycle and two covering tests.
src/config/nat_timeouts.rs	Raised DEFAULT_SEND_ACK_TIMEOUT from 1s → 5s and FAST_SEND_ACK_TIMEOUT from 500ms → 2500ms to handle cross-region hole-punched paths; rationale well-documented.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[connect_with_fallback] --> B{Direct connect}
    B -->|success| Z[Connected - Direct]
    B -->|fail| C{Preferred coordinators from DHT?}
    C -->|Yes: N coordinators| D[Rotate through coordinators\n1.5s quick timeout each except last]
    C -->|No| E[Single coordinator\nfull strategy timeout]
    D --> F{try_hole_punch}
    E --> F
    F -->|NACK received| G[consume_nack - abort early\nrotate to next coordinator]
    G --> D
    F -->|timeout / error| H{More coordinators in rotation?}
    H -->|Yes| D
    H -->|No - should_retry?| F
    H -->|No - exhausted| I[Post-punch direct retry 1s]
    F -->|success| Z2[Connected - HolePunch]
    I -->|success| Z2
    I -->|fail| J{Try relay}
    J -->|5s timeout| K[transition_to_next_relay]
    K -->|more relays| J
    K -->|exhausted| L[Connection Failed]
    J -->|success| Z3[Connected - Relay]
    subgraph Coordinator back-pressure
        M[PUNCH_ME_NOW arrives at coordinator]
        M --> N{RelaySlotTable at capacity?}
        N -->|No - slot acquired| O[Forward to target]
        N -->|Yes - refused| P[Silent drop - initiator times out]
        O --> Q{Target found?}
        Q -->|No| R[Send PUNCH_ME_NOW_NACK]
        Q -->|Yes| S[Relay frame to target]
    end

Loading

Prompt To Fix All With AI

This is a comment left during a code review.
Path: src/connection_strategy.rs
Line: 489-490

Comment:
**Test-vs-implementation mismatch: CI will fail**

The `Default` impl (line 183–184) sets `holepunch_timeout = 3s` and `relay_timeout = 5s`, but this test asserts `8s` and `10s` respectively. These values have never matched in this PR, so `cargo test` will fail.

Either the test needs to be updated to the values the `Default` impl actually produces, or the `Default` impl needs to be corrected to the intended values:

```suggestion
        assert_eq!(config.holepunch_timeout, Duration::from_secs(3));
        assert_eq!(config.relay_timeout, Duration::from_secs(5));
```

How can I resolve this? If you propose a fix, please make it concise.

---

This is a comment left during a code review.
Path: src/p2p_endpoint.rs
Line: 93-104

Comment:
**Docstring references a stale `8s` timeout**

The comment says "the worst-case wait for K preferred coordinators is roughly `(K-1) * 1.5s + 8s`", but the `holepunch_timeout` default in `StrategyConfig` is now `3s` (set in this PR, `connection_strategy.rs` line 183). The `8s` figure is stale — either the default was intended to stay at 8s (in which case `Default` needs fixing) or the docstring should be updated to reflect `3s`.

How can I resolve this? If you propose a fix, please make it concise.

---

This is a comment left during a code review.
Path: src/connection/nat_traversal.rs
Line: 484

Comment:
**Per-connection coordination rate limit raised 60×**

`max_coordination_per_window` went from 5 → 300 PUNCH_ME_NOW requests per 60-second window *per connection*. While the new `RelaySlotTable` provides the actual node-wide back-pressure at 32 concurrent sessions (which is the right control), this effectively neuters the per-connection DoS guard: a single misbehaving peer can now issue 300 relay-probe bursts per minute before the per-connection rate limiter fires. Consider whether the Tier-4 cap alone is sufficient or whether a more moderate per-connection limit (e.g. 60–120/min) is preferable to retain defence-in-depth.

How can I resolve this? If you propose a fix, please make it concise.

---

This is a comment left during a code review.
Path: src/p2p_endpoint.rs
Line: 2263-2275

Comment:
**Stale NACKs may prematurely abort the next coordinator rotation**

When `try_hole_punch` is cancelled (because the outer `timeout(attempt_timeout, …)` fires), any NACK that arrived just before the cancellation stays unconsumed in `self.inner.nack_set`. On the *next* call to `try_hole_punch` (with a different coordinator), `nack_notify` may immediately fire and `consume_nack` will return `true` — returning `Err(...)` even though the *new* coordinator hasn't sent a NACK. Consider clearing the NACK entry for the target when rotating coordinators, or scoping NACKs by `(coordinator_addr, target_peer_id)` so a stale NACK from coordinator A doesn't abort coordinator B.

How can I resolve this? If you propose a fix, please make it concise.

_{Reviews (1): Last reviewed commit: "style: apply rustfmt formatting" | Re-trigger Greptile}

Greptile also left 4 inline comments on this PR.

[greptile-apps]

Test-vs-implementation mismatch: CI will fail

The Default impl (line 183–184) sets holepunch_timeout = 3s and relay_timeout = 5s, but this test asserts 8s and 10s respectively. These values have never matched in this PR, so cargo test will fail.

Either the test needs to be updated to the values the Default impl actually produces, or the Default impl needs to be corrected to the intended values:

Suggested change

	assert_eq!(config.holepunch_timeout, Duration::from_secs(8));
	assert_eq!(config.relay_timeout, Duration::from_secs(10));
	assert_eq!(config.holepunch_timeout, Duration::from_secs(3));
	assert_eq!(config.relay_timeout, Duration::from_secs(5));

Prompt To Fix With AI

This is a comment left during a code review.
Path: src/connection_strategy.rs
Line: 489-490

Comment:
**Test-vs-implementation mismatch: CI will fail**

The `Default` impl (line 183–184) sets `holepunch_timeout = 3s` and `relay_timeout = 5s`, but this test asserts `8s` and `10s` respectively. These values have never matched in this PR, so `cargo test` will fail.

Either the test needs to be updated to the values the `Default` impl actually produces, or the `Default` impl needs to be corrected to the intended values:

```suggestion
        assert_eq!(config.holepunch_timeout, Duration::from_secs(3));
        assert_eq!(config.relay_timeout, Duration::from_secs(5));
```

How can I resolve this? If you propose a fix, please make it concise.

[greptile-apps]

Docstring references a stale 8s timeout

The comment says "the worst-case wait for K preferred coordinators is roughly (K-1) * 1.5s + 8s", but the holepunch_timeout default in StrategyConfig is now 3s (set in this PR, connection_strategy.rs line 183). The 8s figure is stale — either the default was intended to stay at 8s (in which case Default needs fixing) or the docstring should be updated to reflect 3s.

Prompt To Fix With AI

This is a comment left during a code review.
Path: src/p2p_endpoint.rs
Line: 93-104

Comment:
**Docstring references a stale `8s` timeout**

The comment says "the worst-case wait for K preferred coordinators is roughly `(K-1) * 1.5s + 8s`", but the `holepunch_timeout` default in `StrategyConfig` is now `3s` (set in this PR, `connection_strategy.rs` line 183). The `8s` figure is stale — either the default was intended to stay at 8s (in which case `Default` needs fixing) or the docstring should be updated to reflect `3s`.

How can I resolve this? If you propose a fix, please make it concise.

[greptile-apps]

Per-connection coordination rate limit raised 60×

max_coordination_per_window went from 5 → 300 PUNCH_ME_NOW requests per 60-second window per connection. While the new RelaySlotTable provides the actual node-wide back-pressure at 32 concurrent sessions (which is the right control), this effectively neuters the per-connection DoS guard: a single misbehaving peer can now issue 300 relay-probe bursts per minute before the per-connection rate limiter fires. Consider whether the Tier-4 cap alone is sufficient or whether a more moderate per-connection limit (e.g. 60–120/min) is preferable to retain defence-in-depth.

Prompt To Fix With AI

This is a comment left during a code review.
Path: src/connection/nat_traversal.rs
Line: 484

Comment:
**Per-connection coordination rate limit raised 60×**

`max_coordination_per_window` went from 5 → 300 PUNCH_ME_NOW requests per 60-second window *per connection*. While the new `RelaySlotTable` provides the actual node-wide back-pressure at 32 concurrent sessions (which is the right control), this effectively neuters the per-connection DoS guard: a single misbehaving peer can now issue 300 relay-probe bursts per minute before the per-connection rate limiter fires. Consider whether the Tier-4 cap alone is sufficient or whether a more moderate per-connection limit (e.g. 60–120/min) is preferable to retain defence-in-depth.

How can I resolve this? If you propose a fix, please make it concise.

[greptile-apps]

Stale NACKs may prematurely abort the next coordinator rotation

When try_hole_punch is cancelled (because the outer timeout(attempt_timeout, …) fires), any NACK that arrived just before the cancellation stays unconsumed in self.inner.nack_set. On the next call to try_hole_punch (with a different coordinator), nack_notify may immediately fire and consume_nack will return true — returning Err(...) even though the new coordinator hasn't sent a NACK. Consider clearing the NACK entry for the target when rotating coordinators, or scoping NACKs by (coordinator_addr, target_peer_id) so a stale NACK from coordinator A doesn't abort coordinator B.

Prompt To Fix With AI

This is a comment left during a code review.
Path: src/p2p_endpoint.rs
Line: 2263-2275

Comment:
**Stale NACKs may prematurely abort the next coordinator rotation**

When `try_hole_punch` is cancelled (because the outer `timeout(attempt_timeout, …)` fires), any NACK that arrived just before the cancellation stays unconsumed in `self.inner.nack_set`. On the *next* call to `try_hole_punch` (with a different coordinator), `nack_notify` may immediately fire and `consume_nack` will return `true` — returning `Err(...)` even though the *new* coordinator hasn't sent a NACK. Consider clearing the NACK entry for the target when rotating coordinators, or scoping NACKs by `(coordinator_addr, target_peer_id)` so a stale NACK from coordinator A doesn't abort coordinator B.

How can I resolve this? If you propose a fix, please make it concise.

[github-actions]

Benchmark Results

Performance Comparison

Benchmark	Baseline	Current	Change	Status

Summary

Configuration

• Regression threshold: >10% slower
• Improvement threshold: >10% faster
• Measurements: Mean execution time