quonfig 1.1.1 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: df149576c34f45d691f7252a2f0e05b2c02b95681ab9986fac6a373071210c7e
-  data.tar.gz: ab5dc409a48ed4f471b500d62451a8d1b3b1e7de67871172ce684327ba7a1777
+  metadata.gz: d9da26b9a9f898ec76bf8520043abc42db011adf5e298cffa16ee8764c2c0ed6
+  data.tar.gz: '0189ef6ee1e93cec985f9f5b1f1b81f833527bf3c22a1af7886778d8f2dcb50e'
 SHA512:
-  metadata.gz: dec2b311edf9f515e00803d7f2a60c9f10897807779b26a44f4aa842ef5ac46239a432a194e72378eb23c3e03a79002ff3332e6d72be265683b707adb88134ed
-  data.tar.gz: 55c3a892dfa3af12e4db273e09faf5f0b96c8c2861cdfdb611c9ba75877a6e3a1c696568593b0cdd6283874b072f259738cc14c8d3a871a432cfbc17a194df35
+  metadata.gz: e363cf1a35bbc428f35d1d4cebea4223dc84c4a1ddd39c3a7dcbc22bafb58a757b5fde92f357dd1a9b8c0e0cc90db247addd88c873e19887cd1d0eae0bc5332b
+  data.tar.gz: e81f8441d30449624e3c64b506e113d386ce8a55656943e4523cb2d919d97aad5d8afd68df6462df1324cb2368dd8d9694e808146d622dd790ccf722e630e442

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 # 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.

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}"

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,6 +184,10 @@ 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
@@ -203,6 +212,7 @@ module Quonfig
           next false if secondary_fired
 
           secondary_fired = true
+          secondary_spawned = true
         end
         run_leg.call(1) if spawn
       end
@@ -256,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
 
@@ -369,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
 
@@ -388,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/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/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.1'
+  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.1
+  version: 1.2.0
 platform: ruby
 authors:
 - Jeff Dwyer
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-06 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