openfeature-sdk 0.4.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ac02affc7dc168be388d9d2a4be338f8e390587cc911372126fc2e25f07237fc
-  data.tar.gz: dfa2ba4e40f5498b55d70ce5001233632007a9a10decf13f153edf08455672ad
+  metadata.gz: c91c19e8a0f7ef628c048224287a276713d704914142d4a2771bd74bf01ea68e
+  data.tar.gz: 565d980320e40d5a573c4710d6313f038c0a58350f6d5eb1564dcd5c85148853
 SHA512:
-  metadata.gz: 413138e8e435e278376a6a8ac70a25d1673128e76ed454bfffec9e894517a61f42c8e31ef3adfc25ba71786083eb574427e0b6dfa9748dec099c807dce3b3a7d
-  data.tar.gz: 1f494723edf1c24559e19e2083c59fffa6f988f723d46f65df1c7d334023693280f5eb3d9c680fa3a2932bb48737b9dee324c16ce37b55de98dcfe802261664f
+  metadata.gz: 7d5dd24ccd3b4e61de24d7a46d02169ad7373d74776664fc0686db4d51dde98c8851c81e392043130f08a4dfd6cdb877a31c3a5ecb2d42c7bd2f5c92b1008fef
+  data.tar.gz: f8ed5ee65b6bee9dd1e36e1373248b12f3729a5ce5a22857c4212957246f7c3b150d48d5cea6e59a7e164d06e69bb53a5d90fc883924c85aaa4f6d64b15e4764

data/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.4.1"
+  ".": "0.5.0"
 }

data/.ruby-version

@@ -1 +1 @@
-3.4.7
+3.4.8

data/.tool-versions

@@ -1 +1 @@
-ruby 3.4.7
+ruby 3.4.8

data/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## [0.5.0](https://github.com/open-feature/ruby-sdk/compare/v0.4.1...v0.5.0) (2026-01-16)
+
+
+### ⚠ BREAKING CHANGES
+
+* add provider eventing, remove setProvider timeout ([#207](https://github.com/open-feature/ruby-sdk/issues/207))
+
+### Features
+
+* add provider eventing, remove setProvider timeout ([#207](https://github.com/open-feature/ruby-sdk/issues/207)) ([fffd615](https://github.com/open-feature/ruby-sdk/commit/fffd6155ff308c75220185de030c38eb6eeac7e8))
+
 ## [0.4.1](https://github.com/open-feature/ruby-sdk/compare/v0.4.0...v0.4.1) (2025-11-03)
 
 

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    openfeature-sdk (0.4.1)
+    openfeature-sdk (0.5.0)
 
 GEM
   remote: https://rubygems.org/
@@ -89,12 +89,14 @@ GEM
       rubocop-performance (~> 1.20.2)
     stringio (3.1.0)
     strscan (3.1.0)
+    timecop (0.9.10)
     unicode-display_width (2.5.0)
 
 PLATFORMS
   arm64-darwin-21
   arm64-darwin-22
   arm64-darwin-23
+  arm64-darwin-24
   x64-mingw-ucrt
   x64-mingw32
   x86_64-darwin-19
@@ -112,6 +114,7 @@ DEPENDENCIES
   simplecov-cobertura (~> 2.1.0)
   standard
   standard-performance
+  timecop (~> 0.9.10)
 
 BUNDLED WITH
    2.3.25

data/LICENSE

@@ -186,7 +186,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright [yyyy] [name of copyright owner]
+   Copyright OpenFeature Maintainers
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

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.4.1">
-    <img alt="Release" src="https://img.shields.io/static/v1?label=release&message=v0.4.1&color=blue&style=for-the-badge" />
+  <a href="https://github.com/open-feature/ruby-sdk/releases/tag/v0.5.0">
+    <img alt="Release" src="https://img.shields.io/static/v1?label=release&message=v0.5.0&color=blue&style=for-the-badge" />
   </a>
 
   <!-- x-release-please-end -->
@@ -104,7 +104,7 @@ object = client.fetch_object_value(flag_key: 'object_value', default_value: { na
 | ⚠️      | [Hooks](#hooks)                                                     | Add functionality to various stages of the flag evaluation life-cycle.                                                                                       |
 | ❌      | [Logging](#logging)                                                 | Integrate with popular logging packages.                                                                                                                     |
 | ✅      | [Domains](#domains)                                                 | Logically bind clients with providers.                                                                                                                       |
-| ❌      | [Eventing](#eventing)                                               | React to state changes in the provider or flag management system.                                                                                            |
+| ✅      | [Eventing](#eventing)                                               | React to state changes in the provider or flag management system.                                                                                            |
 | ⚠️      | [Shutdown](#shutdown)                                               | Gracefully clean up a provider during application shutdown.                                                                                                  |
 | ❌      | [Transaction Context Propagation](#transaction-context-propagation) | Set a specific [evaluation context](https://openfeature.dev/docs/reference/concepts/evaluation-context) for a transaction (e.g. an HTTP request or a thread) |
 | ⚠️      | [Extending](#extending)                                             | Extend OpenFeature with custom providers and hooks.                                                                                                          |
@@ -142,6 +142,7 @@ begin
 rescue OpenFeature::SDK::ProviderInitializationError => e
   puts "Provider failed to initialize: #{e.message}"
   puts "Error code: #{e.error_code}"
+  # original_error contains the underlying exception that caused the initialization failure
   puts "Original error: #{e.original_error}"
 end
 
@@ -163,8 +164,9 @@ end
 
 The `set_provider_and_wait` method:
 - Waits for the provider's `init` method to complete successfully
-- Raises `ProviderInitializationError` with `PROVIDER_FATAL` error code if initialization fails or times out
-- Provides access to the original error, provider instance, and error code for debugging
+- Raises `ProviderInitializationError` if initialization fails or times out
+- Provides access to the provider instance, error code, and original exception for debugging
+- The `original_error` field contains the underlying exception that caused the initialization failure
 - Uses the same thread-safe provider switching as `set_provider`
 
 In some situations, it may be beneficial to register multiple providers in the same application.
@@ -231,15 +233,47 @@ legacy_flag_client = OpenFeature::SDK.build_client(domain: "legacy_flags")
 
 ### Eventing
 
-Coming Soon! [Issue available](https://github.com/open-feature/ruby-sdk/issues/51) to be worked on.
-
-<!-- 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.
+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`.
 
-Please refer to the documentation of the provider you're using to see what events are supported. -->
+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!"
+end
+
+OpenFeature::SDK.add_handler(OpenFeature::SDK::ProviderEvent::PROVIDER_READY, ready_handler)
+
+# The SDK automatically emits lifecycle events. Providers can emit additional spontaneous events
+# using the EventEmitter mixin to signal internal state changes like configuration updates.
+class MyEventAwareProvider
+  include OpenFeature::SDK::Provider::EventEmitter
 
-<!-- TODO: code example of a PROVIDER_CONFIGURATION_CHANGED event for the client and a PROVIDER_STALE event for the API -->
+  def init(evaluation_context)
+    # Start background process to monitor for configuration changes
+    # Note: SDK automatically emits PROVIDER_READY when init completes successfully
+    start_background_process
+  end
+
+  def start_background_process
+    Thread.new do
+      # Monitor for configuration changes and emit events when they occur
+      if configuration_changed?
+        emit_event(
+          OpenFeature::SDK::ProviderEvent::PROVIDER_CONFIGURATION_CHANGED,
+          message: "Flag configuration updated"
+        )
+      end
+    end
+  end
+end
+
+# Remove specific handlers when no longer needed
+OpenFeature::SDK.remove_handler(OpenFeature::SDK::ProviderEvent::PROVIDER_READY, ready_handler)
+```
 
 ### Shutdown
 

data/lib/open_feature/sdk/api.rb

@@ -51,6 +51,22 @@ module OpenFeature
       rescue
         Client.new(provider: Provider::NoOpProvider.new, evaluation_context:)
       end
+
+      def add_handler(event_type, handler)
+        configuration.add_handler(event_type, handler)
+      end
+
+      def remove_handler(event_type, handler)
+        configuration.remove_handler(event_type, handler)
+      end
+
+      def logger
+        configuration.logger
+      end
+
+      def logger=(new_logger)
+        configuration.logger = new_logger
+      end
     end
   end
 end

data/lib/open_feature/sdk/client.rb

@@ -27,6 +27,16 @@ module OpenFeature
         @hooks = []
       end
 
+      def add_handler(event_type, handler = nil, &block)
+        actual_handler = handler || block
+        OpenFeature::SDK.configuration.add_client_handler(self, event_type, actual_handler)
+      end
+
+      def remove_handler(event_type, handler = nil, &block)
+        actual_handler = handler || block
+        OpenFeature::SDK.configuration.remove_client_handler(self, event_type, actual_handler)
+      end
+
       RESULT_TYPE.each do |result_type|
         SUFFIXES.each do |suffix|
           class_eval <<-RUBY, __FILE__, __LINE__ + 1

data/lib/open_feature/sdk/configuration.rb

@@ -3,6 +3,10 @@
 require "timeout"
 require_relative "api"
 require_relative "provider_initialization_error"
+require_relative "event_dispatcher"
+require_relative "provider_event"
+require_relative "provider_state_registry"
+require_relative "provider/event_emitter"
 
 module OpenFeature
   module SDK
@@ -14,73 +18,233 @@ module OpenFeature
       extend Forwardable
 
       attr_accessor :evaluation_context, :hooks
+      attr_reader :logger
 
       def initialize
         @hooks = []
         @providers = {}
         @provider_mutex = Mutex.new
+        @logger = nil
+        @event_dispatcher = EventDispatcher.new(@logger)
+        @provider_state_registry = ProviderStateRegistry.new
+        @client_handlers = {}
+        @client_handlers_mutex = Mutex.new
       end
 
       def provider(domain: nil)
         @providers[domain] || @providers[nil]
       end
 
-      # When switching providers, there are a few lifecycle methods that need to be taken care of.
-      #   1. If a provider is already set, we need to call `shutdown` on it.
-      #   2. On the new provider, call `init`.
-      #   3. Finally, set the internal provider to the new provider
+      def logger=(new_logger)
+        @logger = new_logger
+        @event_dispatcher.logger = new_logger if @event_dispatcher
+      end
+
+      def add_handler(event_type, handler)
+        @event_dispatcher.add_handler(event_type, handler)
+        run_immediate_handler(event_type, handler, nil)
+      end
+
+      def remove_handler(event_type, handler)
+        @event_dispatcher.remove_handler(event_type, handler)
+      end
+
+      # @api private
+      def add_client_handler(client, event_type, handler)
+        @client_handlers_mutex.synchronize do
+          @client_handlers[client] ||= Hash.new { |h, k| h[k] = [] }
+          @client_handlers[client][event_type] << handler
+        end
+
+        run_immediate_handler(event_type, handler, client)
+      end
+
+      # @api private
+      def remove_client_handler(client, event_type, handler)
+        @client_handlers_mutex.synchronize do
+          return unless @client_handlers[client]
+          handlers = @client_handlers[client][event_type]
+          handlers&.delete(handler)
+        end
+      end
+
       def set_provider(provider, domain: nil)
+        set_provider_internal(provider, domain: domain, wait_for_init: false)
+      end
+
+      def set_provider_and_wait(provider, domain: nil)
+        set_provider_internal(provider, domain: domain, wait_for_init: true)
+      end
+
+      private
+
+      def reset
+        @event_dispatcher.clear_all_handlers
+        @client_handlers_mutex.synchronize do
+          @client_handlers.clear
+        end
+        @provider_state_registry.clear
         @provider_mutex.synchronize do
-          @providers[domain].shutdown if @providers[domain].respond_to?(:shutdown)
-          provider.init if provider.respond_to?(:init)
-          new_providers = @providers.dup
-          new_providers[domain] = provider
-          @providers = new_providers
+          @providers.clear
         end
       end
 
-      # Sets a provider and waits for the initialization to complete or fail.
-      # This method ensures the provider is ready (or in error state) before returning.
-      #
-      # @param provider [Object] the provider to set
-      # @param domain [String, nil] the domain for the provider (optional)
-      # @param timeout [Integer] maximum time to wait for initialization in seconds (default: 30)
-      # @raise [ProviderInitializationError] if the provider fails to initialize or times out
-      def set_provider_and_wait(provider, domain: nil, timeout: 30)
+      def set_provider_internal(provider, domain:, wait_for_init:)
+        # Capture evaluation context before acquiring mutex to prevent race conditions
+        context_for_init = @evaluation_context
+
+        old_provider, provider_to_init = nil
+
         @provider_mutex.synchronize do
           old_provider = @providers[domain]
 
-          # Shutdown old provider (ignore errors)
+          # Remove old provider state to prevent memory leaks
+          @provider_state_registry.remove_provider(old_provider)
+
+          new_providers = @providers.dup
+          new_providers[domain] = provider
+          @providers = new_providers
+
+          @provider_state_registry.set_initial_state(provider)
+
+          provider.send(:attach, self) if provider.is_a?(Provider::EventEmitter)
+
+          provider_to_init = provider
+        end
+
+        # Shutdown old provider outside mutex to avoid blocking other operations
+        # Only shutdown if it's a different provider to prevent race condition
+        if old_provider && old_provider != provider
           begin
             old_provider.shutdown if old_provider.respond_to?(:shutdown)
-          rescue
-            # Ignore shutdown errors and continue with provider initialization
+          rescue => e
+            @logger&.warn("Error shutting down previous provider #{old_provider&.class&.name || "unknown"}: #{e.message}")
           end
+        end
 
-          begin
-            # Initialize new provider with timeout
-            if provider.respond_to?(:init)
-              Timeout.timeout(timeout) do
-                provider.init
+        # Initialize provider outside the mutex to avoid blocking other operations
+        if wait_for_init
+          init_provider(provider_to_init, context_for_init, raise_on_error: true)
+        else
+          Thread.new do
+            init_provider(provider_to_init, context_for_init, raise_on_error: false)
+          end
+        end
+      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
+
+        dispatch_provider_event(provider, ProviderEvent::PROVIDER_READY)
+      rescue => e
+        dispatch_provider_event(provider, ProviderEvent::PROVIDER_ERROR,
+          error_code: Provider::ErrorCode::GENERAL,
+          message: e.message)
+
+        if raise_on_error
+          # Re-raise as ProviderInitializationError for synchronous callers
+          raise ProviderInitializationError.new(
+            "Provider #{provider.class.name} initialization failed: #{e.message}",
+            provider:,
+            error_code: Provider::ErrorCode::GENERAL,
+            original_error: e
+          )
+        end
+      end
+
+      def dispatch_provider_event(provider, event_type, details = {})
+        @provider_state_registry.update_state_from_event(provider, event_type, details)
+
+        provider_name = extract_provider_name(provider)
+
+        event_details = {
+          provider_name: provider_name
+        }.merge(details)
+
+        run_handlers_for_provider(provider, event_type, event_details)
+      end
+
+      def provider_state(provider)
+        @provider_state_registry.get_state(provider)
+      end
+
+      private
+
+      def extract_provider_name(provider)
+        provider.respond_to?(:metadata) ? provider.metadata.name : provider.class.name
+      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)
+
+        # Run client handlers (domain-scoped)
+        @client_handlers_mutex.synchronize do
+          @client_handlers.each do |client, handlers_by_event|
+            # Check if this client should receive events from this provider
+            client_provider = provider(domain: client.metadata.domain)
+            next unless client_provider&.equal?(provider)
+
+            # Trigger handlers for this client
+            handlers = handlers_by_event[event_type]
+            handlers.each do |handler|
+              handler.call(event_details)
+            rescue => e
+              @logger&.error("Client event handler failed: #{e.message}")
+            end
+          end
+        end
+      end
+
+      def run_immediate_handler(event_type, handler, client)
+        status_to_event = {
+          ProviderState::READY => ProviderEvent::PROVIDER_READY,
+          ProviderState::ERROR => ProviderEvent::PROVIDER_ERROR,
+          ProviderState::FATAL => ProviderEvent::PROVIDER_ERROR,
+          ProviderState::STALE => ProviderEvent::PROVIDER_STALE
+        }
+
+        if client.nil?
+          # API-level handler: check all providers
+          @providers.each do |domain, provider|
+            next unless provider
+
+            provider_state = @provider_state_registry.get_state(provider)
+
+            if event_type == status_to_event[provider_state]
+              provider_name = extract_provider_name(provider)
+              event_details = {provider_name: provider_name}
+
+              begin
+                handler.call(event_details)
+              rescue => e
+                @logger&.error("Immediate API event handler failed: #{e.message}")
               end
             end
+          end
+        else
+          # Client-level handler: check specific provider only
+          client_provider = provider(domain: client.metadata.domain)
+          return unless client_provider
 
-            # Set the new provider
-            new_providers = @providers.dup
-            new_providers[domain] = provider
-            @providers = new_providers
-          rescue Timeout::Error => e
-            raise ProviderInitializationError.new(
-              "Provider initialization timed out after #{timeout} seconds",
-              provider:,
-              original_error: e
-            )
-          rescue => e
-            raise ProviderInitializationError.new(
-              "Provider initialization failed: #{e.message}",
-              provider:,
-              original_error: e
-            )
+          provider_state = @provider_state_registry.get_state(client_provider)
+
+          if event_type == status_to_event[provider_state]
+            provider_name = extract_provider_name(client_provider)
+            event_details = {provider_name: provider_name}
+
+            begin
+              handler.call(event_details)
+            rescue => e
+              @logger&.error("Immediate client event handler failed: #{e.message}")
+            end
           end
         end
       end

data/lib/open_feature/sdk/event_dispatcher.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require_relative "provider_event"
+
+module OpenFeature
+  module SDK
+    # Thread-safe pub-sub for provider events
+    class EventDispatcher
+      attr_writer :logger
+
+      def initialize(logger = nil)
+        @handlers = {}
+        @mutex = Mutex.new
+        @logger = logger
+        ProviderEvent::ALL_EVENTS.each { |event| @handlers[event] = [] }
+      end
+
+      def add_handler(event_type, handler)
+        raise ArgumentError, "Invalid event type: #{event_type}" unless valid_event?(event_type)
+        raise ArgumentError, "Handler must respond to call" unless handler.respond_to?(:call)
+
+        @mutex.synchronize do
+          @handlers[event_type] << handler
+        end
+      end
+
+      def remove_handler(event_type, handler)
+        return unless valid_event?(event_type)
+
+        @mutex.synchronize do
+          @handlers[event_type].delete(handler)
+        end
+      end
+
+      def remove_all_handlers(event_type)
+        return unless valid_event?(event_type)
+
+        @mutex.synchronize do
+          @handlers[event_type].clear
+        end
+      end
+
+      def trigger_event(event_type, event_details = {})
+        return unless valid_event?(event_type)
+
+        handlers_to_call = nil
+        @mutex.synchronize do
+          handlers_to_call = @handlers[event_type].dup
+        end
+
+        # Call handlers outside of mutex to avoid deadlocks
+        handlers_to_call.each do |handler|
+          handler.call(event_details)
+        rescue => e
+          @logger&.warn "Event handler failed for #{event_type}: #{e.message}\n#{e.backtrace.join("\n")}"
+        end
+      end
+
+      def handler_count(event_type)
+        return 0 unless valid_event?(event_type)
+
+        @mutex.synchronize do
+          @handlers[event_type].size
+        end
+      end
+
+      def clear_all_handlers
+        @mutex.synchronize do
+          @handlers.each_value(&:clear)
+        end
+      end
+
+      private
+
+      def valid_event?(event_type)
+        ProviderEvent::ALL_EVENTS.include?(event_type)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative "../provider_event"
+
+module OpenFeature
+  module SDK
+    module Provider
+      # Mixin for providers that emit lifecycle events
+      module EventEmitter
+        def emit_event(event_type, details = {})
+          config = @configuration
+          return unless config
+
+          unless ::OpenFeature::SDK::ProviderEvent::ALL_EVENTS.include?(event_type)
+            raise ArgumentError, "Invalid event type: #{event_type}"
+          end
+
+          config.send(:dispatch_provider_event, self, event_type, details)
+        end
+
+        def configuration_attached?
+          !@configuration.nil?
+        end
+
+        private
+
+        def attach(configuration)
+          @configuration = configuration
+        end
+
+        def detach
+          @configuration = nil
+        end
+      end
+    end
+  end
+end

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

@@ -12,7 +12,7 @@ module OpenFeature
           @flags = flags
         end
 
-        def init
+        def init(evaluation_context = nil)
           # Intentional no-op, used for testing
         end
 

data/lib/open_feature/sdk/provider.rb

@@ -2,9 +2,20 @@ require_relative "provider/error_code"
 require_relative "provider/reason"
 require_relative "provider/resolution_details"
 require_relative "provider/provider_metadata"
+
+# Provider interfaces
+require_relative "provider/event_emitter"
+
+# Provider implementations
 require_relative "provider/no_op_provider"
 require_relative "provider/in_memory_provider"
 
+# Event system components
+require_relative "provider_event"
+require_relative "provider_state"
+require_relative "event_dispatcher"
+require_relative "provider_state_registry"
+
 module OpenFeature
   module SDK
     module Provider

data/lib/open_feature/sdk/provider_event.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module OpenFeature
+  module SDK
+    # Provider Event Types
+    #
+    # Defines the standard event types that providers can emit during their lifecycle.
+    # These events correspond to the OpenFeature specification events:
+    # https://openfeature.dev/specification/sections/events/
+    #
+    module ProviderEvent
+      PROVIDER_READY = "PROVIDER_READY"
+      PROVIDER_ERROR = "PROVIDER_ERROR"
+      PROVIDER_CONFIGURATION_CHANGED = "PROVIDER_CONFIGURATION_CHANGED"
+      PROVIDER_STALE = "PROVIDER_STALE"
+
+      ALL_EVENTS = [
+        PROVIDER_READY,
+        PROVIDER_ERROR,
+        PROVIDER_CONFIGURATION_CHANGED,
+        PROVIDER_STALE
+      ].freeze
+    end
+  end
+end

data/lib/open_feature/sdk/provider_state.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module OpenFeature
+  module SDK
+    # Provider State Types
+    #
+    # Defines the standard states that providers can be in during their lifecycle.
+    # These states correspond to the OpenFeature specification provider states:
+    # https://openfeature.dev/specification/types#provider-status
+    #
+    module ProviderState
+      NOT_READY = "NOT_READY"
+      READY = "READY"
+      ERROR = "ERROR"
+      STALE = "STALE"
+      FATAL = "FATAL"
+
+      ALL_STATES = [
+        NOT_READY,
+        READY,
+        ERROR,
+        STALE,
+        FATAL
+      ].freeze
+    end
+  end
+end

data/lib/open_feature/sdk/provider_state_registry.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require_relative "provider_state"
+require_relative "provider_event"
+require_relative "provider/error_code"
+
+module OpenFeature
+  module SDK
+    # Tracks provider states
+    class ProviderStateRegistry
+      def initialize
+        @states = {}
+        @mutex = Mutex.new
+      end
+
+      def set_initial_state(provider, state = ProviderState::NOT_READY)
+        return unless provider
+
+        @mutex.synchronize do
+          @states[provider.object_id] = state
+        end
+      end
+
+      def update_state_from_event(provider, event_type, event_details = nil)
+        return ProviderState::NOT_READY unless provider
+
+        new_state = state_from_event(event_type, event_details)
+
+        # Only update state if the event should cause a state change
+        if new_state
+          @mutex.synchronize do
+            @states[provider.object_id] = new_state
+          end
+          new_state
+        else
+          # Return current state without changing it
+          get_state(provider)
+        end
+      end
+
+      def get_state(provider)
+        return ProviderState::NOT_READY unless provider
+
+        @mutex.synchronize do
+          @states[provider.object_id] || ProviderState::NOT_READY
+        end
+      end
+
+      def remove_provider(provider)
+        return unless provider
+
+        @mutex.synchronize do
+          @states.delete(provider.object_id)
+        end
+      end
+
+      def ready?(provider)
+        get_state(provider) == ProviderState::READY
+      end
+
+      def error?(provider)
+        state = get_state(provider)
+        [ProviderState::ERROR, ProviderState::FATAL].include?(state)
+      end
+
+      def clear
+        @mutex.synchronize do
+          @states.clear
+        end
+      end
+
+      private
+
+      def state_from_event(event_type, event_details = nil)
+        case event_type
+        when ProviderEvent::PROVIDER_READY
+          ProviderState::READY
+        when ProviderEvent::PROVIDER_STALE
+          ProviderState::STALE
+        when ProviderEvent::PROVIDER_ERROR
+          state_from_error_event(event_details)
+        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
+        end
+      end
+
+      def state_from_error_event(event_details)
+        error_code = event_details&.dig(:error_code)
+        if error_code == Provider::ErrorCode::PROVIDER_FATAL
+          ProviderState::FATAL
+        else
+          ProviderState::ERROR
+        end
+      end
+    end
+  end
+end

data/lib/open_feature/sdk/version.rb

@@ -2,6 +2,6 @@
 
 module OpenFeature
   module SDK
-    VERSION = "0.4.1"
+    VERSION = "0.5.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: openfeature-sdk
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.5.0
 platform: ruby
 authors:
 - OpenFeature Authors
@@ -121,6 +121,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 2.1.0
+- !ruby/object:Gem::Dependency
+  name: timecop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.10
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.10
 description: Ruby SDK for an the specifications for the open standard of feature flag
   management
 email:
@@ -152,21 +166,26 @@ 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/event_dispatcher.rb
 - lib/open_feature/sdk/hooks/hints.rb
 - lib/open_feature/sdk/provider.rb
 - lib/open_feature/sdk/provider/error_code.rb
+- lib/open_feature/sdk/provider/event_emitter.rb
 - lib/open_feature/sdk/provider/in_memory_provider.rb
 - lib/open_feature/sdk/provider/no_op_provider.rb
 - lib/open_feature/sdk/provider/provider_metadata.rb
 - lib/open_feature/sdk/provider/reason.rb
 - lib/open_feature/sdk/provider/resolution_details.rb
+- lib/open_feature/sdk/provider_event.rb
 - lib/open_feature/sdk/provider_initialization_error.rb
+- lib/open_feature/sdk/provider_state.rb
+- lib/open_feature/sdk/provider_state_registry.rb
 - lib/open_feature/sdk/version.rb
 - release-please-config.json
 - renovate.json
 homepage: https://github.com/open-feature/openfeature-ruby
 licenses:
-- Apache-2.0'
+- Apache-2.0
 metadata:
   homepage_uri: https://github.com/open-feature/openfeature-ruby
   source_code_uri: https://github.com/open-feature/openfeature-ruby