diff --git a/docs/cultnet-transport-parity.md b/docs/cultnet-transport-parity.md index d77924c7..c9ff1d96 100644 --- a/docs/cultnet-transport-parity.md +++ b/docs/cultnet-transport-parity.md @@ -32,7 +32,7 @@ CultNet owns cross-runtime transport semantics: | TypeScript `cultnet-ts` | `CultNetPeer` over any Node `Duplex`, TCP-framed transport, or single-peer RUDP socket transport; interop uses TCP | UDP multicast probe/announce in the interop peer | First UDP socket binding for the shared RUDP reliability owner | | Rust `cultnet-rs` | Interop example uses TCP length-prefixed MessagePack frames; single-peer RUDP socket transport exists in the library | UDP multicast probe/announce | UDP socket binding for the shared RUDP reliability owner | | Python `cultcache-py` | TCP sockets with 4-byte length-prefixed MessagePack frames for local CultMesh/CultNet server and client; single-peer RUDP socket transport exists in the library | Endpoint lists and CultMesh peer/Verse catalogs | UDP socket binding for the shared RUDP reliability owner | -| Kotlin `cultmesh-kotlin` | Minimal WebSocket-like lane over TCP socket; single-peer RUDP socket transport exists in the library | CultMesh Verse and peer catalogs, plus endpoint lists carried in schema-v0 catalog messages | UDP socket binding for the shared RUDP reliability owner, with build-script self-test | +| Kotlin `cultmesh-kotlin` | Channel-aware WebSocket transport connection for reliable ordered `schema` frames; single-peer RUDP socket transport exists in the library | CultMesh Verse and peer catalogs, plus endpoint lists carried in schema-v0 catalog messages | WebSocket adapter plus UDP socket binding for the shared RUDP reliability owner, with build-script self-test | The live split is therefore: payload language and the native RUDP packet/session language now converge across the targeted runtimes, while production service @@ -160,6 +160,10 @@ Current progress: `TcpFramedTransportConnection` with schema-channel `send`, `receive`, and transfer stats. The Rust interop peer advertises and uses that shared port instead of owning raw TCP frame I/O directly. +- Kotlin now has a `websocket` transport profile helper plus + `CultNetWebSocketTransportConnection`, which wraps the older binary + WebSocket client behind the same `CultNetTransportFrame` and stats shape for + reliable ordered `schema` frames. - TypeScript, C#, Rust, Python, and Kotlin now share the first `cultnet.transport.rudp.v0` packet codec fixture: the same reliable ordered fragmented data packet encodes to the same bytes in every runtime. This is not diff --git a/docs/runtime-parity-scope.md b/docs/runtime-parity-scope.md index 33f74f35..4d85325c 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, schema catalogs, shard catalogs/logs, local TCP CultMesh server, session/prediction/simulation fact helpers, authority leases, streams, 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, transport profiles, TCP-framed transport port, shared RUDP socket transport, RUDP reconnect policy/controller, RUDP reconnect-loop helper, local CultMesh node/catalog/authority/stream ergonomics | Full C# game session/server stack | | Rust | Low-level cache/transport/runtime substrate | CultCache/CultNet interop lane, 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 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, schema/shard catalogs, authority leases, stream catalog, branded `CultMesh` facade, 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, schema/shard catalogs, authority leases, 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 | ## Evidence Gates diff --git a/packages/cultmesh-kotlin/README.md b/packages/cultmesh-kotlin/README.md index 1dbae2ac..88536d75 100644 --- a/packages/cultmesh-kotlin/README.md +++ b/packages/cultmesh-kotlin/README.md @@ -2,8 +2,8 @@ Kotlin/JVM and Android client substrate for CultCache, CultNet, and CultMesh. -It provides typed MessagePack document codecs, a tiny WebSocket CultNet lane, -a single-peer CultNet RUDP socket transport, stream catalog negotiation, an +It provides typed MessagePack document codecs, a channel-aware WebSocket +CultNet transport, a single-peer CultNet RUDP socket transport, stream catalog negotiation, an in-memory CultCache, and the first Eve dashboard/sensor document contracts. The branded entrypoint mirrors C#/TypeScript/Python: @@ -68,6 +68,24 @@ val note = target.require(notes, "note:1") raw bytes re-enter the typed cache through the same document definitions that local Kotlin callers use. +## WebSocket Transport + +For browser/mobile-friendly schema lanes, `CultNetWebSocketTransportConnection` +wraps the tiny WebSocket client behind the same transport-frame shape used by +the other runtimes: + +```kotlin +val transport = CultMesh.startNode().connectTransport(URI("ws://127.0.0.1:3075/mesh")) + +transport.sendSchema(cultNetSchemaCatalogRequest(messageId = "schemas").toBytes()) +val frame = transport.receive() +check(frame?.channelId == "schema") +``` + +The WebSocket adapter advertises a `websocket` transport profile with one +reliable ordered `schema` channel and exposes transfer stats. It is the stream +adapter; RUDP remains the portable realtime UDP path. + Schema catalogs are also first-class, so Kotlin peers can publish and consume descriptor responses instead of hand-assembling maps: 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 a190a07c..fa1d7d0a 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 @@ -11,6 +11,7 @@ import java.net.DatagramPacket import java.net.DatagramSocket import java.net.InetAddress import java.net.InetSocketAddress +import java.net.ServerSocket import java.net.Socket import java.net.SocketTimeoutException import java.net.URI @@ -227,6 +228,9 @@ class CultMeshNode( ) { fun connect(uri: URI): CultNetWebSocketClient = CultNetWebSocketClient.connect(uri, random) + fun connectTransport(uri: URI): CultNetWebSocketTransportConnection = + CultNetWebSocketTransportConnection.connect(uri, random) + fun remember(codec: CultDocumentCodec, key: String, value: T) { cache.put(codec, key, value) } @@ -615,6 +619,28 @@ fun createRudpTransportProfile( ), ) +fun createWebSocketTransportProfile( + runtimeId: String, + transportId: String = "websocket", + host: String? = null, + port: Int? = null, + maxPayloadBytes: Int? = null, +): CultNetTransportProfile = CultNetTransportProfile( + runtimeId = runtimeId, + transports = listOf( + CultNetTransportDescriptor( + transportId = transportId.ifBlank { "websocket" }, + protocol = "websocket", + host = host, + port = port, + wireContracts = listOf("cultnet.schema.v0"), + channels = listOf( + CultNetTransportChannel("schema", "reliable", "ordered", maxPayloadBytes), + ), + ), + ), +) + data class CultNetMessage( val schemaVersion: String, val body: Map = emptyMap(), @@ -2539,6 +2565,7 @@ fun main(args: Array) { cultNetReconnectPolicyExposesPortableDelayContract() cultNetReconnectControllerSchedulesAttemptsAndReset() cultNetRudpReconnectLoopConsumesSharedController() + cultNetWebSocketTransportCarriesSchemaFramesWithStats() cultNetSchemaCatalogsRoundTripDescriptors() cultMeshCatalogsRoundTripDiscoveryMessages() cultMeshAuthorityLeasesGatePeerTrust() @@ -2817,6 +2844,58 @@ private fun cultNetRudpReconnectLoopConsumesSharedController() { check(loop.transport == null) } +private fun cultNetWebSocketTransportCarriesSchemaFramesWithStats() { + val loopback = InetAddress.getByName("127.0.0.1") + ServerSocket(0, 1, loopback).use { server -> + var serverError: Throwable? = null + val thread = Thread { + try { + server.accept().use { socket -> + socket.soTimeout = 1_000 + val input = socket.getInputStream() + val output = socket.getOutputStream() + readWebSocketHandshake(input) + output.write( + ( + "HTTP/1.1 101 Switching Protocols\r\n" + + "Upgrade: websocket\r\n" + + "Connection: Upgrade\r\n\r\n" + ).toByteArray(StandardCharsets.US_ASCII), + ) + output.flush() + val request = readMaskedWebSocketBinaryPayload(input) + check(String(request, StandardCharsets.UTF_8) == "client-state") + writeUnmaskedWebSocketBinaryPayload(output, "server-state".toByteArray(StandardCharsets.UTF_8)) + } + } catch (error: Throwable) { + serverError = error + } + } + thread.isDaemon = true + thread.start() + + CultNetWebSocketTransportConnection.connect( + URI("ws://127.0.0.1:${server.localPort}/mesh"), + runtimeId = "kotlin-websocket-test", + ).use { transport -> + val descriptor = transport.profile.transports.single() + check(descriptor.protocol == "websocket") + check(descriptor.channels == listOf(CultNetTransportChannel("schema", "reliable", "ordered"))) + + transport.sendSchema("client-state") + val response = transport.receive() ?: error("WebSocket transport did not receive schema frame") + check(response.channelId == "schema") + check(String(response.payload, StandardCharsets.UTF_8) == "server-state") + check(transport.stats.framesSent == 1L) + check(transport.stats.framesReceived == 1L) + } + + thread.join(1_000) + if (thread.isAlive) error("WebSocket transport test server did not finish") + serverError?.let { throw it } + } +} + private fun cultNetSchemaCatalogsRoundTripDescriptors() { val catalog = CultNetSchemaCatalog() var watched: CultNetSchemaDescriptor? = null @@ -3710,6 +3789,118 @@ private fun InputStream.readExact(buffer: ByteArray) { } } +private fun readWebSocketHandshake(input: InputStream): String { + val bytes = ByteArrayOutputStream() + var a = -1 + var b = -1 + var c = -1 + while (true) { + val d = input.read() + if (d < 0) throw EOFException("websocket handshake closed") + bytes.write(d) + if (a == '\r'.code && b == '\n'.code && c == '\r'.code && d == '\n'.code) break + a = b + b = c + c = d + } + return bytes.toString(StandardCharsets.US_ASCII.name()) +} + +private fun readMaskedWebSocketBinaryPayload(input: InputStream): ByteArray { + val b0 = input.read() + val b1 = input.read() + if (b0 < 0 || b1 < 0) throw EOFException("websocket frame closed") + if ((b0 and 0x0f) != 2) throw IOException("Expected websocket binary opcode, received ${b0 and 0x0f}") + if ((b1 and 0x80) == 0) throw IOException("Expected masked websocket client frame") + var length = (b1 and 0x7f).toLong() + if (length == 126L) { + val extended = ByteArray(2) + input.readExact(extended) + length = ((extended[0].toInt() and 0xff) shl 8 or (extended[1].toInt() and 0xff)).toLong() + } else if (length == 127L) { + val extended = ByteArray(8) + input.readExact(extended) + length = ByteBuffer.wrap(extended).getLong() + } + val mask = ByteArray(4) + input.readExact(mask) + val payload = ByteArray(length.toInt()) + input.readExact(payload) + payload.indices.forEach { payload[it] = (payload[it].toInt() xor mask[it % 4].toInt()).toByte() } + return payload +} + +private fun writeUnmaskedWebSocketBinaryPayload(output: OutputStream, payload: ByteArray) { + val frame = ByteArrayOutputStream() + frame.write(0x82) + when { + payload.size < 126 -> frame.write(payload.size) + payload.size <= 65535 -> { + frame.write(126) + frame.write((payload.size shr 8) and 0xff) + frame.write(payload.size and 0xff) + } + else -> { + frame.write(127) + frame.write(ByteBuffer.allocate(8).putLong(payload.size.toLong()).array()) + } + } + frame.write(payload) + output.write(frame.toByteArray()) + output.flush() +} + +class CultNetWebSocketTransportConnection( + private val client: CultNetWebSocketClient, + val profile: CultNetTransportProfile, +) : AutoCloseable { + var stats: CultNetTransportStats = CultNetTransportStats() + private set + + companion object { + fun connect( + uri: URI, + random: SecureRandom = SecureRandom(), + runtimeId: String = "kotlin-websocket-client", + transportId: String = "websocket", + maxPayloadBytes: Int? = null, + ): CultNetWebSocketTransportConnection { + val port = if (uri.port > 0) uri.port else 80 + return CultNetWebSocketTransportConnection( + CultNetWebSocketClient.connect(uri, random), + createWebSocketTransportProfile( + runtimeId = runtimeId, + transportId = transportId, + host = uri.host, + port = port, + maxPayloadBytes = maxPayloadBytes, + ), + ) + } + } + + fun send(channelId: String, payload: ByteArray) { + if (channelId != "schema") throw IOException("websocket transport only supports the reliable ordered schema channel") + client.sendBinary(payload) + stats = stats.copy(bytesSent = stats.bytesSent + payload.size, framesSent = stats.framesSent + 1) + } + + fun sendSchema(payload: ByteArray) = send("schema", payload) + + fun sendSchema(payload: String) = sendSchema(payload.toByteArray(StandardCharsets.UTF_8)) + + fun receive(): CultNetTransportFrame? { + val frame = client.readFrame() + if (frame.opcode != 2) return null + stats = stats.copy(bytesReceived = stats.bytesReceived + frame.payload.size, framesReceived = stats.framesReceived + 1) + return CultNetTransportFrame("schema", frame.payload) + } + + override fun close() { + client.close() + } +} + class MessagePackReader(payload: ByteArray) { private val input = DataInputStream(ByteArrayInputStream(payload)) private var pushed = -1