Add new configuration types and serializers for numeric and boolean values (#353)

Author: twisti-dev

gradle.properties

@@ -7,6 +7,6 @@ org.jetbrains.dokka.experimental.gradle.pluginMode=V2Enabled
 javaVersion=25
 mcVersion=26.1.2
 group=dev.slne.surf.api
-version=3.11.2
+version=3.12.0
 relocationPrefix=dev.slne.surf.api.libs
 snapshot=false

surf-api-core/surf-api-core-server/src/main/kotlin/dev/slne/surf/api/core/server/CoreInstance.kt

@@ -4,8 +4,10 @@ import dev.slne.surf.api.core.messages.Colors
 import dev.slne.surf.api.core.server.listener.CoreListenerManager
 import dev.slne.surf.api.core.server.util.PlayerSkinFetcher
 import org.jetbrains.annotations.MustBeInvokedByOverriders
+import java.util.concurrent.atomic.AtomicBoolean
 
 abstract class CoreInstance {
+    private val bootstrapping = AtomicBoolean(true)
 
     @MustBeInvokedByOverriders
     open suspend fun bootstrap() {
@@ -14,6 +16,7 @@ abstract class CoreInstance {
 
     @MustBeInvokedByOverriders
     open suspend fun onLoad() {
+        bootstrapping.set(false)
     }
 
     @MustBeInvokedByOverriders
@@ -30,4 +33,6 @@ abstract class CoreInstance {
         PlayerSkinFetcher
         Colors
     }
+
+    fun isBootstrapping(): Boolean = bootstrapping.get()
 }

surf-api-core/surf-api-core/api/surf-api-core.api

@@ -0,0 +1,10 @@
+package dev.slne.surf.api.core.config.constraints
+
+internal fun Any?.configSizeOrNull(): Int? = when (this) {
+    null -> null
+    is Collection<*> -> size
+    is Map<*, *> -> size
+    is Array<*> -> size
+    is CharSequence -> length
+    else -> null
+}

surf-api-core/surf-api-core/src/main/kotlin/dev/slne/surf/api/core/config/constraints/CollectionConstraintUtils.kt

@@ -0,0 +1,27 @@
+package dev.slne.surf.api.core.config.constraints
+
+import org.spongepowered.configurate.objectmapping.meta.Constraint
+import org.spongepowered.configurate.serialize.SerializationException
+import java.lang.reflect.Type
+
+/**
+ * Requires a string config value to contain a specific substring.
+ *
+ * This annotation ensures that the annotated string contains the specified substring.
+ * If the validation fails, a `SerializationException` is thrown with a descriptive error message.
+ *
+ * @property value The substring that must be present in the string value.
+ */
+@Target(AnnotationTarget.FIELD)
+@Retention(AnnotationRetention.RUNTIME)
+annotation class Contains(val value: String) {
+    companion object {
+        internal object Factory : Constraint.Factory<Contains, String?> {
+            override fun make(data: Contains, type: Type): Constraint<String?> = { value ->
+                if (value != null && !value.contains(data.value)) {
+                    throw SerializationException("String must contain '${data.value}'")
+                }
+            }
+        }
+    }
+}

surf-api-core/surf-api-core/src/main/kotlin/dev/slne/surf/api/core/config/constraints/Contains.kt

@@ -0,0 +1,43 @@
+package dev.slne.surf.api.core.config.constraints
+
+import org.spongepowered.configurate.objectmapping.meta.Constraint
+import org.spongepowered.configurate.serialize.SerializationException
+import java.lang.reflect.Type
+import kotlin.io.path.exists
+import kotlin.io.path.isDirectory
+
+/**
+ * Ensures that a configuration value represents a valid, existing directory.
+ *
+ * This annotation validates that the annotated value points to a directory that exists on the filesystem.
+ * If the value does not exist, or if it does not represent a directory, validation will fail with a
+ * `SerializationException`.
+ *
+ * This constraint supports different types of input, such as `Path`, `File`, and `String`, converting
+ * them to a `Path` internally using the helper method `asPathOrNull`.
+ *
+ * Constraints:
+ * - The value must point to an existing directory.
+ * - The value must be convertible to a `Path` object.
+ *
+ * Intended for use on fields in configuration classes.
+ *
+ * Validation failure will throw a `SerializationException` with a descriptive message indicating the
+ * problem with the directory path.
+ *
+ * Associated factory implementation provides the actual validation logic.
+ */
+@Target(AnnotationTarget.FIELD)
+@Retention(AnnotationRetention.RUNTIME)
+annotation class Directory {
+    companion object {
+        internal object Factory : Constraint.Factory<Directory, Any?> {
+            override fun make(data: Directory, type: Type): Constraint<Any?> = Constraint { value ->
+                val path = value.asPathOrNull() ?: return@Constraint
+                if (!path.exists() || !path.isDirectory()) {
+                    throw SerializationException("Path must point to an existing directory: $path")
+                }
+            }
+        }
+    }
+}

surf-api-core/surf-api-core/src/main/kotlin/dev/slne/surf/api/core/config/constraints/Directory.kt

@@ -0,0 +1,27 @@
+package dev.slne.surf.api.core.config.constraints
+
+import org.spongepowered.configurate.objectmapping.meta.Constraint
+import org.spongepowered.configurate.serialize.SerializationException
+import java.lang.reflect.Type
+
+/**
+ * Prevents specific values from being assigned to the annotated field.
+ *
+ * This annotation is used to define a set of disallowed string values for a field. If the annotated field's
+ * value matches any of the specified disallowed values (case-insensitive), a `SerializationException` is thrown.
+ *
+ * @property values The array of string values that are disallowed.
+ */
+@Target(AnnotationTarget.FIELD)
+@Retention(AnnotationRetention.RUNTIME)
+annotation class DisallowValues(vararg val values: String) {
+    companion object {
+        internal object Factory : Constraint.Factory<DisallowValues, Any?> {
+            override fun make(data: DisallowValues, type: Type): Constraint<Any?> = { value ->
+                if (value != null && data.values.any { it.equals(value.toString(), ignoreCase = true) }) {
+                    throw SerializationException("Value '$value' is not allowed")
+                }
+            }
+        }
+    }
+}

surf-api-core/surf-api-core/src/main/kotlin/dev/slne/surf/api/core/config/constraints/DisallowValues.kt

@@ -0,0 +1,27 @@
+package dev.slne.surf.api.core.config.constraints
+
+import org.spongepowered.configurate.objectmapping.meta.Constraint
+import org.spongepowered.configurate.serialize.SerializationException
+import java.lang.reflect.Type
+
+/**
+ * Validates that a string config value ends with a specified suffix.
+ *
+ * This annotation ensures that the annotated string ends with the provided suffix.
+ * If the validation fails, a `SerializationException` is thrown with a descriptive error message.
+ *
+ * @property suffix The suffix that the string value must end with.
+ */
+@Target(AnnotationTarget.FIELD)
+@Retention(AnnotationRetention.RUNTIME)
+annotation class EndsWith(val suffix: String) {
+    companion object {
+        internal object Factory : Constraint.Factory<EndsWith, String?> {
+            override fun make(data: EndsWith, type: Type): Constraint<String?> = { value ->
+                if (value != null && !value.endsWith(data.suffix)) {
+                    throw SerializationException("String must end with '${data.suffix}'")
+                }
+            }
+        }
+    }
+}

surf-api-core/surf-api-core/src/main/kotlin/dev/slne/surf/api/core/config/constraints/EndsWith.kt

@@ -0,0 +1,52 @@
+package dev.slne.surf.api.core.config.constraints
+
+import org.spongepowered.configurate.objectmapping.meta.Constraint
+import org.spongepowered.configurate.serialize.SerializationException
+import java.io.File
+import java.lang.reflect.Type
+import java.nio.file.Path
+import kotlin.io.path.exists
+import kotlin.io.path.isRegularFile
+
+/**
+ * Requires that the annotated field refers to an existing file.
+ *
+ * This annotation ensures that the value of the annotated field corresponds to
+ * a valid file path that exists and is a regular file. If the validation fails,
+ * a `SerializationException` is thrown with a descriptive error message.
+ *
+ * The value can be:
+ * - A `Path` object.
+ * - A `File` object.
+ * - A `String` representing the file path.
+ *
+ * If the value is not convertible to a file path or the file does not exist
+ * or is not a regular file, the validation fails.
+ *
+ * This annotation is typically used for configuration values to ensure
+ * that specified file paths are valid at runtime.
+ */
+@Target(AnnotationTarget.FIELD)
+@Retention(AnnotationRetention.RUNTIME)
+annotation class ExistingFile {
+    companion object {
+        internal object Factory : Constraint.Factory<ExistingFile, Any?> {
+            override fun make(data: ExistingFile, type: Type): Constraint<Any?> = Constraint { value ->
+                val path = value.asPathOrNull() ?: return@Constraint
+                if (!path.exists() || !path.isRegularFile()) {
+                    throw SerializationException("Path must point to an existing file: $path")
+                }
+            }
+        }
+    }
+}
+
+internal fun Any?.asPathOrNull(): Path? {
+    return when (this) {
+        null -> null
+        is Path -> this
+        is File -> toPath()
+        is String -> runCatching { Path.of(this) }.getOrNull()
+        else -> null
+    }
+}

surf-api-core/surf-api-core/src/main/kotlin/dev/slne/surf/api/core/config/constraints/ExistingFile.kt

@@ -0,0 +1,29 @@
+package dev.slne.surf.api.core.config.constraints
+
+import dev.slne.surf.api.core.config.type.ConfigDuration
+import org.spongepowered.configurate.objectmapping.meta.Constraint
+import org.spongepowered.configurate.serialize.SerializationException
+import java.lang.reflect.Type
+
+/**
+ * Annotation for constraining a `ConfigDuration`'s value to a maximum duration.
+ *
+ * This annotation ensures that the duration value of the annotated field does not exceed
+ * the specified number of seconds. If the validation fails, a `SerializationException`
+ * is thrown with a descriptive error message.
+ *
+ * @property seconds The maximum duration in seconds that the annotated field can have.
+ */
+@Target(AnnotationTarget.FIELD)
+@Retention(AnnotationRetention.RUNTIME)
+annotation class MaxDuration(val seconds: Long) {
+    companion object {
+        internal object Factory : Constraint.Factory<MaxDuration, ConfigDuration?> {
+            override fun make(data: MaxDuration, type: Type): Constraint<ConfigDuration?> = { value ->
+                if (value != null && value.value.inWholeSeconds > data.seconds) {
+                    throw SerializationException("Duration is too long: ${value.value}, expected <= ${data.seconds}s")
+                }
+            }
+        }
+    }
+}