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 use Tokio bidirectional copy; 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.