quonfig 1.9.0 → 1.11.0

data/lib/quonfig/options.rb

@@ -13,6 +13,11 @@ module Quonfig
                 :telemetry_max_retained_bytes, :telemetry_max_retained_age_ms
     attr_accessor :is_fork
 
+    # The deprecated on_init_failure spelling passed (:raise / :return), or nil.
+    attr_reader :on_init_failure_alias
+    # An unrecognized on_init_failure value (treated as :fail), or nil.
+    attr_reader :on_init_failure_unknown
+
     # Default fallback poll interval, in milliseconds. The SDK polls api-delivery
     # at this cadence only when SSE is unavailable for >= 2x this value.
     DEFAULT_FALLBACK_POLL_INTERVAL_MS = 60_000
@@ -76,9 +81,42 @@ module Quonfig
       ms == ms.to_i ? ms.to_i : ms
     end
 
+    # What Client.new does when no config has loaded by +init_timeout_ms+
+    # (qfg-9p4i.10; project/plans/2026-10-05-init-failure-design.md B.1-B.3):
+    #
+    # - +:fail+ (default): raise Quonfig::Errors::InitializationError. Every
+    #   delivery leg answering 401/403 raises at once, without waiting out the
+    #   timeout.
+    # - +:wait+: keep blocking and retrying with no upper bound.
+    # - +:continue+: return a client over an empty store (getters answer with
+    #   the caller's default) that keeps retrying in the background.
+    #
+    # +:raise+ and +:return+ are the deprecated earlier spellings of +:fail+ and
+    # +:continue+. They are still accepted and log a one-time WARN.
     module ON_INITIALIZATION_FAILURE
+      FAIL = :fail
+      WAIT = :wait
+      CONTINUE = :continue
+      # @deprecated Use FAIL.
       RAISE = :raise
+      # @deprecated Use CONTINUE.
       RETURN = :return
+
+      MODES = [FAIL, WAIT, CONTINUE].freeze
+      ALIASES = { RAISE => FAIL, RETURN => CONTINUE }.freeze
+
+      # [canonical mode, deprecated alias given or nil, unknown value or nil].
+      # Strings are accepted ('fail', ':raise'). An unknown value resolves to
+      # FAIL, the safe default, and is reported so the client can warn.
+      def self.resolve(value)
+        return [FAIL, nil, nil] if value.nil?
+
+        sym = value.to_s.delete_prefix(':').to_sym
+        return [sym, nil, nil] if MODES.include?(sym)
+        return [ALIASES[sym], sym, nil] if ALIASES.key?(sym)
+
+        [FAIL, nil, value]
+      end
     end
 
     module ON_NO_DEFAULT
@@ -217,6 +255,13 @@ module Quonfig
     private
 
     # @!method initialize(options = {})
+    #   @option options [Integer] :init_timeout_ms (10000)
+    #     How long +Client.new+ retries the initial config fetch before
+    #     +:on_init_failure+ decides. A value <= 0 runs exactly one fetch
+    #     attempt, lets it finish (it is bounded by the per-leg fetch timeouts,
+    #     not by this option), then applies +:on_init_failure+: +:fail+ raises,
+    #     +:continue+ starts on code defaults and keeps retrying in the
+    #     background, +:wait+ keeps retrying. It never means "no deadline".
     #   @option options [Boolean] :data_dir_auto_reload (false)
     #     Datadir mode only. When +true+, the SDK watches the workspace
     #     directory and re-reads the envelope whenever files inside it
@@ -271,7 +316,7 @@ module Quonfig
       on_no_default: ON_NO_DEFAULT::RAISE,
       init_timeout_ms: nil,
       initialization_timeout_sec: nil,
-      on_init_failure: ON_INITIALIZATION_FAILURE::RAISE,
+      on_init_failure: ON_INITIALIZATION_FAILURE::FAIL,
       config_fetch_timeout_ms: nil,
       config_fetch_hedge_delay_ms: nil,
       config_fetch_hedge_abort_ms: nil,
@@ -334,7 +379,10 @@ module Quonfig
                          else
                            DEFAULT_INIT_TIMEOUT_MS
                          end
-      @on_init_failure = on_init_failure
+      # Stored canonical (:fail / :wait / :continue); the deprecated spelling
+      # the caller used, if any, is kept for the client's one-time WARN.
+      @on_init_failure, @on_init_failure_alias, @on_init_failure_unknown =
+        ON_INITIALIZATION_FAILURE.resolve(on_init_failure)
       # qfg-7h5d.1.9: per-URL config-fetch timeout. nil → DEFAULT_CONFIG_FETCH_TIMEOUT_MS.
       @config_fetch_timeout_ms = config_fetch_timeout_ms || DEFAULT_CONFIG_FETCH_TIMEOUT_MS
       # qfg-7h5d.1.14: parallel-failover hedge knobs. nil → defaults. The hedge

data/lib/quonfig/sse_config_client.rb

@@ -76,6 +76,14 @@ module Quonfig
     # letting it win the race.
     READ_TIMEOUT_HEADROOM = 30
 
+    # Size-caps rule (qfg-6vno.8, supervisor-test-contract.md "Rule — size
+    # caps"; sdk-go's sseMaxLine): one SSE event, any single line and the sum
+    # of a multi-line data:, is capped at 4 MiB. The parser stops reading at
+    # the cap, so memory per stream stays near the cap plus one read chunk
+    # even for an event with no terminator. Over the cap is not a frame: the
+    # connection is a failed attempt. A constant, not an option.
+    MAX_EVENT_BYTES = 4 * 1024 * 1024
+
     # +on_error+: optional callable invoked on every SSE error edge. Parent
     # Quonfig::Client wires this to drive @sse_state -> :error so that
     # +connection_state+ reflects the disconnect (qfg-47c2.27). A connection
@@ -118,6 +126,13 @@ module Quonfig
       # that reintroduces stream-URL rotation is observable to the failover
       # chaos probe (f05) and to operators.
       @failed_over_to_secondary = false
+      # Oversized gate (size caps, sdk-go's +oversized+): set when a stream
+      # ended on an event over MAX_EVENT_BYTES. While set, a keepalive is not
+      # a frame, so a connection that only re-delivers the oversized snapshot
+      # never reports connected and the fallback poller keeps config fresh.
+      # The first envelope clears it (and ends the WARN episode). Touched only
+      # by the worker thread.
+      @oversized = false
     end
 
     # True if the live SSE stream has ever connected to a non-primary leg. Read
@@ -250,6 +265,9 @@ module Quonfig
             # parser, before the frame's envelope is installed.
             frame_seen = false
             on_frame = lambda do
+              # Gated, the parser reports only envelopes as frames; one ends
+              # the oversized episode.
+              @oversized = false
               next if frame_seen
 
               frame_seen = true
@@ -275,6 +293,11 @@ module Quonfig
               # survives a clean-EOF reconnect only until the next connection
               # ends frameless.
               handle_frameless_end(ended_url) unless frame_seen || @stopped.value
+            rescue SSEEventTooLargeError => e
+              # A failed attempt even if an earlier frame arrived on this
+              # connection (sdk-go returns frameSeen=false here).
+              frame_seen = false
+              handle_oversized_event(e) unless @stopped.value
             rescue StandardError => e
               handle_error(e) unless @stopped.value
             end
@@ -353,7 +376,7 @@ module Quonfig
         http.request(req) do |resp|
           check_response_status!(resp.code.to_i, url)
 
-          parser = EventParser.new
+          parser = EventParser.new(keepalive_is_frame: !@oversized)
           # qfg-tj18: run_loop wraps the body in +:on_blocking+ which
           # *would* still deliver during read_body (read_body is a
           # blocking IO call), but be explicit: we want the watchdog raise
@@ -449,6 +472,18 @@ module Quonfig
       end
     end
 
+    # Size caps R4: one WARN per oversized episode (redacted source + cap in
+    # bytes), repeats at DEBUG. The episode lasts until an envelope gets
+    # through (@oversized cleared in run_loop's on_frame).
+    def handle_oversized_event(error)
+      where = Quonfig::ConfigLoader.redact_userinfo("#{current_url}/api/v2/sse/config")
+      msg = "SSE event from #{where} exceeds the maximum size of #{MAX_EVENT_BYTES} bytes; " \
+            'dropping it and backing off (fallback polling will take over)'
+      @oversized ? @logger.debug(msg) : @logger.warn(msg)
+      @oversized = true
+      invoke_on_error(error)
+    end
+
     def handle_error(error)
       if error.is_a?(SSEHTTPAuthError)
         # Already logged once by check_response_status! (R5).
@@ -546,6 +581,14 @@ module Quonfig
     # from any other transport error for backoff/restart purposes.
     class SSEReadDeadlineExceeded < StandardError; end
 
+    # Raised by the parser when one event passes MAX_EVENT_BYTES (size caps).
+    # Ends the connection as a failed attempt; passed to on_error.
+    class SSEEventTooLargeError < StandardError
+      def initialize(msg = "SSE event exceeds the maximum size of #{MAX_EVENT_BYTES} bytes")
+        super
+      end
+    end
+
     # Private: raised from inside +read_body+ when +close+ has been called,
     # so the worker leaves the stream without Net::HTTP draining the body
     # (qfg-yrly). Rescued in +stream_once+; never reaches callers.
@@ -636,8 +679,11 @@ module Quonfig
     # Malformed +data:+ JSON is logged and skipped; one bad event does not
     # tear down the stream.
     class EventParser
-      def initialize(logger: nil)
+      # +keepalive_is_frame+: false while the client's oversized gate is set,
+      # so only an envelope counts as a frame (size caps).
+      def initialize(logger: nil, keepalive_is_frame: true)
         @logger = logger
+        @keepalive_is_frame = keepalive_is_frame
         @reader = LineReader.new
         @data = +''
         @have_data = false
@@ -663,7 +709,7 @@ module Quonfig
             if event
               on_frame&.call
               yield event
-            elsif comment_only
+            elsif comment_only && @keepalive_is_frame
               on_frame&.call
             end
           elsif line.start_with?(':')
@@ -687,6 +733,14 @@ module Quonfig
 
         case name
         when 'data'
+          # Cap the joined multi-line data (each line is already capped by
+          # LineReader).
+          if @have_data && @data.bytesize + 1 + rest.bytesize > MAX_EVENT_BYTES
+            @data = +''
+            @have_data = false
+            raise SSEEventTooLargeError
+          end
+
           if @have_data
             @data << "\n" << rest
           else
@@ -766,9 +820,14 @@ module Quonfig
           loop do
             idx = @buffer.index(/[\r\n]/, [pos, @scanned].max)
             if idx.nil?
+              # Size caps: an unterminated line past the cap can never be a
+              # valid event; stop here instead of buffering the rest.
+              raise SSEEventTooLargeError if @buffer.bytesize - pos > MAX_EVENT_BYTES
+
               @scanned = @buffer.bytesize
               break
             end
+            raise SSEEventTooLargeError if idx - pos > MAX_EVENT_BYTES
 
             ch = @buffer.getbyte(idx)
             if idx == pos && ch == LF && @last_was_cr

data/lib/quonfig/version.rb

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

data/lib/quonfig.rb

@@ -32,6 +32,7 @@ require 'quonfig/exponential_backoff'
 require 'quonfig/waits'
 require 'quonfig/worker_supervisor'
 require 'quonfig/periodic_sync'
+require 'quonfig/errors/initialization_error'
 require 'quonfig/errors/initialization_timeout_error'
 require 'quonfig/errors/invalid_sdk_key_error'
 require 'quonfig/errors/missing_default_error'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: quonfig
 version: !ruby/object:Gem::Version
-  version: 1.9.0
+  version: 1.11.0
 platform: ruby
 authors:
 - Jeff Dwyer
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-20 00:00:00.000000000 Z
+date: 2026-10-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -101,6 +101,7 @@ files:
 - lib/quonfig/error.rb
 - lib/quonfig/errors/decryption_error.rb
 - lib/quonfig/errors/env_var_parse_error.rb
+- lib/quonfig/errors/initialization_error.rb
 - lib/quonfig/errors/initialization_timeout_error.rb
 - lib/quonfig/errors/invalid_environment_error.rb
 - lib/quonfig/errors/invalid_sdk_key_error.rb