Posted inProgramming

Building a Feature Flag System with OpenFeature in TypeScript: Flexible Toggles and Canary Deployments

Programming tutorial - IT technology blog
Programming tutorial - IT technology blog

Problem Statement: The Pain of High-Stakes Deployments

It is 3:15 PM on a Thursday. Your team just deployed a complete rewrite of the checkout service to production. Ten minutes later, PagerDuty erupts. An unindexed query in the new payment pipeline is choking your PostgreSQL connection pool, holding all 60 connections open. Latency spikes past 4,500 ms. Initiating a rollback means waiting twelve minutes for CI to rebuild, run smoke tests, and roll out pods. During that downtime, every failed checkout bleeds roughly $8,000 a minute in lost revenue.

This failure mode exposes a classic architectural trap: conflating deployment with release. When pushing binaries automatically exposes new logic to every user, your blast radius is immediately 100%. Staging environments rarely match production traffic patterns, messy tenant data, or peak concurrency spikes.

Root Cause: Coupled Deployments and Vendor Lock-in

Why do engineering teams hit this wall? Two technical issues are usually to blame:

  • Lack of Runtime Control: Tying feature activation to environment variables or Helm values requires a full pod restart to flip a switch. Restarts take minutes. Incident response demands milliseconds. Feature control must exist independently outside the container lifecycle.
  • SDK Lock-in: Teams often start with crude if/else checks querying a Redis key or an internal Postgres table. As requirements grow, they migrate to enterprise platforms like LaunchDarkly, Split, or Unleash. Sprinkling vendor-specific SDK calls across 50 microservices creates painful technical debt. Swapping providers later turns into a multi-month refactoring slog.

OpenFeature solves this architectural coupling. Governed by the Cloud Native Computing Foundation (CNCF), OpenFeature provides a vendor-agnostic specification and standard SDK. It decouples your business logic from underlying flag vendors across major runtimes, including TypeScript.

Core Concepts: How OpenFeature Works

OpenFeature divides responsibility across four distinct primitives:

  • Evaluation Context: Runtime attributes passed during flag evaluation. These include contextual properties like targetingKey, tenantId, email domain, country code, or app version.
  • Client: The developer-facing API that requests flag values (booleans, strings, numbers, or JSON payloads).
  • Provider: The translation adapter between the OpenFeature API and your flag storage engine. This engine can be an in-memory dictionary, an open-source engine like Flipt or GO Feature Flag, or a SaaS platform. You can swap providers dynamically without modifying a single evaluation line in your application code.
  • Hooks: Composable lifecycle interceptors executed before, during, or after flag resolution. They are ideal for pushing telemetry to OpenTelemetry, Prometheus, or Datadog.

Standardizing on this abstraction simplifies zero-downtime releases. You gain granular traffic steering without touching infrastructure configs.

Hands-on Practice: Building a Canary Rollout System with TypeScript

Let’s build a runnable TypeScript service that performs deterministic, percentage-based canary rollouts using OpenFeature.

1. Initializing the Project

Set up a fresh Node.js workspace and install the required packages:

mkdir ts-openfeature-canary
cd ts-openfeature-canary
npm init -y
npm install @openfeature/server-sdk murmurhash
npm install --save-dev typescript @types/node @types/murmurhash ts-node
npx tsc --init

We use murmurhash to hash user identifiers into a uniform distribution from 0 to 99. This guarantees sticky cohort assignments: the same user always gets the exact same flag result.

2. Creating a Custom Canary Provider

While production systems usually consume managed providers, writing a local in-memory provider clarifies how contextual evaluations work under the hood.

Save this implementation as canaryProvider.ts:

import {
  Provider,
  ResolutionDetails,
  EvaluationContext,
  ProviderMetadata,
  StandardResolutionReasons,
} from '@openfeature/server-sdk';
import murmurhash from 'murmurhash';

export interface FlagRule {
  defaultValue: boolean;
  canaryPercentage?: number; // Integer between 0 and 100
  targetUsers?: string[];
}

export class CanaryFlagProvider implements Provider {
  readonly metadata: ProviderMetadata = {
    name: 'CanaryFlagProvider',
  };

  private flags: Map<string, FlagRule> = new Map();

  constructor(initialFlags: Record<string, FlagRule>) {
    for (const [key, rule] of Object.entries(initialFlags)) {
      this.flags.set(key, rule);
    }
  }

  // Dynamically update flags at runtime without restarting the process
  public updateFlag(key: string, rule: FlagRule): void {
    this.flags.set(key, rule);
  }

  async resolveBooleanEvaluation(
    flagKey: string,
    defaultValue: boolean,
    context: EvaluationContext
  ): Promise<ResolutionDetails<boolean>> {
    const rule = this.flags.get(flagKey);

    if (!rule) {
      return {
        value: defaultValue,
        reason: StandardResolutionReasons.DEFAULT,
      };
    }

    const targetingKey = context.targetingKey || (context.userId as string);

    // 1. Explicit allowlist check
    if (targetingKey && rule.targetUsers?.includes(targetingKey)) {
      return {
        value: true,
        reason: StandardResolutionReasons.TARGETING_MATCH,
      };
    }

    // 2. Deterministic percentage bucket calculation
    if (targetingKey && typeof rule.canaryPercentage === 'number') {
      const hash = Math.abs(murmurhash.v3(`${flagKey}:${targetingKey}`));
      const bucket = hash % 100;
      const isIncluded = bucket < rule.canaryPercentage;

      return {
        value: isIncluded,
        reason: isIncluded
          ? StandardResolutionReasons.TARGETING_MATCH
          : StandardResolutionReasons.DEFAULT,
      };
    }

    return {
      value: rule.defaultValue,
      reason: StandardResolutionReasons.STATIC,
    };
  }

  async resolveStringEvaluation(flagKey: string, defaultValue: string) {
    return { value: defaultValue, reason: StandardResolutionReasons.DEFAULT };
  }

  async resolveNumberEvaluation(flagKey: string, defaultValue: number) {
    return { value: defaultValue, reason: StandardResolutionReasons.DEFAULT };
  }

  async resolveObjectEvaluation<T>(flagKey: string, defaultValue: T) {
    return { value: defaultValue, reason: StandardResolutionReasons.DEFAULT };
  }
}

3. Integrating OpenFeature into Your Application Logic

Register the custom provider with the OpenFeature singleton and evaluate user contexts. Create app.ts:

import { OpenFeature } from '@openfeature/server-sdk';
import { CanaryFlagProvider } from './canaryProvider';

async function main() {
  // 1. Configure the rollout rule: 20% traffic + dedicated QA bypass
  const flagConfigs = {
    'v2-checkout-engine': {
      defaultValue: false,
      canaryPercentage: 20,
      targetUsers: ['[email protected]'],
    },
  };

  const provider = new CanaryFlagProvider(flagConfigs);
  await OpenFeature.setProviderAndWait(provider);

  const client = OpenFeature.getClient('payment-service');

  const testUsers = [
    { id: '[email protected]', name: 'Internal QA Engineer' },
    { id: 'usr_live_83910', name: 'Sarah (Tenant A)' },
    { id: 'usr_live_12049', name: 'Marcus (Tenant B)' },
    { id: 'usr_live_44921', name: 'Elena (Tenant C)' },
    { id: 'usr_live_99214', name: 'David (Tenant D)' },
  ];

  console.log('=== Stage 1: 20% Canary Deployment ===');
  for (const user of testUsers) {
    const isEnabled = await client.getBooleanValue(
      'v2-checkout-engine',
      false,
      { targetingKey: user.id }
    );
    console.log(`[Eval] ${user.name.padEnd(24)} -> Flag active: ${isEnabled}`);
  }

  // 2. Promote flag to 100% after monitoring metrics indicate 0% errors
  console.log('\n=== Stage 2: Promoting to 100% Rollout ===');
  provider.updateFlag('v2-checkout-engine', {
    defaultValue: true,
    canaryPercentage: 100,
  });

  for (const user of testUsers) {
    const isEnabled = await client.getBooleanValue(
      'v2-checkout-engine',
      false,
      { targetingKey: user.id }
    );
    console.log(`[Eval] ${user.name.padEnd(24)} -> Flag active: ${isEnabled}`);
  }
}

main().catch(console.error);

4. Executing the Implementation

Execute the script directly with ts-node:

npx ts-node app.ts

During stage one, the QA tester and exactly 20% of customer IDs evaluate to true. The remaining users run the stable legacy code path. Promoting the flag shifts all traffic immediately in-memory without initiating a container restart or triggering pod churn.

Conclusion: Decoupling as an Operational Standard

Separating deployment from release turns high-stress launches into predictable, low-risk routines. Using the OpenFeature specification gives you full operational flexibility while guarding against vendor lock-in.

Three best practices will keep your flag architecture clean as you scale:

  1. Treat toggles as short-lived debt: Set an expiration SLA on release toggles. Delete the flag checks and prune dead branches once a feature reaches 100% for seven consecutive days.
  2. Enforce deterministic fallbacks: Flag systems can encounter network blips. Your default value must always resolve to the safest fallback path (usually false).
  3. Tie toggles directly to alerting: Stream flag evaluation events to your metrics stack. When error rates exceed 0.5% during a canary stage, trigger automated kill-switches to instantly turn the flag off.
Share:
Tags: