quonfig 1.10.0 → 1.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 774d181106fd045eddb916eb177c89744a97f014d7168a4e89d4d51ca2b3d6e2
-  data.tar.gz: c34620585b746c0f013ec473870306593e45fd617b62187ebc31a3d44e14d709
+  metadata.gz: 6d1016bb1930249b2a74a4f670e25cb2143ff0e664edd54062c585437a85527a
+  data.tar.gz: 8e2e0844f5853cf5c1d27f45054e71dc6cda6f8f5aa398468c982a485659d1b8
 SHA512:
-  metadata.gz: 1e56307ab528445682d284fc48b651dd40224ba007f245e6abc4816bbb0b329e1d8fc0f5d6eff6f73137d375b8abbaf47488f074c803fe1d2944d197c3911910
-  data.tar.gz: 8dcfd007ada4cd44417a1b57928a90bf1e47a33e609b2cc14cb4484460911730f00d9e60cc0ef15fb150de61eab245d8e26e19e0c0f51e9ad0e50132afccbc03
+  metadata.gz: 705580a318dd7d773b6b0b01236f0509b6d60f440e44e21d07228de7ce6915d71c9ffe9c9c60a6a4c50ed95ed39018727bbb2ed89389610d4df8c9058b196f48
+  data.tar.gz: a9e69afa6be50db19b7508e9224203dda7c62ef522d1b591d2d7050ffdd69cbef217433791330fead5435c9ebe9fcbd364c245be5127ff9fbb1443e74be6a586

data/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 1.11.0 - 2026-10-23
+
+- **Changed (minor): SSE events and config bodies have size caps (qfg-6vno.20.5, cross-SDK rule qfg-6vno.8).** One SSE event (any single line, and the joined lines of a multi-line `data:`) is capped at 4 MiB (4,194,304 bytes), and a 200 body from `/api/v2/configs` at 16 MiB (16,777,216 bytes). Before, both were read with no limit (1.8.0 noted "there is still no size cap"), so a broken proxy or a stream with no newline could grow memory without bound.
+  - The SDK stops reading at the cap. It never reads the whole event or body and then measures it.
+  - An oversized SSE event is not a frame. The connection counts as a failed attempt: the reconnect delay grows, the client reports not connected, and the fallback poller keeps config fresh over HTTP. Until an envelope arrives on the stream, a later connection that only sends keepalives does not report connected.
+  - An oversized config body is a failed leg, handled like a 5xx. Nothing is installed, its ETag is not stored, and `last_successful_refresh` does not advance.
+  - A non-2xx response from `/api/v2/configs` has its body read to at most 1 KiB, then the SDK stops reading. Before, a large error body (a proxy error page, or a 401 carrying many MiB) was read up to the 16 MiB cap, and a 401/403/404/410 with a body over 16 MiB was logged as an oversized 200 and missed by auth-class detection. The status now comes first, so that response counts as the auth status it is. The bounded config fetch runs on Net::HTTP directly so it can see the status before it reads the body; the URL, headers, proxy and timeouts are the same as before.
+  - Each oversized episode logs one WARN that names the source and the cap in bytes. Repeats log at DEBUG. The caps are constants, not options. Contract: integration-test-data `v2026.10.22.2`, supervisor contract "Rule — size caps" and Test 10 cases 1-5, in `test/test_size_caps.rb`.
+- **Added (minor): `Client#callback_errors_total(callback: nil)` (qfg-6vno.6.1, supervisor contract Test 5).** It counts each call of your `on_update` block that raised a `StandardError` (`quonfig_sdk_callback_errors_total{callback="on_config_update"}`). Pass `callback: 'on_config_update'` or `'on_connection_state_change'` for one label; with no argument it returns the sum. sdk-ruby has no connection-state callback, so `on_connection_state_change` is always 0. An unknown name raises `ArgumentError`. A callback raise is still caught and does not count in `worker_restart_total`; `connection_state` and `last_successful_refresh` do not change. The ERROR line (`[quonfig] onConfigUpdate callback raised: ...`) now includes the first 10 lines of the stack trace. Tests: `test/test_supervisor_callback_throw.rb`, `test/test_on_update_callback_recovery.rb`.
+- **Fix (patch): `Client.new` no longer raises when `Dir.home` fails (qfg-7xlj).** With HOME unset and no passwd entry (some containers), `Dir.home` raises `ArgumentError`, which escaped client construction while dev context was enabled (the default). Dev context is now skipped instead, as in sdk-go. Test: `test/test_dev_context.rb`.
+- **Tests: all workflows run integration-test-data `v2026.10.22.2`.** It adds the regex v1 `enabled` cases (`test/integration/test_enabled.rb` regenerated), the size-caps rule and Test 10, and changes chaos scenario 10 exp[0] to `callback_errors_total`. The chaos probe answers `sdkMetric('quonfig_sdk_callback_errors_total', callback=...)` from the SDK counter, and the scenario 10 `CHAOS_KNOWN_SKIPS` entry is gone, so that row is evaluated instead of SKIPPED.
+- **Tests: the chaos harness reads every asserted value from the SDK, and both chaos suites run integration-test-data `v2026.10.21.1` (qfg-6vno.6, qfg-6vno.7).** The default-suite probe now reports `Client#connection_state` as-is (it used to invent `reconnecting`), the per-layer `worker_restart_total` counters and the SSE dial count straight from the SDK, and no longer counts a callback log line as a restart. A chaos step the rig cannot apply fails the scenario instead of printing a no-op. `scenarios-http-proxy/08` and the caught-`fail` init test are collected and reported SKIPPED with their reason, and scenario 00 (init-failure modes) runs. A new CI step (`scripts/check-itd-refs.sh`) fails when the workflows pin different integration-test-data refs. No SDK change.
+
 ## 1.10.0 - 2026-10-21
 
 - **Fix (patch): the init deadline reason follows sdk-go (qfg-9p4i.17.14, design decision 10).** A new init attempt now starts whenever time remains before `init_timeout_ms`, however little. Before, a retry was skipped with under 250ms left and the boot was decided on the previous attempt, so an attempt that fails fast followed by a delivery that blackholes until the deadline raised `reason: :unavailable` where sdk-go raises `InitializationTimeoutError` (`reason: :timeout`). An attempt still in flight at the deadline decides the reason (`:timeout` only if none of its legs answered); a deadline that lands in the backoff is decided by the last completed attempt (`:timeout` only if every leg timed out). Test: `test/test_init_failure.rb`.

data/README.md

@@ -708,6 +708,10 @@ reuse the parent's client object in a child process without it.
   polling). Returns `nil` before the first install. Preserved across `stop`.
 - `client.connection_state` — a `Symbol` describing the aggregate state:
   `:initializing`, `:connected`, `:disconnected`, or `:falling_back`.
+- `client.callback_errors_total(callback: 'on_config_update')` — how many
+  times your `on_update` block raised. The SDK catches the error, logs it at
+  ERROR with its stack, and keeps delivering updates; a raise is not a worker
+  restart.
 
 > Do not wire `last_successful_refresh` or `connection_state` directly into a Kubernetes liveness probe. These signals are diagnostic, not pass/fail. A liveness probe based on SDK freshness will amplify transient network blips into restart cascades.
 

data/lib/quonfig/client.rb

@@ -21,6 +21,12 @@ module Quonfig
   class Client
     LOG = Quonfig::InternalLogger.new(self)
 
+    # The +callback+ label values of quonfig_sdk_callback_errors_total
+    # (supervisor contract). sdk-ruby has no public connection-state callback,
+    # so +on_connection_state_change+ stays 0; it is listed so a reader of
+    # either name gets the contract's answer.
+    CALLBACK_NAMES = %w[on_config_update on_connection_state_change].freeze
+
     # Init fetch loop cadence (qfg-9p4i.10; init-failure design B.3, C).
     INIT_PROGRESS_EVERY_S = 5
     INIT_WAIT_PROGRESS_EVERY_S = 30
@@ -97,6 +103,9 @@ module Quonfig
       @sse_state = :idle
       @sse_ever_connected = false
       @fallback_engage_timer = nil
+      # quonfig_sdk_callback_errors_total{callback} (supervisor contract Test 5,
+      # qfg-6vno.6.1). Guarded by @state_mutex. See #callback_errors_total.
+      @callback_errors = CALLBACK_NAMES.to_h { |name| [name, 0] }
       # Auth-failed regime (rule R2-R4, qfg-goi1.10.26). Set by the poller's
       # fetch cycle on entry, cleared by the first accepted probe. While set:
       # no SSE, no polling, one probe per [150s, 300s]. Read by
@@ -561,6 +570,29 @@ module Quonfig
       end
     end
 
+    # quonfig_sdk_callback_errors_total counter (supervisor contract Test 5,
+    # qfg-6vno.6.1). Counts each call of your +on_update+ block that raised a
+    # StandardError the SDK caught and logged at ERROR. Such a raise is not a
+    # worker restart: #worker_restart_total does not change, the stream keeps
+    # running, and the next update still reaches your block.
+    #
+    # Pass +callback:+ ('on_config_update' or 'on_connection_state_change',
+    # String or Symbol) for one label; the default returns the sum. sdk-ruby
+    # has no connection-state callback, so 'on_connection_state_change' is
+    # always 0. An unknown name raises ArgumentError. Starts at 0 when the
+    # client is built.
+    def callback_errors_total(callback: nil)
+      @state_mutex.synchronize do
+        next @callback_errors.values.sum if callback.nil?
+
+        name = callback.to_s
+        raise ArgumentError, "unknown callback #{callback.inspect}; expected one of #{CALLBACK_NAMES.join(', ')}" unless
+          @callback_errors.key?(name)
+
+        @callback_errors[name]
+      end
+    end
+
     # Wall-clock time of the last installed envelope (any source: datadir,
     # initial HTTP fetch, SSE, or polling fallback). +nil+ before the first
     # install. Preserved after +stop+.
@@ -2007,7 +2039,10 @@ module Quonfig
       begin
         cb.call
       rescue StandardError => e
-        LOG.error "[quonfig] onConfigUpdate callback raised: #{e.class}: #{e.message}"
+        # Counted, not a worker restart (supervisor contract Test 5).
+        @state_mutex.synchronize { @callback_errors['on_config_update'] += 1 }
+        bt = (e.backtrace || []).first(10).join("\n  ")
+        LOG.error "[quonfig] onConfigUpdate callback raised: #{e.class}: #{e.message}\n  #{bt}"
       end
     end
 

data/lib/quonfig/config_loader.rb

@@ -19,6 +19,13 @@ 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).
@@ -186,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
@@ -468,7 +478,8 @@ module Quonfig
       # 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).
@@ -488,6 +499,7 @@ 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
@@ -505,6 +517,12 @@ module Quonfig
                       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
@@ -545,6 +563,18 @@ module Quonfig
       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

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/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

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.10.0'
+  VERSION = '1.11.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: quonfig
 version: !ruby/object:Gem::Version
-  version: 1.10.0
+  version: 1.11.0
 platform: ruby
 authors:
 - Jeff Dwyer
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-21 00:00:00.000000000 Z
+date: 2026-10-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport