quonfig 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d12e38af54000d7cfeb34f7c3f50739527e63448668abf9d6fd4b436b27b277f
-  data.tar.gz: 1421bc6f53246ee1260a5c832ef342faa5ca70b6854acba6f12d9b51a464e99d
+  metadata.gz: d9da26b9a9f898ec76bf8520043abc42db011adf5e298cffa16ee8764c2c0ed6
+  data.tar.gz: '0189ef6ee1e93cec985f9f5b1f1b81f833527bf3c22a1af7886778d8f2dcb50e'
 SHA512:
-  metadata.gz: 73d25bb37c6c30e1d1b756172e0ffd4885bf901c9b600eec3c060f06bead7b45cf74e09544908d925a4345fcb5f9b6efe6d8331d7f8544079ffabf7b9d5b1228
-  data.tar.gz: 04df7b6f24efb0f9a3c30c47e32c686f2407ac54c1776eb7a2313fe1332f8339eac4693fc49edb49d76e00b7521680701bedfbfae5839b4d9158b3ace473efbc
+  metadata.gz: e363cf1a35bbc428f35d1d4cebea4223dc84c4a1ddd39c3a7dcbc22bafb58a757b5fde92f357dd1a9b8c0e0cc90db247addd88c873e19887cd1d0eae0bc5332b
+  data.tar.gz: e81f8441d30449624e3c64b506e113d386ce8a55656943e4523cb2d919d97aad5d8afd68df6462df1324cb2368dd8d9694e808146d622dd790ccf722e630e442

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 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.
+- **Feat (telemetry): emit failover-behavior signals on the existing telemetry wire (qfg-41nh.18).** The SDK now folds three additive failover counters into the periodic telemetry flush so the failover dashboards can be built — previously no SDK emitted any failover signal. Each flush window that saw failover activity ships one `failover` event alongside the existing `summaries` / `contextShapes` / `exampleContexts` events: `hedgeFired` (config-fetch cycles where the parallel primary+secondary hedge fired its secondary leg), `guardRejected` (installs dropped by the reject-older ordering guard, counted on BOTH the HTTP config-fetch path and the SSE message path), and `resolvedFromPrimary` / `resolvedFromSecondary` (which upstream leg served each successful HTTP install; SSE/datadir installs are not counted). `resolvedFromLkg` is reserved and always `0`. The event is emitted only when at least one counter is non-zero in the window, so a steady-state client with no config churn emits nothing. Recording rides the existing telemetry opt-out (nothing is emitted unless telemetry is enabled) and adds only a per-config-refresh mutex increment — no new dependencies, no per-evaluation overhead. Wire shape is additive and matches sdk-go exactly (an older api-telemetry strips the unknown field).
+
+## 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/README.md

@@ -258,6 +258,42 @@ Quonfig::Client.new(
 | `data_dir_auto_reload_debounce_ms`  | `Integer` (ms)    | `200`                                                               | Debounce window for the auto-reload watcher — events arriving inside the window are coalesced into a single re-read. Ignored when `data_dir_auto_reload` is `false`. |
 | `logger`          | Logger-like object         | `nil`                                                               | Optional host-app logger (e.g. `Rails.logger`). Must respond to `debug`/`info`/`warn`/`error`. When set, all SDK warnings/errors flow through this logger instead of the default stderr / SemanticLogger backend. |
 
+## Failover & `QUONFIG_DOMAIN`
+
+By default the SDK derives every hostname from `QUONFIG_DOMAIN` (default
+`quonfig.com`):
+
+| Role                     | URL                                     |
+|--------------------------|-----------------------------------------|
+| Config fetch (primary)   | `https://primary.quonfig.com`           |
+| SSE stream (primary)     | `https://stream.primary.quonfig.com`    |
+| Config fetch (secondary) | `https://secondary.quonfig.com`         |
+| SSE stream (secondary)   | `https://stream.secondary.quonfig.com`  |
+| Telemetry                | `https://telemetry.quonfig.com`         |
+
+Set `QUONFIG_DOMAIN` to move all of them together (e.g.
+`QUONFIG_DOMAIN=quonfig-staging.com`). **Automatic failover and hedging between
+the primary and the secondary are on by default** — the secondary runs on
+separate infrastructure, and the HTTP config-fetch fails over to it if the
+primary is unreachable and hedges to it if the primary is slow.
+
+`api_urls:` replaces the derived list wholesale. To keep automatic failover
+with custom URLs, **pass both a primary and a secondary URL**:
+
+```ruby
+Quonfig::Client.new(
+  sdk_key: 'your-sdk-key',
+  api_urls: [
+    'https://primary.your-proxy.example',
+    'https://secondary.your-proxy.example'
+  ]
+)
+```
+
+A single URL disables failover, and the SDK logs a warning at init. See
+https://docs.quonfig.com/docs/explanations/architecture/resiliency for the full
+model.
+
 ## Typed getters
 
 Each typed getter takes a config key and an optional context hash. If the key

data/lib/quonfig/client.rb

@@ -66,6 +66,16 @@ module Quonfig
       @poll_supervisor = nil
       @stopped = false
       @telemetry_reporter = nil
+      # Shared failover-telemetry aggregator (qfg-41nh.18). Created once and
+      # shared between the ConfigLoader (which records hedge-fired /
+      # guard-rejected / resolved-from at the failover call sites) and the
+      # TelemetryReporter (which drains it on each flush). Created before the
+      # ConfigLoader so the initial HTTP fetch — often the ONLY HTTP fetch when
+      # SSE is healthy — is captured. Recording is a per-config-refresh mutex +
+      # increment (negligible); nothing is EMITTED unless telemetry is enabled
+      # (the reporter, which owns the drain, only starts then). Survives fork:
+      # the pre-fork stop drains it, the child's rebuilt reporter drains onward.
+      @failover_aggregator = Quonfig::Telemetry::FailoverAggregator.new
       @state_mutex = Mutex.new
       @last_successful_refresh = nil
       @sse_state = :idle
@@ -689,6 +699,7 @@ module Quonfig
         context_shape_aggregator: shape_aggregator,
         example_contexts_aggregator: example_aggregator,
         evaluation_summaries_aggregator: summaries_aggregator,
+        failover_aggregator: @failover_aggregator,
         sync_interval: @options.collect_sync_interval
       )
 
@@ -813,8 +824,9 @@ module Quonfig
 
       warn_if_pin_ignored_in_delivery_mode
       warn_if_hedge_abort_exceeds_init_timeout
+      warn_if_explicit_api_urls_disables_failover
 
-      @config_loader = Quonfig::ConfigLoader.new(@store, @options)
+      @config_loader = Quonfig::ConfigLoader.new(@store, @options, failover_aggregator: @failover_aggregator)
 
       perform_initial_fetch
 
@@ -914,6 +926,27 @@ module Quonfig
       )
     end
 
+    # qfg-41nh.26: the SDK's 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 (secondary runs on separate infra). An
+    # explicit `api_urls:` replaces that list wholesale, so a single-entry
+    # override silently drops the secondary and disables automatic failover.
+    # Warn once at init in delivery mode so the customer isn't surprised.
+    # Mirrors sdk-go's construction-time warning (quonfig.go). Does not change
+    # behavior. Fired only when the caller explicitly set api_urls AND the
+    # resolved list has fewer than two legs — never on the default/derived
+    # two-URL list.
+    def warn_if_explicit_api_urls_disables_failover
+      return unless @options.respond_to?(:api_urls_explicit)
+      return unless @options.api_urls_explicit
+      return unless Array(@options.config_api_urls).length < 2
+
+      LOG.warn(
+        '[quonfig] explicit api_urls disables automatic failover to the ' \
+        'secondary; pass both primary and secondary URLs to keep it'
+      )
+    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}"
@@ -970,18 +1003,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 +1040,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

@@ -37,7 +37,7 @@ module Quonfig
     #
     # Backward compat: callers that pass a single +base_client+ (mock client
     # used by tests that expects `.options`) are still supported.
-    def initialize(store_or_base_client, options = nil, logger: nil)
+    def initialize(store_or_base_client, options = nil, logger: nil, failover_aggregator: nil)
       if options.nil? && store_or_base_client.respond_to?(:options)
         # Legacy shape: ConfigLoader.new(base_client)
         @options = store_or_base_client.options
@@ -47,6 +47,11 @@ module Quonfig
         @options = options
       end
 
+      # Optional failover-telemetry sink (qfg-41nh.18). When telemetry is
+      # enabled the Client passes the shared FailoverAggregator; nil otherwise,
+      # so every record call below is a no-op under a telemetry opt-out.
+      @failover_aggregator = failover_aggregator
+
       @api_config = Concurrent::Map.new
       # 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
@@ -179,16 +184,26 @@ module Quonfig
       # mutually exclusive — exactly one of suppress/fire wins.
       gate = Mutex.new
       secondary_fired = false
-
+      # Distinct from secondary_fired (which is ALSO set true by suppress on a
+      # fast primary win): this is set only when the secondary leg was ACTUALLY
+      # spawned, so it is the exact "the hedge fired" signal (qfg-41nh.18).
+      secondary_spawned = 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
 
@@ -197,6 +212,7 @@ module Quonfig
           next false if secondary_fired
 
           secondary_fired = true
+          secondary_spawned = true
         end
         run_leg.call(1) if spawn
       end
@@ -250,6 +266,14 @@ module Quonfig
       # Stop the timer if it is still sleeping (already-fired is harmless).
       hedge_timer.kill if hedge_timer.alive?
 
+      # Failover observability (qfg-41nh.18): if the secondary leg was actually
+      # spawned this cycle, the hedge fired (the primary was slow past the hedge
+      # delay or errored fast). Recorded once per cycle regardless of which leg's
+      # payload won the reject-older guard. Read under the gate — the flag is
+      # written under it by fire_secondary, which may run on the timer thread.
+      hedged = gate.synchronize { secondary_spawned }
+      @failover_aggregator&.record_hedge_fired if hedged
+
       return :updated if installed
       return :not_modified if saw_not_modified
 
@@ -363,6 +387,10 @@ module Quonfig
         # 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
           return :not_modified
         end
 
@@ -382,6 +410,11 @@ module Quonfig
         @held_generation = incoming_gen
         @install_count += 1
         @resolved_from_index = source_index unless source_index.nil?
+        # Failover observability (qfg-41nh.18): record which leg served this
+        # successful HTTP install (source_index 0 = primary, > 0 = secondary).
+        # SSE / datadir installs pass source_index nil and are ignored by the
+        # aggregator, so they are never counted.
+        @failover_aggregator&.record_resolved_from(source_index)
 
         # Replace the live store atomically.
         return if @store.nil?

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/options.rb

@@ -8,7 +8,7 @@ module Quonfig
     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, :config_fetch_timeout_ms,
-                :config_fetch_hedge_delay_ms, :config_fetch_hedge_abort_ms
+                :config_fetch_hedge_delay_ms, :config_fetch_hedge_abort_ms, :api_urls_explicit
     attr_accessor :is_fork
 
     # Default fallback poll interval, in milliseconds. The SDK polls api-delivery
@@ -308,6 +308,16 @@ module Quonfig
       #   3. Hardcoded DEFAULT_DOMAIN ('quonfig.com')
       domain = Quonfig::Options.domain
 
+      # Whether the caller explicitly supplied api_urls (vs. the SDK deriving
+      # both legs from QUONFIG_DOMAIN / DEFAULT_DOMAIN). The default and every
+      # domain-derived list carries a primary AND a secondary leg, so the SDK
+      # hedges/fails over automatically; an explicit single-entry override
+      # silently drops the secondary. Client warns once at init when this is
+      # true and the resolved list has < 2 legs (see
+      # Client#warn_if_explicit_api_urls_disables_failover). Mirrors sdk-go's
+      # apiURLsExplicit flag (qfg-41nh.26).
+      @api_urls_explicit = !api_urls.nil?
+
       @api_urls = Array(api_urls || Quonfig::Options.derive_api_urls(domain))
                   .map { |url| remove_trailing_slash(url) }
 

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/telemetry/failover_aggregator.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module Quonfig
+  module Telemetry
+    # Accumulates failover-behavior counters over a flush window: how many times
+    # the config-fetch hedge fired its secondary leg, how many installs the
+    # reject-older ordering guard dropped, and which upstream leg served each
+    # successful HTTP install. Every counter is additive and carries NO user
+    # data.
+    #
+    # The aggregator is independently thread-safe (its own mutex) and is written
+    # directly from the failover call sites in ConfigLoader rather than through
+    # any queue — the call rate is per-config-refresh, not per-evaluation, so a
+    # plain mutex has negligible overhead.
+    #
+    # Wire shape matches sdk-go's FailoverEvent (the canonical reference) and
+    # api-telemetry's failover schema EXACTLY — camelCase keys, unix-millis
+    # window. #drain_event returns +nil+ when every counter is zero, so a healthy
+    # steady-state client emits no failover event at all.
+    #
+    #   { "failover": {
+    #       "start": <int ms>, "end": <int ms>,
+    #       "hedgeFired": <int>, "guardRejected": <int>,
+    #       "resolvedFromPrimary": <int>, "resolvedFromSecondary": <int>,
+    #       "resolvedFromLkg": <int>
+    #   } }
+    class FailoverAggregator
+      def initialize
+        @mutex = Mutex.new
+        @start_at_ms = nil
+        @hedge_fired = 0
+        @guard_rejected = 0
+        @resolved_from_primary = 0
+        @resolved_from_secondary = 0
+        # Reserved for a future last-known-good delivery path; backends emit 0.
+        @resolved_from_lkg = 0
+      end
+
+      # Count one config-fetch cycle whose hedge fired the secondary leg (the
+      # primary was slow past the hedge delay or errored fast).
+      def record_hedge_fired
+        @mutex.synchronize do
+          @start_at_ms ||= Quonfig::TimeHelpers.now_in_ms
+          @hedge_fired += 1
+        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).
+      def record_guard_rejected
+        @mutex.synchronize do
+          @start_at_ms ||= Quonfig::TimeHelpers.now_in_ms
+          @guard_rejected += 1
+        end
+      end
+
+      # Count one successful HTTP install by the leg that served it: source_index
+      # 0 is the primary, any index > 0 is a failover/secondary leg. A nil or
+      # negative index (SSE / datadir install with no HTTP leg) is ignored.
+      def record_resolved_from(source_index)
+        return if source_index.nil? || source_index.negative?
+
+        @mutex.synchronize do
+          @start_at_ms ||= Quonfig::TimeHelpers.now_in_ms
+          if source_index.zero?
+            @resolved_from_primary += 1
+          else
+            @resolved_from_secondary += 1
+          end
+        end
+      end
+
+      # Return the window's counters as a telemetry event hash and reset state.
+      # Returns +nil+ when no failover activity occurred (every counter zero).
+      def drain_event
+        @mutex.synchronize do
+          if @hedge_fired.zero? && @guard_rejected.zero? &&
+             @resolved_from_primary.zero? && @resolved_from_secondary.zero? &&
+             @resolved_from_lkg.zero?
+            return nil
+          end
+
+          event = {
+            'failover' => {
+              'start' => @start_at_ms || Quonfig::TimeHelpers.now_in_ms,
+              'end' => Quonfig::TimeHelpers.now_in_ms,
+              'hedgeFired' => @hedge_fired,
+              'guardRejected' => @guard_rejected,
+              'resolvedFromPrimary' => @resolved_from_primary,
+              'resolvedFromSecondary' => @resolved_from_secondary,
+              'resolvedFromLkg' => @resolved_from_lkg
+            }
+          }
+
+          reset
+          event
+        end
+      end
+
+      private
+
+      # Caller holds @mutex.
+      def reset
+        @start_at_ms = nil
+        @hedge_fired = 0
+        @guard_rejected = 0
+        @resolved_from_primary = 0
+        @resolved_from_secondary = 0
+        @resolved_from_lkg = 0
+      end
+    end
+  end
+end

data/lib/quonfig/telemetry/telemetry_reporter.rb

@@ -13,7 +13,8 @@ module Quonfig
     #     "events": [
     #       { "summaries":       { "start": ..., "end": ..., "summaries": [...] } },
     #       { "contextShapes":   { "shapes":   [...] } },
-    #       { "exampleContexts": { "examples": [...] } }
+    #       { "exampleContexts": { "examples": [...] } },
+    #       { "failover":        { "start": ..., "end": ..., "hedgeFired": ..., ... } }
     #     ]
     #   }
     #
@@ -30,6 +31,7 @@ module Quonfig
                      context_shape_aggregator: nil,
                      example_contexts_aggregator: nil,
                      evaluation_summaries_aggregator: nil,
+                     failover_aggregator: nil,
                      sync_interval: nil,
                      http_connection: nil)
         @options = options
@@ -39,6 +41,11 @@ module Quonfig
         @context_shape_aggregator = context_shape_aggregator
         @example_contexts_aggregator = example_contexts_aggregator
         @evaluation_summaries_aggregator = evaluation_summaries_aggregator
+        # Failover counters carry no user data and are the operational signal for
+        # the secondary-delivery hardening (qfg-41nh.18), so they ride the
+        # existing telemetry stream. The ConfigLoader records directly into this
+        # aggregator at the failover call sites; the reporter only drains it.
+        @failover_aggregator = failover_aggregator
         @http_connection = http_connection
         @sync_interval = calculate_sync_interval(sync_interval)
         @stopped = Concurrent::AtomicBoolean.new(false)
@@ -125,6 +132,9 @@ module Quonfig
         if (example_event = @example_contexts_aggregator&.drain_event)
           events << example_event
         end
+        if (failover_event = @failover_aggregator&.drain_event)
+          events << failover_event
+        end
 
         return if events.empty?
 

data/lib/quonfig/version.rb

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

data/lib/quonfig.rb

@@ -61,6 +61,7 @@ require 'quonfig/telemetry/context_shape'
 require 'quonfig/telemetry/context_shape_aggregator'
 require 'quonfig/telemetry/example_contexts_aggregator'
 require 'quonfig/telemetry/evaluation_summaries_aggregator'
+require 'quonfig/telemetry/failover_aggregator'
 require 'quonfig/telemetry/telemetry_reporter'
 require 'quonfig/client'
 require 'quonfig/bound_client'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: quonfig
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Jeff Dwyer
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-01 00:00:00.000000000 Z
+date: 2026-07-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -130,6 +130,7 @@ files:
 - lib/quonfig/telemetry/context_shape_aggregator.rb
 - lib/quonfig/telemetry/evaluation_summaries_aggregator.rb
 - lib/quonfig/telemetry/example_contexts_aggregator.rb
+- lib/quonfig/telemetry/failover_aggregator.rb
 - lib/quonfig/telemetry/telemetry_reporter.rb
 - lib/quonfig/time_helpers.rb
 - lib/quonfig/types.rb