pgbus 0.19.4 → 0.20.1

data/lib/pgbus/workflow/signal_matcher.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Pgbus
+  class Workflow
+    # Which signal a `wait_for:` step takes:
+    #
+    #   step :capture, wait_for: :payment_confirmed do ... end
+    #   step :ship, wait_for: Pgbus::Workflow::SignalMatcher.new(:shipped) { |payload| payload[:region] == "eu" }
+    #   step :ship, wait_for: EuShipment.new          # any object answering matches?(signal)
+    #
+    # A matcher runs under the workflow row lock (when the step reaches its
+    # gate, and when signal! looks for a waiting step), so it must be fast
+    # and free of side effects. It gets a Pgbus::WorkflowSignal whose
+    # +payload+ has indifferent access.
+    class SignalMatcher
+      attr_reader :signal_name, :condition
+
+      # A name becomes a matcher; a matcher, or anything answering matches?,
+      # is kept as it is.
+      def self.coerce(value)
+        return value if value.respond_to?(:matches?)
+        return new(value) if (value.is_a?(Symbol) || value.is_a?(String)) && !value.to_s.strip.empty?
+
+        raise ArgumentError, "wait_for: takes a signal name, a Pgbus::Workflow::SignalMatcher or an object " \
+                             "answering matches?(signal), got #{value.inspect}"
+      end
+
+      # What the step row's wait_for column shows: the signal name, else the
+      # matcher's class.
+      def self.label(matcher)
+        return matcher.signal_name.to_s if matcher.respond_to?(:signal_name) && matcher.signal_name
+
+        matcher.class.name.to_s
+      end
+
+      def initialize(name, &condition)
+        raise ArgumentError, "a SignalMatcher needs a signal name, got #{name.inspect}" if name.to_s.strip.empty?
+
+        @signal_name = -name.to_s.strip
+        @condition = condition
+        freeze
+      end
+
+      def matches?(signal)
+        return false unless signal.name.to_s.strip == signal_name
+
+        condition.nil? || (condition.call(signal.payload) ? true : false)
+      end
+
+      def to_s = signal_name
+    end
+  end
+end

data/lib/pgbus/workflow/signals.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+module Pgbus
+  class Workflow
+    # Signals (issue #541): what a wait_for: step waits for.
+    #
+    # deliver (signal!) stores the signal under the run's row lock and, when
+    # the run's current step is waiting for a signal it matches, claims it
+    # for that step and wakes it. Otherwise it stays pending (buffered).
+    #
+    # gate runs in the StepJob after the claim and the guards, under the same
+    # lock: a signal this step already holds (woken by signal!, or claimed by
+    # an earlier attempt that reattempted or paused on a failure), else the
+    # oldest pending one its matcher takes, else the step parks as waiting.
+    #
+    # A claimed signal is consumed when its step ends, except when that
+    # attempt reattempts or fails into a pause: the next attempt runs with it.
+    module Signals
+      module_function
+
+      # Returns [record, signal]. A redelivery with a stored idempotency key
+      # returns the stored signal (duplicate_delivery? true) and does nothing
+      # else. A blank key is no key: "" would otherwise dedup every signal
+      # sent with it against the first.
+      def deliver(workflow_id, name, payload:, idempotency_key:, actor:, reason: nil)
+        name = signal_name!(name)
+        serialized = Payload.dump(payload || {}, what: "payload of signal #{name}")
+        key = idempotency_key.to_s.presence
+        Runner.locked(workflow_id) do |record, notes|
+          raise ActiveRecord::RecordNotFound, "workflow #{workflow_id} is gone" unless record
+
+          States.check!(:signal, record.status)
+          signal = WorkflowSignal.insert_signal!(workflow_id: workflow_id, name: name, payload: serialized, idempotency_key: key)
+          signal ||= duplicate(record, key)
+          received!(record, signal, actor: actor, reason: reason, notes: notes)
+          [record, signal]
+        end
+      end
+
+      # The gate of a wait_for: step. True when the body runs (with a signal,
+      # or timed out), false when the step parked. Sets received_signal and
+      # timed_out? on +workflow+.
+      def gate(record, step, definition, workflow, now: Time.current)
+        if timed_out?(step, now)
+          workflow.send(:enter_wait, signal: nil, timed_out: true)
+          return true
+        end
+
+        signal = WorkflowSignal.held_by_step(record.workflow_id, step.step_name) || match(record, definition.wait_for)
+        return park(record, step, definition, now) unless signal
+
+        claim!(record, step, signal, actor: Runner::SYSTEM_ACTOR) if signal.status == "pending"
+        step.update_columns(signal_id: signal.id) unless step.signal_id == signal.id
+        workflow.send(:enter_wait, signal: signal, timed_out: false)
+        true
+      end
+
+      # The step's attempt ended (StepOutcome.apply): consume the signal it
+      # holds, unless the next attempt runs with it.
+      def settle(step, status, column, now:)
+        return unless step.respond_to?(:signal_id) && step.signal_id
+        return if column == "reattempted" || (status == "failed" && column == "paused")
+
+        WorkflowSignal.consume!(step.signal_id, now: now)
+      end
+
+      def signal_name!(name)
+        text = name.to_s.strip
+        raise ArgumentError, "signal! needs a signal name, got #{name.inspect}" if text.empty?
+
+        -text
+      end
+
+      def duplicate(record, key)
+        WorkflowSignal.find_by!(workflow_id: record.workflow_id, idempotency_key: key).tap do |signal|
+          signal.duplicate_delivery = true
+        end
+      end
+
+      def received!(record, signal, actor:, notes:, reason: nil)
+        duplicate = signal.duplicate_delivery?
+        Runner.event!(record, "signal_received", actor: actor, reason: reason,
+                                                 details: { name: signal.name, idempotency_key: signal.idempotency_key,
+                                                            signal_id: signal.id, duplicate: duplicate }.compact)
+        woke = !duplicate && wake_waiting(record, signal, actor: actor)
+        notes.instrument("pgbus.workflow.signal",
+                         Runner.payload_for(record, name: signal.name, duplicate: duplicate, woke: woke))
+      end
+
+      def wake_waiting(record, signal, actor:) # rubocop:disable Naming/PredicateMethod -- true when it woke the step
+        step = WorkflowStep.latest_for(record.workflow_id)
+        return false unless step&.status == "waiting" && step.batch_id.nil?
+
+        definition = record.workflow_klass&.workflow_steps&.fetch(step.step_name)
+        return false unless definition&.waits_for_signal? && definition.wait_for.matches?(signal)
+
+        claim!(record, step, signal, actor: actor)
+        Waiting.wake!(record, step, now: Time.current, signal_id: signal.id)
+        true
+      end
+
+      def claim!(record, step, signal, actor:)
+        now = Time.current
+        WorkflowSignal.claim!(signal.id, step_id: step.id, now: now)
+        signal.assign_attributes(status: "claimed", claimed_by_step_id: step.id, claimed_at: now)
+        Runner.event!(record, "signal_claimed", actor: actor, step: step, details: { name: signal.name, signal_id: signal.id })
+      end
+
+      # The oldest pending signal +matcher+ takes. A SignalMatcher narrows the
+      # query to its name; any other matcher sees every pending signal.
+      def match(record, matcher)
+        name = matcher.respond_to?(:signal_name) ? matcher.signal_name : nil
+        WorkflowSignal.pending_for(record.workflow_id, name: name).find_each(batch_size: 100) do |signal|
+          return signal if matcher.matches?(signal)
+        end
+        nil
+      end
+
+      def park(record, step, definition, now) # rubocop:disable Naming/PredicateMethod -- the gate's false: the body does not run
+        timeout_at = definition.wait_timeout && (now + definition.wait_timeout)
+        Waiting.park!(record, step, now: now, wait_for: definition.wait_for_name, timeout_at: timeout_at)
+        false
+      end
+
+      # This attempt waited, holds no signal, and its wait_timeout passed: the
+      # sweep woke it with on_timeout: :run.
+      def timed_out?(step, now)
+        !step.waiting_since.nil? && step.signal_id.nil? && !step.timeout_at.nil? && step.timeout_at <= now + 1
+      end
+    end
+  end
+end

data/lib/pgbus/workflow/states.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module Pgbus
+  class Workflow
+    # The one transition table (issue #540). Every verb, the workflow states
+    # it is legal from, the state it moves the workflow to, and what it does
+    # to the step rows. The runner's guarded UPDATEs take their WHERE status
+    # IN (...) from here, available_actions (dashboard buttons, MCP tools)
+    # reads it, and the docs page lists it. Nothing else decides whether a
+    # transition is legal.
+    #
+    # Outside verbs are the ones a person or a program calls on a run
+    # (console, dashboard, MCP); runner verbs are the StepJob's and the
+    # sweep's own moves, never offered as actions.
+    module States
+      WORKFLOW = %w[ready performing waiting paused finished cancelled].freeze
+      ONGOING = %w[ready performing waiting paused].freeze
+      TERMINAL = %w[finished cancelled].freeze
+      STEP = %w[scheduled waiting in_progress completed failed cancelled skipped].freeze
+      OPEN_STEP = %w[scheduled waiting in_progress].freeze
+
+      # Why an ongoing run needs a person (the sweep's gauge, and the
+      # dashboard's needs-attention view later).
+      STUCK_REASONS = %w[paused_error stalled paused_manual overdue waiting_overdue].freeze
+
+      Transition = Data.define(:verb, :from, :to, :outside, :error, :effect)
+
+      TRANSITIONS = Ractor.make_shareable(
+        [
+          # Outside verbs
+          Transition.new(verb: :pause, from: %w[ready performing waiting], to: "paused", outside: true,
+                         error: :InvalidTransition,
+                         effect: "a running step finishes and records its outcome; nothing new is claimed"),
+          Transition.new(verb: :resume, from: %w[paused], to: "ready", outside: true, error: :NotPaused,
+                         effect: "a failed step runs again as a new attempt; a completed or skipped one is " \
+                                 "followed by the next step; a scheduled one is sent again; a waiting one waits again"),
+          Transition.new(verb: :resume_at, from: %w[paused], to: "ready", outside: true, error: :NotPaused,
+                         effect: "the named step runs as a new attempt"),
+          Transition.new(verb: :cancel, from: ONGOING, to: "cancelled", outside: true, error: :InvalidTransition,
+                         effect: "scheduled and in_progress steps are cancelled; a running step's outcome is ignored"),
+          Transition.new(verb: :run_now, from: %w[ready], to: "ready", outside: true, error: :InvalidTransition,
+                         effect: "the scheduled step's wait is cut short and it is sent now"),
+          Transition.new(verb: :reschedule, from: %w[ready], to: "ready", outside: true, error: :InvalidTransition,
+                         effect: "the scheduled step moves to the given time"),
+          Transition.new(verb: :rerun, from: TERMINAL, to: "ready", outside: true, error: :InvalidTransition,
+                         effect: "a new run starts with the same subject and arguments"),
+          Transition.new(verb: :skip, from: %w[waiting], to: "ready", outside: true, error: :InvalidTransition,
+                         effect: "the waiting step is skipped (a signal it holds is consumed) and the next step is " \
+                                 "scheduled, or the run finishes after the last"),
+          # signal leaves the state alone unless it wakes a waiting step (wake).
+          Transition.new(verb: :signal, from: ONGOING, to: nil, outside: true, error: :NotOngoing,
+                         effect: "the signal is stored; a waiting step it matches is scheduled again, otherwise it " \
+                                 "stays pending until a step claims it"),
+          # Runner verbs
+          Transition.new(verb: :claim, from: %w[ready], to: "performing", outside: false, error: :InvalidTransition,
+                         effect: "the scheduled step moves to in_progress"),
+          Transition.new(verb: :advance, from: %w[performing], to: "ready", outside: false, error: :InvalidTransition,
+                         effect: "the step is completed or skipped and the next step is scheduled"),
+          Transition.new(verb: :finish, from: %w[performing paused], to: "finished", outside: false,
+                         error: :InvalidTransition, effect: "the last step (or one that called finished!) completed"),
+          Transition.new(verb: :reattempt, from: %w[performing], to: "ready", outside: false, error: :InvalidTransition,
+                         effect: "the step failed and its next attempt is scheduled"),
+          Transition.new(verb: :step_pause, from: %w[performing], to: "paused", outside: false,
+                         error: :InvalidTransition,
+                         effect: "the step completed after pause!, or failed (an exception or a stall)"),
+          Transition.new(verb: :step_cancel, from: %w[performing paused], to: "cancelled", outside: false,
+                         error: :InvalidTransition, effect: "the step called cancel!, or cancel_if or a policy cancelled it"),
+          Transition.new(verb: :unpause, from: %w[paused], to: "performing", outside: false, error: :NotPaused,
+                         effect: "resume! while the step that was running at the outside pause! is still running: " \
+                                 "the run goes on performing it"),
+          Transition.new(verb: :hold, from: %w[paused], to: "paused", outside: false, error: :InvalidTransition,
+                         effect: "an outcome that arrived after an outside pause!: recorded on the step; a " \
+                                 "completed, skipped or reattempted step has its next row scheduled; the workflow " \
+                                 "stays paused"),
+          Transition.new(verb: :park, from: %w[performing], to: "waiting", outside: false, error: :InvalidTransition,
+                         effect: "the step waits for a matching signal or for its fan-out batch; nothing is sent " \
+                                 "until it is woken"),
+          Transition.new(verb: :wake, from: %w[waiting], to: "ready", outside: false, error: :InvalidTransition,
+                         effect: "a matching signal arrived, or the wait timed out with on_timeout: :run: the " \
+                                 "waiting step is scheduled again"),
+          Transition.new(verb: :resolve, from: %w[waiting], to: "performing", outside: false,
+                         error: :InvalidTransition,
+                         effect: "the fan-out batch finished, the wait timed out, or an operator skipped the step: " \
+                                 "its outcome is applied as for a finished attempt"),
+          Transition.new(verb: :rewait, from: %w[paused], to: "waiting", outside: false, error: :NotPaused,
+                         effect: "resume! on a run paused while its step was waiting: it waits again")
+        ].to_h { |transition| [transition.verb, transition] }
+      )
+
+      module_function
+
+      def fetch(verb)
+        TRANSITIONS.fetch(verb.to_sym) { raise ArgumentError, "unknown workflow verb #{verb.inspect}" }
+      end
+
+      def from(verb) = fetch(verb).from
+
+      def to(verb) = fetch(verb).to
+
+      def legal?(verb, status) = from(verb).include?(status.to_s)
+
+      # Returns the target state, or raises the verb's documented error.
+      def check!(verb, status)
+        transition = fetch(verb)
+        return transition.to if transition.from.include?(status.to_s)
+
+        raise Workflow.const_get(transition.error),
+              "cannot #{verb.to_s.tr("_", " ")} a #{status} workflow (allowed from: #{transition.from.join(", ")})"
+      end
+
+      # The outside verbs legal in +status+: the dashboard's buttons and the
+      # MCP write tools.
+      def available_actions(status)
+        state = status.to_s
+        TRANSITIONS.each_value.select { |transition| transition.outside && transition.from.include?(state) }.map(&:verb)
+      end
+    end
+  end
+end

data/lib/pgbus/workflow/step_context.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Pgbus
+  class Workflow
+    # The workflow step running in this fiber, while its body runs:
+    #
+    #   Pgbus::Workflow::StepContext.workflow_id   # => "6f1c…" (nil outside a step)
+    #   Rails.logger.tagged("wf=#{Pgbus::Workflow::StepContext.workflow_id}") { ... }
+    #
+    # Not named Current: every constant under Pgbus::Workflow is visible from
+    # a workflow subclass's step bodies, and a bare `Current` there must stay
+    # the app's ActiveSupport::CurrentAttributes.
+    #
+    # Fiber-local (Thread.current[] is per fiber), saved and restored around
+    # each step so a nested or concurrent step never sees another's context.
+    # Pgbus's own log lines inside a step carry workflow=… step=… attempt=…
+    # through Pgbus::LogFormatter's context.
+    module StepContext
+      KEY = :pgbus_workflow_step_context
+
+      # The running step, as the fiber-local value.
+      Frame = Data.define(:workflow_id, :workflow_class, :step_name, :attempt)
+
+      # Which attempt a workflow instance is running its body for. Set by the
+      # StepJob on the fresh instance it runs the body on, never by app code.
+      Attempt = Data.define(:step_id, :step_name, :attempt)
+
+      module_function
+
+      def with(workflow_id:, workflow_class:, step_name:, attempt:, &)
+        previous = Thread.current[KEY]
+        Thread.current[KEY] = Frame.new(workflow_id: workflow_id, workflow_class: workflow_class,
+                                        step_name: step_name, attempt: attempt)
+        LogFormatter.with_context(workflow: workflow_id, step: step_name, attempt: attempt, &)
+      ensure
+        Thread.current[KEY] = previous
+      end
+
+      def context = Thread.current[KEY]
+
+      def workflow_id = context&.workflow_id
+
+      def workflow_class = context&.workflow_class
+
+      def step_name = context&.step_name
+
+      def attempt = context&.attempt
+
+      # "workflow=… step=… attempt=…" for a log line, or "" outside a step.
+      def log_tag
+        current = context
+        return "" unless current
+
+        "workflow=#{current.workflow_id} step=#{current.step_name} attempt=#{current.attempt}"
+      end
+    end
+  end
+end

data/lib/pgbus/workflow/step_definition.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module Pgbus
+  class Workflow
+    # One declared step: its name, its body (a block or the name of an
+    # instance method) and its options. Built and validated when the class
+    # body runs, so a bad option fails at load, not on the first run.
+    class StepDefinition
+      OPTIONS = %i[wait skip_if job_options timeout on_exception wait_for wait_timeout on_timeout].freeze
+      # What a wait_for: step does when its wait_timeout: passes first.
+      ON_TIMEOUT = %i[pause! cancel! skip! run notify].freeze
+      # The values written without a bang (they do not end the wait as a verb would).
+      PLAIN_ON_TIMEOUT = %w[run notify].freeze
+      # The StepJob options a class (set_step_job_options) or a step
+      # (job_options:) may set. Anything else raises at class load.
+      JOB_OPTIONS = %i[queue priority wait wait_until].freeze
+
+      attr_reader :name, :body, :wait, :skip_if, :job_options, :timeout, :exception_policies,
+                  :wait_for, :wait_for_name, :wait_timeout, :on_timeout
+
+      def self.validate_job_options!(options)
+        raise ArgumentError, "job_options: must be a Hash, got #{options.inspect}" unless options.is_a?(Hash)
+
+        options.to_h do |key, value|
+          key = key.to_sym
+          unless JOB_OPTIONS.include?(key)
+            raise ArgumentError,
+                  "unknown job_options: #{key.inspect} — accepted: #{JOB_OPTIONS.map(&:inspect).join(", ")}"
+          end
+
+          [key, job_option_value(key, value)]
+        end.freeze
+      end
+
+      def self.job_option_value(key, value)
+        case key
+        when :queue
+          raise ArgumentError, "job_options: queue must be a queue name, got #{value.inspect}" if value.to_s.strip.empty?
+
+          -value.to_s
+        when :priority
+          return value if value.is_a?(Integer)
+
+          raise ArgumentError, "job_options: priority must be an Integer, got #{value.inspect}"
+        when :wait then seconds(value, "job_options: wait", positive: false)
+        when :wait_until
+          # Time, DateTime and TimeWithZone; not a String, which ActiveSupport
+          # also gives #to_time (nil for an unparseable one).
+          return value.to_time if value.respond_to?(:to_time) && !value.is_a?(String) && value.to_time
+
+          raise ArgumentError, "job_options: wait_until must be a Time, got #{value.inspect}"
+        else value
+        end
+      end
+
+      # Seconds as an Integer when whole, else a Float. Durations are
+      # accepted; nil stays nil.
+      def self.seconds(value, option, positive:)
+        return nil if value.nil?
+
+        seconds = duration?(value) ? value.to_f : value
+        unless seconds.is_a?(Numeric) && seconds.real? && seconds.finite? && (positive ? seconds.positive? : !seconds.negative?)
+          requirement = positive ? "a positive" : "a non-negative"
+          raise ArgumentError, "#{option}: must be #{requirement} number of seconds or a Duration, got #{value.inspect}"
+        end
+
+        seconds == seconds.to_i ? seconds.to_i : seconds.to_f
+      end
+
+      def self.duration?(value)
+        defined?(ActiveSupport::Duration) && value.is_a?(ActiveSupport::Duration)
+      end
+
+      def initialize(name:, body:, wait: nil, skip_if: nil, job_options: {}, timeout: nil, on_exception: nil,
+                     wait_for: nil, wait_timeout: nil, on_timeout: nil)
+        @name = -name.to_s
+        @body = body
+        @wait = self.class.seconds(wait, "wait", positive: false) || 0
+        @skip_if = validate_skip_if(skip_if)
+        @job_options = self.class.validate_job_options!(job_options.nil? ? {} : job_options)
+        @timeout = self.class.seconds(timeout, "timeout", positive: true)
+        @exception_policies = ExceptionPolicy.coerce_all(on_exception)
+        assign_wait(wait_for, wait_timeout, on_timeout)
+        freeze
+      end
+
+      def kind = "step"
+
+      # True for a wait_for: step: it parks until a matching signal arrives.
+      def waits_for_signal? = !wait_for.nil?
+
+      def removed? = false
+
+      # Runs the body on +workflow+; the return value is ignored.
+      def invoke(workflow)
+        body.is_a?(Symbol) ? workflow.send(body) : workflow.instance_exec(&body)
+        nil
+      end
+
+      def skip?(workflow)
+        return false if skip_if.nil?
+
+        result = skip_if.is_a?(Symbol) ? workflow.send(skip_if) : workflow.instance_exec(&skip_if)
+        result ? true : false
+      end
+
+      private
+
+      def assign_wait(wait_for, wait_timeout, on_timeout)
+        @wait_for = wait_for.nil? ? nil : SignalMatcher.coerce(wait_for)
+        @wait_for_name = @wait_for && SignalMatcher.label(@wait_for)
+        raise ArgumentError, "on_timeout: needs wait_for: and wait_timeout:" if !on_timeout.nil? && (@wait_for.nil? || wait_timeout.nil?)
+        raise ArgumentError, "wait_timeout: needs wait_for: (it bounds the wait for a signal)" if wait_timeout && @wait_for.nil?
+
+        @wait_timeout = self.class.seconds(wait_timeout, "wait_timeout", positive: true)
+        @on_timeout = @wait_timeout && normalize_on_timeout(on_timeout.nil? ? :pause! : on_timeout)
+      end
+
+      def normalize_on_timeout(value)
+        verb = PLAIN_ON_TIMEOUT.include?(value.to_s) ? value.to_sym : :"#{value.to_s.delete_suffix("!")}!"
+        return verb if ON_TIMEOUT.include?(verb)
+
+        raise ArgumentError, "on_timeout: must be one of #{ON_TIMEOUT.map(&:inspect).join(", ")}, got #{value.inspect}"
+      end
+
+      def validate_skip_if(value)
+        return value if value.nil? || value.is_a?(Symbol) || value.is_a?(Proc)
+
+        raise ArgumentError, "skip_if: must be a lambda, a Proc or a method name, got #{value.inspect}"
+      end
+    end
+  end
+end