fix: update doc arch

ENGINE.md

@@ -18,11 +18,13 @@ Our ET server sits at home, reachable from the Internet only through the front s
 
 `etrelay` runs on the front and owns the public UDP port 27960. It does two things on **the same socket**:
 
-- **Proxy**: forwards every client (players, server browsers, masters) to the ET server, like nginx `stream`.
+- **Proxy**: forwards every client (players, server browsers, masters) to the ET server, one upstream socket per client address. Packets a client has no business sending (`rcon`...) are dropped on the way.
 - **Heartbeat**: sends the heartbeats itself, so the master challenges the **front** address. That challenge is just another client packet: it goes through the proxy, the ET server answers it, the answer leaves from the front address, and the master lists the front.
 
 The ET server's own heartbeats are disabled (`sv_master1..5 ""`).
 
+The ET server is its own WireGuard peer of the front, with no proxy in between (the DNAT rule and the home nginx `stream` are gone). Each client reaches it from its own port of the front's tunnel address: the **control API** maps that port back to the real address, and bans addresses (see [Control API and bans](#control-api-and-bans)).
+
 Masters are independent: a server is only listed on the masters it heartbeats, and each client browses its own master (ET 2.60b: `etmaster.idsoftware.com`, ET: Legacy: `etmaster.net`). The relay heartbeats both by default; diagrams show `etmaster.net`, the id Software master works the same way.
 
 ![After: everything goes through the front](diagrams/architecture.png)
@@ -51,17 +53,39 @@ The last two lines are a server tracker that got the address from the master.
 
 ![Player: one session per client address](diagrams/player-session.png)
 
-The ET server sees every client as the nginx `stream` host (one source IP, one port per session): IP bans don't work, same as before the relay.
+The ET server sees every client as `<front-wg>:<port>`: one source IP (the front's tunnel address), one port per session, the port of the session's upstream socket. Its own IP bans can't tell players apart: bans are etrelay's (below). A player coming back after the session expired gets a new port.
+
+## Control API and bans
+
+With `--control <addr>`, an HTTP API listens on the front's tunnel address (unreachable from the internet), bearer token on top. It serves an admin tool on the tunnel side:
+
+- `GET /sessions`: the open sessions, real client address and port the ET server sees, so the tool can put a real address on each player.
+- `GET /bans`, `PUT /bans/{ip}`, `DELETE /bans/{ip}`: bans by source IP, with a reason and an optional duration.
+
+![Control API: real address and ban of a player](diagrams/ban.png)
+
+A ban cuts the address's sessions at once, and the relay loop drops its packets before any session lookup: the ET server gets nothing more from the player and times them out, and they can't come back. Bans are saved to `<state-dir>/bans.json` on each change (written next to it, then renamed), expired ones forgotten.
+
+## Filter
+
+Only what clients and masters send a server gets through, checked on the first word as the ET server tokenizes it:
+
+- in-game packets (no `\xff\xff\xff\xff` prefix): always;
+- `getstatus`, `getinfo`, `getchallenge`, `connect`, PunkBuster's `PB_...`: allowed;
+- anything else, `rcon` above all, dropped: it travels in clear, and a stream of it blocks the local admin's own rcon (2.60b runs one rcon per 500 ms, whoever sends it).
+
+`getstatus` and `getinfo` are limited per source IP (token bucket: a burst of 5, then 1/s): their answers are much bigger than the query, and from a spoofed source they would make the server a DDoS reflector. The limiter remembers at most 65 536 IPs, idle ones forgotten after 60 s.
 
 ## Internals
 
-Single-threaded tokio runtime, three kinds of tasks:
+Single-threaded tokio runtime, four kinds of tasks. The sessions and the bans are shared by the relay loop and the control API behind a mutex, never held across an `await`:
 
 ![Tasks and data flow](diagrams/tasks.png)
 
-- **relay loop**: reads the public socket, finds the client's session and pushes the packet into its queue. No session, or an expired one: opens a new one (and purges expired entries). A full queue drops the packet, like any congested UDP hop.
-- **session task**: owns one ephemeral socket connected to the ET server. Forwards the queue to the ET server and the ET server answers back to the client **through the public socket** (so they come from `:27960`). Ends after `SESSION_TIMEOUT` without a packet either way.
+- **relay loop**: reads the public socket, runs the filter and the ban check, finds the client's session and pushes the packet into its queue. No session, or an expired one: opens a new one (and purges expired entries), unless `MAX_SESSIONS` are open. A full queue drops the packet, like any congested UDP hop.
+- **session task**: owns one ephemeral socket connected to the ET server. Forwards the queue to the ET server and the ET server answers back to the client **through the public socket** (so they come from `:27960`). Ends after `SESSION_TIMEOUT` without a packet either way, or at once when a ban drops its queue's sender.
 - **heartbeat task**: probes the ET server with `getinfo` on its own socket (up to 3 attempts, 3 s each), then heartbeats the masters through the public socket. Masters are resolved on every heartbeat (DNS may change).
+- **control API task** (with `--control`): axum on the tunnel address. Binding is retried every 10 s: the tunnel may come up after etrelay.
 
 ### Heartbeat states
 
@@ -78,6 +102,10 @@ The master drops a server that stops heartbeating after a while anyway; the flat
 | `SESSION_TIMEOUT` | 2 min | Idle clients (server browsers) freed quickly; players send packets constantly |
 | `SESSION_QUEUE` | 64 packets | Burst absorption per client before dropping |
 | `MAX_PACKET` | 65 535 B | Any UDP datagram: `statusResponse` easily exceeds nginx's old 512 B buffer |
+| `MAX_SESSIONS` | 2048 | One socket each: spoofed sources must not use up the file descriptors (`LimitNOFILE=4096` in the unit) |
+| `QUERY_BURST`, `QUERY_RATE` | 5, then 1/s | `getstatus`/`getinfo` per source IP: a browser refresh or a master's check passes, a reflection attack doesn't |
+| `MAX_QUERY_SOURCES`, `QUERY_FORGET` | 65 536 IPs, 60 s | The limiter's memory stays bounded under a flood of spoofed sources |
+| `MIN_TOKEN` | 32 characters | Shortest control API token accepted |
 
 ### Protocol cheat sheet
 
@@ -92,5 +120,7 @@ Connectionless packets start with `\xff\xff\xff\xff`, then a command:
 | `infoResponse` | server → master/browser | Hostname, map, player count, challenge |
 | `getstatus` / `statusResponse` | browser ↔ server | Full cvars + player list |
 | `getchallenge` / `challengeResponse` / `connect` | player ↔ server | Connection handshake |
+| `PB_...` | PunkBuster ↔ server | PunkBuster's own packets |
+| `rcon <password> <command>` | admin → server | Remote console: dropped by the relay |
 
-Anything else (no prefix) is in-game traffic: forwarded as-is, only counted in `--debug` logs.
+Packets with no prefix are in-game traffic: forwarded as-is, only counted in `--debug` logs.