geneva_drive 0.6.0 → 0.7.0

data/test/workflow/signal_consumption_test.rb

@@ -0,0 +1,397 @@
+# frozen_string_literal: true
+
+require "test_helper"
+
+# Claim and consumption accounting. A signal stays claimed - and therefore
+# attachable - while any attached execution chain is unresolved, and flips to
+# consumed when the last one resolves cleanly. With a single claimant that is
+# the same moment as the step completing; the counters are what make a
+# one-to-many dispatch legible.
+class SignalConsumptionTest < ActiveSupport::TestCase
+  include GenevaDrive::TestHelpers
+
+  class InvoiceWorkflow < GenevaDrive::Workflow
+    step :await_payment, wait_for: :payment_confirmed do
+      raise "gateway unavailable" unless Thread.current[:consumption_healed]
+    end
+
+    step :issue_receipt do
+    end
+  end
+
+  class SkippingWorkflow < GenevaDrive::Workflow
+    step :await_payment, wait_for: :payment_confirmed do
+      skip!
+    end
+  end
+
+  class TwoWaitersWorkflow < GenevaDrive::Workflow
+    step :first_wait, wait_for: :ping do
+    end
+
+    step :second_wait, wait_for: :ping do
+    end
+  end
+
+  class ResumableWaitWorkflow < GenevaDrive::Workflow
+    resumable_step :process_items, wait_for: :batch_ready, max_iterations: 2 do |iter|
+      iter.iterate_over([1, 2, 3, 4]) { |item| }
+    end
+  end
+
+  class SkippableWaitWorkflow < GenevaDrive::Workflow
+    step :await_payment, wait_for: :payment_confirmed, skip_if: -> { Thread.current[:consumption_presigned] } do
+    end
+
+    step :await_payment_again, wait_for: :payment_confirmed do
+    end
+  end
+
+  class FailingWaitWorkflow < GenevaDrive::Workflow
+    step :await_payment, wait_for: :payment_confirmed do
+      raise "gateway unavailable"
+    end
+
+    step :issue_receipt do
+    end
+  end
+
+  setup do
+    @user = create_user
+    Thread.current[:consumption_healed] = true
+    Thread.current[:consumption_presigned] = nil
+  end
+
+  teardown do
+    Thread.current[:consumption_healed] = nil
+    Thread.current[:consumption_presigned] = nil
+  end
+
+  # Builds a step execution attached to a signal, the way dispatch or the gate
+  # would. Used to stage attachment shapes that only the DAG scheduler can
+  # produce for real.
+  def attach_execution(workflow, signal, step_name:, state:, outcome: nil)
+    signal.claim!
+    workflow.step_executions.create!(
+      step_name: step_name,
+      state: state,
+      scheduled_for: Time.current,
+      waiting_since: (state == "waiting") ? Time.current : nil,
+      outcome: outcome,
+      signal_id: signal.id
+    )
+  end
+
+  test "a clean single-claimant run counts one claim and one consumption" do
+    workflow = InvoiceWorkflow.create!(hero: @user)
+    signal = workflow.signal!(:payment_confirmed)
+
+    assert_equal 0, signal.claimed
+    assert_equal 0, signal.consumed
+
+    perform_next_step(workflow)
+    signal.reload
+
+    assert_equal "consumed", signal.state
+    assert_equal 1, signal.claimed
+    assert_equal 1, signal.consumed
+    assert_not_nil signal.claimed_at
+    assert_not_nil signal.consumed_at
+  end
+
+  test "a skipping step consumes its signal too" do
+    workflow = SkippingWorkflow.create!(hero: @user)
+    signal = workflow.signal!(:payment_confirmed)
+
+    perform_next_step(workflow)
+    signal.reload
+
+    assert_equal "consumed", signal.state
+    assert_equal 1, signal.consumed
+  end
+
+  test "a retry re-attaching counts a second claim but only one consumption" do
+    Thread.current[:consumption_healed] = false
+    workflow = InvoiceWorkflow.create!(hero: @user)
+    signal = workflow.signal!(:payment_confirmed)
+
+    assert_raises(RuntimeError) { perform_next_step(workflow) }
+    signal.reload
+
+    assert_equal "claimed", signal.state
+    assert_equal 1, signal.claimed
+    assert_equal 0, signal.consumed
+    first_claimed_at = signal.claimed_at
+
+    Thread.current[:consumption_healed] = true
+    workflow.resume!
+    speedrun_workflow(workflow)
+    signal.reload
+
+    assert_equal "consumed", signal.state
+    assert_equal 2, signal.claimed
+    assert_equal 1, signal.consumed
+    # claimed_at keeps meaning "when this event started being handled"
+    assert_equal first_claimed_at.to_i, signal.claimed_at.to_i
+  end
+
+  test "successor executions carry the pin over without counting a new claim" do
+    workflow = ResumableWaitWorkflow.create!(hero: @user)
+    signal = workflow.signal!(:batch_ready, payload: {batch_id: "b1"})
+
+    run_iterations(workflow, count: 2)
+    assert_equal 1, signal.reload.claimed
+    assert_equal 0, signal.consumed
+
+    speedrun_current_step(workflow)
+    signal.reload
+
+    assert_operator workflow.step_executions.where(signal_id: signal.id).count, :>, 1
+    assert_equal 1, signal.claimed
+    assert_equal 1, signal.consumed
+    assert_equal "consumed", signal.state
+  end
+
+  test "the signal stays claimed while another attached execution is still active" do
+    workflow = TwoWaitersWorkflow.create!(hero: @user)
+    workflow.current_execution.execute!
+    assert_waiting_for_signal(workflow, :ping)
+
+    signal = workflow.signal!(:ping)
+    assert_equal 1, signal.reload.claimed
+
+    # Stage a second attached execution, as a DAG salvo would produce
+    attach_execution(workflow, signal, step_name: "second_wait", state: "waiting")
+    assert_equal 2, signal.reload.claimed
+
+    perform_next_step(workflow)
+    signal.reload
+
+    assert_equal "claimed", signal.state
+    assert_equal 1, signal.consumed
+    assert_nil signal.consumed_at
+  end
+
+  test "the flip happens when the last attached chain resolves" do
+    workflow = TwoWaitersWorkflow.create!(hero: @user)
+    signal = workflow.signal!(:ping)
+
+    first = attach_execution(workflow, signal, step_name: "first_wait", state: "waiting")
+    second = attach_execution(workflow, signal, step_name: "second_wait", state: "waiting")
+    assert_equal 2, signal.reload.claimed
+
+    first.update!(state: "completed", outcome: "success", completed_at: Time.current)
+    signal.record_consumption!
+
+    assert_equal "claimed", signal.state
+    assert_equal 1, signal.consumed
+
+    second.update!(state: "skipped", outcome: "skipped", skipped_at: Time.current)
+    signal.record_consumption!
+
+    assert_equal "consumed", signal.state
+    assert_equal 2, signal.consumed
+    assert_not_nil signal.consumed_at
+  end
+
+  test "claimed? and consumed? read the counters, not the lifecycle state" do
+    workflow = TwoWaitersWorkflow.create!(hero: @user)
+    signal = workflow.signal!(:ping)
+
+    assert_equal "pending", signal.state
+    assert_not signal.claimed?
+    assert_not signal.consumed?
+
+    execution = attach_execution(workflow, signal, step_name: "first_wait", state: "waiting")
+    signal.reload
+
+    assert_equal "claimed", signal.state
+    assert signal.claimed?
+    assert_not signal.consumed?
+
+    # A second chain keeps the state at claimed, but the first clean
+    # resolution already makes consumed? true
+    second = attach_execution(workflow, signal, step_name: "second_wait", state: "waiting")
+    execution.update!(state: "completed", outcome: "success")
+    signal.record_consumption!
+
+    assert_equal "claimed", signal.state
+    assert signal.consumed?
+    assert_equal 1, signal.consumed
+
+    second.update!(state: "completed", outcome: "success")
+    signal.record_consumption!
+
+    assert_equal "consumed", signal.state
+    assert signal.claimed?
+    assert signal.consumed?
+  end
+
+  test "the state enum generates neither predicates nor scopes" do
+    assert_not GenevaDrive::Signal.new.respond_to?(:pending?)
+    assert_not GenevaDrive::Signal.respond_to?(:pending)
+
+    # The names the enum would have taken belong to the counters
+    assert_equal 0, GenevaDrive::Signal.new.claimed
+    assert_equal 0, GenevaDrive::Signal.new.consumed
+  end
+
+  # === Skips settle the signal they were delivered ===
+
+  test "skip_if firing at wake consumes the signal that woke the step" do
+    workflow = SkippableWaitWorkflow.create!(hero: @user)
+    workflow.current_execution.execute!
+    assert_waiting_for_signal(workflow, :payment_confirmed)
+
+    # The condition flips while the step sits parked, then the event arrives
+    Thread.current[:consumption_presigned] = true
+    signal = workflow.signal!(:payment_confirmed)
+    assert_equal "claimed", signal.reload.state
+    assert_equal signal.id, workflow.reload.current_execution.signal_id
+
+    perform_next_step(workflow)
+    signal.reload
+
+    assert_step_executed(workflow, :await_payment, state: "skipped")
+    assert_equal "consumed", signal.state
+    assert_equal 1, signal.claimed
+    assert_equal 1, signal.consumed
+    assert_not_nil signal.consumed_at
+  end
+
+  test "a step skipped at wake does not hand its stale event to the next waiter" do
+    workflow = SkippableWaitWorkflow.create!(hero: @user)
+    workflow.current_execution.execute!
+
+    Thread.current[:consumption_presigned] = true
+    signal = workflow.signal!(:payment_confirmed)
+    perform_next_step(workflow)
+
+    # The second step waits on the same name and must park: the only event so
+    # far was settled by the skip
+    workflow.reload.current_execution.execute!
+
+    assert_waiting_for_signal(workflow, :payment_confirmed)
+    assert_nil workflow.reload.current_execution.signal_id
+    assert_equal 1, signal.reload.consumed
+
+    # ... and a fresh event moves it along
+    fresh = workflow.signal!(:payment_confirmed)
+    perform_next_step(workflow)
+
+    assert_equal "consumed", fresh.reload.state
+    assert_equal "finished", workflow.reload.state
+  end
+
+  test "external skip! settles the signal of a dispatched execution" do
+    workflow = SkippableWaitWorkflow.create!(hero: @user)
+    workflow.current_execution.execute!
+    signal = workflow.signal!(:payment_confirmed)
+
+    # Dispatched, attached, but its job never ran
+    assert_equal "scheduled", workflow.reload.current_execution.state
+    workflow.skip!
+    signal.reload
+
+    assert_step_executed(workflow, :await_payment, state: "skipped")
+    assert_equal "consumed", signal.state
+    assert_equal 1, signal.consumed
+  end
+
+  test "external skip! on a paused workflow settles the claim its failed step held" do
+    workflow = FailingWaitWorkflow.create!(hero: @user)
+    signal = workflow.signal!(:payment_confirmed)
+
+    assert_raises(RuntimeError) { perform_next_step(workflow) }
+    assert_equal "paused", workflow.reload.state
+    assert_equal "claimed", signal.reload.state
+    assert_equal 1, signal.claimed
+    assert_equal 0, signal.consumed
+
+    workflow.skip!
+    signal.reload
+
+    assert_equal "consumed", signal.state
+    assert_equal 1, signal.consumed
+    assert_not_nil signal.consumed_at
+    assert_equal "issue_receipt", workflow.reload.next_step_name
+    assert_equal "scheduled", workflow.current_execution.state
+  end
+
+  test "skipping at park time leaves a buffered signal pending" do
+    Thread.current[:consumption_presigned] = true
+    workflow = SkippableWaitWorkflow.create!(hero: @user)
+    buffered = workflow.signal!(:unrelated_event)
+
+    # The step never attaches - skip_if is evaluated before the gate
+    perform_next_step(workflow)
+
+    assert_step_executed(workflow, :await_payment, state: "skipped")
+    buffered.reload
+    assert_equal "pending", buffered.state
+    assert_equal 0, buffered.claimed
+    assert_equal 0, buffered.consumed
+  end
+
+  test "external skip! of an unattached parked execution touches no buffered signal" do
+    workflow = SkippableWaitWorkflow.create!(hero: @user)
+    workflow.current_execution.execute!
+    assert_waiting_for_signal(workflow, :payment_confirmed)
+    buffered = workflow.signal!(:unrelated_event)
+
+    workflow.skip!
+
+    buffered.reload
+    assert_equal "pending", buffered.state
+    assert_equal 0, buffered.consumed
+  end
+
+  test "a signal with no attachments is vacuously resolved" do
+    workflow = TwoWaitersWorkflow.create!(hero: @user)
+
+    assert workflow.signal!(:ping).fully_resolved?
+  end
+
+  test "an unresolved chain keeps the signal from being fully resolved" do
+    workflow = TwoWaitersWorkflow.create!(hero: @user)
+    signal = workflow.signal!(:ping)
+    # Free up the one-active slot so each staged state can occupy it in turn
+    workflow.step_executions.update_all(state: "canceled", outcome: "canceled")
+
+    %w[waiting scheduled in_progress].each_with_index do |state, index|
+      execution = attach_execution(workflow, signal, step_name: "node_#{index}", state: state)
+      assert_not signal.fully_resolved?, "expected #{state} to count as unresolved"
+      execution.update!(state: "completed", outcome: "success")
+    end
+
+    assert signal.fully_resolved?
+  end
+
+  test "a chain whose latest execution failed or was canceled keeps the signal claimed" do
+    workflow = TwoWaitersWorkflow.create!(hero: @user)
+    signal = workflow.signal!(:ping)
+    execution = attach_execution(workflow, signal, step_name: "first_wait", state: "failed", outcome: "failed")
+
+    assert_not signal.fully_resolved?
+
+    execution.update!(state: "canceled", outcome: "canceled")
+    assert_not signal.fully_resolved?
+
+    execution.update!(state: "completed", outcome: "success")
+    assert signal.fully_resolved?
+  end
+
+  test "only the latest execution of a chain decides whether it resolved" do
+    workflow = TwoWaitersWorkflow.create!(hero: @user)
+    signal = workflow.signal!(:ping)
+
+    attach_execution(workflow, signal, step_name: "first_wait", state: "completed", outcome: "continued")
+    attach_execution(workflow, signal, step_name: "first_wait", state: "completed", outcome: "reattempted")
+
+    assert_not signal.fully_resolved?
+
+    attach_execution(workflow, signal, step_name: "first_wait", state: "completed", outcome: "success")
+
+    assert signal.fully_resolved?
+  end
+end

data/test/workflow/signal_delivery_test.rb

@@ -0,0 +1,255 @@
+# frozen_string_literal: true
+
+require "test_helper"
+
+# The sender side of the rendezvous: Workflow#signal! and the Signal record
+# itself. The receiver side (gate, park, wake) lives in
+# signal_rendezvous_test.rb.
+class SignalDeliveryTest < ActiveSupport::TestCase
+  include GenevaDrive::TestHelpers
+
+  class InvoiceWorkflow < GenevaDrive::Workflow
+    step :await_payment, wait_for: :payment_confirmed do
+      Thread.current[:signal_delivery_amount] = received_signal.payload[:amount_cents]
+    end
+
+    step :issue_receipt do
+    end
+  end
+
+  class PlainWorkflow < GenevaDrive::Workflow
+    step :only_step do
+    end
+  end
+
+  setup do
+    @user = create_user
+    Thread.current[:signal_delivery_amount] = nil
+  end
+
+  teardown do
+    Thread.current[:signal_delivery_amount] = nil
+  end
+
+  test "signal! persists a pending signal" do
+    workflow = PlainWorkflow.create!(hero: @user)
+
+    signal = workflow.signal!(:something_happened, payload: {order_id: 42})
+
+    assert signal.persisted?
+    assert_equal "something_happened", signal.name
+    assert_equal "pending", signal.state
+    assert_nil signal.claimed_at
+    assert_nil signal.consumed_at
+    assert_not signal.duplicate_delivery?
+    assert_equal workflow.id, signal.workflow_id
+  end
+
+  test "payload comes back with indifferent access" do
+    workflow = PlainWorkflow.create!(hero: @user)
+
+    workflow.signal!(:webhook, payload: {"order_id" => 42, :amount_cents => 100})
+    signal = workflow.signals.last.reload
+
+    assert_equal 42, signal.payload[:order_id]
+    assert_equal 42, signal.payload["order_id"]
+    assert_equal 100, signal.payload[:amount_cents]
+    assert_equal 100, signal.payload["amount_cents"]
+  end
+
+  test "payload round-trips types through ActiveJob serialization" do
+    workflow = PlainWorkflow.create!(hero: @user)
+    moment = Time.current.change(usec: 0)
+
+    workflow.signal!(:webhook, payload: {at: moment, hero: @user})
+    signal = workflow.signals.last.reload
+
+    assert_equal moment, signal.payload[:at]
+    assert_equal @user, signal.payload[:hero]
+  end
+
+  test "non-hash payloads are returned as-is" do
+    workflow = PlainWorkflow.create!(hero: @user)
+
+    workflow.signal!(:webhook, payload: "just a string")
+
+    assert_equal "just a string", workflow.signals.last.reload.payload
+  end
+
+  test "an empty payload is the default" do
+    workflow = PlainWorkflow.create!(hero: @user)
+
+    signal = workflow.signal!(:webhook)
+
+    assert_equal({}, signal.reload.payload)
+  end
+
+  test "signal! requires a name" do
+    workflow = PlainWorkflow.create!(hero: @user)
+
+    assert_raises(ArgumentError) { workflow.signal!(nil) }
+    assert_raises(ArgumentError) { workflow.signal!("") }
+  end
+
+  test "signal! rejects unknown options so the keyword surface stays usable" do
+    workflow = PlainWorkflow.create!(hero: @user)
+
+    error = assert_raises(ArgumentError) { workflow.signal!(:webhook, timeout: 5.minutes) }
+    assert_match(/timeout/, error.message)
+  end
+
+  test "an oversized payload raises before anything is persisted" do
+    workflow = PlainWorkflow.create!(hero: @user)
+    original = GenevaDrive.max_signal_payload_size
+    GenevaDrive.max_signal_payload_size = 64
+
+    error = assert_raises(GenevaDrive::SignalPayloadTooLargeError) do
+      workflow.signal!(:webhook, payload: {blob: "x" * 1024})
+    end
+
+    assert_match(/max_signal_payload_size/, error.message)
+    assert_equal 0, workflow.signals.count
+  ensure
+    GenevaDrive.max_signal_payload_size = original
+  end
+
+  test "the payload bound can be disabled" do
+    workflow = PlainWorkflow.create!(hero: @user)
+    original = GenevaDrive.max_signal_payload_size
+    GenevaDrive.max_signal_payload_size = nil
+
+    signal = workflow.signal!(:webhook, payload: {blob: "x" * 1024})
+
+    assert signal.persisted?
+  ensure
+    GenevaDrive.max_signal_payload_size = original
+  end
+
+  test "redelivery with the same idempotency key returns the original row" do
+    workflow = PlainWorkflow.create!(hero: @user)
+
+    first = workflow.signal!(:webhook, payload: {n: 1}, idempotency_key: "evt_1")
+    second = workflow.signal!(:webhook, payload: {n: 2}, idempotency_key: "evt_1")
+
+    assert_equal first.id, second.id
+    assert second.duplicate_delivery?
+    assert_not first.duplicate_delivery?
+    assert_equal 1, workflow.signals.count
+    # The first payload wins - the duplicate is a no-op, not an update
+    assert_equal 1, second.payload[:n]
+  end
+
+  test "the same idempotency key under a different name is a different signal" do
+    workflow = PlainWorkflow.create!(hero: @user)
+
+    workflow.signal!(:webhook_a, idempotency_key: "evt_1")
+    workflow.signal!(:webhook_b, idempotency_key: "evt_1")
+
+    assert_equal 2, workflow.signals.count
+  end
+
+  test "the same idempotency key on a different workflow is a different signal" do
+    other_user = create_user(email: "other@example.com")
+    workflow = PlainWorkflow.create!(hero: @user)
+    other_workflow = PlainWorkflow.create!(hero: other_user)
+
+    workflow.signal!(:webhook, idempotency_key: "evt_1")
+    other_workflow.signal!(:webhook, idempotency_key: "evt_1")
+
+    assert_equal 1, workflow.signals.count
+    assert_equal 1, other_workflow.signals.count
+  end
+
+  test "signals without an idempotency key never deduplicate" do
+    workflow = PlainWorkflow.create!(hero: @user)
+
+    workflow.signal!(:webhook)
+    workflow.signal!(:webhook)
+
+    assert_equal 2, workflow.signals.count
+  end
+
+  test "signal! on a finished workflow raises WorkflowNotOngoing" do
+    workflow = PlainWorkflow.create!(hero: @user)
+    speedrun_workflow(workflow)
+    assert_equal "finished", workflow.state
+
+    error = assert_raises(GenevaDrive::WorkflowNotOngoing) { workflow.signal!(:webhook) }
+
+    assert_match(/finished workflow/, error.message)
+    assert_equal 0, workflow.signals.count
+  end
+
+  test "signal! on a canceled workflow raises WorkflowNotOngoing" do
+    workflow = PlainWorkflow.create!(hero: @user)
+    workflow.cancel!
+
+    assert_raises(GenevaDrive::WorkflowNotOngoing) { workflow.signal!(:webhook) }
+  end
+
+  test "redelivery of the event that finished the workflow is a no-op" do
+    workflow = InvoiceWorkflow.create!(hero: @user)
+    workflow.signal!(:payment_confirmed, payload: {amount_cents: 500}, idempotency_key: "evt_1")
+    speedrun_workflow(workflow)
+    assert_equal "finished", workflow.state
+
+    redelivered = workflow.signal!(:payment_confirmed, payload: {amount_cents: 500}, idempotency_key: "evt_1")
+
+    assert redelivered.duplicate_delivery?
+    assert_equal 1, workflow.signals.count
+  end
+
+  test "a new event on a finished workflow still raises even when other signals exist" do
+    workflow = InvoiceWorkflow.create!(hero: @user)
+    workflow.signal!(:payment_confirmed, idempotency_key: "evt_1")
+    speedrun_workflow(workflow)
+
+    assert_raises(GenevaDrive::WorkflowNotOngoing) do
+      workflow.signal!(:payment_confirmed, idempotency_key: "evt_2")
+    end
+  end
+
+  test "signal! survives an enclosing transaction thanks to the savepoint" do
+    workflow = PlainWorkflow.create!(hero: @user)
+    workflow.signal!(:webhook, idempotency_key: "evt_1")
+
+    GenevaDrive::Workflow.transaction do
+      duplicate = workflow.signal!(:webhook, idempotency_key: "evt_1")
+      assert duplicate.duplicate_delivery?
+
+      # The enclosing transaction is still usable
+      workflow.signal!(:other_webhook)
+    end
+
+    assert_equal 2, workflow.signals.count
+  end
+
+  test "signals can still be recorded for a workflow whose class was removed" do
+    workflow = InvoiceWorkflow.create!(hero: @user)
+    perform_next_step(workflow)
+    workflow.current_execution.execute!
+    assert_waiting_for_signal(workflow, :payment_confirmed)
+
+    # The class is gone: STI resolution falls back to the base Workflow, which
+    # has no step definitions - so no matcher can be resolved and nothing is
+    # woken, but the row is still written.
+    GenevaDrive::Workflow.where(id: workflow.id).update_all(type: "DeletedInvoiceWorkflow")
+    orphan = GenevaDrive::Workflow.find(workflow.id)
+    assert_equal GenevaDrive::Workflow, orphan.class
+
+    signal = orphan.signal!(:payment_confirmed)
+
+    assert signal.persisted?
+    assert_equal "pending", signal.reload.state
+    assert_equal "waiting", orphan.current_execution.state
+  end
+
+  test "signals are deleted with their workflow" do
+    workflow = PlainWorkflow.create!(hero: @user)
+    workflow.signal!(:webhook)
+
+    assert_difference -> { GenevaDrive::Signal.count }, -1 do
+      workflow.destroy!
+    end
+  end
+end