Add Python CultNet raw snapshot facade

This commit is contained in:
Meta Vens 2026-06-14 04:21:05 +01:00
commit 5886bde804
6 changed files with 190 additions and 1 deletions

View file

@ -14,6 +14,10 @@ CultCache, CultNet, and CultMesh. It is evidence, not confetti.
- Python CultNet raw client:
Fetches schema catalogs, raw snapshots, shard catalogs, shard logs, and live
database subscription changes.
- Python CultNet raw snapshot:
Provides typed `CultNetRawSnapshotResponse` and `CultNetRawDocumentRecord`
helpers plus `CultNetRawClient.fetch_snapshot_response(...)` for inspecting
peer snapshots before handing them to the existing replication helpers.
- Python CultNet schema catalog:
Exposes shared wire-message schema descriptors from the package surface so
both the interop peer and CultMesh local server describe the CultNet/CultMesh

View file

@ -33,6 +33,8 @@ EXPECTED_EXPORTS: dict[str, tuple[str, ...]] = {
"CultNetDatabaseSubscription",
"CultNetMessage",
"CultNetRawClient",
"CultNetRawDocumentRecord",
"CultNetRawSnapshotResponse",
"CultNetSchemaCatalog",
"CultNetSchemaDescriptor",
"CultNetShardCatalog",

View file

@ -36,6 +36,7 @@ from .schema_catalog import (
)
from .shard_catalog import CultNetShardCatalog, CultNetShardDescriptor
from .shard_log import CultNetShardLogEntry, CultNetShardLogResponse
from .snapshot import CultNetRawDocumentRecord, CultNetRawSnapshotResponse
from .subscription import CultNetDatabaseChange
from .simulation import (
CultNetSimulationConsensus,
@ -54,6 +55,8 @@ __all__ = [
"CultNetShardDescriptor",
"CultNetShardLogEntry",
"CultNetShardLogResponse",
"CultNetRawDocumentRecord",
"CultNetRawSnapshotResponse",
"CultNetAppliedRecord",
"CultNetClientAuthorityScope",
"CultNetSimulationConsensus",

View file

@ -19,6 +19,7 @@ from .messages import (
from .schema_catalog import CultNetSchemaCatalog, CultNetSchemaDescriptor
from .shard_catalog import CultNetShardCatalog, CultNetShardDescriptor
from .shard_log import CultNetShardLogResponse
from .snapshot import CultNetRawSnapshotResponse
from .subscription import CultNetDatabaseChange
@ -114,6 +115,23 @@ class CultNetRawClient:
expected_schema_version="cultnet.snapshot_response_raw.v0",
)
def fetch_snapshot_response(
self,
*,
message_id: str = "cultnet-python-snapshot",
schema_ids: list[str] | None = None,
record_keys: list[str] | None = None,
shard_id: str | None = None,
shard_epoch: int | None = None,
) -> CultNetRawSnapshotResponse:
return CultNetRawSnapshotResponse.from_wire(self.fetch_snapshot(
message_id=message_id,
schema_ids=schema_ids,
record_keys=record_keys,
shard_id=shard_id,
shard_epoch=shard_epoch,
))
def fetch_shard_catalog(
self,
*,

View file

@ -0,0 +1,123 @@
from __future__ import annotations
from dataclasses import dataclass
from typing import Any
@dataclass(frozen=True)
class CultNetRawDocumentRecord:
schema_id: str
record_key: str
payload: bytes
stored_at: str | None = None
payload_encoding: str = "messagepack"
source_runtime_id: str | None = None
source_agent_id: str | None = None
source_role: str | None = None
tags: tuple[str, ...] = ()
@classmethod
def from_wire(cls, value: dict[str, Any]) -> "CultNetRawDocumentRecord":
schema_id = str(value.get("schemaId") or "")
record_key = str(value.get("recordKey") or "")
if not schema_id:
raise ValueError("raw document record schemaId must be non-empty")
if not record_key:
raise ValueError("raw document record recordKey must be non-empty")
return cls(
schema_id=schema_id,
record_key=record_key,
payload=bytes(value.get("payload") or b""),
stored_at=_optional_string(value.get("storedAt")),
payload_encoding=str(value.get("payloadEncoding") or "messagepack"),
source_runtime_id=_optional_string(value.get("sourceRuntimeId")),
source_agent_id=_optional_string(value.get("sourceAgentId")),
source_role=_optional_string(value.get("sourceRole")),
tags=tuple(str(tag) for tag in value.get("tags") or ()),
)
def to_wire(self) -> dict[str, Any]:
wire: dict[str, Any] = {
"schemaId": self.schema_id,
"recordKey": self.record_key,
"payloadEncoding": self.payload_encoding,
"payload": self.payload,
}
if self.stored_at is not None:
wire["storedAt"] = self.stored_at
if self.source_runtime_id is not None:
wire["sourceRuntimeId"] = self.source_runtime_id
if self.source_agent_id is not None:
wire["sourceAgentId"] = self.source_agent_id
if self.source_role is not None:
wire["sourceRole"] = self.source_role
if self.tags:
wire["tags"] = list(self.tags)
return wire
@dataclass(frozen=True)
class CultNetRawSnapshotResponse:
message_id: str
documents: tuple[CultNetRawDocumentRecord, ...]
shard_id: str | None = None
shard_epoch: int | None = None
shard_log_sequence: int | None = None
@classmethod
def from_wire(cls, response: dict[str, Any]) -> "CultNetRawSnapshotResponse":
if response.get("schemaVersion") != "cultnet.snapshot_response_raw.v0":
raise ValueError(f"Expected cultnet.snapshot_response_raw.v0, received {response.get('schemaVersion')!r}")
return cls(
message_id=str(response.get("messageId") or ""),
documents=tuple(
CultNetRawDocumentRecord.from_wire(document)
for document in response.get("documents") or ()
if isinstance(document, dict)
),
shard_id=_optional_string(response.get("shardId")),
shard_epoch=_optional_int(response.get("shardEpoch")),
shard_log_sequence=_optional_int(response.get("shardLogSequence")),
)
def filter(
self,
*,
schema_ids: list[str] | None = None,
record_keys: list[str] | None = None,
) -> tuple[CultNetRawDocumentRecord, ...]:
requested_schema_ids = set(schema_ids or [])
requested_record_keys = set(record_keys or [])
return tuple(
document
for document in self.documents
if (not requested_schema_ids or document.schema_id in requested_schema_ids)
and (not requested_record_keys or document.record_key in requested_record_keys)
)
def to_wire(self) -> dict[str, Any]:
wire: dict[str, Any] = {
"schemaVersion": "cultnet.snapshot_response_raw.v0",
"messageId": self.message_id,
"documents": [document.to_wire() for document in self.documents],
}
if self.shard_id is not None:
wire["shardId"] = self.shard_id
if self.shard_epoch is not None:
wire["shardEpoch"] = self.shard_epoch
if self.shard_log_sequence is not None:
wire["shardLogSequence"] = self.shard_log_sequence
return wire
def _optional_string(value: Any) -> str | None:
if value is None:
return None
text = str(value)
return text if text else None
def _optional_int(value: Any) -> int | None:
if value is None:
return None
return int(value)

View file

@ -25,6 +25,8 @@ from cultnet_py import (
CultNetDatabaseChange,
CultNetClientAuthorityScope,
CultNetRawClient,
CultNetRawDocumentRecord,
CultNetRawSnapshotResponse,
CultNetSchemaCatalog,
CultNetSchemaDescriptor,
CultNetShardCatalog,
@ -429,6 +431,38 @@ class CultCacheTests(unittest.TestCase):
self.assertEqual(snapshot["shardId"], "interop")
self.assertEqual(snapshot["shardEpoch"], 1)
def test_cultnet_raw_snapshot_response_filters_and_roundtrips_records(self) -> None:
response = CultNetRawSnapshotResponse.from_wire({
"schemaVersion": "cultnet.snapshot_response_raw.v0",
"messageId": "snapshot-1",
"shardId": "notes",
"shardEpoch": 3,
"shardLogSequence": 8,
"documents": [
CultNetRawDocumentRecord(
schema_id="schema-note",
record_key="note:1",
stored_at="2026-06-14T00:00:00Z",
payload=b"note",
source_runtime_id="python-test",
tags=("snapshot",),
).to_wire(),
{
"schemaId": "schema-fact",
"recordKey": "fact:1",
"payloadEncoding": "messagepack",
"payload": b"fact",
},
],
})
self.assertEqual(response.shard_id, "notes")
self.assertEqual(response.shard_epoch, 3)
self.assertEqual(response.shard_log_sequence, 8)
self.assertEqual(response.documents[0].source_runtime_id, "python-test")
self.assertEqual(response.filter(schema_ids=["schema-note"])[0].record_key, "note:1")
self.assertEqual(response.filter(record_keys=["fact:1"])[0].schema_id, "schema-fact")
self.assertEqual(response.to_wire()["documents"][0]["tags"], ["snapshot"])
def test_cultnet_raw_client_fetches_schema_snapshot_and_shard_reads(self) -> None:
import msgpack # type: ignore
from cultnet_py import read_frame, write_frame
@ -496,7 +530,9 @@ class CultCacheTests(unittest.TestCase):
client = CultNetRawClient("127.0.0.1", port_holder[0], timeout_seconds=2.0)
self.assertEqual(client.fetch_schema_catalog(kinds=["wire_message"])["schemaVersion"], "cultnet.schema_catalog_response.v0")
self.assertEqual(client.fetch_snapshot(shard_id="interop", shard_epoch=1)["schemaVersion"], "cultnet.snapshot_response_raw.v0")
typed_snapshot = client.fetch_snapshot_response(shard_id="interop", shard_epoch=1)
self.assertEqual(typed_snapshot.shard_id, None)
self.assertEqual(typed_snapshot.documents, ())
shard_catalog = CultNetShardCatalog()
synced_shards = client.sync_shard_catalog(shard_catalog, schema_ids=["schema-a"])
self.assertEqual(synced_shards[0].shard_id, "interop")
@ -1835,6 +1871,7 @@ class CultCacheTests(unittest.TestCase):
include_schema_json=True,
)
snapshot_response = raw_client.fetch_snapshot(schema_ids=["mesh.server_note.v1"])
typed_snapshot_response = raw_client.fetch_snapshot_response(schema_ids=["mesh.server_note.v1"])
shard_catalog = raw_client.fetch_shard_catalog(schema_ids=["mesh.server_note.v1"])
synced_shard_catalog = CultNetShardCatalog()
synced_shards = raw_client.sync_shard_catalog(synced_shard_catalog, schema_ids=["mesh.server_note.v1"])
@ -1879,6 +1916,8 @@ class CultCacheTests(unittest.TestCase):
self.assertIn("cultnet.document_put_raw.v0", {descriptor.schema_version for descriptor in synced_wire_descriptors})
self.assertIsNotNone(synced_schema_catalog.get("https://github.com/GameCult/cultnet-ts/contracts/cultnet.document-put-raw.schema.json"))
self.assertEqual(snapshot_response["documents"][0]["recordKey"], "note:1")
self.assertEqual(typed_snapshot_response.documents[0].record_key, "note:1")
self.assertEqual(typed_snapshot_response.documents[0].schema_id, "mesh.server_note.v1")
self.assertEqual(shard_catalog["shards"][0]["schemaIds"], ["mesh.server_note.v1"])
self.assertEqual(synced_shards[0].shard_id, "primary")
self.assertEqual(synced_shard_catalog.get("primary"), synced_shards[0])