active_durable 0.5.0

data/app/controllers/active_durable/executions_controller.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module ActiveDurable
+  # Lists executions, shows their notebook and runs the operator actions.
+  class ExecutionsController < ApplicationController
+    PER_PAGE = 50
+
+    rescue_from ActiveDurable::Error do |error|
+      redirect_to execution_path(params[:id]), alert: error.message
+    end
+
+    def index
+      @page = [params[:page].to_i, 1].max
+      rows = filtered_executions.offset((@page - 1) * PER_PAGE).limit(PER_PAGE + 1).to_a
+      @next_page = rows.size > PER_PAGE
+      @executions = rows.first(PER_PAGE)
+      @steps_by_execution = Step.where(execution_id: @executions.map(&:id)).order(:id).group_by(&:execution_id)
+      @counts = Execution.group(:status).count
+      @recipes = Execution.distinct.order(:recipe).pluck(:recipe)
+    end
+
+    def show
+      @execution = Execution.find(params[:id])
+      steps = @execution.steps.to_a
+      @steps = steps
+      @forward_steps = steps.reject(&:undo?).sort_by { |step| step.position.to_i }
+      @undo_steps = steps.select(&:undo?)
+      @signals = @execution.signals.to_a
+      @reruns = Execution.where(forked_from: @execution.id).order(:created_at).to_a
+    end
+
+    def retry_now
+      ActiveDurable.retry(params[:id])
+      redirect_to execution_path(params[:id]), notice: "Retrying. Failed steps got a fresh set of attempts."
+    end
+
+    def compensate
+      ActiveDurable.compensate(params[:id], reason: "Compensated from the dashboard")
+      redirect_to execution_path(params[:id]), notice: "Compensation started."
+    end
+
+    def rerun
+      execution = ActiveDurable.rerun(params[:id], from: params.require(:from))
+      redirect_to execution_path(execution), notice: "New execution started from :#{params[:from]}."
+    end
+
+    private
+
+    def filtered_executions
+      scope = Execution.order(updated_at: :desc)
+      @status = params[:status].presence_in(Execution::STATUSES)
+      scope = scope.where(status: @status) if @status
+      @recipe = params[:recipe].presence
+      scope = scope.where(recipe: @recipe) if @recipe
+      @query = params[:q].to_s.strip
+      @query.present? ? scope.where("id LIKE ?", "%#{Execution.sanitize_sql_like(@query)}%") : scope
+    end
+  end
+end

data/app/helpers/active_durable/dashboard_helper.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+module ActiveDurable
+  # View helpers for the dashboard.
+  module DashboardHelper
+    # One block of the track: a step (or a parallel group) and the state it is drawn in.
+    TrackItem = Struct.new(:name, :kind, :state, :step, :branches, keyword_init: true)
+
+    STATUS_TONES = {
+      "completed" => "good", "compensated" => "undo", "blocked" => "bad", "superseded" => "muted",
+      "running" => "busy", "pending" => "busy", "sleeping" => "wait", "waiting" => "wait",
+      "retrying" => "wait", "failed" => "bad", "undone" => "undo"
+    }.freeze
+
+    STATUS_WORDS = {
+      "pending" => "Queued", "running" => "Running", "sleeping" => "Sleeping", "waiting" => "Waiting",
+      "completed" => "Completed", "compensated" => "Undone", "blocked" => "Needs a person",
+      "superseded" => "Superseded"
+    }.freeze
+
+    def status_pill(status)
+      tag.span(status, class: "pill pill-#{STATUS_TONES.fetch(status.to_s, "muted")}")
+    end
+
+    def status_counts
+      @status_counts ||= Execution.group(:status).count
+    end
+
+    def recipe_names
+      @recipe_names ||= Execution.distinct.order(:recipe).pluck(:recipe)
+    end
+
+    def json_preview(value, limit: 160)
+      return tag.span("—", class: "muted") if value.nil?
+
+      text = value.to_json
+      text = "#{text[0, limit]}…" if text.length > limit
+      tag.code(text, class: "json")
+    end
+
+    def pretty_json(value)
+      return tag.p("Nothing yet.", class: "muted") if value.nil?
+
+      tag.pre(JSON.pretty_generate(value), class: "json-block")
+    end
+
+    # Absolute time, rewritten by the page script as "3 min ago" / "in 2 h".
+    def when_text(time)
+      return tag.span("—", class: "muted") if time.nil?
+
+      absolute = time.utc.strftime("%Y-%m-%d %H:%M:%S UTC")
+      tag.time(absolute, datetime: time.utc.iso8601, title: absolute, data: { relative: true })
+    end
+
+    # Lets long step names wrap after an underscore instead of in the middle of a word.
+    def breakable(name)
+      safe_join(name.to_s.split(/(?<=_)/), tag.wbr)
+    end
+
+    def ticket_for(execution, step)
+      "#{execution.id}:#{step.name}"
+    end
+
+    def compensating_now?(execution)
+      execution.compensating && execution.status != "compensated"
+    end
+
+    # The first step that did not complete: rerunning from earlier would repeat work that succeeded.
+    def rerun_default(steps)
+      (steps.find { |step| !step.completed? } || steps.last).name
+    end
+
+    def can_retry?(execution)
+      execution.status == "blocked"
+    end
+
+    def can_compensate?(execution, steps)
+      %w[blocked pending running sleeping waiting].include?(execution.status) && !execution.compensating &&
+        steps.none? { |step| step.kind == "pivot" && step.completed? }
+    end
+
+    def can_rerun?(execution)
+      execution.status == "completed" || (execution.status == "blocked" && !execution.compensating)
+    end
+
+    # Turns a notebook into the blocks of the track, in recipe order. Parallel branches are grouped under
+    # their parallel step, undone steps are marked, and an active execution gets a "next" ghost block.
+    def track_items(execution, steps)
+      undone = steps.select { |step| step.undo? && step.completed? }.to_set { |step| step.name.delete_suffix(":undo") }
+      branches, main = steps.reject(&:undo?).partition { |step| step.position.nil? }
+
+      items = main.sort_by(&:position).map do |step|
+        build_item(step, undone, branches.select { |branch| branch.name.start_with?("#{step.name}/") })
+      end
+      items.concat(unfinished_parallel_groups(main, branches, undone))
+      items << TrackItem.new(name: "next", kind: "ghost", state: "next", step: nil, branches: []) if moving?(execution)
+      items
+    end
+
+    # Undo entries in the order they ran (last step first).
+    def undo_lane(steps)
+      steps.select(&:undo?).sort_by { |step| [step.updated_at, step.id] }
+    end
+
+    def item_title(item)
+      attempts = item.step&.attempts.to_i
+      [item.name, item.kind, state_word(item.state), ("#{attempts} attempts" if attempts > 1)].compact.join(", ")
+    end
+
+    def state_word(state)
+      {
+        "completed" => "done", "failed" => "failed", "retrying" => "retrying", "waiting" => "waiting for a signal",
+        "sleeping" => "sleeping", "undone" => "undone", "next" => "up next", "running" => "running"
+      }.fetch(state.to_s, state.to_s)
+    end
+
+    # When the block wakes up (retry, sleep or wait timeout), for the countdowns.
+    def item_wake_at(item)
+      step = item.step
+      return nil unless step
+      return Time.iso8601(step.result["wake_at"]) if step.kind == "sleep" && step.result.is_a?(Hash)
+
+      step.wake_at
+    rescue ArgumentError
+      nil
+    end
+
+    private
+
+    # Branches of a flow.parallel whose own entry is not written yet (it is written when every branch ends).
+    def unfinished_parallel_groups(main, branches, undone)
+      recorded = main.to_set(&:name)
+      branches.group_by { |branch| branch.name.split("/", 2).first }.filter_map do |group, kids|
+        next if recorded.include?(group)
+
+        TrackItem.new(name: group, kind: "parallel", state: "running", step: nil,
+                      branches: kids.map { |kid| build_item(kid, undone, []) })
+      end
+    end
+
+    def moving?(execution)
+      %w[pending running].include?(execution.status) && !execution.compensating
+    end
+
+    def build_item(step, undone, kids)
+      TrackItem.new(name: step.name.split("/", 2).last, kind: step.kind, state: step_state(step, undone), step: step,
+                    branches: kids.map { |kid| build_item(kid, undone, []) })
+    end
+
+    def step_state(step, undone)
+      return "undone" if undone.include?(step.name)
+      return "sleeping" if step.kind == "sleep" && sleeping?(step)
+
+      step.status
+    end
+
+    def sleeping?(step)
+      step.result.is_a?(Hash) && Time.iso8601(step.result.fetch("wake_at", "")) > Time.current
+    rescue ArgumentError
+      false
+    end
+  end
+end

data/app/views/active_durable/executions/index.html.erb

@@ -0,0 +1,90 @@
+<% content_for :title, "Executions" %>
+<% blocked = @counts["blocked"].to_i %>
+<% moving = ActiveDurable::Execution::ACTIVE.sum { |status| @counts[status].to_i } %>
+
+<header class="stage-head">
+  <div>
+    <h1><%= @status ? ActiveDurable::DashboardHelper::STATUS_WORDS[@status] : "Executions" %><%= " in #{@recipe}" if @recipe %></h1>
+    <p class="lede" data-live-summary>
+      <% if blocked.positive? %>
+        <strong class="error"><%= pluralize(blocked, "saga") %> <%= blocked == 1 ? "needs" : "need" %> a person.</strong>
+      <% end %>
+      <%= moving.zero? ? "Nothing is in progress." : "#{pluralize(moving, "saga")} in progress." %>
+      <%= pluralize(@counts.values.sum, "execution") %> in total.
+    </p>
+  </div>
+  <div class="tools">
+    <%= form_with url: executions_path, method: :get, class: "inline", local: true do %>
+      <%= hidden_field_tag :status, @status if @status %>
+      <%= select_tag :recipe, options_for_select([["All recipes", ""]] + @recipes, @recipe), id: "recipe-filter", "aria-label": "Recipe" %>
+      <%= search_field_tag :q, @query, placeholder: "Execution id contains…", id: "id-filter", "aria-label": "Execution id" %>
+      <button type="submit">Filter</button>
+    <% end %>
+    <button type="button" class="live" data-live-toggle aria-pressed="false">
+      <span class="led" aria-hidden="true"></span><span data-live-label>Paused</span>
+    </button>
+  </div>
+</header>
+
+<section class="sheet" data-live-region>
+  <% if @executions.empty? %>
+    <div class="empty">
+      <div class="mini" aria-hidden="true"><i class="b st-next"></i><i class="b st-next"></i><i class="b st-next"></i></div>
+      <p><strong>No executions here yet.</strong></p>
+      <p class="muted">Start one with <code>Durable.start(:recipe_name)</code> and it appears here.</p>
+    </div>
+  <% else %>
+    <table>
+      <thead>
+        <tr><th>Execution</th><th>Steps</th><th>Status</th><th>Wakes</th><th>Problem</th><th>Updated</th></tr>
+      </thead>
+      <tbody>
+        <% @executions.each do |execution| %>
+          <% items = track_items(execution, @steps_by_execution.fetch(execution.id, [])) %>
+          <tr data-id="<%= execution.id %>" data-status="<%= execution.status %>">
+            <td>
+              <%= link_to execution.id, execution_path(execution), class: "exec-link" %>
+              <span class="recipe"><%= execution.recipe %>, version <%= execution.recipe_version %></span>
+            </td>
+            <td>
+              <span class="mini" role="img" aria-label="<%= items.map { |item| item_title(item) }.join("; ") %>">
+                <% items.first(14).each_with_index do |item, index| %>
+                  <% if item.branches.any? %>
+                    <span class="stack" title="<%= item_title(item) %>">
+                      <% item.branches.first(4).each do |branch| %>
+                        <i class="b st-<%= branch.state %>" style="--i: <%= index %>"></i>
+                      <% end %>
+                    </span>
+                  <% else %>
+                    <i class="b st-<%= item.state %> k-<%= item.kind %>" style="--i: <%= index %>" title="<%= item_title(item) %>"></i>
+                  <% end %>
+                <% end %>
+                <% if items.size > 14 %><span class="more">+<%= items.size - 14 %></span><% end %>
+              </span>
+            </td>
+            <td>
+              <span class="status tone-<%= ActiveDurable::DashboardHelper::STATUS_TONES.fetch(execution.status, "muted") %>">
+                <i class="dot" aria-hidden="true"></i><%= execution.status %>
+              </span>
+              <% if compensating_now?(execution) %><%= status_pill("compensating") %><% end %>
+            </td>
+            <td class="when"><%= execution.wake_at ? when_text(execution.wake_at) : tag.span("—", class: "muted") %></td>
+            <td class="problem"><%= execution.error&.dig("message").to_s.truncate(110) %></td>
+            <td class="when"><%= when_text(execution.updated_at) %></td>
+          </tr>
+        <% end %>
+      </tbody>
+    </table>
+  <% end %>
+</section>
+
+<% if @page > 1 || @next_page %>
+  <nav class="pager" aria-label="Pages">
+    <% if @page > 1 %>
+      <%= link_to "Newer", executions_path(status: @status, recipe: @recipe, q: @query.presence, page: @page - 1) %>
+    <% end %>
+    <% if @next_page %>
+      <%= link_to "Older", executions_path(status: @status, recipe: @recipe, q: @query.presence, page: @page + 1) %>
+    <% end %>
+  </nav>
+<% end %>

data/app/views/active_durable/executions/show.html.erb

@@ -0,0 +1,197 @@
+<% content_for :title, @execution.id %>
+<% tone = ActiveDurable::DashboardHelper::STATUS_TONES.fetch(@execution.status, "muted") %>
+<% items = track_items(@execution, @steps) %>
+<% undos = undo_lane(@steps) %>
+<% backwards = @execution.compensating %>
+
+<p class="crumbs">Executions / <%= @execution.recipe %></p>
+
+<header class="hero tone-<%= tone %>">
+  <div class="beacon" aria-hidden="true"></div>
+  <div class="hero-main">
+    <h1><%= @execution.id %></h1>
+    <p class="sub">
+      Recipe <strong><%= @execution.recipe %></strong>, version <%= @execution.recipe_version %>.
+      Started <%= when_text(@execution.created_at) %>, last change <%= when_text(@execution.updated_at) %>.
+      <% if @execution.wake_at %>Wakes <%= when_text(@execution.wake_at) %>.<% end %>
+      <% if @execution.forked_from %>
+        Rerun of <%= link_to @execution.forked_from, execution_path(@execution.forked_from), class: "mono" %>.
+      <% end %>
+    </p>
+  </div>
+  <span class="badge"><%= ActiveDurable::DashboardHelper::STATUS_WORDS.fetch(@execution.status, @execution.status) %><%= ", undoing" if compensating_now?(@execution) %></span>
+</header>
+
+<% if @execution.error %>
+  <section class="problem-card" role="alert">
+    <strong><%= @execution.error["message"] %></strong>
+    <span><%= @execution.error["class"] %><%= " in :#{@execution.error["step"]}" if @execution.error["step"] %></span>
+  </section>
+<% end %>
+
+<% if can_retry?(@execution) || can_compensate?(@execution, @forward_steps) || (can_rerun?(@execution) && @forward_steps.any?) %>
+  <section class="actions" aria-label="Actions">
+    <% if can_retry?(@execution) %>
+      <%= button_to retry_execution_path(@execution), class: "primary", form_class: "inline" do %>Retry<% end %>
+    <% end %>
+    <% if can_compensate?(@execution, @forward_steps) %>
+      <%= button_to compensate_execution_path(@execution), class: "danger", form_class: "inline",
+                    form: { data: { confirm: "Undo every completed step of #{@execution.id}?" } } do %>
+        Undo everything
+      <% end %>
+    <% end %>
+    <% if can_rerun?(@execution) && @forward_steps.any? %>
+      <%= form_with url: rerun_execution_path(@execution), method: :post, class: "inline", local: true do %>
+        <label for="rerun-from">Run again from</label>
+        <%= select_tag :from, options_for_select(@forward_steps.map(&:name), rerun_default(@forward_steps)), id: "rerun-from" %>
+        <button type="submit">Rerun</button>
+      <% end %>
+      <p class="note">A rerun is a new execution. Steps before the one you choose are reused; that step and the ones
+        after it run again with new tickets, so they have effects again.</p>
+    <% end %>
+  </section>
+<% end %>
+
+<section class="board" aria-labelledby="track-title">
+  <div class="board-head">
+    <h2 id="track-title">The saga, step by step</h2>
+    <span class="muted"><%= pluralize(@forward_steps.count { |step| step.position }, "step") %> reached<%= ", undoing backwards" if compensating_now?(@execution) %></span>
+  </div>
+  <% if items.empty? %>
+    <p class="muted">No step has run yet. A worker picks this saga up from its queue.</p>
+  <% else %>
+    <div class="track-scroll">
+      <div class="track">
+        <% items.each_with_index do |item, index| %>
+          <% if index.positive? %>
+            <% previous = items[index - 1] %>
+            <% if previous.kind == "pivot" && previous.state != "failed" %>
+              <span class="gate" style="--i: <%= index %>"><span>point of no return</span></span>
+            <% end %>
+            <% wire = if item.state == "undone" || (backwards && previous.state == "undone") then "back"
+                      elsif %w[completed sleeping waiting].include?(item.state) then "lit"
+                      elsif %w[next running retrying].include?(item.state) then "lit to-active"
+                      else "" end %>
+            <span class="wire <%= wire %>" style="--i: <%= index %>" aria-hidden="true"></span>
+          <% end %>
+          <% wake_at = item_wake_at(item) %>
+          <article class="block st-<%= item.state %> k-<%= item.kind %>" style="--i: <%= index %>" aria-label="<%= item_title(item) %>">
+            <div class="top">
+              <span class="kind <%= "k-pivot-word" if item.kind == "pivot" %>"><%= item.kind == "ghost" ? "up next" : item.kind %></span>
+              <% if item.step&.position %><span class="no"><%= item.step.position %></span><% end %>
+            </div>
+            <h3><%= item.kind == "ghost" ? "…" : breakable(item.name) %></h3>
+            <p class="state"><%= state_word(item.state).capitalize %></p>
+            <% if item.step && item.step.attempts.to_i > 1 %><p class="meta"><%= item.step.attempts %> attempts</p><% end %>
+            <% if wake_at && %w[retrying sleeping waiting].include?(item.state) %>
+              <p class="meta"><%= item.state == "waiting" ? "Gives up" : "Wakes" %> <%= when_text(wake_at) %></p>
+            <% end %>
+            <% if item.step&.result && item.state == "completed" && item.kind != "sleep" && item.branches.empty? %>
+              <p class="peek" title="<%= item.step.result.to_json %>"><%= item.step.result.to_json %></p>
+            <% end %>
+            <% if item.branches.any? %>
+              <div class="branches">
+                <% item.branches.each do |branch| %>
+                  <span class="branch"><i class="st-<%= branch.state %>" aria-hidden="true"></i><%= branch.name %>
+                    <span class="muted"><%= state_word(branch.state) %></span></span>
+                <% end %>
+              </div>
+            <% end %>
+            <% if item.state == "waiting" %>
+              <span class="radar" aria-hidden="true"></span>
+            <% elsif item.state == "retrying" %>
+              <span class="spin" aria-hidden="true"></span>
+            <% elsif item.state == "sleeping" %>
+              <span class="ring" aria-hidden="true" data-ring-from="<%= item.step.created_at.utc.iso8601 %>"
+                    data-ring-until="<%= wake_at&.utc&.iso8601 %>"></span>
+            <% end %>
+          </article>
+        <% end %>
+      </div>
+    </div>
+  <% end %>
+  <% if undos.any? %>
+    <div class="undo-lane" aria-label="Undos, in the order they ran">
+      <span class="label">Undone, last step first</span>
+      <% undos.each_with_index do |undo, index| %>
+        <% if index.positive? %><span class="arrow" aria-hidden="true">←</span><% end %>
+        <span class="undo-chip <%= "failed" unless undo.completed? %>" style="--i: <%= index %>">
+          <%= undo.name.delete_suffix(":undo") %><% unless undo.completed? %>, <%= undo.status %> after <%= undo.attempts %><% end %>
+        </span>
+      <% end %>
+    </div>
+  <% end %>
+</section>
+
+<div class="details">
+  <section class="panel" aria-labelledby="notebook-title">
+    <h2 id="notebook-title">Notebook</h2>
+    <% if @forward_steps.empty? %>
+      <p class="muted">Empty: no step has been written down yet.</p>
+    <% else %>
+      <div class="sheet">
+        <table>
+          <thead>
+            <tr><th>#</th><th>Step and ticket</th><th>Status</th><th>Attempts</th><th>Result</th><th>Error</th></tr>
+          </thead>
+          <tbody>
+            <% @forward_steps.each do |step| %>
+              <tr>
+                <td><%= step.position %></td>
+                <td>
+                  <strong><%= step.name %></strong><span class="k <%= "k-pivot-word" if step.kind == "pivot" %>"><%= step.kind %></span><br>
+                  <code class="muted ticket"><%= ticket_for(@execution, step) %></code>
+                </td>
+                <td><%= status_pill(step.status) %></td>
+                <td><%= step.attempts %></td>
+                <td class="result"><%= json_preview(step.result) %></td>
+                <td class="error"><%= step.error&.dig("message").to_s.truncate(120) %></td>
+              </tr>
+            <% end %>
+            <% @undo_steps.each do |step| %>
+              <tr>
+                <td></td>
+                <td><strong><%= step.name %></strong><span class="k">undo</span></td>
+                <td><%= status_pill(step.completed? ? "undone" : step.status) %></td>
+                <td><%= step.attempts %></td>
+                <td></td>
+                <td class="error"><%= step.error&.dig("message").to_s.truncate(120) %></td>
+              </tr>
+            <% end %>
+          </tbody>
+        </table>
+      </div>
+    <% end %>
+  </section>
+
+  <div class="side">
+    <section class="panel">
+      <h2>Input</h2>
+      <%= pretty_json(@execution.input) %>
+    </section>
+    <section class="panel">
+      <h2>Output</h2>
+      <%= pretty_json(@execution.output) %>
+    </section>
+    <% if @signals.any? %>
+      <section class="panel">
+        <h2>Signals</h2>
+        <dl class="facts">
+          <% @signals.each do |signal| %>
+            <dt><strong><%= signal.name %></strong></dt>
+            <dd><%= json_preview(signal.payload) %><br>
+              <span class="muted">received <%= when_text(signal.created_at) %><%= signal.consumed_at ? ", used" : ", not used yet" %></span></dd>
+          <% end %>
+        </dl>
+      </section>
+    <% end %>
+    <% if @reruns.any? %>
+      <section class="panel">
+        <h2>Reruns</h2>
+        <% @reruns.each do |rerun| %>
+          <p><%= link_to rerun.id, execution_path(rerun), class: "mono" %> <%= status_pill(rerun.status) %></p>
+        <% end %>
+      </section>
+    <% end %>
+  </div>
+</div>