Add Python CultNet subscription change facade

This commit is contained in:
Meta Vens 2026-06-14 04:13:44 +01:00
commit 91f7ac32af
6 changed files with 117 additions and 10 deletions

View file

@ -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.

View file

@ -28,6 +28,7 @@ EXPECTED_EXPORTS: dict[str, tuple[str, ...]] = {
),
"cultnet_py": (
"CultNetAppliedRecord",
"CultNetDatabaseChange",
"CultNetClientAuthorityScope",
"CultNetDatabaseSubscription",
"CultNetMessage",

View file

@ -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",

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 .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

View file

@ -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

View file

@ -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: