Merge branch 'main' into feat/ofrep-provider

Author: EtaCassiopeia

core/src/main/scala/zio/openfeature/MultiProviderStrategy.scala

@@ -0,0 +1,25 @@
+package zio.openfeature
+
+import dev.openfeature.sdk.multiprovider.{FirstMatchStrategy, FirstSuccessfulStrategy}
+
+/** Built-in strategies for [[FeatureFlags.fromMultiProvider]] and [[FeatureFlags.fromMultiProviderAsync]].
+  *
+  * Re-exports the Java SDK's strategy implementations under stable Scala names so callers do not need to depend on the
+  * `dev.openfeature.sdk.multiprovider` package directly.
+  */
+object MultiProviderStrategy {
+
+  /** Alias for [[dev.openfeature.sdk.multiprovider.Strategy]]. */
+  type Strategy = dev.openfeature.sdk.multiprovider.Strategy
+
+  /** Returns the result of the first provider whose evaluation does not surface a default value. An evaluation error
+    * from any provider aborts the chain; use [[firstSuccessful]] if you want errors to fall through to the next
+    * provider. A fresh instance is returned each call to stay safe if the upstream class ever gains internal state.
+    */
+  def firstMatch: Strategy = new FirstMatchStrategy
+
+  /** Returns the result of the first provider whose evaluation completes without an error. Errors fall through to the
+    * next provider; default-reason results do not. A fresh instance is returned each call.
+    */
+  def firstSuccessful: Strategy = new FirstSuccessfulStrategy
+}

core/src/test/scala/zio/openfeature/MultiProviderStrategySpec.scala

@@ -0,0 +1,25 @@
+package zio.openfeature
+
+import dev.openfeature.sdk.multiprovider.{FirstMatchStrategy, FirstSuccessfulStrategy}
+import zio.test._
+
+object MultiProviderStrategySpec extends ZIOSpecDefault {
+
+  def spec = suite("MultiProviderStrategy")(
+    test("firstMatch alias resolves to FirstMatchStrategy") {
+      assertTrue(MultiProviderStrategy.firstMatch.isInstanceOf[FirstMatchStrategy])
+    },
+    test("firstSuccessful alias resolves to FirstSuccessfulStrategy") {
+      assertTrue(MultiProviderStrategy.firstSuccessful.isInstanceOf[FirstSuccessfulStrategy])
+    },
+    test("Strategy type alias is assignable to the Java SDK Strategy type (compile-time check)") {
+      // If the type alias were wrong, this assignment would not compile.
+      val _: dev.openfeature.sdk.multiprovider.Strategy = MultiProviderStrategy.firstMatch
+      assertCompletes
+    },
+    test("firstMatch and firstSuccessful return fresh instances on each call") {
+      assertTrue(MultiProviderStrategy.firstMatch ne MultiProviderStrategy.firstMatch) &&
+      assertTrue(MultiProviderStrategy.firstSuccessful ne MultiProviderStrategy.firstSuccessful)
+    }
+  )
+}

docs/extras.md

@@ -229,7 +229,7 @@ Adding `zio-openfeature-ofrep` pulls in Jackson (core/databind/jsr310), Guava, C
 
 ## Circuit Breaker Provider
 
-A decorator that wraps any provider with circuit breaker logic for fast failover. When the delegate provider fails repeatedly or becomes unhealthy, the circuit opens and evaluations fail immediately (< 1ms) — enabling instant fallback when composed with `MultiProvider` and `FirstSuccessfulStrategy`.
+A decorator that wraps any provider with circuit breaker logic for fast failover. When the delegate provider fails repeatedly or becomes unhealthy, the circuit opens and evaluations fail immediately (< 1ms) — enabling instant fallback when composed with `MultiProvider` and `MultiProviderStrategy.firstSuccessful`.
 
 ### When to use
 
@@ -256,7 +256,6 @@ The circuit breaker has three states:
 import zio.*
 import zio.openfeature.*
 import zio.openfeature.extras.*
-import dev.openfeature.sdk.multiprovider.FirstSuccessfulStrategy
 
 // Wrap the primary provider with circuit breaker
 val resilientProvider = CircuitBreakerProvider(
@@ -273,7 +272,7 @@ val resilientProvider = CircuitBreakerProvider(
 // Compose with fallback using MultiProvider
 val layer = FeatureFlags.fromMultiProvider(
   List(resilientProvider, EnvVarProvider()),
-  new FirstSuccessfulStrategy()
+  MultiProviderStrategy.firstSuccessful
 )
 ```
 
@@ -286,7 +285,7 @@ for
            ))
   layer = FeatureFlags.fromMultiProvider(
             List(cb, EnvVarProvider()),
-            new FirstSuccessfulStrategy()
+            MultiProviderStrategy.firstSuccessful
           )
 yield layer
 ```
@@ -315,7 +314,7 @@ Controls how the circuit breaker reacts when the delegate provider is in `STALE`
 
 | Approach | During outage | Failover latency |
 |:---------|:--------------|:-----------------|
-| `MultiProvider` + `FirstSuccessfulStrategy` alone | Tries primary every time, waits for failure | Up to minutes |
+| `MultiProvider` + `firstSuccessful` alone | Tries primary every time, waits for failure | Up to minutes |
 | Add timeout only (e.g., 50ms) | Still tries primary every time | 50ms per call |
 | **Circuit breaker** | Skips primary entirely when open | **< 1ms** |
 

docs/providers.md

@@ -446,7 +446,7 @@ val layer = FeatureFlags.fromProviderWithHooks(provider, hooks)
 
 ### fromMultiProvider
 
-Create from multiple providers using the SDK's MultiProvider support. The first provider that returns without error is used:
+Create from multiple providers using the SDK's MultiProvider support. By default this uses the first-match strategy — the first provider whose result is not a default value is returned (a provider error from any source aborts the chain):
 
 ```scala
 import dev.openfeature.sdk.FeatureProvider
@@ -458,17 +458,19 @@ val remoteProvider: FeatureProvider = // remote service
 val layer = FeatureFlags.fromMultiProvider(List(localProvider, remoteProvider))
 ```
 
-You can also supply a custom strategy:
+You can also supply a custom strategy. The two built-in strategies are exposed via `MultiProviderStrategy` so you don't need to import the Java SDK's multiprovider package directly:
 
 ```scala
-import dev.openfeature.sdk.multiprovider.FirstSuccessfulStrategy
+import zio.openfeature.MultiProviderStrategy
 
 val layer = FeatureFlags.fromMultiProvider(
   List(primaryProvider, fallbackProvider),
-  new FirstSuccessfulStrategy()
+  MultiProviderStrategy.firstSuccessful
 )
 ```
 
+`MultiProviderStrategy.firstMatch` and `MultiProviderStrategy.firstSuccessful` are the two built-ins. For a custom strategy, implement the `MultiProviderStrategy.Strategy` interface (an alias for the Java SDK's `Strategy`) and pass an instance the same way.
+
 ### Async Variants (Non-Blocking Initialization)
 
 Every factory method has an async counterpart that uses the Java SDK's non-blocking `setProvider` instead of `setProviderAndWait`. The provider initializes in the background; evaluations fail with `ProviderNotReady` until the provider is ready.