geneva_drive 0.7.0 → 0.8.0

data/test/test_helper.rb

@@ -7,29 +7,52 @@ require_relative "../test/dummy/config/environment"
 ActiveRecord::Migrator.migrations_paths = [File.expand_path("../test/dummy/db/migrate", __dir__)]
 ActiveRecord::Migrator.migrations_paths << File.expand_path("../db/migrate", __dir__)
 
-# Ensure GenevaDrive migrations exist and database is prepared.
-# The generator is the single source of truth for migrations.
+# Bring the dummy app's database in line with the migrations the install
+# generator produces, recreating it from scratch whenever it has drifted.
+#
+# Rebuilding rather than migrating forward is deliberate. The generated
+# migrations are gitignored and get fresh timestamps every time they are
+# regenerated, so a database left behind by an earlier generation records
+# versions that no longer exist on disk: every migration reads as pending, and
+# replaying them onto the existing tables just fails on "table already exists".
 unless defined?(GENEVA_DRIVE_TEST_DB_PREPARED)
   GENEVA_DRIVE_TEST_DB_PREPARED = true
 
   dummy_root = File.expand_path("../test/dummy", __dir__)
-  migrations = Dir.glob("#{dummy_root}/db/migrate/*geneva_drive*.rb")
-  tables_exist = begin
-    ActiveRecord::Base.connection.table_exists?("geneva_drive_workflows")
-  rescue
-    false
-  end
+  db_config = ActiveRecord::Base.connection_db_config
+  # Adapter-specific, and deliberately so - see the comment in the dummy app's
+  # config/database.yml. Ask Rails for the path rather than rebuilding it here.
+  schema_file = ActiveRecord::Tasks::DatabaseTasks.schema_dump_path(db_config)
 
-  if migrations.empty? && !tables_exist
+  # The generator is the single source of truth for migrations.
+  if Dir.glob("#{dummy_root}/db/migrate/*geneva_drive*.rb").empty?
     puts "Generating GenevaDrive migrations..."
     Dir.chdir(dummy_root) do
       system("bin/rails", "generate", "geneva_drive:install", "--skip") || abort("Failed to generate migrations")
-      system("bin/rails", "db:migrate") || abort("Failed to run migrations")
     end
-  elsif migrations.any? && !tables_exist
-    puts "Running pending migrations..."
+  end
+
+  on_disk = Dir.glob("#{dummy_root}/db/migrate/*.rb").map { |path| File.basename(path)[/\A\d+/] }
+  applied = begin
+    ActiveRecord::Base.connection.select_values("SELECT version FROM schema_migrations").map(&:to_s)
+  rescue
+    [] # No database, or no schema_migrations in it yet
+  end
+
+  if (on_disk - applied).any? || !File.exist?(schema_file)
+    puts "Recreating the #{db_config.adapter} test database..."
+    # db:migrate seeds an empty database from the schema dump before applying
+    # anything, so the outdated dump has to go first - otherwise it recreates
+    # exactly the tables the migrations are about to create.
+    File.delete(schema_file) if File.exist?(schema_file)
+    # bin/rails cannot drop a database this process still holds a connection to.
+    ActiveRecord::Base.connection_handler.clear_all_connections!
     Dir.chdir(dummy_root) do
-      system("bin/rails", "db:prepare") || abort("Failed to prepare database")
+      # One bin/rails per task, deliberately. Asking a single process to drop,
+      # recreate and migrate carries its column cache across the drop, and the
+      # schema it then dumps silently loses column defaults.
+      system("bin/rails", "db:drop") || abort("Failed to drop the test database")
+      system("bin/rails", "db:prepare") || abort("Failed to recreate the test database")
     end
   end
 end
@@ -44,6 +67,21 @@ if ActiveSupport::TestCase.respond_to?(:fixture_paths=)
   ActiveSupport::TestCase.fixtures :all
 end
 
+# Rails 8.1 clears Active Record's connections before forking the parallel test
+# workers. 7.2 and 8.0 fork with them still open, and a libpq connection
+# inherited across the fork takes the child down with a segfault in
+# PG::Connection#connect_start as it opens its own - a race, so it only bites
+# some of the time, which makes it maddening rather than merely broken. Where
+# upstream has no pre-fork hook to register on, wrap the fork point itself.
+unless ActiveSupport::Testing::Parallelization.respond_to?(:before_fork_hook)
+  ActiveSupport::Testing::Parallelization.prepend(Module.new do
+    def start
+      ActiveRecord::Base.connection_handler.clear_all_connections!
+      super
+    end
+  end)
+end
+
 # Test helper methods
 class ActiveSupport::TestCase
   # Run tests in parallel with specified workers

data/test/workflow/removed_step_test.rb

@@ -0,0 +1,294 @@
+# frozen_string_literal: true
+
+require "test_helper"
+
+class RemovedStepTest < ActiveSupport::TestCase
+  include GenevaDrive::TestHelpers
+
+  # The shape a workflow has after `capture_payment` was taken out of the
+  # middle of it and a gravestone left behind.
+  class PaymentWorkflow < GenevaDrive::Workflow
+    step :authorize do
+      Thread.current[:ran] << :authorize
+    end
+
+    removed_step :capture_payment
+
+    step :send_receipt do
+      Thread.current[:ran] << :send_receipt
+    end
+  end
+
+  # A gravestone in first position, so nothing runnable precedes it.
+  class LeadingRemovalWorkflow < GenevaDrive::Workflow
+    removed_step :old_preflight
+
+    step :only_step do
+      Thread.current[:ran] << :only_step
+    end
+  end
+
+  # A gravestone in last position, so nothing runnable follows it.
+  class TrailingRemovalWorkflow < GenevaDrive::Workflow
+    step :only_step do
+      Thread.current[:ran] << :only_step
+    end
+
+    removed_step :old_teardown
+  end
+
+  # Every step removed - there is nothing left to run at all.
+  class FullyRemovedWorkflow < GenevaDrive::Workflow
+    removed_step :gone_one
+    removed_step :gone_two
+  end
+
+  # A step deleted outright, with no gravestone. This is the situation
+  # removed_step exists to prevent, kept here to prove the default is
+  # unchanged: the workflow still pauses rather than guessing.
+  class UndeclaredRemovalWorkflow < GenevaDrive::Workflow
+    step :step_one do
+      Thread.current[:ran] << :step_one
+    end
+
+    step :step_two do
+      Thread.current[:ran] << :step_two
+    end
+  end
+
+  setup do
+    @user = create_user
+    Thread.current[:ran] = []
+  end
+
+  teardown do
+    Thread.current[:ran] = nil
+  end
+
+  # ===========================================
+  # The declaration itself
+  # ===========================================
+
+  test "removed_step registers a gravestone that reports itself as removed" do
+    step_def = PaymentWorkflow.steps.named("capture_payment")
+
+    assert_not_nil step_def
+    assert_predicate step_def, :removed?
+    assert_equal "capture_payment", step_def.name
+  end
+
+  test "an ordinary step is not removed" do
+    assert_not_predicate PaymentWorkflow.steps.named("authorize"), :removed?
+  end
+
+  test "a removed step keeps its name resolvable" do
+    assert PaymentWorkflow.steps.key?("capture_payment")
+  end
+
+  test "a removed step holds its position in the declared order" do
+    assert_equal %w[authorize capture_payment send_receipt], PaymentWorkflow.steps.map(&:name)
+  end
+
+  test "runnable omits removed steps and removed lists them" do
+    assert_equal %w[authorize send_receipt], PaymentWorkflow.steps.runnable.map(&:name)
+    assert_equal %w[capture_payment], PaymentWorkflow.steps.removed.map(&:name)
+  end
+
+  test "removed_step refuses a name already taken by a step" do
+    error = assert_raises(GenevaDrive::StepConfigurationError) do
+      Class.new(GenevaDrive::Workflow) do
+        def self.name = "DoubleDeclarationWorkflow"
+
+        step :thing do
+          # no-op
+        end
+
+        removed_step :thing
+      end
+    end
+
+    assert_match(/already defined/, error.message)
+  end
+
+  test "removed_step requires a name" do
+    assert_raises(ArgumentError) do
+      Class.new(GenevaDrive::Workflow) do
+        removed_step nil
+      end
+    end
+  end
+
+  test "before_step can still reference a removed step" do
+    klass = Class.new(GenevaDrive::Workflow) do
+      def self.name = "PositionedAroundRemovalWorkflow"
+
+      removed_step :gone
+
+      step :inserted, before_step: :gone do
+        # no-op
+      end
+    end
+
+    assert_equal %w[inserted gone], klass.steps.map(&:name)
+  end
+
+  # ===========================================
+  # Navigation never lands on a gravestone
+  # ===========================================
+
+  test "next_after steps over a removed step" do
+    assert_equal "send_receipt", PaymentWorkflow.steps.next_after("authorize").name
+  end
+
+  test "next_after from a removed step returns the next runnable one" do
+    assert_equal "send_receipt", PaymentWorkflow.steps.next_after("capture_payment").name
+  end
+
+  test "next_after returns nil when only removed steps remain" do
+    assert_nil TrailingRemovalWorkflow.steps.next_after("only_step")
+  end
+
+  test "next_after from the beginning skips a leading removed step" do
+    assert_equal "only_step", LeadingRemovalWorkflow.steps.next_after(nil).name
+  end
+
+  test "next_after still returns nil for a name the collection never had" do
+    assert_nil PaymentWorkflow.steps.next_after("never_existed")
+  end
+
+  test "previous_before steps over a removed step" do
+    assert_equal "authorize", PaymentWorkflow.steps.previous_before("send_receipt").name
+  end
+
+  test "previous_before returns nil when only removed steps precede" do
+    assert_nil LeadingRemovalWorkflow.steps.previous_before("only_step")
+  end
+
+  # ===========================================
+  # Scheduling never spools a removed step
+  # ===========================================
+
+  test "a new workflow runs straight past a removed middle step" do
+    workflow = PaymentWorkflow.create!(hero: @user)
+    speedrun_workflow(workflow)
+
+    assert_equal %i[authorize send_receipt], Thread.current[:ran]
+    assert_workflow_state(workflow, :finished)
+    assert_empty workflow.step_executions.where(step_name: "capture_payment")
+  end
+
+  test "a new workflow starts at the first runnable step, not a leading gravestone" do
+    workflow = LeadingRemovalWorkflow.create!(hero: @user)
+
+    assert_equal "only_step", workflow.next_step_name
+
+    speedrun_workflow(workflow)
+
+    assert_equal %i[only_step], Thread.current[:ran]
+    assert_workflow_state(workflow, :finished)
+  end
+
+  test "a trailing gravestone finishes the workflow instead of being scheduled" do
+    workflow = TrailingRemovalWorkflow.create!(hero: @user)
+    speedrun_workflow(workflow)
+
+    assert_workflow_state(workflow, :finished)
+    assert_empty workflow.step_executions.where(step_name: "old_teardown")
+  end
+
+  test "a workflow whose every step was removed finishes immediately" do
+    workflow = FullyRemovedWorkflow.create!(hero: @user)
+
+    assert_workflow_state(workflow, :finished)
+    assert_empty workflow.step_executions
+  end
+
+  # ===========================================
+  # Executions scheduled before the removal shipped
+  # ===========================================
+
+  test "an execution scheduled before the removal is skipped and the workflow continues" do
+    workflow = PaymentWorkflow.create!(hero: @user)
+
+    # Stand in for a rolling deploy: this row was written by the old code,
+    # which still had capture_payment as a real step.
+    execution = reschedule_at(workflow, "capture_payment")
+
+    execution.execute!
+
+    assert_equal "skipped", execution.reload.state
+    assert_equal "skipped", execution.outcome
+
+    speedrun_workflow(workflow)
+
+    assert_equal %i[send_receipt], Thread.current[:ran]
+    assert_workflow_state(workflow, :finished)
+  end
+
+  test "an execution for a trailing removed step finishes the workflow" do
+    workflow = TrailingRemovalWorkflow.create!(hero: @user)
+    execution = reschedule_at(workflow, "old_teardown")
+
+    execution.execute!
+
+    assert_equal "skipped", execution.reload.state
+    assert_workflow_state(workflow, :finished)
+  end
+
+  test "a step deleted without a gravestone still pauses the workflow" do
+    workflow = UndeclaredRemovalWorkflow.create!(hero: @user)
+    execution = reschedule_at(workflow, "deleted_without_a_trace")
+
+    assert_raises(GenevaDrive::StepNotDefinedError) { execution.execute! }
+
+    assert_workflow_state(workflow, :paused)
+  end
+
+  # ===========================================
+  # Knowing when the gravestone can go
+  # ===========================================
+
+  test "removed_steps_in_flight counts rows still pointing at a removed step" do
+    workflow = PaymentWorkflow.create!(hero: @user)
+    reschedule_at(workflow, "capture_payment")
+
+    assert_equal({"capture_payment" => 1}, PaymentWorkflow.removed_steps_in_flight)
+  end
+
+  test "removed_steps_in_flight ignores workflows that will never run again" do
+    workflow = PaymentWorkflow.create!(hero: @user)
+    reschedule_at(workflow, "capture_payment")
+    workflow.update!(state: "canceled")
+
+    assert_empty PaymentWorkflow.removed_steps_in_flight
+  end
+
+  test "removed_steps_in_flight is empty once nothing references the name" do
+    PaymentWorkflow.create!(hero: @user)
+
+    assert_empty PaymentWorkflow.removed_steps_in_flight
+  end
+
+  test "removed_steps_in_flight is empty for a workflow with no removals" do
+    assert_empty UndeclaredRemovalWorkflow.removed_steps_in_flight
+  end
+
+  private
+
+  # Replaces whatever is scheduled with an execution for the given step name,
+  # the way a row written by a previous deploy would look.
+  def reschedule_at(workflow, step_name)
+    workflow.step_executions.where(state: %w[scheduled waiting]).update_all(
+      state: "canceled",
+      outcome: "canceled",
+      canceled_at: Time.current
+    )
+    execution = workflow.step_executions.create!(
+      step_name: step_name,
+      state: "scheduled",
+      scheduled_for: Time.current
+    )
+    workflow.update!(next_step_name: step_name, current_step_name: nil)
+    execution
+  end
+end

data/test/workflow/resume_at_test.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+require "test_helper"
+
+class ResumeAtTest < ActiveSupport::TestCase
+  include GenevaDrive::TestHelpers
+
+  class ThreeStepWorkflow < GenevaDrive::Workflow
+    step :step_one do
+      Thread.current[:ran] << :step_one
+    end
+
+    step :step_two do
+      Thread.current[:ran] << :step_two
+    end
+
+    step :step_three do
+      Thread.current[:ran] << :step_three
+    end
+  end
+
+  class WorkflowWithRemoval < GenevaDrive::Workflow
+    step :step_one do
+      Thread.current[:ran] << :step_one
+    end
+
+    removed_step :parked_forever
+
+    step :step_three do
+      Thread.current[:ran] << :step_three
+    end
+  end
+
+  setup do
+    @user = create_user
+    Thread.current[:ran] = []
+  end
+
+  teardown do
+    Thread.current[:ran] = nil
+  end
+
+  # ===========================================
+  # resume_at!
+  # ===========================================
+
+  test "resume_at! continues from the named step" do
+    workflow = paused_at(ThreeStepWorkflow.create!(hero: @user), "step_two")
+
+    execution = workflow.resume_at!(:step_three)
+
+    assert_equal "step_three", execution.step_name
+    assert_equal "step_three", workflow.reload.next_step_name
+    assert_equal "ready", workflow.state
+
+    speedrun_workflow(workflow)
+
+    assert_equal %i[step_three], Thread.current[:ran]
+    assert_workflow_state(workflow, :finished)
+  end
+
+  test "resume_at! cancels the execution the workflow was pointed at" do
+    workflow = ThreeStepWorkflow.create!(hero: @user)
+    stale = workflow.current_execution
+    workflow.pause!
+
+    workflow.resume_at!(:step_three)
+
+    assert_equal "canceled", stale.reload.state
+  end
+
+  test "resume_at! accepts a string as readily as a symbol" do
+    workflow = paused_at(ThreeStepWorkflow.create!(hero: @user), "step_two")
+
+    assert_equal "step_three", workflow.resume_at!("step_three").step_name
+  end
+
+  test "resume_at! rejects a step that is not defined" do
+    workflow = paused_at(ThreeStepWorkflow.create!(hero: @user), "step_two")
+
+    error = assert_raises(GenevaDrive::StepNotDefinedError) { workflow.resume_at!(:nowhere) }
+
+    assert_match(/not defined/, error.message)
+    assert_match(/step_one, step_two, step_three/, error.message)
+    assert_equal "paused", workflow.reload.state
+  end
+
+  test "resume_at! refuses to land on a removed step" do
+    workflow = paused_at(WorkflowWithRemoval.create!(hero: @user), "step_one")
+
+    error = assert_raises(GenevaDrive::StepNotDefinedError) { workflow.resume_at!(:parked_forever) }
+
+    assert_match(/removed_step/, error.message)
+    assert_equal "paused", workflow.reload.state
+  end
+
+  test "resume_at! only applies to paused workflows" do
+    workflow = ThreeStepWorkflow.create!(hero: @user)
+
+    assert_raises(GenevaDrive::InvalidStateError) { workflow.resume_at!(:step_three) }
+  end
+
+  # ===========================================
+  # resume! on a workflow pointed at a vanished step
+  # ===========================================
+
+  test "resume! explains itself when the step it points at is gone" do
+    workflow = paused_at(ThreeStepWorkflow.create!(hero: @user), "deleted_without_a_trace")
+
+    error = assert_raises(GenevaDrive::StepNotDefinedError) { workflow.resume! }
+
+    assert_match(/no longer defined/, error.message)
+    assert_match(/resume_at!/, error.message)
+    assert_match(/removed_step :deleted_without_a_trace/, error.message)
+    assert_match(/step_one, step_two, step_three/, error.message)
+  end
+
+  test "resume_at! rescues a workflow stranded by a vanished step" do
+    workflow = paused_at(ThreeStepWorkflow.create!(hero: @user), "deleted_without_a_trace")
+
+    workflow.resume_at!(:step_three)
+    speedrun_workflow(workflow)
+
+    assert_equal %i[step_three], Thread.current[:ran]
+    assert_workflow_state(workflow, :finished)
+  end
+
+  # ===========================================
+  # A step removed while an execution was parked
+  # ===========================================
+
+  test "resume! releases an execution parked on a since-removed step" do
+    workflow = WorkflowWithRemoval.create!(hero: @user)
+
+    # The old code parked here waiting for a signal; the new code has only a
+    # gravestone, so nothing can ever match.
+    workflow.step_executions.where(state: %w[scheduled waiting]).update_all(
+      state: "canceled", outcome: "canceled", canceled_at: Time.current
+    )
+    parked = workflow.step_executions.create!(
+      step_name: "parked_forever",
+      state: "waiting",
+      scheduled_for: Time.current,
+      waiting_since: Time.current
+    )
+    workflow.update!(next_step_name: "parked_forever", current_step_name: nil)
+    workflow.pause!
+
+    workflow.resume!
+
+    assert_equal "skipped", parked.reload.state
+
+    speedrun_workflow(workflow)
+
+    assert_equal %i[step_three], Thread.current[:ran]
+    assert_workflow_state(workflow, :finished)
+  end
+
+  private
+
+  # Puts the workflow in the state it would be in after pausing while pointed
+  # at the given step name, with no live execution left behind.
+  def paused_at(workflow, step_name)
+    workflow.step_executions.where(state: %w[scheduled waiting]).update_all(
+      state: "canceled", outcome: "canceled", canceled_at: Time.current
+    )
+    workflow.update!(state: "paused", next_step_name: step_name, current_step_name: nil)
+    workflow
+  end
+end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: geneva_drive
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.8.0
 platform: ruby
 authors:
 - Julik Tarkhanov
 bindir: bin
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2026-10-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -94,6 +94,7 @@ files:
 - MANUAL.md
 - README.md
 - Rakefile
+- bin/matrix
 - bin/md2html
 - bin/rails
 - bin/rubocop
@@ -121,7 +122,9 @@ files:
 - lib/geneva_drive/job_options.rb
 - lib/geneva_drive/jobs/housekeeping_job.rb
 - lib/geneva_drive/jobs/perform_step_job.rb
+- lib/geneva_drive/json_column.rb
 - lib/geneva_drive/migration_helpers.rb
+- lib/geneva_drive/removed_step_definition.rb
 - lib/geneva_drive/resumable_step_definition.rb
 - lib/geneva_drive/signal.rb
 - lib/geneva_drive/signal_matcher.rb
@@ -168,6 +171,7 @@ files:
 - test/dummy/config/initializers/assets.rb
 - test/dummy/config/initializers/content_security_policy.rb
 - test/dummy/config/initializers/filter_parameter_logging.rb
+- test/dummy/config/initializers/geneva_drive.rb
 - test/dummy/config/initializers/inflections.rb
 - test/dummy/config/locales/en.yml
 - test/dummy/config/puma.rb
@@ -182,6 +186,14 @@ files:
 - test/dummy/public/icon.png
 - test/dummy/public/icon.svg
 - test/dummy_install/config/storage.yml
+- test/dummy_install/db/migrate/20260217112949_create_geneva_drive_workflows.rb
+- test/dummy_install/db/migrate/20260217112950_create_geneva_drive_step_executions.rb
+- test/dummy_install/db/migrate/20260217112951_add_finished_at_to_geneva_drive_step_executions.rb
+- test/dummy_install/db/migrate/20260217112952_add_error_class_name_to_geneva_drive_step_executions.rb
+- test/dummy_install/db/migrate/20260217112953_add_resumable_step_support_to_geneva_drive_step_executions.rb
+- test/dummy_install/db/migrate/20260217112954_add_chained_step_executions_to_geneva_drive_step_executions.rb
+- test/dummy_install/db/schema.rb
+- test/dummy_install/log/test.log
 - test/geneva_drive_test.rb
 - test/jobs/housekeeping_job_test.rb
 - test/jobs/housekeeping_signals_test.rb
@@ -205,10 +217,12 @@ files:
 - test/workflow/pause_resume_test.rb
 - test/workflow/precondition_exception_test.rb
 - test/workflow/reattempt_on_exception_integration_test.rb
+- test/workflow/removed_step_test.rb
 - test/workflow/resumable_step_integration_test.rb
 - test/workflow/resumable_step_test.rb
 - test/workflow/resumable_without_migration_test.rb
 - test/workflow/resume_and_skip_test.rb
+- test/workflow/resume_at_test.rb
 - test/workflow/signal_consumption_test.rb
 - test/workflow/signal_delivery_test.rb
 - test/workflow/signal_durability_test.rb