geneva_drive 0.6.0 → 0.8.0

data/test/dsl/signal_step_definition_test.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+require "test_helper"
+
+# wait: and wait_for: read alike and take disjoint types, so the step
+# definition enforces the disjointness in both directions at class load.
+class SignalStepDefinitionTest < ActiveSupport::TestCase
+  class NameSetMatcher
+    def initialize(*names)
+      @names = names.map(&:to_s)
+    end
+
+    def matches?(signal)
+      @names.include?(signal.name)
+    end
+  end
+
+  def build_step(**options)
+    GenevaDrive::StepDefinition.new(name: "capture", callable: proc {}, **options)
+  end
+
+  test "wait_for: with a symbol builds a name matcher" do
+    step_def = build_step(wait_for: :payment_confirmed)
+
+    assert step_def.waits_for_signal?
+    assert_equal "payment_confirmed", step_def.signal_matcher.name
+    assert_nil step_def.signal_matcher.condition
+  end
+
+  test "wait_for: with a string builds a name matcher" do
+    step_def = build_step(wait_for: "payment_confirmed")
+
+    assert step_def.waits_for_signal?
+    assert_equal "payment_confirmed", step_def.signal_matcher.name
+  end
+
+  test "wait_for: with a SignalMatcher keeps it as-is" do
+    matcher = GenevaDrive::SignalMatcher.new(:payment_confirmed) { |payload| payload[:order_id] == 1 }
+    step_def = build_step(wait_for: matcher)
+
+    assert_same matcher, step_def.signal_matcher
+    assert_equal "payment_confirmed", step_def.signal_matcher.name
+    assert step_def.signal_matcher.condition
+  end
+
+  test "a SignalMatcher needs a name" do
+    assert_raises(ArgumentError) { GenevaDrive::SignalMatcher.new(nil) }
+    assert_raises(ArgumentError) { GenevaDrive::SignalMatcher.new("") }
+  end
+
+  test "wait_for: with a custom matcher object delegates the whole predicate" do
+    matcher = NameSetMatcher.new(:a, :b)
+    step_def = build_step(wait_for: matcher)
+
+    assert step_def.waits_for_signal?
+    assert_same matcher, step_def.signal_matcher
+  end
+
+  test "steps without wait_for: do not wait for a signal" do
+    assert_not build_step.waits_for_signal?
+    assert_nil build_step.signal_matcher
+  end
+
+  test "wait_for: with a duration points at wait:" do
+    error = assert_raises(GenevaDrive::StepConfigurationError) { build_step(wait_for: 2.days) }
+
+    assert_match(/wait_for: 2 days/, error.message)
+    assert_match(/to delay the step, use wait:/, error.message)
+  end
+
+  test "wait_for: with a number points at wait:" do
+    error = assert_raises(GenevaDrive::StepConfigurationError) { build_step(wait_for: 30) }
+
+    assert_match(/to delay the step, use wait:/, error.message)
+  end
+
+  test "wait_for: with a time points at wait:" do
+    error = assert_raises(GenevaDrive::StepConfigurationError) { build_step(wait_for: Time.current) }
+
+    assert_match(/to delay the step, use wait:/, error.message)
+  end
+
+  test "wait: with a symbol points at wait_for:" do
+    error = assert_raises(GenevaDrive::StepConfigurationError) { build_step(wait: :payment_confirmed) }
+
+    assert_match(/wait: :payment_confirmed/, error.message)
+    assert_match(/to wait for a signal, use wait_for:/, error.message)
+  end
+
+  test "wait: with a string points at wait_for: instead of silently meaning zero seconds" do
+    error = assert_raises(GenevaDrive::StepConfigurationError) { build_step(wait: "payment_confirmed") }
+
+    assert_match(/to wait for a signal, use wait_for:/, error.message)
+  end
+
+  test "wait: with a duration-shaped string is rejected too" do
+    error = assert_raises(GenevaDrive::StepConfigurationError) { build_step(wait: "7200") }
+
+    assert_match(/to wait for a signal, use wait_for:/, error.message)
+  end
+
+  test "wait: with a matcher object points at wait_for:" do
+    error = assert_raises(GenevaDrive::StepConfigurationError) { build_step(wait: NameSetMatcher.new(:a)) }
+
+    assert_match(/to wait for a signal, use wait_for:/, error.message)
+  end
+
+  test "wait: still accepts durations and numbers" do
+    assert_equal 2.days, build_step(wait: 2.days).wait
+    assert_equal 30, build_step(wait: 30).wait
+  end
+
+  test "wait_for: with an unusable value is rejected" do
+    error = assert_raises(GenevaDrive::StepConfigurationError) { build_step(wait_for: Object.new) }
+
+    assert_match(/must be a Symbol, String, GenevaDrive::SignalMatcher, or an object responding to #matches\?/, error.message)
+  end
+
+  test "wait: and wait_for: compose" do
+    step_def = build_step(wait: 2.days, wait_for: :payment_confirmed)
+
+    assert_equal 2.days, step_def.wait
+    assert step_def.waits_for_signal?
+  end
+
+  test "resumable steps accept wait_for:" do
+    step_def = GenevaDrive::ResumableStepDefinition.new(name: "iterate", wait_for: :go) { |iter| }
+
+    assert step_def.resumable?
+    assert step_def.waits_for_signal?
+  end
+end

data/test/dummy/config/database.yml

@@ -1,13 +1,48 @@
-# PostgreSQL configuration for GenevaDrive test suite
+<%
+  # Everything the database tasks write under db/ is adapter-specific, the
+  # schema dump above all: parallelize() builds every worker database out of
+  # that dump, and a PostgreSQL one carries jsonb columns SQLite cannot load.
+  # CI points DATABASE_URL at a different engine per leg, so each engine gets
+  # its own corner of db/ and the legs stop overwriting each other's artifacts.
+  #
+  # This has to be resolved here rather than in an initializer - db:prepare and
+  # the other database tasks hang off :load_config, which never runs those.
+  url = ENV["DATABASE_URL"]
+  adapter = if url
+    ActiveRecord::DatabaseConfigurations::ConnectionUrlResolver.new(url).to_hash[:adapter]
+  else
+    "sqlite3"
+  end
+
+  # MariaDB and MySQL are both the mysql2 adapter but do not produce the same
+  # dump - MariaDB has no JSON type - so the engine, when the runner names one,
+  # is what the artifacts get filed under.
+  engine = ENV.fetch("GENEVA_DRIVE_ENGINE", adapter)
+  artifacts = "db/#{engine}"
+
+  # The dump is keyed by Rails minor on top of that: it is written as
+  # `ActiveRecord::Schema[8.1].define`, and 7.2 refuses to load a version it
+  # has never heard of. The databases themselves are not version-specific -
+  # the migrations produce the same DDL - so only the dump gets the suffix.
+  schema_dump = "#{engine}/schema-#{Rails::VERSION::MAJOR}.#{Rails::VERSION::MINOR}.rb"
+
+  # Rails only creates db/ itself, not the subdirectory the dump lives in.
+  require "fileutils"
+  FileUtils.mkdir_p(Rails.root.join(artifacts))
+%>
+# The test suite runs against SQLite by default so that a fresh clone can run
+# `rake` with no database server. CI - and `bin/matrix` locally - override this
+# with DATABASE_URL to also exercise PostgreSQL and MySQL.
 default: &default
-  adapter: postgresql
-  encoding: unicode
+  adapter: sqlite3
   pool: <%= ENV.fetch("RAILS_MAX_THREADS") { 5 } %>
+  timeout: 5000
+  schema_dump: <%= schema_dump %>
 
 development:
   <<: *default
-  database: geneva_drive_development
+  database: storage/development.sqlite3
 
 test:
   <<: *default
-  database: geneva_drive_test
+  database: <%= artifacts %>/test.sqlite3

data/test/dummy/config/initializers/geneva_drive.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+# license: LGPLv3.0
+
+# How long to keep completed/canceled workflows before automatic deletion.
+# Set to nil to disable automatic cleanup.
+# When enabled, finished and canceled workflows older than this threshold
+# will be deleted along with their step execution records.
+#
+# GenevaDrive.delete_completed_workflows_after = 30.days
+
+# How long a step execution can be in "executing" state before being
+# considered stuck. This typically happens when a worker process crashes
+# mid-execution. The HousekeepingJob will recover these based on the
+# stuck_recovery_action setting.
+#
+# GenevaDrive.stuck_executing_threshold = 1.hour
+
+# How long a step execution can be past its scheduled_for time while
+# still in "scheduled" state before being considered stuck. This can
+# happen if jobs fail to enqueue or are lost by the queue backend.
+#
+# GenevaDrive.stuck_scheduled_threshold = 15.minutes
+
+# Action to take when recovering stuck step executions.
+# - :reattempt - Mark as recovered and schedule a retry (default)
+# - :cancel - Mark as recovered and cancel the workflow
+#
+# GenevaDrive.stuck_recovery_action = :reattempt
+
+# Maximum number of workflows/step executions to process in a single
+# housekeeping run. Prevents runaway processing if there's a large backlog.
+#
+# GenevaDrive.housekeeping_batch_size = 1000
+
+# Whether to defer job enqueueing until after the database transaction commits.
+# In production this ensures step execution records are visible to job workers
+# before the job runs. In test environments (the default when Rails.env.test?)
+# this is set to false so that jobs are enqueued immediately — transactional
+# tests (especially with SQLite) never commit the outermost transaction, which
+# can cause after_commit callbacks to misbehave or not fire at all.
+#
+# Set to true in tests if you need strict transaction semantics for a specific
+# test suite, or if you are not using transactional tests.
+#
+# GenevaDrive.enqueue_after_commit = !Rails.env.test?

data/test/dummy_install/db/migrate/20260217112949_create_geneva_drive_workflows.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+# license: LGPLv3.0
+
+class CreateGenevaDriveWorkflows < ActiveRecord::Migration[7.2]
+  include GenevaDrive::MigrationHelpers
+
+  def change
+    create_table :geneva_drive_workflows, **geneva_drive_table_options do |t|
+      # Core identification (STI)
+      t.string :type, null: false, index: true
+
+      # Polymorphic association to the hero of the workflow
+      t.string :hero_type, null: false
+      t.column :hero_id, geneva_drive_key_type, null: false
+
+      # State machine
+      t.string :state, null: false, default: "ready", index: true
+
+      # Current position in workflow
+      t.string :current_step_name
+      t.string :next_step_name
+
+      # Multiple workflows of same type for same hero
+      t.boolean :allow_multiple, default: false, null: false
+
+      # Timestamps
+      t.datetime :started_at
+      t.datetime :transitioned_at
+
+      t.timestamps
+    end
+
+    # Polymorphic index
+    add_index :geneva_drive_workflows, [:hero_type, :hero_id]
+
+    reversible do |direction|
+      direction.up { create_db_specific_indices }
+    end
+  end
+
+  def create_db_specific_indices
+    # Database-specific uniqueness constraint for ongoing workflows
+    # Ensures only one ongoing workflow per (type, hero) unless allow_multiple is true
+    adapter = connection.adapter_name.downcase
+    if adapter.include?("postgresql")
+      execute <<-SQL
+        CREATE UNIQUE INDEX index_geneva_drive_workflows_unique_ongoing
+        ON geneva_drive_workflows (type, hero_type, hero_id)
+        WHERE state NOT IN ('finished', 'canceled') AND allow_multiple = false;
+      SQL
+    elsif adapter.include?("mysql")
+      execute <<-SQL
+        ALTER TABLE geneva_drive_workflows
+        ADD COLUMN ongoing_unique_key VARCHAR(767)
+        AS (
+          CASE
+            WHEN state NOT IN ('finished', 'canceled') AND allow_multiple = 0
+            THEN CONCAT(type, '-', hero_type, '-', hero_id)
+            ELSE NULL
+          END
+        ) STORED;
+      SQL
+      execute <<-SQL
+        CREATE UNIQUE INDEX index_geneva_drive_workflows_unique_ongoing
+        ON geneva_drive_workflows (ongoing_unique_key);
+      SQL
+    elsif adapter.include?("sqlite")
+      execute <<-SQL
+        CREATE UNIQUE INDEX index_geneva_drive_workflows_unique_ongoing
+        ON geneva_drive_workflows (type, hero_type, hero_id)
+        WHERE state NOT IN ('finished', 'canceled') AND allow_multiple = 0;
+      SQL
+    end
+  end
+end

data/test/dummy_install/db/migrate/20260217112950_create_geneva_drive_step_executions.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+# license: LGPLv3.0
+
+class CreateGenevaDriveStepExecutions < ActiveRecord::Migration[7.2]
+  include GenevaDrive::MigrationHelpers
+
+  def change
+    key_type = geneva_drive_key_type
+
+    create_table :geneva_drive_step_executions, **geneva_drive_table_options do |t|
+      # Link to workflow (cascade delete when workflow is deleted)
+      t.references :workflow,
+        null: false,
+        foreign_key: {to_table: :geneva_drive_workflows, on_delete: :cascade},
+        index: true,
+        type: key_type
+
+      # Which step this execution represents
+      t.string :step_name, null: false
+
+      # Execution state machine
+      t.string :state, null: false, default: "scheduled", index: true
+
+      # Outcome for audit purposes
+      t.string :outcome
+
+      # Scheduling
+      t.datetime :scheduled_for, null: false, index: true
+
+      # Execution tracking (individual timestamps for audit trail)
+      t.datetime :started_at
+      t.datetime :completed_at
+      t.datetime :failed_at
+      t.datetime :canceled_at
+      t.datetime :skipped_at
+
+      # Error tracking
+      t.string :error_class_name
+      t.text :error_message
+      t.text :error_backtrace
+
+      # Job tracking (for debugging)
+      t.string :job_id
+
+      t.timestamps
+    end
+
+    # Index for finding scheduled executions
+    add_index :geneva_drive_step_executions,
+      [:state, :scheduled_for],
+      name: "index_geneva_drive_step_executions_scheduled"
+
+    # Index for workflow execution history
+    add_index :geneva_drive_step_executions, [:workflow_id, :created_at]
+
+    # Index for common query patterns
+    add_index :geneva_drive_step_executions, [:workflow_id, :state]
+
+    reversible do |direction|
+      direction.up { create_db_specific_indices }
+    end
+  end
+
+  def create_db_specific_indices
+    # Database-specific uniqueness constraint for active step executions
+    # Ensures only one active (scheduled/in_progress) step per workflow
+    adapter = connection.adapter_name.downcase
+    if adapter.include?("postgresql")
+      execute <<-SQL
+        CREATE UNIQUE INDEX index_geneva_drive_step_executions_one_active
+        ON geneva_drive_step_executions (workflow_id)
+        WHERE state IN ('scheduled', 'in_progress');
+      SQL
+    elsif adapter.include?("mysql")
+      execute <<-SQL
+        ALTER TABLE geneva_drive_step_executions
+        ADD COLUMN active_unique_key VARCHAR(767)
+        AS (
+          CASE
+            WHEN state IN ('scheduled', 'in_progress')
+            THEN CAST(workflow_id AS CHAR)
+            ELSE NULL
+          END
+        ) STORED;
+      SQL
+      execute <<-SQL
+        CREATE UNIQUE INDEX index_geneva_drive_step_executions_one_active
+        ON geneva_drive_step_executions (active_unique_key);
+      SQL
+    elsif adapter.include?("sqlite")
+      execute <<-SQL
+        CREATE UNIQUE INDEX index_geneva_drive_step_executions_one_active
+        ON geneva_drive_step_executions (workflow_id)
+        WHERE state IN ('scheduled', 'in_progress');
+      SQL
+    end
+  end
+end

data/test/dummy_install/db/migrate/20260217112951_add_finished_at_to_geneva_drive_step_executions.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+# license: LGPLv3.0
+
+class AddFinishedAtToGenevaDriveStepExecutions < ActiveRecord::Migration[7.2]
+  def change
+    add_column :geneva_drive_step_executions, :finished_at, :datetime
+
+    add_index :geneva_drive_step_executions, :finished_at
+
+    reversible do |direction|
+      direction.up do
+        # Backfill finished_at from existing timestamp columns.
+        # Uses COALESCE to pick the first non-null value.
+        execute <<-SQL.squish
+          UPDATE geneva_drive_step_executions
+          SET finished_at = COALESCE(completed_at, failed_at, canceled_at, skipped_at)
+          WHERE finished_at IS NULL
+            AND (completed_at IS NOT NULL
+              OR failed_at IS NOT NULL
+              OR canceled_at IS NOT NULL
+              OR skipped_at IS NOT NULL)
+        SQL
+      end
+    end
+  end
+end

data/test/dummy_install/db/migrate/20260217112952_add_error_class_name_to_geneva_drive_step_executions.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+# license: LGPLv3.0
+
+class AddErrorClassNameToGenevaDriveStepExecutions < ActiveRecord::Migration[7.2]
+  def change
+    add_column :geneva_drive_step_executions, :error_class_name, :string, if_not_exists: true
+  end
+end

data/test/dummy_install/db/migrate/20260217112953_add_resumable_step_support_to_geneva_drive_step_executions.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+# license: LGPLv3.0
+
+class AddResumableStepSupportToGenevaDriveStepExecutions < ActiveRecord::Migration[7.2]
+  def change
+    # Use database-native JSON type:
+    # - PostgreSQL: jsonb (indexed, efficient, supports containment queries)
+    # - MySQL 5.7+: json (native validation and storage)
+    # - SQLite: json (Rails handles as TEXT with serialization)
+    adapter = connection.adapter_name.downcase
+    if adapter.include?("postgresql")
+      add_column :geneva_drive_step_executions, :cursor, :jsonb
+    else
+      add_column :geneva_drive_step_executions, :cursor, :json
+    end
+
+    add_column :geneva_drive_step_executions, :completed_iterations, :integer, default: 0, null: false
+
+    reversible do |direction|
+      direction.up { update_unique_index_for_suspended_state }
+      direction.down { restore_original_unique_index }
+    end
+  end
+
+  private
+
+  def update_unique_index_for_suspended_state
+    # Update unique constraint to include 'suspended' as an active state.
+    # The constraint ensures only one active step execution per workflow.
+    adapter = connection.adapter_name.downcase
+
+    if adapter.include?("postgresql")
+      execute <<-SQL
+        DROP INDEX IF EXISTS index_geneva_drive_step_executions_one_active;
+      SQL
+      execute <<-SQL
+        CREATE UNIQUE INDEX index_geneva_drive_step_executions_one_active
+        ON geneva_drive_step_executions (workflow_id)
+        WHERE state IN ('scheduled', 'in_progress', 'suspended');
+      SQL
+    elsif adapter.include?("mysql")
+      # Drop the old generated column and index
+      execute <<-SQL
+        DROP INDEX index_geneva_drive_step_executions_one_active
+        ON geneva_drive_step_executions;
+      SQL
+      execute <<-SQL
+        ALTER TABLE geneva_drive_step_executions
+        DROP COLUMN active_unique_key;
+      SQL
+      # Create new generated column including suspended state
+      execute <<-SQL
+        ALTER TABLE geneva_drive_step_executions
+        ADD COLUMN active_unique_key VARCHAR(767)
+        AS (
+          CASE
+            WHEN state IN ('scheduled', 'in_progress', 'suspended')
+            THEN CAST(workflow_id AS CHAR)
+            ELSE NULL
+          END
+        ) STORED;
+      SQL
+      execute <<-SQL
+        CREATE UNIQUE INDEX index_geneva_drive_step_executions_one_active
+        ON geneva_drive_step_executions (active_unique_key);
+      SQL
+    elsif adapter.include?("sqlite")
+      execute <<-SQL
+        DROP INDEX IF EXISTS index_geneva_drive_step_executions_one_active;
+      SQL
+      execute <<-SQL
+        CREATE UNIQUE INDEX index_geneva_drive_step_executions_one_active
+        ON geneva_drive_step_executions (workflow_id)
+        WHERE state IN ('scheduled', 'in_progress', 'suspended');
+      SQL
+    end
+  end
+
+  def restore_original_unique_index
+    # Restore original unique constraint without 'suspended' state
+    adapter = connection.adapter_name.downcase
+
+    if adapter.include?("postgresql")
+      execute <<-SQL
+        DROP INDEX IF EXISTS index_geneva_drive_step_executions_one_active;
+      SQL
+      execute <<-SQL
+        CREATE UNIQUE INDEX index_geneva_drive_step_executions_one_active
+        ON geneva_drive_step_executions (workflow_id)
+        WHERE state IN ('scheduled', 'in_progress');
+      SQL
+    elsif adapter.include?("mysql")
+      execute <<-SQL
+        DROP INDEX index_geneva_drive_step_executions_one_active
+        ON geneva_drive_step_executions;
+      SQL
+      execute <<-SQL
+        ALTER TABLE geneva_drive_step_executions
+        DROP COLUMN active_unique_key;
+      SQL
+      execute <<-SQL
+        ALTER TABLE geneva_drive_step_executions
+        ADD COLUMN active_unique_key VARCHAR(767)
+        AS (
+          CASE
+            WHEN state IN ('scheduled', 'in_progress')
+            THEN CAST(workflow_id AS CHAR)
+            ELSE NULL
+          END
+        ) STORED;
+      SQL
+      execute <<-SQL
+        CREATE UNIQUE INDEX index_geneva_drive_step_executions_one_active
+        ON geneva_drive_step_executions (active_unique_key);
+      SQL
+    elsif adapter.include?("sqlite")
+      execute <<-SQL
+        DROP INDEX IF EXISTS index_geneva_drive_step_executions_one_active;
+      SQL
+      execute <<-SQL
+        CREATE UNIQUE INDEX index_geneva_drive_step_executions_one_active
+        ON geneva_drive_step_executions (workflow_id)
+        WHERE state IN ('scheduled', 'in_progress');
+      SQL
+    end
+  end
+end