feat!: add provider eventing, remove setProvider timeout

[sameerank]

This PR

Fixes the behavior of set_provider_and_wait and implements eventing to trigger event handlers on changes to provider state.

What was wrong?

Both set_provider and set_provider_and_wait initialize synchronously. By fixing set_provider to be non-blocking, it is also useful to have eventing, so the SDK can be used to trigger handlers according to background provider updates.

The Ruby SDK was missing the provider lifecycle event system defined in the OpenFeature specification, which other SDKs use for monitoring provider state changes and enabling event-driven workflows.

What this PR does:

• Makes set_provider non-blocking - returns immediately and initializes in a background thread, enabling async operation
• Implements provider lifecycle events (PROVIDER_READY, PROVIDER_ERROR, etc.) as defined in the Events specification to enable event-driven workflows
• Adds provider state management - tracks provider states (NOT_READY, READY, ERROR, FATAL, STALE) as defined in the Provider Status specification
• Enables background provider monitoring - providers can emit events for configuration changes, connection issues, etc.
• Breaking change: Removed timeout parameter from set_provider_and_wait to align with other OpenFeature SDKs (Go and Java don't support timeouts)

Key changes:

1. Event System Foundation:

   • EventEmitter - thread-safe pub/sub for provider events (based on Go SDK's eventExecutor)
   • ProviderEvent constants matching the Events specification
   • EventToStateMapper for state transitions per Provider Status specification

2. Provider Interface (opt-in via mixin, based on Go SDK patterns):

   • EventHandler - event emission capabilities based on Go's EventHandler

3. Provider Initialization:

   • Blocking pattern: Provider init() methods are expected to block until ready
   • OpenFeature::SDK.set_provider(provider) - runs init in background thread (non-blocking API call)
   • OpenFeature::SDK.set_provider_and_wait(provider) - runs init synchronously and blocks until complete (Req 1.1.2.4)
   • Events are emitted automatically by SDK after init completion and can be used by consumers via handlers

4. Error Handling and Logging:

   • Exception handling (rescues StandardError only, not all exceptions)
   • ProviderInitializationError exception for set_provider_and_wait failures with structured error details (provider, error_code, original_error)
   • Provider events use hash-based error details ({error_code:, message:}) similar to Java's ProviderEventDetails
   • Configurable logger support (config.logger = my_logger) - Note: Go SDK deprecated SetLogger, Java uses SLF4J facade
   • Events include error codes and messages only (not full exceptions) - matching Go's event structure and Java's pattern

5. Testing:

   • Specification requirement tests for traceability
   • 100% test coverage + Standard Ruby linting

Related Issues

Fixes #51

Notes

• This implementation mostly follows the Go SDK but adapted for Ruby (opt-in event support via mixins, similar to Go's interface approach) with some difference, e.g. Ruby uses callbacks for event handlers vs Go's interface-based approach.
• Ruby allows user-configurable logging while Go only logs panics internally and Java delegates to SLF4J
• Changes are mostly backward compatible - providers don't need modifications unless they want event capabilities or were using the timeout parameter in set_provider_and_wait

Follow-up Tasks

• Documentation updates/migration guide for events support in the Ruby SDK
• Consider adding client-level event handlers (currently only API-level) as described in Req 5.2.1 bfb771d
• Something I noticed: RFC 2119 compliance cleanup in specification tests (key words like MUST, SHOULD, MAY, etc. are typically in caps)

How to test

1. Basic functionality:

# Async initialization (non-blocking)
OpenFeature::SDK.set_provider(MyProvider.new)  # Returns immediately

# Blocking initialization
OpenFeature::SDK.set_provider_and_wait(MyProvider.new)  # Blocks until ready

2. Event handlers:

OpenFeature::SDK.add_handler(OpenFeature::SDK::ProviderEvent::PROVIDER_READY) do |event|
  puts "Provider #{event[:provider_name]} is ready!"
end

3. Run the test suite:

bundle exec rspec
# 447 / 447 LOC (100.0%) covered.

4. Example provider:

# Provider using EventHandler
class CustomProvider
  include OpenFeature::SDK::Provider::EventHandler

  def init(evaluation_context)
    # Initialize provider synchronously - blocks until ready
    fetch_configuration  # This should block
    # Note: SDK automatically emits PROVIDER_READY when init completes
    
    # Start background process to monitor for runtime changes
    Thread.new do
      monitor_for_config_changes
      if configuration_changed?
        emit_event(OpenFeature::SDK::ProviderEvent::PROVIDER_CONFIGURATION_CHANGED,
                   message: "Configuration updated")
      end
    end
  end
end

[gemini-code-assist]

Summary of Changes

Hello @sameerank, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request addresses a critical issue where the set_provider_and_wait method did not actually wait for providers to be ready, leading to potential race conditions and incorrect flag evaluations. It introduces a robust, OpenFeature-compliant provider lifecycle event system, enabling asynchronous provider initialization and reliable state management. This change ensures that the SDK correctly handles provider readiness and errors, improving stability and adherence to the specification.

Highlights

• Provider Event System: Introduced a comprehensive event system for providers, including EventEmitter for thread-safe pub/sub, ProviderEvent constants, and EventToStateMapper for state transitions, aligning with OpenFeature specifications.
• Asynchronous Provider Initialization: Refactored set_provider to be non-blocking, initializing providers in background threads. This allows for asynchronous operations without blocking the main thread.
• Corrected set_provider_and_wait Behavior: Fixed set_provider_and_wait to properly block until a PROVIDER_READY or PROVIDER_ERROR event is received, ensuring providers are ready before returning, fulfilling a critical OpenFeature requirement.
• Provider State Management: Implemented ProviderStateRegistry to track provider states (NOT_READY, READY, ERROR, FATAL, STALE) based on emitted events, providing better visibility into provider lifecycle.
• New Provider Interfaces: Added opt-in mixins for provider interfaces: StateHandler (init/shutdown), EventHandler (event emission), and ContextAwareStateHandler (timeout support for init/shutdown), inspired by the Go SDK.
• Backward Compatibility: Ensured that existing providers continue to function without modification, while new interfaces allow for enhanced event-driven capabilities.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request is a significant and well-executed enhancement that introduces a provider eventing system, aligning the Ruby SDK more closely with the OpenFeature specification. The core improvement is fixing set_provider_and_wait to correctly block until a provider is ready, which is achieved through a robust, thread-safe event mechanism using EventEmitter, ProviderStateRegistry, and new provider interfaces (EventHandler, StateHandler). The changes are thoughtfully designed to be backward-compatible, and the comprehensive new test suite, including specification compliance tests, is excellent.

My feedback focuses on a few areas to further improve robustness and maintainability: refining exception handling to be more specific, enhancing debuggability by preserving original error information in event payloads, and cleaning up a small amount of unused code.

[gemini-code-assist]

Code Review

This pull request is a fantastic and significant improvement. It correctly implements the provider eventing system as specified by OpenFeature, fixing the broken behavior of set_provider_and_wait. The introduction of EventEmitter, EventHandler, and state management is well-structured and thread-safe. The changes are also backward compatible, which is a huge plus. The test coverage for the new asynchronous logic is thorough. I've found a few minor but important issues related to overly broad exception handling (rescue => e) and a small redundancy in event payload creation, which I've commented on. Once these are addressed, this PR will be in excellent shape.

[gemini-code-assist]

Code Review

This is an excellent pull request that introduces a provider eventing system, aligning the Ruby SDK more closely with the OpenFeature specification. The implementation correctly fixes the behavior of set_provider_and_wait and makes set_provider non-blocking, which is a great improvement for providers requiring asynchronous initialization. The code is well-structured, with clear separation of concerns into new modules and classes for eventing and state management. The test coverage is comprehensive and thoughtful, especially the tests for backward compatibility and specification compliance.

I have identified a few areas for improvement, primarily focusing on enhancing thread safety and encapsulation. Specifically, I've pointed out a potential race condition in the error handling of set_provider_and_wait and suggested a way to improve how the logger is managed. These changes will make the implementation more robust in concurrent environments. Overall, this is a very strong contribution.

[gemini-code-assist]

Code Review

This is an excellent and comprehensive pull request that addresses a critical issue with set_provider_and_wait and brings the Ruby SDK much closer to the OpenFeature specification for provider eventing. The introduction of an asynchronous, event-driven provider lifecycle is a significant improvement.

I'm impressed by the thoroughness of the implementation, including:

• Thread-safe event emitter and state management.
• Correct handling of asynchronous initialization and error conditions.
• Thoughtful approach to backward compatibility, allowing old providers to function without modification.
• Extensive test coverage, including tests for concurrency, which gives high confidence in these complex changes.

I have one suggestion regarding the creation of the event dispatcher in Configuration#set_provider to improve code clarity and maintainability.

Overall, this is a high-quality contribution that significantly enhances the SDK's functionality and robustness.

[gemini-code-assist]

Code Review

This pull request introduces a comprehensive provider eventing system, which is a significant and well-executed feature. It successfully fixes the behavior of set_provider_and_wait to be truly blocking and aligns the SDK with the OpenFeature specification for provider events. The implementation includes a thread-safe event emitter, new provider mixins for lifecycle management, and asynchronous provider initialization, all supported by a thorough test suite. I've identified a couple of critical scoping issues that would cause runtime errors and a minor opportunity for code cleanup. Overall, this is an excellent contribution to the SDK.

[gemini-code-assist]

Code Review

This is a fantastic pull request that brings the Ruby SDK much closer to the OpenFeature specification for provider events and lifecycle. The implementation of an async set_provider and a truly blocking set_provider_and_wait using a thread-safe event system is well-executed. The code is clean, modular, and impressively well-tested, covering backward compatibility, thread safety, and specification requirements.

I've found two potential race conditions with high severity that should be addressed:

1. In Configuration#set_provider_and_wait, there's a race condition that could lead to incorrect provider state restoration on initialization failure.
2. In Provider::EventHandler#emit_event, a race condition could lead to a NoMethodError if a provider is detached concurrently.

After addressing these concurrency issues, this PR will be a very strong and valuable addition to the SDK. Great work on the thoroughness and quality of this change.

[gemini-code-assist]

Code Review

This is an excellent and comprehensive implementation of the provider eventing system, aligning the Ruby SDK more closely with the OpenFeature specification. The changes are well-structured, thread-safe, and maintain backward compatibility. The introduction of EventEmitter, StateHandler, and EventHandler provides a solid foundation for asynchronous providers. The new test suites are thorough and cover many edge cases, which is great to see.

I've found one critical issue related to handling nil providers during shutdown and have one suggestion to improve the maintainability of the new test files. Overall, this is a very strong contribution.

[gemini-code-assist]

Code Review

This pull request introduces a comprehensive event handling and provider state management system to the OpenFeature SDK. The set_provider method is now asynchronous, initializing providers in a separate thread, while a new set_provider_and_wait method provides blocking initialization with timeout and error handling, including reverting to the previous provider on failure. This is achieved through new EventEmitter and ProviderStateRegistry classes, along with EventHandler and StateHandler mixins for providers to implement event emission and lifecycle methods. The API now exposes methods for managing event handlers and configuring the logger. Review comments suggest enhancing error and warning messages in Configuration by including the provider's class name for improved debugging, and raise a concern about the fragility of relying on init method arity for argument handling.

[gemini-code-assist]

Code Review

This is a substantial and well-executed feature addition. It correctly implements the provider eventing system according to the OpenFeature specification, which fixes the behavior of set_provider_and_wait. The use of Thread for async initialization, Queue for synchronization, and Mutex for protecting shared state is well-handled. The new modules and classes (EventEmitter, EventHandler, ProviderStateRegistry, etc.) are well-structured and promote good design patterns. Backward compatibility for existing providers is also thoughtfully implemented. The test coverage is excellent, with new unit tests, async-specific tests, and specification compliance tests. I have a couple of suggestions for minor refactoring to improve robustness and simplify the code, but overall this is a high-quality contribution.

[gemini-code-assist]

Code Review

This is an excellent pull request that implements a comprehensive provider eventing system, correctly fixing the behavior of set_provider_and_wait. The changes are well-structured, thoroughly tested, and align with the OpenFeature specification. The use of background threads for initialization, Queue for synchronization, and careful handling of backward compatibility are all well-executed. My feedback is minor, focusing on improving consistency by using defined constants instead of string literals in a couple of places.

[sameerank]

I concede that it is odd to have a hash with just one attribute, but when I look through the SDKs provider_name seems to be the only consistent attribute in all of them. E.g.

js-sdk

export type CommonEventDetails = {
  readonly providerName: string;
  /**
   * @deprecated alias of "domain", use domain instead
   */
  readonly clientName?: string;
  readonly domain?: string;
};

go-sdk

type EventDetails struct {
	ProviderName string
	ProviderEventDetails
}

python-sdk

class EventDetails(ProviderEventDetails):
    provider_name: str = ""
    flags_changed: typing.Optional[list[str]] = None
    message: typing.Optional[str] = None
    error_code: typing.Optional[ErrorCode] = None
    metadata: dict[str, typing.Union[bool, str, int, float]] = field(
        default_factory=dict
    )

And this is the only one marked as "required" in the spec https://openfeature.dev/specification/types#event-details

So I'm thinking it's okay to keep this minimal for now and add the others later

[sameerank]

The SDKs vary in how they interpreted Requirement 5.3.3 for the immediate invocation of the handler

Handlers attached after the provider is already in the associated state, MUST run immediately.

The python-sdk only runs the handler on the default provider-client.

def add_global_handler(event: ProviderEvent, handler: EventHandler) -> None:
    with _global_lock:
        _global_handlers[event].append(handler)

    from openfeature.api import get_client  # noqa: PLC0415

    _run_immediate_handler(get_client(), event, handler)

The go-sdk behaves similarly.

	e.emitOnRegistration(defaultDomain, e.defaultProviderReference, t, c)

These are effectively treating the following the two scenarios as the same at the time of adding a global handler

1. from openfeature import api; client = api.get_client(); client.add_handler(...
2. from openfeature import api; api.add_handler(...

But later, events from any provider can trigger the global handler even if they didn't at the time of adding the global handler.

The js-client takes a different approach and checks all the providers.

[...new Map([[undefined, this._defaultProvider]]), ...this._domainScopedProviders].forEach((keyProviderTuple) => {

I went with the js-client's approach because it makes more sense to me, to not have two ways of doing the same thing, and also it feels more consistent for an API-level handler to behave "global" in scope both at the time of being added, and later when domain-scoped providers trigger the global handler

[sameerank]

The race condition scenario is multiple threads setting the same provider instance concurrently:

• Thread A: set_provider(provider_x)
• Thread B: set_provider(provider_x) <-- same provider

What would happen without the old_provider != provider check:

1. Thread A captures old_provider = nil, because @providers = {} and sets provider_x
2. Thread B captures old_provider = provider_x, sets provider_x (same provider)
3. Thread A skips shutdown because no old_provider ✅ (correct)
4. Thread B calls provider_x.shutdown() ❌ This is a problem because it shuts down the active provider

Tested with

ruby-sdk/spec/open_feature/sdk/configuration_spec.rb

Line 57 in f78e5de

it "does not call shutdown on same provider instance when set multiple times concurrently" do

which fails without the check

[sameerank]

The updated reset method invokes @event_dispatcher.clear_all_handlers which also clears the SDK-level handlers, which were set in other tests that do OpenFeature::SDK.add_handler

With the updated reset method, we no longer need to account for + 1 additional due to SDK because that was cleared too

[toddbaert]

Hey thanks again. I will take a look at this again on Monday.