quonfig 1.10.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 774d181106fd045eddb916eb177c89744a97f014d7168a4e89d4d51ca2b3d6e2
-  data.tar.gz: c34620585b746c0f013ec473870306593e45fd617b62187ebc31a3d44e14d709
+  metadata.gz: c7947aba694daddefb1357930d7d1b3e63d13c3f68ad71b1e5d33eff15584aa6
+  data.tar.gz: db349b68906829c24953f9504511200f7b837c8980ad9beb53a755586420f470
 SHA512:
-  metadata.gz: 1e56307ab528445682d284fc48b651dd40224ba007f245e6abc4816bbb0b329e1d8fc0f5d6eff6f73137d375b8abbaf47488f074c803fe1d2944d197c3911910
-  data.tar.gz: 8dcfd007ada4cd44417a1b57928a90bf1e47a33e609b2cc14cb4484460911730f00d9e60cc0ef15fb150de61eab245d8e26e19e0c0f51e9ad0e50132afccbc03
+  metadata.gz: 687f621eeff45b850bba0ab6845963abbdb8478ac18e32e1006d9f02de3b8a3ed850b75bf37ae2e907dd9512756f98fc79ae942221aaa7c17a0abd683bb9b920
+  data.tar.gz: 96792d273e01d2748f78435a75c3d8b4be405ff65470f465b646595539cf786ab4c204cab167350e66b42be03907739e49aaa01ad5b8a2228ebd7736fd4bb8e8

data/CHANGELOG.md

@@ -1,5 +1,113 @@
 # Changelog
 
+## 2.0.0 - 2026-10-26
+
+The typed-getter contract (qfg-zvyy), shared by every Quonfig SDK and pinned by
+the integration-test-data matrix (`getter.contract.*`, tag `v2026.10.26`). A
+typed read that cannot return a value of the getter's type no longer raises
+past your `default:`; your default applies.
+
+### UPGRADE to 2.0
+
+1. **A failed read returns your `default:`.** In 1.x the typed getters raised
+   even when you passed a `default:`: `get_int('k', default: 0)` on a string
+   config raised `TypeMismatchError`, and any getter on an unset ENV_VAR or a
+   secret that cannot be decrypted raised `MissingEnvVarError` /
+   `DecryptionError`. In 2.0 the getter returns the default. This covers a
+   value of another type, a malformed stored or ENV_VAR value, an unset ENV_VAR
+   and a decryption failure. The untyped `get(key, default)` does the same for
+   the failures it can see. Code that rescued these errors around a getter
+   with a `default:` now gets the default instead.
+
+2. **No default: `on_no_default` decides.** `:raise` (the default) still raises
+   the error (`TypeMismatchError`, `EnvVarParseError`, `MissingEnvVarError`,
+   `DecryptionError`), as in 1.x. Under `on_no_default: :return_nil` the getter
+   now returns `nil` instead of raising.
+
+3. **No string coercion.** A stored string is never a bool or a number:
+   `get_bool` on a string `"false"` is a type mismatch, and `enabled?` on a
+   string `"true"` is `false` (1.x returned `true`). Store values with the
+   config type you read them with.
+
+4. **Numbers convert only when exact.** `get_float` on an int config now
+   returns the value (`30` -> `30.0`); 1.x raised `TypeMismatchError`.
+   `get_int` on a double config returns the value when it is whole and within
+   +/-(2^53-1) (`3.0` -> `3`); `3.9`, `1e300` and `2^53` are type mismatches,
+   never truncated.
+
+5. **Stricter types.** `get_json` reads json configs only, `get_string_list`
+   string_list configs only, and `get_string` string and log_level configs
+   only. In 1.x `get_json` returned any value and `get_string_list` accepted
+   any array of strings.
+
+6. **`enabled?` never raises.** It returns `false` for a missing key, a flag
+   with no matching rule, a value that is not the bool `true`, and any
+   resolution error (1.x raised `MissingEnvVarError` / `DecryptionError` and
+   errors from a malformed value).
+
+7. **One WARN per key.** A failed read that returns your default or `nil`, and
+   `enabled?` returning `false` for one of the reasons above, log one WARN per
+   key per client: `[quonfig] read of "<key>" returned no value: <reason>`. It
+   names the key and the types, never the value. A wrong decryption key in
+   production now degrades to your defaults with these WARNs. **If that must be
+   fatal**, read without a `default:` on a client with `on_no_default: :raise`
+   (the default), or use `get_or_raise`, which raises `MissingEnvVarError`,
+   `EnvVarParseError` and `DecryptionError` even when you pass a `default:`.
+
+### Changed
+
+- **Major: typed getters (`get_string`, `get_int`, `get_float`, `get_bool`,
+  `get_string_list`, `get_duration`, `get_json`, and the same on
+  `BoundClient`) follow the contract above.** The 1.x identity bypass is gone:
+  a value that happened to be `equal?` to the default skipped the type check,
+  so `get_string('a_bool', default: true)` returned `true` with no error.
+- **Major: `enabled?` is true only for the bool `true`.**
+- **Major: `get(key, default)` returns the default on an unset ENV_VAR, a
+  decryption failure or a malformed value.** A malformed stored duration read
+  with no default now follows `on_no_default` (1.x returned `nil`).
+- **`*_details`: a malformed value, stored or ENV_VAR, is `TYPE_MISMATCH`** (it
+  was `GENERAL` for an ENV_VAR value), as in sdk-go. `get_int_details` /
+  `get_float_details` follow the int <-> double rule.
+- **`get_or_raise` raises `EnvVarParseError` on a malformed stored int or
+  double** (1.x raised a bare `ArgumentError`).
+- **A `decryptWith` key config that is missing, matches no rule or is empty now raises `DecryptionError`** (1.x raised a plain `Quonfig::Error`), so it counts as a decryption failure and the typed getters apply your default. `DecryptionError` is a `Quonfig::Error`, so `rescue Quonfig::Error` still catches it.
+- **`TypeMismatchError` names the config's value type** (`... expected Integer,
+  got a string value`) when the type is known.
+
+### Tests
+
+- All workflows run integration-test-data `v2026.10.26`, which adds the
+  typed-getter matrix to `get.yaml`, `get_or_raise.yaml` and `enabled.yaml`.
+  The typed `get_or_raise` cases call the typed getter on a client with
+  `on_no_default: :raise` (Ruby's untyped `get_or_raise` cannot tell a
+  wrong-type value from a found one); that generator change is
+  quonfig/integration-test-data `ruby.ts`, see the PR for this release.
+- `test/test_typed_getter_contract.rb` covers what the corpus cannot: the
+  once-per-key WARN, `enabled?` never raising, int <-> double edges (NaN,
+  infinity, 2^53), the Details error codes, and the untyped `get` /
+  `get_or_raise`.
+
+### Fixed
+
+- **A config payload refused as older no longer pins its ETag (qfg-j7ui).** When a `/api/v2/configs` 200 is dropped by the reject-older guard because its generation is lower than the one held, the SDK no longer remembers its ETag. Before, if the server later repaired that same commit to a higher generation, every poll got a 304 and the client stayed on the old config until the next commit. The same already held for a generation-0 payload (qfg-9dxb.9). A same-generation re-delivery still keeps its ETag. Pinned by supervisor contract Test 11 (integration-test-data `v2026.10.27.1`).
+
+### Docs
+
+- **README note on forking servers during a delivery outage (qfg-6vno.24).** Under Startup failure: a forked worker rebuilds its own snapshot under the same `on_init_failure` mode, `:fail` raises until delivery heals, `:wait` blocks the first request, and frequent recyclers should use `:continue`. Links to the startup-failure docs page. No code change.
+
+## 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

@@ -298,6 +298,24 @@ timeout runs out (false). Under `:wait`, point your readiness probe at
 `ready?`. `:raise` and `:return` are the deprecated spellings of `:fail` and
 `:continue`; they still work and log a one-time WARN.
 
+### Forking servers (Puma, Sidekiq)
+
+A forked worker (Puma cluster or phased restart, Unicorn, Sidekiq, Resque)
+never serves the parent's config: it rebuilds its own snapshot on first use and
+applies the same `on_init_failure` mode as a fresh boot (see
+[Rails integration](#rails-integration)). If delivery is unreachable when a
+worker is recycled:
+
+- `:fail` (default): the worker's first lookup raises
+  `Quonfig::Errors::InitializationError`, and later lookups keep raising until
+  delivery heals.
+- `:wait`: the worker's first request blocks until delivery is back.
+- `:continue`: the worker serves code defaults until it heals. Apps that
+  recycle workers often (frequent phased restarts, a fork per job) should use
+  this and keep their defaults safe.
+
+Details: [Startup failure: forked workers](https://docs.quonfig.com/docs/explanations/architecture/startup-failure#forked-workers-and-worker-recycling).
+
 ## Constructor options
 
 ```ruby
@@ -391,12 +409,40 @@ Each typed getter takes a config key plus two optional keyword arguments:
 for this call). On a `BoundClient` (see `with_context` above) the getters take
 only `default:`; the context is the bound one.
 
+Upgrading from 1.x? See [UPGRADE to 2.0](CHANGELOG.md#upgrade-to-20).
+
 - **Missing key:** returns `default:` when you pass one. Without a default the
   `on_no_default` option decides: `:raise` (the default) raises
   `Quonfig::Errors::MissingDefaultError`, `:return_nil` returns `nil`.
-- **Wrong type:** a value that does not match the getter's type (for example
-  `get_int` on a string config) raises `Quonfig::Errors::TypeMismatchError`,
-  with or without a `default:`.
+- **Failed read:** a read that cannot produce a value of the getter's type
+  returns `default:` when you pass one and logs one WARN per key (it names the
+  key, never the value). Without a default it follows `on_no_default`:
+  `:return_nil` returns `nil` (and logs the WARN), `:raise` raises the error:
+
+| Situation | Error raised with no default under `:raise` |
+|---|---|
+| Value of another type (e.g. `get_bool` on a string config) | `Quonfig::Errors::TypeMismatchError` |
+| Malformed stored or ENV_VAR value (an int `"twelve"`, a duration `"30s"`) | `Quonfig::Errors::EnvVarParseError` |
+| ENV_VAR not set | `Quonfig::Errors::MissingEnvVarError` |
+| Secret cannot be decrypted | `Quonfig::Errors::DecryptionError` |
+
+Strings are never coerced: a stored `"false"` is a string, so `get_bool`
+treats it as a type mismatch instead of returning `false`. The only conversions
+are between numbers, and only when exact: `get_float` reads an int config
+(`30` -> `30.0`), and `get_int` reads a double config holding a whole number
+within +/-(2^53-1) (`3.0` -> `3`; `3.9` is a type mismatch, never truncated).
+The untyped `get(key, default)` follows the same rule for the failures it can
+see (malformed values, ENV_VAR and decryption errors).
+
+`enabled?` never raises. It returns `true` only for a flag that resolves to the
+bool `true`, and `false` (with one WARN per key) for a missing key, a flag with
+no matching rule, a value that is not a bool (a stored string `"true"`
+included) or any resolution error.
+
+A wrong decryption key or an unset ENV_VAR therefore degrades to your defaults
+with one WARN per key. If a broken config must stop your service, call the
+getter without a `default:` on a client with `on_no_default: :raise` (the
+default), or use `get_or_raise`.
 
 | Method                                              | Returns                                   |
 |-----------------------------------------------------|-------------------------------------------|
@@ -407,11 +453,10 @@ only `default:`; the context is the bound one.
 | `get_string_list(key, default:, context:)`          | `Array<String>`                           |
 | `get_duration(key, default:, context:)`             | `Integer` (milliseconds)                  |
 | `get_json(key, default:, context:)`                 | `Hash`, `Array`, or a scalar              |
-| `enabled?(feature_name, context = nil)`             | `true` or `false` (`false` when missing)  |
+| `enabled?(feature_name, context = nil)`             | `true` or `false`; never raises           |
 
 `get_duration` returns integer milliseconds (`PT1.5S` is `1500`). A duration
-value that is not valid ISO-8601 returns `default:` and logs one warning per
-key; with no default it follows `on_no_default`.
+value that is not valid ISO-8601 is a malformed value (see above).
 
 Example:
 
@@ -426,13 +471,18 @@ client.get_json('homepage.layout', default: {})
 client.enabled?('beta-feature', user: { key: 'user-123' })
 ```
 
-`get_or_raise(key, default:, context:)` returns the value like `get`, but a
-missing key without a `default:` always raises
-`Quonfig::Errors::MissingDefaultError` (whatever `on_no_default` is set to), and
-an unset or malformed ENV_VAR value, a malformed stored duration, or a
-decryption failure raises its error. `get_duration_details(key, context:)`
-returns `Quonfig::EvaluationDetails` with the duration in integer milliseconds,
-like the other `*_details` getters.
+`get_or_raise(key, default:, context:)` returns the value like `get` (untyped),
+but a missing key without a `default:` always raises
+`Quonfig::Errors::MissingDefaultError` (whatever `on_no_default` is set to),
+and an unset or malformed ENV_VAR value, a malformed stored value, or a
+decryption failure raises its error even when you pass a `default:` (the
+default only covers a missing key). For a typed read that raises, call the
+typed getter with no `default:` under `on_no_default: :raise`.
+
+The `*_details` getters (`get_int_details(key, context:)` and so on) never
+raise. They return `Quonfig::EvaluationDetails`; a wrong-type or malformed
+value is `reason: "ERROR"` with `error_code: "TYPE_MISMATCH"`.
+`get_duration_details` carries the duration in integer milliseconds.
 
 ## Dynamic log levels (SemanticLogger)
 
@@ -708,6 +758,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,48 @@ module Quonfig
   class Client
     LOG = Quonfig::InternalLogger.new(self)
 
+    # Errors that make a read of a present key fail (qfg-zvyy). Each one is
+    # handled by #failed_read: the caller's default, nil, or the error.
+    READ_FAILURES = [
+      Quonfig::Errors::TypeMismatchError,
+      Quonfig::Errors::EnvVarParseError,
+      Quonfig::Errors::MissingEnvVarError,
+      Quonfig::Errors::DecryptionError
+    ].freeze
+
+    # Largest integer a double holds exactly: +/-(2^53-1), the bound the
+    # cross-SDK contract (and cli verify) uses for a double -> int read.
+    MAX_SAFE_INTEGER = (2**53) - 1
+
+    # Declared value type each typed getter reads. The only conversions are
+    # between numbers, and only when exact (see #typed_number).
+    ACCEPTED_TYPES = {
+      String => %w[string log_level],
+      Integer => %w[int double],
+      Float => %w[double int],
+      bool: %w[bool],
+      string_list: %w[string_list],
+      json: %w[json],
+      duration: %w[duration]
+    }.freeze
+
+    TYPE_NAMES = {
+      String => 'String',
+      Integer => 'Integer',
+      Float => 'Float',
+      bool: 'Boolean',
+      string_list: 'Array<String>',
+      json: 'JSON',
+      duration: 'ISO-8601 Duration'
+    }.freeze
+    private_constant :READ_FAILURES, :MAX_SAFE_INTEGER, :ACCEPTED_TYPES, :TYPE_NAMES
+
+    # 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
@@ -75,9 +117,12 @@ module Quonfig
       @evaluator = Quonfig::Evaluator.new(@store, env_id: @options.environment)
       @resolver = Quonfig::Resolver.new(@store, @evaluator)
       @semantic_logger_filters = {}
-      # Keys already warned about for a malformed duration value (qfg-2agi.10).
-      @malformed_duration_warned = Set.new
-      @malformed_duration_mutex = Mutex.new
+      # Keys already warned about for a failed read: a wrong-type value, a
+      # malformed value, an unset ENV_VAR or a decryption failure, plus
+      # enabled? returning false for a missing key (qfg-2agi.10, qfg-zvyy).
+      # One WARN per key per client.
+      @read_failure_warned = Set.new
+      @read_failure_mutex = Mutex.new
       @sse_client = nil
       @poll_supervisor = nil
       @stopped = false
@@ -97,6 +142,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
@@ -142,23 +190,27 @@ module Quonfig
 
     # ---- Lookup --------------------------------------------------------
 
+    # The config's value, untyped.
+    #
+    # A missing key returns +default+, or applies +on_no_default+ (nil under
+    # :return_nil, MissingDefaultError under :raise). A read that fails (an
+    # unset ENV_VAR, a decryption failure, a malformed stored or ENV_VAR
+    # value) follows the typed-getter contract (qfg-zvyy): +default+ when one
+    # is given, otherwise nil under :return_nil or the error itself under
+    # :raise, and one WARN per key either way.
     def get(key, default = NO_DEFAULT_PROVIDED, jit_context = NO_DEFAULT_PROVIDED)
       ensure_initialized_after_fork
       ctx = build_context(jit_context)
       record_context_for_telemetry(ctx)
-      result =
-        begin
-          @resolver.get(key, ctx)
-        rescue Quonfig::Errors::MissingDefaultError
-          # The Resolver raises (matching Quonfig.get_or_raise semantics).
-          # The Client's get applies the caller-provided default *or* the
-          # configured on_no_default policy via handle_missing.
-          nil
-        end
-      return handle_missing(key, default) if result.nil?
+      begin
+        result = resolve_for_read(key, ctx)
+        return handle_missing(key, default) if result.nil?
 
-      record_evaluation_for_telemetry(result)
-      result.unwrapped_value
+        record_evaluation_for_telemetry(result)
+        unwrap_for_read(result)
+      rescue *READ_FAILURES => e
+        failed_read(key, default, e)
+      end
     end
 
     def get_string(key, default: NO_DEFAULT_PROVIDED, context: NO_DEFAULT_PROVIDED)
@@ -181,31 +233,13 @@ module Quonfig
       typed_get(key, :string_list, default: default, context: context)
     end
 
-    # Integer milliseconds for a duration config (qfg-2agi.10).
-    #
-    # - A config whose valueType is not duration raises TypeMismatchError,
-    #   like get_int on a string config.
-    # - Values follow the shared grammar (Quonfig::Duration); ms are rounded
-    #   half up on both the stored and the ENV_VAR path.
-    # - A malformed value (stored or ENV_VAR) returns +default+ and logs one
-    #   warning per key. With no default it returns nil under
-    #   on_no_default: :return_nil and raises EnvVarParseError under :raise.
+    # Integer milliseconds for a duration config (qfg-2agi.10). Values follow
+    # the shared grammar (Quonfig::Duration); ms are rounded half up on both
+    # the stored and the ENV_VAR path. A config whose valueType is not
+    # duration, or a malformed duration, is a failed read under the
+    # typed-getter contract (see #typed_get).
     def get_duration(key, default: NO_DEFAULT_PROVIDED, context: NO_DEFAULT_PROVIDED)
-      ensure_initialized_after_fork
-      ctx = build_context(context)
-      record_context_for_telemetry(ctx)
-      result =
-        begin
-          @resolver.get(key, ctx)
-        rescue Quonfig::Errors::MissingDefaultError
-          nil
-        rescue Quonfig::Errors::EnvVarParseError => e
-          return malformed_duration(key, default, e)
-        end
-      return handle_missing(key, default) if result.nil?
-
-      record_evaluation_for_telemetry(result)
-      duration_millis(key, result, default)
+      typed_get(key, :duration, default: default, context: context)
     end
 
     def get_json(key, default: NO_DEFAULT_PROVIDED, context: NO_DEFAULT_PROVIDED)
@@ -239,10 +273,7 @@ module Quonfig
       end
 
       record_evaluation_for_telemetry(result)
-      value = result.unwrapped_value
-      raise malformed_stored_duration_error(result) if malformed_stored_duration?(result, value)
-
-      value
+      unwrap_for_read(result)
     end
 
     # ---- Details getters ----------------------------------------------
@@ -284,9 +315,27 @@ module Quonfig
       evaluate_details(key, :duration, context)
     end
 
+    # True only when the flag resolves to the bool +true+. Never raises
+    # (qfg-zvyy): a missing key, a flag with no matching rule, a value that is
+    # not a bool (a stored string "true" included) or any resolution error
+    # returns false and logs one WARN per key.
     def enabled?(feature_name, jit_context = NO_DEFAULT_PROVIDED)
-      value = get(feature_name, false, jit_context)
-      [true, 'true'].include?(value)
+      ensure_initialized_after_fork
+      begin
+        ctx = build_context(jit_context)
+        record_context_for_telemetry(ctx)
+        result = resolve_for_read(feature_name, ctx)
+        if result.nil?
+          warn_read_failure(feature_name, 'missing key or no matching rule; enabled? returns false')
+          return false
+        end
+
+        record_evaluation_for_telemetry(result)
+        typed_value(feature_name, result, :bool) == true
+      rescue StandardError => e
+        warn_read_failure(feature_name, "#{e.message}; enabled? returns false")
+        false
+      end
     end
 
     def defined?(key)
@@ -561,6 +610,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+.
@@ -1825,19 +1897,25 @@ module Quonfig
         # last_successful_refresh (only an install or fetch does that).
         on_connected: sse_connected_callback
       )
+      # The block returns the install result (:updated / :not_modified); the
+      # SSE client clears its oversized gate only on :updated (qfg-6vno.20.8).
+      # The connected edge comes from on_connected at the first frame (or,
+      # while the oversized gate is set, at the first installed envelope), so
+      # an envelope the reject-older guard drops never reports connected here.
       @sse_client.start do |envelope, _event, _source|
         next if @stopped
 
         begin
-          @config_loader.apply_envelope(envelope)
+          result = @config_loader.apply_envelope(envelope)
           sync_evaluator_env_id!
-          handle_sse_state_change(:connected)
+          handle_sse_state_change(:connected) if result == :updated
           record_refresh!
         rescue StandardError => e
           LOG.warn "[quonfig] Error applying SSE envelope: #{e.message}"
           next
         end
         notify_on_update_callback
+        result
       end
       true
     rescue StandardError => e
@@ -2007,7 +2085,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
 
@@ -2125,6 +2206,17 @@ module Quonfig
             variant: build_variant(Quonfig::EvaluationDetails::REASON_ERROR, nil, nil),
             flag_metadata: build_flag_metadata(nil, nil, nil, nil, nil)
           )
+        rescue Quonfig::Errors::EnvVarParseError => e
+          # An ENV_VAR value that does not parse as the config's type is
+          # TYPE_MISMATCH, like a malformed stored value (as in sdk-go).
+          return Quonfig::EvaluationDetails.new(
+            value: nil,
+            reason: Quonfig::EvaluationDetails::REASON_ERROR,
+            error_code: Quonfig::EvaluationDetails::ERROR_TYPE_MISMATCH,
+            error_message: e.message,
+            variant: build_variant(Quonfig::EvaluationDetails::REASON_ERROR, nil, nil),
+            flag_metadata: build_flag_metadata(nil, nil, nil, nil, nil)
+          )
         end
 
       if result.nil?
@@ -2140,15 +2232,12 @@ module Quonfig
 
       config_id = result.config&.dig('id') || result.config&.dig(:id)
       config_type = result.config&.dig('type') || result.config&.dig(:type)
-      raw_value = result.unwrapped_value
 
       begin
-        if expected_type == :duration
-          raise Quonfig::Errors::TypeMismatchError.new(key, 'ISO-8601 Duration', raw_value) unless duration_result?(result)
-          raise malformed_stored_duration_error(result) if malformed_stored_duration?(result, raw_value)
-        end
-        coerced = coerce_and_check(key, raw_value, expected_type) unless raw_value.nil?
-      rescue Quonfig::Errors::TypeMismatchError => e
+        coerced = typed_value(key, result, expected_type)
+      rescue Quonfig::Errors::TypeMismatchError, Quonfig::Errors::EnvVarParseError => e
+        # A wrong-type value and a malformed one (the getter cannot produce
+        # a value of its type) are both TYPE_MISMATCH, as in sdk-go.
         return Quonfig::EvaluationDetails.new(
           value: nil,
           reason: Quonfig::EvaluationDetails::REASON_ERROR,
@@ -2213,32 +2302,122 @@ module Quonfig
       md
     end
 
+    # A typed read under the typed-getter contract (qfg-zvyy, shared with
+    # every Quonfig SDK and pinned by integration-test-data getter.contract.*).
+    #
+    # A missing key returns +default+ or applies +on_no_default+. A read that
+    # fails (a value of another type, a malformed stored or ENV_VAR value, an
+    # unset ENV_VAR, a decryption failure) returns +default+ when one is
+    # given; with no default it returns nil under on_no_default: :return_nil
+    # and raises the error (TypeMismatchError, EnvVarParseError,
+    # MissingEnvVarError, DecryptionError) under :raise. Either way it logs
+    # one WARN per key per client.
     def typed_get(key, expected_type, default:, context:)
-      jit = context == NO_DEFAULT_PROVIDED ? NO_DEFAULT_PROVIDED : context
-      value = get(key, default, jit)
+      ensure_initialized_after_fork
+      ctx = build_context(context)
+      record_context_for_telemetry(ctx)
+      begin
+        result = resolve_for_read(key, ctx)
+        return handle_missing(key, default) if result.nil?
+
+        record_evaluation_for_telemetry(result)
+        typed_value(key, result, expected_type)
+      rescue *READ_FAILURES => e
+        failed_read(key, default, e)
+      end
+    end
+
+    # The resolved Evaluation for +key+, or nil when the key is missing or no
+    # rule matched. Resolution errors (MissingEnvVarError, EnvVarParseError,
+    # DecryptionError) propagate.
+    def resolve_for_read(key, ctx)
+      @resolver.get(key, ctx)
+    rescue Quonfig::Errors::MissingDefaultError
+      nil
+    end
+
+    # +result+'s value with no type check. A stored value that does not parse
+    # as its declared type (an int "twelve", a duration "30s") raises
+    # EnvVarParseError, as a malformed ENV_VAR value does.
+    def unwrap_for_read(result)
+      value =
+        begin
+          result.unwrapped_value
+        rescue ArgumentError, TypeError, FloatDomainError
+          raise malformed_stored_value_error(result)
+        end
+      raise malformed_stored_value_error(result) if malformed_stored_duration?(result, value)
+
+      value
+    end
+
+    # +result+'s value as +expected_type+, or raise TypeMismatchError (a value
+    # of another type) / EnvVarParseError (a malformed value). Strings are
+    # never coerced: a stored "false" is not a bool and "3" is not an int.
+    def typed_value(key, result, expected_type)
+      stored = stored_value_type(result)
+      accepted = ACCEPTED_TYPES.fetch(expected_type)
+      raise Quonfig::Errors::TypeMismatchError.new(key, TYPE_NAMES.fetch(expected_type), nil, actual_type: stored) unless stored.nil? || accepted.include?(stored)
 
-      # Missing path: resolver returned the caller's default (or nil under
-      # on_no_default=:return_nil) — skip type coercion.
-      return value if default != NO_DEFAULT_PROVIDED && value.equal?(default)
+      value = unwrap_for_read(result)
       return nil if value.nil?
 
-      coerce_and_check(key, value, expected_type)
+      if [Integer, Float].include?(expected_type)
+        typed_number(key, result, value, expected_type)
+      elsif expected_type == :bool
+        typed_bool(key, result)
+      else
+        check_class(key, value, expected_type)
+      end
     end
 
-    def duration_millis(key, result, default)
-      raise Quonfig::Errors::TypeMismatchError.new(key, 'ISO-8601 Duration', result.unwrapped_value) unless duration_result?(result)
+    # The Value's declared type ('int', 'string', ...); a resolved ENV_VAR or
+    # decrypted value carries the type it was coerced to. Nil when unknown.
+    def stored_value_type(result)
+      type = result.type
+      if type.nil? || type == 'provided'
+        config = result.config || {}
+        type = config['valueType'] || config[:valueType] || config['value_type'] || config[:value_type]
+      end
+      type&.to_s
+    end
 
-      value = result.unwrapped_value
-      millis = value.is_a?(Integer) ? value : Quonfig::Duration.parse_millis(value)
-      return millis unless millis.nil?
+    # Double getter: any int or double (30 -> 30.0). Int getter: an int, or a
+    # double that is whole and within +/-(2^53-1) (3.0 -> 3). Never truncates:
+    # 3.9, 1e300 and NaN are type mismatches.
+    def typed_number(key, result, value, expected_type)
+      # A stored int whose raw value is a Float would unwrap truncated.
+      raw = result.raw_value
+      number = raw.is_a?(Numeric) ? raw : value
+      mismatch = -> { Quonfig::Errors::TypeMismatchError.new(key, TYPE_NAMES.fetch(expected_type), number) }
+      raise mismatch.call unless number.is_a?(Integer) || number.is_a?(Float)
 
-      malformed_duration(key, default, malformed_stored_duration_error(result))
+      return number.to_f if expected_type == Float
+      return number if number.is_a?(Integer)
+      raise mismatch.call unless number.finite? && number == number.floor && number.abs <= MAX_SAFE_INTEGER
+
+      number.to_i
     end
 
-    def duration_result?(result)
-      config = result.config || {}
-      value_type = config['valueType'] || config[:valueType] || config['value_type'] || config[:value_type]
-      value_type == 'duration' || result.type == 'duration'
+    # A bool Value unwraps with !!raw, so check the raw value: only a real
+    # true/false is a bool.
+    def typed_bool(key, result)
+      raw = result.raw_value
+      raise Quonfig::Errors::TypeMismatchError.new(key, 'Boolean', raw) unless [true, false].include?(raw)
+
+      raw
+    end
+
+    def check_class(key, value, expected_type)
+      ok =
+        if expected_type == String then value.is_a?(String)
+        elsif expected_type == :string_list then value.is_a?(Array) && value.all?(String)
+        elsif expected_type == :duration then value.is_a?(Integer)
+        else true # :json: any JSON value
+        end
+      raise Quonfig::Errors::TypeMismatchError.new(key, TYPE_NAMES.fetch(expected_type), value) unless ok
+
+      value
     end
 
     # A stored duration string outside the shared grammar unwraps to nil.
@@ -2246,49 +2425,27 @@ module Quonfig
       unwrapped.nil? && result.type == 'duration' && !result.raw_value.nil?
     end
 
-    def malformed_stored_duration_error(result)
+    def malformed_stored_value_error(result)
       Quonfig::Errors::EnvVarParseError.new(result.raw_value, result.config || {}, nil, stored: true)
     end
 
-    def malformed_duration(key, default, error)
-      if @malformed_duration_mutex.synchronize { @malformed_duration_warned.add?(key.to_s) }
-        LOG.warn "[quonfig] #{key} is not a valid ISO-8601 duration; " \
-                 "#{default == NO_DEFAULT_PROVIDED ? 'no default given' : 'returning the default'}"
-      end
-      return default unless default == NO_DEFAULT_PROVIDED
-      raise error if @options.on_no_default == Quonfig::Options::ON_NO_DEFAULT::RAISE
+    # The failed-read rule (qfg-zvyy): +default+ when one is given, else nil
+    # under on_no_default: :return_nil, each with one WARN per key; else
+    # +error+ under :raise (the raise is the signal, so it is not logged).
+    def failed_read(key, default, error)
+      no_default = default == NO_DEFAULT_PROVIDED
+      raise error if no_default && @options.on_no_default == Quonfig::Options::ON_NO_DEFAULT::RAISE
 
-      nil
+      warn_read_failure(key, "#{error.message}; #{no_default ? 'returning nil' : 'returning the default'}")
+      no_default ? nil : default
     end
 
-    def coerce_and_check(key, value, expected_type)
-      case expected_type
-      when :bool
-        raise Quonfig::Errors::TypeMismatchError.new(key, 'Boolean', value) unless [true, false].include?(value)
-
-        value
-      when :string_list
-        arr = value.is_a?(Array) ? value : nil
-        raise Quonfig::Errors::TypeMismatchError.new(key, 'Array<String>', value) unless arr&.all?(String)
+    # Logs once per config key per client. The reason names the key and the
+    # types involved, never the value (it can be a decrypted secret).
+    def warn_read_failure(key, reason)
+      return unless @read_failure_mutex.synchronize { @read_failure_warned.add?(key.to_s) }
 
-        arr
-      when :duration
-        return value if value.is_a?(Integer)
-
-        millis = Quonfig::Duration.parse_millis(value)
-        raise Quonfig::Errors::TypeMismatchError.new(key, 'ISO-8601 Duration', value) if millis.nil?
-
-        millis
-      when :json
-        # JSON values are returned as-is (Hash, Array, or scalar from the wire).
-        value
-      when Class
-        raise Quonfig::Errors::TypeMismatchError.new(key, expected_type.to_s, value) unless value.is_a?(expected_type)
-
-        value
-      else
-        value
-      end
+      LOG.warn "[quonfig] read of #{key.to_s.inspect} returned no value: #{reason}"
     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
@@ -290,7 +300,8 @@ module Quonfig
     # 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
     # guarded by the same reject-older rule (a late SSE snapshot must not regress
-    # an established client).
+    # an established client). Returns :updated when the envelope installed and
+    # :not_modified when the guard dropped it.
     def apply_envelope(envelope)
       install_envelope(envelope, source: :sse, source_index: nil)
     end
@@ -468,7 +479,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).
@@ -483,11 +495,13 @@ module Quonfig
         envelope = parse_envelope(response.body)
         result = install_envelope(envelope, source: source, source_index: index)
         # Write this leg's ETag back AFTER the response (per-leg, race-free).
-        # Exception (qfg-9dxb.9): an ignored gen<=0 payload keeps the previous
-        # ETag. Its ETag is the git sha, and the server may later repair the
-        # 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
+        # Exception (qfg-9dxb.9, qfg-j7ui; supervisor contract Test 11): an
+        # ignored gen<=0 payload, or one dropped as STRICTLY older, keeps the
+        # previous ETag. Its ETag is the git sha, and the server may later
+        # repair the generation for the SAME sha; remembering it would 304 that
+        # repair until the next commit. A same-generation 200 stores its ETag.
+        set_etag_for(index, new_etag) unless result == :not_modified && refused_by_generation?(envelope)
+        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 +519,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 +565,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
@@ -676,9 +708,22 @@ module Quonfig
         # SSE / datadir installs pass source_index nil and are ignored by the
         # aggregator, so they are never counted.
         @failover_aggregator&.record_resolved_from(source_index)
+        :updated
       end
     end
 
+    # Whether the reject-older guard refused this envelope as unversioned
+    # (gen <= 0) or strictly older than the held generation, rather than as a
+    # same-generation re-delivery. The held generation only rises, so a
+    # payload older at decision time is still older here.
+    def refused_by_generation?(envelope)
+      incoming_gen = extract_generation(envelope.meta || {})
+      return true if incoming_gen <= 0
+
+      held = @held_generation
+      !held.nil? && incoming_gen < held
+    end
+
     # The install decision for a network payload (see #install_envelope).
     def should_install?(incoming_gen)
       return true if @held_generation.nil?

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

@@ -7,8 +7,11 @@ module Quonfig
       # class only. The value itself is never interpolated: it can be a
       # decrypted secret, and exception messages end up in logs and error
       # trackers (qfg-goi1.2.11).
-      def initialize(key, expected, actual_value)
-        super("Quonfig value for key '#{key}' expected #{expected}, got #{actual_value.class}")
+      # +actual_type+, when given, is the config's declared value type
+      # ('string', 'duration', ...) and is named instead of the Ruby class.
+      def initialize(key, expected, actual_value, actual_type: nil)
+        got = actual_type ? "a #{actual_type} value" : actual_value.class
+        super("Quonfig value for key '#{key}' expected #{expected}, got #{got}")
       end
     end
   end

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

@@ -257,15 +257,27 @@ module Quonfig
         )
       end
 
+      # A missing, unmatched or empty key is a decryption failure too, so the
+      # typed getters apply the caller's default (qfg-zvyy). DecryptionError is
+      # a Quonfig::Error, so rescuing Quonfig::Error still catches it.
       key_cfg = @store.get(decrypt_with)
-      raise Quonfig::Error, %(Decryption key config "#{decrypt_with}" not found) if key_cfg.nil?
+      if key_cfg.nil?
+        raise Quonfig::Errors::DecryptionError.new(config_key(config),
+                                                   %(decryption key config "#{decrypt_with}" not found))
+      end
 
       key_match = @evaluator.evaluate_config(key_cfg, context, resolver: self)
-      raise Quonfig::Error, %(Decryption key config "#{decrypt_with}" did not match) if key_match.nil?
+      if key_match.nil?
+        raise Quonfig::Errors::DecryptionError.new(config_key(config),
+                                                   %(decryption key config "#{decrypt_with}" did not match))
+      end
 
       resolved_key = resolve_value_on_path(key_match.value, key_cfg, context, key_path)
       secret_key = vget(resolved_key, :value, 'value').to_s
-      raise Quonfig::Error, %(Decryption key from "#{decrypt_with}" is empty) if secret_key.empty?
+      if secret_key.empty?
+        raise Quonfig::Errors::DecryptionError.new(config_key(config),
+                                                   %(decryption key from "#{decrypt_with}" is empty))
+      end
 
       ciphertext = vget(value, :value, 'value').to_s
       begin

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,15 @@ 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 INSTALLED envelope clears it (and ends the WARN episode):
+      # the on_envelope block returns :updated for an install, and an
+      # envelope the reject-older guard drops neither clears the gate nor
+      # counts as a frame (qfg-6vno.20.8). Touched only by the worker thread.
+      @oversized = false
     end
 
     # True if the live SSE stream has ever connected to a non-primary leg. Read
@@ -248,13 +265,22 @@ module Quonfig
             # 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.
+            #
+            # While the oversized gate is set the parser reports only
+            # envelopes as frames, and even those are deferred until the
+            # on_envelope block says the envelope installed (:updated): an
+            # envelope the reject-older guard drops is not an install, so it
+            # neither ends the episode nor makes the connection connected.
             frame_seen = false
-            on_frame = lambda do
+            mark_frame = lambda do
               next if frame_seen
 
               frame_seen = true
               invoke_on_connected
             end
+            on_frame = lambda do
+              mark_frame.call unless @oversized
+            end
             begin
               ended_url = stream_once(on_frame) do |event|
                 # Persist the most recent id so the next reconnect resumes
@@ -266,7 +292,11 @@ module Quonfig
                 # qfg-m3lk: callback exceptions are isolated. A buggy
                 # listener must not look like a transport error and trigger
                 # a reconnect.
-                invoke_on_envelope_safely(on_envelope, event)
+                result = invoke_on_envelope_safely(on_envelope, event)
+                if @oversized && result == :updated
+                  @oversized = false
+                  mark_frame.call
+                end
               end
               # A clean EOF before any frame (200 headers then close) is a
               # failed attempt, exactly like a connect error: report it so
@@ -275,6 +305,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 +388,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 +484,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 at the first installed envelope).
+    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).
@@ -462,7 +509,8 @@ module Quonfig
     # qfg-m3lk: rescue StandardError (NOT Exception) so SystemExit /
     # Interrupt / SignalException still escape — Ctrl-C inside a customer
     # callback must still kill the process. StandardError is the right
-    # boundary for "the caller's listener has a bug".
+    # boundary for "the caller's listener has a bug". Returns the block's
+    # value (:updated for an installed envelope), or nil when it raised.
     def invoke_on_envelope_safely(on_envelope, event)
       on_envelope.call(event.envelope, event, :sse)
     rescue StandardError => e
@@ -546,6 +594,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 +692,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 +722,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 +746,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 +833,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 = '2.0.0'
 end

metadata

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