Add Python CultMesh database watchers
This commit is contained in:
parent
c125b0fb20
commit
473bece217
7 changed files with 185 additions and 9 deletions
|
|
@ -24,6 +24,9 @@ CultCache, CultNet, and CultMesh. It is evidence, not confetti.
|
|||
- Python CultMesh database facade:
|
||||
`node.database` owns the local typed document read/write/snapshot/sync surface
|
||||
so Python callers do not need to reach through the node composition wrapper.
|
||||
It also exposes local `watch(...)` / `watch_record(...)` callbacks for database
|
||||
changes, including authoritative shard-log reconciliation applied through the
|
||||
session facade.
|
||||
- Python CultMesh committed simulation facts:
|
||||
The live interop harness sends Python a simulation observation, receives a
|
||||
consensus candidate, then requests the committed `gamecult.mesh.simulation_fact`
|
||||
|
|
|
|||
|
|
@ -224,6 +224,7 @@ from cultmesh_py import CultMesh, CultMeshGameSessionOptions, peer_exchange_requ
|
|||
note_doc = define_database_entry_type("mesh.note", [("body", 0)])
|
||||
node = CultMesh.start_node("mesh.cc", runtime_id="python-runtime")
|
||||
node.database.register_document(note_doc)
|
||||
unsubscribe = node.database.watch_record(note_doc, "note:1", lambda change: print(change.change_kind))
|
||||
node.database.put(note_doc, "note:1", {"body": "hello"})
|
||||
live_note = node.database.get_required(note_doc, "note:1")
|
||||
put_message = node.database.put_raw_message(note_doc, "note:2", {"body": "wire me"}, shard_id="interop", shard_epoch=1)
|
||||
|
|
@ -269,6 +270,7 @@ session = CultMesh.create_game_session(
|
|||
)
|
||||
session_commits = session.submit_and_commit(observation.to_wire())
|
||||
prediction = session.predict(note_doc, "input:python:move", {"body": "predicted input"})
|
||||
unsubscribe()
|
||||
```
|
||||
|
||||
## Wire Parity
|
||||
|
|
|
|||
|
|
@ -30,6 +30,7 @@ EXPECTED_EXPORTS: dict[str, tuple[str, ...]] = {
|
|||
"cultmesh_py": (
|
||||
"CultMesh",
|
||||
"CultMeshDatabase",
|
||||
"CultMeshDatabaseChange",
|
||||
"CultMeshGameSession",
|
||||
"CultMeshPeerExchangeClient",
|
||||
"CultMeshSimulationFact",
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
from .client import CultMeshDiscoveryClient, CultMeshPeerExchangeClient, CultMeshVerseDiscoveryClient
|
||||
from .facade import CultMesh
|
||||
from .node import CultMeshDatabase, CultMeshNode, create_node
|
||||
from .node import CultMeshDatabase, CultMeshDatabaseChange, CultMeshNode, create_node
|
||||
from .session import (
|
||||
CultMeshGameSession,
|
||||
CultMeshGameSessionOptions,
|
||||
|
|
@ -41,6 +41,7 @@ from .wire import (
|
|||
__all__ = [
|
||||
"CultMeshNode",
|
||||
"CultMeshDatabase",
|
||||
"CultMeshDatabaseChange",
|
||||
"CultMesh",
|
||||
"CultMeshGameSession",
|
||||
"CultMeshGameSessionOptions",
|
||||
|
|
|
|||
|
|
@ -2,7 +2,7 @@ from __future__ import annotations
|
|||
|
||||
from dataclasses import dataclass, field
|
||||
from pathlib import Path
|
||||
from typing import Any
|
||||
from typing import Any, Callable
|
||||
|
||||
from cultcache_py import CultCache, CultCacheEnvelope, SingleFileMessagePackBackingStore
|
||||
from cultcache_py.documents import DocumentDefinition
|
||||
|
|
@ -10,13 +10,24 @@ from cultnet_py import (
|
|||
CultNetAppliedRecord,
|
||||
CultNetMessage,
|
||||
CultNetRawClient,
|
||||
apply_raw_snapshot,
|
||||
apply_shard_log_response,
|
||||
apply_raw_snapshot as apply_cultnet_raw_snapshot,
|
||||
apply_shard_log_response as apply_cultnet_shard_log_response,
|
||||
document_delete,
|
||||
document_put_raw,
|
||||
schema_document_map,
|
||||
)
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class CultMeshDatabaseChange:
|
||||
document: DocumentDefinition[Any]
|
||||
schema_id: str
|
||||
record_key: str
|
||||
change_kind: str
|
||||
value: Any | None = None
|
||||
previous_value: Any | None = None
|
||||
|
||||
|
||||
@dataclass
|
||||
class CultMeshNode:
|
||||
cache: CultCache = field(default_factory=CultCache)
|
||||
|
|
@ -122,6 +133,7 @@ class CultMeshNode:
|
|||
class CultMeshDatabase:
|
||||
def __init__(self, node: CultMeshNode) -> None:
|
||||
self._node = node
|
||||
self._subscribers: list[tuple[DocumentDefinition[Any] | None, str | None, Callable[[CultMeshDatabaseChange], None]]] = []
|
||||
|
||||
@property
|
||||
def cache(self) -> CultCache:
|
||||
|
|
@ -135,12 +147,38 @@ class CultMeshDatabase:
|
|||
def runtime_id(self) -> str:
|
||||
return self._node.runtime_id
|
||||
|
||||
def watch(
|
||||
self,
|
||||
callback: Callable[[CultMeshDatabaseChange], None],
|
||||
*,
|
||||
document: DocumentDefinition[Any] | None = None,
|
||||
key: str | None = None,
|
||||
) -> Callable[[], None]:
|
||||
subscriber = (document, key, callback)
|
||||
self._subscribers.append(subscriber)
|
||||
|
||||
def unsubscribe() -> None:
|
||||
if subscriber in self._subscribers:
|
||||
self._subscribers.remove(subscriber)
|
||||
|
||||
return unsubscribe
|
||||
|
||||
def watch_record(
|
||||
self,
|
||||
document: DocumentDefinition[Any],
|
||||
key: str,
|
||||
callback: Callable[[CultMeshDatabaseChange], None],
|
||||
) -> Callable[[], None]:
|
||||
return self.watch(callback, document=document, key=key)
|
||||
|
||||
def register_document(self, document: DocumentDefinition[Any]) -> None:
|
||||
self.cache.register_document_type(document)
|
||||
self.documents.append(document)
|
||||
|
||||
def put(self, document: DocumentDefinition[Any], key: str, value: Any) -> None:
|
||||
previous = self.cache.get(document, key)
|
||||
self.cache.put(document, key, value)
|
||||
self._publish_local_change(document, key, "added" if previous is None else "updated", value, previous)
|
||||
|
||||
def put_raw_message(
|
||||
self,
|
||||
|
|
@ -153,6 +191,7 @@ class CultMeshDatabase:
|
|||
shard_epoch: int | None = None,
|
||||
) -> CultNetMessage:
|
||||
catalog_entry = document.catalog_entry()
|
||||
previous = self.cache.get(document, key)
|
||||
envelope = CultCacheEnvelope.create(
|
||||
key=key,
|
||||
type=document.type,
|
||||
|
|
@ -160,7 +199,8 @@ class CultMeshDatabase:
|
|||
schema_id=catalog_entry.schema_id,
|
||||
catalog_entry=catalog_entry,
|
||||
)
|
||||
self.cache.put_envelope(document, envelope)
|
||||
value = self.cache.put_envelope(document, envelope)
|
||||
self._publish_local_change(document, key, "added" if previous is None else "updated", value, previous)
|
||||
return document_put_raw(
|
||||
message_id=message_id,
|
||||
key=key,
|
||||
|
|
@ -179,7 +219,10 @@ class CultMeshDatabase:
|
|||
return self.cache.get_required(document, key)
|
||||
|
||||
def delete(self, document: DocumentDefinition[Any], key: str) -> None:
|
||||
previous = self.cache.get(document, key)
|
||||
self.cache.delete(document, key)
|
||||
if previous is not None:
|
||||
self._publish_local_change(document, key, "removed", None, previous)
|
||||
|
||||
def delete_raw_message(
|
||||
self,
|
||||
|
|
@ -221,7 +264,7 @@ class CultMeshDatabase:
|
|||
shard_id=shard_id,
|
||||
shard_epoch=shard_epoch,
|
||||
)
|
||||
return apply_raw_snapshot(self.cache, self.documents, response)
|
||||
return self.apply_snapshot_response(response)
|
||||
|
||||
def sync_shard_log(
|
||||
self,
|
||||
|
|
@ -238,7 +281,56 @@ class CultMeshDatabase:
|
|||
after_sequence=after_sequence,
|
||||
limit=limit,
|
||||
)
|
||||
return apply_shard_log_response(self.cache, self.documents, response)
|
||||
return self.apply_shard_log_response(response)
|
||||
|
||||
def apply_snapshot_response(self, response: dict[str, Any]) -> list[CultNetAppliedRecord]:
|
||||
applied = apply_cultnet_raw_snapshot(self.cache, self.documents, response)
|
||||
self._publish_applied_records(applied)
|
||||
return applied
|
||||
|
||||
def apply_shard_log_response(self, response: dict[str, Any]) -> list[CultNetAppliedRecord]:
|
||||
applied = apply_cultnet_shard_log_response(self.cache, self.documents, response)
|
||||
self._publish_applied_records(applied)
|
||||
return applied
|
||||
|
||||
def _publish_local_change(
|
||||
self,
|
||||
document: DocumentDefinition[Any],
|
||||
key: str,
|
||||
change_kind: str,
|
||||
value: Any | None,
|
||||
previous: Any | None,
|
||||
) -> None:
|
||||
self._publish(CultMeshDatabaseChange(
|
||||
document=document,
|
||||
schema_id=document.catalog_entry().schema_id,
|
||||
record_key=key,
|
||||
change_kind=change_kind,
|
||||
value=value,
|
||||
previous_value=previous,
|
||||
))
|
||||
|
||||
def _publish_applied_records(self, applied: list[CultNetAppliedRecord]) -> None:
|
||||
documents_by_schema_id = schema_document_map(self.documents)
|
||||
for record in applied:
|
||||
document = documents_by_schema_id.get(record.schema_id)
|
||||
if document is None:
|
||||
continue
|
||||
self._publish(CultMeshDatabaseChange(
|
||||
document=document,
|
||||
schema_id=record.schema_id,
|
||||
record_key=record.record_key,
|
||||
change_kind=record.change_kind,
|
||||
value=record.value,
|
||||
))
|
||||
|
||||
def _publish(self, change: CultMeshDatabaseChange) -> None:
|
||||
for document, key, callback in list(self._subscribers):
|
||||
if document is not None and document.type != change.document.type:
|
||||
continue
|
||||
if key is not None and key != change.record_key:
|
||||
continue
|
||||
callback(change)
|
||||
|
||||
|
||||
def create_node(cache_path: str | Path | None = None, *, runtime_id: str = "python-runtime") -> CultMeshNode:
|
||||
|
|
|
|||
|
|
@ -10,7 +10,6 @@ from cultnet_py import (
|
|||
CultNetRawClient,
|
||||
CultNetSimulationConsensusOptions,
|
||||
CultNetSimulationObservationHub,
|
||||
apply_shard_log_response,
|
||||
)
|
||||
|
||||
from .node import CultMeshNode
|
||||
|
|
@ -78,7 +77,7 @@ class CultMeshGameSession:
|
|||
return CultMeshPrediction(key=key, schema_id=schema_id, document=document, value=value)
|
||||
|
||||
def apply_shard_log_response(self, response: dict[str, Any]) -> list[CultMeshSessionChange]:
|
||||
applied = apply_shard_log_response(self.node.cache, self.node.documents, response)
|
||||
applied = self.node.database.apply_shard_log_response(response)
|
||||
return self._reconcile_applied(applied)
|
||||
|
||||
def sync_shard_log(
|
||||
|
|
|
|||
|
|
@ -48,6 +48,7 @@ from cultmesh_py import create_node
|
|||
from cultmesh_py import (
|
||||
CultMesh,
|
||||
CultMeshDatabase,
|
||||
CultMeshDatabaseChange,
|
||||
CultMeshGameSessionOptions,
|
||||
CultMeshPeerCard,
|
||||
CultMeshPeerCatalog,
|
||||
|
|
@ -878,6 +879,30 @@ class CultCacheTests(unittest.TestCase):
|
|||
reopened.database.pull()
|
||||
self.assertEqual(reopened.database.get(document, "note:1")["body"], "hello")
|
||||
|
||||
def test_cultmesh_database_watchers_observe_local_changes_and_unsubscribe(self) -> None:
|
||||
document = define_database_entry_type("mesh.watch", [("body", 0)])
|
||||
node = CultMesh.create_node(runtime_id="mesh-watch")
|
||||
node.database.register_document(document)
|
||||
changes: list[CultMeshDatabaseChange] = []
|
||||
all_changes: list[CultMeshDatabaseChange] = []
|
||||
|
||||
unsubscribe_record = node.database.watch_record(document, "note:1", changes.append)
|
||||
unsubscribe_all = node.database.watch(all_changes.append, document=document)
|
||||
|
||||
node.database.put(document, "note:1", {"body": "hello"})
|
||||
node.database.put(document, "note:2", {"body": "skip"})
|
||||
node.database.put(document, "note:1", {"body": "updated"})
|
||||
node.database.delete(document, "note:1")
|
||||
unsubscribe_record()
|
||||
node.database.put(document, "note:1", {"body": "after-unsubscribe"})
|
||||
unsubscribe_all()
|
||||
|
||||
self.assertEqual([change.change_kind for change in changes], ["added", "updated", "removed"])
|
||||
self.assertEqual([change.record_key for change in changes], ["note:1", "note:1", "note:1"])
|
||||
self.assertEqual(changes[1].previous_value, {"body": "hello"})
|
||||
self.assertIsNone(changes[2].value)
|
||||
self.assertEqual([change.record_key for change in all_changes], ["note:1", "note:2", "note:1", "note:1", "note:1"])
|
||||
|
||||
def test_cultmesh_facade_matches_peer_runtime_entrypoints(self) -> None:
|
||||
with tempfile.TemporaryDirectory() as tmp:
|
||||
store_path = Path(tmp) / "mesh.cc"
|
||||
|
|
@ -1120,6 +1145,59 @@ class CultCacheTests(unittest.TestCase):
|
|||
self.assertEqual(changes[0].change_kind, "reconciled")
|
||||
self.assertEqual(node.get_required(note_doc, prediction.key)["body"], "authoritative")
|
||||
|
||||
def test_cultmesh_database_watchers_observe_authoritative_shard_log_reconciliation(self) -> None:
|
||||
note_doc = define_database_entry_type(
|
||||
"mesh.watched_input",
|
||||
[("body", 0)],
|
||||
schema_id="mesh.watched_input.v1",
|
||||
)
|
||||
node = CultMesh.create_node(runtime_id="client-watch")
|
||||
node.database.register_document(note_doc)
|
||||
seen: list[CultMeshDatabaseChange] = []
|
||||
node.database.watch_record(note_doc, "input:client-watch:move", seen.append)
|
||||
session = CultMesh.create_game_session(
|
||||
node,
|
||||
CultMeshGameSessionOptions(
|
||||
client_authority_scopes=(
|
||||
CultNetClientAuthorityScope(
|
||||
"client-watch",
|
||||
schema_ids=("mesh.watched_input.v1",),
|
||||
key_prefix="input:client-watch",
|
||||
),
|
||||
)
|
||||
),
|
||||
)
|
||||
|
||||
prediction = session.predict(note_doc, "input:client-watch:move", {"body": "predicted"})
|
||||
put = document_put_raw(
|
||||
message_id="authoritative-watch",
|
||||
key=prediction.key,
|
||||
schema_id=prediction.schema_id,
|
||||
stored_at="2026-06-13T00:00:00Z",
|
||||
payload=note_doc.encode_payload({"body": "authoritative"}),
|
||||
shard_id="inputs",
|
||||
shard_epoch=1,
|
||||
)
|
||||
session_changes = session.apply_shard_log_response({
|
||||
"schemaVersion": "cultnet.shard_log_response.v0",
|
||||
"messageId": "inputs-watch-log",
|
||||
"shardId": "inputs",
|
||||
"shardEpoch": 1,
|
||||
"entries": [
|
||||
{
|
||||
"sequence": 1,
|
||||
"committedAt": "2026-06-13T00:00:00Z",
|
||||
"changeKind": "updated",
|
||||
"put": put.to_wire(),
|
||||
}
|
||||
],
|
||||
"resyncRequired": False,
|
||||
})
|
||||
|
||||
self.assertEqual([change.change_kind for change in seen], ["added", "updated"])
|
||||
self.assertEqual(seen[1].value, {"body": "authoritative"})
|
||||
self.assertEqual(session_changes[0].change_kind, "reconciled")
|
||||
|
||||
def test_cultmesh_verse_catalog_response_matches_schema_v0_wire_shape(self) -> None:
|
||||
import msgpack # type: ignore
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue