openfeature-sdk 0.4.1 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ac02affc7dc168be388d9d2a4be338f8e390587cc911372126fc2e25f07237fc
-  data.tar.gz: dfa2ba4e40f5498b55d70ce5001233632007a9a10decf13f153edf08455672ad
+  metadata.gz: 36540a362c2f482ce84d2aa8ba3a6efd9b5d68fe7881ed4037f1422ad85f5525
+  data.tar.gz: 4f7e6a764074d50467949e056b0d50be794df0a67323bb80c5e34a724236314b
 SHA512:
-  metadata.gz: 413138e8e435e278376a6a8ac70a25d1673128e76ed454bfffec9e894517a61f42c8e31ef3adfc25ba71786083eb574427e0b6dfa9748dec099c807dce3b3a7d
-  data.tar.gz: 1f494723edf1c24559e19e2083c59fffa6f988f723d46f65df1c7d334023693280f5eb3d9c680fa3a2932bb48737b9dee324c16ce37b55de98dcfe802261664f
+  metadata.gz: b77f6731c17b537069bbf72cf4760e88293bc59c9ae147079ff3b24ac6ac7f1b18b42b49e29fd1a04a85a6054d0a43834289561c06d6b342ba579ec23d510ef8
+  data.tar.gz: 077d8a3f20c396c82413dad70b9a93cff0cd27a76ff8034f67c50bfa0d08235e3424755a4cd33b81c39fed962d7a62e40d1f257d3bbc4e87bac787d0e315b3fb

data/.release-please-manifest.json

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

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,23 @@
 # Changelog
 
+## [0.5.1](https://github.com/open-feature/ruby-sdk/compare/v0.5.0...v0.5.1) (2026-03-04)
+
+
+### Features
+
+* implement hooks lifecycle (spec section 4) ([#214](https://github.com/open-feature/ruby-sdk/issues/214)) ([41c3b9e](https://github.com/open-feature/ruby-sdk/commit/41c3b9e2b73b34f50d8135122fb4592f8ec44e49))
+
+## [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/CLAUDE.md

@@ -0,0 +1,72 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+OpenFeature Ruby SDK — implements the [OpenFeature specification](https://openfeature.dev) (v0.8.0) for vendor-agnostic feature flag management. Published as the `openfeature-sdk` gem. Pure Ruby, no runtime dependencies. Requires Ruby >= 3.1.
+
+## Commands
+
+```bash
+# Install dependencies
+bundle install
+
+# Run full test suite + linting (default rake task)
+bundle exec rake
+
+# Run tests only
+bundle exec rspec
+
+# Run a single test file
+bundle exec rspec spec/open_feature/sdk/client_spec.rb
+
+# Run a specific test by line number
+bundle exec rspec spec/open_feature/sdk/client_spec.rb:40
+
+# Lint (StandardRB with performance plugin)
+bundle exec rake standard
+
+# Auto-fix lint issues
+bundle exec standardrb --fix
+```
+
+## Architecture
+
+Entry point: `require 'open_feature/sdk'` — the `OpenFeature::SDK` module delegates all method calls to `API.instance` (Singleton) via `method_missing`.
+
+### Core Components
+
+- **API** (`lib/open_feature/sdk/api.rb`) — Singleton orchestrator. Manages providers (global or domain-scoped), builds clients, stores API-level evaluation context, and registers event handlers.
+- **Configuration** (`lib/open_feature/sdk/configuration.rb`) — Thread-safe provider storage. Handles provider lifecycle (init/shutdown), domain-scoped provider mapping, and event dispatching. Uses Mutex for all shared state.
+- **Client** (`lib/open_feature/sdk/client.rb`) — Flag evaluation interface. Uses `class_eval` metaprogramming to generate 12 typed methods: `fetch_{boolean,string,number,integer,float,object}_value` and `fetch_*_details` variants. Merges evaluation contexts (API + client + invocation).
+- **EvaluationContext** (`lib/open_feature/sdk/evaluation_context.rb`) — Key-value targeting data with a special `targeting_key`. Supports merging with precedence: invocation > client > API.
+
+### Provider System
+
+- **Provider interface** — Must implement 6 `fetch_*_value` methods, optional `init(evaluation_context)` and `shutdown`. Returns `ResolutionDetails`.
+- **EventEmitter** (`lib/open_feature/sdk/provider/event_emitter.rb`) — Mixin that providers include to emit lifecycle events.
+- **Built-in providers**: `NoOpProvider` (default), `InMemoryProvider` (testing/examples).
+- **Provider states**: `NOT_READY → READY`, with `ERROR`, `FATAL`, `STALE` transitions. Tracked per-instance via `ProviderStateRegistry` using `object_id`.
+- **Initialization modes**: `set_provider` (async, background thread) or `set_provider_and_wait` (sync, raises `ProviderInitializationError` on failure).
+
+### Event System
+
+- **EventDispatcher** (`lib/open_feature/sdk/event_dispatcher.rb`) — Thread-safe pub-sub. Handlers called outside mutex to prevent deadlocks. Supports API-level and client-level handlers.
+- **ProviderEvent** constants: `PROVIDER_READY`, `PROVIDER_ERROR`, `PROVIDER_STALE`, `PROVIDER_CONFIGURATION_CHANGED`.
+
+## Test Structure
+
+Tests in `spec/` split into two categories:
+- `spec/specification/` — OpenFeature spec compliance tests, organized by requirement number (e.g., "Requirement 1.1.1")
+- `spec/open_feature/` — Unit tests for individual components
+
+Uses Timecop for time-sensitive tests (auto-reset after each test), SimpleCov for coverage.
+
+## Conventions
+
+- **Linter**: StandardRB (Ruby Standard Style) with `standard-performance` plugin, targeting Ruby 3.1
+- **Commits**: Conventional Commits required for PR titles (enforced by CI)
+- **Releases**: Automated via release-please; changelog auto-generated
+- **Threading**: All shared mutable state must be Mutex-protected. Provider storage uses immutable reassignment (`@providers = @providers.dup.merge(...)`)
+- **Structs for DTOs**: `EvaluationDetails`, `ResolutionDetails`, `ClientMetadata`, `ProviderMetadata` are `Struct`-based

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    openfeature-sdk (0.4.1)
+    openfeature-sdk (0.5.1)
 
 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.1">
+    <img alt="Release" src="https://img.shields.io/static/v1?label=release&message=v0.5.1&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

@@ -8,6 +8,7 @@ require_relative "evaluation_context"
 require_relative "evaluation_context_builder"
 require_relative "evaluation_details"
 require_relative "client_metadata"
+require_relative "hooks"
 require_relative "client"
 require_relative "provider"
 
@@ -51,6 +52,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

@@ -15,6 +15,7 @@ module OpenFeature
       }.freeze
       RESULT_TYPE = TYPE_CLASS_MAP.keys.freeze
       SUFFIXES = %i[value details].freeze
+      EMPTY_HINTS = Hooks::Hints.new.freeze
 
       attr_reader :metadata, :evaluation_context
 
@@ -27,14 +28,21 @@ 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
-            # def fetch_boolean_details(flag_key:, default_value:, evaluation_context: nil)
-            #   result = @provider.fetch_boolean_value(flag_key: flag_key, default_value: default_value, evaluation_context: evaluation_context)
-            # end
-            def fetch_#{result_type}_#{suffix}(flag_key:, default_value:, evaluation_context: nil)
-              evaluation_details = fetch_details(type: :#{result_type}, flag_key:, default_value:, evaluation_context:)
+            def fetch_#{result_type}_#{suffix}(flag_key:, default_value:, evaluation_context: nil, hooks: [], hook_hints: nil)
+              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
           RUBY
@@ -43,12 +51,54 @@ module OpenFeature
 
       private
 
-      def fetch_details(type:, flag_key:, default_value:, evaluation_context: nil)
+      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 = EvaluationContextBuilder.new.call(api_context: OpenFeature::SDK.evaluation_context, client_context: self.evaluation_context, invocation_context: evaluation_context)
+        built_context = EvaluationContextBuilder.new.call(
+          api_context: OpenFeature::SDK.evaluation_context,
+          client_context: self.evaluation_context,
+          invocation_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]
+
+        # Fast path: skip hook ceremony when no hooks are registered
+        if ordered_hooks.empty?
+          return evaluate_flag(type: type, flag_key: flag_key, default_value: default_value, evaluation_context: built_context)
+        end
+
+        hook_context = Hooks::HookContext.new(
+          flag_key: flag_key,
+          flag_value_type: type,
+          default_value: default_value,
+          evaluation_context: built_context,
+          client_metadata: @metadata,
+          provider_metadata: @provider.respond_to?(:metadata) ? @provider.metadata : nil
+        )
+
+        hints = if hook_hints.is_a?(Hooks::Hints)
+          hook_hints
+        elsif hook_hints
+          Hooks::Hints.new(hook_hints)
+        else
+          EMPTY_HINTS
+        end
+
+        executor = Hooks::HookExecutor.new(logger: OpenFeature::SDK.configuration.logger)
+        executor.execute(ordered_hooks: ordered_hooks, hook_context: hook_context, hints: hints) do |hctx|
+          evaluate_flag(type: type, flag_key: flag_key, default_value: default_value, evaluation_context: hctx.evaluation_context)
+        end
+      end
 
-        resolution_details = @provider.send(:"fetch_#{type}_value", flag_key:, default_value:, evaluation_context: built_context)
+      def evaluate_flag(type:, flag_key:, default_value:, evaluation_context:)
+        resolution_details = @provider.send(
+          :"fetch_#{type}_value",
+          flag_key: flag_key,
+          default_value: default_value,
+          evaluation_context: evaluation_context
+        )
 
         if TYPE_CLASS_MAP[type].none? { |klass| resolution_details.value.is_a?(klass) }
           resolution_details.value = default_value
@@ -56,7 +106,7 @@ module OpenFeature
           resolution_details.reason = Provider::Reason::ERROR
         end
 
-        EvaluationDetails.new(flag_key:, resolution_details:)
+        EvaluationDetails.new(flag_key: flag_key, resolution_details: resolution_details)
       end
 
       def validate_default_value_type(type, default_value)

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/hooks/hints.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "delegate"
+
 module OpenFeature
   module SDK
     module Hooks

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

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module OpenFeature
+  module SDK
+    module Hooks
+      # Module that hooks include. Provides default no-op implementations
+      # for all four lifecycle stages. A hook overrides the stages it cares about.
+      #
+      # Spec 4.3.1: Hooks MUST specify at least one stage.
+      module Hook
+        # Called before flag evaluation. May return an EvaluationContext
+        # that gets merged into the existing context (spec 4.3.2.1, 4.3.4, 4.3.5).
+        def before(hook_context:, hints:)
+          nil
+        end
+
+        # Called after successful flag evaluation (spec 4.3.3).
+        def after(hook_context:, evaluation_details:, hints:)
+          nil
+        end
+
+        # Called when an error occurs during flag evaluation (spec 4.3.6).
+        def error(hook_context:, exception:, hints:)
+          nil
+        end
+
+        # Called unconditionally after flag evaluation (spec 4.3.7).
+        def finally(hook_context:, evaluation_details:, hints:)
+          nil
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module OpenFeature
+  module SDK
+    module Hooks
+      # Provides context to hook stages during flag evaluation.
+      #
+      # Per spec 4.1.1-4.1.5:
+      # - flag_key, flag_value_type, default_value are immutable (4.1.3)
+      # - client_metadata, provider_metadata are optional (4.1.2)
+      # - evaluation_context is mutable (for before hooks to modify, 4.1.4.1)
+      class HookContext
+        attr_reader :flag_key, :flag_value_type, :default_value,
+          :client_metadata, :provider_metadata
+        attr_accessor :evaluation_context
+
+        def initialize(flag_key:, flag_value_type:, default_value:, evaluation_context:,
+          client_metadata: nil, provider_metadata: nil)
+          @flag_key = flag_key.freeze
+          @flag_value_type = flag_value_type.freeze
+          @default_value = default_value.freeze
+          @evaluation_context = evaluation_context
+          @client_metadata = client_metadata
+          @provider_metadata = provider_metadata
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module OpenFeature
+  module SDK
+    module Hooks
+      # Orchestrates the full hook lifecycle for flag evaluation.
+      #
+      # Hook execution order (spec 4.4.2):
+      #   Before: API → Client → Invocation → Provider
+      #   After/Error/Finally: Provider → Invocation → Client → API (reverse)
+      #
+      # Error handling (spec 4.4.3-4.4.7):
+      #   - Before/after hook error → stop remaining hooks, run error hooks, return default
+      #   - Error hook error → log, continue remaining error hooks
+      #   - Finally hook error → log, continue remaining finally hooks
+      class HookExecutor
+        def initialize(logger: nil)
+          @logger = logger
+        end
+
+        # Executes the full hook lifecycle around the flag evaluation block.
+        #
+        # @param ordered_hooks [Array] hooks in before-order (API, Client, Invocation, Provider)
+        # @param hook_context [HookContext] the hook context
+        # @param hints [Hints] hook hints
+        # @param evaluate_block [Proc] the flag evaluation to wrap
+        # @return [EvaluationDetails] the evaluation result
+        def execute(ordered_hooks:, hook_context:, hints:, &evaluate_block)
+          evaluation_details = nil
+
+          begin
+            run_before_hooks(ordered_hooks, hook_context, hints)
+            evaluation_details = evaluate_block.call(hook_context)
+            run_after_hooks(ordered_hooks, hook_context, evaluation_details, hints)
+          rescue => e
+            run_error_hooks(ordered_hooks, hook_context, e, hints)
+
+            evaluation_details = EvaluationDetails.new(
+              flag_key: hook_context.flag_key,
+              resolution_details: Provider::ResolutionDetails.new(
+                value: hook_context.default_value,
+                error_code: Provider::ErrorCode::GENERAL,
+                reason: Provider::Reason::ERROR,
+                error_message: e.message
+              )
+            )
+          ensure
+            run_finally_hooks(ordered_hooks, hook_context, evaluation_details, hints)
+          end
+
+          evaluation_details
+        end
+
+        private
+
+        # Spec 4.4.2: Before hooks run in order: API → Client → Invocation → Provider
+        # Spec 4.3.4/4.3.5: If a before hook returns an EvaluationContext, it is merged
+        # into the existing context for subsequent hooks and evaluation.
+        def run_before_hooks(hooks, hook_context, hints)
+          hooks.each do |hook|
+            next unless hook.respond_to?(:before)
+            result = hook.before(hook_context: hook_context, hints: hints)
+            if result.is_a?(EvaluationContext)
+              existing = hook_context.evaluation_context
+              hook_context.evaluation_context = existing ? existing.merge(result) : result
+            end
+          end
+        end
+
+        # Spec 4.4.2: After hooks run in reverse order: Provider → Invocation → Client → API
+        def run_after_hooks(hooks, hook_context, evaluation_details, hints)
+          hooks.reverse_each do |hook|
+            next unless hook.respond_to?(:after)
+            hook.after(hook_context: hook_context, evaluation_details: evaluation_details, hints: hints)
+          end
+        end
+
+        # Spec 4.4.4: Error hooks run in reverse order.
+        # If an error hook itself errors, log and continue remaining error hooks.
+        def run_error_hooks(hooks, hook_context, exception, hints)
+          hooks.reverse_each do |hook|
+            next unless hook.respond_to?(:error)
+            hook.error(hook_context: hook_context, exception: exception, hints: hints)
+          rescue => e
+            @logger&.error("Error hook #{hook.class.name} failed: #{e.message}")
+          end
+        end
+
+        # Spec 4.4.3: Finally hooks run in reverse order unconditionally.
+        # If a finally hook errors, log and continue remaining finally hooks.
+        def run_finally_hooks(hooks, hook_context, evaluation_details, hints)
+          hooks.reverse_each do |hook|
+            next unless hook.respond_to?(:finally)
+            hook.finally(hook_context: hook_context, evaluation_details: evaluation_details, hints: hints)
+          rescue => e
+            @logger&.error("Finally hook #{hook.class.name} failed: #{e.message}")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/open_feature/sdk/hooks.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require_relative "hooks/hints"
+require_relative "hooks/hook"
+require_relative "hooks/hook_context"
+require_relative "hooks/hook_executor"

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.1"
   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.1
 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:
@@ -136,6 +150,7 @@ files:
 - ".standard.yml"
 - ".tool-versions"
 - CHANGELOG.md
+- CLAUDE.md
 - CODEOWNERS
 - CODE_OF_CONDUCT.md
 - CONTRIBUTING.md
@@ -152,21 +167,30 @@ 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.rb
 - lib/open_feature/sdk/hooks/hints.rb
+- lib/open_feature/sdk/hooks/hook.rb
+- lib/open_feature/sdk/hooks/hook_context.rb
+- lib/open_feature/sdk/hooks/hook_executor.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