diff --git a/docs/cultnet-transport-parity.md b/docs/cultnet-transport-parity.md index 5f2c01e4..edcfefcd 100644 --- a/docs/cultnet-transport-parity.md +++ b/docs/cultnet-transport-parity.md @@ -369,8 +369,12 @@ Current progress: catalogs, peer catalogs, authority lease catalogs, stream catalogs, and RUDP client/server construction. Kotlin also parses advertised `rudp://host:port` endpoints and can build a RUDP client directly from a peer - card contact hint. The facade delegates to the same owners as the top-level - helpers instead of creating a second authority path. + card contact hint or the first peer authorized by the authority lease catalog. + The facade can now also return a connected RUDP client from a direct endpoint, + peer card, or authorized peer lookup, so schema-message transport helpers can + use RUDP without caller-side handshake ceremony. The facade delegates to the + same owners as the top-level helpers instead of creating a second authority + path. - Kotlin WebSocket and RUDP transports now expose catalog fetch/sync helpers for schema and shard catalogs. The helpers send standard schema-v0 requests, require the matching response schema, and apply through the caller's catalog, diff --git a/docs/runtime-parity-scope.md b/docs/runtime-parity-scope.md index bda1c36d..44bccf07 100644 --- a/docs/runtime-parity-scope.md +++ b/docs/runtime-parity-scope.md @@ -34,7 +34,7 @@ CultMesh. | 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, authorized peer lookup, RUDP endpoint parsing, and peer-card/authorized-peer 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 | +| 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, connected RUDP CultMesh client helpers, 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 | ## Evidence Gates diff --git a/packages/cultmesh-kotlin/README.md b/packages/cultmesh-kotlin/README.md index 7e819584..b25050bb 100644 --- a/packages/cultmesh-kotlin/README.md +++ b/packages/cultmesh-kotlin/README.md @@ -228,13 +228,14 @@ branded entrypoint to select an authorized RUDP peer for a Verse role: val peers = CultMesh.createPeerCatalog() val leases = CultMesh.createAuthorityLeaseCatalog() -val client = CultMesh.createRudpClientForAuthorizedPeer( +val client = CultMesh.connectRudpClientForAuthorizedPeer( runtimeId = "kotlin-client", connectionId = 0x10203040, peers = peers, leases = leases, verseId = "local", role = "schema", + connectPayload = "join".toByteArray(), ) ``` @@ -242,13 +243,16 @@ The helper uses `CultMeshPeerCatalog.firstAuthorized(...)`, which delegates trust to `CultMeshAuthorityLeaseCatalog.isAuthorized(...)`; peer endpoints remain contact hints, not authority. -The sugar delegates to the same `CultNetRudpSocketTransportConnection` and +The connected helper delegates to the same `CultNetRudpSocketTransportConnection` +after authorized peer selection and handshake. The lower-level +`createRudpClient...` helpers remain available when a caller intentionally owns +the handshake or in-process polling loop. The sugar delegates to the same +transport and `cultnet.transport.rudp.v0` packet codec used by the cross-runtime interop harness. `sendSchema`, `sendLatest`, and `sendRealtime` select the shared -channel semantics; they do not create a Kotlin-only dialect. For a remote peer -that already has its own receive loop, use `connectAndWait(...)`; for two -same-process transports, use `pumpRudpPairUntilConnected(...)` to drive both -sides through the handshake. Because RUDP also implements +channel semantics; they do not create a Kotlin-only dialect. For two +same-process transports, use `pumpRudpPairUntilConnected(...)` or an explicit +server pump to drive both sides through the handshake. Because RUDP also implements `CultNetSchemaMessageTransport`, it uses the same catalog helpers as WebSocket, with timeout-aware receive loops: `fetchSchemaCatalog`, `fetchSchemaDescriptors`, `syncSchemaCatalog`, `fetchShardCatalog`, diff --git a/packages/cultmesh-kotlin/src/main/kotlin/org/gamecult/cultmesh/CultMesh.kt b/packages/cultmesh-kotlin/src/main/kotlin/org/gamecult/cultmesh/CultMesh.kt index cf11272f..39a2ca5f 100644 --- a/packages/cultmesh-kotlin/src/main/kotlin/org/gamecult/cultmesh/CultMesh.kt +++ b/packages/cultmesh-kotlin/src/main/kotlin/org/gamecult/cultmesh/CultMesh.kt @@ -23,6 +23,7 @@ import java.time.Instant import java.util.ArrayDeque import java.util.Base64 import java.util.TreeMap +import java.util.concurrent.atomic.AtomicBoolean interface CultDocumentCodec { val documentType: String @@ -397,6 +398,104 @@ object CultMesh { return createRudpClientForPeer(runtimeId, connectionId, peer, bindHost, bindPort, tuning) } + fun connectRudpClient( + runtimeId: String, + connectionId: Long, + endpoint: CultNetRudpEndpoint, + bindHost: String = "127.0.0.1", + bindPort: Int = 0, + tuning: CultNetRudpSocketTuning = CultNetRudpSocketTuning(), + connectPayload: ByteArray = ByteArray(0), + timeoutMs: Long = 1_000, + pollIntervalMs: Long = 5, + ): CultNetRudpSocketTransportConnection { + val client = createRudpClient(runtimeId, connectionId, endpoint, bindHost, bindPort, tuning) + if (!client.connectAndWait(connectPayload, timeoutMs, pollIntervalMs)) { + client.close() + throw IOException("Timed out waiting for RUDP client $runtimeId to connect") + } + return client + } + + fun connectRudpClient( + runtimeId: String, + connectionId: Long, + endpoint: String, + bindHost: String = "127.0.0.1", + bindPort: Int = 0, + tuning: CultNetRudpSocketTuning = CultNetRudpSocketTuning(), + connectPayload: ByteArray = ByteArray(0), + timeoutMs: Long = 1_000, + pollIntervalMs: Long = 5, + ): CultNetRudpSocketTransportConnection = connectRudpClient( + runtimeId = runtimeId, + connectionId = connectionId, + endpoint = parseRudpEndpoint(endpoint), + bindHost = bindHost, + bindPort = bindPort, + tuning = tuning, + connectPayload = connectPayload, + timeoutMs = timeoutMs, + pollIntervalMs = pollIntervalMs, + ) + + fun connectRudpClientForPeer( + runtimeId: String, + connectionId: Long, + peer: CultMeshPeerCard, + bindHost: String = "127.0.0.1", + bindPort: Int = 0, + tuning: CultNetRudpSocketTuning = CultNetRudpSocketTuning(), + connectPayload: ByteArray = ByteArray(0), + timeoutMs: Long = 1_000, + pollIntervalMs: Long = 5, + ): CultNetRudpSocketTransportConnection { + val endpoint = peer.endpoints.firstOrNull { it.startsWith("rudp://", ignoreCase = true) } + ?: throw IOException("Peer ${peer.peerId} does not advertise a RUDP endpoint") + return connectRudpClient( + runtimeId, + connectionId, + endpoint, + bindHost, + bindPort, + tuning, + connectPayload, + timeoutMs, + pollIntervalMs, + ) + } + + fun connectRudpClientForAuthorizedPeer( + runtimeId: String, + connectionId: Long, + peers: CultMeshPeerCatalog, + leases: CultMeshAuthorityLeaseCatalog, + verseId: String, + role: String, + shardId: String? = null, + at: Instant = Instant.now(), + bindHost: String = "127.0.0.1", + bindPort: Int = 0, + tuning: CultNetRudpSocketTuning = CultNetRudpSocketTuning(), + connectPayload: ByteArray = ByteArray(0), + timeoutMs: Long = 1_000, + pollIntervalMs: Long = 5, + ): CultNetRudpSocketTransportConnection { + val peer = peers.firstAuthorized(verseId, role, leases, shardId, at) + ?: throw IOException("No authorized RUDP peer for role $role in Verse $verseId") + return connectRudpClientForPeer( + runtimeId, + connectionId, + peer, + bindHost, + bindPort, + tuning, + connectPayload, + timeoutMs, + pollIntervalMs, + ) + } + fun createRudpReconnectLoop( reconnectPolicy: CultNetReconnectPolicy = createReconnectPolicy(), connectPayload: ByteArray = ByteArray(0), @@ -3983,17 +4082,36 @@ private fun rudpSocketTransportErgonomicFactoriesCarrySchemaFrames() { expiresAt = Instant.now().plusSeconds(60), ), ) - CultMesh.createRudpClientForAuthorizedPeer( - runtimeId = "kotlin-rudp-sugar-client", - connectionId = connectionId, - peers = peers, - leases = leases, - verseId = "local", - role = "schema", - tuning = CultNetRudpSocketTuning(resendDelayMs = 25, maxFragmentBytes = 1024, maxPendingReliablePackets = 16), - ).use { client -> - client.connect("join") - check(pumpRudpPairUntilConnected(client, server)) + val serverPumpDone = AtomicBoolean(false) + val serverPump = Thread { + while (!server.connected && !serverPumpDone.get()) { + server.receiveOnce() + server.pollResends() + Thread.sleep(5) + } + } + serverPump.isDaemon = true + serverPump.start() + + val client = try { + CultMesh.connectRudpClientForAuthorizedPeer( + runtimeId = "kotlin-rudp-sugar-client", + connectionId = connectionId, + peers = peers, + leases = leases, + verseId = "local", + role = "schema", + tuning = CultNetRudpSocketTuning(resendDelayMs = 25, maxFragmentBytes = 1024, maxPendingReliablePackets = 16), + connectPayload = "join".toByteArray(StandardCharsets.UTF_8), + ) + } finally { + serverPumpDone.set(true) + serverPump.join(1_000) + } + + client.use { + check(client.connected) + check(server.connected) val schemaCatalog = CultNetSchemaCatalog() schemaCatalog.upsert( defineCultNetSchemaDescriptor(