@vercel/flags-core 1.8.1 → 1.9.0-0fd2f41-20260915094243

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @vercel/flags-core
 
+## 1.9.0-0fd2f41-20260915094243
+
+### Minor Changes
+
+- [#498](https://github.com/vercel/flags/pull/498) [`da0b044`](https://github.com/vercel/flags/commit/da0b044c2f2efb1c61900c43f21fa21813a3ef20) Thanks [@luismeyer](https://github.com/luismeyer)! - Add a header-driven `vercel` client mode that uses request config-version timestamps instead of streaming or polling. Reuse fresh definitions, refresh in the background when the request version is up to 10 seconds newer than the cached configuration, and block for a refresh when the gap is larger. Deduplicate concurrent refreshes, allow retries after fetch failures, and discard late responses after shutdown.
+  
+  Add opt-in controller, stream, and header-source diagnostics with `DEBUG=@vercel/flags-core` to show data origins, connection lifecycle, and refresh decisions without logging credentials or flag values.
+
 ## 1.8.1
 
 ### Patch Changes

package/README.md

@@ -12,18 +12,39 @@ npm i @vercel/flags-core
 
 ## Usage
 
+Create a shared client at module scope, but evaluate flags inside a request handler when using Vercel OIDC authentication. `evaluate()` and `bulkEvaluate()` initialize the client automatically on first use; you do not need to call `initialize()` first.
+
+For example, in an Express app deployed to Vercel:
+
 ```ts
+import express from 'express';
 import { createClient } from '@vercel/flags-core';
 
-const client = createClient(process.env.FLAGS!);
-
-await client.initialize();
+const app = express();
+const client = createClient(); // Uses Vercel OIDC; does not initialize yet.
 
-const result = await client.evaluate<boolean>('show-new-feature', false, {
-  user: { id: 'user-123' },
+app.get('/api/feature', async (_req, res) => {
+  const result = await client.evaluate<boolean>('show-new-feature', false);
+  res.json({ enabled: result.value });
 });
+
+export default app;
 ```
 
+Outside Vercel, pass an SDK key explicitly: `createClient(process.env.FLAGS)`.
+
+### Initialization and request-scoped OIDC
+
+On Vercel, the OIDC token can be supplied through the current request context (`x-vercel-oidc-token`). It is not guaranteed to be available while modules are loading. Creating the client at module scope is safe, but starting `client.initialize()` there can attempt authentication before a request exists.
+
+Do not store a module-scope initialization promise and await it later in a handler. Calling `initialize()` starts the work immediately; awaiting the promise inside a request does not move that work into the request context. If the promise rejects, every handler awaiting that same promise will reject before reaching evaluation and its fallback handling.
+
+This also applies when definitions are embedded at build time: with OIDC authentication, the client uses the token's `project_id` claim to select the embedded definitions. An importable `@vercel/flags-definitions` module alone is not enough.
+
+For local development, `vercel env pull` writes an OIDC token to `.env.local`. If your local runner loads that file, the environment-variable fallback can make module-scope initialization appear to work, even though request-scoped authentication on a deployment requires deferring it.
+
+Explicit `await client.initialize()` is optional and can be useful when you want to wait for initialization and handle its errors yourself. Only call it once authentication is available: inside a request handler for request-scoped OIDC, or during startup when using an SDK key or an already-available environment token. For normal flag evaluation, prefer calling `evaluate()` or `bulkEvaluate()` directly in the handler.
+
 ## Evaluation Metrics
 
 To associate evaluation metrics with an environment, pass the
@@ -38,6 +59,30 @@ const client = createClient(process.env.FLAGS!, {
 This option is sent only to the metrics ingestion endpoint. It does not select
 the environment used for flag evaluation.
 
+## Debugging data sources
+
+Set `DEBUG=@vercel/flags-core` in your application's server environment (for
+example, in `.env.local` or the Vercel project's environment variables), then
+restart or redeploy the app:
+
+```bash
+DEBUG=@vercel/flags-core pnpm dev
+```
+
+Debug logs are written with `console.log` and labeled `[controller]`,
+`[stream-source]`, or `[header-source]`. They show initialization settings and
+state transitions, the origin and cache status of each read, stream connections
+and disconnections, and header freshness decisions (`serve-cached`,
+`background-refresh`, or `blocking-refresh`). Missing headers, unmatched projects,
+and invalid timestamps are reported with a reason instead of raw header values.
+
+The controller's `origin` distinguishes `stream`, `poll`, `provided`, `bundled`,
+and `fetched` data; `mode` identifies the active update strategy. Debug metadata
+includes project IDs, revisions, and timestamps, but not SDK keys, tokens, flag
+values, or full datafiles. This setting also enables the existing ingest debug
+logging. Unset `DEBUG` to disable debug output; normal warnings and errors are
+unaffected.
+
 ## OpenFeature
 
 An OpenFeature-compatible provider is available at `@vercel/flags-core/openfeature`:

package/dist/{chunk-5BWCBI7I.js → chunk-FEALIMCH.js}

@@ -573,7 +573,7 @@ function bulkEvaluate(flags, shared) {
 }
 
 // package.json
-var version = "1.8.1";
+var version = "1.9.0-0fd2f41-20260915094243";
 
 // src/lib/report-value.ts
 function internalReportValue(key, value, data) {
@@ -971,6 +971,12 @@ function createCreateRawClient(fns) {
   };
 }
 
+// src/utils/debug.ts
+function debugLog(source, message, details = {}) {
+  if (!process.env.DEBUG?.includes("@vercel/flags-core")) return;
+  console.log(`@vercel/flags-core [${source}] ${message}`, details);
+}
+
 // src/utils/read-bundled-definitions.ts
 var sdkKeyHashCache = /* @__PURE__ */ new Map();
 async function computeHash(sdkKey) {
@@ -1051,7 +1057,7 @@ var MAX_EVENTS_PER_REQUEST = 2e3;
 var EVALUATING_OIDC_TOKEN_HEADER = "X-Vercel-Flags-OIDC-Token";
 var FLUSH_REASON_HEADER = "X-Vercel-Flags-Flush-Reason";
 var isDebugMode = process.env.DEBUG?.includes("@vercel/flags-core");
-var debugLog = (...args) => {
+var debugLog2 = (...args) => {
   if (!isDebugMode) return;
   console.log(...args);
 };
@@ -1097,7 +1103,7 @@ async function sendIngestChunk(options, eventsToSend, flushId, flushReason) {
         headers: await getIngestHeaders(options, flushReason),
         body: JSON.stringify(eventsToSend)
       });
-      debugLog(
+      debugLog2(
         `@vercel/flags-core: Ingest response ${response.status} for ${eventsToSend.length} events on ${response.headers.get("x-vercel-id")}`
       );
       if (response.ok) {
@@ -1494,6 +1500,178 @@ async function fetchDatafile(options) {
   }
 }
 
+// src/controller/header-source.ts
+import { waitUntil as waitUntil3 } from "@vercel/functions";
+
+// src/controller/tagged-data.ts
+function tagData(data, origin) {
+  return Object.assign(data, { _origin: origin });
+}
+function originToMetricsSource(origin) {
+  switch (origin) {
+    case "stream":
+    case "poll":
+    case "provided":
+      return "in-memory";
+    case "fetched":
+      return "remote";
+    case "bundled":
+      return "embedded";
+  }
+}
+
+// src/controller/typed-emitter.ts
+var TypedEmitter = class {
+  handlers = /* @__PURE__ */ new Map();
+  on(event, handler) {
+    let set = this.handlers.get(event);
+    if (!set) {
+      set = /* @__PURE__ */ new Set();
+      this.handlers.set(event, set);
+    }
+    set.add(handler);
+  }
+  off(event, handler) {
+    this.handlers.get(event)?.delete(handler);
+  }
+  emit(event, ...args) {
+    const set = this.handlers.get(event);
+    if (set) {
+      for (const handler of set) {
+        handler(...args);
+      }
+    }
+  }
+};
+
+// src/controller/header-source.ts
+var HeaderSource = class extends TypedEmitter {
+  options;
+  abortController;
+  promise;
+  constructor(options) {
+    super();
+    this.options = options;
+  }
+  fetchDatafile() {
+    if (this.promise) {
+      debugLog("header-source", "Reusing pending refresh");
+      return this.promise;
+    }
+    debugLog("header-source", "Starting refresh");
+    const abortController = new AbortController();
+    this.abortController = abortController;
+    this.promise = fetchDatafile({
+      ...this.options,
+      signal: abortController.signal
+    }).then((data) => {
+      abortController.signal.throwIfAborted();
+      debugLog("header-source", "Refresh completed", {
+        projectId: data.projectId,
+        configUpdatedAt: Number(data.configUpdatedAt),
+        revision: data.revision
+      });
+      this.emit("data", data);
+      return data;
+    }).catch((error) => {
+      debugLog("header-source", "Refresh failed", {
+        aborted: abortController.signal.aborted
+      });
+      throw error;
+    }).finally(() => {
+      if (this.abortController === abortController) {
+        this.promise = void 0;
+        this.abortController = void 0;
+      }
+    });
+    return this.promise;
+  }
+  getUpdatedAtHeader(projectId) {
+    const ctx = getRequestContext();
+    const headerName = ctx.headers?.["x-vercel-edge-config-versions"] != null ? "x-vercel-edge-config-versions" : "edge-config-versions";
+    const header = ctx.headers?.[headerName];
+    if (!header) {
+      debugLog("header-source", "Header unavailable", {
+        projectId,
+        reason: "missing-header"
+      });
+      return;
+    }
+    const prefix = `flags_${projectId}=`;
+    const value = header.split(";").map((part) => part.trim()).find((part) => part.startsWith(prefix))?.slice(prefix.length);
+    const timestamp = Number(value);
+    if (!Number.isFinite(timestamp) || timestamp <= 0) {
+      debugLog("header-source", "Header unavailable", {
+        projectId,
+        headerName,
+        reason: value === void 0 ? "project-not-found" : "invalid-timestamp"
+      });
+      return;
+    }
+    debugLog("header-source", "Header version available", {
+      projectId,
+      headerName,
+      timestamp
+    });
+    return timestamp;
+  }
+  async resolveData(currentData) {
+    if (!currentData.configUpdatedAt) {
+      debugLog("header-source", "Skipping header refresh", {
+        projectId: currentData.projectId,
+        reason: "missing-data-timestamp"
+      });
+      return;
+    }
+    const updatedAtHeader = this.getUpdatedAtHeader(currentData.projectId);
+    if (!updatedAtHeader) {
+      return;
+    }
+    const currentUpdatedAt = Number(currentData.configUpdatedAt);
+    const deltaMs = updatedAtHeader - currentUpdatedAt;
+    debugLog("header-source", "Freshness decision", {
+      projectId: currentData.projectId,
+      currentUpdatedAt,
+      headerUpdatedAt: updatedAtHeader,
+      deltaMs,
+      action: updatedAtHeader <= currentUpdatedAt ? "serve-cached" : updatedAtHeader <= currentUpdatedAt + 1e4 ? "background-refresh" : "blocking-refresh"
+    });
+    if (updatedAtHeader <= currentUpdatedAt) {
+      return [currentData, "HIT"];
+    }
+    if (updatedAtHeader <= currentUpdatedAt + 1e4) {
+      const pending = this.fetchDatafile();
+      const signal = this.abortController?.signal;
+      const background = pending.catch((error) => {
+        if (!signal?.aborted) {
+          console.error("@vercel/flags-core: Header refresh failed:", error);
+        }
+      });
+      waitUntil3(background);
+      return [currentData, "STALE"];
+    }
+    const data = await this.fetchDatafile();
+    return [tagData(data, "fetched"), "MISS"];
+  }
+  read(currentData) {
+    return this.resolveData(currentData);
+  }
+  isAvailable(projectId) {
+    return !!this.getUpdatedAtHeader(projectId);
+  }
+  /**
+   * Abort the current header-driven fetch and discard its pending work.
+   */
+  stop() {
+    debugLog("header-source", "Stopping header refresh", {
+      pending: this.promise !== void 0
+    });
+    this.abortController?.abort();
+    this.abortController = void 0;
+    this.promise = void 0;
+  }
+};
+
 // src/controller/normalized-options.ts
 var DEFAULT_STREAM_INIT_TIMEOUT_MS = 3e3;
 var DEFAULT_POLLING_INTERVAL_MS = 3e4;
@@ -1545,30 +1723,6 @@ function normalizeOptions(options) {
   };
 }
 
-// src/controller/typed-emitter.ts
-var TypedEmitter = class {
-  handlers = /* @__PURE__ */ new Map();
-  on(event, handler) {
-    let set = this.handlers.get(event);
-    if (!set) {
-      set = /* @__PURE__ */ new Set();
-      this.handlers.set(event, set);
-    }
-    set.add(handler);
-  }
-  off(event, handler) {
-    this.handlers.get(event)?.delete(handler);
-  }
-  emit(event, ...args) {
-    const set = this.handlers.get(event);
-    if (set) {
-      for (const handler of set) {
-        handler(...args);
-      }
-    }
-  }
-};
-
 // src/controller/polling-source.ts
 var PollingSource = class extends TypedEmitter {
   config;
@@ -1854,7 +2008,11 @@ var StreamSource = class extends TypedEmitter {
    * If already started, returns the existing promise.
    */
   start() {
-    if (this.promise) return this.promise;
+    if (this.promise) {
+      debugLog("stream-source", "Reusing stream connection");
+      return this.promise;
+    }
+    debugLog("stream-source", "Starting stream connection");
     const abortController = new AbortController();
     this.abortController = abortController;
     abortController.signal.addEventListener(
@@ -1878,21 +2036,41 @@ var StreamSource = class extends TypedEmitter {
         },
         {
           onDatafile: (newData) => {
+            debugLog("stream-source", "Connected with datafile", {
+              projectId: newData.projectId,
+              configUpdatedAt: Number(newData.configUpdatedAt),
+              revision: newData.revision
+            });
             this.emit("data", newData);
             this.emit("connected");
           },
           onPrimed: (message) => {
+            debugLog("stream-source", "Connected with current revision", {
+              projectId: message.projectId,
+              revision: message.revision
+            });
             this.emit("primed", message);
             this.emit("connected");
           },
           onDisconnect: () => {
+            debugLog("stream-source", "Disconnected", {
+              aborted: abortController.signal.aborted
+            });
             this.emit("disconnected");
           }
         }
       );
-      this.promise = promise;
-      return promise;
+      this.promise = promise.catch((error) => {
+        debugLog("stream-source", "Stream initialization failed", {
+          aborted: abortController.signal.aborted
+        });
+        throw error;
+      });
+      return this.promise;
     } catch (error) {
+      debugLog("stream-source", "Stream initialization failed", {
+        aborted: abortController.signal.aborted
+      });
       this.promise = void 0;
       this.abortController = void 0;
       throw error;
@@ -1902,29 +2080,15 @@ var StreamSource = class extends TypedEmitter {
    * Stop the stream connection.
    */
   stop() {
+    debugLog("stream-source", "Stopping stream connection", {
+      active: this.abortController !== void 0
+    });
     this.abortController?.abort();
     this.abortController = void 0;
     this.promise = void 0;
   }
 };
 
-// src/controller/tagged-data.ts
-function tagData(data, origin) {
-  return Object.assign(data, { _origin: origin });
-}
-function originToMetricsSource(origin) {
-  switch (origin) {
-    case "stream":
-    case "poll":
-    case "provided":
-      return "in-memory";
-    case "fetched":
-      return "remote";
-    case "bundled":
-      return "embedded";
-  }
-}
-
 // src/controller/index.ts
 function parseConfigUpdatedAt(value) {
   if (typeof value === "number") return value;
@@ -1949,6 +2113,7 @@ var Controller = class {
   streamSource;
   pollingSource;
   bundledSource;
+  headerSource;
   // Usage tracking
   usageTracker;
   isFirstGetData = true;
@@ -1968,6 +2133,7 @@ var Controller = class {
       auth: this.options.auth,
       readBundledDefinitions
     });
+    this.headerSource = new HeaderSource(this.options);
     this.wireSourceEvents();
     if (this.options.datafile) {
       this.data = tagData(this.options.datafile, "provided");
@@ -2003,6 +2169,11 @@ var Controller = class {
   onPollError = (error) => {
     console.error("@vercel/flags-core: Poll failed:", error);
   };
+  onFetchedData = (data) => {
+    if (this.isNewerData(data)) {
+      this.data = tagData(data, "fetched");
+    }
+  };
   // ---------------------------------------------------------------------------
   // Source event wiring
   // ---------------------------------------------------------------------------
@@ -2013,6 +2184,7 @@ var Controller = class {
     this.streamSource.on("disconnected", this.onStreamDisconnected);
     this.pollingSource.on("data", this.onPollData);
     this.pollingSource.on("error", this.onPollError);
+    this.headerSource.on("data", this.onFetchedData);
   }
   unwireSourceEvents() {
     this.streamSource.off("data", this.onStreamData);
@@ -2021,11 +2193,18 @@ var Controller = class {
     this.streamSource.off("disconnected", this.onStreamDisconnected);
     this.pollingSource.off("data", this.onPollData);
     this.pollingSource.off("error", this.onPollError);
+    this.headerSource.off("data", this.onFetchedData);
   }
   // ---------------------------------------------------------------------------
   // State machine
   // ---------------------------------------------------------------------------
   transition(to) {
+    debugLog("controller", "State changed", {
+      from: this.state,
+      to,
+      projectId: this.data?.projectId,
+      origin: this.data?._origin
+    });
     this.state = to;
   }
   get isConnected() {
@@ -2038,6 +2217,8 @@ var Controller = class {
         return "streaming";
       case "polling":
         return "polling";
+      case "vercel":
+        return "vercel";
       default:
         return "offline";
     }
@@ -2054,6 +2235,14 @@ var Controller = class {
    * Offline mode (neither): datafile → bundled → one-time fetch
    */
   async initialize() {
+    debugLog("controller", "Initializing", {
+      buildStep: this.options.buildStep,
+      streamEnabled: this.options.stream.enabled,
+      pollingEnabled: this.options.polling.enabled,
+      hasData: this.data !== void 0,
+      projectId: this.data?.projectId,
+      origin: this.data?._origin
+    });
     if (this.options.buildStep) {
       this.transition("build:loading");
       await this.initializeForBuildStep();
@@ -2073,7 +2262,9 @@ var Controller = class {
       }
     }
     if (this.data) {
-      if (this.options.stream.enabled) {
+      if (this.headerSource.isAvailable(this.data.projectId)) {
+        this.transition("vercel");
+      } else if (this.options.stream.enabled) {
         this.transition("initializing:stream");
         await this.tryInitializeStream();
       } else if (this.options.polling.enabled) {
@@ -2084,6 +2275,9 @@ var Controller = class {
       }
       return;
     }
+    debugLog("controller", "Header mode unavailable", {
+      reason: "no-definitions"
+    });
     if (this.options.stream.enabled) {
       this.transition("initializing:stream");
       const streamSuccess = await this.tryInitializeStream();
@@ -2112,6 +2306,15 @@ var Controller = class {
     const [result, cacheStatus] = await this.resolveData();
     const readMs = Date.now() - startTime;
     const source = originToMetricsSource(result._origin);
+    debugLog("controller", "Read resolved", {
+      projectId: result.projectId,
+      mode: this.mode,
+      source,
+      origin: result._origin,
+      cacheStatus,
+      configUpdatedAt: parseConfigUpdatedAt(result.configUpdatedAt),
+      revision: result.revision
+    });
     this.trackRead(startTime, cacheHadDefinitions, isFirstRead, source);
     if (this.dataViewSource !== result) {
       const { _origin, ...rest } = result;
@@ -2136,6 +2339,7 @@ var Controller = class {
     this.unwireSourceEvents();
     this.streamSource.stop();
     this.pollingSource.stop();
+    this.headerSource.stop();
     this.data = this.options.datafile ? tagData(this.options.datafile, "provided") : void 0;
     this.transition("shutdown");
     await this.usageTracker.shutdown();
@@ -2179,6 +2383,15 @@ var Controller = class {
       }
     }
     const source = originToMetricsSource(result._origin);
+    debugLog("controller", "Datafile resolved", {
+      projectId: result.projectId,
+      mode: this.mode,
+      source,
+      origin: result._origin,
+      cacheStatus,
+      configUpdatedAt: parseConfigUpdatedAt(result.configUpdatedAt),
+      revision: result.revision
+    });
     if (this.dataViewSource !== result) {
       const { _origin, ...rest } = result;
       this.dataViewBase = rest;
@@ -2217,6 +2430,12 @@ var Controller = class {
       return this.resolveDataForBuildStep();
     }
     if (this.data) {
+      if (this.mode === "vercel") {
+        const result = await this.headerSource.read(this.data);
+        if (result) {
+          return result;
+        }
+      }
       const cacheStatus = this.isConnected ? "HIT" : "STALE";
       return [this.data, cacheStatus];
     }
@@ -2255,6 +2474,14 @@ var Controller = class {
       ]);
       clearTimeout(timeoutId);
       if (result === "timeout") {
+        debugLog(
+          "controller",
+          "Stream initialization timed out; using fallback",
+          {
+            timeoutMs: this.options.stream.initTimeoutMs,
+            origin: this.data?._origin
+          }
+        );
         console.warn(
           "@vercel/flags-core: Stream initialization timeout, falling back while continuing to connect in the background"
         );
@@ -2673,4 +2900,4 @@ export {
   resetDefaultFlagsClient,
   createClient
 };
-//# sourceMappingURL=chunk-5BWCBI7I.js.map
+//# sourceMappingURL=chunk-FEALIMCH.js.map