geneva_drive 0.5.0 → 0.7.0

data/lib/geneva_drive/resumable_step_definition.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+# Metadata about a resumable step definition in a workflow.
+# Extends StepDefinition with cursor-based iteration support.
+#
+# Resumable steps can iterate over large collections with checkpointing,
+# allowing them to be suspended and resumed across job executions.
+#
+# @api private
+class GenevaDrive::ResumableStepDefinition < GenevaDrive::StepDefinition
+  # @return [Proc] the block to execute (receives IterableStep)
+  attr_reader :block
+
+  # @return [Integer, nil] maximum number of iterations before auto-suspend
+  attr_reader :max_iterations
+
+  # @return [ActiveSupport::Duration, nil] maximum runtime before auto-suspend
+  attr_reader :max_runtime
+
+  # Creates a new resumable step definition.
+  #
+  # @param name [String, Symbol] the step name
+  # @param max_iterations [Integer, nil] maximum iterations before auto-suspend
+  # @param max_runtime [ActiveSupport::Duration, nil] maximum runtime before auto-suspend
+  # @param options [Hash] additional options (same as StepDefinition)
+  # @param block [Proc] the block to execute (required, receives IterableStep)
+  # @raise [StepConfigurationError] if configuration is invalid
+  def initialize(name:, max_iterations: nil, max_runtime: nil, **options, &block)
+    @block = block
+    @max_iterations = max_iterations
+    @max_runtime = max_runtime
+
+    # Pass a dummy callable to parent since we use block instead
+    super(name: name, callable: block, **options)
+
+    validate_resumable!
+  end
+
+  # Returns true to indicate this step supports resumable iteration.
+  #
+  # @return [Boolean]
+  def resumable?
+    true
+  end
+
+  # Executes the step block with an IterableStep in the workflow context.
+  #
+  # @param workflow [GenevaDrive::Workflow] the workflow instance
+  # @param iterable_step [GenevaDrive::IterableStep] the iteration context
+  # @return [Object] the result of the step execution
+  def execute_in_context(workflow, iterable_step)
+    workflow.instance_exec(iterable_step, &@block)
+  end
+
+  private
+
+  # Validates resumable-specific configuration.
+  #
+  # @raise [StepConfigurationError] if configuration is invalid
+  def validate_resumable!
+    validate_block!
+    validate_max_iterations!
+    validate_max_runtime!
+  end
+
+  # Validates that the block is present.
+  #
+  # @raise [StepConfigurationError] if block is missing
+  def validate_block!
+    return if @block.is_a?(Proc)
+
+    raise GenevaDrive::StepConfigurationError,
+      "Resumable step '#{@name}' requires a block"
+  end
+
+  # Validates the max_iterations value.
+  #
+  # @raise [StepConfigurationError] if max_iterations is invalid
+  def validate_max_iterations!
+    return if @max_iterations.nil?
+    return if @max_iterations.is_a?(Integer) && @max_iterations.positive?
+
+    raise GenevaDrive::StepConfigurationError,
+      "Resumable step '#{@name}' has invalid max_iterations: must be a positive integer"
+  end
+
+  # Validates the max_runtime value.
+  #
+  # @raise [StepConfigurationError] if max_runtime is invalid
+  def validate_max_runtime!
+    return if @max_runtime.nil?
+    return if @max_runtime.respond_to?(:to_i) && @max_runtime.to_i.positive?
+
+    raise GenevaDrive::StepConfigurationError,
+      "Resumable step '#{@name}' has invalid max_runtime: must be a positive duration"
+  end
+end

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

@@ -2,7 +2,7 @@
 
 # Metadata about a step definition in a workflow.
 # Holds the step name, callable (block or method name), wait time,
-# skip conditions, and exception handling configuration.
+# job options, skip conditions, and exception handling configuration.
 #
 # @api private
 class GenevaDrive::StepDefinition
@@ -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
 
@@ -24,6 +28,9 @@ class GenevaDrive::StepDefinition
   # @return [ActiveSupport::Duration, nil] wait time before executing this step
   attr_reader :wait
 
+  # @return [Hash] frozen, symbol-keyed Active Job options for this step
+  attr_reader :job_options
+
   # @return [Proc, Symbol, Boolean, nil] condition for skipping this step
   attr_reader :skip_condition
 
@@ -42,12 +49,19 @@ 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
   # @param callable [Proc, Symbol, nil] the code to execute (block or method name)
   # @param options [Hash] additional options
   # @option options [ActiveSupport::Duration, nil] :wait delay before execution
+  # @option options [Hash] :job_options options passed to Active Job's set method
   # @option options [Proc, Symbol, Boolean, nil] :skip_if condition for skipping
   # @option options [Proc, Symbol, Boolean, nil] :if condition for running (inverse of skip_if)
   # @option options [Symbol, GenevaDrive::ExceptionPolicy, Proc, Array<GenevaDrive::ExceptionPolicy>] :on_exception
@@ -65,6 +79,8 @@ 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]
     @skip_condition = @skip_if_option || @if_option
@@ -76,7 +92,9 @@ class GenevaDrive::StepDefinition
     @after_step = options[:after_step]&.to_s
 
     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.
@@ -106,6 +124,20 @@ class GenevaDrive::StepDefinition
     evaluate_condition(@skip_condition, workflow)
   end
 
+  # Returns whether this is a resumable step.
+  #
+  # @return [Boolean] false for standard steps
+  def resumable?
+    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
@@ -131,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.
@@ -183,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,