@vercel/flags-core 1.9.0 → 1.10.0-6128616-20261001141857

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # @vercel/flags-core
 
+## 1.10.0-6128616-20261001141857
+
+### 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 and `getDatafile()` 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. `getDatafile()` shares lazy initialization and the evaluation resolution path, including header assessment, SWR, blocking refresh, stale-if-error, and source fallback. Initialization alone does not trigger this switch. A cold shared fetch discovers project identity before accepting header evidence; failed discovery starts source fallback.
+  
+  The controller supplies a source freshness-status callback to the cache and configures one shared fetch callback. HeaderSource keeps version observations; the cache handles serving, background/blocking refreshes, shared work, cancellation, and stale-if-error. The cache owns age and resets it on accepted updates or confirmations, without rewriting `fetchedAt`. Streaming becomes stale after 60 seconds and expires after 90 seconds. Polling becomes stale after its interval plus the 10-second fetch deadline and expires after two intervals plus that deadline (40/70 seconds by default). Stale reads refresh in the background; expired reads block on the shared refresh. Stream pings reset age and clear failures. Polling initialization honors its configured timeout while preserving the pending poll and interval; cached fallback does not renew cache age or stale-if-error.
+  
+  Ping timeouts reconnect the stream internally, allowing suspended runtimes to resume without starting polling. Reconnection alone does not renew cache freshness. Connection errors, server closure, and exhausted retries trigger an immediate background poll followed by interval polling. Reads and polling share pending HTTP refreshes; stream recovery stops polling.
+  
+  Use `staleWhileRevalidate` (default 10) and `staleIfError` (default Infinity) in **seconds**, including fractions. Setting either to `0` disables its stale allowance. `staleWhileRevalidate` controls header-driven refreshes; stream/poll freshness follows their update schedules. 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. Accepted updates, valid equal-version responses, or matching stream primed revisions reset the allowance. Storing 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) [`7c434bf`](https://github.com/vercel/flags/commit/7c434bf866cf58b860345b717021af382b481862) Thanks [@luismeyer](https://github.com/luismeyer)! - Add detailed client lifecycle, cache freshness, and network diagnostics using the existing `DEBUG=@vercel/flags-core` environment variable. 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) [`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,101 @@ 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`. Missing, empty, malformed, or unrelated entries
+permanently switch 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 read 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. 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()` uses the same lazy initialization and resolution path as evaluations,
+including header checks, background revalidation, blocking refresh, stale-if-error, and
+source fallback. Concurrent calls share HTTP refreshes across both APIs.
+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. An accepted
+source update, or a finite equal version for the same project and environment,
+clears the outage. A stream `primed` message also 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. Ping timeouts
+reconnect quietly without recording a failure or starting polling, including after runtime
+suspension. Genuine disconnections start an immediate poll, sharing pending read
+refreshes, then continue at the configured interval. Every transition to polling
+waits for the first poll or `polling.initTimeoutMs`, including reads with cached data.
+On timeout, reads follow `staleIfError` while polling continues. A zero initialization
+timeout waits for the poll, which still has a ten-second fetch deadline. Stream
+recovery stops polling. `getFallbackDatafile()` remains an independent bundled-data export.
+
+Streaming data becomes stale after 60 seconds and expires after 90 seconds, allowing
+one missed 30-second ping before revalidation and matching the stream's ping
+timeout. Polling data becomes stale after its interval plus the 10-second fetch
+deadline, and expires after two intervals plus that deadline (40 and 70 seconds with
+the default 30-second interval). These windows are independent of `staleWhileRevalidate`.
+Stale evaluations and `getDatafile()` calls refresh in the background; expired reads
+wait for the shared refresh. Refresh failures still follow `staleIfError`.
+
+Accepted updates 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; polling intervals remain active after startup timeout.
+
 ## Evaluation Metrics
 
 To associate evaluation metrics with an environment, pass the
@@ -64,3 +159,64 @@ const client = OpenFeature.getClient();
 - [Core Library Docs](https://vercel.com/docs/flags/vercel-flags/sdks/core)
 - [OpenFeature Provider Docs](https://vercel.com/docs/flags/vercel-flags/sdks/openfeature)
 - [Vercel Flags](https://vercel.com/docs/flags/vercel-flags)
+
+### Client debug logging
+
+Set `DEBUG=@vercel/flags-core` to enable detailed diagnostics. This reuses the
+existing ingest debug switch:
+
+```sh
+DEBUG=@vercel/flags-core pnpm dev
+```
+
+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. |
+| `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.