Ship relay hosting, interoperability, documentation, and CI #72

Parent

Part of #61.

Canonical specification

Implement PR 4 of docs/plans/circuit-relay-v2-relay-server.md. That document and the resolved decisions in #62–#68 are authoritative. This issue proves and documents the approved design; it must not reopen product decisions or silently claim parity for deliberate deviations.

What to build

Finish the relay-server series as something operators can host, users can discover and understand, CI can continuously validate, and maintainers can verify against the pinned rust-libp2p implementation.

The default example must remain the small application happy path while exposing practical production controls when requested.

Hosting example

• Add a relay-server hosting example with QUIC and TCP binds and the default three-line builder/bind path prominently represented.
• Support an optional persisted identity key, explicit announce addresses, an accepting pause/resume toggle, and practical flags for the frozen resource/rate/control limits.
• Render typed lifecycle events and operational errors readably, including peer identities, statuses, directional byte totals, close causes, and actionable diagnostics.
• Validate bad configuration and announce addresses before binding where possible and exit with actionable errors.
• Keep optional operational controls out of the minimal default path and do not introduce policy absent from the canonical specification.

Documentation

• Update the NAT traversal guide, feature matrix, top-level README, affected crate READMEs, example documentation, and public rustdoc so users no longer need to bring an external relay.
• Document the application API, feature independence/composition, static HOP advertisement, address selection/trust, future-only Identify updates, accepting pause, event handling, and hosting guidance.
• The relay-server README contains one explicit compatibility table covering: one-reservation-per-peer cardinality; exact-connection renewal; rate-first and exact-capacity admission; both-end circuit limits; fixed optional token buckets; static HOP and outbound-only NAT HOP; pause semantics; address precedence/filtering/deduplication/truncation; future-only Identify; circuit-HOP denial; 8 KiB frame and malformed-input handling; per-direction accepted bytes including pipelined payload; full crossing-chunk overshoot; duration start and zero/unlimited behavior; exactly-once lifecycles and directional totals; separate post-negotiation HOP/STOP caps and end-to-end timing; action-based forwarding/backpressure; optional wall time; and voucher: None.
• Classify each behavior accurately as Circuit Relay v2 parity, rust-libp2p parity, a deliberate minip2p deviation, or a minip2p extension, using the pinned audit in Audit the relay-server compatibility envelope #62.
• Explicitly document the lack of reservation vouchers, relay discovery/autorelay, ACLs, metrics, proxy-aware IP limiting, portable/smoltcp Endpoint driver, Swarm-wide pre-negotiation stream caps, and replacement of existing test relay fixtures.
• Document the single-connection-per-peer assumption and why exact stored connection IDs are sufficient for STOP targeting.
• Every public item has rustdoc with actionable configuration, control, transport-failure, timeout, and lifecycle semantics.

CI and packaging

• Add test/check/clippy feature-matrix coverage for relay-server, nat, and nat,relay-server, including the relevant TCP and QUIC variants.
• Add or extend no_std checks so all portable wire, Swarm, and relay-server crates remain covered while the Endpoint feature stays std-only.
• Add documentation coverage and release-package checks for the new crate, feature, and example.
• Keep the foreign interoperability tool outside the Cargo workspace and keep its network-dependent run ignored in ordinary unit tests.
• CI and release checks prove all published packages contain the required README/rustdoc and feature metadata.

Pinned interoperability

• Add just interop-relay-rust under the existing interoperability harness, pinned to rust-libp2p libp2p-relay 0.22 commit 170c3c81ddd80e7c58b0500563e00a09139e8545 and Circuit Relay v2 commit 6b6203ee6f62938ce67efdb33498173f475851c0.
• The harness runs a minip2p relay server with rust-libp2p reserving and dialing clients.
• Verify reservation succeeds, Identify advertises HOP as specified, CONNECT/HOP and STOP negotiate successfully, and bytes flow in both directions.
• Exercise enough configuration to prove the advertised wire limits and voucher: None remain interoperable without relying on behaviors documented as deliberate deviations.
• Record the pinned foreign revision, command, environment, and successful result so the outcome is reproducible.

Completion checks

• just fmt passes.
• just test passes across the completed feature matrix.
• just clippy passes with warnings denied across the completed feature matrix and fuzz package.
• just check-nostd passes.
• Endpoint real-client integration tests from Integrate the relay server into std Endpoint #71 pass.
• just interop-relay-rust passes and the pinned result is recorded.
• Documentation and release-package checks pass.
• The compatibility table covers every resolved choice from Audit the relay-server compatibility envelope #62–Approve the implementation-ready relay-server specification #68 and every deliberate upstream deviation in the canonical specification.
• No behavior in the canonical specification is left to inference, and all stated non-goals remain explicit rather than appearing as parity.

Blocked by

• Integrate the relay server into std Endpoint #71