Add Kotlin CultMesh connected RUDP clients

This commit is contained in:
Meta Vens 2026-06-17 05:42:02 +01:00
commit 2ec98d60da
4 changed files with 146 additions and 20 deletions

View file

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

View file

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

View file

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

View file

@ -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<T> {
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(