quonfig 1.7.2 → 1.9.0

data/lib/quonfig/config_loader.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'json'
+require 'uri'
 
 module Quonfig
   # Fetches config envelopes from the Quonfig delivery API and installs them
@@ -18,6 +19,79 @@ module Quonfig
 
     CONFIGS_PATH = '/api/v2/configs'
 
+    # Rule R1 (qfg-goi1.10.26): the auth class. A fetch cycle with no 200/304
+    # on any leg and one of these on the primary leg is rejected; the client's
+    # poller then enters auth-failed (Client#start_polling).
+    AUTH_STATUSES = [401, 403, 404, 410].freeze
+
+    # 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
+
+      def initialize(result, statuses, primary_host)
+        @result = result
+        @statuses = statuses
+        @primary_host = primary_host
+      end
+
+      def primary_status
+        @statuses[0] || 0
+      end
+
+      # Rule R2: no leg returned 200/304 and the primary returned an
+      # auth-class status. A 200 the guard dropped, or a 304, never qualifies.
+      def auth_rejected?
+        return false unless @result == :failed
+        return false if @statuses.values.any? { |s| [200, 304].include?(s) }
+
+        AUTH_STATUSES.include?(primary_status)
+      end
+    end
+
+    # Collects one cycle's per-leg log lines. +mode+:
+    #   :normal - log at once, as always (init fetch, refresh, legacy callers)
+    #   :poll   - a poller cycle: hold the auth-class lines until the cycle is
+    #             classified, so an entering cycle logs its one ERROR in their
+    #             place (rule R5); otherwise they are logged unchanged
+    #   :probe  - an auth-failed probe: every line at DEBUG (rule R5)
+    class CycleLog
+      def initialize(logger, mode)
+        @logger = logger
+        @mode = mode
+        @held = []
+        @released = false
+        @mutex = Mutex.new
+      end
+
+      def log(level, msg, auth: false)
+        return @logger.debug(msg) if @mode == :probe
+
+        if @mode == :poll && auth
+          hold = @mutex.synchronize do
+            @held << [level, msg] unless @released
+            !@released
+          end
+          return if hold
+        end
+        @logger.public_send(level, msg)
+      end
+
+      # Log (or with +drop+, discard) the held lines. Lines from a leg that
+      # settles later are logged as they come.
+      def release(drop: false)
+        held = @mutex.synchronize do
+          @released = true
+          h = @held
+          @held = []
+          h
+        end
+        held.each { |level, msg| @logger.public_send(level, msg) } unless drop
+      end
+    end
+
     attr_reader :version, :environment_id
 
     # qfg-7h5d.1.9 (canonical ordering). Diagnostic surface read by the failover/
@@ -127,17 +201,32 @@ module Quonfig
     #   :not_modified  -- a leg answered 304 (no change) and nothing installed
     #   :failed        -- every fired leg failed
     def fetch!
+      fetch_cycle!.result
+    end
+
+    # One fetch cycle, as #fetch!, returning a FetchCycle that carries each
+    # 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)
       urls = Array(@options.config_api_urls)
-      return :failed if urls.empty?
+      statuses = Concurrent::Map.new
+      return FetchCycle.new(:failed, statuses, '') if urls.empty?
 
+      cycle_log = CycleLog.new(@logger, 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.
-      return fetch_from(urls[0], 0, timeout_ms: config_fetch_timeout_ms) if urls.length < 2
-
-      fetch_hedged(urls)
+      result = if urls.length < 2
+                 fetch_from(urls[0], 0, timeout_ms: config_fetch_timeout_ms, statuses: statuses, cycle_log: cycle_log)
+               else
+                 fetch_hedged(urls, statuses: statuses, cycle_log: cycle_log)
+               end
+      cycle = FetchCycle.new(result, statuses, host_of(urls[0]))
+      cycle_log.release(drop: cycle.auth_rejected?)
+      cycle
     end
 
     # Apply a ConfigEnvelope (from SSE) to the store. Called by the SSE client
@@ -176,7 +265,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)
+    def fetch_hedged(urls, statuses: nil, cycle_log: nil)
       hedge_delay_s = hedge_delay_ms / 1000.0
       abort_ms = hedge_abort_ms
 
@@ -204,7 +293,7 @@ module Quonfig
         Thread.new do
           result = :failed
           begin
-            result = fetch_from(urls[index], index, timeout_ms: abort_ms)
+            result = fetch_from(urls[index], index, timeout_ms: abort_ms, statuses: statuses, cycle_log: cycle_log)
           rescue StandardError => e
             @logger.debug "Hedge leg #{index} failed: #{e.class}: #{e.message}"
           ensure
@@ -306,7 +395,15 @@ module Quonfig
       @options.respond_to?(:config_fetch_timeout_ms) ? @options.config_fetch_timeout_ms : nil
     end
 
-    def fetch_from(source, index = nil, timeout_ms: nil)
+    def host_of(url)
+      uri = URI(url.to_s)
+      uri.host ? "#{uri.host}:#{uri.port}" : url.to_s
+    rescue URI::InvalidURIError
+      ''
+    end
+
+    def fetch_from(source, index = nil, timeout_ms: nil, statuses: nil, cycle_log: nil)
+      cycle_log ||= CycleLog.new(@logger, :normal)
       # 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 /
@@ -318,6 +415,7 @@ module Quonfig
       etag = etag_for(index)
       headers['If-None-Match'] = etag if etag
       response = conn.get(CONFIGS_PATH, headers)
+      statuses[index || 0] = response.status.to_i if statuses
 
       case response.status
       when 200
@@ -337,23 +435,29 @@ module Quonfig
         @logger.debug "Configs not modified (304) from #{source}"
         :not_modified
       when 401, 403
-        @logger.warn "Config fetch rejected (#{response.status}) from #{source}: #{short_body(response)}"
+        cycle_log.log(:warn, "Config fetch rejected (#{response.status}) from #{source}: #{short_body(response)}", auth: true)
         :failed
       else
-        @logger.info "Config fetch failed: status #{response.status} from #{source}"
+        cycle_log.log(:info, "Config fetch failed: status #{response.status} from #{source}",
+                      auth: AUTH_STATUSES.include?(response.status.to_i))
         :failed
       end
     rescue NonEnvelopeError => e
       # 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).
-      @logger.warn "Config fetch from #{source} returned a non-envelope 200 (#{e.message}); treating as a failed leg"
+      cycle_log.log(:warn, "Config fetch from #{source} returned a non-envelope 200 (#{e.message}); treating as a failed leg")
+      :failed
+    rescue Quonfig::ConfigShape::AllInvalidError => e
+      # 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 #{source}: #{e.message}; treating as a failed leg")
       :failed
     rescue Faraday::ConnectionFailed => e
       @logger.debug "Connection failure fetching configs from #{source}: #{e.message}"
       :failed
     rescue StandardError => e
-      @logger.warn "Unexpected error fetching configs from #{source}: #{e.message}"
+      cycle_log.log(:warn, "Unexpected error fetching configs from #{source}: #{e.message}")
       :failed
     end
 
@@ -373,10 +477,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'] || {}
-      )
+      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 short_body(response)
@@ -461,6 +566,27 @@ module Quonfig
         @version = meta['version'] || meta[:version] || @version
         @environment_id = meta['environment'] || meta[:environment] || @environment_id
 
+        # Replace the live store first, then advance the generation
+        # (qfg-goi1.10.2). An interrupt part-way through the store write
+        # (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?
+          next_configs = {}
+          envelope.configs.each do |cfg|
+            key = config_key(cfg)
+            next if key.nil?
+
+            next_configs[key] = cfg
+          end
+          @store.replace_all(next_configs)
+        end
+
         # qfg-9dxb.3 Fix A: an unversioned install (generation <= 0) carries no
         # ordering info and must never LOWER a positive held generation. Under
         # the qfg-9dxb.9 rule it only installs when held is nil/0 anyway, so
@@ -473,21 +599,6 @@ module Quonfig
         # 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?
-
-        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)
-
-        envelope.configs.each do |cfg|
-          key = config_key(cfg)
-          next if key.nil?
-
-          @store.set(key, cfg)
-        end
       end
     end
 

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

@@ -3,7 +3,9 @@
 module Quonfig
   module Errors
     class EnvVarParseError < Quonfig::Error
-      def initialize(_env_var, config, env_var_name)
+      # +stored: true+ marks a malformed stored value (no env var involved);
+      # the message then names the stored value rather than a variable.
+      def initialize(_env_var, config, env_var_name, stored: false)
         key, value_type =
           if config.is_a?(Hash)
             [config[:key] || config['key'],
@@ -12,8 +14,13 @@ module Quonfig
             [config.key, config.value_type]
           end
         # +_env_var+ (the raw value) is deliberately left out of the message:
-        # an env var or stored value can be a secret (qfg-goi1.2.11).
-        super("Evaluating #{key} couldn't coerce #{env_var_name} to #{value_type}")
+        # an env var or stored value can be a secret (qfg-goi1.2.11). The
+        # wording is the cross-SDK template pinned by integration-test-data
+        # (v2026.10.12): it names the variable, the lowercase type and the
+        # config key, never the value or a parser message quoting it.
+        type_name = value_type.to_s.downcase
+        source = stored ? 'stored value' : %(environment variable "#{env_var_name}")
+        super(%(#{source} cannot be converted to #{type_name} for config "#{key}"))
       end
     end
   end