Add Python publication document sync

This commit is contained in:
Meta Vens 2026-06-27 23:44:06 +01:00
commit 420e91f4f9
4 changed files with 233 additions and 2 deletions

View file

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

View file

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

View file

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

View file

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