feat: Hook support for client class

[NeaguGeorgiana23]

This PR

• Implements client side hook registration methods (AddHook, AddHooks, GetHooks) on the Client interface and ClientAPI class specified in OpenFeature Specification Requirement 1.2.1.
• Adds thread-safe hook storage in ClientAPI using std::shared_mutex for reader-writer concurrency.
• Ensures nullptr entries are filtered out when registering hooks and registration order is preserved.
• Updates BUILD dependencies for client, client_api, and client_api_test targets.
• Adds unit tests in test/client_api_test.cpp covering initial state, single/multiple hook registration, order preservation, and null filtering.

Related Issues

Fixes #126

Notes

• Hooks registered at the client level are isolated to that client instance and will be merged into the evaluation pipeline alongside global API, invocation, and provider hooks.

Follow-up Tasks

• Implement the hook execution lifecycle pipeline (before, after, error, finally) inside ClientAPI::EvaluateFlag.
• Add overloads for flag evaluation methods accepting EvaluationOptions (for invocation-level hooks and hints).
• Add detailed flag evaluation methods (Get*Details).

[coderabbitai]

Warning

Review limit reached

@NeaguGeorgiana23, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 44 minutes

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 8e3ed061-8fbb-4f6c-a185-9e359d5bf0d5

📥 Commits

Reviewing files that changed from the base of the PR and between 0b6c84b and 098cf4a.

📒 Files selected for processing (2)

• openfeature/client.h
• openfeature/client_api.cpp

📝 Walkthrough

Walkthrough

The PR adds EvaluationOptions overloads to typed flag evaluation APIs. It adds client-level and global hook registration, retrieval, null filtering, synchronization, ordering, and shutdown cleanup. It also separates default and domain-specific provider accessors.

Changes

Evaluation and client hook APIs

Layer / File(s)	Summary
Evaluation options propagation openfeature/features.h, openfeature/client_api.h, openfeature/client_api.cpp, test/client_api_test.cpp	Typed flag evaluation accepts optional EvaluationOptions with implicit or explicit contexts. Tests cover all supported value types.
Client hook management openfeature/client.h, openfeature/client_api.h, openfeature/client_api.cpp, test/client_api_test.cpp	Client APIs add, append, filter, and retrieve hooks with synchronized storage.
Global hooks and provider access openfeature/openfeature.h, openfeature/openfeature_api.h, openfeature/openfeature_api.cpp, test/openfeature_api_test.cpp	Global hook APIs use synchronized storage and clear hooks during Shutdown(). Provider, metadata, and status accessors now have explicit default and domain overloads.
Build and compatibility validation openfeature/BUILD, test/BUILD, openfeature/flag_evaluation_details.h, openfeature/hook.h, test/hook_test.cpp	Build targets include the new API dependencies. Header guard comments and an unchanged namespace closing line are updated. Tests cover contexts, hooks, provider status, null filtering, and cleanup.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Sequence Diagram(s)

sequenceDiagram
  participant ClientAPI
  participant EvaluateFlag
  participant FeatureProvider
  ClientAPI->>EvaluateFlag: pass EvaluationContext and EvaluationOptions
  EvaluateFlag->>FeatureProvider: evaluate typed flag
  FeatureProvider-->>ClientAPI: return typed evaluation result

Loading

sequenceDiagram
  participant Application
  participant OpenFeatureAPI
  participant HookStorage
  Application->>OpenFeatureAPI: AddHook or AddHooks
  OpenFeatureAPI->>HookStorage: store valid hooks under lock
  Application->>OpenFeatureAPI: GetHooks
  OpenFeatureAPI-->>Application: return hook snapshot
  Application->>OpenFeatureAPI: Shutdown
  OpenFeatureAPI->>HookStorage: clear registered hooks

Loading

Possibly related PRs

• open-feature/cpp-sdk#118: Adds the GeneralHook API used by the new client and global hook registration.
• open-feature/cpp-sdk#120: Adds the EvaluationOptions type used by the new evaluation overloads.
• open-feature/cpp-sdk#121: Adds provider-level hook access complemented by these client and global hook APIs.

Suggested reviewers: m-olko

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Out of Scope Changes check	⚠️ Warning	Global hook APIs, provider accessor changes, and EvaluationOptions overloads extend beyond the client-hook objective in [#126].	Limit this pull request to client-level hook registration, or split global hook and EvaluationOptions changes into separate issues and pull requests.
Docstring Coverage	⚠️ Warning	Docstring coverage is 31.25% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly identifies client hook support, which is the primary change in the pull request.
Description check	✅ Passed	The description accurately covers client hooks, thread safety, filtering, ordering, dependencies, and tests related to the changeset.
Linked Issues check	✅ Passed	The pull request implements client-level hook registration, ordering, null filtering, thread safety, and tests required by [#126].

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

openfeature/openfeature.h (1)

40-62: 🗄️ Data Integrity & Integration | 🟠 Major | 🏗️ Heavy lift

Preserve compatibility for existing OpenFeature implementations.

The previous interface used default arguments on the domain overloads. The new pure virtual overloads for GetProvider, GetProviderMetadata, and GetProviderStatus make existing subclasses abstract after recompilation. They also change the vtable layout for existing binaries.

Keep the domain overloads as the virtual extension points. Implement the no-argument overloads as non-virtual forwarding helpers, or document this as a major-version ABI and source-compatibility break.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@openfeature/openfeature.h` around lines 40 - 62, Preserve source and binary
compatibility in the OpenFeature interface by making the no-argument
GetProvider, GetProviderMetadata, and GetProviderStatus overloads non-virtual
forwarding helpers, while retaining the domain overloads as the virtual
extension points. Ensure each helper delegates to the corresponding
default-domain behavior without requiring existing OpenFeature subclasses to
implement new pure virtual methods.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@openfeature/client_api.h`:
- Around line 9-14: Update openfeature/client_api.h to include the standard
<shared_mutex> header directly, alongside the existing standard-library
includes, so its std::shared_mutex declaration does not rely on transitive
inclusion.

---

Outside diff comments:
In `@openfeature/openfeature.h`:
- Around line 40-62: Preserve source and binary compatibility in the OpenFeature
interface by making the no-argument GetProvider, GetProviderMetadata, and
GetProviderStatus overloads non-virtual forwarding helpers, while retaining the
domain overloads as the virtual extension points. Ensure each helper delegates
to the corresponding default-domain behavior without requiring existing
OpenFeature subclasses to implement new pure virtual methods.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 248816f4-a3f8-4c5f-8ec1-0b65d94bcc19

📥 Commits

Reviewing files that changed from the base of the PR and between 4c1bb41 and 0b6c84b.

📒 Files selected for processing (14)

• openfeature/BUILD
• openfeature/client.h
• openfeature/client_api.cpp
• openfeature/client_api.h
• openfeature/features.h
• openfeature/flag_evaluation_details.h
• openfeature/hook.h
• openfeature/openfeature.h
• openfeature/openfeature_api.cpp
• openfeature/openfeature_api.h
• test/BUILD
• test/client_api_test.cpp
• test/hook_test.cpp
• test/openfeature_api_test.cpp