quonfig 1.11.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6d1016bb1930249b2a74a4f670e25cb2143ff0e664edd54062c585437a85527a
-  data.tar.gz: 8e2e0844f5853cf5c1d27f45054e71dc6cda6f8f5aa398468c982a485659d1b8
+  metadata.gz: c7947aba694daddefb1357930d7d1b3e63d13c3f68ad71b1e5d33eff15584aa6
+  data.tar.gz: db349b68906829c24953f9504511200f7b837c8980ad9beb53a755586420f470
 SHA512:
-  metadata.gz: 705580a318dd7d773b6b0b01236f0509b6d60f440e44e21d07228de7ce6915d71c9ffe9c9c60a6a4c50ed95ed39018727bbb2ed89389610d4df8c9058b196f48
-  data.tar.gz: a9e69afa6be50db19b7508e9224203dda7c62ef522d1b591d2d7050ffdd69cbef217433791330fead5435c9ebe9fcbd364c245be5127ff9fbb1443e74be6a586
+  metadata.gz: 687f621eeff45b850bba0ab6845963abbdb8478ac18e32e1006d9f02de3b8a3ed850b75bf37ae2e907dd9512756f98fc79ae942221aaa7c17a0abd683bb9b920
+  data.tar.gz: 96792d273e01d2748f78435a75c3d8b4be405ff65470f465b646595539cf786ab4c204cab167350e66b42be03907739e49aaa01ad5b8a2228ebd7736fd4bb8e8

data/CHANGELOG.md

@@ -1,5 +1,100 @@
 # 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.

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)
 

data/lib/quonfig/client.rb

@@ -21,6 +21,42 @@ 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
@@ -81,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
@@ -151,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)
@@ -190,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)
@@ -248,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 ----------------------------------------------
@@ -293,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)
@@ -1857,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
@@ -2160,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?
@@ -2175,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,
@@ -2248,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
+
+    # 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
 
-    def duration_millis(key, result, default)
-      raise Quonfig::Errors::TypeMismatchError.new(key, 'ISO-8601 Duration', result.unwrapped_value) unless duration_result?(result)
+    # 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)
 
-      value = result.unwrapped_value
-      millis = value.is_a?(Integer) ? value : Quonfig::Duration.parse_millis(value)
-      return millis unless millis.nil?
+      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
 
-      malformed_duration(key, default, malformed_stored_duration_error(result))
+      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.
@@ -2281,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)
-
-        arr
-      when :duration
-        return value if value.is_a?(Integer)
+    # 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) }
 
-        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

@@ -300,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
@@ -494,11 +495,12 @@ 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.
@@ -706,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/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/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

@@ -130,8 +130,10 @@ module Quonfig
       # 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.
+      # 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
 
@@ -263,16 +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
-              # Gated, the parser reports only envelopes as frames; one ends
-              # the oversized episode.
-              @oversized = false
+            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
@@ -284,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
@@ -474,7 +486,7 @@ module Quonfig
 
     # 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).
+    # 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; " \
@@ -497,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

data/lib/quonfig/version.rb

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

metadata

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