quonfig 1.5.0 → 1.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5be29a29cae00eb43e09f2aadef25191ec4dc9959ff0037cdfd7ba89dfbd5a10
-  data.tar.gz: b47703c3beb5a4f85f6b2237b3e4295e8e82055ab105168827e750dbd428d13e
+  metadata.gz: ea0ee1cb9b012622117d24f82d00e9ce5fdf61d160562846c6c9b6fa03b4a524
+  data.tar.gz: 2aa051314de0c538eb77218e015368dab3c4fd5c0405ea5469b75c84817314c3
 SHA512:
-  metadata.gz: 7616048fcd0a2a0727ac79a0a801f35d71be44cd54667dc4aaa8aa86009033194f20abbfb69f0b959dc5ba90cdf3e29069db1384e8a432caafe34898f69e3165
-  data.tar.gz: 31d412725f88752b8cbde55daa05c99b926212c2951519a177c24dae72b19d665b3452f4f723e5b2b7e78258cdb37e064733e18249316f7b055846408d2eda92
+  metadata.gz: 0a0d54912f70d45cec55a53c758636d8bb7448eac31c1aee6a19463e6575247e8bc0374ed9ff3b279630b00031556dacb6657ffef7a9f16ac87ec5eb2a2f65ef
+  data.tar.gz: 8838087ac35f83bc5c8761cba0c58a1a8a3fc1a0b3472c6de0b81c20a71d950f4ec1759098ce72e129fd6b4dadd8dd5b6190416d58014cf9dffb99b2bfc9cdd0

data/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## 1.7.0 - 2026-10-02
+
+- **New: public `Client#get_or_raise` and `Client#get_duration_details` (also on `BoundClient`) (qfg-2agi.27).** `get_or_raise(key, default:, context:)` returns the value like `get`; a missing key with no `default:` raises `MissingDefaultError` even under `on_no_default: :return_nil`, and an unset ENV_VAR (`MissingEnvVarError`), an uncoercible ENV_VAR or malformed stored duration (`EnvVarParseError`) or a decryption failure (`DecryptionError`) raises. `get_duration_details` returns integer milliseconds in `EvaluationDetails`; a non-duration config is `ERROR`/`TYPE_MISMATCH` and a malformed value is `ERROR` with a nil value. The shared integration suite's init-timeout `get_or_raise` case now calls the public method instead of falling back to `get`.
+- **Fix: durations follow the one grammar all Quonfig SDKs share, and a malformed duration returns the default instead of a made-up number (qfg-2agi.10).** Grammar (integration-test-data `tests/duration/grammar.yaml`): `P[nD][T[nH][nM][n[.fff]S]]`, at least one component, a fraction only on seconds (at most 9 digits), at most `P36500D`. Before, the pattern was unanchored, so `xxPT5Sxx` read as 5000 ms, `PT5M3H` as 300000 ms and `garbage` as 0. Milliseconds are now rounded half up on both the stored and the ENV_VAR path (`PT1.9999S` from an env var was 1999, now 2000).
+  - `get_duration` on 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 `Quonfig::Errors::EnvVarParseError` under the default `:raise` policy.
+  - `get_duration` on a config whose value type is not duration now raises `TypeMismatchError`, like `get_int` on a string config. Before, an int config's number was returned as milliseconds.
+  - `get` on a malformed stored duration returns `nil` (was `0` or a wrong number).
+  - `Quonfig::Duration.parse` raises `ArgumentError` on an invalid string (it returned `0`). New `Quonfig::Duration.parse_millis` (Integer ms or `nil`) and `Quonfig::Duration.valid?`. Values that used fractions on D/H/M (`PT0.5H`, `PT1.5M`) are now invalid; write `PT30M`, `PT90S`.
+- **Fix: `Client#get` on a duration provided by an ENV_VAR now returns integer milliseconds, the same as a stored duration (qfg-2agi.22).** Before, it returned the raw ISO string (`PT30M` came back as `"PT30M"` from the env var but `1800000` when stored). `get_duration` was already correct.
+- **Behaviour change (bug fix): a named context from a newer tier now replaces the whole same-named context from an older tier, instead of being merged into it property by property (qfg-2agi.36).** Tiers, oldest to newest: `global_context`, `with_context` / `in_context` scopes (outer to inner), per-call context. Example: with `global_context: { user: { 'role' => 'admin' } }`, a call passing `user: { 'plan' => 'pro' }` now evaluates with `user.plan` only; `user.role` is no longer present. Named contexts the newer tier does not mention (for example `team`) are still kept. A symbol name and a string name (`:user` vs `'user'`) count as the same named context. This is the documented rule. Callers that relied on the old property-level merge should pass every attribute of a named context they set.
+- **Fix (security): evaluation-summary telemetry no longer sends the plaintext of `confidential` or `decryptWith` config values (qfg-2agi.15).** `selectedValue` now carries the `*****<hash>` redacted form the resolver already computed; before, `Client#get` reported the decrypted value. Non-confidential values are reported unchanged.
+- **Tests: the shared integration suite now drives every case through the public `Quonfig::Client` (qfg-2agi.33).** Each case uses a datadir client and the typed getter named by its `type:` (`get_string`, `get_int`, `get_float`, `get_bool`, `get_string_list`, `get_json`, `get_duration`), `enabled?` or `get_or_raise`. Context tiers go through `global_context:`, `with_context` and `in_context`. Telemetry cases flush the client's real reporter to a local HTTP server and check the POST. Before, most cases called the internal resolver, and the harness redacted telemetry values itself, so a broken typed getter, a negated `enabled?` or dropped redaction left the suite green. No library change.
+- **Tests: the shared integration suite now checks every duration case through the public `Client#get_duration`, with an exact integer millisecond comparison (qfg-2agi.4).** Before, it checked the internal resolver, so a bug in `get_duration` could not fail the suite. No library change.
+
+## 1.6.0 - 2026-09-28
+
+- **Change: a weighted rollout that hashes on a property missing from the context now hashes an empty value, so every such caller gets the same variant for that flag (qfg-9dxb.8).** Before, such evaluations got a random variant on every call. It is the same variant a context with the property set to `""` gets, and a variant with weight 0 is not served. The reason is still `SPLIT`. The `flag_metadata` of `get_*_details` results includes `'hashPropertyMissing' => true` when the property is missing, and the SDK logs one warning per flag. A weighted rollout with no hash property configured still picks a random variant on every evaluation, unchanged. Users whose context has the property keep the same variant as in 1.5.0.
+- **Change: once the client holds a numbered config generation, a payload with generation 0 is ignored and the client keeps its current config (qfg-9dxb.9).** Only a delivery server with a damaged git store sends one. In 1.5.0 such a payload installed and could move the client back to older config. `held_generation` never goes backward. A client that has never received a real generation (for example one talking to `qfg serve`) still installs every payload.
+- **Fix: a segment or `decryptWith` key that references itself (directly or through a chain) no longer crashes with `SystemStackError` (qfg-9dxb.7).** The looping segment reference evaluates as a missing segment. A `decryptWith` loop raises `DecryptionError`.
+- **Fix: an HTTP 200 or SSE event that is not a config payload (for example `{}` from a proxy) is ignored instead of deleting all configs (qfg-9dxb.3).** Over HTTP the SDK tries the next server.
+
 ## 1.5.0 - 2026-09-25
 
 - **Telemetry transport policy (qfg-y8je.8).** The telemetry POST had no timeout of its own (Faraday's defaults, 60s connect + 60s read); it now has a 15s overall deadline (`telemetry_timeout_ms`) and a 5s connect + TLS deadline (`telemetry_connect_timeout_ms`). A failed batch is kept byte-for-byte and resent (never merged with newer data, so the server dedups a resend of a batch that did land). Resends happen no sooner than 30s after a failure and honor `Retry-After` up to 10 min. The retained queue is capped at 5 batches / 2MB / 5 min (oldest dropped). At most one POST is in flight. 401/403/404 disable telemetry for the process with one ERROR; any other 4xx drops that batch with one ERROR. Before this, a failed batch was simply lost.

data/README.md

@@ -259,7 +259,7 @@ Quonfig::Client.new(
   fallback_poll_enabled:     true,
   fallback_poll_interval_ms: 60_000,
   init_timeout_ms:           10_000,
-  on_no_default:             :error,
+  on_no_default:             :raise,
   global_context:            {},
   datadir:                   '/path/to/workspace',
   environment:               'production',
@@ -277,7 +277,7 @@ Quonfig::Client.new(
 | `fallback_poll_enabled`   | `Boolean`                  | `true`                                                              | Engage HTTP polling as a fallback when SSE is unavailable for >= 2x `fallback_poll_interval_ms`. Deprecated alias: `enable_polling`. |
 | `fallback_poll_interval_ms` | `Integer` (ms)           | `60_000`                                                            | Interval between fallback HTTP polls, in milliseconds. Deprecated alias: `poll_interval` (seconds, multiplied by 1000 internally). |
 | `init_timeout_ms` | `Integer` (ms)             | `10_000`                                                            | Maximum time to wait for the initial config load, in milliseconds. Deprecated alias: `initialization_timeout_sec` (seconds, multiplied by 1000 internally). |
-| `on_no_default`   | `Symbol`                   | `:error`                                                            | Behavior when a key has no value and no default: `:error`, `:warn`, or `:ignore`.                 |
+| `on_no_default`   | `Symbol`                   | `:raise`                                                            | Behavior when a key has no value and no default: `:raise` (raise `Quonfig::Errors::MissingDefaultError`) or `:return_nil`. |
 | `global_context`  | `Hash`                     | `{}`                                                                | Context applied to every evaluation.                                                              |
 | `datadir`         | `String`                   | `ENV['QUONFIG_DIR']`                                                | Path to a local workspace. When set, the SDK runs offline from disk.                              |
 | `environment`     | `String`                   | `ENV['QUONFIG_ENVIRONMENT']`                                        | Environment to evaluate in datadir mode. Required when `datadir` is set.                          |
@@ -361,6 +361,14 @@ client.get_json('homepage.layout')
 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.
+
 ## Dynamic log levels (SemanticLogger)
 
 Quonfig can drive per-class log levels at runtime. Set config keys like

data/lib/quonfig/bound_client.rb

@@ -40,6 +40,10 @@ module Quonfig
       @client.get_json(key, default: default, context: @context)
     end
 
+    def get_or_raise(key, default: NO_DEFAULT_PROVIDED)
+      @client.get_or_raise(key, default: default, context: @context)
+    end
+
     # ---- Details getters ----------------------------------------------
 
     def get_bool_details(key)
@@ -66,15 +70,18 @@ module Quonfig
       @client.get_json_details(key, context: @context)
     end
 
+    def get_duration_details(key)
+      @client.get_duration_details(key, context: @context)
+    end
+
     def enabled?(feature_name)
       @client.enabled?(feature_name, @context)
     end
 
-    # Returns a new BoundClient whose bound context is the merge of this
-    # bound context and +additional+. Merge is one level deep per named
-    # context (mirrors sdk-node's mergeContexts): later values override
-    # earlier within the same named context; keys unique to each side are
-    # preserved.
+    # Returns a new BoundClient whose bound context is this bound context
+    # plus +additional+ (qfg-2agi.24): a named context in +additional+
+    # REPLACES the whole same-named context (no per-property merge); named
+    # contexts it does not mention are kept. Names compare as strings.
     def in_context(additional)
       self.class.new(@client, merge_contexts(@context, additional || {}))
     end
@@ -87,9 +94,10 @@ module Quonfig
 
     def merge_contexts(left, right)
       merged = {}
-      left.each  { |name, ctx| merged[name] = ctx.dup }
+      left.each { |name, ctx| merged[name] = ctx.dup }
       right.each do |name, ctx|
-        merged[name] = merged[name] ? merged[name].merge(ctx) : ctx.dup
+        merged.delete_if { |existing, _| existing.to_s == name.to_s }
+        merged[name] = ctx.dup
       end
       merged
     end

data/lib/quonfig/client.rb

@@ -2,6 +2,7 @@
 
 require 'json'
 require 'timeout'
+require 'set'
 
 module Quonfig
   # Public Quonfig SDK client.
@@ -63,6 +64,9 @@ 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
       @sse_client = nil
       @poll_supervisor = nil
       @stopped = false
@@ -161,14 +165,70 @@ 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.
     def get_duration(key, default: NO_DEFAULT_PROVIDED, context: NO_DEFAULT_PROVIDED)
-      typed_get(key, :duration, default: default, context: context)
+      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)
     end
 
     def get_json(key, default: NO_DEFAULT_PROVIDED, context: NO_DEFAULT_PROVIDED)
       typed_get(key, :json, default: default, context: context)
     end
 
+    # Like +get+, but never applies the +on_no_default+ policy (qfg-2agi.27):
+    #
+    # - A missing key (or a config with no matching value) returns +default:+
+    #   when one is given and otherwise raises MissingDefaultError, even
+    #   under on_no_default: :return_nil.
+    # - A config provided by an unset ENV_VAR raises MissingEnvVarError; an
+    #   ENV_VAR value that cannot be coerced to the config's type raises
+    #   EnvVarParseError; a decryption failure raises DecryptionError.
+    # - A malformed stored duration raises EnvVarParseError (a given
+    #   +default:+ is not applied; it only covers a missing key).
+    def get_or_raise(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
+        end
+      if result.nil?
+        raise Quonfig::Errors::MissingDefaultError, key if default == NO_DEFAULT_PROVIDED
+
+        return default
+      end
+
+      record_evaluation_for_telemetry(result)
+      value = result.unwrapped_value
+      raise malformed_stored_duration_error(result) if malformed_stored_duration?(result, value)
+
+      value
+    end
+
     # ---- Details getters ----------------------------------------------
     #
     # Mirrors the typed getters above but returns a +Quonfig::EvaluationDetails+
@@ -201,6 +261,13 @@ module Quonfig
       evaluate_details(key, :json, context)
     end
 
+    # Integer milliseconds in +value+ (qfg-2agi.27). A config whose valueType
+    # is not duration is ERROR / TYPE_MISMATCH; a malformed value (stored or
+    # ENV_VAR) is ERROR with a nil value.
+    def get_duration_details(key, context: NO_DEFAULT_PROVIDED)
+      evaluate_details(key, :duration, context)
+    end
+
     def enabled?(feature_name, jit_context = NO_DEFAULT_PROVIDED)
       value = get(feature_name, false, jit_context)
       [true, 'true'].include?(value)
@@ -1153,7 +1220,9 @@ module Quonfig
         config_type: config_field(config, :type),
         conditional_value_index: result.rule_index,
         weighted_value_index: result.weighted_value_index,
-        selected_value: result.unwrapped_value,
+        # Confidential / decryptWith values ship as the `*****<hash>` redacted
+        # form, never the plaintext (qfg-2agi.15).
+        selected_value: result.reportable_value.nil? ? result.unwrapped_value : result.reportable_value,
         reason: result.wire_reason
       )
     rescue StandardError => e
@@ -1516,7 +1585,7 @@ module Quonfig
 
     # Combine the customer-supplied globalContext with the optional dev
     # context loaded from ~/.quonfig/tokens.json. Dev context goes UNDER the
-    # customer's so any explicit `quonfig-user` keys win on collision.
+    # customer's, so an explicit customer `quonfig-user` context replaces it.
     def build_initial_global_context(options)
       customer = normalize_context(options.global_context)
       return customer unless dev_context_enabled?(options)
@@ -1549,21 +1618,19 @@ module Quonfig
       raise ArgumentError, "Quonfig context must be a Hash, got #{ctx.class}"
     end
 
-    # One-level-deep merge per named context (mirrors sdk-node's mergeContexts):
-    # later values override earlier within the same named context; keys unique
-    # to each side are preserved.
+    # Combine two context tiers (qfg-2agi.24): a named context in +right+
+    # REPLACES the whole same-named context in +left+ (no per-property merge);
+    # named contexts only in +left+ survive. Names compare as strings, so
+    # +:user+ and +'user'+ are the same named context.
     def merge_contexts(left, right)
       return right || {} if left.nil? || left.empty?
       return left if right.nil? || right.empty?
 
       merged = {}
-      left.each  { |name, ctx| merged[name] = ctx.is_a?(Hash) ? ctx.dup : ctx }
+      left.each { |name, ctx| merged[name] = ctx.is_a?(Hash) ? ctx.dup : ctx }
       right.each do |name, ctx|
-        merged[name] = if merged[name].is_a?(Hash) && ctx.is_a?(Hash)
-                         merged[name].merge(ctx)
-                       else
-                         ctx.is_a?(Hash) ? ctx.dup : ctx
-                       end
+        merged.delete_if { |existing, _| existing.to_s == name.to_s }
+        merged[name] = ctx.is_a?(Hash) ? ctx.dup : ctx
       end
       merged
     end
@@ -1623,6 +1690,10 @@ module Quonfig
       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
         return Quonfig::EvaluationDetails.new(
@@ -1636,13 +1707,15 @@ module Quonfig
       end
 
       reason = result.of_reason
+      flag_metadata = build_flag_metadata(
+        config_id, config_type, result.rule_index, result.weighted_value_index, reason
+      )
+      flag_metadata['hashPropertyMissing'] = true if result.hash_property_missing
       Quonfig::EvaluationDetails.new(
         value: coerced,
         reason: reason,
         variant: build_variant(reason, result.rule_index, result.weighted_value_index),
-        flag_metadata: build_flag_metadata(
-          config_id, config_type, result.rule_index, result.weighted_value_index, reason
-        )
+        flag_metadata: flag_metadata
       )
     rescue StandardError => e
       Quonfig::EvaluationDetails.new(
@@ -1699,6 +1772,42 @@ module Quonfig
       coerce_and_check(key, value, expected_type)
     end
 
+    def duration_millis(key, result, default)
+      raise Quonfig::Errors::TypeMismatchError.new(key, 'ISO-8601 Duration', result.unwrapped_value) unless duration_result?(result)
+
+      value = result.unwrapped_value
+      millis = value.is_a?(Integer) ? value : Quonfig::Duration.parse_millis(value)
+      return millis unless millis.nil?
+
+      malformed_duration(key, default, malformed_stored_duration_error(result))
+    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'
+    end
+
+    # A stored duration string outside the shared grammar unwraps to nil.
+    def malformed_stored_duration?(result, unwrapped)
+      unwrapped.nil? && result.type == 'duration' && !result.raw_value.nil?
+    end
+
+    def malformed_stored_duration_error(result)
+      Quonfig::Errors::EnvVarParseError.new(result.raw_value, result.config || {}, 'stored value')
+    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
+
+      nil
+    end
+
     def coerce_and_check(key, value, expected_type)
       case expected_type
       when :bool
@@ -1711,10 +1820,12 @@ module Quonfig
 
         arr
       when :duration
-        return value.to_i if value.is_a?(Numeric)
-        return (Quonfig::Duration.parse(value) * 1000).to_i if value.is_a?(String)
+        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?
 
-        raise Quonfig::Errors::TypeMismatchError.new(key, 'ISO-8601 Duration', value)
+        millis
       when :json
         # JSON values are returned as-is (Hash, Array, or scalar from the wire).
         value

data/lib/quonfig/config_envelope.rb

@@ -1,5 +1,20 @@
 # frozen_string_literal: true
 
 module Quonfig
-  ConfigEnvelope = Struct.new(:configs, :meta, keyword_init: true)
+  ConfigEnvelope = Struct.new(:configs, :meta, keyword_init: true) do
+    # qfg-9dxb.3: true when a decoded wire payload is a config envelope — a
+    # Hash carrying a +meta+ object with a non-empty +version+. api-delivery and
+    # `qfg serve` always send one; a `{}` or `{"error":"x"}` 200 from a
+    # misbehaving proxy/WAF does not, and must never be installed (it would
+    # read as "zero configs" and wipe every key on an established client).
+    def self.wire_envelope?(data)
+      return false unless data.is_a?(Hash)
+
+      meta = data['meta']
+      return false unless meta.is_a?(Hash)
+
+      version = meta['version']
+      !version.nil? && !version.to_s.empty?
+    end
+  end
 end

data/lib/quonfig/config_loader.rb

@@ -325,7 +325,11 @@ 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).
-        set_etag_for(index, new_etag)
+        # 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
         # 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
@@ -339,6 +343,12 @@ module Quonfig
         @logger.info "Config fetch failed: status #{response.status} from #{source}"
         :failed
       end
+    rescue NonEnvelopeError => e
+      # qfg-9dxb.3: a non-envelope 200 is a leg error, NOT an install — the
+      # hedge/failover proceeds and this leg's ETag is never stored (so a junk
+      # 200 cannot pin itself through later 304s).
+      @logger.warn "Config fetch from #{source} returned a non-envelope 200 (#{e.message}); treating as a failed leg"
+      :failed
     rescue Faraday::ConnectionFailed => e
       @logger.debug "Connection failure fetching configs from #{source}: #{e.message}"
       :failed
@@ -355,8 +365,14 @@ module Quonfig
       @etag_mutex.synchronize { @etags[index || 0] = value }
     end
 
+    # Raised by #parse_envelope for a 200 whose body is not a config envelope
+    # (qfg-9dxb.3). Caught in #fetch_from as a leg error.
+    class NonEnvelopeError < StandardError; end
+
     def parse_envelope(body)
       data = body.is_a?(String) ? JSON.parse(body) : body
+      raise NonEnvelopeError, 'missing meta.version' unless Quonfig::ConfigEnvelope.wire_envelope?(data)
+
       Quonfig::ConfigEnvelope.new(
         configs: data['configs'] || [],
         meta: data['meta'] || {}
@@ -375,23 +391,37 @@ module Quonfig
       incoming_gen = extract_generation(meta)
 
       @install_mutex.synchronize do
-        # Reject-older install guard (canonical ordering, §5f). A fresh client
-        # (no held generation) seeds off whatever arrives first — even an older
-        # or gen-0 snapshot. An established client installs ONLY when the incoming
-        # generation strictly advances the held one: a same-generation snapshot is
-        # a no-op (no store churn, no install-count bump, no resolved-from change)
-        # so a duplicate leg never flaps an established client, and an OLDER
-        # snapshot (a stale secondary reached on failover) is dropped so the client
-        # never regresses. Reject-older is the whole rule — no source ranking; a
-        # newer primary landing late heals forward automatically. Applies on every
-        # network install path (initial fetch, failover/poll fetch, SSE snapshot,
-        # SSE update, fallback poller); datadir install bypasses this (it is the
-        # local source of truth and goes through Client#apply_datadir_envelope).
-        # Carve-out: an UNVERSIONED snapshot (generation <= 0 — a server that
-        # predates the watermark, or one whose rev-count failed) carries no
-        # ordering info, so it is never rejected as "older"; freezing the client
-        # on stale config would be worse (mirrors sdk-node).
-        unless @held_generation.nil? || incoming_gen <= 0 || incoming_gen > @held_generation
+        # Reject-older install guard (canonical ordering, §5f; mirrors sdk-go
+        # shouldInstall). The rule:
+        #   - fresh client (nothing installed yet)  -> install, whatever arrives
+        #   - incoming generation <= 0 (unversioned) -> install ONLY if the held
+        #     generation is 0 (the client has never held a real generation)
+        #   - otherwise -> install iff incoming strictly exceeds held
+        # A same-generation snapshot is a no-op (no store churn, no install-count
+        # bump, no resolved-from change) so a duplicate leg never flaps an
+        # established client, and an OLDER snapshot (a stale secondary reached on
+        # failover) is dropped so the client never regresses. Reject-older is the
+        # whole rule — no source ranking; a newer primary landing late heals
+        # forward automatically. Applies on every network install path (initial
+        # fetch, failover/poll fetch, SSE snapshot, SSE update, fallback poller);
+        # datadir install bypasses this (it is the local source of truth and goes
+        # through Client#apply_datadir_envelope).
+        #
+        # Unversioned payloads (qfg-9dxb.9): the pre-watermark servers that sent
+        # gen 0 on every payload are long gone. Today gen 0 comes only from a
+        # server whose git store is damaged (rev-count failed) — the least
+        # trustworthy source — so it must not override a held real generation.
+        # A client that has only ever seen gen 0 (e.g. `qfg serve`) keeps
+        # installing each gen 0 payload.
+        unless should_install?(incoming_gen)
+          if incoming_gen <= 0
+            # Unversioned payload while a real generation is held: not provably
+            # older (it carries no ordering info), so a silent no-op — NOT
+            # counted as guardRejected.
+            @logger.debug "Unversioned payload ignored: held generation #{@held_generation} (source=#{source})"
+            return :not_modified
+          end
+
           if incoming_gen < @held_generation
             @logger.debug "Reject-older guard: dropping incoming generation #{incoming_gen} < held #{@held_generation} (source=#{source})"
             # Failover observability (qfg-41nh.18): count the guard rejection.
@@ -431,7 +461,11 @@ module Quonfig
         @version = meta['version'] || meta[:version] || @version
         @environment_id = meta['environment'] || meta[:environment] || @environment_id
 
-        @held_generation = incoming_gen
+        # qfg-9dxb.3 Fix A: an unversioned install (generation <= 0) carries no
+        # ordering info and must never LOWER a positive held generation. Under
+        # the qfg-9dxb.9 rule it only installs when held is nil/0 anyway, so
+        # this keeps held at 0 there; a fresh client seeds off it as usual.
+        @held_generation = incoming_gen if @held_generation.nil? || incoming_gen.positive?
         @install_count += 1
         @resolved_from_index = source_index unless source_index.nil?
         # Failover observability (qfg-41nh.18): record which leg served this
@@ -457,6 +491,14 @@ module Quonfig
       end
     end
 
+    # The install decision for a network payload (see #install_envelope).
+    def should_install?(incoming_gen)
+      return true if @held_generation.nil?
+      return @held_generation.zero? if incoming_gen <= 0
+
+      incoming_gen > @held_generation
+    end
+
     # Read Meta.generation (qfg-7h5d.1.1) — the monotonic per-branch commit
     # counter the backend stamps on every envelope. Absent/garbage → 0 (an old
     # backend that doesn't emit it, or fixture mode with no FIXTURE_GENERATION).

data/lib/quonfig/duration.rb

@@ -1,27 +1,76 @@
 # frozen_string_literal: true
 
 module Quonfig
+  # ISO-8601 duration parsing for the grammar every Quonfig SDK shares
+  # (integration-test-data/tests/duration/grammar.yaml, qfg-2agi.29):
+  #
+  #   \AP(?:[0-9]+D)?(?:T(?:[0-9]+H)?(?:[0-9]+M)?(?:[0-9]+(?:\.[0-9]{1,9})?S)?)?\z
+  #
+  # plus: at least one component, no dangling T, a fraction only on S (at
+  # most 9 digits), total magnitude <= P36500D. Anchored with \A/\z (Ruby's
+  # ^/$ match at line boundaries) and [0-9] (never \d).
+  #
+  # Milliseconds use exact Rational arithmetic, rounded half up.
   class Duration
-    PATTERN = /P(?:(?<days>\d+(?:\.\d+)?)D)?(?:T(?:(?<hours>\d+(?:\.\d+)?)H)?(?:(?<minutes>\d+(?:\.\d+)?)M)?(?:(?<seconds>\d+(?:\.\d+)?)S)?)?/
+    PATTERN = /\AP(?:(?<days>[0-9]+)D)?(?:T(?<time>(?:(?<hours>[0-9]+)H)?(?:(?<minutes>[0-9]+)M)?(?:(?<seconds>[0-9]+(?:\.[0-9]{1,9})?)S)?))?\z/
     MINUTES_IN_SECONDS = 60
     HOURS_IN_SECONDS = 60 * MINUTES_IN_SECONDS
     DAYS_IN_SECONDS = 24 * HOURS_IN_SECONDS
+    MAX_SECONDS = 36_500 * DAYS_IN_SECONDS
 
     def initialize(definition)
       @seconds = self.class.parse(definition)
     end
 
+    # Integer milliseconds for a valid duration string, or nil when +definition+
+    # is not a String or does not match the grammar.
+    def self.parse_millis(definition)
+      seconds = exact_seconds(definition)
+      return nil if seconds.nil?
+
+      (seconds * 1000).round(half: :up).to_i
+    end
+
+    def self.valid?(definition)
+      !exact_seconds(definition).nil?
+    end
+
+    # Seconds as a Float. Raises ArgumentError when +definition+ is not a valid
+    # duration (it used to return 0 for anything unparseable).
     def self.parse(definition)
+      seconds = exact_seconds(definition)
+      raise ArgumentError, "invalid ISO-8601 duration: #{definition.inspect}" if seconds.nil?
+
+      seconds.to_f
+    end
+
+    # Exact Rational seconds, or nil when invalid.
+    def self.exact_seconds(definition)
+      return nil unless definition.is_a?(String)
+
       match = PATTERN.match(definition)
-      return 0 unless match
+      return nil if match.nil?
+      return nil if match[:days].nil? && match[:time].nil?
+      return nil if match[:time] && match[:time].empty?
+
+      total = (Integer(match[:days] || '0', 10) * DAYS_IN_SECONDS) +
+              (Integer(match[:hours] || '0', 10) * HOURS_IN_SECONDS) +
+              (Integer(match[:minutes] || '0', 10) * MINUTES_IN_SECONDS) +
+              decimal_seconds(match[:seconds])
+      return nil if total > MAX_SECONDS
+
+      total
+    end
+
+    def self.decimal_seconds(text)
+      return 0 if text.nil?
 
-      days = match[:days]&.to_f || 0
-      hours = match[:hours]&.to_f || 0
-      minutes = match[:minutes]&.to_f || 0
-      seconds = match[:seconds]&.to_f || 0
+      whole, frac = text.split('.', 2)
+      return Integer(whole, 10) if frac.nil?
 
-      ((days * DAYS_IN_SECONDS) + (hours * HOURS_IN_SECONDS) + (minutes * MINUTES_IN_SECONDS) + seconds)
+      Integer(whole, 10) + Rational(Integer(frac, 10), 10**frac.length)
     end
+    private_class_method :decimal_seconds
 
     def in_seconds
       @seconds

data/lib/quonfig/evaluator.rb

@@ -131,10 +131,15 @@ module Quonfig
 
     # --- Rule evaluation ------------------------------------------------
 
-    def evaluate_rules(rules, context, config)
+    # +seg_path+ holds the keys of the configs being evaluated above this one
+    # through IN_SEG / NOT_IN_SEG, so segment resolution can detect a
+    # reference cycle instead of recursing until SystemStackError
+    # (qfg-9dxb.7). It is a path, not a global visited set, so a diamond (two
+    # segments that both reference a third) still resolves.
+    def evaluate_rules(rules, context, config, seg_path = [])
       rules.each_with_index do |rule, index|
         criteria = Array(hget(rule, :criteria) || [])
-        next unless all_criteria_match?(criteria, context, config)
+        next unless all_criteria_match?(criteria, context, config, seg_path)
 
         value_hash = hget(rule, :value)
         return EvalResult.new(value: value_hash, rule_index: index, config: config)
@@ -142,8 +147,8 @@ module Quonfig
       nil
     end
 
-    def all_criteria_match?(criteria, context, config)
-      criteria.all? { |c| evaluate_criterion(c, context, config) }
+    def all_criteria_match?(criteria, context, config, seg_path)
+      criteria.all? { |c| evaluate_criterion(c, context, config, seg_path) }
     end
 
     # --- Per-operator evaluation ---------------------------------------
@@ -151,7 +156,7 @@ module Quonfig
     # Faithful port of sdk-node/src/operators.ts evaluateCriterion. Matches
     # context-exists / missing-context semantics (e.g. PROP_IS_NOT_ONE_OF is
     # true when context is missing).
-    def evaluate_criterion(criterion, context, _config)
+    def evaluate_criterion(criterion, context, config, seg_path)
       property_name = hget(criterion, :propertyName) || ''
       operator = hget(criterion, :operator)
       match_value = hget(criterion, :valueToMatch)
@@ -296,7 +301,7 @@ module Quonfig
       when OP_IN_SEG, OP_NOT_IN_SEG
         if match_value
           segment_key = to_s_nil(hget(match_value, :value))
-          found, result = resolve_segment(segment_key, context)
+          found, result = resolve_segment(segment_key, context, config, seg_path)
           return operator == OP_NOT_IN_SEG unless found
 
           return result == (operator == OP_IN_SEG)
@@ -319,16 +324,22 @@ module Quonfig
 
     # --- Segment resolution -------------------------------------------
 
-    def resolve_segment(segment_key, context)
+    def resolve_segment(segment_key, context, config, seg_path)
       return [false, false] if segment_key.nil? || segment_key.empty?
 
+      # A reference back onto the current evaluation path is a cycle. Treat
+      # it like a missing segment (IN_SEG false, NOT_IN_SEG true), matching
+      # sdk-go (qfg-9dxb.4).
+      current_key = hget(config, :key).to_s
+      return [false, false] if segment_key == current_key || seg_path.include?(segment_key)
+
       seg_config = @store.get(segment_key)
       return [false, false] if seg_config.nil?
 
       # Segments have no environment-specific rules in the JSON shape; we
       # evaluate against default rules only (mirrors sdk-node behaviour —
       # evaluate_config with env_id='' falls through to default).
-      match = evaluate_rules(default_rules_of(seg_config), context, seg_config)
+      match = evaluate_rules(default_rules_of(seg_config), context, seg_config, seg_path + [current_key])
       return [false, false] if match.nil?
 
       raw = match.raw_value
@@ -424,14 +435,18 @@ module Quonfig
     REASON_TARGETING_MATCH  = 2
     REASON_SPLIT            = 3
 
-    attr_reader :value, :rule_index, :config, :reportable_value
+    attr_reader :value, :rule_index, :config, :reportable_value, :hash_property_missing
     attr_accessor :weighted_value_index
 
-    def initialize(value:, rule_index:, config:, weighted_value_index: nil, reportable_value: nil)
+    def initialize(value:, rule_index:, config:, weighted_value_index: nil, reportable_value: nil,
+                   hash_property_missing: false)
       @value = value
       @rule_index = rule_index
       @config = config
       @weighted_value_index = weighted_value_index
+      # True when a weighted rollout's hash property was missing from the
+      # context and an empty value was hashed instead (qfg-9dxb.8).
+      @hash_property_missing = hash_property_missing
       # Telemetry-safe substitute for #unwrapped_value. Set by Resolver when
       # the underlying Value was confidential / decryptWith, so callers
       # (the eval-summary aggregator) never see the plaintext. Mirrors
@@ -541,8 +556,9 @@ module Quonfig
       when Numeric
         raw.to_i
       when String
-        seconds = Quonfig::Duration.parse(raw)
-        (seconds * 1000).round
+        # nil for a malformed value, so get() never returns the raw string or
+        # a made-up number; Client#get_duration applies the default.
+        Quonfig::Duration.parse_millis(raw)
       when Hash
         secs = (raw['seconds'] || raw[:seconds] || 0).to_f
         nanos = (raw['nanos'] || raw[:nanos] || 0).to_f

data/lib/quonfig/resolver.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'digest'
+require 'set'
 
 module Quonfig
   # Public-API resolver: looks up a config by key in a ConfigStore and runs
@@ -16,6 +17,7 @@ module Quonfig
   # production read path (with config_loader, SSE updates, telemetry), see
   # Quonfig::ConfigResolver — the two coexist during the JSON migration.
   class Resolver
+    LOG = Quonfig::InternalLogger.new(self)
     TRUE_VALUES = %w[true 1 t yes].freeze
     # Prefix the eval-summary aggregator stamps onto redacted confidential
     # values before the 5-char MD5 hash. Matches CONFIDENTIAL_PREFIX in
@@ -29,6 +31,9 @@ module Quonfig
     def initialize(store, evaluator)
       @store = store
       @evaluator = evaluator
+      # Config keys already warned about a missing hash property (qfg-9dxb.8).
+      @hash_missing_warned = Set.new
+      @hash_missing_mutex = Mutex.new
     end
 
     def raw(key)
@@ -50,7 +55,8 @@ module Quonfig
       return nil if eval_result.nil?
 
       weighted_index = nil
-      resolved_value = resolve_value(eval_result.value, config, context) do |idx|
+      hash_missing = []
+      resolved_value = resolve_value_on_path(eval_result.value, config, context, [], hash_missing) do |idx|
         weighted_index = idx
       end
       EvalResult.new(
@@ -58,7 +64,8 @@ module Quonfig
         rule_index: eval_result.rule_index,
         config: config,
         weighted_value_index: weighted_index,
-        reportable_value: redacted_reportable_value(eval_result.value)
+        reportable_value: redacted_reportable_value(eval_result.value),
+        hash_property_missing: !hash_missing.empty?
       )
     end
 
@@ -68,32 +75,42 @@ module Quonfig
     # - confidential + decryptWith → look up the key config, decrypt
     # - everything else passes through unchanged
     def resolve_value(value, config, context = nil, &on_weighted_index)
+      resolve_value_on_path(value, config, context, [], &on_weighted_index)
+    end
+
+    # Integration shims for code that expects a ConfigResolver. Keep these
+    # narrow; the real ConfigResolver still owns the production hot path.
+    def symbolize_json_names?
+      false
+    end
+
+    private
+
+    # resolve_value plus +key_path+: the config keys already being resolved
+    # above this one through decryptWith, so a decryptWith cycle raises a
+    # DecryptionError instead of recursing until SystemStackError
+    # (qfg-9dxb.7, matching sdk-go qfg-9dxb.4). +hash_missing+, when given,
+    # gets an entry for each weighted rollout whose hash property was missing
+    # from the context (qfg-9dxb.8).
+    def resolve_value_on_path(value, config, context, key_path, hash_missing = nil, &on_weighted_index)
       return nil if value.nil?
 
       type = vget(value, :type, 'type')
 
       return resolve_provided(value, config) if type == 'provided'
 
-      return resolve_weighted(value, config, context, &on_weighted_index) if type == 'weighted_values'
+      return resolve_weighted(value, config, context, key_path, hash_missing, &on_weighted_index) if type == 'weighted_values'
 
       confidential = vget(value, :confidential, 'confidential')
       decrypt_with = vget(value, :decryptWith, 'decryptWith', :decrypt_with, 'decrypt_with')
       if confidential && decrypt_with && !decrypt_with.to_s.empty?
         return resolve_decryption(value, config, context,
-                                  decrypt_with)
+                                  decrypt_with, key_path)
       end
 
       value
     end
 
-    # Integration shims for code that expects a ConfigResolver. Keep these
-    # narrow; the real ConfigResolver still owns the production hot path.
-    def symbolize_json_names?
-      false
-    end
-
-    private
-
     # If +value+ is confidential or has a decryptWith key, return the
     # `*****<5-hex>` redacted string the eval-summary telemetry aggregator
     # should ship in place of the resolved plaintext. The hash is computed
@@ -162,7 +179,12 @@ module Quonfig
     # (or fall back to a per-call random) into [0,1), then walk the variant
     # weights until cumulative weight >= bucket. Recurses through
     # resolve_value so nested provided/encrypted variants work too.
-    def resolve_weighted(value, config, context, &on_weighted_index)
+    #
+    # A hash property that is configured but missing from the context (or
+    # nil) hashes an empty value, the same bucket as a present "", and warns
+    # once per config key (qfg-9dxb.8). With no hash property configured the
+    # pick stays random per call.
+    def resolve_weighted(value, config, context, key_path, hash_missing = nil, &on_weighted_index)
       payload = vget(value, :value, 'value') || {}
       weighted = vget(payload, :weightedValues, 'weightedValues', :weighted_values, 'weighted_values')
       return value unless weighted.is_a?(Array) && !weighted.empty?
@@ -182,23 +204,42 @@ module Quonfig
       end
 
       cfg_key = config_key(config)
+      if hash_value.nil? && !hash_property.to_s.empty?
+        hash_value = ''
+        hash_missing&.push(true)
+        warn_hash_property_missing(cfg_key, hash_property)
+      end
       picker = Quonfig::WeightedValueResolver.new(weighted, cfg_key, hash_value)
       variant, index = picker.resolve
       on_weighted_index&.call(index)
       variant_value = vget(variant, :value, 'value')
-      resolve_value(variant_value, config, context, &on_weighted_index)
+      resolve_value_on_path(variant_value, config, context, key_path, hash_missing, &on_weighted_index)
+    end
+
+    def warn_hash_property_missing(cfg_key, hash_property)
+      return unless @hash_missing_mutex.synchronize { @hash_missing_warned.add?(cfg_key) }
+
+      LOG.warn "quonfig: weighted rollout for \"#{cfg_key}\" hashes on \"#{hash_property}\" " \
+               'which is missing from context; hashing an empty value instead'
     end
 
     # Recursively resolve the decryption-key config (it may itself be a
     # provided ENV_VAR), then AES-GCM decrypt the value with that key.
-    def resolve_decryption(value, config, context, decrypt_with)
+    def resolve_decryption(value, config, context, decrypt_with, key_path)
+      key_path += [config_key(config).to_s]
+      if key_path.include?(decrypt_with.to_s)
+        raise Quonfig::Errors::DecryptionError.new(
+          config_key(config), %(decryption key config "#{decrypt_with}" is part of a decryptWith cycle)
+        )
+      end
+
       key_cfg = @store.get(decrypt_with)
       raise Quonfig::Error, %(Decryption key config "#{decrypt_with}" not found) if key_cfg.nil?
 
       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?
 
-      resolved_key = resolve_value(key_match.value, key_cfg, context)
+      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?
 
@@ -233,6 +274,8 @@ module Quonfig
       when 'string_list'
         env_value.split(/\s*,\s*/)
       when 'duration'
+        raise ArgumentError, 'invalid ISO-8601 duration' unless Quonfig::Duration.valid?(env_value)
+
         env_value
       else
         env_value
@@ -247,6 +290,9 @@ module Quonfig
       when 'double'      then 'double'
       when 'bool'        then 'bool'
       when 'string_list' then 'string_list'
+      # Keep 'duration' so Evaluator#unwrapped_value converts to ms and
+      # get() matches the stored path (qfg-2agi.22).
+      when 'duration'    then 'duration'
       else 'string'
       end
     end

data/lib/quonfig/sse_config_client.rb

@@ -604,6 +604,14 @@ module Quonfig
           return nil
         end
 
+        # qfg-9dxb.3: drop a JSON event that is not a config envelope (no meta
+        # object with a non-empty version) exactly like malformed JSON — it must
+        # never reach install and wipe an established client's keys.
+        unless Quonfig::ConfigEnvelope.wire_envelope?(parsed)
+          (@logger || LOG).error 'SSE Streaming Error: non-envelope event (missing meta.version); dropped'
+          return nil
+        end
+
         envelope = Quonfig::ConfigEnvelope.new(
           configs: parsed['configs'] || [],
           meta: parsed['meta'] || {}

data/lib/quonfig/version.rb

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

metadata

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