diff --git a/packages/cultcache-py/README.md b/packages/cultcache-py/README.md index 76d20bd5..8f464e35 100644 --- a/packages/cultcache-py/README.md +++ b/packages/cultcache-py/README.md @@ -199,7 +199,7 @@ checks, and stream transport negotiation: ```python from cultcache_py import define_database_entry_type -from cultmesh_py import CultMeshPeerCatalog, CultMeshStreamCatalog, create_node, peer_exchange_request +from cultmesh_py import CultMeshDiscoveryClient, CultMeshPeerCatalog, CultMeshStreamCatalog, create_node, peer_exchange_request note_doc = define_database_entry_type("mesh.note", [("body", 0)]) node = create_node("mesh.cc", runtime_id="python-runtime") @@ -209,6 +209,10 @@ node.put(note_doc, "note:1", {"body": "hello"}) peers = CultMeshPeerCatalog() response = peers.create_response(peer_exchange_request("pex-1", verse_id="local")) +client = CultMeshDiscoveryClient("127.0.0.1", 3075) +verses = client.fetch_verses(transport_version="cultmesh.v0") +mesh_peers = client.fetch_peers(verse_id="python-interop", roles=["read-replica"]) + streams = CultMeshStreamCatalog() ``` @@ -231,7 +235,9 @@ Current receipts: put/delete, mutation receipt, fire-command receipt, database subscription changes, shard catalog, shard log catch-up, simulation consensus candidates, 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. + 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. - `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/__init__.py b/packages/cultcache-py/src/cultmesh_py/__init__.py index c2382243..0f703b74 100644 --- a/packages/cultcache-py/src/cultmesh_py/__init__.py +++ b/packages/cultcache-py/src/cultmesh_py/__init__.py @@ -1,3 +1,4 @@ +from .client import CultMeshDiscoveryClient, peer_from_wire, verse_from_wire from .node import CultMeshNode, create_node from .wire import ( PEER_EXCHANGE_REQUEST, @@ -26,6 +27,7 @@ __all__ = [ "CultMeshPeerCatalog", "CultMeshAuthorityLease", "CultMeshAuthorityLeaseCatalog", + "CultMeshDiscoveryClient", "CultMeshStreamCatalog", "CultMeshStreamConsumerProfile", "CultMeshStreamDescriptor", @@ -39,6 +41,8 @@ __all__ = [ "VERSE_CATALOG_REQUEST", "VERSE_CATALOG_RESPONSE", "create_node", + "peer_from_wire", "peer_exchange_request", "verse_catalog_request", + "verse_from_wire", ] diff --git a/packages/cultcache-py/src/cultmesh_py/client.py b/packages/cultcache-py/src/cultmesh_py/client.py new file mode 100644 index 00000000..e34006df --- /dev/null +++ b/packages/cultcache-py/src/cultmesh_py/client.py @@ -0,0 +1,132 @@ +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 .wire import ( + PEER_EXCHANGE_RESPONSE, + VERSE_CATALOG_RESPONSE, + CultMeshPeerCard, + CultMeshVerseCompatibility, + CultMeshVerseDescriptor, + peer_exchange_request, + verse_catalog_request, +) + + +@dataclass(frozen=True) +class CultMeshDiscoveryClient: + host: str + port: int + 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 + + def request_verse_catalog( + self, + message_id: str = "cultmesh-python-verse-catalog", + *, + verse_ids: list[str] | None = None, + transport_version: str | None = None, + ) -> dict[str, Any]: + return self.request( + verse_catalog_request(message_id, verse_ids=verse_ids, transport_version=transport_version), + expected_schema_version=VERSE_CATALOG_RESPONSE, + ) + + def request_peer_exchange( + self, + message_id: str = "cultmesh-python-peer-exchange", + *, + verse_id: str, + roles: list[str] | None = None, + known_peer_ids: list[str] | None = None, + limit: int | None = None, + ) -> dict[str, Any]: + return self.request( + peer_exchange_request( + message_id, + verse_id=verse_id, + roles=roles, + known_peer_ids=known_peer_ids, + limit=limit, + ), + expected_schema_version=PEER_EXCHANGE_RESPONSE, + ) + + def fetch_verses( + self, + *, + verse_ids: list[str] | None = None, + transport_version: str | None = None, + ) -> list[CultMeshVerseDescriptor]: + response = self.request_verse_catalog(verse_ids=verse_ids, transport_version=transport_version) + return [verse_from_wire(verse) for verse in response.get("verses", [])] + + def fetch_peers( + self, + *, + verse_id: str, + roles: list[str] | None = None, + known_peer_ids: list[str] | None = None, + limit: int | None = None, + ) -> list[CultMeshPeerCard]: + response = self.request_peer_exchange( + verse_id=verse_id, + roles=roles, + known_peer_ids=known_peer_ids, + limit=limit, + ) + return [peer_from_wire(peer) for peer in response.get("peers", [])] + + +def verse_from_wire(value: dict[str, Any]) -> CultMeshVerseDescriptor: + compatibility = value.get("compatibility") or {} + return CultMeshVerseDescriptor( + verse_id=str(value["verseId"]), + display_name=str(value.get("displayName") or value["verseId"]), + authority_model=str(value.get("authorityModel") or ""), + compatibility=CultMeshVerseCompatibility( + transport_version=str(compatibility.get("transportVersion") or ""), + rules_hash=str(compatibility.get("rulesHash") or ""), + compatible_verse_ids=tuple(compatibility.get("compatibleVerseIds") or ()), + required_plugin_ids=tuple(compatibility.get("requiredPluginIds") or ()), + optional_plugin_ids=tuple(compatibility.get("optionalPluginIds") or ()), + ), + discovery_endpoints=tuple(value.get("discoveryEndpoints") or ()), + authority_runtime_ids=tuple(value.get("authorityRuntimeIds") or ()), + parent_verse_id=value.get("parentVerseId"), + description=value.get("description"), + ) + + +def peer_from_wire(value: dict[str, Any]) -> CultMeshPeerCard: + return CultMeshPeerCard( + peer_id=str(value["peerId"]), + verse_id=str(value["verseId"]), + endpoints=tuple(value.get("endpoints") or ()), + roles=tuple(value.get("roles") or ()), + shard_ids=tuple(value.get("shardIds") or ()), + region=value.get("region"), + authority_lease_id=value.get("authorityLeaseId"), + expires_at=value.get("expiresAt"), + signature=value.get("signature"), + ) + diff --git a/packages/cultcache-py/tests/test_cultcache.py b/packages/cultcache-py/tests/test_cultcache.py index 04349ff6..67ae1d26 100644 --- a/packages/cultcache-py/tests/test_cultcache.py +++ b/packages/cultcache-py/tests/test_cultcache.py @@ -1,7 +1,9 @@ from __future__ import annotations import json +import socket import tempfile +import threading import unittest from dataclasses import asdict, dataclass from datetime import UTC, datetime, timedelta @@ -23,6 +25,7 @@ from cultmesh_py import ( CultMeshPeerCatalog, CultMeshAuthorityLease, CultMeshAuthorityLeaseCatalog, + CultMeshDiscoveryClient, CultMeshStreamCatalog, CultMeshStreamConsumerProfile, CultMeshStreamDescriptor, @@ -398,6 +401,81 @@ class CultCacheTests(unittest.TestCase): self.assertIn("read-replica", decoded["peers"][0]["roles"]) self.assertEqual(decoded["peers"][0]["authorityLeaseId"], "lease-1") + def test_cultmesh_discovery_client_fetches_typed_catalogs_over_cultnet_frames(self) -> None: + import msgpack # type: ignore + from cultnet_py import read_frame, write_frame + + verses = CultMeshVerseCatalog() + verses.upsert( + CultMeshVerseDescriptor( + verse_id="aetheria-main", + display_name="Aetheria", + authority_model="federated", + compatibility=CultMeshVerseCompatibility( + transport_version="cultmesh.v0", + rules_hash="rules-1", + required_plugin_ids=("core",), + ), + discovery_endpoints=("cultmesh://aetheria.example.test:3075",), + authority_runtime_ids=("runtime-a",), + ) + ) + peers = CultMeshPeerCatalog() + peers.upsert( + CultMeshPeerCard( + peer_id="peer-a", + verse_id="aetheria-main", + endpoints=("cultnet://peer-a.example.test:3075",), + roles=("read-replica",), + shard_ids=("players",), + ) + ) + + ready = threading.Event() + server_error: list[BaseException] = [] + + def serve_two_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(2) + ready.set() + for _ in range(2): + connection, _ = server.accept() + with connection: + stream = connection.makefile("rwb") + request = msgpack.unpackb(read_frame(stream), raw=False) + if request["schemaVersion"] == "cultmesh.verse_catalog_request.v0": + response = verses.create_response(request) + elif request["schemaVersion"] == "cultmesh.peer_exchange_request.v0": + response = peers.create_response(request) + 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() + + port_holder: list[int] = [] + thread = threading.Thread(target=serve_two_requests, daemon=True) + thread.start() + self.assertTrue(ready.wait(2.0)) + self.assertFalse(server_error) + + client = CultMeshDiscoveryClient("127.0.0.1", port_holder[0], timeout_seconds=2.0) + fetched_verses = client.fetch_verses(transport_version="cultmesh.v0") + fetched_peers = client.fetch_peers(verse_id="aetheria-main", roles=["read-replica"]) + + thread.join(2.0) + self.assertFalse(server_error) + self.assertEqual(fetched_verses[0].verse_id, "aetheria-main") + self.assertEqual(fetched_verses[0].compatibility.required_plugin_ids, ("core",)) + self.assertEqual(fetched_peers[0].peer_id, "peer-a") + self.assertEqual(fetched_peers[0].shard_ids, ("players",)) + def test_cultmesh_authority_lease_requires_live_matching_lease(self) -> None: peer = CultMeshPeerCard( peer_id="voidbot-local", diff --git a/packages/cultnet-ts/test/interop/cultnet-interop.test.ts b/packages/cultnet-ts/test/interop/cultnet-interop.test.ts index b64c03b1..5e4b843b 100644 --- a/packages/cultnet-ts/test/interop/cultnet-interop.test.ts +++ b/packages/cultnet-ts/test/interop/cultnet-interop.test.ts @@ -291,6 +291,12 @@ test("CultNet TS/Rust/C#/Python peers discover each other and exchange raw state assert.equal(pythonPeerExchange.peers[0].peerId, "python-peer"); assert.ok(pythonPeerExchange.peers[0].roles.includes("read-replica")); + const pythonCultMeshClient = await runPythonCultMeshClient(pythonPort); + assert.equal(pythonCultMeshClient.verses[0].verseId, "python-interop"); + assert.equal(pythonCultMeshClient.verses[0].transportVersion, "cultmesh.v0"); + assert.equal(pythonCultMeshClient.peers[0].peerId, "python-peer"); + assert.ok(pythonCultMeshClient.peers[0].roles.includes("read-replica")); + const pythonChange = await requestPythonDatabaseChange(pythonPort, { schemaVersion: "cultnet.database_subscribe.v0", messageId: "python-subscribe", @@ -702,6 +708,29 @@ async function requestCultMeshFromPython(port: number, request: Record { + const script = [ + "import json", + "from cultmesh_py import CultMeshDiscoveryClient", + `client = CultMeshDiscoveryClient("127.0.0.1", ${port}, timeout_seconds=4.0)`, + "verses = client.fetch_verses(transport_version='cultmesh.v0')", + "peers = client.fetch_peers(verse_id='python-interop', roles=['read-replica'])", + "print(json.dumps({", + " 'verses': [{'verseId': verse.verse_id, 'transportVersion': verse.compatibility.transport_version} for verse in verses],", + " 'peers': [{'peerId': peer.peer_id, 'roles': list(peer.roles)} for peer in peers],", + "}))", + ].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();