quonfig 1.8.0 → 1.10.0

data/lib/quonfig/config_loader.rb

@@ -24,17 +24,54 @@ module Quonfig
     # poller then enters auth-failed (Client#start_polling).
     AUTH_STATUSES = [401, 403, 404, 410].freeze
 
+    # The leg error recorded when a leg ended on a timeout (its per-leg
+    # deadline or the hedge abort). The init loop reads it to tell a hung
+    # attempt from one that failed fast (init-failure design, decision 7).
+    LEG_TIMED_OUT = 'timed out'
+
+    # host:port of +url+ (scheme kept when present), never its userinfo, path
+    # or query. For log lines and leg errors (init-failure design, decision 9).
+    def self.display_url(url)
+      return url.to_s unless url.is_a?(String) || url.is_a?(URI::Generic)
+
+      uri = URI.parse(url.to_s)
+      return redact_userinfo(url.to_s) unless uri.host
+
+      "#{"#{uri.scheme}://" if uri.scheme}#{uri.host}:#{uri.port}"
+    rescue URI::InvalidURIError
+      redact_userinfo(url.to_s)
+    end
+
+    # Strip "user:pass@" from every URL in +text+.
+    def self.redact_userinfo(text)
+      text.to_s.gsub(%r{(//)[^/@\s]+@}, '\\1')
+    end
+
     # Result of one fetch cycle across the configured legs. +statuses+ maps a
     # config_api_urls index to the HTTP status that leg returned (0 = no
     # response: timeout, connection failure). +primary_host+ is host:port of
     # the primary leg, for the entry ERROR (never the key).
     class FetchCycle
-      attr_reader :result, :statuses, :primary_host
+      attr_reader :result, :statuses, :primary_host, :leg_errors
 
-      def initialize(result, statuses, primary_host)
+      # +leg_errors+ maps a config_api_urls index to a one-line description of
+      # why that leg failed (host-free, key-free), for the init log contract.
+      def initialize(result, statuses, primary_host, leg_errors = {})
         @result = result
         @statuses = statuses
         @primary_host = primary_host
+        @leg_errors = leg_errors
+      end
+
+      # Every leg answered and every answer was in the auth class (401/403,
+      # plus 404/410 per rule R1): the key is rejected (init-failure design
+      # B.3, "401/403 from both legs"). Stricter than #auth_rejected? (the
+      # poller's rule R2, primary leg only), because init short-circuits on it.
+      def all_legs_unauthorized?(leg_count)
+        return false unless @result == :failed
+
+        values = @statuses.values
+        values.size >= leg_count && values.all? { |s| AUTH_STATUSES.include?(s) }
       end
 
       def primary_status
@@ -66,8 +103,16 @@ module Quonfig
         @mutex = Mutex.new
       end
 
+      # Send this cycle's remaining lines to DEBUG. The init loop calls it when
+      # it gives up on an attempt that is still in flight: its legs keep running
+      # on their own threads up to the hedge abort, and their late failures are
+      # already summarized in the init ERROR (qfg-9p4i.10).
+      def silence!
+        @silenced = true
+      end
+
       def log(level, msg, auth: false)
-        return @logger.debug(msg) if @mode == :probe
+        return @logger.debug(msg) if @mode == :probe || @silenced
 
         if @mode == :poll && auth
           hold = @mutex.synchronize do
@@ -208,27 +253,39 @@ module Quonfig
     # leg's status (rule R2, qfg-goi1.10.26). +log_mode+ is one of CycleLog's
     # modes; the poller passes :poll for an ordinary cycle and :probe while
     # auth-failed.
-    def fetch_cycle!(log_mode: :normal)
+    #
+    # +leg_errors+ lets a caller pass in the map the legs record their errors
+    # into, so it can still read them if it abandons the cycle mid-flight (the
+    # init loop at init_timeout_ms).
+    def fetch_cycle!(log_mode: :normal, cycle_log: nil, leg_errors: nil)
       urls = Array(@options.config_api_urls)
       statuses = Concurrent::Map.new
-      return FetchCycle.new(:failed, statuses, '') if urls.empty?
+      leg_errors ||= Concurrent::Map.new
+      return FetchCycle.new(:failed, statuses, '', leg_errors) if urls.empty?
 
-      cycle_log = CycleLog.new(@logger, log_mode)
+      cycle_log ||= new_cycle_log(log_mode)
       # 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.
       result = if urls.length < 2
-                 fetch_from(urls[0], 0, timeout_ms: config_fetch_timeout_ms, statuses: statuses, cycle_log: cycle_log)
+                 fetch_from(urls[0], 0, timeout_ms: config_fetch_timeout_ms, statuses: statuses,
+                                        cycle_log: cycle_log, leg_errors: leg_errors)
                else
-                 fetch_hedged(urls, statuses: statuses, cycle_log: cycle_log)
+                 fetch_hedged(urls, statuses: statuses, cycle_log: cycle_log, leg_errors: leg_errors)
                end
-      cycle = FetchCycle.new(result, statuses, host_of(urls[0]))
+      cycle = FetchCycle.new(result, statuses, host_of(urls[0]), leg_errors)
       cycle_log.release(drop: cycle.auth_rejected?)
       cycle
     end
 
+    # A CycleLog over this loader's logger, for a caller that wants to hold on
+    # to it (see CycleLog#silence!).
+    def new_cycle_log(mode = :normal)
+      CycleLog.new(@logger, mode)
+    end
+
     # Apply a ConfigEnvelope (from SSE) to the store. Called by the SSE client
     # 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
@@ -265,7 +322,7 @@ module Quonfig
     # 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, statuses: nil, cycle_log: nil)
+    def fetch_hedged(urls, statuses: nil, cycle_log: nil, leg_errors: nil)
       hedge_delay_s = hedge_delay_ms / 1000.0
       abort_ms = hedge_abort_ms
 
@@ -293,7 +350,8 @@ module Quonfig
         Thread.new do
           result = :failed
           begin
-            result = fetch_from(urls[index], index, timeout_ms: abort_ms, statuses: statuses, cycle_log: cycle_log)
+            result = fetch_from(urls[index], index, timeout_ms: abort_ms, statuses: statuses, cycle_log: cycle_log,
+                                                    leg_errors: leg_errors)
           rescue StandardError => e
             @logger.debug "Hedge leg #{index} failed: #{e.class}: #{e.message}"
           ensure
@@ -402,8 +460,10 @@ module Quonfig
       ''
     end
 
-    def fetch_from(source, index = nil, timeout_ms: nil, statuses: nil, cycle_log: nil)
+    def fetch_from(source, index = nil, timeout_ms: nil, statuses: nil, cycle_log: nil, leg_errors: nil)
       cycle_log ||= CycleLog.new(@logger, :normal)
+      where = self.class.display_url(source)
+      note = ->(msg) { leg_errors[index || 0] = self.class.redact_userinfo(msg)[0, 200] if leg_errors }
       # 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 /
@@ -432,30 +492,59 @@ module Quonfig
         # 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}"
+        @logger.debug "Configs not modified (304) from #{where}"
         :not_modified
       when 401, 403
-        cycle_log.log(:warn, "Config fetch rejected (#{response.status}) from #{source}: #{short_body(response)}", auth: true)
+        note.call("HTTP #{response.status} (SDK key rejected)")
+        # Never the response body: it is upstream content (decision 9).
+        cycle_log.log(:warn, "Config fetch rejected (#{response.status}) from #{where}", auth: true)
         :failed
       else
-        cycle_log.log(:info, "Config fetch failed: status #{response.status} from #{source}",
+        note.call("HTTP #{response.status}")
+        cycle_log.log(:info, "Config fetch failed: status #{response.status} from #{where}",
                       auth: AUTH_STATUSES.include?(response.status.to_i))
         :failed
       end
     rescue NonEnvelopeError => e
+      note.call("non-envelope 200 (#{e.message})")
       # qfg-9dxb.3: a non-envelope 200 is a leg error, NOT an install — the
       # hedge/failover proceeds and this leg's ETag is never stored (so a junk
       # 200 cannot pin itself through later 304s).
-      cycle_log.log(:warn, "Config fetch from #{source} returned a non-envelope 200 (#{e.message}); treating as a failed leg")
+      cycle_log.log(:warn, "Config fetch from #{where} returned a non-envelope 200 (#{e.message}); treating as a failed leg")
+      :failed
+    rescue Quonfig::ConfigShape::AllInvalidError => e
+      note.call(e.message)
+      # qfg-krjt: a payload with no loadable config is a leg error, so it can
+      # never install as an empty workspace.
+      cycle_log.log(:warn, "Config fetch from #{where}: #{e.message}; treating as a failed leg")
+      :failed
+    rescue JSON::ParserError
+      # The parser's message quotes the body; never pass it on (decision 9).
+      note.call('non-JSON 200 body')
+      cycle_log.log(:warn, "Config fetch from #{where} returned a non-JSON 200; treating as a failed leg")
+      :failed
+    rescue Faraday::TimeoutError
+      note.call(LEG_TIMED_OUT)
+      cycle_log.log(:warn, "Timeout error fetching configs from #{where}")
       :failed
     rescue Faraday::ConnectionFailed => e
-      @logger.debug "Connection failure fetching configs from #{source}: #{e.message}"
+      # The Net::HTTP adapter wraps a connect timeout (Net::OpenTimeout) in
+      # ConnectionFailed. That is a hang, not a fast failure (decision 7).
+      note.call(connect_timeout?(e) ? LEG_TIMED_OUT : e.message)
+      @logger.debug "Connection failure fetching configs from #{where}: #{self.class.redact_userinfo(e.message)}"
       :failed
     rescue StandardError => e
-      cycle_log.log(:warn, "Unexpected error fetching configs from #{source}: #{e.message}")
+      note.call("#{e.class}: #{e.message}")
+      cycle_log.log(:warn, "Unexpected error fetching configs from #{where}: #{self.class.redact_userinfo(e.message)}")
       :failed
     end
 
+    def connect_timeout?(err)
+      cause = err.respond_to?(:wrapped_exception) ? err.wrapped_exception : nil
+      cause ||= err.cause
+      cause.is_a?(Timeout::Error) || cause.is_a?(Errno::ETIMEDOUT)
+    end
+
     def etag_for(index)
       @etag_mutex.synchronize { @etags[index || 0] }
     end
@@ -472,17 +561,11 @@ module Quonfig
       data = body.is_a?(String) ? JSON.parse(body) : body
       raise NonEnvelopeError, 'missing meta.version' unless Quonfig::ConfigEnvelope.wire_envelope?(data)
 
-      Quonfig::ConfigEnvelope.new(
-        configs: data['configs'] || [],
-        meta: data['meta'] || {}
-      )
-    end
-
-    def short_body(response)
-      return '' if response.body.nil?
-
-      str = response.body.to_s
-      str.length > 200 ? "#{str[0, 200]}..." : str
+      meta = data['meta'] || {}
+      # Skip one malformed config, keep the rest (qfg-krjt). Raises
+      # ConfigShape::AllInvalidError when none is loadable.
+      configs = Quonfig::ConfigShape.filter(data['configs'] || [], logger: @logger, version: meta['version'])
+      Quonfig::ConfigEnvelope.new(configs: configs, meta: meta)
     end
 
     def install_envelope(envelope, source:, source_index: nil)
@@ -517,12 +600,12 @@ module Quonfig
             # Unversioned payload while a real generation is held: not provably
             # older (it carries no ordering info), so a silent no-op — NOT
             # counted as guardRejected.
-            @logger.debug "Unversioned payload ignored: held generation #{@held_generation} (source=#{source})"
+            @logger.debug "Unversioned payload ignored: held generation #{@held_generation} (source=#{self.class.display_url(source)})"
             return :not_modified
           end
 
           if incoming_gen < @held_generation
-            @logger.debug "Reject-older guard: dropping incoming generation #{incoming_gen} < held #{@held_generation} (source=#{source})"
+            @logger.debug "Reject-older guard: dropping incoming generation #{incoming_gen} < held #{@held_generation} (source=#{self.class.display_url(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
@@ -542,7 +625,7 @@ module Quonfig
             # `guardRejected` made a healthy client report failover activity from
             # init alone. Not installed, not counted — but still :not_modified, so
             # the caller's liveness stamp is unchanged.
-            @logger.debug "Same-generation re-delivery: ignoring incoming generation #{incoming_gen} (source=#{source})"
+            @logger.debug "Same-generation re-delivery: ignoring incoming generation #{incoming_gen} (source=#{self.class.display_url(source)})"
           end
           return :not_modified
         end
@@ -565,18 +648,20 @@ module Quonfig
         # (Thread#raise, Timeout) then leaves the held generation where it
         # was, so the same-generation redelivery that follows installs again
         # and repairs the store instead of being ignored as a duplicate.
+        #
+        # The new config set is built off to the side and swapped in with one
+        # reference write (qfg-i86q), so a concurrent lookup never sees a flag
+        # from this envelope with a segment from the last one, or a key that
+        # is momentarily absent.
         unless @store.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)
-
+          next_configs = {}
           envelope.configs.each do |cfg|
             key = config_key(cfg)
             next if key.nil?
 
-            @store.set(key, cfg)
+            next_configs[key] = cfg
           end
+          @store.replace_all(next_configs)
         end
 
         # qfg-9dxb.3 Fix A: an unversioned install (generation <= 0) carries no

data/lib/quonfig/config_shape.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+module Quonfig
+  # Decode-time shape check for config entries (qfg-krjt; the WS8
+  # skip-one-bad-config rule, as sdk-go 2f6b98b, sdk-node qfg-goi1.10.1 and
+  # sdk-python qfg-goi1.10.5).
+  #
+  # The store keeps raw JSON and the evaluator walks it as Hashes and Arrays,
+  # so a config whose rule, criterion or default has the wrong shape, or whose
+  # weighted value has a non-integer weight, would install and then raise
+  # NoMethodError/TypeError out of every read of that key. Each delivery path
+  # (HTTP, SSE, datadir) runs its configs through .filter instead: a bad entry
+  # is skipped with a WARN naming its key, so the key reads as not found, and
+  # the rest installs. If every entry fails, .filter raises AllInvalidError so
+  # the payload is rejected and can never install as an empty workspace.
+  module ConfigShape
+    LOG = Quonfig::InternalLogger.new(self)
+
+    # Raised by .filter when a non-empty payload has no loadable config.
+    class AllInvalidError < StandardError; end
+
+    module_function
+
+    # Returns the configs that pass #problem, in order. +version+ is only used
+    # in the log line.
+    def filter(configs, logger: nil, version: nil)
+      raise AllInvalidError, 'every config failed to load: configs is not a list' unless configs.is_a?(Array)
+
+      log = logger || LOG
+      first_problem = nil
+      kept = configs.select do |cfg|
+        reason = problem(cfg)
+        next true if reason.nil?
+
+        first_problem ||= reason
+        log.warn "[quonfig] skipping config \"#{key_of(cfg)}\" that failed to load (version #{version}): " \
+                 "#{reason}; other configs are unaffected"
+        false
+      end
+      raise AllInvalidError, "every config failed to load (first: #{first_problem})" if kept.empty? && first_problem
+
+      kept
+    end
+
+    # nil when +cfg+ has a shape the evaluator can walk, else a short reason.
+    def problem(cfg)
+      return 'config entry is not an object' unless cfg.is_a?(Hash)
+
+      key = field(cfg, 'key')
+      return 'config entry has no key' unless key.is_a?(String) && !key.empty?
+
+      default = field(cfg, 'default')
+      unless default.nil?
+        return 'default is not an object' unless default.is_a?(Hash)
+
+        reason = rules_problem(field(default, 'rules'), 'default')
+        return reason if reason
+      end
+
+      env = field(cfg, 'environment')
+      return nil if env.nil?
+      return 'environment is not an object' unless env.is_a?(Hash)
+
+      rules_problem(field(env, 'rules'), 'environment')
+    end
+
+    def rules_problem(rules, where)
+      return nil if rules.nil?
+      return "#{where}.rules is not a list" unless rules.is_a?(Array)
+
+      rules.each_with_index do |rule, i|
+        reason = rule_problem(rule)
+        return "#{where}.rules[#{i}]: #{reason}" if reason
+      end
+      nil
+    end
+
+    def rule_problem(rule)
+      return 'rule is not an object' unless rule.is_a?(Hash)
+
+      criteria = field(rule, 'criteria')
+      unless criteria.nil?
+        return 'criteria is not a list' unless criteria.is_a?(Array)
+
+        criteria.each_with_index do |criterion, i|
+          return "criteria[#{i}] is not an object" unless criterion.is_a?(Hash)
+
+          match = field(criterion, 'valueToMatch')
+          return "criteria[#{i}].valueToMatch is not an object" unless match.nil? || match.is_a?(Hash)
+        end
+      end
+
+      value_problem(field(rule, 'value'))
+    end
+
+    def value_problem(value)
+      return nil if value.nil?
+      return 'value is not an object' unless value.is_a?(Hash)
+      return nil unless field(value, 'type') == 'weighted_values'
+
+      weighted = field(value, 'value')
+      return 'weighted_values value is not an object' unless weighted.is_a?(Hash)
+
+      entries = field(weighted, 'weightedValues')
+      return nil if entries.nil?
+      return 'weightedValues is not a list' unless entries.is_a?(Array)
+
+      entries.each_with_index do |entry, i|
+        return "weightedValues[#{i}] is not an object" unless entry.is_a?(Hash)
+
+        # A missing weight counts as 0; a present one must be an Integer
+        # (sdk-go's int weight fails json.Unmarshal the same way).
+        next unless entry.key?('weight') || entry.key?(:weight)
+        next if field(entry, 'weight').is_a?(Integer)
+
+        return "weightedValues[#{i}].weight must be an integer (got #{field(entry, 'weight').class})"
+      end
+      nil
+    end
+
+    def field(hash, name)
+      return hash[name] if hash.key?(name)
+
+      hash[name.to_sym]
+    end
+
+    def key_of(cfg)
+      return '' unless cfg.is_a?(Hash)
+
+      key = field(cfg, 'key')
+      key.is_a?(String) ? key : ''
+    end
+  end
+end

data/lib/quonfig/config_store.rb

@@ -3,48 +3,94 @@
 module Quonfig
   # In-memory store of configs keyed by config key.
   #
-  # Mirrors sdk-node's ConfigStore (src/store.ts). Integration tests and the
-  # new Resolver/Evaluator trio construct this directly, independent of any
-  # Client/ConfigLoader plumbing.
+  # Integration tests and the Resolver/Evaluator trio construct this
+  # directly, independent of any Client/ConfigLoader plumbing.
   #
-  # Thread-safety: backed by Concurrent::Map, whose per-key reads, writes, and
-  # deletes are atomic. There is no compound multi-key operation here that
-  # needs an outer lock — envelope application in ConfigLoader is a sequence
-  # of independent set/delete calls, and readers tolerate seeing the
-  # in-progress mix. Eventual consistency across an envelope is acceptable
-  # and matches sdk-node behavior.
+  # Thread-safety (qfg-i86q): the store holds one frozen Hash snapshot behind
+  # an AtomicReference. An install builds the next Hash off to the side and
+  # swaps the reference once (#replace_all), so a reader sees the old
+  # envelope or the new one, never a mix. Matches sdk-go runtime_store.go.
+  # #set / #delete / #clear are copy-on-write under a writer mutex, for the
+  # test harness and single-key callers.
+  #
+  # One lookup can read several keys (a flag, then the segments it
+  # references, then a decryptWith key). #pinned holds one snapshot for the
+  # current thread for the duration of a block, so every read in that
+  # lookup comes from the same envelope even if an install swaps the store
+  # mid-evaluation.
   class ConfigStore
+    EMPTY = {}.freeze
+    private_constant :EMPTY
+
     def initialize(initial_configs = nil)
-      @configs = Concurrent::Map.new
+      @write_mutex = Mutex.new
+      @pin_key = :"__quonfig_store_pin_#{object_id}"
+      @snapshot = Concurrent::AtomicReference.new(EMPTY)
       return unless initial_configs
 
-      initial_configs.each { |k, v| @configs[k] = v }
+      replace_all(initial_configs.to_h)
     end
 
     def get(key)
-      @configs[key]
+      snapshot[key]
     end
 
     def set(key, config)
-      @configs[key] = config
+      @write_mutex.synchronize do
+        @snapshot.set(@snapshot.get.merge(key => config).freeze)
+      end
+      config
     end
 
     def delete(key)
-      @configs.delete(key)
+      @write_mutex.synchronize do
+        current = @snapshot.get
+        return nil unless current.key?(key)
+
+        next_map = current.dup
+        value = next_map.delete(key)
+        @snapshot.set(next_map.freeze)
+        value
+      end
     end
 
     def clear
-      @configs.each_key { |k| @configs.delete(k) }
+      replace_all(EMPTY)
+    end
+
+    # Atomically replace every config with +configs+ (a Hash of key =>
+    # config). Readers see either the previous set or this one.
+    def replace_all(configs)
+      next_map = configs.frozen? ? configs : configs.dup.freeze
+      @write_mutex.synchronize { @snapshot.set(next_map) }
+      nil
     end
 
     def keys
-      @configs.keys
+      snapshot.keys
     end
 
     def all_configs
-      h = {}
-      @configs.each_pair { |k, v| h[k] = v }
-      h
+      snapshot.dup
+    end
+
+    # Run the block with this thread's reads pinned to the current snapshot.
+    # Re-entrant: a nested call keeps the outer pin.
+    def pinned
+      return yield if Thread.current[@pin_key]
+
+      Thread.current[@pin_key] = @snapshot.get
+      begin
+        yield
+      ensure
+        Thread.current[@pin_key] = nil
+      end
+    end
+
+    private
+
+    def snapshot
+      Thread.current[@pin_key] || @snapshot.get
     end
   end
 end

data/lib/quonfig/datadir.rb

@@ -50,18 +50,18 @@ module Quonfig
         end
       end
 
+      version = "datadir:#{datadir}"
+      # Skip one malformed config file, keep the rest (qfg-krjt).
       Quonfig::ConfigEnvelope.new(
-        configs: configs,
-        meta: { 'version' => "datadir:#{datadir}", 'environment' => env_id }
+        configs: Quonfig::ConfigShape.filter(configs, version: version),
+        meta: { 'version' => version, 'environment' => env_id }
       )
     end
 
     # Convenience: load the envelope and populate a fresh ConfigStore.
     def load_store(datadir, environment = nil)
       envelope = load_envelope(datadir, environment)
-      store = Quonfig::ConfigStore.new
-      envelope.configs.each { |cfg| store.set(cfg['key'], cfg) }
-      store
+      Quonfig::ConfigStore.new(envelope.configs.to_h { |cfg| [cfg['key'], cfg] })
     end
 
     def resolve_environment(quonfig_path, environment)

data/lib/quonfig/errors/initialization_error.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Quonfig
+  module Errors
+    # Raised by Client.new under on_init_failure: :fail (the default) when no
+    # config could be loaded (qfg-9p4i.10; init-failure design B.4). The base
+    # of the init-failure family: rescue this to catch every init failure.
+    #
+    # +reason+ is one of:
+    # - +:unavailable+ - every attempt failed fast (refused, DNS, 5xx) until
+    #   init_timeout_ms ran out
+    # - +:unauthorized+ - every delivery leg rejected the SDK key (401/403);
+    #   raised at once, without waiting out the timeout
+    # - +:timeout+ - an attempt was still in flight at init_timeout_ms
+    #   (InitializationTimeoutError)
+    #
+    # +errors+ is the per-leg summary (+primary=<host>: <error>; ...+). It names
+    # hosts only, never the SDK key.
+    class InitializationError < Quonfig::Error
+      REASONS = %i[unavailable unauthorized timeout].freeze
+
+      attr_reader :reason, :errors
+
+      def initialize(message = 'Quonfig failed to initialize', reason: :unavailable, errors: nil)
+        @reason = reason
+        @errors = errors
+        super(message)
+      end
+    end
+  end
+end

data/lib/quonfig/errors/initialization_timeout_error.rb

@@ -2,10 +2,15 @@
 
 module Quonfig
   module Errors
-    class InitializationTimeoutError < Quonfig::Error
-      def initialize(timeout_sec, key)
-        message = "Quonfig couldn't initialize in #{timeout_sec} second timeout. Trying to fetch key `#{key}`."
-        super(message)
+    # The init-failure error for a hang: an attempt was still in flight when
+    # init_timeout_ms ran out. A subclass of InitializationError (reason
+    # +:timeout+), so rescuing either class catches it.
+    class InitializationTimeoutError < InitializationError
+      # +timeout_sec+ and +key+ keep the original positional signature.
+      def initialize(timeout_sec, key = nil, message: nil, errors: nil)
+        message ||= "Quonfig couldn't initialize in #{timeout_sec} second timeout."
+        message += " Trying to fetch key `#{key}`." if key
+        super(message, reason: :timeout, errors: errors)
       end
     end
   end

data/lib/quonfig/evaluation_details.rb

@@ -16,6 +16,8 @@ module Quonfig
   # +error_code+ (only when reason == "ERROR") is one of:
   #   "FLAG_NOT_FOUND" — the key was unknown to the store
   #   "TYPE_MISMATCH"  — the resolved value didn't satisfy the requested type
+  #   "PROVIDER_NOT_READY" — the client has no config yet (init continued
+  #                          on code defaults, or a caught init failure)
   #   "GENERAL"        — any other failure
   class EvaluationDetails
     REASON_STATIC          = 'STATIC'
@@ -27,6 +29,7 @@ module Quonfig
     ERROR_FLAG_NOT_FOUND = 'FLAG_NOT_FOUND'
     ERROR_TYPE_MISMATCH  = 'TYPE_MISMATCH'
     ERROR_GENERAL        = 'GENERAL'
+    ERROR_PROVIDER_NOT_READY = 'PROVIDER_NOT_READY'
 
     attr_reader :value, :reason, :error_code, :error_message, :variant, :flag_metadata
 

data/lib/quonfig/http_connection.rb

@@ -90,7 +90,7 @@ module Quonfig
 
       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
+                      "wall-clock per-request deadline #{deadline_s}s exceeded for #{Quonfig::ConfigLoader.redact_userinfo(@uri)}") do
         block.call
       end
     end