feat: implement hooks lifecycle (spec section 4)

[josecolella]

Tip

Best reviewed commit-by-commit

Summary

• Implements the full OpenFeature hooks lifecycle per specification section 4
• Adds Hook interface module, HookContext class, and HookExecutor engine
• Integrates hooks into Client flag evaluation with proper ordering (API → Client → Invocation → Provider for before; reverse for after/error/finally)
• Includes a no-hooks fast path to avoid allocations when hooks aren't registered
• Replaces pending tests for Requirements 1.1.4 and 1.2.1

Closes #52

Test plan

• 320 examples, 0 failures (full bundle exec rake)
• 99.31% code coverage
• StandardRB lint clean (58 files, no offenses)
• Hooks unit tests: spec/open_feature/sdk/hooks/
• Hooks spec compliance tests: spec/specification/hooks_spec.rb
• No regressions in existing tests: spec/open_feature/sdk/client_spec.rb, spec/specification/flag_evaluation_api_spec.rb

🤖 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 by introducing a robust and spec-compliant hooks lifecycle. It allows developers to inject custom logic at various stages of flag evaluation, from before the evaluation to after, error handling, and final cleanup. This feature provides greater flexibility and control over how feature flags are processed, enabling advanced use cases like context modification, metric collection, and error recovery, all while maintaining performance with an optimized execution path.

Highlights

• Full Hooks Lifecycle Implementation: Implemented the complete OpenFeature hooks lifecycle as defined in specification section 4, enabling custom logic at various stages of flag evaluation.
• New Hooks Modules and Engine: Introduced a Hook interface module, a HookContext class for providing evaluation context to hooks, and a HookExecutor engine to manage the execution of hooks.
• Integrated Hook Ordering: Integrated hooks into the Client flag evaluation process with the specified ordering: API → Client → Invocation → Provider for 'before' hooks, and the reverse for 'after', 'error', and 'finally' hooks.
• Performance Optimization: Included a 'no-hooks fast path' to avoid unnecessary allocations and overhead when no hooks are registered for a given flag evaluation.
• Updated Specification Compliance Tests: Replaced pending tests for Requirements 1.1.4 and 1.2.1, and added comprehensive new tests to ensure full compliance with the OpenFeature hooks specification.

Changelog

• lib/open_feature/sdk/api.rb
  • Added a new require statement for the 'hooks' module.
• lib/open_feature/sdk/client.rb
  • Added EMPTY_HINTS constant for performance optimization.
  • Modified fetch_ methods to accept hooks and hook_hints parameters.
  • Refactored fetch_details to orchestrate the hook lifecycle using HookExecutor.
  • Introduced a new private method evaluate_flag to encapsulate the core flag resolution logic.
• lib/open_feature/sdk/hooks.rb
  • Added a new module to consolidate and require all hook-related components.
• lib/open_feature/sdk/hooks/hints.rb
  • Added a require statement for the 'delegate' library.
• lib/open_feature/sdk/hooks/hook.rb
  • Added a new module Hook defining the before, after, error, and finally lifecycle methods with no-op default implementations.
• lib/open_feature/sdk/hooks/hook_context.rb
  • Added a new class HookContext to encapsulate immutable flag evaluation details and a mutable evaluation context for hooks.
• lib/open_feature/sdk/hooks/hook_executor.rb
  • Added a new class HookExecutor responsible for orchestrating the execution of hooks in the correct order and handling errors during the lifecycle.
• spec/open_feature/sdk/hooks/hook_context_spec.rb
  • Added new unit tests for the HookContext class, verifying immutability and mutability of its properties.
• spec/open_feature/sdk/hooks/hook_executor_spec.rb
  • Added new unit tests for the HookExecutor class, covering hook execution order, context merging, and error handling scenarios.
• spec/open_feature/sdk/hooks/hook_spec.rb
  • Added new unit tests for the Hook module, verifying default implementations and the ability to override stages.
• spec/specification/flag_evaluation_api_spec.rb
  • Updated and implemented previously pending tests for API and Client hook registration (Requirements 1.1.4 and 1.2.1).
• spec/specification/hooks_spec.rb
  • Added a new comprehensive specification compliance test file for the OpenFeature hooks, covering all requirements from section 4.
• spec/support/recording_hook_helper.rb
  • Added a new helper module RecordingHookHelper to facilitate testing hook execution order by logging calls.

Activity

• Implemented the full OpenFeature hooks lifecycle per specification section 4.
• Added Hook interface module, HookContext class, and HookExecutor engine.
• Integrated hooks into Client flag evaluation with proper ordering (API → Client → Invocation → Provider for before; reverse for after/error/finally).
• Included a no-hooks fast path to avoid allocations when hooks aren't registered.
• Replaced pending tests for Requirements 1.1.4 and 1.2.1.
• Achieved 320 examples, 0 failures in full test suite.
• Maintained 99.31% code coverage.
• Ensured StandardRB lint clean with no offenses.

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. ↩

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 99.64%. Comparing base (e347439) to head (6e30988).
⚠️ Report is 2 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #214      +/-   ##
==========================================
+ Coverage   99.59%   99.64%   +0.05%     
==========================================
  Files          22       26       +4     
  Lines         491      571      +80     
==========================================
+ Hits          489      569      +80     
  Misses          2        2              

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[gemini-code-assist]

Code Review

This pull request implements the full OpenFeature hooks lifecycle, which is a major feature. The implementation is well-structured, following the specification closely. New components like HookExecutor, HookContext, and the Hook module are introduced, and they are integrated into the Client's flag evaluation process. The inclusion of a fast path for when no hooks are present is a good performance consideration. The code is accompanied by a comprehensive suite of unit and specification compliance tests, which is excellent. I have one suggestion regarding the immutability of default_value in the HookContext to fully align with the specification. Overall, this is a high-quality contribution.