geneva_drive 0.5.0 → 0.7.0

data/lib/geneva_drive/step_execution.rb

@@ -26,6 +26,7 @@ class GenevaDrive::StepExecution < ActiveRecord::Base
   # Provides: scheduled, in_progress, etc. scopes
   enum :state, {
     scheduled: "scheduled",
+    waiting: "waiting",
     in_progress: "in_progress",
     completed: "completed",
     failed: "failed",
@@ -36,6 +37,7 @@ class GenevaDrive::StepExecution < ActiveRecord::Base
   # Outcome values for audit purposes
   OUTCOMES = %w[
     success
+    continued
     reattempted
     skipped
     canceled
@@ -50,6 +52,26 @@ 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
+
+  # The signal this execution is processing (the "attachment pin"). Set once,
+  # at the gate or by dispatch, and copied to successor executions so the
+  # payload stays stable across a whole resumable chain.
+  belongs_to :signal,
+    class_name: "GenevaDrive::Signal",
+    foreign_key: :signal_id,
+    optional: true
+
   # Validations
   validates :step_name, presence: true
   validates :scheduled_for, presence: true
@@ -60,6 +82,90 @@ 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
+
+    # Lazily checks whether the signal columns (signal_id and
+    # waiting_since) have been migrated, mirroring resumable_columns?.
+    # Never hits the database at class definition time.
+    #
+    # Everything unrelated to signals keeps working without them; a step
+    # declaring wait_for: fails loudly with a "run the install generator"
+    # message instead of silently running without its event.
+    #
+    # @return [Boolean]
+    def signal_columns?
+      if defined?(@_signal_columns)
+        return @_signal_columns
+      end
+
+      @_signal_columns = table_exists? &&
+        column_names.include?("signal_id") &&
+        column_names.include?("waiting_since")
+    end
+
+    # Clears the cached signal column detection result. Call this in tests or
+    # after running migrations in-process so the next access re-checks.
+    #
+    # @return [void]
+    def reset_signal_columns_cache!
+      remove_instance_variable(:@_signal_columns) if defined?(@_signal_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.
   #
@@ -136,6 +242,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
@@ -145,9 +282,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

data/lib/geneva_drive/test_helpers.rb

@@ -20,11 +20,11 @@ module GenevaDrive::TestHelpers
   # Executes all steps of a workflow synchronously for testing.
   #
   # This method runs through all scheduled steps, executing each one
-  # immediately regardless of wait times. Useful for testing complete
-  # workflow behavior.
+  # immediately regardless of wait times. Resumable steps are run to
+  # completion (interruption limits are disabled).
   #
   # @param workflow [GenevaDrive::Workflow] the workflow to run
-  # @param max_iterations [Integer] maximum steps to execute (safety limit)
+  # @param max_iterations [Integer] maximum step executions (safety limit)
   # @return [GenevaDrive::Workflow] the workflow after execution
   # @raise [RuntimeError] if max_iterations is exceeded
   #
@@ -46,7 +46,10 @@ module GenevaDrive::TestHelpers
       step_execution = workflow.current_execution
       break unless step_execution
 
-      step_execution.execute!
+      raise_if_parked!(step_execution, "speedrun_workflow")
+
+      # interruptible: false so resumable steps run to completion
+      step_execution.execute!(interruptible: false)
       iterations += 1
 
       if iterations >= max_iterations
@@ -78,6 +81,8 @@ module GenevaDrive::TestHelpers
     step_execution = workflow.current_execution
     return nil unless step_execution
 
+    raise_if_parked!(step_execution, "perform_next_step")
+
     step_execution.execute!
     workflow.reload
     step_execution
@@ -116,8 +121,9 @@ module GenevaDrive::TestHelpers
         "Available steps: #{available}"
     end
 
-    # Cancel any existing scheduled step executions to satisfy uniqueness constraint
-    workflow.step_executions.where(state: "scheduled").update_all(
+    # Cancel any existing scheduled or parked step executions to satisfy the
+    # uniqueness constraint
+    workflow.step_executions.where(state: %w[scheduled waiting]).update_all(
       state: "canceled",
       outcome: "canceled",
       canceled_at: Time.current
@@ -170,4 +176,204 @@ module GenevaDrive::TestHelpers
     assert_equal expected_state.to_s, workflow.state,
       "Expected workflow to be #{expected_state}, but was #{workflow.state}"
   end
+
+  # === Resumable Step Test Helpers ===
+
+  # Runs the current step to completion without advancing to the next step.
+  #
+  # For regular steps, this is equivalent to `perform_next_step`.
+  # For resumable steps, this disables interruption checks and runs until
+  # the step completes (or fails/cancels/skips).
+  #
+  # @param workflow [GenevaDrive::Workflow] the workflow containing the step
+  # @param max_executions [Integer] safety limit on job executions (default: 100)
+  # @return [GenevaDrive::StepExecution] the step execution
+  #
+  # @example Run current step to completion
+  #   workflow = BulkEmailWorkflow.create!(hero: campaign)
+  #   speedrun_current_step(workflow)
+  #   assert_step_executed(workflow, :send_emails)
+  #
+  def speedrun_current_step(workflow, max_executions: 100)
+    workflow.reload
+    step_execution = workflow.current_execution
+    return nil unless step_execution
+
+    raise_if_parked!(step_execution, "speedrun_current_step")
+
+    executions = 0
+    original_step_name = step_execution.step_name
+
+    loop do
+      step_execution.reload
+      raise_if_parked!(step_execution, "speedrun_current_step")
+
+      # Follow the execution chain: a completed execution that spawned a
+      # successor means the step is still going (suspend! and skip_to! create
+      # successors even with interruption checks disabled).
+      if GenevaDrive::StepExecution.resumable_columns? &&
+          step_execution.completed? && (successor = step_execution.successor)
+        step_execution = successor
+        next
+      end
+
+      break if step_execution.completed? || step_execution.failed? || step_execution.canceled? || step_execution.skipped?
+
+      # interruptible: false so the step runs to completion
+      step_execution.execute!(interruptible: false)
+      executions += 1
+
+      if executions >= max_executions
+        raise "speedrun_current_step exceeded max_executions (#{max_executions}). " \
+              "Step '#{original_step_name}' may be in an infinite loop."
+      end
+    end
+
+    workflow.reload
+    step_execution.reload
+    step_execution
+  end
+
+  # Runs the current (resumable) step for a limited number of iterations,
+  # then lets it interrupt and create a successor execution.
+  #
+  # Useful for testing partial progress and cursor state of resumable steps.
+  #
+  # @param workflow [GenevaDrive::Workflow] the workflow containing the step
+  # @param count [Integer] the number of iterations to run before interrupting
+  # @return [GenevaDrive::StepExecution] the executed (now completed) step execution
+  #
+  # @example Run three iterations, then inspect the cursor
+  #   run_iterations(workflow, count: 3)
+  #   assert_cursor(workflow, 3)
+  #
+  def run_iterations(workflow, count:)
+    workflow.reload
+    step_execution = workflow.current_execution
+    raise "No current step execution to run" unless step_execution
+
+    step_execution.execute!(max_iterations: count)
+
+    workflow.reload
+    step_execution.reload
+    step_execution
+  end
+
+  # Asserts that a resumable step's cursor matches the expected value.
+  #
+  # @param workflow [GenevaDrive::Workflow] the workflow to check
+  # @param expected_cursor [Object] the expected cursor value
+  # @return [void]
+  #
+  # @example Check cursor position
+  #   assert_cursor(workflow, 42)
+  #   assert_cursor(workflow, "page_token_abc")
+  #
+  def assert_cursor(workflow, expected_cursor)
+    workflow.reload
+    execution = workflow.current_execution
+    actual = execution&.cursor_value
+
+    assert_equal expected_cursor, actual,
+      "Expected cursor #{expected_cursor.inspect}, got #{actual.inspect}"
+  end
+
+  # Asserts that a step completed and has a scheduled successor execution.
+  # Used to verify that a resumable step was interrupted and will continue.
+  #
+  # @param workflow [GenevaDrive::Workflow] the workflow to check
+  # @param step_name [String, Symbol] the step name to check
+  # @return [void]
+  #
+  # @example Check step has a scheduled successor
+  #   assert_step_has_successor(workflow, :bulk_process)
+  #
+  def assert_step_has_successor(workflow, step_name)
+    workflow.reload
+    completed = workflow.step_executions.find_by(step_name: step_name.to_s, state: "completed")
+    assert completed, "Expected completed execution for step #{step_name}"
+
+    successor = completed.successor
+    assert successor, "Expected successor execution for step #{step_name}, but none found"
+    assert successor.scheduled?, "Expected successor to be scheduled, but was #{successor.state}"
+  end
+
+  # === Signal Test Helpers ===
+
+  # Asserts that the workflow is parked waiting for a signal.
+  #
+  # @param workflow [GenevaDrive::Workflow] the workflow to check
+  # @param signal_name [String, Symbol, nil] the signal name the step waits for
+  # @return [void]
+  #
+  # @example Check that the workflow is waiting
+  #   assert_waiting_for_signal(workflow, :payment_confirmed)
+  #
+  def assert_waiting_for_signal(workflow, signal_name = nil)
+    workflow.reload
+    execution = workflow.step_executions.where(state: "waiting").first
+
+    assert execution,
+      "Expected #{workflow.class.name} to be waiting for a signal, but no parked step execution was found " \
+      "(current execution: #{workflow.current_execution&.state.inspect})"
+
+    return unless signal_name
+
+    matcher = execution.step_definition&.signal_matcher
+    assert_equal signal_name.to_s, matcher_name(matcher),
+      "Expected step '#{execution.step_name}' to be waiting for #{signal_name.inspect}, " \
+      "but it waits for #{matcher}"
+  end
+
+  # Asserts that a signal with the given name exists in the given state.
+  #
+  # @param workflow [GenevaDrive::Workflow] the workflow to check
+  # @param signal_name [String, Symbol] the signal name
+  # @param state [String, Symbol] the expected signal state
+  # @return [void]
+  #
+  # @example Check that the signal was consumed
+  #   assert_signal_state(workflow, :payment_confirmed, :consumed)
+  #
+  def assert_signal_state(workflow, signal_name, state)
+    signal = workflow.signals.where(name: signal_name.to_s).order(:created_at, :id).last
+
+    assert signal, "Expected a #{signal_name.inspect} signal on #{workflow.class.name}, but none was found"
+    assert_equal state.to_s, signal.state,
+      "Expected signal #{signal_name.inspect} to be #{state}, but was #{signal.state}"
+  end
+
+  private
+
+  # The signal name a matcher accepts, when it has one to give. Custom
+  # matchers own their whole predicate and need not expose a name.
+  #
+  # @param matcher [Object, nil] anything responding to #matches?(signal)
+  # @return [String, nil]
+  def matcher_name(matcher)
+    matcher.name if matcher.respond_to?(:name)
+  end
+
+  # Raises a descriptive error when a step-driving helper runs into a parked
+  # execution. Without this a parked workflow would look like an infinite
+  # loop (or a silently passing assertion) instead of "you forgot to signal".
+  #
+  # @param step_execution [GenevaDrive::StepExecution] the execution about to be driven
+  # @param helper_name [String] the helper that was called
+  # @return [void]
+  def raise_if_parked!(step_execution, helper_name)
+    return unless step_execution.waiting?
+
+    matcher = begin
+      step_execution.step_definition&.signal_matcher
+    rescue
+      nil
+    end
+    waiting_for = matcher ? " waiting for #{matcher}" : ""
+    example_name = matcher_name(matcher)&.to_sym
+
+    raise "#{helper_name} cannot drive step '#{step_execution.step_name}': its execution is parked" \
+          "#{waiting_for}. Deliver the signal first, e.g. " \
+          "workflow.signal!(#{example_name.inspect}), then call #{helper_name} again."
+  end
 end

data/lib/geneva_drive/version.rb

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

data/lib/geneva_drive/workflow/metadata_accessor.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+# Provides safe read/write access to the freeform JSON metadata column
+# on workflows. 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 Workflow.
+#
+# @api private
+module GenevaDrive::Workflow::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
+
+    # 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
+
+  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