feat: added evaluation hooks

Author: jsalaber

src/main/java/com/devcycle/sdk/server/cloud/api/DevCycleCloudClient.java

@@ -20,13 +20,15 @@
 import java.util.Collections;
 import java.util.HashMap;
 import java.util.Map;
+import java.util.Optional;
 
 public final class DevCycleCloudClient implements IDevCycleClient {
 
     private static final ObjectMapper OBJECT_MAPPER = new ObjectMapper();
     private final IDevCycleApi api;
     private final DevCycleCloudOptions dvcOptions;
     private final DevCycleProvider openFeatureProvider;
+    private final EvalHooksRunner evalHooksRunner;
 
     public DevCycleCloudClient(String sdkKey) {
         this(sdkKey, DevCycleCloudOptions.builder().build());
@@ -50,6 +52,7 @@ public DevCycleCloudClient(String sdkKey, DevCycleCloudOptions options) {
         OBJECT_MAPPER.setSerializationInclusion(JsonInclude.Include.NON_NULL);
 
         this.openFeatureProvider = new DevCycleProvider(this);
+        this.evalHooksRunner = new EvalHooksRunner();
     }
 
     /**
@@ -110,13 +113,17 @@ public <T> Variable<T> variable(DevCycleUser user, String key, T defaultValue) {
 
         TypeEnum variableType = TypeEnum.fromClass(defaultValue.getClass());
         Variable<T> variable;
+        HookContext context = new HookContext(user, key, defaultValue);
 
         try {
+            HookContext newContext = context.merge(evalHooksRunner.executeBefore(context));
             Call<Variable> response = api.getVariableByKey(user, key, dvcOptions.getEnableEdgeDB());
             variable = getResponseWithRetries(response, 5);
             if (variable.getType() != variableType) {
                 throw new IllegalArgumentException("Variable type mismatch, returning default value");
             }
+            evalHooksRunner.executeAfter(newContext, variable);
+            evalHooksRunner.executeFinally(newContext, variable);
             variable.setIsDefaulted(false);
         } catch (Exception exception) {
             variable = (Variable<T>) Variable.builder()
@@ -126,6 +133,8 @@ public <T> Variable<T> variable(DevCycleUser user, String key, T defaultValue) {
                     .defaultValue(defaultValue)
                     .isDefaulted(true)
                     .build();
+            evalHooksRunner.executeError(context, exception);
+            evalHooksRunner.executeFinally(context, variable);
         }
         return variable;
     }

src/main/java/com/devcycle/sdk/server/common/exception/AfterHookError.java

@@ -0,0 +1,14 @@
+package com.devcycle.sdk.server.common.exception;
+
+/**
+ * Exception thrown when an after hook fails during variable evaluation.
+ */
+public class AfterHookError extends RuntimeException {
+    public AfterHookError(String message) {
+        super(message);
+    }
+
+    public AfterHookError(String message, Throwable cause) {
+        super(message, cause);
+    }
+} 

src/main/java/com/devcycle/sdk/server/common/exception/BeforeHookError.java

@@ -0,0 +1,14 @@
+package com.devcycle.sdk.server.common.exception;
+
+/**
+ * Exception thrown when a before hook fails during variable evaluation.
+ */
+public class BeforeHookError extends RuntimeException {
+    public BeforeHookError(String message) {
+        super(message);
+    }
+
+    public BeforeHookError(String message, Throwable cause) {
+        super(message, cause);
+    }
+} 

src/main/java/com/devcycle/sdk/server/common/model/EvalHook.java

@@ -0,0 +1,13 @@
+package com.devcycle.sdk.server.common.model;
+
+import java.util.Optional;
+
+public interface EvalHook<T> {
+
+    default Optional<HookContext<T>> before(HookContext<T> ctx) {
+        return Optional.empty();
+    }
+    default void after(HookContext<T> ctx, Variable<T> variable) {}
+    default void error(HookContext<T> ctx, Throwable e) {}
+    default void onFinally(HookContext<T> ctx, Variable<T> variable) {}
+}

src/main/java/com/devcycle/sdk/server/common/model/EvalHooksRunner.java

@@ -0,0 +1,118 @@
+package com.devcycle.sdk.server.common.model;
+
+import com.devcycle.sdk.server.common.exception.AfterHookError;
+import com.devcycle.sdk.server.common.exception.BeforeHookError;
+
+import javax.swing.text.html.Option;
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.List;
+import java.util.Optional;
+import java.util.concurrent.CompletableFuture;
+
+/**
+ * A class that manages evaluation hooks for the DevCycle SDK.
+ * Provides functionality to add and clear hooks, storing them in an array.
+ */
+public class EvalHooksRunner {
+    private List<EvalHook> hooks;
+
+    /**
+     * Default constructor initializes an empty list of hooks.
+     */
+    public EvalHooksRunner() {
+        this.hooks = new ArrayList<>();
+    }
+
+    /**
+     * Adds a single hook to the collection.
+     * 
+     * @param hook The hook to add
+     */
+    public void addHook(EvalHook hook) {
+        if (hook != null) {
+            hooks.add(hook);
+        }
+    }
+
+    /**
+     * Clears all hooks from the collection.
+     */
+    public void clearHooks() {
+        hooks.clear();
+    }
+
+    /**
+     * Runs all before hooks in order.
+     *
+     * @param context The context to pass to the hooks
+     * @param <T> The type of the variable value
+     * @return The potentially modified context
+     */
+    public <T> HookContext<T> executeBefore(HookContext<T> context) {
+        HookContext<T> beforeContext = context;
+        for (EvalHook<T> hook : hooks) {
+            try {
+                Optional<HookContext<T>> newContext = hook.before(beforeContext);
+                if (newContext.isPresent()) {
+                    beforeContext = beforeContext.merge(newContext.get());
+                }
+            } catch (Exception e) {
+                throw new BeforeHookError("Before hook failed", e);
+            }
+        }
+        return beforeContext;
+    }
+
+    /**
+     * Runs all after hooks in reverse order.
+     *
+     * @param context The context to pass to the hooks
+     * @param variable The variable result to pass to the hooks
+     * @param <T> The type of the variable value
+     */
+    public <T> void executeAfter(HookContext<T> context, Variable<T> variable) {
+        for (EvalHook<T> hook : hooks) {
+            try {
+                hook.after(context, variable);
+            } catch (Exception e) {
+                throw new AfterHookError("After hook failed", e);
+            }
+        }
+    }
+
+    /**
+     * Runs all error hooks in reverse order.
+     *
+     * @param context The context to pass to the hooks
+     * @param error The error that occurred
+     * @param <T> The type of the variable value
+     */
+    public <T> void executeError(HookContext<T> context, Throwable error) {
+        for (EvalHook<T> hook : hooks) {
+            try {
+                hook.error(context, error);
+            } catch (Exception hookError) {
+                // Log hook error but don't throw to avoid masking the original error
+                System.err.println("Error hook failed: " + hookError.getMessage());
+            }
+        }
+    }
+
+    /**
+     * Runs all finally hooks in reverse order.
+     * 
+     * @param context The context to pass to the hooks
+     * @param variable The variable result to pass to the hooks (may be null)
+     */
+    public void executeFinally(HookContext context, Variable variable) {
+        for (EvalHook hook : hooks) {
+            try {
+                hook.onFinally(context, variable);
+            } catch (Exception e) {
+                // Log finally hook error but don't throw
+                System.err.println("Finally hook failed: " + e.getMessage());
+            }
+        }
+    }
+}

src/main/java/com/devcycle/sdk/server/common/model/HookContext.java

@@ -0,0 +1,48 @@
+package com.devcycle.sdk.server.common.model;
+
+import java.util.Map;
+
+/**
+ * Context object passed to hooks during variable evaluation.
+ * Contains the user, variable key, default value, and additional context data.
+ */
+public class HookContext<T> {
+    private DevCycleUser user;
+    private final String key;
+    private final T defaultValue;
+    private Variable<T> variableDetails;
+
+    public HookContext(DevCycleUser user, String key, T defaultValue) {
+        this.user = user;
+        this.key = key;
+        this.defaultValue = defaultValue;
+    }
+
+    public HookContext(DevCycleUser user, String key, T defaultValue, Variable<T> variable) {
+        this.user = user;
+        this.key = key;
+        this.defaultValue = defaultValue;
+        this.variableDetails = variable;
+    }
+
+    public DevCycleUser getUser() {
+        return user;
+    }
+
+    public String getKey() {
+        return key;
+    }
+
+    public T getDefaultValue() {
+        return defaultValue;
+    }
+
+    public Variable<T> getVariableDetails() { return variableDetails; }
+
+    public HookContext<T> merge(HookContext<T> other) {
+        if (other == null) {
+            return this;
+        }
+        return new HookContext<>(other.getUser(), key, defaultValue, variableDetails);
+    }
+}

src/main/java/com/devcycle/sdk/server/common/model/VariableResolver.java

@@ -0,0 +1,19 @@
+package com.devcycle.sdk.server.common.model;
+
+import java.util.concurrent.CompletableFuture;
+
+/**
+ * Functional interface for resolving variables during hook evaluation.
+ * 
+ * @param <T> The type of the variable value
+ */
+@FunctionalInterface
+public interface VariableResolver<T> {
+    /**
+     * Resolves a variable based on the provided context.
+     * 
+     * @param context The hook context containing user, key, and default value
+     * @return A CompletableFuture that completes with the resolved variable
+     */
+    CompletableFuture<Variable<T>> resolve(HookContext<T> context);
+}