@featbit/openfeature-provider-node-server 1.0.0

package/examples/console-app/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "openfeature-provider-node-server-demo",
+  "version": "1.0.0",
+  "description": "",
+  "type": "commonjs",
+  "scripts": {
+    "esm": "tsx src/esm.ts",
+    "cjs": "tsx src/commonjs.cjs"
+  },
+  "author": "",
+  "license": "ISC",
+  "dependencies": {
+    "@featbit/node-server-sdk": "file:../../../featbit-node-server-sdk",
+    "@featbit/openfeature-provider-node-server": "file:../../",
+    "@openfeature/server-sdk": "^1.7.5"
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.1",
+    "tsx": "^4.6.2"
+  }
+}

package/examples/console-app/src/commonjs.cjs

@@ -0,0 +1,30 @@
+const fb = require('@featbit/node-server-sdk');
+const { FbProvider } = require("@featbit/openfeature-provider-node-server");
+const { OpenFeature, ProviderEvents } = require("@openfeature/server-sdk");
+
+const provider = new FbProvider({ sdkKey: 'j-2pVwU1e0uNg8LR_u27KAL1n1amy42U2P2kDf5acCMA', streamingUri: 'ws://localhost:5100', eventsUri: 'http://localhost:5100' });
+OpenFeature.setProvider(provider);
+
+// If you need access to the FbClient, then you can use provider.getClient()
+
+// Evaluations before the provider indicates it is ready may get default values with a
+// CLIENT_NOT_READY reason.
+OpenFeature.addHandler(ProviderEvents.Ready, (eventDetails) => {
+    console.log(`Changed ${eventDetails.flagsChanged}`);
+});
+
+
+// The FeatBit provider supports the ProviderEvents.ConfigurationChanged event.
+// The provider will emit this event for any flag key that may have changed (each event will contain
+// a single key in the `flagsChanged` field).
+OpenFeature.addHandler(ProviderEvents.ConfigurationChanged, async (eventDetails) => {
+    const client = OpenFeature.getClient();
+    const value = await client.getBooleanValue('ff1', false, {targetingKey: 'my-key'});
+    console.log({...eventDetails, value});
+});
+
+// (async () => {
+//     // When the FeatBit provider is closed it will flush the events on the FbClient instance.
+//     // This can be useful for short lived processes.
+//     await OpenFeature.close();
+// })();

package/examples/console-app/src/esm.ts

@@ -0,0 +1,34 @@
+import { OpenFeature, ProviderEvents } from '@openfeature/server-sdk';
+import { FbProvider } from '@featbit/openfeature-provider-node-server';
+
+const provider = new FbProvider({
+  sdkKey: 'j-2pVwU1e0uNg8LR_u27KAL1n1amy42U2P2kDf5acCMA',
+  streamingUri: 'ws://localhost:5100',
+  eventsUri: 'http://localhost:5100'
+});
+
+OpenFeature.setProvider(provider);
+
+// If you need access to the FbClient, then you can use provider.getClient()
+
+// Evaluations before the provider indicates it is ready may get default values with a
+// CLIENT_NOT_READY reason.
+OpenFeature.addHandler(ProviderEvents.Ready, (eventDetails) => {
+  console.log(`Changed ${eventDetails.flagsChanged}`);
+});
+
+
+// The FeatBit provider supports the ProviderEvents.ConfigurationChanged event.
+// The provider will emit this event for any flag key that may have changed (each event will contain
+// a single key in the `flagsChanged` field).
+OpenFeature.addHandler(ProviderEvents.ConfigurationChanged, async (eventDetails) => {
+  const client = OpenFeature.getClient();
+  const value = await client.getBooleanValue('ff1', false, {targetingKey: 'my-key'});
+  console.log({...eventDetails, value});
+});
+
+// (async () => {
+//   // When the FeatBit provider is closed it will flush the events on the FbClient instance.
+//   // This can be useful for short lived processes.
+//   await OpenFeature.close();
+// })();

package/jest.config.js

@@ -0,0 +1,7 @@
+module.exports = {
+  transform: { '^.+\\.ts?$': 'ts-jest' },
+  testMatch: ['**/*.test.ts?(x)'],
+  testEnvironment: 'node',
+  moduleFileExtensions: ['ts', 'js'],
+  collectCoverageFrom: ['src/**/*.ts']
+};

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@featbit/openfeature-provider-node-server",
+  "version": "1.0.0",
+  "description": "A OpenFeature provider implementation for the FeatBit node SDK",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "rimraf dist && tsc --build",
+    "test": "npx jest --ci",
+    "prepublishOnly": "npm run build"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/featbit/openfeature-provider-node-server.git"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "bugs": {
+    "url": "https://github.com/featbit/openfeature-provider-node-server/issues"
+  },
+  "homepage": "https://github.com/featbit/openfeature-provider-node-server#readme",
+  "peerDependencies": {
+    "@featbit/node-server-sdk": "^1.0.0",
+    "@openfeature/server-sdk": "^1.9.0"
+  },
+  "devDependencies": {
+    "@featbit/node-server-sdk": "^1.0.0",
+    "@openfeature/server-sdk": "^1.9.0",
+    "@types/jest": "^29.5.11",
+    "jest": "^29.7.0",
+    "rimraf": "^5.0.5",
+    "ts-jest": "^29.1.1",
+    "typescript": "^5.3.3"
+  }
+}

package/src/FbProvider.ts

@@ -0,0 +1,203 @@
+import {
+  EvaluationContext,
+  Hook,
+  JsonValue,
+  OpenFeatureEventEmitter,
+  Provider,
+  ProviderEvents,
+  ProviderStatus,
+  ResolutionDetails,
+} from "@openfeature/server-sdk";
+import {
+  BasicLogger,
+  FbClientBuilder,
+  ILogger,
+  IFbClient,
+  IOptions
+} from "@featbit/node-server-sdk";
+import SafeLogger from "./SafeLogger";
+import { translateContext } from "./translateContext";
+import { translateResult } from "./translateResult";
+
+
+/**
+ * An OpenFeature provider for the FeatBit SDK for node.
+ */
+export class FbProvider implements Provider {
+  metadata = {
+    name: 'featbit-node-provider',
+  };
+
+  private readonly logger: ILogger;
+  private readonly client: IFbClient;
+  private readonly clientConstructionError: any;
+  private innerStatus: ProviderStatus = ProviderStatus.NOT_READY;
+
+  public readonly events = new OpenFeatureEventEmitter();
+
+  /**
+   * Construct a {@link FbProvider}.
+   * @param options The {@link IOptions} to initialize the FeatBit client instance.
+   */
+  constructor(options: IOptions) {
+    if (options.logger) {
+      this.logger = new SafeLogger(options.logger, new BasicLogger({level: 'info'}));
+    } else {
+      this.logger = new BasicLogger({level: 'info'});
+    }
+
+    try {
+      this.client = new FbClientBuilder(options).build();
+      this.client.on('update', ({key}: {
+        key: string
+      }) => this.events.emit(ProviderEvents.ConfigurationChanged, {flagsChanged: [key]}))
+    } catch (err) {
+      this.clientConstructionError = err;
+      this.logger.error(`Encountered unrecoverable initialization error, ${ err }`);
+      this.innerStatus = ProviderStatus.ERROR;
+    }
+  }
+
+  async initialize(context?: EvaluationContext): Promise<void> {
+    if (!this.client) {
+      // The client could not be constructed.
+      if (this.clientConstructionError) {
+        throw this.clientConstructionError;
+      }
+      throw new Error('Unknown problem encountered during initialization');
+    }
+    try {
+      await this.client.waitForInitialization();
+      this.innerStatus = ProviderStatus.READY;
+    } catch (e) {
+      this.innerStatus = ProviderStatus.ERROR;
+      throw e;
+    }
+  }
+
+  /**
+   * Determines the boolean variation of a feature flag for a context, along with information about
+   * how it was calculated.
+   *
+   * If the flag does not evaluate to a boolean value, then the defaultValue will be returned.
+   *
+   * @param flagKey The unique key of the feature flag.
+   * @param defaultValue The default value of the flag, to be used if the value is not available
+   *   from FeatBit.
+   * @param context The context requesting the flag.
+   * @returns A promise which will resolve to a ResolutionDetails.
+   */
+  async resolveBooleanEvaluation(
+    flagKey: string,
+    defaultValue: boolean,
+    context: EvaluationContext
+  ): Promise<ResolutionDetails<boolean>> {
+    const res = await this.client.boolVariationDetail(
+      flagKey,
+      translateContext(this.logger, context),
+      defaultValue,
+    );
+
+    return Promise.resolve(translateResult(res));
+  }
+
+  /**
+   * Determines the string variation of a feature flag for a context, along with information about
+   * how it was calculated.
+   *
+   * If the flag does not evaluate to a string value, then the defaultValue will be returned.
+   *
+   * @param flagKey The unique key of the feature flag.
+   * @param defaultValue The default value of the flag, to be used if the value is not available
+   *   from FeatBit.
+   * @param context The context requesting the flag.
+   * @returns A promise which will resolve to a ResolutionDetails.
+   */
+  async resolveStringEvaluation(
+    flagKey: string,
+    defaultValue: string,
+    context: EvaluationContext
+  ): Promise<ResolutionDetails<string>> {
+    const res = await this.client.stringVariationDetail(
+      flagKey,
+      translateContext(this.logger, context),
+      defaultValue,
+    );
+
+    return Promise.resolve(translateResult(res));
+  }
+
+  /**
+   * Determines the numeric variation of a feature flag for a context, along with information about
+   * how it was calculated.
+   *
+   * If the flag does not evaluate to a numeric value, then the defaultValue will be returned.
+   *
+   * @param flagKey The unique key of the feature flag.
+   * @param defaultValue The default value of the flag, to be used if the value is not available
+   *   from FeatBit.
+   * @param context The context requesting the flag.
+   * @returns A promise which will resolve to a ResolutionDetails.
+   */
+  async resolveNumberEvaluation(
+    flagKey: string,
+    defaultValue: number,
+    context: EvaluationContext
+  ): Promise<ResolutionDetails<number>> {
+    const res = await this.client.numberVariationDetail(
+      flagKey,
+      translateContext(this.logger, context),
+      defaultValue,
+    );
+
+    return Promise.resolve(translateResult(res));
+  }
+
+  /**
+   * Determines the object variation of a feature flag for a context, along with information about
+   * how it was calculated.
+   *
+   * @param flagKey The unique key of the feature flag.
+   * @param defaultValue The default value of the flag, to be used if the value is not available
+   *   from FeatBit.
+   * @param context The context requesting the flag.
+   * @returns A promise which will resolve to a ResolutionDetails.
+   */
+  async resolveObjectEvaluation<T extends JsonValue>(
+    flagKey: string,
+    defaultValue: T,
+    context: EvaluationContext
+  ): Promise<ResolutionDetails<T>> {
+    const res = await this.client.jsonVariationDetail(
+      flagKey,
+      translateContext(this.logger, context),
+      defaultValue,
+    );
+
+    return Promise.resolve(translateResult<T>(res));
+  }
+
+  /**
+   * Get the status of the FeatBit provider.
+   */
+  public get status() {
+    return this.innerStatus;
+  }
+
+  get hooks(): Hook[] {
+    return [];
+  }
+
+  /**
+   * Get the IFbClientWithEvents instance used by this provider.
+   *
+   * @returns The client for this provider.
+   */
+  public getClient() {
+    return this.client;
+  }
+
+  async onClose(): Promise<void> {
+    await this.client.close();
+  }
+}

package/src/SafeLogger.ts

@@ -0,0 +1,67 @@
+import { ILogger } from "@featbit/node-server-sdk";
+
+/**
+ * Logging levels. Each should correspond to a method on the logger.
+ */
+const LEVELS = ['error', 'warn', 'info', 'debug'];
+
+/**
+ * The safeLogger logic exists because we allow the application to pass in a custom logger, but
+ * there is no guarantee that the logger works correctly and if it ever throws exceptions there
+ * could be serious consequences (e.g. an uncaught exception within an error event handler, due
+ * to the provider trying to log the error, can terminate the application). An exception could
+ * result from faulty logic in the logger implementation, or it could be that this is not a logger
+ * at all but some other kind of object; the former is handled by a catch block that logs an error
+ * message to the provider's default logger, and we can at least partly guard against the latter by
+ * checking for the presence of required methods at configuration time.
+ */
+export default class SafeLogger implements ILogger {
+  private logger: ILogger;
+
+  private fallback: ILogger;
+
+  /**
+   * Construct a safe logger with the specified logger.
+   * @param logger The logger to use.
+   * @param fallback A fallback logger to use in case an issue is  encountered using
+   * the provided logger.
+   */
+  constructor(logger: ILogger, fallback: ILogger) {
+    LEVELS.forEach((level) => {
+      if (!logger[level] || typeof logger[level] !== 'function') {
+        throw new Error(`Provided logger instance must support logger.${level}(...) method`);
+        // Note that the provider normally does not throw exceptions to the application, but that
+        // rule does not apply to the constructor which will throw an exception if the parameters
+        // are so invalid that we cannot proceed with creating the client. An invalid logger meets
+        // those criteria since the SDK calls the logger during nearly all of its operations.
+      }
+    });
+    this.logger = logger;
+    this.fallback = fallback;
+  }
+
+  private log(level: 'error' | 'warn' | 'info' | 'debug', args: any[]) {
+    try {
+      this.logger[level](...args);
+    } catch {
+      // If all else fails do not break.
+      this.fallback[level](...args);
+    }
+  }
+
+  error(...args: any[]): void {
+    this.log('error', args);
+  }
+
+  warn(...args: any[]): void {
+    this.log('warn', args);
+  }
+
+  info(...args: any[]): void {
+    this.log('info', args);
+  }
+
+  debug(...args: any[]): void {
+    this.log('debug', args);
+  }
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+import { FbProvider } from "./FbProvider";
+
+
+export {
+    FbProvider
+}

package/src/translateContext.ts

@@ -0,0 +1,40 @@
+import { IUser, UserBuilder, IContextProperty, ILogger } from "@featbit/node-server-sdk";
+import { EvaluationContext } from "@openfeature/server-sdk";
+
+const builtInKeys = ['key', 'name', 'custom', 'targetingKey'];
+
+export function translateContext(logger: ILogger, evalContext: EvaluationContext): IUser {
+  const custom: IContextProperty[] = (evalContext.custom || []) as unknown as IContextProperty[];
+  const name: string = evalContext.name as string || '';
+  const key: string = evalContext.targetingKey || evalContext.key as string || '';
+
+  if (key === '') {
+    logger.error("The EvaluationContext must contain either a 'targetingKey' or a 'key' and the "
+      + 'type must be a string.');
+  }
+
+  const builder = new UserBuilder(key)
+    .name(name);
+
+  if (custom) {
+    if (Array.isArray(custom)) {
+      custom.forEach(({ name, value }) => {
+        builder.custom(name, value);
+      });
+    } else if (typeof custom === 'object') {
+      Object.entries(custom).forEach(([key, value]) => {
+        builder.custom(key, value as any as string);
+      });
+    }
+  }
+
+  Object.entries(evalContext).forEach(([key, value]) => {
+    if (builtInKeys.includes(key)) {
+      return;
+    }
+
+    builder.custom(key, value as string);
+  });
+
+  return builder.build();
+}

package/src/translateResult.ts

@@ -0,0 +1,42 @@
+import { ErrorCode, ResolutionDetails, StandardResolutionReasons } from "@openfeature/server-sdk";
+import { ReasonKinds, IEvalDetail } from "@featbit/node-server-sdk";
+
+/**
+ * Create a ResolutionDetails for an evaluation that produced a type different
+ * than the expected type.
+ * @param value The default value to populate the ResolutionDetails with.
+ * @returns A ResolutionDetails with the default value.
+ */
+function errorResult<T>(value: T, errorCode: ErrorCode, errorMessage?: string): ResolutionDetails<T> {
+  return {
+    value,
+    reason: StandardResolutionReasons.ERROR,
+    errorCode,
+    errorMessage
+  };
+}
+
+export function translateResult<T>(result: IEvalDetail<T>): ResolutionDetails<T> {
+  if (result.kind === ReasonKinds.WrongType) {
+    return errorResult(result.value, ErrorCode.TYPE_MISMATCH, result.reason);
+  }
+
+  if (result.kind === ReasonKinds.FlagNotFound) {
+    return errorResult(result.value, ErrorCode.FLAG_NOT_FOUND, result.reason);
+  }
+
+  if (result.kind === ReasonKinds.Error) {
+    return errorResult(result.value, ErrorCode.GENERAL, result.reason);
+  }
+
+  if (result.kind === ReasonKinds.ClientNotReady) {
+    return errorResult(result.value, ErrorCode.PROVIDER_NOT_READY, result.reason);
+  }
+
+  const resolution: ResolutionDetails<T> = {
+    value: result.value,
+    reason: result.kind,
+  };
+
+  return resolution;
+}