feat(api): add pooled RCON client and game event bus

[and3rn3t]

Description

Phase 0 of the new family server roadmap: two
pieces of plumbing that most of the planned gameplay features depend on, plus
the roadmap itself.

api/rcon.py — an in-process RCON client

Every command previously shelled out to scripts/rcon-client.sh, which opened a
new TCP connection and re-authenticated for each one. That is roughly 50-100ms
of overhead per command and makes command batches impractical.

The script's Python fallback also had two defects:

• A single unframed sock.recv(4096), so responses longer than that were
  truncated or split across reads.
• Any reply of four or more bytes was treated as a successful login, rather than
  checking for the -1 request id the protocol uses to signal auth failure.

The new client holds one authenticated connection open behind a lock,
reassembles the multi-packet responses Minecraft sends for output over 4096
bytes, reconnects transparently when the container restarts underneath it, and
rejects commands long enough that the server would silently truncate them.

api/server.py reaches it through a new run_rcon_command() helper that falls
back to the shell script when RCON is unconfigured or unreachable, since that
script can also reach rcon-cli inside the container when the port is not
published to the host. scripts/rcon-client.sh is unchanged for CLI use.

api/events.py — a game event bus

See docs/EVENT_BUS.md.

The server log is the only real-time signal Minecraft produces. It was followed
purely to stream raw text to the browser, so anything reactive had to re-parse
raw lines for itself, and nothing was captured at all unless someone had the
dashboard open.

Lines are now parsed into typed events, appended to
data/events/YYYY-MM-DD.jsonl, and dispatched to registered handlers. Writes
are batched and files older than 30 days are pruned, to limit SD-card wear on
the Pi. A handler that raises is logged and skipped rather than stopping the bus.

The follower now starts with the API rather than on the first browser
connection, and no longer stops when the last client disconnects. Events that
happened with the dashboard closed were previously lost. stop_log_reader()
brings it down deliberately.

Adds GET /api/events and GET /api/events/types (both logs.view), a
game_event WebSocket message alongside the existing raw logs stream,
getEvents() and getEventTypes() in web/src/services/api.js, and the
matching OpenAPI paths and schema.

Security fix included

The WebSocket execute_command handler reached RCON without sanitising its
input, bypassing the command allowlist that POST /api/server/command
enforces. Anyone holding an API key could run arbitrary console commands through
it. It now runs the same validation and writes the same audit entries.

Notes for review

Two decisions worth a look:

1. connect and join are separate event types. A single player session
   logs two lines, one carrying the network address and one saying they joined.
   Mapping both to join double-counted every session, which a smoke test on a
   realistic log caught.
2. tests/api/test_log_streaming.py was updated, not worked around. It
   asserted that the follower stops when the last viewer disconnects, which is
   exactly the behaviour this PR removes on purpose. Those tests now cover the
   new contract and the stop flag that replaced it.

Death detection matches the opening phrases of Minecraft's death.attack.*
strings, since vanilla death messages have no marker of their own. Chat is
matched first so a player typing a fake death message cannot fake a death event.
Anything the phrase list does not cover is simply not treated as a death, which
is the safe direction to fail.

Type of Change

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Refactor (code change that neither fixes a bug nor adds a feature)
• Documentation (changes to docs only)
• Other (please describe):

Checklist

• I have performed a self-review of my code
• I have added tests that prove my fix or feature works
• I have updated documentation as needed
• Lint and tests pass locally
• I have not introduced any security vulnerabilities

Verification run locally:

Check	Result
make test-api	336 pass, up from 251
make test-web	144 pass
Coverage	50.7%, threshold 40%
make lint	passes
docker compose config	valid

The RCON tests run against a real socket server speaking the protocol, so
framing, authentication, multi-packet reassembly and reconnection are exercised
end to end rather than mocked.

Related Issues

🤖 Generated with Claude Code

[github-actions]

Dependency Review

✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.

Scanned Files

None

[Copilot]

Copilot review overview

🟡 Changes recommended

Critical command-retry and event-persistence issues, along with moderate correctness gaps, remain unresolved.

Get a fresh assessment by requesting another Copilot review.

Review effort: Lite
Findings: 4 · 1 · 1

Open (6)

• Retrying after lost responses can duplicate commands · New
• 502 fallback can duplicate side-effecting commands · New
• Follower replays backlog events on every restart · New
• Non-string commands crash before returning command_error · New
• Stopping the log reader cannot unblock a blocked pipe · New
• New event API methods lack service tests · New

What changed in this PR

Adds pooled RCON support and an always-on, typed Minecraft event bus with REST/WebSocket exposure, persistence, and frontend integration.

Changes:

• Adds framed pooled RCON execution, reconnection, fallback, and validation.
• Parses, persists, and dispatches game events.
• Updates APIs, tests, OpenAPI, documentation, roadmap, and changelog.

File	Reviewed changes and final review notes
web/​src/​services/​api.js	Adds event API helpers. Nit: add coverage for parameters and cached event types.
tests/​api/​test_rcon.py	Adds RCON protocol, authentication, framing, and reconnection tests.
tests/​api/​test_log_streaming.py	Updates tests for the always-on follower contract.
tests/​api/​test_events.py	Adds event bus and endpoint tests. Moderate: the documented 500-item limit is not actually asserted.
docs/​INDEX.md	Updates documentation navigation.
docs/​FAMILY_SERVER_ROADMAP.md	Adds the family server roadmap. Nit: listed event names differ from shipped names.
docs/​EVENT_BUS.md	Documents the event bus and event delivery.
CHANGELOG.md	Adds release notes for the new infrastructure.
api/​server.py	Integrates RCON, event endpoints, log capture, and WebSocket validation. Critical: replayed tails duplicate events, 502 fallback can repeat sent commands, and non-string commands can escape error handling. Moderate: stopping may not terminate a blocked follower.
api/​rcon.py	Adds the pooled RCON client. Critical: post-send failures can retry side-effecting commands. Moderate: cached credentials do not reflect password rotation.
api/​openapi.yaml	Adds event API paths and schemas.
api/​events.py	Adds parsing, persistence, dispatch, batching, and retention. Moderate: quiet periods may leave events unflushed, and concurrent flushes can write out of order.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[and3rn3t]

All six review findings are fixed in e9a9a33, along with the four CodeQL notes and the three issues raised in the summary table. Each was verified against the code before acting; all six were real, and two of them had a second instance the review had not reached.

Beyond the inline threads:

• api/events.py flush correctness. The buffer swap was locked but the file append was not, so two concurrent flushes could interleave their lines. A dedicated write lock now serialises the append, without holding up publishes for the duration of the I/O. Separately, the size and age thresholds were only evaluated on publish, so the last few events of a quiet period sat buffered indefinitely and would be lost if the process stopped; a daemon timer now flushes them.
• Cached RCON credentials. The config is re-read when its mtime changes, so rotating the password with scripts/rcon-setup.sh no longer needs an API restart.
• The 500-item cap on GET /api/events was documented but not asserted. The test now stores 600 events and checks that 500 come back.
• The roadmap listed server_start/server_stop and omitted connect. It now names the types that shipped.
• CodeQL: explained three empty except clauses and removed the duplicate module import in tests/api/test_events.py.

Two things I want to flag rather than leave implied:

1. The backlog replay was the worst of these. It reproduced exactly the flaw this PR set out to remove from scripts/player-stats-tracker.sh, which re-reads the whole log and inflates its counts. I went with --tail 0 rather than a durable cursor, because deduplicating identical lines is unreliable: two identical chat messages in the same second are legitimately distinct events. The cost is that events occurring while the API is down are not captured.
2. The retry fix has a caveat I would rather state than paper over. A partial write cannot be distinguished from a failed one in principle. The retry relies on a command packet being well under one TCP segment, so a stale socket fails with nothing delivered. That is the case the retry exists for, and it is noted in the docstring.

Check	Before	After
API tests	336	368
Web tests	144	150
Coverage	50.7%	52.4%

make lint passes, docker compose config validates, and Black is clean on the new files.

🤖 Generated with Claude Code