quonfig 1.7.1 → 1.8.0

data/lib/quonfig/sse_config_client.rb

@@ -51,10 +51,17 @@ module Quonfig
 
     LOG = Quonfig::InternalLogger.new(self)
 
-    # qfg-i5xv: HTTP status codes the SDK classifies as terminal — these will
-    # not heal by retrying (bad key, revoked permission, missing endpoint).
-    # Anything else (5xx, 429, network errors) stays on the transient path.
-    TERMINAL_HTTP_CODES = [401, 403, 404].freeze
+    # Auth-class statuses (rule R1, qfg-goi1.10.26). On the stream they keep the
+    # normal reconnect ladder: SSE alone never stops retrying and never enters
+    # auth-failed (R2); the client's fallback poller decides that from a whole
+    # fetch cycle. They only get their own log line: WARN once per status,
+    # re-armed by a 200, DEBUG otherwise (R5).
+    AUTH_HTTP_CODES = [401, 403, 404, 410].freeze
+
+    # @deprecated since 1.8.0. qfg-i5xv's "terminal" codes. Nothing is terminal
+    # any more (the latch is gone, qfg-goi1.10.26); kept as an alias of
+    # AUTH_HTTP_CODES for code that references the constant.
+    TERMINAL_HTTP_CODES = AUTH_HTTP_CODES
 
     # qfg-6y44: headroom added to +sse_read_timeout+ when configuring
     # Net::HTTP#read_timeout. The ReadDeadlineWatchdog already covers both the
@@ -88,6 +95,8 @@ module Quonfig
       @active_http = nil
 
       @last_event_id = nil
+      # Auth-class statuses already logged at WARN since the last 200 (R5).
+      @auth_warned = Set.new
       # qfg-7h5d.1.9 / qfg-41nh.6: latches true if a connection attempt ever
       # targets a non-primary sse_api_urls leg. The failover epic asserts SSE
       # does NOT fail over to the secondary (f05) — the stream is PINNED to
@@ -220,7 +229,7 @@ module Quonfig
           begin
             unless first_attempt
               increment_restart!
-              interruptible_sleep(jittered(delay))
+              interruptible_sleep(jittered(Quonfig::Waits.duration(:sse, delay)))
               break if @stopped.value
             end
             first_attempt = false
@@ -314,26 +323,7 @@ module Quonfig
 
       begin
         http.request(req) do |resp|
-          code = resp.code.to_i
-          if TERMINAL_HTTP_CODES.include?(code)
-            # qfg-i5xv: 401/403/404 will not heal by retrying — bad key,
-            # revoked permission, or wrong endpoint. Mark stopped *before*
-            # invoking on_error so the loop's terminal-error branch is
-            # already locked in if the parent callback inspects state, and
-            # so the inner rescue's `handle_error(e) unless @stopped.value`
-            # guard suppresses a second on_error edge.
-            err = SSEHTTPTerminalError.new(code)
-            @logger.error "SSE Streaming Terminal Error: HTTP #{code} for url #{url}; will not retry"
-            @stopped.make_true
-            invoke_on_error(err)
-            raise err
-          end
-          if code != 200
-            err = SSEHTTPStatusError.new(code)
-            @logger.error "SSE Streaming Error: HTTP #{code} for url #{url}"
-            invoke_on_error(err)
-            raise err
-          end
+          check_response_status!(resp.code.to_i, url)
 
           parser = EventParser.new
           # qfg-tj18: run_loop wraps the body in +:on_blocking+ which
@@ -365,6 +355,35 @@ module Quonfig
       end
     end
 
+    # Classify the stream response. Raises for any non-200 so run_loop applies
+    # its backoff.
+    #
+    # Auth class (401/403/404/410, qfg-goi1.10.26): no latch. The normal
+    # ladder applies and run_loop's handle_error fires on_error once, so the
+    # client schedules the fallback poller exactly as for any drop; that
+    # poller's fetch cycle is what decides auth-failed (R2). Logged WARN once
+    # per status until a 200 re-arms it, DEBUG otherwise (R5), so a revoked
+    # key does not log two ERRORs per attempt for the ~2 min before entry.
+    def check_response_status!(code, url)
+      if AUTH_HTTP_CODES.include?(code)
+        if @auth_warned.add?(code)
+          @logger.warn "SSE Streaming Error: HTTP #{code} for url #{url}; " \
+                       'the SDK key may be invalid or revoked (check the SDK key); retrying'
+        else
+          @logger.debug "SSE Streaming Error: HTTP #{code} for url #{url}; retrying"
+        end
+        raise SSEHTTPAuthError, code
+      end
+      if code != 200
+        err = SSEHTTPStatusError.new(code)
+        @logger.error "SSE Streaming Error: HTTP #{code} for url #{url}"
+        invoke_on_error(err)
+        raise err
+      end
+
+      @auth_warned.clear
+    end
+
     # Track the active connection so close() can interrupt a blocked
     # read_body from another thread. Guarded by @conn_mutex.
     def register_active(http)
@@ -376,7 +395,12 @@ module Quonfig
     end
 
     def handle_error(error)
-      @logger.error "SSE Streaming Error: #{error.inspect}"
+      if error.is_a?(SSEHTTPAuthError)
+        # Already logged once by check_response_status! (R5).
+        @logger.debug "SSE Streaming Error: #{error.inspect}"
+      else
+        @logger.error "SSE Streaming Error: #{error.inspect}"
+      end
       invoke_on_error(error)
     end
 
@@ -445,13 +469,14 @@ module Quonfig
       end
     end
 
-    # qfg-i5xv: terminal HTTP failures the SDK will not retry. 401 = bad key,
-    # 403 = revoked workspace permission, 404 = wrong endpoint / missing
-    # workspace. A subclass of SSEHTTPStatusError so existing on_error
-    # callbacks that only check `is_a?(SSEHTTPStatusError)` keep working,
-    # while customers that want to distinguish (alerting, OpenFeature
-    # provider error events) can dispatch on the subclass.
-    class SSEHTTPTerminalError < SSEHTTPStatusError; end
+    # An auth-class (401/403/404/410) stream response (qfg-goi1.10.26). A
+    # subclass of SSEHTTPStatusError so on_error callbacks that only check
+    # `is_a?(SSEHTTPStatusError)` keep working. The stream keeps retrying.
+    class SSEHTTPAuthError < SSEHTTPStatusError; end
+
+    # @deprecated since 1.8.0: qfg-i5xv's name for SSEHTTPAuthError. The stream
+    # no longer stops on these statuses.
+    SSEHTTPTerminalError = SSEHTTPAuthError # rubocop:disable Lint/UselessConstantScoping
 
     # Raised by the watchdog into the worker thread when the per-chunk
     # read deadline elapses. Caught by run_loop's rescue, indistinguishable
@@ -630,37 +655,59 @@ module Quonfig
       def initialize
         @buffer = +''.b
         @last_was_cr = false
+        # Bytes of @buffer already scanned without finding a terminator, so
+        # the next feed resumes there instead of rescanning from byte 0
+        # (qfg-goi1.10.2; O(n^2) on a long line in small chunks).
+        @scanned = 0
       end
 
+      # Lines are sliced out by position and the consumed prefix is dropped
+      # once per feed (in +ensure+, so a raising block does not see a line
+      # twice), not once per line.
       def feed(chunk)
         @buffer << chunk.b
-        loop do
-          idx = @buffer.index(/[\r\n]/)
-          break if idx.nil?
+        pos = 0
+        begin
+          loop do
+            idx = @buffer.index(/[\r\n]/, [pos, @scanned].max)
+            if idx.nil?
+              @scanned = @buffer.bytesize
+              break
+            end
 
-          ch = @buffer[idx]
-          if idx.zero? && ch == "\n" && @last_was_cr
-            # Dangling LF of a CRLF pair split across chunks — consume and skip.
-            @last_was_cr = false
-            @buffer.slice!(0, 1)
-            next
-          end
+            ch = @buffer.getbyte(idx)
+            if idx == pos && ch == LF && @last_was_cr
+              # Dangling LF of a CRLF pair split across chunks — consume and skip.
+              @last_was_cr = false
+              pos += 1
+              next
+            end
 
-          line = @buffer[0, idx].force_encoding('UTF-8')
-          consume = idx + 1
-          @last_was_cr = false
-          if ch == "\r"
-            if consume == @buffer.bytesize
-              # CR at end of buffer — could be CRLF split across feeds.
-              @last_was_cr = true
-            elsif @buffer[consume] == "\n"
-              consume += 1
+            line = @buffer.byteslice(pos, idx - pos).force_encoding('UTF-8')
+            consume_to = idx + 1
+            @last_was_cr = false
+            if ch == CR
+              if consume_to == @buffer.bytesize
+                # CR at end of buffer — could be CRLF split across feeds.
+                @last_was_cr = true
+              elsif @buffer.getbyte(consume_to) == LF
+                consume_to += 1
+              end
             end
+            pos = consume_to
+            yield line
+          end
+        ensure
+          if pos.positive?
+            @buffer = @buffer.byteslice(pos, @buffer.bytesize - pos)
+            @scanned = [@scanned - pos, 0].max
           end
-          @buffer.slice!(0, consume)
-          yield line
         end
       end
+
+      CR = 13
+      LF = 10
+      private_constant :CR, :LF
     end
   end
 end

data/lib/quonfig/stdlib_formatter.rb

@@ -74,7 +74,7 @@ module Quonfig
         path = logger_name || progname
         level = SEVERITY_TO_LEVEL[severity.to_s.upcase] || :info
 
-        if client.should_log?(logger_path: path, desired_level: level)
+        if emit?(client, path, level)
           format_record(severity, datetime, progname, msg)
         else
           ''
@@ -82,6 +82,17 @@ module Quonfig
       end
     end
 
+    # The formatter runs inside the host app's Logger calls and must never
+    # raise out of them. A resolution error (unset ENV_VAR, decryption
+    # failure, ...) emits the line, matching SemanticLoggerFilter
+    # (qfg-goi1.2.11, qfg-goi1.2.28). Nothing is logged here, since logging
+    # from inside a formatter can recurse.
+    def self.emit?(client, path, level)
+      client.should_log?(logger_path: path, desired_level: level)
+    rescue StandardError
+      true
+    end
+
     # Default record formatter. Matches ::Logger::Formatter's general shape
     # ("I, [timestamp pid] SEVERITY -- progname: message") but without the
     # process-id first-letter noise so output is readable in tests and

data/lib/quonfig/telemetry/example_contexts_aggregator.rb

@@ -15,6 +15,10 @@ module Quonfig
       # prunes expired entries, and is not recorded if it is still full.
       SEEN_CAP = 100_000
 
+      # Max nesting depth copied from a context value; deeper levels are left
+      # out. Guards the recursive copy against stack exhaustion.
+      MAX_SNAPSHOT_DEPTH = 32
+
       attr_reader :data, :cache
 
       def initialize(max_contexts:, rate_limit_seconds: ONE_HOUR_SECONDS, seen_cap: SEEN_CAP)
@@ -38,7 +42,7 @@ module Quonfig
         return unless room_in_cache?
 
         @cache.set(key)
-        @data.push([Quonfig::TimeHelpers.now_in_ms, context])
+        @data.push([Quonfig::TimeHelpers.now_in_ms, snapshot(context)])
       end
 
       def prepare_data
@@ -65,6 +69,19 @@ module Quonfig
 
       private
 
+      # Copy +context+ into plain JSON-safe data at record time (qfg-goi1.2.35).
+      # The caller owns its nested Hashes/Arrays and may mutate them after
+      # get() returns, while the window is serialized later on the reporter
+      # thread. NaN/Infinity become nil, and an edge that closes a cycle is
+      # left out, so one bad value no longer makes JSON.generate raise and drop
+      # the whole window. Any other object is rendered with #to_s, which is
+      # what JSON.generate already sent for it (a UUID-like key keeps the
+      # example reportable); one whose #to_s raises is left out.
+      def snapshot(context)
+        named = contexts_to_list(context)
+        named.to_h { |entry| [entry['type'], snapshot_value(entry['values'], 0, {})] }
+      end
+
       def room_in_cache?
         return true if @cache.data.size < @seen_cap
 
@@ -102,6 +119,43 @@ module Quonfig
         end
       end
 
+      OMIT = Object.new.freeze
+      private_constant :OMIT
+
+      def snapshot_value(value, depth, ancestors)
+        case value
+        when nil, true, false, Integer then value
+        when Float then value.finite? ? value : nil
+        when String then value.frozen? ? value : value.dup
+        when Symbol then value.to_s
+        when Hash, Array then snapshot_container(value, depth, ancestors)
+        else value.to_s
+        end
+      rescue StandardError
+        OMIT
+      end
+
+      # +ancestors+ holds the containers on the current path only, so the same
+      # value reached twice without a cycle is still copied both times.
+      def snapshot_container(value, depth, ancestors)
+        id = value.object_id
+        return OMIT if depth >= MAX_SNAPSHOT_DEPTH || ancestors.key?(id)
+
+        ancestors[id] = true
+        begin
+          if value.is_a?(Hash)
+            value.each_with_object({}) do |(k, v), acc|
+              copied = snapshot_value(v, depth + 1, ancestors)
+              acc[k.to_s] = copied unless copied.equal?(OMIT)
+            end
+          else
+            value.map { |v| snapshot_value(v, depth + 1, ancestors) }.reject { |v| v.equal?(OMIT) }
+          end
+        ensure
+          ancestors.delete(id)
+        end
+      end
+
       def stringify_values(hash)
         return {} unless hash.is_a?(Hash)
 

data/lib/quonfig/version.rb

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

data/lib/quonfig/waits.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Quonfig
+  # Internal test seam for the SDK's background waits (qfg-goi1.10.26).
+  #
+  # Every long background wait goes through here with a kind:
+  #   :sse    - SSE reconnect backoff (the unjittered base delay)
+  #   :engage - fallback-poller grace after a mid-life SSE drop
+  #   :poll   - fallback / polling-mode poll interval
+  #   :probe  - auth-failed probe period (rule R3)
+  #
+  # A hook, when set, sees the REQUESTED seconds and returns the seconds to
+  # actually wait. Tests use it to record the requested values and compress
+  # time (supervisor-test-contract.md Test 8). It is not a customer option and
+  # is nil in production.
+  module Waits
+    class << self
+      attr_accessor :hook
+
+      def duration(kind, seconds)
+        h = hook
+        h ? h.call(kind, seconds) : seconds
+      end
+
+      def sleep(kind, seconds)
+        Kernel.sleep(duration(kind, seconds))
+      end
+    end
+  end
+end

data/lib/quonfig/worker_supervisor.rb

@@ -95,6 +95,11 @@ module Quonfig
         t
       end
       return if thread.nil?
+      # Called from the worker itself (the poller leaving auth-failed hands
+      # back to SSE, qfg-goi1.10.26): the flag is enough. The worker returns,
+      # run_loop sees stop? and exits without a restart. Raising into or
+      # joining the current thread would kill it mid-handoff.
+      return if thread == Thread.current
 
       raise_shutdown(thread)
       thread.join(SHUTDOWN_TIMEOUT_SEC)

data/lib/quonfig.rb

@@ -29,6 +29,7 @@ require 'quonfig/evaluation'
 require 'quonfig/evaluation_details'
 require 'quonfig/encryption'
 require 'quonfig/exponential_backoff'
+require 'quonfig/waits'
 require 'quonfig/worker_supervisor'
 require 'quonfig/periodic_sync'
 require 'quonfig/errors/initialization_timeout_error'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: quonfig
 version: !ruby/object:Gem::Version
-  version: 1.7.1
+  version: 1.8.0
 platform: ruby
 authors:
 - Jeff Dwyer
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-03 00:00:00.000000000 Z
+date: 2026-10-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -136,6 +136,7 @@ files:
 - lib/quonfig/time_helpers.rb
 - lib/quonfig/types.rb
 - lib/quonfig/version.rb
+- lib/quonfig/waits.rb
 - lib/quonfig/weighted_value_resolver.rb
 - lib/quonfig/worker_supervisor.rb
 - quonfig.gemspec