diff --git a/packages/cultcache-py/PARITY.md b/packages/cultcache-py/PARITY.md index c4a4f047..33b45bf0 100644 --- a/packages/cultcache-py/PARITY.md +++ b/packages/cultcache-py/PARITY.md @@ -30,6 +30,11 @@ CultCache, CultNet, and CultMesh. It is evidence, not confetti. Provides typed `CultNetShardLogResponse` and `CultNetShardLogEntry` helpers for inspecting mutation-log entries, resync pressure, and sequence cursors, while cache mutation remains owned by the existing replication helpers. +- Python CultNet database subscription changes: + Provides typed `CultNetDatabaseChange` parsing plus + `CultNetDatabaseSubscription.read_next_change(...)` / `iter_changes(...)` for + live raw database subscriptions. Snapshot frames remain raw and feed the + existing snapshot replication helpers. - Python CultMesh discovery client: Fetches Verse catalogs and peer exchange responses from the live Python endpoint over CultNet frames. diff --git a/packages/cultcache-py/src/cultcache_py/verify.py b/packages/cultcache-py/src/cultcache_py/verify.py index ddcb62f8..daf410ac 100644 --- a/packages/cultcache-py/src/cultcache_py/verify.py +++ b/packages/cultcache-py/src/cultcache_py/verify.py @@ -28,6 +28,7 @@ EXPECTED_EXPORTS: dict[str, tuple[str, ...]] = { ), "cultnet_py": ( "CultNetAppliedRecord", + "CultNetDatabaseChange", "CultNetClientAuthorityScope", "CultNetDatabaseSubscription", "CultNetMessage", diff --git a/packages/cultcache-py/src/cultnet_py/__init__.py b/packages/cultcache-py/src/cultnet_py/__init__.py index 1d1c355b..34283849 100644 --- a/packages/cultcache-py/src/cultnet_py/__init__.py +++ b/packages/cultcache-py/src/cultnet_py/__init__.py @@ -36,6 +36,7 @@ from .schema_catalog import ( ) from .shard_catalog import CultNetShardCatalog, CultNetShardDescriptor from .shard_log import CultNetShardLogEntry, CultNetShardLogResponse +from .subscription import CultNetDatabaseChange from .simulation import ( CultNetSimulationConsensus, CultNetSimulationConsensusOptions, @@ -45,6 +46,7 @@ from .simulation import ( __all__ = [ "CultNetMessage", "CultNetDatabaseSubscription", + "CultNetDatabaseChange", "CultNetRawClient", "CultNetSchemaCatalog", "CultNetSchemaDescriptor", diff --git a/packages/cultcache-py/src/cultnet_py/client.py b/packages/cultcache-py/src/cultnet_py/client.py index e7a62fa5..092266c6 100644 --- a/packages/cultcache-py/src/cultnet_py/client.py +++ b/packages/cultcache-py/src/cultnet_py/client.py @@ -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 .subscription import CultNetDatabaseChange @dataclass(frozen=True) @@ -271,8 +272,18 @@ class CultNetDatabaseSubscription: raise ValueError(f"Unexpected CultNet subscription message {schema_version!r}") return response + def read_next_change(self) -> CultNetDatabaseChange: + message = self.read_next() + return CultNetDatabaseChange.from_wire(message) + def iter_messages(self, *, max_messages: int | None = None) -> Any: received = 0 while max_messages is None or received < max_messages: yield self.read_next() received += 1 + + def iter_changes(self, *, max_messages: int | None = None) -> Any: + received = 0 + while max_messages is None or received < max_messages: + yield self.read_next_change() + received += 1 diff --git a/packages/cultcache-py/src/cultnet_py/subscription.py b/packages/cultcache-py/src/cultnet_py/subscription.py new file mode 100644 index 00000000..3d5b9b46 --- /dev/null +++ b/packages/cultcache-py/src/cultnet_py/subscription.py @@ -0,0 +1,59 @@ +from __future__ import annotations + +from dataclasses import dataclass +from typing import Any + + +@dataclass(frozen=True) +class CultNetDatabaseChange: + message_id: str + subscription_id: str + change_kind: str + document: dict[str, Any] | None = None + schema_id: str | None = None + record_key: str | None = None + + @classmethod + def from_wire(cls, message: dict[str, Any]) -> "CultNetDatabaseChange": + if message.get("schemaVersion") != "cultnet.database_change_raw.v0": + raise ValueError(f"Expected cultnet.database_change_raw.v0, received {message.get('schemaVersion')!r}") + change_kind = str(message.get("changeKind") or "") + if change_kind not in {"added", "updated", "removed"}: + raise ValueError(f"unsupported database changeKind {change_kind!r}") + document = message.get("document") + document_record = dict(document) if isinstance(document, dict) else None + schema_id = _optional_string(message.get("schemaId")) + record_key = _optional_string(message.get("recordKey")) + if document_record is not None: + schema_id = schema_id or _optional_string(document_record.get("schemaId")) + record_key = record_key or _optional_string(document_record.get("recordKey")) + return cls( + message_id=str(message.get("messageId") or ""), + subscription_id=str(message.get("subscriptionId") or ""), + change_kind=change_kind, + document=document_record, + schema_id=schema_id, + record_key=record_key, + ) + + def to_wire(self) -> dict[str, Any]: + wire: dict[str, Any] = { + "schemaVersion": "cultnet.database_change_raw.v0", + "messageId": self.message_id, + "subscriptionId": self.subscription_id, + "changeKind": self.change_kind, + } + if self.document is not None: + wire["document"] = self.document + if self.schema_id is not None: + wire["schemaId"] = self.schema_id + if self.record_key is not None: + wire["recordKey"] = self.record_key + return wire + + +def _optional_string(value: Any) -> str | None: + if value is None: + return None + text = str(value) + return text if text else None diff --git a/packages/cultcache-py/tests/test_cultcache.py b/packages/cultcache-py/tests/test_cultcache.py index eafdd3ef..bb3282a3 100644 --- a/packages/cultcache-py/tests/test_cultcache.py +++ b/packages/cultcache-py/tests/test_cultcache.py @@ -22,6 +22,7 @@ from cultcache_py.interop import read_note, write_note from cultcache_py.verify import verify from cultnet_py import ( compute_simulation_claim_hash, + CultNetDatabaseChange, CultNetClientAuthorityScope, CultNetRawClient, CultNetSchemaCatalog, @@ -355,6 +356,34 @@ class CultCacheTests(unittest.TestCase): self.assertEqual(unsubscribe["messageId"], "unsub-message") self.assertEqual(unsubscribe["subscriptionId"], "sub-1") + def test_cultnet_database_change_parses_put_and_delete_shapes(self) -> None: + put_change = CultNetDatabaseChange.from_wire({ + "schemaVersion": "cultnet.database_change_raw.v0", + "messageId": "change-put", + "subscriptionId": "sub-1", + "changeKind": "added", + "document": { + "schemaId": "schema-note", + "recordKey": "note:1", + "payload": b"payload", + }, + }) + self.assertEqual(put_change.schema_id, "schema-note") + self.assertEqual(put_change.record_key, "note:1") + self.assertEqual(put_change.to_wire()["document"]["recordKey"], "note:1") + + delete_change = CultNetDatabaseChange.from_wire({ + "schemaVersion": "cultnet.database_change_raw.v0", + "messageId": "change-delete", + "subscriptionId": "sub-1", + "changeKind": "removed", + "schemaId": "schema-note", + "recordKey": "note:1", + }) + self.assertIsNone(delete_change.document) + self.assertEqual(delete_change.schema_id, "schema-note") + self.assertEqual(delete_change.to_wire()["recordKey"], "note:1") + def test_cultnet_raw_put_helper_carries_message_id(self) -> None: put = document_put_raw( message_id="put-1", @@ -561,13 +590,13 @@ class CultCacheTests(unittest.TestCase): with client.subscribe_database(subscription_id="sub-1", schema_ids=[schema_id]) as subscription: snapshot = subscription.read_next() subscription.send(put) - change = subscription.read_next() + change = subscription.read_next_change() thread.join(2.0) self.assertFalse(server_error) self.assertEqual(snapshot["schemaVersion"], "cultnet.snapshot_response_raw.v0") - self.assertEqual(change["schemaVersion"], "cultnet.database_change_raw.v0") - self.assertEqual(change["document"]["recordKey"], "item:sub") + self.assertEqual(change.change_kind, "added") + self.assertEqual(change.record_key, "item:sub") self.assertEqual(received_versions, [ "cultnet.database_subscribe.v0", "cultnet.document_put_raw.v0", @@ -1825,7 +1854,7 @@ class CultCacheTests(unittest.TestCase): shard_id="primary", shard_epoch=1, )) - subscription_change = subscription.read_next() + subscription_change = subscription.read_next_change() subscription.send(document_delete( message_id="server-delete", schema_id="mesh.server_note.v1", @@ -1833,7 +1862,7 @@ class CultCacheTests(unittest.TestCase): shard_id="primary", shard_epoch=1, )) - subscription_delete = subscription.read_next() + subscription_delete = subscription.read_next_change() finally: server.stop() @@ -1859,11 +1888,11 @@ class CultCacheTests(unittest.TestCase): self.assertEqual(fetched_verses[0].verse_id, "server-verse") self.assertEqual(fetched_peers[0].peer_id, "mesh-server") self.assertEqual(subscription_snapshot["schemaVersion"], "cultnet.snapshot_response_raw.v0") - self.assertEqual(subscription_change["schemaVersion"], "cultnet.database_change_raw.v0") - self.assertEqual(subscription_change["changeKind"], "added") - self.assertEqual(subscription_change["document"]["recordKey"], "note:2") - self.assertEqual(subscription_delete["changeKind"], "removed") - self.assertEqual(subscription_delete["recordKey"], "note:2") + self.assertEqual(subscription_change.change_kind, "added") + self.assertEqual(subscription_change.record_key, "note:2") + self.assertEqual(subscription_change.document["recordKey"], "note:2") + self.assertEqual(subscription_delete.change_kind, "removed") + self.assertEqual(subscription_delete.record_key, "note:2") self.assertIsNone(node.database.get(document, "note:2")) def test_cultmesh_authority_lease_requires_live_matching_lease(self) -> None: