cultnet-py: error_message builder and closed-code/full-key validation in parse_message
Some checks failed
CultMesh QUIC native / Build win32-x64 (pull_request) Has been skipped
CultMesh QUIC native / Build linux-x64 (pull_request) Has been skipped
CultMesh QUIC native / Release native binaries (pull_request) Has been skipped
CultMesh portability and performance / ubuntu-latest one-command multiplayer onboarding (pull_request) Has been cancelled
CultMesh portability and performance / windows-latest one-command multiplayer onboarding (pull_request) Has been cancelled
CultMesh portability and performance / ubuntu-latest reactive semantics and leases (pull_request) Has been cancelled
CultMesh portability and performance / windows-latest reactive semantics and leases (pull_request) Has been cancelled
CultNet cross-runtime interop / C# / TypeScript / Rust / Python / Kotlin (pull_request) Has been cancelled
CultMesh QUIC native / Verify committed binaries match SHA256SUMS (pull_request) Has been cancelled

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
Libby 2026-11-06 19:45:52 +00:00
commit 3250ba49d3
3 changed files with 169 additions and 0 deletions

View file

@ -38,6 +38,7 @@ from .cultmesh_contracts import (
)
from .framing import decode_frame, encode_frame, read_frame, write_frame
from .messages import (
CULTNET_ERROR_CODES,
CultNetMessage,
CultNetWitnessArtifactBundle,
compute_simulation_claim_hash,
@ -47,6 +48,7 @@ from .messages import (
document_delete,
document_put_raw,
encode_witness_artifact_bundle_payload,
error_message,
hello,
login,
login_success,
@ -165,6 +167,7 @@ __all__ = [
"simulation_fact_document",
"verse_catalog_request",
"verse_from_wire",
"CULTNET_ERROR_CODES",
"CultNetMessage",
"CultNetWitnessArtifactBundle",
"CultNetDatabaseSubscription",
@ -247,6 +250,7 @@ __all__ = [
"encode_witness_artifact_bundle_payload",
"encode_frame",
"encode_rudp_packet",
"error_message",
"hello",
"INTEROP_WIRE_CONTRACT",
"login",

View file

@ -28,9 +28,61 @@ def parse_message(payload: bytes) -> CultNetMessage:
raise ValueError("CultNet schema-v0 messages must declare schemaVersion")
body = dict(decoded)
del body["schemaVersion"]
if schema_version == "cultnet.error.v0":
_validate_error_body(body)
return CultNetMessage(schema_version=schema_version, body=body)
# Closed refusal-code set of cultnet.error.v0 (contracts/cultnet/cultnet.error.schema.json). Adding a
# code is one coordinated change across every runtime; a peer refuses a code it does not know.
CULTNET_ERROR_CODES: tuple[str, ...] = (
"selection_invalid",
"cursor_stale",
"cursor_invalid",
"reference_outside_target",
"variant_unsupported",
"unowned_schema",
"write_not_authorized",
)
_ERROR_DETAILS_KEYS = ("field", "value", "asOf", "current")
def _is_uint(value: Any) -> bool:
return isinstance(value, int) and not isinstance(value, bool) and value >= 0
def _validate_error_body(body: dict[str, Any]) -> None:
"""Refuse a cultnet.error.v0 body that is not the full-key shape the schema requires."""
expected = ("error", "routingHint", "code", "details")
if set(body) != set(expected):
raise ValueError(f"cultnet.error.v0 must carry exactly {list(expected)}, got {sorted(body)}")
if not isinstance(body["error"], str) or not body["error"]:
raise ValueError("cultnet.error.v0 error must be a non-empty string")
code = body["code"]
if code is not None and (not isinstance(code, str) or code not in CULTNET_ERROR_CODES):
raise ValueError(f"cultnet.error.v0 code {code!r} is not a recognized refusal code")
hint = body["routingHint"]
if hint is not None:
if (
not isinstance(hint, dict)
or set(hint) != {"shard", "reason"}
or not isinstance(hint["reason"], str)
or not (hint["shard"] is None or isinstance(hint["shard"], dict))
):
raise ValueError("cultnet.error.v0 routingHint must be null or {shard, reason}")
details = body["details"]
if details is not None:
if not isinstance(details, dict) or set(details) != set(_ERROR_DETAILS_KEYS):
raise ValueError(f"cultnet.error.v0 details must be null or carry exactly {list(_ERROR_DETAILS_KEYS)}")
for key in ("field", "value"):
if details[key] is not None and not isinstance(details[key], str):
raise ValueError(f"cultnet.error.v0 details.{key} must be a string or null")
for key in ("asOf", "current"):
if details[key] is not None and not _is_uint(details[key]):
raise ValueError(f"cultnet.error.v0 details.{key} must be a non-negative integer or null")
def hello(
*,
runtime_id: str,
@ -99,6 +151,29 @@ def verify_session(
)
def error_message(
error: str,
*,
code: str | None = None,
details: dict[str, Any] | None = None,
routing_hint: dict[str, Any] | None = None,
) -> CultNetMessage:
"""Build cultnet.error.v0 with every key written (nil included), as the C# map formatter does.
``details`` may name any of field/value/asOf/current; the rest are written as null.
"""
body = {
"error": error,
"routingHint": routing_hint,
"code": code,
"details": None if details is None else {key: details.get(key) for key in _ERROR_DETAILS_KEYS},
}
if details is not None and set(details) - set(_ERROR_DETAILS_KEYS):
raise ValueError(f"cultnet.error.v0 details has unknown keys {sorted(set(details) - set(_ERROR_DETAILS_KEYS))}")
_validate_error_body(body)
return CultNetMessage("cultnet.error.v0", body)
def login_success(
*,
nonce: str,

View file

@ -0,0 +1,90 @@
from __future__ import annotations
import json
import unittest
from pathlib import Path
import msgpack
from cultnet_py import CULTNET_ERROR_CODES, error_message, parse_message
# contracts/cultnet/interop/error-vectors.json: bytes captured from MessagePack C# 3.1.7 and pinned
# by cultnet-rs/tests/error_message.rs (Rust encodes to exactly these bytes).
_REPO = Path(__file__).resolve().parents[3]
_VECTORS = json.loads((_REPO / "contracts/cultnet/interop/error-vectors.json").read_text(encoding="utf-8"))["vectors"]
_SCHEMA = json.loads((_REPO / "contracts/cultnet/cultnet.error.schema.json").read_text(encoding="utf-8"))
class CultNetErrorMessageTests(unittest.TestCase):
def test_closed_code_set_equals_the_schema_enum(self) -> None:
schema_codes = [c for c in _SCHEMA["properties"]["code"]["enum"] if c is not None]
self.assertEqual(sorted(CULTNET_ERROR_CODES), sorted(schema_codes))
def test_vectors_cover_every_code(self) -> None:
self.assertEqual({v["message"]["code"] for v in _VECTORS}, set(CULTNET_ERROR_CODES))
def test_decodes_csharp_and_rust_written_bytes_with_every_key(self) -> None:
for vector in _VECTORS:
message = parse_message(bytes.fromhex(vector["messagePackHex"]))
self.assertEqual(message.to_wire(), vector["message"], vector["name"])
self.assertEqual(
list(message.to_wire()), ["schemaVersion", "error", "routingHint", "code", "details"], vector["name"]
)
def test_reencode_is_byte_identical(self) -> None:
for vector in _VECTORS:
expected = bytes.fromhex(vector["messagePackHex"])
self.assertEqual(parse_message(expected).to_bytes(), expected, vector["name"])
def test_builder_produces_the_csharp_bytes(self) -> None:
by_name = {v["name"]: bytes.fromhex(v["messagePackHex"]) for v in _VECTORS}
stale = error_message(
"cursor_stale: cursor is stale", code="cursor_stale", details={"asOf": 1, "current": 2}
)
self.assertEqual(stale.to_bytes(), by_name["cursor_stale"])
invalid = error_message("cursor_invalid: cannot parse cursor", code="cursor_invalid")
self.assertEqual(invalid.to_bytes(), by_name["cursor_invalid"])
selection = error_message(
"selection_invalid: blank key entry",
code="selection_invalid",
details={"field": "keys", "value": " "},
)
self.assertEqual(selection.to_bytes(), by_name["selection_invalid_field_value"])
def test_builder_writes_nil_keys_and_accepts_a_null_code(self) -> None:
wire = error_message("boom").to_wire()
self.assertEqual(wire, {"schemaVersion": "cultnet.error.v0", "error": "boom", "routingHint": None, "code": None, "details": None})
def test_unknown_code_is_refused_by_builder_and_decoder(self) -> None:
with self.assertRaises(ValueError):
error_message("x", code="unsupported_schema_version")
bad = msgpack.packb(
{"schemaVersion": "cultnet.error.v0", "error": "x", "routingHint": None, "code": "nope", "details": None},
use_bin_type=True,
)
with self.assertRaises(ValueError):
parse_message(bad)
def test_dropping_code_or_details_is_refused(self) -> None:
vector = next(v for v in _VECTORS if v["name"] == "cursor_stale")
for dropped in ("code", "details", "routingHint"):
wire = dict(vector["message"])
del wire[dropped]
with self.assertRaises(ValueError, msg=dropped):
parse_message(msgpack.packb(wire, use_bin_type=True))
def test_malformed_details_are_refused(self) -> None:
base = dict(next(v for v in _VECTORS if v["name"] == "cursor_stale")["message"])
for details in (
{"field": None, "value": None, "asOf": 1},
{"field": None, "value": None, "asOf": -1, "current": 2},
{"field": None, "value": None, "asOf": 1, "current": 2, "extra": 1},
):
with self.assertRaises(ValueError, msg=str(details)):
parse_message(msgpack.packb({**base, "details": details}, use_bin_type=True))
with self.assertRaises(ValueError):
error_message("x", code="cursor_stale", details={"asOf": 1, "bogus": 2})
if __name__ == "__main__":
unittest.main()