geneva_drive 0.6.0 → 0.8.0

data/lib/geneva_drive/workflow.rb

@@ -43,6 +43,11 @@ class GenevaDrive::Workflow < ActiveRecord::Base
     foreign_key: :workflow_id,
     inverse_of: :workflow,
     dependent: :delete_all
+  has_many :signals,
+    class_name: "GenevaDrive::Signal",
+    foreign_key: :workflow_id,
+    inverse_of: :workflow,
+    dependent: :delete_all
 
   # Class-inheritable attributes for DSL
   class_attribute :_step_definitions, instance_writer: false, default: []
@@ -201,6 +206,92 @@ class GenevaDrive::Workflow < ActiveRecord::Base
       step_def
     end
 
+    # Marks a step as removed, leaving a gravestone in the position the step
+    # used to occupy.
+    #
+    # Deleting a `step` outright is unsafe while workflows are in flight.
+    # Executions scheduled under the old name find no definition when their
+    # job runs, and the workflow pauses with {StepNotDefinedError} - stuck
+    # until an operator intervenes. The gem cannot recover from this on its
+    # own: it knows the step is gone, but not whether the work it did still
+    # needs doing, and not which of the remaining steps would have run had it
+    # executed. Only the author of the removal knows that.
+    #
+    # `removed_step` is how that knowledge gets written down. Declaring it
+    # where the step used to be says "this step no longer needs to happen,
+    # carry on past it", and the gem can then act without guessing:
+    #
+    # - Executions already scheduled for the name resolve, are skipped, and
+    #   the workflow proceeds to the next runnable step.
+    # - Scheduling never spools a new execution for the name again.
+    # - `before_step:` / `after_step:` references to it keep working.
+    #
+    # Ship the `removed_step`, let in-flight workflows drain past it, then
+    # delete the line once {.removed_steps_in_flight} comes back empty.
+    #
+    # A removed step takes a name and nothing else. There is nothing to
+    # configure about a step that does not run.
+    #
+    # @param name [String, Symbol] the name of the step that was removed
+    # @return [RemovedStepDefinition] the gravestone
+    #
+    # @example Taking a step out of a live workflow
+    #   class PaymentWorkflow < GenevaDrive::Workflow
+    #     step :authorize do
+    #       # ...
+    #     end
+    #
+    #     removed_step :capture_payment
+    #
+    #     step :send_receipt do
+    #       # ...
+    #     end
+    #   end
+    def removed_step(name)
+      raise ArgumentError, "removed_step requires a step name" if name.nil?
+
+      caller_loc = caller_locations(1, 1).first
+      call_location = caller_loc ? [caller_loc.path, caller_loc.lineno] : nil
+
+      step_name = prepare_step_registration!(name, {})
+
+      step_def = GenevaDrive::RemovedStepDefinition.new(
+        name: step_name,
+        call_location: call_location
+      )
+
+      _step_definitions << step_def
+
+      step_def
+    end
+
+    # Returns the names of this workflow's removed steps that step execution
+    # rows still reference, so a `removed_step` gravestone is only deleted
+    # once nothing can land on it any more.
+    #
+    # Each name maps to the number of rows still referencing it. An empty
+    # hash means every in-flight workflow has drained past the removal and
+    # the `removed_step` lines can go.
+    #
+    # Rows belonging to finished and canceled workflows are ignored - they
+    # will never execute again.
+    #
+    # @return [Hash{String => Integer}] removed step names to referencing row counts
+    #
+    # @example
+    #   PaymentWorkflow.removed_steps_in_flight
+    #   # => {"capture_payment" => 3}
+    def removed_steps_in_flight
+      removed_names = steps.removed.map(&:name)
+      return {} if removed_names.empty?
+
+      GenevaDrive::StepExecution
+        .where(step_name: removed_names)
+        .where(workflow_id: where.not(state: %w[finished canceled]).select(:id))
+        .group(:step_name)
+        .count
+    end
+
     # Defines a blanket cancellation condition for the workflow.
     # Checked before every step execution.
     #
@@ -523,7 +614,14 @@ class GenevaDrive::Workflow < ActiveRecord::Base
 
     # A scheduled execution preserved by pause! takes precedence - re-enqueue it
     scheduled_execution = current_execution
-    return enqueue_scheduled_execution(scheduled_execution) if scheduled_execution
+    if scheduled_execution
+      # A parked execution is not re-enqueued: it is waiting for an event, not
+      # for a clock. Re-run the rendezvous instead, which delivers any signal
+      # that arrived while the workflow was paused.
+      return rendezvous_waiting_execution!(scheduled_execution) if scheduled_execution.waiting?
+
+      return enqueue_scheduled_execution(scheduled_execution)
+    end
 
     # Resumable-step continuations need the cursor/continues_from_id columns
     if GenevaDrive::StepExecution.resumable_columns?
@@ -554,15 +652,276 @@ class GenevaDrive::Workflow < ActiveRecord::Base
 
     # No scheduled execution exists - create one for the next step
     step_def = steps.named(next_step_name)
+
+    # The step this workflow is pointed at can be gone from the code - that is
+    # what paused it in the first place if it paused with StepNotDefinedError.
+    # Say so plainly instead of dying on nil deeper in create_step_execution,
+    # and name the way out.
+    unless step_def
+      raise GenevaDrive::StepNotDefinedError.new(
+        "Cannot resume #{self.class.name} ##{id}: step '#{next_step_name}' is no longer defined in " \
+        "#{self.class.name}. Pick the step to continue from with resume_at!(:step_name) - the steps " \
+        "still defined are #{steps.runnable.map(&:name).join(", ")} - or cancel! the workflow. To stop " \
+        "future removals from stranding workflows this way, leave a removed_step :#{next_step_name} " \
+        "gravestone in place of the deleted step.",
+        step_execution: nil,
+        workflow: self
+      )
+    end
+
     create_step_execution(step_def, wait: nil)
   end
 
+  # Resumes a paused workflow at a specific step, instead of at whatever step
+  # it was pointed at when it paused.
+  #
+  # This is the operator's escape hatch for a workflow stranded on a step that
+  # no longer exists - the step was deleted without leaving a
+  # {GenevaDrive::Workflow.removed_step} gravestone, so the workflow paused
+  # with {StepNotDefinedError} and plain {#resume!} has nowhere to go.
+  #
+  # Where to land is deliberately a human decision. A deleted step's position
+  # in the sequence says nothing about whether the steps that follow it were
+  # ever meant to run: a `capture_payment` that normally ends the workflow by
+  # calling `finished!` sits directly before `refund`, and nothing in the
+  # database distinguishes "carry on" from "stop here". Only the person who
+  # removed the step knows which, so this method asks them.
+  #
+  # Any stray scheduled execution is canceled first, so the workflow continues
+  # from the named step and nowhere else.
+  #
+  # @param step_name [String, Symbol] the step to continue from
+  # @return [StepExecution] the created step execution
+  # @raise [InvalidStateError] if the workflow is not paused
+  # @raise [StepNotDefinedError] if the named step is not defined, or is a removed_step
+  #
+  # @example Continue a stranded workflow past a deleted step
+  #   workflow = GenevaDrive::Workflow.find(id)
+  #   workflow.resume_at!(:send_receipt)
+  def resume_at!(step_name)
+    raise GenevaDrive::InvalidStateError, "Cannot resume a #{state} workflow" unless state == "paused"
+
+    step_def = steps.named(step_name.to_s)
+
+    if step_def.nil? || step_def.removed?
+      reason = step_def ? "a removed_step" : "not defined"
+      raise GenevaDrive::StepNotDefinedError.new(
+        "Cannot resume #{self.class.name} ##{id} at '#{step_name}': that step is #{reason} in " \
+        "#{self.class.name}. The steps it can be resumed at are #{steps.runnable.map(&:name).join(", ")}.",
+        step_execution: nil,
+        workflow: self
+      )
+    end
+
+    logger.info("Resuming paused workflow at step #{step_def.name.inspect} (was pointed at #{next_step_name.inspect})")
+
+    with_lock do
+      update!(state: "ready", current_step_name: nil, transitioned_at: nil)
+    end
+
+    create_step_execution(step_def, wait: nil)
+  end
+
+  # Delivers an external event to this workflow.
+  #
+  # The signal row is persisted first and dispatched second, which is what
+  # makes arrival order irrelevant: a signal that lands before the waiting
+  # step's execution even exists simply sits in the table until that step's
+  # gate picks it up, and a signal that lands while a step is already parked
+  # wakes it immediately.
+  #
+  # Pass an +idempotency_key+ (a webhook's event id, typically) to make
+  # redelivery a no-op: the second call returns the row the first one wrote,
+  # flagged {GenevaDrive::Signal#duplicate_delivery?}, without dispatching.
+  #
+  # On a paused workflow the row is persisted but not dispatched - waking a
+  # step while the workflow is paused would only get its execution canceled.
+  # {#resume!} performs the rendezvous instead.
+  #
+  # @param signal_name [Symbol, String] the event name
+  # @param payload [Object] data describing the event, serialized through ActiveJob
+  # @param idempotency_key [String, nil] deduplication key, scoped to (workflow, name)
+  # @return [GenevaDrive::Signal] the persisted signal
+  # @raise [ArgumentError] if the signal name is blank
+  # @raise [WorkflowNotOngoing] if the workflow is finished or canceled and this is a new event
+  # @raise [SignalPayloadTooLargeError] if the payload exceeds GenevaDrive.max_signal_payload_size
+  #
+  # @example Deliver a webhook event
+  #   workflow = OrderFulfillmentWorkflow.ongoing.for_hero(order).first
+  #   workflow.signal!(:payment_confirmed,
+  #     payload: {amount_cents: 12_500},
+  #     idempotency_key: event["id"])
+  def signal!(signal_name, payload: {}, idempotency_key: nil, **unknown_options)
+    if unknown_options.any?
+      raise ArgumentError,
+        "Unknown options passed to signal!: #{unknown_options.keys.join(", ")}"
+    end
+
+    if signal_name.blank?
+      raise ArgumentError, "signal! requires a signal name"
+    end
+
+    name = signal_name.to_s
+    dedup_key = idempotency_key&.to_s
+
+    # Serialize (and bound) before anything is persisted.
+    serialized_payload = GenevaDrive::Signal.serialize_payload(payload)
+
+    signal = nil
+    duplicate = false
+
+    # One transaction covers the lot: the INSERT, the waiting-execution scan,
+    # and every attach, flip and counter bump. Taking the lock before writing
+    # anything is what makes delivery all-or-nothing - insert first and
+    # dispatch second, and a crash in between would leave a pending signal
+    # sitting next to a waiting execution with nothing left to introduce them.
+    with_lock do
+      # with_lock reloads; the terminal check belongs inside it
+      unless ongoing?
+        existing = dedup_key && signals.find_by(name: name, idempotency_key: dedup_key)
+        unless existing
+          raise GenevaDrive::WorkflowNotOngoing,
+            "Cannot deliver signal #{name.inspect} to a #{state} workflow"
+        end
+
+        logger.info("Signal #{name.inspect} redelivered to #{state} workflow, returning existing row")
+        signal = existing
+        duplicate = true
+        next
+      end
+
+      begin
+        # A savepoint so that hitting the dedup index does not poison the
+        # transaction - the caller's, if they had one open, or ours.
+        transaction(requires_new: true) do
+          record = signals.new(name: name, idempotency_key: dedup_key, state: "pending")
+          record[:payload] = serialized_payload
+          record.save!
+          signal = record
+        end
+      rescue ActiveRecord::RecordNotUnique
+        signal = signals.find_by!(name: name, idempotency_key: dedup_key)
+        logger.info("Signal #{name.inspect} is a duplicate delivery of signal #{signal.id}, not dispatching")
+        duplicate = true
+        next
+      end
+
+      logger.info("Received signal #{name.inspect} as signal #{signal.id}")
+
+      if paused?
+        logger.info("Workflow is paused, buffering signal #{signal.id} until resume!")
+      else
+        wake_executions_matching!(signal)
+      end
+    end
+
+    signal.duplicate_delivery! if duplicate
+    signal
+  end
+
   # Returns the current active step execution, if any.
-  # Includes scheduled and in_progress states.
+  # Includes scheduled, waiting and in_progress states.
   #
   # @return [StepExecution, nil] the current execution
   def current_execution
-    step_executions.where(state: %w[scheduled in_progress]).first
+    step_executions.where(state: %w[scheduled waiting in_progress]).first
+  end
+
+  # Signals that may still be attached to an execution, oldest first, each
+  # pointing back at this workflow instance.
+  #
+  # Matcher blocks are instance_exec'd on `signal.workflow`, and `inverse_of:`
+  # only primes records loaded straight off the association - a scoped
+  # relation would hand each signal a freshly loaded workflow, which would
+  # then see none of the caller's unsaved state.
+  #
+  # @return [Array<GenevaDrive::Signal>]
+  # @api private
+  public def attachable_signals
+    signals.attachable.map { |signal| adopt_signal(signal) }
+  end
+
+  # Wakes every parked step execution whose matcher accepts the given signal.
+  #
+  # Runs under the workflow row lock - the same lock create_step_execution
+  # and the Executor take - so whichever of dispatch and the gate commits
+  # second sees the other's write and no signal can slip through the gap.
+  #
+  # @param signal [GenevaDrive::Signal] the signal to deliver
+  # @return [Array<StepExecution>] the executions that were woken
+  # @api private
+  public def dispatch_signal!(signal)
+    return [] unless GenevaDrive::StepExecution.signal_columns?
+
+    with_lock { wake_executions_matching!(signal) }
+  end
+
+  # Settles the signal attached to an execution we are deliberately moving
+  # past, wherever the skip came from: `skip_if` firing at wake, flow control
+  # inside the step, an exception policy, or an operator calling `skip!`.
+  #
+  # Consumption follows attachment. A skip in any flavor says "we are done
+  # with this step", so an event that was delivered to it is spent by that
+  # decision - leaving it claimed would hand a stale event to the next waiter
+  # for the same name, which is exactly what consume-once-per-event forbids.
+  # An execution that never attached has nothing to settle, so buffered
+  # signals a step never reached are left alone.
+  #
+  # Must be called with the workflow lock held, so the settle rides the same
+  # transaction as the skip itself.
+  #
+  # @param step_execution [StepExecution, nil] the execution being skipped past
+  # @return [GenevaDrive::Signal, nil] the settled signal, if there was one
+  # @api private
+  public def settle_signal_for_skipped!(step_execution)
+    return unless GenevaDrive::StepExecution.signal_columns?
+    return if step_execution.nil? || step_execution.signal_id.blank?
+
+    signal = step_execution.signal
+    return unless signal && signal.state == "claimed"
+
+    logger.info("Skipping past step #{step_execution.step_name}, settling attached signal #{signal.id} (#{signal.name})")
+    signal.record_consumption!(resolved_step_names: [step_execution.step_name])
+    signal
+  end
+
+  # The body of dispatch, for callers that already hold the workflow lock
+  # (`signal!` holds it across the whole delivery so the rows land atomically).
+  #
+  # @param signal [GenevaDrive::Signal] the signal to deliver
+  # @return [Array<StepExecution>] the executions that were woken
+  # @api private
+  public def wake_executions_matching!(signal)
+    return [] unless GenevaDrive::StepExecution.signal_columns?
+    return [] if paused? || !ongoing?
+
+    # Matcher blocks run on signal.workflow, so point the signal at this very
+    # instance instead of letting it load a second copy from the database.
+    adopt_signal(signal)
+    woken = []
+
+    step_executions.where(state: "waiting").order(created_at: :asc, id: :asc).each do |execution|
+      step_def = execution.step_definition
+      # A step whose definition is gone (class removed, step renamed) can
+      # never match - the matcher lives on the definition.
+      next unless step_def&.waits_for_signal?
+      next unless step_def.signal_matcher.matches?(signal)
+
+      signal.claim!
+      execution.update!(
+        signal_id: signal.id,
+        state: "scheduled",
+        scheduled_for: Time.current,
+        waiting_since: nil
+      )
+      woken << [execution, step_def]
+    end
+
+    woken.each do |execution, step_def|
+      enqueue_woken_execution(execution, step_def)
+    end
+
+    woken.map(&:first)
   end
 
   # Returns all step executions in chronological order.
@@ -714,7 +1073,7 @@ class GenevaDrive::Workflow < ActiveRecord::Base
   #
   # @return [void]
   def log_workflow_created
-    step_count = self.class.step_definitions.size
+    step_count = steps.runnable.size
     logger.info("Created workflow with #{step_count} step(s) defined")
   end
 
@@ -722,7 +1081,10 @@ class GenevaDrive::Workflow < ActiveRecord::Base
   #
   # @return [StepExecution, nil] the created step execution
   def schedule_first_step!
-    first_step = self.class.step_definitions.first
+    # next_after(nil) means "from the beginning" and honours both the
+    # before_step:/after_step: ordering and removed_step gravestones, neither
+    # of which the raw _step_definitions array knows about.
+    first_step = steps.next_after(nil)
     unless first_step
       logger.info("No steps defined, finishing workflow immediately")
       return finish_workflow!
@@ -732,6 +1094,76 @@ class GenevaDrive::Workflow < ActiveRecord::Base
     create_step_execution(first_step, wait: first_step.wait)
   end
 
+  # Points a signal's workflow association at this instance, so matcher
+  # blocks - which are instance_exec'd on it - see the live object.
+  #
+  # @param signal [GenevaDrive::Signal]
+  # @return [GenevaDrive::Signal] the same signal
+  def adopt_signal(signal)
+    signal.association(:workflow).target = self
+    signal
+  end
+
+  # Enqueues the PerformStepJob for an execution that dispatch just flipped
+  # from waiting to scheduled. Uses the same enqueue discipline (merged job
+  # options, after-commit deferral, job_id writeback) as create_step_execution.
+  #
+  # @param step_execution [StepExecution] the woken execution
+  # @param step_definition [StepDefinition] its step definition
+  # @return [void]
+  def enqueue_woken_execution(step_execution, step_definition)
+    job_options = merged_step_job_options(step_definition)
+    execution_id = step_execution.id
+    workflow_logger = logger
+
+    run_after_commit do
+      job = GenevaDrive::PerformStepJob
+        .set(**job_options)
+        .perform_later(execution_id)
+
+      workflow_logger.debug("Enqueued PerformStepJob with job_id=#{job.job_id} for woken step execution #{execution_id}")
+
+      GenevaDrive::StepExecution
+        .where(id: execution_id)
+        .update_all(job_id: job.job_id)
+    end
+  end
+
+  # Re-runs the rendezvous for a step execution that is parked waiting for a
+  # signal. Signals that arrived while the workflow was paused are delivered
+  # here, on resume.
+  #
+  # @param step_execution [StepExecution] the parked execution
+  # @return [StepExecution] the same execution (rescheduled if a signal matched)
+  def rendezvous_waiting_execution!(step_execution)
+    step_def = step_execution.step_definition
+
+    # The step was removed while this execution sat parked. It waits for an
+    # event that nothing will ever match now, so release it here rather than
+    # leaving it parked for good.
+    if step_def&.removed?
+      logger.info("Step #{step_execution.step_name} was parked but is now a removed_step — releasing it and continuing")
+
+      step_execution.mark_skipped!
+      settle_signal_for_skipped!(step_execution)
+      return schedule_next_step!
+    end
+
+    matcher = step_def&.signal_matcher
+
+    if matcher
+      candidate = attachable_signals.detect { |signal| matcher.matches?(signal) }
+      if candidate
+        logger.info("Resuming into a matching signal #{candidate.id} (#{candidate.name}) for step #{step_execution.step_name}")
+        dispatch_signal!(candidate)
+        return step_execution.reload
+      end
+    end
+
+    logger.info("Step #{step_execution.step_name} stays parked - no matching signal has arrived yet")
+    step_execution
+  end
+
   # Enqueues a job for an existing scheduled execution.
   #
   # If the execution is overdue (scheduled_for is in the past), runs immediately.
@@ -785,22 +1217,24 @@ class GenevaDrive::Workflow < ActiveRecord::Base
     scheduled_for = wait ? wait.from_now : Time.current
 
     with_lock do
-      # Cancel any stray scheduled executions - the successor is the one
-      # execution that should run next (same as create_step_execution).
-      canceled_count = step_executions.scheduled.update_all(
-        state: "canceled",
-        outcome: "canceled",
-        canceled_at: Time.current
-      )
-      logger.debug("Canceled #{canceled_count} previously scheduled step execution(s)") if canceled_count > 0
+      # Cancel any stray scheduled or parked executions - the successor is the
+      # one execution that should run next (same as create_step_execution).
+      cancel_stray_executions!
 
-      successor = step_executions.create!(
+      successor_attributes = {
         step_name: predecessor.step_name,
         state: "scheduled",
         scheduled_for: scheduled_for,
         continues_from_id: predecessor.id,
         cursor: predecessor.cursor
-      )
+      }
+      # Carry the attachment pin across the chain so successors never re-park
+      # and received_signal stays stable for the whole iteration.
+      if GenevaDrive::StepExecution.signal_columns?
+        successor_attributes[:signal_id] = predecessor.signal_id
+      end
+
+      successor = step_executions.create!(**successor_attributes)
 
       # next_step_name points to the step that's scheduled to run next
       update!(next_step_name: predecessor.step_name)
@@ -840,15 +1274,7 @@ class GenevaDrive::Workflow < ActiveRecord::Base
     scheduled_for = wait ? wait.from_now : Time.current
 
     with_lock do
-      # Cancel any scheduled step executions (not in_progress - those are being executed).
-      # Safe to use update_all since we hold the workflow lock, blocking any executor
-      # that would try to start these steps.
-      canceled_count = step_executions.scheduled.update_all(
-        state: "canceled",
-        outcome: "canceled",
-        canceled_at: Time.current
-      )
-      logger.debug("Canceled #{canceled_count} previously scheduled step execution(s)") if canceled_count > 0
+      cancel_stray_executions!
 
       step_execution = step_executions.create!(
         step_name: step_definition.name,
@@ -892,6 +1318,26 @@ class GenevaDrive::Workflow < ActiveRecord::Base
     end
   end
 
+  # Cancels any scheduled or parked step executions so that the execution
+  # about to be created is the only one that will run. In-progress executions
+  # are left alone - they are being executed.
+  #
+  # Safe to use update_all because the caller holds the workflow lock, which
+  # blocks any executor that would try to start these steps. Parked executions
+  # are swept for the same reason: no legitimate path creates a new execution
+  # past one that is waiting.
+  #
+  # @return [Integer] the number of executions canceled
+  def cancel_stray_executions!
+    canceled_count = step_executions.where(state: %w[scheduled waiting]).update_all(
+      state: "canceled",
+      outcome: "canceled",
+      canceled_at: Time.current
+    )
+    logger.debug("Canceled #{canceled_count} previously scheduled step execution(s)") if canceled_count > 0
+    canceled_count
+  end
+
   # Finishes the workflow.
   #
   # @return [nil]
@@ -948,6 +1394,33 @@ class GenevaDrive::Workflow < ActiveRecord::Base
     @tagged_logger = previous_tagged_logger
   end
 
+  # The signal that woke the step currently executing, or nil when the step
+  # does not declare +wait_for:+. Available inside step bodies only.
+  #
+  # @return [GenevaDrive::Signal, nil]
+  #
+  # @example Read the payload of the event that woke the step
+  #   step :capture, wait_for: :payment_confirmed do
+  #     hero.capture!(received_signal.payload[:amount_cents])
+  #   end
+  public attr_reader :received_signal
+
+  # Temporarily makes a signal available to step code as +received_signal+
+  # for the duration of the block. Injected by the Executor the same way the
+  # tagged logger is.
+  #
+  # @param signal [GenevaDrive::Signal, nil] the attached signal
+  # @yield the block to execute with the signal in scope
+  # @return [Object] the result of the block
+  # @api private
+  public def with_received_signal(signal)
+    previous_received_signal = @received_signal
+    @received_signal = signal
+    yield
+  ensure
+    @received_signal = previous_received_signal
+  end
+
   # Returns the Logger properly tagged to this Workflow
   #
   # @return [Logger]

data/lib/geneva_drive.rb

@@ -32,19 +32,25 @@ module GenevaDrive
   autoload :StepExecutionError, "geneva_drive/flow_control"
   autoload :StepNotDefinedError, "geneva_drive/flow_control"
   autoload :CursorTooLargeError, "geneva_drive/flow_control"
+  autoload :SignalPayloadTooLargeError, "geneva_drive/flow_control"
+  autoload :WorkflowNotOngoing, "geneva_drive/flow_control"
   autoload :StepFailedError, "geneva_drive/flow_control"
   autoload :PreconditionError, "geneva_drive/flow_control"
   autoload :FlowControl, "geneva_drive/flow_control"
   autoload :StepDefinition, "geneva_drive/step_definition"
   autoload :ResumableStepDefinition, "geneva_drive/resumable_step_definition"
+  autoload :RemovedStepDefinition, "geneva_drive/removed_step_definition"
   autoload :StepCollection, "geneva_drive/step_collection"
   autoload :Workflow, "geneva_drive/workflow"
   autoload :StepExecution, "geneva_drive/step_execution"
+  autoload :Signal, "geneva_drive/signal"
+  autoload :SignalMatcher, "geneva_drive/signal_matcher"
   autoload :IterableStep, "geneva_drive/iterable_step"
   autoload :Executor, "geneva_drive/executor"
   autoload :ExceptionPolicy, "geneva_drive/exception_policy"
   autoload :JobOptions, "geneva_drive/job_options"
   autoload :CombinedExceptionPolicy, "geneva_drive/combined_exception_policy"
+  autoload :JsonColumn, "geneva_drive/json_column"
   autoload :MigrationHelpers, "geneva_drive/migration_helpers"
   autoload :TestHelpers, "geneva_drive/test_helpers"
 
@@ -88,6 +94,22 @@ module GenevaDrive
     # @return [Integer, nil]
     attr_accessor :max_cursor_size
 
+    # Maximum size in bytes of a signal payload once serialized to JSON.
+    # A payload describes an event - an order id, an amount, a decision -
+    # not the data the step is going to work on. Exceeding the limit raises
+    # SignalPayloadTooLargeError from Workflow#signal!, before anything is
+    # persisted. Set to nil to disable the check.
+    # @return [Integer, nil]
+    attr_accessor :max_signal_payload_size
+
+    # How long a step execution may sit in the "waiting" state before
+    # housekeeping counts it in the `geneva_drive.waiting_overdue` gauge.
+    # Waiting indefinitely is legitimate, so this is not a timeout - it is
+    # the floor that keeps a stalled rendezvous from being silent.
+    # Set to nil to disable the gauge.
+    # @return [ActiveSupport::Duration, nil]
+    attr_accessor :waiting_visibility_threshold
+
     # Whether to defer job enqueueing to after the database transaction commits.
     # When true (the default in non-test environments), jobs are enqueued inside
     # an `after_all_transactions_commit` callback to ensure the step execution
@@ -175,5 +197,7 @@ module GenevaDrive
   self.housekeeping_batch_size = 1000
   self.stuck_recovery_action = :reattempt
   self.max_cursor_size = 128 * 1024
+  self.max_signal_payload_size = 128 * 1024
+  self.waiting_visibility_threshold = 7.days
   self.enqueue_after_commit = !Rails.env.test?
 end