ctf-ad-mirror-tool-rust/findings.md

# Findings and decisions

## Legacy behavior (source verified)
- Source: `../ad_scripts/mirror_tool`, commit `3011813` (2026-05-16); Downloads copy identical for 12 tracked files.
- Flask panel :6700, one subprocess per proxied port, threads per connection/replica.
- Primary returns responses; replica responses are never drained, so mirroring can stall.
- Replica queue drops oldest chunks on overflow (corrupts TCP application stream).
- Primary socket connect timeout remains a 3s read/write timeout.
- Shared stop flag breaks TCP half-close; peer direction can stop prematurely.
- `_pick_candidate` is undefined and its apparent body sits after an unconditional return.
- UI stops/restarts forwarders for primary/replica edits despite live-retarget backend support.
- Counters estimate speed from total bytes / time since last update, not interval deltas.
- Global mutable process state, no route-state restart recovery, unacknowledged stdin controls, startup success before bind.
- Canonical ForcAD `pomo-mondreganto/ForcAD`, inspected SHA `6ce3407be569b7f69f879501c5e2ca79231c1ff9`. Engine.IO 4 / Socket.IO namespace `/game_events`.
- Crucial legacy bug: `init_scoreboard` envelope contains `{data:{teams,tasks,state}}`; `update_scoreboard` contains `{data:{round,round_start,team_tasks,...}}` (state only). Keep cached metadata and merge updates. Sources: backend/services/events/app.py, backend/lib/storage/game.py, front/src/store/index.js.
- Use persistent Engine.IO polling (the upstream explicitly supports it), ping/pong, namespace ack, bounded HTTP bodies, bounded reconnect backoff and freshness based on received scoreboard data. No per-cycle Socket.IO reconnect.
- adplatf uses GET `/state`; map UP/CORRUPT/MUMBLE/DOWN to 101/102/103/104.

## Architecture direction
- Tokio tasks, bounded buffers, shared immutable route snapshots; no process/thread per connection.
- Direct paths reuse read buffers; mirrored paths share `Bytes` chunks across bounded channels. Always drain replica replies.
- Explicit strict/isolate replica policy; no silent chunk dropping. Strict backpressure trades throughput for bounded reliable delivery.
- Health and fresh scoreboard inform deterministic candidate selection with hysteresis/cooldown; no switch solely from stale/missing evidence.
- Axum control plane, embedded static UI, single authenticated SSE stream instead of four polling loops.
- No kernel routing work: user explicitly chose internal upstream routing.

## Final restoration and review
- Original base CSS retained (24037 characters modulo trailing whitespace); matching Bootstrap5.1.3/Font Awesome6.0.0 bundled locally. Main panel keeps original columns/rows/controls and four counters.
- Top status strip represents own-team main_team_ip independently of primary. Direct custom IP resolves its target atomically through standard service PUT.
- R1-R3 corrected with negative-control regressions; R4 redesigned journal removed; R5 old primary retained as replica. Absolute heartbeat and recoverable accept supervision also implemented.
- Final review discovered R6: cancellation of an HTTP request can cancel the controller future between disk/runtime/publication steps. Fix transaction ownership rather than merely trying to keep HTTP sockets alive.
- Browser Use fill does not trigger a native dirty-field change on blur in this environment; direct-IP behavior was verified with keyboard typing and Tab instead. Browser-wide viewport override was ineffective; tab-scoped CDP metrics produced actual390x844 and was cleared after verification.

- R6 resolved by one owned admitted transaction; cancelled waiters allocate no worker. Five cancellation regressions plus independent actual HTTP red/green prove cleanup/publication/rollback convergence. Final review approved, no remaining Critical/Important.