quonfig 1.2.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d9da26b9a9f898ec76bf8520043abc42db011adf5e298cffa16ee8764c2c0ed6
-  data.tar.gz: '0189ef6ee1e93cec985f9f5b1f1b81f833527bf3c22a1af7886778d8f2dcb50e'
+  metadata.gz: 5e8807ad54199b5ee24245cdf140a72aed0644e712308d867457d729df1bb122
+  data.tar.gz: 20b1d12fb441394f4d31198854b55dd90f78c925115982a32548415993c77958
 SHA512:
-  metadata.gz: e363cf1a35bbc428f35d1d4cebea4223dc84c4a1ddd39c3a7dcbc22bafb58a757b5fde92f357dd1a9b8c0e0cc90db247addd88c873e19887cd1d0eae0bc5332b
-  data.tar.gz: e81f8441d30449624e3c64b506e113d386ce8a55656943e4523cb2d919d97aad5d8afd68df6462df1324cb2368dd8d9694e808146d622dd790ccf722e630e442
+  metadata.gz: cda8d4a8d332710a58f3be0e1e068e767858c9806f199bc23a5a2f010e7540d4fd9a159b20ac23f9d34f1a7f60b5aac10fcffdeda030356ace8536779048126a
+  data.tar.gz: 33dcc1b5201298630936e743f5e44b188393b810ee94287623dce7598b98ab68ee0a2eb8bddb70f92da2fb3419f6a0b7f2a3081e2510b7f2d144087765b541b6

data/CHANGELOG.md

@@ -1,5 +1,40 @@
 # Changelog
 
+## 1.4.0 - 2026-09-10
+
+> **If you fork worker processes and keep evaluating in the parent, upgrade.** On 1.0.0–1.3.0 the parent process went permanently dark after any `fork(2)` — it kept serving whatever config snapshot it held at the moment of the fork, forever, while `connection_state` reported `:connected`.
+
+- **Fix (fork): the `Process._fork` hook is now child-only — the parent is never touched (qfg-lv4n.1).** Since 0.0.16 the hook tore the SSE worker, fallback poller, telemetry reporter, and datadir watcher down **in the parent** before the fork syscall, and restarted them only in the child. Any topology where the parent keeps evaluating after a fork — a Sidekiq process using the `parallel` gem, a `fork { ... }` inside a job, a rake task that forks — lost live updates permanently. A customer's Sidekiq process served a 13-day-old snapshot through four rollout changes this way. The hook now does **nothing** on the parent side: the parent keeps its stream, its poller, its telemetry reporter, and its live config straight through any number of forks. This restores the design every other SDK in this space uses (Reforge's `Reforge.fork`, LaunchDarkly's `postfork`, dd-trace-rb / redis-client / connection_pool, which all branch on the child stage of `_fork` only). No customer wiring is required, and no public API was removed.
+- **Change (fork): a forked child re-initializes on its FIRST use of the client, and never inherits the parent's config snapshot.** The hook does no I/O at all: it drops what the child inherited — including the parent's store — and arms a flag. The first `get` / `defined?` / `keys` / details lookup in the child then does exactly what `Client.new` does: its own blocking config fetch under the configured `init_timeout_ms` and `on_init_failure`, then its own SSE stream (or fallback poller) and its own telemetry reporter. Three consequences worth knowing: the first call in a forked child pays one fetch; a child that never uses the client costs nothing (no fetch, no socket, no thread, and `stop` returns immediately); and because the child's store starts empty, its first envelope is *installed* rather than dropped by the reject-older guard as same-generation. This is full parity with Reforge, where a forked process simply builds a new client. `connection_state` does not trigger the re-initialization — a diagnostic must never open a socket — and answers `:initializing` while one is pending.
+- **Fix (fork): concurrent first use in a child waits for the one rebuild (qfg-lv4n.1).** The re-initialization used an unlocked fast path and cleared its pending flag *before* doing the work, so only the thread that won the mutex actually blocked: every other thread read the cleared flag, skipped the mutex, and evaluated against the brand-new **empty** store. Sixteen threads hitting a freshly forked client against a 400ms config endpoint returned `{nil=>15, "v1"=>1}`. The flag now stays set for the whole rebuild, so every other caller blocks on it and then sees the fetched config — one fetch, one stream dial, one reporter per child, however many threads race the first request. A same-thread guard keeps a customer logger (a `semantic_logger_filter` / `stdlib_formatter` that evaluates a config) from deadlocking on the non-reentrant lock if it fires from inside the rebuild.
+- **Fix (fork): a hard timeout mid-rebuild no longer leaves the child dark forever (qfg-lv4n.1).** `Timeout::ExitException` (Ruby 3.3's `timeout` 0.4.1), rack-timeout's `RequestTimeoutException`, and `Thread#kill` are all `Exception`, not `StandardError`, so they crossed the rebuild's rescue untouched — and with the pending flag already cleared, every later call in that child returned `nil` over an empty store with no stream, no poller and no reporter, permanently. The flag is now cleared at the point the child actually has a live path to config, so anything that escapes before that leaves the rebuild armed and the next call retries it.
+- **Fix (fork): `stop` racing an in-flight rebuild no longer orphans an SSE worker (qfg-lv4n.1).** `stop` cleared the pending flag and tore down without taking the rebuild lock, so a rebuild already past that point went on to build a stream nothing held a reference to and nothing could close. `stop` now raises its stopped flag **before** queueing for the rebuild lock — an in-flight rebuild sees it and starts neither an update channel nor a telemetry reporter — and the teardown itself runs under that lock, so it can never interleave with construction.
+- **Fix (fork): a datadir child whose rebuild fails no longer dials SSE (qfg-lv4n.1).** The failure path started the update channel regardless of mode, so a child of a purely **offline** (datadir) client opened a stream to `stream.primary.quonfig.com` on its first lookup and then logged ``Error applying SSE envelope: undefined method `apply_envelope' for nil`` for every envelope that arrived — with nothing re-armed, repairing the workspace on disk never helped. A datadir client's healing path is the filesystem: the failure path now starts the datadir watcher when `data_dir_auto_reload` is on, and otherwise re-arms the rebuild so the next use retries the load.
+- **Fix (fork): `after_fork_in_child` called in the PARENT is now a no-op (qfg-lv4n.1).** Releases 1.0.0–1.3.0 documented calling `Quonfig.instance.after_fork_in_child` in the parent after `fork` returned as the workaround for the parent going dark. On 1.4.0 the parent's components are alive, so each such call orphaned a live SSE worker and its stream, zeroed the store, and stopped the **owner's** telemetry reporter — three calls took a process from 2 worker threads and 1 live stream to 8 and 4, and the orphans outlived `stop`. The hook now early-returns (one debug line) in the process that **owns** the client, decided by comparing the current pid against the one stamped when the client was built. **If you added that call in the parent as a 1.3.0 workaround, remove it; it does nothing there now.**
+- **Fix (fork): a child forked from inside an `on_update` callback rebuilds like any other child (qfg-lv4n.1).** Parent-vs-child detection asked whether the inherited SSE worker thread was alive. `on_update` runs *on* that worker thread, so a customer who forks from the callback forks on it — making it the child's one surviving thread, and making the inherited `@worker.alive?` answer **true in a real child**. Such a child was classified as the parent: the hook ignored it, it served the parent's snapshot for the rest of its life, reported `:connected`, and resumed the parent's SSE loop on the shared file descriptor. Ownership is now a pid stamp taken at construction (and re-taken when a child rebuilds), so a pid mismatch is proof of a fork child whatever the inherited `Thread` objects claim. The same stamp closes the other end of the hole: a parent-side `after_fork_in_child` on a client with no threads at all (datadir + `data_dir_auto_reload: false` + no SDK key) sailed straight past the old liveness guard and wiped the live store; it is now correctly a no-op.
+- **Fix (fork): a retried rebuild no longer dials a second stream (qfg-lv4n.1).** The rebuild disarms its pending flag only *after* the update channel is up, so a non-`StandardError` landing in that window (rack-timeout, `Timeout::ExitException`, `Thread#kill`) left the flag armed **with a live stream**. The retry re-ran network init, opened a second SSE stream, and overwrote `@sse_client` — orphaning the first worker where `stop` could never reach it, and leaving the child holding two streams against the delivery service. `start_update_channel` is now idempotent: it returns immediately if an SSE worker or poll supervisor is already alive.
+- **Fix (fork): `on_init_failure: :raise` behaves the same in a forked child as in a fresh client (qfg-lv4n.1).** A failed re-initialization was always swallowed and logged, so the documented "exactly like a newly constructed client" was false for the one option whose entire job is raise-vs-return. Under `:raise` the first use in a child now raises the init error out of the lookup — Reforge does the same, raising the init error out of `get` itself — and later lookups keep raising, without re-fetching, until the update channel lands an envelope. The update channel is still started on the way out so the child can heal. **Note that `:raise` is the default**, so with default options a forked child whose first lookup lands in a total delivery outage (primary and secondary both unreachable) raises where 1.3.0 silently served the parent's snapshot; set `on_init_failure: :return` if you would rather a child serve defaults through an outage. `:return` is unchanged: one line logged, defaults served.
+- **Fix (fork): `Quonfig.fork` / `Client#fork` in a child the hook already prepared returns the same client (qfg-4t5o).** The 1.0–1.3 README taught `on_worker_boot { Quonfig.fork }`, and on Ruby 3.1+ that call ran *after* the `Process._fork` hook had already prepared the client in the worker. Before first use it discarded the prepared client and built a second one with an eager fetch; after first use it left the worker holding two live SSE streams and two telemetry reporters, the first pair orphaned where `stop` could never reach them. `Client#fork` now returns `self` when the hook has already prepared it in the current process, so a leftover call from older docs is harmless. Outside a hook-prepared child (the owning process, Ruby 3.0, a client stopped before the fork) it still builds a fresh client, which is the Ruby 3.0 manual-wiring path; the old client is never stopped.
+- **Fix (fork): the public `store` / `resolver` / `evaluator` / `config_loader` readers route through the post-fork re-initialization (qfg-lv4n.1).** They bypassed it entirely, so in a forked child that had not been used yet `client.store.get(key)` answered `nil` and `client.resolver.get(key, {})` raised `MissingDefaultError` against the empty store. They stay public (semver) and now re-initialize before handing the component back; reading one in a forked child can therefore block on the child's own fetch.
+- **Fix (fork): the child drops inherited references instead of closing them.** `fork(2)` duplicates file descriptors, so the child's copy of the SSE socket points at the connection the **parent** is still streaming on — closing it would write a TLS `close_notify` onto that shared connection and kill the parent's stream. The child now nils `@sse_client`, `@poll_supervisor`, `@telemetry_reporter`, `@datadir_watcher`, and the pending fallback-engage timer without calling `close` / `stop` / `join` on any of them (joining an inherited thread blocks forever, since the thread does not exist in the child), then builds everything fresh.
+- **Fix (fork): the child's telemetry starts empty.** The forked child gets brand-new context-shape, example-context, evaluation-summary, and failover aggregators rather than inheriting the parent's half-full ones (the reporter is not *started* until the child's first use). The parent flushes the data it collected; the child reports only its own, so a fork no longer double-counts a window of evaluations.
+- **Fix (fork/telemetry): the inherited `at_exit` drain no longer speaks for the parent.** `TelemetryReporter#start` registers a process-wide `Kernel.at_exit` closure over the reporter; `fork(2)` copies it, and dropping the client's reference in the child does not unregister it — so any child that exited the normal way (block-form `fork` + `exit`, which is what the `parallel` gem does) POSTed a full copy of the **parent's** un-flushed window under the parent's `instanceHash`, and the parent then POSTed it again. The reporter now records an owner pid on `start`, and `sync`, `stop`, and the `at_exit` drain are no-ops (one debug line) in any other process; the child additionally discards the inherited aggregators. Measured on a three-child `Parallel.map`: 404 evaluations reported for 101 performed, now 101. Nothing is closed, stopped, or joined — the thread does not exist in the child and the HTTP connection's fd is shared with the parent.
+- **Fix (fork): one client failing to rebuild no longer takes the rest of the registry down with it.** The child-side fan-out was covered by a single hook-wide rescue, so the first `after_fork_in_child` to raise (thread exhaustion, a customer logger that raises) aborted the loop and every client behind it in the registry stayed dark. Each instance now has its own rescue and the fan-out continues, logging the failure at error.
+- **Fix (fork): a forked datadir child gets its own telemetry reporter (qfg-vquv).** The datadir branch of `after_fork_in_child` returned before the aggregator/reporter rebuild, so a datadir + SDK-key child — an emitting combination since 1.3.0 — recorded nothing of its own for the rest of its life. It now rebuilds aggregators and reporter under exactly the SDK-key gating a fresh client applies.
+- **Fix (diagnostics): `connection_state` derives from liveness, not from a stored flag.** It previously answered `:connected` off `@sse_state` alone, which the teardown path never reset — so a client with no SSE worker and no poller alive still reported healthy. That is why the incident above stayed invisible for 13 days. A network client that is supposed to hold an SSE stream and has no live worker now reports `:disconnected`. The documented value set (`:initializing`, `:connected`, `:disconnected`, `:falling_back`) is unchanged, and `:connected` still covers datadir mode and post-fetch clients with SSE disabled.
+- **Deprecated: `Client#before_fork_in_parent`.** Still public and still works, but the fork hook no longer calls it. There is no longer any reason to tear a parent down before forking; call `stop` if you want a client dead. Slated for removal in 2.0.0.
+- **Docs:** "one telemetry POST at exit" for a per-job forking worker is now qualified — the at-exit drain only happens when the child exits *normally*. `Parallel` children do; **Resque children call `exit!` by default**, which skips every `at_exit` handler, so there is no drain and no telemetry POST unless `RUN_AT_EXIT_HOOKS=1` is set.
+- **Docs:** the README's fork section previously claimed the SDK covered "Sidekiq's parent-forks-workers model" (Sidekiq OSS does not fork — it runs jobs on threads) and documented "does not auto-restart the parent" as intentional. Both are corrected. The Puma snippet no longer suggests `before_fork { Quonfig.instance.stop }`, and the cases that actually fork inside Sidekiq (the `parallel` gem, an explicit `fork { }`, Enterprise swarm) are named as covered. The Ruby 3.0 `parallel` snippet no longer calls `Quonfig.fork` once per row (that builds a client per item; it is now a pid-memoized rebuild once per child process, with a note that 3.0 is EOL), and the Puma/Unicorn worker-boot snippets show `SemanticLogger.reopen` alone on 3.1+ — calling `Quonfig.fork` there after the hook has already rebuilt leaves the worker with two live SSE streams and two reporters.
+
+## 1.3.0 - 2026-08-18
+
+> **Heads up — datadir users will start emitting telemetry.** Datadir mode with a valid SDK key now emits usage telemetry as documented; it previously sent nothing. If you run the SDK with a `datadir:` (or `QUONFIG_DIR`) **and** an SDK key, upgrading to 1.3.0 means evaluation summaries and context telemetry begin flowing to the telemetry service from that deployment — data you were not sending on 1.2.0. Disable with the standard telemetry options if unwanted (`collect_evaluation_summaries: false` and `context_upload_mode: :none`). A datadir client with **no** SDK key still sends nothing at all.
+
+- **Fix (telemetry): the telemetry gate is SDK-key presence, not delivery mode (qfg-5x9x).** `Options#telemetry_allowed?` consulted `local_only?` (i.e. "is a datadir set?"), which forced every `collect_max_*` to `0` the moment a datadir was configured. With no collector limits the client built no aggregators, took `initialize_telemetry`'s early return, and never constructed a `TelemetryReporter` — so a datadir client holding a perfectly valid SDK key emitted **no** evaluation summaries, **no** context telemetry, nothing at all. Datadir is a config-**delivery** mode: it decides where config comes from, not whether usage is reported. The gate is now the SDK key alone, which is what identifies the workspace telemetry is attributed to. This aligns sdk-ruby with sdk-node, sdk-go, sdk-python, sdk-java, and sdk-net, and is the inverse of the defect fixed for sdk-go / sdk-python in 1.2.1 (those *over*-sent without a key). No wire-format change, no new dependencies, no public API removed.
+- **Fix (telemetry): a keyless client now collects nothing at all.** Without an SDK key there is no workspace to attribute telemetry to, so the aggregators are no longer even allocated and the reporter never starts (previously the collectors filled up in delivery mode and were discarded at flush time). Behavior for the open-source / no-account path is unchanged from the outside — still zero telemetry HTTP — but nothing is accumulated in memory on the way there.
+- **Deprecated: `allow_telemetry_in_local_mode:` is now a no-op.** It existed only to re-enable telemetry that datadir mode had suppressed; with mode out of the decision there is nothing left for it to unlock. The kwarg is still accepted so existing callers keep working, and it can neither enable telemetry without a key nor suppress it with one. Slated for removal in 2.0.0 — use `collect_evaluation_summaries: false` / `context_upload_mode: :none` to opt out.
+- **Docs:** the README's datadir section previously claimed the mode "performs no network I/O" unconditionally. It now states the delivery-side guarantee precisely (no config fetch, no SSE, no polling) and documents the telemetry gate, including how to run datadir + key with telemetry off.
+
 ## 1.2.0 - 2026-07-08
 
 - **Feat (options): warn when an explicit `api_urls` disables automatic failover (qfg-41nh.26).** The default (and every `QUONFIG_DOMAIN`-derived) `api_urls` list carries a primary AND a secondary leg, and the HTTP config-fetch hedges/fails over between them (the secondary runs on separate infrastructure). An explicit `api_urls:` replaces that list wholesale, so a single-entry override silently dropped the secondary and disabled automatic failover. The client now logs one WARN at init when the caller explicitly set `api_urls` and the resolved list has fewer than two legs, pointing at the fix (pass both a primary and a secondary URL). Behavior is otherwise unchanged; no new dependencies. A new README "Failover & `QUONFIG_DOMAIN`" section documents the URL derivation and the failover model.

data/README.md

@@ -86,7 +86,8 @@ bound.get_int('rate-limit')
 
 For tests, CI, or air-gapped environments, point the client at a local workspace
 directory instead of the Quonfig API. In datadir mode the SDK loads JSON config
-files from disk and performs no network I/O.
+files from disk — config delivery does no network I/O at all: no config fetch,
+no SSE stream, no polling.
 
 ```ruby
 client = Quonfig::Client.new(
@@ -111,6 +112,32 @@ export QUONFIG_ENVIRONMENT=production
 client = Quonfig::Client.new  # reads QUONFIG_DIR + QUONFIG_ENVIRONMENT
 ```
 
+### Telemetry in datadir mode
+
+Usage telemetry is gated on **SDK-key presence, not on mode**. A datadir client
+with an `sdk_key:` configured still reports evaluation summaries and context
+telemetry to the telemetry service, exactly as a delivery-mode client does —
+that combination is what makes flag usage visible in the Quonfig UI for services
+that read config from a checked-out workspace.
+
+A datadir client with **no** SDK key has no workspace to attribute telemetry to,
+so it collects and sends nothing: fully offline, zero network I/O.
+
+To run with a key but without telemetry, use the standard opt-outs:
+
+```ruby
+client = Quonfig::Client.new(
+  datadir:                      '/path/to/workspace',
+  environment:                  'production',
+  sdk_key:                      ENV['QUONFIG_BACKEND_SDK_KEY'],
+  collect_evaluation_summaries: false,
+  context_upload_mode:          :none
+)
+```
+
+> Changed in 1.3.0: before 1.3.0 a datadir sent nothing even with a valid SDK
+> key. See the CHANGELOG.
+
 ## Datadir mode: auto-reload on file changes
 
 In datadir mode the SDK loads the workspace once at construction time and then
@@ -183,16 +210,16 @@ Default is `false`; datadir mode is silent until you opt in.
 
 The auto-reload watcher uses a background thread, which — like any Ruby
 thread — does not survive `fork(2)`. **You do not need to wire this up
-manually on Ruby 3.1+.** The SDK's `Process._fork` hook (see [Rails
-integration](#rails-integration) below) stops the watcher in the parent
-before fork and restarts a fresh watcher in each child after fork. This
-covers Puma clustered mode, Unicorn, Sidekiq's parent-forks-workers model,
-Resque, Spring, and manual `fork { ... }` calls.
+manually on Ruby 3.1+.** After a fork, the child re-loads the workspace from
+disk and registers a fresh watcher on its first use of the client (see [Rails
+integration](#rails-integration) below); a child that never uses the client
+starts no watcher at all. The parent's watcher is left alone and keeps
+working. This covers Puma clustered mode, Unicorn, Resque, Spring, and manual
+`fork { ... }` calls — including a `fork` inside a Sidekiq job.
 
-On Ruby 3.0 (no `Process._fork`), follow the manual `before_fork` /
-`on_worker_boot` pattern in the [Rails integration](#rails-integration)
-section — `Quonfig.fork` rebuilds the full client, including the datadir
-watcher, in the child.
+On Ruby 3.0 (no `Process._fork`), follow the manual `on_worker_boot` pattern
+in the [Rails integration](#rails-integration) section — `Quonfig.fork`
+rebuilds the full client, including the datadir watcher, in the child.
 
 ### Tuning the debounce window
 
@@ -387,16 +414,41 @@ If both are supplied, the explicit `logger_name:` wins.
 
 ## Rails integration
 
-The SDK runs a background SSE thread (and optional polling thread) that you do
-not want to inherit across a `fork(2)`. Forked threads in the child process
-are dead — the SSE socket is held open by a thread that no longer exists, and
-the child silently stops receiving live updates.
+The SDK runs a background SSE thread (and optional polling thread). Ruby
+threads do not survive `fork(2)`, so a child process inherits references to
+threads that no longer exist and silently stops receiving live updates.
 
 **On Ruby 3.1+ the SDK installs a `Process._fork` hook at load time** that
-automatically tears down threaded components in the parent and restarts them
-in the child. This covers any `Process.fork` / `Kernel#fork` path — Puma's
-clustered mode, Unicorn, Sidekiq's parent-forks-workers model, Spring, and
-manual `fork { ... }` calls. **No customer wiring is required.**
+handles this for you. It covers any `Process.fork` / `Kernel#fork` path —
+Puma's clustered mode, Unicorn, Spring, Resque, a `fork { ... }` inside a
+Sidekiq job, and the `parallel` gem. **No customer wiring is required.**
+
+**The hook is child-only. A fork never touches the process that forked.**
+The parent keeps its SSE stream, its poller, its telemetry reporter, and its
+live config straight through any number of forks — so a long-lived process
+that forks workers *and keeps evaluating* (a Sidekiq process using the
+`parallel` gem, a rake task that calls `fork`) stays current.
+In the child, the SDK drops the inherited references without touching the
+objects — it never closes the inherited socket, because `fork(2)` duplicates
+the file descriptor and closing the child's copy of a TLS connection would
+tear down the stream the **parent** is still using.
+
+> **Upgrading from 1.3.0 or earlier:** if you added a manual
+> `Quonfig.instance.after_fork_in_child` call **in the parent** as a
+> workaround for the parent going dark, remove it. As of 1.4.0 that call is a
+> no-op in the process that owns the client — the SDK decides that by
+> comparing the current pid against the one it stamped when the client was
+> built, so it is exact whether or not the parent has any threads running. It
+> will not hurt you, but it is no longer doing anything, and the parent needs
+> no call.
+
+**After a fork, the child re-initializes on its first use of the client,
+exactly like a newly constructed client — including its `on_init_failure`
+policy: it fetches its own config and starts its own threads. It does not
+evaluate from the parent's snapshot.** The hook itself does no I/O — it drops
+what the child inherited and arms the re-initialization. So the first call in
+a forked child pays one fetch, and a child that never uses the client costs
+nothing: no fetch, no stream, no thread, no telemetry.
 
 Caveats:
 
@@ -404,13 +456,44 @@ Caveats:
 - `system("fork-and-exec ...")` and `Process.spawn` are not covered (they do
   not go through `Process._fork`), but those execute a new program, so the
   in-process SSE state is moot.
-- The hook tears down the SSE/polling/telemetry threads in the parent before
-  fork (so the child does not inherit a live socket fd) and does **not**
-  auto-restart the parent. This mirrors the Puma master case: the master no
-  longer serves requests, so it does not need a live SSE connection. If you
-  have a non-Puma topology where the parent must keep streaming after fork,
-  call `Quonfig.instance.after_fork_in_child` manually in the parent after
-  the fork returns.
+- The first lookup in a forked child **blocks** on that child's own config
+  fetch, under the same `init_timeout_ms` and `on_init_failure` options a
+  fresh client uses. **The default is `on_init_failure: :raise`**, so if the
+  child's fetch fails against every `api_urls` leg (primary and secondary
+  both unreachable) the failure **raises out of that first lookup**, exactly
+  as `Client.new` would at boot, and later lookups keep raising — without
+  re-fetching — until the update channel lands an envelope, at which point
+  the client serves config normally again. On 1.3.0 and earlier a child in
+  that situation silently served the parent's snapshot instead. If you would
+  rather a forked child serve defaults through an outage, set
+  `on_init_failure: :return`: a failed fetch then logs one line and the child
+  serves defaults until its stream or poller lands the first envelope.
+- **Other threads wait.** Every thread that reaches the client while that
+  first fetch is in flight blocks on it and then sees the fetched config. One
+  fetch, one stream dial, and one telemetry reporter per child, however many
+  threads race the first request.
+- **`connection_state` never triggers the re-initialization** — a diagnostic
+  must not open a socket. A child that has not used the client yet answers
+  `:initializing`, which is exactly what it is; it flips to `:connected` on
+  first use.
+- The child's telemetry aggregators start empty. The parent flushes the data
+  it collected before the fork; the child reports only its own.
+- **Per-job forking pays per job.** A Resque-style worker that forks a child
+  per job (or `Parallel.map` with one row per process) pays, in each child
+  that touches the client, one config fetch, one SSE dial, and — **when the
+  child exits normally** — one telemetry POST at exit. That is the price of
+  the child holding its own current config and its own telemetry window, and
+  it is deliberate — the delivery service counts each of those connections as
+  a real client. A child that never uses the client pays none of it.
+
+  The at-exit drain depends on the child running `at_exit` handlers at all.
+  `Parallel` children do. **Resque children call `exit!` by default**, which
+  skips every `at_exit` handler — so there is no drain and no telemetry POST
+  unless you set `RUN_AT_EXIT_HOOKS=1`. Nothing else about the child changes;
+  it just never flushes the evaluations it collected.
+- In datadir mode a child whose workspace fails to load never dials the
+  network: it logs the failure and, if `data_dir_auto_reload` is on, watches
+  for a repaired workspace; otherwise the next use retries the load.
 
 ### Puma (clustered mode)
 
@@ -423,52 +506,72 @@ handle the rest:
 Quonfig.init(Quonfig::Options.new(sdk_key: ENV.fetch('QUONFIG_BACKEND_SDK_KEY')))
 ```
 
-If you're on Ruby 3.0 (no `Process._fork`), wire the legacy hooks manually:
+If you use SemanticLogger you still need to reopen it in each worker — but
+`Quonfig.fork` is not needed in that block on 3.1+. The SDK has already
+handled the fork by the time `on_worker_boot` runs, and since 1.4.0 a
+`Quonfig.fork` call in a child the hook has already prepared simply returns
+the same client (so a leftover call from older docs is harmless):
 
 ```ruby
-# config/puma.rb (Ruby 3.0 only)
-before_fork do
-  Quonfig.instance.stop          # close the master's SSE before forking
+# config/puma.rb (Ruby 3.1+)
+on_worker_boot do
+  SemanticLogger.reopen
 end
+```
+
+If you're on Ruby 3.0 (no `Process._fork`), wire the worker boot hook
+manually:
 
+```ruby
+# config/puma.rb (Ruby 3.0 only)
 on_worker_boot do
-  Quonfig.fork                   # rebuild a fresh client per worker
+  Quonfig.fork          # rebuild a fresh client per worker
+  SemanticLogger.reopen # if you use SemanticLogger
 end
 ```
 
+Do **not** add a `before_fork { Quonfig.instance.stop }` — the master's
+client does not need to be torn down for the workers to be healthy, and
+stopping it means the master stops receiving config.
+
 ### Sidekiq
 
-On Ruby 3.1+ the automatic fork hook covers Sidekiq workers too — no
-`configure_server` wiring required.
+Sidekiq OSS does not fork: it runs jobs on threads inside one process, so
+`Quonfig.init` in your initializer is all you need on any Ruby version.
 
-On Ruby 3.0:
+Some jobs *do* fork — the `parallel` gem, an explicit `fork { ... }`, or
+Sidekiq Enterprise's swarm mode. On Ruby 3.1+ those are covered
+automatically, with nothing to call, and (since 1.4.0) the Sidekiq process
+itself keeps streaming config the whole time.
 
-```ruby
-# config/initializers/quonfig.rb
-Quonfig.init(Quonfig::Options.new(sdk_key: ENV.fetch('QUONFIG_BACKEND_SDK_KEY')))
+Ruby 3.0 is end-of-life and has no `Process._fork` hook. The `parallel` gem
+has no per-worker boot hook to wire a rebuild into either — `Parallel.each`
+just runs your block in each child, once per row — so calling `Quonfig.fork`
+at the top of the block builds a **new client per row**, each with its own
+SSE stream and telemetry reporter. Upgrade to 3.1+ if you can. If you must
+stay on 3.0, rebuild once per child process by memoizing on the pid:
 
-# config/initializers/sidekiq.rb (Ruby 3.0 only)
-Sidekiq.configure_server do |config|
-  config.on(:startup)  { Quonfig.fork if Process.ppid != 1 }
-  config.on(:shutdown) { Quonfig.instance.stop rescue nil }
+```ruby
+# Ruby 3.0 only — one rebuild per child process, not one per row.
+Parallel.each(batch, in_processes: 4) do |row|
+  Quonfig.fork if $quonfig_pid != Process.pid
+  $quonfig_pid = Process.pid
+  # ...
 end
 ```
 
-For Sidekiq web/CLI processes that don't fork (default `concurrency: 1`),
-`Quonfig.init` in the initializer is sufficient on any Ruby version.
-
 ### Spring / Bootsnap preloaders
 
-Spring forks the preloader for each command. If your initializer creates a
-Quonfig client at boot, the SSE thread will be inherited dead in every child.
-Two options:
+Spring forks the preloader for each command. On Ruby 3.1+ the automatic hook
+already rebuilds the client in each spawned command, and the preloader itself
+keeps streaming. On Ruby 3.0, either:
 
 1. **Recommended:** initialize lazily — wrap `Quonfig.init` so it only runs
    the first time `Quonfig.instance` is called from a non-preloader process.
 2. **Or:** call `Quonfig.fork` from a `Spring.after_fork` hook.
 
 ```ruby
-# config/spring.rb
+# config/spring.rb (Ruby 3.0 only)
 Spring.after_fork do
   Quonfig.fork if defined?(Quonfig) && Quonfig.instance_variable_get(:@singleton)
 end
@@ -501,8 +604,10 @@ envelope is intentional: a reader concurrent with envelope application may
 observe the new value for some keys and the old value for others, then
 converge once the envelope finishes applying.
 
-`Quonfig.fork` is the only safe way to "carry" a client across `Process.fork`
-— do not reuse the parent's client in a child process.
+Forking is handled for you on Ruby 3.1+: the child rebuilds automatically and
+the parent is left running (see [Rails integration](#rails-integration)). On
+Ruby 3.0, `Quonfig.fork` is the way to "carry" a client into a child — do not
+reuse the parent's client object in a child process without it.
 
 ## Diagnostic health signals