Skip to content

Commit 60260d8

Browse files
jonathannorrisjonathannorris
committed
feat: copy over multi-provider README's
Signed-off-by: Jonathan Norris <[email protected]>
1 parent f6f4313 commit 60260d8

File tree

2 files changed

+384
-0
lines changed
  • packages

2 files changed

+384
-0
lines changed

‎packages/server/src/provider/multi-provider/README.md‎

Lines changed: 185 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,185 @@
1+
# OpenFeature Multi-Provider
2+
3+
The Multi-Provider allows you to use multiple underlying providers as sources of flag data for the OpenFeature server SDK.
4+
When a flag is being evaluated, the Multi-Provider will consult each underlying provider it is managing in order to determine
5+
the final result. Different evaluation strategies can be defined to control which providers get evaluated and which result is used.
6+
7+
The Multi-Provider is a powerful tool for performing migrations between flag providers, or combining multiple providers into a single
8+
feature flagging interface. For example:
9+
10+
- *Migration*: When migrating between two providers, you can run both in parallel under a unified flagging interface. As flags are added to the
11+
new provider, the Multi-Provider will automatically find and return them, falling back to the old provider if the new provider does not have
12+
- *Multiple Data Sources*: The Multi-Provider allows you to seamlessly combine many sources of flagging data, such as environment variables,
13+
local files, database values and SaaS hosted feature management systems.
14+
15+
## Usage
16+
17+
The Multi-Provider is initialized with an array of providers it should evaluate:
18+
19+
```typescript
20+
import { MultiProvider } from '@openfeature/server-sdk'
21+
import { OpenFeature } from '@openfeature/server-sdk'
22+
23+
const multiProvider = new MultiProvider([
24+
{ provider: new ProviderA() },
25+
{ provider: new ProviderB() }
26+
])
27+
28+
await OpenFeature.setProviderAndWait(multiProvider)
29+
30+
const client = OpenFeature.getClient()
31+
32+
console.log("Evaluating flag")
33+
console.log(await client.getBooleanDetails("my-flag", false));
34+
```
35+
36+
By default, the Multi-Provider will evaluate all underlying providers in order and return the first successful result. If a provider indicates
37+
it does not have a flag (FLAG_NOT_FOUND error code), then it will be skipped and the next provider will be evaluated. If any provider throws
38+
or returns an error result, the operation will fail and the error will be thrown. If no provider returns a successful result, the operation
39+
will fail with a FLAG_NOT_FOUND error code.
40+
41+
To change this behaviour, a different "strategy" can be provided:
42+
43+
```typescript
44+
import { MultiProvider, FirstSuccessfulStrategy } from '@openfeature/server-sdk'
45+
46+
const multiProvider = new MultiProvider(
47+
[
48+
{ provider: new ProviderA() },
49+
{ provider: new ProviderB() }
50+
],
51+
new FirstSuccessfulStrategy()
52+
)
53+
```
54+
55+
## Strategies
56+
57+
The Multi-Provider comes with three strategies out of the box:
58+
59+
- `FirstMatchStrategy` (default): Evaluates all providers in order and returns the first successful result. Providers that indicate FLAG_NOT_FOUND error will be skipped and the next provider will be evaluated. Any other error will cause the operation to fail and the set of errors to be thrown.
60+
- `FirstSuccessfulStrategy`: Evaluates all providers in order and returns the first successful result. Any error will cause that provider to be skipped.
61+
If no successful result is returned, the set of errors will be thrown.
62+
- `ComparisonStrategy`: Evaluates all providers in parallel. If every provider returns a successful result with the same value, then that result is returned.
63+
Otherwise, the result returned by the configured "fallback provider" will be used. When values do not agree, an optional callback will be executed to notify
64+
you of the mismatch. This can be useful when migrating between providers that are expected to contain identical configuration. You can easily spot mismatches
65+
in configuration without affecting flag behaviour.
66+
67+
This strategy accepts several arguments during initialization:
68+
69+
```typescript
70+
import { MultiProvider, ComparisonStrategy } from '@openfeature/server-sdk'
71+
72+
const providerA = new ProviderA()
73+
const multiProvider = new MultiProvider(
74+
[
75+
{ provider: providerA },
76+
{ provider: new ProviderB() }
77+
],
78+
new ComparisonStrategy(providerA, (details) => {
79+
console.log("Mismatch detected", details)
80+
})
81+
)
82+
```
83+
84+
The first argument is the "fallback provider" whose value to use in the event that providers do not agree. It should be the same object reference as one of the providers in the list. The second argument is a callback function that will be executed when a mismatch is detected. The callback will be passed an object containing the details of each provider's resolution, including the flag key, the value returned, and any errors that were thrown.
85+
86+
## Tracking Support
87+
88+
The Multi-Provider supports tracking events across multiple providers. When you call the `track` method, it will by default send the tracking event to all underlying providers that implement the `track` method.
89+
90+
```typescript
91+
import { OpenFeature } from '@openfeature/server-sdk'
92+
import { MultiProvider } from '@openfeature/server-sdk'
93+
94+
const multiProvider = new MultiProvider([
95+
{ provider: new ProviderA() },
96+
{ provider: new ProviderB() }
97+
])
98+
99+
await OpenFeature.setProviderAndWait(multiProvider)
100+
const client = OpenFeature.getClient()
101+
102+
// Tracked events will be sent to all providers by default
103+
client.track('purchase', { targetingKey: 'user123' }, { value: 99.99, currency: 'USD' })
104+
```
105+
106+
### Tracking Behavior
107+
108+
- **Default**: All providers receive tracking calls by default
109+
- **Error Handling**: If one provider fails to track, others continue normally and errors are logged
110+
- **Provider Status**: Providers in `NOT_READY` or `FATAL` status are automatically skipped
111+
- **Optional Method**: Providers without a `track` method are gracefully skipped
112+
113+
### Customizing Tracking with Strategies
114+
115+
You can customize which providers receive tracking calls by overriding the `shouldTrackWithThisProvider` method in your custom strategy:
116+
117+
```typescript
118+
import { BaseEvaluationStrategy, StrategyPerProviderContext } from '@openfeature/server-sdk'
119+
120+
class CustomTrackingStrategy extends BaseEvaluationStrategy {
121+
shouldTrackWithThisProvider(
122+
strategyContext: StrategyPerProviderContext,
123+
context: EvaluationContext,
124+
trackingEventName: string,
125+
trackingEventDetails: TrackingEventDetails,
126+
): boolean {
127+
// Only track with the primary provider
128+
if (strategyContext.providerName === 'primary-provider') {
129+
return true;
130+
}
131+
132+
// Skip tracking for analytics events on backup providers
133+
if (trackingEventName.startsWith('analytics.')) {
134+
return false;
135+
}
136+
137+
return super.shouldTrackWithThisProvider(strategyContext, context, trackingEventName, trackingEventDetails);
138+
}
139+
}
140+
```
141+
142+
## Custom Strategies
143+
144+
It is also possible to implement your own strategy if the above options do not fit your use case. To do so, create a class which implements the "BaseEvaluationStrategy":
145+
146+
```typescript
147+
export abstract class BaseEvaluationStrategy {
148+
public runMode: 'parallel' | 'sequential' = 'sequential';
149+
150+
abstract shouldEvaluateThisProvider(strategyContext: StrategyPerProviderContext, evalContext: EvaluationContext): boolean;
151+
152+
abstract shouldEvaluateNextProvider<T extends FlagValue>(
153+
strategyContext: StrategyPerProviderContext,
154+
context: EvaluationContext,
155+
result: ProviderResolutionResult<T>,
156+
): boolean;
157+
158+
abstract shouldTrackWithThisProvider(
159+
strategyContext: StrategyPerProviderContext,
160+
context: EvaluationContext,
161+
trackingEventName: string,
162+
trackingEventDetails: TrackingEventDetails,
163+
): boolean;
164+
165+
abstract determineFinalResult<T extends FlagValue>(
166+
strategyContext: StrategyEvaluationContext,
167+
context: EvaluationContext,
168+
resolutions: ProviderResolutionResult<T>[],
169+
): FinalResult<T>;
170+
}
171+
```
172+
173+
The `runMode` property determines whether the list of providers will be evaluated sequentially or in parallel.
174+
175+
The `shouldEvaluateThisProvider` method is called just before a provider is evaluated by the Multi-Provider. If the function returns `false`, then
176+
the provider will be skipped instead of being evaluated. The function is called with details about the evaluation including the flag key and type.
177+
Check the type definitions for the full list.
178+
179+
The `shouldEvaluateNextProvider` function is called after a provider is evaluated. If it returns `true`, the next provider in the sequence will be called,
180+
otherwise no more providers will be evaluated. It is called with the same data as `shouldEvaluateThisProvider` as well as the details about the evaluation result. This function is not called when the `runMode` is `parallel`.
181+
182+
The `shouldTrackWithThisProvider` method is called before sending a tracking event to each provider. Return `false` to skip tracking with that provider. By default, it only tracks with providers that are in a ready state (not `NOT_READY` or `FATAL`). Override this method to implement custom tracking logic based on the tracking event name, details, or provider characteristics.
183+
184+
The `determineFinalResult` function is called after all providers have been called, or the `shouldEvaluateNextProvider` function returned false. It is called
185+
with a list of results from all the individual providers' evaluations. It returns the final decision for evaluation result, or throws an error if needed.

‎packages/web/src/provider/multi-provider/README.md‎

Lines changed: 199 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,199 @@
1+
# OpenFeature Multi-Provider
2+
3+
The Multi-Provider allows you to use multiple underlying providers as sources of flag data for the OpenFeature web SDK.
4+
When a flag is being evaluated, the Multi-Provider will consult each underlying provider it is managing in order to determine
5+
the final result. Different evaluation strategies can be defined to control which providers get evaluated and which result is used.
6+
7+
The Multi-Provider is a powerful tool for performing migrations between flag providers, or combining multiple providers into a single
8+
feature flagging interface. For example:
9+
10+
- *Migration*: When migrating between two providers, you can run both in parallel under a unified flagging interface. As flags are added to the
11+
new provider, the Multi-Provider will automatically find and return them, falling back to the old provider if the new provider does not have
12+
- *Multiple Data Sources*: The Multi-Provider allows you to seamlessly combine many sources of flagging data, such as environment variables,
13+
local files, database values and SaaS hosted feature management systems.
14+
15+
## Usage
16+
17+
The Multi-Provider is initialized with an array of providers it should evaluate:
18+
19+
```typescript
20+
import { WebMultiProvider } from '@openfeature/web-sdk'
21+
import { OpenFeature } from '@openfeature/web-sdk'
22+
23+
const multiProvider = new WebMultiProvider([
24+
{ provider: new ProviderA() },
25+
{ provider: new ProviderB() }
26+
])
27+
28+
await OpenFeature.setProviderAndWait(multiProvider)
29+
30+
const client = OpenFeature.getClient()
31+
32+
console.log("Evaluating flag")
33+
console.log(client.getBooleanDetails("my-flag", false));
34+
```
35+
36+
By default, the Multi-Provider will evaluate all underlying providers in order and return the first successful result. If a provider indicates
37+
it does not have a flag (FLAG_NOT_FOUND error code), then it will be skipped and the next provider will be evaluated. If any provider throws
38+
or returns an error result, the operation will fail and the error will be thrown. If no provider returns a successful result, the operation
39+
will fail with a FLAG_NOT_FOUND error code.
40+
41+
To change this behaviour, a different "strategy" can be provided:
42+
43+
```typescript
44+
import { WebMultiProvider, FirstSuccessfulStrategy } from '@openfeature/web-sdk'
45+
46+
const multiProvider = new WebMultiProvider(
47+
[
48+
{ provider: new ProviderA() },
49+
{ provider: new ProviderB() }
50+
],
51+
new FirstSuccessfulStrategy()
52+
)
53+
```
54+
55+
## Strategies
56+
57+
The Multi-Provider comes with three strategies out of the box:
58+
59+
- `FirstMatchStrategy` (default): Evaluates all providers in order and returns the first successful result. Providers that indicate FLAG_NOT_FOUND error will be skipped and the next provider will be evaluated. Any other error will cause the operation to fail and the set of errors to be thrown.
60+
- `FirstSuccessfulStrategy`: Evaluates all providers in order and returns the first successful result. Any error will cause that provider to be skipped.
61+
If no successful result is returned, the set of errors will be thrown.
62+
- `ComparisonStrategy`: Evaluates all providers in parallel. If every provider returns a successful result with the same value, then that result is returned.
63+
Otherwise, the result returned by the configured "fallback provider" will be used. When values do not agree, an optional callback will be executed to notify
64+
you of the mismatch. This can be useful when migrating between providers that are expected to contain identical configuration. You can easily spot mismatches
65+
in configuration without affecting flag behaviour.
66+
67+
This strategy accepts several arguments during initialization:
68+
69+
```typescript
70+
import { WebMultiProvider, ComparisonStrategy } from '@openfeature/web-sdk'
71+
72+
const providerA = new ProviderA()
73+
const multiProvider = new WebMultiProvider(
74+
[
75+
{ provider: providerA },
76+
{ provider: new ProviderB() }
77+
],
78+
new ComparisonStrategy(providerA, (details) => {
79+
console.log("Mismatch detected", details)
80+
})
81+
)
82+
```
83+
84+
The first argument is the "fallback provider" whose value to use in the event that providers do not agree. It should be the same object reference as one of the providers in the list. The second argument is a callback function that will be executed when a mismatch is detected. The callback will be passed an object containing the details of each provider's resolution, including the flag key, the value returned, and any errors that were thrown.
85+
86+
## Custom Strategies
87+
88+
It is also possible to implement your own strategy if the above options do not fit your use case. To do so, create a class which implements the "BaseEvaluationStrategy":
89+
90+
```typescript
91+
export abstract class BaseEvaluationStrategy {
92+
public runMode: 'parallel' | 'sequential' = 'sequential';
93+
94+
abstract shouldEvaluateThisProvider(strategyContext: StrategyPerProviderContext, evalContext: EvaluationContext): boolean;
95+
96+
abstract shouldEvaluateNextProvider<T extends FlagValue>(
97+
strategyContext: StrategyPerProviderContext,
98+
context: EvaluationContext,
99+
result: ProviderResolutionResult<T>,
100+
): boolean;
101+
102+
abstract shouldTrackWithThisProvider(
103+
strategyContext: StrategyProviderContext,
104+
context: EvaluationContext,
105+
trackingEventName: string,
106+
trackingEventDetails: TrackingEventDetails,
107+
): boolean;
108+
109+
abstract determineFinalResult<T extends FlagValue>(
110+
strategyContext: StrategyEvaluationContext,
111+
context: EvaluationContext,
112+
resolutions: ProviderResolutionResult<T>[],
113+
): FinalResult<T>;
114+
}
115+
```
116+
117+
The `runMode` property determines whether the list of providers will be evaluated sequentially or in parallel.
118+
119+
The `shouldEvaluateThisProvider` method is called just before a provider is evaluated by the Multi-Provider. If the function returns `false`, then
120+
the provider will be skipped instead of being evaluated. The function is called with details about the evaluation including the flag key and type.
121+
Check the type definitions for the full list.
122+
123+
The `shouldEvaluateNextProvider` function is called after a provider is evaluated. If it returns `true`, the next provider in the sequence will be called,
124+
otherwise no more providers will be evaluated. It is called with the same data as `shouldEvaluateThisProvider` as well as the details about the evaluation result. This function is not called when the `runMode` is `parallel`.
125+
126+
The `shouldTrackWithThisProvider` method is called before tracking an event with each provider. If the function returns `false`, then
127+
the provider will be skipped for that tracking event. The method includes the tracking event name and details,
128+
allowing for fine-grained control over which providers receive which events. By default, providers in `NOT_READY` or `FATAL` status are skipped.
129+
130+
The `determineFinalResult` function is called after all providers have been called, or the `shouldEvaluateNextProvider` function returned false. It is called
131+
with a list of results from all the individual providers' evaluations. It returns the final decision for evaluation result, or throws an error if needed.
132+
133+
## Tracking Support
134+
135+
The Multi-Provider supports tracking events across multiple providers, allowing you to send analytics events to all configured providers simultaneously.
136+
137+
### Basic Tracking Usage
138+
139+
```typescript
140+
import { WebMultiProvider } from '@openfeature/web-sdk'
141+
import { OpenFeature } from '@openfeature/web-sdk'
142+
143+
const multiProvider = new WebMultiProvider([
144+
{ provider: new ProviderA() },
145+
{ provider: new ProviderB() }
146+
])
147+
148+
await OpenFeature.setProviderAndWait(multiProvider)
149+
const client = OpenFeature.getClient()
150+
151+
// Tracked events will be sent to all providers by default
152+
client.track('user-conversion', {
153+
value: 99.99,
154+
currency: 'USD',
155+
conversionType: 'purchase'
156+
})
157+
158+
client.track('page-view', {
159+
page: '/checkout',
160+
source: 'direct'
161+
})
162+
```
163+
164+
### Tracking Behavior
165+
166+
- **Default**: All providers receive tracking calls by default
167+
- **Error Handling**: If one provider fails to track, others continue normally and errors are logged
168+
- **Provider Status**: Providers in `NOT_READY` or `FATAL` status are automatically skipped
169+
- **Optional Method**: Providers without a `track` method are gracefully skipped
170+
171+
### Customizing Tracking with Strategies
172+
173+
You can customize which providers receive tracking calls by overriding the `shouldTrackWithThisProvider` method in your custom strategy:
174+
175+
```typescript
176+
import { BaseEvaluationStrategy, StrategyProviderContext } from '@openfeature/web-sdk'
177+
178+
class CustomTrackingStrategy extends BaseEvaluationStrategy {
179+
// Override tracking behavior
180+
shouldTrackWithThisProvider(
181+
strategyContext: StrategyProviderContext,
182+
context: EvaluationContext,
183+
trackingEventName: string,
184+
trackingEventDetails: TrackingEventDetails,
185+
): boolean {
186+
// Only track with the primary provider
187+
if (strategyContext.providerName === 'primary-provider') {
188+
return true;
189+
}
190+
191+
// Skip tracking for analytics events on backup providers
192+
if (trackingEventName.startsWith('analytics.')) {
193+
return false;
194+
}
195+
196+
return super.shouldTrackWithThisProvider(strategyContext, context, trackingEventName, trackingEventDetails);
197+
}
198+
}
199+
```

0 commit comments

Comments
 (0)