refactor: consolidate duplicate immediate handler methods

- Replace run_immediate_handler_for_api and run_immediate_handler with single unified method
- Update method signature to require explicit client parameter (nil for API-level)
- Fix test isolation by clearing provider state in client event handler tests
- Update test expectations to account for immediate handler execution
- Remove unused default parameters from helper methods

Author: sameerank

lib/open_feature/sdk/configuration.rb

@@ -42,6 +42,7 @@ def logger=(new_logger)
 
       def add_handler(event_type, handler)
         @event_emitter.add_handler(event_type, handler)
+        run_immediate_handler(event_type, handler, nil)
       end
 
       def remove_handler(event_type, handler)
@@ -61,7 +62,7 @@ def add_client_handler(client, event_type, handler)
           @client_handlers[client][event_type] << handler
         end
 
-        run_immediate_handler(client, event_type, handler)
+        run_immediate_handler(event_type, handler, client)
       end
 
       def remove_client_handler(client, event_type, handler)
@@ -191,30 +192,48 @@ def run_handlers_for_provider(provider, event_type, event_details)
         end
       end
 
-      def run_immediate_handler(client, event_type, handler)
+      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
         }
 
-        # Get provider for specific domain, but don't fall back to default unless domain is nil
-        client_provider = @providers[client.metadata.domain]
-        client_provider ||= @providers[nil] if client.metadata.domain.nil?
-        return unless client_provider
+        if client.nil?
+          # API-level handler: check all providers
+          @providers.each do |domain, provider|
+            next unless provider
 
-        provider_state = @provider_state_registry.get_state(client_provider)
+            provider_state = @provider_state_registry.get_state(provider)
 
-        # Only run if the event type matches the current provider status
-        if event_type == status_to_event[provider_state]
-          provider_name = extract_provider_name(client_provider)
-          event_details = {provider_name: provider_name}
+            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 client event handler failed: #{e.message}")
+              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
+
+          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

spec/open_feature/sdk/client_event_handlers_spec.rb

@@ -21,6 +21,10 @@
   end
 
   it "allows clients to add event handlers scoped to their domain" do
+    # Clear providers to ensure clean state - no default provider should exist
+    OpenFeature::SDK.configuration.instance_variable_set(:@providers, {})
+    OpenFeature::SDK.configuration.instance_variable_get(:@provider_state_registry).instance_variable_set(:@states, {})
+
     events_received = []
 
     # Create client with specific domain
@@ -42,6 +46,10 @@
   end
 
   it "does not trigger handlers for other domains" do
+    # Clear providers to ensure clean state - no default provider should exist
+    OpenFeature::SDK.configuration.instance_variable_set(:@providers, {})
+    OpenFeature::SDK.configuration.instance_variable_get(:@provider_state_registry).instance_variable_set(:@states, {})
+
     events_received = []
 
     # Create client with specific domain
@@ -60,6 +68,10 @@
   end
 
   it "allows removal of client event handlers" do
+    # Clear providers to ensure clean state - no default provider should exist
+    OpenFeature::SDK.configuration.instance_variable_set(:@providers, {})
+    OpenFeature::SDK.configuration.instance_variable_get(:@provider_state_registry).instance_variable_set(:@states, {})
+
     events_received = []
 
     client = OpenFeature::SDK.build_client(domain: "test_domain")
@@ -79,6 +91,10 @@
   end
 
   it "supports block syntax for handlers" do
+    # Clear providers to ensure clean state - no default provider should exist
+    OpenFeature::SDK.configuration.instance_variable_set(:@providers, {})
+    OpenFeature::SDK.configuration.instance_variable_get(:@provider_state_registry).instance_variable_set(:@states, {})
+
     events_received = []
 
     client = OpenFeature::SDK.build_client(domain: "test_domain")
@@ -113,7 +129,7 @@
 
   private
 
-  def test_provider(name = "TestProvider")
+  def test_provider(name)
     Class.new do
       include OpenFeature::SDK::Provider::EventHandler
 

spec/specification/events_spec.rb

@@ -5,7 +5,6 @@
 
 RSpec.describe "OpenFeature Specification: Events" do
   before(:each) do
-    # Reset to default provider
     OpenFeature::SDK.set_provider(OpenFeature::SDK::Provider::NoOpProvider.new)
   end
 
@@ -220,14 +219,16 @@ def shutdown
       OpenFeature::SDK.set_provider(provider1)
       sleep(0.1)
 
-      expect(handler_call_count).to eq(1)
+      # Should be 2: 1 immediate (NoOpProvider is READY by set_provider in before(:each)) + 1 from InMemoryProvider
+      expect(handler_call_count).to eq(2)
 
       # Set second provider - handler should still be active
       provider2 = OpenFeature::SDK::Provider::NoOpProvider.new
       OpenFeature::SDK.set_provider(provider2)
       sleep(0.1)
 
-      expect(handler_call_count).to eq(2)
+      # Should be 3: 1 immediate + 2 from provider changes
+      expect(handler_call_count).to eq(3)
 
       # Cleanup
       OpenFeature::SDK.remove_handler(OpenFeature::SDK::ProviderEvent::PROVIDER_READY, handler)
@@ -256,22 +257,40 @@ def shutdown
   end
 
   context "Requirement 5.3.3" do
-    specify "Handlers attached after the provider is already in the associated state, MUST run immediately" do
-      events_received = []
+    describe "Handlers attached after the provider is already in the associated state, MUST run immediately" do
+      context "API-level handlers" do
+        specify "PROVIDER_READY handler runs immediately when provider is already READY" do
+          events_received = []
 
-      # Set up provider and get it into READY state first
-      provider = OpenFeature::SDK::Provider::InMemoryProvider.new
-      OpenFeature::SDK.set_provider_and_wait(provider, domain: "immediate_test")
+          provider = OpenFeature::SDK::Provider::InMemoryProvider.new
+          OpenFeature::SDK.set_provider_and_wait(provider)
 
-      # Now create client and add handler - should run immediately since provider is READY
-      client = OpenFeature::SDK.build_client(domain: "immediate_test")
-      client.add_handler(OpenFeature::SDK::ProviderEvent::PROVIDER_READY) do |event|
-        events_received << event
+          handler = ->(event) { events_received << event }
+          OpenFeature::SDK.add_handler(OpenFeature::SDK::ProviderEvent::PROVIDER_READY, handler)
+
+          expect(events_received).to have_attributes(size: 1)
+          expect(events_received[0][:provider_name]).to eq("In-memory Provider")
+
+          OpenFeature::SDK.remove_handler(OpenFeature::SDK::ProviderEvent::PROVIDER_READY, handler)
+        end
       end
 
-      # Handler should have executed immediately, no additional events needed
-      expect(events_received).to have_attributes(size: 1)
-      expect(events_received[0][:provider_name]).to eq("In-memory Provider")
+      context "Client-level handlers" do
+        specify "PROVIDER_READY handler runs immediately when provider is already READY" do
+          events_received = []
+
+          provider = OpenFeature::SDK::Provider::InMemoryProvider.new
+          OpenFeature::SDK.set_provider_and_wait(provider, domain: "immediate_test")
+
+          client = OpenFeature::SDK.build_client(domain: "immediate_test")
+          client.add_handler(OpenFeature::SDK::ProviderEvent::PROVIDER_READY) do |event|
+            events_received << event
+          end
+
+          expect(events_received).to have_attributes(size: 1)
+          expect(events_received[0][:provider_name]).to eq("In-memory Provider")
+        end
+      end
     end
   end
 end