job-workflow 0.4.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 213a0654cb0482f1a2574f4e55d26c72f5274d24b61b933abd04e9e21f4c19d1
-  data.tar.gz: 0f19fce390ff18dcb13d80c8a4c6841dc2e096d4ea7586f0a2d6e2c6a467a45b
+  metadata.gz: fbf6231d334745f4814282d93fa8c7b54461680e6bb57edc6632cd39b86cb71b
+  data.tar.gz: c627082defb65e2a4cd79cb2b88d3f54ce8b082a88d9ccaff3d96029ee49ea65
 SHA512:
-  metadata.gz: 89e0d194c4f14817bd2866b4b07f2efe3eea0ffdbc74ff4b7c1f5474d59fb0a18749d68fc2c724ea690f370d1b335d1e69bf0f006ab9bb1964f74fcfd689232b
-  data.tar.gz: 49150a706fb10a4ba79a87397b4cbbfcb4554eba5e974d22d6176799d377f5d9814f20862be996bca253328fc1efa6a10429947cc308f4aa3dd884eaadd378d0
+  metadata.gz: f8caf717541c7f549d3957a5939d636881f8ad98389e5e53759dde43e561c8bbdeda0211feab0843f2625fbc974fb217b479bc2421e0bc828b9f6d910b749cd5
+  data.tar.gz: 466d87d40597d0d3c68de4cec3f2f6d158faab74100d098420cd376108fb88667f15cf1ecccdf2b810e41df402a9db5f7d84945a71de2dd756e71ae99588fe58

data/.rubocop.yml

@@ -41,7 +41,7 @@ Metrics/BlockLength:
 Metrics/ClassLength:
   Enabled: true
   CountComments: false
-  Max: 100
+  Max: 124
   CountAsOne:
     - array
     - hash
@@ -88,4 +88,3 @@ Style/StringLiteralsInInterpolation:
 
 ThreadSafety/ClassAndModuleAttributes:
   Enabled: false
-

data/CHANGELOG.md

@@ -1,5 +1,35 @@
 ## [Unreleased]
 
+## [0.6.0] - 2026-05-24
+
+### Added
+
+- Add `JobWorkflow::SubTaskJob` for `enqueue: true` task fan-out so each-task sub-jobs run on a dedicated job class instead of reusing the workflow DSL job class directly
+- Add a JobWorkflow monitoring UI engine with an execution DAG overview for browsing workflow definitions, root executions, DAG state, arguments, outputs, fan-out progress, and linked Mission Control Jobs rows
+
+### Changed
+
+- **Breaking:** `WorkflowStatus.find` / `find_by` are now root-workflow-only APIs. Sub-task job IDs are excluded and should be tracked via `JobStatus`.
+
+### Fixed
+
+- Route enqueued each-task execution through `SubTaskJob`, restoring workflow/task context from the parent workflow job and keeping parent/sub-job identity separate during async execution
+- Extend queue-adapter and workflow-status hydration so monitoring can paginate root workflow executions, hydrate sub-task detail on demand, and keep partially completed fan-out tasks visible as `running` until the workflow actually settles
+
+### Removed
+
+- Remove `enqueue: { concurrency: N }`. Async map task fan-out is still controlled by `enqueue`, but execution caps are now configured exclusively with `throttle`.
+
+## [0.5.0] - 2026-05-13
+
+### Added
+
+- Add task-scoped cursor helpers on `Context` so tasks can persist progress, restore task-local continuation state, and delegate explicit checkpoints without exposing ActiveJob continuation internals
+
+### Fixed
+
+- Initialize the SolidQueue adapter from a Railtie after Rails boot so the `ClaimedExecution` patch is applied reliably, rescheduled `dependency_wait` jobs are not marked finished early, and Rails apps no longer need a manual initializer
+
 ## [0.4.0] - 2026-05-12
 
 ### Fixed

data/README.md

@@ -1,6 +1,6 @@
 # JobWorkflow
 
-> ⚠️ **Early Stage (v0.4.0):** This library is in active development. APIs and features may change in breaking ways without notice. Use in production at your own risk and expect potential breaking changes in future releases.
+> ⚠️ **Early Stage (v0.6.0):** This library is in active development. APIs and features may change in breaking ways without notice. Use in production at your own risk and expect potential breaking changes in future releases.
 
 ## Overview
 

data/app/controllers/job_workflow/monitoring/application_controller.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module JobWorkflow
+  module Monitoring
+    # Resolve the host app controller at load time so engine controllers inherit
+    # the app's existing authentication and access control hooks.
+    class ApplicationController < JobWorkflow::Monitoring.resolved_base_controller_class.constantize
+      layout "job_workflow/monitoring/application"
+    end
+  end
+end

data/app/controllers/job_workflow/monitoring/executions_controller.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module JobWorkflow
+  module Monitoring
+    class ExecutionsController < ApplicationController
+      def index
+        @workflow = WorkflowRegistry.find(params[:workflow_job_class_name])
+        return render plain: "Workflow definition not found.", status: :not_found if @workflow.nil?
+
+        @page = ExecutionRegistry.page_for(
+          job_class_name: @workflow.name,
+          cursor: params[:cursor]
+        )
+        @executions = @page.executions
+      end
+
+      def show
+        @workflow = WorkflowRegistry.find(params[:workflow_job_class_name])
+        return render plain: "Workflow definition not found.", status: :not_found if @workflow.nil?
+
+        @execution = ExecutionRegistry.find(params[:id])
+        return if @execution && @execution.job_class_name == @workflow.name
+
+        render plain: "Workflow execution is no longer available.", status: :not_found
+      end
+    end
+  end
+end

data/app/controllers/job_workflow/monitoring/workflows_controller.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module JobWorkflow
+  module Monitoring
+    class WorkflowsController < ApplicationController
+      def index
+        @workflows = Monitoring.workflows
+      end
+    end
+  end
+end

data/app/views/job_workflow/monitoring/executions/index.html.erb

@@ -0,0 +1,57 @@
+<section class="d-flex flex-column flex-lg-row justify-content-between align-items-lg-end gap-3 mb-4">
+  <div>
+    <div class="text-body-secondary small mb-1">Workflow</div>
+    <h1 class="display-6 fw-semibold mb-2"><%= @workflow.name %></h1>
+    <p class="text-body-secondary mb-0">Paginated root executions. sub task jobs appear only inside execution detail.</p>
+  </div>
+  <div>
+    <%= link_to "Back to workflows", root_path, class: "btn btn-outline-secondary" %>
+  </div>
+</section>
+
+<div class="card jw-card">
+  <div class="card-body p-0">
+    <% if @executions.empty? %>
+      <div class="p-4 text-body-secondary">No currently available workflow executions.</div>
+    <% else %>
+      <div class="table-responsive">
+        <table class="table table-hover align-middle mb-0">
+          <thead class="table-light">
+            <tr>
+              <th class="ps-4">Status</th>
+              <th>Current task</th>
+              <th>Queue</th>
+              <th>Job</th>
+              <th class="text-end pe-4">Detail</th>
+            </tr>
+          </thead>
+          <tbody>
+            <% @executions.each do |execution| %>
+              <% status_class = case execution.workflow_status
+                               when :succeeded then "text-bg-success"
+                               when :failed then "text-bg-danger"
+                               when :running then "text-bg-primary"
+                               else "text-bg-secondary"
+                               end %>
+              <tr>
+                <td class="ps-4"><span class="badge <%= status_class %>"><%= execution.workflow_status %></span></td>
+                <td><%= execution.current_task_name || "-" %></td>
+                <td><span class="jw-mono"><%= execution.queue_name || "-" %></span></td>
+                <td class="jw-mono"><%= execution.job_id %></td>
+                <td class="text-end pe-4">
+                  <%= link_to "Open", workflow_execution_path(@workflow.name, execution.job_id), class: "btn btn-sm btn-primary" %>
+                </td>
+              </tr>
+            <% end %>
+          </tbody>
+        </table>
+      </div>
+    <% end %>
+  </div>
+</div>
+
+<% if @page.next_cursor %>
+  <div class="d-flex justify-content-end mt-3">
+    <%= link_to "Next page", workflow_executions_path(@workflow.name, cursor: @page.next_cursor), class: "btn btn-outline-primary" %>
+  </div>
+<% end %>

data/app/views/job_workflow/monitoring/executions/show.html.erb

@@ -0,0 +1,200 @@
+<% status_class = case @execution.workflow_status
+                 when :succeeded then "text-bg-success"
+                 when :failed then "text-bg-danger"
+                 when :running then "text-bg-primary"
+                 else "text-bg-secondary"
+                 end %>
+<% dag_layout = @execution.dag_layout %>
+
+<section class="d-flex flex-column flex-lg-row justify-content-between align-items-lg-start gap-3 mb-4">
+  <div>
+    <div class="text-body-secondary small mb-1">Execution</div>
+    <h1 class="display-6 fw-semibold mb-3"><%= @execution.job_class_name %></h1>
+    <div class="d-flex flex-wrap gap-2">
+      <span class="badge <%= status_class %>"><%= @execution.workflow_status %></span>
+      <span class="badge text-bg-light border text-dark">task <%= @execution.current_task_name || "-" %></span>
+      <span class="badge text-bg-light border text-dark">failed <%= @execution.failed_task_name || "-" %></span>
+    </div>
+  </div>
+  <div class="d-flex flex-wrap gap-2">
+    <%= link_to "Back to executions", workflow_executions_path(@workflow.name), class: "btn btn-outline-secondary" %>
+    <% if @execution.mission_control_job_path %>
+      <%= link_to "Mission Control Jobs", @execution.mission_control_job_path, class: "btn btn-primary" %>
+    <% end %>
+  </div>
+</section>
+
+<div class="row g-4 mb-4">
+  <div class="col-12 col-xl-4">
+    <div class="card jw-card h-100">
+      <div class="card-header bg-white fw-semibold">Execution Summary</div>
+      <div class="card-body">
+        <dl class="row mb-0">
+          <dt class="col-sm-4">Job ID</dt>
+          <dd class="col-sm-8 jw-mono"><%= @execution.job_id %></dd>
+          <dt class="col-sm-4">Queue</dt>
+          <dd class="col-sm-8"><%= @execution.queue_name || "-" %></dd>
+          <dt class="col-sm-4">Current</dt>
+          <dd class="col-sm-8"><%= @execution.current_task_name || "-" %></dd>
+          <dt class="col-sm-4">Failed</dt>
+          <dd class="col-sm-8"><%= @execution.failed_task_name || "-" %></dd>
+        </dl>
+      </div>
+    </div>
+  </div>
+
+  <div class="col-12 col-xl-8">
+    <div class="card jw-card h-100">
+      <div class="card-header bg-white fw-semibold">Arguments</div>
+      <div class="card-body">
+        <pre class="jw-pre"><%= JSON.pretty_generate(@execution.filtered_arguments.as_json) %></pre>
+      </div>
+    </div>
+  </div>
+</div>
+
+<div class="card jw-card">
+  <div class="card-header bg-white fw-semibold">DAG</div>
+  <% if dag_layout[:nodes].any? %>
+    <div class="card-body border-bottom" aria-hidden="true">
+      <div class="small text-body-secondary mb-3">graph overview</div>
+      <div class="jw-dag-viewport">
+        <div
+          class="jw-dag-canvas"
+          style="width: <%= dag_layout[:width] %>px; height: <%= dag_layout[:height] %>px;"
+        >
+          <svg
+            class="jw-dag-svg"
+            viewBox="0 0 <%= dag_layout[:width] %> <%= dag_layout[:height] %>"
+            preserveAspectRatio="xMinYMin meet"
+          >
+            <% dag_layout[:edges].each do |edge| %>
+              <path class="jw-dag-edge" d="<%= edge[:path] %>"></path>
+            <% end %>
+          </svg>
+
+          <% dag_layout[:nodes].each do |task| %>
+            <% graph_status_class = case task[:status]
+                                   when :succeeded then "text-bg-success"
+                                   when :failed then "text-bg-danger"
+                                   when :running then "text-bg-primary"
+                                   else "text-bg-secondary"
+                                   end %>
+            <div
+              class="jw-dag-node"
+              style="left: <%= task[:x] %>px; top: <%= task[:y] %>px; width: <%= task[:width] %>px; height: <%= task[:height] %>px;"
+            >
+              <div class="d-flex flex-column align-items-start gap-1">
+                <div class="fw-semibold jw-dag-node-title" title="<%= task[:label] %>"><%= task[:truncated_label] %></div>
+                <span class="badge <%= graph_status_class %>"><%= task[:status] %></span>
+              </div>
+
+              <% if task[:meta_label] %>
+                <div class="jw-dag-node-meta"><%= task[:meta_label] %></div>
+              <% end %>
+            </div>
+          <% end %>
+        </div>
+      </div>
+    </div>
+  <% end %>
+  <div class="list-group list-group-flush">
+    <% @execution.tasks.each do |task| %>
+      <% task_status_class = case task[:status]
+                            when :succeeded then "text-bg-success"
+                            when :failed then "text-bg-danger"
+                            when :running then "text-bg-primary"
+                            else "text-bg-secondary"
+                            end %>
+      <div class="list-group-item p-4">
+        <div class="d-flex flex-column flex-lg-row justify-content-between gap-3">
+          <div>
+            <div class="d-flex flex-wrap align-items-center gap-2 mb-2">
+              <span class="fw-semibold"><%= task[:name] %></span>
+              <span class="badge <%= task_status_class %>"><%= task[:status] %></span>
+              <% if task[:each] %>
+                <span class="badge text-bg-light border text-dark">
+                  each <%= task[:each_progress][:succeeded] %>/<%= task[:each_progress][:total] %>
+                </span>
+              <% end %>
+            </div>
+            <% if task[:depends_on].any? %>
+              <div class="text-body-secondary small">depends on <%= task[:depends_on].join(", ") %></div>
+            <% end %>
+          </div>
+
+          <% if task[:each] %>
+            <div class="text-lg-end">
+              <div class="small text-body-secondary mb-1">fan-out progress</div>
+              <div class="progress" role="progressbar" aria-valuemin="0" aria-valuemax="<%= task[:each_progress][:total] %>" aria-valuenow="<%= task[:each_progress][:succeeded] %>">
+                <div
+                  class="progress-bar"
+                  style="width: <%= task[:each_progress][:total].positive? ? (task[:each_progress][:succeeded] * 100 / task[:each_progress][:total]) : 0 %>%"
+                ></div>
+              </div>
+            </div>
+          <% end %>
+        </div>
+
+        <div class="row g-3 mt-1">
+          <div class="col-12 col-xl-6">
+            <div class="small text-body-secondary mb-2">configuration</div>
+            <pre class="jw-pre"><%= JSON.pretty_generate(task[:configuration].as_json) %></pre>
+          </div>
+
+          <div class="col-12 col-xl-6">
+            <div class="small text-body-secondary mb-2">progress</div>
+            <pre class="jw-pre"><%= JSON.pretty_generate(task[:each_progress].as_json) %></pre>
+          </div>
+        </div>
+
+        <% if task[:outputs].any? %>
+          <div class="mt-3">
+            <div class="small text-body-secondary mb-2">outputs</div>
+            <pre class="jw-pre"><%= JSON.pretty_generate(task[:outputs].as_json) %></pre>
+          </div>
+        <% end %>
+
+        <% if Array(task[:sub_task_jobs]).any? %>
+          <div class="mt-3">
+            <div class="small text-body-secondary mb-2">sub task jobs</div>
+            <div class="table-responsive">
+              <table class="table table-sm align-middle mb-0">
+                <thead>
+                  <tr>
+                    <th>Each</th>
+                    <th>Status</th>
+                    <th>Job ID</th>
+                    <th class="text-end">Mission Control</th>
+                  </tr>
+                </thead>
+                <tbody>
+                  <% Array(task[:sub_task_jobs]).each do |sub_task_job| %>
+                    <% sub_task_status_class = case sub_task_job[:status]
+                                              when :succeeded then "text-bg-success"
+                                              when :failed then "text-bg-danger"
+                                              when :running then "text-bg-primary"
+                                              else "text-bg-secondary"
+                                              end %>
+                    <tr>
+                      <td><%= sub_task_job[:each_index] %></td>
+                      <td><span class="badge <%= sub_task_status_class %>"><%= sub_task_job[:status] %></span></td>
+                      <td class="jw-mono"><%= sub_task_job[:job_id] %></td>
+                      <td class="text-end">
+                        <% if sub_task_job[:mission_control_job_path] %>
+                          <%= link_to "Open", sub_task_job[:mission_control_job_path], class: "btn btn-sm btn-outline-primary" %>
+                        <% else %>
+                          <span class="text-body-secondary">-</span>
+                        <% end %>
+                      </td>
+                    </tr>
+                  <% end %>
+                </tbody>
+              </table>
+            </div>
+          </div>
+        <% end %>
+      </div>
+    <% end %>
+  </div>
+</div>

data/app/views/job_workflow/monitoring/workflows/index.html.erb

@@ -0,0 +1,39 @@
+<section class="mb-4">
+  <h1 class="display-6 fw-semibold mb-2">Workflow Definitions</h1>
+  <p class="text-body-secondary mb-0">Root execution only. Select one workflow, then drill into its executions.</p>
+</section>
+
+<div class="card jw-card">
+  <div class="card-body p-0">
+    <% if @workflows.empty? %>
+      <div class="p-4 text-body-secondary">No workflows are registered.</div>
+    <% else %>
+      <div class="table-responsive">
+        <table class="table table-hover align-middle mb-0">
+          <thead class="table-light">
+            <tr>
+              <th class="ps-4">Workflow</th>
+              <th>Tasks</th>
+              <th class="text-end pe-4">Executions</th>
+            </tr>
+          </thead>
+          <tbody>
+            <% @workflows.each do |workflow| %>
+              <tr>
+                <td class="ps-4">
+                  <div class="fw-semibold"><%= workflow.job_class_name %></div>
+                </td>
+                <td>
+                  <span class="badge text-bg-secondary"><%= workflow.task_count %> tasks</span>
+                </td>
+                <td class="text-end pe-4">
+                  <%= link_to "View executions", workflow_executions_path(workflow.job_class_name), class: "btn btn-sm btn-primary" %>
+                </td>
+              </tr>
+            <% end %>
+          </tbody>
+        </table>
+      </div>
+    <% end %>
+  </div>
+</div>

data/app/views/layouts/job_workflow/monitoring/application.html.erb

@@ -0,0 +1,117 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <title>JobWorkflow Monitoring</title>
+    <link
+      href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.8/dist/css/bootstrap.min.css"
+      rel="stylesheet"
+      integrity="sha384-sRIl4kxILFvY47J16cr9ZwB07vP4J8+LH7qKQnuqkuIAvNWLzeN8tE5YBujZqJLB"
+      crossorigin="anonymous"
+    >
+    <style>
+      :root {
+        --jw-surface: #f8f9fa;
+        --jw-border: #dee2e6;
+      }
+
+      body {
+        background:
+          radial-gradient(circle at top right, rgba(13, 110, 253, 0.08), transparent 24rem),
+          linear-gradient(180deg, #f8fbff 0%, #f8f9fa 100%);
+      }
+
+      .jw-shell {
+        max-width: 1200px;
+      }
+
+      .jw-mono {
+        font-family: ui-monospace, SFMono-Regular, SFMono-Regular, Menlo, Consolas, monospace;
+        word-break: break-all;
+      }
+
+      .jw-pre {
+        background: #212529;
+        color: #f8f9fa;
+        border-radius: 0.75rem;
+        padding: 1rem;
+        margin: 0;
+        white-space: pre-wrap;
+      }
+
+      .jw-card {
+        border-color: var(--jw-border);
+        box-shadow: 0 0.5rem 1.5rem rgba(33, 37, 41, 0.06);
+      }
+
+      .jw-dag-viewport {
+        overflow-x: auto;
+        padding-bottom: 0.25rem;
+      }
+
+      .jw-dag-canvas {
+        position: relative;
+        min-height: 12rem;
+      }
+
+      .jw-dag-svg {
+        position: absolute;
+        inset: 0;
+        overflow: visible;
+      }
+
+      .jw-dag-edge {
+        fill: none;
+        stroke: #adb5bd;
+        stroke-width: 2;
+        stroke-linecap: round;
+        stroke-linejoin: round;
+      }
+
+      .jw-dag-node {
+        position: absolute;
+        display: flex;
+        flex-direction: column;
+        justify-content: flex-start;
+        gap: 0.4rem;
+        background: #fff;
+        border: 1px solid var(--jw-border);
+        border-radius: 0.85rem;
+        box-shadow: 0 0.4rem 1rem rgba(33, 37, 41, 0.08);
+        padding: 0.75rem 0.875rem;
+      }
+
+      .jw-dag-node-title {
+        font-size: 0.875rem;
+        line-height: 1.15;
+        max-width: 10rem;
+        overflow: hidden;
+        text-overflow: ellipsis;
+        white-space: nowrap;
+      }
+
+      .jw-dag-node-meta {
+        color: #6c757d;
+        font-size: 0.72rem;
+      }
+    </style>
+  </head>
+  <body>
+    <nav class="navbar navbar-expand-lg bg-white border-bottom sticky-top">
+      <div class="container-fluid jw-shell px-3 px-lg-4">
+        <a class="navbar-brand fw-semibold" href="<%= root_path %>">JobWorkflow Monitoring</a>
+      </div>
+    </nav>
+
+    <main class="container-fluid jw-shell py-4 py-lg-5 px-3 px-lg-4">
+      <%= yield %>
+    </main>
+
+    <script
+      src="https://cdn.jsdelivr.net/npm/bootstrap@5.3.8/dist/js/bootstrap.bundle.min.js"
+      integrity="sha384-FKyoEForCGlyvwx9Hj09JcYn3nv7wiPVlz7YYwJrWVcXK/BmnVDxM+D2scQbITxI"
+      crossorigin="anonymous"
+    ></script>
+  </body>
+</html>

data/config/routes.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+JobWorkflow::Monitoring::Engine.routes.draw do
+  resources :workflows, only: [:index], param: :job_class_name do
+    resources :executions, only: %i[index show]
+  end
+  root "workflows#index"
+end