Add Python CultMesh discovery client
This commit is contained in:
parent
536d056ba8
commit
6d20e69a6c
5 changed files with 251 additions and 2 deletions
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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",
|
||||
]
|
||||
|
|
|
|||
132
packages/cultcache-py/src/cultmesh_py/client.py
Normal file
132
packages/cultcache-py/src/cultmesh_py/client.py
Normal 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"),
|
||||
)
|
||||
|
||||
|
|
@ -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",
|
||||
|
|
|
|||
|
|
@ -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();
|
||||
|
|
|
|||
Loading…
Reference in a new issue