✨ feat(config): add new validation annotations for configuration values

twisti-dev · twisti-dev · commit eb800249688b · 2026-05-17T22:49:37.000+02:00
- introduce Contains, Directory, DisallowValues, EndsWith, ExistingFile, MaxDuration,
  MaxLength, MaxSize, MinDuration, MinSize, Namespace, NegativeNumber, NoDuplicates,
  NotEmpty, StartsWith, and WritablePath annotations
- each annotation provides specific validation logic for configuration fields
diff --git a/surf-api-core/surf-api-core/src/main/kotlin/dev/slne/surf/api/core/config/constraints/Contains.kt b/surf-api-core/surf-api-core/src/main/kotlin/dev/slne/surf/api/core/config/constraints/Contains.kt
@@ -4,6 +4,14 @@ 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) {
diff --git a/surf-api-core/surf-api-core/src/main/kotlin/dev/slne/surf/api/core/config/constraints/Directory.kt b/surf-api-core/surf-api-core/src/main/kotlin/dev/slne/surf/api/core/config/constraints/Directory.kt
@@ -6,6 +6,27 @@ 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 {
diff --git a/surf-api-core/surf-api-core/src/main/kotlin/dev/slne/surf/api/core/config/constraints/DisallowValues.kt b/surf-api-core/surf-api-core/src/main/kotlin/dev/slne/surf/api/core/config/constraints/DisallowValues.kt
@@ -4,6 +4,14 @@ 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) {
diff --git a/surf-api-core/surf-api-core/src/main/kotlin/dev/slne/surf/api/core/config/constraints/EndsWith.kt b/surf-api-core/surf-api-core/src/main/kotlin/dev/slne/surf/api/core/config/constraints/EndsWith.kt
@@ -4,6 +4,14 @@ 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) {
diff --git a/surf-api-core/surf-api-core/src/main/kotlin/dev/slne/surf/api/core/config/constraints/ExistingFile.kt b/surf-api-core/surf-api-core/src/main/kotlin/dev/slne/surf/api/core/config/constraints/ExistingFile.kt
@@ -8,6 +8,24 @@ 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 {
diff --git a/surf-api-core/surf-api-core/src/main/kotlin/dev/slne/surf/api/core/config/constraints/MaxDuration.kt b/surf-api-core/surf-api-core/src/main/kotlin/dev/slne/surf/api/core/config/constraints/MaxDuration.kt
@@ -5,6 +5,15 @@ 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) {
diff --git a/surf-api-core/surf-api-core/src/main/kotlin/dev/slne/surf/api/core/config/constraints/MaxLength.kt b/surf-api-core/surf-api-core/src/main/kotlin/dev/slne/surf/api/core/config/constraints/MaxLength.kt
@@ -4,6 +4,15 @@ import org.spongepowered.configurate.objectmapping.meta.Constraint
 import org.spongepowered.configurate.serialize.SerializationException
 import java.lang.reflect.Type
 
+/**
+ * Validates that a string config value does not exceed a specified maximum length.
+ *
+ * This annotation is used to ensure that the length of the annotated string
+ * is less than or equal to the specified maximum value. If the validation fails,
+ * a `SerializationException` is thrown with a descriptive error message.
+ *
+ * @property max The maximum allowed length for the string value.
+ */
 @Target(AnnotationTarget.FIELD)
 @Retention(AnnotationRetention.RUNTIME)
 annotation class MaxLength(val max: Int) {
diff --git a/surf-api-core/surf-api-core/src/main/kotlin/dev/slne/surf/api/core/config/constraints/MaxSize.kt b/surf-api-core/surf-api-core/src/main/kotlin/dev/slne/surf/api/core/config/constraints/MaxSize.kt
@@ -4,6 +4,15 @@ import org.spongepowered.configurate.objectmapping.meta.Constraint
 import org.spongepowered.configurate.serialize.SerializationException
 import java.lang.reflect.Type
 
+/**
+ * Specifies a maximum size constraint for collections, maps, arrays, or strings.
+ *
+ * This annotation enforces that the size or length of the annotated value does not exceed
+ * the specified maximum. If the validation fails, a `SerializationException` is thrown
+ * with a descriptive error message.
+ *
+ * @property max The maximum allowed size or length for the annotated value.
+ */
 @Target(AnnotationTarget.FIELD)
 @Retention(AnnotationRetention.RUNTIME)
 annotation class MaxSize(val max: Int) {
diff --git a/surf-api-core/surf-api-core/src/main/kotlin/dev/slne/surf/api/core/config/constraints/MinDuration.kt b/surf-api-core/surf-api-core/src/main/kotlin/dev/slne/surf/api/core/config/constraints/MinDuration.kt
@@ -5,6 +5,15 @@ import org.spongepowered.configurate.objectmapping.meta.Constraint
 import org.spongepowered.configurate.serialize.SerializationException
 import java.lang.reflect.Type
 
+/**
+ * Specifies a minimum duration constraint for configuration values annotated with this annotation.
+ *
+ * This annotation ensures that durations provided in the configuration meet or exceed
+ * the specified minimum value in seconds. If the validation fails, a `SerializationException`
+ * is thrown with a descriptive error message.
+ *
+ * @property seconds The minimum allowed duration in seconds.
+ */
 @Target(AnnotationTarget.FIELD)
 @Retention(AnnotationRetention.RUNTIME)
 annotation class MinDuration(val seconds: Long) {
diff --git a/surf-api-core/surf-api-core/src/main/kotlin/dev/slne/surf/api/core/config/constraints/MinSize.kt b/surf-api-core/surf-api-core/src/main/kotlin/dev/slne/surf/api/core/config/constraints/MinSize.kt
@@ -4,6 +4,15 @@ import org.spongepowered.configurate.objectmapping.meta.Constraint
 import org.spongepowered.configurate.serialize.SerializationException
 import java.lang.reflect.Type
 
+/**
+ * Specifies a minimum size constraint for collections, maps, arrays, or strings.
+ *
+ * This annotation enforces that the size or length of the annotated value is at least
+ * the specified minimum. If the validation fails, a `SerializationException` is thrown
+ * with a descriptive error message.
+ *
+ * @property min The minimum required size or length for the annotated value.
+ */
 @Target(AnnotationTarget.FIELD)
 @Retention(AnnotationRetention.RUNTIME)
 annotation class MinSize(val min: Int) {
diff --git a/surf-api-core/surf-api-core/src/main/kotlin/dev/slne/surf/api/core/config/constraints/Namespace.kt b/surf-api-core/surf-api-core/src/main/kotlin/dev/slne/surf/api/core/config/constraints/Namespace.kt
@@ -5,6 +5,15 @@ import org.spongepowered.configurate.objectmapping.meta.Constraint
 import org.spongepowered.configurate.serialize.SerializationException
 import java.lang.reflect.Type
 
+/**
+ * Ensures that a key value conforms to a specific namespace.
+ *
+ * This annotation validates that the `namespace` of a key matches the expected namespace
+ * defined in the `Namespace` annotation. If the validation fails, a `SerializationException`
+ * is thrown with a descriptive error message.
+ *
+ * @property namespace The required namespace for the key value.
+ */
 @Target(AnnotationTarget.FIELD)
 @Retention(AnnotationRetention.RUNTIME)
 annotation class Namespace(val namespace: String) {
diff --git a/surf-api-core/surf-api-core/src/main/kotlin/dev/slne/surf/api/core/config/constraints/NegativeNumber.kt b/surf-api-core/surf-api-core/src/main/kotlin/dev/slne/surf/api/core/config/constraints/NegativeNumber.kt
@@ -4,6 +4,12 @@ import org.spongepowered.configurate.objectmapping.meta.Constraint
 import org.spongepowered.configurate.serialize.SerializationException
 import java.lang.reflect.Type
 
+/**
+ * Ensures that a numeric config value is strictly negative.
+ *
+ * This annotation validates that the annotated numeric value is less than zero. If the
+ * validation fails, a `SerializationException` is thrown with a descriptive error message.
+ */
 @Target(AnnotationTarget.FIELD)
 @Retention(AnnotationRetention.RUNTIME)
 annotation class NegativeNumber {
diff --git a/surf-api-core/surf-api-core/src/main/kotlin/dev/slne/surf/api/core/config/constraints/NoDuplicates.kt b/surf-api-core/surf-api-core/src/main/kotlin/dev/slne/surf/api/core/config/constraints/NoDuplicates.kt
@@ -4,6 +4,22 @@ import org.spongepowered.configurate.objectmapping.meta.Constraint
 import org.spongepowered.configurate.serialize.SerializationException
 import java.lang.reflect.Type
 
+/**
+ * Ensures that a collection or array does not contain duplicate elements.
+ *
+ * This annotation validates that the annotated value, if it is a collection or array,
+ * contains only unique elements. If duplicates are found, a `SerializationException`
+ * is thrown with a descriptive error message.
+ *
+ * Supported types:
+ * - `Iterable<?>`: Validates all elements in the iterable.
+ * - `Array<?>`: Validates all elements in the array.
+ *
+ * Values that are `null` or of unsupported types are ignored during validation.
+ *
+ * Exceptions:
+ * - `SerializationException`: Thrown if the collection or array contains duplicate elements.
+ */
 @Target(AnnotationTarget.FIELD)
 @Retention(AnnotationRetention.RUNTIME)
 annotation class NoDuplicates {
diff --git a/surf-api-core/surf-api-core/src/main/kotlin/dev/slne/surf/api/core/config/constraints/NotEmpty.kt b/surf-api-core/surf-api-core/src/main/kotlin/dev/slne/surf/api/core/config/constraints/NotEmpty.kt
@@ -4,6 +4,13 @@ import org.spongepowered.configurate.objectmapping.meta.Constraint
 import org.spongepowered.configurate.serialize.SerializationException
 import java.lang.reflect.Type
 
+/**
+ * Ensures that a collection, map, array, or string config value is not empty.
+ *
+ * This annotation enforces that the size or length of the annotated value is greater
+ * than 0. If the validation fails, a `SerializationException` is thrown with a
+ * descriptive error message.
+ */
 @Target(AnnotationTarget.FIELD)
 @Retention(AnnotationRetention.RUNTIME)
 annotation class NotEmpty {
diff --git a/surf-api-core/surf-api-core/src/main/kotlin/dev/slne/surf/api/core/config/constraints/StartsWith.kt b/surf-api-core/surf-api-core/src/main/kotlin/dev/slne/surf/api/core/config/constraints/StartsWith.kt
@@ -4,6 +4,14 @@ import org.spongepowered.configurate.objectmapping.meta.Constraint
 import org.spongepowered.configurate.serialize.SerializationException
 import java.lang.reflect.Type
 
+/**
+ * Validates that a string config value starts with a specified prefix.
+ *
+ * This annotation ensures that the annotated string begins with the provided prefix.
+ * If the validation fails, a `SerializationException` is thrown with a descriptive error message.
+ *
+ * @property prefix The prefix that the string value must start with.
+ */
 @Target(AnnotationTarget.FIELD)
 @Retention(AnnotationRetention.RUNTIME)
 annotation class StartsWith(val prefix: String) {
diff --git a/surf-api-core/surf-api-core/src/main/kotlin/dev/slne/surf/api/core/config/constraints/WritablePath.kt b/surf-api-core/surf-api-core/src/main/kotlin/dev/slne/surf/api/core/config/constraints/WritablePath.kt
@@ -6,6 +6,22 @@ import java.lang.reflect.Type
 import kotlin.io.path.exists
 import kotlin.io.path.isWritable
 
+/**
+ * Validates that a configuration value represents a writable path.
+ *
+ * This annotation ensures that the annotated value refers to a file system path
+ * that exists and is writable. If the validation fails, a `SerializationException`
+ * will be thrown with a descriptive error message.
+ *
+ * Supported value types include:
+ * - `Path`: Directly represents a file system path.
+ * - `File`: Converted to a `Path` for validation.
+ * - `String`: Parsed as a file system path.
+ *
+ * Validation checks:
+ * - If the path exists, it must be writable.
+ * - If the value cannot be converted to a valid path, it is ignored during validation.
+ */
 @Target(AnnotationTarget.FIELD)
 @Retention(AnnotationRetention.RUNTIME)
 annotation class WritablePath {
diff --git a/surf-api-core/surf-api-core/src/main/kotlin/dev/slne/surf/api/core/config/type/ConfigDuration.kt b/surf-api-core/surf-api-core/src/main/kotlin/dev/slne/surf/api/core/config/type/ConfigDuration.kt
@@ -9,6 +9,14 @@ import kotlin.time.Duration
 import kotlin.time.DurationUnit
 import kotlin.time.toDuration
 
+/**
+ * Encapsulates a configuration value representing a duration, with functionality for parsing,
+ * formatting, and serialization.
+ *
+ * @property value The parsed duration value as a [Duration].
+ * @property rawValue The original raw input that was used to construct this [ConfigDuration].
+ *                    This is stored for serialization purposes.
+ */
 data class ConfigDuration(
     val value: Duration,
     val rawValue: String = format(value)
