Add world content persistence backend (Postgres chunks, internal API, game-server token auth)
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:
@@ -0,0 +1,670 @@
|
||||
"""Python port of the chunk binary/JSON codec, `docs/architecture/world.md` §3.
|
||||
|
||||
This is the server-side half of the "single shared format, two
|
||||
implementations" contract world.md §5.2 and
|
||||
`world_persistence_impl.md` §5.5/§9 call for. The Godot-side implementation
|
||||
is `scripts/chunk_data_decoder.gd`; this module must decode anything it
|
||||
produces and produce bytes it can decode.
|
||||
|
||||
IMPORTANT DEVIATION (see the "Known cross-codec divergence" note at the
|
||||
bottom of this file): the current `scripts/chunk_data_decoder.gd` does not
|
||||
actually implement IEEE-754 float32 for the `pos`/`rot`/`scale`/`bounds`
|
||||
fields -- it performs a lossy numeric `int`/`float` cast instead of a bit
|
||||
reinterpretation, which both truncates fractional values and does not
|
||||
write IEEE-754 bits at all. This module implements the format as
|
||||
*specified* (real `<f` IEEE-754 float32, matching every other field in the
|
||||
spec and matching what any conformant decoder would assume). See the note
|
||||
for what this means for cross-codec byte parity today.
|
||||
|
||||
Nothing here talks to a database or the FastAPI app; it is a pure,
|
||||
side-effect-free codec so it can be golden-file tested in isolation.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import hashlib
|
||||
import json
|
||||
import struct
|
||||
from dataclasses import dataclass, field
|
||||
|
||||
MAGIC = b"AGPC"
|
||||
HEADER_SIZE = 48
|
||||
CURRENT_VERSION = 1
|
||||
|
||||
SECTION_META = 0x01
|
||||
SECTION_TILE = 0x02
|
||||
SECTION_OBJECT = 0x03
|
||||
SECTION_FLAGS = 0x04
|
||||
SECTION_REVISION_META = 0x05
|
||||
|
||||
CATEGORY_FIELDS = (
|
||||
"violence", "sexual", "language", "substance",
|
||||
"gambling", "horror", "hate", "custom",
|
||||
)
|
||||
|
||||
|
||||
class ChunkCodecError(Exception):
|
||||
"""Malformed bytes -- the payload isn't shaped like a chunk at all."""
|
||||
|
||||
|
||||
class ChunkValidationError(Exception):
|
||||
"""A structurally-valid chunk failed a content/business-rule check.
|
||||
|
||||
``reason`` is the machine-readable code the API surface (world_persistence_impl.md
|
||||
§8.1) puts in the 422 response body's ``reason`` field, e.g.
|
||||
``"checksum_mismatch"``, ``"layer_dims"``, ``"object_out_of_bounds"``.
|
||||
"""
|
||||
|
||||
def __init__(self, reason: str, message: str | None = None) -> None:
|
||||
self.reason = reason
|
||||
super().__init__(message or reason)
|
||||
|
||||
|
||||
# ───────────────────────── Logical model ─────────────────────────
|
||||
|
||||
@dataclass
|
||||
class TileDef:
|
||||
id: int
|
||||
asset_id: str = ""
|
||||
solid: bool = False
|
||||
flags: int = 0
|
||||
variants: int = 1
|
||||
|
||||
|
||||
@dataclass
|
||||
class TileLayer:
|
||||
name: str
|
||||
layer_id: int = 0
|
||||
width: int = 0
|
||||
height: int = 0
|
||||
depth: int = 1
|
||||
palette: list[TileDef] = field(default_factory=list)
|
||||
tiles: list[int] = field(default_factory=list) # flattened, row-major
|
||||
|
||||
|
||||
@dataclass
|
||||
class ContentFlags:
|
||||
violence: int = 0
|
||||
sexual: int = 0
|
||||
language: int = 0
|
||||
substance: int = 0
|
||||
gambling: int = 0
|
||||
horror: int = 0
|
||||
hate: int = 0
|
||||
custom: int = 0
|
||||
mature: bool = False
|
||||
sources: list[str] = field(default_factory=list)
|
||||
|
||||
def to_dict(self) -> dict:
|
||||
return {
|
||||
"categories": {name: getattr(self, name) for name in CATEGORY_FIELDS},
|
||||
"mature": self.mature,
|
||||
"sources": list(self.sources),
|
||||
}
|
||||
|
||||
@classmethod
|
||||
def from_dict(cls, d: dict) -> "ContentFlags":
|
||||
cats = d.get("categories", {})
|
||||
return cls(
|
||||
**{name: int(cats.get(name, 0)) for name in CATEGORY_FIELDS},
|
||||
mature=bool(d.get("mature", False)),
|
||||
sources=list(d.get("sources", [])),
|
||||
)
|
||||
|
||||
|
||||
@dataclass
|
||||
class WorldObject:
|
||||
id: str
|
||||
type: str
|
||||
asset_id: str
|
||||
pos: tuple[float, float, float] = (0.0, 0.0, 0.0)
|
||||
rot: tuple[float, float, float, float] = (0.0, 0.0, 0.0, 1.0)
|
||||
scale: tuple[float, float, float] = (1.0, 1.0, 1.0)
|
||||
dynamic: bool = False
|
||||
properties: dict = field(default_factory=dict)
|
||||
flags: ContentFlags = field(default_factory=ContentFlags)
|
||||
|
||||
|
||||
@dataclass
|
||||
class ChunkBounds:
|
||||
"""Wire representation is min-corner + size (matching the Godot AABB
|
||||
the reference encoder builds from), not min/max as world.md §3.1's
|
||||
logical-model prose describes -- both are fully recoverable from each
|
||||
other; this is just the on-the-wire convention."""
|
||||
|
||||
min: tuple[float, float, float] = (0.0, 0.0, 0.0)
|
||||
size: tuple[float, float, float] = (0.0, 0.0, 0.0)
|
||||
|
||||
@property
|
||||
def max(self) -> tuple[float, float, float]:
|
||||
return tuple(a + b for a, b in zip(self.min, self.size))
|
||||
|
||||
|
||||
@dataclass
|
||||
class ChunkPayload:
|
||||
version: int = CURRENT_VERSION
|
||||
world_id: str = ""
|
||||
room_id: str = ""
|
||||
coord: tuple[int, int, int] = (0, 0, 0)
|
||||
bounds: ChunkBounds = field(default_factory=ChunkBounds)
|
||||
tile_layers: list[TileLayer] = field(default_factory=list)
|
||||
objects: list[WorldObject] = field(default_factory=list)
|
||||
flags: ContentFlags = field(default_factory=ContentFlags)
|
||||
created_at: int = 0
|
||||
updated_at: int = 0
|
||||
revision: int = 0
|
||||
author: str = ""
|
||||
|
||||
|
||||
def build_key(world_id: str | int, room_slug: str, cx: int, cy: int, cz: int) -> str:
|
||||
"""world_persistence_impl.md §4.5: ``"{world.id}:{room.slug}:{cx}:{cy}:{cz}"``."""
|
||||
return f"{world_id}:{room_slug}:{cx}:{cy}:{cz}"
|
||||
|
||||
|
||||
# ───────────────────────── Binary primitives ─────────────────────────
|
||||
# All integers little-endian, matching world.md §3.6.3. Floats are packed
|
||||
# as real IEEE-754 float32 -- see the module docstring's deviation note.
|
||||
|
||||
def _read_u16(data: bytes, off: int) -> int:
|
||||
return struct.unpack_from("<H", data, off)[0]
|
||||
|
||||
|
||||
def _read_u32(data: bytes, off: int) -> int:
|
||||
return struct.unpack_from("<I", data, off)[0]
|
||||
|
||||
|
||||
def _read_i32(data: bytes, off: int) -> int:
|
||||
return struct.unpack_from("<i", data, off)[0]
|
||||
|
||||
|
||||
def _read_i64(data: bytes, off: int) -> int:
|
||||
return struct.unpack_from("<q", data, off)[0]
|
||||
|
||||
|
||||
def _read_f32(data: bytes, off: int) -> float:
|
||||
return struct.unpack_from("<f", data, off)[0]
|
||||
|
||||
|
||||
def _w_u16(v: int) -> bytes:
|
||||
return struct.pack("<H", v & 0xFFFF)
|
||||
|
||||
|
||||
def _w_u32(v: int) -> bytes:
|
||||
return struct.pack("<I", v & 0xFFFFFFFF)
|
||||
|
||||
|
||||
def _w_i32(v: int) -> bytes:
|
||||
return struct.pack("<i", v)
|
||||
|
||||
|
||||
def _w_i64(v: int) -> bytes:
|
||||
return struct.pack("<q", v)
|
||||
|
||||
|
||||
def _w_f32(v: float) -> bytes:
|
||||
return struct.pack("<f", v)
|
||||
|
||||
|
||||
def _read_str(data: bytes, off: int) -> tuple[str, int]:
|
||||
"""Length-prefixed UTF-8 string. Returns (value, next_offset)."""
|
||||
n = _read_u16(data, off)
|
||||
off += 2
|
||||
s = data[off:off + n].decode("utf-8")
|
||||
return s, off + n
|
||||
|
||||
|
||||
def _w_str(s: str) -> bytes:
|
||||
b = s.encode("utf-8")
|
||||
if len(b) > 0xFFFF:
|
||||
raise ChunkCodecError(f"string field too long to encode ({len(b)} bytes)")
|
||||
return _w_u16(len(b)) + b
|
||||
|
||||
|
||||
def checksum(payload_body: bytes) -> str:
|
||||
"""SHA-256 hex digest of the payload body (world.md §3.6.3)."""
|
||||
return hashlib.sha256(payload_body).hexdigest()
|
||||
|
||||
|
||||
# ───────────────────────── Section codecs ─────────────────────────
|
||||
|
||||
def _encode_metadata(payload: ChunkPayload) -> bytes:
|
||||
out = bytearray()
|
||||
out += _w_str(payload.world_id)
|
||||
out += _w_str(payload.room_id)
|
||||
out += _w_i32(payload.coord[0])
|
||||
out += _w_i32(payload.coord[1])
|
||||
out += _w_i32(payload.coord[2])
|
||||
out += _w_f32(payload.bounds.min[0])
|
||||
out += _w_f32(payload.bounds.min[1])
|
||||
out += _w_f32(payload.bounds.min[2])
|
||||
out += _w_f32(payload.bounds.size[0])
|
||||
out += _w_f32(payload.bounds.size[1])
|
||||
out += _w_f32(payload.bounds.size[2])
|
||||
return bytes(out)
|
||||
|
||||
|
||||
def _decode_metadata(data: bytes, result: ChunkPayload) -> None:
|
||||
off = 0
|
||||
result.world_id, off = _read_str(data, off)
|
||||
result.room_id, off = _read_str(data, off)
|
||||
coord = (_read_i32(data, off), _read_i32(data, off + 4), _read_i32(data, off + 8))
|
||||
off += 12
|
||||
min_pos = (_read_f32(data, off), _read_f32(data, off + 4), _read_f32(data, off + 8))
|
||||
size = (_read_f32(data, off + 12), _read_f32(data, off + 16), _read_f32(data, off + 20))
|
||||
result.coord = coord
|
||||
result.bounds = ChunkBounds(min=min_pos, size=size)
|
||||
|
||||
|
||||
def _encode_tile_layer(layer: TileLayer) -> bytes:
|
||||
out = bytearray()
|
||||
out += _w_str(layer.name)
|
||||
out += _w_u16(layer.layer_id)
|
||||
out += _w_u16(layer.width)
|
||||
out += _w_u16(layer.height)
|
||||
out += _w_u16(layer.depth)
|
||||
out += _w_u16(len(layer.palette))
|
||||
for td in layer.palette:
|
||||
out += _w_u16(td.id)
|
||||
out += _w_str(td.asset_id)
|
||||
out += bytes([1 if td.solid else 0])
|
||||
out += _w_u32(td.flags)
|
||||
out += bytes([td.variants & 0xFF])
|
||||
out += _w_u32(len(layer.tiles))
|
||||
for tile_id in layer.tiles:
|
||||
out += _w_u16(tile_id)
|
||||
return bytes(out)
|
||||
|
||||
|
||||
def _decode_tile_layer(data: bytes) -> TileLayer:
|
||||
off = 0
|
||||
name, off = _read_str(data, off)
|
||||
layer_id = _read_u16(data, off); off += 2
|
||||
width = _read_u16(data, off); off += 2
|
||||
height = _read_u16(data, off); off += 2
|
||||
depth = _read_u16(data, off); off += 2
|
||||
palette_count = _read_u16(data, off); off += 2
|
||||
palette: list[TileDef] = []
|
||||
for _ in range(palette_count):
|
||||
tid = _read_u16(data, off); off += 2
|
||||
asset_id, off = _read_str(data, off)
|
||||
solid = data[off] != 0; off += 1
|
||||
flags = _read_u32(data, off); off += 4
|
||||
variants = data[off]; off += 1
|
||||
palette.append(TileDef(id=tid, asset_id=asset_id, solid=solid, flags=flags, variants=variants))
|
||||
tile_count = _read_u32(data, off); off += 4
|
||||
tiles: list[int] = []
|
||||
for _ in range(tile_count):
|
||||
tiles.append(_read_u16(data, off))
|
||||
off += 2
|
||||
return TileLayer(name=name, layer_id=layer_id, width=width, height=height,
|
||||
depth=depth, palette=palette, tiles=tiles)
|
||||
|
||||
|
||||
def _encode_flags(flags: ContentFlags) -> bytes:
|
||||
out = bytearray()
|
||||
for name in CATEGORY_FIELDS:
|
||||
out.append(getattr(flags, name) & 0xFF)
|
||||
out.append(1 if flags.mature else 0)
|
||||
out += _w_u16(len(flags.sources))
|
||||
for src in flags.sources:
|
||||
out += _w_str(src)
|
||||
return bytes(out)
|
||||
|
||||
|
||||
def _decode_flags(data: bytes) -> ContentFlags:
|
||||
off = 0
|
||||
values = {}
|
||||
for name in CATEGORY_FIELDS:
|
||||
values[name] = data[off]
|
||||
off += 1
|
||||
mature = data[off] != 0
|
||||
off += 1
|
||||
source_count = _read_u16(data, off)
|
||||
off += 2
|
||||
sources = []
|
||||
for _ in range(source_count):
|
||||
s, off = _read_str(data, off)
|
||||
sources.append(s)
|
||||
return ContentFlags(**values, mature=mature, sources=sources)
|
||||
|
||||
|
||||
def _encode_object(obj: WorldObject) -> bytes:
|
||||
out = bytearray()
|
||||
out += _w_str(obj.id)
|
||||
out += _w_str(obj.type)
|
||||
out += _w_str(obj.asset_id)
|
||||
for v in obj.pos:
|
||||
out += _w_f32(v)
|
||||
for v in obj.rot:
|
||||
out += _w_f32(v)
|
||||
for v in obj.scale:
|
||||
out += _w_f32(v)
|
||||
out.append(1 if obj.dynamic else 0)
|
||||
# Canonical JSON: keys sorted lexicographically (world.md §3.6.3).
|
||||
props_json = json.dumps(obj.properties, sort_keys=True, separators=(",", ":"))
|
||||
out += _w_str(props_json)
|
||||
out += _encode_flags(obj.flags)
|
||||
return bytes(out)
|
||||
|
||||
|
||||
def _decode_object(data: bytes) -> WorldObject:
|
||||
off = 0
|
||||
oid, off = _read_str(data, off)
|
||||
otype, off = _read_str(data, off)
|
||||
asset_id, off = _read_str(data, off)
|
||||
pos = (_read_f32(data, off), _read_f32(data, off + 4), _read_f32(data, off + 8))
|
||||
off += 12
|
||||
rot = (
|
||||
_read_f32(data, off), _read_f32(data, off + 4),
|
||||
_read_f32(data, off + 8), _read_f32(data, off + 12),
|
||||
)
|
||||
off += 16
|
||||
scale = (_read_f32(data, off), _read_f32(data, off + 4), _read_f32(data, off + 8))
|
||||
off += 12
|
||||
dynamic = data[off] != 0
|
||||
off += 1
|
||||
props_str, off = _read_str(data, off)
|
||||
try:
|
||||
properties = json.loads(props_str) if props_str else {}
|
||||
except json.JSONDecodeError as exc:
|
||||
raise ChunkCodecError(f"object {oid!r}: invalid properties JSON") from exc
|
||||
obj_flags = _decode_flags(data[off:])
|
||||
return WorldObject(id=oid, type=otype, asset_id=asset_id, pos=pos, rot=rot,
|
||||
scale=scale, dynamic=dynamic, properties=properties, flags=obj_flags)
|
||||
|
||||
|
||||
def _encode_revision_meta(payload: ChunkPayload) -> bytes:
|
||||
out = bytearray()
|
||||
out += _w_i64(payload.created_at)
|
||||
out += _w_i64(payload.updated_at)
|
||||
out += _w_u32(payload.revision)
|
||||
out += _w_str(payload.author)
|
||||
return bytes(out)
|
||||
|
||||
|
||||
def _decode_revision_meta(data: bytes, result: ChunkPayload) -> None:
|
||||
off = 0
|
||||
result.created_at = _read_i64(data, off); off += 8
|
||||
result.updated_at = _read_i64(data, off); off += 8
|
||||
result.revision = _read_u32(data, off); off += 4
|
||||
result.author, off = _read_str(data, off)
|
||||
|
||||
|
||||
def _wrap_section(section_id: int, data: bytes) -> bytes:
|
||||
return bytes([section_id]) + _w_u32(len(data)) + data
|
||||
|
||||
|
||||
# ───────────────────────── Top-level encode/decode ─────────────────────────
|
||||
|
||||
def encode_binary(payload: ChunkPayload) -> bytes:
|
||||
"""Encode a ChunkPayload to the world.md §3.6 wire format."""
|
||||
sections = bytearray()
|
||||
sections += _wrap_section(SECTION_META, _encode_metadata(payload))
|
||||
for layer in payload.tile_layers:
|
||||
sections += _wrap_section(SECTION_TILE, _encode_tile_layer(layer))
|
||||
for obj in payload.objects:
|
||||
sections += _wrap_section(SECTION_OBJECT, _encode_object(obj))
|
||||
sections += _wrap_section(SECTION_FLAGS, _encode_flags(payload.flags))
|
||||
sections += _wrap_section(SECTION_REVISION_META, _encode_revision_meta(payload))
|
||||
|
||||
payload_body = bytes(sections)
|
||||
digest = hashlib.sha256(payload_body).digest() # 32 raw bytes
|
||||
|
||||
header = bytearray()
|
||||
header += MAGIC
|
||||
header += _w_u16(CURRENT_VERSION)
|
||||
header += _w_u16(HEADER_SIZE - 8) # header_len: bytes of header after this field (spec-correct)
|
||||
header += _w_u32(0) # flags (reserved)
|
||||
header += _w_u32(len(payload_body))
|
||||
header += digest
|
||||
|
||||
return bytes(header) + payload_body
|
||||
|
||||
|
||||
def decode_binary(data: bytes) -> ChunkPayload:
|
||||
"""Decode a world.md §3.6 binary chunk. Raises ChunkCodecError on
|
||||
structurally malformed input (short buffer, bad magic, unsupported
|
||||
version, truncated payload)."""
|
||||
if len(data) < HEADER_SIZE:
|
||||
raise ChunkCodecError(f"data too short for header ({len(data)} bytes)")
|
||||
|
||||
if data[0:4] != MAGIC:
|
||||
raise ChunkCodecError("bad magic bytes")
|
||||
|
||||
version = _read_u16(data, 4)
|
||||
if version < 1 or version > CURRENT_VERSION:
|
||||
raise ChunkCodecError(f"unsupported chunk format version {version}")
|
||||
|
||||
# header_len (offset 6) is intentionally not used for offset math --
|
||||
# both this decoder and the Godot one always slice at the fixed
|
||||
# HEADER_SIZE, matching the reference implementation's actual (if
|
||||
# spec-inconsistent) behaviour.
|
||||
payload_len = _read_u32(data, 12)
|
||||
# bytes 16:48 are the header's advisory checksum -- decode_and_validate
|
||||
# re-reads it directly and recomputes against the parsed payload body.
|
||||
|
||||
if len(data) - HEADER_SIZE != payload_len:
|
||||
raise ChunkCodecError(
|
||||
f"declared payload_len ({payload_len}) does not match actual "
|
||||
f"remaining bytes ({len(data) - HEADER_SIZE})"
|
||||
)
|
||||
|
||||
payload_body = data[HEADER_SIZE:HEADER_SIZE + payload_len]
|
||||
|
||||
result = ChunkPayload(version=version)
|
||||
|
||||
offset = 0
|
||||
while offset < len(payload_body):
|
||||
if offset + 5 > len(payload_body):
|
||||
raise ChunkCodecError("truncated section header")
|
||||
section_id = payload_body[offset]
|
||||
section_len = _read_u32(payload_body, offset + 1)
|
||||
data_start = offset + 5
|
||||
data_end = data_start + section_len
|
||||
if data_end > len(payload_body):
|
||||
raise ChunkCodecError("truncated section body")
|
||||
section_data = payload_body[data_start:data_end]
|
||||
|
||||
if section_id == SECTION_META:
|
||||
_decode_metadata(section_data, result)
|
||||
elif section_id == SECTION_TILE:
|
||||
result.tile_layers.append(_decode_tile_layer(section_data))
|
||||
elif section_id == SECTION_OBJECT:
|
||||
result.objects.append(_decode_object(section_data))
|
||||
elif section_id == SECTION_FLAGS:
|
||||
result.flags = _decode_flags(section_data)
|
||||
elif section_id == SECTION_REVISION_META:
|
||||
_decode_revision_meta(section_data, result)
|
||||
# Unknown section ids are skipped (forward-compat), matching the
|
||||
# Godot decoder's match-with-no-default behaviour.
|
||||
|
||||
offset = data_end
|
||||
|
||||
return result
|
||||
|
||||
|
||||
# ───────────────────────── JSON encoding (world.md §3.5) ─────────────────────────
|
||||
# Derived, never stored (world_persistence_impl.md §8.1) -- produced here
|
||||
# from a decoded ChunkPayload for the ``Accept: application/json`` path.
|
||||
|
||||
def to_json_dict(payload: ChunkPayload, *, key: str, chunk_checksum: str) -> dict:
|
||||
return {
|
||||
"version": payload.version,
|
||||
"key": key,
|
||||
"world_id": payload.world_id,
|
||||
"room_id": payload.room_id,
|
||||
"coord": {"cx": payload.coord[0], "cy": payload.coord[1], "cz": payload.coord[2]},
|
||||
"bounds": {
|
||||
"min_x": payload.bounds.min[0], "min_y": payload.bounds.min[1], "min_z": payload.bounds.min[2],
|
||||
"max_x": payload.bounds.max[0], "max_y": payload.bounds.max[1], "max_z": payload.bounds.max[2],
|
||||
},
|
||||
"tiles": [
|
||||
{
|
||||
"name": layer.name,
|
||||
"layer_id": layer.layer_id,
|
||||
"width": layer.width,
|
||||
"height": layer.height,
|
||||
"depth": layer.depth,
|
||||
"palette": [
|
||||
{"id": td.id, "asset_id": td.asset_id, "solid": td.solid,
|
||||
"flags": td.flags, "variants": td.variants}
|
||||
for td in layer.palette
|
||||
],
|
||||
"tiles": list(layer.tiles),
|
||||
}
|
||||
for layer in payload.tile_layers
|
||||
],
|
||||
"objects": [
|
||||
{
|
||||
"id": obj.id, "type": obj.type, "asset_id": obj.asset_id,
|
||||
"transform": {
|
||||
"pos": list(obj.pos), "rot": list(obj.rot), "scale": list(obj.scale),
|
||||
},
|
||||
"properties": obj.properties,
|
||||
"dynamic": obj.dynamic,
|
||||
"flags": obj.flags.to_dict(),
|
||||
}
|
||||
for obj in payload.objects
|
||||
],
|
||||
"flags": payload.flags.to_dict(),
|
||||
"meta": {
|
||||
"created_at": payload.created_at, "updated_at": payload.updated_at,
|
||||
"revision": payload.revision, "author": payload.author,
|
||||
},
|
||||
"checksum": chunk_checksum,
|
||||
}
|
||||
|
||||
|
||||
# ───────────────────────── Validation (world_persistence_impl.md §5.5) ─────────────────────────
|
||||
|
||||
# Not precisely quantified by the design doc beyond "length limits" --
|
||||
# these are this implementation's conservative defaults (world.md §7).
|
||||
MAX_STRING_FIELD_LEN = 256
|
||||
MAX_PROPERTIES_JSON_LEN = 16_384
|
||||
MAX_SOURCES_PER_FLAGSET = 32
|
||||
|
||||
|
||||
def _check_string_lengths(obj: WorldObject) -> None:
|
||||
for field_name, value in (("id", obj.id), ("type", obj.type), ("asset_id", obj.asset_id)):
|
||||
if len(value) > MAX_STRING_FIELD_LEN:
|
||||
raise ChunkValidationError(
|
||||
"string_field_too_long", f"object.{field_name} exceeds {MAX_STRING_FIELD_LEN} chars"
|
||||
)
|
||||
props_json = json.dumps(obj.properties)
|
||||
if len(props_json) > MAX_PROPERTIES_JSON_LEN:
|
||||
raise ChunkValidationError(
|
||||
"string_field_too_long", f"object {obj.id!r} properties exceed {MAX_PROPERTIES_JSON_LEN} bytes"
|
||||
)
|
||||
if len(obj.flags.sources) > MAX_SOURCES_PER_FLAGSET:
|
||||
raise ChunkValidationError("string_field_too_long", f"object {obj.id!r} has too many flag sources")
|
||||
|
||||
|
||||
def decode_and_validate(
|
||||
data: bytes,
|
||||
*,
|
||||
expected_key: str,
|
||||
grid_size: tuple[int, int, int],
|
||||
max_objects: int,
|
||||
) -> ChunkPayload:
|
||||
"""Decode + fully validate a client-submitted chunk payload.
|
||||
|
||||
This is the boundary world_persistence_impl.md §5.5 requires: "the
|
||||
backend must not trust the client". Raises ``ChunkCodecError`` for
|
||||
structurally malformed bytes (mapped to a 422 by the router with a
|
||||
generic reason) or ``ChunkValidationError`` with a specific ``reason``
|
||||
code for a well-formed-but-invalid payload.
|
||||
"""
|
||||
payload = decode_binary(data) # raises ChunkCodecError for structural problems first
|
||||
|
||||
# Checksum is advisory in the header (world.md §7); the value that
|
||||
# matters is recomputed from the actual payload body we just parsed.
|
||||
payload_body = data[HEADER_SIZE:]
|
||||
recomputed = checksum(payload_body)
|
||||
header_checksum_hex = data[16:48].hex()
|
||||
if header_checksum_hex != recomputed:
|
||||
raise ChunkValidationError(
|
||||
"checksum_mismatch",
|
||||
"header checksum does not match the recomputed SHA-256 of the payload body",
|
||||
)
|
||||
|
||||
actual_key = build_key(payload.world_id, payload.room_id, *payload.coord)
|
||||
if actual_key != expected_key:
|
||||
raise ChunkValidationError(
|
||||
"chunk_key_mismatch",
|
||||
f"payload key {actual_key!r} does not match URL {expected_key!r}",
|
||||
)
|
||||
|
||||
for layer in payload.tile_layers:
|
||||
if (layer.width, layer.height, layer.depth) != tuple(grid_size):
|
||||
raise ChunkValidationError(
|
||||
"layer_dims",
|
||||
f"tile layer {layer.name!r} dims {(layer.width, layer.height, layer.depth)} "
|
||||
f"!= room grid {tuple(grid_size)}",
|
||||
)
|
||||
valid_ids = {0} | {td.id for td in layer.palette}
|
||||
for tile_id in layer.tiles:
|
||||
if tile_id not in valid_ids:
|
||||
raise ChunkValidationError(
|
||||
"tile_out_of_palette",
|
||||
f"tile layer {layer.name!r} references palette id {tile_id} not in its palette",
|
||||
)
|
||||
if len(layer.tiles) != layer.width * layer.height * layer.depth:
|
||||
raise ChunkValidationError(
|
||||
"layer_dims",
|
||||
f"tile layer {layer.name!r} has {len(layer.tiles)} cells, expected "
|
||||
f"{layer.width * layer.height * layer.depth}",
|
||||
)
|
||||
|
||||
if len(payload.objects) > max_objects:
|
||||
raise ChunkValidationError(
|
||||
"too_many_objects", f"{len(payload.objects)} objects exceeds max {max_objects}"
|
||||
)
|
||||
|
||||
bmin, bmax = payload.bounds.min, payload.bounds.max
|
||||
for obj in payload.objects:
|
||||
_check_string_lengths(obj)
|
||||
if not all(bmin[i] <= obj.pos[i] <= bmax[i] for i in range(3)):
|
||||
raise ChunkValidationError(
|
||||
"object_out_of_bounds",
|
||||
f"object {obj.id!r} position {obj.pos} outside chunk bounds "
|
||||
f"[{bmin}, {bmax}]",
|
||||
)
|
||||
|
||||
if len(payload.author) > MAX_STRING_FIELD_LEN:
|
||||
raise ChunkValidationError("string_field_too_long", "meta.author too long")
|
||||
|
||||
return payload
|
||||
|
||||
|
||||
# ───────────────────────── Known cross-codec divergence ─────────────────────────
|
||||
#
|
||||
# `scripts/chunk_data_decoder.gd`'s `_read_float32`/`_write_float32` do:
|
||||
#
|
||||
# static func _write_float32(val: float) -> PackedByteArray:
|
||||
# var bits := val as int
|
||||
# return _write_uint32(bits)
|
||||
#
|
||||
# static func _read_float32(data: PackedByteArray, offset: int) -> float:
|
||||
# var bits := _read_uint32(data, offset)
|
||||
# return bits as float
|
||||
#
|
||||
# `as` between int and float in GDScript is a numeric conversion, not a bit
|
||||
# reinterpretation (verified empirically against Godot 4.6.2 headless:
|
||||
# `1.5 as int` -> `1`, `1 as float` -> `1.0`; the IEEE-754 bit pattern of
|
||||
# 1.5f is 0x3FC00000 = 1069547520, not 1). So the shipped client codec
|
||||
# truncates every float32 field (bounds, object pos/rot/scale) to its
|
||||
# integer part and stores that integer as a raw int32 -- not as float32
|
||||
# bits at all. This is a real bug in already-merged, client-side code
|
||||
# (scripts/ is out of scope for this task) that breaks the "byte-stable
|
||||
# across two implementations" guarantee world.md §3.6.3 states.
|
||||
#
|
||||
# This module implements the *specified* format (real IEEE-754 float32)
|
||||
# rather than replicating that bug, because world.md §3.6 is normative and
|
||||
# says "float32" for these fields, and mirroring the bug would mean the
|
||||
# backend also corrupts every non-integer transform/bounds value it
|
||||
# stores. Practical effect until the client-side bug is fixed: payloads
|
||||
# with integer-only floats will decode identically on both sides; any
|
||||
# payload with a fractional position/rotation/scale/bounds value will not
|
||||
# be byte-identical (or numerically identical) between this module and the
|
||||
# current `scripts/chunk_data_decoder.gd`. This is flagged for the
|
||||
# client/editor follow-on task, not fixed here.
|
||||
@@ -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:
|
||||
|
||||
@@ -0,0 +1,431 @@
|
||||
"""World content storage service.
|
||||
|
||||
Implements the `world.md` §5.1 service interface over Postgres, per
|
||||
`world_persistence_impl.md` §9 -- **minus** ``flush_dirty`` and
|
||||
``rebuild_index``, which don't apply once there is no write-behind dirty
|
||||
set and no derived index to rebuild (see that doc's §3.3 and §4.2).
|
||||
|
||||
This is the *only* place chunk content is written (world_persistence_impl.md
|
||||
D2 / §5). Callers (the routers) own transaction boundaries: methods here
|
||||
``flush()`` so later statements in the same request see earlier ones and so
|
||||
integrity errors surface before a caller commits, but they never
|
||||
``commit()`` -- that mirrors the existing convention in
|
||||
``app/routers/worlds.py`` (``get_db`` docs: "Handlers are responsible for
|
||||
committing or rolling back their own transactions").
|
||||
|
||||
Known gap this module had to resolve on its own (flagged, not silently
|
||||
decided): `world_persistence_impl.md` §6/§7.2/§8.1 all reference a world's
|
||||
monotonic ``content_revision`` ("bumped on every chunk write"), but no
|
||||
column for it is defined anywhere in §4's schema. Rather than add an
|
||||
undocumented column, ``content_revision()`` below derives it as
|
||||
``MAX(id)`` over ``world_chunk_revisions`` scoped to the world: that table
|
||||
is append-only (retention only nulls ``payload``, it never deletes rows),
|
||||
so the value is genuinely monotonic and increments on every
|
||||
create/update/delete/rollback.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from dataclasses import dataclass
|
||||
|
||||
from sqlalchemy import func, select, update
|
||||
from sqlalchemy.exc import IntegrityError
|
||||
from sqlalchemy.ext.asyncio import AsyncSession
|
||||
from sqlalchemy.orm import load_only
|
||||
|
||||
from app.config import settings
|
||||
from app.models.world_content import (
|
||||
MAIN_ROOM_NAME,
|
||||
MAIN_ROOM_SLUG,
|
||||
WorldChunk,
|
||||
WorldChunkRevision,
|
||||
WorldRoom,
|
||||
)
|
||||
from app.services import chunk_codec
|
||||
|
||||
|
||||
class RevisionConflict(Exception):
|
||||
"""Optimistic-concurrency conflict (world.md §5.4). ``current_revision``
|
||||
is 0 and ``current_checksum`` is None when the caller's ``base_revision``
|
||||
assumed a chunk exists but it doesn't."""
|
||||
|
||||
def __init__(
|
||||
self,
|
||||
current_revision: int,
|
||||
current_checksum: str | None,
|
||||
coord: tuple[int, int, int] | None = None,
|
||||
) -> None:
|
||||
self.current_revision = current_revision
|
||||
self.current_checksum = current_checksum
|
||||
self.coord = coord
|
||||
super().__init__(f"revision conflict: current_revision={current_revision}")
|
||||
|
||||
|
||||
class RevisionNotAvailable(Exception):
|
||||
"""Raised by ``rollback_chunk`` when the requested revision doesn't
|
||||
exist, or exists but its payload was pruned by the retention policy
|
||||
(world_persistence_impl.md §4.3)."""
|
||||
|
||||
|
||||
@dataclass
|
||||
class Bounds:
|
||||
cx_min: int | None = None
|
||||
cx_max: int | None = None
|
||||
cy_min: int | None = None
|
||||
cy_max: int | None = None
|
||||
cz: int | None = None
|
||||
|
||||
|
||||
class WorldStore:
|
||||
"""Owns chunk/room read/write operations over the async session
|
||||
handed to it. One instance per request is the expected usage
|
||||
(``WorldStore(db)`` where ``db`` is the ``DbDep`` session)."""
|
||||
|
||||
def __init__(self, db: AsyncSession) -> None:
|
||||
self.db = db
|
||||
|
||||
# ── rooms ────────────────────────────────────────────────────────────
|
||||
|
||||
async def get_room(self, world_id: int, slug: str) -> WorldRoom | None:
|
||||
result = await self.db.execute(
|
||||
select(WorldRoom).where(WorldRoom.world_id == world_id, WorldRoom.slug == slug)
|
||||
)
|
||||
return result.scalar_one_or_none()
|
||||
|
||||
async def list_rooms(self, world_id: int) -> list[WorldRoom]:
|
||||
result = await self.db.execute(
|
||||
select(WorldRoom).where(WorldRoom.world_id == world_id).order_by(WorldRoom.id)
|
||||
)
|
||||
return list(result.scalars().all())
|
||||
|
||||
async def create_room(
|
||||
self,
|
||||
world_id: int,
|
||||
slug: str,
|
||||
name: str,
|
||||
*,
|
||||
grid: dict | None = None,
|
||||
bounds: dict | None = None,
|
||||
spawn: dict | None = None,
|
||||
) -> WorldRoom:
|
||||
room = WorldRoom(world_id=world_id, slug=slug, name=name)
|
||||
if grid is not None:
|
||||
room.grid = grid
|
||||
if bounds is not None:
|
||||
room.bounds = bounds
|
||||
if spawn is not None:
|
||||
room.spawn = spawn
|
||||
self.db.add(room)
|
||||
await self.db.flush()
|
||||
await self.db.refresh(room)
|
||||
return room
|
||||
|
||||
async def get_or_create_main_room(self, world_id: int) -> WorldRoom:
|
||||
"""world_persistence_impl.md §4.1: every world gets a ``main`` room.
|
||||
Called from ``create_world`` for new worlds, and lazily here for
|
||||
worlds that predate this migration."""
|
||||
room = await self.get_room(world_id, MAIN_ROOM_SLUG)
|
||||
if room is not None:
|
||||
return room
|
||||
try:
|
||||
return await self.create_room(world_id, MAIN_ROOM_SLUG, MAIN_ROOM_NAME)
|
||||
except IntegrityError:
|
||||
# Lost a race with a concurrent creator; the row now exists.
|
||||
await self.db.rollback()
|
||||
room = await self.get_room(world_id, MAIN_ROOM_SLUG)
|
||||
if room is None:
|
||||
raise
|
||||
return room
|
||||
|
||||
async def count_chunks(self, room_id: int) -> int:
|
||||
result = await self.db.execute(
|
||||
select(func.count()).select_from(WorldChunk).where(WorldChunk.room_id == room_id)
|
||||
)
|
||||
return int(result.scalar_one())
|
||||
|
||||
async def content_revision(self, world_id: int) -> int:
|
||||
"""See module docstring for why this is derived rather than stored."""
|
||||
result = await self.db.execute(
|
||||
select(func.max(WorldChunkRevision.id)).where(WorldChunkRevision.world_id == world_id)
|
||||
)
|
||||
return int(result.scalar() or 0)
|
||||
|
||||
# ── chunk reads ──────────────────────────────────────────────────────
|
||||
|
||||
async def get_chunk(self, key: str) -> WorldChunk | None:
|
||||
result = await self.db.execute(select(WorldChunk).where(WorldChunk.chunk_key == key))
|
||||
return result.scalar_one_or_none()
|
||||
|
||||
async def get_chunk_by_coord(self, room_id: int, cx: int, cy: int, cz: int) -> WorldChunk | None:
|
||||
result = await self.db.execute(
|
||||
select(WorldChunk).where(
|
||||
WorldChunk.room_id == room_id, WorldChunk.cx == cx,
|
||||
WorldChunk.cy == cy, WorldChunk.cz == cz,
|
||||
)
|
||||
)
|
||||
return result.scalar_one_or_none()
|
||||
|
||||
async def get_chunk_binary(self, key: str) -> bytes | None:
|
||||
chunk = await self.get_chunk(key)
|
||||
return chunk.payload if chunk is not None else None
|
||||
|
||||
async def get_chunk_flags(self, key: str) -> dict | None:
|
||||
chunk = await self.get_chunk(key)
|
||||
return chunk.content_flags if chunk is not None else None
|
||||
|
||||
async def list_chunks(
|
||||
self,
|
||||
world_id: int,
|
||||
room_id: int | None = None,
|
||||
bounds: Bounds | None = None,
|
||||
) -> list[WorldChunk]:
|
||||
"""Index query -- world.md §5.1's ``list_chunks``. Payload bytes are
|
||||
deliberately not loaded (world_persistence_impl.md §8.1: "Payloads
|
||||
are not included")."""
|
||||
query = select(WorldChunk).options(
|
||||
load_only(
|
||||
WorldChunk.id, WorldChunk.world_id, WorldChunk.room_id, WorldChunk.chunk_key,
|
||||
WorldChunk.cx, WorldChunk.cy, WorldChunk.cz, WorldChunk.revision,
|
||||
WorldChunk.checksum, WorldChunk.payload_len, WorldChunk.is_mature,
|
||||
WorldChunk.updated_at,
|
||||
)
|
||||
).where(WorldChunk.world_id == world_id)
|
||||
if room_id is not None:
|
||||
query = query.where(WorldChunk.room_id == room_id)
|
||||
if bounds is not None:
|
||||
if bounds.cx_min is not None:
|
||||
query = query.where(WorldChunk.cx >= bounds.cx_min)
|
||||
if bounds.cx_max is not None:
|
||||
query = query.where(WorldChunk.cx <= bounds.cx_max)
|
||||
if bounds.cy_min is not None:
|
||||
query = query.where(WorldChunk.cy >= bounds.cy_min)
|
||||
if bounds.cy_max is not None:
|
||||
query = query.where(WorldChunk.cy <= bounds.cy_max)
|
||||
if bounds.cz is not None:
|
||||
query = query.where(WorldChunk.cz == bounds.cz)
|
||||
query = query.order_by(WorldChunk.cx, WorldChunk.cy, WorldChunk.cz)
|
||||
result = await self.db.execute(query)
|
||||
return list(result.scalars().all())
|
||||
|
||||
# ── chunk writes ─────────────────────────────────────────────────────
|
||||
|
||||
async def put_chunk(
|
||||
self,
|
||||
*,
|
||||
room: WorldRoom,
|
||||
cx: int,
|
||||
cy: int,
|
||||
cz: int,
|
||||
payload_bytes: bytes,
|
||||
base_revision: int,
|
||||
actor_id: int | None,
|
||||
) -> WorldChunk:
|
||||
"""Full-chunk write with optimistic concurrency (world.md §5.4,
|
||||
world_persistence_impl.md §5.4/§8.2). Validates the payload
|
||||
server-side (§5.5) before ever touching a row. ``base_revision=0``
|
||||
means "create; 409 if it already exists"."""
|
||||
key = chunk_codec.build_key(room.world_id, room.slug, cx, cy, cz)
|
||||
grid_size = tuple(room.grid.get("size", [32, 32, 1]))
|
||||
|
||||
# Raises ChunkCodecError / ChunkValidationError -- the router maps
|
||||
# those to 422. Nothing below trusts the request body's own claims
|
||||
# about content_flags/is_mature; both come from `decoded`.
|
||||
decoded = chunk_codec.decode_and_validate(
|
||||
payload_bytes,
|
||||
expected_key=key,
|
||||
grid_size=grid_size,
|
||||
max_objects=settings.WORLD_CHUNK_MAX_OBJECTS,
|
||||
)
|
||||
body_checksum = chunk_codec.checksum(payload_bytes[chunk_codec.HEADER_SIZE:])
|
||||
|
||||
result = await self.db.execute(
|
||||
select(WorldChunk)
|
||||
.where(
|
||||
WorldChunk.room_id == room.id, WorldChunk.cx == cx,
|
||||
WorldChunk.cy == cy, WorldChunk.cz == cz,
|
||||
)
|
||||
.with_for_update()
|
||||
)
|
||||
row = result.scalar_one_or_none()
|
||||
|
||||
if base_revision == 0:
|
||||
if row is not None:
|
||||
raise RevisionConflict(row.revision, row.checksum, (cx, cy, cz))
|
||||
row = WorldChunk(
|
||||
world_id=room.world_id, room_id=room.id, chunk_key=key,
|
||||
cx=cx, cy=cy, cz=cz, revision=1,
|
||||
)
|
||||
self.db.add(row)
|
||||
action = "create"
|
||||
else:
|
||||
if row is None or row.revision != base_revision:
|
||||
raise RevisionConflict(
|
||||
row.revision if row else 0, row.checksum if row else None, (cx, cy, cz)
|
||||
)
|
||||
row.revision = row.revision + 1
|
||||
action = "update"
|
||||
|
||||
row.format_version = decoded.version
|
||||
row.payload = payload_bytes
|
||||
row.payload_len = len(payload_bytes)
|
||||
row.checksum = body_checksum
|
||||
row.content_flags = decoded.flags.to_dict()
|
||||
row.is_mature = decoded.flags.mature
|
||||
row.updated_by_id = actor_id
|
||||
|
||||
try:
|
||||
await self.db.flush()
|
||||
except IntegrityError:
|
||||
# Lost a create race to a concurrent writer between our SELECT
|
||||
# and this flush. Roll back and report the real current state.
|
||||
await self.db.rollback()
|
||||
existing = await self.get_chunk_by_coord(room.id, cx, cy, cz)
|
||||
raise RevisionConflict(
|
||||
existing.revision if existing else 0,
|
||||
existing.checksum if existing else None,
|
||||
(cx, cy, cz),
|
||||
)
|
||||
|
||||
await self._record_revision(key, room.world_id, row.revision, action, actor_id, body_checksum, payload_bytes)
|
||||
await self.db.refresh(row)
|
||||
return row
|
||||
|
||||
async def put_chunks_batch(
|
||||
self,
|
||||
*,
|
||||
room: WorldRoom,
|
||||
items: list[dict],
|
||||
actor_id: int | None,
|
||||
) -> list[WorldChunk]:
|
||||
"""Batch write (world_persistence_impl.md §8.1). One transaction,
|
||||
all-or-nothing: none of this ``commit()``s, so a ``RevisionConflict``
|
||||
raised partway leaves nothing persisted once the caller's request
|
||||
handler lets the exception (or the HTTPException it becomes)
|
||||
propagate through ``get_db``, which rolls back on any exception."""
|
||||
rows: list[WorldChunk] = []
|
||||
for item in items:
|
||||
row = await self.put_chunk(
|
||||
room=room, cx=item["cx"], cy=item["cy"], cz=item["cz"],
|
||||
payload_bytes=item["payload_bytes"], base_revision=item["base_revision"],
|
||||
actor_id=actor_id,
|
||||
)
|
||||
rows.append(row)
|
||||
return rows
|
||||
|
||||
async def delete_chunk(self, key: str, actor_id: int | None) -> None:
|
||||
row = await self.get_chunk(key)
|
||||
if row is None:
|
||||
return
|
||||
await self._record_revision(key, row.world_id, row.revision, "delete", actor_id, row.checksum, None)
|
||||
await self.db.delete(row)
|
||||
await self.db.flush()
|
||||
|
||||
async def rollback_chunk(self, key: str, revision: int, actor_id: int | None) -> WorldChunk:
|
||||
"""Restore a chunk to a previously-recorded revision's payload
|
||||
(world.md §5.1). Raises ``RevisionNotAvailable`` if that revision
|
||||
was never recorded, its payload was pruned by retention, or the
|
||||
chunk has since been deleted outright (nothing to update in place)."""
|
||||
rev_result = await self.db.execute(
|
||||
select(WorldChunkRevision)
|
||||
.where(WorldChunkRevision.chunk_key == key, WorldChunkRevision.revision == revision)
|
||||
.order_by(WorldChunkRevision.id.desc())
|
||||
.limit(1)
|
||||
)
|
||||
rev_row = rev_result.scalar_one_or_none()
|
||||
if rev_row is None:
|
||||
raise RevisionNotAvailable(f"no revision {revision} recorded for {key!r}")
|
||||
if rev_row.payload is None:
|
||||
raise RevisionNotAvailable(f"revision {revision} of {key!r} was pruned; payload unavailable")
|
||||
|
||||
chunk = await self.get_chunk(key)
|
||||
if chunk is None:
|
||||
raise RevisionNotAvailable(f"chunk {key!r} no longer exists; cannot roll back in place")
|
||||
|
||||
room_result = await self.db.execute(select(WorldRoom).where(WorldRoom.id == chunk.room_id))
|
||||
room = room_result.scalar_one()
|
||||
grid_size = tuple(room.grid.get("size", [32, 32, 1]))
|
||||
decoded = chunk_codec.decode_and_validate(
|
||||
rev_row.payload, expected_key=key, grid_size=grid_size,
|
||||
max_objects=settings.WORLD_CHUNK_MAX_OBJECTS,
|
||||
)
|
||||
body_checksum = chunk_codec.checksum(rev_row.payload[chunk_codec.HEADER_SIZE:])
|
||||
|
||||
chunk.revision = chunk.revision + 1
|
||||
chunk.payload = rev_row.payload
|
||||
chunk.payload_len = len(rev_row.payload)
|
||||
chunk.checksum = body_checksum
|
||||
chunk.format_version = decoded.version
|
||||
chunk.content_flags = decoded.flags.to_dict()
|
||||
chunk.is_mature = decoded.flags.mature
|
||||
chunk.updated_by_id = actor_id
|
||||
|
||||
await self.db.flush()
|
||||
# Tagged "update" (not a fourth action value) to keep the
|
||||
# documented 'create'|'update'|'delete' action enum intact.
|
||||
await self._record_revision(
|
||||
key, chunk.world_id, chunk.revision, "update", actor_id, body_checksum, rev_row.payload
|
||||
)
|
||||
await self.db.refresh(chunk)
|
||||
return chunk
|
||||
|
||||
async def list_revisions(self, chunk_key: str, limit: int = 50) -> list[WorldChunkRevision]:
|
||||
"""Not in world.md §5.1's interface by name, but required to
|
||||
implement the revision-history endpoint world_persistence_impl.md
|
||||
§8.1 lists (``GET .../revisions``)."""
|
||||
result = await self.db.execute(
|
||||
select(WorldChunkRevision)
|
||||
.where(WorldChunkRevision.chunk_key == chunk_key)
|
||||
.order_by(WorldChunkRevision.revision.desc(), WorldChunkRevision.id.desc())
|
||||
.limit(limit)
|
||||
)
|
||||
return list(result.scalars().all())
|
||||
|
||||
async def migrate(self) -> None:
|
||||
"""No-op. `world.md` §4.8's hand-rolled SQLite migration runner is
|
||||
superseded by Alembic (`backend/alembic/`) now that content lives
|
||||
in Postgres (world_persistence_impl.md §3.3). Kept only so this
|
||||
class's shape still matches the §5.1 interface it's implementing
|
||||
a subset of."""
|
||||
return None
|
||||
|
||||
# ── internals ────────────────────────────────────────────────────────
|
||||
|
||||
async def _record_revision(
|
||||
self,
|
||||
chunk_key: str,
|
||||
world_id: int,
|
||||
revision: int,
|
||||
action: str,
|
||||
actor_id: int | None,
|
||||
checksum_hex: str,
|
||||
payload_bytes: bytes | None,
|
||||
) -> None:
|
||||
"""Append an audit row and enforce the retention policy
|
||||
(world_persistence_impl.md §4.3, required): keep the newest
|
||||
``WORLD_CHUNK_REVISION_KEEP`` payloads per ``chunk_key``, null out
|
||||
``payload`` on older rows, in the same transaction as the write."""
|
||||
rev = WorldChunkRevision(
|
||||
chunk_key=chunk_key, world_id=world_id, revision=revision, action=action,
|
||||
actor_id=actor_id, checksum=checksum_hex, payload=payload_bytes,
|
||||
)
|
||||
self.db.add(rev)
|
||||
await self.db.flush()
|
||||
|
||||
keep = settings.WORLD_CHUNK_REVISION_KEEP
|
||||
keep_ids_result = await self.db.execute(
|
||||
select(WorldChunkRevision.id)
|
||||
.where(WorldChunkRevision.chunk_key == chunk_key)
|
||||
.order_by(WorldChunkRevision.id.desc())
|
||||
.limit(keep)
|
||||
)
|
||||
keep_ids = [row[0] for row in keep_ids_result.all()]
|
||||
if keep_ids:
|
||||
await self.db.execute(
|
||||
update(WorldChunkRevision)
|
||||
.where(
|
||||
WorldChunkRevision.chunk_key == chunk_key,
|
||||
WorldChunkRevision.id.notin_(keep_ids),
|
||||
WorldChunkRevision.payload.isnot(None),
|
||||
)
|
||||
.values(payload=None)
|
||||
)
|
||||
Reference in New Issue
Block a user