geneva_drive 0.6.0 → 0.8.0

data/lib/geneva_drive/signal.rb

@@ -0,0 +1,245 @@
+# 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
+  include GenevaDrive::JsonColumn
+
+  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
+
+      encode_json_column(:payload, 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.class.decode_json_column(:payload, 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_collection.rb

@@ -65,30 +65,54 @@ class GenevaDrive::StepCollection
     ordered_steps[position]
   end
 
-  # Returns the next step after the given step name.
+  # Returns the next runnable step after the given step name.
+  #
+  # Steps declared with `removed_step` are stepped over: they hold a position
+  # in the sequence so that executions scheduled before their removal still
+  # resolve, but no execution is ever scheduled for one.
+  #
+  # A nil current_name means "the beginning", so the first runnable step is
+  # returned - which is how the first step of a workflow is chosen.
   #
   # @param current_name [String, Symbol, nil] the current step name
-  # @return [StepDefinition, nil] the next step or nil if at end
+  # @return [StepDefinition, nil] the next runnable step or nil if at end
   def next_after(current_name)
-    return first if current_name.nil?
+    return ordered_steps.find { |s| !s.removed? } if current_name.nil?
 
     current_index = ordered_steps.index { |s| s.name == current_name.to_s }
     return nil unless current_index
 
-    self[current_index + 1]
+    ordered_steps[(current_index + 1)..].find { |s| !s.removed? }
   end
 
-  # Returns the step before the given step name in the ordered sequence.
+  # Returns the previous runnable step before the given step name in the
+  # ordered sequence. Removed steps are stepped over, for the same reason
+  # {#next_after} steps over them.
   #
   # @param current_name [String, Symbol, nil] the current step name
-  # @return [StepDefinition, nil] the previous step or nil if at beginning
+  # @return [StepDefinition, nil] the previous runnable step or nil if at beginning
   def previous_before(current_name)
     return nil if current_name.nil?
 
     current_index = find_index { |s| s.name == current_name.to_s }
     return nil unless current_index && current_index > 0
 
-    self[current_index - 1]
+    ordered_steps[0...current_index].reverse_each.find { |s| !s.removed? }
+  end
+
+  # Returns the steps that can actually run, in order, with `removed_step`
+  # gravestones filtered out.
+  #
+  # @return [Array<StepDefinition>] the runnable step definitions
+  def runnable
+    ordered_steps.reject(&:removed?)
+  end
+
+  # Returns the `removed_step` gravestones, in order.
+  #
+  # @return [Array<StepDefinition>] the removed step definitions
+  def removed
+    ordered_steps.select(&:removed?)
   end
 
   # Checks if a step exists with the given name.

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,22 @@ class GenevaDrive::StepDefinition
     false
   end
 
+  # Returns whether this step is a gravestone left by `removed_step`.
+  # Removed steps keep their name resolvable for executions scheduled before
+  # the step was taken out, but are never scheduled and never run.
+  #
+  # @return [Boolean] false for standard steps
+  def removed?
+    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 +172,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 +276,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

@@ -20,12 +20,14 @@ class GenevaDrive::StepExecution < ActiveRecord::Base
 
   require_relative "step_execution/metadata_accessor"
   include MetadataAccessor
+  include GenevaDrive::JsonColumn
 
   # Step execution states as enum with string values
   # Provides: scheduled?, in_progress?, etc. predicates
   # Provides: scheduled, in_progress, etc. scopes
   enum :state, {
     scheduled: "scheduled",
+    waiting: "waiting",
     in_progress: "in_progress",
     completed: "completed",
     failed: "failed",
@@ -63,6 +65,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 +112,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.
@@ -126,7 +163,7 @@ class GenevaDrive::StepExecution < ActiveRecord::Base
         end
       end
 
-      serialized
+      encode_json_column(:cursor, serialized)
     end
   end
 
@@ -214,7 +251,7 @@ class GenevaDrive::StepExecution < ActiveRecord::Base
   def cursor_value
     return nil unless self.class.resumable_columns?
     return nil if cursor.blank?
-    ActiveJob::Arguments.deserialize([cursor]).first
+    ActiveJob::Arguments.deserialize([self.class.decode_json_column(:cursor, cursor)]).first
   end
 
   # Sets the cursor value for resumable steps.