Add Python CultNet raw client

This commit is contained in:
Meta Vens 2026-06-13 23:22:20 +01:00
commit 664f6b96d9
6 changed files with 226 additions and 18 deletions

View file

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

View file

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

View file

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

View file

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

View file

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

View file

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