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.
|
||||
Reference in New Issue
Block a user