geneva_drive 0.7.0 → 0.9.0

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,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: geneva_drive
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.9.0
 platform: ruby
 authors:
 - Julik Tarkhanov
@@ -94,6 +94,7 @@ files:
 - MANUAL.md
 - README.md
 - Rakefile
+- bin/matrix
 - bin/md2html
 - bin/rails
 - bin/rubocop
@@ -113,6 +114,8 @@ files:
 - lib/generators/geneva_drive/install/templates/initializer.rb.tt
 - lib/geneva_drive.rb
 - lib/geneva_drive/combined_exception_policy.rb
+- lib/geneva_drive/dispatchers/active_job_dispatcher.rb
+- lib/geneva_drive/dispatchers/sidekiq_dispatcher.rb
 - lib/geneva_drive/engine.rb
 - lib/geneva_drive/exception_policy.rb
 - lib/geneva_drive/executor.rb
@@ -121,7 +124,12 @@ 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/jobs/sidekiq_housekeeping_job.rb
+- lib/geneva_drive/jobs/sidekiq_perform_step_job.rb
+- lib/geneva_drive/jobs/step_execution_lookup.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,12 +176,52 @@ 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
 - test/dummy/config/routes.rb
 - test/dummy/config/storage.yml
 - test/dummy/db/migrate/20241217000000_create_users.rb
+- test/dummy/db/mysql/schema-8.1.rb
+- test/dummy/db/postgres/schema-8.1.rb
+- test/dummy/db/sqlite/schema-7.2.rb
+- test/dummy/db/sqlite/schema-8.0.rb
+- test/dummy/db/sqlite/schema-8.1.rb
+- test/dummy/db/sqlite/test.sqlite3
+- test/dummy/db/sqlite/test.sqlite3-0
+- test/dummy/db/sqlite/test.sqlite3-1
+- test/dummy/db/sqlite/test.sqlite3-2
+- test/dummy/db/sqlite/test.sqlite3-3
+- test/dummy/db/sqlite/test.sqlite3-4
+- test/dummy/db/sqlite/test.sqlite3-5
+- test/dummy/db/sqlite/test.sqlite3-6
+- test/dummy/db/sqlite/test.sqlite3-7
+- test/dummy/db/sqlite/test.sqlite3-8
+- test/dummy/db/sqlite/test.sqlite3-9
+- test/dummy/db/sqlite/test.sqlite3_0
+- test/dummy/db/sqlite/test.sqlite3_1
+- test/dummy/db/sqlite/test.sqlite3_2
+- test/dummy/db/sqlite/test.sqlite3_3
+- test/dummy/db/sqlite/test.sqlite3_4
+- test/dummy/db/sqlite/test.sqlite3_5
+- test/dummy/db/sqlite/test.sqlite3_6
+- test/dummy/db/sqlite/test.sqlite3_7
+- test/dummy/db/sqlite/test.sqlite3_8
+- test/dummy/db/sqlite/test.sqlite3_9
+- test/dummy/db/sqlite3/schema-7.2.rb
+- test/dummy/db/sqlite3/schema-8.1.rb
+- test/dummy/db/sqlite3/test.sqlite3
+- test/dummy/db/sqlite3/test.sqlite3_0
+- test/dummy/db/sqlite3/test.sqlite3_1
+- test/dummy/db/sqlite3/test.sqlite3_2
+- test/dummy/db/sqlite3/test.sqlite3_3
+- test/dummy/db/sqlite3/test.sqlite3_4
+- test/dummy/db/sqlite3/test.sqlite3_5
+- test/dummy/db/sqlite3/test.sqlite3_6
+- test/dummy/db/sqlite3/test.sqlite3_7
+- test/dummy/db/sqlite3/test.sqlite3_8
+- test/dummy/db/sqlite3/test.sqlite3_9
 - test/dummy/public/400.html
 - test/dummy/public/404.html
 - test/dummy/public/406-unsupported-browser.html
@@ -182,12 +230,23 @@ 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/generators/install_generator_test.rb
 - test/geneva_drive_test.rb
 - test/jobs/housekeeping_job_test.rb
 - test/jobs/housekeeping_signals_test.rb
 - test/jobs/perform_step_job_double_deferral_test.rb
 - test/jobs/perform_step_job_test.rb
 - test/migration_helpers_test.rb
+- test/sidekiq/sidekiq_dispatcher_test.rb
+- test/sidekiq/sidekiq_redis_test.rb
 - test/step_execution/metadata_accessor_test.rb
 - test/test_helper.rb
 - test/test_helper_test.rb
@@ -205,10 +264,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