feat: multi-provider implementation

.github/component_owners.yml

@@ -35,6 +35,8 @@ components:
     - novalisdenahi
   providers/statsig:
     - liran2000
+  providers/multi-provider:
+    - liran2000
 
 ignored-authors:
   - renovate-bot

.release-please-manifest.json

@@ -9,5 +9,6 @@
   "providers/flipt": "0.1.1",
   "providers/configcat": "0.1.0",
   "providers/statsig": "0.1.0",
+  "providers/multi-provider": "0.0.1",
   "tools/junit-openfeature": "0.1.1"
 }

pom.xml

@@ -38,6 +38,7 @@
         <module>providers/flipt</module>
         <module>providers/configcat</module>
         <module>providers/statsig</module>
+        <module>providers/multiprovider</module>
     </modules>
 
     <scm>

providers/multiprovider/CHANGELOG.md

@@ -0,0 +1,81 @@
+# Changelog
+
+## [0.1.0](https://github.com/open-feature/java-sdk-contrib/compare/dev.openfeature.contrib.providers.statsig-v0.0.4...dev.openfeature.contrib.providers.statsig-v0.1.0) (2024-09-25)
+
+
+### ⚠ BREAKING CHANGES
+
+* use sdk-maintained state, require 1.12 ([#964](https://github.com/open-feature/java-sdk-contrib/issues/964))
+
+### 🐛 Bug Fixes
+
+* **deps:** update dependency com.statsig:serversdk to v1.13.0 ([#699](https://github.com/open-feature/java-sdk-contrib/issues/699)) ([f5c38cf](https://github.com/open-feature/java-sdk-contrib/commit/f5c38cf832e6d4970b3076811ac5b6c2b7da86ee))
+* **deps:** update dependency com.statsig:serversdk to v1.13.1 ([#704](https://github.com/open-feature/java-sdk-contrib/issues/704)) ([5d35725](https://github.com/open-feature/java-sdk-contrib/commit/5d357255f10f6608a51bf253bac5dc999fef5a83))
+* **deps:** update dependency com.statsig:serversdk to v1.14.0 ([#718](https://github.com/open-feature/java-sdk-contrib/issues/718)) ([7f76265](https://github.com/open-feature/java-sdk-contrib/commit/7f76265b4f610a171bd5bd239941cb1d1420ab55))
+* **deps:** update dependency com.statsig:serversdk to v1.15.0 ([#728](https://github.com/open-feature/java-sdk-contrib/issues/728)) ([f101e2f](https://github.com/open-feature/java-sdk-contrib/commit/f101e2f6d5b5d9486bc5b426a1f05c71b70d658c))
+* **deps:** update dependency com.statsig:serversdk to v1.16.0 ([#754](https://github.com/open-feature/java-sdk-contrib/issues/754)) ([c8e5cb6](https://github.com/open-feature/java-sdk-contrib/commit/c8e5cb66305db5b076ed4ba5f1a6d1a60b0115f3))
+* **deps:** update dependency com.statsig:serversdk to v1.17.0 ([#758](https://github.com/open-feature/java-sdk-contrib/issues/758)) ([e0c7a26](https://github.com/open-feature/java-sdk-contrib/commit/e0c7a266835ab41e9298cd9b726f696bcac21527))
+* **deps:** update dependency com.statsig:serversdk to v1.17.1 ([#768](https://github.com/open-feature/java-sdk-contrib/issues/768)) ([40d4492](https://github.com/open-feature/java-sdk-contrib/commit/40d4492372c44abccf45f03a3ec499b3727b6d0a))
+* **deps:** update dependency com.statsig:serversdk to v1.17.2 ([#770](https://github.com/open-feature/java-sdk-contrib/issues/770)) ([1da0305](https://github.com/open-feature/java-sdk-contrib/commit/1da0305d8daf35fc64d0864bf9839ac1afe88bf4))
+* **deps:** update dependency com.statsig:serversdk to v1.17.3 ([#774](https://github.com/open-feature/java-sdk-contrib/issues/774)) ([fa56579](https://github.com/open-feature/java-sdk-contrib/commit/fa56579fdebe99cbc5415e95585ba791b4e1b247))
+* **deps:** update dependency com.statsig:serversdk to v1.18.0 ([#799](https://github.com/open-feature/java-sdk-contrib/issues/799)) ([bfbdef8](https://github.com/open-feature/java-sdk-contrib/commit/bfbdef8cdfe6bdbb1015ffc65354f852b3889fa5))
+* **deps:** update dependency com.statsig:serversdk to v1.18.1 ([#806](https://github.com/open-feature/java-sdk-contrib/issues/806)) ([17c61c3](https://github.com/open-feature/java-sdk-contrib/commit/17c61c32d5669ef19e886230b95c4028e9d87d0c))
+* **deps:** update dependency com.statsig:serversdk to v1.22.0 ([#822](https://github.com/open-feature/java-sdk-contrib/issues/822)) ([a560308](https://github.com/open-feature/java-sdk-contrib/commit/a560308452ea737b41b9d19d1d0942dffa7f9e51))
+* **deps:** update dependency org.slf4j:slf4j-api to v2.0.13 ([#752](https://github.com/open-feature/java-sdk-contrib/issues/752)) ([b820fcf](https://github.com/open-feature/java-sdk-contrib/commit/b820fcf1b7ea945a8e450dcc90addb82f5fb865d))
+* **deps:** update dependency org.slf4j:slf4j-api to v2.0.14 ([#904](https://github.com/open-feature/java-sdk-contrib/issues/904)) ([028b332](https://github.com/open-feature/java-sdk-contrib/commit/028b332dc8ac3b134e5453d5449a4c11b4ef250a))
+* **deps:** update dependency org.slf4j:slf4j-api to v2.0.15 ([#910](https://github.com/open-feature/java-sdk-contrib/issues/910)) ([2f58638](https://github.com/open-feature/java-sdk-contrib/commit/2f58638eb4907c948325d1e61853e1b6eabfa4c1))
+* **deps:** update dependency org.slf4j:slf4j-api to v2.0.16 ([#912](https://github.com/open-feature/java-sdk-contrib/issues/912)) ([52571d8](https://github.com/open-feature/java-sdk-contrib/commit/52571d806e7c547006db836245b4895fe9bc4660))
+
+
+### ✨ New Features
+
+* add support for getBooleanEvaluation with default value ([#722](https://github.com/open-feature/java-sdk-contrib/issues/722)) ([835f672](https://github.com/open-feature/java-sdk-contrib/commit/835f6727d98883bb7fc351b5dd59039228fbcb2b))
+* use sdk-maintained state, require 1.12 ([#964](https://github.com/open-feature/java-sdk-contrib/issues/964)) ([4a041b0](https://github.com/open-feature/java-sdk-contrib/commit/4a041b0dda9c4e460f4c2199f3bc680df0dda621))
+
+
+### 🧹 Chore
+
+* **deps:** update dependency org.apache.logging.log4j:log4j-slf4j2-impl to v2.23.1 ([#709](https://github.com/open-feature/java-sdk-contrib/issues/709)) ([d0bc7a5](https://github.com/open-feature/java-sdk-contrib/commit/d0bc7a5aceb746d6d7c442e189a6a1e011673ba7))
+* **deps:** update dependency org.apache.logging.log4j:log4j-slf4j2-impl to v2.24.0 ([#940](https://github.com/open-feature/java-sdk-contrib/issues/940)) ([5465337](https://github.com/open-feature/java-sdk-contrib/commit/546533739b453988720bb051d5e623ac7eb0b588))
+* fix pmd violations ([#856](https://github.com/open-feature/java-sdk-contrib/issues/856)) ([f10d872](https://github.com/open-feature/java-sdk-contrib/commit/f10d87205dd6a21222de362694d208fd293d9200))
+* update failing tests ([#732](https://github.com/open-feature/java-sdk-contrib/issues/732)) ([e1eaf4e](https://github.com/open-feature/java-sdk-contrib/commit/e1eaf4e3778d11ecf25d4276d3733760fa72eb9f))
+
+## [0.0.4](https://github.com/open-feature/java-sdk-contrib/compare/dev.openfeature.contrib.providers.statsig-v0.0.3...dev.openfeature.contrib.providers.statsig-v0.0.4) (2024-02-27)
+
+
+### 🐛 Bug Fixes
+
+* **deps:** update dependency com.statsig:serversdk to v1.12.1 ([#687](https://github.com/open-feature/java-sdk-contrib/issues/687)) ([91da6fe](https://github.com/open-feature/java-sdk-contrib/commit/91da6fee020bdf60d51e1a6849e94201a2b04dec))
+
+
+### ✨ New Features
+
+* Statsig provider evaluate boolean updates ([#691](https://github.com/open-feature/java-sdk-contrib/issues/691)) ([04df666](https://github.com/open-feature/java-sdk-contrib/commit/04df6669264227e3c3c6165ea0d876e5d8aa8766))
+
+
+### 🧹 Chore
+
+* **deps:** update dependency org.apache.logging.log4j:log4j-slf4j2-impl to v2.23.0 ([#689](https://github.com/open-feature/java-sdk-contrib/issues/689)) ([6589871](https://github.com/open-feature/java-sdk-contrib/commit/65898713166b5d02f246302c54fd7400ee4238d5))
+
+## [0.0.3](https://github.com/open-feature/java-sdk-contrib/compare/dev.openfeature.contrib.providers.statsig-v0.0.2...dev.openfeature.contrib.providers.statsig-v0.0.3) (2024-02-14)
+
+
+### 🐛 Bug Fixes
+
+* null exception when no options used ([#681](https://github.com/open-feature/java-sdk-contrib/issues/681)) ([19b96f8](https://github.com/open-feature/java-sdk-contrib/commit/19b96f8c8a62dbde3ed52177953d3e9fe9398912))
+
+## [0.0.2](https://github.com/open-feature/java-sdk-contrib/compare/dev.openfeature.contrib.providers.statsig-v0.0.1...dev.openfeature.contrib.providers.statsig-v0.0.2) (2024-02-09)
+
+
+### 🐛 Bug Fixes
+
+* **deps:** update dependency com.statsig:serversdk to v1.11.1 ([#658](https://github.com/open-feature/java-sdk-contrib/issues/658)) ([ad668ac](https://github.com/open-feature/java-sdk-contrib/commit/ad668acd81568f86c55d3a02f3678f7169631275))
+* **deps:** update dependency com.statsig:serversdk to v1.12.0 ([#671](https://github.com/open-feature/java-sdk-contrib/issues/671)) ([4bdfb15](https://github.com/open-feature/java-sdk-contrib/commit/4bdfb157f33a5b141e7c7b2a905b91db952d7611))
+* **deps:** update dependency org.slf4j:slf4j-api to v2.0.12 ([#661](https://github.com/open-feature/java-sdk-contrib/issues/661)) ([f03d933](https://github.com/open-feature/java-sdk-contrib/commit/f03d93305bda8ea932831e81db57c989ce4e14e4))
+
+
+### ✨ New Features
+
+* Add Statsig provider ([#641](https://github.com/open-feature/java-sdk-contrib/issues/641)) ([f814696](https://github.com/open-feature/java-sdk-contrib/commit/f814696463dd742ee30d1a1e5bdc196b6689447e))
+
+## Changelog

providers/multiprovider/README.md

@@ -0,0 +1,103 @@
+# OpenFeature Multi-Provider for Java
+
+The OpenFeature Multi-Provider wraps multiple underlying providers in a unified interface, allowing the SDK client to transparently interact with all those providers at once.
+This allows use cases where a single client and evaluation interface is desired, but where the flag data should come from more than one source.
+
+Some examples:
+
+- A migration from one feature flagging provider to another.
+  During that process, you may have some flags that have been ported to the new system and others that haven’t.
+  Therefore, you’d want the Multi-Provider to return the result of the “new” system if available otherwise, return the "
+  old" system’s result.
+- Long-term use of multiple sources for flags.
+  For example, someone might want to be able to combine environment variables, database entries, and vendor feature flag
+  results together in a single interface, and define the precedence order in which those sources should be consulted.
+- Setting a fallback for cloud providers.
+  You can use the Multi-Provider to automatically fall back to a local configuration if an external vendor provider goes
+  down, rather than using the default values. By using the FirstSuccessfulStrategy, the Multi-Provider will move on to
+  the next provider in the list if an error is thrown.
+
+## Strategies
+
+The Multi-Provider supports multiple ways of deciding how to evaluate the set of providers it is managing, and how to
+deal with any errors that are thrown.
+
+Strategies must be adaptable to the various requirements that might be faced in a multi-provider situation.
+In some cases, the strategy may want to ignore errors from individual providers as long as one of them successfully
+responds.
+In other cases, it may want to evaluate providers in order and skip the rest if a successful result is obtained.
+In still other scenarios, it may be required to always call every provider and decide what to do with the set of
+results.
+
+The strategy to use is passed in to the Multi-Provider.
+
+By default, the Multi-Provider uses the “FirstMatchStrategy”.
+
+Here are some standard strategies that come with the Multi-Provider:
+
+### First Match
+
+Return the first result returned by a provider.
+Skip providers that indicate they had no value due to `FLAG_NOT_FOUND`.
+In all other cases, use the value returned by the provider.
+If any provider returns an error result other than `FLAG_NOT_FOUND`, the whole evaluation should error and “bubble up”
+the individual provider’s error in the result.
+
+As soon as a value is returned by a provider, the rest of the operation should short-circuit and not call the rest of
+the providers.
+
+### First Successful
+
+Similar to “First Match”, except that errors from evaluated providers do not halt execution.
+Instead, it will return the first successful result from a provider. If no provider successfully responds, it will throw
+an error result.
+
+### User Defined
+
+Rather than making assumptions about when to use a provider’s result and when not to (which may not hold across all
+providers) there is also a way for the user to define their own strategy that determines whether or not to use a result
+or fall through to the next one.
+
+## Installation
+
+<!-- x-release-please-start-version -->
+
+```xml
+
+<dependency>
+    <groupId>dev.openfeature.contrib.providers</groupId>
+    <artifactId>multi-provider</artifactId>
+    <version>0.0.1</version>
+</dependency>
+```
+
+<!-- x-release-please-end-version -->
+
+## Usage
+
+Usage example:
+
+```
+...
+List<FeatureProvider> providers = new ArrayList<>(2);
+providers.add(provider1);
+providers.add(provider2);
+
+// initialize using default strategy (first match)
+MultiProvider multiProvider = new MultiProvider(providers);
+OpenFeatureAPI.getInstance().setProviderAndWait(multiProvider);
+
+// initialize using a different strategy
+
+// notice LinkedHashMap is used, since order is important
+Map<String, FeatureProvider> providersMap = new LinkedHashMap<>(2);
+
+providersMap.put(provider1.getMetadata().getName(), provider1);
+providersMap.put(provider2.getMetadata().getName(), provider2);
+multiProvider = new MultiProvider(providers, new FirstSuccessfulStrategy(providersMap));
+...
+```
+
+See [MultiProviderTest](./src/test/java/dev/openfeature/contrib/providers/multiprovider/MultiProviderTest.java)
+for more information.
+

providers/multiprovider/lombok.config

@@ -0,0 +1,5 @@
+# This file is needed to avoid errors throw by findbugs when working with lombok.
+lombok.addSuppressWarnings = true
+lombok.addLombokGeneratedAnnotation = true
+config.stopBubbling = true
+lombok.extern.findbugs.addSuppressFBWarnings = true

providers/multiprovider/pom.xml

@@ -0,0 +1,32 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://maven.apache.org/POM/4.0.0"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+    <parent>
+        <groupId>dev.openfeature.contrib</groupId>
+        <artifactId>parent</artifactId>
+        <version>0.1.0</version>
+        <relativePath>../../pom.xml</relativePath>
+    </parent>
+    <groupId>dev.openfeature.contrib.providers</groupId>
+    <artifactId>multiprovider</artifactId>
+    <version>0.0.1</version> <!--x-release-please-version -->
+
+    <name>multiprovider</name>
+    <description>OpenFeature Multi-Provider</description>
+    <url>https://github.com/open-feature/java-sdk-contrib/tree/main/providers/multi-provider</url>
+
+    <dependencies>
+        <dependency>
+            <groupId>org.json</groupId>
+            <artifactId>json</artifactId>
+            <version>20240303</version>
+        </dependency>
+        <dependency>
+            <groupId>org.apache.logging.log4j</groupId>
+            <artifactId>log4j-slf4j2-impl</artifactId>
+            <version>2.24.1</version>
+            <scope>test</scope>
+        </dependency>
+    </dependencies>
+</project>

providers/multiprovider/src/main/java/dev/openfeature/contrib/providers/multiprovider/BaseStrategy.java

@@ -0,0 +1,26 @@
+package dev.openfeature.contrib.providers.multiprovider;
+
+import dev.openfeature.sdk.FeatureProvider;
+import lombok.AccessLevel;
+import lombok.Getter;
+import lombok.extern.slf4j.Slf4j;
+
+import java.util.List;
+import java.util.Map;
+
+import static dev.openfeature.contrib.providers.multiprovider.MultiProvider.buildProviders;
+
+/**
+ * Base strategy.
+ */
+@Slf4j
+public abstract class BaseStrategy implements Strategy {
+
+    @Getter(AccessLevel.PROTECTED)
+    private final Map<String, FeatureProvider> providers;
+
+    public BaseStrategy(List<FeatureProvider> providers) {
+        this.providers = buildProviders(providers);
+    }
+
+}

providers/multiprovider/src/main/java/dev/openfeature/contrib/providers/multiprovider/FirstMatchStrategy.java

@@ -0,0 +1,55 @@
+package dev.openfeature.contrib.providers.multiprovider;
+
+import dev.openfeature.sdk.EvaluationContext;
+import dev.openfeature.sdk.FeatureProvider;
+import dev.openfeature.sdk.ProviderEvaluation;
+import dev.openfeature.sdk.exceptions.FlagNotFoundError;
+import lombok.extern.slf4j.Slf4j;
+
+import java.util.List;
+import java.util.function.Function;
+
+import static dev.openfeature.sdk.ErrorCode.FLAG_NOT_FOUND;
+
+/**
+ * First match strategy.
+ * Return the first result returned by a provider. Skip providers that indicate they had no value due to
+ * FLAG_NOT_FOUND.
+ * In all other cases, use the value returned by the provider.
+ * If any provider returns an error result other than FLAG_NOT_FOUND, the whole evaluation should error and
+ * “bubble up” the individual provider’s error in the result.
+ * As soon as a value is returned by a provider, the rest of the operation should short-circuit and not call
+ * the rest of the providers.
+ */
+@Slf4j
+public class FirstMatchStrategy extends BaseStrategy {
+
+    public FirstMatchStrategy(List<FeatureProvider> providers) {
+        super(providers);
+    }
+
+    /**
+     * Represents a strategy that evaluates providers based on a first-match approach.
+     * Provides a method to evaluate providers using a specified function and return the evaluation result.
+     *
+     * @param providerFunction provider function
+     * @param <T> ProviderEvaluation type
+     * @return the provider evaluation
+     */
+    @Override
+    public <T> ProviderEvaluation<T> evaluate(String key, T defaultValue, EvaluationContext ctx,
+              Function<FeatureProvider, ProviderEvaluation<T>> providerFunction) {
+        for (FeatureProvider provider: getProviders().values()) {
+            try {
+                ProviderEvaluation<T> res = providerFunction.apply(provider);
+                if (!FLAG_NOT_FOUND.equals(res.getErrorCode())) {
+                    return res;
+                }
+            } catch (FlagNotFoundError e) {
+                log.debug("flag not found {}", e.getMessage());
+            }
+        }
+
+        throw new FlagNotFoundError("flag not found");
+    }
+}

providers/multiprovider/src/main/java/dev/openfeature/contrib/providers/multiprovider/FirstSuccessfulStrategy.java

@@ -0,0 +1,41 @@
+package dev.openfeature.contrib.providers.multiprovider;
+
+import dev.openfeature.sdk.EvaluationContext;
+import dev.openfeature.sdk.FeatureProvider;
+import dev.openfeature.sdk.ProviderEvaluation;
+import dev.openfeature.sdk.exceptions.GeneralError;
+import lombok.extern.slf4j.Slf4j;
+
+import java.util.List;
+import java.util.function.Function;
+
+/**
+ * First Successful Strategy.
+ * Similar to “First Match”, except that errors from evaluated providers do not halt execution.
+ * Instead, it will return the first successful result from a provider.
+ * If no provider successfully responds, it will throw an error result.
+ */
+@Slf4j
+public class FirstSuccessfulStrategy extends BaseStrategy {
+
+    public FirstSuccessfulStrategy(List<FeatureProvider> providers) {
+        super(providers);
+    }
+
+    @Override
+    public <T> ProviderEvaluation<T> evaluate(String key, T defaultValue, EvaluationContext ctx,
+              Function<FeatureProvider, ProviderEvaluation<T>> providerFunction) {
+        for (FeatureProvider provider: getProviders().values()) {
+            try {
+                ProviderEvaluation<T> res = providerFunction.apply(provider);
+                if (res.getErrorCode() == null) {
+                    return res;
+                }
+            } catch (Exception e) {
+                log.debug("evaluation exception {}", e.getMessage());
+            }
+        }
+
+        throw new GeneralError("evaluation error");
+    }
+}