feat: enhance whitelist functionality and transaction handling

- Refactored whitelist handling by replacing separate group and server fields with `Either<String, String>`.
- Added support for cascading updates in multiple tables and associated migrations.
- Introduced `CoroutineTxContextProvider` to manage coroutine transaction contexts dynamically.
- Updated dependencies (`spring-boot` to 3.5.4, `surf-api-gradle-plugin` to 1.21.8).
- Improved cache handling with Caffeine for annotations and transaction providers.
- General code cleanup and removed unused imports.

Author: twisti-dev

build.gradle.kts

@@ -1,6 +1,5 @@
 import com.github.jengelman.gradle.plugins.shadow.tasks.ShadowJar
 import dev.slne.surf.surfapi.gradle.util.slnePublic
-import jdk.javadoc.internal.tool.resources.javadoc
 import org.jetbrains.kotlin.gradle.dsl.KotlinJvmExtension
 
 buildscript {
@@ -9,7 +8,7 @@ buildscript {
         maven("https://repo.slne.dev/repository/maven-public/") { name = "maven-public" }
     }
     dependencies {
-        classpath("dev.slne.surf:surf-api-gradle-plugin:1.21.7+")
+        classpath("dev.slne.surf:surf-api-gradle-plugin:1.21.8+")
     }
 }
 
@@ -41,7 +40,7 @@ allprojects {
 
         implementation(platform(project(":surf-cloud-bom")))
 
-        compileOnly("org.springframework.boot:spring-boot-configuration-processor:3.5.3")
+        compileOnly("org.springframework.boot:spring-boot-configuration-processor:3.5.4")
         //    "kapt"("org.springframework.boot:spring-boot-configuration-processor:3.4.3")
 
         testImplementation(kotlin("test"))

buildSrc/src/main/kotlin/core-convention.gradle.kts

@@ -12,7 +12,7 @@ repositories {
 }
 
 dependencies {
-    implementation(platform("org.springframework.boot:spring-boot-dependencies:3.5.3"))
+    implementation(platform("org.springframework.boot:spring-boot-dependencies:3.5.4"))
     implementation(platform("io.ktor:ktor-bom:3.2.1"))
     implementation(platform("org.jetbrains.kotlin-wrappers:kotlin-wrappers-bom:2025.7.8"))
 

gradle.properties

@@ -6,3 +6,6 @@ kotlin.code.style=official
 org.jetbrains.dokka.experimental.gradle.pluginMode=V2Enabled
 org.jetbrains.dokka.experimental.gradle.pluginMode.noWarn=true
 version=1.21.7-1.0.0-SNAPSHOT
+ksp.incremental=false
+ksp.incremental.log=true
+ksp.useKSP2=false

gradle/wrapper/gradle-wrapper.jar

@@ -1,7 +1,7 @@
 #!/bin/sh
 
 #
-# Copyright © 2015-2021 the original authors.
+# Copyright © 2015 the original authors.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

gradlew

@@ -1,110 +1,275 @@
 package dev.slne.surf.cloud.api.common.util
 
+import dev.slne.surf.cloud.api.common.util.Either.Companion.left
+import dev.slne.surf.cloud.api.common.util.Either.Companion.right
+import kotlinx.serialization.SerialName
 import kotlinx.serialization.Serializable
 
+/**
+ * Represents a value of one of two possible types.
+ * An [Either] is either a [Left] containing a value of type [L],
+ * or a [Right] containing a value of type [R].
+ *
+ * This implementation is **neutral**: neither side implies success or failure.
+ * It is useful whenever a value can be one of two distinct, equally valid types.
+ *
+ * @param L the type of the left value.
+ * @param R the type of the right value.
+ * @property left the left value if present, otherwise `null`.
+ * @property right the right value if present, otherwise `null`.
+ */
 @Serializable
 sealed class Either<L, R> {
 
-    abstract fun <C, D> mapBoth(
-        leftMapper: (L) -> C,
-        rightMapper: (R) -> D
-    ): Either<C, D>
-
-    abstract fun <T> map(leftMapper: (L) -> T, rightMapper: (R) -> T): T
-
+    /** The left value if present, otherwise `null`. */
     abstract val left: L?
+
+    /** The right value if present, otherwise `null`. */
     abstract val right: R?
 
-    fun <T> mapLeft(mapper: (L) -> T): Either<T, R> = map({ left(mapper(it)) }, ::right)
-    fun <T> mapRight(mapper: (R) -> T): Either<L, T> = map(::left) { right(mapper(it)) }
+    /**
+     * Indicates whether this instance holds a left value.
+     *
+     * @return `true` if this is a [Left]; `false` otherwise.
+     */
+    val isLeft: Boolean get() = left != null
 
-    fun leftOrThrow(): L {
-        return left ?: throw NoSuchElementException("Either is Right, no Left value present")
-    }
+    /**
+     * Indicates whether this instance holds a right value.
+     *
+     * @return `true` if this is a [Right]; `false` otherwise.
+     */
+    val isRight: Boolean get() = right != null
 
-    fun rightOrThrow(): R {
-        return right ?: throw NoSuchElementException("Either is Left, no Right value present")
-    }
+    /**
+     * Returns the left value if present.
+     *
+     * @return the non-null left value.
+     * @throws NoSuchElementException if no left value is present.
+     */
+    fun leftOrThrow(): L = left ?: throw NoSuchElementException("Either contains no left value")
 
-    fun swap(): Either<R, L> = map(::right, ::left)
-    fun <L2> flatMap(leftMapper: (L) -> Either<L2, R>): Either<L2, R> = map(leftMapper, ::right)
+    /**
+     * Returns the right value if present.
+     *
+     * @return the non-null right value.
+     * @throws NoSuchElementException if no right value is present.
+     */
+    fun rightOrThrow(): R = right ?: throw NoSuchElementException("Either contains no right value")
 
-    companion object {
-        fun <L, R> left(value: L): Either<L, R> = Left(value)
-        fun <L, R> right(value: R): Either<L, R> = Right(value)
-        fun <U> unwrap(either: Either<out U, out U>): U = either.map({ it }, { it })
-    }
+    /**
+     * Returns the left value or `null` if absent.
+     *
+     * @return the left value, or `null` if this is a [Right].
+     */
+    fun leftOrNull(): L? = left
 
-    @PublishedApi
-    @Serializable
-    internal class Left<L, R>(override val left: L) : Either<L, R>() {
-        @Transient
-        override val right: R? = null
-
-        override fun <C, D> mapBoth(
-            leftMapper: (L) -> C,
-            rightMapper: (R) -> D
-        ): Either<C, D> = Left(leftMapper(left))
+    /**
+     * Returns the right value or `null` if absent.
+     *
+     * @return the right value, or `null` if this is a [Left].
+     */
+    fun rightOrNull(): R? = right
 
-        override fun <T> map(leftMapper: (L) -> T, rightMapper: (R) -> T): T = leftMapper(left)
+    /**
+     * Returns the left value if present, otherwise computes a default.
+     *
+     * @param default a function invoked to produce a value when no left value is present.
+     * @return the left value or the result of [default].
+     */
+    inline fun getLeftOrElse(default: () -> L): L = left ?: default()
 
-        override fun toString(): String = "Either.Left($left)"
+    /**
+     * Returns the right value if present, otherwise computes a default.
+     *
+     * @param default a function invoked to produce a value when no right value is present.
+     * @return the right value or the result of [default].
+     */
+    inline fun getRightOrElse(default: () -> R): R = right ?: default()
 
-        override fun equals(other: Any?): Boolean {
-            if (this === other) return true
-            if (other !is Left<*, *>) return false
+    /**
+     * Applies one of the given functions based on which side is present and returns its result.
+     *
+     * @param T the result type.
+     * @param ifLeft function to apply when this is a [Left].
+     * @param ifRight function to apply when this is a [Right].
+     * @return the result of applying the appropriate function.
+     */
+    inline fun <T> fold(ifLeft: (L) -> T, ifRight: (R) -> T): T = when (this) {
+        is Left -> ifLeft(left)
+        is Right -> ifRight(right)
+    }
 
-            if (left != other.left) return false
+    /**
+     * Alias for [fold]. Transforms the contained value to a single common type.
+     *
+     * @param T the result type.
+     * @param ifLeft function to apply when this is a [Left].
+     * @param ifRight function to apply when this is a [Right].
+     * @return the result of applying the appropriate function.
+     */
+    inline fun <T> map(ifLeft: (L) -> T, ifRight: (R) -> T): T = fold(ifLeft, ifRight)
 
-            return true
+    /**
+     * Transforms both possible sides independently and returns a new [Either] with the mapped types.
+     *
+     * @param L2 the mapped left type.
+     * @param R2 the mapped right type.
+     * @param leftMapper function to apply to the left value.
+     * @param rightMapper function to apply to the right value.
+     * @return a new [Either] containing the transformed value.
+     */
+    inline fun <L2, R2> mapBoth(leftMapper: (L) -> L2, rightMapper: (R) -> R2): Either<L2, R2> =
+        when (this) {
+            is Left -> Left(leftMapper(left))
+            is Right -> Right(rightMapper(right))
         }
 
-        override fun hashCode(): Int {
-            return left?.hashCode() ?: 0
-        }
+    /**
+     * Transforms the left value if present, keeping the right value as-is.
+     *
+     * @param L2 the mapped left type.
+     * @param leftMapper function to apply to the left value.
+     * @return a new [Either] with the transformed left type.
+     */
+    inline fun <L2> mapLeft(leftMapper: (L) -> L2): Either<L2, R> = when (this) {
+        is Left -> Left(leftMapper(left))
+        is Right -> Right(right)
     }
 
+    /**
+     * Transforms the right value if present, keeping the left value as-is.
+     *
+     * @param R2 the mapped right type.
+     * @param rightMapper function to apply to the right value.
+     * @return a new [Either] with the transformed right type.
+     */
+    inline fun <R2> mapRight(rightMapper: (R) -> R2): Either<L, R2> = when (this) {
+        is Left -> Left(left)
+        is Right -> Right(rightMapper(right))
+    }
 
-    @Serializable
-    @PublishedApi
-    internal class Right<L, R>(override val right: R) : Either<L, R>() {
-        @Transient
-        override val left: L? = null
+    /**
+     * Swaps the sides of this instance: left becomes right and vice versa.
+     *
+     * @return a new [Either] with left and right values swapped.
+     */
+    fun swap(): Either<R, L> = fold(::right, ::left)
 
-        override fun <C, D> mapBoth(
-            leftMapper: (L) -> C,
-            rightMapper: (R) -> D
-        ): Either<C, D> = Right(rightMapper(right))
+    /**
+     * Executes [action] only when this is a [Left], then returns this instance for chaining.
+     *
+     * @param action the side-effect to perform on the left value.
+     * @return this instance.
+     */
+    inline fun ifLeft(action: (L) -> Unit): Either<L, R> {
+        if (this is Left) action(left)
+        return this
+    }
 
-        override fun <T> map(leftMapper: (L) -> T, rightMapper: (R) -> T): T = rightMapper(right)
 
-        override fun toString(): String = "Either.Right($right)"
+    /**
+     * Executes [action] only when this is a [Right], then returns this instance for chaining.
+     *
+     * @param action the side-effect to perform on the right value.
+     * @return this instance.
+     */
+    inline fun ifRight(action: (R) -> Unit): Either<L, R> {
+        if (this is Right) action(right)
+        return this
+    }
 
-        override fun equals(other: Any?): Boolean {
-            if (this === other) return true
-            if (other !is Right<*, *>) return false
+    /**
+     * Combines two [Either] values **only if** they are of the same side type.
+     *
+     * If both are [Left], [combineLeft] is used. If both are [Right], [combineRight] is used.
+     * If they differ, this instance is returned unchanged.
+     *
+     * @param L2 the left type of [other].
+     * @param R2 the right type of [other].
+     * @param other the other [Either] to combine with.
+     * @param combineLeft function to combine two left values into one.
+     * @param combineRight function to combine two right values into one.
+     * @return a combined [Either] when sides match; otherwise this instance.
+     */
+    inline fun <L2, R2> zipSame(
+        other: Either<L2, R2>,
+        combineLeft: (L, L2) -> L,
+        combineRight: (R, R2) -> R
+    ): Either<L, R> = when (this) {
+        is Left if other is Left -> Left(combineLeft(this.left, other.left))
+        is Right if other is Right -> Right(combineRight(this.right, other.right))
+        else -> this
+    }
 
-            if (right != other.right) return false
+    /**
+     * Applies [leftMapper] when this is a [Left]; returns the right side unchanged otherwise.
+     *
+     * @param L2 the mapped left type.
+     * @param leftMapper function transforming the left value into another [Either].
+     * @return the mapped [Either] when left; otherwise the unchanged right side.
+     */
+    fun <L2> flatMap(leftMapper: (L) -> Either<L2, R>): Either<L2, R> = map(leftMapper, ::right)
 
-            return true
-        }
+    companion object {
+
+        /**
+         * Creates an [Either] containing the given left value.
+         *
+         * @param value the value to store on the left side.
+         * @return an [Either] representing [value] as [Left].
+         */
+        fun <L, R> left(value: L): Either<L, R> = Left(value)
+
+        /**
+         * Creates an [Either] containing the given right value.
+         *
+         * @param value the value to store on the right side.
+         * @return an [Either] representing [value] as [Right].
+         */
+        fun <L, R> right(value: R): Either<L, R> = Right(value)
+
+        /**
+         * Unwraps an [Either] whose left and right types are identical.
+         *
+         * @param either the [Either] instance to unwrap.
+         * @param U the common value type.
+         * @return the contained value regardless of side.
+         */
+        fun <U> unwrap(either: Either<out U, out U>): U = either.fold({ it }, { it })
 
-        override fun hashCode(): Int {
-            return right?.hashCode() ?: 0
+        /**
+         * Creates an [Either] from nullable left and right values. Exactly **one** must be non-null.
+         *
+         * @param left the candidate left value; may be `null`.
+         * @param right the candidate right value; may be `null`.
+         * @return an [Either] containing the single non-null value.
+         * @throws IllegalStateException if both values are null or both are non-null.
+         */
+        fun <L, R> of(left: L?, right: R?): Either<L, R> = when {
+            left != null && right == null -> Left(left)
+            right != null && left == null -> Right(right)
+            left == null -> error("Either must have a left or right value")
+            else -> error("Either cannot have both left and right values")
         }
     }
-}
 
-inline fun <L, R> Either<L, R>.ifLeft(action: (L) -> Unit): Either<L, R> {
-    if (this is Either.Left) {
-        action(left)
+    @PublishedApi
+    @Serializable
+    @SerialName("left")
+    internal data class Left<L, R>(override val left: L) : Either<L, R>() {
+        @Transient
+        override val right: R? = null
+        override fun toString(): String = "Either.Left($left)"
     }
-    return this
-}
 
-inline fun <L, R> Either<L, R>.ifRight(action: (R) -> Unit): Either<L, R> {
-    if (this is Either.Right) {
-        action(right)
+
+    @Serializable
+    @PublishedApi
+    @SerialName("right")
+    internal data class Right<L, R>(override val right: R) : Either<L, R>() {
+        @Transient
+        override val left: L? = null
+        override fun toString(): String = "Either.Right($right)"
     }
-    return this
 }