Add Python CultMesh discovery client

This commit is contained in:
Meta Vens 2026-06-13 23:05:10 +01:00
commit 6d20e69a6c
5 changed files with 251 additions and 2 deletions

View file

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

View file

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

View file

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

View file

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

View file

@ -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<string, u
});
}
async function runPythonCultMeshClient(port: number): Promise<any> {
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<string, unknown>, put: Record<string, unknown>): Promise<any> {
const socket = connectTcp(port, "127.0.0.1");
const framer = new LengthPrefixedMessageFramer();