Integrate the relay server into std Endpoint #71

Parent

Part of #61.

Canonical specification

Implement PR 3 of docs/plans/circuit-relay-v2-relay-server.md. That document and the resolved decisions in #62–#68 are authoritative. Do not reopen the frozen public API, protocol roles, address trust model, admission/lifecycle policy, or compatibility decisions.

What to build

Make the relay server an independently selectable std Endpoint capability with the intended three-line happy path, complete public controls, deterministic driver integration, NAT coexistence, typed observability, and real TCP/QUIC end-to-end coverage.

All sockets, clocks, blocking waits, transport event routing, Endpoint composition, and Identify contribution aggregation belong in this integration. Do not broaden the low-level public surface into the application crate.

Feature and public API

• Add a std-only relay-server feature depending on the relay-server service and independent of nat.
• Implement the frozen builder methods: default enablement, validated custom configuration, and order-independent announce-address configuration.
• Announce-address methods never enable the service. If addresses remain configured at bind without relay-server enablement, bind fails actionably before socket allocation where possible.
• Validate configuration before binding and again at the low-level agent boundary. Validate structural addresses immediately and repeat identity-dependent peer-ID matching at bind.
• Implement accepting control, atomic runtime announce-address replacement/clearing, event draining, and focused blocking wait to a caller deadline.
• Runtime controls on an absent service return NotConfigured. Invalid runtime addresses retain the complete nested indexed address error as their source and preserve the previous override.
• Re-export all types needed to name the Endpoint API: config/rate limit, events and reasons, byte counts/directions/legs, exact relay Status, configuration/address/control/runtime errors and error kinds, and ConnectionCloseCause.
• Do not re-export action tokens, stream keys, pending-control records, or driver plumbing from the application crate.

Composition and routing

• Relay-server enablement statically registers inbound and Identify-advertised HOP plus outbound STOP.
• NAT registers outbound-only HOP and trusted inbound/advertised STOP. NAT-only endpoints can reserve without advertising or accepting HOP.
• Relay-server-only endpoints own and reset unsolicited inbound STOP.
• HOP over a circuit connection negotiates and returns PERMISSION_DENIED.
• Route transport events with exact direct-versus-circuit classification and exact connection identity/address data.
• For each sampled time, call the relay agent's tick before delivering an event. After each claimed input, drain actions and echo synchronous results to quiescence before delivering another transport event.
• Drive relay-server before NAT and pubsub while preserving existing behavior of generic application protocols.
• Every failed open/send/close/reset action produces the corresponding runtime diagnostic event; successful stale opens are cleaned up.

Identify and reservation addresses

• Replace std Endpoint's wholesale external-address replacement with source-keyed NAT and relay-server contributions.
• Rebuild one stable first-wins contribution union in NAT-then-relay order without letting either source clobber the other.
• Preserve bound transport addresses as the Swarm runtime's first Identify source; append the contribution union with first-wins deduplication.
• Keep the portable Endpoint's caller-owned external-address setter unchanged.
• Feed only AutoNAT-confirmed public direct addresses into relay-server selection; never promote raw Identify-observed addresses.
• Relay-server selection uses explicit override, then confirmed NAT addresses, then concrete listeners. Its selected normalized addresses contribute to future Identify responses.
• Recompute address sources after relevant changes without terminating live reservations or circuits. Identify Push and forced re-identification remain out of scope.

Driver progress, events, and deadlines

• Integrate relay-server actions, events, counts, deadlines, and wakes with DriverProgress and Endpoint's pending-event capacity.
• take_relay_server_events drains only relay events and returns promptly.
• next_relay_server_event drives the whole Endpoint until a relay event or caller deadline, preserving unrelated queued events and existing wait behavior.
• Relay control-stream and lifecycle deadlines participate in the driver's next wake without busy waiting.
• Runtime pause changes only new admission and preserves static HOP advertisement, reservations, and active circuits; resume reuses existing state.

Integration tests

• Compile and test relay-server, nat, and nat,relay-server feature combinations with both TCP and QUIC matrix variants.
• Two real minip2p clients can reserve, advertise, CONNECT through the relay, and exchange bidirectional payload over TCP and QUIC paths.
• Tests exercise reservation/circuit capacity and rate limits, directional byte and duration limits, separate control caps/timeouts, pause/resume, runtime address replacement/clearing, and connection supersession.
• Tests observe the exact typed acceptance, denial, open, close, byte-total, close-cause, and runtime-error events at their specified commit points.
• NAT-only Identify omits HOP while outbound reservation succeeds; relay-only Identify includes HOP; combined mode routes trusted STOP correctly.
• Source-keyed tests prove NAT and relay-server address contributions cannot overwrite each other, duplicates remain stable first-wins, and changes affect future Identify exchanges only.
• Wildcard listeners without a usable explicit/confirmed/concrete address refuse new reservations while preserving existing state.
• Invalid builder/runtime address shapes and conflicting peer IDs return the exact actionable error without partial mutation.
• Pending event capacity, counts, focused waits, wakeups, deadline-first ordering, and all driver action failure paths have focused coverage.

Documentation and compatibility

• Add feature documentation and application-facing rustdoc for the three-line default path, custom configuration, announce addresses, pause/resume, event consumption, and failure semantics.
• Document the exact protocol role matrix for relay-only, NAT-only, and combined endpoints.
• Document that the Swarm remains single-connection-per-peer and that exact connection targeting is a load-bearing assumption.
• Preserve every deliberate compatibility choice from Audit the relay-server compatibility envelope #62–Approve the implementation-ready relay-server specification #68, including static HOP advertisement, future-only Identify updates, trusted address precedence, circuit-HOP denial, and typed exactly-once lifecycle observability.
• Keep reservation vouchers, relay discovery/autorelay, ACLs, metrics, proxy-aware IP limiting, portable/smoltcp Endpoint driving, fixture replacement, and Swarm-wide pre-negotiation caps out of scope.

Completion checks

• Every new public API has rustdoc with actionable validation, control, wait, and asynchronous failure semantics.
• just fmt passes.
• just test passes across the required Endpoint feature matrix.
• just clippy passes with warnings denied across relay-server, NAT, combined, TCP, and QUIC variants.
• just check-nostd passes; enabling this std-only feature does not regress portable core crates.
• Real-client integration tests pass for both transports and all required composition variants.
• No compatibility shim is introduced for pre-1.0 internal APIs, and no frozen behavior is left to implementation judgment.

Blocked by

• Add Swarm foundations and the sans-I/O relay-server service #70