quonfig 1.4.0 → 1.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5e8807ad54199b5ee24245cdf140a72aed0644e712308d867457d729df1bb122
-  data.tar.gz: 20b1d12fb441394f4d31198854b55dd90f78c925115982a32548415993c77958
+  metadata.gz: 8ecc1b6f2a6c327c36d7da4cf091623b8c44b81d6949b887356301961229a684
+  data.tar.gz: bf357130f83dc29baf032c8dd0db652c8910797aac2fc6a499ec3461e5b56ff6
 SHA512:
-  metadata.gz: cda8d4a8d332710a58f3be0e1e068e767858c9806f199bc23a5a2f010e7540d4fd9a159b20ac23f9d34f1a7f60b5aac10fcffdeda030356ace8536779048126a
-  data.tar.gz: 33dcc1b5201298630936e743f5e44b188393b810ee94287623dce7598b98ab68ee0a2eb8bddb70f92da2fb3419f6a0b7f2a3081e2510b7f2d144087765b541b6
+  metadata.gz: '08951e8e2261dce91f0308de7920ea46eef5077979efdd0bd8df55b403719d8fb1f2e7f6ed863a12d38108b30cdef8b92d08832059a68c45b96425a5ced249f6'
+  data.tar.gz: 81738455b310e66693801fe2b2aa3ff027e676b28b032398271d1de17c9421212d5e0c9d3b20c37164a7299c74f2347a52f371abfabc36d8ebca3c75492d17d0

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 1.4.1 - 2026-09-11
+
+- **Fix (fork/telemetry): a forked child now reports under its OWN `instanceHash` (qfg-xcym).** `@instance_hash` was minted once in `Client#initialize` and survived `fork(2)`, so every forked child POSTed its telemetry under the **parent's** hash. The Quonfig Debugger groups SDK last-seen by that hash, so an 8-worker Puma cluster (or a `parallel`-gem batch) collapsed into a single instance row with the parent's and the children's windows interleaved on top of each other. A child now mints a fresh hash as part of the same post-fork rebuild that gives it fresh aggregators and a fresh reporter — before the reporter is constructed, so the hash the child POSTs under is its own. This is parity with Reforge, where a forked process simply builds a whole new client. The parent's hash is never touched, and a child's row count is unchanged (it already reported its own window; it just did so under the wrong identity). Present since 0.0.16.
+- **Fix (telemetry): only a STRICTLY older payload counts as `guardRejected` (qfg-rr5b).** The reject-older install guard treated an **equal**-generation payload as "older" and counted it, but two server behaviors re-deliver the envelope a client already holds in perfectly normal steady state: api-delivery's SSE `sendInitialConfig` re-sends the current envelope on every connect regardless of the `Last-Event-Id` the client sends, and a config poll against an empty per-leg ETag slot — a fresh transport, a reconnect, the fallback poller's engage fetch — answers with a full 200 at the same generation. A healthy client therefore reported `guardRejected >= 1` from initialization alone and picked up another on every SSE reconnect, which is noise in a field whose entire purpose is to say "a leg tried to move us **backwards**". **Semantic narrowing worth noting if you query this field: equal-generation re-deliveries are no longer counted, so `guardRejected` will read lower than on 1.4.0 for the same traffic — that is the fix, not a regression.** Nothing else about the guard changed: an equal-generation envelope is still not installed, still returns `:not_modified`, and still advances the liveness stamp exactly where it did before, and the unversioned (`generation <= 0`) carve-out is untouched. No wire, ClickHouse, or dashboard-query change is required. This is the Ruby half of a change being applied across all six backend SDKs (sdk-python ships it in 1.4.1; Go, Java, .NET and Node follow in their next releases), so counts may differ across languages until then.
+- **Docs (fork): a child forked from inside an `on_update` callback must exit (qfg-ec2q).** `on_update` runs on the SDK's SSE reader thread, so a child created with non-block `fork` (no block) from inside that callback inherits that thread as its one surviving thread. If the child does its work and *returns* from the callback instead of exiting, the inherited reader resumes its read loop on the **parent's** socket and consumes frames the parent never sees. The README fork section now says to `exit!` (or `exec`) from such a child. Block-form `fork { ... }`, any child that exits, the documented patterns, and the `parallel` gem are all unaffected — no code change.
+
 ## 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`.

data/README.md

@@ -494,6 +494,13 @@ Caveats:
 - 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.
+- **A child forked from inside an `on_update` callback must exit.**
+  `on_update` runs on the SDK's SSE reader thread, so a child created with
+  non-block `fork` (no block) from inside that callback must `exit!` (or
+  `exec`) rather than return from the callback — a child that returns lets the
+  inherited reader thread resume on the parent's socket, where it consumes
+  frames the parent never sees. Block-form `fork { ... }` and any child that
+  exits are unaffected.
 
 ### Puma (clustered mode)
 

data/lib/quonfig/client.rb

@@ -437,6 +437,18 @@ module Quonfig
       # fetches (or loads) its own on first use.
       reset_store_in_child!
 
+      # A fresh instance hash (qfg-xcym). `@instance_hash` identifies this
+      # SDK instance in every telemetry payload, and app-quonfig's Debugger
+      # groups SDK last-seen by it — so a child that keeps the parent's hash
+      # collapses an 8-worker Puma cluster into ONE row with the parent's and
+      # the children's windows interleaved. Reforge does not have this
+      # problem: `Reforge.fork` builds a whole new Client, which mints its
+      # own. This MUST run before +rebuild_aggregators_in_child!+: the
+      # reporter captures the hash at construction, so minting after the
+      # rebuild would leave the child POSTing under the parent's identity.
+      # The parent's hash is untouched — the hook never runs there.
+      @instance_hash = SecureRandom.uuid
+
       # Fresh aggregators. The parent flushes its own copy; a child that
       # flushed inherited data would double-report it. The reporter is BUILT
       # here (so the child's config loader points at the child's failover

data/lib/quonfig/config_loader.rb

@@ -392,11 +392,29 @@ module Quonfig
         # ordering info, so it is never rejected as "older"; freezing the client
         # on stale config would be worse (mirrors sdk-node).
         unless @held_generation.nil? || incoming_gen <= 0 || incoming_gen > @held_generation
-          @logger.debug "Reject-older guard: dropping incoming generation #{incoming_gen} <= held #{@held_generation} (source=#{source})"
-          # Failover observability (qfg-41nh.18): count the guard rejection. This
-          # single guard covers BOTH the HTTP config-fetch path and the SSE
-          # message path (apply_envelope) — every network install funnels here.
-          @failover_aggregator&.record_guard_rejected
+          if incoming_gen < @held_generation
+            @logger.debug "Reject-older guard: dropping incoming generation #{incoming_gen} < held #{@held_generation} (source=#{source})"
+            # Failover observability (qfg-41nh.18): count the guard rejection.
+            # This single guard covers BOTH the HTTP config-fetch path and the
+            # SSE message path (apply_envelope) — every network install funnels
+            # here. Only a STRICTLY older payload is counted (qfg-rr5b): that is
+            # the one thing `guardRejected` is meant to report, "a leg tried to
+            # move us backwards", which is what the sdk_failover dashboard panel
+            # is for.
+            @failover_aggregator&.record_guard_rejected
+          else
+            # Equal generation: a re-delivery of the envelope we already hold, and
+            # a silent no-op (qfg-rr5b). Two server behaviors produce it in normal
+            # steady state — api-delivery's SSE `sendInitialConfig` re-sends the
+            # current envelope on every connect regardless of the Last-Event-Id
+            # we send, and a config poll on an empty per-leg ETag slot (a
+            # fresh transport, a reconnect, the fallback poller's engage fetch)
+            # returns a full 200 at the same generation. Counting those as
+            # `guardRejected` made a healthy client report failover activity from
+            # init alone. Not installed, not counted — but still :not_modified, so
+            # the caller's liveness stamp is unchanged.
+            @logger.debug "Same-generation re-delivery: ignoring incoming generation #{incoming_gen} (source=#{source})"
+          end
           return :not_modified
         end
 

data/lib/quonfig/telemetry/failover_aggregator.rb

@@ -45,8 +45,10 @@ module Quonfig
         end
       end
 
-      # Count one install dropped by the reject-older ordering guard (an
-      # equal-or-older snapshot on any install path — HTTP config-fetch or SSE).
+      # Count one install dropped by the reject-older ordering guard because it
+      # was STRICTLY older than the held generation, on any install path (HTTP
+      # config-fetch or SSE). An equal-generation re-delivery is dropped too but
+      # is not counted (qfg-rr5b).
       def record_guard_rejected
         @mutex.synchronize do
           @start_at_ms ||= Quonfig::TimeHelpers.now_in_ms

data/lib/quonfig/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Quonfig
-  VERSION = '1.4.0'
+  VERSION = '1.4.1'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: quonfig
 version: !ruby/object:Gem::Version
-  version: 1.4.0
+  version: 1.4.1
 platform: ruby
 authors:
 - Jeff Dwyer