From 664f6b96d9539a2b7d78da7e334f725d237eab50 Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Sat, 13 Jun 2026 23:22:20 +0100 Subject: [PATCH] Add Python CultNet raw client --- packages/cultcache-py/README.md | 12 +- .../cultcache-py/src/cultmesh_py/client.py | 21 +--- .../cultcache-py/src/cultnet_py/__init__.py | 2 + .../cultcache-py/src/cultnet_py/client.py | 109 ++++++++++++++++++ packages/cultcache-py/tests/test_cultcache.py | 70 +++++++++++ .../test/interop/cultnet-interop.test.ts | 30 +++++ 6 files changed, 226 insertions(+), 18 deletions(-) create mode 100644 packages/cultcache-py/src/cultnet_py/client.py diff --git a/packages/cultcache-py/README.md b/packages/cultcache-py/README.md index 3de51812..4eddde16 100644 --- a/packages/cultcache-py/README.md +++ b/packages/cultcache-py/README.md @@ -146,6 +146,7 @@ member order. ```python from cultnet_py import ( + CultNetRawClient, compute_simulation_claim_hash, database_subscribe, decode_frame, @@ -160,8 +161,13 @@ from cultnet_py import ( payload = hello(runtime_id="python-runtime").to_bytes() message = parse_message(decode_frame(encode_frame(payload))) +client = CultNetRawClient("127.0.0.1", 3075) +catalog = client.fetch_schema_catalog(kinds=["wire_message"]) +snapshot = client.fetch_snapshot(schema_ids=["cultnet.interop-note"]) +shard_catalog = client.fetch_shard_catalog(schema_ids=["cultnet.interop-note"]) + subscription = database_subscribe(subscription_id="ui", schema_ids=["cultnet.interop-note"]) -shards = shard_catalog_request(message_id="shards", schema_ids=["cultnet.interop-note"]) +shard_request = shard_catalog_request(message_id="shards", schema_ids=["cultnet.interop-note"]) claim_hash = compute_simulation_claim_hash("frame:42", "subject:player-1", "hit") observation = simulation_observation( message_id="obs-1", @@ -238,7 +244,9 @@ Current receipts: and witness artifact bundle round-trips. The same test asks the Python peer for CultMesh Verse catalog and peer exchange responses over the CultNet pipe, then verifies the public `CultMeshDiscoveryClient` can fetch typed Python - Verse and peer descriptors from that live endpoint. + Verse and peer descriptors from that live endpoint. It also verifies + `CultNetRawClient` can fetch the live Python peer's schema catalog, raw + snapshot, and shard catalog. - `packages/cultcache-py/tests/test_cultcache.py` covers Python CultMesh Verse catalog, peer exchange, authority lease, stream negotiation, CultNet helper shapes, simulation claim hashing, and witness artifact bundle payload diff --git a/packages/cultcache-py/src/cultmesh_py/client.py b/packages/cultcache-py/src/cultmesh_py/client.py index f5913b55..527c187a 100644 --- a/packages/cultcache-py/src/cultmesh_py/client.py +++ b/packages/cultcache-py/src/cultmesh_py/client.py @@ -1,12 +1,9 @@ from __future__ import annotations -import socket from dataclasses import dataclass from typing import Any -import msgpack - -from cultnet_py.framing import read_frame, write_frame +from cultnet_py import CultNetRawClient from .wire import ( PEER_EXCHANGE_RESPONSE, @@ -29,18 +26,10 @@ class CultMeshDiscoveryClient: timeout_seconds: float = 4.0 def request(self, message: dict[str, Any], *, expected_schema_version: str) -> dict[str, Any]: - with socket.create_connection((self.host, self.port), timeout=self.timeout_seconds) as connection: - connection.settimeout(self.timeout_seconds) - stream = connection.makefile("rwb") - write_frame(stream, msgpack.packb(message, use_bin_type=True)) - stream.flush() - response = msgpack.unpackb(read_frame(stream), raw=False) - if not isinstance(response, dict): - raise ValueError("CultMesh discovery response must be a MessagePack map") - schema_version = response.get("schemaVersion") - if schema_version != expected_schema_version: - raise ValueError(f"Expected {expected_schema_version}, received {schema_version!r}") - return response + return CultNetRawClient(self.host, self.port, self.timeout_seconds).request( + message, + expected_schema_version=expected_schema_version, + ) def request_verse_catalog( self, diff --git a/packages/cultcache-py/src/cultnet_py/__init__.py b/packages/cultcache-py/src/cultnet_py/__init__.py index e35c24bb..8508465a 100644 --- a/packages/cultcache-py/src/cultnet_py/__init__.py +++ b/packages/cultcache-py/src/cultnet_py/__init__.py @@ -1,3 +1,4 @@ +from .client import CultNetRawClient from .framing import decode_frame, encode_frame, read_frame, write_frame from .messages import ( CultNetMessage, @@ -20,6 +21,7 @@ from .messages import ( __all__ = [ "CultNetMessage", + "CultNetRawClient", "compute_simulation_claim_hash", "database_subscribe", "database_unsubscribe", diff --git a/packages/cultcache-py/src/cultnet_py/client.py b/packages/cultcache-py/src/cultnet_py/client.py new file mode 100644 index 00000000..633be3a2 --- /dev/null +++ b/packages/cultcache-py/src/cultnet_py/client.py @@ -0,0 +1,109 @@ +from __future__ import annotations + +import socket +from dataclasses import dataclass +from typing import Any + +import msgpack + +from .framing import read_frame, write_frame +from .messages import ( + CultNetMessage, + schema_catalog_request, + shard_catalog_request, + shard_log_request, + snapshot_request, +) + + +@dataclass(frozen=True) +class CultNetRawClient: + host: str + port: int + timeout_seconds: float = 4.0 + + def request(self, message: CultNetMessage | dict[str, Any], *, expected_schema_version: str) -> dict[str, Any]: + wire = message.to_wire() if isinstance(message, CultNetMessage) else message + with socket.create_connection((self.host, self.port), timeout=self.timeout_seconds) as connection: + connection.settimeout(self.timeout_seconds) + stream = connection.makefile("rwb") + write_frame(stream, msgpack.packb(wire, use_bin_type=True)) + stream.flush() + response = msgpack.unpackb(read_frame(stream), raw=False) + if not isinstance(response, dict): + raise ValueError("CultNet response must be a MessagePack map") + schema_version = response.get("schemaVersion") + if schema_version != expected_schema_version: + raise ValueError(f"Expected {expected_schema_version}, received {schema_version!r}") + return response + + def fetch_schema_catalog( + self, + *, + message_id: str = "cultnet-python-schema-catalog", + include_schema_json: bool = False, + schema_ids: list[str] | None = None, + kinds: list[str] | None = None, + ) -> dict[str, Any]: + return self.request( + schema_catalog_request( + message_id=message_id, + include_schema_json=include_schema_json, + schema_ids=schema_ids, + kinds=kinds, + ), + expected_schema_version="cultnet.schema_catalog_response.v0", + ) + + def fetch_snapshot( + self, + *, + message_id: str = "cultnet-python-snapshot", + 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]: + return self.request( + snapshot_request( + message_id=message_id, + schema_ids=schema_ids, + record_keys=record_keys, + shard_id=shard_id, + shard_epoch=shard_epoch, + ), + expected_schema_version="cultnet.snapshot_response_raw.v0", + ) + + def fetch_shard_catalog( + self, + *, + message_id: str = "cultnet-python-shard-catalog", + schema_ids: list[str] | None = None, + record_keys: list[str] | None = None, + ) -> dict[str, Any]: + return self.request( + shard_catalog_request(message_id=message_id, schema_ids=schema_ids, record_keys=record_keys), + expected_schema_version="cultnet.shard_catalog_response.v0", + ) + + def fetch_shard_log( + self, + *, + shard_id: str, + message_id: str = "cultnet-python-shard-log", + shard_epoch: int | None = None, + after_sequence: int = 0, + limit: int | None = None, + ) -> dict[str, Any]: + return self.request( + shard_log_request( + message_id=message_id, + shard_id=shard_id, + shard_epoch=shard_epoch, + after_sequence=after_sequence, + limit=limit, + ), + expected_schema_version="cultnet.shard_log_response.v0", + ) + diff --git a/packages/cultcache-py/tests/test_cultcache.py b/packages/cultcache-py/tests/test_cultcache.py index 255155eb..f4a363f3 100644 --- a/packages/cultcache-py/tests/test_cultcache.py +++ b/packages/cultcache-py/tests/test_cultcache.py @@ -19,6 +19,7 @@ from cultcache_py import ( from cultcache_py.interop import read_note, write_note from cultnet_py import ( compute_simulation_claim_hash, + CultNetRawClient, database_subscribe, database_unsubscribe, decode_frame, @@ -261,6 +262,75 @@ class CultCacheTests(unittest.TestCase): self.assertEqual(snapshot["shardId"], "interop") self.assertEqual(snapshot["shardEpoch"], 1) + def test_cultnet_raw_client_fetches_schema_snapshot_and_shard_reads(self) -> None: + import msgpack # type: ignore + from cultnet_py import read_frame, write_frame + + received_versions: list[str] = [] + ready = threading.Event() + server_error: list[BaseException] = [] + port_holder: list[int] = [] + + def serve_requests() -> None: + try: + with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as server: + server.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1) + server.bind(("127.0.0.1", 0)) + port_holder.append(server.getsockname()[1]) + server.listen(4) + ready.set() + for _ in range(4): + connection, _ = server.accept() + with connection: + stream = connection.makefile("rwb") + request = msgpack.unpackb(read_frame(stream), raw=False) + received_versions.append(request["schemaVersion"]) + if request["schemaVersion"] == "cultnet.schema_catalog_request.v0": + self.assertEqual(request["kinds"], ["wire_message"]) + response = {"schemaVersion": "cultnet.schema_catalog_response.v0", "messageId": request["messageId"], "schemas": []} + elif request["schemaVersion"] == "cultnet.snapshot_request.v0": + self.assertEqual(request["shardId"], "interop") + response = {"schemaVersion": "cultnet.snapshot_response_raw.v0", "messageId": request["messageId"], "documents": []} + elif request["schemaVersion"] == "cultnet.shard_catalog_request.v0": + response = {"schemaVersion": "cultnet.shard_catalog_response.v0", "messageId": request["messageId"], "shards": []} + elif request["schemaVersion"] == "cultnet.shard_log_request.v0": + self.assertEqual(request["afterSequence"], 7) + response = { + "schemaVersion": "cultnet.shard_log_response.v0", + "messageId": request["messageId"], + "shardId": request["shardId"], + "shardEpoch": request["shardEpoch"], + "entries": [], + "resyncRequired": False, + } + else: + raise AssertionError(f"unexpected request {request['schemaVersion']}") + write_frame(stream, msgpack.packb(response, use_bin_type=True)) + stream.flush() + except BaseException as error: + server_error.append(error) + ready.set() + + thread = threading.Thread(target=serve_requests, daemon=True) + thread.start() + self.assertTrue(ready.wait(2.0)) + self.assertFalse(server_error) + + client = CultNetRawClient("127.0.0.1", port_holder[0], timeout_seconds=2.0) + self.assertEqual(client.fetch_schema_catalog(kinds=["wire_message"])["schemaVersion"], "cultnet.schema_catalog_response.v0") + self.assertEqual(client.fetch_snapshot(shard_id="interop", shard_epoch=1)["schemaVersion"], "cultnet.snapshot_response_raw.v0") + self.assertEqual(client.fetch_shard_catalog(schema_ids=["schema-a"])["schemaVersion"], "cultnet.shard_catalog_response.v0") + self.assertEqual(client.fetch_shard_log(shard_id="interop", shard_epoch=1, after_sequence=7)["schemaVersion"], "cultnet.shard_log_response.v0") + + thread.join(2.0) + self.assertFalse(server_error) + self.assertEqual(received_versions, [ + "cultnet.schema_catalog_request.v0", + "cultnet.snapshot_request.v0", + "cultnet.shard_catalog_request.v0", + "cultnet.shard_log_request.v0", + ]) + def test_cultnet_document_delete_helper_matches_schema_v0_shape(self) -> None: message = document_delete( message_id="delete-1", diff --git a/packages/cultnet-ts/test/interop/cultnet-interop.test.ts b/packages/cultnet-ts/test/interop/cultnet-interop.test.ts index 5e4b843b..b2d3e21d 100644 --- a/packages/cultnet-ts/test/interop/cultnet-interop.test.ts +++ b/packages/cultnet-ts/test/interop/cultnet-interop.test.ts @@ -297,6 +297,11 @@ test("CultNet TS/Rust/C#/Python peers discover each other and exchange raw state assert.equal(pythonCultMeshClient.peers[0].peerId, "python-peer"); assert.ok(pythonCultMeshClient.peers[0].roles.includes("read-replica")); + const pythonCultNetClient = await runPythonCultNetRawClient(pythonPort); + assert.ok(pythonCultNetClient.wireSchemaCount >= 1); + assert.ok(pythonCultNetClient.snapshotRecordKeys.includes("note:python-peer")); + assert.equal(pythonCultNetClient.shards[0].shardId, "interop"); + const pythonChange = await requestPythonDatabaseChange(pythonPort, { schemaVersion: "cultnet.database_subscribe.v0", messageId: "python-subscribe", @@ -731,6 +736,31 @@ async function runPythonCultMeshClient(port: number): Promise { return JSON.parse(stdout); } +async function runPythonCultNetRawClient(port: number): Promise { + const script = [ + "import json", + "from cultnet_py import CultNetRawClient", + `client = CultNetRawClient("127.0.0.1", ${port}, timeout_seconds=4.0)`, + "catalog = client.fetch_schema_catalog(kinds=['wire_message'])", + `snapshot = client.fetch_snapshot(schema_ids=['${interopNoteSchemaId}'])`, + `shards = client.fetch_shard_catalog(schema_ids=['${interopNoteSchemaId}'])`, + "print(json.dumps({", + " 'wireSchemaCount': len(catalog.get('schemas', [])),", + " 'snapshotRecordKeys': [document.get('recordKey') for document in snapshot.get('documents', [])],", + " 'shards': [{'shardId': shard.get('shardId'), 'epoch': shard.get('epoch')} for shard in shards.get('shards', [])],", + "}))", + ].join("\n"); + const { stdout } = await execFileAsync(pythonCommand, ["-c", script], { + cwd: cultcachePyRoot, + env: { + ...process.env, + PYTHONPATH: cultcachePySrc, + }, + timeout: 8000, + }); + return JSON.parse(stdout); +} + async function requestPythonDatabaseChange(port: number, subscribe: Record, put: Record): Promise { const socket = connectTcp(port, "127.0.0.1"); const framer = new LengthPrefixedMessageFramer();