ruby_reactor 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 70ff13eac6ccfdaafcad7bd36db33adf6efbf91e84d22967527c84625373b921
-  data.tar.gz: a6c599b3967660e6761e92caf071f3d81b9a0c9db074261a8e79322b8955644c
+  metadata.gz: 598c9e49f00183da45e7b370c394445e9efddfe5952e3aabd701bbf954aa9712
+  data.tar.gz: 949ed81bd787d7bee47284e7f7b5905af3de4ae4057a90a4d0afa707959f5cbb
 SHA512:
-  metadata.gz: 32326a6f81978625cc3447284b023e19c79b5b051adb115fe13291112f2db9b815a06dedef990ee9b903e93288023d0a97b5f319da6d01fe23229bfe9e5ab47a
-  data.tar.gz: 17f9361bd3222c82d4f098acb87a16244260c41b9ef13d990986351905d6ae7968448ce8639f460616a56c7fbdfeca64b789fbccbd4253e4080403581cbe0754
+  metadata.gz: ae8f8f8a2916254068757d79d352df0a0148d4693f92238b456cecc1cb90d9f6cc77087f2b486e3359f5f0042779aecc9112df1da9898fa8efba6c9ed425ef39
+  data.tar.gz: 14fcbf6f880396176503008239e6517415977b19193f3f0d8600226acb7cf53d54a18bb79a42012646a1746d3202a62b73479715b6d088f69c208ce1c143aa92

data/.rubocop.yml

@@ -13,6 +13,7 @@ AllCops:
     - bin/*
     - db/**/*
     - config/**/*
+    - demo_app/**/*
 
 Style/StringLiterals:
   EnforcedStyle: double_quotes
@@ -27,13 +28,13 @@ Metrics/BlockLength:
 Metrics/MethodLength:
   Exclude:
     - spec/**/*
-  Max: 25
+  Max: 36
   CountComments: false
 
 Metrics/ClassLength:
   Exclude:
     - spec/**/*
-  Max: 200
+  Max: 250
 
 Style/Documentation:
   Exclude:
@@ -96,3 +97,10 @@ RSpec/DescribeClass:
 
 RSpec/AnyInstance:
   Enabled: false
+
+Naming/VariableNumber:
+  Enabled: false
+
+Metrics/ModuleLength:
+  Max: 200
+

data/README.md

@@ -2,6 +2,8 @@
 
 A dynamic, dependency-resolving saga orchestrator for Ruby. Ruby Reactor implements the Saga pattern with compensation-based error handling and DAG-based execution planning. It leverages **Sidekiq** for asynchronous execution and **Redis** for state persistence.
 
+![Payment workflow reactor](documentation/images/payment_workflow.png)
+
 ## Features
 
 - **DAG-based Execution**: Steps are executed based on their dependencies, allowing for parallel execution of independent steps.
@@ -9,6 +11,7 @@ A dynamic, dependency-resolving saga orchestrator for Ruby. Ruby Reactor impleme
 - **Map & Parallel Execution**: Iterate over collections in parallel with the `map` step, distributing work across multiple workers.
 - **Retries**: Configurable retry logic for failed steps, with exponential backoff.
 - **Compensation**: Automatic rollback of completed steps when a failure occurs.
+- **Interrupts**: Pause and resume workflows to wait for external events (webhooks, user approvals).
 - **Input Validation**: Integrated with `dry-validation` for robust input checking.
 
 ## Installation
@@ -47,6 +50,25 @@ RubyReactor.configure do |config|
 end
 ```
 
+## Web Dashboard
+
+RubyReactor comes with a built-in web dashboard to inspect reactor executions, view logs, and retry failed steps.
+
+### Rails Installation
+
+Mount the dashboard engine in your `config/routes.rb`:
+
+```ruby
+Rails.application.routes.draw do
+  # ... other routes
+  mount RubyReactor::Web::Application => '/ruby_reactor'
+end
+```
+
+![RubyReactor Dashboard Screenshot](documentation/images/failed_order_processing.png)
+
+You can secure the dashboard using standard Rails authentication methods (e.g., `authenticate` block with Devise).
+
 ## Usage
 
 RubyReactor allows you to define complex workflows as "reactors" with steps that can depend on each other, handle failures with compensations, and validate inputs.
@@ -198,6 +220,42 @@ def create(params)
 end
 ```
 
+### Interrupts (Pause & Resume)
+
+Pause execution to wait for external events like webhooks or user approvals.
+
+```ruby
+class ApprovalReactor < RubyReactor::Reactor
+  step :submit_request do
+    run { |args| RequestService.submit(args) }
+  end
+
+  interrupt :wait_for_manager do
+    wait_for :submit_request
+    # Resume using this ID
+    correlation_id { |ctx| "req-#{ctx.result(:submit_request)[:id]}" }
+  end
+
+  step :process_decision do
+    argument :decision, result(:wait_for_manager)
+    run do |args| 
+      args[:decision] == 'approved' ? Success() : Failure("Rejected")
+    end
+  end
+end
+
+# Usage:
+# 1. Start execution
+execution = ApprovalReactor.run(params) # => Returns Paused status
+
+# 2. Later, resume it via correlation ID
+ApprovalReactor.continue_by_correlation_id(
+  correlation_id: "req-123",
+  payload: "approved",
+  step_name: :wait_for_manager
+)
+```
+
 ### Map & Parallel Execution
 
 Process collections in parallel using the `map` step:
@@ -540,6 +598,9 @@ Master the `map` feature for processing collections. Learn about parallel execut
 ### [Retry Configuration](documentation/retry_configuration.md)
 Configure robust retry policies for your steps. This guide details the available backoff strategies (exponential, linear, fixed), how to configure retries at the reactor or step level, and how async retries work without blocking workers.
 
+### [Interrupts](documentation/interrupts.md)
+Learn how to pause and resume reactors to handle long-running processes, manual approvals, and asynchronous callbacks. Patterns for correlation IDs, timeouts, and payload validation.
+
 ### Examples
 - [Order Processing](documentation/examples/order_processing.md) - Complete order processing workflow example
 - [Payment Processing](documentation/examples/payment_processing.md) - Payment handling with compensation
@@ -548,12 +609,20 @@ Configure robust retry policies for your steps. This guide details the available
 ## Future improvements
 
 - [X] Global id to serialize ActiveRecord classes
-- [ ] Middlewares
-- [ ] Descriptive errors
+- [X] Descriptive errors
 - [X] `map` step to iterate over arrays in parallel
 - [X] `compose` special step to execute reactors as step
+- [X] `interrupt` to pause and resume reactors
+- [ ] Middlewares
 - [ ] Async ruby to parallelize same level steps
-- [ ] Dedicated interface to inspect reactor results and errors
+- [x] Web dashboard to inspect reactor results and errors
+- [ ] Multiple storage adapters
+  - [X] Redis
+  - [ ] ActiveRecord
+- [ ] Multiple Async adapters
+  - [X] Sidekiq
+  - [ ] ActiveJob
+- [ ] OpenTelemetry support
 
 ## Development
 

data/Rakefile

@@ -5,8 +5,33 @@ require "rspec/core/rake_task"
 
 RSpec::Core::RakeTask.new(:spec)
 
-require "rubocop/rake_task"
+namespace :build do
+  desc "Build the UI assets"
+  task :ui do
+    puts "Building UI..."
+    system("cd gui && npm install && npm run build") || abort("UI build failed")
 
-RuboCop::RakeTask.new
+    # Copy assets to public
+    # Vite builds to dist by default. We want it in lib/ruby_reactor/web/public
+    # Actually, we should configure Vite to build to the right place or copy it.
+    # Let's copy.
+    FileUtils.rm_rf("lib/ruby_reactor/web/public")
+    FileUtils.mkdir_p("lib/ruby_reactor/web/public")
+    FileUtils.cp_r("gui/dist/.", "lib/ruby_reactor/web/public/")
+    puts "UI built and assets copied to lib/ruby_reactor/web/public"
+  end
+end
+
+namespace :server do
+  desc "Start the server"
+  task :start do
+    puts "Starting server..."
+    system("rackup -Ilib lib/ruby_reactor/web/config.ru -p 9292") || abort("Server failed to start")
+  end
+end
+
+# require "rubocop/rake_task"
+
+# RuboCop::RakeTask.new
 
 task default: %i[spec rubocop]

data/documentation/interrupts.md

@@ -0,0 +1,161 @@
+# Interrupts (Pause & Resume)
+
+RubyReactor introduces the `interrupt` mechanism to support long-running processes that require external input, such as user approvals, webhooks, or asynchronous job completions. Unlike standard steps that execute immediately, an `interrupt` pauses the reactor execution and persists its state, waiting for a signal to resume.
+
+## DSL Usage
+
+Use the `interrupt` keyword to define a pause point in your reactor.
+
+```ruby
+class ReportReactor < RubyReactor::Reactor
+  step :request_report do
+    run do
+      response = HTTP.post("https://api.example.com/reports")
+      Success(response.fetch(:id))
+    end
+  end
+
+  interrupt :wait_for_report do
+    # Declare dependency: execution must trigger this interrupt only after :request_report succeeds
+    wait_for :request_report
+
+    # Optional: deterministic correlation ID for looking up this execution later
+    correlation_id do |context|
+      "report-#{context.result(:request_report)}"
+    end
+
+    # Optional: timeout in seconds
+    # Strategies:
+    # - :lazy (default) - checked only when resume is attempted
+    # - :active - schedules a background job to wake up the reactor and fail it
+    timeout 1800, strategy: :active
+
+    # Optional: validate incoming payload immediately using dry-validation
+    validate do
+      required(:status).filled(:string)
+      required(:url).filled(:string)
+    end
+
+    # Optional: limit validation attempts (default: 1)
+    # If exhausted, the reactor is cancelled and compensated.
+    # Use :infinity for unlimited attempts.
+    max_attempts 3
+  end
+
+  step :process_report do
+    # The result of the interrupt step is the payload provided when resuming
+    argument :webhook_payload, result(:wait_for_report)
+
+    run do |args|
+      Success(ReportProcessor.call(args[:webhook_payload]))
+    end
+  end
+end
+```
+
+### Options
+
+*   **`wait_for`**: declare dependencies similar to `step`.
+*   **`correlation_id`**: A block that returns a unique string to identify this execution. This allows you to resume the reactor using a business key (e.g., order ID) instead of the internal execution UUID.
+*   **`timeout`**: Set a time limit for the interrupt.
+*   **`validate`**: A `dry-validation` schema block to validate the payload provided when resuming.
+*   **`max_attempts`**: Limit the number of times `continue` can be called with an invalid payload before the reactor is automatically cancelled and compensated. Defaults to 1. Set to `:infinity` for unlimited retries.
+
+## Runtime Behavior
+
+When a reactor encounters an `interrupt`:
+
+1.  It executes any dependencies.
+2.  It persists the full `Context` (results of previous steps) to the configured storage (e.g., Redis).
+3.  It returns an `InterruptResult` and halts execution.
+
+```ruby
+execution = ReportReactor.run(company_id: 1)
+
+if execution.paused?
+  execution.id         # => "uuid-123"
+  execution.status     # => :paused
+end
+```
+
+## Resuming Execution
+
+You can resume a paused reactor using its UUID or the defined `correlation_id`.
+
+### By UUID
+
+```ruby
+ReportReactor.continue(
+  id: "uuid-123",
+  payload: { status: "completed", url: "..." },
+  step_name: :wait_for_report
+)
+```
+
+### By Correlation ID
+
+```ruby
+ReportReactor.continue_by_correlation_id(
+  correlation_id: "report-999",
+  payload: { status: "completed", url: "..." },
+  step_name: :wait_for_report
+)
+```
+
+### Resuming Method Styles
+
+There are two ways to invoke continuation:
+
+1.  **Strict / Fire-and-Forget (Class Method)**:
+    *   `Reactor.continue(...)`
+    *   If payload is invalid, it **automatically compensates (undo)** and cancels the reactor.
+    *   Best for webhooks where you can't ask the sender to fix the payload.
+
+2.  **Flexible (Instance Method)**:
+    *   First find the reactor: `reactor = ReportReactor.find("uuid-123")`
+    *   Then call: `result = reactor.continue(payload: ..., step_name: :wait_for_report)`
+    *   If payload is invalid, it returns a failure result but **does not** cancel execution.
+    *   Allows you to handle the error (e.g., show a form error to a user) and try again.
+
+## Cancellation & Undo
+
+You can cancel a paused reactor if the operation is no longer needed.
+
+```ruby
+# Undo: Runs defined compensations for completed steps in reverse order, then deletes execution.
+ReportReactor.undo("uuid-123")
+
+# Cancel: Stops execution immediately and marks the reactor as cancelled with the provided reason.
+# The context is preserved for inspection, but resumption is disabled.
+ReportReactor.cancel("uuid-123", reason: "User cancelled")
+```
+
+## Common Use Cases
+
+### Human Approvals
+
+```ruby
+interrupt :wait_for_approval do
+  wait_for :submit_request
+  correlation_id { |ctx| "approval-#{ctx.input(:request_id)}" }
+end
+
+step :process_decision do
+  argument :decision, result(:wait_for_approval)
+  run do |args|
+    if args[:decision][:approved]
+      Success("Approved")
+    else
+      Failure("Rejected")
+    end
+  end
+end
+```
+
+### Webhooks
+
+Use `correlation_id` to map an external resource ID (like a Payment Intent ID) back to the reactor waiting for confirmation.
+
+### Scheduled Follow-ups
+
+Using `timeout` with `strategy: :active` to wake up a reactor after a delay if no external event occurs (e.g., expiring a reservation).

data/gui/.gitignore

@@ -0,0 +1,24 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+dist
+dist-ssr
+*.local
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?

data/gui/README.md

@@ -0,0 +1,73 @@
+# React + TypeScript + Vite
+
+This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.
+
+Currently, two official plugins are available:
+
+- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Babel](https://babeljs.io/) (or [oxc](https://oxc.rs) when used in [rolldown-vite](https://vite.dev/guide/rolldown)) for Fast Refresh
+- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/) for Fast Refresh
+
+## React Compiler
+
+The React Compiler is not enabled on this template because of its impact on dev & build performances. To add it, see [this documentation](https://react.dev/learn/react-compiler/installation).
+
+## Expanding the ESLint configuration
+
+If you are developing a production application, we recommend updating the configuration to enable type-aware lint rules:
+
+```js
+export default defineConfig([
+  globalIgnores(['dist']),
+  {
+    files: ['**/*.{ts,tsx}'],
+    extends: [
+      // Other configs...
+
+      // Remove tseslint.configs.recommended and replace with this
+      tseslint.configs.recommendedTypeChecked,
+      // Alternatively, use this for stricter rules
+      tseslint.configs.strictTypeChecked,
+      // Optionally, add this for stylistic rules
+      tseslint.configs.stylisticTypeChecked,
+
+      // Other configs...
+    ],
+    languageOptions: {
+      parserOptions: {
+        project: ['./tsconfig.node.json', './tsconfig.app.json'],
+        tsconfigRootDir: import.meta.dirname,
+      },
+      // other options...
+    },
+  },
+])
+```
+
+You can also install [eslint-plugin-react-x](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-x) and [eslint-plugin-react-dom](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-dom) for React-specific lint rules:
+
+```js
+// eslint.config.js
+import reactX from 'eslint-plugin-react-x'
+import reactDom from 'eslint-plugin-react-dom'
+
+export default defineConfig([
+  globalIgnores(['dist']),
+  {
+    files: ['**/*.{ts,tsx}'],
+    extends: [
+      // Other configs...
+      // Enable lint rules for React
+      reactX.configs['recommended-typescript'],
+      // Enable lint rules for React DOM
+      reactDom.configs.recommended,
+    ],
+    languageOptions: {
+      parserOptions: {
+        project: ['./tsconfig.node.json', './tsconfig.app.json'],
+        tsconfigRootDir: import.meta.dirname,
+      },
+      // other options...
+    },
+  },
+])
+```

data/gui/eslint.config.js

@@ -0,0 +1,23 @@
+import js from '@eslint/js'
+import globals from 'globals'
+import reactHooks from 'eslint-plugin-react-hooks'
+import reactRefresh from 'eslint-plugin-react-refresh'
+import tseslint from 'typescript-eslint'
+import { defineConfig, globalIgnores } from 'eslint/config'
+
+export default defineConfig([
+  globalIgnores(['dist']),
+  {
+    files: ['**/*.{ts,tsx}'],
+    extends: [
+      js.configs.recommended,
+      tseslint.configs.recommended,
+      reactHooks.configs.flat.recommended,
+      reactRefresh.configs.vite,
+    ],
+    languageOptions: {
+      ecmaVersion: 2020,
+      globals: globals.browser,
+    },
+  },
+])

data/gui/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>ui</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>