Mirror authorized RUDP peer sugar

This commit is contained in:
Meta Vens 2026-06-16 16:52:20 +01:00
commit 0680855925
8 changed files with 210 additions and 13 deletions

View file

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

View file

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

View file

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

View file

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

View file

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

View file

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

View file

@ -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<string, CultMeshPeerCard>();
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<CultNetRudpSocketTransportConnection> {
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 {

View file

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