Add Python CultNet raw snapshot facade
This commit is contained in:
parent
91f7ac32af
commit
5886bde804
6 changed files with 190 additions and 1 deletions
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -33,6 +33,8 @@ EXPECTED_EXPORTS: dict[str, tuple[str, ...]] = {
|
|||
"CultNetDatabaseSubscription",
|
||||
"CultNetMessage",
|
||||
"CultNetRawClient",
|
||||
"CultNetRawDocumentRecord",
|
||||
"CultNetRawSnapshotResponse",
|
||||
"CultNetSchemaCatalog",
|
||||
"CultNetSchemaDescriptor",
|
||||
"CultNetShardCatalog",
|
||||
|
|
|
|||
|
|
@ -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",
|
||||
|
|
|
|||
|
|
@ -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,
|
||||
*,
|
||||
|
|
|
|||
123
packages/cultcache-py/src/cultnet_py/snapshot.py
Normal file
123
packages/cultcache-py/src/cultnet_py/snapshot.py
Normal 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)
|
||||
|
|
@ -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])
|
||||
|
|
|
|||
Loading…
Reference in a new issue