diff --git a/packages/cultmesh-kotlin/README.md b/packages/cultmesh-kotlin/README.md index 60cc03ff..72fa8e14 100644 --- a/packages/cultmesh-kotlin/README.md +++ b/packages/cultmesh-kotlin/README.md @@ -6,6 +6,31 @@ It provides typed MessagePack document codecs, a tiny WebSocket CultNet lane, a single-peer CultNet RUDP socket transport, an in-memory CultCache, and the first Eve dashboard/sensor document contracts. +## CultCache Happy Path + +Kotlin keeps the cache small but typed: document definitions wrap codecs, +records are stored as encoded payload bytes, and callers work through typed +helpers: + +```kotlin +val notes = stringDocument("kotlin.note", "kotlin.note.v1") +val cache = CultCache() + +cache.put(notes, "note:1", "hello") +val note = cache.getRequired(notes, "note:1") + +val handle = cache.document(notes, "note:2") +handle.put("second") + +val allNotes = cache.getAll(notes) +cache.delete(notes, "note:1") +``` + +`CultMeshNode` exposes the same typed cache surface through `remember`, +`recall`, `require`, and `forget`. This is not the C# SoA store; it is the +Kotlin client/runtime cache shape needed for feature and ergonomic parity +without pretending Android wants Unity's hot-loop memory layout. + ## RUDP Happy Path Kotlin exposes factory helpers around the shared RUDP transport so callers can 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 9b6193fe..bda0c0a8 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 @@ -29,26 +29,150 @@ interface CultDocumentCodec { fun decode(payload: ByteArray): T } +data class CultDocumentDefinition( + val codec: CultDocumentCodec, + val global: Boolean = false, +) { + val documentType: String get() = codec.documentType + val schemaVersion: String get() = codec.schemaVersion +} + +data class CultCacheRecord( + val key: String, + val value: T, +) + class CultCache { + companion object { + const val GLOBAL_KEY = "__global__" + } + private val codecs = linkedMapOf>() - private val values = linkedMapOf() + private val values = linkedMapOf>() fun register(codec: CultDocumentCodec) { codecs[codec.documentType] = codec } - fun put(codec: CultDocumentCodec, key: String, value: T) { - register(codec) - values["${codec.documentType}\n$key"] = value + fun register(document: CultDocumentDefinition) { + register(document.codec) + } + + fun put(codec: CultDocumentCodec, key: String, value: T) { + register(codec) + values.getOrPut(codec.documentType) { linkedMapOf() }[key] = codec.encode(value) + } + + fun put(document: CultDocumentDefinition, key: String, value: T) { + if (document.global && key != GLOBAL_KEY) throw IOException("Global document ${document.documentType} must use putGlobal") + put(document.codec, key, value) } - @Suppress("UNCHECKED_CAST") fun get(codec: CultDocumentCodec, key: String): T? { register(codec) - return values["${codec.documentType}\n$key"] as? T + return values[codec.documentType]?.get(key)?.let { codec.decode(it.copyOf()) } } + + fun get(document: CultDocumentDefinition, key: String): T? { + if (document.global && key != GLOBAL_KEY) throw IOException("Global document ${document.documentType} must use getGlobal") + return get(document.codec, key) + } + + fun getRequired(codec: CultDocumentCodec, key: String): T = + get(codec, key) ?: throw NoSuchElementException("No ${codec.documentType} record for key $key") + + fun getRequired(document: CultDocumentDefinition, key: String): T = + get(document, key) ?: throw NoSuchElementException("No ${document.documentType} record for key $key") + + fun getAll(codec: CultDocumentCodec): List> { + register(codec) + return values[codec.documentType] + ?.map { (key, payload) -> CultCacheRecord(key, codec.decode(payload.copyOf())) } + ?: emptyList() + } + + fun getAll(document: CultDocumentDefinition): List> = getAll(document.codec) + + fun delete(codec: CultDocumentCodec, key: String): Boolean { + register(codec) + val records = values[codec.documentType] ?: return false + val removed = records.remove(key) != null + if (records.isEmpty()) values.remove(codec.documentType) + return removed + } + + fun delete(document: CultDocumentDefinition, key: String): Boolean { + if (document.global && key != GLOBAL_KEY) throw IOException("Global document ${document.documentType} must use deleteGlobal") + return delete(document.codec, key) + } + + fun putGlobal(document: CultDocumentDefinition, value: T) { + put(document.codec, GLOBAL_KEY, value) + } + + fun getGlobal(document: CultDocumentDefinition): T? = get(document.codec, GLOBAL_KEY) + + fun getRequiredGlobal(document: CultDocumentDefinition): T = + getGlobal(document) ?: throw NoSuchElementException("No global ${document.documentType} record") + + fun deleteGlobal(document: CultDocumentDefinition): Boolean = delete(document.codec, GLOBAL_KEY) } +fun cultDocument( + codec: CultDocumentCodec, + global: Boolean = false, +): CultDocumentDefinition = CultDocumentDefinition(codec, global) + +class CultCacheDocumentHandle( + private val cache: CultCache, + private val document: CultDocumentDefinition, + private val key: String, +) { + fun get(): T? = cache.get(document, key) + + fun require(): T = cache.getRequired(document, key) + + fun put(value: T) = cache.put(document, key, value) + + fun delete(): Boolean = cache.delete(document, key) +} + +fun CultCache.document(document: CultDocumentDefinition, key: String): CultCacheDocumentHandle = + CultCacheDocumentHandle(this, document, key) + +fun CultCache.global(document: CultDocumentDefinition): CultCacheDocumentHandle = + CultCacheDocumentHandle(this, document, CultCache.GLOBAL_KEY) + +class StringDocumentCodec( + override val documentType: String, + override val schemaVersion: String, +) : CultDocumentCodec { + override fun encode(value: String): ByteArray = value.toByteArray(StandardCharsets.UTF_8) + + override fun decode(payload: ByteArray): String = String(payload, StandardCharsets.UTF_8) +} + +class ByteArrayDocumentCodec( + override val documentType: String, + override val schemaVersion: String, +) : CultDocumentCodec { + override fun encode(value: ByteArray): ByteArray = value.copyOf() + + override fun decode(payload: ByteArray): ByteArray = payload.copyOf() +} + +fun stringDocument( + documentType: String, + schemaVersion: String, + global: Boolean = false, +): CultDocumentDefinition = cultDocument(StringDocumentCodec(documentType, schemaVersion), global) + +fun bytesDocument( + documentType: String, + schemaVersion: String, + global: Boolean = false, +): CultDocumentDefinition = cultDocument(ByteArrayDocumentCodec(documentType, schemaVersion), global) + class CultMeshNode( val cache: CultCache = CultCache(), private val random: SecureRandom = SecureRandom(), @@ -59,7 +183,27 @@ class CultMeshNode( cache.put(codec, key, value) } + fun remember(document: CultDocumentDefinition, key: String, value: T) { + cache.put(document, key, value) + } + + fun rememberGlobal(document: CultDocumentDefinition, value: T) { + cache.putGlobal(document, value) + } + fun recall(codec: CultDocumentCodec, key: String): T? = cache.get(codec, key) + + fun recall(document: CultDocumentDefinition, key: String): T? = cache.get(document, key) + + fun require(document: CultDocumentDefinition, key: String): T = cache.getRequired(document, key) + + fun recallGlobal(document: CultDocumentDefinition): T? = cache.getGlobal(document) + + fun requireGlobal(document: CultDocumentDefinition): T = cache.getRequiredGlobal(document) + + fun forget(document: CultDocumentDefinition, key: String): Boolean = cache.delete(document, key) + + fun forgetGlobal(document: CultDocumentDefinition): Boolean = cache.deleteGlobal(document) } data class CultNetFrame(val opcode: Int, val payload: ByteArray) @@ -776,6 +920,7 @@ private fun nowMs(): Long = Instant.now().toEpochMilli() fun main(args: Array) { if (args.isEmpty()) { + cultCacheErgonomicsCoverTypedDocumentsAndGlobals() rudpPacketCodecUsesDeterministicReliableOrderedFixture() rudpSessionPingsAndDetectsReceiveTimeout() rudpSessionBoundsPendingReliablePacketsBeforeEnqueue() @@ -794,6 +939,37 @@ fun main(args: Array) { } } +private fun cultCacheErgonomicsCoverTypedDocumentsAndGlobals() { + val notes = stringDocument("kotlin.note", "kotlin.note.v1") + val settings = stringDocument("kotlin.settings", "kotlin.settings.v1", global = true) + val blobs = bytesDocument("kotlin.blob", "kotlin.blob.v1") + val cache = CultCache() + + cache.put(notes, "note:1", "hello") + check(cache.getRequired(notes, "note:1") == "hello") + val handle = cache.document(notes, "note:2") + handle.put("second") + check(handle.require() == "second") + check(cache.getAll(notes).map { it.key to it.value } == listOf("note:1" to "hello", "note:2" to "second")) + check(cache.delete(notes, "note:1")) + check(cache.get(notes, "note:1") == null) + + cache.putGlobal(settings, "dark-mode") + check(cache.global(settings).require() == "dark-mode") + check(cache.deleteGlobal(settings)) + check(cache.getGlobal(settings) == null) + + val payload = byteArrayOf(1, 2, 3) + cache.put(blobs, "blob:1", payload) + payload[0] = 9 + check(cache.getRequired(blobs, "blob:1").contentEquals(byteArrayOf(1, 2, 3))) + + val node = CultMeshNode() + node.remember(notes, "node-note", "remembered") + check(node.require(notes, "node-note") == "remembered") + check(node.forget(notes, "node-note")) +} + private fun rudpServeOnce(options: Map) { val bindHost = options["bind-host"] ?: "127.0.0.1" val bindPort = options["bind-port"]?.toInt() ?: 0