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.

[toddbaert]

@sameerank Hey! I'm also not the best with Ruby, but I authored a good deal of the specification, so I will do by best to review this at least from an "OpenFeature semantics" perspective. Expect a review from me tomorrow, and many thanks!

[dd-oleksii]

I've left a couple of nits and corner cases but looks good overall.

[dd-oleksii]

minor: I think it makes sense to always set original_error for ergonomics and semantics (it's a bit surprising that it is not set when there is an underlying error). The fact that it's now nilable is arguably a breaking change as well.

[dd-oleksii]

minor: this note seems inaccurate. PROVIDER_READY is only emitted automatically iff the provider does not include the EventHandler mixin. If the mixin is used, the provider must emit its own PROVIDER_READY event. (Which this example doesn't seem to do?)

[toddbaert]

Whether or not the provider implements events, the SDK should automatically emit READY/ERROR events when the init function succeeds/fails (raises exception in this case). More here: https://github.com/open-feature/ruby-sdk/pull/207/changes#r2624429319

[sameerank]

I believe these statements are made consistent with the code in d17fee9

dispatch_provider_event is now invoked as a lifecycle event irrespective of the EventHandler mixin being included in the provider. This works because these events go through the SDK's event system, which is a separate path

1. SDK events: init_provider → dispatch_provider_event → EventEmitter → registered handlers
2. Provider events: Provider code → emit_event (EventHandler mixin) → ProviderEventDispatcher → dispatch_provider_event → EventEmitter → registered handlers

Both SDK events and provider events end up going through the same global EventEmitter, but the EventHandler mixin provides the mechanism for providers to attach to emit their own custom events and detach for replacement, if needed.

The other SDKs have comparable opt-in patterns:

1. Go: EventHandler interface with channels
2. Java: EventProvider abstract class with emit() method, i.e. class MyEventProvider extends EventProvider to make a provider that supports spontaneous events
3. JavaScript: Optional events property with ProviderEventEmitter

[dd-oleksii]

major(spec): according Events | OpenFeature, PROVIDER_CONFIGURATION_CHANGED must not update the state. The default shall also be "no state changes."

[dd-oleksii]

nitpick: given how set_provider_internal is used (always acquiring mutex for a single call), it almost looks like this method should acquire the mutex internally. This would also make it easier to read that method (don't need to look back at all call sites to confirm that modifying @providers is safe).

It might also use a shorter synchronize block (e.g. calling init_provider inside the synchronize block seems like it can be problematic if provider blocks).

[sameerank]

fc4ab55

[dd-oleksii]

major: removing the timeout parameter is a breaking change. Is this intended?

[toddbaert]

Very good observation! It is a breaking change, but it's a divergence from the spec. I would actually recommend removing it. We instead prefer to have providers handle this themselves, with some kind of timeout, ideally specified in their options/constructors.

Simply adding a ! to the title (feat!: ...) will mark this change as breaking, which is fine since this is a <1.0 SDK.

[dd-oleksii]

minor: small sleeps in tests add up rather quickly. It's best if we can avoid sleeps and instead use async communication or time mocking.

[sameerank]

Agreed. Added Timecop as a dev dependency and used Timecop.travel to advance time and removed some sleeps

c5a117b

[dd-oleksii]

minor: attach/detach seem like internal methods (we don't expect users calling them) — shall we make them private or mark them internal?

[sameerank]

688c908

[dd-oleksii]

major(spec): one thing that seems to be missing is client-level event handlers. The user shall be able to attach event handler to specific clients instead of globally.

[toddbaert]

Correct: https://openfeature.dev/specification/sections/events#requirement-521

A corollary to this is "domain scoping" - a client bound to domain x should not get events originating from a provider from domain y. Additionally, late binding to domains should be observed. For example, initially a client bound to domain x will use the default provider, but if a new provider is bound to domain x, that becomes the provider from which the client sources its events.

See 5.1.2 and 5.1.3

[dd-oleksii]

major(spec):

Events | OpenFeature:

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

[toddbaert]

Ya I noticed this as well due to a skipped test case: #207 (comment)

[dd-oleksii]

major: PROVIDER_FATAL seems too harsh as it signal irrecoverable error. The provider might still be trying to initialize and emit PROVIDER_READY later, so non-fatal error is a safer choice.

[dd-oleksii]

minor: does it make sense to always initialize provider in a new thread and for set_provider_and_wait to wait for PROVIDER_READY event? Otherwise, set_provider_and_wait does not wait for async-initializing providers (which is its major reasons to exist).

[sameerank]

The specs themselves say little about sync-vs-async initialization, but from what I’ve gathered so far it looks like initialize is assumed to be blocking (Python, Java, etc.), except in languages with await/async (JS, Swift, etc.) where it’ll return a promise/task. Examples:

1. Async initialize: js-sdk, dotnet-sdk, swift-sdk
2. These initialize signatures cannot indicate if there are underlying async processes that need to be waited for and so are assumed to be blocking: java-sdk, python-sdk, go-sdk

And so in the example of js-sdk you can use an await to make an async initialization blocking and event handlers will still get triggered:

  async setProviderAndWait(provider: Provider): Promise<void> {
      await this.setAwaitableProvider(domain, provider);
  }

  protected setAwaitableProvider(domain, provider): Promise<void> | void {
    return provider.initialize?.(…)
      .then(() => {
      this._apiEmitter?.emit(AllProviderEvents.Ready, { … });
    }).catch((error) => {
      this._apiEmitter?.emit(AllProviderEvents.Error, { … });
    })
  }

Whereas in the java-sdk

    public void setProviderAndWait(FeatureProvider provider) throws OpenFeatureError {
        providerRepository.setProvider(provider, ..., true); // true = waitForInit
    }

And in this case, when waitForInit=true, initializeProvider() runs on the current thread and no extra events are emitted.

Since Ruby is in the same class of non-async/await languages, I think we follow the Java example. One thing that Go does differently though is that it also triggers event handlers when setting the provider with the synchronous wait. This might be something to carry over to Ruby because that matches up with Requirement 5.3.1 which is unconcerned with the sync-vs-async distinction.

If the provider's initialize function terminates normally, PROVIDER_READY handlers MUST run

[sameerank]

Actually this PR already fulfills Requirement 5.3.1. init_provider always calls dispatch_provider_event (irrespective of being invoked blocking the current thread or async in a separate thread):

ruby-sdk/lib/open_feature/sdk/configuration.rb

Lines 137 to 141 in fc4ab55

	unless provider.is_a?(Provider::EventHandler)
	dispatch_provider_event(provider, ProviderEvent::PROVIDER_READY)
	end
	rescue => e
	dispatch_provider_event(provider, ProviderEvent::PROVIDER_ERROR,

And dispatch_provider_event triggers all providers

ruby-sdk/lib/open_feature/sdk/configuration.rb

Line 165 in fc4ab55

run_handlers_for_provider(provider, event_type, event_details)

[toddbaert]

The emission of the READY/ERROR events should occur regardless of whether or not the provider is capable of emitting its own events.

The SDK should always emit either an init or error depending on the normal/abnormal termination of the provider's init method. If the provider has no init method, the SDK should just emit READY at the same point the method would have been called.

This is outlined here in section 5.3.

A bit more background:

The provider can "spontaneously" emit events (for instance, an error event if a persistent connection is lost) but the SDK emits events that correspond to the provider lifecycle and actions the application integrator has initiated (such as the READY event expected after a provider is set and initialized).

[dd-oleksii]

How should this work with asynchronous provider initialization?

I'm not too familiar with Ruby concurrency model, so sorry if my question does not make sense. My understanding is that set_provider should not block the thread (even if initialization takes a while) but set_provider_and_wait should. In languages that have promises, the SDK would wait for the initialization promise to resolve before emitting event, which may be much later that initialization function return.

Ruby doesn't have promises, so the options I see are:

1. wait for provider event before declaring it ready
2. let the provider block in initialization method
3. the current PR is a mix of the two, depending on whether provider is able to emit events

From what I gathered, the second option is preferred because we can't rule out a method blocking the thread and blocking seems very common in Ruby, so it's likely that many providers already implement it this way. I think it makes sense to ask initialize to always block before it's ready/error and always emit events after initialize returns. Now, if I'm correct that we want set_provider to be non-blocking, this means that we need to initialize provider in a new Thread, which seems suboptimal but it's not too bad.

Does this match your expectations?

[toddbaert]

From what I gathered, the second option is preferred because we can't rule out a method blocking the thread and blocking seems very common in Ruby, so it's likely that many providers already implement it this way. I think it makes sense to ask initialize to always block before it's ready/error and always emit events after initialize returns. Now, if I'm correct that we want set_provider to be non-blocking, this means that we need to initialize provider in a new Thread, which seems suboptimal but it's not too bad.

Yes, absolutely. This is exactly how other equivalent languages behave (Java is the obvious example). Provider init methods can block while the provider starts up (establishing connections, whatever...) and the SDK will start this method in a new thread and then fire the READY event when it completes. You can see that here in the Java SDK.

This also makes things nice and easy for provider authors - they can just do whatever work they need to in the init method, blocking, and the SDK takes care of the rest.

[sameerank]

So there are two types of events (spontaneous vs lifecycle events), and my mental model of the support matrix:

EventHandler mixin in provider	spontaneous provider events	SDK lifecycle events
❌ not included	❌ not supported	✅ always supported
✅ included	✅ supported	✅ always supported

If I got it right, then the fix is simply removal of the provider.is_a?(Provider::EventHandler) check. I also added a couple tests to verify:

The emission of the READY/ERROR events should occur regardless of whether or not the provider is capable of emitting its own events.

If the provider has no init method, the SDK should just emit READY

d17fee9

[toddbaert]

I think we need to implement this as well before a release. If this PR is getting too big, I don't mind if it gets done in a separate one, but I don't want it to linger un-implemented too long.

[sameerank]

It just a little extra code, so I'm doing it here. Implemented and tested for both API-level and client-level handlers: 31ddc6f#diff-5c0a7cf78bb2cdb2c4302271ce8254af79024949d009a3dd4978dd5bfc3b3a41

[toddbaert]

@sameerank excellent work, this is great progress.

I've left some feedback. The main things missing that I can see are around automatic event emission at provider init, and missing client event handlers (as well as the associated domain scoping, which can be tricky to implement).

Please check the Java and JS SDKs for tests and implementation around these, as they may be helpful.

Thanks so much for your efforts! ❤️

[toddbaert]

@dd-oleksii Thanks for your detailed reviews as well 🙏

[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