@vercel/flags-core 1.9.0 → 1.10.0-0037f35-20261006132750

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # @vercel/flags-core
 
+## 1.10.0-0037f35-20261006132750
+
+### Minor Changes
+
+- [#511](https://github.com/vercel/flags/pull/511) [`ab6d65d`](https://github.com/vercel/flags/commit/ab6d65d5e4fcb0d0a563d982e23ccefd4f314113) 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) and expires afterwards. Polling serves stale data while refreshing over HTTP in the background and makes expired reads wait for the shared fetch. While streaming, no HTTP request competes with the connection: stale reads serve the cache, and expired reads drop an overdue connection and wait up to ten seconds for the replacement stream to confirm or replace the cache. 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. Polling gives up on a 401 too. Whenever no live source is active, because the stream is reconnecting or the stream or polling gave up, reads apply plain stale-while-revalidate over HTTP: fresh within `staleWhileRevalidate`, served while refreshing in the background beyond that, and waiting for the refresh once older than `staleWhileRevalidate` plus `staleIfError`; data of unknown age refreshes in the background. 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) [`10f19eb`](https://github.com/vercel/flags/commit/10f19ebc3896fe8f0d1ccc56755a59ee81173314) 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
+
+- [#518](https://github.com/vercel/flags/pull/518) [`38f7f77`](https://github.com/vercel/flags/commit/38f7f77b8965a6dc613f2925ae00c137d8d20cd2) Thanks [@luismeyer](https://github.com/luismeyer)! - Add detailed client lifecycle, cache freshness, and network diagnostics using the `DEBUG=@vercel/flags-core` environment variable. `DEBUG` now follows the usual conventions for both the diagnostics and the ingest debug header: comma- or space-separated patterns, `*` wildcards, and `-` exclusions. A shared global logger emits events without passing logger instances through the client. Every client diagnostic includes the configured `clientName`, including cache, source, and background network activity. Logs omit credentials, definitions, and raw errors.
+  
+  State changes include their cause; refresh logs distinguish response receipt, cache application, shared work, stream confirmation, and shutdown cancellation. Startup and source logs expose timeout and freshness thresholds, and recovery is logged only when a failure clears.
+
+- [#511](https://github.com/vercel/flags/pull/511) [`e8f0c91`](https://github.com/vercel/flags/commit/e8f0c91ab834ef288c3b8e03faa50b882faca4a6) 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,123 @@ 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. Polling gives up on a 401 as well. Whenever no live source is active,
+because the stream is reconnecting or the stream or polling gave up, reads apply plain
+stale-while-revalidate over HTTP: data refreshed within `staleWhileRevalidate` is served
+as is, older data is served while a background refresh runs, and data older than
+`staleWhileRevalidate` plus `staleIfError` waits for the refresh. Data without a known
+age refreshes in the background. `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)
+and then expired. Polling serves stale data while refreshing over HTTP in the background
+and makes expired reads wait for the shared fetch. Streaming starts no HTTP work while
+the connection is active: stale reads serve the cache, and expired reads drop a
+connection that has been silent for over 60 seconds and wait up to ten seconds for the
+replacement stream to confirm or replace the cache.
+`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
+active source first confirms it; without a live source it is revalidated like stale data.
+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
@@ -59,6 +176,73 @@ await OpenFeature.setProviderAndWait(new VercelProvider());
 const client = OpenFeature.getClient();
 ```
 
+## Client debug logging
+
+Set `DEBUG=@vercel/flags-core` to enable detailed diagnostics:
+
+```sh
+DEBUG=@vercel/flags-core pnpm dev
+```
+
+`DEBUG` follows the usual conventions: patterns are separated by commas or spaces,
+`*` is a wildcard (`DEBUG=*` or `DEBUG=@vercel/*` enable the logs), and a leading `-`
+excludes a pattern (`DEBUG=*,-@vercel/flags-core` keeps them off). The same switch
+also marks usage ingestion requests with an `x-vercel-debug-ingest: 1` header.
+
+Client diagnostics use `console.debug` with the `@vercel/flags-core` prefix and
+an object containing an `event`, the configured `clientName`, and its diagnostic
+details. Set `clientName` when creating each client to distinguish their logs:
+
+```ts
+const client = createClient(undefined, { clientName: 'checkout' });
+```
+
+The controller, cache, and network sources all use the same global logging
+function, including the client name on background work and reconnects. For example:
+
+```text
+@vercel/flags-core { event: 'client.state', clientName: 'checkout', from: 'idle', to: 'vercel', reason: 'header-mode-enabled', ... }
+@vercel/flags-core { event: 'cache.freshness', clientName: 'checkout', status: 'expired', revision: 42, ageMs: 15000, ... }
+@vercel/flags-core { event: 'cache.refresh.blocking', clientName: 'checkout', reason: 'expired', ... }
+@vercel/flags-core { event: 'datafile.fetch.attempt', clientName: 'checkout', attempt: 1, maxAttempts: 3 }
+@vercel/flags-core { event: 'datafile.fetch.response', clientName: 'checkout', attempt: 1, status: 200 }
+@vercel/flags-core { event: 'cache.update.accepted', clientName: 'checkout', revision: 43, ... }
+@vercel/flags-core { event: 'cache.fetch.applied', clientName: 'checkout', revision: 43, ... }
+@vercel/flags-core { event: 'client.read', clientName: 'checkout', state: 'vercel', cacheStatus: 'MISS', ... }
+```
+
+Follow `client.state` for the previous state, next state, and transition reason.
+`state` describes the internal lifecycle; `mode` is the public operating mode.
+Read and cache events include the project, revision, and cache age when available.
+
+| Event | What it explains |
+| --- | --- |
+| `cache.freshness` | The source's age/version assessment and whether failure policy permits serving the entry. |
+| `cache.source-error` / `header.fallback` | The source cannot assess this project or its cached version; the controller starts fallback without changing the fetch-failure deadline. |
+| `cache.refresh.background` / `.blocking` | Why a read returns stale data immediately or waits for refresh. |
+| `cache.fetch.shared` | A caller joins an existing HTTP refresh instead of starting another. |
+| `datafile.fetch.complete` / `cache.fetch.applied` | The response has been parsed / processed by the cache version guard. Only the latter finishes cache refresh work; an older response may be ignored. |
+| `cache.fetch.cancel` / `cache.refresh.superseded` | A stream update or confirmation supersedes HTTP work / releases a waiting read using the confirmed cache. |
+| `cache.fetch.aborted` | `source-confirmed` distinguishes superseded work from `cache-cleared` during shutdown. |
+| `datafile.fetch.aborted` | `timeout` is the fetch's own ten-second deadline; `external` is a cancellation by its caller. |
+| `stream.exhausted` | The stream gave up for good (retries exhausted, 401, or token failure) and polling takes over when enabled. |
+| `cache.stale-if-error.expired` / `cache.recovered` | The failure allowance prevents serving data / an actual failure has cleared. Ordinary confirmations do not log recovery. |
+| `stream.initialize.timeout` / `poll.initialize.timeout` | Startup reached its deadline; `hasData` and `startupFallback` show whether cached fallback is available. |
+
+Events cover initialization and shutdown, selected modes and state transitions,
+evaluation/getDatafile results, cache versions and age, version acceptance/confirmation,
+header timestamps, background/blocking/shared refreshes, stale-if-error expiry,
+HTTP attempts and retry delays, polling, stream pings, timeouts, and reconnect reasons.
+Stream/poll startup events include their stale and expired age thresholds.
+Cache ages and delays are in milliseconds; `Infinity` denotes unknown age or an
+unlimited stale-if-error window. The new client diagnostics omit credentials,
+raw headers, flag definitions, evaluation entities, and raw error messages.
+
+Logging is off by default. The logger checks `DEBUG` on each call; removing the
+namespace disables client diagnostics, including for existing clients. Diagnostics
+are verbose, including an event for each read, and event names/fields are internal
+rather than a stable API. Configure your log collector to include `console.debug` output.
+
 ## Documentation
 
 - [Core Library Docs](https://vercel.com/docs/flags/vercel-flags/sdks/core)