@terreno/feature-flags 0.19.0 → 0.20.0

package/src/featureFlagsApp.ts

@@ -1,7 +1,9 @@
+import {OpenFeature} from "@openfeature/server-sdk";
 import {
   APIError,
   asyncHandler,
   authenticateMiddleware,
+  logger,
   type ModelRouterOptions,
   modelRouter,
   type OpenApiMiddleware,
@@ -10,9 +12,31 @@ import {
 } from "@terreno/api";
 import type express from "express";
 import type {Model} from "mongoose";
+import mongoose from "mongoose";
 import {evaluateAllFlags} from "./evaluate";
 import {FeatureFlag} from "./featureFlagModel";
-import type {FeatureFlagDocument, FeatureFlagsOptions, SegmentFunction} from "./types";
+import {buildFlagDefinition} from "./flagConfiguration";
+import {MongoFeatureFlagProvider} from "./openFeatureProvider";
+import type {
+  FeatureFlagDocument,
+  FeatureFlagsLiveUpdatesOptions,
+  FeatureFlagsOptions,
+  FlagConfigurationResponse,
+  FlagDefinition,
+  SegmentFunction,
+} from "./types";
+
+let evaluateDeprecationWarned = false;
+
+const resolveSocketServer = (
+  live: FeatureFlagsLiveUpdatesOptions
+): import("./types").FeatureFlagsSocketEmitter | null => {
+  const server = live.socketIoServer;
+  if (typeof server === "function") {
+    return server();
+  }
+  return server;
+};
 
 /**
  * TerrenoPlugin that provides feature flags and A/B testing.
@@ -35,6 +59,7 @@ import type {FeatureFlagDocument, FeatureFlagsOptions, SegmentFunction} from "./
 export class FeatureFlagsApp implements TerrenoPlugin {
   private options: FeatureFlagsOptions;
   private segments: Record<string, SegmentFunction>;
+  private mongoProvider?: MongoFeatureFlagProvider;
 
   constructor(options?: FeatureFlagsOptions) {
     this.options = options ?? {};
@@ -43,6 +68,8 @@ export class FeatureFlagsApp implements TerrenoPlugin {
 
   register(app: express.Application, openApi?: unknown): void {
     const basePath = this.options.basePath ?? "/feature-flags";
+    const openFeatureDomain = this.options.openFeatureDomain ?? "feature-flags";
+
     const routerOptions: ModelRouterOptions<FeatureFlagDocument> = {
       ...(openApi ? {openApi: openApi as OpenApiMiddleware} : {}),
       permissions: this.options.permissions ?? {
@@ -55,17 +82,54 @@ export class FeatureFlagsApp implements TerrenoPlugin {
       sort: "-created",
     };
 
-    // Admin CRUD routes for flags
+    this.mongoProvider = new MongoFeatureFlagProvider({
+      flagModel: FeatureFlag,
+      segments: this.segments,
+    });
+    OpenFeature.setProvider(openFeatureDomain, this.mongoProvider);
+
     app.use(
       `${basePath}/flags`,
       modelRouter(FeatureFlag as Model<FeatureFlagDocument>, routerOptions)
     );
 
-    // GET /feature-flags/evaluate — evaluate all flags for current user
+    app.get(
+      `${basePath}/flagConfiguration`,
+      authenticateMiddleware(),
+      asyncHandler(async (req: express.Request, res: express.Response) => {
+        const user = req.user as {_id?: unknown; id?: string} | undefined;
+        if (!user) {
+          throw new APIError({status: 401, title: "Authentication required"});
+        }
+
+        const targetingKey = String(user._id ?? user.id);
+        const flags = await FeatureFlag.find({archived: {$ne: true}, enabled: true});
+        const config: Record<string, FlagDefinition> = {};
+
+        for (const flag of flags) {
+          config[flag.key] = buildFlagDefinition(flag, targetingKey, user, this.segments);
+        }
+
+        const body: FlagConfigurationResponse = {data: config};
+        return res.json(body);
+      })
+    );
+
     app.get(
       `${basePath}/evaluate`,
       authenticateMiddleware(),
       asyncHandler(async (req: express.Request, res: express.Response) => {
+        if (!evaluateDeprecationWarned) {
+          evaluateDeprecationWarned = true;
+          logger.warn(
+            "[feature-flags] GET /evaluate is deprecated; migrate clients to GET /flagConfiguration or use @terreno/rtk useFeatureFlags / useTerrenoFeatureFlags."
+          );
+        }
+
+        const sunset = new Date(Date.now() + 90 * 86400000).toUTCString();
+        res.setHeader("Deprecation", "true");
+        res.setHeader("Sunset", sunset);
+
         const user = req.user as {_id?: unknown; id?: string} | undefined;
         if (!user) {
           throw new APIError({status: 401, title: "Authentication required"});
@@ -78,7 +142,6 @@ export class FeatureFlagsApp implements TerrenoPlugin {
       })
     );
 
-    // GET /feature-flags/segments — list registered segment names (admin only)
     app.get(
       `${basePath}/segments`,
       authenticateMiddleware(),
@@ -94,5 +157,62 @@ export class FeatureFlagsApp implements TerrenoPlugin {
         return res.json({data: Object.keys(this.segments)});
       })
     );
+
+    const live = this.options.liveUpdates;
+    if (live && this.mongoProvider) {
+      const eventName = live.eventName ?? "featureFlagsChanged";
+      let stream: {
+        close: () => Promise<void> | void;
+        on: (event: string, handler: (...args: unknown[]) => void) => unknown;
+      } | null = null;
+      let didRetry = false;
+
+      const cleanupStream = (): void => {
+        try {
+          stream?.close();
+        } catch {
+          /* ignore close errors */
+        }
+        stream = null;
+      };
+
+      const bindStream = (): void => {
+        try {
+          stream = FeatureFlag.watch([], {fullDocument: "updateLookup"});
+        } catch (err) {
+          logger.warn(
+            `[feature-flags] FeatureFlag.watch() failed — live updates require MongoDB as a replica set (even single-node). ${String(err)}`
+          );
+          return;
+        }
+
+        stream.on("change", (change) => {
+          const key = (change as {fullDocument?: {key?: string}}).fullDocument?.key;
+          const ioResolved = resolveSocketServer(live);
+          if (ioResolved) {
+            ioResolved.emit(eventName, {key});
+          }
+          this.mongoProvider?.emitConfigurationChanged();
+        });
+
+        stream.on("error", (err) => {
+          logger.warn(`[feature-flags] change stream error: ${String(err)}`);
+          cleanupStream();
+          if (!didRetry) {
+            didRetry = true;
+            bindStream();
+            return;
+          }
+          logger.warn("[feature-flags] change stream disabled after repeated errors");
+        });
+      };
+
+      bindStream();
+
+      const onConnectionClose = (): void => {
+        cleanupStream();
+      };
+      mongoose.connection.on("close", onConnectionClose);
+    }
   }
 }

package/src/flagConfiguration.ts

@@ -0,0 +1,57 @@
+import {evaluateFlag} from "./evaluate";
+import type {FeatureFlagDocument, FlagDefinition, SegmentFunction} from "./types";
+
+/**
+ * Resolves the OpenFeature defaultVariant for a flag document, including legacy
+ * documents that omit the field.
+ */
+export const effectiveDefaultVariantForFlag = (flag: FeatureFlagDocument): string => {
+  if (flag.defaultVariant) {
+    return flag.defaultVariant;
+  }
+  if (flag.type === "boolean") {
+    return "off";
+  }
+  return flag.variants[0]?.key ?? "off";
+};
+
+/**
+ * Builds a {@link FlagDefinition} for the `/flagConfiguration` wire shape from a
+ * persisted flag and the resolved evaluation for one user.
+ */
+export const buildFlagDefinition = (
+  flag: FeatureFlagDocument,
+  targetingKey: string,
+  user: unknown,
+  segments: Record<string, SegmentFunction>
+): FlagDefinition => {
+  const evaluated = evaluateFlag(flag, targetingKey, user, segments);
+
+  if (flag.type === "boolean") {
+    const active = evaluated === true;
+    return {
+      defaultVariant: active ? "on" : "off",
+      disabled: false,
+      variants: {off: false, on: true},
+    };
+  }
+
+  const variantKeys = flag.variants.map((v) => v.key);
+  let resolved: string;
+  if (typeof evaluated === "string" && variantKeys.includes(evaluated)) {
+    resolved = evaluated;
+  } else {
+    resolved = effectiveDefaultVariantForFlag(flag);
+  }
+
+  const variants: Record<string, string> = {};
+  for (const k of variantKeys) {
+    variants[k] = k;
+  }
+
+  return {
+    defaultVariant: resolved,
+    disabled: false,
+    variants,
+  };
+};

package/src/index.ts

@@ -1,13 +1,19 @@
 export {deterministicHash, evaluateAllFlags, evaluateFlag} from "./evaluate";
 export {FeatureFlag, featureFlagAdminConfig} from "./featureFlagModel";
 export {FeatureFlagsApp} from "./featureFlagsApp";
+export {buildFlagDefinition, effectiveDefaultVariantForFlag} from "./flagConfiguration";
+export {MongoFeatureFlagProvider} from "./openFeatureProvider";
 export type {
   EvaluationResult,
   FeatureFlagDocument,
   FeatureFlagModel,
   FeatureFlagRule,
+  FeatureFlagsLiveUpdatesOptions,
   FeatureFlagsOptions,
+  FeatureFlagsSocketEmitter,
   FeatureFlagType,
   FeatureFlagVariant,
+  FlagConfigurationResponse,
+  FlagDefinition,
   SegmentFunction,
 } from "./types";

package/src/openFeatureProvider.ts

@@ -0,0 +1,141 @@
+import {
+  ErrorCode,
+  type EvaluationContext,
+  type JsonValue,
+  type Logger,
+  OpenFeatureEventEmitter,
+  type Provider,
+  type ResolutionDetails,
+  ServerProviderEvents,
+  StandardResolutionReasons,
+} from "@openfeature/server-sdk";
+import {evaluateFlag} from "./evaluate";
+import type {FeatureFlagModel, SegmentFunction} from "./types";
+
+export interface MongoFeatureFlagProviderOptions {
+  flagModel: FeatureFlagModel;
+  segments?: Record<string, SegmentFunction>;
+}
+
+export class MongoFeatureFlagProvider implements Provider {
+  readonly metadata = {name: "MongoFeatureFlagProvider"} as const;
+  readonly runsOn = "server" as const;
+  readonly events = new OpenFeatureEventEmitter();
+
+  private readonly flagModel: FeatureFlagModel;
+  private readonly segments: Record<string, SegmentFunction>;
+
+  constructor(options: MongoFeatureFlagProviderOptions) {
+    this.flagModel = options.flagModel;
+    this.segments = options.segments ?? {};
+  }
+
+  async resolveBooleanEvaluation(
+    flagKey: string,
+    defaultValue: boolean,
+    context: EvaluationContext,
+    _logger: Logger
+  ): Promise<ResolutionDetails<boolean>> {
+    return this.resolve<boolean>(flagKey, defaultValue, context, "boolean", _logger);
+  }
+
+  async resolveStringEvaluation(
+    flagKey: string,
+    defaultValue: string,
+    context: EvaluationContext,
+    _logger: Logger
+  ): Promise<ResolutionDetails<string>> {
+    return this.resolve<string>(flagKey, defaultValue, context, "variant", _logger);
+  }
+
+  async resolveNumberEvaluation(
+    _flagKey: string,
+    defaultValue: number,
+    _context: EvaluationContext,
+    _logger: Logger
+  ): Promise<ResolutionDetails<number>> {
+    return {
+      errorCode: ErrorCode.FLAG_NOT_FOUND,
+      reason: StandardResolutionReasons.ERROR,
+      value: defaultValue,
+    };
+  }
+
+  async resolveObjectEvaluation<T extends JsonValue>(
+    _flagKey: string,
+    defaultValue: T,
+    _context: EvaluationContext,
+    _logger: Logger
+  ): Promise<ResolutionDetails<T>> {
+    return {
+      errorCode: ErrorCode.FLAG_NOT_FOUND,
+      reason: StandardResolutionReasons.ERROR,
+      value: defaultValue,
+    };
+  }
+
+  emitConfigurationChanged(): void {
+    this.events.emit(ServerProviderEvents.ConfigurationChanged, {flagsChanged: []});
+  }
+
+  private async resolve<T extends boolean | string>(
+    flagKey: string,
+    defaultValue: T,
+    context: EvaluationContext,
+    expectedType: "boolean" | "variant",
+    _logger: Logger
+  ): Promise<ResolutionDetails<T>> {
+    const flag = await this.flagModel.findOneOrNone({archived: {$ne: true}, key: flagKey});
+    if (!flag) {
+      return {
+        errorCode: ErrorCode.FLAG_NOT_FOUND,
+        reason: StandardResolutionReasons.ERROR,
+        value: defaultValue,
+      };
+    }
+
+    if (flag.type !== expectedType) {
+      return {
+        errorCode: ErrorCode.TYPE_MISMATCH,
+        reason: StandardResolutionReasons.ERROR,
+        value: defaultValue,
+      };
+    }
+
+    if (!flag.enabled) {
+      return {
+        reason: StandardResolutionReasons.DISABLED,
+        value: defaultValue,
+        variant: flag.defaultVariant,
+      };
+    }
+
+    const targetingKey = context.targetingKey ?? "";
+    const userFromContext = (context as {user?: unknown}).user;
+    const user = userFromContext !== undefined ? userFromContext : context;
+    const result = evaluateFlag(flag, targetingKey, user, this.segments);
+
+    if (expectedType === "boolean") {
+      const value = result as boolean as T;
+      return {
+        reason: StandardResolutionReasons.TARGETING_MATCH,
+        value,
+        variant: value ? "on" : "off",
+      };
+    }
+
+    if (result === null) {
+      return {
+        reason: StandardResolutionReasons.DISABLED,
+        value: defaultValue,
+        variant: flag.defaultVariant,
+      };
+    }
+
+    return {
+      reason: StandardResolutionReasons.TARGETING_MATCH,
+      value: result as T,
+      variant: result as string,
+    };
+  }
+}

package/src/tests/featureFlagModel.test.ts

@@ -202,6 +202,51 @@ describe("FeatureFlag model", () => {
     const maybe = await FeatureFlag.findOneOrNone({key: "missing-flag"});
     expect(maybe).toBeNull();
   });
+
+  it("auto-fills defaultVariant to off for boolean flags when omitted", async () => {
+    const flag = await FeatureFlag.create({
+      key: "default-variant-bool",
+      name: "Default variant bool",
+    });
+    expect(flag.defaultVariant).toBe("off");
+  });
+
+  it("auto-fills defaultVariant to the first variant key when omitted on variant flags", async () => {
+    const flag = await FeatureFlag.create({
+      key: "default-variant-var",
+      name: "Default variant var",
+      type: "variant",
+      variants: [
+        {key: "control", weight: 40},
+        {key: "treatment", weight: 60},
+      ],
+    });
+    expect(flag.defaultVariant).toBe("control");
+  });
+
+  it("accepts explicit defaultVariant on for boolean flags", async () => {
+    const flag = await FeatureFlag.create({
+      defaultVariant: "on",
+      enabled: true,
+      key: "explicit-on-bool",
+      name: "Explicit on",
+      rolloutPercentage: 100,
+      type: "boolean",
+    });
+    expect(flag.defaultVariant).toBe("on");
+  });
+
+  it("rejects boolean defaultVariant values other than on or off", async () => {
+    await expect(
+      FeatureFlag.create({
+        defaultVariant: "maybe",
+        enabled: true,
+        key: "bad-default-variant",
+        name: "Bad default",
+        type: "boolean",
+      })
+    ).rejects.toMatchObject({title: "Boolean flags must use defaultVariant 'on' or 'off'"});
+  });
 });
 
 describe("featureFlagAdminConfig", () => {
@@ -215,6 +260,7 @@ describe("featureFlagAdminConfig", () => {
       "type",
       "enabled",
       "archived",
+      "defaultVariant",
       "created",
     ]);
   });

package/src/tests/featureFlagsApp.liveUpdates.test.ts

@@ -0,0 +1,114 @@
+import {afterEach, beforeEach, describe, expect, it, mock, spyOn} from "bun:test";
+import EventEmitter from "node:events";
+import {OpenFeature} from "@openfeature/server-sdk";
+import {
+  addAuthRoutes,
+  apiErrorMiddleware,
+  apiUnauthorizedMiddleware,
+  logger,
+  setupAuth,
+  type UserModel as UserModelType,
+} from "@terreno/api";
+import {getBaseServer, setupDb, UserModel} from "@terreno/api/src/tests";
+import type express from "express";
+
+import {FeatureFlag} from "../featureFlagModel";
+import {FeatureFlagsApp} from "../featureFlagsApp";
+
+class FakeChangeStream extends EventEmitter {
+  public close = mock((): Promise<void> => Promise.resolve());
+}
+
+const buildAppWithLive = (options: {
+  eventName?: string;
+  io: {emit: ReturnType<typeof mock>};
+}): express.Application => {
+  const app = getBaseServer();
+  setupAuth(app, UserModel as unknown as UserModelType);
+  addAuthRoutes(app, UserModel as unknown as UserModelType);
+
+  const plugin = new FeatureFlagsApp({
+    liveUpdates: {
+      eventName: options.eventName,
+      socketIoServer: () => options.io,
+    },
+  });
+  plugin.register(app);
+
+  app.use(apiUnauthorizedMiddleware);
+  app.use(apiErrorMiddleware);
+  return app;
+};
+
+describe("FeatureFlagsApp live updates", () => {
+  let watchSpy: ReturnType<typeof spyOn>;
+
+  beforeEach(async () => {
+    await setupDb();
+    await FeatureFlag.deleteMany({});
+  });
+
+  afterEach(async () => {
+    await FeatureFlag.deleteMany({});
+    watchSpy?.mockRestore();
+    await OpenFeature.clearProviders();
+  });
+
+  it("emits the default socket event and payload on change stream events", async () => {
+    const stream = new FakeChangeStream();
+    watchSpy = spyOn(FeatureFlag, "watch").mockReturnValue(stream as never);
+
+    const io = {emit: mock(() => {})};
+    buildAppWithLive({io});
+
+    stream.emit("change", {fullDocument: {key: "todo-summary-card"}});
+
+    expect(io.emit).toHaveBeenCalledWith("featureFlagsChanged", {key: "todo-summary-card"});
+  });
+
+  it("respects a custom liveUpdates.eventName", async () => {
+    const stream = new FakeChangeStream();
+    watchSpy = spyOn(FeatureFlag, "watch").mockReturnValue(stream as never);
+
+    const io = {emit: mock(() => {})};
+    buildAppWithLive({eventName: "flagsUpdated", io});
+
+    stream.emit("change", {fullDocument: {key: "k"}});
+
+    expect(io.emit).toHaveBeenCalledWith("flagsUpdated", {key: "k"});
+  });
+
+  it("logs a warn on stream error, retries once, then disables after a second error", async () => {
+    const warnSpy = spyOn(logger, "warn").mockImplementation(() => {});
+
+    const stream1 = new FakeChangeStream();
+    const stream2 = new FakeChangeStream();
+    let call = 0;
+    watchSpy = spyOn(FeatureFlag, "watch").mockImplementation(() => {
+      call += 1;
+      if (call === 1) {
+        return stream1 as never;
+      }
+      return stream2 as never;
+    });
+
+    const io = {emit: mock(() => {})};
+    buildAppWithLive({io});
+
+    stream1.emit("error", new Error("first"));
+    await new Promise<void>((resolve) => {
+      setTimeout(resolve, 0);
+    });
+    stream2.emit("error", new Error("second"));
+    await new Promise<void>((resolve) => {
+      setTimeout(resolve, 0);
+    });
+
+    const disabledMsg = warnSpy.mock.calls.find(
+      (c) => typeof c[0] === "string" && c[0].includes("change stream disabled")
+    );
+    expect(disabledMsg).toBeDefined();
+
+    warnSpy.mockRestore();
+  });
+});

package/src/tests/featureFlagsApp.test.ts

@@ -1,4 +1,5 @@
 import {afterEach, beforeEach, describe, expect, it} from "bun:test";
+import {OpenFeature} from "@openfeature/server-sdk";
 import {
   addAuthRoutes,
   apiErrorMiddleware,
@@ -43,6 +44,7 @@ describe("FeatureFlagsApp", () => {
 
   afterEach(async () => {
     await FeatureFlag.deleteMany({});
+    await OpenFeature.clearProviders();
   });
 
   describe("construction", () => {
@@ -187,6 +189,105 @@ describe("FeatureFlagsApp", () => {
       // notAdmin isn't admin, rolloutPercentage is 0 → should evaluate false
       expect(notAdminRes.body.data["user-only"]).toBe(false);
     });
+
+    it("includes Deprecation and Sunset headers on GET /evaluate", async () => {
+      await FeatureFlag.create({
+        enabled: true,
+        key: "hdr-flag",
+        name: "Hdr",
+        rolloutPercentage: 100,
+      });
+      adminAgent = await authAsUser(app, "admin");
+      const res = await adminAgent.get("/feature-flags/evaluate").expect(200);
+      expect(res.headers.deprecation).toBe("true");
+      expect(res.headers.sunset).toBeDefined();
+      expect(res.body.data["hdr-flag"]).toBe(true);
+    });
+  });
+
+  describe("GET /feature-flags/flagConfiguration", () => {
+    beforeEach(async () => {
+      const segments: Record<string, SegmentFunction> = {
+        admins: (user: unknown) => (user as {admin?: boolean}).admin === true,
+      };
+      app = buildApp({segments});
+    });
+
+    it("returns 401 when unauthenticated", async () => {
+      const unauth = supertest(app);
+      await unauth.get("/feature-flags/flagConfiguration").expect(401);
+    });
+
+    it("returns OpenFeature-shaped entries for enabled flags and omits disabled and archived", async () => {
+      await FeatureFlag.create({
+        enabled: true,
+        key: "bool-active",
+        name: "Bool",
+        rolloutPercentage: 100,
+        type: "boolean",
+      });
+      await FeatureFlag.create({
+        defaultVariant: "compact",
+        enabled: true,
+        key: "profile",
+        name: "Profile",
+        rules: [],
+        type: "variant",
+        variants: [
+          {key: "compact", weight: 50},
+          {key: "detailed", weight: 50},
+        ],
+      });
+      await FeatureFlag.create({
+        enabled: false,
+        key: "disabled-one",
+        name: "Off",
+        rolloutPercentage: 100,
+        type: "boolean",
+      });
+      await FeatureFlag.create({
+        archived: true,
+        enabled: true,
+        key: "archived-one",
+        name: "Archived",
+        rolloutPercentage: 100,
+        type: "boolean",
+      });
+
+      adminAgent = await authAsUser(app, "admin");
+      const res = await adminAgent.get("/feature-flags/flagConfiguration").expect(200);
+      const data = res.body.data as Record<
+        string,
+        {defaultVariant: string; disabled: boolean; variants: Record<string, boolean | string>}
+      >;
+
+      expect(data["bool-active"]).toEqual({
+        defaultVariant: "on",
+        disabled: false,
+        variants: {off: false, on: true},
+      });
+      expect(data.profile?.disabled).toBe(false);
+      expect(["compact", "detailed"].includes(data.profile?.defaultVariant ?? "")).toBe(true);
+      expect(data.profile?.variants.compact).toBe("compact");
+      expect(data["disabled-one"]).toBeUndefined();
+      expect(data["archived-one"]).toBeUndefined();
+    });
+
+    it("uses resolved boolean variant as defaultVariant (not the persisted schema default alone)", async () => {
+      await FeatureFlag.create({
+        defaultVariant: "off",
+        enabled: true,
+        key: "resolved-bool",
+        name: "Resolved",
+        rolloutPercentage: 100,
+        rules: [],
+        type: "boolean",
+      });
+      adminAgent = await authAsUser(app, "admin");
+      const res = await adminAgent.get("/feature-flags/flagConfiguration").expect(200);
+      expect(res.body.data["resolved-bool"].defaultVariant).toBe("on");
+      expect(res.body.data["resolved-bool"].variants.on).toBe(true);
+    });
   });
 
   describe("GET /feature-flags/segments", () => {