feat: add shutdown API, provider status, and status short-circuit

[josecolella]

Summary

• Add API#shutdown that propagates shutdown to all registered providers and clears state (spec 1.6.1, 1.6.2)
• Add Client#provider_status accessor returning the provider's current state (spec 1.7.1)
• Add short-circuit guard in Client#fetch_details for NOT_READY and FATAL provider states — returns default value with appropriate error code instead of calling the provider (spec 1.7.6, 1.7.7)
• Add ProviderStateRegistry#tracked? to distinguish unregistered providers from NOT_READY ones

Spec References

• Requirement 1.6.1 — shutdown mechanism
• Requirement 1.6.2 — shutdown invokes provider shutdown
• Requirement 1.7.1 — provider status accessor
• Requirement 1.7.6 — NOT_READY short-circuit
• Requirement 1.7.7 — FATAL short-circuit

Part of the spec compliance roadmap: #220

Test plan

• bundle exec rspec spec/specification/flag_evaluation_api_spec.rb — all pass
• bundle exec rspec spec/open_feature/sdk/client_spec.rb — all pass (no regression)
• bundle exec standardrb — no offenses

🤖 Jose's AI agent

[gemini-code-assist]

Summary of Changes

Hello, 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 significantly enhances the OpenFeature SDK's compliance with the specification by introducing robust mechanisms for managing provider lifecycles and handling their operational states. It allows for graceful shutdown of providers, provides a clear way to query their readiness, and ensures that flag evaluations are handled safely and predictably when providers are not fully operational.

Highlights

• Shutdown API: Added an API#shutdown method that propagates shutdown requests to all registered providers and clears their state, aligning with OpenFeature specification requirements 1.6.1 and 1.6.2.
• Provider Status Accessor: Introduced a Client#provider_status accessor to retrieve the current readiness state of the associated provider, fulfilling specification requirement 1.7.1.
• Short-Circuit Flag Evaluation: Implemented short-circuiting logic in Client#fetch_details for NOT_READY and FATAL provider states. If a provider is in one of these states, flag evaluation will immediately return the default value with an appropriate error code, as per specification requirements 1.7.6 and 1.7.7.
• Provider Tracking: Added ProviderStateRegistry#tracked? to distinguish between providers that are explicitly unregistered and those that are merely in a NOT_READY state.

Changelog

• lib/open_feature/sdk/api.rb
  • Added shutdown method to the API module.
• lib/open_feature/sdk/client.rb
  • Added provider_status method to retrieve the provider's state.
  • Implemented short-circuit logic in fetch_details for NOT_READY and FATAL provider states.
• lib/open_feature/sdk/configuration.rb
  • Added provider_state method to get a provider's state from the registry.
  • Added provider_tracked? method to check if a provider is being tracked.
  • Implemented shutdown method to iterate and shut down all registered providers.
  • Relocated provider_state method from a private section to a public interface.
• lib/open_feature/sdk/provider_state_registry.rb
  • Added tracked? method to determine if a provider's state is being managed.
• spec/specification/flag_evaluation_api_spec.rb
  • Added new test contexts for '1.6 - Shutdown' and '1.7 - Provider Status'.
  • Included tests for OpenFeature::SDK.shutdown functionality, ensuring provider shutdown and state clearing.
  • Added tests for Client#provider_status accessor.
  • Implemented tests for short-circuit behavior in fetch_details when provider state is NOT_READY or FATAL.

Activity

• The author has confirmed that bundle exec rspec spec/specification/flag_evaluation_api_spec.rb passes all tests.
• The author has confirmed that bundle exec rspec spec/open_feature/sdk/client_spec.rb passes all tests without regression.
• The author has confirmed that bundle exec standardrb reports no offenses, indicating adherence to code style guidelines.

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 introduces several key features aligned with the OpenFeature specification, including a shutdown API for registered providers, a client-side accessor for provider status, and short-circuiting logic in flag evaluation for NOT_READY and FATAL provider states. The changes are well-tested and contribute significantly to the SDK's compliance and robustness.

[gemini-code-assist]

The logic for handling NOT_READY and FATAL provider states in fetch_details contains some duplication in the creation of Provider::ResolutionDetails and EvaluationDetails. This can be refactored to improve readability and reduce redundancy by determining the error_code once and then constructing the resolution details.

For example, you could set the error_code based on the state within a single conditional block.

        if OpenFeature::SDK.configuration.provider_tracked?(@provider)
          error_code = nil
          case state
          when ProviderState::NOT_READY
            error_code = Provider::ErrorCode::PROVIDER_NOT_READY
          when ProviderState::FATAL
            error_code = Provider::ErrorCode::PROVIDER_FATAL
          end

          if error_code
            resolution = Provider::ResolutionDetails.new(
              value: default_value,
              error_code: error_code,
              reason: Provider::Reason::ERROR
            )
            return EvaluationDetails.new(flag_key: flag_key, resolution_details: resolution)
          end
        end