@vercel/flags-core 1.9.0 → 1.10.0-4925dc8-20261001115512

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # @vercel/flags-core
 
+## 1.10.0-4925dc8-20261001115512
+
+### 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.
+  
+  An evaluation with a missing or empty version header permanently starts streaming when enabled, otherwise polling. 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. Initialization and snapshot reads do not trigger this switch.
+  
+  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 evaluations refresh in the background; expired evaluations 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 still trigger the existing polling fallback.
+  
+  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) [`0810c82`](https://github.com/vercel/flags/commit/0810c82c42250602d083c2ce9a30f29c78188a44) 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. 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,87 @@ 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. If an evaluation has no version
+header (or an empty one), the client permanently switches to streaming when enabled,
+otherwise polling. Concurrent new evaluations 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. A present but malformed or unrelated header keeps the
+existing cached-read behavior, fetching only when the cache is empty.
+
+```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()` remains a snapshot read: it applies stale-if-error but does not inspect
+headers. Use `vercel: false` to select the existing 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 or ping timeout records `stream: disconnected` if no earlier failure
+exists. `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 disconnect
+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 refresh in the background; expired evaluations 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 +145,56 @@ 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` and its diagnostic details. The controller, cache,
+and network sources all use the same global logging function. For example:
+
+```text
+@vercel/flags-core { event: 'client.state', from: 'idle', to: 'vercel', reason: 'header-mode-enabled', ... }
+@vercel/flags-core { event: 'cache.freshness', status: 'expired', revision: 42, ageMs: 15000, ... }
+@vercel/flags-core { event: 'cache.refresh.blocking', reason: 'expired', ... }
+@vercel/flags-core { event: 'datafile.fetch.attempt', attempt: 1, maxAttempts: 3 }
+@vercel/flags-core { event: 'datafile.fetch.response', attempt: 1, status: 200 }
+@vercel/flags-core { event: 'cache.update.accepted', revision: 43, ... }
+@vercel/flags-core { event: 'cache.fetch.applied', revision: 43, ... }
+@vercel/flags-core { event: 'client.read', 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.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,
+read/snapshot 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.