@vercel/flags-core 1.9.0 → 1.10.0-356954d-20261005082852

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # @vercel/flags-core
 
+## 1.10.0-356954d-20261005082852
+
+### Minor Changes
+
+- [#511](https://github.com/vercel/flags/pull/511) [`88c323c`](https://github.com/vercel/flags/commit/88c323c9539661fef385f1381ff7e3e89776fdc7) Thanks [@luismeyer](https://github.com/luismeyer)! - Add a header-driven `vercel` client mode, enabled by default when `VERCEL=1`. Initialization loads provided/bundled definitions; request versions trigger refreshes and an empty cache fetches on its first read. Explicit offline/build behavior is preserved.
+  
+  Evaluations require a valid positive version header for their own project. Missing, empty, malformed, or unrelated project entries permanently start streaming when enabled, otherwise polling; multiple clients select their sources independently. Concurrent reads share startup and pending HTTP refreshes. Accepted stream updates and valid confirmations cancel superseded refreshes; waiting reads use the confirmed cache, and late responses cannot change cache or authorization state. A cold shared fetch discovers project identity before accepting header evidence; a failed cold fetch rejects without switching sources and is retried by the next read. `getDatafile()` remains a snapshot that never starts streaming or polling: it serves cached definitions through the same header checks, stale-while-revalidate, blocking refresh, and stale-if-error, and loads bundled definitions or performs a one-time fetch when the cache is empty.
+  
+  **Cached definitions now expire by age in streaming and polling mode.** Streaming data is fresh for 60 seconds after the last message; polling data is fresh for its interval plus the 10-second fetch deadline (40 seconds by default). Data then stays stale for `staleWhileRevalidate` seconds (default 10) while reads refresh over HTTP in the background, and expired reads wait for the shared refresh. Data without a known age is served until its source first confirms it. Accepted updates, source responses, valid confirmations, and stream pings reset age without rewriting `fetchedAt`.
+  
+  Streaming and polling never run at the same time. A stream startup timeout or disconnect keeps the stream reconnecting in the background while reads serve the cache; polling starts only once the stream gives up for good (retries exhausted, 401, or token failure), waiting for its first poll up to `polling.initTimeoutMs`. Ping timeouts reconnect the stream internally, allowing suspended runtimes to resume. If the stream gives up and polling is disabled, reads revalidate over HTTP on the streaming schedule. Shutting down and reinitializing a client rewires its sources and starts with a clean cache and failure deadline.
+  
+  Use `staleWhileRevalidate` (default 10) and `staleIfError` (default Infinity) in **seconds**, including fractions. Setting either to `0` disables its stale allowance. Datafiles preserve optional `fetchedAt` epoch-millisecond timestamps across serialization and bundled/provided reuse.
+
+- [#540](https://github.com/vercel/flags/pull/540) [`1a38dee`](https://github.com/vercel/flags/commit/1a38dee43b41030496bd63290816e06e5d5890ae) Thanks [@vincent-derks](https://github.com/vincent-derks)! - Remove `projectId` from connection strings.
+
+- [#510](https://github.com/vercel/flags/pull/510) [`3ef9a2e`](https://github.com/vercel/flags/commit/3ef9a2e8c99905142b1d349fa2d68ffa06e04445) Thanks [@luismeyer](https://github.com/luismeyer)! - Add `staleIfError` in seconds to bound cached runtime reads after the first consecutive stream/poll failure or stream disconnect. The default `Infinity` preserves unlimited fallback; finite nonnegative durations (including fractional seconds) use existing evaluation defaults and errors after expiry, and `getDatafile()` follows the same allowance. Any successful source response resets the allowance, including one the version guard rejects as older or for a different project, as does a matching stream primed revision. Storing provided or bundled fallback data does not confirm freshness or renew the failure clock. Build/offline behavior and source scheduling remain unchanged.
+
+### Patch Changes
+
+- [#511](https://github.com/vercel/flags/pull/511) [`1971366`](https://github.com/vercel/flags/commit/1971366423fa61bf5c99023a0a946d79d5bf057e) Thanks [@luismeyer](https://github.com/luismeyer)! - Record `fetchedAt` when a datafile fetch completes and preserve it in generated flag definitions. Loading the bundle retains the original timestamp so the Flags SDK can determine its age.
+  
+  Expose optional `fetchedAt` metadata on datafiles. Record it for accepted live updates and preserve valid timestamps when loading provided or bundled definitions, without mutating the input.
+
 ## 1.9.0
 
 ### Minor Changes

package/README.md

@@ -33,6 +33,115 @@ export default app;
 
 Outside Vercel, pass an SDK key explicitly: `createClient(process.env.FLAGS)`.
 
+## Header-driven reads on Vercel
+
+When `VERCEL=1`, the client defaults to `vercel: true`. Initialization loads provided
+or bundled definitions without starting a stream or polling. Request version headers
+indicate when cached definitions need refreshing. Header mode requires a valid positive
+version for the client’s own `projectId`. An evaluation whose request carries a missing,
+empty, malformed, or unrelated entry permanently switches that client to streaming when
+enabled, otherwise polling. Clients also switch when cached definitions have no valid
+positive config version to compare. Clients with different projects select their sources
+independently within the same request. Concurrent reads share that startup and later
+headers do not switch the client back. Pending HTTP refreshes remain shared until the
+stream delivers current data or confirms the cached version. That confirmation cancels the
+superseded refresh, and waiting reads use the confirmed cache; late responses cannot
+change cache or authorization state. With an empty cache, the first read uses a shared
+fetch to load definitions and discover the client’s project. The next evaluation assesses
+that project’s header entry and starts the stream/poll fallback if it is unavailable.
+If the cold fetch fails, the read rejects without switching sources, and the next read
+retries it. Fetch failures use cached data only while stale-if-error permits it; source
+assessment errors start fallback.
+
+```ts
+const client = createClient(process.env.FLAGS!, {
+  vercel: true,
+  staleWhileRevalidate: 10, // Seconds of background-refresh grace.
+  staleIfError: 60, // Seconds of cached fallback after a refresh failure.
+});
+```
+
+`staleWhileRevalidate` defaults to 10 seconds and accepts finite, nonnegative values,
+including fractions. `0` makes header-driven refreshes block. The window starts at the latest
+accepted fetch or valid confirmation, including an equal-version fetch response.
+The cache tracks this age independently of `fetchedAt`. Bundled/provided definitions
+preserve their original `fetchedAt`; unknown or expired cache age requires a blocking
+refresh when a newer request version arrives. Refresh failures use `staleIfError`.
+A newer-header read attempts blocking recovery after that failure allowance expires.
+
+`getDatafile()` is a snapshot: it never starts streaming or polling. It serves cached
+definitions through the same header checks, background revalidation, blocking refresh,
+and stale-if-error as evaluations, shares pending HTTP refreshes with them, and loads
+bundled definitions or performs a one-time fetch when the cache is empty. Only
+evaluations switch a client to streaming or polling.
+Use `vercel: false` to select the stream/poll behavior. Disabling both
+stream and polling still selects offline mode, and builds retain their existing loading.
+
+## Cached reads after errors
+
+`staleIfError` controls how many seconds evaluations and `getDatafile()` may use
+cached flag definitions after a stream/poll/header-refresh failure or stream disconnect:
+
+```ts
+const client = createClient(process.env.FLAGS!, {
+  staleIfError: 60,
+});
+```
+
+The default is `Infinity`, preserving unlimited cached fallback. Use a finite
+nonnegative number of seconds to bound fallback. Fractional seconds are supported
+(for example, `0.5` allows 500 milliseconds). A positive window includes its exact
+deadline; `0` disables cached fallback immediately after failure.
+Negative values, `NaN`, and negative infinity throw when creating the client.
+
+The allowance starts at the first consecutive failure. Repeated errors,
+disconnects, and provided or bundled fallback data do not renew it. Any successful
+source response clears the outage: a newer datafile replaces the cached one, while
+an equal, older, or differently identified response proves the source is reachable
+and leaves the stored definitions in place. A stream `primed` message clears it when
+its finite numeric revision and identity match the cached entry. Pings clear failures
+too: the server sends `primed` or a datafile before pings on each connection. Opening
+a connection alone does not clear a failure. A later failure starts a new allowance.
+Responses are observed in completion order, with existing version acceptance.
+
+After expiry, `evaluate()` returns the caller's default with reason `error`, or
+throws the first failure when no default is supplied. `bulkEvaluate()` returns
+an error result for each requested flag, with its default value when provided.
+`getDatafile()` follows the same allowance and throws after expiry. The entry is
+retained for recovery, including its revision for stream reconnection. A clean
+stream close records `stream: disconnected` if no earlier failure exists, and the
+stream reconnects on its own with backoff while reads keep serving the cache. A
+routine reconnect takes about a second, so keep `staleIfError` above the reconnect
+delay; `0` or sub-second values fail reads during every reconnect. Ping timeouts
+reconnect quietly without recording a failure, including after runtime suspension.
+
+Streaming and polling never run at the same time. Polling starts only once the stream
+has given up for good: its retry budget is exhausted, it receives a 401, or its token
+cannot be resolved. A stream startup timeout keeps connecting in the background without
+polling. Whenever polling starts, reads wait for the first poll or `polling.initTimeoutMs`;
+on timeout, reads follow `staleIfError` while polling continues at the configured
+interval. A zero initialization timeout waits for the poll, which still has a ten-second
+fetch deadline. If the stream gives up and polling is disabled, reads revalidate over
+HTTP on the streaming schedule below. `getFallbackDatafile()` remains an independent
+bundled-data export.
+
+**Cached definitions now expire by age.** Streaming data is fresh for 60 seconds after
+the last message, allowing one missed 30-second ping. Polling data is fresh for its
+interval plus the 10-second fetch deadline (40 seconds with the default 30-second
+interval). After that, data is stale for `staleWhileRevalidate` seconds (10 by default):
+evaluations and `getDatafile()` calls serve it and refresh over HTTP in the background.
+Once that window passes, the data is expired and reads wait for the shared refresh.
+`staleWhileRevalidate: 0` makes reads block as soon as the fresh window ends. Data
+without a known age, such as a provided datafile without `fetchedAt`, is served until the
+source first confirms it. Refresh failures still follow `staleIfError`.
+
+Accepted updates, source responses, and valid confirmations reset cache age without
+rewriting `fetchedAt`. Stream pings also reset age and clear any failure. Poll errors
+feed the shared failure handler without logging each failed poll. An initialization
+timeout alone does not start the failure allowance or reset cache age; it permits
+cached fallback while the pending update continues. Shutting down and reinitializing
+a client starts with a clean cache and failure deadline.
+
 ## Evaluation Metrics
 
 To associate evaluation metrics with an environment, pass the