quonfig 2.0.0 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c7947aba694daddefb1357930d7d1b3e63d13c3f68ad71b1e5d33eff15584aa6
-  data.tar.gz: db349b68906829c24953f9504511200f7b837c8980ad9beb53a755586420f470
+  metadata.gz: 939842e745249a0ce6cee689801a6fe3a7cbdc56552ad88bdabaa0c36e79ef92
+  data.tar.gz: df5b171629c4b6c556f04b80a0035d5726c76929e78d11ba5382332d0e4b2293
 SHA512:
-  metadata.gz: 687f621eeff45b850bba0ab6845963abbdb8478ac18e32e1006d9f02de3b8a3ed850b75bf37ae2e907dd9512756f98fc79ae942221aaa7c17a0abd683bb9b920
-  data.tar.gz: 96792d273e01d2748f78435a75c3d8b4be405ff65470f465b646595539cf786ab4c204cab167350e66b42be03907739e49aaa01ad5b8a2228ebd7736fd4bb8e8
+  metadata.gz: 4c6822328fa6147d3816b404fe9543991d7095a5f663a2dc045f425113daba93f18da02e739c32dfce962858b00c190809acf4a62e56f1f049669bf813d8cdcd
+  data.tar.gz: 04a636c09573823cf0895c3cbbdcd2d9d79f22b875a877e55587244a2077bf1ae054007b729cc64bb8a2208e806fbdb962a7c55be38f2663c015b41d2685e09d

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 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

@@ -484,6 +484,21 @@ 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.
 
+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 +622,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 +772,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

@@ -285,34 +285,48 @@ module Quonfig
     # raise — exceptions are caught and rendered as ERROR details.
 
     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.
     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 +664,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 +696,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 +978,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 +2205,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)
@@ -2234,7 +2256,7 @@ 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.
@@ -2257,7 +2279,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 +2293,22 @@ module Quonfig
       )
     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

@@ -19,6 +19,10 @@ module Quonfig
   #   "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'
@@ -31,16 +35,17 @@ module Quonfig
     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 +55,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 +70,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.1.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: quonfig
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 2.1.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