geneva_drive 0.4.0 → 0.6.0

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,8 @@ module GenevaDrive::TestHelpers
       step_execution = workflow.current_execution
       break unless step_execution
 
-      step_execution.execute!
+      # interruptible: false so resumable steps run to completion
+      step_execution.execute!(interruptible: false)
       iterations += 1
 
       if iterations >= max_iterations
@@ -170,4 +171,122 @@ 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
+
+    executions = 0
+    original_step_name = step_execution.step_name
+
+    loop do
+      step_execution.reload
+
+      # 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
 end

data/lib/geneva_drive/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module GenevaDrive
-  VERSION = "0.4.0"
+  VERSION = "0.6.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