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
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:
parent
03b31f1f68
commit
3250ba49d3
3 changed files with 169 additions and 0 deletions
|
|
@ -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",
|
||||
|
|
|
|||
|
|
@ -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,
|
||||
|
|
|
|||
90
packages/cultnet-py/tests/test_cultnet_error.py
Normal file
90
packages/cultnet-py/tests/test_cultnet_error.py
Normal 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()
|
||||
Loading…
Reference in a new issue