quonfig 1.9.0 → 1.11.0

data/lib/quonfig/config_loader.rb

@@ -19,22 +19,66 @@ module Quonfig
 
     CONFIGS_PATH = '/api/v2/configs'
 
+    # Size-caps rule (qfg-6vno.8, supervisor-test-contract.md "Rule — size
+    # caps"): a 200 body from /api/v2/configs over 16 MiB is a failed leg,
+    # exactly like a 5xx. 4x the SSE event cap, so a workspace that outgrows
+    # the stream still stays fresh through the fallback poller. A constant,
+    # not an option.
+    MAX_CONFIG_BODY_BYTES = 16 * 1024 * 1024
+
     # 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
 
+    # 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 +110,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
@@ -141,6 +193,9 @@ module Quonfig
       # request, write-back after — the network wait happens with no lock held).
       @etags = {}
       @etag_mutex = Mutex.new
+      # Leg indexes in an oversized-body episode (WARN once, then DEBUG until
+      # that leg installs an envelope). Guarded by @etag_mutex.
+      @oversized_legs = Set.new
       @version = nil
       @environment_id = nil
       @logger = logger || LOG
@@ -208,27 +263,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 +332,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 +360,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,13 +470,16 @@ 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 /
       # single-URL path it passes config_fetch_timeout_ms.
-      conn = Quonfig::HttpConnection.new(source, @options.sdk_key, timeout_ms: timeout_ms)
+      conn = Quonfig::HttpConnection.new(source, @options.sdk_key, timeout_ms: timeout_ms,
+                                                                   max_body_bytes: MAX_CONFIG_BODY_BYTES)
       headers = {}
       # Per-leg ETag: snapshot this leg's slot before the request (no lock held
       # during the network wait).
@@ -428,39 +499,82 @@ module Quonfig
         # generation for the SAME sha; remembering it would 304 that repair.
         ignored_unversioned = result == :not_modified && extract_generation(envelope.meta || {}) <= 0
         set_etag_for(index, new_etag) unless ignored_unversioned
+        end_oversized_episode(index) if result == :updated
         # install_envelope returns :not_modified when the reject-older guard drops
         # an equal/older payload — surface that so the caller doesn't double-count.
         result == :not_modified ? :not_modified : :updated
       when 304
-        @logger.debug "Configs not modified (304) from #{source}"
+        @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 Quonfig::HttpConnection::BodyTooLargeError => e
+      # Size caps (qfg-6vno.20.5): a failed leg, like a 5xx. Reading stopped at
+      # the cap; nothing is installed and this leg's ETag is not stored.
+      note.call("200 body over the #{e.max_bytes}-byte cap")
+      log_oversized_body(index, where, e.max_bytes)
+      :failed
     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 #{source}: #{e.message}; treating as a failed leg")
+      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
+
+    # One WARN per oversized episode per leg; repeats at DEBUG (size-caps R4).
+    def log_oversized_body(index, where, max_bytes)
+      first = @etag_mutex.synchronize { @oversized_legs.add?(index || 0) }
+      msg = "Config fetch from #{where} returned a body over the maximum size of #{max_bytes} bytes; " \
+            'treating it as a failed leg'
+      first ? @logger.warn(msg) : @logger.debug(msg)
+    end
+
+    def end_oversized_episode(index)
+      @etag_mutex.synchronize { @oversized_legs.delete(index || 0) }
+    end
+
     def etag_for(index)
       @etag_mutex.synchronize { @etags[index || 0] }
     end
@@ -484,13 +598,6 @@ module Quonfig
       Quonfig::ConfigEnvelope.new(configs: configs, meta: meta)
     end
 
-    def short_body(response)
-      return '' if response.body.nil?
-
-      str = response.body.to_s
-      str.length > 200 ? "#{str[0, 200]}..." : str
-    end
-
     def install_envelope(envelope, source:, source_index: nil)
       meta = envelope.meta || {}
       incoming_gen = extract_generation(meta)
@@ -523,12 +630,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
@@ -548,7 +655,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

data/lib/quonfig/dev_context.rb

@@ -17,7 +17,14 @@ module Quonfig
     TOKENS_BASENAME = File.join('.quonfig', 'tokens.json')
 
     def self.load_quonfig_user_context
-      path = File.join(Dir.home, TOKENS_BASENAME)
+      home = begin
+        Dir.home
+      rescue ArgumentError
+        # HOME unset and no passwd entry (some containers): no dev context,
+        # as in sdk-go (qfg-7xlj).
+        return nil
+      end
+      path = File.join(home, TOKENS_BASENAME)
       return nil unless File.exist?(path)
 
       raw = begin

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

@@ -2,6 +2,9 @@
 
 require 'base64'
 require 'json'
+require 'net/http'
+require 'openssl'
+require 'zlib'
 require 'timeout'
 
 module Quonfig
@@ -26,6 +29,31 @@ module Quonfig
     # structurally cannot catch.
     WALL_CLOCK_HEADROOM_S = 0.25
 
+    # Raised by #get when +max_body_bytes+ is set and the response body grows
+    # past it (size-caps rule, qfg-6vno.20.5). Reading stops at the cap: the
+    # body is streamed through a byte counter, never read whole and measured
+    # afterwards. Not a Faraday error, so callers handle it explicitly.
+    class BodyTooLargeError < StandardError
+      attr_reader :max_bytes
+
+      def initialize(max_bytes)
+        @max_bytes = max_bytes
+        super("response body exceeds the maximum size of #{max_bytes} bytes")
+      end
+    end
+
+    # Size caps (qfg-6vno.20.5): a non-2xx body is read to at most this many
+    # bytes, then reading stops and the connection is dropped. Callers never
+    # use a non-2xx body (it is never logged), so a large one (a proxy error
+    # page, a 401 with 17 MiB of junk) must not be read toward the 16 MiB cap.
+    NON_2XX_BODY_READ_LIMIT = 1024
+
+    # Raised from inside the body read to stop it early; never escapes.
+    class StopReading < StandardError; end
+
+    # Minimal response for the bounded path: the fields callers use.
+    BoundedResponse = Struct.new(:status, :headers, :body)
+
     # +timeout_ms+ (qfg-7h5d.1.9): per-request bound applied to BOTH the connect
     # (open) and read phases of every request made through this connection, AND
     # (qfg-41nh.6) enforced as a wall-clock ceiling over the whole request. nil
@@ -39,17 +67,25 @@ module Quonfig
     # connect (open) phase — TCP connect plus TLS handshake. nil uses
     # +timeout_ms+ for it, as before. The telemetry reporter passes 5s here and
     # 15s as +timeout_ms+.
-    def initialize(uri, sdk_key, timeout_ms: nil, open_timeout_ms: nil)
+    #
+    # +max_body_bytes+ (qfg-6vno.20.5): when set, #get streams the body through
+    # a counter and raises BodyTooLargeError as soon as it passes this many
+    # bytes, so memory stays bounded near the cap. nil reads the body whole,
+    # as before. The config fetch passes ConfigLoader::MAX_CONFIG_BODY_BYTES.
+    def initialize(uri, sdk_key, timeout_ms: nil, open_timeout_ms: nil, max_body_bytes: nil)
       @uri = uri
       @sdk_key = sdk_key
       @timeout_ms = timeout_ms
       @open_timeout_ms = open_timeout_ms
+      @max_body_bytes = max_body_bytes
     end
 
     attr_reader :uri
 
     def get(path, headers = {})
-      with_wall_clock_deadline { connection(headers).get(path) }
+      return with_wall_clock_deadline { connection(headers).get(path) } unless @max_body_bytes
+
+      get_bounded(path, headers)
     end
 
     # A String +body+ is sent verbatim (the telemetry reporter resends a
@@ -78,6 +114,85 @@ module Quonfig
 
     private
 
+    # The bounded GET runs on Net::HTTP directly, because it needs the status
+    # BEFORE the body is read: a 2xx body is streamed through a counter that
+    # raises BodyTooLargeError past +max_body_bytes+; a non-2xx body is read to
+    # at most NON_2XX_BODY_READ_LIMIT bytes. Faraday 1.x's +on_data+ gives no
+    # status to the callback, so it cannot tell the two apart. URL, headers and
+    # proxy still come from the Faraday connection, so the request is the same.
+    # Transport errors are re-raised as the Faraday errors callers rescue.
+    def get_bounded(path, headers)
+      with_wall_clock_deadline { net_http_get_bounded(path, headers) }
+    end
+
+    def net_http_get_bounded(path, headers)
+      conn = connection(headers)
+      url = conn.build_exclusive_url(path)
+      req = Net::HTTP::Get.new(url.request_uri)
+      conn.headers.each { |k, v| req[k] = v }
+      result = nil
+      begin
+        bounded_http(conn, url).start do |http|
+          http.request(req) do |res|
+            result = BoundedResponse.new(res.code.to_i, response_headers(res), +''.b)
+            read_bounded_body(res, result)
+          end
+        end
+      rescue StopReading
+        nil
+      end
+      result.body.force_encoding(Encoding::UTF_8)
+      result
+    rescue BodyTooLargeError, Faraday::Error
+      raise
+    rescue Timeout::Error, Errno::ETIMEDOUT => e
+      raise Faraday::TimeoutError, e
+    rescue IOError, SystemCallError, SocketError, Net::ProtocolError, Net::HTTPBadResponse,
+           Net::HTTPHeaderSyntaxError, Zlib::Error, OpenSSL::SSL::SSLError => e
+      raise Faraday::ConnectionFailed, e
+    end
+
+    def bounded_http(conn, url)
+      proxy = conn.proxy
+      http = if proxy
+               Net::HTTP.new(url.hostname, url.port, proxy.uri.hostname, proxy.uri.port, proxy.user, proxy.password)
+             else
+               Net::HTTP.new(url.hostname, url.port, nil)
+             end
+      http.use_ssl = (url.scheme == 'https')
+      if @timeout_ms
+        http.open_timeout = @timeout_ms / 1000.0
+        http.read_timeout = @timeout_ms / 1000.0
+      end
+      http.open_timeout = @open_timeout_ms / 1000.0 if @open_timeout_ms
+      http.max_retries = 0 if http.respond_to?(:max_retries=)
+      http
+    end
+
+    def response_headers(res)
+      headers = Faraday::Utils::Headers.new
+      res.each_header { |k, v| headers[k] = v }
+      headers
+    end
+
+    # Reading stops at the limit: the chunk that would cross it is not kept.
+    def read_bounded_body(res, result)
+      buf = result.body
+      if (200..299).cover?(result.status)
+        max = @max_body_bytes
+        res.read_body do |chunk|
+          raise BodyTooLargeError, max if buf.bytesize + chunk.bytesize > max
+
+          buf << chunk.b
+        end
+      else
+        res.read_body do |chunk|
+          buf << chunk.b.byteslice(0, NON_2XX_BODY_READ_LIMIT - buf.bytesize)
+          raise StopReading if buf.bytesize >= NON_2XX_BODY_READ_LIMIT
+        end
+      end
+    end
+
     # 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
@@ -90,7 +205,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

data/lib/quonfig/internal_logger.rb

@@ -34,28 +34,28 @@ module Quonfig
     end
 
     # Log methods
-    def trace(message = nil, &block)
-      log_message(:trace, message, &block)
+    def trace(message = nil, event: nil, &block)
+      log_message(:trace, message, event: event, &block)
     end
 
-    def debug(message = nil, &block)
-      log_message(:debug, message, &block)
+    def debug(message = nil, event: nil, &block)
+      log_message(:debug, message, event: event, &block)
     end
 
-    def info(message = nil, &block)
-      log_message(:info, message, &block)
+    def info(message = nil, event: nil, &block)
+      log_message(:info, message, event: event, &block)
     end
 
-    def warn(message = nil, &block)
-      log_message(:warn, message, &block)
+    def warn(message = nil, event: nil, &block)
+      log_message(:warn, message, event: event, &block)
     end
 
-    def error(message = nil, &block)
-      log_message(:error, message, &block)
+    def error(message = nil, event: nil, &block)
+      log_message(:error, message, event: event, &block)
     end
 
-    def fatal(message = nil, &block)
-      log_message(:fatal, message, &block)
+    def fatal(message = nil, event: nil, &block)
+      log_message(:fatal, message, event: event, &block)
     end
 
     def level
@@ -172,7 +172,10 @@ module Quonfig
       level_str&.downcase&.to_sym
     end
 
-    def log_message(level, message, &block)
+    # +event+ (e.g. 'quonfig.init.failed') is a structured field: SemanticLogger
+    # gets it as the payload ({ event: ... }); plain Logger-shaped sinks only
+    # get the message, which already carries the full line.
+    def log_message(level, message, event: nil, &block)
       override = Quonfig::InternalLogger.user_logger
       if override
         write_to_user_logger(override, level, message, &block)
@@ -180,7 +183,11 @@ module Quonfig
       end
 
       if @using_semantic
-        @logger.send(level, message, &block)
+        if event
+          @logger.send(level, message, { event: event }, &block)
+        else
+          @logger.send(level, message, &block)
+        end
       else
         # stdlib Logger doesn't have trace
         level = :debug if level == :trace