LaunchDarkly OpenFeature Provider for the Cloudflare Server-Side SDK

This package provides an OpenFeature provider that wraps the LaunchDarkly Cloudflare SDK.

This provider is designed primarily for use in multi-user Cloudflare Workers. It follows the server-side LaunchDarkly model for multi-user contexts. It is not intended for use in desktop and embedded systems applications.

Feature matrix

This matrix mirrors the feature matrix of the OpenFeature SDK for JavaScript and describes what this provider supports. Rows which are not supported state whether the limitation comes from the OpenFeature JavaScript SDK or from the provider.

| Status | Feature | Notes | | ------ | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ✅ | Providers | Evaluates boolean, string, number, and object flags through the LaunchDarkly Cloudflare SDK. | | ✅ | Targeting | The EvaluationContext is converted to a LaunchDarkly single or multi-context. See OpenFeature Specific Considerations. | | ✅ | Hooks | Hooks are registered on the OpenFeature API and client; the provider requires no additional support and its results are visible to hooks, including flag metadata. | | ✅ | Logging | The provider logs through the logging configuration of the LDOptions it is given. | | ✅ | Domains | Domains bind clients to providers in the OpenFeature SDK; a separate provider instance may be registered per domain. The provider is not domain-scoped, so one instance may also be shared by several domains. | | ❌ | Eventing | This provider does not emit ConfigurationChanged, Error, or Stale events because the Cloudflare SDK reads flag data from a KV namespace on each evaluation and has no connection to LaunchDarkly to provide an underlying event to translate. This is a Cloudflare platform limitation, not an OpenFeature SDK or provider gap. See ConfigurationChanged is not supported on this platform and #1886. | | ✅ | Transaction Context Propagation | Provided by the OpenFeature SDK, which merges the transaction context into the evaluation context before the provider is called; no provider support is required. | | ✅ | Tracking | The common provider implementation translates tracking details and sends them through the Cloudflare LaunchDarkly client. | | ✅ | Initialization | initialize waits for the Cloudflare LaunchDarkly client with the common provider's default 10-second timeout; the Cloudflare provider passes no initialization-timeout override. | | ✅ | Shutdown | The common provider implementation flushes and closes the Cloudflare LaunchDarkly client. A closed client cannot be restarted, so a new provider instance is required afterward. | | ✅ | Extending | The underlying LaunchDarkly client is available through getClient() for functionality with no OpenFeature equivalent. | | ✅ | Multi-Provider | Provided by the OpenFeature SDK; no provider support is required. | | ✅ | Flag metadata | LaunchDarkly evaluation reason details are returned as OpenFeature flag metadata. See Flag Metadata. |

Supported: ✅ | Partially supported: ⚠️ | Not supported: ❌

Installation

npm install @openfeature/server-sdk @launchdarkly/cloudflare-server-sdk @launchdarkly/openfeature-cloudflare-server

Then turn on the Node.js compatibility flag in your wrangler.toml. This allows the underlying Cloudflare SDK to use node:events:

compatibility_flags = [ "nodejs_compat" ]

Usage

OpenFeature.setProviderAndWait registers the provider on a registry shared by every concurrent request in the Workers isolate. Calling it on every request races concurrent requests against that shared state. Initialize the provider once per isolate and reuse it for every subsequent request, matching the Cloudflare SDK's own guidance that applications should instantiate a single instance for the lifetime of the worker:

import { OpenFeature } from '@openfeature/server-sdk';
import { LaunchDarklyProvider } from '@launchdarkly/openfeature-cloudflare-server';

const clientSideID = 'your-client-side-id';

let provider: LaunchDarklyProvider | undefined;
let providerReady: Promise<unknown> | undefined;

function ensureProviderReady(env: Bindings): Promise<unknown> {
  if (!providerReady) {
    // env.LD_KV is the Cloudflare KV namespace binding configured for LaunchDarkly.
    // See https://developers.cloudflare.com/workers/runtime-apis/kv#kv-bindings
    provider = new LaunchDarklyProvider(clientSideID, env.LD_KV /*, LDOptions here */);
    providerReady = OpenFeature.setProviderAndWait(provider);
  }
  return providerReady;
}

export default {
  async fetch(request: Request, env: Bindings, ctx: ExecutionContext): Promise<Response> {
    // setProviderAndWait throws if initialization fails; catch as needed.
    await ensureProviderReady(env);

    const client = OpenFeature.getClient();
    const flagValue = await client.getBooleanValue('flag-key', false, {
      targetingKey: 'user-key',
    });

    // Flushing (not closing) is safe to call per request -- it only sends this
    // request's queued events and never tears down the shared provider/client.
    ctx.waitUntil(provider!.getClient().flush());

    return new Response(`flag-key: ${flagValue}`);
  },
};

See the full getting-started example.

ConfigurationChanged is not supported on this platform

Unlike the LaunchDarkly OpenFeature provider for Node.js, this provider does not emit the OpenFeature ConfigurationChanged event.

The Cloudflare SDK reads flag data out of a Cloudflare KV namespace via its EdgeFeatureStore on each evaluation; that store's upsert and delete methods -- which a streaming, long-lived SDK client would use to react to flag changes -- are hardcoded no-ops on this platform. There is no persistent connection to LaunchDarkly and no local cache that receives update notifications, so there is no underlying event for the provider to translate into ConfigurationChanged. Because Cloudflare Workers are short-lived and re-read the latest flag data from KV on every request, you do not need a change notification to see up-to-date flag values -- simply re-evaluate the flag on the next request.

OpenFeature Specific Considerations

LaunchDarkly evaluates contexts, and it can either evaluate a single-context or a multi-context. When using OpenFeature, both single and multi-contexts must be encoded into a single EvaluationContext. This is accomplished by looking for an attribute named kind in the EvaluationContext.

There are 4 different scenarios related to the kind:

1. There is no kind attribute. The provider will treat the context as a single context of kind "user".
2. There is a kind attribute with the value "multi". The provider will treat the context as a multi-context.
3. There is a kind attribute with a string value other than "multi". The provider will treat it as a single context of the specified kind.
4. There is a kind attribute, but its value is not a string. The value will be discarded, the context will be treated as kind "user", and a warning will be logged.

The kind attribute should be a string containing only ASCII letters, numbers, ., _, or -.

The OpenFeature specification allows for an optional targeting key, but LaunchDarkly requires a key for evaluation. A targeting key must be specified for each context being evaluated. It may be specified using either targetingKey, as defined in the OpenFeature specification, or key, which is the typical LaunchDarkly identifier. If both are specified, targetingKey takes precedence.

There are several attributes with special handling within a single or multi-context:

• privateAttributes - Must be an array of strings. Equivalent to _meta.privateAttributes in the SDK.
• anonymous - Must be a boolean. Equivalent to anonymous in the SDK.
• name - Must be a string. Equivalent to name in the SDK.

Examples

A single user context

const evaluationContext = {
  targetingKey: 'my-user-key',
};

A single context of kind "organization"

const evaluationContext = {
  kind: 'organization',
  targetingKey: 'my-org-key',
};

A multi-context containing a "user" and an "organization"

const evaluationContext = {
  kind: 'multi',
  organization: {
    targetingKey: 'my-org-key',
    myCustomAttribute: 'myAttributeValue',
  },
  user: {
    targetingKey: 'my-user-key',
  },
};

Setting private attributes in a single context

const evaluationContext = {
  kind: 'organization',
  name: 'the-org-name',
  targetingKey: 'my-org-key',
  myCustomAttribute: 'myCustomValue',
  privateAttributes: ['myCustomAttribute'],
};

Setting private attributes in a multi-context

const evaluationContext = {
  kind: 'multi',
  organization: {
    targetingKey: 'my-org-key',
    name: 'the-org-name',
    // privateAttributes only applies to the "organization" context.
    privateAttributes: ['myCustomAttribute'],
    // This attribute will be private.
    myCustomAttribute: 'myAttributeValue',
  },
  user: {
    targetingKey: 'my-user-key',
    anonymous: true,
    // This attribute will not be private.
    myCustomAttribute: 'myAttributeValue',
  },
};

Contributing

See Contributing.

Verifying SDK build provenance with the SLSA framework

LaunchDarkly uses the SLSA framework (Supply-chain Levels for Software Artifacts) to help developers make their supply chain more secure by ensuring the authenticity and build integrity of our published SDK packages. To learn more, see the provenance guide.

About LaunchDarkly

• LaunchDarkly is a continuous delivery platform that provides feature flags as a service and allows developers to iterate quickly and safely. We allow you to easily flag your features and manage them from the LaunchDarkly dashboard. With LaunchDarkly, you can:
  • Roll out a new feature to a subset of your users (like a group of users who opt-in to a beta tester group), gathering feedback and bug reports from real-world use cases.
  • Gradually roll out a feature to an increasing percentage of users, and track the effect that the feature has on key metrics (for instance, how likely is a user to complete a purchase if they have feature A versus feature B?).
  • Turn off a feature that you realize is causing performance problems in production, without needing to re-deploy, or even restart the application with a changed configuration file.
  • Grant access to certain features based on user attributes, like payment plan (eg: users on the 'gold' plan get access to more features than users in the 'silver' plan).
  • Disable parts of your application to facilitate maintenance, without taking everything offline.
• LaunchDarkly provides feature flag SDKs for a wide variety of languages and technologies. Check out our documentation for a complete list.
• Explore LaunchDarkly
  • launchdarkly.com for more information
  • docs.launchdarkly.com for our documentation and SDK reference guides
  • apidocs.launchdarkly.com for our API documentation
  • blog.launchdarkly.com for the latest product updates