ruby_reactor 0.3.2 → 0.4.0

data/documentation/getting_started.md

@@ -1,242 +0,0 @@
-# Getting Started with RubyReactor
-
-This guide walks you through installation, configuration, and your first reactor.
-
-## Installation
-
-Add RubyReactor to your Gemfile:
-
-```ruby
-gem 'ruby_reactor'
-```
-
-Or install directly:
-
-```bash
-gem install ruby_reactor
-```
-
-## Configuration
-
-RubyReactor uses Redis for state persistence and Sidekiq for async execution. Configure both before running any reactors:
-
-```ruby
-RubyReactor.configure do |config|
-  # Redis configuration for state persistence
-  config.storage.adapter = :redis
-  config.storage.redis_url = ENV.fetch("REDIS_URL", "redis://localhost:6379/0")
-  config.storage.redis_options = { timeout: 1 }
-
-  # Sidekiq configuration for async execution
-  config.sidekiq_queue = :default
-  config.sidekiq_retry_count = 3
-
-  # Logger
-  config.logger = Logger.new($stdout)
-end
-```
-
-## Your First Reactor
-
-Reactors are subclasses of `RubyReactor::Reactor`. Declare `input`s, define `step`s with their `argument`s and `run` block, and optionally a `returns` step:
-
-```ruby
-require 'ruby_reactor'
-
-class OrderProcessingReactor < RubyReactor::Reactor
-  input :order_id do
-    required(:order_id).filled(:integer, gt?: 0)
-  end
-
-  step :validate_order do
-    argument :order_id, input(:order_id)
-
-    run do |args, _context|
-      order = Order.find_by(id: args[:order_id])
-      return Failure("Order not found") unless order
-      return Failure("Order already processed") if order.processed?
-
-      Success({ order: order })
-    end
-  end
-
-  step :process_payment do
-    argument :order, result(:validate_order, :order)
-
-    run do |args, _context|
-      payment = PaymentService.charge(args[:order].total, args[:order].customer.card_token)
-      payment.success? ? Success({ payment_id: payment.id }) : Failure("Payment failed")
-    end
-  end
-
-  step :update_inventory do
-    argument :order, result(:validate_order, :order)
-
-    run do |args, _context|
-      args[:order].items.each do |item|
-        InventoryService.decrement(item.product_id, item.quantity)
-      end
-      Success({ inventory_updated: true })
-    end
-  end
-
-  step :send_confirmation do
-    argument :order, result(:validate_order, :order)
-    argument :payment_id, result(:process_payment, :payment_id)
-
-    run do |args, _context|
-      EmailService.send_confirmation(args[:order].customer.email, order: args[:order])
-      Success({ confirmation_sent: true })
-    end
-  end
-
-  returns :send_confirmation
-end
-```
-
-### Run blocks always receive `(arguments, context)`
-
-Every step's `run` block receives two positional arguments: the resolved arguments hash and the execution context. Use `argument :name, source` to declare which value goes into `args[:name]`.
-
-## Executing a Reactor
-
-### Synchronous Execution
-
-```ruby
-result = OrderProcessingReactor.run(order_id: 123)
-
-if result.success?
-  puts "Order processed: #{result.value}"
-else
-  puts "Order processing failed: #{result.error}"
-end
-```
-
-`Reactor.run` returns one of:
-
-- `RubyReactor::Success` — `result.success?` is `true`, `result.value` holds the step output for `returns` (or the full `intermediate_results` hash if no `returns` is set).
-- `RubyReactor::Failure` — `result.failure?` is `true`. Useful readers: `result.error`, `result.step_name`, `result.exception_class`, `result.backtrace`, `result.step_arguments`.
-- `RubyReactor::AsyncResult` — returned when the reactor (or a step) is async. Holds `job_id`, `execution_id`, and any `intermediate_results` available at handoff.
-- `RubyReactor::InterruptResult` — returned when an `interrupt` step pauses execution. Use `result.execution_id` and `result.correlation_id` to resume later.
-
-### Asynchronous Execution
-
-For async execution, configure Sidekiq and either mark the reactor `async true` or mark individual steps async:
-
-```ruby
-class OrderProcessingReactor < RubyReactor::Reactor
-  async true  # Entire reactor runs in a Sidekiq worker
-
-  # ... steps defined above
-end
-
-async_result = OrderProcessingReactor.run(order_id: 123)
-async_result.execution_id # => UUID for looking up state later
-```
-
-To inspect a running execution, reload it from storage:
-
-```ruby
-reactor = OrderProcessingReactor.find(async_result.execution_id)
-reactor.context.status      # => "running" | "completed" | "failed" | "paused"
-reactor.result              # Success / Failure / InterruptResult
-```
-
-See [Async Reactors](async_reactors.md) for the full async model.
-
-## Inspecting the Context
-
-Step outputs are stored on the context, not the result object. After a sync execution you can reach them via the reactor instance:
-
-```ruby
-reactor = OrderProcessingReactor.new
-reactor.run(order_id: 123)
-
-reactor.context.intermediate_results[:validate_order]   # => { order: <Order> }
-reactor.context.intermediate_results[:process_payment]  # => { payment_id: "pay_123" }
-reactor.context.status                                  # => "completed"
-reactor.execution_trace                                 # => [{ type: :run, step: :validate_order, ... }, ...]
-```
-
-For black-box assertions in tests, use the `test_reactor` helper described in [Testing with RSpec](testing.md).
-
-## Step Dependencies
-
-Steps depend on each other through `argument :name, result(:other_step)`. The dependency graph topologically sorts steps; circular dependencies raise `RubyReactor::Error::DependencyError`:
-
-```ruby
-class ComplexReactor < RubyReactor::Reactor
-  step :validate_order do
-    run { |args, _ctx| validate_order_logic(args) }
-  end
-
-  step :check_inventory do
-    argument :order, result(:validate_order)
-
-    run do |args, _context|
-      check_inventory_for_order(args[:order])
-    end
-  end
-
-  step :process_payment do
-    argument :order, result(:check_inventory)
-
-    run do |args, _context|
-      process_payment_for_order(args[:order])
-    end
-  end
-end
-```
-
-You can also declare order without data flow using `wait_for :step_name`.
-
-## Error Handling and Compensation
-
-When a step fails (returns `Failure(...)` or raises), the reactor:
-
-1. Runs the **`compensate`** block of the failing step (signature: `|error, arguments, context|`).
-2. Walks back through previously successful steps and runs each one's **`undo`** block in reverse order (signature: `|result, arguments, context|`).
-3. Returns a `Failure`.
-
-```ruby
-class OrderProcessingReactor < RubyReactor::Reactor
-  step :process_payment do
-    argument :order, result(:validate_order)
-
-    run { |args, _ctx| PaymentService.charge(args[:order]) }
-
-    undo do |result, _args, _ctx|
-      # Runs if a later step fails
-      PaymentService.refund(result[:payment_id])
-      Success()
-    end
-  end
-
-  step :update_inventory do
-    argument :order, result(:validate_order)
-
-    run { |args, _ctx| InventoryService.decrement_all(args[:order].items) }
-
-    compensate do |_error, args, _ctx|
-      # Runs only if THIS step fails
-      args[:order].items.each { |i| InventoryService.increment(i.product_id, i.quantity) }
-      Success()
-    end
-  end
-end
-```
-
-If `update_inventory` fails: its `compensate` runs, then `process_payment`'s `undo` runs.
-
-See [Core Concepts](core_concepts.md#compensation) for the full compensation/undo model.
-
-## Next Steps
-
-- [Core Concepts](core_concepts.md) — Reactors, Steps, Context, Results
-- [Async Reactors](async_reactors.md) — Full and step-level async execution
-- [Retry Configuration](retry_configuration.md) — Backoff strategies and retry policies
-- [Interrupts](interrupts.md) — Pause/resume workflows
-- [Composition](composition.md) — Build complex flows from smaller reactors
-- [Data Pipelines](data_pipelines.md) — Map over collections in parallel
-- [Testing with RSpec](testing.md) — `test_reactor`, mocks, matchers
-- [Examples](examples/) — End-to-end workflows

data/documentation/interrupts.md

@@ -1,163 +0,0 @@
-# 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 |_args, _ctx|
-      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, _ctx|
-      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.execution_id  # => "uuid-123"
-  execution.correlation_id # => "report-..." (if defined)
-  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 undo/compensate blocks for completed steps in reverse order,
-# then marks the execution as cancelled.
-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(id: "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, _ctx|
-    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).