@vercel/flags-core 1.8.1 → 1.9.0-004baf8-20260915082635

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @vercel/flags-core
 
+## 1.9.0-004baf8-20260915082635
+
+### 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.
+
 ## 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

package/dist/{chunk-DYSF37WV.js → chunk-KURHLZJF.js}

@@ -558,7 +558,7 @@ function bulkEvaluate(flags, shared) {
 }
 
 // package.json
-var version = "1.8.1";
+var version = "1.9.0-004baf8-20260915082635";
 
 // src/lib/report-value.ts
 function internalReportValue(key, value, data) {
@@ -1479,6 +1479,131 @@ 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) return this.promise;
+    const abortController = new AbortController();
+    this.abortController = abortController;
+    this.promise = fetchDatafile({
+      ...this.options,
+      signal: abortController.signal
+    }).then((data) => {
+      abortController.signal.throwIfAborted();
+      this.emit("data", data);
+      return data;
+    }).finally(() => {
+      if (this.abortController === abortController) {
+        this.promise = void 0;
+        this.abortController = void 0;
+      }
+    });
+    return this.promise;
+  }
+  getUpdatedAtHeader(projectId) {
+    const ctx = getRequestContext();
+    const header = ctx.headers?.["x-vercel-edge-config-versions"] ?? ctx.headers?.["edge-config-versions"];
+    if (!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);
+    return Number.isFinite(timestamp) && timestamp > 0 ? timestamp : void 0;
+  }
+  async resolveData(currentData) {
+    if (!currentData.configUpdatedAt) {
+      return;
+    }
+    const updatedAtHeader = this.getUpdatedAtHeader(currentData.projectId);
+    if (!updatedAtHeader) {
+      return;
+    }
+    const currentUpdatedAt = Number(currentData.configUpdatedAt);
+    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() {
+    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;
@@ -1530,30 +1655,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;
@@ -1893,23 +1994,6 @@ var StreamSource = class extends TypedEmitter {
   }
 };
 
-// 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;
@@ -1934,6 +2018,7 @@ var Controller = class {
   streamSource;
   pollingSource;
   bundledSource;
+  headerSource;
   // Usage tracking
   usageTracker;
   isFirstGetData = true;
@@ -1953,6 +2038,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");
@@ -1988,6 +2074,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
   // ---------------------------------------------------------------------------
@@ -1998,6 +2089,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);
@@ -2006,6 +2098,7 @@ 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
@@ -2023,6 +2116,8 @@ var Controller = class {
         return "streaming";
       case "polling":
         return "polling";
+      case "vercel":
+        return "vercel";
       default:
         return "offline";
     }
@@ -2058,7 +2153,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) {
@@ -2121,6 +2218,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();
@@ -2202,6 +2300,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];
     }
@@ -2683,4 +2787,4 @@ export {
   resetDefaultFlagsClient,
   createClient
 };
-//# sourceMappingURL=chunk-DYSF37WV.js.map
+//# sourceMappingURL=chunk-KURHLZJF.js.map