quonfig-openfeature 1.0.3 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dfe40285fc303f81102212e0c9f7e3df54ec3c1b502df6fddab51f6b69c8b5ff
-  data.tar.gz: c76f4b36468e11354f11a133b64cfd5766ae0b3a31591d30aa70ce100b62cfd4
+  metadata.gz: 20da9ec1d24f20fa576a6430d8cd765b6d821a2cc052e0bfb8f59a5511b8447a
+  data.tar.gz: 333ea7e9395c479af7e7768bdb256c79860e7c495e009e9c51e8d14af51807e4
 SHA512:
-  metadata.gz: bf6a9629d4a67816b6e6c42da14a20b13194d63a6fda798e81249fe2029872537b5edd245cf6587f377244b23963bd5ba8fce8a6e3bcf20e142a212311ed2aee
-  data.tar.gz: a3834afebc880a6f26fe4c3f40e8cf6253393a0a1c47c996df06bef2b7c8df50e24c2c882d86bc93e86394f5b964b79274e7f3b47821d4ab55355ef49370979f
+  metadata.gz: b3319e1dbd57f6bcfa125befb424e8c2f811dc3c01f921b94c3426a0e62eed5f3ab100a49c372236e68adaa1fde3ca5d259d55af09800c40e0a4043393915c2d
+  data.tar.gz: 5cc0aecc4fcd057d426ae31381572bb27e97160dea9e154cc84e85bf668849618d5a2def62c950f3713353aef3c6f1d0c8e386055bcc35cd58b0affd1e3e0321

data/CHANGELOG.md

@@ -1,5 +1,81 @@
 # Changelog
 
+## 2.0.0 - 2026-10-27
+
+**BREAKING / UPGRADE (major, qfg-zvyy.6).** This release tracks sdk-ruby 2.0.0, the cross-SDK
+typed-getter contract. Require `quonfig` (sdk-ruby) `>= 2.0.0` (floor raised from `>= 1.11.0`). No
+change to this provider's code: it passes through the SDK's `*_details` results, so provider users
+inherit the contract below.
+
+### UPGRADE to 2.0
+
+A value a `fetch_*` method cannot read as its type returns your default with reason `ERROR` and
+error code `TYPE_MISMATCH`. Strings are never coerced, and the only number conversions are exact
+ones. What changes for provider users:
+
+- `fetch_float_value` on an int config now returns the value (`30` -> `30.0`). 1.x returned your
+  default with `TYPE_MISMATCH`.
+- `fetch_integer_value` on a double config returns the value when it is whole and within
+  +/-(2^53-1) (`3.0` -> `3`). 1.x returned your default for every double. `3.9`, `2^53` and `1e300`
+  still return your default with `TYPE_MISMATCH`, never truncated.
+- `fetch_number_value` on a `duration` config returns your default with `TYPE_MISMATCH`. 1.x
+  returned the duration in milliseconds (`30000`, reason `STATIC`). Durations are native-only: use
+  `provider.client.get_duration` (integer milliseconds). `fetch_float_value` on a duration already
+  returned your default.
+- A malformed stored int or double (for example `"twelve"`) or a malformed ENV_VAR value returns
+  your default with error code `TYPE_MISMATCH`, as in sdk-go. 1.x reported `GENERAL`. An unset
+  ENV_VAR still returns your default with `GENERAL`.
+- sdk-ruby logs one WARN per key per client when a read returns your default because of a type
+  mismatch, a malformed value, an unset ENV_VAR or a decryption failure. The line names the key and
+  types, never the value. A wrong decryption key now degrades to your defaults with these WARNs.
+- If you call the native client via `provider.client`: typed getters with a `default:` return the
+  default instead of raising, `enabled?` is true only for the bool `true` and never raises, and
+  `get_bool` on a stored string `"true"` is a type mismatch. See the sdk-ruby CHANGELOG
+  "UPGRADE to 2.0".
+
+These already held under 1.11.0 through the provider, and the new tests now pin them: a stored
+string `"true"` / `"false"` read as a boolean, a stored `"3"` read as a number, an int or bool read as
+a string, an int read as a boolean, and a string or bool read as an object all return your default
+with `TYPE_MISMATCH`.
+
+### Tests
+
+- New `test/integration/test_typed_getter_contract.rb` (31 tests) drives the real provider through
+  the OpenFeature client against the integration-test-data `getter.contract.*` fixtures. 7 of the 31
+  fail on sdk-ruby 1.11.0; all pass on 2.0.0.
+
+## 1.1.0 - 2026-10-23
+
+- **UPGRADE: raise the `quonfig` floor from `>= 1.10.0` to `>= 1.11.0`. Requires sdk-ruby 1.11.0:
+  SSE event and config body size caps, `Client#callback_errors_total`.** The provider code does not
+  change for 1.11.0. The new floor means every install of this provider gets those sdk-ruby changes:
+  an oversized SSE event (over 4 MiB) or config body (over 16 MiB) is treated as a failed attempt
+  instead of being read without limit, and `Dir.home` failures no longer raise from `Client.new`.
+  Read the 1.11.0 entry in the sdk-ruby CHANGELOG. Build and test against `quonfig` 1.11.0
+  (Gemfile.lock).
+- **UPGRADE: raise the `quonfig` floor from `>= 1.7.2` to `>= 1.10.0` (qfg-9p4i.12).** The provider
+  now uses sdk-ruby 1.10.0's init-failure surface (`on_init_failure: :fail | :wait | :continue`,
+  `init_timeout_ms`, `Client#ready?` / `#wait_for_ready`, `Quonfig::Errors::InitializationError`).
+  Read the 1.10.0 entry in the sdk-ruby CHANGELOG: `Client.new` now retries a failed boot until
+  `init_timeout_ms` (default 10s) before it raises, instead of raising on the first failed attempt.
+- **Added (minor): the provider emits OpenFeature events and its status follows `on_init_failure`
+  (init-failure design B.5).** Pass `on_init_failure:` and `init_timeout_ms:` to `Provider.new`; they
+  are forwarded to `Quonfig::Client.new` as before.
+  - `:fail` (the default): `init` raises `Quonfig::Errors::InitializationError` when no config loads,
+    so `set_provider_and_wait` raises and the provider is ERROR. sdk-ruby returns no client under
+    `:fail`, so nothing retries in the background; the process restart is the retry.
+  - `:wait`: `init` blocks until config loads. The provider is NOT_READY for the whole wait, then READY.
+  - `:continue` with no config: `init` resolves, then the provider emits `PROVIDER_ERROR` (error code
+    `PROVIDER_NOT_READY`), so its status is ERROR rather than READY while every evaluation returns the
+    code default. When the client's background retry loads config, the provider emits
+    `PROVIDER_READY`. Before, the provider reported READY and emitted no events.
+  - A client injected with `client:` gets the same treatment: if it has no config at `init`, the
+    provider reports ERROR until it heals.
+- **Fix: an evaluation before config loads reports `PROVIDER_NOT_READY`.** sdk-ruby 1.10.0's
+  `*_details` getters return error code `PROVIDER_NOT_READY` on a client with no config; the provider
+  mapped that to `GENERAL`. `Quonfig::Errors::InitializationError` (any reason, not only the timeout
+  subclass) now maps to `PROVIDER_NOT_READY` too.
+
 ## 1.0.3 - 2026-10-16
 
 - Build and test against `quonfig` 1.8.0 (Gemfile.lock). The runtime floor stays at `>= 1.7.2`: this

data/README.md

@@ -56,6 +56,26 @@ is_pro = client.fetch_boolean_value(flag_key: 'pro-feature', default_value: fals
                                      evaluation_context: ctx)
 ```
 
+## Startup failure and provider status
+
+The provider forwards `on_init_failure:` and `init_timeout_ms:` to `Quonfig::Client.new`, and its
+OpenFeature status follows the mode:
+
+| `on_init_failure` | `init` when no config loads | Provider status | Later |
+|-------------------|-----------------------------|-----------------|-------|
+| `:fail` (default) | raises `Quonfig::Errors::InitializationError` after `init_timeout_ms` (at once if the SDK key is rejected) | ERROR | No client exists, so nothing retries; restart the process |
+| `:wait`           | blocks and retries with no upper bound | NOT_READY while waiting | READY when config loads |
+| `:continue`       | returns; emits `PROVIDER_ERROR` | ERROR; evaluations return your default with `PROVIDER_NOT_READY` | emits `PROVIDER_READY` when the background retry loads config |
+
+```ruby
+provider = Quonfig::OpenFeature::Provider.new(
+  sdk_key: 'qf_sk_production_...',
+  on_init_failure: :continue, # :fail (default), :wait or :continue
+  init_timeout_ms: 10_000
+)
+OpenFeature::SDK.set_provider_and_wait(provider)
+```
+
 ## Context mapping
 
 OpenFeature context is flat; Quonfig context is nested by namespace. This provider
@@ -114,13 +134,30 @@ Quonfig features require the native `quonfig` SDK:
 
 1. **Log levels** -- `should_log?` and the `semantic_logger_filter` are native-only.
 2. **`string_list` configs** -- accessed via `fetch_object_value` and used as `Array<String>`.
-3. **`duration` configs** -- exposed only via the native `get_duration` (returns milliseconds).
+3. **`duration` configs** -- native-only: read them with `provider.client.get_duration` (integer
+   milliseconds). `fetch_float_value` and `fetch_number_value` on a duration config return your
+   default with `TYPE_MISMATCH`.
 4. **`bytes` configs** -- not accessible via OpenFeature (no binary type in OF).
 5. **`keys` / raw config inspection** -- native-only via `provider.client`.
 6. **Context keys use dot-notation** -- `"user.email"`, not nested hashes.
 7. **`targeting_key` maps to `user.id` by default** -- configure
    `targeting_key_mapping` if you target a different namespace.
 
+## Typed reads
+
+Each `fetch_*` method reads only values of its type (the cross-SDK typed-getter contract,
+`quonfig` >= 2.0.0). A value of another type returns your default with reason `ERROR` and error
+code `TYPE_MISMATCH`:
+
+- A stored string is never coerced: `"false"` is not a boolean and `"3"` is not a number.
+- Numbers convert only when exact: `fetch_float_value` on an int config returns `30.0`, and
+  `fetch_integer_value` on a double config returns the value only when it is whole and within
+  +/-(2^53-1) (`3.0` -> `3`; `3.9` is a mismatch, never truncated).
+- A malformed stored or ENV_VAR value (an int `"twelve"`) also returns your default with
+  `TYPE_MISMATCH`. An unset ENV_VAR returns your default with `GENERAL`.
+
+sdk-ruby logs one WARN per key when a read returns your default for one of these reasons.
+
 ## Offline / test mode
 
 Pass `datadir:` to evaluate against a Quonfig workspace on disk -- the same

data/VERSION

@@ -1 +1 @@
-1.0.3
+2.0.0

data/lib/quonfig/openfeature/errors.rb

@@ -21,7 +21,7 @@ module Quonfig
         return ErrorCode::TYPE_MISMATCH if defined?(::Quonfig::Errors::TypeMismatchError) && err.is_a?(::Quonfig::Errors::TypeMismatchError)
 
         if (defined?(::Quonfig::Errors::UninitializedError) && err.is_a?(::Quonfig::Errors::UninitializedError)) ||
-           (defined?(::Quonfig::Errors::InitializationTimeoutError) && err.is_a?(::Quonfig::Errors::InitializationTimeoutError))
+           (defined?(::Quonfig::Errors::InitializationError) && err.is_a?(::Quonfig::Errors::InitializationError))
           return ErrorCode::PROVIDER_NOT_READY
         end
 

data/lib/quonfig/openfeature/provider.rb

@@ -31,9 +31,26 @@ module Quonfig
     #
     #   client = OpenFeature::SDK.build_client
     #   client.fetch_boolean_value(flag_key: 'my-flag', default_value: false)
+    #
+    # Provider status follows the SDK's +on_init_failure+ mode (init-failure
+    # design B.5). Pass +on_init_failure:+ and +init_timeout_ms:+ through
+    # +Provider.new+; they are forwarded to +Quonfig::Client.new+.
+    #
+    #   * +:fail+ (default): +init+ raises, so the provider is ERROR. sdk-ruby
+    #     returns no client, so nothing retries; restart the process.
+    #   * +:wait+: +init+ blocks until config loads (NOT_READY), then READY.
+    #   * +:continue+: +init+ resolves; with no config yet the provider emits
+    #     PROVIDER_ERROR (ERROR, evaluations return the default with
+    #     PROVIDER_NOT_READY), then PROVIDER_READY when the client heals.
     class Provider
+      include ::OpenFeature::SDK::Provider::EventEmitter
+
       NAME = 'quonfig'
 
+      # How long the heal watcher waits for OpenFeature to record the READY it
+      # dispatches when +init+ returns, before it reports PROVIDER_ERROR.
+      INIT_DISPATCH_WAIT_S = 5
+
       ResolutionDetails = ::OpenFeature::SDK::Provider::ResolutionDetails
       Reason            = ::OpenFeature::SDK::Provider::Reason
       ErrorCode         = ::OpenFeature::SDK::Provider::ErrorCode
@@ -63,16 +80,19 @@ module Quonfig
           environment: environment,
           extra: quonfig_options
         )
-        @initialized = !@client.nil?
+        @initialized = false
       end
 
       # Initialize the underlying Quonfig client. Called by
-      # +OpenFeature::SDK.set_provider_and_wait+.
+      # +OpenFeature::SDK.set_provider_and_wait+. Raises under
+      # +on_init_failure: :fail+ when no config loads, which OpenFeature
+      # records as ERROR.
       def init(_evaluation_context = nil)
         return if @initialized
 
-        @client = ::Quonfig::Client.new(@quonfig_options)
+        @client ||= ::Quonfig::Client.new(@quonfig_options)
         @initialized = true
+        watch_for_heal(@client) unless client_ready?(@client)
         nil
       end
 
@@ -83,6 +103,8 @@ module Quonfig
         @client = nil
         @initialized = false
         client&.stop
+        @heal_thread&.join(1)
+        @heal_thread = nil
         nil
       end
 
@@ -141,6 +163,41 @@ module Quonfig
 
       private
 
+      def client_ready?(client)
+        !client.respond_to?(:ready?) || client.ready?
+      end
+
+      # +on_init_failure: :continue+ left the client without config. Report
+      # ERROR once OpenFeature has recorded the READY it dispatches after +init+
+      # returns, then READY when the client's background retry heals.
+      def watch_for_heal(client)
+        @heal_thread = Thread.new do
+          await_init_dispatch
+          unless client.ready?
+            emit_event(::OpenFeature::SDK::ProviderEvent::PROVIDER_ERROR,
+                       error_code: ErrorCode::PROVIDER_NOT_READY,
+                       message: 'Quonfig has no config yet (on_init_failure: :continue); ' \
+                                'serving code defaults while it retries')
+          end
+          emit_event(::OpenFeature::SDK::ProviderEvent::PROVIDER_READY) if client.wait_for_ready && @client.equal?(client)
+        end
+      end
+
+      # OpenFeature dispatches PROVIDER_READY after +init+ returns. Wait for it
+      # so our PROVIDER_ERROR lands after it, not before. +provider_state+ is
+      # private in openfeature-sdk 0.5.x and public in 0.6.x.
+      def await_init_dispatch
+        config = @configuration
+        return unless config.respond_to?(:provider_state, true)
+
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + INIT_DISPATCH_WAIT_S
+        while config.send(:provider_state, self) == ::OpenFeature::SDK::ProviderState::NOT_READY
+          break if Process.clock_gettime(Process::CLOCK_MONOTONIC) > deadline
+
+          sleep 0.01
+        end
+      end
+
       # Map a Quonfig::EvaluationDetails to the OpenFeature ResolutionDetails
       # the SDK consumes. The Quonfig SDK's *_details methods don't raise, so
       # this is a pure mapping layer.
@@ -187,6 +244,7 @@ module Quonfig
         case error_code
         when ::Quonfig::EvaluationDetails::ERROR_FLAG_NOT_FOUND then ErrorCode::FLAG_NOT_FOUND
         when ::Quonfig::EvaluationDetails::ERROR_TYPE_MISMATCH  then ErrorCode::TYPE_MISMATCH
+        when ::Quonfig::EvaluationDetails::ERROR_PROVIDER_NOT_READY then ErrorCode::PROVIDER_NOT_READY
         else ErrorCode::GENERAL
         end
       end
@@ -204,7 +262,7 @@ module Quonfig
 
         mapped_ctx = Context.map_context(evaluation_context, @targeting_key_mapping)
         yield(client, mapped_ctx)
-      rescue ::Quonfig::Errors::UninitializedError, ::Quonfig::Errors::InitializationTimeoutError => e
+      rescue ::Quonfig::Errors::UninitializedError, ::Quonfig::Errors::InitializationError => e
         ResolutionDetails.new(value: default_value, reason: Reason::ERROR,
                               error_code: ErrorCode::PROVIDER_NOT_READY,
                               error_message: e.message)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: quonfig-openfeature
 version: !ruby/object:Gem::Version
-  version: 1.0.3
+  version: 2.0.0
 platform: ruby
 authors:
 - Jeff Dwyer
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-16 00:00:00.000000000 Z
+date: 2026-10-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: openfeature-sdk
@@ -30,14 +30,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.7.2
+        version: 2.0.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.7.2
+        version: 2.0.0
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement