quonfig 1.8.0 → 1.10.0

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

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

@@ -47,7 +47,33 @@ module Quonfig
     # the legacy "return nil if absent" shape can rescue and recover (see
     # IntegrationTestHelpers.assert_resolved, which folds a missing-key
     # raise into the test's expected default).
+    # The whole lookup reads one store snapshot (qfg-i86q): the flag, the
+    # segments it references and any decryptWith key all come from the same
+    # envelope even if an install lands mid-evaluation.
     def get(key, context = nil)
+      return get_unpinned(key, context) unless @store.respond_to?(:pinned)
+
+      @store.pinned { get_unpinned(key, context) }
+    end
+
+    # Post-evaluation value resolution. Mirrors sdk-node Resolver#resolveValue
+    # and sdk-go resolver.Resolve:
+    # - "provided" + ENV_VAR  → read ENV[lookup], coerce to config's valueType
+    # - confidential + decryptWith → look up the key config, decrypt
+    # - everything else passes through unchanged
+    def resolve_value(value, config, context = nil, &on_weighted_index)
+      resolve_value_on_path(value, config, context, [], &on_weighted_index)
+    end
+
+    # Integration shims for code that expects a ConfigResolver. Keep these
+    # narrow; the real ConfigResolver still owns the production hot path.
+    def symbolize_json_names?
+      false
+    end
+
+    private
+
+    def get_unpinned(key, context)
       config = raw(key)
       raise Quonfig::Errors::MissingDefaultError, key if config.nil?
 
@@ -75,23 +101,6 @@ module Quonfig
       )
     end
 
-    # Post-evaluation value resolution. Mirrors sdk-node Resolver#resolveValue
-    # and sdk-go resolver.Resolve:
-    # - "provided" + ENV_VAR  → read ENV[lookup], coerce to config's valueType
-    # - confidential + decryptWith → look up the key config, decrypt
-    # - everything else passes through unchanged
-    def resolve_value(value, config, context = nil, &on_weighted_index)
-      resolve_value_on_path(value, config, context, [], &on_weighted_index)
-    end
-
-    # Integration shims for code that expects a ConfigResolver. Keep these
-    # narrow; the real ConfigResolver still owns the production hot path.
-    def symbolize_json_names?
-      false
-    end
-
-    private
-
     # resolve_value plus +key_path+: the config keys already being resolved
     # above this one through decryptWith, so a decryptWith cycle raises a
     # DecryptionError instead of recursing until SystemStackError

data/lib/quonfig/sse_config_client.rb

@@ -34,10 +34,12 @@ module Quonfig
       #
       # sse_initial_reconnect_delay / sse_max_reconnect_delay: backoff bounds.
       # Each failed reconnect doubles the delay (with +/-50% jitter) up to the
-      # max. A successful event delivery resets the delay to the initial
-      # value — matches sdk-python's policy. A clean server-initiated FIN is
-      # treated as "not a failure for backoff purposes" because LBs recycling
-      # connections is normal; the reconnect counter still increments.
+      # max. A connection that delivers its first valid frame (a config
+      # envelope or a keepalive) resets the delay to the initial value. A
+      # clean server-initiated FIN after such a frame is "not a failure for
+      # backoff purposes" because LBs recycling connections is normal; the
+      # reconnect counter still increments. A connection that ends before any
+      # frame is a failed attempt (qfg-goi1.10.43).
       def initialize(sse_read_timeout: 90,
                      sse_connect_timeout: 10,
                      sse_initial_reconnect_delay: 1.0,
@@ -76,13 +78,22 @@ module Quonfig
 
     # +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).
-    def initialize(prefab_options, config_loader, options = nil, logger = nil, on_error: nil)
+    # +connection_state+ reflects the disconnect (qfg-47c2.27). A connection
+    # that ends before its first valid frame, clean EOF included, is an error
+    # edge too (qfg-goi1.10.43).
+    #
+    # +on_connected+: optional callable invoked once per connection, at its
+    # first valid frame (a keepalive, or a data block that validates as a
+    # config envelope), before that frame's envelope reaches +on_envelope+.
+    # Never on the 200 headers alone (supervisor-test-contract.md "Rule — a
+    # connection is `connected` at its first valid frame").
+    def initialize(prefab_options, config_loader, options = nil, logger = nil, on_error: nil, on_connected: nil)
       @prefab_options = prefab_options
       @options = options || Options.new
       @config_loader = config_loader
       @logger = logger || LOG
       @on_error = on_error
+      @on_connected = on_connected
 
       @stopped = Concurrent::AtomicBoolean.new(false)
       @restart_total = 0
@@ -234,10 +245,18 @@ module Quonfig
             end
             first_attempt = false
 
-            connected_at_least_once = false
+            # First-frame rule (qfg-goi1.10.43): this connection counts as
+            # connected only at its first valid frame. Raised once, from the
+            # parser, before the frame's envelope is installed.
+            frame_seen = false
+            on_frame = lambda do
+              next if frame_seen
+
+              frame_seen = true
+              invoke_on_connected
+            end
             begin
-              stream_once do |event|
-                connected_at_least_once = true
+              ended_url = stream_once(on_frame) do |event|
                 # Persist the most recent id so the next reconnect resumes
                 # from there via Last-Event-Id. Updated *before* the user
                 # callback runs so a raising listener still advances the
@@ -248,22 +267,30 @@ module Quonfig
                 # listener must not look like a transport error and trigger
                 # a reconnect.
                 invoke_on_envelope_safely(on_envelope, event)
-                # A connection healthy enough to deliver a real envelope
-                # earns a reset of the backoff. Sustained outages never
-                # reach this branch (no event ever delivered) so the
-                # exponential growth still holds.
-                delay = @options.sse_initial_reconnect_delay
               end
+              # A clean EOF before any frame (200 headers then close) is a
+              # failed attempt, exactly like a connect error: report it so
+              # the client leaves :connected and arms the fallback poller.
+              # This is what bounds ruby's transparent reconnect: connected
+              # survives a clean-EOF reconnect only until the next connection
+              # ends frameless.
+              handle_frameless_end(ended_url) unless frame_seen || @stopped.value
             rescue StandardError => e
               handle_error(e) unless @stopped.value
             end
 
-            # Backoff only grows on failed connect attempts. A server-
-            # initiated clean FIN after a healthy session (normal LB
-            # recycling) reuses the same delay — punishing it would make
-            # us look broken under benign rolling restarts. Matches
-            # sdk-go's `connectedOK` distinction.
-            delay = [delay * 2, @options.sse_max_reconnect_delay].min unless connected_at_least_once
+            # The backoff resets only for a connection that delivered a
+            # frame; it then reconnects at the initial delay even after a
+            # clean FIN (normal LB recycling) or an IO error later in the
+            # session. Every other attempt (connect error, non-200, or a
+            # frameless 200) doubles it. Sustained outages never deliver a
+            # frame, so the exponential growth still holds. Matches sdk-go's
+            # connectOnce "frame seen" result.
+            delay = if frame_seen
+                      @options.sse_initial_reconnect_delay
+                    else
+                      [delay * 2, @options.sse_max_reconnect_delay].min
+                    end
           rescue SSEReadDeadlineExceeded => e
             # Paranoid backstop (qfg-tj18). A watchdog raise that landed
             # outside +stream_once+ — typically in +interruptible_sleep+
@@ -279,7 +306,8 @@ module Quonfig
 
     # Opens one SSE request and yields each parsed event until the stream
     # ends (clean FIN, error, or stop). Raises on transport errors so the
-    # caller can apply backoff. Clean FIN returns without raising.
+    # caller can apply backoff. Clean FIN returns the URL without raising.
+    # +on_frame+ is called at every valid frame (see EventParser#feed).
     #
     # A watchdog thread closes the socket if no bytes arrive within
     # +sse_read_timeout+. Net::HTTP#read_timeout is NOT reliable for the
@@ -288,7 +316,7 @@ module Quonfig
     # against a configured deadline). sdk-go and sdk-node hit the same
     # gotcha and solve it the same way: per-chunk reset, async close on
     # expiry (chaos scenario 02 — sse_silent_stall).
-    def stream_once(&block)
+    def stream_once(on_frame = nil, &block)
       base = current_url
       # f05 latch: record if this connection attempt targets a non-primary
       # stream leg. With the pin in #current_url this is structurally false;
@@ -333,9 +361,14 @@ module Quonfig
           Thread.handle_interrupt(SSEReadDeadlineExceeded => :immediate) do
             resp.read_body do |chunk|
               watchdog.reset!
-              break if @stopped.value
-
-              parser.feed(chunk, &block)
+              # Never +break+ here (qfg-yrly): a break returns into
+              # Net::HTTPResponse#reading_body, which then calls +body+ to
+              # drain the rest of the response with no block. On an endless
+              # SSE stream that blocks the worker forever. Raising skips the
+              # drain, and Net::HTTP closes the socket on the way out.
+              raise SSEStopRequested if @stopped.value
+
+              parser.feed(chunk, on_frame: on_frame, &block)
             end
           end
           # read_body returned cleanly — either a server-initiated FIN, or
@@ -344,6 +377,9 @@ module Quonfig
           # next iteration.
           @logger.debug "SSE stream ended for url #{url}"
         end
+        url
+      rescue SSEStopRequested
+        url
       ensure
         watchdog.stop
         register_active(nil)
@@ -394,6 +430,25 @@ module Quonfig
       @restart_mutex.synchronize { @restart_total += 1 }
     end
 
+    # A connection that returned 200 and ended cleanly before its first valid
+    # frame (qfg-goi1.10.43).
+    def handle_frameless_end(url)
+      err = SSEFramelessSessionError.new
+      @logger.warn "SSE Streaming Error: stream for url #{url} ended before its first frame; " \
+                   'treating it as a failed attempt'
+      invoke_on_error(err)
+    end
+
+    def invoke_on_connected
+      return unless @on_connected
+
+      begin
+        @on_connected.call
+      rescue StandardError => e
+        @logger.error "SSE on_connected callback raised: #{e.inspect}"
+      end
+    end
+
     def handle_error(error)
       if error.is_a?(SSEHTTPAuthError)
         # Already logged once by check_response_status! (R5).
@@ -478,11 +533,25 @@ module Quonfig
     # no longer stops on these statuses.
     SSEHTTPTerminalError = SSEHTTPAuthError # rubocop:disable Lint/UselessConstantScoping
 
+    # Passed to on_error when a 200 stream ends cleanly before its first valid
+    # frame (qfg-goi1.10.43). Not raised.
+    class SSEFramelessSessionError < StandardError
+      def initialize(msg = 'SSE stream ended before its first frame')
+        super
+      end
+    end
+
     # Raised by the watchdog into the worker thread when the per-chunk
     # read deadline elapses. Caught by run_loop's rescue, indistinguishable
     # from any other transport error for backoff/restart purposes.
     class SSEReadDeadlineExceeded < StandardError; 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.
+    class SSEStopRequested < StandardError; end
+    private_constant :SSEStopRequested
+
     # Background watchdog that interrupts the worker thread if no chunk
     # arrives within +deadline_s+ seconds. Uses Thread#raise — the only
     # reliable cross-platform way to unblock a Ruby thread blocked in
@@ -560,7 +629,7 @@ module Quonfig
     #   - chunks that split a line mid-way
     #   - any of CR / LF / CRLF as line terminators
     #   - +data:+, +data: + (optional space per SSE spec)
-    #   - +:comment+ lines (keepalives — ignored)
+    #   - +:comment+ lines (keepalives; a comment-only block is a frame)
     #   - multi-line +data:+ (concatenated with +\n+, per spec)
     # Ignores +event:+ and +retry:+ — api-delivery does not emit them and the
     # Quonfig wire contract does not honor reconnect-time directives.
@@ -573,16 +642,34 @@ module Quonfig
         @data = +''
         @have_data = false
         @id = nil
+        @saw_comment = false
+        @saw_field = false
       end
 
-      def feed(chunk)
+      # Yields each config envelope. +on_frame+ (optional) is called at every
+      # valid frame, before that frame's envelope is yielded. A valid frame is
+      # a block ended by a blank line that is either comment-only (the
+      # +: keepalive+ heartbeat; +:+ alone counts) or carries +data:+ that
+      # decodes and validates as a config envelope. A block cut off by EOF, a
+      # malformed or non-envelope data block, an +id:+-only block and a bare
+      # blank line are not frames (qfg-goi1.10.43).
+      def feed(chunk, on_frame: nil)
         @reader.feed(chunk) do |line|
           if line.empty?
+            comment_only = @saw_comment && !@saw_field
+            @saw_comment = false
+            @saw_field = false
             event = flush
-            yield event if event
+            if event
+              on_frame&.call
+              yield event
+            elsif comment_only
+              on_frame&.call
+            end
           elsif line.start_with?(':')
-            # comment / keepalive — ignore
+            @saw_comment = true
           else
+            @saw_field = true
             process_field(line)
           end
         end
@@ -637,10 +724,18 @@ module Quonfig
           return nil
         end
 
-        envelope = Quonfig::ConfigEnvelope.new(
-          configs: parsed['configs'] || [],
-          meta: parsed['meta'] || {}
-        )
+        meta = parsed['meta'] || {}
+        # Skip one malformed config, keep the rest (qfg-krjt); an event with
+        # no loadable config is dropped like malformed JSON.
+        begin
+          configs = Quonfig::ConfigShape.filter(parsed['configs'] || [], logger: @logger || LOG,
+                                                                         version: meta['version'])
+        rescue Quonfig::ConfigShape::AllInvalidError => e
+          (@logger || LOG).error "SSE Streaming Error: #{e.message}; event dropped"
+          return nil
+        end
+
+        envelope = Quonfig::ConfigEnvelope.new(configs: configs, meta: meta)
         StreamEvent.new(envelope, id, data)
       end
     end

data/lib/quonfig/version.rb

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

data/lib/quonfig/weighted_value_resolver.rb

@@ -43,7 +43,9 @@ module Quonfig
     private
 
     def weight_of(variant)
-      variant[:weight] || variant['weight']
+      # A missing weight counts as 0 (qfg-krjt); a present one is checked to
+      # be an Integer at decode (ConfigShape).
+      variant[:weight] || variant['weight'] || 0
     end
   end
 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'
@@ -50,6 +51,7 @@ require 'quonfig/config_store'
 require 'quonfig/evaluator'
 require 'quonfig/resolver'
 require 'quonfig/config_envelope'
+require 'quonfig/config_shape'
 require 'quonfig/config_loader'
 require 'quonfig/datadir'
 require 'listen'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: quonfig
 version: !ruby/object:Gem::Version
-  version: 1.8.0
+  version: 1.10.0
 platform: ruby
 authors:
 - Jeff Dwyer
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-16 00:00:00.000000000 Z
+date: 2026-10-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -90,6 +90,7 @@ files:
 - lib/quonfig/client.rb
 - lib/quonfig/config_envelope.rb
 - lib/quonfig/config_loader.rb
+- lib/quonfig/config_shape.rb
 - lib/quonfig/config_store.rb
 - lib/quonfig/context.rb
 - lib/quonfig/datadir.rb
@@ -100,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