daddy/modbison
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add world content persistence backend (Postgres chunks, internal API, game-server token auth)

Browse Source 
Implements docs/architecture/world_persistence_impl.md §9's backend task:
chunk/room/revision Postgres schema (migration 0005), a Python port of the
world.md §3.6 binary chunk codec with golden-file tests, a WorldStore
service (world.md §5.1 minus flush_dirty/rebuild_index), the public
world-content router (rooms/chunks CRUD, optimistic concurrency, batch
writes) and the internal read-only API for dedicated servers, and
game_servers.py changes: a per-spawn bearer token, --api-url/--server-token
args, and a real "ready"-field wait replacing _await_port, which bound the
UDP port before content existed and failed open (no error) past its
deadline.

create_world now auto-creates the "main" room.

Deviations/findings, not silently decided:
- chunk_codec.py implements real IEEE-754 float32 packing rather than
  mirroring a confirmed bug in scripts/chunk_data_decoder.gd's
  _read_float32/_write_float32, which do a lossy int<->float cast instead
  of a bit reinterpretation (verified against Godot 4.6.2 headless) and
  will corrupt any non-integer position/rotation/scale/bounds value. Not
  fixed here (client-side, out of scope); flagged for the client task.
- world_persistence_impl.md references a world's monotonic
  content_revision (§6/§7.2/§8.1) but never defines where it's stored.
  Resolved as MAX(id) over the append-only world_chunk_revisions table,
  scoped to world_id, rather than adding an undocumented column.
- No existing Godot-side golden fixture/test vectors were found to reuse,
  so tests/fixtures/chunks/*.bin are authored fresh from this
  implementation (see generate_fixtures.py).

Verification: 132/132 backend pytest tests pass against a real ephemeral
Postgres (both reusing an already-running instance and cold via
conftest.py's own docker-compose bootstrap), including migration
upgrade/downgrade/upgrade, codec round-trip + validation-error tests, and
full HTTP round trips for PUT/GET/batch/delete/revisions/rollback and the
internal API's token auth.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Y2FESCaMXeJpC9gSctiEeD
This commit is contained in:
daddy
2026-09-14 19:48:01 +00:00
parent c54ea6f055
commit b6c6ddfbc4
21 changed files with 3056 additions and 19 deletions
Download Patch File Download Diff File Expand all files Collapse all files
backend/app/services/game_servers.py
+71 -14
View File
@@ -13,15 +13,26 @@ project are on the host (see ``settings.GODOT_BIN`` / ``GAME_PROJECT_DIR``);
the backend spawns them as subprocesses.
Design notes / limits (PC3):
- All worlds currently load the same test level (per-world content is M2/M7).
``world_id`` still scopes a distinct server process + session.
- Port allocation is a linear scan of the configured range.
- No crash-restart: if a server process dies, the next join respawns it.
With world content now durable in Postgres (world_persistence_impl.md
D2), this is genuinely safe rather than merely tolerated: the sim
process holds no unsaved world content, so a reap/crash/kill can never
lose world data.
Per-spawn auth token (world_persistence_impl.md §7.3): each spawned server
gets a random ``secrets.token_urlsafe(32)`` on its command line, which it
uses as a Bearer token against ``/api/internal`` to pull its world's
content read-only before binding its ENet port. The token grants access to
exactly one world and dies with its process (the reaper's
``del self._servers[wid]`` invalidates it; see ``validate_token``).
"""
from __future__ import annotations
import asyncio
import hmac
import json
import secrets
import socket
import subprocess
import tempfile
@@ -38,6 +49,7 @@ class _WorldServer:
port: int
proc: subprocess.Popen
status_path: Path
token: str
started_at: float = field(default_factory=time.time)
last_join: float = field(default_factory=time.time)
@@ -50,6 +62,9 @@ class _WorldServer:
def player_count(self) -> int:
return int(self.status().get("players", 0))
def is_ready(self) -> bool:
return self.status().get("ready") is True
def alive(self) -> bool:
return self.proc.poll() is None
@@ -104,16 +119,35 @@ class GameServerSupervisor:
if srv is None:
srv = self._spawn(world_id)
self._servers[world_id] = srv
# Give the engine a moment to bind the ENet port before we
# hand the address to a client.
await self._await_port(srv.port)
try:
await self._await_ready(srv)
except TimeoutError:
# Real failure now, not a silent "hope it's fine" --
# see _await_ready's docstring. Don't leave a possibly
# half-started process registered.
srv.stop()
del self._servers[world_id]
raise RuntimeError(
f"dedicated server for world {world_id} did not become ready in time"
)
srv.last_join = time.time()
return {"host": settings.GAME_SERVER_HOST, "port": srv.port, "world_id": world_id}
def validate_token(self, world_id: str, token: str) -> bool:
"""`require_game_server` dependency support (world_persistence_impl.md
§7.3): true iff *token* is the live token for *world_id*'s server.
A dict lookup, as the doc specifies, plus a constant-time compare
since it's a bearer credential."""
srv = self._servers.get(str(world_id))
if srv is None or not srv.alive():
return False
return hmac.compare_digest(srv.token, token)
# ── internals ────────────────────────────────────────────────────────
def _spawn(self, world_id: str) -> _WorldServer:
port = self._free_port()
token = secrets.token_urlsafe(32)
status_path = self._runtime_dir / f"world_{world_id}_{port}.json"
status_path.unlink(missing_ok=True)
cmd = [
@@ -123,9 +157,13 @@ class GameServerSupervisor:
"--port", str(port),
"--world", str(world_id),
"--status-file", str(status_path),
"--api-url", settings.GAME_SERVER_INTERNAL_API_URL,
"--server-token", token,
]
proc = subprocess.Popen(cmd, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
return _WorldServer(world_id=world_id, port=port, proc=proc, status_path=status_path)
return _WorldServer(
world_id=world_id, port=port, proc=proc, status_path=status_path, token=token
)
def _free_port(self) -> int:
used = {s.port for s in self._servers.values()}
@@ -140,16 +178,35 @@ class GameServerSupervisor:
continue
raise RuntimeError("no free game-server port in the configured range")
async def _await_port(self, port: int, timeout: float = 8.0) -> None:
deadline = time.time() + timeout
async def _await_ready(self, srv: _WorldServer) -> None:
"""Wait for a ``"ready": true`` field in the status file
(world_persistence_impl.md §7.4).
This replaces the old ``_await_port``, which had two real bugs:
it treated a bound UDP port as "ready", but with content loading
the port binds *before* the server has fetched its world's rooms
and chunks (world_persistence_impl.md §7.2 step 4) -- so a client
could get handed an address for a server still mid-fetch. And it
*failed open*: past its 8s deadline it simply returned, with no
error, so ``ensure_server`` reported success for a server that may
never have started at all. This raises ``TimeoutError`` instead,
which ``ensure_server`` turns into a real 503 for the joining
client, and also bails out early (same exception) if the process
has already exited.
"""
deadline = time.time() + settings.GAME_SERVER_READY_TIMEOUT_SECONDS
while time.time() < deadline:
# ENet is UDP; a bind failure means something (our server) has it.
with socket.socket(socket.AF_INET, socket.SOCK_DGRAM) as s:
try:
s.bind(("0.0.0.0", port))
except OSError:
return
if srv.is_ready():
return
if not srv.alive():
raise TimeoutError(
f"server process for world {srv.world_id} exited before becoming ready"
)
await asyncio.sleep(0.25)
raise TimeoutError(
f"server for world {srv.world_id} did not report ready within "
f"{settings.GAME_SERVER_READY_TIMEOUT_SECONDS}s"
)
async def _reap_loop(self) -> None:
try: