Add env-var provider

Author: bencehornak

.gitignore

@@ -8,4 +8,7 @@
 build
 
 # Ignore IntelliJ files
-.idea
+.idea
+
+# Ignore Kotlin files
+.kotlin

gradle/libs.versions.toml

@@ -1,5 +1,10 @@
 [versions]
+kotlin = "2.1.21"
 open-feature-kotlin-sdk = "0.4.1"
 
 [libraries]
-open-feature-kotlin-sdk = { group="dev.openfeature", name="kotlin-sdk", version.ref="open-feature-kotlin-sdk" }
+openfeature-kotlin-sdk = { group="dev.openfeature", name="kotlin-sdk", version.ref="open-feature-kotlin-sdk" }
+kotlin-test = { group="org.jetbrains.kotlin", name="kotlin-test", version.ref="kotlin" }
+
+[plugins]
+kotlin-multiplatform = { id="org.jetbrains.kotlin.multiplatform", version.ref="kotlin" }

kotlin-js-store/yarn.lock

@@ -0,0 +1,84 @@
+# Environment Variables Kotlin Provider
+
+Environment Variables provider allows you to read feature flags from the [process's environment](https://en.wikipedia.org/wiki/Environment_variable).
+
+## Installation
+
+<!-- x-release-please-start-version -->
+
+```xml
+<dependency>
+    <groupId>dev.openfeature.kotlin.contrib.providers</groupId>
+    <artifactId>env-var</artifactId>
+    <version>0.1.0</version>
+</dependency>
+```
+
+<!-- x-release-please-end-version -->
+
+## Usage
+
+To use the `EnvVarProvider` create an instance and use it as a provider:
+
+```kotlin
+    val provider = EnvVarProvider()
+    OpenFeatureAPI.setProviderAndWait(provider)
+```
+
+### Configuring different methods for fetching environment variables
+
+This provider defines an `EnvironmentGateway` interface, which is used to access the actual environment variables.
+The method [`platformSpecificEnvironmentGateway`][platformSpecificEnvironmentGateway], which is implemented for each supported platform, returns a default implementation.
+
+```kotlin
+    val testFake = EnvironmentGateway { arg -> "true" } // always returns true
+    
+    val provider = EnvVarProvider(testFake)
+    OpenFeatureAPI.getInstance().setProvider(provider)
+```
+
+### Key transformation
+
+This provider supports transformation of keys to support different patterns used for naming feature flags and for
+naming environment variables, e.g. SCREAMING_SNAKE_CASE env variables vs. hyphen-case keys for feature flags.
+It supports chaining/combining different transformers incl. self-written ones by providing a transforming function in the constructor.
+Currently, the following transformations are supported out of the box:
+
+- converting to lower case (e.g. `Feature.Flag` => `feature.flag`)
+- converting to UPPER CASE (e.g. `Feature.Flag` => `FEATURE.FLAG`)
+- converting hyphen-case to SCREAMING_SNAKE_CASE (e.g. `Feature-Flag` => `FEATURE_FLAG`)
+- convert to camelCase (e.g. `FEATURE_FLAG` => `featureFlag`)
+- replace '_' with '.' (e.g. `feature_flag` => `feature.flag`)
+- replace '.' with '_' (e.g. `feature.flag` => `feature_flag`)
+
+**Examples:**
+
+1. hyphen-case feature flag names to screaming snake-case environment variables:
+
+   ```kotlin
+       // Definition of the EnvVarProvider:
+       val provider = EnvVarProvider(EnvironmentKeyTransformer.hyphenCaseToScreamingSnake())
+   ```
+
+2. chained/composed transformations:
+
+   ```kotlin
+       // Definition of the EnvVarProvider:
+       val keyTransformer = EnvironmentKeyTransformer
+           .toLowerCaseTransformer()
+           .andThen(EnvironmentKeyTransformer.replaceUnderscoreWithDotTransformer())
+   
+       val provider = EnvVarProvider(keyTransformer)
+   ```
+
+3. freely defined transformation function:
+
+   ```kotlin
+       // Definition of the EnvVarProvider:   
+       val keyTransformer = EnvironmentKeyTransformer { key -> key.substring(1) }
+       val provider = EnvVarProvider(keyTransformer)
+   ```
+
+<!-- links -->
+
+[platformSpecificEnvironmentGateway]: src/commonMain/kotlin/dev/openfeature/kotlin/contrib/providers/envvar/PlatformSpecificEnvironmentGateway.kt

providers/env-var/README.md

@@ -0,0 +1,30 @@
+import org.jetbrains.kotlin.gradle.dsl.JvmTarget
+
+plugins {
+    alias(libs.plugins.kotlin.multiplatform)
+}
+
+kotlin {
+    jvm {
+        compilations.all {
+            compileTaskProvider.configure {
+                compilerOptions {
+                    jvmTarget.set(JvmTarget.JVM_21)
+                }
+            }
+        }
+    }
+    linuxX64 {}
+    js {
+        nodejs()
+    }
+
+    sourceSets {
+        commonMain.dependencies {
+            api(libs.openfeature.kotlin.sdk)
+        }
+        commonTest.dependencies {
+            implementation(libs.kotlin.test)
+        }
+    }
+}

providers/env-var/build.gradle.kts

@@ -0,0 +1,26 @@
+package dev.openfeature.kotlin.contrib.providers.envvar
+
+/**
+ * Converts an underscore-separated string to camel case.
+ */
+internal fun String.camelCase(): String {
+    // Split by underscores
+    val words =
+        split('_')
+            .filter { it.isNotEmpty() } // Remove empty strings that might result from splitting
+
+    if (words.isEmpty()) {
+        return ""
+    }
+
+    // The first word is converted to lowercase
+    val firstWord = words.first().lowercase()
+
+    // Subsequent words are capitalized (first letter uppercase, rest lowercase)
+    val restOfWords =
+        words.drop(1).joinToString("") { word ->
+            word.lowercase().replaceFirstChar { if (it.isLowerCase()) it.titlecase() else it.toString() }
+        }
+
+    return firstWord + restOfWords
+}

providers/env-var/src/commonMain/kotlin/dev/openfeature/kotlin/contrib/providers/envvar/CamelCase.kt

@@ -0,0 +1,92 @@
+package dev.openfeature.kotlin.contrib.providers.envvar
+
+import dev.openfeature.sdk.EvaluationContext
+import dev.openfeature.sdk.FeatureProvider
+import dev.openfeature.sdk.Hook
+import dev.openfeature.sdk.ProviderEvaluation
+import dev.openfeature.sdk.ProviderMetadata
+import dev.openfeature.sdk.Reason
+import dev.openfeature.sdk.Value
+import dev.openfeature.sdk.exceptions.OpenFeatureError
+
+/** EnvVarProvider is the Kotlin provider implementation for the environment variables.  */
+class EnvVarProvider(
+    private val environmentGateway: EnvironmentGateway = platformSpecificEnvironmentGateway(),
+    private val keyTransformer: EnvironmentKeyTransformer = EnvironmentKeyTransformer.doNothing(),
+) : FeatureProvider {
+    override val hooks: List<Hook<*>> = emptyList()
+    override val metadata: ProviderMetadata
+        get() = Metadata
+
+    override suspend fun initialize(initialContext: EvaluationContext?) {
+        // Nothing to do here
+    }
+
+    override fun shutdown() {
+        // Nothing to do here
+    }
+
+    override suspend fun onContextSet(
+        oldContext: EvaluationContext?,
+        newContext: EvaluationContext,
+    ) {
+        // Nothing to do here
+    }
+
+    override fun getBooleanEvaluation(
+        key: String,
+        defaultValue: Boolean,
+        context: EvaluationContext?,
+    ): ProviderEvaluation<Boolean> = evaluateEnvironmentVariable(key, String::toBoolean)
+
+    override fun getDoubleEvaluation(
+        key: String,
+        defaultValue: Double,
+        context: EvaluationContext?,
+    ): ProviderEvaluation<Double> = evaluateEnvironmentVariable(key, String::toDouble)
+
+    override fun getIntegerEvaluation(
+        key: String,
+        defaultValue: Int,
+        context: EvaluationContext?,
+    ): ProviderEvaluation<Int> = evaluateEnvironmentVariable(key, String::toInt)
+
+    override fun getStringEvaluation(
+        key: String,
+        defaultValue: String,
+        context: EvaluationContext?,
+    ): ProviderEvaluation<String> = evaluateEnvironmentVariable(key, { it })
+
+    override fun getObjectEvaluation(
+        key: String,
+        defaultValue: Value,
+        context: EvaluationContext?,
+    ): ProviderEvaluation<Value> = throw OpenFeatureError.GeneralError("EnvVarProvider supports only primitives")
+
+    private fun <T> evaluateEnvironmentVariable(
+        key: String,
+        parse: (String) -> T,
+    ): ProviderEvaluation<T> {
+        val value: String =
+            environmentGateway.getEnvironmentVariable(keyTransformer.transformKey(key))
+                ?: throw OpenFeatureError.FlagNotFoundError(key)
+
+        try {
+            return ProviderEvaluation(
+                value = parse(value),
+                reason = Reason.STATIC.toString(),
+            )
+        } catch (e: Exception) {
+            throw OpenFeatureError.ParseError(e.message ?: "Unknown parsing error")
+        }
+    }
+
+    companion object {
+        private val NAME: String = "Environment Variables Provider"
+    }
+
+    private object Metadata : ProviderMetadata {
+        override val name: String
+            get() = NAME
+    }
+}

providers/env-var/src/commonMain/kotlin/dev/openfeature/kotlin/contrib/providers/envvar/EnvVarProvider.kt

@@ -0,0 +1,11 @@
+package dev.openfeature.kotlin.contrib.providers.envvar
+
+/**
+ * This is an abstraction to fetch environment variables. It can be used to support
+ * environment-specific access or provide additional functionality, like prefixes, casing and even
+ * sources like spring configurations which come from different sources. Also, a test double could
+ * implement this interface, making the tests independent of the actual environment.
+ */
+fun interface EnvironmentGateway {
+    fun getEnvironmentVariable(key: String): String?
+}

providers/env-var/src/commonMain/kotlin/dev/openfeature/kotlin/contrib/providers/envvar/EnvironmentGateway.kt

@@ -0,0 +1,81 @@
+package dev.openfeature.kotlin.contrib.providers.envvar
+
+/**
+ * This class provides a way to transform any given key to another value. This is helpful, if keys in the code have a
+ * different representation as in the actual environment, e.g. SCREAMING_SNAKE_CASE env vars vs. hyphen-case keys
+ * for feature flags.
+ *
+ *
+ * This class also supports chaining/combining different transformers incl. self-written ones by providing
+ * a transforming function in the constructor. <br></br>
+ * Currently, the following transformations are supported out of the box:
+ *
+ *  * [converting to lower case][.toLowerCaseTransformer]
+ *  * [converting to UPPER CASE][.toUpperCaseTransformer]
+ *  * [converting hyphen-case to SCREAMING_SNAKE_CASE][.hyphenCaseToScreamingSnake]
+ *  * [convert to camelCase][.toCamelCaseTransformer]
+ *  * [replace &#39;_&#39; with &#39;.&#39;][.replaceUnderscoreWithDotTransformer]
+ *  * [replace &#39;.&#39; with &#39;_&#39;][.replaceDotWithUnderscoreTransformer]
+ *
+ *
+ *
+ * **Examples:**
+ *
+ *
+ * 1. hyphen-case feature flag names to screaming snake-case environment variables:
+ * <pre>
+ * `// Definition of the EnvVarProvider:
+ * EnvironmentKeyTransformer transformer = EnvironmentKeyTransformer
+ * .hyphenCaseToScreamingSnake();
+ *
+ * FeatureProvider provider = new EnvVarProvider(transformer);
+` *
+</pre> *
+ * 2. chained/composed transformations:
+ * <pre>
+ * `// Definition of the EnvVarProvider:
+ * EnvironmentKeyTransformer transformer = EnvironmentKeyTransformer
+ * .toLowerCaseTransformer()
+ * .andThen(EnvironmentKeyTransformer.replaceUnderscoreWithDotTransformer());
+ *
+ * FeatureProvider provider = new EnvVarProvider(transformer);
+` *
+</pre> *
+ * 3. freely defined transformation function:
+ * <pre>
+ * `// Definition of the EnvVarProvider:
+ * EnvironmentKeyTransformer transformer = new EnvironmentKeyTransformer(key -> "constant");
+ *
+ * FeatureProvider provider = new EnvVarProvider(keyTransformer);
+` *
+</pre> *
+ */
+fun interface EnvironmentKeyTransformer {
+    fun transformKey(key: String): String
+
+    fun andThen(another: EnvironmentKeyTransformer): EnvironmentKeyTransformer =
+        EnvironmentKeyTransformer { key ->
+            another.transformKey(
+                this.transformKey(key),
+            )
+        }
+
+    companion object {
+        fun toLowerCaseTransformer(): EnvironmentKeyTransformer = EnvironmentKeyTransformer { key -> key.lowercase() }
+
+        fun toUpperCaseTransformer(): EnvironmentKeyTransformer = EnvironmentKeyTransformer { key -> key.uppercase() }
+
+        fun toCamelCaseTransformer(): EnvironmentKeyTransformer = EnvironmentKeyTransformer { key -> key.camelCase() }
+
+        fun replaceUnderscoreWithDotTransformer(): EnvironmentKeyTransformer = EnvironmentKeyTransformer { key -> key.replace('_', '.') }
+
+        fun replaceDotWithUnderscoreTransformer(): EnvironmentKeyTransformer = EnvironmentKeyTransformer { key -> key.replace('.', '_') }
+
+        fun hyphenCaseToScreamingSnake(): EnvironmentKeyTransformer =
+            EnvironmentKeyTransformer { key ->
+                key.replace('-', '_').uppercase()
+            }
+
+        fun doNothing(): EnvironmentKeyTransformer = EnvironmentKeyTransformer { s -> s }
+    }
+}

providers/env-var/src/commonMain/kotlin/dev/openfeature/kotlin/contrib/providers/envvar/EnvironmentKeyTransformer.kt

@@ -0,0 +1,3 @@
+package dev.openfeature.kotlin.contrib.providers.envvar
+
+internal expect fun platformSpecificEnvironmentGateway(): EnvironmentGateway