feat: add hook data support

Signed-off-by: Alexandra Oberaigner <[email protected]>

Author: alexandraoberaigner

src/main/java/dev/openfeature/sdk/HookContext.java

@@ -1,16 +1,16 @@
 package dev.openfeature.sdk;
 
 import lombok.Builder;
+import lombok.Data;
 import lombok.NonNull;
-import lombok.Value;
 import lombok.With;
 
 /**
  * A data class to hold immutable context that {@link Hook} instances use.
  *
  * @param <T> the type for the flag being evaluated
  */
-@Value
+@Data
 @Builder
 @With
 public class HookContext<T> {
@@ -26,7 +26,7 @@ public class HookContext<T> {
     Metadata providerMetadata;
 
     /**
-     * Builds a {@link HookContext} instances from request data.
+     * Builds {@link HookContext} instances from request data.
      *
      * @param key              feature flag key
      * @param type             flag value type
@@ -53,4 +53,8 @@ public static <T> HookContext<T> from(
                 .defaultValue(defaultValue)
                 .build();
     }
+
+    HookData getHookData() {
+        return null;
+    }
 }

src/main/java/dev/openfeature/sdk/HookContextDecorator.java

@@ -0,0 +1,23 @@
+package dev.openfeature.sdk;
+
+/**
+ * A base decorator class for {@link HookContext} that enables dynamic enhancement of its functionality.
+ * This class wraps an existing {@code HookContext<T>} instance and delegates method calls to it.
+ *
+ * @param <T> the type for the flag being evaluated
+ */
+class HookContextDecorator<T> extends HookContext<T> {
+
+    HookContext<T> decorated;
+
+    protected HookContextDecorator(HookContext<T> context) {
+        super(context.getFlagKey(), context.getType(), context.getDefaultValue(), context.getCtx(),
+                context.getClientMetadata(), context.getProviderMetadata());
+        this.decorated = context;
+    }
+
+    @Override
+    public HookData getHookData() {
+        return decorated.getHookData();
+    }
+}

src/main/java/dev/openfeature/sdk/HookContextWithData.java

@@ -0,0 +1,21 @@
+package dev.openfeature.sdk;
+
+/**
+ * A concrete decorator for {@link HookContext} that adds {@link HookData} to the existing functionality.
+ *
+ * @param <T> the type for the flag being evaluated
+ */
+public class HookContextWithData<T> extends HookContextDecorator<T> {
+
+    private final HookData hookData;
+
+    public HookContextWithData(HookContext<T> context, HookData data) {
+        super(context);
+        this.hookData = data;
+    }
+
+    @Override
+    public HookData getHookData() {
+        return hookData;
+    }
+}

src/main/java/dev/openfeature/sdk/HookData.java

@@ -0,0 +1,81 @@
+package dev.openfeature.sdk;
+
+import java.util.HashMap;
+import java.util.Map;
+
+/**
+ * Hook data provides a way for hooks to maintain state across their execution stages.
+ * Each hook instance gets its own isolated data store that persists only for the duration
+ * of a single flag evaluation.
+ */
+public interface HookData {
+
+    /**
+     * Sets a value for the given key.
+     *
+     * @param key the key to store the value under
+     * @param value the value to store
+     */
+    void set(String key, Object value);
+
+    /**
+     * Gets the value for the given key.
+     *
+     * @param key the key to retrieve the value for
+     * @return the value, or null if not found
+     */
+    Object get(String key);
+
+    /**
+     * Gets the value for the given key, cast to the specified type.
+     *
+     * @param <T> the type to cast to
+     * @param key the key to retrieve the value for
+     * @param type the class to cast to
+     * @return the value cast to the specified type, or null if not found
+     * @throws ClassCastException if the value cannot be cast to the specified type
+     */
+    <T> T get(String key, Class<T> type);
+
+    /**
+     * Default implementation uses a HashMap.
+     */
+    static HookData create() {
+        return new DefaultHookData();
+    }
+
+    /**
+     * Default implementation of HookData.
+     */
+    class DefaultHookData implements HookData {
+        private Map<String, Object> data;
+
+        @Override
+        public void set(String key, Object value) {
+            if (data == null) {
+                data = new HashMap<>();
+            }
+            data.put(key, value);
+        }
+
+        @Override
+        public Object get(String key) {
+            if (data == null) {
+                return null;
+            }
+            return data.get(key);
+        }
+
+        @Override
+        public <T> T get(String key, Class<T> type) {
+            Object value = get(key);
+            if (value == null) {
+                return null;
+            }
+            if (!type.isInstance(value)) {
+                throw new ClassCastException("Value for key '" + key + "' is not of type " + type.getName());
+            }
+            return type.cast(value);
+        }
+    }
+}

src/main/java/dev/openfeature/sdk/HookSupport.java

@@ -5,7 +5,7 @@
 import java.util.List;
 import java.util.Map;
 import java.util.Optional;
-import java.util.function.Consumer;
+import java.util.function.BiConsumer;
 import lombok.RequiredArgsConstructor;
 import lombok.extern.slf4j.Slf4j;
 
@@ -15,52 +15,81 @@
 class HookSupport {
 
     public EvaluationContext beforeHooks(
-            FlagValueType flagValueType, HookContext hookCtx, List<Hook> hooks, Map<String, Object> hints) {
-        return callBeforeHooks(flagValueType, hookCtx, hooks, hints);
+            FlagValueType flagValueType,
+            HookContext hookCtx,
+            List<Pair<Hook, HookData>> hookDataPairs,
+            Map<String, Object> hints) {
+        return callBeforeHooks(flagValueType, hookCtx, hookDataPairs, hints);
     }
 
     public void afterHooks(
             FlagValueType flagValueType,
             HookContext hookContext,
             FlagEvaluationDetails details,
-            List<Hook> hooks,
+            List<Pair<Hook, HookData>> hookDataPairs,
             Map<String, Object> hints) {
-        executeHooksUnchecked(flagValueType, hooks, hook -> hook.after(hookContext, details, hints));
+        executeHooksUnchecked(
+                flagValueType, hookDataPairs, hookContext, (hook, ctx) -> hook.after(ctx, details, hints));
     }
 
     public void afterAllHooks(
             FlagValueType flagValueType,
             HookContext hookCtx,
             FlagEvaluationDetails details,
-            List<Hook> hooks,
+            List<Pair<Hook, HookData>> hookDataPairs,
             Map<String, Object> hints) {
-        executeHooks(flagValueType, hooks, "finally", hook -> hook.finallyAfter(hookCtx, details, hints));
+        executeHooks(
+                flagValueType,
+                hookDataPairs,
+                hookCtx,
+                "finally",
+                (hook, ctx) -> hook.finallyAfter(ctx, details, hints));
     }
 
     public void errorHooks(
             FlagValueType flagValueType,
             HookContext hookCtx,
             Exception e,
-            List<Hook> hooks,
+            List<Pair<Hook, HookData>> hookDataPairs,
             Map<String, Object> hints) {
-        executeHooks(flagValueType, hooks, "error", hook -> hook.error(hookCtx, e, hints));
+        executeHooks(flagValueType, hookDataPairs, hookCtx, "error", (hook, ctx) -> hook.error(ctx, e, hints));
+    }
+
+    public List<Pair<Hook, HookData>> getHookDataPairs(List<Hook> hooks, FlagValueType flagValueType) {
+        var pairs = new ArrayList<Pair<Hook, HookData>>();
+        for (Hook hook : hooks) {
+            if (hook.supportsFlagValueType(flagValueType)) {
+                pairs.add(Pair.of(hook, HookData.create()));
+            }
+        }
+        return pairs;
     }
 
     private <T> void executeHooks(
-            FlagValueType flagValueType, List<Hook> hooks, String hookMethod, Consumer<Hook<T>> hookCode) {
-        if (hooks != null) {
-            for (Hook hook : hooks) {
-                if (hook.supportsFlagValueType(flagValueType)) {
-                    executeChecked(hook, hookCode, hookMethod);
-                }
+            FlagValueType flagValueType,
+            List<Pair<Hook, HookData>> hookDataPairs,
+            HookContext hookContext,
+            String hookMethod,
+            BiConsumer<Hook<T>, HookContext> hookCode) {
+        if (hookDataPairs != null) {
+            for (Pair<Hook, HookData> hookDataPair : hookDataPairs) {
+                Hook hook = hookDataPair.getLeft();
+                HookData hookData = hookDataPair.getRight();
+                executeChecked(hook, hookData, hookContext, hookCode, hookMethod);
             }
         }
     }
 
     // before, error, and finally hooks shouldn't throw
-    private <T> void executeChecked(Hook<T> hook, Consumer<Hook<T>> hookCode, String hookMethod) {
+    private <T> void executeChecked(
+            Hook<T> hook,
+            HookData hookData,
+            HookContext hookContext,
+            BiConsumer<Hook<T>, HookContext> hookCode,
+            String hookMethod) {
         try {
-            hookCode.accept(hook);
+            var hookCtxWithData = new HookContextWithData(hookContext, hookData);
+            hookCode.accept(hook, hookCtxWithData);
         } catch (Exception exception) {
             log.error(
                     "Unhandled exception when running {} hook {} (only 'after' hooks should throw)",
@@ -71,29 +100,41 @@ private <T> void executeChecked(Hook<T> hook, Consumer<Hook<T>> hookCode, String
     }
 
     // after hooks can throw in order to do validation
-    private <T> void executeHooksUnchecked(FlagValueType flagValueType, List<Hook> hooks, Consumer<Hook<T>> hookCode) {
-        if (hooks != null) {
-            for (Hook hook : hooks) {
-                if (hook.supportsFlagValueType(flagValueType)) {
-                    hookCode.accept(hook);
-                }
+    private <T> void executeHooksUnchecked(
+            FlagValueType flagValueType,
+            List<Pair<Hook, HookData>> hookDataPairs,
+            HookContext hookContext,
+            BiConsumer<Hook<T>, HookContext> hookCode) {
+        if (hookDataPairs != null) {
+            for (Pair<Hook, HookData> hookDataPair : hookDataPairs) {
+                Hook hook = hookDataPair.getLeft();
+                HookData hookData = hookDataPair.getRight();
+                var hookCtxWithData = new HookContextWithData(hookContext, hookData);
+                hookCode.accept(hook, hookCtxWithData);
             }
         }
     }
 
     private EvaluationContext callBeforeHooks(
-            FlagValueType flagValueType, HookContext hookCtx, List<Hook> hooks, Map<String, Object> hints) {
+            FlagValueType flagValueType,
+            HookContext hookCtx,
+            List<Pair<Hook, HookData>> hookDataPairs,
+            Map<String, Object> hints) {
         // These traverse backwards from normal.
-        List<Hook> reversedHooks = new ArrayList<>(hooks);
+        List<Pair<Hook, HookData>> reversedHooks = new ArrayList<>(hookDataPairs);
         Collections.reverse(reversedHooks);
         EvaluationContext context = hookCtx.getCtx();
-        for (Hook hook : reversedHooks) {
-            if (hook.supportsFlagValueType(flagValueType)) {
-                Optional<EvaluationContext> optional =
-                        Optional.ofNullable(hook.before(hookCtx, hints)).orElse(Optional.empty());
-                if (optional.isPresent()) {
-                    context = context.merge(optional.get());
-                }
+
+        for (Pair<Hook, HookData> hookDataPair : reversedHooks) {
+            Hook hook = hookDataPair.getLeft();
+            HookData hookData = hookDataPair.getRight();
+
+            // Create a new context with this hook's data
+            HookContext contextWithHookData = new HookContextWithData(hookCtx, hookData);
+            Optional<EvaluationContext> optional =
+                    Optional.ofNullable(hook.before(contextWithHookData, hints)).orElse(Optional.empty());
+            if (optional.isPresent()) {
+                context = context.merge(optional.get());
             }
         }
         return context;

src/main/java/dev/openfeature/sdk/ImmutableContext.java

@@ -20,6 +20,8 @@
 @SuppressWarnings("PMD.BeanMembersShouldSerialize")
 public final class ImmutableContext implements EvaluationContext {
 
+    public static final ImmutableContext EMPTY = new ImmutableContext();
+
     @Delegate(excludes = DelegateExclusions.class)
     private final ImmutableStructure structure;