geneva_drive 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 70c9ef44e4b9666d6eb8e4ad93e7e06a7bcc2b00c96ad2271572ab0fc0b11714
-  data.tar.gz: d6e2439f6d272d74eb9e155876416a22d28a097a992f7153954cd6be2eac9b02
+  metadata.gz: 277866fbccabdb2fc26e37af632234df751620057a2b42d94607d8ad5fa180e7
+  data.tar.gz: 054417cf89b79e8534e6e3268bb8577df7f5d21da6b0ccc37b8dce1862596377
 SHA512:
-  metadata.gz: f4fc719769aa9cd69604d9ac55d24bbdb06c390bb4009728b1f809247ed284e5aa23e155ab1cdcbf80b3b2e975c30e5d486c67953674550f3a0b58e063283796
-  data.tar.gz: bd0c110f3f0158e1fe8e48faaf957b81c4084b4dfa479be8704ec37f5717e5db54bc754de5738904fc06ef9b7a9bc297883505355274950e9671bc208e1d1373
+  metadata.gz: '013668a74a368b8ed7b75b75d0536c5ffd3d7f4ed8a6f110ff740f186ede6dbe79eb6f3e480295c895b280dd64f804ca4e701427c05543aa03e5b3637ee1c702'
+  data.tar.gz: 7bc7f954847dd03f4b2501ae84bc4395a7c51d22681a289e58f0d49e3ae0d5dc00f66bd14f437abfb99de114b7d72aac22afafb7bc7aeebcc60e56e9b83c7d7b

data/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## [Unreleased]
 
+## [0.4.0]
+
+- Preserve original scheduled time when resuming a paused workflow. When a workflow with a future-scheduled step is paused and then resumed before that time, the step is rescheduled for the original time (not run immediately). If the original time has passed, the step runs immediately.
+- Add `max_reattempts:` option for steps with `on_exception: :reattempt!` to limit consecutive reattempts before pausing the workflow (default: 100, set to `nil` to disable)
+- Handle unexpected exceptions during prepare_execution (e.g., NameError from invalid hero_type) by marking step as failed and transitioning workflow based on on_exception policy
+
 ## [0.3.0]
 
 - Fix `resume!` to retry the failed step instead of skipping it

data/MANUAL.md

@@ -676,6 +676,42 @@ Available exception handlers:
 - `:reattempt!` — Retry the step
 - `:skip!` — Skip the step and continue to the next
 
+### Limiting Reattempts
+
+When using `on_exception: :reattempt!`, you can limit the number of consecutive reattempts before the workflow pauses. This prevents infinite retry loops when an error is persistent rather than transient.
+
+```ruby
+class ExternalApiWorkflow < GenevaDrive::Workflow
+  # Will pause after 5 consecutive failures
+  step :sync_to_crm, on_exception: :reattempt!, max_reattempts: 5 do
+    CrmApi.sync(hero)
+  end
+end
+```
+
+The `max_reattempts:` option:
+
+- **Defaults to 100** when `on_exception: :reattempt!` is used — a safety net against infinite loops
+- **Set to `nil`** to disable the limit and allow unlimited reattempts
+- **Only counts consecutive reattempts** — if the step succeeds, the count resets
+- **Does not affect manual `reattempt!` calls** — only automatic exception handling respects this limit
+
+When the limit is exceeded, GenevaDrive logs a warning and pauses the workflow, storing the original exception for debugging:
+
+```ruby
+# Unlimited reattempts (explicit opt-out of the safety limit)
+step :polling_step, on_exception: :reattempt!, max_reattempts: nil do
+  check_external_status!
+end
+
+# Custom limit
+step :flaky_api, on_exception: :reattempt!, max_reattempts: 10 do
+  FlakyService.call(hero)
+end
+```
+
+This option only makes sense with `on_exception: :reattempt!` — specifying `max_reattempts:` with other exception handlers will raise a `StepConfigurationError`.
+
 ### Manual Exception Handling
 
 For granular control, handle exceptions within the step:
@@ -1280,5 +1316,6 @@ end
 | `wait:` | Duration | Delay before step executes |
 | `skip_if:` | Proc, Symbol, Boolean | Condition to skip step |
 | `on_exception:` | Symbol | Exception handler (`:pause!`, `:cancel!`, `:reattempt!`, `:skip!`) |
+| `max_reattempts:` | Integer, nil | Max consecutive reattempts before pausing (default: 100, `nil` = unlimited) |
 | `before_step:` | Symbol | Insert before this step |
 | `after_step:` | Symbol | Insert after this step |

data/lib/geneva_drive/executor.rb

@@ -202,6 +202,9 @@ class GenevaDrive::Executor
       workflow.update!(current_step_name: step_def.name)
 
       step_def
+    rescue => e
+      exception_to_raise = handle_prepare_exception(e)
+      nil
     end
 
     raise exception_to_raise if exception_to_raise
@@ -415,6 +418,7 @@ class GenevaDrive::Executor
     {
       type: :exception,
       error: error,
+      step_def: step_def,
       on_exception: step_def.on_exception
     }
   end
@@ -435,10 +439,17 @@ class GenevaDrive::Executor
 
     case on_exception
     when :reattempt!
-      logger.info("Precondition exception policy: reattempt! - rescheduling step")
-      transition_step!("completed", outcome: "reattempted")
-      transition_workflow!("ready")
-      workflow.reschedule_current_step!
+      if reattempt_limit_exceeded?(step_def)
+        logger.warn("Max reattempts (#{step_def.max_reattempts}) exceeded - pausing workflow instead")
+        step_execution.update!(error_attributes_for(error))
+        transition_step!("failed", outcome: "failed")
+        transition_workflow!("paused")
+      else
+        logger.info("Precondition exception policy: reattempt! - rescheduling step")
+        transition_step!("completed", outcome: "reattempted")
+        transition_workflow!("ready")
+        workflow.reschedule_current_step!
+      end
 
     when :cancel!
       logger.info("Precondition exception policy: cancel! - canceling workflow")
@@ -470,6 +481,65 @@ class GenevaDrive::Executor
     error
   end
 
+  # Handles unexpected exceptions that occur during prepare_execution before
+  # the step actually runs (e.g., NameError when hero_type references a
+  # non-existent class). Uses the step's on_exception policy if available,
+  # otherwise defaults to :pause!.
+  # Returns the original exception to be re-raised after the transaction commits.
+  #
+  # @param error [Exception] the exception that occurred
+  # @return [Exception] the original exception to be re-raised
+  def handle_prepare_exception(error)
+    logger.error("Unexpected exception during prepare_execution: #{error.class} - #{error.message}")
+    Rails.error.report(error)
+
+    # Try to get step_def for on_exception policy, but it may not be available yet
+    step_def = begin
+      step_execution.step_definition
+    rescue
+      nil
+    end
+    on_exception = step_def&.on_exception || :pause!
+
+    logger.info("Prepare exception handling with on_exception: #{on_exception.inspect}")
+
+    step_execution.update!(error_attributes_for(error))
+    transition_step!("failed", outcome: "failed")
+
+    case on_exception
+    when :reattempt!
+      if step_def && reattempt_limit_exceeded?(step_def)
+        logger.warn("Max reattempts (#{step_def.max_reattempts}) exceeded - pausing workflow instead")
+        transition_workflow!("paused")
+      else
+        logger.info("Prepare exception policy: reattempt! - rescheduling step")
+        transition_workflow!("ready")
+        workflow.reschedule_current_step!
+      end
+
+    when :cancel!
+      logger.info("Prepare exception policy: cancel! - canceling workflow")
+      transition_workflow!("canceled")
+
+    when :skip!
+      logger.info("Prepare exception policy: skip! - skipping to next step")
+      transition_workflow!("ready")
+      workflow.schedule_next_step!
+
+    when :pause!
+      logger.info("Prepare exception policy: pause! - pausing workflow")
+      transition_workflow!("paused")
+
+    else
+      # Default: pause
+      logger.info("Prepare exception policy: default (pause!) - pausing workflow")
+      transition_workflow!("paused")
+    end
+
+    # Return original exception to be re-raised after transaction commits
+    error
+  end
+
   # Handles successful step completion.
   #
   # @return [void]
@@ -487,16 +557,24 @@ class GenevaDrive::Executor
   # @return [Exception] the original exception to be re-raised
   def handle_captured_exception(context)
     error = context[:error]
+    step_def = context[:step_def]
     on_exception = context[:on_exception]
 
     logger.info("Handling exception with on_exception: #{on_exception.inspect}")
 
     case on_exception
     when :reattempt!
-      logger.info("Exception policy: reattempt! - rescheduling step")
-      transition_step!("completed", outcome: "reattempted")
-      transition_workflow!("ready")
-      workflow.reschedule_current_step!
+      if reattempt_limit_exceeded?(step_def)
+        logger.warn("Max reattempts (#{step_def.max_reattempts}) exceeded - pausing workflow instead")
+        step_execution.update!(error_attributes_for(error))
+        transition_step!("failed", outcome: "failed")
+        transition_workflow!("paused")
+      else
+        logger.info("Exception policy: reattempt! - rescheduling step")
+        transition_step!("completed", outcome: "reattempted")
+        transition_workflow!("ready")
+        workflow.reschedule_current_step!
+      end
 
     when :cancel!
       logger.info("Exception policy: cancel! - canceling workflow")
@@ -542,6 +620,39 @@ class GenevaDrive::Executor
     attrs
   end
 
+  # Counts consecutive reattempts for the current step since the last successful execution.
+  # This is used to enforce the max_reattempts limit.
+  #
+  # @param step_name [String] the step name to count reattempts for
+  # @return [Integer] the number of consecutive reattempts
+  def consecutive_reattempt_count(step_name)
+    # Find the most recent non-reattempt completion for this step
+    # (success, skipped, canceled, failed - anything that isn't a reattempt)
+    last_non_reattempt_id = workflow.step_executions
+      .where(step_name: step_name, state: "completed")
+      .where.not(outcome: "reattempted")
+      .order(created_at: :desc)
+      .pick(:id)
+
+    # Count reattempts after that point (or all reattempts if no prior success)
+    scope = workflow.step_executions.where(step_name: step_name, outcome: "reattempted")
+    scope = scope.where("id > ?", last_non_reattempt_id) if last_non_reattempt_id
+    scope.count
+  end
+
+  # Checks if the max reattempts limit has been exceeded for the current step.
+  # Returns true if we should fall back to :pause! instead of reattempting.
+  #
+  # @param step_def [StepDefinition] the step definition
+  # @return [Boolean] true if limit exceeded, false otherwise
+  def reattempt_limit_exceeded?(step_def)
+    max_reattempts = step_def.max_reattempts
+    return false if max_reattempts.nil? # Limit disabled
+
+    count = consecutive_reattempt_count(step_def.name)
+    count >= max_reattempts
+  end
+
   # Handles a flow control signal.
   #
   # @param signal [FlowControlSignal]

data/lib/geneva_drive/step_definition.rb

@@ -33,6 +33,9 @@ class GenevaDrive::StepDefinition
   # @return [String, nil] name of step this should be placed after
   attr_reader :after_step
 
+  # @return [Integer, nil] maximum consecutive reattempts before pausing (nil = unlimited)
+  attr_reader :max_reattempts
+
   # @return [Array<String, Integer>, nil] source location where step was called [path, lineno]
   attr_reader :call_location
 
@@ -65,6 +68,7 @@ class GenevaDrive::StepDefinition
     @on_exception = options[:on_exception] || :pause!
     @before_step = options[:before_step]&.to_s
     @after_step = options[:after_step]&.to_s
+    @max_reattempts = options.key?(:max_reattempts) ? options[:max_reattempts] : default_max_reattempts
 
     validate!
   end
@@ -101,6 +105,14 @@ class GenevaDrive::StepDefinition
     validate_exception_handler!
     validate_positioning!
     validate_skip_condition!
+    validate_max_reattempts!
+  end
+
+  # Returns the default max_reattempts value based on on_exception setting.
+  #
+  # @return [Integer, nil] 100 if on_exception is :reattempt!, nil otherwise
+  def default_max_reattempts
+    (@on_exception == :reattempt!) ? 100 : nil
   end
 
   # Validates that the callable is present and valid.
@@ -162,6 +174,26 @@ class GenevaDrive::StepDefinition
       "but was #{@skip_condition.class}"
   end
 
+  # Validates the max_reattempts option.
+  #
+  # @raise [StepConfigurationError] if max_reattempts is invalid
+  def validate_max_reattempts!
+    # nil is always valid (disables the check)
+    return if @max_reattempts.nil?
+
+    # max_reattempts only makes sense with on_exception: :reattempt!
+    unless @on_exception == :reattempt!
+      raise GenevaDrive::StepConfigurationError,
+        "Step '#{@name}' has max_reattempts: but on_exception: is not :reattempt!"
+    end
+
+    # Must be a positive integer
+    unless @max_reattempts.is_a?(Integer) && @max_reattempts > 0
+      raise GenevaDrive::StepConfigurationError,
+        "Step '#{@name}' has invalid max_reattempts: must be a positive integer or nil"
+    end
+  end
+
   # Evaluates a condition in the workflow context.
   #
   # @param condition [Proc, Symbol, Boolean, nil] the condition to evaluate

data/lib/geneva_drive/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module GenevaDrive
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
 end

data/lib/geneva_drive/workflow.rb

@@ -265,11 +265,43 @@ class GenevaDrive::Workflow < ActiveRecord::Base
     create_step_execution(step_def, wait: wait)
   end
 
-  # Resumes a paused workflow.
-  # Creates a new step execution for the next step.
+  # Resumes a paused workflow by creating a new step execution for the next step.
+  #
+  # ## Scheduling behavior
+  #
+  # The scheduling depends on why the workflow was paused:
+  #
+  # - **Paused due to step failure** (`on_exception: :pause!`): The failed step is retried
+  #   immediately. This allows quick retry after fixing the underlying issue.
+  #
+  # - **Paused externally** (via `pause!`): If the paused step had a future scheduled time
+  #   that hasn't passed yet, the step is rescheduled for that original time (preserving
+  #   remaining wait). If the time has passed, the step runs immediately.
+  #
+  # @example Resuming after step failure (runs immediately)
+  #   # step_two fails with on_exception: :pause!
+  #   workflow.state          # => "paused"
+  #   workflow.resume!        # step_two retries immediately
+  #
+  # @example Resuming externally paused workflow (preserves wait time)
+  #   # step_two has wait: 2.days, scheduled for tomorrow
+  #   workflow.pause!         # paused today
+  #   workflow.resume!        # step_two still scheduled for tomorrow
+  #
+  # @example Resuming after scheduled time passed (runs immediately)
+  #   # step_two was scheduled for yesterday
+  #   workflow.pause!         # paused last week
+  #   workflow.resume!        # step_two runs immediately (time already passed)
   #
   # @return [StepExecution] the created step execution
   # @raise [InvalidStateError] if workflow is not paused
+  #
+  # ## Implementation details
+  #
+  # When pause! is called externally, it cancels the pending step execution with
+  # outcome "workflow_paused", preserving the original scheduled_for timestamp.
+  # On resume, we look for this canceled execution to calculate remaining wait time.
+  # See calculate_remaining_wait_for_resume for the full algorithm.
   def resume!
     raise GenevaDrive::InvalidStateError, "Cannot resume a #{state} workflow" unless state == "paused"
 
@@ -279,7 +311,9 @@ class GenevaDrive::Workflow < ActiveRecord::Base
     end
 
     step_def = steps.named(next_step_name)
-    create_step_execution(step_def)
+    wait = calculate_remaining_wait_for_resume(next_step_name)
+
+    create_step_execution(step_def, wait: wait)
   end
 
   # Returns the current active step execution, if any.
@@ -407,6 +441,32 @@ class GenevaDrive::Workflow < ActiveRecord::Base
     create_step_execution(first_step, wait: first_step.wait)
   end
 
+  # Calculates the remaining wait time when resuming a paused workflow.
+  #
+  # When a workflow was paused externally (via pause!) while a step was scheduled for
+  # a future time, this method finds that original scheduled time and calculates how
+  # much wait time remains.
+  #
+  # @param step_name [String] the name of the step being resumed
+  # @return [ActiveSupport::Duration, nil] remaining wait time, or nil to run immediately
+  def calculate_remaining_wait_for_resume(step_name)
+    # Find the most recent canceled execution for this step that was paused externally.
+    # The "workflow_paused" outcome indicates external pause (vs "failed" for step failures).
+    paused_execution = step_executions
+      .where(step_name: step_name, outcome: "workflow_paused")
+      .order(created_at: :desc)
+      .first
+
+    return nil unless paused_execution&.scheduled_for
+
+    # Calculate remaining time until the original scheduled execution time
+    remaining_seconds = paused_execution.scheduled_for - Time.current
+
+    # If the original time has passed, run immediately (return nil)
+    # Otherwise, return the remaining time as a duration
+    (remaining_seconds > 0) ? remaining_seconds.seconds : nil
+  end
+
   # Creates a step execution and enqueues the job after transaction commits.
   # Any existing scheduled step executions are canceled first.
   # In-progress step executions are left alone - they're being executed.

data/test/dsl/step_definition_test.rb

@@ -332,4 +332,100 @@ class StepDefinitionTest < ActiveSupport::TestCase
     assert_equal :should_skip?, step_def.skip_condition
     assert_equal :reattempt!, step_def.on_exception
   end
+
+  # Tests for max_reattempts validation
+  test "defaults max_reattempts to 100 when on_exception is reattempt!" do
+    workflow_class = Class.new(GenevaDrive::Workflow) do
+      step :reattempting, on_exception: :reattempt! do
+      end
+    end
+
+    step_def = workflow_class.step_definitions.first
+    assert_equal 100, step_def.max_reattempts
+  end
+
+  test "defaults max_reattempts to nil when on_exception is not reattempt!" do
+    workflow_class = Class.new(GenevaDrive::Workflow) do
+      step :pausing, on_exception: :pause! do
+      end
+
+      step :canceling, on_exception: :cancel! do
+      end
+
+      step :skipping, on_exception: :skip! do
+      end
+    end
+
+    workflow_class.step_definitions.each do |step_def|
+      assert_nil step_def.max_reattempts, "#{step_def.name} should have nil max_reattempts"
+    end
+  end
+
+  test "accepts custom max_reattempts value with on_exception reattempt!" do
+    workflow_class = Class.new(GenevaDrive::Workflow) do
+      step :custom_limit, on_exception: :reattempt!, max_reattempts: 5 do
+      end
+    end
+
+    step_def = workflow_class.step_definitions.first
+    assert_equal 5, step_def.max_reattempts
+  end
+
+  test "accepts nil max_reattempts to disable limit with on_exception reattempt!" do
+    workflow_class = Class.new(GenevaDrive::Workflow) do
+      step :unlimited, on_exception: :reattempt!, max_reattempts: nil do
+      end
+    end
+
+    step_def = workflow_class.step_definitions.first
+    assert_nil step_def.max_reattempts
+  end
+
+  test "rejects max_reattempts when on_exception is not reattempt!" do
+    error = assert_raises(GenevaDrive::StepConfigurationError) do
+      Class.new(GenevaDrive::Workflow) do
+        step :invalid, on_exception: :pause!, max_reattempts: 10 do
+        end
+      end
+    end
+
+    assert_match(/max_reattempts:/, error.message)
+    assert_match(/on_exception: is not :reattempt!/, error.message)
+  end
+
+  test "rejects non-positive max_reattempts values" do
+    error = assert_raises(GenevaDrive::StepConfigurationError) do
+      Class.new(GenevaDrive::Workflow) do
+        step :zero_limit, on_exception: :reattempt!, max_reattempts: 0 do
+        end
+      end
+    end
+
+    assert_match(/max_reattempts:/, error.message)
+    assert_match(/positive integer/, error.message)
+  end
+
+  test "rejects negative max_reattempts values" do
+    error = assert_raises(GenevaDrive::StepConfigurationError) do
+      Class.new(GenevaDrive::Workflow) do
+        step :negative_limit, on_exception: :reattempt!, max_reattempts: -5 do
+        end
+      end
+    end
+
+    assert_match(/max_reattempts:/, error.message)
+    assert_match(/positive integer/, error.message)
+  end
+
+  test "rejects non-integer max_reattempts values" do
+    error = assert_raises(GenevaDrive::StepConfigurationError) do
+      Class.new(GenevaDrive::Workflow) do
+        step :float_limit, on_exception: :reattempt!, max_reattempts: 5.5 do
+        end
+      end
+    end
+
+    assert_match(/max_reattempts:/, error.message)
+    assert_match(/positive integer/, error.message)
+  end
 end