feat: Update global api

openfeature/BUILD

@@ -4,6 +4,12 @@ package(
     default_visibility = ["//visibility:public"],
 )
 
+cc_library(
+    name = "base_hook",
+    hdrs = ["base_hook.h"],
+    include_prefix = "openfeature",
+)
+
 cc_library(
     name = "client",
     hdrs = ["client.h"],
@@ -50,6 +56,16 @@ cc_library(
     include_prefix = "openfeature",
 )
 
+cc_library(
+    name = "evaluation_options",
+    hdrs = ["evaluation_options.h"],
+    include_prefix = "openfeature",
+    deps = [
+        ":base_hook",
+        ":hook_hints",
+    ],
+)
+
 cc_library(
     name = "feature_provider_status_manager",
     srcs = ["feature_provider_status_manager.cpp"],
@@ -74,6 +90,20 @@ cc_library(
     ],
 )
 
+cc_library(
+    name = "flag_evaluation_details",
+    srcs = ["flag_evaluation_details.cpp"],
+    hdrs = ["flag_evaluation_details.h"],
+    include_prefix = "openfeature",
+    deps = [
+        ":error_code",
+        ":flag_metadata",
+        ":reason",
+        ":resolution_details",
+        ":value"
+    ],
+)
+
 cc_library(
     name = "flag_metadata",
     hdrs = ["flag_metadata.h"],
@@ -124,6 +154,21 @@ cc_library(
     include_prefix = "openfeature",
 )
 
+cc_library(
+    name = "hook",
+    srcs = ["hook.cpp"],
+    hdrs = ["hook.h"],
+    include_prefix = "openfeature",
+    deps = [
+        ":base_hook",
+        ":evaluation_context",
+        ":flag_evaluation_details",
+        ":hook_context",
+        ":hook_hints",
+        ":value",
+    ],
+)
+
 cc_library(
     name = "metadata",
     hdrs = ["metadata.h"],
@@ -136,6 +181,7 @@ cc_library(
     hdrs = ["openfeature_api.h"],
     include_prefix = "openfeature",
     deps = [
+        ":base_hook",
         ":client",
         ":client_api",
         ":evaluation_context",
@@ -153,6 +199,7 @@ cc_library(
     hdrs = ["noop_provider.h"],
     include_prefix = "openfeature",
     deps = [
+        ":base_hook",
         ":evaluation_context",
         ":metadata",
         ":provider",
@@ -167,6 +214,7 @@ cc_library(
     hdrs = ["openfeature.h"],
     include_prefix = "openfeature",
     deps = [
+        ":base_hook",
         ":client",
         ":evaluation_context",
         ":metadata",
@@ -201,6 +249,7 @@ cc_library(
     deps = [
         "@abseil-cpp//absl/status",
         "@abseil-cpp//absl/status:statusor",
+        ":base_hook",
         ":evaluation_context",
         ":metadata",
         ":resolution_details",

openfeature/base_hook.h

@@ -0,0 +1,21 @@
+#ifndef CPP_SDK_INCLUDE_OPENFEATURE_BASE_HOOK_H_
+#define CPP_SDK_INCLUDE_OPENFEATURE_BASE_HOOK_H_
+
+namespace openfeature {
+
+// Non-templated base class for all hooks. This will allow storing different
+// hook types (e.g., BoolHook,
+// StringHook) inside evaluation options.
+class BaseHook {
+ public:
+  BaseHook() = default;
+  BaseHook(const BaseHook&) = delete;
+  BaseHook(BaseHook&&) = delete;
+  BaseHook& operator=(const BaseHook&) = delete;
+  BaseHook& operator=(BaseHook&&) = delete;
+  virtual ~BaseHook() = default;
+};
+
+}  // namespace openfeature
+
+#endif  // CPP_SDK_INCLUDE_OPENFEATURE_BASE_HOOK_H_

openfeature/evaluation_options.h

@@ -0,0 +1,14 @@
+#ifndef CPP_SDK_INCLUDE_OPENFEATURE_EVALUATION_OPTIONS_H_
+#define CPP_SDK_INCLUDE_OPENFEATURE_EVALUATION_OPTIONS_H_
+#include <memory>
+#include <vector>
+
+#include "openfeature/base_hook.h"
+#include "openfeature/hook_hints.h"
+namespace openfeature {
+struct EvaluationOptions {
+  std::vector<std::shared_ptr<BaseHook>> hooks;
+  HookHints hook_hints;
+};
+}  // namespace openfeature
+#endif  // CPP_SDK_INCLUDE_OPENFEATURE_EVALUATION_OPTIONS_H_

openfeature/flag_evaluation_details.cpp

@@ -0,0 +1,42 @@
+#include "openfeature/flag_evaluation_details.h"
+
+#include <optional>
+#include <string>
+#include <string_view>
+
+#include "openfeature/error_code.h"
+#include "openfeature/flag_metadata.h"
+#include "openfeature/reason.h"
+#include "openfeature/resolution_details.h"
+#include "openfeature/value.h"
+
+namespace openfeature {
+
+template <typename T>
+FlagEvaluationDetails<T>::FlagEvaluationDetails(
+    std::string flag_key, T value, Reason reason,
+    std::optional<std::string> variant, const FlagMetadata& flag_metadata,
+    std::optional<ErrorCode> error_code,
+    std::optional<std::string> error_message)
+    : ResolutionDetails<T>(std::move(value), reason, std::move(variant),
+                           flag_metadata, error_code, std::move(error_message)),
+      flag_key_(std::move(flag_key)) {}
+
+template <typename T>
+FlagEvaluationDetails<T>::FlagEvaluationDetails(
+    std::string flag_key, const ResolutionDetails<T>& resolution_details)
+    : ResolutionDetails<T>(resolution_details),
+      flag_key_(std::move(flag_key)) {}
+
+template <typename T>
+std::string_view FlagEvaluationDetails<T>::GetFlagKey() const {
+  return flag_key_;
+}
+
+template class FlagEvaluationDetails<bool>;
+template class FlagEvaluationDetails<std::string>;
+template class FlagEvaluationDetails<int64_t>;
+template class FlagEvaluationDetails<double>;
+template class FlagEvaluationDetails<Value>;
+
+}  // namespace openfeature

openfeature/flag_evaluation_details.h

@@ -0,0 +1,48 @@
+#ifndef CPP_SDK_INCLUDE_OPENFEATURE_FLAG_EVALUATION_DETAILS_H_
+#define CPP_SDK_INCLUDE_OPENFEATURE_FLAG_EVALUATION_DETAILS_H_
+
+#include <optional>
+#include <string>
+#include <string_view>
+
+#include "openfeature/error_code.h"
+#include "openfeature/flag_metadata.h"
+#include "openfeature/reason.h"
+#include "openfeature/resolution_details.h"
+#include "openfeature/value.h"
+
+namespace openfeature {
+
+template <typename T>
+class FlagEvaluationDetails : public ResolutionDetails<T> {
+ public:
+  FlagEvaluationDetails(
+      std::string flag_key, T value, Reason reason,
+      std::optional<std::string> variant, const FlagMetadata& flag_metadata,
+      std::optional<ErrorCode> error_code = std::nullopt,
+      std::optional<std::string> error_message = std::nullopt);
+
+  FlagEvaluationDetails(std::string flag_key,
+                        const ResolutionDetails<T>& resolution_details);
+
+  FlagEvaluationDetails(const FlagEvaluationDetails&) = default;
+  FlagEvaluationDetails& operator=(const FlagEvaluationDetails&) = default;
+  FlagEvaluationDetails(FlagEvaluationDetails&&) noexcept = default;
+  FlagEvaluationDetails& operator=(FlagEvaluationDetails&&) noexcept = default;
+  ~FlagEvaluationDetails() = default;
+  std::string_view GetFlagKey() const;
+
+ private:
+  std::string flag_key_;
+};
+
+// Type aliases for common types.
+using BoolFlagEvaluationDetails = FlagEvaluationDetails<bool>;
+using StringFlagEvaluationDetails = FlagEvaluationDetails<std::string>;
+using IntFlagEvaluationDetails = FlagEvaluationDetails<int64_t>;
+using DoubleFlagEvaluationDetails = FlagEvaluationDetails<double>;
+using ObjectFlagEvaluationDetails = FlagEvaluationDetails<Value>;
+
+}  // namespace openfeature
+
+#endif  // CPP_SDK_INCLUDE_OPENFEATURE_FLAG_EVALUATION_DETAILS_H_

openfeature/hook.cpp

@@ -0,0 +1,12 @@
+#include "openfeature/hook.h"
+
+namespace openfeature {
+
+// Explicit template instantiations for common hook types.
+template class Hook<bool>;
+template class Hook<std::string>;
+template class Hook<int64_t>;
+template class Hook<double>;
+template class Hook<Value>;
+
+}  // namespace openfeature

openfeature/hook.h

@@ -0,0 +1,66 @@
+#ifndef CPP_SDK_INCLUDE_OPENFEATURE_HOOK_H_
+#define CPP_SDK_INCLUDE_OPENFEATURE_HOOK_H_
+
+#include <cstdint>
+#include <exception>
+#include <optional>
+#include <string>
+
+#include "openfeature/base_hook.h"
+#include "openfeature/evaluation_context.h"
+#include "openfeature/flag_evaluation_details.h"
+#include "openfeature/hook_context.h"
+#include "openfeature/hook_hints.h"
+#include "openfeature/value.h"
+
+namespace openfeature {
+
+// Hook allows application developers to add arbitrary behavior to the
+// flag evaluation lifecycle. Hooks operate similarly to middleware in web
+// frameworks. They are executed stack-wise with respect to flag resolution,
+// prioritizing increasing specificity (API, Client, Invocation, Provider)
+// first, and the order in which they were added second.
+/// https://openfeature.dev/specification/sections/hooks
+template <typename T>
+class Hook : public BaseHook {
+ public:
+  Hook() = default;
+  Hook(const Hook&) = delete;
+  Hook& operator=(const Hook&) = delete;
+  Hook(Hook&&) = delete;
+  Hook& operator=(Hook&&) = delete;
+  ~Hook() override = default;
+
+  // Runs before the flag evaluation occurs.
+  virtual std::optional<EvaluationContext> Before(HookContext<T>& ctx,
+                                                  const HookHints& hints) {
+    return std::nullopt;
+  }
+
+  // Runs immediately after successful flag evaluation occurs.
+  virtual void After(const HookContext<T>& ctx,
+                     const FlagEvaluationDetails<T>& details,
+                     const HookHints& hints) {}
+
+  // Runs if an error occurs during flag evaluation or in `Before`/`After`
+  // stages.
+  virtual void Error(const HookContext<T>& ctx, const std::exception& error,
+                     const HookHints& hints) {}
+
+  // Runs after the flag evaluation occurs, regardless of whether it was
+  // successful or not.
+  virtual void Finally(const HookContext<T>& ctx,
+                       const FlagEvaluationDetails<T>& details,
+                       const HookHints& hints) {}
+};
+
+// Type aliases for common hook specializations.
+using BoolHook = Hook<bool>;
+using StringHook = Hook<std::string>;
+using IntHook = Hook<int64_t>;
+using DoubleHook = Hook<double>;
+using ObjectHook = Hook<Value>;
+
+}  // namespace openfeature
+
+#endif  // CPP_SDK_INCLUDE_OPENFEATURE_HOOK_H_

openfeature/memory_provider/BUILD

@@ -21,6 +21,7 @@ cc_library(
     hdrs = ["in_memory_provider.h"],
     include_prefix = "openfeature",
     deps = [
+        "//openfeature:base_hook",
         "//openfeature:error_code",
         "//openfeature:evaluation_context",
         ":flag",

openfeature/memory_provider/in_memory_provider.cpp

@@ -5,6 +5,7 @@
 #include <utility>
 
 #include "absl/status/statusor.h"
+#include "openfeature/base_hook.h"
 #include "openfeature/error_code.h"
 #include "openfeature/memory_provider/flag.h"
 #include "openfeature/reason.h"
@@ -21,6 +22,10 @@ Metadata InMemoryProvider::GetMetadata() const {
   return Metadata{std::string(kName)};
 }
 
+std::vector<std::shared_ptr<BaseHook>> InMemoryProvider::GetHooks() const {
+  return {};
+}
+
 absl::Status InMemoryProvider::Init(const EvaluationContext& ctx) {
   {
     std::unique_lock lock(mutex_);

openfeature/memory_provider/in_memory_provider.h

@@ -10,6 +10,7 @@
 
 #include "absl/status/status.h"
 #include "absl/status/statusor.h"
+#include "openfeature/base_hook.h"
 #include "openfeature/evaluation_context.h"
 #include "openfeature/metadata.h"
 #include "openfeature/provider.h"
@@ -44,6 +45,8 @@ class InMemoryProvider : public FeatureProvider {
   // will be added to the configuration.
   void UpdateFlag(std::string key, std::any new_flag);
 
+  std::vector<std::shared_ptr<BaseHook>> GetHooks() const override;
+
   absl::StatusOr<std::unique_ptr<BoolResolutionDetails>> GetBooleanEvaluation(
       std::string_view key, bool default_value,
       const EvaluationContext& ctx) override;

openfeature/noop_provider.cpp

@@ -4,6 +4,10 @@ namespace openfeature {
 
 Metadata NoopProvider::GetMetadata() const { return Metadata{name_}; }
 
+std::vector<std::shared_ptr<BaseHook>> NoopProvider::GetHooks() const {
+  return {};
+}
+
 absl::StatusOr<std::unique_ptr<BoolResolutionDetails>>
 NoopProvider::GetBooleanEvaluation(std::string_view flag, bool default_value,
                                    const EvaluationContext& ctx) {

openfeature/noop_provider.h

@@ -6,6 +6,7 @@
 #include <string_view>
 
 #include "absl/status/statusor.h"
+#include "openfeature/base_hook.h"
 #include "openfeature/evaluation_context.h"
 #include "openfeature/metadata.h"
 #include "openfeature/provider.h"
@@ -23,6 +24,9 @@ class NoopProvider : public FeatureProvider {
   // Metadata returns the metadata of the provider.
   Metadata GetMetadata() const override;
 
+  // GetHooks returns an empty vector of hooks.
+  std::vector<std::shared_ptr<BaseHook>> GetHooks() const override;
+
   // BooleanEvaluation returns a boolean flag.
   absl::StatusOr<std::unique_ptr<BoolResolutionDetails>> GetBooleanEvaluation(
       std::string_view flag, bool default_value,