diff --git a/docs/cultnet-transport-parity.md b/docs/cultnet-transport-parity.md index daa83580..3f894093 100644 --- a/docs/cultnet-transport-parity.md +++ b/docs/cultnet-transport-parity.md @@ -302,7 +302,9 @@ Current progress: without creating a second catalog authority. The facade now also parses `rudp://host:port` endpoints and creates RUDP client/server transports from endpoint or peer-card contact hints while leaving packet/session semantics in - `cultnet_py`. + `cultnet_py`. Python peer catalogs also expose authorized-peer lookup, and + the branded facade can create a RUDP client from the first peer authorized by + the authority lease catalog for a Verse role. - Rust now has a poll-driven `CultNetRudpReconnectLoop` for substrate callers: service loops report closure, ask `reconnect_if_due(now_ms)` inside their own reactor, and the shared controller owns retry delay/exhaustion state while the @@ -325,7 +327,10 @@ Current progress: do not have to leave the CultMesh entrypoint for schema discovery or shard topology. The facade now also parses `rudp://host:port` endpoints and creates RUDP client/server transports from endpoint or peer-card contact hints while - leaving packet/session semantics in `cultnet-ts`. + leaving packet/session semantics in `cultnet-ts`. TypeScript now also mirrors + Kotlin's authorized-peer lookup and RUDP client helper, so peer cards remain + contact hints until the authority lease catalog authorizes the requested + Verse role. - TypeScript now also has a `CultNetSchemaCatalog` for remote schema descriptors plus `CultNetPeer` request/fetch/sync helpers for `cultnet.schema_catalog_request.v0` / `cultnet.schema_catalog_response.v0`. diff --git a/docs/runtime-parity-scope.md b/docs/runtime-parity-scope.md index 725f7cc1..0dc8a841 100644 --- a/docs/runtime-parity-scope.md +++ b/docs/runtime-parity-scope.md @@ -31,8 +31,8 @@ CultMesh. | Runtime | Role | Claimed parity | Not claimed | | --- | --- | --- | --- | | C# | Reference implementation and production game/server substrate | CultCache typed documents and SoA, CultNet schema-v0, LiteNetLib production path with adapter profile, shared transport profiles, shared RUDP socket transport, RUDP reconnect policy/controller and reconnect-loop helper, LiteNetLib client reconnect-controller adoption, schema-client transport port for service request/response clients, CultMesh node/session/catalog/stream/simulation surfaces | No need to abandon LiteNetLib before the CultNet adapter fully owns production service adoption | -| Python | Package runtime, local daemon endpoint, raw interop peer, typed state participant | CultCache/CultNet/CultMesh package surface, branded CultMesh node/schema/shard/Verse/peer/authority/stream/RUDP ergonomics, shard catalogs/logs, schema-transport factory for raw client request/subscription flows, local TCP CultMesh server, session/prediction/simulation fact helpers, RUDP codec/session/socket transport, RUDP reconnect policy/controller and reconnect-loop helper, schema-v0 MessagePack over RUDP evidence, benchmark evidence against C# cache paths | Universal C# throughput, full C# daemon/server stack, and RUDP as the only public service pipe | -| TypeScript | Node/browser-adjacent projection and interop runtime | CultCache parity tests, CultNet schema-v0 peer, advertised schema/shard catalog wire contracts plus request/sync helpers, transport profiles, TCP-framed transport port and peer helper, shared RUDP socket transport, RUDP reconnect policy/controller, RUDP reconnect-loop helper, branded CultMesh node/schema/shard/Verse/peer/authority/stream/RUDP ergonomics | Full C# game session/server stack | +| Python | Package runtime, local daemon endpoint, raw interop peer, typed state participant | CultCache/CultNet/CultMesh package surface, branded CultMesh node/schema/shard/Verse/peer/authority/stream/RUDP ergonomics, authorized peer lookup, shard catalogs/logs, schema-transport factory for raw client request/subscription flows, local TCP CultMesh server, session/prediction/simulation fact helpers, RUDP codec/session/socket transport, RUDP reconnect policy/controller and reconnect-loop helper, schema-v0 MessagePack over RUDP evidence, benchmark evidence against C# cache paths | Universal C# throughput, full C# daemon/server stack, and RUDP as the only public service pipe | +| TypeScript | Node/browser-adjacent projection and interop runtime | CultCache parity tests, CultNet schema-v0 peer, advertised schema/shard catalog wire contracts plus request/sync helpers, transport profiles, TCP-framed transport port and peer helper, shared RUDP socket transport, RUDP reconnect policy/controller, RUDP reconnect-loop helper, branded CultMesh node/schema/shard/Verse/peer/authority/stream/RUDP ergonomics, authorized peer lookup | Full C# game session/server stack | | Rust | Low-level cache/transport/runtime substrate | CultCache/CultNet interop lane, schema and shard catalog helpers, transport profiles, TCP-framed port, shared RUDP codec/session/socket transport, RUDP reconnect policy/controller and reconnect-loop helper, schema-v0 MessagePack over RUDP evidence, small CultMesh facade for schema registry, shard catalog, peer cards, authority leases, RUDP endpoint parsing, and peer-card RUDP client construction | Full CultMesh game-session/server facade, stream catalog, or production game-session server | | Kotlin | JVM/Android client substrate | Typed MessagePack cache, built-in schema catalog advertisement, schema/shard catalogs with shared schema-message transport fetch/sync helpers, authority leases, authorized peer lookup, stream catalog, branded `CultMesh` facade, WebSocket transport profile/connection helper, RUDP client/server sugar, RUDP reconnect policy/controller and reconnect-loop helper, schema-v0 MessagePack over RUDP evidence | C# SoA store, full C# server daemon, or Unity hot-loop memory layout | diff --git a/packages/cultcache-py/PARITY.md b/packages/cultcache-py/PARITY.md index 76e9d9dc..9e3ca7dc 100644 --- a/packages/cultcache-py/PARITY.md +++ b/packages/cultcache-py/PARITY.md @@ -131,11 +131,14 @@ CultCache, CultNet, and CultMesh. It is evidence, not confetti. schema catalogs, built-in schema catalogs, shard catalogs, sessions, streams, authority leases, local TCP node serving, simulation fact commits, RUDP endpoint parsing, and RUDP client/server construction from endpoint or - peer-card contact hints. The durable shard-log node option attaches a - file-backed authoritative log store beside the cache file by default. Schema, - shard, and RUDP factories delegate to the existing `cultnet_py` owners, so the - branded entrypoint does not create a second source of discovery or transport - truth. The `cultmesh-py-daemon` / + peer-card contact hints. Peer catalogs expose authorized-peer lookup, and the + branded facade can open a RUDP client from the first peer authorized by the + authority lease catalog for a Verse role, keeping endpoint contact separate + from trust. The durable shard-log node option attaches a file-backed + authoritative log store beside the cache file by default. Schema, shard, and + RUDP factories delegate to the existing `cultnet_py` owners, so the branded + entrypoint does not create a second source of discovery or transport truth. + The `cultmesh-py-daemon` / `python -m cultmesh_py.daemon` entrypoint launches that same local TCP server body and emits a bounded readiness document for process supervisors while the served CultNet endpoint remains the capability owner. Readiness now mirrors diff --git a/packages/cultcache-py/src/cultmesh_py/facade.py b/packages/cultcache-py/src/cultmesh_py/facade.py index ec37fa78..35b57042 100644 --- a/packages/cultcache-py/src/cultmesh_py/facade.py +++ b/packages/cultcache-py/src/cultmesh_py/facade.py @@ -2,6 +2,7 @@ from __future__ import annotations import socket as socket_module from dataclasses import dataclass +from datetime import datetime from pathlib import Path from typing import Any from urllib.parse import urlparse @@ -226,6 +227,29 @@ class CultMesh: raise ValueError(f"Peer {peer.peer_id!r} does not advertise a RUDP endpoint") return CultMesh.create_rudp_client(runtime_id, connection_id, endpoint, **options) + @staticmethod + def create_rudp_client_for_authorized_peer( + runtime_id: str, + connection_id: int, + peers: CultMeshPeerCatalog, + leases: CultMeshAuthorityLeaseCatalog, + verse_id: str, + role: str, + *, + shard_id: str | None = None, + at: datetime | None = None, + **options: Any, + ) -> CultNetRudpSocketTransportConnection: + peer = peers.first_authorized(verse_id, role, leases, shard_id=shard_id, at=at) + if peer is None: + raise ValueError(f"No authorized RUDP peer for role {role!r} in Verse {verse_id!r}") + return CultMesh.create_rudp_client_for_peer( + runtime_id, + connection_id, + peer, + **options, + ) + @staticmethod def create_verse_discovery_client( host: str = "localhost", diff --git a/packages/cultcache-py/src/cultmesh_py/wire.py b/packages/cultcache-py/src/cultmesh_py/wire.py index 7b276d26..9a666a1e 100644 --- a/packages/cultcache-py/src/cultmesh_py/wire.py +++ b/packages/cultcache-py/src/cultmesh_py/wire.py @@ -222,6 +222,32 @@ class CultMeshPeerCatalog: if peer.verse_id == verse_id and (role is None or peer.has_role(role)) ] + def find_authorized( + self, + verse_id: str, + role: str, + leases: "CultMeshAuthorityLeaseCatalog", + shard_id: str | None = None, + at: datetime | None = None, + ) -> list[CultMeshPeerCard]: + require_non_empty(verse_id, "verse_id") + require_non_empty(role, "role") + return [ + peer + for peer in self.find(verse_id, role) + if leases.is_authorized(peer, role, shard_id=shard_id, at=at) + ] + + def first_authorized( + self, + verse_id: str, + role: str, + leases: "CultMeshAuthorityLeaseCatalog", + shard_id: str | None = None, + at: datetime | None = None, + ) -> CultMeshPeerCard | None: + return next(iter(self.find_authorized(verse_id, role, leases, shard_id, at)), None) + def get(self, peer_id: str) -> CultMeshPeerCard | None: require_non_empty(peer_id, "peer_id") return self._peers.get(peer_id) diff --git a/packages/cultcache-py/tests/test_cultcache.py b/packages/cultcache-py/tests/test_cultcache.py index 17f5b8a0..e23010f1 100644 --- a/packages/cultcache-py/tests/test_cultcache.py +++ b/packages/cultcache-py/tests/test_cultcache.py @@ -1159,11 +1159,41 @@ class CultCacheTests(unittest.TestCase): verse_id="local", endpoints=(endpoint.uri,), roles=("schema",), + authority_lease_id="lease:python-cultmesh-rudp-server", ) - client = CultMesh.create_rudp_client_for_peer( + peers = CultMesh.create_peer_catalog() + leases = CultMesh.create_authority_lease_catalog() + peers.upsert(peer) + with self.assertRaisesRegex(ValueError, "No authorized RUDP peer"): + CultMesh.create_rudp_client_for_authorized_peer( + "python-cultmesh-rudp-client", + connection_id, + peers, + leases, + "local", + "schema", + resend_delay_ms=25, + max_fragment_bytes=1024, + max_pending_reliable_packets=16, + ) + leases.upsert( + CultMeshAuthorityLease( + lease_id="lease:python-cultmesh-rudp-server", + verse_id="local", + peer_id="python-cultmesh-rudp-server", + roles=("schema",), + valid_from=datetime.now(UTC) - timedelta(seconds=1), + expires_at=datetime.now(UTC) + timedelta(seconds=30), + issuer_runtime_id="python-authority", + ) + ) + client = CultMesh.create_rudp_client_for_authorized_peer( "python-cultmesh-rudp-client", connection_id, - peer, + peers, + leases, + "local", + "schema", resend_delay_ms=25, max_fragment_bytes=1024, max_pending_reliable_packets=16, @@ -4974,8 +5004,11 @@ class CultCacheTests(unittest.TestCase): authority_lease_id="lease:voidbot-local", ) leases = CultMeshAuthorityLeaseCatalog() + peers = CultMeshPeerCatalog() + peers.upsert(peer) now = datetime.now(UTC) self.assertFalse(leases.is_authorized(peer, "shard-primary", at=now)) + self.assertEqual(peers.find_authorized("local", "shard-primary", leases, at=now), []) leases.upsert( CultMeshAuthorityLease( @@ -5002,6 +5035,15 @@ class CultCacheTests(unittest.TestCase): self.assertTrue(lease.covers(peer, "shard-primary", shard_id="shard-a", at=now)) self.assertFalse(lease.covers(peer, "shard-primary", shard_id="shard-b", at=now)) self.assertTrue(leases.is_authorized(peer, "shard-primary", shard_id="shard-a", at=now)) + self.assertEqual( + peers.find_authorized("local", "shard-primary", leases, shard_id="shard-a", at=now), + [peer], + ) + self.assertEqual( + peers.first_authorized("local", "shard-primary", leases, shard_id="shard-a", at=now), + peer, + ) + self.assertIsNone(peers.first_authorized("local", "read-replica", leases, at=now)) self.assertFalse(leases.is_authorized(peer, "shard-primary", shard_id="shard-b", at=now)) self.assertFalse(leases.is_authorized(peer, "read-replica", at=now)) self.assertIsNone(leases.get("missing")) diff --git a/packages/cultmesh-ts/src/index.ts b/packages/cultmesh-ts/src/index.ts index 1af2dc32..ef81b9f5 100644 --- a/packages/cultmesh-ts/src/index.ts +++ b/packages/cultmesh-ts/src/index.ts @@ -127,6 +127,12 @@ export interface CultMeshRudpSocketOptions { reconnectPolicy?: CultNetReconnectPolicy; } +export interface CultMeshAuthorizedRudpSocketOptions + extends CultMeshRudpSocketOptions { + shardId?: string; + at?: Date; +} + export class CultMeshPeerCatalog { readonly #peers = new Map(); readonly #subscribers = new Set<(peer: CultMeshPeerCard) => void>(); @@ -166,6 +172,30 @@ export class CultMeshPeerCatalog { (!role || peer.roles?.includes(role) === true), ); } + + public findAuthorized( + verseId: string, + role: string, + leases: CultMeshAuthorityLeaseCatalog, + shardId?: string, + at = new Date(), + ): readonly CultMeshPeerCard[] { + requireNonEmpty(verseId, "verseId"); + requireNonEmpty(role, "role"); + return this.find(verseId, role).filter((peer) => + leases.isAuthorized(peer, role, shardId, at), + ); + } + + public firstAuthorized( + verseId: string, + role: string, + leases: CultMeshAuthorityLeaseCatalog, + shardId?: string, + at = new Date(), + ): CultMeshPeerCard | undefined { + return this.findAuthorized(verseId, role, leases, shardId, at)[0]; + } } export interface CultMeshAuthorityLease { @@ -605,6 +635,28 @@ export class CultMesh { } return CultMesh.createRudpClient(runtimeId, connectionId, endpoint, options); } + + public static async createRudpClientForAuthorizedPeer( + runtimeId: string, + connectionId: number, + peers: CultMeshPeerCatalog, + leases: CultMeshAuthorityLeaseCatalog, + verseId: string, + role: string, + options: CultMeshAuthorizedRudpSocketOptions = {}, + ): Promise { + const peer = peers.firstAuthorized( + verseId, + role, + leases, + options.shardId, + options.at, + ); + if (!peer) { + throw new Error(`No authorized RUDP peer for role ${role} in Verse ${verseId}.`); + } + return CultMesh.createRudpClientForPeer(runtimeId, connectionId, peer, options); + } } function requireNonEmpty(value: string, name: string): void { diff --git a/packages/cultmesh-ts/test/cultmesh.test.ts b/packages/cultmesh-ts/test/cultmesh.test.ts index 506a8f3a..ff553a44 100644 --- a/packages/cultmesh-ts/test/cultmesh.test.ts +++ b/packages/cultmesh-ts/test/cultmesh.test.ts @@ -78,6 +78,10 @@ test("CultMesh TS local authority leases do not trust peer cards by contact alon assert.equal(peers.get("voidbot-local"), peer); assert.deepEqual(peers.find("local", "shard-primary"), [peer]); assert.equal(leases.isAuthorized(peer, "shard-primary"), false); + assert.deepEqual( + peers.findAuthorized("local", "shard-primary", leases), + [], + ); const leaseUpdates: string[] = []; const unsubscribeLease = leases.watch((lease) => { @@ -101,6 +105,15 @@ test("CultMesh TS local authority leases do not trust peer cards by contact alon "lease:voidbot-local", ]); assert.equal(leases.isAuthorized(peer, "shard-primary"), true); + assert.deepEqual( + peers.findAuthorized("local", "shard-primary", leases), + [peer], + ); + assert.equal( + peers.firstAuthorized("local", "shard-primary", leases), + peer, + ); + assert.equal(peers.firstAuthorized("local", "schema", leases), undefined); }); test("CultMesh TS local Verse catalog exposes sorted views and watch ergonomics", () => { @@ -221,11 +234,43 @@ test("CultMesh TS branded facade creates RUDP clients from peer endpoints", asyn verseId: "local", endpoints: [endpoint.uri], roles: ["schema"], + authorityLeaseId: "lease:cultmesh-ts-rudp-server", }; - const client = await CultMesh.createRudpClientForPeer( + const peers = CultMesh.createPeerCatalog(); + const leases = CultMesh.createAuthorityLeaseCatalog(); + peers.upsert(peer); + await assert.rejects( + CultMesh.createRudpClientForAuthorizedPeer( + "cultmesh-ts-rudp-client", + connectionId, + peers, + leases, + "local", + "schema", + { + resendDelayMs: 25, + resendPollMs: 5, + maxFragmentBytes: 1024, + maxPendingReliablePackets: 16, + }, + ), + /No authorized RUDP peer/, + ); + leases.upsert({ + leaseId: "lease:cultmesh-ts-rudp-server", + verseId: "local", + peerId: "cultmesh-ts-rudp-server", + roles: ["schema"], + validFrom: new Date(Date.now() - 1000), + expiresAt: new Date(Date.now() + 1000), + }); + const client = await CultMesh.createRudpClientForAuthorizedPeer( "cultmesh-ts-rudp-client", connectionId, - peer, + peers, + leases, + "local", + "schema", { resendDelayMs: 25, resendPollMs: 5,