feat: added evaluation hooks for variable calls (#119)

Author: jsalaber

docs/Client.md

@@ -30,7 +30,7 @@ DevCycle.configure do |config|
 end
 
 api_instance = DevCycle::Client.new
-user = DevCycle::User.new({ user_id: 'user_id_example' }) # DevCycle::User | 
+user = DevCycle::User.new({ user_id: 'user_id_example' }) # DevCycle::User |
 
 begin
   # Get all features by key for user data
@@ -61,9 +61,9 @@ end
 
 ### Parameters
 
-| Name | Type                                  | Description | Notes |
-| ---- |---------------------------------------| ----------- | ----- |
-| **user** | [**DevCycle::User**](DevCycleUser.md) |  |  |
+| Name     | Type                                  | Description | Notes |
+| -------- | ------------------------------------- | ----------- | ----- |
+| **user** | [**DevCycle::User**](DevCycleUser.md) |             |       |
 
 ### Return type
 

lib/devcycle-ruby-server-sdk.rb

@@ -25,6 +25,11 @@
 require 'devcycle-ruby-server-sdk/models/user_data_and_events_body'
 require 'devcycle-ruby-server-sdk/models/variable'
 
+# Eval Hooks
+require 'devcycle-ruby-server-sdk/eval_hooks_runner'
+require 'devcycle-ruby-server-sdk/models/eval_hook'
+require 'devcycle-ruby-server-sdk/models/eval_hook_context'
+
 # APIs
 require 'devcycle-ruby-server-sdk/api/client'
 require 'devcycle-ruby-server-sdk/api/dev_cycle_provider'

lib/devcycle-ruby-server-sdk/api/client.rb

@@ -14,6 +14,7 @@ def initialize(sdkKey, dvc_options = Options.new, wait_for_init = false)
       @sdkKey = sdkKey
       @dvc_options = dvc_options
       @logger = dvc_options.logger
+      @eval_hooks_runner = EvalHooksRunner.new
 
       if @dvc_options.enable_cloud_bucketing
         @api_client = ApiClient.default
@@ -172,35 +173,68 @@ def variable(user, key, default, opts = {})
 
       validate_model(user)
 
-      if @dvc_options.enable_cloud_bucketing
-        data, _status_code, _headers = variable_with_http_info(key, user, default, opts)
-        return data
+      # Create hook context
+      hook_context = HookContext.new(key: key, user: user, default_value: default)
+
+      before_hook_error = nil
+      # Run before hooks
+      begin
+        hook_context = @eval_hooks_runner.run_before_hooks(hook_context)
+      rescue BeforeHookError => e
+        before_hook_error = e
+        @logger.warn("Error in before hooks: #{e.message}")
       end
 
-      value = default
-      type = determine_variable_type(default)
-      defaulted = true
-      if local_bucketing_initialized? && @local_bucketing.has_config
-        type_code = variable_type_code_from_type(type)
-        variable_pb = variable_for_user_pb(user, key, type_code)
-        unless variable_pb.nil?
-          value = get_variable_value(variable_pb)
-          defaulted = false
+      variable_result = nil
+
+      begin
+        if @dvc_options.enable_cloud_bucketing
+          data, _status_code, _headers = variable_with_http_info(key, user, default, opts)
+          variable_result = data
+        else
+          value = default
+          type = determine_variable_type(default)
+          defaulted = true
+          if local_bucketing_initialized? && @local_bucketing.has_config
+            type_code = variable_type_code_from_type(type)
+            variable_pb = variable_for_user_pb(user, key, type_code)
+            unless variable_pb.nil?
+              value = get_variable_value(variable_pb)
+              defaulted = false
+            end
+          else
+            @logger.warn("Local bucketing not initialized, returning default value for variable #{key}")
+            variable_event = Event.new({ type: DevCycle::EventTypes[:agg_variable_defaulted], target: key })
+            bucketed_config = BucketedUserConfig.new({}, {}, {}, {}, {}, {}, [])
+            @event_queue.queue_aggregate_event(variable_event, bucketed_config)
+          end
+
+          variable_result = Variable.new({
+            key: key,
+            value: value,
+            type: type,
+            defaultValue: default,
+            isDefaulted: defaulted
+          })
         end
-      else
-        @logger.warn("Local bucketing not initialized, returning default value for variable #{key}")
-        variable_event = Event.new({ type: DevCycle::EventTypes[:agg_variable_defaulted], target: key })
-        bucketed_config = BucketedUserConfig.new({}, {}, {}, {}, {}, {}, [])
-        @event_queue.queue_aggregate_event(variable_event, bucketed_config)
-      end
-
-      Variable.new({
-        key: key,
-        value: value,
-        type: type,
-        defaultValue: default,
-        isDefaulted: defaulted
-      })
+
+
+        # Run after hooks only if no before hook error occurred
+        if before_hook_error != nil
+          @logger.info("before_hook_error is not nil, skipping after hooks")
+          raise before_hook_error
+        else
+          @eval_hooks_runner.run_after_hooks(hook_context)
+        end
+      rescue => e
+        # Run error hooks
+        @eval_hooks_runner.run_error_hooks(hook_context, e)
+      ensure
+        # Run finally hooks in all cases
+        @eval_hooks_runner.run_finally_hooks(hook_context)
+      end
+
+      variable_result
     end
 
     def variable_for_user(user, key, variable_type_code)
@@ -526,6 +560,32 @@ def variable_type_pb_code_from_type_code(type_code)
         raise ArgumentError.new("Invalid type code for variable: #{type_code}")
       end
     end
+
+    def get_variable_value(variable_pb)
+      case variable_pb.type
+      when :Boolean
+        variable_pb.boolValue
+      when :Number
+        variable_pb.doubleValue
+      when :String
+        variable_pb.stringValue
+      when :JSON
+        JSON.parse variable_pb.stringValue
+      end
+    end
+
+    # Adds an eval hook to the client
+    # @param [EvalHook] eval_hook The eval hook to add
+    # @return [void]
+    def add_eval_hook(eval_hook)
+      @eval_hooks_runner.add_hook(eval_hook)
+    end
+
+    # Clears all eval hooks from the client
+    # @return [void]
+    def clear_eval_hooks
+      @eval_hooks_runner.clear_hooks
+    end
   end
 
   # @deprecated Use `DevCycle::Client` instead.

lib/devcycle-ruby-server-sdk/eval_hooks_runner.rb

@@ -0,0 +1,135 @@
+require 'devcycle-ruby-server-sdk/models/eval_hook'
+require 'devcycle-ruby-server-sdk/models/eval_hook_context'
+
+module DevCycle
+  # Custom error raised when a before hook fails
+  class BeforeHookError < StandardError
+    attr_reader :original_error, :hook_context
+
+    def initialize(message = nil, original_error = nil, hook_context = nil)
+      super(message || "Before hook execution failed")
+      @original_error = original_error
+      @hook_context = hook_context
+    end
+
+    def to_s
+      msg = super
+      msg += "\nOriginal error: #{@original_error.message}" if @original_error
+      msg
+    end
+  end
+
+  # Custom error raised when an after hook fails
+  class AfterHookError < StandardError
+    attr_reader :original_error, :hook_context
+
+    def initialize(message = nil, original_error = nil, hook_context = nil)
+      super(message || "After hook execution failed")
+      @original_error = original_error
+      @hook_context = hook_context
+    end
+
+    def to_s
+      msg = super
+      msg += "\nOriginal error: #{@original_error.message}" if @original_error
+      msg
+    end
+  end
+
+  class EvalHooksRunner
+    # @return [Array<EvalHook>] Array of eval hooks to run
+    attr_reader :eval_hooks
+
+    # Initializes the EvalHooksRunner with an optional array of eval hooks
+    # @param [Array<EvalHook>, nil] eval_hooks Array of eval hooks to run
+    def initialize(eval_hooks = [])
+      @eval_hooks = eval_hooks || []
+    end
+
+    # Runs all before hooks with the given context
+    # @param [HookContext] context The context to pass to the hooks
+    # @return [HookContext] The potentially modified context
+    # @raise [BeforeHookError] when a before hook fails
+    def run_before_hooks(context)
+      current_context = context
+      
+      @eval_hooks.each do |hook|
+        next unless hook.before
+
+        begin
+          result = hook.before.call(current_context)
+          # If the hook returns a new context, use it for subsequent hooks
+          current_context = result if result.is_a?(DevCycle::HookContext)
+        rescue => e
+          # Raise BeforeHookError to allow client to handle and skip after hooks
+          raise BeforeHookError.new(e.message, e, current_context)
+        end
+      end
+      
+      current_context
+    end
+
+    # Runs all after hooks with the given context
+    # @param [HookContext] context The context to pass to the hooks
+    # @return [void]
+    # @raise [AfterHookError] when an after hook fails
+    def run_after_hooks(context)
+      @eval_hooks.each do |hook|
+        next unless hook.after
+
+        begin
+          hook.after.call(context)
+        rescue => e
+          # Log error but continue with next hook
+          raise AfterHookError.new(e.message, e, context)
+        end
+      end
+    end
+
+    # Runs all finally hooks with the given context
+    # @param [HookContext] context The context to pass to the hooks
+    # @return [void]
+    def run_finally_hooks(context)
+      @eval_hooks.each do |hook|
+        next unless hook.on_finally
+
+        begin
+          hook.on_finally.call(context)
+        rescue => e
+          # Log error but don't re-raise to prevent blocking evaluation
+          warn "Error in finally hook: #{e.message}"
+        end
+      end
+    end
+
+    # Runs all error hooks with the given context and error
+    # @param [HookContext] context The context to pass to the hooks
+    # @param [Exception] error The error that occurred
+    # @return [void]
+    def run_error_hooks(context, error)
+      @eval_hooks.each do |hook|
+        next unless hook.error
+
+        begin
+          hook.error.call(context, error)
+        rescue => e
+          # Log error but don't re-raise to prevent blocking evaluation
+          warn "Error in error hook: #{e.message}"
+        end
+      end
+    end
+
+    # Adds an eval hook to the runner
+    # @param [EvalHook] eval_hook The eval hook to add
+    # @return [void]
+    def add_hook(eval_hook)
+      @eval_hooks << eval_hook
+    end
+
+    # Clears all eval hooks from the runner
+    # @return [void]
+    def clear_hooks
+      @eval_hooks.clear
+    end
+  end
+end

lib/devcycle-ruby-server-sdk/models/eval_hook.rb

@@ -0,0 +1,28 @@
+module DevCycle
+  class EvalHook
+    # Callback to be executed before evaluation
+    attr_accessor :before
+
+    # Callback to be executed after evaluation
+    attr_accessor :after
+
+    # Callback to be executed finally (always runs)
+    attr_accessor :on_finally
+
+    # Callback to be executed on error
+    attr_accessor :error
+
+    # Initializes the object with optional callback functions
+    # @param [Hash] callbacks Callback functions in the form of hash
+    # @option callbacks [Proc, nil] :before Callback to execute before evaluation
+    # @option callbacks [Proc, nil] :after Callback to execute after evaluation
+    # @option callbacks [Proc, nil] :on_finally Callback to execute finally (always runs)
+    # @option callbacks [Proc, nil] :error Callback to execute on error
+    def initialize(callbacks = {})
+      @before = callbacks[:before]
+      @after = callbacks[:after]
+      @on_finally = callbacks[:on_finally]
+      @error = callbacks[:error]
+    end
+  end
+end

lib/devcycle-ruby-server-sdk/models/eval_hook_context.rb

@@ -0,0 +1,22 @@
+module DevCycle
+  class HookContext
+    # The key of the variable being evaluated
+    attr_accessor :key
+
+    # The user for whom the variable is being evaluated
+    attr_accessor :user
+
+    # The default value for the variable
+    attr_accessor :default_value
+
+    # Initializes the object
+    # @param [String] key The key of the variable being evaluated
+    # @param [DevCycle::User] user The user for whom the variable is being evaluated
+    # @param [Object] default_value The default value for the variable
+    def initialize(key:, user:, default_value:)
+      @key = key
+      @user = user
+      @default_value = default_value
+    end
+  end
+end