feat: Add multi-provider support

pom.xml

@@ -70,6 +70,12 @@
             <version>2.0.17</version>
         </dependency>
 
+        <dependency>
+            <groupId>org.json</groupId>
+            <artifactId>json</artifactId>
+            <version>20250517</version>
+        </dependency>
+
         <!-- test -->
         <dependency>
             <groupId>com.tngtech.archunit</groupId>

src/main/java/dev/openfeature/sdk/multiprovider/FirstMatchStrategy.java

@@ -0,0 +1,53 @@
+package dev.openfeature.sdk.multiprovider;
+
+import static dev.openfeature.sdk.ErrorCode.FLAG_NOT_FOUND;
+
+import dev.openfeature.sdk.EvaluationContext;
+import dev.openfeature.sdk.FeatureProvider;
+import dev.openfeature.sdk.ProviderEvaluation;
+import dev.openfeature.sdk.exceptions.FlagNotFoundError;
+import java.util.Map;
+import java.util.function.Function;
+import lombok.NoArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+
+/**
+ * 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
+@NoArgsConstructor
+public class FirstMatchStrategy implements Strategy {
+
+    /**
+     * 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(
+            Map<String, FeatureProvider> providers,
+            String key,
+            T defaultValue,
+            EvaluationContext ctx,
+            Function<FeatureProvider, ProviderEvaluation<T>> providerFunction) {
+        for (FeatureProvider provider : providers.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");
+    }
+}

src/main/java/dev/openfeature/sdk/multiprovider/FirstSuccessfulStrategy.java

@@ -0,0 +1,41 @@
+package dev.openfeature.sdk.multiprovider;
+
+import dev.openfeature.sdk.EvaluationContext;
+import dev.openfeature.sdk.FeatureProvider;
+import dev.openfeature.sdk.ProviderEvaluation;
+import dev.openfeature.sdk.exceptions.GeneralError;
+import java.util.Map;
+import java.util.function.Function;
+import lombok.NoArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+
+/**
+ * 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
+@NoArgsConstructor
+public class FirstSuccessfulStrategy implements Strategy {
+
+    @Override
+    public <T> ProviderEvaluation<T> evaluate(
+            Map<String, FeatureProvider> providers,
+            String key,
+            T defaultValue,
+            EvaluationContext ctx,
+            Function<FeatureProvider, ProviderEvaluation<T>> providerFunction) {
+        for (FeatureProvider provider : providers.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");
+    }
+}

src/main/java/dev/openfeature/sdk/multiprovider/MultiProvider.java

@@ -0,0 +1,148 @@
+package dev.openfeature.sdk.multiprovider;
+
+import dev.openfeature.sdk.EvaluationContext;
+import dev.openfeature.sdk.EventProvider;
+import dev.openfeature.sdk.FeatureProvider;
+import dev.openfeature.sdk.Metadata;
+import dev.openfeature.sdk.ProviderEvaluation;
+import dev.openfeature.sdk.Value;
+import dev.openfeature.sdk.exceptions.GeneralError;
+import java.util.ArrayList;
+import java.util.Collection;
+import java.util.Collections;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+import java.util.concurrent.Callable;
+import java.util.concurrent.ExecutorService;
+import java.util.concurrent.Executors;
+import java.util.concurrent.Future;
+import lombok.Getter;
+import lombok.extern.slf4j.Slf4j;
+import org.json.JSONObject;
+
+/** <b>Experimental:</b> Provider implementation for Multi-provider. */
+@Slf4j
+public class MultiProvider extends EventProvider {
+
+    @Getter
+    private static final String NAME = "multiprovider";
+
+    public static final int INIT_THREADS_COUNT = 8;
+    private final Map<String, FeatureProvider> providers;
+    private final Strategy strategy;
+    private String metadataName;
+
+    /**
+     * Constructs a MultiProvider with the given list of FeatureProviders, using a default strategy.
+     *
+     * @param providers the list of FeatureProviders to initialize the MultiProvider with
+     */
+    public MultiProvider(List<FeatureProvider> providers) {
+        this(providers, null);
+    }
+
+    /**
+     * Constructs a MultiProvider with the given list of FeatureProviders and a strategy.
+     *
+     * @param providers the list of FeatureProviders to initialize the MultiProvider with
+     * @param strategy the strategy
+     */
+    public MultiProvider(List<FeatureProvider> providers, Strategy strategy) {
+        this.providers = buildProviders(providers);
+        if (strategy != null) {
+            this.strategy = strategy;
+        } else {
+            this.strategy = new FirstMatchStrategy();
+        }
+    }
+
+    protected static Map<String, FeatureProvider> buildProviders(List<FeatureProvider> providers) {
+        Map<String, FeatureProvider> providersMap = new LinkedHashMap<>(providers.size());
+        for (FeatureProvider provider : providers) {
+            FeatureProvider prevProvider =
+                    providersMap.put(provider.getMetadata().getName(), provider);
+            if (prevProvider != null) {
+                log.warn("duplicated provider name: {}", provider.getMetadata().getName());
+            }
+        }
+        return Collections.unmodifiableMap(providersMap);
+    }
+
+    /**
+     * Initialize the provider.
+     *
+     * @param evaluationContext evaluation context
+     * @throws Exception on error
+     */
+    @Override
+    public void initialize(EvaluationContext evaluationContext) throws Exception {
+        JSONObject json = new JSONObject();
+        json.put("name", NAME);
+        JSONObject providersMetadata = new JSONObject();
+        json.put("originalMetadata", providersMetadata);
+        ExecutorService initPool = Executors.newFixedThreadPool(INIT_THREADS_COUNT);
+        Collection<Callable<Boolean>> tasks = new ArrayList<>(providers.size());
+        for (FeatureProvider provider : providers.values()) {
+            tasks.add(() -> {
+                provider.initialize(evaluationContext);
+                return true;
+            });
+            JSONObject providerMetadata = new JSONObject();
+            providerMetadata.put("name", provider.getMetadata().getName());
+            providersMetadata.put(provider.getMetadata().getName(), providerMetadata);
+        }
+        List<Future<Boolean>> results = initPool.invokeAll(tasks);
+        for (Future<Boolean> result : results) {
+            if (!result.get()) {
+                throw new GeneralError("init failed");
+            }
+        }
+        metadataName = json.toString();
+    }
+
+    @Override
+    public Metadata getMetadata() {
+        return () -> metadataName;
+    }
+
+    @Override
+    public ProviderEvaluation<Boolean> getBooleanEvaluation(String key, Boolean defaultValue, EvaluationContext ctx) {
+        return strategy.evaluate(
+                providers, key, defaultValue, ctx, p -> p.getBooleanEvaluation(key, defaultValue, ctx));
+    }
+
+    @Override
+    public ProviderEvaluation<String> getStringEvaluation(String key, String defaultValue, EvaluationContext ctx) {
+        return strategy.evaluate(providers, key, defaultValue, ctx, p -> p.getStringEvaluation(key, defaultValue, ctx));
+    }
+
+    @Override
+    public ProviderEvaluation<Integer> getIntegerEvaluation(String key, Integer defaultValue, EvaluationContext ctx) {
+        return strategy.evaluate(
+                providers, key, defaultValue, ctx, p -> p.getIntegerEvaluation(key, defaultValue, ctx));
+    }
+
+    @Override
+    public ProviderEvaluation<Double> getDoubleEvaluation(String key, Double defaultValue, EvaluationContext ctx) {
+        return strategy.evaluate(providers, key, defaultValue, ctx, p -> p.getDoubleEvaluation(key, defaultValue, ctx));
+    }
+
+    @Override
+    public ProviderEvaluation<Value> getObjectEvaluation(String key, Value defaultValue, EvaluationContext ctx) {
+        return strategy.evaluate(providers, key, defaultValue, ctx, p -> p.getObjectEvaluation(key, defaultValue, ctx));
+    }
+
+    @Override
+    public void shutdown() {
+        log.debug("shutdown begin");
+        for (FeatureProvider provider : providers.values()) {
+            try {
+                provider.shutdown();
+            } catch (Exception e) {
+                log.error("error shutdown provider {}", provider.getMetadata().getName(), e);
+            }
+        }
+        log.debug("shutdown end");
+    }
+}

src/main/java/dev/openfeature/sdk/multiprovider/Strategy.java

@@ -0,0 +1,17 @@
+package dev.openfeature.sdk.multiprovider;
+
+import dev.openfeature.sdk.EvaluationContext;
+import dev.openfeature.sdk.FeatureProvider;
+import dev.openfeature.sdk.ProviderEvaluation;
+import java.util.Map;
+import java.util.function.Function;
+
+/** strategy. */
+public interface Strategy {
+    <T> ProviderEvaluation<T> evaluate(
+            Map<String, FeatureProvider> providers,
+            String key,
+            T defaultValue,
+            EvaluationContext ctx,
+            Function<FeatureProvider, ProviderEvaluation<T>> providerFunction);
+}