feat!: add provider eventing, remove setProvider timeout

Gemfile.lock

@@ -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

README.md

@@ -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
 

lib/open_feature/sdk/api.rb

@@ -51,6 +51,22 @@ def build_client(domain: nil, evaluation_context: nil)
       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

lib/open_feature/sdk/client.rb

@@ -27,6 +27,16 @@ def initialize(provider:, domain: nil, evaluation_context: nil)
         @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