orchestr8 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: bb3a329867dcd0ded2c80e15c9429b242d94bb1da71ad08e0903710d9ebee189
+  data.tar.gz: '0251029e374e577258ccf68759bdee887cd6dffffbee0bdd29cd9d8dfdac3b56'
+SHA512:
+  metadata.gz: b7f5204b20d5f299ccc5c9b7e2ead98e91dc8b6f3ba0ecb29c4b1648490f12def2578b24051c543ecee13b3950a4add6de849d5746bce7fc52b5330da23d4df3
+  data.tar.gz: bd5867c70e787185453a8487be232235c08c2100fd48b639813ad599fcff3cdf7040f75a38e1c5d288f82f254637f92a478726e87ff176104dd11bb302459b20

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Romulo Storel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,186 @@
+# Orchestr8
+
+DAG-based job workflow orchestration for Rails. Define multi-step workflows as directed acyclic graphs with parallel execution, dependency tracking, failure handling, and a built-in dashboard. No Redis required — all state lives in your database.
+
+[![CI](https://github.com/romulostorel/orchestr8/actions/workflows/ci.yml/badge.svg)](https://github.com/romulostorel/orchestr8/actions/workflows/ci.yml)
+
+## What It Does
+
+- Compose jobs into workflows with explicit dependencies
+- Steps with no unmet dependencies run in parallel automatically
+- Steps can pass output data to downstream steps
+- Configurable failure handling per step (halt the workflow or continue)
+- Built-in web dashboard with DAG visualization and real-time status updates
+- Works with any Active Job backend (Solid Queue, Sidekiq, GoodJob, etc.)
+- Test helper for synchronous, in-process workflow execution in specs
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "orchestr8"
+```
+
+Run the migrations:
+
+```sh
+bundle exec rails orchestr8:install:migrations
+bundle exec rails db:migrate
+```
+
+Mount the dashboard in `config/routes.rb`:
+
+```ruby
+mount Orchestr8::Engine => "/orchestr8"
+```
+
+## Quick Start
+
+### 1. Define a Workflow
+
+```ruby
+# app/workflows/etl_workflow.rb
+class EtlWorkflow < Orchestr8::Workflow
+  step :fetch,     job: FetchDataJob
+  step :transform, job: TransformJob, after: :fetch
+  step :load,      job: LoadJob,      after: :transform
+end
+```
+
+### 2. Add Stepable to Your Jobs
+
+```ruby
+class FetchDataJob < ApplicationJob
+  include Orchestr8::Stepable
+
+  def perform(arguments)
+    data = fetch_data(arguments["url"])
+    output(data)   # share data with downstream steps
+  end
+end
+
+class TransformJob < ApplicationJob
+  include Orchestr8::Stepable
+
+  def perform(arguments)
+    raw = payloads[:fetch]   # read upstream output
+    output(transform(raw))
+  end
+end
+```
+
+### 3. Run a Workflow
+
+```ruby
+EtlWorkflow.create!(arguments: { "url" => "https://api.example.com/data" })
+```
+
+Orchestr8 enqueues ready steps immediately, then re-evaluates and enqueues downstream steps as each step completes.
+
+## Step Options
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `job:` | Class | required | The Active Job class to perform |
+| `after:` | Symbol or Array | `[]` | Step name(s) this step depends on |
+| `on_failure:` | `:halt` / `:continue` | `:halt` | What to do when this step fails |
+| `queue:` | String | nil | Override the queue name for this step |
+
+```ruby
+class MyWorkflow < Orchestr8::Workflow
+  step :fetch,   job: FetchJob,   queue: "critical"
+  step :notify,  job: NotifyJob,  after: :fetch, on_failure: :continue
+  step :cleanup, job: CleanupJob, after: %i[fetch notify]
+end
+```
+
+## Failure Handling
+
+By default (`on_failure: :halt`), a failed step prevents downstream steps from running and marks the workflow as failed.
+
+With `on_failure: :continue`, downstream steps still run even if this step fails. The failed step's output will be `nil` in `payloads`.
+
+```ruby
+class ReportWorkflow < Orchestr8::Workflow
+  step :fetch_primary,   job: FetchPrimaryJob
+  step :fetch_secondary, job: FetchSecondaryJob, on_failure: :continue
+  step :aggregate,       job: AggregateJob,       after: %i[fetch_primary fetch_secondary]
+end
+```
+
+## Retry
+
+Retry a single failed step:
+
+```ruby
+step = workflow.steps.find_by(name: "transform")
+step.retry!
+```
+
+Retry all failed steps in a workflow:
+
+```ruby
+workflow.retry!
+```
+
+Both reset the step(s) to `pending` and re-trigger the scheduler immediately.
+
+## Dashboard
+
+Mount the engine in your routes:
+
+```ruby
+mount Orchestr8::Engine => "/orchestr8"
+```
+
+The dashboard at `/orchestr8` lists all workflows with status and step progress. Each workflow's detail page shows a DAG visualization with real-time status updates via Turbo Streams.
+
+### Securing the Dashboard
+
+Configure a base controller class that enforces authentication:
+
+```ruby
+# config/initializers/orchestr8.rb
+Orchestr8.configure do |config|
+  config.base_controller_class = "AdminController"
+end
+```
+
+The engine's controllers will inherit from that class, so any `before_action` defined there (e.g. `authenticate_admin!`) will apply automatically.
+
+## Testing
+
+Use `Orchestr8::TestHelper` to execute workflows synchronously in specs without a real job backend:
+
+```ruby
+# spec/rails_helper.rb (or in a specific spec)
+require "orchestr8/test_helper"
+
+RSpec.describe "My feature" do
+  include Orchestr8::TestHelper
+
+  it "completes the workflow inline" do
+    workflow = MyWorkflow.create!(arguments: { "key" => "value" })
+
+    expect(workflow.reload.status).to eq("completed")
+    expect(workflow.steps.all? { |s| s.status == "completed" }).to be true
+  end
+end
+```
+
+`Orchestr8::TestHelper` hooks into RSpec's `before`/`after` to enable and reset synchronous mode around each example. In synchronous mode the scheduler runs each job inline via `perform_now` and loops until all reachable steps are processed.
+
+## Works With
+
+Orchestr8 uses Active Job and makes no assumptions about the backend.
+
+| Backend | Gem | Notes |
+|---|---|---|
+| Solid Queue | `solid_queue` | Recommended for zero-Redis setups |
+| Sidekiq | `sidekiq` | Set `config.active_job.queue_adapter = :sidekiq` |
+| GoodJob | `good_job` | Postgres-native, supports concurrency controls |
+
+## License
+
+MIT — see [LICENSE](LICENSE).

data/Rakefile

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+
+APP_RAKEFILE = File.expand_path("spec/dummy/Rakefile", __dir__)
+load "rails/tasks/engine.rake"
+load "rails/tasks/statistics.rake"
+
+require "rspec/core/rake_task"
+RSpec::Core::RakeTask.new(:spec)
+task default: :spec

data/app/assets/stylesheets/orchestr8/application.css

@@ -0,0 +1,436 @@
+/* Orchestr8 Web UI Styles */
+
+*, *::before, *::after {
+  box-sizing: border-box;
+}
+
+.orchestr8 {
+  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
+  font-size: 14px;
+  color: #1a1a2e;
+  background: #f5f5f7;
+  min-height: 100vh;
+}
+
+.orchestr8-header {
+  background: #1a1a2e;
+  color: #fff;
+  padding: 16px 24px;
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+}
+
+.orchestr8-header h1 {
+  margin: 0;
+  font-size: 20px;
+  font-weight: 700;
+}
+
+.orchestr8-header h1 a {
+  color: #fff;
+  text-decoration: none;
+}
+
+.orchestr8-header h1 a:hover {
+  text-decoration: underline;
+}
+
+.orchestr8-main {
+  padding: 24px;
+  max-width: 1280px;
+  margin: 0 auto;
+}
+
+/* Flash notices */
+.orchestr8-notice {
+  background: #d1fae5;
+  border: 1px solid #6ee7b7;
+  border-radius: 6px;
+  color: #065f46;
+  padding: 12px 16px;
+  margin-bottom: 20px;
+}
+
+.orchestr8-alert {
+  background: #fee2e2;
+  border: 1px solid #fca5a5;
+  border-radius: 6px;
+  color: #991b1b;
+  padding: 12px 16px;
+  margin-bottom: 20px;
+}
+
+/* Filters */
+.orchestr8-filters {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  margin-bottom: 20px;
+  flex-wrap: wrap;
+}
+
+.orchestr8-filters label {
+  font-weight: 600;
+  color: #374151;
+}
+
+.orchestr8-filters select {
+  padding: 8px 12px;
+  border: 1px solid #d1d5db;
+  border-radius: 6px;
+  background: #fff;
+  font-size: 14px;
+  cursor: pointer;
+  color: #374151;
+}
+
+.orchestr8-filters select:focus {
+  outline: none;
+  border-color: #6366f1;
+  box-shadow: 0 0 0 2px rgba(99, 102, 241, 0.2);
+}
+
+/* Table */
+.orchestr8-table {
+  width: 100%;
+  border-collapse: collapse;
+  background: #fff;
+  border-radius: 8px;
+  overflow: hidden;
+  box-shadow: 0 1px 3px rgba(0,0,0,0.1);
+}
+
+.orchestr8-table thead {
+  background: #f9fafb;
+}
+
+.orchestr8-table th {
+  padding: 12px 16px;
+  text-align: left;
+  font-weight: 600;
+  color: #6b7280;
+  font-size: 12px;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  border-bottom: 1px solid #e5e7eb;
+}
+
+.orchestr8-table td {
+  padding: 12px 16px;
+  border-bottom: 1px solid #f3f4f6;
+  color: #374151;
+}
+
+.orchestr8-table tbody tr:last-child td {
+  border-bottom: none;
+}
+
+.orchestr8-table tbody tr:hover {
+  background: #f9fafb;
+  cursor: pointer;
+}
+
+.orchestr8-table a {
+  color: #6366f1;
+  text-decoration: none;
+  font-weight: 500;
+}
+
+.orchestr8-table a:hover {
+  text-decoration: underline;
+}
+
+/* Badges */
+.orchestr8-badge {
+  display: inline-flex;
+  align-items: center;
+  padding: 3px 10px;
+  border-radius: 9999px;
+  font-size: 12px;
+  font-weight: 600;
+  text-transform: lowercase;
+}
+
+.orchestr8-badge--pending {
+  background: #f3f4f6;
+  color: #6b7280;
+}
+
+.orchestr8-badge--enqueued {
+  background: #ede9fe;
+  color: #7c3aed;
+}
+
+.orchestr8-badge--running {
+  background: #dbeafe;
+  color: #1d4ed8;
+}
+
+.orchestr8-badge--completed {
+  background: #d1fae5;
+  color: #065f46;
+}
+
+.orchestr8-badge--failed {
+  background: #fee2e2;
+  color: #991b1b;
+}
+
+/* Progress bar */
+.orchestr8-progress {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+}
+
+.orchestr8-progress-bar {
+  flex: 1;
+  height: 8px;
+  background: #e5e7eb;
+  border-radius: 9999px;
+  overflow: hidden;
+  min-width: 80px;
+}
+
+.orchestr8-progress-fill {
+  height: 100%;
+  background: #6366f1;
+  border-radius: 9999px;
+  transition: width 0.3s ease;
+}
+
+.orchestr8-progress-text {
+  font-size: 12px;
+  color: #6b7280;
+  white-space: nowrap;
+}
+
+/* Buttons */
+.orchestr8-btn {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  padding: 8px 16px;
+  border-radius: 6px;
+  font-size: 14px;
+  font-weight: 500;
+  cursor: pointer;
+  border: none;
+  text-decoration: none;
+  transition: background 0.15s, box-shadow 0.15s;
+}
+
+.orchestr8-btn--primary {
+  background: #6366f1;
+  color: #fff;
+}
+
+.orchestr8-btn--primary:hover {
+  background: #4f46e5;
+  color: #fff;
+}
+
+.orchestr8-btn--secondary {
+  background: #f3f4f6;
+  color: #374151;
+}
+
+.orchestr8-btn--secondary:hover {
+  background: #e5e7eb;
+  color: #374151;
+}
+
+.orchestr8-btn--danger {
+  background: #fee2e2;
+  color: #991b1b;
+}
+
+.orchestr8-btn--danger:hover {
+  background: #fecaca;
+  color: #7f1d1d;
+}
+
+.orchestr8-btn--sm {
+  padding: 4px 10px;
+  font-size: 12px;
+}
+
+/* Page header */
+.orchestr8-page-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  margin-bottom: 24px;
+  flex-wrap: wrap;
+  gap: 12px;
+}
+
+.orchestr8-page-header h2 {
+  margin: 0;
+  font-size: 22px;
+  font-weight: 700;
+  color: #1a1a2e;
+}
+
+/* Detail header */
+.orchestr8-detail-header {
+  background: #fff;
+  border-radius: 8px;
+  padding: 20px 24px;
+  margin-bottom: 24px;
+  box-shadow: 0 1px 3px rgba(0,0,0,0.1);
+  display: flex;
+  align-items: center;
+  gap: 16px;
+  flex-wrap: wrap;
+}
+
+.orchestr8-detail-header h2 {
+  margin: 0;
+  font-size: 20px;
+  font-weight: 700;
+  color: #1a1a2e;
+  flex: 1;
+}
+
+.orchestr8-detail-meta {
+  font-size: 12px;
+  color: #6b7280;
+  margin-top: 4px;
+}
+
+/* DAG visualization */
+.orchestr8-dag {
+  background: #fff;
+  border-radius: 8px;
+  padding: 24px;
+  box-shadow: 0 1px 3px rgba(0,0,0,0.1);
+  overflow-x: auto;
+}
+
+.orchestr8-dag-layers {
+  display: flex;
+  align-items: center;
+  gap: 0;
+  min-width: fit-content;
+}
+
+.orchestr8-dag-layer {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 12px;
+  padding: 0 8px;
+}
+
+.orchestr8-dag-arrow {
+  display: flex;
+  align-items: center;
+  color: #d1d5db;
+  font-size: 24px;
+  padding: 0 4px;
+  align-self: center;
+}
+
+/* Step nodes */
+.orchestr8-node {
+  border: 2px solid #e5e7eb;
+  border-radius: 8px;
+  padding: 12px 16px;
+  min-width: 180px;
+  max-width: 220px;
+  background: #fff;
+  transition: border-color 0.2s, box-shadow 0.2s;
+}
+
+.orchestr8-node:hover {
+  box-shadow: 0 2px 8px rgba(0,0,0,0.12);
+}
+
+.orchestr8-node--pending {
+  border-color: #d1d5db;
+  background: #f9fafb;
+}
+
+.orchestr8-node--enqueued {
+  border-color: #a78bfa;
+  background: #faf5ff;
+}
+
+.orchestr8-node--running {
+  border-color: #60a5fa;
+  background: #eff6ff;
+  animation: orchestr8-pulse 2s infinite;
+}
+
+.orchestr8-node--completed {
+  border-color: #34d399;
+  background: #f0fdf4;
+}
+
+.orchestr8-node--failed {
+  border-color: #f87171;
+  background: #fff5f5;
+}
+
+@keyframes orchestr8-pulse {
+  0%, 100% { box-shadow: 0 0 0 0 rgba(96, 165, 250, 0.4); }
+  50% { box-shadow: 0 0 0 6px rgba(96, 165, 250, 0); }
+}
+
+.orchestr8-node-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  margin-bottom: 8px;
+}
+
+.orchestr8-node-name {
+  font-weight: 700;
+  font-size: 13px;
+  color: #1a1a2e;
+}
+
+.orchestr8-node-job {
+  font-size: 11px;
+  color: #6b7280;
+  margin-bottom: 8px;
+  word-break: break-all;
+}
+
+.orchestr8-node-meta {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  font-size: 11px;
+  color: #9ca3af;
+}
+
+.orchestr8-node-error {
+  margin-top: 8px;
+  font-size: 11px;
+  color: #ef4444;
+  background: #fee2e2;
+  border-radius: 4px;
+  padding: 4px 8px;
+  word-break: break-word;
+}
+
+.orchestr8-node-actions {
+  margin-top: 10px;
+  display: flex;
+  gap: 6px;
+}
+
+/* Empty state */
+.orchestr8-empty {
+  text-align: center;
+  padding: 48px 24px;
+  color: #9ca3af;
+}
+
+.orchestr8-empty p {
+  font-size: 16px;
+  margin: 0;
+}

data/app/controllers/orchestr8/application_controller.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Orchestr8
+  class ApplicationController < ::ActionController::Base
+    protect_from_forgery with: :exception
+  end
+end

data/app/controllers/orchestr8/steps_controller.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Orchestr8
+  class StepsController < ApplicationController
+    def retry
+      workflow = Workflow.find(params[:workflow_id])
+      step = workflow.steps.find(params[:id])
+      step.retry!
+      redirect_to workflow_path(workflow), notice: "Retrying step: #{step.name}"
+    end
+  end
+end