ruby_reactor 0.3.1 → 0.4.0

data/documentation/getting_started.md

@@ -1,224 +0,0 @@
-# Getting Started with RubyReactor
-
-This guide will help you get started with RubyReactor, from installation to your first reactor.
-
-## Installation
-
-Add RubyReactor to your Gemfile:
-
-```ruby
-gem 'ruby_reactor'
-```
-
-Or install directly:
-
-```bash
-gem install ruby_reactor
-```
-
-## Your First Reactor
-
-Let's create a simple order processing reactor:
-
-```ruby
-require 'ruby_reactor'
-
-class OrderProcessingReactor < RubyReactor::Reactor
-  step :validate_order do
-    validate_args do
-      required(:order_id).filled(:string)
-    end
-
-    run do |order_id|
-      # Validate the order exists and is in correct state
-      order = Order.find(order_id)
-      raise "Order not found" unless order
-      raise "Order already processed" if order.processed?
-
-      Success({ order: order })
-    end
-  end
-
-  step :process_payment do
-    run do |order:, **|
-      # Process payment for the order
-      payment_result = PaymentService.charge(order.total, order.customer.card_token)
-      raise "Payment failed" unless payment_result.success?
-
-      Success({ payment_id: payment_result.id })
-    end
-  end
-
-  step :update_inventory do
-    run do |order:, **|
-      # Update inventory for each item
-      order.items.each do |item|
-        InventoryService.decrement(item.product_id, item.quantity)
-      end
-
-      Success({ inventory_updated: true })
-    end
-  end
-
-  step :send_confirmation do
-    run do |order:, payment_id:, **|
-      # Send confirmation email
-      email_result = EmailService.send_confirmation(
-        order.customer.email,
-        order_id: order.id,
-        payment_id: payment_id
-      )
-
-      Success({ confirmation_sent: email_result.success? })
-    end
-  end
-end
-```
-
-## Executing a Reactor
-
-### Synchronous Execution
-
-```ruby
-# Run the reactor synchronously
-result = OrderProcessingReactor.run(order_id: 123)
-
-if result.success?
-  puts "Order processed successfully!"
-  puts "Results: #{result.step_results}"
-else
-  puts "Order processing failed: #{result.error}"
-end
-```
-
-### Asynchronous Execution
-
-For async execution, you need Sidekiq configured. Mark the reactor as async:
-
-```ruby
-class OrderProcessingReactor < RubyReactor::Reactor
-  async true  # Enable full reactor async
-
-  # ... steps defined above
-end
-
-# Run asynchronously
-async_result = OrderProcessingReactor.run(order_id: 123)
-# Returns immediately with AsyncResult
-# Check status later with async_result.status
-```
-
-## Understanding Results
-
-RubyReactor returns detailed execution results:
-
-```ruby
-result = OrderProcessingReactor.run(order_id: 123)
-
-# Check overall success
-result.success?  # => true/false
-
-# Access step results
-result.step_results[:validate_order]  # => { order: #<Order> }
-result.step_results[:process_payment] # => { payment_id: "pay_123" }
-
-# Access intermediate results
-result.intermediate_results  # => Hash of all step outputs
-
-# Check completed steps
-result.completed_steps  # => Set of completed step names
-
-# Error information (if failed)
-result.error  # => Exception that caused failure
-```
-
-## Step Dependencies
-
-Steps can depend on each other using the `argument` method with `result()`:
-
-```ruby
-class ComplexReactor < RubyReactor::Reactor
-  step :validate_order do
-    run { validate_order_logic }
-  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
-```
-
-## Error Handling and Compensation
-
-RubyReactor automatically handles errors and provides compensation:
-
-```ruby
-class OrderProcessingReactor < RubyReactor::Reactor
-  step :validate_order do
-    run { validate_order_logic }
-  end
-
-  step :process_payment do
-    run { process_payment_logic }
-
-    undo do |payment_id:, **|
-      # Undo the payment if something fails later
-      PaymentService.refund(payment_id)
-    end
-  end
-
-  step :update_inventory do
-    run { update_inventory_logic }
-
-    compensate do |order:, **|
-      # Restore inventory if something fails later
-      order.items.each do |item|
-        InventoryService.increment(item.product_id, item.quantity)
-      end
-    end
-  end
-end
-```
-
-If `update_inventory` fails, RubyReactor will:
-1. Run the `update_inventory` compensate block
-2. Run the `process_payment` undo block
-3. Return a failure result
-
-## Configuration
-
-### Sidekiq Setup (for Async)
-
-Add to your Sidekiq configuration:
-
-```ruby
-# config/sidekiq.rb
-require 'ruby_reactor/worker'
-
-# Configure RubyReactor
-RubyReactor.configure do |config|
-  config.sidekiq_queue = :default
-  config.sidekiq_retry_count = 3
-  config.logger = Logger.new('log/ruby_reactor.log')
-end
-```
-
-
-## Next Steps
-
-- Learn about [async reactors](async_reactors.md)
-- Configure [retry policies](retry_configuration.md)
-- See [examples](examples/) for more patterns
-- Check the [API reference](api_reference.md) for detailed documentation

data/documentation/interrupts.md

@@ -1,161 +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
-      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).