openfeature-sdk 0.6.6 → 0.6.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 500c09c5333475a75aeff77cdab714c1360f4c14a84c28f9f16fe3b0dc42cb8f
-  data.tar.gz: 4d760e25308fad1ea762e8547260f87dea3474a8861eadd25993cfd2dde55b04
+  metadata.gz: 93f85fdb9eb64b634a3267d0987415f3e4b9033a9d864e80478dfde83074fa7d
+  data.tar.gz: 14e94971fdae29a56d31db9d8ee44716b805b6783e0d381ac04e6348168ccf67
 SHA512:
-  metadata.gz: 4bfda5295966ab245426ecaa0d2dbb440b7f273833193906b9fd91fd6ffeb41e5b49e652a9d05dbf6679c08cfc434c4733d34384dfc1d64be995194f3938cdf1
-  data.tar.gz: 2359651d7407cdd30e41e15e4d764efc47565e025b2046adbc4942da0c25d62396bd5e52991626d728b675b123aa52bcce733f8ebc71703112ebe77d6704e96e
+  metadata.gz: c1e726bae4617d91ed82f676270bb51b7355e8694fac68a76af5f8ea046ed60c33d4c31b0a716827ad61edffe2849c3eb444c614975ac8a09707dcf620286c03
+  data.tar.gz: 47d740d86cac2c493058c0f35aa6c2489d89f0502e8df3eb9ba850585777934478fe2dcf500b7eac9b71c96cfb2c857bc6026e9d1214e7876bc385788fcf6f18

data/.release-please-manifest.json

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

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 # 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)
 
 

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    openfeature-sdk (0.6.6)
+    openfeature-sdk (0.6.7)
 
 GEM
   remote: https://rubygems.org/

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.6">
-    <img alt="Release" src="https://img.shields.io/static/v1?label=release&message=v0.6.6&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 -->
@@ -301,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)
@@ -351,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
@@ -442,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

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,8 +75,6 @@ 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)
@@ -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: EvaluationError.code_for(e),
-              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(
@@ -143,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:)
@@ -153,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

@@ -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)
@@ -118,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
@@ -129,22 +137,29 @@ 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
@@ -153,6 +168,7 @@ module OpenFeature
           if old_provider && !old_provider.equal?(provider)
             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
@@ -171,45 +187,65 @@ 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.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 = {})
@@ -239,6 +275,40 @@ module OpenFeature
         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/version.rb

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

data/sig/open_feature/sdk/configuration.rbs

@@ -32,9 +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/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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: openfeature-sdk
 version: !ruby/object:Gem::Version
-  version: 0.6.6
+  version: 0.6.7
 platform: ruby
 authors:
 - OpenFeature Authors