# Async TCP engine implementation evidence

Historical implementation-stage evidence. Final integrated results, accept supervision and quiesce follow-ups are recorded in `docs/verification.md` and `docs/backend-fixes-report.md`; the11-test count below predates those additions.

2026-10-23. Scope: `src/engine.rs`, `tests/forwarding.rs`, and the engine module export. All fixtures use local loopback sockets; no legacy credentials, game hosts, or payload logs were used.

## Implementation

- Tokio listener supervisors own a `JoinSet` of sessions. A semaphore shared by all services in one Engine bounds accepted active sessions, including upstream connection setup. Excess accepted sockets are immediately closed and counted as rejected, without creating a task.
- Routes are copied at accept time under a short synchronous lock. Target-only changes preserve the listener and affect subsequent sessions. There is no primary retry/replay after partial delivery.
- Bind errors propagate before replacing a working listener. Listener stop is acknowledged after the socket is dropped, making disable/re-enable deterministic. Disable stops accepting but allows established sessions to continue. Remove waits up to `drain_timeout_ms`, cancels remaining sessions, joins all session and replica tasks, and only then removes metrics. Whole-engine shutdown uses one drain deadline shared across services and retains snapshots with `running=false`, `active=0`.
- Both TCP directions run concurrently until their respective EOFs, propagating write half-close without terminating the opposite direction. Only connection establishment has a timeout; idle primary streams have no I/O timeout. TCP_NODELAY is set on client and upstream sockets.
- Each replica has a bounded chunk channel and concurrently drained response stream. `Bytes` references share one request chunk across sinks. Isolate uses nonblocking queue admission; saturation disconnects that replica for that session instead of skipping a chunk and continuing. Replica connection failure does not delay primary setup/traffic. Strict connects all configured replicas before reading client bytes, awaits queue capacity, and terminates the session on replica error.
- Atomic counters use relaxed operations. Byte counters increment after each successful socket write, including partial chunks preceding an error. Active accounting and semaphore release occur after child workers have been aborted and joined on forced cancellation. `accepted` includes promptly rejected sockets; `completed` counts natural successful session completion, not forced cancellation. Replica failures can accompany a successful primary session in isolate mode.
- Shared error/counter state survives a listener-address change while old sessions drain. No lock spans network I/O.

## Fresh verification

Native macOS command:

```text
cargo test --test forwarding
running 11 tests
... all 11 tests ok ...
test result: ok. 11 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 3.20s
```

The tests cover:

1. Exact 2 MB binary delivery in both directions and byte counters.
2. A reply generated only after request EOF, following 3.2 seconds idle.
3. Live retargeting with old sessions retained on the original target, plus disable/re-enable.
4. Bind conflict propagation with the prior listener still usable.
5. A shared connection limit across two distinct service listeners, prompt rejection, and bounded active shutdown.
6. Continued delivery after disabling a listener, followed by bounded remove and socket closure.
7. Exact 1 MB strict replica request delivery while draining a 2 MB replica reply concurrently.
8. Unavailable isolate replica preserving primary delivery and recording a single replica error/disconnect.
9. Unavailable strict replica ending the session before any primary payload bytes.
10. A stalled isolate replica explicitly disconnected during a 16 MB successful primary exchange.
11. A stalled strict replica applying backpressure during a 32 MB upload, with shutdown joining its workers.

```text
rustfmt --edition 2024 --check src/engine.rs tests/forwarding.rs
exit 0, no output
```

An earlier `cargo check --lib` passed. `cargo clippy --lib -- -D warnings` was attempted and reported `clippy::derivable_impls` in root-owned `src/config.rs`; that issue was reported to the root agent. The last integration-test run also emitted an unused `serde_json::json` import warning in concurrently developed `src/scoreboard.rs`, reported to the root agent. No clean whole-project clippy claim is made here.

The original replica fixture used 127.0.0.2, which macOS did not expose as a configured loopback address (`AddrNotAvailable`). The fixture now uses ::1 for replicas and 127.0.0.1 for the primary, preserving the common configured service port without altering host interfaces. Orb reports x86_64 with rustc/cargo 1.93.1; integrated Linux staging and test execution remain root-agent work.

## Limits and operator semantics

This is live TCP request mirroring, not database replication. It does not guarantee zero latency or loss during network/peer failures. Successful writes measure bytes accepted by the local socket, not application-level commit or remote durable receipt. A replica may have received only a prefix when it disconnects. No reconnect or replay is attempted within that session.

Strict mode can block indefinitely on a slow peer during normal operation and sacrifices primary throughput/availability to required replicas. Isolate mode can explicitly disconnect even a healthy replica when the configured queue cannot absorb a traffic burst. After both primary directions finish, isolated replica tail drain is bounded by `drain_timeout_ms`; unfinished tails are explicitly disconnected and counted. Primary socket write-half closure is propagated before that tail wait.

Payload memory is bounded by the configured session, replica, queue and buffer sizes, plus OS socket buffers; the maximum can still be large if the operator chooses large resource limits. Upsert expects validated topology/network settings from the configuration layer. Call and await `shutdown()` before disposing of the Engine; dropping a clone is not a shutdown operation. This report contains functional evidence, not a throughput/latency benchmark.