feat: provide key transformations (#288)

Signed-off-by: Lars Opitz <[email protected]>
Co-authored-by: Michael Beemer <[email protected]>

Author: lopitz

providers/env-var/README.md

@@ -18,10 +18,70 @@ Environment Variables provider allows you to read feature flags from the [proces
 
 ## Usage
 
-`EnvVarProvider` doesn't have any options.
-Just create an instance and use it as a provider:
+To use the `EnvVarProvider` create an instance and use it as a provider:
 
 ```java
-EnvVarProvider provider = new EnvVarProvider();
-OpenFeatureAPI.getInstance().setProvider(provider);
+    EnvVarProvider provider = new EnvVarProvider();
+    OpenFeatureAPI.getInstance().setProvider(provider);
 ```
+
+### Configuring different methods of fetching environment variables
+
+This provider defines an `EnvironmentGateway` interface, which is used to access the actual environment variables. 
+The class [OS][os-class] is implementing this interface and creates the actual connection between provider 
+and environment variables. For testing or in case accessing the environment variables is more complex than supported
+by Java's `java.lang.System` class, the implementation can be switched accordingly by passing it into the constructor 
+of the provider.
+
+```java
+    EnvironmentGateway testFake = arg -> "true"; //always returns true
+    
+    EnvVarProvider provider = new 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:
+
+```java
+    // Definition of the EnvVarProvider:
+    FeatureProvider provider = new EnvVarProvider(EnvironmentKeyTransformer.hyphenCaseToScreamingSnake());
+```
+
+2. chained/composed transformations:
+
+```java
+    // Definition of the EnvVarProvider:
+    EnvironmentKeyTransformer keyTransformer = EnvironmentKeyTransformer
+        .toLowerCaseTransformer()
+        .andThen(EnvironmentKeyTransformer.replaceUnderscoreWithDotTransformer());
+
+    FeatureProvider provider = new EnvVarProvider(keyTransformer);
+```
+
+3. freely defined transformation function:
+
+```java
+    // Definition of the EnvVarProvider:   
+    EnvironmentKeyTransformer keyTransformer = new EnvironmentKeyTransformer(key -> key.substring(1));
+    FeatureProvider provider = new EnvVarProvider(keyTransformer);
+```
+
+<!-- links -->
+
+[os-class]: src/main/java/dev/openfeature/contrib/providers/envvar/OS.java

providers/env-var/pom.xml

@@ -21,4 +21,12 @@
             <name>Siarhei Krukau</name>
         </developer>
     </developers>
+
+    <dependencies>
+        <dependency>
+            <groupId>org.apache.commons</groupId>
+            <artifactId>commons-lang3</artifactId>
+            <version>3.12.0</version>
+        </dependency>
+    </dependencies>
 </project>

providers/env-var/src/main/java/dev/openfeature/contrib/providers/envvar/EnvVarProvider.java

@@ -14,13 +14,23 @@ public final class EnvVarProvider implements FeatureProvider {
     private static final String NAME = "Environment Variables Provider";
 
     private final EnvironmentGateway environmentGateway;
+    private final EnvironmentKeyTransformer keyTransformer;
 
     public EnvVarProvider() {
-        this.environmentGateway = new OS();
+        this(new OS(), EnvironmentKeyTransformer.doNothing());
     }
 
     public EnvVarProvider(EnvironmentGateway environmentGateway) {
+        this(environmentGateway, EnvironmentKeyTransformer.doNothing());
+    }
+
+    public EnvVarProvider(EnvironmentKeyTransformer keyTransformer) {
+        this(new OS(), keyTransformer);
+    }
+
+    public EnvVarProvider(EnvironmentGateway environmentGateway, EnvironmentKeyTransformer keyTransformer) {
         this.environmentGateway = environmentGateway;
+        this.keyTransformer = keyTransformer;
     }
 
     @Override
@@ -57,7 +67,7 @@ private <T> ProviderEvaluation<T> evaluateEnvironmentVariable(
             String key,
             Function<String, T> parse
     ) {
-        final String value = environmentGateway.getEnvironmentVariable(key);
+        final String value = environmentGateway.getEnvironmentVariable(keyTransformer.transformKey(key));
 
         if (value == null) {
             throw new FlagNotFoundError();

providers/env-var/src/main/java/dev/openfeature/contrib/providers/envvar/EnvironmentKeyTransformer.java

@@ -0,0 +1,109 @@
+package dev.openfeature.contrib.providers.envvar;
+
+import java.util.function.*;
+
+import lombok.RequiredArgsConstructor;
+import org.apache.commons.lang3.StringUtils;
+import org.apache.commons.text.CaseUtils;
+
+/**
+ * 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.
+ *
+ * <p>This class also supports chaining/combining different transformers incl. self-written ones by providing
+ * a transforming function in the constructor. <br>
+ * Currently, the following transformations are supported out of the box:
+ * <ul>
+ *     <li>{@link #toLowerCaseTransformer() converting to lower case}</li>
+ *     <li>{@link #toUpperCaseTransformer() converting to UPPER CASE}</li>
+ *     <li>{@link #hyphenCaseToScreamingSnake() converting hyphen-case to SCREAMING_SNAKE_CASE}</li>
+ *     <li>{@link #toCamelCaseTransformer() convert to camelCase}</li>
+ *     <li>{@link #replaceUnderscoreWithDotTransformer() replace '_' with '.'}</li>
+ *     <li>{@link #replaceDotWithUnderscoreTransformer() replace '.' with '_'}</li>
+ * </ul>
+ *
+ * <p><strong>Examples:</strong>
+ *
+ * <p>1. hyphen-case feature flag names to screaming snake-case environment variables:
+ * <pre>
+ * {@code
+ * // Definition of the EnvVarProvider:
+ * EnvironmentKeyTransformer transformer = EnvironmentKeyTransformer
+ *     .hyphenCaseToScreamingSnake();
+ *
+ * FeatureProvider provider = new EnvVarProvider(transformer);
+ * }
+ * </pre>
+ * 2. chained/composed transformations:
+ * <pre>
+ * {@code
+ * // Definition of the EnvVarProvider:
+ * EnvironmentKeyTransformer transformer = EnvironmentKeyTransformer
+ *     .toLowerCaseTransformer()
+ *     .andThen(EnvironmentKeyTransformer.replaceUnderscoreWithDotTransformer());
+ *
+ * FeatureProvider provider = new EnvVarProvider(transformer);
+ * }
+ * </pre>
+ * 3. freely defined transformation function:
+ * <pre>
+ * {@code
+ *
+ * // Definition of the EnvVarProvider:
+ * EnvironmentKeyTransformer transformer = new EnvironmentKeyTransformer(key -> "constant");
+ *
+ * FeatureProvider provider = new EnvVarProvider(keyTransformer);
+ * }
+ * </pre>
+ */
+@RequiredArgsConstructor
+public class EnvironmentKeyTransformer {
+
+    private static final UnaryOperator<String> TO_LOWER_CASE = StringUtils::lowerCase;
+    private static final UnaryOperator<String> TO_UPPER_CASE = StringUtils::upperCase;
+    private static final UnaryOperator<String> TO_CAMEL_CASE = s -> CaseUtils.toCamelCase(s, false, '_');
+    private static final UnaryOperator<String> REPLACE_DOT_WITH_UNDERSCORE = s -> StringUtils.replaceChars(s, ".", "_");
+    private static final UnaryOperator<String> REPLACE_UNDERSCORE_WITH_DOT = s -> StringUtils.replaceChars(s, "_", ".");
+    private static final UnaryOperator<String> REPLACE_HYPHEN_WITH_UNDERSCORE =
+        s -> StringUtils.replaceChars(s, "-", "_");
+
+    private final Function<String, String> transformation;
+
+    public String transformKey(String key) {
+        return transformation.apply(key);
+    }
+
+    public EnvironmentKeyTransformer andThen(EnvironmentKeyTransformer another) {
+        return new EnvironmentKeyTransformer(transformation.andThen(another::transformKey));
+    }
+
+    public static EnvironmentKeyTransformer toLowerCaseTransformer() {
+        return new EnvironmentKeyTransformer(TO_LOWER_CASE);
+    }
+
+    public static EnvironmentKeyTransformer toUpperCaseTransformer() {
+        return new EnvironmentKeyTransformer(TO_UPPER_CASE);
+    }
+
+    public static EnvironmentKeyTransformer toCamelCaseTransformer() {
+        return new EnvironmentKeyTransformer(TO_CAMEL_CASE);
+    }
+
+    public static EnvironmentKeyTransformer replaceUnderscoreWithDotTransformer() {
+        return new EnvironmentKeyTransformer(REPLACE_UNDERSCORE_WITH_DOT);
+    }
+
+    public static EnvironmentKeyTransformer replaceDotWithUnderscoreTransformer() {
+        return new EnvironmentKeyTransformer(REPLACE_DOT_WITH_UNDERSCORE);
+    }
+
+    public static EnvironmentKeyTransformer hyphenCaseToScreamingSnake() {
+        return new EnvironmentKeyTransformer(REPLACE_HYPHEN_WITH_UNDERSCORE)
+            .andThen(EnvironmentKeyTransformer.toUpperCaseTransformer());
+    }
+
+    public static EnvironmentKeyTransformer doNothing() {
+        return new EnvironmentKeyTransformer(s -> s);
+    }
+}

providers/env-var/src/test/java/dev/openfeature/contrib/providers/envvar/EnvVarProviderTest.java

@@ -4,14 +4,13 @@
 import dev.openfeature.sdk.exceptions.FlagNotFoundError;
 import dev.openfeature.sdk.exceptions.ParseError;
 import dev.openfeature.sdk.exceptions.ValueNotConvertableError;
-import org.junit.jupiter.api.DynamicTest;
-import org.junit.jupiter.api.Test;
-import org.junit.jupiter.api.TestFactory;
+import org.junit.jupiter.api.*;
 
-import java.util.Arrays;
+import java.util.*;
 import java.util.function.Consumer;
 import java.util.function.Function;
 
+import static org.assertj.core.api.Assertions.assertThat;
 import static org.junit.jupiter.api.Assertions.assertEquals;
 import static org.junit.jupiter.api.Assertions.assertThrows;
 
@@ -134,6 +133,33 @@ Iterable<DynamicTest> shouldThrowOnUnparseableValues() {
         );
     }
 
+    @Test
+    @DisplayName("should transform key if configured")
+    void shouldTransformKeyIfConfigured() {
+        String key = "key.transformed";
+        String expected = "key_transformed";
+
+        EnvironmentKeyTransformer transformer = EnvironmentKeyTransformer.replaceDotWithUnderscoreTransformer();
+        EnvironmentGateway gateway = s -> s;
+        EnvVarProvider provider = new EnvVarProvider(gateway, transformer);
+
+        String environmentVariableValue = provider.getStringEvaluation(key, "failed", null).getValue();
+
+        assertThat(environmentVariableValue).isEqualTo(expected);
+    }
+
+    @Test
+    @DisplayName("should use passed-in EnvironmentGateway")
+    void shouldUsePassedInEnvironmentGateway() {
+        EnvironmentGateway testFake = s -> "true";
+
+        EnvVarProvider provider = new EnvVarProvider(testFake);
+
+        boolean actual = provider.getBooleanEvaluation("any key", false, null).getValue();
+
+        assertThat(actual).isTrue();
+    }
+
     private <T> DynamicTest evaluationTest(
             String testName,
             String variableName,