From 49a5a2ae30836cbaf98eff5868b1b9ff13e1c6ca Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Tue, 16 Jun 2026 11:41:32 +0100 Subject: [PATCH] Add Kotlin WebSocket schema message sugar --- docs/cultnet-transport-parity.md | 4 ++- packages/cultmesh-kotlin/README.md | 11 +++++-- .../kotlin/org/gamecult/cultmesh/CultMesh.kt | 29 ++++++++++++++----- 3 files changed, 34 insertions(+), 10 deletions(-) diff --git a/docs/cultnet-transport-parity.md b/docs/cultnet-transport-parity.md index 578f4571..d831fd1a 100644 --- a/docs/cultnet-transport-parity.md +++ b/docs/cultnet-transport-parity.md @@ -181,7 +181,9 @@ Current progress: - 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. + reliable ordered `schema` frames. The adapter now also has `sendSchemaMessage` + and `receiveSchemaMessage` sugar so JVM callers can exchange schema-v0 + MessagePack messages without hand-parsing transport 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/packages/cultmesh-kotlin/README.md b/packages/cultmesh-kotlin/README.md index 1fbcdd94..801a82da 100644 --- a/packages/cultmesh-kotlin/README.md +++ b/packages/cultmesh-kotlin/README.md @@ -82,11 +82,18 @@ val transport = CultMesh.startNode().connectTransport(URI("ws://127.0.0.1:3075/m transport.sendSchema(cultNetSchemaCatalogRequest(messageId = "schemas").toBytes()) val frame = transport.receive() check(frame?.channelId == "schema") + +// Or stay at the schema-message level. +transport.sendSchemaMessage(cultNetSchemaCatalogRequest(messageId = "schemas")) +val message = transport.receiveSchemaMessage() +check(message?.schemaVersion == "cultnet.schema_catalog_response.v0") ``` 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. +reliable ordered `schema` channel and exposes transfer stats. `sendSchema`, +`sendSchemaMessage`, `receiveSchema`, and `receiveSchemaMessage` keep the +schema lane at the same ergonomic level as RUDP. 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 11f1055f..daf64293 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 @@ -2918,9 +2918,17 @@ private fun cultNetWebSocketTransportCarriesSchemaFramesWithStats() { ).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)) + val request = parseCultNetMessage(readMaskedWebSocketBinaryPayload(input)) + check(request.schemaVersion == "cultnet.schema_catalog_request.v0") + writeUnmaskedWebSocketBinaryPayload( + output, + cultNetHello( + runtimeId = "kotlin-websocket-server", + runtimeKind = "kotlin", + displayName = "Kotlin WebSocket Server", + supportedMessageVersions = listOf("cultnet.hello.v0"), + ).toBytes(), + ) } } catch (error: Throwable) { serverError = error @@ -2937,10 +2945,11 @@ private fun cultNetWebSocketTransportCarriesSchemaFramesWithStats() { 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") + transport.sendSchemaMessage(cultNetSchemaCatalogRequest(messageId = "websocket-schema")) + val response = transport.receiveSchemaMessage() + ?: error("WebSocket transport did not receive schema message") + check(response.schemaVersion == "cultnet.hello.v0") + check(response.body["runtimeId"] == "kotlin-websocket-server") check(transport.stats.framesSent == 1L) check(transport.stats.framesReceived == 1L) } @@ -3960,6 +3969,8 @@ class CultNetWebSocketTransportConnection( fun sendSchema(payload: String) = sendSchema(payload.toByteArray(StandardCharsets.UTF_8)) + fun sendSchemaMessage(message: CultNetMessage) = sendSchema(message.toBytes()) + fun receive(): CultNetTransportFrame? { val frame = client.readFrame() if (frame.opcode != 2) return null @@ -3967,6 +3978,10 @@ class CultNetWebSocketTransportConnection( return CultNetTransportFrame("schema", frame.payload) } + fun receiveSchema(): ByteArray? = receive()?.takeIf { it.channelId == "schema" }?.payload + + fun receiveSchemaMessage(): CultNetMessage? = receiveSchema()?.let { parseCultNetMessage(it) } + override fun close() { client.close() }