From 420e91f4f95808fa1db08f7a5276d3425131973c Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Sat, 27 Jun 2026 23:44:06 +0100 Subject: [PATCH] Add Python publication document sync --- .../cultcache-py/src/cultmesh_py/__init__.py | 10 +- .../cultcache-py/src/cultmesh_py/facade.py | 28 +++- packages/cultcache-py/src/cultmesh_py/node.py | 67 +++++++++ packages/cultcache-py/tests/test_cultcache.py | 130 ++++++++++++++++++ 4 files changed, 233 insertions(+), 2 deletions(-) diff --git a/packages/cultcache-py/src/cultmesh_py/__init__.py b/packages/cultcache-py/src/cultmesh_py/__init__.py index faf39479..0667ab77 100644 --- a/packages/cultcache-py/src/cultmesh_py/__init__.py +++ b/packages/cultcache-py/src/cultmesh_py/__init__.py @@ -10,7 +10,14 @@ from .client import ( ) from .daemon import READY_SCHEMA_VERSION, daemon_ready_document from .facade import CultMesh, CultMeshRudpEndpoint -from .node import CultMeshDatabase, CultMeshDatabaseChange, CultMeshNode, CultMeshNodeOptions, create_node +from .node import ( + CultMeshDatabase, + CultMeshDatabaseChange, + CultMeshDocumentPublicationSource, + CultMeshNode, + CultMeshNodeOptions, + create_node, +) from .server import CultMeshLocalServer from .session import ( CultMeshGameSession, @@ -56,6 +63,7 @@ __all__ = [ "CultMeshNodeOptions", "CultMeshDatabase", "CultMeshDatabaseChange", + "CultMeshDocumentPublicationSource", "CultMesh", "CultMeshGameSession", "CultMeshGameSessionOptions", diff --git a/packages/cultcache-py/src/cultmesh_py/facade.py b/packages/cultcache-py/src/cultmesh_py/facade.py index 849d8a7a..5feab180 100644 --- a/packages/cultcache-py/src/cultmesh_py/facade.py +++ b/packages/cultcache-py/src/cultmesh_py/facade.py @@ -22,7 +22,7 @@ from cultnet_py import ( ) from .client import CultMeshDocumentSubscription, CultMeshPeerExchangeClient, CultMeshVerseDiscoveryClient -from .node import CultMeshNode, CultMeshNodeOptions, create_node +from .node import CultMeshDocumentPublicationSource, CultMeshNode, CultMeshNodeOptions, create_node from .server import CultMeshLocalServer from .session import CultMeshGameSession, CultMeshGameSessionOptions from .simulation import CultMeshSimulationFactCommitter @@ -292,6 +292,32 @@ class CultMesh: shard_epoch=shard_epoch, ) + @staticmethod + def publication_source_from_peer_snapshot( + client: CultNetRawClient, + *, + shard_id: str | None = None, + shard_epoch: int | None = None, + ) -> CultMeshDocumentPublicationSource: + return CultMeshDocumentPublicationSource.peer_snapshot( + client, + shard_id=shard_id, + shard_epoch=shard_epoch, + ) + + @staticmethod + def publication_source_from_single_file(path: str | Path) -> CultMeshDocumentPublicationSource: + return CultMeshDocumentPublicationSource.single_file(path) + + @staticmethod + def sync_document_from_publication( + node: CultMeshNode, + source: CultMeshDocumentPublicationSource, + document: DocumentDefinition[Any], + key: str, + ) -> Any: + return node.sync_document_from_publication(source, document, key) + @staticmethod def subscribe_document( node: CultMeshNode, diff --git a/packages/cultcache-py/src/cultmesh_py/node.py b/packages/cultcache-py/src/cultmesh_py/node.py index 53e175c7..59d49c9a 100644 --- a/packages/cultcache-py/src/cultmesh_py/node.py +++ b/packages/cultcache-py/src/cultmesh_py/node.py @@ -37,6 +37,33 @@ class CultMeshDatabaseChange: previous_value: Any | None = None +@dataclass(frozen=True) +class CultMeshDocumentPublicationSource: + kind: str + client: CultNetRawClient | None = None + path: Path | None = None + shard_id: str | None = None + shard_epoch: int | None = None + + @staticmethod + def peer_snapshot( + client: CultNetRawClient, + *, + shard_id: str | None = None, + shard_epoch: int | None = None, + ) -> "CultMeshDocumentPublicationSource": + return CultMeshDocumentPublicationSource( + kind="peer_snapshot", + client=client, + shard_id=shard_id, + shard_epoch=shard_epoch, + ) + + @staticmethod + def single_file(path: str | Path) -> "CultMeshDocumentPublicationSource": + return CultMeshDocumentPublicationSource(kind="single_file", path=Path(path)) + + @dataclass class CultMeshNode: cache: CultCache = field(default_factory=CultCache) @@ -197,6 +224,14 @@ class CultMeshNode: shard_epoch=shard_epoch, ) + def sync_document_from_publication( + self, + source: CultMeshDocumentPublicationSource, + document: DocumentDefinition[Any], + key: str, + ) -> Any: + return self.database.sync_document_from_publication(source, document, key) + def sync_shard_log( self, client: CultNetRawClient, @@ -670,6 +705,38 @@ class CultMeshDatabase: ) return self.get_required(requested, key) + def sync_document_from_publication( + self, + source: CultMeshDocumentPublicationSource, + document: DocumentDefinition[Any], + key: str, + ) -> Any: + if not key: + raise ValueError("key must be non-empty") + if source.kind == "peer_snapshot": + if source.client is None: + raise ValueError("peer snapshot publication sources require a client") + return self.sync_document( + source.client, + document, + key, + shard_id=source.shard_id, + shard_epoch=source.shard_epoch, + ) + if source.kind == "single_file": + if source.path is None: + raise ValueError("single-file publication sources require a path") + registered = self._resolve_document_alias(document) + cache = CultCache() + cache.register_document_type(registered) + cache.add_generic_store(SingleFileMessagePackBackingStore(source.path)) + cache.pull_all_backing_stores() + value = cache.get_required(registered, key) + requested = self._convert_document_value(value, registered, document) + self.put(document, key, requested) + return self.get_required(document, key) + raise ValueError(f"Unsupported CultMesh document publication source: {source.kind!r}") + def sync_shard_log( self, client: CultNetRawClient, diff --git a/packages/cultcache-py/tests/test_cultcache.py b/packages/cultcache-py/tests/test_cultcache.py index bc27892f..ecd839f2 100644 --- a/packages/cultcache-py/tests/test_cultcache.py +++ b/packages/cultcache-py/tests/test_cultcache.py @@ -2136,6 +2136,136 @@ class CultCacheTests(unittest.TestCase): }, ]) + def test_cultmesh_node_sync_document_from_publication_returns_requested_alias_type(self) -> None: + @dataclass + class CanonicalNote: + body: str + + @dataclass + class UiNote: + body: str + + document = define_database_entry_type( + "mesh.publication_alias_note", + [("body", 0)], + cls=CanonicalNote, + schema_id="mesh.publication_alias_note.v1", + schema_name="mesh.publication_alias_note", + schema_version="mesh.publication_alias_note.v1", + ) + alias = define_database_entry_type( + "mesh.publication_alias_note.ui", + [("body", 0)], + cls=UiNote, + schema_id="mesh.publication_alias_note.v1", + schema_name="mesh.publication_alias_note", + schema_version="mesh.publication_alias_note.v1", + ) + node = create_node(runtime_id="python-publication-node") + node.register_document(document) + requests: list[dict[str, Any]] = [] + + class SnapshotClient: + def fetch_snapshot_response( + self, + *, + schema_ids: list[str] | None = None, + record_keys: list[str] | None = None, + shard_id: str | None = None, + shard_epoch: int | None = None, + ) -> dict[str, Any]: + requests.append({ + "schema_ids": schema_ids, + "record_keys": record_keys, + "shard_id": shard_id, + "shard_epoch": shard_epoch, + }) + return { + "schemaVersion": "cultnet.snapshot_response_raw.v0", + "messageId": "publication-sync-document", + "documents": [ + { + "schemaId": document.catalog_entry().schema_id, + "recordKey": "note:published-peer", + "storedAt": "2026-06-27T00:00:00Z", + "payloadEncoding": "messagepack", + "payload": document.encode_payload(CanonicalNote("peer-publication-alias")), + } + ], + } + + source = CultMesh.publication_source_from_peer_snapshot( + SnapshotClient(), + shard_id="notes", + shard_epoch=3, + ) + + synced = node.sync_document_from_publication(source, alias, "note:published-peer") + facade_synced = CultMesh.sync_document_from_publication(node, source, alias, "note:published-peer") + + self.assertIsInstance(synced, UiNote) + self.assertEqual(synced.body, "peer-publication-alias") + self.assertIsInstance(facade_synced, UiNote) + self.assertEqual(facade_synced.body, "peer-publication-alias") + self.assertEqual(node.get_required(document, "note:published-peer").body, "peer-publication-alias") + self.assertEqual(requests, [ + { + "schema_ids": ["mesh.publication_alias_note.v1"], + "record_keys": ["note:published-peer"], + "shard_id": "notes", + "shard_epoch": 3, + }, + { + "schema_ids": ["mesh.publication_alias_note.v1"], + "record_keys": ["note:published-peer"], + "shard_id": "notes", + "shard_epoch": 3, + }, + ]) + + def test_cultmesh_node_sync_document_from_single_file_publication_uses_node_aliases(self) -> None: + @dataclass + class CanonicalNote: + body: str + + @dataclass + class UiNote: + body: str + + document = define_database_entry_type( + "mesh.file_publication_alias_note", + [("body", 0)], + cls=CanonicalNote, + schema_id="mesh.file_publication_alias_note.v1", + schema_name="mesh.file_publication_alias_note", + schema_version="mesh.file_publication_alias_note.v1", + ) + alias = define_database_entry_type( + "mesh.file_publication_alias_note.ui", + [("body", 0)], + cls=UiNote, + schema_id="mesh.file_publication_alias_note.v1", + schema_name="mesh.file_publication_alias_note", + schema_version="mesh.file_publication_alias_note.v1", + ) + with tempfile.TemporaryDirectory() as tmp: + path = Path(tmp) / "publication.ccmp" + writer = CultCache() + writer.register_document_type(document) + writer.add_generic_store(SingleFileMessagePackBackingStore(path)) + writer.put(document, "note:published-file", CanonicalNote("file-publication-alias")) + + node = create_node(runtime_id="python-file-publication-node") + node.register_document(document) + source = CultMesh.publication_source_from_single_file(path) + + synced = CultMesh.sync_document_from_publication(node, source, alias, "note:published-file") + + self.assertIsInstance(synced, UiNote) + self.assertEqual(synced.body, "file-publication-alias") + self.assertEqual(node.get_required(document, "note:published-file").body, "file-publication-alias") + self.assertIsInstance(node.get_required(alias, "note:published-file"), UiNote) + def test_cultmesh_node_emits_raw_put_and_delete_messages_for_local_writes(self) -> None: document = define_database_entry_type( "mesh.emit_item",