✨ feat(environment): add type-safe environment variable API

README.md

@@ -64,6 +64,42 @@ surf-api
 > projects. `-server` modules contain implementations that are shaded into the final JAR and never
 > exposed as a public API dependency.
 
+## Environment Variables
+
+`surf-api-core` provides small, type-safe environment-variable access without a separate schema or
+lookup phase. Direct reads resolve immediately:
+
+```kotlin
+val DATABASE_HOST: String = env.required("DATABASE_HOST")
+val DATABASE_PORT: Int = env.int("DATABASE_PORT", default = 5432) {
+    requireIn(1..65535)
+}
+val INSTANCE_ID: UUID? = env.optionalUuid("INSTANCE_ID")
+```
+
+Property delegates resolve lazily on first access, infer the variable name exactly from the property,
+and cache the parsed value thread-safely:
+
+```kotlin
+object ServiceEnvironment {
+    val DATABASE_HOST by env.requiredNonBlank()
+    val DATABASE_PORT by env.int(default = 5432) {
+        requireIn(1..65535)
+    }
+    val DATABASE_PASSWORD by env.requiredSecret()
+    val DEBUG by env.boolean(default = false)
+}
+```
+
+Use `env.required().named("DATABASE_HOST")` for an explicitly named delegate. Required values are
+non-null, optional values are nullable, and defaulted values are non-null. Missing required values,
+conversion failures, and validation failures throw dedicated exceptions containing the variable
+name. Mark values as sensitive, or use `requiredSecret`, to keep raw values and parser causes out of
+error details. Required strings preserve present blank values; `requiredNonBlank` rejects them.
+Built-in converters cover strings, numeric types, strict booleans, UUIDs, enums, and Kotlin
+durations. Custom converters can be passed directly, for example
+`env.required("ID", UUID::fromString)`.
+
 ---
 
 ## Key Concepts

gradle.properties

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

surf-api-core/surf-api-core/src/main/kotlin/dev/slne/surf/api/core/environment/EnvironmentSource.kt

@@ -0,0 +1,14 @@
+package dev.slne.surf.api.core.environment
+
+/**
+ * Supplies raw environment-variable values.
+ *
+ * A source returns `null` only when a variable is missing. Present blank values must be returned as
+ * an empty or whitespace-only string so callers can distinguish them from missing variables.
+ */
+fun interface EnvironmentSource {
+    /**
+     * Returns the raw value for [name], or `null` when the variable is missing.
+     */
+    operator fun get(name: String): String?
+}

surf-api-core/surf-api-core/src/main/kotlin/dev/slne/surf/api/core/environment/EnvironmentVariableDelegate.kt

@@ -0,0 +1,48 @@
+package dev.slne.surf.api.core.environment
+
+import kotlin.properties.PropertyDelegateProvider
+import kotlin.properties.ReadOnlyProperty
+import kotlin.reflect.KProperty
+
+/**
+ * A lazy, thread-safe environment-variable property delegate.
+ *
+ * The variable is resolved on first access and the parsed value, including `null`, is cached for
+ * all later accesses. When no explicit name is supplied, the delegated property's name is used
+ * exactly as written.
+ */
+class EnvironmentVariableDelegate<T> internal constructor(
+    private val explicitName: String?,
+    private val resolver: (String) -> T
+) : PropertyDelegateProvider<Any?, ReadOnlyProperty<Any?, T>> {
+    /**
+     * Returns an equivalent delegate that resolves the explicit environment-variable [name].
+     *
+     * ```kotlin
+     * val databaseHost by env.required().named("DATABASE_HOST")
+     * ```
+     */
+    fun named(name: String): EnvironmentVariableDelegate<T> {
+        require(name.isNotEmpty()) { "Environment-variable names must not be empty." }
+        require('\u0000' !in name && '=' !in name) {
+            "Environment-variable name '$name' contains an invalid character."
+        }
+
+        return EnvironmentVariableDelegate(name, resolver)
+    }
+
+    /**
+     * Captures the property name and creates the cached read-only delegate.
+     */
+    override fun provideDelegate(
+        thisRef: Any?,
+        property: KProperty<*>
+    ): ReadOnlyProperty<Any?, T> {
+        val variableName = explicitName ?: property.name
+        val resolved = lazy(LazyThreadSafetyMode.SYNCHRONIZED) {
+            resolver(variableName)
+        }
+
+        return ReadOnlyProperty { _, _ -> resolved.value }
+    }
+}

surf-api-core/surf-api-core/src/main/kotlin/dev/slne/surf/api/core/environment/EnvironmentVariableException.kt

@@ -0,0 +1,107 @@
+package dev.slne.surf.api.core.environment
+
+/**
+ * Base class for failures encountered while resolving an environment variable.
+ *
+ * @property variableName The name of the environment variable that could not be resolved.
+ */
+sealed class EnvironmentVariableException(
+    val variableName: String,
+    message: String,
+    cause: Throwable? = null
+) : IllegalStateException(message, cause)
+
+/**
+ * Thrown when a required environment variable is missing.
+ */
+class MissingEnvironmentVariableException(
+    variableName: String
+) : EnvironmentVariableException(
+    variableName,
+    "Required environment variable '$variableName' is missing."
+)
+
+/**
+ * Thrown when an environment variable cannot be converted to its expected type.
+ *
+ * For sensitive variables, [rawValue] and [cause] are deliberately omitted because parser
+ * exceptions can include their input in the exception message.
+ *
+ * @property expectedType A human-readable description of the expected target type.
+ * @property rawValue The invalid raw value, or `null` when the variable is sensitive.
+ */
+class InvalidEnvironmentVariableException internal constructor(
+    variableName: String,
+    val expectedType: String,
+    val rawValue: String?,
+    sensitive: Boolean,
+    cause: Throwable
+) : EnvironmentVariableException(
+    variableName,
+    buildString {
+        append("Environment variable '")
+        append(variableName)
+        append("' has an invalid value for ")
+        append(expectedType)
+        append(": ")
+        if (sensitive) {
+            append("the sensitive value was not included.")
+        } else {
+            append(formatRawValue(rawValue.orEmpty()))
+            append('.')
+        }
+    },
+    cause.takeUnless { sensitive }
+)
+
+/**
+ * Thrown when a parsed environment-variable value fails inline validation.
+ *
+ * @property reason A description of the failed validation rule.
+ * @property rawValue The resolved value, or `null` when the variable is sensitive.
+ */
+class EnvironmentVariableValidationException internal constructor(
+    variableName: String,
+    val reason: String,
+    val rawValue: String?,
+    sensitive: Boolean,
+    cause: Throwable? = null
+) : EnvironmentVariableException(
+    variableName,
+    buildString {
+        append("Environment variable '")
+        append(variableName)
+        append("' failed validation: ")
+        append(reason)
+        if (sensitive) {
+            append(" The sensitive value was not included.")
+        } else if (rawValue != null) {
+            append(" Resolved ")
+            append(formatRawValue(rawValue))
+            append('.')
+        }
+    },
+    cause.takeUnless { sensitive }
+)
+
+private fun formatRawValue(value: String): String {
+    val truncated = value.length > MAX_DISPLAYED_VALUE_LENGTH
+    val escaped = buildString {
+        value.take(MAX_DISPLAYED_VALUE_LENGTH).forEach { character ->
+            when (character) {
+                '\n' -> append("\\n")
+                '\r' -> append("\\r")
+                '\t' -> append("\\t")
+                else -> append(character)
+            }
+        }
+    }
+
+    return if (truncated) {
+        "value '$escaped…'"
+    } else {
+        "value '$escaped'"
+    }
+}
+
+private const val MAX_DISPLAYED_VALUE_LENGTH = 128

surf-api-core/surf-api-core/src/main/kotlin/dev/slne/surf/api/core/environment/EnvironmentVariableValidation.kt

@@ -0,0 +1,59 @@
+package dev.slne.surf.api.core.environment
+
+/**
+ * Validates one parsed environment-variable value.
+ *
+ * Validation is performed immediately for direct reads and during the first access for delegated
+ * reads. Use [require] to add rules inside a typed environment-variable declaration.
+ */
+class EnvironmentVariableValidation<T> internal constructor(
+    private val variableName: String,
+    private val rawValue: String?,
+    private val sensitive: Boolean,
+    private val value: T
+) {
+    /**
+     * Requires [predicate] to accept the resolved value.
+     */
+    fun require(predicate: (T) -> Boolean) {
+        require("the value did not satisfy the required condition", predicate)
+    }
+
+    /**
+     * Requires [predicate] to accept the resolved value and reports [message] if it does not.
+     */
+    fun require(message: String, predicate: (T) -> Boolean) {
+        val accepted = try {
+            predicate(value)
+        } catch (exception: Exception) {
+            throw failure(
+                exception.message ?: "the validation rule threw ${exception::class.simpleName}",
+                exception
+            )
+        }
+
+        if (!accepted) {
+            throw failure(message)
+        }
+    }
+
+    internal fun failure(
+        message: String,
+        cause: Throwable? = null
+    ): EnvironmentVariableValidationException {
+        return EnvironmentVariableValidationException(
+            variableName = variableName,
+            reason = message,
+            rawValue = rawValue.takeUnless { sensitive },
+            sensitive = sensitive,
+            cause = cause
+        )
+    }
+}
+
+/**
+ * Requires the resolved value to be inside the inclusive [range].
+ */
+fun <T : Comparable<T>> EnvironmentVariableValidation<T>.requireIn(range: ClosedRange<T>) {
+    require("expected a value in the range $range") { it in range }
+}