Add Kotlin WebSocket transport helper

This commit is contained in:
Meta Vens 2026-06-16 07:14:31 +01:00
commit 35f259a2a2
4 changed files with 217 additions and 4 deletions

View file

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

View file

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

View file

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

View file

@ -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 <T : Any> remember(codec: CultDocumentCodec<T>, 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<String, Any?> = emptyMap(),
@ -2539,6 +2565,7 @@ fun main(args: Array<String>) {
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