quonfig 1.0.0 → 1.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4a4a3747c89f6d3eff1e1708f103c4b131784bb39826be73df5756bf2c52582a
-  data.tar.gz: 2346cd0fb9d75dc3bcbd382ffa312bfa1b67ae2fb6cb57321bf964f40aebc089
+  metadata.gz: df149576c34f45d691f7252a2f0e05b2c02b95681ab9986fac6a373071210c7e
+  data.tar.gz: ab5dc409a48ed4f471b500d62451a8d1b3b1e7de67871172ce684327ba7a1777
 SHA512:
-  metadata.gz: 662491807b3ba2c9267c96b5cfbc9f9243e7fe0f096707710a354d27df339a5e058889d41dca1d5d4268b3bdac5d62db7b3f3577478343e70366091c198e61ad
-  data.tar.gz: f5d9141986179a7b184ef638e541d62fd575683f2c42b42387c87c9facacaaab0ec25fd7c50260310d74872f11edee11ef136597503b701dc1bea3c705a444d6
+  metadata.gz: dec2b311edf9f515e00803d7f2a60c9f10897807779b26a44f4aa842ef5ac46239a432a194e72378eb23c3e03a79002ff3332e6d72be265683b707adb88134ed
+  data.tar.gz: 55c3a892dfa3af12e4db273e09faf5f0b96c8c2861cdfdb611c9ba75877a6e3a1c696568593b0cdd6283874b072f259738cc14c8d3a871a432cfbc17a194df35

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 # 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`).
+- **Feat (options): two additive hedge knobs.** `config_fetch_hedge_delay_ms` (default `2000`) is how long the hedge waits for the primary before also firing the secondary in parallel. `config_fetch_hedge_abort_ms` (default `6000`) is the per-leg hard-abort deadline on the hedged path; it must exceed the longest healable primary latency so a late-but-newer primary heals forward, and must be below `init_timeout_ms` so the init-path heal leg is not clipped (the client logs a one-time warning at construction if `init_timeout_ms <= config_fetch_hedge_abort_ms` with a secondary leg configured). The existing `config_fetch_timeout_ms` is unchanged and still governs the sequential / single-URL fetch path.
+- **Backward-compatible behavioral notes (additive minor).** (1) In a fast-both topology where both legs answer well inside the hedge delay, `resolved_from` may now report `"primary"` where 1.0.0's sequential fetch could report `"secondary"` — a fast healthy primary now always wins. (2) On a heal-forward (a late newer leg landing after readiness latched), an **extra** post-ready `on_update` config-update callback may fire as the client converges on the higher generation. (3) ETags are now tracked **per leg** rather than as a single shared value, so a 304 from one leg can no longer mask the other and the two concurrent legs no longer race on a shared ETag.
+- **Install-guard carve-out for unversioned snapshots:** a delivery payload whose `generation` is absent or `<= 0` (e.g. from a server that predates the generation watermark) is installed by an established client rather than rejected as older. Defensive back-compat guard — with servers that emit true generations it never triggers.
+
 ## 1.0.0 - 2026-06-06
 
 - **Stable 1.0.0 release.** The Quonfig Ruby SDK is now declared stable. No API or

data/lib/quonfig/client.rb

@@ -409,6 +409,48 @@ module Quonfig
       end
     end
 
+    # ---- Failover + canonical-ordering diagnostics (qfg-7h5d.1.9) ------
+    #
+    # Read-only signals surfaced for the failover/ordering chaos probe and for
+    # operators. Like #connection_state / #last_successful_refresh these are
+    # DIAGNOSTIC ONLY — do not wire them into a liveness probe.
+
+    # True once the SDK has installed at least one envelope (any source). The
+    # failover scenarios assert the client reaches readiness off the secondary
+    # leg inside the init budget even when the primary is refused/hung/slow.
+    def ready?
+      !last_successful_refresh.nil?
+    end
+
+    # Meta.generation of the currently-held envelope (0 before the first install
+    # or when the backend does not emit a generation). Canonical ordering: an
+    # established client never regresses to a lower generation.
+    def held_generation
+      @config_loader&.held_generation || 0
+    end
+
+    # Count of envelopes actually installed. Rejected-older and same-generation
+    # snapshots do NOT bump this, so o04 can assert "no flap" via a stable count.
+    def config_install_count
+      @config_loader&.install_count || 0
+    end
+
+    # 'primary' / 'secondary' / '' — which config_api_urls leg produced the
+    # currently-held config. Used to assert HTTP config-fetch failover (f01-f04).
+    def resolved_from
+      @config_loader&.resolved_from || ''
+    end
+
+    # True if the live SSE stream has ever repointed to a non-primary leg. The
+    # failover epic asserts this stays false (f05): SSE does not fail over.
+    def sse_failed_over_to_secondary?
+      sse = @sse_client
+      return false if sse.nil?
+      return false unless sse.respond_to?(:failed_over_to_secondary?)
+
+      sse.failed_over_to_secondary?
+    end
+
     def fork
       self.class.new(@options.for_fork)
     end
@@ -770,6 +812,7 @@ module Quonfig
       raise Quonfig::Errors::InvalidSdkKeyError, @options.sdk_key if @options.sdk_key.nil? || @options.sdk_key.to_s.strip.empty?
 
       warn_if_pin_ignored_in_delivery_mode
+      warn_if_hedge_abort_exceeds_init_timeout
 
       @config_loader = Quonfig::ConfigLoader.new(@store, @options)
 
@@ -847,6 +890,30 @@ module Quonfig
       )
     end
 
+    # qfg-7h5d.1.14: the per-leg hedge abort MUST be < init_timeout_ms, otherwise
+    # the init-path heal leg is clipped by the overall init deadline before it can
+    # heal forward. Mirrors sdk-go's construction-time warning in options.go. Warn
+    # once at init in delivery mode; does not change behavior.
+    def warn_if_hedge_abort_exceeds_init_timeout
+      return unless @options.respond_to?(:config_fetch_hedge_abort_ms)
+      # The hedge (and its heal leg) only engages with a secondary leg; with a
+      # single config_api_url there is no heal leg to clip, so the warning would
+      # be misleading.
+      return unless Array(@options.config_api_urls).length >= 2
+
+      abort_ms = @options.config_fetch_hedge_abort_ms
+      init_ms = @options.init_timeout_ms
+      return if abort_ms.nil? || init_ms.nil?
+      return if init_ms > abort_ms
+
+      LOG.warn(
+        "[quonfig] init_timeout_ms (#{init_ms}ms) <= config_fetch_hedge_abort_ms " \
+        "(#{abort_ms}ms); the hedged config-fetch heal leg may be clipped by the " \
+        'init deadline before it can heal forward. Set init_timeout_ms above the ' \
+        'hedge abort.'
+      )
+    end
+
     def handle_init_failure(err)
       if @options.on_init_failure == Quonfig::Options::ON_INITIALIZATION_FAILURE::RETURN
         LOG.warn "[quonfig] Initialization did not complete cleanly; continuing with empty store: #{err.message}"
@@ -903,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
 
@@ -923,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

@@ -18,7 +18,18 @@ module Quonfig
 
     CONFIGS_PATH = '/api/v2/configs'
 
-    attr_reader :etag, :version, :environment_id
+    attr_reader :version, :environment_id
+
+    # qfg-7h5d.1.9 (canonical ordering). Diagnostic surface read by the failover/
+    # ordering chaos probe and by operators:
+    #   held_generation — Meta.generation of the currently-installed envelope
+    #                     (nil before the first install).
+    #   install_count   — number of envelopes actually installed (rejected-older
+    #                     and same-generation snapshots do NOT bump this).
+    #   resolved_from   — 'primary' / 'secondary' / '' — which config_api_urls leg
+    #                     produced the currently-held config (HTTP installs only;
+    #                     SSE does not change it).
+    attr_reader :held_generation, :install_count
 
     # +store+: the Quonfig::ConfigStore to populate on successful fetch.
     # +options+: a Quonfig::Options instance (supplies sdk_key + config_api_urls).
@@ -37,32 +48,94 @@ module Quonfig
       end
 
       @api_config = Concurrent::Map.new
-      @etag = nil
+      # qfg-7h5d.1.14: per-leg ETag is load-bearing for the parallel hedge. The
+      # hedge runs the primary and secondary legs concurrently; a SINGLE shared
+      # ETag would (a) let a 304 from one leg mask the other and (b) be a data
+      # race with two legs writing it. Each leg keeps its own slot keyed by
+      # config_api_urls index, guarded by @etag_mutex (snapshot before the
+      # request, write-back after — the network wait happens with no lock held).
+      @etags = {}
+      @etag_mutex = Mutex.new
       @version = nil
       @environment_id = nil
       @logger = logger || LOG
+
+      # Canonical-ordering state (qfg-7h5d.1.9). @install_mutex makes the
+      # guard-check-and-install atomic across every install path (initial fetch,
+      # failover/poll fetch, SSE snapshot, SSE update, fallback poller) — these
+      # run on different threads and must never interleave a stale install with a
+      # fresh one.
+      @held_generation = nil
+      @install_count = 0
+      @resolved_from_index = nil
+      @install_mutex = Mutex.new
+    end
+
+    # Backward-compatible reader: the primary leg's last ETag. Pre-hedge this was
+    # a single shared @etag; per-leg isolation now means index 0 is the canonical
+    # "the ETag" for callers/tests that read one value.
+    def etag
+      @etag_mutex.synchronize { @etags[0] }
     end
 
-    # Fetch configs from /api/v2/configs with ETag / If-None-Match caching.
-    # On 200 responses, installs the envelope into the attached ConfigStore
-    # (if one was provided).
+    # 'primary' / 'secondary' / '' for the leg that produced the currently-held
+    # config (config_api_urls index 0 = primary, 1 = secondary).
+    def resolved_from
+      case @resolved_from_index
+      when nil then ''
+      when 0 then 'primary'
+      when 1 then 'secondary'
+      else "url#{@resolved_from_index}"
+      end
+    end
+
+    # Fetch configs from /api/v2/configs with per-leg ETag / If-None-Match caching.
+    #
+    # qfg-7h5d.1.14 — PARALLEL-FAILOVER HEDGE. On every init/refresh fetch the
+    # PRIMARY leg (config_api_urls[0]) is fired first, on the CALLING thread. If
+    # it answers within config_fetch_hedge_delay_ms it WINS and the secondary is
+    # NEVER contacted (cold standby — zero extra load on a healthy system). If the
+    # primary is SLOW past the hedge delay OR errors fast, the SECONDARY leg
+    # (config_api_urls[1]) is ALSO fired IN PARALLEL on a background thread,
+    # at-most-once — the primary is NOT cancelled. Whatever arrives is installed
+    # through the EXISTING reject-older guard (#install_envelope), so watermark-MAX
+    # falls out for free: a higher generation wins, a late OLDER payload never
+    # regresses an established client, and a late NEWER payload heals forward.
+    #
+    # fetch! returns as soon as the FIRST leg installs (readiness latches off it);
+    # any still-running leg keeps running on its own thread, bounded by
+    # config_fetch_hedge_abort_ms, and heals forward if it lands a newer
+    # generation. There is NO coalescing/in-flight gate — overlapping fetches are
+    # safe (per-leg ETag isolation + every install serialized through
+    # @install_mutex + the reject-older guard + each leg bounded by the abort), and
+    # a coalescing gate would make a manual refresh silently no-op (a contract
+    # violation).
     #
     # Returns one of:
-    #   :updated       -- 200 response; store replaced
-    #   :not_modified  -- 304 response; store untouched
-    #   :failed        -- every configured source failed
+    #   :updated       -- at least one leg installed a 200 envelope
+    #   :not_modified  -- a leg answered 304 (no change) and nothing installed
+    #   :failed        -- every fired leg failed
     def fetch!
-      Array(@options.config_api_urls).each do |api_url|
-        result = fetch_from(api_url)
-        return result if result != :failed
-      end
-      :failed
+      urls = Array(@options.config_api_urls)
+      return :failed if urls.empty?
+
+      # Single leg (or no secondary configured): no hedge, just fetch on the
+      # calling thread under the SEQUENTIAL per-URL timeout (config_fetch_timeout_ms
+      # is unchanged and still governs any non-hedged path). Preserves the
+      # synchronous, single-request-per-call shape the legacy/mock callers depend
+      # on.
+      return fetch_from(urls[0], 0, timeout_ms: config_fetch_timeout_ms) if urls.length < 2
+
+      fetch_hedged(urls)
     end
 
     # Apply a ConfigEnvelope (from SSE) to the store. Called by the SSE client
-    # when a new event arrives.
+    # when a new event arrives. SSE is a single-leg live stream, so it carries no
+    # config_api_urls index and does not change #resolved_from — but it IS
+    # guarded by the same reject-older rule (a late SSE snapshot must not regress
+    # an established client).
     def apply_envelope(envelope)
-      install_envelope(envelope, source: :sse)
+      install_envelope(envelope, source: :sse, source_index: nil)
     end
 
     def calc_config
@@ -83,19 +156,155 @@ module Quonfig
 
     private
 
-    def fetch_from(source)
-      conn = Quonfig::HttpConnection.new(source, @options.sdk_key)
+    # Hedge orchestration (qfg-7h5d.1.14). Fires the primary leg on its own
+    # thread; if it is slow past the hedge delay OR errors fast, ALSO fires the
+    # secondary in parallel — at-most-once, never after a fast primary win, never
+    # cancelling the primary. Both legs push their settled result to a shared
+    # queue. fetch! returns as soon as the FIRST leg INSTALLS (so readiness
+    # latches off it); the other leg keeps running on its own thread, bounded by
+    # the hedge abort inside fetch_from, and heals forward through the
+    # reject-older guard. We never join the slow leg — a hung primary must not
+    # block a successful secondary install.
+    def fetch_hedged(urls)
+      hedge_delay_s = hedge_delay_ms / 1000.0
+      abort_ms = hedge_abort_ms
+
+      # Each fired leg pushes exactly one [:done, index, result] message. A
+      # SizedQueue large enough for both legs so a finished leg never blocks on
+      # push after we've stopped draining.
+      results = Queue.new
+
+      # At-most-once secondary gate. The mutex makes "a fast primary win
+      # suppresses the secondary" and "the hedge-delay elapsing fires it"
+      # mutually exclusive — exactly one of suppress/fire wins.
+      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 = :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}"
+          ensure
+            results.push([:done, index, result])
+          end
+        end
+      end
+
+      fire_secondary = lambda do
+        spawn = gate.synchronize do
+          next false if secondary_fired
+
+          secondary_fired = true
+        end
+        run_leg.call(1) if spawn
+      end
+
+      suppress_secondary = lambda do
+        gate.synchronize { secondary_fired = true }
+      end
+
+      # The primary always runs. A separate hedge-delay timer thread fires the
+      # secondary if the primary has not settled by then — without waiting for
+      # the primary to finish.
+      primary_thread = run_leg.call(0)
+
+      hedge_timer = Thread.new do
+        sleep hedge_delay_s
+        # If the primary is still in flight at the hedge delay, hedge in parallel.
+        fire_secondary.call if primary_thread.alive?
+      end
+
+      installed = false
+      saw_not_modified = false
+      drained = 0
+
+      # Drain leg results until the FIRST install latches readiness, or until
+      # every fired leg has reported (so a both-fail / both-304 cycle still
+      # terminates). `fired` is read under the gate because the secondary can be
+      # spawned concurrently by the timer or the primary's fast-error path.
+      loop do
+        fired = gate.synchronize { secondary_fired ? 2 : 1 }
+        break if drained >= fired && results.empty?
+
+        _tag, index, result = results.pop
+        drained += 1
+
+        case result
+        when :failed
+          # A fast primary error must hedge immediately (do not wait for the
+          # timer). The gate keeps the secondary at-most-once.
+          fire_secondary.call if index.zero?
+        when :not_modified
+          saw_not_modified = true
+        else # :updated -> a real install
+          installed = true
+          # If the PRIMARY just won inside the hedge window, close the gate so a
+          # racing timer can never fire the secondary — the cold-standby promise.
+          suppress_secondary.call if index.zero?
+          break
+        end
+      end
+
+      # Stop the timer if it is still sleeping (already-fired is harmless).
+      hedge_timer.kill if hedge_timer.alive?
+
+      return :updated if installed
+      return :not_modified if saw_not_modified
+
+      :failed
+    end
+
+    def hedge_delay_ms
+      if @options.respond_to?(:config_fetch_hedge_delay_ms) && @options.config_fetch_hedge_delay_ms
+        @options.config_fetch_hedge_delay_ms
+      else
+        Quonfig::Options::DEFAULT_CONFIG_FETCH_HEDGE_DELAY_MS
+      end
+    end
+
+    def hedge_abort_ms
+      if @options.respond_to?(:config_fetch_hedge_abort_ms) && @options.config_fetch_hedge_abort_ms
+        @options.config_fetch_hedge_abort_ms
+      else
+        Quonfig::Options::DEFAULT_CONFIG_FETCH_HEDGE_ABORT_MS
+      end
+    end
+
+    def config_fetch_timeout_ms
+      @options.respond_to?(:config_fetch_timeout_ms) ? @options.config_fetch_timeout_ms : nil
+    end
+
+    def fetch_from(source, index = nil, timeout_ms: nil)
+      # qfg-7h5d.1.9 / .1.14: bound this single per-leg attempt so a hung upstream
+      # aborts (Faraday::TimeoutError, caught below as :failed). On the hedged
+      # path the caller passes config_fetch_hedge_abort_ms; on the sequential /
+      # single-URL path it passes config_fetch_timeout_ms.
+      conn = Quonfig::HttpConnection.new(source, @options.sdk_key, timeout_ms: timeout_ms)
       headers = {}
-      headers['If-None-Match'] = @etag if @etag
+      # Per-leg ETag: snapshot this leg's slot before the request (no lock held
+      # during the network wait).
+      etag = etag_for(index)
+      headers['If-None-Match'] = etag if etag
       response = conn.get(CONFIGS_PATH, headers)
 
       case response.status
       when 200
         new_etag = response.headers['ETag'] || response.headers['etag']
         envelope = parse_envelope(response.body)
-        install_envelope(envelope, source: source)
-        @etag = new_etag
-        :updated
+        result = install_envelope(envelope, source: source, source_index: index)
+        # Write this leg's ETag back AFTER the response (per-leg, race-free).
+        set_etag_for(index, new_etag)
+        # install_envelope returns :not_modified when the reject-older guard drops
+        # an equal/older payload — surface that so the caller doesn't double-count.
+        result == :not_modified ? :not_modified : :updated
       when 304
         @logger.debug "Configs not modified (304) from #{source}"
         :not_modified
@@ -114,6 +323,14 @@ module Quonfig
       :failed
     end
 
+    def etag_for(index)
+      @etag_mutex.synchronize { @etags[index || 0] }
+    end
+
+    def set_etag_for(index, value)
+      @etag_mutex.synchronize { @etags[index || 0] = value }
+    end
+
     def parse_envelope(body)
       data = body.is_a?(String) ? JSON.parse(body) : body
       Quonfig::ConfigEnvelope.new(
@@ -129,37 +346,74 @@ module Quonfig
       str.length > 200 ? "#{str[0, 200]}..." : str
     end
 
-    def install_envelope(envelope, source:)
-      # Update internal tracking map (for legacy callers / introspection).
-      next_map = Concurrent::Map.new
-      envelope.configs.each do |cfg|
-        key = config_key(cfg)
-        next if key.nil?
+    def install_envelope(envelope, source:, source_index: nil)
+      meta = envelope.meta || {}
+      incoming_gen = extract_generation(meta)
+
+      @install_mutex.synchronize do
+        # Reject-older install guard (canonical ordering, §5f). A fresh client
+        # (no held generation) seeds off whatever arrives first — even an older
+        # or gen-0 snapshot. An established client installs ONLY when the incoming
+        # generation strictly advances the held one: a same-generation snapshot is
+        # a no-op (no store churn, no install-count bump, no resolved-from change)
+        # so a duplicate leg never flaps an established client, and an OLDER
+        # snapshot (a stale secondary reached on failover) is dropped so the client
+        # never regresses. Reject-older is the whole rule — no source ranking; a
+        # newer primary landing late heals forward automatically. Applies on every
+        # network install path (initial fetch, failover/poll fetch, SSE snapshot,
+        # SSE update, fallback poller); datadir install bypasses this (it is the
+        # local source of truth and goes through Client#apply_datadir_envelope).
+        # Carve-out: an UNVERSIONED snapshot (generation <= 0 — a server that
+        # predates the watermark, or one whose rev-count failed) carries no
+        # 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})"
+          return :not_modified
+        end
 
-        next_map[key] = { source: source, config: cfg }
-      end
-      @api_config = next_map
+        # Update internal tracking map (for legacy callers / introspection).
+        next_map = Concurrent::Map.new
+        envelope.configs.each do |cfg|
+          key = config_key(cfg)
+          next if key.nil?
 
-      meta = envelope.meta || {}
-      @version = meta['version'] || meta[:version] || @version
-      @environment_id = meta['environment'] || meta[:environment] || @environment_id
+          next_map[key] = { source: source, config: cfg }
+        end
+        @api_config = next_map
+
+        @version = meta['version'] || meta[:version] || @version
+        @environment_id = meta['environment'] || meta[:environment] || @environment_id
 
-      # Replace the live store atomically.
-      return if @store.nil?
+        @held_generation = incoming_gen
+        @install_count += 1
+        @resolved_from_index = source_index unless source_index.nil?
 
-      new_keys = next_map.keys.to_set
-      old_keys = @store.keys.to_set
-      # Drop keys that disappeared server-side.
-      (old_keys - new_keys).each { |k| @store.delete(k) } if @store.respond_to?(:delete)
+        # Replace the live store atomically.
+        return if @store.nil?
 
-      envelope.configs.each do |cfg|
-        key = config_key(cfg)
-        next if key.nil?
+        new_keys = next_map.keys.to_set
+        old_keys = @store.keys.to_set
+        # Drop keys that disappeared server-side.
+        (old_keys - new_keys).each { |k| @store.delete(k) } if @store.respond_to?(:delete)
 
-        @store.set(key, cfg)
+        envelope.configs.each do |cfg|
+          key = config_key(cfg)
+          next if key.nil?
+
+          @store.set(key, cfg)
+        end
       end
     end
 
+    # Read Meta.generation (qfg-7h5d.1.1) — the monotonic per-branch commit
+    # counter the backend stamps on every envelope. Absent/garbage → 0 (an old
+    # backend that doesn't emit it, or fixture mode with no FIXTURE_GENERATION).
+    def extract_generation(meta)
+      g = meta['generation'] || meta[:generation]
+      g.is_a?(Numeric) ? g.to_i : 0
+    end
+
     def config_key(cfg)
       return cfg['key'] || cfg[:key] if cfg.is_a?(Hash)
 

data/lib/quonfig/http_connection.rb

@@ -2,6 +2,7 @@
 
 require 'base64'
 require 'json'
+require 'timeout'
 
 module Quonfig
   class HttpConnection
@@ -13,30 +14,77 @@ module Quonfig
       'X-Quonfig-SDK-Version' => SDK_VERSION
     }.freeze
 
-    def initialize(uri, sdk_key)
+    # 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, 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 (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
+      @timeout_ms = timeout_ms
     end
 
     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 = {})
       merged = JSON_HEADERS.merge('Authorization' => auth_header).merge(headers)
       Faraday.new(@uri) do |conn|
         conn.headers.merge!(merged)
+        if @timeout_ms
+          seconds = @timeout_ms / 1000.0
+          # open_timeout bounds the TCP connect; timeout bounds the read. A
+          # 'timeout' toxic accepts the connection but never sends bytes, so the
+          # read deadline is the one that fires — set both so a refused/slow
+          # connect is bounded too.
+          conn.options.open_timeout = seconds
+          conn.options.timeout = seconds
+        end
       end
     end
 
     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/options.rb

@@ -7,7 +7,8 @@ module Quonfig
   class Options
     attr_reader :sdk_key, :environment, :api_urls, :sse_api_urls, :telemetry_destination, :config_api_urls,
                 :on_no_default, :init_timeout_ms, :on_init_failure, :collect_sync_interval, :datadir, :enable_sse, :fallback_poll_enabled, :fallback_poll_interval_ms, :global_context, :logger_key, :logger, :enable_quonfig_user_context,
-                :data_dir_auto_reload, :data_dir_auto_reload_debounce_ms
+                :data_dir_auto_reload, :data_dir_auto_reload_debounce_ms, :config_fetch_timeout_ms,
+                :config_fetch_hedge_delay_ms, :config_fetch_hedge_abort_ms
     attr_accessor :is_fork
 
     # Default fallback poll interval, in milliseconds. The SDK polls api-delivery
@@ -18,6 +19,38 @@ module Quonfig
     # long for the initial config fetch before failing per :on_init_failure.
     DEFAULT_INIT_TIMEOUT_MS = 10_000
 
+    # Default per-URL config-fetch timeout, in milliseconds (qfg-7h5d.1.9). Each
+    # leg in config_api_urls gets its own bounded attempt on the initial fetch
+    # AND the fallback poller, so a hung primary aborts fast (~3s) and leaves
+    # budget to reach the secondary inside init_timeout_ms instead of starving it
+    # until the global deadline. ~3s is short enough to fail over well inside a
+    # default 10s init budget, long enough to tolerate a slow-but-healthy
+    # upstream. Additive + a default that already fails over → backward
+    # compatible, not a breaking change.
+    DEFAULT_CONFIG_FETCH_TIMEOUT_MS = 3_000
+
+    # Default hedge delay, in milliseconds (qfg-7h5d.1.14). On the init/refresh
+    # config-fetch the SDK fires the PRIMARY leg first; if it has not settled
+    # within this delay (or errors fast) the SDK ALSO fires the secondary leg in
+    # PARALLEL without cancelling the primary. ~2s is below a realistic
+    # slow-but-alive primary's worst case yet far enough below the per-leg abort
+    # that a healthy sub-second primary is NEVER hedged — the secondary stays a
+    # cold standby and a healthy system adds zero secondary load. Standardized to
+    # 2000ms across all backend SDKs (qfg-7h5d.1.14). Tunable via
+    # +config_fetch_hedge_delay_ms+. Additive + backward compatible.
+    DEFAULT_CONFIG_FETCH_HEDGE_DELAY_MS = 2_000
+
+    # Default per-leg hedge hard-abort deadline, in milliseconds (qfg-7h5d.1.14).
+    # The hedged config-fetch path bounds each leg by this instead of
+    # #config_fetch_timeout_ms (which still governs the sequential FetchConfigs
+    # path). It MUST exceed the longest healable primary latency so a late-but-
+    # newer primary heals forward (rather than aborting), and MUST be <
+    # init_timeout_ms so the init-path heal leg is not clipped — the client logs a
+    # warning at construction if init_timeout_ms <= this value. ~6s sits between a
+    # ~3s slow-but-healthy upstream and the default 10s init budget. Tunable via
+    # +config_fetch_hedge_abort_ms+. Additive + backward compatible.
+    DEFAULT_CONFIG_FETCH_HEDGE_ABORT_MS = 6_000
+
     # Deprecated alias for #fallback_poll_enabled. Will be removed in a future
     # minor release.
     def enable_polling
@@ -184,6 +217,9 @@ module Quonfig
       init_timeout_ms: nil,
       initialization_timeout_sec: nil,
       on_init_failure: ON_INITIALIZATION_FAILURE::RAISE,
+      config_fetch_timeout_ms: nil,
+      config_fetch_hedge_delay_ms: nil,
+      config_fetch_hedge_abort_ms: nil,
       collect_max_paths: DEFAULT_MAX_PATHS,
       collect_sync_interval: nil,
       context_upload_mode: :periodic_example, # :periodic_example, :shapes_only, :none
@@ -238,6 +274,14 @@ module Quonfig
                            DEFAULT_INIT_TIMEOUT_MS
                          end
       @on_init_failure = on_init_failure
+      # qfg-7h5d.1.9: per-URL config-fetch timeout. nil → DEFAULT_CONFIG_FETCH_TIMEOUT_MS.
+      @config_fetch_timeout_ms = config_fetch_timeout_ms || DEFAULT_CONFIG_FETCH_TIMEOUT_MS
+      # qfg-7h5d.1.14: parallel-failover hedge knobs. nil → defaults. The hedge
+      # delay is when the secondary ALSO fires in parallel; the hedge abort is the
+      # per-leg hard deadline on the hedged path (the sequential FetchConfigs path
+      # keeps using config_fetch_timeout_ms).
+      @config_fetch_hedge_delay_ms = config_fetch_hedge_delay_ms || DEFAULT_CONFIG_FETCH_HEDGE_DELAY_MS
+      @config_fetch_hedge_abort_ms = config_fetch_hedge_abort_ms || DEFAULT_CONFIG_FETCH_HEDGE_ABORT_MS
 
       @collect_max_paths = collect_max_paths
       @collect_sync_interval = collect_sync_interval

data/lib/quonfig/sse_config_client.rb

@@ -87,8 +87,23 @@ module Quonfig
       @conn_mutex = Mutex.new
       @active_http = nil
 
-      @source_index = -1
       @last_event_id = nil
+      # 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
+
+    # True if the live SSE stream has ever connected to a non-primary leg. Read
+    # by the failover chaos probe (f05). See @failed_over_to_secondary.
+    def failed_over_to_secondary?
+      @failed_over_to_secondary
     end
 
     # Layer 1 (SSE) reconnect counter. Bumped exactly once per reconnect
@@ -256,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}"
 
@@ -392,13 +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
-      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.0.0'
+  VERSION = '1.1.1'
 end

metadata

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