rigid_workflow 1.0.0

data/app/models/rigid_workflow/run.rb

@@ -0,0 +1,209 @@
+# frozen_string_literal: true
+
+require "active_record"
+require "action_view"
+
+module RigidWorkflow
+  # Represents an execution of a workflow.
+  class Run < ::ActiveRecord::Base
+    self.table_name = "rigid_workflow_runs"
+
+    has_many :steps,
+             class_name: "RigidWorkflow::Step",
+             foreign_key: "rigid_workflow_run_id",
+             dependent: :destroy
+    has_many :signals,
+             class_name: "RigidWorkflow::Signal",
+             foreign_key: "rigid_workflow_run_id",
+             dependent: :destroy
+
+    def memory
+      super || {}
+    end
+
+    def memory=(value)
+      raise "Immutable once finished" if finished?
+      super(value)
+    end
+
+    def read_only?
+      completed?
+    end
+
+    before_create :generate_uuid
+
+    enum :status,
+         {
+           pending: "pending",
+           running: "running",
+           completed: "completed",
+           failed: "failed",
+           compensating: "compensating"
+         },
+         default: :pending
+
+    OPEN_STATES = %w[pending running compensating].freeze
+
+    def finished?
+      completed? || failed?
+    end
+
+    def duration
+      return nil if started_at.nil? || finished_at.nil?
+
+      finished_at - started_at
+    end
+
+    validates :workflow_class, presence: true
+    validates :version,
+              presence: true,
+              numericality: {
+                only_integer: true,
+                greater_than: 0
+              }
+
+    def start!
+      self.status = :running
+      self.started_at = Time.current
+      save!(context: :state_change)
+    end
+
+    def finish!
+      RigidWorkflow.instrument("workflow.complete", run_id: id) do
+        self.status = :completed
+        self.finished_at = Time.current
+        save!(context: :state_change)
+        cleanup_signals!
+      end
+    end
+
+    def fail!
+      RigidWorkflow.instrument("workflow.fail", run_id: id) do
+        self.status = :failed
+        save!(context: :state_change)
+        cleanup_signals!
+      end
+    end
+
+    def compensate!
+      # Set status to compensating BEFORE transaction so it persists on failure
+      update!(status: :compensating) unless compensating?
+
+      transaction do
+        # Find completed steps in reverse order (last completed = first to compensate)
+        steps
+          .where(status: :completed)
+          .order(id: :desc)
+          .find_each do |step|
+            activity_class = step.activity_class.constantize
+            activity = activity_class.new(step)
+            activity.compensate
+            step.update!(status: :compensated)
+          end
+      end
+
+      # If we get here, compensation succeeded
+      update!(status: :failed)
+    rescue => error
+      # If compensation fails mid-way, run stays :compensating (NOT failed)
+      raise error
+    end
+
+    def retry!
+      raise "Workflow cannot be retried when #{status}" unless failed? || running?
+
+      transaction do
+        self.status = :running
+        save!(context: :state_change)
+
+        failed_steps = steps.where(status: :failed)
+        failed_steps.each do |step|
+          step.update!(status: :pending)
+        end
+        failed_step_ids = failed_steps.pluck(:id)
+        failed_step_ids.each do |step_id|
+          RigidWorkflow.instrument("step.retry", run_id: id, step_id: step_id)
+        end
+
+        Orchestrator.schedule(self)
+      end
+    end
+
+    def cancel!
+      raise "Workflow is already finished" if finished?
+
+      transaction do
+        self.status = :failed
+        save!(context: :state_change)
+        # ActiveJob::Base.limits_concurrency ensures only one ActivityJob
+        # runs per step_id at a time, so race condition on attempt
+        # creation is not possible for a single step.
+        open_steps = steps.where(status: OPEN_STATES).includes(:attempts)
+        open_step_ids = open_steps.pluck(:id)
+        open_steps.each do |step|
+          step.attempts.last&.update!(
+            status: :failed,
+            error_details: {
+              "message" => "canceled"
+            }
+          )
+          step.update!(status: :failed)
+        end
+        open_step_ids.each do |step_id|
+          RigidWorkflow.instrument(
+            "step.canceled",
+            run_id: id,
+            step_id: step_id,
+            reason: "canceled"
+          )
+        end
+        cleanup_signals!
+      end
+    end
+
+    def self.bulk_apply(ids, action)
+      runs = where(id: ids)
+      results = { success: [], failed: [] }
+
+      runs.each do |run|
+        begin
+          run.send("#{action}!")
+          results[:success] << run.id
+        rescue StandardError => error
+          results[:failed] << { id: run.id, error: error.message }
+        end
+      end
+
+      results
+    end
+
+    def cleanup_signals!
+      now = Time.current
+      signals
+        .where(received_at: nil, canceled_at: nil)
+        .where("expires_at IS NULL OR expires_at > ?", now)
+        .update_all(canceled_at: now)
+    end
+
+    def emit_signal(name, payload = {})
+      signal = signals.where(name: name).first!
+      RigidWorkflow::Signal.process!(signal, payload)
+    end
+
+    def self.filter_runs(statuses = nil, workflow_class: nil)
+      relation = self.where(created_at: 1.month.ago..)
+      relation = relation.where(status: statuses) if statuses.present?
+      relation =
+        relation.where(
+          workflow_class: workflow_class
+        ) if workflow_class.present?
+      relation.order(created_at: :desc)
+    end
+
+    private
+
+    def generate_uuid
+      self.id ||= RigidWorkflow::IdGenerator.uuid_v7
+    end
+  end
+end

data/app/models/rigid_workflow/signal.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module RigidWorkflow
+  # Represents a signal for inter-step communication.
+  # Supports waiting with optional timeout and payload exchange.
+  class Signal < ::ActiveRecord::Base
+    self.table_name = "rigid_workflow_signals"
+
+    belongs_to :workflow_run,
+               class_name: "RigidWorkflow::Run",
+               foreign_key: "rigid_workflow_run_id"
+
+    before_create :generate_uuid
+
+    scope :pending,
+          lambda {
+            where(received_at: nil, canceled_at: nil).where(
+              "expires_at IS NULL OR expires_at > ?",
+              Time.current
+            )
+          }
+    scope :received, -> { where.not(received_at: nil) }
+    scope :expired,
+          -> do
+            where(received_at: nil, canceled_at: nil).where(
+              "expires_at <= ?",
+              Time.current
+            )
+          end
+    scope :canceled, -> { where.not(canceled_at: nil) }
+
+    def received?
+      received_at.present?
+    end
+
+    def expired?
+      expires_at.present? && expires_at <= Time.current
+    end
+
+    def self.process!(signal, payload)
+      return if signal.received?
+
+      signal.update!(received_at: Time.current, payload: payload)
+      RigidWorkflow.instrument(
+        "signal.received",
+        run_id: signal.rigid_workflow_run_id,
+        signal_id: signal.id,
+        signal_name: signal.name
+      )
+      Orchestrator.schedule(signal.workflow_run)
+    end
+
+    # Class methods for processing signals.
+
+    class << self # Processes a signal and resumes the workflow if applicable.
+      # @param signal_id [Integer] The signal ID to process
+      # @return [Boolean] True if signal was processed successfully
+      def process_signal(signal_id)
+        signal = RigidWorkflow::Signal.find_by(id: signal_id)
+        return false if signal.nil? || signal.received?
+
+        run = signal.workflow_run
+        return false if !run.present? || run.finished?
+
+        signal.update!(received_at: Time.current)
+        RigidWorkflow::Orchestrator.schedule(run)
+        true
+      end
+    end
+
+    private
+
+    def generate_uuid
+      self.id ||= RigidWorkflow::IdGenerator.uuid_v7
+    end
+  end
+end

data/app/models/rigid_workflow/step.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+module RigidWorkflow
+  # Represents a single step within a workflow execution.
+  # Tracks activity class, status, input/output, and retry attempts.
+  class Step < ::ActiveRecord::Base
+    self.table_name = "rigid_workflow_steps"
+
+    belongs_to :workflow_run,
+               class_name: "RigidWorkflow::Run",
+               foreign_key: "rigid_workflow_run_id"
+
+    has_many :attempts,
+             class_name: "RigidWorkflow::StepAttempt",
+             foreign_key: "rigid_workflow_step_id",
+             dependent: :destroy
+
+    before_create :generate_uuid
+
+    enum :status,
+         {
+           pending: "pending",
+           enqueued: "enqueued",
+           running: "running",
+           waiting: "waiting",
+           completed: "completed",
+           failed: "failed",
+           compensating: "compensating",
+           compensated: "compensated"
+         },
+         default: :pending
+
+    validates :step_name, presence: true
+    validates :activity_class, presence: true
+
+    def completed?
+      status == "completed"
+    end
+
+    def attempt_count
+      attempts.count
+    end
+
+    def current_attempt
+      attempts.last
+    end
+
+    def output
+      current_attempt&.output || {}
+    end
+
+    def error_details
+      current_attempt&.error_details
+    end
+
+    def started_at
+      current_attempt&.started_at
+    end
+
+    def finished_at
+      current_attempt&.finished_at
+    end
+
+    def failed_at
+      current_attempt&.failed_at
+    end
+
+    def start!
+      pending_attempt = attempts.where(status: :pending).last
+      if pending_attempt
+        pending_attempt.update!(
+          status: :running,
+          started_at: Time.current
+        )
+      else
+        attempts.create!(
+          attempt_number: attempts.count + 1,
+          status: :running,
+          input: input,
+          started_at: Time.current
+        )
+      end
+      update!(status: :running)
+    end
+
+    def complete!(output = {})
+      RigidWorkflow.instrument(
+        "step.complete",
+        run_id: rigid_workflow_run_id,
+        step_id: id
+      ) do
+        safe_output =
+          if output.nil?
+            {}
+          elsif !output.is_a?(Hash)
+            { result: output }
+          else
+            output
+          end
+        current_attempt&.update!(
+          status: :completed,
+          finished_at: Time.current,
+          output: safe_output
+        )
+        update!(status: :completed)
+      end
+    end
+
+    def fail!(error_details = {})
+      RigidWorkflow.instrument(
+        "step.fail",
+        run_id: rigid_workflow_run_id,
+        step_id: id
+      ) do
+        current_attempt&.update!(
+          status: :failed,
+          failed_at: Time.current,
+          error_details: error_details
+        )
+        update!(status: :failed)
+      end
+    end
+
+    # Class methods for executing activities.
+    class << self
+      # Executes an activity for a given step.
+      # @param step_id [Integer] The step ID to execute
+      # @return [Object, false] The activity result or false if not runnable
+      def execute_activity(step_id)
+        step =
+          RigidWorkflow::Step.includes(:workflow_run, :attempts).find_by_id(
+            step_id
+          )
+        return false if step.nil? || step.completed?
+
+        workflow_run = step.workflow_run
+        return false unless workflow_run
+        return false unless runnable?(workflow_run)
+
+        step.start!
+
+        # brakeman:ignore UnsafeReflection
+        # This is intentional - activity_class is a validated string from the workflow definition
+        activity_class = step.activity_class.constantize
+        unless activity_class && activity_class < RigidWorkflow::Activity
+          raise ArgumentError, "#{step.activity_class} is not a valid Activity"
+        end
+
+        activity = activity_class.new(step)
+
+        input = step.input.deep_symbolize_keys
+        result = activity.perform(**input)
+
+        step.complete!(result)
+
+        RigidWorkflow::Orchestrator.schedule(workflow_run)
+        result
+      rescue StandardError => error
+        step.fail!(
+          error: error.class.to_s,
+          message: error.message,
+          backtrace: error.backtrace&.first(5)
+        )
+        # Schedule workflow advancement to handle retries or mark workflow as failed (Bug 3 fix)
+        if workflow_run && !workflow_run.finished?
+          RigidWorkflow::Orchestrator.schedule(workflow_run)
+        end
+        raise error
+      end
+
+      def runnable?(workflow_run)
+        workflow_run.present? && !workflow_run.finished?
+      end
+    end
+
+    private
+
+    def generate_uuid
+      self.id ||= RigidWorkflow::IdGenerator.uuid_v7
+    end
+  end
+end

data/app/models/rigid_workflow/step_attempt.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module RigidWorkflow
+  # Represents a single execution attempt of a step.
+  # Tracks attempt-specific status, input/output, and error details.
+  #
+  # Step ↔ StepAttempt Relationship:
+  #
+  # Step (1) ──── (has_many) ────> StepAttempt (N)
+  #   - step_name                           - attempt_number
+  #   - activity_class                       - status
+  #   - input                               - input
+  #   - status                              - output
+  #   - max_attempts                        - error_details
+  #   - scheduled_at                        - started_at
+  #                                          - finished_at
+  #                                          - failed_at
+  #
+  # Query current state: step.current_attempt
+  # Query history: step.attempts
+  class StepAttempt < ::ActiveRecord::Base
+    self.table_name = "rigid_workflow_step_attempts"
+
+    belongs_to :step,
+               class_name: "RigidWorkflow::Step",
+               foreign_key: "rigid_workflow_step_id"
+
+    before_create :generate_uuid
+
+    enum :status,
+         {
+           pending: "pending",
+           running: "running",
+           completed: "completed",
+           failed: "failed"
+         },
+         default: :running
+
+    validates :rigid_workflow_step_id, presence: true
+    validates :attempt_number, presence: true, numericality: { greater_than: 0 }
+
+    private
+
+    def generate_uuid
+      self.id ||= RigidWorkflow::IdGenerator.uuid_v7
+    end
+  end
+end

data/app/views/rigid_workflow/layouts/application.html.erb

@@ -0,0 +1,77 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title><%= content_for(:title) || "RigidWorkflow Admin" %></title>
+    <meta name="viewport" content="width=device-width,initial-scale=1">
+    <meta name="apple-mobile-web-app-capable" content="yes">
+    <meta name="application-name" content="RigidWorkflow Admin">
+    <meta name="mobile-web-app-capable" content="yes">
+    <%= csrf_meta_tags %>
+    <%= csp_meta_tag %>
+
+    <%= yield :head %>
+
+    <%# Enable PWA manifest for installable apps (make sure to enable in config/routes.rb too!) %>
+    <%#= tag.link rel: "manifest", href: pwa_manifest_path(format: :json) %>
+
+    <link rel="icon" href="/icon.png" type="image/png">
+    <link rel="icon" href="/icon.svg" type="image/svg+xml">
+    <link rel="apple-touch-icon" href="/icon.png">
+
+    <%# Includes all stylesheet files %>
+    <%= stylesheet_link_tag "rigid_workflow/application", "data-turbo-track": "reload" %>
+
+    <%# Use blocking script for tailwind and vis-timeline to prevent reflow and repaint %>
+    <script src="https://cdn.jsdelivr.net/npm/@tailwindcss/browser@4" defer></script>
+    <script src="https://cdn.jsdelivr.net/npm/vis-timeline@latest/standalone/umd/vis-timeline-graph2d.min.js" defer></script>
+
+    <%# Includes all javascript files %>
+    <%= javascript_importmap_tags "rigid_workflow/application" %>
+  </head>
+
+  <body class="bg-gray-50 text-gray-900 font-sans leading-normal tracking-normal transition-colors duration-500 min-h-screen">
+
+    <main class="min-h-screen">
+      <div id="flash-messages" class="fixed top-0 left-0 w-full h-full justify-center items-end z-50 pb-10 flex gap-2 pointer-events-none animate-fade-in-up">
+        <% if notice %>
+          <div class="p-4 bg-green-50 border border-green-300 text-green-700 rounded-2xl shadow-lg shadow-green-100/50">
+            <%= notice %>
+          </div>
+        <% end %>
+        <% if alert %>
+          <div class="p-4 bg-red-50 border border-red-300 text-red-700 rounded-2xl shadow-lg shadow-red-100/50">
+            <%= alert %>
+          </div>
+        <% end %>
+      </div>
+
+      <div class="flex min-h-screen">
+        <aside class="w-64 bg-gray-200/75 border-r border-gray-300">
+          <% @sidebar.each do |section| %>
+            <div class="m-4 mb-0">
+              <h2 class="text-xs font-semibold text-gray-400 uppercase tracking-wider"><%= section[:heading] %></h2>
+            </div>
+            <nav class="mt-2 px-3 mb-6 text-gray-700 ">
+              <% section[:items].each do |item| %>
+                <%= link_to item[:path], data: { turbo_frame: "_top" }, class: "nav-item flex justify-between items-center px-3 py-2 rounded-lg text-sm font-medium transition-colors #{'bg-gray-300 text-gray-900' if  current_page?(item[:path])}" do %>
+                  <span><%= item[:name] %></span>
+                  <% if item[:count] %>
+                    <span class="ml-2 bg-gray-100 text-gray-500 rounded-full px-2 py-0.5 text-xs font-mono">
+                      <%= number_with_delimiter(item[:count]) %>
+                    </span>
+                  <% end %>
+                <% end %>
+              <% end %>
+            </nav>
+          <% end %>
+        </aside>
+
+        <div class="grow">
+          <%= yield %>
+        </div>
+      </div>
+    </main>
+
+  </body>
+</html>
+