-
Notifications
You must be signed in to change notification settings - Fork 8
feat: Multi provider impl #168
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
Show all changes
25 commits
Select commit
Hold shift + click to select a range
af65a59
Multi provider impl draft
PenguinDan 79f59ba
Ktlint
PenguinDan 6127d68
Try emit initial state for Multi provider
PenguinDan 2142879
Shared flow should always have content
PenguinDan c6f3a8f
Add tests
PenguinDan f2f415a
Update multi provider strategy to better align with Open Feature specs
PenguinDan 199236c
Add original metadata and allow all providers to shutdown
PenguinDan 38fac8c
Add default reason to default value in First Match Strategy
PenguinDan 48033c5
Remove json dependency and update ProviderMetadata
PenguinDan 4fa33eb
Align to Event spec
PenguinDan d5f5546
Ktlint
PenguinDan 8d8cbec
Update API dumps for multiprovider and ProviderMetadata changes
PenguinDan 3818a11
Use Lazy and ktlint
PenguinDan f834a43
Add TODO once EventDetails have been added
PenguinDan c299717
PR comments; remove redundant comments, fix test definitions, move st…
PenguinDan 2305056
Return an error result for FirstSuccessfulStrategy rather than throwing
PenguinDan 70a892d
Revert sample app changes
PenguinDan 6fe18eb
Add README documentation for Multiprovider
PenguinDan 870ae07
Lets favor not throwing in the FirstMatchStrategy also
PenguinDan 5472c08
Update tests to represent to non-throwing pattern and api dump
PenguinDan 7df6772
Kotlin Format
PenguinDan 2cc75c5
Update kotlin-sdk/src/commonMain/kotlin/dev/openfeature/kotlin/sdk/mu…
PenguinDan e71d448
Update multi provider readme
PenguinDan c4c49db
Merge branch 'main' into MultiProvider-Impl
PenguinDan f540783
API dump
PenguinDan File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,126 @@ | ||
| ## MultiProvider (OpenFeature Kotlin SDK) | ||
|
|
||
| Combine multiple `FeatureProvider`s into a single provider with deterministic ordering, pluggable evaluation strategies, and unified status/event handling. | ||
|
|
||
| ### Why use MultiProvider? | ||
| - **Layer providers**: fall back from an in-memory or experiment provider to a remote provider. | ||
| - **Migrate safely**: put the new provider first, retain the old as fallback. | ||
| - **Handle errors predictably**: choose whether errors should short-circuit or be skipped. | ||
|
|
||
| This implementation is adapted for Kotlin coroutines, flows, and OpenFeature error types. | ||
|
|
||
| ### Quick start | ||
| ```kotlin | ||
| import dev.openfeature.kotlin.sdk.OpenFeatureAPI | ||
| import dev.openfeature.kotlin.sdk.multiprovider.MultiProvider | ||
| import dev.openfeature.kotlin.sdk.multiprovider.FirstMatchStrategy | ||
| // import dev.openfeature.kotlin.sdk.multiprovider.FirstSuccessfulStrategy | ||
|
|
||
| // 1) Construct your providers (examples) | ||
| val experiments = MyExperimentProvider() // e.g., local overrides/experiments | ||
| val remote = MyRemoteProvider() // e.g., network-backed | ||
|
|
||
| // 2) Wrap them with MultiProvider in the desired order | ||
| val multi = MultiProvider( | ||
| providers = listOf(experiments, remote), | ||
| strategy = FirstMatchStrategy() // default; FirstSuccessfulStrategy() also available | ||
| ) | ||
|
|
||
| // 3) Set the SDK provider and wait until ready | ||
| OpenFeatureAPI.setProviderAndWait() | ||
|
|
||
| // 4) Use the client as usual | ||
| val client = OpenFeatureAPI.getClient("my-app") | ||
| val enabled = client.getBooleanValue("new-ui", defaultValue = false) | ||
| ``` | ||
|
|
||
| ### How it works (at a glance) | ||
| - The `MultiProvider` delegates each evaluation to its child providers in the order you supply. | ||
| - A pluggable `Strategy` decides which child result to return. | ||
| - Provider events are observed and converted into a single aggregate SDK status. | ||
| - Context changes are forwarded to all children concurrently. | ||
|
|
||
| ### Strategies | ||
|
|
||
| - **FirstMatchStrategy (default)** | ||
| - Returns the first child result that is not "flag not found". | ||
| - If a child returns an error other than `FLAG_NOT_FOUND`, that error is returned immediately. | ||
| - If all children report `FLAG_NOT_FOUND`, the default value is returned with reason `DEFAULT`. | ||
|
|
||
| - **FirstSuccessfulStrategy** | ||
| - Skips over errors from children and continues to the next provider. | ||
| - Returns the first successful evaluation (no error code). | ||
| - If no provider succeeds, the default value is returned with `FLAG_NOT_FOUND`. | ||
|
|
||
| Pick the strategy that best matches your failure-policy: | ||
| - Prefer early, explicit error surfacing: use `FirstMatchStrategy`. | ||
| - Prefer resilience and best-effort success: use `FirstSuccessfulStrategy`. | ||
|
|
||
| ### Evaluation order matters | ||
| Children are evaluated in the order provided. Put the most authoritative or fastest provider first. For example, place a small in-memory override provider before a remote provider to reduce latency. | ||
|
|
||
| ### Events and status aggregation | ||
| `MultiProvider` listens to child provider events and emits a single, aggregate status via `OpenFeatureAPI.statusFlow`. The highest-precedence status among children wins: | ||
|
|
||
| 1. Fatal | ||
| 2. NotReady | ||
| 3. Error | ||
| 4. Reconciling / Stale | ||
| 5. Ready | ||
|
|
||
| `ProviderConfigurationChanged` is re-emitted as-is. When the aggregate status changes due to a child event, the original triggering event is also emitted. | ||
|
|
||
| ### Context propagation | ||
| When the evaluation context changes, `MultiProvider` calls `onContextSet` on all child providers concurrently. Aggregate status transitions to Reconciling and then back to Ready (or Error) in line with SDK behavior. | ||
|
|
||
| ### Provider metadata | ||
| `MultiProvider.metadata` exposes: | ||
| - `name = "multiprovider"` | ||
| - `originalMetadata`: a map of child-name → child `ProviderMetadata` | ||
|
|
||
| Child names are derived from each provider’s `metadata.name`. If duplicates occur, stable suffixes are applied (e.g., `myProvider_1`, `myProvider_2`). | ||
|
|
||
| Example: inspect provider metadata | ||
| ```kotlin | ||
| val meta = OpenFeatureAPI.getProviderMetadata() | ||
| println(meta?.name) // "multiprovider" | ||
| println(meta?.originalMetadata) // map of child names to their metadata | ||
| ``` | ||
|
|
||
| ### Shutdown behavior | ||
| `shutdown()` is invoked on all children. If any child fails to shut down, an aggregated error is thrown that includes all individual failures. Resources should be released in child providers even if peers fail. | ||
|
|
||
| ### Custom strategies | ||
| You can provide your own composition policy by implementing `MultiProvider.Strategy`: | ||
| ```kotlin | ||
| import dev.openfeature.kotlin.sdk.* | ||
| import dev.openfeature.kotlin.sdk.multiprovider.MultiProvider | ||
|
|
||
| class MyStrategy : MultiProvider.Strategy { | ||
| override fun <T> evaluate( | ||
| providers: List<FeatureProvider>, | ||
| key: String, | ||
| defaultValue: T, | ||
| evaluationContext: EvaluationContext?, | ||
| flagEval: FeatureProvider.(String, T, EvaluationContext?) -> ProviderEvaluation<T> | ||
| ): ProviderEvaluation<T> { | ||
| // Example: try all, prefer the highest integer value (demo only) | ||
| var best: ProviderEvaluation<T>? = null | ||
| for (p in providers) { | ||
| val e = p.flagEval(key, defaultValue, evaluationContext) | ||
| // ... decide whether to keep e as best ... | ||
| best = best ?: e | ||
| } | ||
| return best ?: ProviderEvaluation(defaultValue) | ||
| } | ||
| } | ||
|
|
||
| val multi = MultiProvider(listOf(experiments, remote), strategy = MyStrategy()) | ||
| ``` | ||
|
|
||
| ### Notes and limitations | ||
| - Hooks on `MultiProvider` are currently not applied. | ||
| - Ensure each child’s `metadata.name` is set for clearer diagnostics in `originalMetadata`. | ||
|
|
||
|
|
||
|
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
33 changes: 33 additions & 0 deletions
33
kotlin-sdk/src/commonMain/kotlin/dev/openfeature/kotlin/sdk/ProviderMetadata.kt
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,5 +1,38 @@ | ||
| package dev.openfeature.kotlin.sdk | ||
|
|
||
| /** | ||
| * Provider metadata as defined by the OpenFeature specification. | ||
| * | ||
| * In a single provider, `name` identifies the provider. In a Multi-Provider, the outer provider | ||
| * exposes its own `name` and surfaces the metadata of its managed providers via `originalMetadata`, | ||
| * keyed by each provider's resolved unique name. | ||
| * | ||
| * See: https://openfeature.dev/specification/appendix-a/#metadata | ||
| */ | ||
| interface ProviderMetadata { | ||
| /** | ||
| * Human-readable provider name. | ||
| * | ||
| * - Used in logs, events, and error reporting. | ||
| * - In a Multi-Provider, names must be unique. | ||
| */ | ||
| val name: String? | ||
|
|
||
| /** | ||
| * For Multi-Provider: a map of child provider names to their metadata. | ||
| * | ||
| * - For normal providers this MUST be an empty map. | ||
| * - For the Multi-Provider, this contains each inner provider's `ProviderMetadata`, keyed by | ||
| * that provider's resolved unique name. | ||
| * | ||
| * Example shape: | ||
| * { | ||
| * "providerA": {...}, | ||
| * "providerB": {...} | ||
| * } | ||
| * | ||
| * See: https://openfeature.dev/specification/appendix-a/#metadata | ||
| */ | ||
| val originalMetadata: Map<String, ProviderMetadata> | ||
| get() = emptyMap() | ||
| } | ||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.