quonfig 2.0.0 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c7947aba694daddefb1357930d7d1b3e63d13c3f68ad71b1e5d33eff15584aa6
-  data.tar.gz: db349b68906829c24953f9504511200f7b837c8980ad9beb53a755586420f470
+  metadata.gz: 7fb6a1cbb69335648d8e68194ef6c177360f575248942a145b214fae2e3a0bf6
+  data.tar.gz: 7782d66fe639d2b690932d7d3c7ed2becb793c0a18252ddd7988424eaf29fec5
 SHA512:
-  metadata.gz: 687f621eeff45b850bba0ab6845963abbdb8478ac18e32e1006d9f02de3b8a3ed850b75bf37ae2e907dd9512756f98fc79ae942221aaa7c17a0abd683bb9b920
-  data.tar.gz: 96792d273e01d2748f78435a75c3d8b4be405ff65470f465b646595539cf786ab4c204cab167350e66b42be03907739e49aaa01ad5b8a2228ebd7736fd4bb8e8
+  metadata.gz: 3ff89f7539988b7a95527fcc93b8fd2b1662ed52c664c87e9855c7f9e926877d4240c04c8703e62d93f93e81c3e28ce5540c27682bfcc65e306942d3985084aa
+  data.tar.gz: 8ea638dc75cadf24d41bfc6030748cf03116c359e69a3f8c03a72dea26496f01fe64395502a3f6dafd437c929f07ab81121b84c66cdafeb1feff38f58ba6a875

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 2.2.0 - 2026-10-29
+
+- **Changed (edge case): the `*_details` getters and `evaluate_details` report a value that cannot be parsed as `error_code: "PARSE_ERROR"` (qfg-wg1n).** A malformed ENV_VAR value (an int config whose env var is `"twelve"`, a duration env var `"PT5S garbage"`) and, on the typed getters, a malformed stored int, double or duration (`"twelve"`, `"abc"`, `"PT0.5H"`) were reported as `TYPE_MISMATCH`; they are now `PARSE_ERROR`, the code OpenFeature uses for this case, with the same `reason: "ERROR"`, nil value, variant and `flag_metadata` as before. A value of another type (`get_int_details` on a string config) is still `TYPE_MISMATCH`. The new constant is `Quonfig::EvaluationDetails::ERROR_PARSE_ERROR`. Only the error code on these failure paths changes: the plain getters, `get_or_raise` and the raised errors (`EnvVarParseError`, `TypeMismatchError`) are unchanged, and `evaluate_details` still returns a malformed stored value as stored with a success reason. Code that compared `error_code` to `TYPE_MISMATCH` to detect a malformed value should also accept `PARSE_ERROR`. quonfig-openfeature 2.3.0 already passes `PARSE_ERROR` straight through. Tests: `test/test_parse_error_details.rb`.
+
+## 2.1.0 - 2026-10-29
+
+- **Added: `evaluate_details(key, context:)`, an untyped details read (qfg-177f).** It returns a `Quonfig::EvaluationDetails` whose `value` is the config's resolved value as stored, after ENV_VAR provision and decryption, with no type check or conversion: a duration comes back as its ISO 8601 text exactly as stored (`"PT90S"`, not milliseconds), a `string_list` as an Array, JSON as stored. The new `value_type` attribute names the stored type (`"duration"`, `"int"`, ...; `nil` when nothing resolved). Reason, variant, `flag_metadata`, error codes and telemetry are the same as the typed `*_details` getters, and it never raises. A malformed stored value (a duration `"30s"`) is returned as-is with a success reason; an unset or unparseable ENV_VAR is still `reason: "ERROR"`, as in the typed getters. Available on the client and on a `with_context` bound client. It matches sdk-go's `Client.EvaluateDetails` and is meant for OpenFeature providers and other callers that do their own typing. Existing getters are unchanged. Tests: `test/test_evaluate_details.rb`.
+- **Fixed: `connection_state` no longer answers `:connected` before the SSE stream's first frame (qfg-fi1s).** On a network client with SSE on, the init fetch installs an envelope before the stream has delivered anything, and `connection_state` read that install as `:connected`. It now reports `:initializing` until the stream's first frame arrives (the connected edge), as the supervisor contract says ("after 200 headers, no frame" is initializing) and as sdk-go, sdk-java, sdk-net and sdk-python already do. Datadir clients and clients with `enable_sse: false` still read `:connected` once config is installed. Tests: `test/test_health_primitives.rb`, `test/test_sse_first_frame.rb` (Test 9a/9b now assert on the public getter).
+
 ## 2.0.0 - 2026-10-26
 
 The typed-getter contract (qfg-zvyy), shared by every Quonfig SDK and pinned by

data/README.md

@@ -480,10 +480,28 @@ 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"`.
+raise. They return `Quonfig::EvaluationDetails`; a value of another type is
+`reason: "ERROR"` with `error_code: "TYPE_MISMATCH"`, and a value that cannot
+be parsed as its declared type (a malformed ENV_VAR value, or a malformed
+stored int, double or duration) is `reason: "ERROR"` with
+`error_code: "PARSE_ERROR"`.
 `get_duration_details` carries the duration in integer milliseconds.
 
+To read a value without a type, use `evaluate_details(key, context:)`. It
+returns the value as stored, with `value_type` naming its type, and the same
+`reason`, `variant` and `flag_metadata` as the typed details getters. A
+duration comes back as its ISO 8601 text:
+
+```ruby
+details = client.evaluate_details('http.timeout', context: { user: { key: 'u1' } })
+details.value       # => "PT90S"
+details.value_type  # => "duration"
+details.reason      # => "STATIC"
+```
+
+It does no type check and never raises; a missing key is `reason: "ERROR"`
+with `error_code: "FLAG_NOT_FOUND"`.
+
 ## Dynamic log levels (SemanticLogger)
 
 Quonfig can drive per-class log levels at runtime. Set config keys like
@@ -607,8 +625,8 @@ Caveats:
   threads race the first request.
 - **`connection_state` never triggers the re-initialization** — a diagnostic
   must not open a socket. A child that has not used the client yet answers
-  `:initializing`, which is exactly what it is; it flips to `:connected` on
-  first use.
+  `:initializing`, which is exactly what it is; it flips to `:connected`
+  after its first use, once the stream delivers its first frame.
 - The child's telemetry aggregators start empty. The parent flushes the data
   it collected before the fork; the child reports only its own.
 - **Per-job forking pays per job.** A Resque-style worker that forks a child
@@ -757,7 +775,9 @@ reuse the parent's client object in a child process without it.
   envelope install (any source: datadir, initial HTTP fetch, SSE, or fallback
   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`.
+  `:initializing`, `:connected`, `:disconnected`, or `:falling_back`. With
+  SSE on, the client reads `:initializing` until the stream delivers its
+  first frame, even after the initial fetch has installed config.
 - `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

data/lib/quonfig/bound_client.rb

@@ -74,6 +74,11 @@ module Quonfig
       @client.get_duration_details(key, context: @context)
     end
 
+    # See Quonfig::Client#evaluate_details.
+    def evaluate_details(key)
+      @client.evaluate_details(key, context: @context)
+    end
+
     def enabled?(feature_name)
       @client.enabled?(feature_name, @context)
     end

data/lib/quonfig/client.rb

@@ -282,37 +282,54 @@ module Quonfig
     # carrying the OpenFeature-aligned resolution +reason+ ("STATIC",
     # "TARGETING_MATCH", "SPLIT", "DEFAULT", or "ERROR") plus an
     # +error_code+/+error_message+ on the error path. These methods never
-    # raise — exceptions are caught and rendered as ERROR details.
+    # raise — exceptions are caught and rendered as ERROR details. A value of
+    # another type is error_code TYPE_MISMATCH; a value that cannot be parsed
+    # as its declared type (a malformed ENV_VAR value, a malformed stored
+    # int, double or duration) is PARSE_ERROR.
 
     def get_bool_details(key, context: NO_DEFAULT_PROVIDED)
-      evaluate_details(key, :bool, context)
+      build_details(key, :bool, context)
     end
 
     def get_string_details(key, context: NO_DEFAULT_PROVIDED)
-      evaluate_details(key, String, context)
+      build_details(key, String, context)
     end
 
     def get_int_details(key, context: NO_DEFAULT_PROVIDED)
-      evaluate_details(key, Integer, context)
+      build_details(key, Integer, context)
     end
 
     def get_float_details(key, context: NO_DEFAULT_PROVIDED)
-      evaluate_details(key, Float, context)
+      build_details(key, Float, context)
     end
 
     def get_string_list_details(key, context: NO_DEFAULT_PROVIDED)
-      evaluate_details(key, :string_list, context)
+      build_details(key, :string_list, context)
     end
 
     def get_json_details(key, context: NO_DEFAULT_PROVIDED)
-      evaluate_details(key, :json, context)
+      build_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.
+    # ENV_VAR) is ERROR / PARSE_ERROR with a nil value.
     def get_duration_details(key, context: NO_DEFAULT_PROVIDED)
-      evaluate_details(key, :duration, context)
+      build_details(key, :duration, context)
+    end
+
+    # Untyped details read (matches sdk-go Client.EvaluateDetails). +value+
+    # is the resolved value in its stored form, after ENV_VAR provision and
+    # decryption, with no type check, coercion or parse validation: a
+    # duration is its ISO 8601 text exactly as stored ("PT90S"), a
+    # string_list an Array, a json value as stored. +value_type+ is the
+    # stored value type ('string', 'int', 'double', 'bool', 'string_list',
+    # 'duration', 'json', ...; nil when nothing resolved). Reason, variant,
+    # error_code and telemetry are the same as the typed *_details getters,
+    # and like them it never raises. Meant for OpenFeature providers and
+    # other callers that do their own typing.
+    def evaluate_details(key, context: NO_DEFAULT_PROVIDED)
+      build_details(key, nil, context)
     end
 
     # True only when the flag resolves to the bool +true+. Never raises
@@ -650,7 +667,8 @@ module Quonfig
     # Aggregate connection state. Returns one of:
     #
     # - +:initializing+ — no envelope has been installed and SSE is not yet
-    #   connected.
+    #   connected, or (SSE clients) the stream has not delivered its first
+    #   frame yet, even if the init fetch already installed an envelope.
     # - +:connected+ — SSE is live, or the SDK is delivering configs from a
     #   loaded envelope (datadir mode or post-initial-fetch with no SSE).
     # - +:disconnected+ — +stop+ was called, or SSE errored and no fallback
@@ -681,9 +699,14 @@ module Quonfig
         next :disconnected if sse_channel_expected? && !sse_worker_alive?
         next :connected if @sse_state == :connected
         next :disconnected if @sse_state == :error
+        # First-frame rule (qfg-fi1s): a client that is supposed to hold an
+        # SSE stream is not :connected until that stream delivers its first
+        # frame. The init fetch's install alone does not make it connected;
+        # "after 200 headers, no frame" is :initializing (contract Test 6).
+        next :initializing if sse_channel_expected? && !@sse_ever_connected
 
         # No SSE state change yet: state is driven by whether any envelope
-        # has been installed (datadir / initial fetch).
+        # has been installed (datadir / SSE disabled / initial fetch).
         @last_successful_refresh.nil? ? :initializing : :connected
       end
     end
@@ -958,7 +981,7 @@ module Quonfig
     end
 
     # Lazy post-fork re-initialization. Called from every read entry point
-    # (+get+, +evaluate_details+, +defined?+, +keys+) — the flag read is a
+    # (+get+, +evaluate_details+ / the +*_details+ getters, +defined?+, +keys+) — the flag read is a
     # plain boolean, so the steady-state cost is one comparison per lookup.
     #
     # The first caller in the child does what +Client.new+ does: its own
@@ -2185,9 +2208,11 @@ module Quonfig
     end
 
     # Build a Quonfig::EvaluationDetails for +key+, evaluated against the
-    # caller's context, after coercing/checking +expected_type+. Never
-    # raises; all exceptions become ERROR details.
-    def evaluate_details(key, expected_type, context)
+    # caller's context, after coercing/checking +expected_type+. A nil
+    # +expected_type+ is the untyped #evaluate_details read: the stored value
+    # with no type check, plus +value_type+. Never raises; all
+    # exceptions become ERROR details.
+    def build_details(key, expected_type, context)
       ensure_initialized_after_fork
       jit = context == NO_DEFAULT_PROVIDED ? nil : context
       ctx = build_context(jit)
@@ -2208,11 +2233,11 @@ module Quonfig
           )
         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).
+          # PARSE_ERROR, like a malformed stored value (qfg-wg1n).
           return Quonfig::EvaluationDetails.new(
             value: nil,
             reason: Quonfig::EvaluationDetails::REASON_ERROR,
-            error_code: Quonfig::EvaluationDetails::ERROR_TYPE_MISMATCH,
+            error_code: Quonfig::EvaluationDetails::ERROR_PARSE_ERROR,
             error_message: e.message,
             variant: build_variant(Quonfig::EvaluationDetails::REASON_ERROR, nil, nil),
             flag_metadata: build_flag_metadata(nil, nil, nil, nil, nil)
@@ -2234,14 +2259,14 @@ module Quonfig
       config_type = result.config&.dig('type') || result.config&.dig(:type)
 
       begin
-        coerced = typed_value(key, result, expected_type)
+        coerced = expected_type.nil? ? stored_value(result) : 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.
+        # A value of another type is TYPE_MISMATCH; a malformed one (a stored
+        # int "twelve", a duration "30s") is PARSE_ERROR (qfg-wg1n).
         return Quonfig::EvaluationDetails.new(
           value: nil,
           reason: Quonfig::EvaluationDetails::REASON_ERROR,
-          error_code: Quonfig::EvaluationDetails::ERROR_TYPE_MISMATCH,
+          error_code: details_error_code(e),
           error_message: e.message,
           variant: build_variant(Quonfig::EvaluationDetails::REASON_ERROR, nil, nil),
           flag_metadata: build_flag_metadata(config_id, config_type, nil, nil, nil)
@@ -2257,7 +2282,8 @@ module Quonfig
         value: coerced,
         reason: reason,
         variant: build_variant(reason, result.rule_index, result.weighted_value_index),
-        flag_metadata: flag_metadata
+        flag_metadata: flag_metadata,
+        value_type: expected_type.nil? ? stored_value_type(result) : nil
       )
     rescue StandardError => e
       Quonfig::EvaluationDetails.new(
@@ -2270,6 +2296,30 @@ module Quonfig
       )
     end
 
+    def details_error_code(error)
+      if error.is_a?(Quonfig::Errors::EnvVarParseError)
+        Quonfig::EvaluationDetails::ERROR_PARSE_ERROR
+      else
+        Quonfig::EvaluationDetails::ERROR_TYPE_MISMATCH
+      end
+    end
+
+    # +result+'s resolved value in stored form (after ENV_VAR provision and
+    # decryption) with no coercion or parse validation: a duration is its
+    # ISO 8601 text as stored. Hashes and Arrays are copied so a caller
+    # mutating the result cannot rewrite the cached config.
+    def stored_value(result)
+      copy_containers(result.raw_value)
+    end
+
+    def copy_containers(value)
+      case value
+      when Hash then value.to_h { |k, v| [k, copy_containers(v)] }
+      when Array then value.map { |v| copy_containers(v) }
+      else value
+      end
+    end
+
     # Build the variant string per the cross-SDK spec
     # (project/plans/openfeature-resolution-details.md §2).
     def build_variant(reason, rule_index, weighted_value_index)

data/lib/quonfig/evaluation_details.rb

@@ -15,10 +15,17 @@ module Quonfig
   #
   # +error_code+ (only when reason == "ERROR") is one of:
   #   "FLAG_NOT_FOUND" — the key was unknown to the store
-  #   "TYPE_MISMATCH"  — the resolved value didn't satisfy the requested type
+  #   "TYPE_MISMATCH"  — the resolved value is of another type than the getter's
+  #   "PARSE_ERROR"    — the value cannot be parsed as its declared type: a
+  #                      malformed ENV_VAR value, or a malformed stored int,
+  #                      double or duration (qfg-wg1n)
   #   "PROVIDER_NOT_READY" — the client has no config yet (init continued
   #                          on code defaults, or a caught init failure)
   #   "GENERAL"        — any other failure
+  #
+  # +value_type+ is set only by Client#evaluate_details: the stored value
+  # type ("string", "int", "double", "bool", "string_list", "duration",
+  # "json", ...), or nil when nothing resolved. The typed getters leave it nil.
   class EvaluationDetails
     REASON_STATIC          = 'STATIC'
     REASON_TARGETING_MATCH = 'TARGETING_MATCH'
@@ -28,19 +35,21 @@ module Quonfig
 
     ERROR_FLAG_NOT_FOUND = 'FLAG_NOT_FOUND'
     ERROR_TYPE_MISMATCH  = 'TYPE_MISMATCH'
+    ERROR_PARSE_ERROR    = 'PARSE_ERROR'
     ERROR_GENERAL        = 'GENERAL'
     ERROR_PROVIDER_NOT_READY = 'PROVIDER_NOT_READY'
 
-    attr_reader :value, :reason, :error_code, :error_message, :variant, :flag_metadata
+    attr_reader :value, :reason, :error_code, :error_message, :variant, :flag_metadata, :value_type
 
     def initialize(value:, reason:, error_code: nil, error_message: nil,
-                   variant: nil, flag_metadata: nil)
+                   variant: nil, flag_metadata: nil, value_type: nil)
       @value         = value
       @reason        = reason
       @error_code    = error_code
       @error_message = error_message
       @variant       = variant
       @flag_metadata = flag_metadata
+      @value_type    = value_type
     end
 
     def ==(other)
@@ -50,12 +59,13 @@ module Quonfig
         other.error_code == @error_code &&
         other.error_message == @error_message &&
         other.variant == @variant &&
-        other.flag_metadata == @flag_metadata
+        other.flag_metadata == @flag_metadata &&
+        other.value_type == @value_type
     end
     alias eql? ==
 
     def hash
-      [@value, @reason, @error_code, @error_message, @variant, @flag_metadata].hash
+      [@value, @reason, @error_code, @error_message, @variant, @flag_metadata, @value_type].hash
     end
 
     def inspect
@@ -64,6 +74,7 @@ module Quonfig
       parts << "error_message=#{@error_message.inspect}" if @error_message
       parts << "variant=#{@variant.inspect}" if @variant
       parts << "flag_metadata=#{@flag_metadata.inspect}" if @flag_metadata
+      parts << "value_type=#{@value_type.inspect}" if @value_type
       "#<Quonfig::EvaluationDetails #{parts.join(' ')}>"
     end
   end

data/lib/quonfig/version.rb

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

metadata

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