feat: implement player cache system and synchronization protocols

- Added `CloudPlayerCacheImpl` as the core implementation of player caching.
- Introduced various cache types: `CacheListImpl`, `CacheSetImpl`, `CacheMapImpl`, and `CacheStructuredImpl` for structured data handling.
- Developed `EntryMeta` to manage cache entry metadata, supporting multiple entry types.
- Implemented delta packets (`PlayerCacheListDeltaPacket`, `PlayerCacheSetDeltaPacket`, etc.) for partial synchronization.
- Created full synchronization packets (`PlayerCacheFullSyncPacket`, `PlayerCacheRequestFullSyncPacket`) to support player state consistency.
- Included `ChangeCounter` for tracking cache mutations and ensuring synchronization accuracy.
- Refactored `AdventureKeySerializer` to streamline serialization logic.

Author: twisti-dev

surf-cloud-api/surf-cloud-api-common/src/main/kotlin/dev/slne/surf/cloud/api/common/netty/network/codec/StreamDecoder.kt

@@ -1,6 +1,26 @@
 package dev.slne.surf.cloud.api.common.netty.network.codec
 
+import dev.slne.surf.cloud.api.common.netty.protocol.buffer.SurfByteBuf
+import io.netty.buffer.ByteBuf
+import io.netty.buffer.Unpooled
+
 @FunctionalInterface
 fun interface StreamDecoder<I, T> {
     fun decode(buf: I): T
-}
+}
+
+inline fun <I, T> StreamDecoder<I, T>.decodeFromByteArray(
+    creator: (ByteArray) -> I,
+    from: ByteArray
+): T {
+    return decode(creator(from))
+}
+
+inline fun <I : ByteBuf, T> StreamDecoder<I, T>.decodeFromByteArray(
+    from: ByteArray,
+    creator: (ByteBuf) -> I
+) = decodeFromByteArray({ creator(Unpooled.wrappedBuffer(it)) }, from)
+
+@Suppress("NOTHING_TO_INLINE")
+inline fun <T> StreamDecoder<SurfByteBuf, T>.decodeFromByteArray(from: ByteArray) =
+    decodeFromByteArray(from) { SurfByteBuf(it) }

surf-cloud-api/surf-cloud-api-common/src/main/kotlin/dev/slne/surf/cloud/api/common/netty/network/codec/StreamEncoder.kt

@@ -1,6 +1,80 @@
 package dev.slne.surf.cloud.api.common.netty.network.codec
 
+import dev.slne.surf.cloud.api.common.netty.protocol.buffer.SurfByteBuf
+import io.netty.buffer.ByteBuf
+import io.netty.buffer.Unpooled
+
 @FunctionalInterface
 fun interface StreamEncoder<O, T> {
     fun encode(buf: O, value: T)
+}
+
+
+inline fun <O, T> StreamEncoder<O, T>.encodeToByteArray(
+    size: Int,
+    creator: (ByteArray) -> O,
+    value: T
+): ByteArray {
+    val arr = ByteArray(size)
+    val out = creator(arr)
+    encode(out, value)
+    return arr
+}
+
+inline fun <O : ByteBuf, T> StreamEncoder<O, T>.encodeToByteArray(
+    size: Int,
+    creator: (ByteBuf) -> O,
+    value: T
+): ByteArray {
+    val arr = ByteArray(size)
+    val buf = Unpooled.wrappedBuffer(arr)
+    buf.clear()
+    val out = creator(buf)
+    encode(out, value)
+
+    val written = buf.writerIndex()
+    return if (written == arr.size) arr else arr.copyOf(written)
+}
+
+inline fun <O : ByteBuf, T> StreamEncoder<O, T>.encodeInto(
+    target: ByteArray,
+    creator: (ByteBuf) -> O,
+    value: T
+): Int {
+    val buf = Unpooled.wrappedBuffer(target)
+    buf.clear()
+    val out = creator(buf)
+    encode(out, value)
+    return buf.writerIndex()
+}
+
+@Suppress("NOTHING_TO_INLINE")
+inline fun <T> StreamEncoder<SurfByteBuf, T>.encodeToByteArray(
+    size: Int,
+    value: T
+): ByteArray = encodeToByteArray(size, { buf: ByteBuf -> SurfByteBuf(buf) }, value)
+
+@Suppress("NOTHING_TO_INLINE")
+inline fun <T> StreamEncoder<SurfByteBuf, T>.encodeInto(
+    target: ByteArray,
+    value: T
+): Int = encodeInto(target, { SurfByteBuf(it) }, value)
+
+@Suppress("NOTHING_TO_INLINE")
+inline fun <T> StreamEncoder<SurfByteBuf, T>.encodeToByteArray(
+    value: T,
+    sizeOf: (T) -> Int
+): ByteArray = encodeToByteArray(sizeOf(value), value)
+
+@Suppress("NOTHING_TO_INLINE")
+inline fun <T> StreamEncoder<SurfByteBuf, T>.encodeToByteArrayDynamic(
+    value: T,
+    initialCapacity: Int = 256
+): ByteArray {
+    val buf = Unpooled.buffer(initialCapacity) // Heap-Buffer
+    encode(SurfByteBuf(buf), value)
+    val written = buf.writerIndex()
+    val out = ByteArray(written)
+    buf.getBytes(0, out)
+    return out
 }

surf-cloud-api/surf-cloud-api-common/src/main/kotlin/dev/slne/surf/cloud/api/common/netty/network/codec/kotlinx/adventure/AdventureKeySerializer.kt

@@ -1,25 +1,23 @@
 package dev.slne.surf.cloud.api.common.netty.network.codec.kotlinx.adventure
 
-import dev.slne.surf.cloud.api.common.netty.network.codec.kotlinx.CloudBufSerializer
-import dev.slne.surf.cloud.api.common.netty.protocol.buffer.SurfByteBuf
+import kotlinx.serialization.KSerializer
 import kotlinx.serialization.Serializable
 import kotlinx.serialization.descriptors.PrimitiveKind
 import kotlinx.serialization.descriptors.PrimitiveSerialDescriptor
+import kotlinx.serialization.encoding.Decoder
+import kotlinx.serialization.encoding.Encoder
 import net.kyori.adventure.key.Key
 
 typealias SerializableKey = @Serializable(with = AdventureKeySerializer::class) Key
 
-object AdventureKeySerializer : CloudBufSerializer<Key>() {
+object AdventureKeySerializer : KSerializer<Key> {
     override val descriptor = PrimitiveSerialDescriptor("Key", PrimitiveKind.STRING)
 
-    override fun serialize0(
-        buf: SurfByteBuf,
-        value: Key
-    ) {
-        buf.writeKey(value)
+    override fun serialize(encoder: Encoder, value: Key) {
+        encoder.encodeString(value.asString())
     }
 
-    override fun deserialize0(buf: SurfByteBuf): Key {
-        return buf.readKey()
+    override fun deserialize(decoder: Decoder): Key {
+        return Key.key(decoder.decodeString())
     }
 }

surf-cloud-api/surf-cloud-api-common/src/main/kotlin/dev/slne/surf/cloud/api/common/player/cache/CacheKey.kt

@@ -0,0 +1,53 @@
+package dev.slne.surf.cloud.api.common.player.cache
+
+import dev.slne.surf.cloud.api.common.netty.network.codec.StreamCodec
+import dev.slne.surf.cloud.api.common.netty.protocol.buffer.SurfByteBuf
+import kotlinx.serialization.Serializable
+import net.kyori.adventure.key.Key
+import java.util.concurrent.ConcurrentMap
+
+@Serializable
+sealed interface CacheKey<T : Any> : Key {
+    companion object {
+        fun <T : Any> of(namespace: String, value: String): CacheKey<T> {
+            return CacheKeyImpl(Key.key(namespace, value))
+        }
+
+        fun <T : Any> of(key: Key): CacheKey<T> {
+            return CacheKeyImpl(key)
+        }
+
+        operator fun <T : Any> invoke(namespace: String, value: String): CacheKey<T> {
+            return of(namespace, value)
+        }
+
+        operator fun <T : Any> invoke(key: Key): CacheKey<T> {
+            return of(key)
+        }
+    }
+
+    @Serializable
+    sealed interface Value<T : Any> : CacheKey<T> {
+        val codec: StreamCodec<SurfByteBuf, T>
+    }
+
+    @Serializable
+    sealed interface List<E : Any> : CacheKey<MutableList<E>> {
+        val elementCodec: StreamCodec<SurfByteBuf, E>
+    }
+
+    @Serializable
+    sealed interface Set<E : Any> : CacheKey<MutableSet<E>> {
+        val elementCodec: StreamCodec<SurfByteBuf, E>
+    }
+
+    @Serializable
+    sealed interface Map<K : Any, V : Any> : CacheKey<ConcurrentMap<K, V>> {
+        val keyCodec: StreamCodec<SurfByteBuf, K>
+        val valueCodec: StreamCodec<SurfByteBuf, V>
+    }
+
+    @Serializable
+    sealed interface Structured<T : Any, D: Any> : CacheKey<T>
+}
+

surf-cloud-api/surf-cloud-api-common/src/main/kotlin/dev/slne/surf/cloud/api/common/player/cache/CacheKeyImpl.kt

@@ -0,0 +1,11 @@
+package dev.slne.surf.cloud.api.common.player.cache
+
+import dev.slne.surf.cloud.api.common.netty.network.codec.kotlinx.adventure.SerializableKey
+import kotlinx.serialization.Serializable
+
+@Serializable
+data class CacheKeyImpl<T : Any>(private val backing: SerializableKey) : CacheKey<T> {
+    override fun namespace() = backing.namespace()
+    override fun value() = backing.value()
+    override fun asString() = backing.asString()
+}

surf-cloud-api/surf-cloud-api-common/src/main/kotlin/dev/slne/surf/cloud/api/common/player/cache/CacheStructured.kt

@@ -0,0 +1,8 @@
+package dev.slne.surf.cloud.api.common.player.cache
+
+interface CacheStructured<T : Any, D : Any> : DirtyMarkable {
+    var value: T
+    val type: StructuredType<T, D>
+
+    fun emit(delta: D)
+}

surf-cloud-api/surf-cloud-api-common/src/main/kotlin/dev/slne/surf/cloud/api/common/player/cache/CacheTypes.kt

@@ -0,0 +1,31 @@
+package dev.slne.surf.cloud.api.common.player.cache
+
+import it.unimi.dsi.fastutil.objects.ObjectArrayList
+import it.unimi.dsi.fastutil.objects.ObjectList
+import it.unimi.dsi.fastutil.objects.ObjectOpenHashSet
+import org.gradle.internal.impldep.it.unimi.dsi.fastutil.objects.Object2ObjectMap
+import java.util.concurrent.ConcurrentMap
+
+interface DeltaBacked {
+    var suppressOutbound: Boolean
+}
+
+interface CacheList<E : Any> : ObjectList<E>, DeltaBacked {
+    fun snapshot(): ObjectArrayList<E>
+}
+
+interface CacheSet<E : Any> : MutableSet<E>, DeltaBacked {
+    fun snapshot(): ObjectOpenHashSet<E>
+}
+
+interface CacheMap<K : Any, V : Any> : ConcurrentMap<K, V>, DeltaBacked {
+    fun snapshot(): Object2ObjectMap<K, V>
+
+    // TODO: 13.08.2025 18:38 - support these methods in a better way
+//    override val entries: MutableSet<MutableMap.MutableEntry<K, V>>
+//        get() = throw UnsupportedOperationException("Use put/remove/clear on CacheMap")
+//    override val keys: MutableSet<K>
+//        get() = throw UnsupportedOperationException("Use put/remove/clear on CacheMap")
+//    override val values: MutableCollection<V>
+//        get() = throw UnsupportedOperationException("Use put/remove/clear on CacheMap")
+}

surf-cloud-api/surf-cloud-api-common/src/main/kotlin/dev/slne/surf/cloud/api/common/player/cache/CloudPlayerCache.kt

@@ -0,0 +1,33 @@
+package dev.slne.surf.cloud.api.common.player.cache
+
+import org.jetbrains.annotations.ApiStatus
+import java.util.*
+
+@ApiStatus.NonExtendable
+interface CloudPlayerCache {
+    val uuid: UUID
+
+    operator fun <T : Any> set(key: CacheKey.Value<T>, value: T)
+    operator fun <T : Any> get(key: CacheKey.Value<T>): T?
+    fun remove(key: CacheKey<*>)
+
+    fun <E : Any> list(key: CacheKey.List<E>): CacheList<E>
+
+    fun <E : Any> set(
+        key: CacheKey.Set<E>,
+    ): CacheSet<E>
+
+    fun <K : Any, V : Any> map(
+        key: CacheKey.Map<K, V>,
+    ): CacheMap<K, V>
+
+    fun <T : Any, D : Any> structured(
+        key: CacheKey.Structured<T, D>,
+        type: StructuredType<T, D>,
+        default: () -> T
+    ): CacheStructured<T, D>
+
+    fun <R> batch(block: CloudPlayerCacheBatch.() -> R): R
+
+    fun clear()
+}

surf-cloud-api/surf-cloud-api-common/src/main/kotlin/dev/slne/surf/cloud/api/common/player/cache/CloudPlayerCacheBatch.kt

@@ -0,0 +1,38 @@
+package dev.slne.surf.cloud.api.common.player.cache
+
+interface CloudPlayerCacheBatch {
+    fun <T : Any> set(key: CacheKey.Value<T>, value: T)
+    fun remove(key: CacheKey<*>)
+
+    fun <E : Any> listAdd(
+        key: CacheKey.List<E>,
+        element: E,
+        index: Int? = null
+    )
+
+    fun <E : Any> listRemoveAt(
+        key: CacheKey.List<E>,
+        index: Int
+    )
+
+    fun <E : Any> setAdd(
+        key: CacheKey.Set<E>,
+        element: E,
+    )
+
+    fun <E : Any> setRemove(
+        key: CacheKey.Set<E>,
+        element: E,
+    )
+
+    fun <K : Any, V : Any> mapPut(
+        key: CacheKey.Map<K, V>,
+        k: K,
+        v: V,
+    )
+
+    fun <K : Any, V : Any> mapRemove(
+        key: CacheKey.Map<K, V>,
+        k: K,
+    )
+}

surf-cloud-api/surf-cloud-api-common/src/main/kotlin/dev/slne/surf/cloud/api/common/player/cache/DirtyMarkable.kt

@@ -0,0 +1,7 @@
+package dev.slne.surf.cloud.api.common.player.cache
+
+interface DirtyMarkable {
+    fun markDirty()
+    fun consumeDirty(): Boolean
+
+}