@vercel/flags-core 1.4.0 → 1.5.0-1602289-20260528072704

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # @vercel/flags-core
 
+## 1.5.0-1602289-20260528072704
+
+### Minor Changes
+
+- [#371](https://github.com/vercel/flags/pull/371) [`bd4d01a`](https://github.com/vercel/flags/commit/bd4d01a9b2b5d70bf7ae62cda645d8cd7292ad83) Thanks [@vincent-derks](https://github.com/vincent-derks)! - Add jitter to ingest retries and the batch-flush window.
+
+  The usage tracker now uses AWS-style "Full Jitter" exponential backoff between
+  retry attempts (replacing the previous deterministic 100/200ms schedule) and
+  randomizes the 5s batch-flush window by ±20% to desynchronize concurrent
+  processes. When all retry attempts are exhausted the SDK now logs a structured
+  warning so consumers can alert on dropped batches.
+
+- [#390](https://github.com/vercel/flags/pull/390) [`503ac50`](https://github.com/vercel/flags/commit/503ac5077588b9d641b751f48df8575cb6993556) Thanks [@luismeyer](https://github.com/luismeyer)! - Add OIDC authentication support for Vercel Flags clients and generated flag definitions.
+
+  `@vercel/flags-core` can now create clients without an SDK key and authenticate with a Vercel OIDC token, while still supporting SDK keys and connection strings. Bundled definitions can be looked up by SDK key hash or OIDC project ID.
+
+  `@vercel/prepare-flags-definitions` now collects both SDK keys and `VERCEL_OIDC_TOKEN`, fetches definitions for each auth entry, deduplicates identical definitions across SDK keys and OIDC project IDs, and writes generated maps keyed by SDK key hash or project ID.
+
+  `@flags-sdk/vercel` now supports provider data lookup for Vercel flag origins that do not include an SDK key, allowing OIDC-backed clients to resolve project metadata.
+
+### Patch Changes
+
+- [#382](https://github.com/vercel/flags/pull/382) [`4d90e91`](https://github.com/vercel/flags/commit/4d90e912a4d7c9d4ef986d5e8dc609c30b203242) Thanks [@dferber90](https://github.com/dferber90)! - Speed up flag evaluation on the hot path.
+
+  - `handleOutcome` no longer recomputes `scaledWeights` on every split-outcome evaluation; the per-outcome scaled weights are cached on first call.
+  - `matchConditions` no longer recompiles `RegExp` on every REGEX / NOT_REGEX condition; the compiled regex is cached on first call.
+  - `Controller.read()` and `getDatafile()` no longer re-destructure and re-spread the in-memory datafile on every call; the result is cached and rebuilt only when stream/poll replaces the underlying data.
+
+  In micro-benchmarks the pure `evaluate()` path is ~22% faster for split outcomes and ~32% faster for regex conditions. The full `client.evaluate()` path is 14–22% faster across all scenarios.
+
 ## 1.4.0
 
 ### Minor Changes

package/dist/{chunk-2F6JQ5SL.js → chunk-COEI5LTV.js}

@@ -32,6 +32,24 @@ var Packed;
 
 // src/evaluate.ts
 var MAX_REGEX_INPUT_LENGTH = 1e4;
+var UINT32_MAX = 4294967295;
+var SCALED_WEIGHTS = /* @__PURE__ */ Symbol("@vercel/flags-core:scaledWeights");
+var COMPILED_REGEX = /* @__PURE__ */ Symbol("@vercel/flags-core:compiledRegex");
+function getScaledWeights(outcome) {
+  const cached = outcome[SCALED_WEIGHTS];
+  if (cached) return cached;
+  const total = sum(outcome.weights);
+  const scaled = outcome.weights.map((w) => w / total * UINT32_MAX);
+  outcome[SCALED_WEIGHTS] = scaled;
+  return scaled;
+}
+function getCompiledRegex(rhs) {
+  const cached = rhs[COMPILED_REGEX];
+  if (cached) return cached;
+  const compiled = new RegExp(rhs.pattern, rhs.flags);
+  rhs[COMPILED_REGEX] = compiled;
+  return compiled;
+}
 function exhaustivenessCheck(_) {
   throw new Error("Exhaustiveness check failed");
 }
@@ -218,12 +236,12 @@ function matchConditions(conditions, params) {
           return (isNumber(rhs) || isString(rhs)) && lhs <= rhs;
         case "regex" /* REGEX */:
           if (isString(lhs) && lhs.length <= MAX_REGEX_INPUT_LENGTH && typeof rhs === "object" && !Array.isArray(rhs) && rhs?.type === "regex") {
-            return new RegExp(rhs.pattern, rhs.flags).test(lhs);
+            return getCompiledRegex(rhs).test(lhs);
           }
           return false;
         case "!regex" /* NOT_REGEX */:
           if (isString(lhs) && lhs.length <= MAX_REGEX_INPUT_LENGTH && typeof rhs === "object" && !Array.isArray(rhs) && rhs?.type === "regex") {
-            return !new RegExp(rhs.pattern, rhs.flags).test(lhs);
+            return !getCompiledRegex(rhs).test(lhs);
           }
           return false;
         case "before" /* BEFORE */: {
@@ -295,13 +313,9 @@ function handleOutcome(params, outcome) {
       if (typeof lhs !== "string") {
         return { value: defaultOutcome, outcomeType: "split" /* SPLIT */ };
       }
-      const maxValue = 4294967295;
       const value = hashInput(lhs, params.definition.seed);
-      const sumOfWeights = sum(outcome.weights);
-      const scaledWeights = outcome.weights.map(
-        (weight) => weight / sumOfWeights * maxValue
-      );
-      const variantIndex = findWeightedIndex(scaledWeights, value, maxValue);
+      const scaledWeights = getScaledWeights(outcome);
+      const variantIndex = findWeightedIndex(scaledWeights, value, UINT32_MAX);
       return {
         value: variantIndex === -1 ? defaultOutcome : getVariant(params.definition.variants, variantIndex),
         outcomeType: "split" /* SPLIT */
@@ -357,9 +371,8 @@ function handleOutcome(params, outcome) {
           outcomeType: "rollout" /* ROLLOUT */
         };
       }
-      const maxValue = 4294967295;
       const value = hashInput(lhs, params.definition.seed);
-      const threshold = currentPromille / 1e5 * maxValue;
+      const threshold = currentPromille / 1e5 * UINT32_MAX;
       return {
         value: value < threshold ? getVariant(params.definition.variants, outcome.rollToVariant) : getVariant(
           params.definition.variants,
@@ -437,7 +450,7 @@ function findWeightedIndex(weights, value, maxValue) {
 }
 
 // package.json
-var version = "1.4.0";
+var version = "1.5.0-1602289-20260528072704";
 
 // src/lib/report-value.ts
 function internalReportValue(key, value, data) {
@@ -632,7 +645,7 @@ function hashSdkKey(sdkKey) {
   sdkKeyHashCache.set(sdkKey, promise);
   return promise;
 }
-async function readBundledDefinitions(sdkKey) {
+async function readBundledDefinitions(auth) {
   let get;
   try {
     const module = await import(
@@ -649,10 +662,20 @@ async function readBundledDefinitions(sdkKey) {
   if (typeof get !== "function") {
     return { definitions: null, state: "missing-file" };
   }
-  const entry = get(sdkKey);
+  let lookup;
+  try {
+    lookup = await auth.resolveBundledDefinitionsLookup();
+  } catch (error) {
+    return { definitions: null, state: "unexpected-error", error };
+  }
+  if (lookup.type === "project-id") {
+    const entry2 = get(lookup.projectId);
+    return entry2 ? { definitions: entry2, state: "ok" } : { definitions: null, state: "missing-entry" };
+  }
+  const entry = get(lookup.sdkKey);
   if (entry) return { definitions: entry, state: "ok" };
   try {
-    const hashedKey = await hashSdkKey(sdkKey);
+    const hashedKey = await hashSdkKey(lookup.sdkKey);
     const hashedEntry = get(hashedKey);
     if (hashedEntry) return { definitions: hashedEntry, state: "ok" };
   } catch (error) {
@@ -663,6 +686,23 @@ async function readBundledDefinitions(sdkKey) {
 
 // src/utils/usage-tracker.ts
 import { waitUntil } from "@vercel/functions";
+
+// src/utils/backoff.ts
+var DEFAULT_BASE_MS = 250;
+var DEFAULT_CAP_MS = 5e3;
+function getRetryDelayMs(attempt, options = {}) {
+  const baseMs = options.baseMs ?? DEFAULT_BASE_MS;
+  const capMs = options.capMs ?? DEFAULT_CAP_MS;
+  const ceiling = Math.min(capMs, baseMs * 2 ** Math.max(0, attempt - 1));
+  return Math.floor(Math.random() * ceiling);
+}
+function getJitteredWaitMs(baseMs, ratio) {
+  const min = baseMs * (1 - ratio);
+  const span = baseMs * 2 * ratio;
+  return Math.floor(min + Math.random() * span);
+}
+
+// src/utils/usage-tracker.ts
 var RESOLVED_VOID = Promise.resolve();
 var isDebugMode = process.env.DEBUG?.includes("@vercel/flags-core");
 var debugLog = (...args) => {
@@ -672,6 +712,7 @@ var debugLog = (...args) => {
 var MAX_RETRIES = 3;
 var MAX_BATCH_SIZE = 50;
 var MAX_BATCH_WAIT_MS = 5e3;
+var BATCH_WAIT_JITTER_RATIO = 0.2;
 var SYMBOL_FOR_REQ_CONTEXT = /* @__PURE__ */ Symbol.for("@vercel/request-context");
 var fromSymbol = globalThis;
 function getRequestContext() {
@@ -778,7 +819,10 @@ var UsageTracker = class {
       const pending = (async () => {
         await new Promise((res) => {
           this.batcher.resolveWait = res;
-          timeout = setTimeout(res, MAX_BATCH_WAIT_MS);
+          timeout = setTimeout(
+            res,
+            getJitteredWaitMs(MAX_BATCH_WAIT_MS, BATCH_WAIT_JITTER_RATIO)
+          );
         });
         this.batcher.pending = null;
         this.batcher.resolveWait = null;
@@ -800,6 +844,7 @@ var UsageTracker = class {
     const eventsToSend = this.batcher.events;
     this.batcher.events = [];
     const flushId = ++this.flushCounter;
+    const token = await this.options.auth.resolveToken();
     for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) {
       try {
         const response = await this.options.fetch(
@@ -808,7 +853,7 @@ var UsageTracker = class {
             method: "POST",
             headers: {
               "Content-Type": "application/json",
-              Authorization: `Bearer ${this.options.sdkKey}`,
+              Authorization: `Bearer ${token}`,
               "User-Agent": `VercelFlagsCore/${version}`,
               ...process.env.VERCEL_ENV ? { "X-Vercel-Env": process.env.VERCEL_ENV } : null,
               ...isDebugMode ? { "x-vercel-debug-ingest": "1" } : null
@@ -832,7 +877,12 @@ Response body: ${await response.text().catch(() => null)}`
           error
         );
         if (attempt < MAX_RETRIES) {
-          await new Promise((res) => setTimeout(res, attempt * 100));
+          const delayMs = getRetryDelayMs(attempt);
+          await new Promise((res) => setTimeout(res, delayMs));
+        } else {
+          console.error(
+            `@vercel/flags-core: Dropped ${eventsToSend.length} events after ${MAX_RETRIES} attempts (flushId=${flushId})`
+          );
         }
       }
     }
@@ -855,11 +905,10 @@ var FallbackEntryNotFoundError = class extends Error {
 
 // src/controller/bundled-source.ts
 var BundledSource = class {
-  promise;
-  options;
   constructor(options) {
     this.options = options;
   }
+  promise;
   /**
    * Load bundled definitions.
    * Throws if bundled definitions are not available.
@@ -904,7 +953,7 @@ var BundledSource = class {
   }
   getResult() {
     if (!this.promise) {
-      this.promise = this.options.readBundledDefinitions(this.options.sdkKey);
+      this.promise = this.options.readBundledDefinitions(this.options.auth);
     }
     return this.promise;
   }
@@ -913,6 +962,7 @@ var BundledSource = class {
 // src/controller/fetch-datafile.ts
 var DEFAULT_FETCH_TIMEOUT_MS = 1e4;
 async function fetchDatafile(options) {
+  const token = await options.auth.resolveToken();
   const controller = new AbortController();
   const timeoutId = setTimeout(
     () => controller.abort(),
@@ -929,7 +979,7 @@ async function fetchDatafile(options) {
   try {
     const res = await options.fetch(`${options.host}/v1/datafile`, {
       headers: {
-        Authorization: `Bearer ${options.sdkKey}`,
+        Authorization: `Bearer ${token}`,
         "User-Agent": `VercelFlagsCore/${version}`,
         ...process.env.VERCEL_ENV ? { "X-Vercel-Env": process.env.VERCEL_ENV } : null
       },
@@ -986,7 +1036,7 @@ function normalizeOptions(options) {
     };
   }
   return {
-    sdkKey: options.sdkKey,
+    auth: options.auth,
     datafile: options.datafile,
     stream,
     polling,
@@ -1097,12 +1147,11 @@ var UnauthorizedError = class extends Error {
   }
 };
 async function connectStream(config, callbacks) {
-  const {
-    host,
-    sdkKey,
-    abortController,
-    fetch: fetchFn = globalThis.fetch
-  } = config;
+  const { host, abortController, fetch: fetchFn = globalThis.fetch } = config;
+  const token = config.token ?? config.sdkKey;
+  if (!token) {
+    throw new Error("stream: missing auth token");
+  }
   const { onDatafile, onPrimed, onDisconnect } = callbacks;
   let retryCount = 0;
   let lastAttemptTime = 0;
@@ -1144,7 +1193,7 @@ async function connectStream(config, callbacks) {
       try {
         lastAttemptTime = Date.now();
         const headers = {
-          Authorization: `Bearer ${sdkKey}`,
+          Authorization: `Bearer ${token}`,
           "User-Agent": `VercelFlagsCore/${version}`,
           "X-Retry-Attempt": String(retryCount)
         };
@@ -1298,27 +1347,29 @@ var StreamSource = class extends TypedEmitter {
       { once: true }
     );
     try {
-      const promise = connectStream(
-        {
-          host: this.options.host,
-          sdkKey: this.options.sdkKey,
-          abortController,
-          fetch: this.options.fetch,
-          revision: this.revision
-        },
-        {
-          onDatafile: (newData) => {
-            this.emit("data", newData);
-            this.emit("connected");
-          },
-          onPrimed: (message) => {
-            this.emit("primed", message);
-            this.emit("connected");
+      const promise = this.options.auth.resolveToken().then(
+        (token) => connectStream(
+          {
+            host: this.options.host,
+            token,
+            abortController,
+            fetch: this.options.fetch,
+            revision: this.revision
           },
-          onDisconnect: () => {
-            this.emit("disconnected");
+          {
+            onDatafile: (newData) => {
+              this.emit("data", newData);
+              this.emit("connected");
+            },
+            onPrimed: (message) => {
+              this.emit("primed", message);
+              this.emit("connected");
+            },
+            onDisconnect: () => {
+              this.emit("disconnected");
+            }
           }
-        }
+        )
       );
       this.promise = promise;
       return promise;
@@ -1370,6 +1421,11 @@ var Controller = class {
   state = "idle";
   // Data state — tagged with origin
   data;
+  // Memoized data spread for read() / getDatafile().
+  // Rebuilt only when `this.data` reference changes (e.g. on stream/poll update).
+  // Holds the result of stripping `_origin`; metrics are appended per-call.
+  dataViewSource = void 0;
+  dataViewBase = void 0;
   // Sources (I/O delegates)
   streamSource;
   pollingSource;
@@ -1383,11 +1439,6 @@ var Controller = class {
   // Suppresses usage tracking when the SDK key is unauthorized
   unauthorized = false;
   constructor(options) {
-    if (!options.sdkKey || typeof options.sdkKey !== "string" || !options.sdkKey.startsWith("vf_")) {
-      throw new Error(
-        '@vercel/flags-core: SDK key must be a string starting with "vf_"'
-      );
-    }
     this.options = normalizeOptions(options);
     this.streamSource = new StreamSource(
       this.options,
@@ -1395,7 +1446,7 @@ var Controller = class {
     );
     this.pollingSource = new PollingSource(this.options);
     this.bundledSource = new BundledSource({
-      sdkKey: this.options.sdkKey,
+      auth: this.options.auth,
       readBundledDefinitions
     });
     this.wireSourceEvents();
@@ -1541,11 +1592,15 @@ var Controller = class {
     this.isFirstGetData = false;
     const [result, cacheStatus] = await this.resolveData();
     const readMs = Date.now() - startTime;
-    const { _origin, ...data } = result;
-    const source = originToMetricsSource(_origin);
+    const source = originToMetricsSource(result._origin);
     this.trackRead(startTime, cacheHadDefinitions, isFirstRead, source);
+    if (this.dataViewSource !== result) {
+      const { _origin, ...rest } = result;
+      this.dataViewBase = rest;
+      this.dataViewSource = result;
+    }
     return {
-      ...data,
+      ...this.dataViewBase,
       metrics: {
         readMs,
         source,
@@ -1591,7 +1646,7 @@ var Controller = class {
         try {
           const fetched = await fetchDatafile({
             host: this.options.host,
-            sdkKey: this.options.sdkKey,
+            auth: this.options.auth,
             fetch: this.options.fetch
           });
           this.data = tagData(fetched, "fetched");
@@ -1605,8 +1660,13 @@ var Controller = class {
       }
     }
     const source = originToMetricsSource(result._origin);
+    if (this.dataViewSource !== result) {
+      const { _origin, ...rest } = result;
+      this.dataViewBase = rest;
+      this.dataViewSource = result;
+    }
     return {
-      ...result,
+      ...this.dataViewBase,
       metrics: {
         readMs: Date.now() - startTime,
         source,
@@ -1782,7 +1842,7 @@ var Controller = class {
     try {
       const fetched = await fetchDatafile({
         host: this.options.host,
-        sdkKey: this.options.sdkKey,
+        auth: this.options.auth,
         fetch: this.options.fetch
       });
       return tagData(fetched, "fetched");
@@ -1814,7 +1874,7 @@ var Controller = class {
       try {
         const fetched = await fetchDatafile({
           host: this.options.host,
-          sdkKey: this.options.sdkKey,
+          auth: this.options.auth,
           fetch: this.options.fetch
         });
         this.data = tagData(fetched, "fetched");
@@ -1866,7 +1926,7 @@ var Controller = class {
       try {
         const fetched = await fetchDatafile({
           host: this.options.host,
-          sdkKey: this.options.sdkKey,
+          auth: this.options.auth,
           fetch: this.options.fetch
         });
         this.data = tagData(fetched, "fetched");
@@ -1939,6 +1999,9 @@ var Controller = class {
   }
 };
 
+// src/controller/auth.ts
+import { getVercelOidcToken } from "@vercel/oidc";
+
 // src/utils/sdk-keys.ts
 var SDK_KEY_REGEX = /^vf_(?:server|client)_/;
 function parseSdkKeyFromFlagsConnectionString(text) {
@@ -1953,28 +2016,80 @@ function parseSdkKeyFromFlagsConnectionString(text) {
   return null;
 }
 
+// src/controller/auth.ts
+async function getOidcToken() {
+  try {
+    return await getVercelOidcToken();
+  } catch {
+    throw new Error(
+      [
+        "@vercel/flags-core: Failed to get OIDC token.",
+        "Are you running in a Vercel Environment where OIDC tokens are available?",
+        "Did you mean to use an SDK Key instead? Use the environment variable FLAGS or pass it directly to the client."
+      ].join(" ")
+    );
+  }
+}
+function getProjectIdFromOidcToken(oidcToken) {
+  const tokenParts = oidcToken.split(".");
+  if (tokenParts.length !== 3 || !tokenParts[1]) {
+    throw new Error("@vercel/flags-core: Invalid OIDC token");
+  }
+  const payload = JSON.parse(
+    Buffer.from(tokenParts[1], "base64url").toString("utf8")
+  );
+  if (typeof payload.project_id !== "string" || !payload.project_id) {
+    throw new Error(
+      "@vercel/flags-core: Missing project_id claim in OIDC token"
+    );
+  }
+  return payload.project_id;
+}
+var Authentication = class {
+  sdkKey;
+  constructor(sdkKeyOrConnectionString) {
+    if (sdkKeyOrConnectionString !== void 0) {
+      if (typeof sdkKeyOrConnectionString !== "string") {
+        throw new Error(
+          `@vercel/flags-core: Invalid sdkKey. Expected string, got ${typeof sdkKeyOrConnectionString}`
+        );
+      }
+      const parsed = parseSdkKeyFromFlagsConnectionString(
+        sdkKeyOrConnectionString
+      );
+      if (!parsed) {
+        throw new Error("@vercel/flags-core: Missing sdkKey");
+      }
+      this.sdkKey = parsed;
+    }
+  }
+  async resolveToken() {
+    if (this.sdkKey) {
+      return this.sdkKey;
+    }
+    return await getOidcToken();
+  }
+  async resolveBundledDefinitionsLookup() {
+    if (this.sdkKey) {
+      return { type: "sdk-key", sdkKey: this.sdkKey };
+    }
+    const oidcToken = await this.resolveToken();
+    return {
+      type: "project-id",
+      projectId: getProjectIdFromOidcToken(oidcToken)
+    };
+  }
+};
+
 // src/index.make.ts
 function make(createRawClient) {
   let _defaultFlagsClient = null;
   function createClient2(sdkKeyOrConnectionString, options) {
-    if (!sdkKeyOrConnectionString)
-      throw new Error("@vercel/flags-core: Missing sdkKey");
-    if (typeof sdkKeyOrConnectionString !== "string")
-      throw new Error(
-        `@vercel/flags-core: Invalid sdkKey. Expected string, got ${typeof sdkKeyOrConnectionString}`
-      );
-    const sdkKey = parseSdkKeyFromFlagsConnectionString(
-      sdkKeyOrConnectionString
-    );
-    if (!sdkKey) {
-      throw new Error(
-        "@vercel/flags-core: Missing sdkKey in connection string"
-      );
-    }
-    const controller = new Controller({ sdkKey, ...options });
+    const auth = new Authentication(sdkKeyOrConnectionString);
+    const controller = new Controller({ auth, ...options });
     return createRawClient({
       controller,
-      origin: { provider: "vercel", sdkKey }
+      origin: { provider: "vercel", sdkKey: auth.sdkKey }
     });
   }
   function resetDefaultFlagsClient2() {
@@ -1983,14 +2098,7 @@ function make(createRawClient) {
   const flagsClient2 = new Proxy({}, {
     get(_, prop) {
       if (!_defaultFlagsClient) {
-        if (!process.env.FLAGS) {
-          throw new Error("flags: Missing environment variable FLAGS");
-        }
-        const sdkKey = parseSdkKeyFromFlagsConnectionString(process.env.FLAGS);
-        if (!sdkKey) {
-          throw new Error("@vercel/flags-core: Missing sdkKey");
-        }
-        _defaultFlagsClient = createClient2(sdkKey);
+        _defaultFlagsClient = createClient2(process.env.FLAGS);
       }
       return _defaultFlagsClient[prop];
     }
@@ -2051,4 +2159,4 @@ export {
   resetDefaultFlagsClient,
   createClient
 };
-//# sourceMappingURL=chunk-2F6JQ5SL.js.map
+//# sourceMappingURL=chunk-COEI5LTV.js.map