geneva_drive 0.6.0 → 0.7.0

data/lib/geneva_drive/jobs/housekeeping_job.rb

@@ -33,6 +33,7 @@ class GenevaDrive::HousekeepingJob < ActiveJob::Base
     results = {
       workflows_cleaned_up: 0,
       step_executions_cleaned_up: 0,
+      signals_cleaned_up: 0,
       stuck_in_progress_recovered: 0,
       stuck_scheduled_recovered: 0
     }
@@ -40,6 +41,7 @@ class GenevaDrive::HousekeepingJob < ActiveJob::Base
     cleanup_completed_workflows!(results)
     recover_stuck_step_executions!(results)
     report_workflow_gauges!
+    report_waiting_gauges!
 
     logger.info("Completed: #{results}")
     results
@@ -89,6 +91,42 @@ class GenevaDrive::HousekeepingJob < ActiveJob::Base
     end
   end
 
+  # Reports gauges for step executions parked waiting for a signal.
+  #
+  # Waiting indefinitely is a legitimate state, not a stuck one, so the stuck
+  # sweeps ignore parked rows. These gauges are what keeps a stalled
+  # rendezvous from being silent:
+  # - `geneva_drive.waiting_step_executions` - parked rows, total and per class
+  # - `geneva_drive.waiting_overdue` - parked longer than
+  #   GenevaDrive.waiting_visibility_threshold, total and per class
+  #
+  # @return [void]
+  def report_waiting_gauges!
+    return unless GenevaDrive::StepExecution.signal_columns?
+
+    report_waiting_gauge!("geneva_drive.waiting_step_executions", GenevaDrive::StepExecution.waiting)
+
+    threshold = GenevaDrive.waiting_visibility_threshold
+    return if threshold.blank?
+
+    overdue = GenevaDrive::StepExecution.waiting.where(waiting_since: ..threshold.ago)
+    report_waiting_gauge!("geneva_drive.waiting_overdue", overdue)
+  end
+
+  # Sets one gauge per workflow class plus an untagged total for the scope.
+  #
+  # @param gauge_name [String] the Measurometer gauge name
+  # @param scope [ActiveRecord::Relation] a step execution scope
+  # @return [void]
+  def report_waiting_gauge!(gauge_name, scope)
+    counts = scope.joins(:workflow).group("#{GenevaDrive::Workflow.table_name}.type").count
+
+    Measurometer.set_gauge(gauge_name, counts.values.sum)
+    counts.each do |type, count|
+      Measurometer.set_gauge(gauge_name, count, workflow: type)
+    end
+  end
+
   # Cleans up completed/canceled workflows older than the configured threshold.
   # Uses efficient batched SQL DELETEs - step executions are deleted first via
   # INNER JOIN, then workflows. Loops until all eligible records are deleted.
@@ -114,7 +152,17 @@ class GenevaDrive::HousekeepingJob < ActiveJob::Base
       break if deleted_count < batch_size
     end
 
-    # Second pass: delete the workflows themselves
+    # Second pass: delete the signals delivered to old workflows
+    if GenevaDrive::Signal.table_available?
+      loop do
+        deleted_count = delete_signals_batch(cutoff_time, batch_size)
+        logger.info("Deleted #{deleted_count} signals")
+        results[:signals_cleaned_up] += deleted_count
+        break if deleted_count < batch_size
+      end
+    end
+
+    # Third pass: delete the workflows themselves
     loop do
       deleted_count = delete_workflows_batch(cutoff_time, batch_size)
       logger.info("Deleted #{deleted_count} workflows")
@@ -123,11 +171,43 @@ class GenevaDrive::HousekeepingJob < ActiveJob::Base
     end
 
     logger.info(
-      "Cleaned up #{results[:workflows_cleaned_up]} workflows " \
-      "and #{results[:step_executions_cleaned_up]} step executions older than #{cutoff_time}"
+      "Cleaned up #{results[:workflows_cleaned_up]} workflows, " \
+      "#{results[:step_executions_cleaned_up]} step executions and " \
+      "#{results[:signals_cleaned_up]} signals older than #{cutoff_time}"
     )
   end
 
+  # Deletes a batch of signals belonging to old workflows.
+  #
+  # @param cutoff_time [Time] workflows transitioned before this time are eligible
+  # @param batch_size [Integer] maximum records to delete in this batch
+  # @return [Integer] number of records deleted
+  def delete_signals_batch(cutoff_time, batch_size)
+    GenevaDrive::Signal.connection_pool.with_connection do |conn|
+      signals_table = conn.quote_table_name(GenevaDrive::Signal.table_name)
+      workflows_table = conn.quote_table_name(GenevaDrive::Workflow.table_name)
+      limit = batch_size.to_i
+
+      # MySQL doesn't support LIMIT in subqueries with IN, so we wrap it in another SELECT
+      # Also, MySQL doesn't handle bind parameters for LIMIT properly, so we interpolate directly
+      sql = <<~SQL.squish
+        DELETE FROM #{signals_table}
+        WHERE id IN (
+          SELECT id FROM (
+            SELECT s.id
+            FROM #{signals_table} s
+            INNER JOIN #{workflows_table} w ON w.id = s.workflow_id
+            WHERE w.state IN ('finished', 'canceled')
+            AND w.transitioned_at < ?
+            LIMIT #{limit}
+          ) AS batch_to_delete
+        )
+      SQL
+
+      conn.delete(GenevaDrive::Signal.sanitize_sql([sql, cutoff_time]))
+    end
+  end
+
   # Deletes a batch of step executions belonging to old workflows.
   #
   # @param cutoff_time [Time] workflows transitioned before this time are eligible

data/lib/geneva_drive/signal.rb

@@ -0,0 +1,243 @@
+# frozen_string_literal: true
+
+# A per-workflow event record. Signals are how the outside world tells a
+# workflow that something happened: a webhook landed, a human clicked
+# "approve", another system finished its part of the job.
+#
+# A signal is always addressed to one workflow instance and is persisted
+# before any processing happens, so it can never be lost between arriving
+# and being noticed - a signal that arrives before the waiting step even
+# exists simply sits in the table until the step's gate picks it up.
+#
+# The lifecycle, in the +state+ column, is +pending+ -> +claimed+ -> +consumed+:
+#
+# - +pending+: persisted, nobody is working on it
+# - +claimed+: attached to at least one step execution, at least one of which
+#   has not resolved yet
+# - +consumed+: every attached chain resolved cleanly; no new execution may attach
+#
+# Alongside the state there are two counters, +claimed+ and +consumed+: how
+# many executions have attached to this event, and how many attached chains
+# have resolved cleanly.
+#
+# @example Delivering a signal
+#   workflow = OrderFulfillmentWorkflow.ongoing.for_hero(order).first
+#   workflow.signal!(:payment_confirmed, payload: {amount_cents: 12_500})
+#
+class GenevaDrive::Signal < ActiveRecord::Base
+  self.table_name = "geneva_drive_signals"
+
+  # Signal lifecycle states as enum with string values.
+  #
+  # Neither predicates nor scopes are generated: the +claimed+ and +consumed+
+  # counter columns own those names, and a `Signal.claimed` scope reading the
+  # state while `signal.claimed` reads the counter would be a trap. The state
+  # is queried explicitly (`where(state: ...)`) and read off the column; the
+  # public predicates are {#claimed?} and {#consumed?} over the counters.
+  enum :state, {
+    pending: "pending",
+    claimed: "claimed",
+    consumed: "consumed"
+  }, instance_methods: false, scopes: false
+
+  # Step execution states that mean "this chain has not come to rest yet".
+  ACTIVE_EXECUTION_STATES = %w[waiting scheduled in_progress].freeze
+
+  # Outcomes that resolve an attached chain cleanly, so the signal can be
+  # considered handled by it.
+  CLEAN_OUTCOMES = %w[success skipped].freeze
+
+  belongs_to :workflow,
+    class_name: "GenevaDrive::Workflow",
+    foreign_key: :workflow_id,
+    inverse_of: :signals
+
+  validates :name, presence: true
+
+  # Signals that may still be attached to a step execution, oldest first.
+  # The eligibility rule for both the gate and dispatch: anything that
+  # matches and has not been consumed, FIFO.
+  scope :attachable, -> { where.not(state: "consumed").order(created_at: :asc, id: :asc) }
+
+  class << self
+    # Lazily checks whether the signals table has been migrated. Never hits
+    # the database at class definition time - only on the first runtime call.
+    #
+    # Deployments usually ship the gem update before running migrations, so
+    # everything except actually sending or waiting for a signal must keep
+    # working when the table is absent.
+    #
+    # @return [Boolean]
+    def table_available?
+      if defined?(@_table_available)
+        return @_table_available
+      end
+
+      @_table_available = table_exists?
+    end
+
+    # Clears the cached table detection result. Call this in tests or after
+    # running migrations in-process so the next access re-checks.
+    #
+    # @return [void]
+    def reset_table_available_cache!
+      remove_instance_variable(:@_table_available) if defined?(@_table_available)
+    end
+
+    # Serializes a payload using ActiveJob serializers (handles Date, Time,
+    # and other types) and enforces GenevaDrive.max_signal_payload_size on
+    # the serialized JSON. The single serialization path for payload writes.
+    #
+    # @param value [Object, nil] the payload
+    # @return [Object, nil] the serialized payload
+    # @raise [SignalPayloadTooLargeError] if the serialized JSON exceeds the limit
+    def serialize_payload(value)
+      return nil if value.nil?
+
+      serialized = ActiveJob::Arguments.serialize([value]).first
+
+      limit = GenevaDrive.max_signal_payload_size
+      if limit
+        bytesize = JSON.generate(serialized).bytesize
+        if bytesize > limit
+          raise GenevaDrive::SignalPayloadTooLargeError,
+            "Serialized signal payload is #{bytesize} bytes, exceeding " \
+            "GenevaDrive.max_signal_payload_size (#{limit} bytes). A payload describes the " \
+            "event, it is not a place to ship the data the step should be working on - " \
+            "write what matters onto the hero instead. Set " \
+            "GenevaDrive.max_signal_payload_size to nil to disable this check."
+        end
+      end
+
+      serialized
+    end
+  end
+
+  # Returns the deserialized payload. Hashes come back with indifferent
+  # access, because webhook senders produce string keys while Ruby senders
+  # produce symbols and matchers should not have to know which.
+  #
+  # @return [Object, nil] the payload
+  def payload
+    raw = self[:payload]
+    return nil if raw.nil?
+
+    value = ActiveJob::Arguments.deserialize([raw]).first
+    value.is_a?(Hash) ? ActiveSupport::HashWithIndifferentAccess.new(value) : value
+  end
+
+  # Sets the payload, serializing it through ActiveJob serializers.
+  #
+  # @param value [Object, nil] the payload
+  # @raise [SignalPayloadTooLargeError] if the serialized JSON exceeds the limit
+  # @return [void]
+  def payload=(value)
+    self[:payload] = self.class.serialize_payload(value)
+  end
+
+  # Whether this instance was returned from a deduplicated delivery - that
+  # is, {GenevaDrive::Workflow#signal!} found an existing row with the same
+  # idempotency key instead of inserting a new one. Not a column: it is a
+  # fact about this call, not about the record.
+  #
+  # @return [Boolean]
+  def duplicate_delivery?
+    !!@duplicate_delivery
+  end
+
+  # Flags this instance as the result of a deduplicated delivery.
+  #
+  # @return [void]
+  # @api private
+  def duplicate_delivery!
+    @duplicate_delivery = true
+  end
+
+  # Whether at least one execution has ever attached to this signal. Reads
+  # the counter, not the lifecycle state, so it stays true after the signal
+  # has been consumed - "this event was picked up" rather than "is being
+  # handled right now".
+  #
+  # @return [Boolean]
+  def claimed? = claimed > 0
+
+  # Whether at least one attached chain has resolved cleanly. Reads the
+  # counter, so for a one-to-many dispatch it goes true with the first
+  # resolved branch, while the state only flips once the last one resolves.
+  #
+  # @return [Boolean]
+  def consumed? = consumed > 0
+
+  # Records one execution attaching to this signal, bumping the claimed
+  # count. The pending -> claimed state flip and claimed_at happen on the
+  # first claim only, so the timestamp keeps meaning "when this event started
+  # being handled". A retry attaching to a still-claimed signal counts as a
+  # new claim; a successor continuing the same chain does not (it carries the
+  # pin over rather than acquiring it).
+  #
+  # @return [void]
+  # @api private
+  def claim!
+    attrs = {claimed: claimed + 1}
+    if state == "pending"
+      attrs[:state] = "claimed"
+      attrs[:claimed_at] = Time.current
+    end
+    update!(attrs)
+  end
+
+  # Records one attached execution chain resolving cleanly, bumping the
+  # consumed count. The state flips to consumed - closing the signal to new
+  # attachments - only once every attached chain has resolved, which for a
+  # single claimant is the same moment.
+  #
+  # @param resolved_step_names [Array<String, Symbol>] steps whose chains are
+  #   resolved by decree rather than by outcome - a skip settles the chain it
+  #   skips past even when that chain's last execution failed
+  # @return [void]
+  # @api private
+  def record_consumption!(resolved_step_names: [])
+    attrs = {consumed: consumed + 1}
+    if state == "claimed" && fully_resolved?(resolved_step_names: resolved_step_names)
+      attrs[:state] = "consumed"
+      attrs[:consumed_at] = Time.current
+    end
+    update!(attrs)
+  end
+
+  # Whether every execution chain attached to this signal has come to a
+  # clean stop. A chain that is still running (or parked), and one whose
+  # latest attached execution failed or was canceled, both keep the state at
+  # claimed - the failed chain's retry re-attaches to it and reads the same
+  # payload.
+  #
+  # Only the most recent attached execution per step counts: the earlier ones
+  # in a chain end with `continued` or `reattempted` precisely because they
+  # handed the work to the next one.
+  #
+  # @param resolved_step_names [Array<String, Symbol>] steps to treat as
+  #   resolved whatever their executions say. Skipping a step is a decision
+  #   that its chain is over, including when that chain ended in a failure -
+  #   no future execution of it is coming to resolve it cleanly.
+  # @return [Boolean]
+  # @api private
+  def fully_resolved?(resolved_step_names: [])
+    settled = Array(resolved_step_names).map(&:to_s)
+    attached = step_executions.order(created_at: :asc, id: :asc).to_a
+    return true if attached.empty?
+
+    unsettled = attached.reject { |execution| settled.include?(execution.step_name) }
+    return false if unsettled.any? { |execution| ACTIVE_EXECUTION_STATES.include?(execution.state) }
+
+    unsettled.group_by(&:step_name).all? do |_step_name, chain|
+      CLEAN_OUTCOMES.include?(chain.last.outcome)
+    end
+  end
+
+  # Step executions pinned to this signal.
+  #
+  # @return [ActiveRecord::Relation<GenevaDrive::StepExecution>]
+  def step_executions
+    GenevaDrive::StepExecution.where(signal_id: id)
+  end
+end

data/lib/geneva_drive/signal_matcher.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+# Decides whether a given {GenevaDrive::Signal} is the one a step is waiting
+# for. A matcher is a plain object, so it can live in a constant and be shared
+# between steps and workflows.
+#
+# Name equality is the whole predicate unless a block is given; the block
+# receives the (indifferent-access) payload and is +instance_exec+'d on the
+# signal's workflow, so +hero+ and the workflow's own methods are in scope.
+#
+# @example Name only (what `wait_for: :payment_confirmed` builds for you)
+#   GenevaDrive::SignalMatcher.new(:payment_confirmed)
+#
+# @example Narrowed by payload
+#   GenevaDrive::SignalMatcher.new(:document_signed) do |payload|
+#     payload[:document_id] == hero.contract_id
+#   end
+#
+# Anything else responding to +#matches?(signal)+ works just as well in
+# +wait_for:+ - a custom matcher owns its whole predicate and can, for
+# instance, accept either of two signal names.
+#
+# Matchers run both at the gate (the waiting step's own job) and at dispatch
+# (inside +signal!+, in the sender's process). They must be cheap and free of
+# side effects, the same expectation +skip_if:+ carries.
+class GenevaDrive::SignalMatcher
+  # @return [String] the signal name this matcher accepts
+  attr_reader :name
+
+  # @return [Proc, nil] the payload predicate, if any
+  attr_reader :condition
+
+  # @param name [String, Symbol] signal name for equality matching
+  # @yield [payload] optional payload predicate, instance_exec'd on the workflow
+  # @raise [ArgumentError] if the name is blank
+  def initialize(name, &condition)
+    raise ArgumentError, "GenevaDrive::SignalMatcher needs a signal name" if name.blank?
+
+    @name = name.to_s
+    @condition = condition
+  end
+
+  # Whether the signal is the one being waited for.
+  #
+  # @param signal [GenevaDrive::Signal] the candidate signal
+  # @return [Boolean]
+  def matches?(signal)
+    return false unless signal.name == @name
+    return true unless @condition
+
+    !!signal.workflow.instance_exec(signal.payload, &@condition)
+  end
+
+  # Human-readable description, used in log lines and test helper messages.
+  #
+  # @return [String]
+  def to_s
+    @condition ? "#{@name} (narrowed by payload)" : @name
+  end
+end

data/lib/geneva_drive/step_definition.rb

@@ -15,6 +15,10 @@ class GenevaDrive::StepDefinition
   # Valid types for skip conditions
   VALID_SKIP_CONDITION_TYPES = [Symbol, Proc, TrueClass, FalseClass, NilClass].freeze
 
+  # Types that mean "a delay" and therefore belong to wait:, never wait_for:.
+  # ActiveSupport::Duration is a Numeric-alike but not a Numeric, hence both.
+  DURATION_SHAPED_TYPES = [ActiveSupport::Duration, Numeric, Time, Date].freeze
+
   # @return [String] the step name
   attr_reader :name
 
@@ -45,6 +49,12 @@ class GenevaDrive::StepDefinition
   # @return [Array<String, Integer>, nil] source location of the step block [path, lineno]
   attr_reader :block_location
 
+  # @return [Symbol, String, Object, nil] the raw wait_for: option
+  attr_reader :wait_for
+
+  # @return [GenevaDrive::SignalMatcher, nil] the normalized signal matcher, if this step waits
+  attr_reader :signal_matcher
+
   # Creates a new step definition.
   #
   # @param name [String, Symbol] the step name
@@ -69,6 +79,7 @@ class GenevaDrive::StepDefinition
     @call_location = call_location
     @block_location = block_location
     @wait = options[:wait]
+    @wait_for = options[:wait_for]
     @job_options = options.fetch(:job_options, {})
     @skip_if_option = options[:skip_if]
     @if_option = options[:if]
@@ -83,6 +94,7 @@ class GenevaDrive::StepDefinition
     validate!
     @job_options = GenevaDrive::JobOptions.validate!(@job_options, context: "Step '#{@name}'").freeze
     @exception_policy = build_exception_policy
+    @signal_matcher = build_signal_matcher
   end
 
   # Returns the action symbol from the exception policy.
@@ -119,6 +131,13 @@ class GenevaDrive::StepDefinition
     false
   end
 
+  # Whether this step parks until a matching signal arrives.
+  #
+  # @return [Boolean]
+  def waits_for_signal?
+    !@signal_matcher.nil?
+  end
+
   # Executes the step callable in the context of the workflow.
   #
   # @param workflow [GenevaDrive::Workflow] the workflow instance
@@ -144,6 +163,58 @@ class GenevaDrive::StepDefinition
     validate_terminal_action_raw!
     validate_positioning!
     validate_skip_condition!
+    validate_wait_for!
+  end
+
+  # Normalizes wait_for: into a matcher. A bare name becomes a
+  # {GenevaDrive::SignalMatcher}; anything else already is one (or quacks
+  # like one).
+  #
+  # @return [Object, nil] an object responding to #matches?(signal)
+  def build_signal_matcher
+    return nil if @wait_for.nil?
+    return GenevaDrive::SignalMatcher.new(@wait_for) if signal_shaped_name?(@wait_for)
+
+    @wait_for
+  end
+
+  # Whether the value is a plain signal name.
+  #
+  # @param value [Object]
+  # @return [Boolean]
+  def signal_shaped_name?(value)
+    value.is_a?(Symbol) || value.is_a?(String)
+  end
+
+  # Whether the value means "a delay" and therefore belongs to wait:.
+  #
+  # @param value [Object]
+  # @return [Boolean]
+  def duration_shaped?(value)
+    DURATION_SHAPED_TYPES.any? { |type| value.is_a?(type) }
+  end
+
+  # Validates wait_for:, including the swap guard that catches a duration
+  # passed to it. wait: and wait_for: read alike and take disjoint types, so
+  # each direction of the mistake gets an error naming the kwarg the author
+  # meant (the other direction lives in validate_wait!).
+  #
+  # @raise [StepConfigurationError] if the option is invalid or swapped
+  def validate_wait_for!
+    return if @wait_for.nil?
+
+    if duration_shaped?(@wait_for)
+      raise GenevaDrive::StepConfigurationError,
+        "Step '#{@name}' has wait_for: #{@wait_for.inspect} — wait_for: takes a signal name or " \
+        "matcher; to delay the step, use wait:"
+    end
+
+    return if signal_shaped_name?(@wait_for)
+    return if @wait_for.respond_to?(:matches?)
+
+    raise GenevaDrive::StepConfigurationError,
+      "Step '#{@name}' has invalid wait_for: must be a Symbol, String, GenevaDrive::SignalMatcher, " \
+      "or an object responding to #matches?(signal), but was #{@wait_for.class}"
   end
 
   # Builds the ExceptionPolicy from validated raw inputs.
@@ -196,9 +267,19 @@ class GenevaDrive::StepDefinition
 
   # Validates the wait duration.
   #
-  # @raise [StepConfigurationError] if wait is negative
+  # @raise [StepConfigurationError] if wait is negative or signal-shaped
   def validate_wait!
     return if @wait.nil?
+
+    # The other half of the wait:/wait_for: swap guard. Durations are numbers
+    # or Durations, never Strings - and a String sails through the to_i check
+    # below as a zero-second wait, so this arm tightens wait: for everyone.
+    if signal_shaped_name?(@wait) || @wait.respond_to?(:matches?)
+      raise GenevaDrive::StepConfigurationError,
+        "Step '#{@name}' has wait: #{@wait.inspect} — wait: takes a duration; to wait for a " \
+        "signal, use wait_for:"
+    end
+
     return if @wait.respond_to?(:to_i) && @wait.to_i >= 0
 
     raise GenevaDrive::StepConfigurationError,

data/lib/geneva_drive/step_execution.rb

@@ -26,6 +26,7 @@ class GenevaDrive::StepExecution < ActiveRecord::Base
   # Provides: scheduled, in_progress, etc. scopes
   enum :state, {
     scheduled: "scheduled",
+    waiting: "waiting",
     in_progress: "in_progress",
     completed: "completed",
     failed: "failed",
@@ -63,6 +64,14 @@ class GenevaDrive::StepExecution < ActiveRecord::Base
     foreign_key: :continues_from_id,
     inverse_of: :continues_from
 
+  # The signal this execution is processing (the "attachment pin"). Set once,
+  # at the gate or by dispatch, and copied to successor executions so the
+  # payload stays stable across a whole resumable chain.
+  belongs_to :signal,
+    class_name: "GenevaDrive::Signal",
+    foreign_key: :signal_id,
+    optional: true
+
   # Validations
   validates :step_name, presence: true
   validates :scheduled_for, presence: true
@@ -102,6 +111,33 @@ class GenevaDrive::StepExecution < ActiveRecord::Base
       remove_instance_variable(:@_resumable_columns) if defined?(@_resumable_columns)
     end
 
+    # Lazily checks whether the signal columns (signal_id and
+    # waiting_since) have been migrated, mirroring resumable_columns?.
+    # Never hits the database at class definition time.
+    #
+    # Everything unrelated to signals keeps working without them; a step
+    # declaring wait_for: fails loudly with a "run the install generator"
+    # message instead of silently running without its event.
+    #
+    # @return [Boolean]
+    def signal_columns?
+      if defined?(@_signal_columns)
+        return @_signal_columns
+      end
+
+      @_signal_columns = table_exists? &&
+        column_names.include?("signal_id") &&
+        column_names.include?("waiting_since")
+    end
+
+    # Clears the cached signal column detection result. Call this in tests or
+    # after running migrations in-process so the next access re-checks.
+    #
+    # @return [void]
+    def reset_signal_columns_cache!
+      remove_instance_variable(:@_signal_columns) if defined?(@_signal_columns)
+    end
+
     # Serializes a cursor value using ActiveJob serializers (handles Date,
     # Time, and other types) and enforces GenevaDrive.max_cursor_size on
     # the serialized JSON. The single serialization path for cursor writes.