@vellumai/vellum-gateway 0.6.1 → 0.6.2

package/Dockerfile

@@ -20,6 +20,8 @@ WORKDIR /app
 
 RUN apt-get update && apt-get upgrade -y && apt-get install -y \
     ca-certificates \
+    iproute2 \
+    procps \
     && rm -rf /var/lib/apt/lists/*
 
 # Copy bun binary from builder

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/vellum-gateway",
-  "version": "0.6.1",
+  "version": "0.6.2",
   "license": "MIT",
   "type": "module",
   "exports": {

package/src/__tests__/feature-flags-route.test.ts

@@ -97,7 +97,7 @@ const {
 } = await import("../feature-flag-defaults.js");
 const { clearFeatureFlagStoreCache, readPersistedFeatureFlags } =
   await import("../feature-flag-store.js");
-const { clearRemoteFeatureFlagStoreCache } =
+const { clearRemoteFeatureFlagStoreCache, writeRemoteFeatureFlags } =
   await import("../feature-flag-remote-store.js");
 
 describe("GET /v1/feature-flags handler", () => {
@@ -337,6 +337,43 @@ describe("GET /v1/feature-flags handler", () => {
     expect(emailFlag.enabled).toBe(false);
   });
 
+  test("reflects updated flags after remote sync writes new values (stale cache regression)", async () => {
+    // Scenario: the LD poller (RemoteFeatureFlagSync) writes
+    // email-channel: false, the gateway caches it, then a subsequent
+    // poll writes email-channel: true. The GET handler should return
+    // the updated value because writeRemoteFeatureFlags() updates
+    // both disk and the in-memory cache.
+
+    // Step 1: First poll writes email-channel: false (simulated via
+    // writeRemoteFeatureFlags, which is what the poller calls internally).
+    writeRemoteFeatureFlags({ "email-channel": false });
+
+    const handler = createFeatureFlagsGetHandler();
+    const res1 = await handler(
+      new Request("http://gateway.test/v1/feature-flags"),
+    );
+    const body1 = await res1.json();
+    const emailFlag1 = body1.flags.find(
+      (f: { key: string }) => f.key === "email-channel",
+    );
+    expect(emailFlag1.enabled).toBe(false);
+
+    // Step 2: Second poll writes email-channel: true — the poller
+    // calls writeRemoteFeatureFlags which updates file + cache.
+    writeRemoteFeatureFlags({ "email-channel": true });
+
+    // Step 3: The GET handler should immediately reflect the update
+    // without needing a file-watcher round-trip.
+    const res2 = await handler(
+      new Request("http://gateway.test/v1/feature-flags"),
+    );
+    const body2 = await res2.json();
+    const emailFlag2 = body2.flags.find(
+      (f: { key: string }) => f.key === "email-channel",
+    );
+    expect(emailFlag2.enabled).toBe(true);
+  });
+
   test("registry default used when neither local nor remote is set", async () => {
     // No local override
     if (existsSync(featureFlagStorePath)) {

package/src/__tests__/remote-feature-flag-sync.test.ts

@@ -487,4 +487,97 @@ describe("RemoteFeatureFlagSync", () => {
     const headers = init?.headers as Record<string, string>;
     expect(headers.Authorization).toBe("Api-Key trimmed-key");
   });
+
+  test("polls with backoff when initial fetch fails, then snaps to steady-state on success", async () => {
+    // Simulate: first two fetches fail (missing creds), third succeeds.
+    let callCount = 0;
+    const credsFn = async (key: string) => {
+      callCount++;
+      // First 6 calls = 2 attempts × 3 credential reads each → missing API key.
+      // After that, credentials are available.
+      if (callCount <= 6) {
+        if (key === "credential/vellum/assistant_api_key") return undefined;
+        return defaultCredentials()[key];
+      }
+      return defaultCredentials()[key];
+    };
+    const creds = { get: credsFn } as unknown as CredentialCache;
+
+    fetchMock = mock(async () =>
+      Response.json({ flags: { "backoff-flag": true } }),
+    );
+
+    const sync = new RemoteFeatureFlagSync({
+      credentials: creds,
+      initialPollIntervalMs: 50,
+    });
+    await sync.start();
+
+    // Initial fetch failed (missing creds) — no fetch calls yet
+    expect(fetchMock).not.toHaveBeenCalled();
+
+    // Wait for first poll (50ms) — still fails (creds still missing)
+    await new Promise((r) => setTimeout(r, 80));
+    expect(fetchMock).not.toHaveBeenCalled();
+
+    // Wait for second poll (100ms = 50ms doubled) — creds now available
+    await new Promise((r) => setTimeout(r, 130));
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+
+    clearRemoteFeatureFlagStoreCache();
+    expect(readRemoteFeatureFlags()).toEqual({ "backoff-flag": true });
+
+    sync.stop();
+  });
+
+  test("snaps to steady-state interval immediately when initial fetch succeeds", async () => {
+    fetchMock = mock(async () => Response.json({ flags: { "ok-flag": true } }));
+
+    const sync = new RemoteFeatureFlagSync({
+      credentials: fakeCredentialCache(defaultCredentials()),
+      initialPollIntervalMs: 50,
+    });
+    await sync.start();
+
+    // Initial fetch succeeded — 1 call
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+
+    // Wait past what would be the initial poll interval — should NOT poll
+    // again because the interval snapped to steady-state (5 min)
+    await new Promise((r) => setTimeout(r, 100));
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+
+    sync.stop();
+  });
+
+  test("doubles poll interval on consecutive failures", async () => {
+    // Always fail — missing creds
+    const creds = defaultCredentials();
+    delete creds["credential/vellum/assistant_api_key"];
+
+    fetchMock = mock(async () => Response.json({ flags: {} }));
+
+    const sync = new RemoteFeatureFlagSync({
+      credentials: fakeCredentialCache(creds),
+      initialPollIntervalMs: 50,
+    });
+    await sync.start();
+
+    // No fetch calls (missing creds)
+    expect(fetchMock).not.toHaveBeenCalled();
+
+    // After 50ms: first poll fires, still fails → interval doubles to 100ms
+    await new Promise((r) => setTimeout(r, 80));
+    expect(fetchMock).not.toHaveBeenCalled();
+
+    // After another 100ms: second poll fires, still fails → interval doubles to 200ms
+    await new Promise((r) => setTimeout(r, 130));
+    expect(fetchMock).not.toHaveBeenCalled();
+
+    // After another 200ms: third poll fires
+    await new Promise((r) => setTimeout(r, 230));
+    expect(fetchMock).not.toHaveBeenCalled();
+
+    sync.stop();
+  });
 });

package/src/feature-flag-registry.json

@@ -126,8 +126,8 @@
       "scope": "macos",
       "key": "referral-codes",
       "label": "Referral Codes",
-      "description": "Show the referral invite link and stats panel on the Billing tab in Settings",
-      "defaultEnabled": false
+      "description": "Surface the Earn Credits referral entry points (sidebar drawer row and Billing tab button) that open the referral modal",
+      "defaultEnabled": true
     },
     {
       "id": "managed-sign-in",

package/src/feature-flag-remote-store.ts

@@ -114,6 +114,25 @@ export function writeRemoteFeatureFlags(values: Record<string, boolean>): void {
   log.info({ count: Object.keys(values).length }, "Wrote remote feature flags");
 }
 
+/**
+ * Clear the in-memory cache so the next `readRemoteFeatureFlags()` call
+ * re-reads from disk. Useful in tests for resetting state between cases.
+ */
 export function clearRemoteFeatureFlagStoreCache(): void {
   cachedRemoteValues = null;
 }
+
+/**
+ * Re-read the remote feature flag file from disk into the in-memory cache.
+ *
+ * Called by the file watcher when `feature-flags-remote.json` changes on
+ * disk (e.g. written by a separate process or a previous gateway instance).
+ * This ensures the next `readRemoteFeatureFlags()` call returns fresh data
+ * without requiring every read to hit disk.
+ */
+export function refreshRemoteFeatureFlagStoreCache(): void {
+  cachedRemoteValues = null;
+  // Force a re-read into cache immediately so the next
+  // readRemoteFeatureFlags() call picks up the new values.
+  readRemoteFeatureFlags();
+}

package/src/feature-flag-watcher.ts

@@ -1,6 +1,6 @@
 /**
- * Watches feature-flags.json for external modifications and invalidates the
- * module-level cache in feature-flag-store.ts.
+ * Watches feature flag files for external modifications and invalidates /
+ * refreshes the corresponding module-level caches.
  *
  * Uses the same fs.watch() + debounce pattern as CredentialWatcher and
  * ConfigFileWatcher. Watches the parent directory (not the file itself)
@@ -15,6 +15,10 @@ import {
   clearFeatureFlagStoreCache,
   getFeatureFlagStorePath,
 } from "./feature-flag-store.js";
+import {
+  refreshRemoteFeatureFlagStoreCache,
+  getRemoteFeatureFlagStorePath,
+} from "./feature-flag-remote-store.js";
 import { getLogger } from "./logger.js";
 
 const log = getLogger("feature-flag-watcher");
@@ -24,16 +28,18 @@ const DEBOUNCE_MS = 500;
 export class FeatureFlagWatcher {
   private watcher: FSWatcher | null = null;
   private debounceTimer: ReturnType<typeof setTimeout> | null = null;
-  private flagPath: string;
-  private flagFilename: string;
+  private localFlagFilename: string;
+  private remoteFlagFilename: string;
+  /** Accumulates which files changed during the debounce window. */
+  private pendingFilenames = new Set<string>();
 
   constructor() {
-    this.flagPath = getFeatureFlagStorePath();
-    this.flagFilename = basename(this.flagPath);
+    this.localFlagFilename = basename(getFeatureFlagStorePath());
+    this.remoteFlagFilename = basename(getRemoteFeatureFlagStorePath());
   }
 
   start(): void {
-    const dir = dirname(this.flagPath);
+    const dir = dirname(getFeatureFlagStorePath());
 
     // Ensure the directory exists so fs.watch() doesn't throw ENOENT
     // on a fresh instance where no flags have been persisted yet.
@@ -43,10 +49,14 @@ export class FeatureFlagWatcher {
 
     try {
       this.watcher = watch(dir, { persistent: false }, (_event, filename) => {
-        if (filename && filename !== this.flagFilename) {
+        if (
+          filename &&
+          filename !== this.localFlagFilename &&
+          filename !== this.remoteFlagFilename
+        ) {
           return;
         }
-        this.scheduleInvalidation();
+        this.scheduleInvalidation(filename ?? undefined);
       });
 
       log.info({ path: dir }, "Watching for feature flag file changes");
@@ -66,14 +76,30 @@ export class FeatureFlagWatcher {
     }
   }
 
-  private scheduleInvalidation(): void {
+  private scheduleInvalidation(filename?: string): void {
+    if (filename) {
+      this.pendingFilenames.add(filename);
+    }
+
     if (this.debounceTimer) {
       clearTimeout(this.debounceTimer);
     }
     this.debounceTimer = setTimeout(() => {
       this.debounceTimer = null;
-      clearFeatureFlagStoreCache();
-      log.info("Feature flag cache invalidated due to file change");
+
+      const filenames = this.pendingFilenames;
+      this.pendingFilenames = new Set<string>();
+
+      if (filenames.has(this.localFlagFilename)) {
+        clearFeatureFlagStoreCache();
+      }
+      if (filenames.has(this.remoteFlagFilename)) {
+        refreshRemoteFeatureFlagStoreCache();
+      }
+      log.info(
+        { filenames: [...filenames] },
+        "Feature flag cache invalidated due to file change",
+      );
     }, DEBOUNCE_MS);
   }
 }

package/src/remote-feature-flag-sync.ts

@@ -8,14 +8,21 @@ import { getLogger } from "./logger.js";
 const log = getLogger("remote-feature-flag-sync");
 
 /**
- * Default polling interval: 5 minutes.
+ * Steady-state polling interval: 5 minutes.
  *
  * Configurable via `REMOTE_FF_POLL_INTERVAL_MS` env var for testing or
  * deployment tuning.
  */
 const DEFAULT_POLL_INTERVAL_MS = 5 * 60 * 1000;
 
-function getPollIntervalMs(): number {
+/**
+ * Initial polling interval when the first fetch fails (e.g. CES sidecar
+ * not ready yet). Doubles on each consecutive failure until it reaches
+ * the steady-state interval.
+ */
+const INITIAL_POLL_INTERVAL_MS = 10_000;
+
+function getMaxPollIntervalMs(): number {
   const envVal = process.env.REMOTE_FF_POLL_INTERVAL_MS;
   if (envVal) {
     const parsed = parseInt(envVal, 10);
@@ -27,63 +34,114 @@ function getPollIntervalMs(): number {
 export type RemoteFeatureFlagSyncConfig = {
   /** Credential cache for resolving platform URL, API key, and assistant ID dynamically. */
   credentials: CredentialCache;
+  /** Override the initial poll interval (ms) — useful for testing. Defaults to 10 000. */
+  initialPollIntervalMs?: number;
 };
 
 /**
  * Manages the lifecycle of syncing remote feature flags from the platform.
  *
  * On start, fetches the current flag state and persists it to disk via the
- * remote feature flag store, then polls on a configurable interval. Errors
- * are caught and logged — the system falls through to registry defaults if
- * this fails.
+ * remote feature flag store, then polls with adaptive back-off: starts at
+ * {@link INITIAL_POLL_INTERVAL_MS} and doubles on each failure until it
+ * reaches the steady-state interval. On the first success the interval
+ * snaps to steady-state immediately.
  */
 export class RemoteFeatureFlagSync {
   private started = false;
-  private pollTimer: ReturnType<typeof setInterval> | null = null;
+  private pollTimer: ReturnType<typeof setTimeout> | null = null;
+  private currentIntervalMs: number;
+  private readonly maxIntervalMs: number;
   private readonly credentials: CredentialCache;
 
   constructor(config: RemoteFeatureFlagSyncConfig) {
     this.credentials = config.credentials;
+    this.currentIntervalMs =
+      config.initialPollIntervalMs ?? INITIAL_POLL_INTERVAL_MS;
+    this.maxIntervalMs = getMaxPollIntervalMs();
   }
 
   async start(): Promise<void> {
     this.started = true;
 
+    let ok = false;
     try {
-      await this.fetchAndCache();
+      ok = await this.fetchAndCache();
     } catch (err) {
       log.warn({ err }, "Failed to sync remote feature flags on startup");
     }
 
-    const intervalMs = getPollIntervalMs();
-    this.pollTimer = setInterval(() => {
-      this.fetchAndCache().catch((err) => {
-        log.warn({ err }, "Failed to sync remote feature flags during poll");
-      });
-    }, intervalMs);
+    if (ok) {
+      // First fetch succeeded — jump straight to steady-state polling.
+      this.currentIntervalMs = this.maxIntervalMs;
+    }
 
-    log.info({ intervalMs }, "Remote feature flag polling started");
+    this.scheduleNextPoll();
+    log.info(
+      { intervalMs: this.currentIntervalMs },
+      "Remote feature flag polling started",
+    );
   }
 
   stop(): void {
     this.started = false;
     if (this.pollTimer) {
-      clearInterval(this.pollTimer);
+      clearTimeout(this.pollTimer);
       this.pollTimer = null;
     }
   }
 
-  private async fetchAndCache(): Promise<void> {
+  private scheduleNextPoll(): void {
+    this.pollTimer = setTimeout(() => {
+      this.poll();
+    }, this.currentIntervalMs);
+  }
+
+  private poll(): void {
+    if (!this.started) return;
+    this.fetchAndCache()
+      .then((ok) => {
+        if (ok) {
+          // Success — snap to steady-state interval.
+          this.currentIntervalMs = this.maxIntervalMs;
+        } else {
+          // Failure — double the interval, capped at max.
+          this.currentIntervalMs = Math.min(
+            this.currentIntervalMs * 2,
+            this.maxIntervalMs,
+          );
+        }
+      })
+      .catch((err) => {
+        log.warn({ err }, "Failed to sync remote feature flags during poll");
+        this.currentIntervalMs = Math.min(
+          this.currentIntervalMs * 2,
+          this.maxIntervalMs,
+        );
+      })
+      .finally(() => {
+        if (this.started) {
+          this.scheduleNextPoll();
+        }
+      });
+  }
+
+  /**
+   * Fetch remote flags and write them to the store.
+   * Returns true if flags were successfully written, false otherwise.
+   */
+  private async fetchAndCache(): Promise<boolean> {
     const values = await this.fetchRemoteFeatureFlags();
     if (values === null) {
-      log.debug("Skipping cache write — fetch returned no usable data");
-      return;
+      log.warn("Skipping cache write — fetch returned no usable data");
+      return false;
     }
     writeRemoteFeatureFlags(values);
     log.info(
       { count: Object.keys(values).length },
       "Synced remote feature flags",
     );
+    return true;
   }
 
   private async fetchRemoteFeatureFlags(): Promise<Record<