Add Kotlin typed cache ergonomics
This commit is contained in:
parent
0d2bbe7029
commit
908db9e5a7
2 changed files with 205 additions and 4 deletions
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -29,26 +29,150 @@ interface CultDocumentCodec<T> {
|
|||
fun decode(payload: ByteArray): T
|
||||
}
|
||||
|
||||
data class CultDocumentDefinition<T : Any>(
|
||||
val codec: CultDocumentCodec<T>,
|
||||
val global: Boolean = false,
|
||||
) {
|
||||
val documentType: String get() = codec.documentType
|
||||
val schemaVersion: String get() = codec.schemaVersion
|
||||
}
|
||||
|
||||
data class CultCacheRecord<T : Any>(
|
||||
val key: String,
|
||||
val value: T,
|
||||
)
|
||||
|
||||
class CultCache {
|
||||
companion object {
|
||||
const val GLOBAL_KEY = "__global__"
|
||||
}
|
||||
|
||||
private val codecs = linkedMapOf<String, CultDocumentCodec<*>>()
|
||||
private val values = linkedMapOf<String, Any>()
|
||||
private val values = linkedMapOf<String, LinkedHashMap<String, ByteArray>>()
|
||||
|
||||
fun <T : Any> register(codec: CultDocumentCodec<T>) {
|
||||
codecs[codec.documentType] = codec
|
||||
}
|
||||
|
||||
fun <T : Any> put(codec: CultDocumentCodec<T>, key: String, value: T) {
|
||||
register(codec)
|
||||
values["${codec.documentType}\n$key"] = value
|
||||
fun <T : Any> register(document: CultDocumentDefinition<T>) {
|
||||
register(document.codec)
|
||||
}
|
||||
|
||||
fun <T : Any> put(codec: CultDocumentCodec<T>, key: String, value: T) {
|
||||
register(codec)
|
||||
values.getOrPut(codec.documentType) { linkedMapOf() }[key] = codec.encode(value)
|
||||
}
|
||||
|
||||
fun <T : Any> put(document: CultDocumentDefinition<T>, 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 <T : Any> get(codec: CultDocumentCodec<T>, 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 <T : Any> get(document: CultDocumentDefinition<T>, key: String): T? {
|
||||
if (document.global && key != GLOBAL_KEY) throw IOException("Global document ${document.documentType} must use getGlobal")
|
||||
return get(document.codec, key)
|
||||
}
|
||||
|
||||
fun <T : Any> getRequired(codec: CultDocumentCodec<T>, key: String): T =
|
||||
get(codec, key) ?: throw NoSuchElementException("No ${codec.documentType} record for key $key")
|
||||
|
||||
fun <T : Any> getRequired(document: CultDocumentDefinition<T>, key: String): T =
|
||||
get(document, key) ?: throw NoSuchElementException("No ${document.documentType} record for key $key")
|
||||
|
||||
fun <T : Any> getAll(codec: CultDocumentCodec<T>): List<CultCacheRecord<T>> {
|
||||
register(codec)
|
||||
return values[codec.documentType]
|
||||
?.map { (key, payload) -> CultCacheRecord(key, codec.decode(payload.copyOf())) }
|
||||
?: emptyList()
|
||||
}
|
||||
|
||||
fun <T : Any> getAll(document: CultDocumentDefinition<T>): List<CultCacheRecord<T>> = getAll(document.codec)
|
||||
|
||||
fun <T : Any> delete(codec: CultDocumentCodec<T>, 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 <T : Any> delete(document: CultDocumentDefinition<T>, key: String): Boolean {
|
||||
if (document.global && key != GLOBAL_KEY) throw IOException("Global document ${document.documentType} must use deleteGlobal")
|
||||
return delete(document.codec, key)
|
||||
}
|
||||
|
||||
fun <T : Any> putGlobal(document: CultDocumentDefinition<T>, value: T) {
|
||||
put(document.codec, GLOBAL_KEY, value)
|
||||
}
|
||||
|
||||
fun <T : Any> getGlobal(document: CultDocumentDefinition<T>): T? = get(document.codec, GLOBAL_KEY)
|
||||
|
||||
fun <T : Any> getRequiredGlobal(document: CultDocumentDefinition<T>): T =
|
||||
getGlobal(document) ?: throw NoSuchElementException("No global ${document.documentType} record")
|
||||
|
||||
fun <T : Any> deleteGlobal(document: CultDocumentDefinition<T>): Boolean = delete(document.codec, GLOBAL_KEY)
|
||||
}
|
||||
|
||||
fun <T : Any> cultDocument(
|
||||
codec: CultDocumentCodec<T>,
|
||||
global: Boolean = false,
|
||||
): CultDocumentDefinition<T> = CultDocumentDefinition(codec, global)
|
||||
|
||||
class CultCacheDocumentHandle<T : Any>(
|
||||
private val cache: CultCache,
|
||||
private val document: CultDocumentDefinition<T>,
|
||||
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 <T : Any> CultCache.document(document: CultDocumentDefinition<T>, key: String): CultCacheDocumentHandle<T> =
|
||||
CultCacheDocumentHandle(this, document, key)
|
||||
|
||||
fun <T : Any> CultCache.global(document: CultDocumentDefinition<T>): CultCacheDocumentHandle<T> =
|
||||
CultCacheDocumentHandle(this, document, CultCache.GLOBAL_KEY)
|
||||
|
||||
class StringDocumentCodec(
|
||||
override val documentType: String,
|
||||
override val schemaVersion: String,
|
||||
) : CultDocumentCodec<String> {
|
||||
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<ByteArray> {
|
||||
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<String> = cultDocument(StringDocumentCodec(documentType, schemaVersion), global)
|
||||
|
||||
fun bytesDocument(
|
||||
documentType: String,
|
||||
schemaVersion: String,
|
||||
global: Boolean = false,
|
||||
): CultDocumentDefinition<ByteArray> = 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 <T : Any> remember(document: CultDocumentDefinition<T>, key: String, value: T) {
|
||||
cache.put(document, key, value)
|
||||
}
|
||||
|
||||
fun <T : Any> rememberGlobal(document: CultDocumentDefinition<T>, value: T) {
|
||||
cache.putGlobal(document, value)
|
||||
}
|
||||
|
||||
fun <T : Any> recall(codec: CultDocumentCodec<T>, key: String): T? = cache.get(codec, key)
|
||||
|
||||
fun <T : Any> recall(document: CultDocumentDefinition<T>, key: String): T? = cache.get(document, key)
|
||||
|
||||
fun <T : Any> require(document: CultDocumentDefinition<T>, key: String): T = cache.getRequired(document, key)
|
||||
|
||||
fun <T : Any> recallGlobal(document: CultDocumentDefinition<T>): T? = cache.getGlobal(document)
|
||||
|
||||
fun <T : Any> requireGlobal(document: CultDocumentDefinition<T>): T = cache.getRequiredGlobal(document)
|
||||
|
||||
fun <T : Any> forget(document: CultDocumentDefinition<T>, key: String): Boolean = cache.delete(document, key)
|
||||
|
||||
fun <T : Any> forgetGlobal(document: CultDocumentDefinition<T>): 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<String>) {
|
||||
if (args.isEmpty()) {
|
||||
cultCacheErgonomicsCoverTypedDocumentsAndGlobals()
|
||||
rudpPacketCodecUsesDeterministicReliableOrderedFixture()
|
||||
rudpSessionPingsAndDetectsReceiveTimeout()
|
||||
rudpSessionBoundsPendingReliablePacketsBeforeEnqueue()
|
||||
|
|
@ -794,6 +939,37 @@ fun main(args: Array<String>) {
|
|||
}
|
||||
}
|
||||
|
||||
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<String, String>) {
|
||||
val bindHost = options["bind-host"] ?: "127.0.0.1"
|
||||
val bindPort = options["bind-port"]?.toInt() ?: 0
|
||||
|
|
|
|||
Loading…
Reference in a new issue