feat: copy multi-provider and multi-provider-web from contrib repo

Signed-off-by: Jonathan Norris <[email protected]>

Author: jonathannorris

package-lock.json

@@ -140,7 +140,85 @@ OpenFeature.setProvider(new MyProvider());
 Once the provider has been registered, the status can be tracked using [events](#eventing).
 
 In some situations, it may be beneficial to register multiple providers in the same application.
-This is possible using [domains](#domains), which is covered in more details below.
+This is possible using [domains](#domains), which is covered in more detail below.
+
+#### Multi-Provider
+
+The Multi-Provider allows you to use multiple underlying providers as sources of flag data for the OpenFeature server SDK. When a flag is being evaluated, the Multi-Provider will consult each underlying provider it is managing in order to determine the final result. Different evaluation strategies can be defined to control which providers get evaluated and which result is used.
+
+The Multi-Provider is a powerful tool for performing migrations between flag providers, or combining multiple providers into a single feature flagging interface. For example:
+
+- **Migration**: Gradually migrate from one provider to another by serving some flags from your old provider and some from your new provider
+- **Backup**: Use one provider as a backup for another in case of failures
+- **Comparison**: Compare results from multiple providers to validate consistency
+- **Hybrid**: Combine multiple providers to leverage different strengths (e.g., one for simple flags, another for complex targeting)
+
+```ts
+import { OpenFeature, MultiProvider, FirstMatchStrategy } from '@openfeature/server-sdk';
+
+// Create providers
+const primaryProvider = new YourPrimaryProvider();
+const backupProvider = new YourBackupProvider();
+
+// Create multi-provider with a strategy
+const multiProvider = new MultiProvider(
+  [primaryProvider, backupProvider],
+  new FirstMatchStrategy()
+);
+
+// Register the multi-provider
+await OpenFeature.setProviderAndWait(multiProvider);
+
+// Use as normal
+const client = OpenFeature.getClient();
+const value = await client.getBooleanValue('my-flag', false);
+```
+
+**Available Strategies:**
+
+- `FirstMatchStrategy`: Returns the first successful result from the list of providers
+- `ComparisonStrategy`: Compares results from multiple providers and can handle discrepancies
+
+**Migration Example:**
+
+```ts
+import { OpenFeature, MultiProvider, FirstMatchStrategy } from '@openfeature/server-sdk';
+
+// During migration, serve some flags from the new provider and fallback to the old one
+const newProvider = new NewFlagProvider();
+const oldProvider = new OldFlagProvider();
+
+const multiProvider = new MultiProvider(
+  [newProvider, oldProvider], // New provider is consulted first
+  new FirstMatchStrategy()
+);
+
+await OpenFeature.setProviderAndWait(multiProvider);
+```
+
+**Comparison Example:**
+
+```ts
+import { OpenFeature, MultiProvider, ComparisonStrategy } from '@openfeature/server-sdk';
+
+// Compare results from two providers for validation
+const providerA = new ProviderA();
+const providerB = new ProviderB();
+
+const comparisonStrategy = new ComparisonStrategy({
+  primary: 0, // Use first provider as primary
+  onMismatch: (flagKey, primaryResult, results) => {
+    console.warn(`Mismatch for ${flagKey}:`, primaryResult, results);
+  }
+});
+
+const multiProvider = new MultiProvider(
+  [providerA, providerB],
+  comparisonStrategy
+);
+
+await OpenFeature.setProviderAndWait(multiProvider);
+```
 
 ### Targeting
 

packages/server/README.md

@@ -1,3 +1,4 @@
 export * from './provider';
 export * from './no-op-provider';
 export * from './in-memory-provider';
+export * from './multi-provider';

packages/server/src/provider/index.ts

@@ -0,0 +1,53 @@
+import type { ErrorCode } from '@openfeature/server-sdk';
+import { GeneralError, OpenFeatureError } from '@openfeature/server-sdk';
+import type { RegisteredProvider } from './types';
+
+export class ErrorWithCode extends OpenFeatureError {
+  constructor(
+    public code: ErrorCode,
+    message: string,
+  ) {
+    super(message);
+  }
+}
+
+export class AggregateError extends GeneralError {
+  constructor(
+    message: string,
+    public originalErrors: { source: string; error: unknown }[],
+  ) {
+    super(message);
+  }
+}
+
+export const constructAggregateError = (providerErrors: { error: unknown; providerName: string }[]) => {
+  const errorsWithSource = providerErrors
+    .map(({ providerName, error }) => {
+      return { source: providerName, error };
+    })
+    .flat();
+
+  // log first error in the message for convenience, but include all errors in the error object for completeness
+  return new AggregateError(
+    `Provider errors occurred: ${errorsWithSource[0].source}: ${errorsWithSource[0].error}`,
+    errorsWithSource,
+  );
+};
+
+export const throwAggregateErrorFromPromiseResults = (
+  result: PromiseSettledResult<unknown>[],
+  providerEntries: RegisteredProvider[],
+) => {
+  const errors = result
+    .map((r, i) => {
+      if (r.status === 'rejected') {
+        return { error: r.reason, providerName: providerEntries[i].name };
+      }
+      return null;
+    })
+    .filter((val): val is { error: unknown; providerName: string } => Boolean(val));
+
+  if (errors.length) {
+    throw constructAggregateError(errors);
+  }
+};

packages/server/src/provider/multi-provider/errors.ts

@@ -0,0 +1,69 @@
+import type { EvaluationDetails, FlagValue, Hook, HookContext, HookHints, Logger } from '@openfeature/server-sdk';
+
+/**
+ * Utility for executing a set of hooks of each type. Implementation is largely copied from the main OpenFeature SDK.
+ */
+export class HookExecutor {
+  constructor(private logger: Logger) {}
+
+  async beforeHooks(hooks: Hook[] | undefined, hookContext: HookContext, hints: HookHints) {
+    for (const hook of hooks ?? []) {
+      // freeze the hookContext
+      Object.freeze(hookContext);
+
+      Object.assign(hookContext.context, {
+        ...(await hook?.before?.(hookContext, Object.freeze(hints))),
+      });
+    }
+
+    // after before hooks, freeze the EvaluationContext.
+    return Object.freeze(hookContext.context);
+  }
+
+  async afterHooks(
+    hooks: Hook[] | undefined,
+    hookContext: HookContext,
+    evaluationDetails: EvaluationDetails<FlagValue>,
+    hints: HookHints,
+  ) {
+    // run "after" hooks sequentially
+    for (const hook of hooks ?? []) {
+      await hook?.after?.(hookContext, evaluationDetails, hints);
+    }
+  }
+
+  async errorHooks(hooks: Hook[] | undefined, hookContext: HookContext, err: unknown, hints: HookHints) {
+    // run "error" hooks sequentially
+    for (const hook of hooks ?? []) {
+      try {
+        await hook?.error?.(hookContext, err, hints);
+      } catch (err) {
+        this.logger.error(`Unhandled error during 'error' hook: ${err}`);
+        if (err instanceof Error) {
+          this.logger.error(err.stack);
+        }
+        this.logger.error((err as Error)?.stack);
+      }
+    }
+  }
+
+  async finallyHooks(
+    hooks: Hook[] | undefined,
+    hookContext: HookContext,
+    evaluationDetails: EvaluationDetails<FlagValue>,
+    hints: HookHints,
+  ) {
+    // run "finally" hooks sequentially
+    for (const hook of hooks ?? []) {
+      try {
+        await hook?.finally?.(hookContext, evaluationDetails, hints);
+      } catch (err) {
+        this.logger.error(`Unhandled error during 'finally' hook: ${err}`);
+        if (err instanceof Error) {
+          this.logger.error(err.stack);
+        }
+        this.logger.error((err as Error)?.stack);
+      }
+    }
+  }
+}

packages/server/src/provider/multi-provider/hook-executor.ts

@@ -0,0 +1,3 @@
+export * from './multi-provider';
+export * from './errors';
+export * from './strategies';