quonfig 1.1.0 → 1.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d12e38af54000d7cfeb34f7c3f50739527e63448668abf9d6fd4b436b27b277f
-  data.tar.gz: 1421bc6f53246ee1260a5c832ef342faa5ca70b6854acba6f12d9b51a464e99d
+  metadata.gz: df149576c34f45d691f7252a2f0e05b2c02b95681ab9986fac6a373071210c7e
+  data.tar.gz: ab5dc409a48ed4f471b500d62451a8d1b3b1e7de67871172ce684327ba7a1777
 SHA512:
-  metadata.gz: 73d25bb37c6c30e1d1b756172e0ffd4885bf901c9b600eec3c060f06bead7b45cf74e09544908d925a4345fcb5f9b6efe6d8331d7f8544079ffabf7b9d5b1228
-  data.tar.gz: 04df7b6f24efb0f9a3c30c47e32c686f2407ac54c1776eb7a2313fe1332f8339eac4693fc49edb49d76e00b7521680701bedfbfae5839b4d9158b3ace473efbc
+  metadata.gz: dec2b311edf9f515e00803d7f2a60c9f10897807779b26a44f4aa842ef5ac46239a432a194e72378eb23c3e03a79002ff3332e6d72be265683b707adb88134ed
+  data.tar.gz: 55c3a892dfa3af12e4db273e09faf5f0b96c8c2861cdfdb611c9ba75877a6e3a1c696568593b0cdd6283874b072f259738cc14c8d3a871a432cfbc17a194df35

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 1.1.1 - 2026-07-03
+
+- **Fix (SSE): the stream leg is pinned to the primary stream URL — SSE never fails over (qfg-41nh.6).** The reconnect loop previously rotated through `sse_api_urls` on every reconnect, so with the default two derived stream URLs a primary blip silently parked the live stream on `stream.secondary` and bound config freshness to the mirror. The stream now always dials `sse_api_urls[0]` and retries it forever with backoff (matching sdk-go); failover remains HTTP-poll only, and the HTTP config-fetch hedge still uses both `api_urls` legs. The `sse_failed_over_to_secondary?` diagnostic is now latched at the dial site, and the failover chaos harness hands the client both stream legs so the f05 probe actually exercises the pin.
+- **Fix (delivery): per-leg config-fetch aborts are now wall-clock (qfg-41nh.6).** The per-leg timeout was enforced with Faraday/Net::HTTP phase timeouts, which are per-read — a slow-drip upstream (one byte per interval) could hold a "bounded" leg open indefinitely and wedge the init fetch, a fallback poll tick, or the hedge drain. `timeout_ms` (plus a small headroom) is now also enforced as a wall-clock ceiling over the whole request, surfacing a `Faraday::TimeoutError` through the existing failure paths. Hedged legs additionally always settle their drain slot, so `fetch!` is guaranteed to return within the per-leg abort budget.
+- **Fix (client): liveness signals no longer lie during outages (qfg-41nh.6).** The fallback poll worker stamped `last_successful_refresh` and fired `on_update` on every tick regardless of fetch outcome, so a total outage with `on_init_failure: :return` reported `ready? == true` over an empty store. The worker now stamps freshness only on successful fetches (`:updated` / `:not_modified`; a 304 or guard-rejected-but-successful response counts) and fires `on_update` only when an envelope is actually installed, matching sdk-go.
+- **Fix (client): the fallback poller fetches immediately on engage and logs the engage edge (qfg-41nh.6).** The poll worker previously slept a full interval before its first fetch, so the first post-engage data arrived ~180s after SSE loss (default 60s interval) vs ~120s in sdk-go; it now fetches first, then sleeps. Engaging Layer 2 also logs at WARN (previously silent — only the stop path logged, at debug), matching sdk-go's operator signal.
+
 ## 1.1.0 - 2026-07-01
 
 - **Feat (delivery): the HTTP config-fetch is now a parallel-failover hedge (qfg-7h5d.1.14).** On every init/refresh config fetch the SDK fires the **primary** `api_urls` leg first; if it answers within `config_fetch_hedge_delay_ms` it **wins and the secondary is never contacted** (cold standby — a healthy system adds zero secondary load). If the primary is slow past the hedge delay **or** errors fast, the SDK **also** fires the secondary **in parallel** without cancelling the primary. Whatever arrives is installed through the existing reject-older guard, so watermark-max falls out for free: the higher generation wins, a late older payload never regresses an established client, and a late newer payload heals forward. Readiness latches on the first successful install; a late-but-newer leg heals forward afterward. SSE is untouched — only the HTTP config-fetch path hedges. Both legs failing preserves the existing init-failure semantics (`on_init_failure`).

data/lib/quonfig/client.rb

@@ -970,18 +970,35 @@ module Quonfig
 
       poll_seconds = poll_ms / 1000.0
       stopped_ref = -> { @stopped }
+      # Fetch-first (qfg-41nh.6): the poller fetches IMMEDIATELY on engage and
+      # then sleeps the interval — matching sdk-go's fallback_poller.go
+      # engage() (immediate Fetch, then ticker). A sleep-first worker made the
+      # first post-engage data arrive a full extra interval late (~180s after
+      # SSE loss with the default 60s interval, vs ~120s in go).
       worker = lambda do |notify_delivered|
         loop do
           break if stopped_ref.call
 
-          sleep poll_seconds
+          result = @config_loader.fetch!
+          # Liveness honesty (qfg-41nh.6): stamp freshness only when the fetch
+          # actually SUCCEEDED. :updated and :not_modified (a 304, or a
+          # guard-rejected-but-successful response) are successes — the
+          # channel is healthy; :failed must NOT advance
+          # last_successful_refresh (pre-fix every tick stamped + notified
+          # regardless of outcome, so ready?/freshness reported healthy over
+          # an empty store through a total outage). on_update fires only on a
+          # real install, matching sdk-go (OnConfigUpdate fires in
+          # installEnvelope only).
+          if result != :failed
+            sync_evaluator_env_id!
+            record_refresh!
+            notify_delivered.call
+          end
+          notify_on_update_callback if result == :updated
+
           break if stopped_ref.call
 
-          @config_loader.fetch!
-          sync_evaluator_env_id!
-          record_refresh!
-          notify_delivered.call
-          notify_on_update_callback
+          sleep poll_seconds
         end
       end
 
@@ -990,6 +1007,10 @@ module Quonfig
       )
       @state_mutex.synchronize { @poll_supervisor = supervisor }
       supervisor.start
+      # Operator signal (qfg-41nh.6): engage was previously unlogged (only the
+      # stop path logged, at debug). Matches sdk-go's WARN on OnEngage — the
+      # poller engaging means the SDK is in a degraded update mode.
+      LOG.warn "[quonfig] Layer 2 fallback poller engaged (interval=#{poll_ms}ms)"
     end
 
     # Invoke the customer-supplied on_update callback under a rescue. A raise

data/lib/quonfig/config_loader.rb

@@ -180,15 +180,21 @@ module Quonfig
       gate = Mutex.new
       secondary_fired = false
 
+      # Each leg is wall-clock bounded by abort_ms (HttpConnection enforces a
+      # whole-request deadline, qfg-41nh.6), so a leg ALWAYS settles — a
+      # slow-drip upstream can no longer hold a leg open past the abort and
+      # wedge the drain below. The push lives in an ensure so even a
+      # non-StandardError escape still settles this leg's drain slot.
       run_leg = lambda do |index|
         Thread.new do
-          result = begin
-            fetch_from(urls[index], index, timeout_ms: abort_ms)
+          result = :failed
+          begin
+            result = fetch_from(urls[index], index, timeout_ms: abort_ms)
           rescue StandardError => e
             @logger.debug "Hedge leg #{index} failed: #{e.class}: #{e.message}"
-            :failed
+          ensure
+            results.push([:done, index, result])
           end
-          results.push([:done, index, result])
         end
       end
 

data/lib/quonfig/http_connection.rb

@@ -2,6 +2,7 @@
 
 require 'base64'
 require 'json'
+require 'timeout'
 
 module Quonfig
   class HttpConnection
@@ -13,13 +14,26 @@ module Quonfig
       'X-Quonfig-SDK-Version' => SDK_VERSION
     }.freeze
 
+    # qfg-41nh.6 (WS2.4): headroom added to +timeout_ms+ to form the WALL-CLOCK
+    # ceiling for the whole request. Faraday's open/read timeouts are per-phase
+    # and — on the Net::HTTP adapter — per-READ: every byte that arrives resets
+    # the read deadline, so a slow-drip upstream (one byte per interval) holds a
+    # "bounded" request open indefinitely and wedges the caller (init fetch,
+    # fallback poll tick, hedge drain). The wall clock is the true per-leg abort
+    # (sdk-go's per-leg context deadline is wall-clock). The headroom keeps
+    # Faraday's own, more specific phase timeouts winning the simple-stall race;
+    # the wall clock only fires on drip-feed pathologies that per-read deadlines
+    # structurally cannot catch.
+    WALL_CLOCK_HEADROOM_S = 0.25
+
     # +timeout_ms+ (qfg-7h5d.1.9): per-request bound applied to BOTH the connect
-    # (open) and read phases of every request made through this connection. nil
+    # (open) and read phases of every request made through this connection, AND
+    # (qfg-41nh.6) enforced as a wall-clock ceiling over the whole request. nil
     # leaves Faraday's defaults (no timeout) in place — preserving the prior
     # behavior for callers that don't pass one. The config-fetch path passes
-    # Options#config_fetch_timeout_ms so a hung upstream (accepts the TCP
-    # connection but never responds) aborts fast instead of blocking the caller's
-    # whole init budget.
+    # Options#config_fetch_timeout_ms (sequential) or the hedge abort (hedged
+    # legs) so a hung OR drip-feeding upstream aborts fast instead of blocking
+    # the caller's whole init budget.
     def initialize(uri, sdk_key, timeout_ms: nil)
       @uri = uri
       @sdk_key = sdk_key
@@ -29,11 +43,11 @@ module Quonfig
     attr_reader :uri
 
     def get(path, headers = {})
-      connection(headers).get(path)
+      with_wall_clock_deadline { connection(headers).get(path) }
     end
 
     def post(path, body)
-      connection.post(path, body.to_json)
+      with_wall_clock_deadline { connection.post(path, body.to_json) }
     end
 
     def connection(headers = {})
@@ -54,6 +68,23 @@ module Quonfig
 
     private
 
+    # Enforce +timeout_ms+ (+ headroom) as a wall-clock deadline over the whole
+    # request. Timeout.timeout is the codebase's accepted backstop pattern (the
+    # init path wraps fetch! the same way in Client#perform_initial_fetch); a
+    # deadline check inside the read loop isn't practical here because Faraday
+    # 1.x's Net::HTTP adapter exposes no per-chunk streaming hook. Raises
+    # Faraday::TimeoutError so callers' existing timeout rescue paths apply
+    # unchanged. No-op when no timeout_ms was configured.
+    def with_wall_clock_deadline(&block)
+      return block.call unless @timeout_ms
+
+      deadline_s = (@timeout_ms / 1000.0) + WALL_CLOCK_HEADROOM_S
+      Timeout.timeout(deadline_s, Faraday::TimeoutError,
+                      "wall-clock per-request deadline #{deadline_s}s exceeded for #{@uri}") do
+        block.call
+      end
+    end
+
     def auth_header
       "Basic #{Base64.strict_encode64("1:#{@sdk_key}")}"
     end

data/lib/quonfig/sse_config_client.rb

@@ -87,14 +87,16 @@ module Quonfig
       @conn_mutex = Mutex.new
       @active_http = nil
 
-      @source_index = -1
       @last_event_id = nil
-      # qfg-7h5d.1.9: latches true if the SSE reconnect rotation ever selects a
-      # non-primary (index > 0) sse_api_urls leg. The failover epic asserts SSE
-      # does NOT fail over to the secondary (f05) — it stays on its own endpoint
-      # and degrades via the single-upstream SSE↔HTTP fallback. With a single SSE
-      # URL configured this can never flip; the flag makes the design choice
-      # observable (and would surface a regression if SSE were given two legs).
+      # qfg-7h5d.1.9 / qfg-41nh.6: latches true if a connection attempt ever
+      # targets a non-primary sse_api_urls leg. The failover epic asserts SSE
+      # does NOT fail over to the secondary (f05) — the stream is PINNED to
+      # sse_api_urls[0] and degrades via the single-upstream SSE↔HTTP fallback,
+      # so with a correct #current_url this never flips even when a secondary
+      # stream URL is configured (options derive one from api_urls by default).
+      # The latch is measured at the dial site in #stream_once, so a regression
+      # that reintroduces stream-URL rotation is observable to the failover
+      # chaos probe (f05) and to operators.
       @failed_over_to_secondary = false
     end
 
@@ -269,7 +271,13 @@ module Quonfig
     # gotcha and solve it the same way: per-chunk reset, async close on
     # expiry (chaos scenario 02 — sse_silent_stall).
     def stream_once(&block)
-      url = "#{current_url}/api/v2/sse/config"
+      base = current_url
+      # f05 latch: record if this connection attempt targets a non-primary
+      # stream leg. With the pin in #current_url this is structurally false;
+      # measuring at the dial site (rather than inside URL selection) keeps a
+      # rotation regression observable to the chaos probe.
+      @failed_over_to_secondary = true if base != @prefab_options.sse_api_urls.first
+      url = "#{base}/api/v2/sse/config"
       cursor = current_cursor
       @logger.debug "SSE Streaming Connect to #{url} start_at #{cursor.inspect}"
 
@@ -405,14 +413,15 @@ module Quonfig
       end
     end
 
-    # Rotate through configured SSE URLs. The same rotation rule the
-    # previous implementation used, preserved so multi-region failover
-    # behavior is unchanged.
+    # The stream leg is PINNED to the primary stream URL (sse_api_urls[0])
+    # and retried forever with backoff — SSE never fails over (f05 invariant,
+    # qfg-41nh.6). Failover is HTTP-poll only: the config-fetch hedge keeps
+    # BOTH api_urls legs, but the live stream never repoints to
+    # stream.secondary (which is sized for poll rps, not SSE herds, and would
+    # silently bind freshness to the mirror). Matches sdk-go's sseClient — a
+    # single pinned URL with reconnect backoff (sse_client.go runLoop).
     def current_url
-      urls = @prefab_options.sse_api_urls
-      @source_index = (@source_index + 1) % urls.size
-      @failed_over_to_secondary = true if @source_index.positive?
-      urls[@source_index]
+      @prefab_options.sse_api_urls.first
     end
 
     # Internal: HTTP-status sentinel error for non-200 SSE responses. Surfaces

data/lib/quonfig/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: quonfig
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.1.1
 platform: ruby
 authors:
 - Jeff Dwyer
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-01 00:00:00.000000000 Z
+date: 2026-07-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport