openfeature-sdk 0.6.5 → 0.6.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 70a393d81225d8b8b546f985dffee74d8b12451e1b9c18d348e6ac3d6a7781e6
-  data.tar.gz: 960f7f7ba3e704965b1dcb1d38c800d162874a9abf423ce0dc09695e8e7b7372
+  metadata.gz: 93f85fdb9eb64b634a3267d0987415f3e4b9033a9d864e80478dfde83074fa7d
+  data.tar.gz: 14e94971fdae29a56d31db9d8ee44716b805b6783e0d381ac04e6348168ccf67
 SHA512:
-  metadata.gz: e166c0c2698e277129734166ec0e0ed33d38329e090fa2760f720d653df93037e599ce83ba14eea803c99bb3be5b7c301e2e522dc99cc47f6299ce41699be451
-  data.tar.gz: f74b128a0a376b5f934940226d5a96906b21500373afbce98d52267580a69fab59cc5b0b043f90546bfbf7ed3393ae5033d510e80c50f5abc57a77f10d5a93c7
+  metadata.gz: c1e726bae4617d91ed82f676270bb51b7355e8694fac68a76af5f8ea046ed60c33d4c31b0a716827ad61edffe2849c3eb444c614975ac8a09707dcf620286c03
+  data.tar.gz: 47d740d86cac2c493058c0f35aa6c2489d89f0502e8df3eb9ba850585777934478fe2dcf500b7eac9b71c96cfb2c857bc6026e9d1214e7876bc385788fcf6f18

data/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.6.5"
+  ".": "0.6.7"
 }

data/.ruby-version

@@ -1 +1 @@
-4.0.2
+4.0.7

data/.tool-versions

@@ -1 +1 @@
-ruby 4.0.2
+ruby 4.0.7

data/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## [0.6.7](https://github.com/open-feature/ruby-sdk/compare/v0.6.6...v0.6.7) (2026-10-23)
+
+
+### Features
+
+* pass the bound domain to provider init and support domain-scoped providers ([#345](https://github.com/open-feature/ruby-sdk/issues/345)) ([f3cf6b7](https://github.com/open-feature/ruby-sdk/commit/f3cf6b76c06297aa4c0a2a95ea1055f816269e3b))
+
+
+### Bug Fixes
+
+* return defaults instead of raising from client calls ([#346](https://github.com/open-feature/ruby-sdk/issues/346)) ([481f21c](https://github.com/open-feature/ruby-sdk/commit/481f21cfe70365de92c6ece3eb92c40117a7e1c5))
+
+## [0.6.6](https://github.com/open-feature/ruby-sdk/compare/v0.6.5...v0.6.6) (2026-10-22)
+
+
+### Features
+
+* add PROVIDER_RECONCILING and PROVIDER_CONTEXT_CHANGED events ([#338](https://github.com/open-feature/ruby-sdk/issues/338)) ([2b93aa4](https://github.com/open-feature/ruby-sdk/commit/2b93aa4daf7087a818d0b758c7978e7ad3c1c589))
+* support variant flags in InMemoryProvider ([#340](https://github.com/open-feature/ruby-sdk/issues/340)) ([1e4b168](https://github.com/open-feature/ruby-sdk/commit/1e4b168373e39522c4884e34383730d48772b95f))
+
+
+### Bug Fixes
+
+* carry provider error codes through hooks ([#339](https://github.com/open-feature/ruby-sdk/issues/339)) ([b9e586c](https://github.com/open-feature/ruby-sdk/commit/b9e586c518a4b8e85facbb90e123c347b0db33e5))
+
 ## [0.6.5](https://github.com/open-feature/ruby-sdk/compare/v0.6.4...v0.6.5) (2026-03-18)
 
 

data/CLAUDE.md

@@ -4,7 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Overview
 
-This is the official OpenFeature SDK for Ruby — an implementation of the [OpenFeature specification](https://openfeature.dev) providing a vendor-agnostic API for feature flag evaluation. Published as the `openfeature-sdk` gem. Requires Ruby >= 3.1.
+This is the official OpenFeature SDK for Ruby — an implementation of the [OpenFeature specification](https://openfeature.dev) providing a vendor-agnostic API for feature flag evaluation. Published as the `openfeature-sdk` gem. Requires Ruby >= 3.4.
 
 ## Commands
 

data/Gemfile

@@ -12,13 +12,13 @@ group :development, :test do
   gem "rspec", "~> 3.13.0"
   gem "standard"
   gem "standard-performance"
-  gem "simplecov", "~> 0.22.0"
-  gem "simplecov-cobertura", "~> 3.0"
-  gem "steep", "~> 1.9"
+  gem "simplecov", "~> 1.3.0"
+  gem "simplecov-cobertura", "~> 4.0"
+  gem "steep", "~> 2.0"
   gem "timecop", "~> 0.9.10"
 end
 
 group :test do
-  gem "cucumber", "~> 10.0"
+  gem "cucumber", "~> 11.0"
   gem "logger"
 end

data/Gemfile.lock

@@ -1,116 +1,92 @@
 PATH
   remote: .
   specs:
-    openfeature-sdk (0.6.5)
+    openfeature-sdk (0.6.7)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    activesupport (8.1.2)
-      base64
-      bigdecimal
-      concurrent-ruby (~> 1.0, >= 1.3.1)
-      connection_pool (>= 2.2.5)
-      drb
-      i18n (>= 1.6, < 2)
-      json
-      logger (>= 1.4.2)
-      minitest (>= 5.1)
-      securerandom (>= 0.3)
-      tzinfo (~> 2.0, >= 2.0.5)
-      uri (>= 0.13.1)
     ast (2.4.3)
     base64 (0.3.0)
-    bigdecimal (4.0.1)
+    bigdecimal (4.1.3)
     builder (3.3.0)
-    concurrent-ruby (1.3.6)
-    connection_pool (3.0.2)
-    csv (3.3.5)
-    cucumber (10.2.0)
+    concurrent-ruby (1.3.8)
+    csv (3.3.6)
+    cucumber (11.1.1)
       base64 (~> 0.2)
       builder (~> 3.2)
       cucumber-ci-environment (> 9, < 12)
-      cucumber-core (> 15, < 17)
+      cucumber-core (>= 16.2.0, < 17)
       cucumber-cucumber-expressions (> 17, < 20)
-      cucumber-html-formatter (> 21, < 23)
+      cucumber-html-formatter (> 21, < 24)
       diff-lcs (~> 1.5)
       logger (~> 1.6)
       mini_mime (~> 1.1)
       multi_test (~> 1.1)
-      sys-uname (~> 1.3)
+      sys-uname (~> 1.5)
     cucumber-ci-environment (11.0.0)
     cucumber-core (16.2.0)
       cucumber-gherkin (> 36, < 40)
       cucumber-messages (> 31, < 33)
       cucumber-tag-expressions (> 6, < 9)
-    cucumber-cucumber-expressions (19.0.0)
+    cucumber-cucumber-expressions (19.0.1)
       bigdecimal
-    cucumber-gherkin (39.0.0)
+    cucumber-gherkin (39.1.0)
       cucumber-messages (>= 31, < 33)
-    cucumber-html-formatter (22.3.0)
+    cucumber-html-formatter (23.1.0)
       cucumber-messages (> 23, < 33)
-    cucumber-messages (32.2.0)
+    cucumber-messages (32.3.1)
     cucumber-tag-expressions (8.1.0)
-    date (3.5.1)
     debug (1.11.1)
       irb (~> 1.10)
       reline (>= 0.3.8)
     diff-lcs (1.6.2)
-    docile (1.4.1)
-    drb (2.2.3)
-    erb (6.0.2)
-    ffi (1.17.3)
-    fileutils (1.8.0)
-    i18n (1.14.8)
-      concurrent-ruby (~> 1.0)
-    io-console (0.8.2)
-    irb (1.17.0)
+    erb (6.0.7)
+    ffi (1.17.4)
+    fileutils (1.8.1)
+    io-console (0.9.4)
+    irb (1.18.0)
       pp (>= 0.6.0)
       prism (>= 1.3.0)
       rdoc (>= 4.0.0)
       reline (>= 0.4.2)
-    json (2.18.1)
-    language_server-protocol (3.17.0.5)
+    json (3.1.0)
+    language_server-protocol (3.17.0.6)
     lint_roller (1.1.0)
-    listen (3.10.0)
+    listen (3.10.1)
       logger
       rb-fsevent (~> 0.10, >= 0.10.3)
       rb-inotify (~> 0.9, >= 0.9.10)
     logger (1.7.0)
-    markly (0.15.2)
+    markly (0.19.0)
     memoist3 (1.0.0)
     mini_mime (1.1.5)
-    minitest (6.0.2)
-      drb (~> 2.0)
-      prism (~> 1.5)
     multi_test (1.1.0)
-    mutex_m (0.3.0)
-    parallel (1.27.0)
-    parser (3.3.10.2)
+    parallel (2.3.0)
+    parser (3.3.12.0)
       ast (~> 2.4.1)
       racc
-    pp (0.6.3)
+    pp (0.6.4)
       prettyprint
-    prettyprint (0.2.0)
+    prettyprint (0.2.1)
     prism (1.9.0)
-    psych (5.3.1)
-      date
-      stringio
     racc (1.8.1)
     rainbow (3.1.1)
-    rake (13.3.1)
+    rake (13.4.2)
     rb-fsevent (0.11.2)
     rb-inotify (0.11.1)
       ffi (~> 1.0)
-    rbs (3.10.3)
+    rbs (4.2.0)
       logger
+      prism (>= 1.6.0)
       tsort
-    rdoc (7.2.0)
+    rdoc (8.1.0)
       erb
-      psych (>= 4.0.0)
+      prism (>= 1.6.0)
+      rbs (>= 4.0.0)
       tsort
-    regexp_parser (2.11.3)
-    reline (0.6.3)
+    regexp_parser (2.13.1)
+    reline (0.7.0)
       io-console (~> 0.5)
     rexml (3.4.4)
     rspec (3.13.2)
@@ -126,18 +102,18 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
     rspec-support (3.13.7)
-    rubocop (1.84.2)
-      json (~> 2.3)
+    rubocop (1.91.0)
+      json (>= 2.3)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.1.0)
-      parallel (~> 1.10)
+      parallel (>= 1.10)
       parser (>= 3.3.0.2)
       rainbow (>= 2.2.2, < 4.0)
       regexp_parser (>= 2.9.3, < 3.0)
       rubocop-ast (>= 1.49.0, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 2.4.0, < 4.0)
-    rubocop-ast (1.49.0)
+    rubocop-ast (1.50.0)
       parser (>= 3.3.7.2)
       prism (~> 1.7)
     rubocop-performance (1.26.1)
@@ -146,19 +122,14 @@ GEM
       rubocop-ast (>= 1.47.1, < 2.0)
     ruby-progressbar (1.13.0)
     securerandom (0.4.1)
-    simplecov (0.22.0)
-      docile (~> 1.1)
-      simplecov-html (~> 0.11)
-      simplecov_json_formatter (~> 0.1)
-    simplecov-cobertura (3.1.0)
+    simplecov (1.3.2)
+    simplecov-cobertura (4.0.0)
       rexml
-      simplecov (~> 0.19)
-    simplecov-html (0.13.2)
-    simplecov_json_formatter (0.1.4)
-    standard (1.54.0)
+      simplecov (~> 1.0)
+    standard (1.57.0)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.0)
-      rubocop (~> 1.84.0)
+      rubocop (~> 1.91.0)
       standard-custom (~> 1.0.0)
       standard-performance (~> 1.8)
     standard-custom (1.0.2)
@@ -167,8 +138,7 @@ GEM
     standard-performance (1.9.0)
       lint_roller (~> 1.1)
       rubocop-performance (~> 1.26.0)
-    steep (1.10.0)
-      activesupport (>= 5.1)
+    steep (2.1.0)
       concurrent-ruby (>= 1.1.10)
       csv (>= 3.0.9)
       fileutils (>= 1.1.0)
@@ -176,29 +146,31 @@ GEM
       language_server-protocol (>= 3.17.0.4, < 4.0)
       listen (~> 3.0)
       logger (>= 1.3.0)
-      mutex_m (>= 0.3.0)
-      parser (>= 3.1)
+      parser (>= 3.2)
+      prism (>= 0.25.0)
       rainbow (>= 2.2.2, < 4.0)
-      rbs (~> 3.9)
+      rbs (~> 4.2)
       securerandom (>= 0.1)
       strscan (>= 1.0.0)
       terminal-table (>= 2, < 5)
       uri (>= 0.12.0)
-    stringio (3.2.0)
-    strscan (3.1.7)
-    sys-uname (1.5.0)
+    strscan (3.1.8)
+    sys-uname (1.5.1)
+      ffi (~> 1.1)
+      memoist3 (~> 1.0.0)
+    sys-uname (1.5.1-universal-mingw32)
       ffi (~> 1.1)
       memoist3 (~> 1.0.0)
+      win32ole
     terminal-table (4.0.0)
       unicode-display_width (>= 1.1.1, < 4)
-    timecop (0.9.10)
+    timecop (0.9.11)
     tsort (0.2.0)
-    tzinfo (2.0.6)
-      concurrent-ruby (~> 1.0)
-    unicode-display_width (3.2.0)
-      unicode-emoji (~> 4.1)
-    unicode-emoji (4.2.0)
-    uri (1.1.1)
+    unicode-display_width (3.3.0)
+      unicode-emoji (~> 4.3)
+    unicode-emoji (4.3.0)
+    uri (1.1.2)
+    win32ole (1.9.3)
 
 PLATFORMS
   arm64-darwin-21
@@ -214,19 +186,19 @@ PLATFORMS
   x86_64-linux
 
 DEPENDENCIES
-  cucumber (~> 10.0)
+  cucumber (~> 11.0)
   debug
   logger
   markly
   openfeature-sdk!
   rake (~> 13.0)
   rspec (~> 3.13.0)
-  simplecov (~> 0.22.0)
-  simplecov-cobertura (~> 3.0)
+  simplecov (~> 1.3.0)
+  simplecov-cobertura (~> 4.0)
   standard
   standard-performance
-  steep (~> 1.9)
+  steep (~> 2.0)
   timecop (~> 0.9.10)
 
 BUNDLED WITH
-   2.3.25
+  4.0.12

data/README.md

@@ -17,8 +17,8 @@
   </a>
   <!-- x-release-please-start-version -->
 
-  <a href="https://github.com/open-feature/ruby-sdk/releases/tag/v0.6.5">
-    <img alt="Release" src="https://img.shields.io/static/v1?label=release&message=v0.6.5&color=blue&style=for-the-badge" />
+  <a href="https://github.com/open-feature/ruby-sdk/releases/tag/v0.6.7">
+    <img alt="Release" src="https://img.shields.io/static/v1?label=release&message=v0.6.7&color=blue&style=for-the-badge" />
   </a>
 
   <!-- x-release-please-end -->
@@ -70,7 +70,6 @@ gem install openfeature-sdk
 
 ```ruby
 require 'open_feature/sdk'
-require 'json' # For JSON.dump
 
 # API Initialization and configuration
 
@@ -79,7 +78,13 @@ OpenFeature::SDK.configure do |config|
   config.set_provider(OpenFeature::SDK::Provider::InMemoryProvider.new(
     {
       "flag1" => true,
-      "flag2" => 1
+      "flag2" => 1,
+      # Variant flags report a variant and reason, and can target on the evaluation context
+      "flag3" => OpenFeature::SDK::Provider::InMemoryProvider::Flag.new(
+        variants: {"on" => true, "off" => false},
+        default_variant: "off",
+        context_evaluator: ->(ctx) { "on" if ctx&.targeting_key == "beta-user" }
+      )
     }
   ))
 end
@@ -91,7 +96,7 @@ client = OpenFeature::SDK.build_client
 bool_value = client.fetch_boolean_value(flag_key: 'boolean_flag', default_value: false)
 
 # a details method is also available for more information about the flag evaluation
-# see `ResolutionDetails` for more info
+# see `EvaluationDetails` for more info
 bool_details = client.fetch_boolean_details(flag_key: 'boolean_flag', default_value: false)
 
 # fetching string value feature flag
@@ -158,9 +163,6 @@ rescue OpenFeature::SDK::ProviderInitializationError => e
   puts "Original error: #{e.original_error}"
 end
 
-# With custom timeout (default is 30 seconds)
-OpenFeature::SDK.set_provider_and_wait(my_provider, timeout: 60)
-
 # Domain-specific provider
 OpenFeature::SDK.set_provider_and_wait(my_provider, domain: "feature-flags")
 
@@ -299,14 +301,15 @@ legacy_flag_client = OpenFeature::SDK.build_client(domain: "legacy_flags")
 
 Events allow you to react to state changes in the provider or underlying flag management system, such as flag definition changes, provider readiness, or error conditions.
 Initialization events (`PROVIDER_READY` on success, `PROVIDER_ERROR` on failure) are dispatched for every provider.
-Some providers support additional events, such as `PROVIDER_CONFIGURATION_CHANGED`.
+Some providers emit additional events: `PROVIDER_CONFIGURATION_CHANGED`, `PROVIDER_STALE`, `PROVIDER_RECONCILING` and `PROVIDER_CONTEXT_CHANGED`.
+Handlers receive a hash with the `provider_name` and any details the provider sent, such as `message` or `error_code`.
 
 Please refer to the documentation of the provider you're using to see what events are supported.
 
 ```ruby
 # Register event handlers at the API (global) level
 ready_handler = ->(event_details) do
-  puts "Provider #{event_details[:provider].metadata.name} is ready!"
+  puts "Provider #{event_details[:provider_name]} is ready!"
 end
 
 OpenFeature::SDK.add_handler(OpenFeature::SDK::ProviderEvent::PROVIDER_READY, ready_handler)
@@ -349,6 +352,9 @@ This should only be called when your application is in the process of shutting d
 OpenFeature::SDK.shutdown
 ```
 
+The SDK also shuts down a replaced provider once no domain uses it.
+Events from shut-down providers are ignored.
+
 Individual providers can implement a `shutdown` method to perform cleanup:
 
 ```ruby
@@ -440,13 +446,21 @@ You’ll then need to write the provider by implementing the `Provider` duck.
 
 ```ruby
 class MyProvider
-  def init
+  # Both arguments are optional; declare only the ones you need.
+  # `domain` is the domain the provider was bound to, or nil for the default provider.
+  def init(evaluation_context = nil, domain: nil)
     # Perform any initialization steps with flag management system here
     # Return value is ignored
     # **Note** The OpenFeature spec defines a lifecycle method called `initialize` to be called when a new provider is set.
     # To avoid conflicting with the Ruby `initialize` method, this method should be named `init` when creating a provider.
   end
 
+  # Optional: return true if this provider keeps state for a single domain.
+  # The SDK then raises ArgumentError if the same instance is bound to a second domain.
+  def domain_scoped?
+    false
+  end
+
   def shutdown
     # Perform any shutdown/reclamation steps with flag management system here
     # Return value is ignored
@@ -454,6 +468,8 @@ class MyProvider
 
   def fetch_boolean_value(flag_key:, default_value:, evaluation_context: nil)
     # Retrieve a boolean value from provider source
+    # To signal an error, return ResolutionDetails with an error_code, or raise
+    # OpenFeature::SDK::EvaluationError.new("message", error_code: OpenFeature::SDK::Provider::ErrorCode::FLAG_NOT_FOUND)
   end
 
   def fetch_string_value(flag_key:, default_value:, evaluation_context: nil)

data/lib/open_feature/sdk/api.rb

@@ -7,6 +7,7 @@ require_relative "configuration"
 require_relative "evaluation_context"
 require_relative "evaluation_context_builder"
 require_relative "evaluation_details"
+require_relative "evaluation_error"
 require_relative "client_metadata"
 require_relative "hooks"
 require_relative "client"

data/lib/open_feature/sdk/client.rb

@@ -56,12 +56,15 @@ module OpenFeature
         built_context = build_evaluation_context(evaluation_context)
 
         @provider.track(tracking_event_name, evaluation_context: built_context, tracking_event_details: tracking_event_details)
+      rescue
+        nil
       end
 
       RESULT_TYPE.each do |result_type|
         SUFFIXES.each do |suffix|
           class_eval <<-RUBY, __FILE__, __LINE__ + 1
             def fetch_#{result_type}_#{suffix}(flag_key:, default_value:, evaluation_context: nil, hooks: [], hook_hints: nil)
+              validate_default_value_type(:#{result_type}, default_value)
               evaluation_details = fetch_details(type: :#{result_type}, flag_key:, default_value:, evaluation_context:, invocation_hooks: hooks, hook_hints: hook_hints)
               #{"evaluation_details.value" if suffix == :value}
             end
@@ -72,15 +75,13 @@ module OpenFeature
       private
 
       def fetch_details(type:, flag_key:, default_value:, evaluation_context: nil, invocation_hooks: [], hook_hints: nil)
-        validate_default_value_type(type, default_value)
-
         built_context = build_evaluation_context(evaluation_context)
 
         # Assemble ordered hooks: API → Client → Invocation → Provider (spec 4.4.2)
         provider_hooks = @provider.respond_to?(:hooks) ? Array(@provider.hooks) : []
         ordered_hooks = [*OpenFeature::SDK.hooks, *@hooks, *invocation_hooks, *provider_hooks]
 
-        # Check for short-circuit conditions (spec 1.7.6 + 1.7.7)
+        # Short-circuit NOT_READY/FATAL providers (required by evaluation_v2.feature)
         short_circuit_code = nil
         if OpenFeature::SDK.configuration.provider_tracked?(@provider)
           short_circuit_code = short_circuit_error_code(provider_status)
@@ -97,17 +98,7 @@ module OpenFeature
             return EvaluationDetails.new(flag_key: flag_key, resolution_details: resolution)
           end
 
-          begin
-            return evaluate_flag(type: type, flag_key: flag_key, default_value: default_value, evaluation_context: built_context)
-          rescue => e
-            resolution = Provider::ResolutionDetails.new(
-              value: default_value,
-              error_code: Provider::ErrorCode::GENERAL,
-              reason: Provider::Reason::ERROR,
-              error_message: e.message
-            )
-            return EvaluationDetails.new(flag_key: flag_key, resolution_details: resolution)
-          end
+          return evaluate_flag(type: type, flag_key: flag_key, default_value: default_value, evaluation_context: built_context)
         end
 
         hook_context = Hooks::HookContext.new(
@@ -130,7 +121,6 @@ module OpenFeature
         executor = Hooks::HookExecutor.new(logger: OpenFeature::SDK.configuration.logger)
 
         if short_circuit_code
-          # Spec 1.7.6 + 1.7.7: short-circuit must still run error hooks and finally hooks
           resolution = Provider::ResolutionDetails.new(
             value: default_value,
             error_code: short_circuit_code,
@@ -144,6 +134,15 @@ module OpenFeature
             evaluate_flag(type: type, flag_key: flag_key, default_value: default_value, evaluation_context: hctx.evaluation_context)
           end
         end
+      rescue StandardError, NotImplementedError => e
+        # Spec 1.4.10 and 1.4.11: report through the details, never raise or log. NotImplementedError is the abstract-method idiom.
+        resolution = Provider::ResolutionDetails.new(
+          value: default_value,
+          error_code: EvaluationError.code_for(e),
+          reason: Provider::Reason::ERROR,
+          error_message: e.message
+        )
+        EvaluationDetails.new(flag_key: flag_key, resolution_details: resolution)
       end
 
       def evaluate_flag(type:, flag_key:, default_value:, evaluation_context:)
@@ -154,9 +153,9 @@ module OpenFeature
           evaluation_context: evaluation_context
         )
 
-        if TYPE_CLASS_MAP[type].none? { |klass| resolution_details.value.is_a?(klass) }
+        if resolution_details.error_code || TYPE_CLASS_MAP[type].none? { |klass| resolution_details.value.is_a?(klass) }
           resolution_details.value = default_value
-          resolution_details.error_code = Provider::ErrorCode::TYPE_MISMATCH
+          resolution_details.error_code ||= Provider::ErrorCode::TYPE_MISMATCH
           resolution_details.reason = Provider::Reason::ERROR
           resolution_details.variant = nil
         end

data/lib/open_feature/sdk/configuration.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
-require "timeout"
 require_relative "api"
 require_relative "provider_initialization_error"
+require_relative "evaluation_error"
 require_relative "event_dispatcher"
 require_relative "provider_event"
 require_relative "provider_state_registry"
@@ -20,9 +20,14 @@ module OpenFeature
       attr_accessor :evaluation_context, :hooks, :transaction_context_propagator
       attr_reader :logger
 
+      # One per registration; +done+ is closed once init finishes, so waiters can pop on it
+      InitAttempt = Struct.new(:state, :error, :done)
+      private_constant :InitAttempt
+
       def initialize
         @hooks = []
         @providers = {}
+        @init_attempts = {}.compare_by_identity
         @provider_mutex = Mutex.new
         @logger = nil
         @event_dispatcher = EventDispatcher.new(@logger)
@@ -89,11 +94,17 @@ module OpenFeature
       end
 
       def shutdown
-        providers_to_shutdown = @provider_mutex.synchronize { @providers.values.uniq(&:object_id) }
+        # Unbind before shutting down so events that arrive mid-shutdown are dropped
+        providers_to_shutdown = @provider_mutex.synchronize do
+          bound = @providers.values.uniq(&:object_id)
+          @providers = {}
+          bound
+        end
 
         providers_to_shutdown.each do |prov|
-          # Spec 1.7.9: Set provider state to NOT_READY before shutdown
+          # Spec 1.7.6: Set provider state to NOT_READY before shutdown
           @provider_state_registry.set_initial_state(prov, ProviderState::NOT_READY)
+          prov.send(:detach) if prov.is_a?(Provider::EventEmitter)
           prov.shutdown if prov.respond_to?(:shutdown)
         rescue => e
           @logger&.warn("Error shutting down provider #{prov&.class&.name || "unknown"}: #{e.message}")
@@ -112,6 +123,9 @@ module OpenFeature
         @provider_state_registry.clear
         @provider_mutex.synchronize do
           @providers.clear
+          # Release anyone waiting on an init that shutdown cut short
+          @init_attempts.each_value { |attempt| attempt.done.close }
+          @init_attempts.clear
         end
         @hooks.clear
         @evaluation_context = nil
@@ -123,31 +137,41 @@ module OpenFeature
         context_for_init = @evaluation_context
 
         old_provider = nil
+        attempt = nil
         needs_init = false
+        init_thread = nil
         needs_shutdown = false
 
+        # Provider code runs before taking the lock: it may call back into the SDK
+        scoped = domain_scoped?(provider)
+
         @provider_mutex.synchronize do
+          validate_domain_scoped_binding!(provider, domain, scoped)
+
           old_provider = @providers[domain]
 
           new_providers = @providers.dup
           new_providers[domain] = provider
           @providers = new_providers
 
-          # Spec 1.1.2.2: Only initialize if the provider is not already active
-          # (i.e., not already bound to another domain)
-          already_active = @providers.any? { |d, p| d != domain && p.equal?(provider) && @provider_state_registry.tracked?(p) }
-          needs_init = !already_active
+          # Spec 1.1.2.2: initialize once per registration; a failed init is retried on the next set
+          attempt = @init_attempts[provider]
+          needs_init = attempt.nil? || attempt.state == :failed
 
           if needs_init
+            attempt = @init_attempts[provider] = InitAttempt.new(:running, nil, Thread::Queue.new)
             @provider_state_registry.set_initial_state(provider)
             provider.send(:attach, self) if provider.is_a?(Provider::EventEmitter)
           end
 
           # Spec 1.1.2.3: Only shutdown old provider if it's no longer bound to any domain
           if old_provider && !old_provider.equal?(provider)
-            still_bound = @providers.any? { |_, p| p.equal?(old_provider) }
-            needs_shutdown = !still_bound
-            @provider_state_registry.remove_provider(old_provider) unless still_bound
+            needs_shutdown = !provider_bound?(old_provider)
+            if needs_shutdown
+              @init_attempts.delete(old_provider)
+              @provider_state_registry.remove_provider(old_provider)
+              old_provider.send(:detach) if old_provider.is_a?(Provider::EventEmitter)
+            end
           end
         end
 
@@ -163,53 +187,74 @@ module OpenFeature
         # Initialize provider outside the mutex to avoid blocking other operations
         if needs_init
           if wait_for_init
-            init_provider(provider, context_for_init, raise_on_error: true)
+            init_provider(provider, context_for_init, domain:, attempt:, raise_on_error: true)
           else
-            Thread.new do
-              init_provider(provider, context_for_init, raise_on_error: false)
+            init_thread = Thread.new do
+              init_provider(provider, context_for_init, domain:, attempt:, raise_on_error: false)
             end
           end
         elsif wait_for_init
-          # Provider already active; no init needed but still dispatch READY
+          # Already registered: wait for an init still in flight, then report its outcome
+          attempt.done.pop
+          unless attempt.state == :succeeded
+            raise attempt.error || ProviderInitializationError.new(
+              "Provider #{provider.class.name} initialization did not complete",
+              provider:,
+              error_code: Provider::ErrorCode::GENERAL
+            )
+          end
+
           dispatch_provider_event(provider, ProviderEvent::PROVIDER_READY)
         end
+      ensure
+        # Fail an attempt no init took over (e.g. a Timeout hit first), or it would stay running forever
+        finish_init_attempt(attempt, :failed) if needs_init && !init_thread
       end
 
-      def init_provider(provider, context, raise_on_error: false)
-        if provider.respond_to?(:init)
-          init_method = provider.method(:init)
-          if init_method.parameters.empty?
-            provider.init
-          else
-            provider.init(context)
-          end
-        end
+      def init_provider(provider, context, domain:, attempt:, raise_on_error: false)
+        call_init(provider, context, domain)
 
+        # Settle the attempt before handlers run, so a handler can register this provider again
+        finish_init_attempt(attempt, :succeeded)
         dispatch_provider_event(provider, ProviderEvent::PROVIDER_READY)
       rescue => e
-        # Spec 1.7.8: Propagate error code from provider if available
-        error_code = if e.respond_to?(:error_code) && e.error_code
-          e.error_code
-        else
-          Provider::ErrorCode::GENERAL
-        end
+        # Spec 1.7.5: PROVIDER_FATAL from init makes the provider FATAL
+        error_code = EvaluationError.code_for(e)
+        error = ProviderInitializationError.new(
+          "Provider #{provider.class.name} initialization failed: #{e.message}",
+          provider:,
+          error_code: error_code,
+          original_error: e
+        )
+        finish_init_attempt(attempt, :failed, error)
 
         dispatch_provider_event(provider, ProviderEvent::PROVIDER_ERROR,
           error_code: error_code,
           message: e.message)
 
-        if raise_on_error
-          raise ProviderInitializationError.new(
-            "Provider #{provider.class.name} initialization failed: #{e.message}",
-            provider:,
-            error_code: error_code,
-            original_error: e
-          )
+        raise error if raise_on_error
+      ensure
+        # Reached unsettled only when init raised something other than a StandardError
+        finish_init_attempt(attempt, :failed)
+      end
+
+      def finish_init_attempt(attempt, state, error = nil)
+        @provider_mutex.synchronize do
+          return unless attempt.state == :running
+
+          attempt.state = state
+          attempt.error = error
         end
+        attempt.done.close
       end
 
       def dispatch_provider_event(provider, event_type, details = {})
-        @provider_state_registry.update_state_from_event(provider, event_type, details)
+        # Under the replacement lock, so a late event can't re-track a replaced or shut-down provider
+        @provider_mutex.synchronize do
+          return unless provider_bound?(provider)
+
+          @provider_state_registry.update_state_from_event(provider, event_type, details)
+        end
 
         provider_name = extract_provider_name(provider)
 
@@ -222,10 +267,48 @@ module OpenFeature
 
       private
 
+      def provider_bound?(provider)
+        @providers.each_value.any? { |p| p.equal?(provider) }
+      end
+
       def extract_provider_name(provider)
         provider.respond_to?(:metadata) ? provider.metadata.name : provider.class.name
       end
 
+      def domain_scoped?(provider)
+        provider.respond_to?(:domain_scoped?) && provider.domain_scoped?
+      end
+
+      def validate_domain_scoped_binding!(provider, domain, scoped)
+        return unless scoped && provider_bound?(provider) && !@providers[domain].equal?(provider)
+
+        raise ArgumentError, "Cannot bind domain-scoped provider to more than one domain"
+      end
+
+      def call_init(provider, context, domain)
+        return unless provider.respond_to?(:init)
+
+        parameters = provider.method(:init).parameters
+        takes_domain = init_accepts_domain?(parameters)
+        if !takes_domain && domain_scoped?(provider)
+          @logger&.warn("Provider #{extract_provider_name(provider)} is domain-scoped but its init doesn't accept domain:")
+        end
+
+        args = init_accepts_evaluation_context?(parameters) ? [context] : []
+        provider.init(*args, **(takes_domain ? {domain:} : {}))
+      end
+
+      # Anonymous `**` (from `...`) and delegators' bare `*` can't be trusted to accept `domain:`
+      def init_accepts_domain?(parameters)
+        parameters.any? do |kind, name|
+          ((kind == :key || kind == :keyreq) && name == :domain) || (kind == :keyrest && name && name != :**)
+        end
+      end
+
+      def init_accepts_evaluation_context?(parameters)
+        parameters.any? { |kind, _| kind == :req || kind == :opt || kind == :rest }
+      end
+
       def run_handlers_for_provider(provider, event_type, event_details)
         # Run global handlers (API-level, no domain filtering)
         @event_dispatcher.trigger_event(event_type, event_details)

data/lib/open_feature/sdk/evaluation_error.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative "provider/error_code"
+
+module OpenFeature
+  module SDK
+    # Raised by a provider to signal an evaluation error with an OpenFeature
+    # error code (spec 2.2.7). Any exception responding to +error_code+ is
+    # honored the same way.
+    class EvaluationError < StandardError
+      # @return [String] the OpenFeature error code
+      attr_reader :error_code
+
+      def initialize(message = nil, error_code: Provider::ErrorCode::GENERAL)
+        super(message || error_code)
+        @error_code = error_code
+      end
+
+      # The error code carried by +exception+, or GENERAL when it has none.
+      # Rescues a failing reader so callers inside a rescue block never raise (spec 1.4.10).
+      def self.code_for(exception)
+        (exception.respond_to?(:error_code) && exception.error_code) || Provider::ErrorCode::GENERAL
+      rescue
+        Provider::ErrorCode::GENERAL
+      end
+    end
+  end
+end

data/lib/open_feature/sdk/hooks/hook_executor.rb

@@ -18,15 +18,15 @@ module OpenFeature
           @logger = logger
         end
 
-        # Runs error hooks and finally hooks for a short-circuit evaluation
-        # (spec 1.7.6 + 1.7.7). Before hooks and after hooks are NOT run.
+        # Runs error hooks and finally hooks for a short-circuit evaluation.
+        # Before hooks and after hooks are NOT run.
         #
         # @param ordered_hooks [Array] hooks in before-order
         # @param hook_context [HookContext] the hook context
         # @param hints [Hints] hook hints
         # @param evaluation_details [EvaluationDetails] the short-circuit result
         def run_short_circuit(ordered_hooks:, hook_context:, hints:, evaluation_details:)
-          error = StandardError.new(evaluation_details.error_code)
+          error = EvaluationError.new(evaluation_details.error_message, error_code: evaluation_details.error_code)
           run_error_hooks(ordered_hooks, hook_context, error, hints)
         ensure
           run_finally_hooks(ordered_hooks, hook_context, evaluation_details, hints)
@@ -49,7 +49,7 @@ module OpenFeature
             # Spec 4.3.6: If evaluation resulted in an error (e.g. FLAG_NOT_FOUND,
             # TYPE_MISMATCH), run error hooks instead of after hooks.
             if evaluation_details.error_code
-              error = StandardError.new(evaluation_details.error_message || evaluation_details.error_code)
+              error = EvaluationError.new(evaluation_details.error_message, error_code: evaluation_details.error_code)
               run_error_hooks(ordered_hooks, hook_context, error, hints)
             else
               run_after_hooks(ordered_hooks, hook_context, evaluation_details, hints)
@@ -61,7 +61,7 @@ module OpenFeature
               flag_key: hook_context.flag_key,
               resolution_details: Provider::ResolutionDetails.new(
                 value: hook_context.default_value,
-                error_code: Provider::ErrorCode::GENERAL,
+                error_code: EvaluationError.code_for(e),
                 reason: Provider::Reason::ERROR,
                 error_message: e.message
               )

data/lib/open_feature/sdk/hooks/logging_hook.rb

@@ -49,8 +49,7 @@ module OpenFeature
 
         def build_error_message(hook_context, exception)
           parts = base_parts("error", hook_context)
-          error_code = exception.respond_to?(:error_code) ? exception.error_code : Provider::ErrorCode::GENERAL
-          parts << "error_code=#{sanitize(error_code)}"
+          parts << "error_code=#{sanitize(EvaluationError.code_for(exception))}"
           parts << "error_message=#{sanitize(exception.message)}"
           parts << "evaluation_context=#{format_context(hook_context.evaluation_context)}" if @include_evaluation_context
           parts.join(" ")

data/lib/open_feature/sdk/provider/in_memory_provider.rb

@@ -8,6 +8,10 @@ module OpenFeature
 
         NAME = "In-memory Provider"
 
+        # A flag with named variants. +context_evaluator+ receives the evaluation
+        # context and returns a variant key; anything else falls back to +default_variant+.
+        Flag = Struct.new(:variants, :default_variant, :context_evaluator, :flag_metadata, :disabled, keyword_init: true)
+
         attr_reader :metadata
 
         def initialize(flags = {})
@@ -70,6 +74,8 @@ module OpenFeature
             return ResolutionDetails.new(value: default_value, error_code: ErrorCode::FLAG_NOT_FOUND, reason: Reason::ERROR)
           end
 
+          return resolve_variant_flag(raw_value, default_value, evaluation_context) if raw_value.is_a?(Flag)
+
           if raw_value.respond_to?(:call)
             value = raw_value.call(evaluation_context)
             ResolutionDetails.new(value: value, reason: Reason::TARGETING_MATCH)
@@ -78,6 +84,24 @@ module OpenFeature
           end
         end
 
+        def resolve_variant_flag(flag, default_value, evaluation_context)
+          flag_metadata = flag.flag_metadata
+          return ResolutionDetails.new(value: default_value, reason: Reason::DISABLED, flag_metadata:) if flag.disabled
+
+          variants = flag.variants.to_h
+          unless variants.key?(flag.default_variant)
+            return ResolutionDetails.new(value: default_value, error_code: ErrorCode::PARSE_ERROR, reason: Reason::ERROR, flag_metadata:)
+          end
+
+          matched = flag.context_evaluator&.call(evaluation_context)
+          if variants.key?(matched)
+            return ResolutionDetails.new(value: variants[matched], variant: matched, reason: Reason::TARGETING_MATCH, flag_metadata:)
+          end
+
+          reason = flag.context_evaluator ? Reason::DEFAULT : Reason::STATIC
+          ResolutionDetails.new(value: variants[flag.default_variant], variant: flag.default_variant, reason:, flag_metadata:)
+        end
+
         def emit_provider_changed(flag_keys)
           return unless configuration_attached?
 

data/lib/open_feature/sdk/provider_event.rb

@@ -13,12 +13,16 @@ module OpenFeature
       PROVIDER_ERROR = "PROVIDER_ERROR"
       PROVIDER_CONFIGURATION_CHANGED = "PROVIDER_CONFIGURATION_CHANGED"
       PROVIDER_STALE = "PROVIDER_STALE"
+      PROVIDER_RECONCILING = "PROVIDER_RECONCILING"
+      PROVIDER_CONTEXT_CHANGED = "PROVIDER_CONTEXT_CHANGED"
 
       ALL_EVENTS = [
         PROVIDER_READY,
         PROVIDER_ERROR,
         PROVIDER_CONFIGURATION_CHANGED,
-        PROVIDER_STALE
+        PROVIDER_STALE,
+        PROVIDER_RECONCILING,
+        PROVIDER_CONTEXT_CHANGED
       ].freeze
     end
   end

data/lib/open_feature/sdk/provider_state_registry.rb

@@ -91,7 +91,7 @@ module OpenFeature
 
       def state_from_event(event_type, event_details = nil)
         case event_type
-        when ProviderEvent::PROVIDER_READY
+        when ProviderEvent::PROVIDER_READY, ProviderEvent::PROVIDER_CONTEXT_CHANGED
           ProviderState::READY
         when ProviderEvent::PROVIDER_STALE
           ProviderState::STALE
@@ -100,7 +100,7 @@ module OpenFeature
         when ProviderEvent::PROVIDER_CONFIGURATION_CHANGED
           nil # No state change per OpenFeature spec Requirement 5.3.5
         else
-          nil # No state change for unknown events - conservative default
+          nil # PROVIDER_RECONCILING (RECONCILING status is static-context only, spec 1.7.2.1) and unknown events
         end
       end
 

data/lib/open_feature/sdk/version.rb

@@ -2,6 +2,6 @@
 
 module OpenFeature
   module SDK
-    VERSION = "0.6.5"
+    VERSION = "0.6.7"
   end
 end

data/renovate.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://docs.renovatebot.com/renovate-schema.json",
   "extends": [
-    "config:recommended",
+    "github>open-feature/community-tooling",
     ":automergeStableNonMajor",
     "security:minimumReleaseAgeNpm"
   ],

data/sig/open_feature/sdk/configuration.rbs

@@ -32,8 +32,15 @@ module OpenFeature
 
       def reset: () -> void
       def set_provider_internal: (untyped provider, domain: String?, wait_for_init: bool) -> void
-      def init_provider: (untyped provider, EvaluationContext? context, ?raise_on_error: bool) -> void
+      def init_provider: (untyped provider, EvaluationContext? context, domain: String?, attempt: untyped, ?raise_on_error: bool) -> void
+      def finish_init_attempt: (untyped attempt, Symbol state, ?ProviderInitializationError? error) -> void
       def dispatch_provider_event: (untyped provider, String event_type, ?Hash[Symbol, untyped] details) -> void
+      def provider_bound?: (untyped provider) -> bool
+      def domain_scoped?: (untyped provider) -> bool
+      def validate_domain_scoped_binding!: (untyped provider, String? domain, bool scoped) -> void
+      def call_init: (untyped provider, EvaluationContext? context, String? domain) -> void
+      def init_accepts_domain?: (Array[[Symbol, Symbol?]] parameters) -> bool
+      def init_accepts_evaluation_context?: (Array[[Symbol, Symbol?]] parameters) -> bool
       def extract_provider_name: (untyped provider) -> String
       def run_handlers_for_provider: (untyped provider, String event_type, Hash[Symbol, untyped] event_details) -> void
       def run_immediate_handler: (String event_type, _ToProc handler, Client? client) -> void

data/sig/open_feature/sdk/evaluation_error.rbs

@@ -0,0 +1,11 @@
+module OpenFeature
+  module SDK
+    class EvaluationError < StandardError
+      attr_reader error_code: String
+
+      def initialize: (?String? message, ?error_code: String) -> void
+
+      def self.code_for: (Exception exception) -> String
+    end
+  end
+end

data/sig/open_feature/sdk/provider/in_memory_provider.rbs

@@ -6,6 +6,16 @@ module OpenFeature
 
         NAME: String
 
+        class Flag < Struct[untyped]
+          attr_accessor variants: Hash[String, untyped]?
+          attr_accessor default_variant: String?
+          attr_accessor context_evaluator: (^(EvaluationContext?) -> String?)?
+          attr_accessor flag_metadata: Hash[String, untyped]?
+          attr_accessor disabled: bool?
+
+          def initialize: (?variants: Hash[String, untyped]?, ?default_variant: String?, ?context_evaluator: (^(EvaluationContext?) -> String?)?, ?flag_metadata: Hash[String, untyped]?, ?disabled: bool?) -> void
+        end
+
         attr_reader metadata: ProviderMetadata
 
         def initialize: (?Hash[String, untyped] flags) -> void
@@ -28,6 +38,7 @@ module OpenFeature
         attr_reader flags: Hash[String, untyped]
 
         def fetch_value: (flag_key: String, default_value: untyped, evaluation_context: EvaluationContext?) -> ResolutionDetails
+        def resolve_variant_flag: (Flag flag, untyped default_value, EvaluationContext? evaluation_context) -> ResolutionDetails
         def emit_provider_changed: (Array[String] flag_keys) -> void
       end
     end

data/sig/open_feature/sdk/provider.rbs

@@ -11,11 +11,15 @@ module OpenFeature
       end
 
       interface _LifecycleProvider
-        def init: (?EvaluationContext? evaluation_context) -> void
+        def init: (?EvaluationContext? evaluation_context, ?domain: String?) -> void
         def shutdown: () -> void
         def metadata: () -> ProviderMetadata
       end
 
+      interface _DomainScopedProvider
+        def domain_scoped?: () -> bool
+      end
+
       interface _TrackableProvider
         def track: (String tracking_event_name, ?evaluation_context: EvaluationContext?, ?tracking_event_details: TrackingEventDetails?) -> void
       end

data/sig/open_feature/sdk/provider_event.rbs

@@ -5,6 +5,8 @@ module OpenFeature
       PROVIDER_ERROR: String
       PROVIDER_CONFIGURATION_CHANGED: String
       PROVIDER_STALE: String
+      PROVIDER_RECONCILING: String
+      PROVIDER_CONTEXT_CHANGED: String
 
       ALL_EVENTS: Array[String]
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: openfeature-sdk
 version: !ruby/object:Gem::Version
-  version: 0.6.5
+  version: 0.6.7
 platform: ruby
 authors:
 - OpenFeature Authors
@@ -20,7 +20,6 @@ files:
 - ".release-please-manifest.json"
 - ".rspec"
 - ".ruby-version"
-- ".simplecov"
 - ".standard.yml"
 - ".tool-versions"
 - ".yardopts"
@@ -48,6 +47,7 @@ files:
 - lib/open_feature/sdk/evaluation_context.rb
 - lib/open_feature/sdk/evaluation_context_builder.rb
 - lib/open_feature/sdk/evaluation_details.rb
+- lib/open_feature/sdk/evaluation_error.rb
 - lib/open_feature/sdk/event_dispatcher.rb
 - lib/open_feature/sdk/hooks.rb
 - lib/open_feature/sdk/hooks/hints.rb
@@ -85,6 +85,7 @@ files:
 - sig/open_feature/sdk/evaluation_context.rbs
 - sig/open_feature/sdk/evaluation_context_builder.rbs
 - sig/open_feature/sdk/evaluation_details.rbs
+- sig/open_feature/sdk/evaluation_error.rbs
 - sig/open_feature/sdk/event_dispatcher.rbs
 - sig/open_feature/sdk/hooks/hints.rbs
 - sig/open_feature/sdk/hooks/hook.rbs
@@ -132,7 +133,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.6
+rubygems_version: 4.0.20
 specification_version: 4
 summary: OpenFeature SDK for Ruby
 test_files: []

data/.simplecov

@@ -1,13 +0,0 @@
-# frozen_string_literal: true
-
-require "simplecov-cobertura"
-
-SimpleCov.start do
-  add_filter "/spec/"
-  minimum_coverage 90
-  if ENV["CI"] == "true"
-    formatter SimpleCov::Formatter::CoberturaFormatter
-  else
-    formatter SimpleCov::Formatter::HTMLFormatter
-  end
-end