Read AppConfig Feature Flags With AWS SDK v3

{
  "newCheckout": { "enabled": true },
  "freeShipping": { "enabled": true, "threshold": 75 },
  "betaSearch": { "enabled": false }
}

// feature-flags.ts: read AWS AppConfig feature flags with the AppConfig Data API (AWS SDK v3).
// Starts one configuration session, reuses the last good flags while the poll interval hasn't passed,
// keeps them when GetLatestConfiguration returns an empty body (no change), and restarts the session
// if the token is rejected (tokens are single use and expire after 24 hours).
import {
  AppConfigDataClient,
  StartConfigurationSessionCommand,
  GetLatestConfigurationCommand,
  BadRequestException,
} from "@aws-sdk/client-appconfigdata";

/** Shape of a deployed AWS.AppConfig.FeatureFlags profile: one entry per flag key. */
export type FlagValue = { enabled: boolean } & Record<string, string | number | boolean | string[] | number[]>;
export type Flags = Record<string, FlagValue>;

export interface FlagSource {
  application: string; // application name or ID
  environment: string; // environment name or ID
  profile: string; // feature flag configuration profile name or ID
  minPollSeconds?: number; // 15 to 86,400; the session refuses faster polling
}

export class FeatureFlags {
  private token: string | undefined;
  private flags: Flags = {};
  private nextPollAt = 0;
  private inFlight: Promise<Flags> | undefined;
  public version: string | undefined;
  private readonly source: FlagSource;
  private readonly defaults: Flags;
  private readonly client: AppConfigDataClient;

  constructor(source: FlagSource, defaults: Flags = {}, client = new AppConfigDataClient({})) {
    this.source = source;
    this.defaults = defaults;
    this.client = client;
  }

  /** All flags. Calls AppConfig at most once per poll interval; concurrent callers share one request. */
  async all(): Promise<Flags> {
    if (Date.now() < this.nextPollAt) return this.flags;
    this.inFlight ??= this.poll().finally(() => {
      this.inFlight = undefined;
    });
    return this.inFlight;
  }

  async isEnabled(key: string): Promise<boolean> {
    const flags = await this.all();
    return (flags[key] ?? this.defaults[key])?.enabled === true;
  }

  async attribute<T extends string | number | boolean | string[] | number[]>(key: string, name: string, fallback: T): Promise<T> {
    const flag = (await this.all())[key] ?? this.defaults[key];
    return flag?.enabled ? ((flag[name] as T | undefined) ?? fallback) : fallback;
  }

  private async startSession(): Promise<string> {
    const res = await this.client.send(
      new StartConfigurationSessionCommand({
        ApplicationIdentifier: this.source.application,
        EnvironmentIdentifier: this.source.environment,
        ConfigurationProfileIdentifier: this.source.profile,
        RequiredMinimumPollIntervalInSeconds: this.source.minPollSeconds,
      }),
    );
    if (!res.InitialConfigurationToken) throw new Error("AppConfig returned no InitialConfigurationToken");
    return res.InitialConfigurationToken;
  }

  private async poll(retried = false): Promise<Flags> {
    try {
      this.token ??= await this.startSession();
      const res = await this.client.send(new GetLatestConfigurationCommand({ ConfigurationToken: this.token }));
      this.token = res.NextPollConfigurationToken; // each token is valid for one call only
      this.nextPollAt = Date.now() + (res.NextPollIntervalInSeconds ?? 60) * 1000;
      const body = res.Configuration?.transformToString() ?? "";
      if (body.length > 0) {
        // A non-empty body means a new version; an empty one means "no change since your last token".
        this.flags = JSON.parse(body) as Flags;
        this.version = res.VersionLabel;
      }
      return this.flags;
    } catch (err) {
      this.token = undefined;
      if (err instanceof BadRequestException && !retried) return this.poll(true); // expired or reused token
      console.error("AppConfig poll failed, serving last known flags:", err);
      this.nextPollAt = Date.now() + 30_000; // back off instead of calling AppConfig on every request
      return Object.keys(this.flags).length ? this.flags : this.defaults;
    }
  }
}

// checkout-handler.ts: using FeatureFlags in a Lambda function. The instance lives outside the handler,
// so warm invocations reuse the cached flags and the session token.
import { FeatureFlags } from "./feature-flags.js";

const flags = new FeatureFlags(
  { application: "shop", environment: "prod", profile: "checkout-flags", minPollSeconds: 30 },
  { newCheckout: { enabled: false }, freeShipping: { enabled: false, threshold: 50 } }, // used if AppConfig is unreachable
);

export async function handler(event: { cartTotal: number }): Promise<{ flow: string; freeShipping: boolean }> {
  const flow = (await flags.isEnabled("newCheckout")) ? "v2" : "v1";
  const threshold = await flags.attribute("freeShipping", "threshold", Number.POSITIVE_INFINITY);
  return { flow, freeShipping: event.cartTotal >= threshold };
}

// extension-flags.ts: read the same flags through the AWS AppConfig Agent Lambda extension instead of the SDK.
// The extension caches the data and polls AppConfig itself (every 45 seconds by default).
type Flags = Record<string, { enabled: boolean } & Record<string, unknown>>;
const port = process.env.AWS_APPCONFIG_EXTENSION_HTTP_PORT ?? "2772";
const url = `http://localhost:${port}/applications/shop/environments/prod/configurations/checkout-flags`;

export async function handler(): Promise<{ flow: string }> {
  const res = await fetch(url);
  if (!res.ok) throw new Error(`AppConfig extension returned ${res.status}`);
  const flags = (await res.json()) as Flags;
  return { flow: flags.newCheckout?.enabled ? "v2" : "v1" };
}

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "ReadCheckoutFlags",
      "Effect": "Allow",
      "Action": [
        "appconfig:StartConfigurationSession",
        "appconfig:GetLatestConfiguration"
      ],
      "Resource": "arn:aws:appconfig:us-east-1:123456789012:application/abc1234/environment/def5678/configuration/ghi9012"
    }
  ]
}

// feature-flags.test.ts: npx tsx test/feature-flags.test.ts
import assert from "node:assert/strict";
import { mockClient } from "aws-sdk-client-mock";
import { Uint8ArrayBlobAdapter } from "@smithy/util-stream";
import {
  AppConfigDataClient,
  StartConfigurationSessionCommand,
  GetLatestConfigurationCommand,
  BadRequestException,
} from "@aws-sdk/client-appconfigdata";
import { FeatureFlags } from "../src/feature-flags.ts";

const mock = mockClient(AppConfigDataClient);
const body = (s: string) => Uint8ArrayBlobAdapter.fromString(s);
let t = 0;
const realNow = Date.now;
Date.now = () => t;

mock.on(StartConfigurationSessionCommand).resolves({ InitialConfigurationToken: "tok-0" });
mock
  .on(GetLatestConfigurationCommand)
  .resolvesOnce({
    Configuration: body('{"newCheckout":{"enabled":true},"freeShipping":{"enabled":true,"threshold":75}}'),
    NextPollConfigurationToken: "tok-1",
    NextPollIntervalInSeconds: 30,
    VersionLabel: "v7",
  })
  .resolvesOnce({ Configuration: body(""), NextPollConfigurationToken: "tok-2", NextPollIntervalInSeconds: 30 })
  .rejectsOnce(new BadRequestException({ message: "expired", $metadata: {} }))
  .resolvesOnce({ Configuration: body('{"newCheckout":{"enabled":false}}'), NextPollConfigurationToken: "tok-4", NextPollIntervalInSeconds: 30 });

const flags = new FeatureFlags({ application: "shop", environment: "prod", profile: "checkout-flags" }, { newCheckout: { enabled: false } });
const [a, b] = await Promise.all([flags.isEnabled("newCheckout"), flags.isEnabled("newCheckout")]);
assert.equal(a && b, true);
assert.equal(mock.commandCalls(GetLatestConfigurationCommand).length, 1); // concurrent callers shared one call
assert.equal(await flags.attribute("freeShipping", "threshold", 0), 75);
assert.equal(flags.version, "v7");
t = 31_000; // interval passed: empty body keeps the flags
assert.equal(await flags.isEnabled("newCheckout"), true);
assert.equal(mock.commandCalls(GetLatestConfigurationCommand)[1].args[0].input.ConfigurationToken, "tok-1");
t = 62_000; // token rejected: new session, then new data
assert.equal(await flags.isEnabled("newCheckout"), false);
assert.equal(mock.commandCalls(StartConfigurationSessionCommand).length, 2);
Date.now = realNow;
console.log("feature flag tests passed; calls:", mock.commandCalls(GetLatestConfigurationCommand).length);