geneva_drive 0.4.0 → 0.6.0

data/lib/geneva_drive/step_definition.rb

@@ -2,13 +2,16 @@
 
 # Metadata about a step definition in a workflow.
 # Holds the step name, callable (block or method name), wait time,
-# skip conditions, and exception handling configuration.
+# job options, skip conditions, and exception handling configuration.
 #
 # @api private
 class GenevaDrive::StepDefinition
   # Valid exception handler values
   EXCEPTION_HANDLERS = %i[pause! cancel! reattempt! skip!].freeze
 
+  # Sentinel value to distinguish "on_exception not provided" from "on_exception: :pause!"
+  NOT_SET = Object.new.freeze
+
   # Valid types for skip conditions
   VALID_SKIP_CONDITION_TYPES = [Symbol, Proc, TrueClass, FalseClass, NilClass].freeze
 
@@ -21,11 +24,14 @@ class GenevaDrive::StepDefinition
   # @return [ActiveSupport::Duration, nil] wait time before executing this step
   attr_reader :wait
 
+  # @return [Hash] frozen, symbol-keyed Active Job options for this step
+  attr_reader :job_options
+
   # @return [Proc, Symbol, Boolean, nil] condition for skipping this step
   attr_reader :skip_condition
 
-  # @return [Symbol] exception handler (:pause!, :cancel!, :reattempt!, :skip!)
-  attr_reader :on_exception
+  # @return [GenevaDrive::ExceptionPolicy, GenevaDrive::CombinedExceptionPolicy] exception handling policy
+  attr_reader :exception_policy
 
   # @return [String, nil] name of step this should be placed before
   attr_reader :before_step
@@ -33,9 +39,6 @@ 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
 
@@ -48,9 +51,13 @@ class GenevaDrive::StepDefinition
   # @param callable [Proc, Symbol, nil] the code to execute (block or method name)
   # @param options [Hash] additional options
   # @option options [ActiveSupport::Duration, nil] :wait delay before execution
+  # @option options [Hash] :job_options options passed to Active Job's set method
   # @option options [Proc, Symbol, Boolean, nil] :skip_if condition for skipping
   # @option options [Proc, Symbol, Boolean, nil] :if condition for running (inverse of skip_if)
-  # @option options [Symbol] :on_exception how to handle exceptions
+  # @option options [Symbol, GenevaDrive::ExceptionPolicy, Proc, Array<GenevaDrive::ExceptionPolicy>] :on_exception
+  #   how to handle exceptions. An Array of {ExceptionPolicy} objects is wrapped in a
+  #   {CombinedExceptionPolicy} that resolves specific policies first, then blanket fallback.
+  # @option options [Integer, nil] :max_reattempts max consecutive reattempts (symbol form only)
   # @option options [String, Symbol, nil] :before_step position before this step
   # @option options [String, Symbol, nil] :after_step position after this step
   # @param call_location [Array<String, Integer>, nil] source location where step was called
@@ -62,15 +69,38 @@ class GenevaDrive::StepDefinition
     @call_location = call_location
     @block_location = block_location
     @wait = options[:wait]
+    @job_options = options.fetch(:job_options, {})
     @skip_if_option = options[:skip_if]
     @if_option = options[:if]
     @skip_condition = @skip_if_option || @if_option
-    @on_exception = options[:on_exception] || :pause!
+    @on_exception_raw = options.fetch(:on_exception, NOT_SET)
+    @max_reattempts_raw = options[:max_reattempts]
+    @max_reattempts_explicitly_set = options.key?(:max_reattempts)
+    @terminal_action_raw = options[:terminal_action]
     @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!
+    @job_options = GenevaDrive::JobOptions.validate!(@job_options, context: "Step '#{@name}'").freeze
+    @exception_policy = build_exception_policy
+  end
+
+  # Returns the action symbol from the exception policy.
+  # Provided for backward compatibility with code that reads step_def.on_exception.
+  #
+  # @return [Symbol, nil] the action symbol, or nil for imperative/combined policies
+  def on_exception
+    return nil unless @exception_policy
+    return nil if @exception_policy.is_a?(GenevaDrive::CombinedExceptionPolicy)
+    @exception_policy.action
+  end
+
+  # Returns the max_reattempts from the exception policy.
+  # Provided for backward compatibility with code that reads step_def.max_reattempts.
+  #
+  # @return [Integer, nil]
+  def max_reattempts
+    @exception_policy&.max_reattempts
   end
 
   # Evaluates whether this step should be skipped for the given workflow.
@@ -82,6 +112,13 @@ class GenevaDrive::StepDefinition
     evaluate_condition(@skip_condition, workflow)
   end
 
+  # Returns whether this is a resumable step.
+  #
+  # @return [Boolean] false for standard steps
+  def resumable?
+    false
+  end
+
   # Executes the step callable in the context of the workflow.
   #
   # @param workflow [GenevaDrive::Workflow] the workflow instance
@@ -102,17 +139,48 @@ class GenevaDrive::StepDefinition
   def validate!
     validate_callable!
     validate_wait!
-    validate_exception_handler!
+    validate_on_exception_raw!
+    validate_max_reattempts_raw!
+    validate_terminal_action_raw!
     validate_positioning!
     validate_skip_condition!
-    validate_max_reattempts!
   end
 
-  # Returns the default max_reattempts value based on on_exception setting.
+  # Builds the ExceptionPolicy from validated raw inputs.
+  # This is the single place where symbols, procs, arrays, and policies are normalized.
+  #
+  # @return [GenevaDrive::ExceptionPolicy, GenevaDrive::CombinedExceptionPolicy]
+  def build_exception_policy
+    return nil if @on_exception_raw == NOT_SET
+
+    case @on_exception_raw
+    when Array
+      GenevaDrive::CombinedExceptionPolicy.new(@on_exception_raw)
+    when GenevaDrive::ExceptionPolicy
+      @on_exception_raw
+    when Proc
+      GenevaDrive::ExceptionPolicy.new(&@on_exception_raw)
+    when Symbol
+      max = (@max_reattempts_raw.nil? && !explicitly_set_max_reattempts?) ? default_max_reattempts(@on_exception_raw) : @max_reattempts_raw
+      opts = {max_reattempts: max}
+      opts[:terminal_action] = @terminal_action_raw if @terminal_action_raw
+      GenevaDrive::ExceptionPolicy.new(@on_exception_raw, **opts)
+    end
+  end
+
+  # Whether max_reattempts: was explicitly passed in options.
   #
-  # @return [Integer, nil] 100 if on_exception is :reattempt!, nil otherwise
-  def default_max_reattempts
-    (@on_exception == :reattempt!) ? 100 : nil
+  # @return [Boolean]
+  def explicitly_set_max_reattempts?
+    @max_reattempts_explicitly_set
+  end
+
+  # Returns the default max_reattempts value based on action.
+  #
+  # @param action [Symbol]
+  # @return [Integer, nil] 100 if action is :reattempt!, nil otherwise
+  def default_max_reattempts(action)
+    (action == :reattempt!) ? 100 : nil
   end
 
   # Validates that the callable is present and valid.
@@ -137,14 +205,86 @@ class GenevaDrive::StepDefinition
       "Step '#{@name}' has invalid wait value: must be non-negative"
   end
 
-  # Validates the exception handler.
+  # Validates the raw on_exception value before unfolding.
   #
   # @raise [StepConfigurationError] if on_exception is invalid
-  def validate_exception_handler!
-    return if EXCEPTION_HANDLERS.include?(@on_exception)
+  def validate_on_exception_raw!
+    return if @on_exception_raw == NOT_SET
 
-    raise GenevaDrive::StepConfigurationError,
-      "Step '#{@name}' has invalid on_exception: must be one of #{EXCEPTION_HANDLERS.join(", ")}"
+    case @on_exception_raw
+    when Symbol
+      return if EXCEPTION_HANDLERS.include?(@on_exception_raw)
+      raise GenevaDrive::StepConfigurationError,
+        "Step '#{@name}' has invalid on_exception: must be one of #{EXCEPTION_HANDLERS.join(", ")}"
+    when GenevaDrive::ExceptionPolicy, Proc
+      nil
+    when Array
+      @on_exception_raw.each do |element|
+        unless element.is_a?(GenevaDrive::ExceptionPolicy)
+          raise GenevaDrive::StepConfigurationError,
+            "Step '#{@name}' has invalid on_exception array element: " \
+            "every element must be a GenevaDrive::ExceptionPolicy, got #{element.class}"
+        end
+      end
+    else
+      raise GenevaDrive::StepConfigurationError,
+        "Step '#{@name}' has invalid on_exception: must be a Symbol, ExceptionPolicy, Proc, or Array of ExceptionPolicy"
+    end
+  end
+
+  # Validates the raw max_reattempts value before unfolding.
+  #
+  # @raise [StepConfigurationError] if max_reattempts is invalid
+  def validate_max_reattempts_raw!
+    return if @max_reattempts_raw.nil?
+
+    on_exc = (@on_exception_raw == NOT_SET) ? :pause! : @on_exception_raw
+
+    # Can't pass max_reattempts when on_exception is already a policy, proc, or array
+    if on_exc.is_a?(GenevaDrive::ExceptionPolicy) || on_exc.is_a?(Proc) || on_exc.is_a?(Array)
+      raise GenevaDrive::StepConfigurationError,
+        "Step '#{@name}' has max_reattempts: but on_exception: is an ExceptionPolicy, Proc, or Array " \
+        "(set max_reattempts on the policy instead)"
+    end
+
+    # max_reattempts only makes sense with on_exception: :reattempt!
+    unless on_exc == :reattempt!
+      raise GenevaDrive::StepConfigurationError,
+        "Step '#{@name}' has max_reattempts: but on_exception: is not :reattempt!"
+    end
+
+    # Must be a positive integer
+    unless @max_reattempts_raw.is_a?(Integer) && @max_reattempts_raw > 0
+      raise GenevaDrive::StepConfigurationError,
+        "Step '#{@name}' has invalid max_reattempts: must be a positive integer or nil"
+    end
+  end
+
+  # Validates the terminal_action option.
+  #
+  # @raise [StepConfigurationError] if terminal_action is invalid
+  def validate_terminal_action_raw!
+    return if @terminal_action_raw.nil?
+
+    on_exc = (@on_exception_raw == NOT_SET) ? :pause! : @on_exception_raw
+
+    # Can't pass terminal_action when on_exception is already a policy, proc, or array
+    if on_exc.is_a?(GenevaDrive::ExceptionPolicy) || on_exc.is_a?(Proc) || on_exc.is_a?(Array)
+      raise GenevaDrive::StepConfigurationError,
+        "Step '#{@name}' has terminal_action: but on_exception: is an ExceptionPolicy, Proc, or Array " \
+        "(set terminal_action on the policy instead)"
+    end
+
+    # terminal_action only makes sense with on_exception: :reattempt!
+    unless on_exc == :reattempt!
+      raise GenevaDrive::StepConfigurationError,
+        "Step '#{@name}' has terminal_action: but on_exception: is not :reattempt!"
+    end
+
+    unless GenevaDrive::ExceptionPolicy::VALID_TERMINAL_ACTIONS.include?(@terminal_action_raw)
+      raise GenevaDrive::StepConfigurationError,
+        "Step '#{@name}' has invalid terminal_action: must be one of #{GenevaDrive::ExceptionPolicy::VALID_TERMINAL_ACTIONS.join(", ")}"
+    end
   end
 
   # Validates the step positioning options.
@@ -174,26 +314,6 @@ 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/step_execution/metadata_accessor.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+# Provides safe read/write access to the freeform JSON metadata column
+# on step executions. All "does the column exist?" logic lives here so
+# the rest of the codebase can call read_metadata / write_metadata without
+# guarding. When the metadata column has not been migrated yet, writes
+# are silent no-ops and reads return nil.
+#
+# Once the migration becomes mandatory, delete this concern and replace with
+# a plain `attribute :metadata, :json, default: -> { {} }` on StepExecution.
+#
+# @api private
+module GenevaDrive::StepExecution::MetadataAccessor
+  extend ActiveSupport::Concern
+
+  class_methods do
+    # Lazily checks whether the metadata column exists. Never hits the
+    # database at class definition time — only on the first runtime call.
+    #
+    # Serialization is handled manually in read/write_metadata rather
+    # than via `attribute :metadata, :json` to avoid timing issues —
+    # registering the JSON type after instances are already loaded
+    # causes those instances to persist Hashes via text-type `#to_s`
+    # instead of `#to_json`.
+    #
+    # @return [Boolean]
+    def metadata_column?
+      if defined?(@_metadata_column)
+        return @_metadata_column
+      end
+
+      @_metadata_column = table_exists? && column_names.include?("metadata")
+    end
+
+    # Counts reattempted step executions in the given scope, excluding
+    # flow-control reattempts when the metadata column is available.
+    # Without the column, counts all reattempts (coarser but safe —
+    # errs on the side of pausing sooner).
+    #
+    # @param scope [ActiveRecord::Relation] a relation of step executions
+    #   already filtered to outcome: "reattempted"
+    # @return [Integer]
+    def count_error_reattempts(scope)
+      unless metadata_column?
+        return scope.count
+      end
+
+      scope.pluck(:metadata).count do |raw|
+        meta = raw.is_a?(String) ? JSON.parse(raw) : raw
+        reason = meta.is_a?(Hash) ? meta["reattempt_reason"] : nil
+        reason != "flow_control"
+      end
+    end
+
+    # Clears the cached detection result. Call this in tests or after
+    # running migrations in-process so the next access re-checks.
+    #
+    # @return [void]
+    def reset_metadata_column_cache!
+      remove_instance_variable(:@_metadata_column) if defined?(@_metadata_column)
+    end
+  end
+
+  # Reads a single key from the metadata hash.
+  #
+  # @param key [String, Symbol] the metadata key
+  # @return [Object, nil] the value, or nil if the column is absent
+  def read_metadata(key)
+    return nil unless self.class.metadata_column?
+    parsed_metadata[key.to_s]
+  end
+
+  # Merges a key/value pair into the metadata hash (in-memory only, does
+  # not persist — call save!/update! separately or include in a broader
+  # update).
+  #
+  # @param key [String, Symbol] the metadata key
+  # @param value [Object] the value to store
+  # @return [void]
+  def write_metadata(key, value)
+    return unless self.class.metadata_column?
+    merged = parsed_metadata.merge(key.to_s => value)
+    write_attribute(:metadata, merged.to_json)
+  end
+
+  # Returns the reattempt reason from metadata.
+  # Possible values: "flow_control", "exception_policy", "precondition", or nil.
+  #
+  # @return [String, nil]
+  def reattempt_reason
+    read_metadata("reattempt_reason")
+  end
+
+  # Returns the exception info hash from metadata, if recorded.
+  # Keys: "class", "message", "backtrace" (backtrace is an Array of strings).
+  #
+  # @return [Hash, nil]
+  def exception_info
+    read_metadata("exception")
+  end
+
+  private
+
+  # Returns metadata as a Hash regardless of whether the JSON attribute
+  # type has been applied to this instance. On SQLite/MySQL the raw value
+  # may still be a JSON string if the record was loaded before the
+  # attribute type was lazily registered.
+  #
+  # @return [Hash]
+  def parsed_metadata
+    raw = metadata
+    case raw
+    when Hash then raw
+    when String then JSON.parse(raw)
+    when NilClass then {}
+    else {}
+    end
+  rescue JSON::ParserError
+    {}
+  end
+end

data/lib/geneva_drive/step_execution.rb

@@ -18,6 +18,9 @@
 class GenevaDrive::StepExecution < ActiveRecord::Base
   self.table_name = "geneva_drive_step_executions"
 
+  require_relative "step_execution/metadata_accessor"
+  include MetadataAccessor
+
   # Step execution states as enum with string values
   # Provides: scheduled?, in_progress?, etc. predicates
   # Provides: scheduled, in_progress, etc. scopes
@@ -33,6 +36,7 @@ class GenevaDrive::StepExecution < ActiveRecord::Base
   # Outcome values for audit purposes
   OUTCOMES = %w[
     success
+    continued
     reattempted
     skipped
     canceled
@@ -47,6 +51,18 @@ class GenevaDrive::StepExecution < ActiveRecord::Base
     foreign_key: :workflow_id,
     inverse_of: :step_executions
 
+  # For chained resumable step executions
+  belongs_to :continues_from,
+    class_name: "GenevaDrive::StepExecution",
+    foreign_key: :continues_from_id,
+    optional: true,
+    inverse_of: :successor
+
+  has_one :successor,
+    class_name: "GenevaDrive::StepExecution",
+    foreign_key: :continues_from_id,
+    inverse_of: :continues_from
+
   # Validations
   validates :step_name, presence: true
   validates :scheduled_for, presence: true
@@ -57,6 +73,63 @@ class GenevaDrive::StepExecution < ActiveRecord::Base
     scheduled.where("scheduled_for <= ?", Time.current)
   }
 
+  class << self
+    # Lazily checks whether the resumable-step columns (cursor and
+    # continues_from_id) have been migrated. Never hits the database at
+    # class definition time — only on the first runtime call.
+    #
+    # Deployments usually ship the gem update before running migrations,
+    # so all cursor/chaining behavior must degrade safely when the columns
+    # are absent: reads return nil, writes are no-ops, and executing an
+    # actual resumable_step raises a clear configuration error instead.
+    #
+    # @return [Boolean]
+    def resumable_columns?
+      if defined?(@_resumable_columns)
+        return @_resumable_columns
+      end
+
+      @_resumable_columns = table_exists? &&
+        column_names.include?("cursor") &&
+        column_names.include?("continues_from_id")
+    end
+
+    # Clears the cached detection result. Call this in tests or after
+    # running migrations in-process so the next access re-checks.
+    #
+    # @return [void]
+    def reset_resumable_columns_cache!
+      remove_instance_variable(:@_resumable_columns) if defined?(@_resumable_columns)
+    end
+
+    # Serializes a cursor value using ActiveJob serializers (handles Date,
+    # Time, and other types) and enforces GenevaDrive.max_cursor_size on
+    # the serialized JSON. The single serialization path for cursor writes.
+    #
+    # @param value [Object, nil] the cursor value
+    # @return [Object, nil] the serialized cursor
+    # @raise [CursorTooLargeError] if the serialized JSON exceeds the limit
+    def serialize_cursor(value)
+      return nil if value.nil?
+
+      serialized = ActiveJob::Arguments.serialize([value]).first
+
+      limit = GenevaDrive.max_cursor_size
+      if limit
+        bytesize = JSON.generate(serialized).bytesize
+        if bytesize > limit
+          raise GenevaDrive::CursorTooLargeError,
+            "Serialized cursor is #{bytesize} bytes, exceeding GenevaDrive.max_cursor_size " \
+            "(#{limit} bytes). The cursor is a position marker (an id, page number, or token), " \
+            "not a place to store the data being processed. Set GenevaDrive.max_cursor_size to " \
+            "nil to disable this check."
+        end
+      end
+
+      serialized
+    end
+  end
+
   # Transitions the step execution to 'in_progress' state.
   # Uses pessimistic locking to prevent double execution.
   #
@@ -133,6 +206,37 @@ class GenevaDrive::StepExecution < ActiveRecord::Base
     end
   end
 
+  # Returns the deserialized cursor value for resumable steps.
+  # Uses ActiveJob serializers to handle Date, Time, and other types.
+  # Returns nil when the cursor column has not been migrated yet.
+  #
+  # @return [Object, nil] the cursor value
+  def cursor_value
+    return nil unless self.class.resumable_columns?
+    return nil if cursor.blank?
+    ActiveJob::Arguments.deserialize([cursor]).first
+  end
+
+  # Sets the cursor value for resumable steps.
+  # Uses ActiveJob serializers to handle Date, Time, and other types.
+  # Silent no-op when the cursor column has not been migrated yet.
+  #
+  # @param value [Object] the cursor value to store
+  # @raise [CursorTooLargeError] if the serialized JSON exceeds GenevaDrive.max_cursor_size
+  # @return [void]
+  def cursor_value=(value)
+    return unless self.class.resumable_columns?
+    self.cursor = self.class.serialize_cursor(value)
+  end
+
+  # Returns true if this execution is resuming from a prior execution.
+  # Always false when the continues_from_id column has not been migrated yet.
+  #
+  # @return [Boolean]
+  def resuming?
+    self.class.resumable_columns? && continues_from_id.present?
+  end
+
   # Returns the step definition for this execution.
   #
   # @return [StepDefinition, nil] the step definition
@@ -142,9 +246,11 @@ class GenevaDrive::StepExecution < ActiveRecord::Base
 
   # Executes this step using the Executor.
   #
+  # @param interruptible [Boolean] whether resumable steps respect interruption conditions
+  # @param max_iterations [Integer, nil] per-execution override of the step's max_iterations
   # @return [void]
-  def execute!
-    GenevaDrive::Executor.execute!(self)
+  def execute!(interruptible: true, max_iterations: nil)
+    GenevaDrive::Executor.execute!(self, interruptible: interruptible, max_iterations: max_iterations)
   end
 
   # Same as ActiveRecord::Base#logger but supplemented with tags for step and workflow
@@ -156,4 +262,20 @@ class GenevaDrive::StepExecution < ActiveRecord::Base
       workflow_tagged_logger.tagged("execution_id=#{id} step_name=#{step_name}")
     end
   end
+
+  # Temporarily overrides the step execution's logger for the duration of the block.
+  # The passed logger is used directly - it should already include step-specific tags.
+  # The original logger is restored after the block completes.
+  #
+  # @param logger [Logger] the logger to use (already fully tagged)
+  # @yield the block to execute with the injected logger
+  # @return [Object] the result of the block
+  # @api private
+  def with_logger(logger)
+    previous_logger = @logger
+    @logger = logger
+    yield
+  ensure
+    @logger = previous_logger
+  end
 end