OpenFeature API and SDK Experimentation

The purpose of this repository is to experiment with different techniques in order to help define the initial spec of OpenFeature. It was inspired by the OpenTelemetry SDK, with a focus on the design principles outlined in the spec. These experiments were written in TypeScript and focus on NodeJS, but the basic concepts should be language agnostic.

Application Author API

These are the APIs and interfaces that Application Author (who doesn't particularly care about the underlying feature flag implementation) uses OpenFeature to control "pivot points" in their code.

// initialize OpenFeature and create a client
openfeature.registerProvider(
  new MyFeatureFlagSystemProvider({ apiKey: 'my-secret-api-key' })
);
const client = openfeature.getClient();

// evaluate a boolean flag
const myFlagEnabled = await client.isEnabled('my-boolean-flag-key', false); // false is the default enabled state

// get a string flag value
const myStringFlagValue = await client.getStringValue(
  'my-string-flag-key',
  'hello world!' //default value
);

// get a numeric flag value
const myNumericFlagValue = await client.getNumberValue(
  'my-numeric-flag-key',
  1337 // 1337 is the default value
);

// get a object flag value
const myObject = await client.getObjectValue<MyObject>(
  'my-object-flag-key',
  new MyObject() // MyObject instance is the default value
);

// provide additional attributes to flag evaluation
const requestData = {
  ip: req.headers['x-forwarded-for'] || req.socket.remoteAddress,
};
const myStringFlagValue = await client.getStringValue(
  'my-string-flag-key',
  'hello world!',
  requestData
);

// get the details of a flag evaluation
const { flagKey, value, variant, reason, errorCode, executedHooks } =
  await client.getStringDetails('my-string-flag-key', 'hello world!');

// attach additional handlers to the flag evaluation lifecycle (can also be attached globally and on client, to impact all evaluations)
const myStringFlagValue = await client.getStringValue(
  'my-string-flag-key',
  'hello world!',
  requestData,
  {
    hooks: [
      {
        name: 'log',
        // "before" can be used for logging, telemetry configuration, and manipulating attributes
        before: (hookContext) => {
          console.log('before');
        },
        // "after" can be used for logging, telemetry cleanup, and even validating and manipulating the returned value
        after: (
          hookContext,
          evaluationDetails: FlagEvaluationDetails<string>
        ) => {
          console.log('after');
        },
      },
    ],
  }
);

Getting started with the SDK experimentation project

To run the demo scenarios described on this page, please make sure you have the following prerequisites configured on your system.

Git
NodeJS 14 or later
Docker

You can then clone the repo and install the dependencies.

clone the repo: git clone https://github.com/open-feature/sdk-research.git
Install dependencies: npm ci

Available demos:

No-op
Environment Variable Provider
Split Provider
CloudBees Feature Management Provider
LaunchDarkly Provider Demo
Flagsmith Provider Demo
OpenTelemetry and Zipkin
Validation Hook Demo

Create a new provider

Providers are an important part of OpenFeature. They're responsible for performing the flag evaluation and must adhere to the feature flag API. To get started, run the following command:

npm run provider-generator

You'll need to provide a name for the generator. After that, the output will contain the path to the new provider class and a start command.

Simple API

A core design principle of OpenFeature is a simple, understandable API. OpenFeature's API needs to be flexible enough to handle all the common use cases of feature flags while being easy to work with. In order to support this, a common API needs to be defined that's capable of supporting core feature flagging use cases. The method names and signatures still need to be agreed upon by the community, but a basic implementation can be found here.

Global Singleton

Inspired by OpenTelemetry, this experimental SDK registers itself globally. Typically doing this is discouraged but, in this case, it provides interesting flexibility. It allows library maintainers to include OpenFeature in their project, even if they're running a different, but compatible version of OpenFeature. An example of how this could be used can be found in the Fibonacci library.

Provider Registration

OpenFeature allows developers to register a provider. Providers are responsible for using the flag identity and context to determine the state of the feature. If no providers are registered, the flags will no-op and return the default value.

No-op Demo

To see this in action, we'll run the API app found here. Notice that we're using OpenFeature but not registering a provider. Let's run the app and see what happens.

Run npm run no-op-demo
Open http://localhost:3333/api in your browser

That's it! You should see Welcome to the api!. Unfortunately, that's all you can do without registering a provider. Thankfully, as we'll see in the next section, that part is easy.

Compatibility

Another key design principle of OpenFeature is compatibility with existing open source and commercial feature flag offerings. It should be possible to register a feature flag provider that's responsible for handling the flag evaluation. Only a single provider can be registered at a time and not providing one will cause flag evaluations to return the default value. This can be tested by running the application without registering a provider.

NOTE: You may notice that the demos below don't register providers directly in the app. This is done before the main app starts using the -r node cli argument. The config can be found here.

Environment Variable Provider Demo

The environment variable provider is a simple demo showing how environment variables could be used make flag evaluations. Its purpose is to show how a provider could be implemented.