ruby_reactor 0.3.0 → 0.3.2

data/documentation/core_concepts.md

@@ -24,12 +24,15 @@ Steps are the individual units of work within a reactor. Each step has a name an
 
 ### Inline Step Definition
 
+`run` blocks always receive two positional arguments: the resolved arguments hash and the execution context. Declare inputs with `argument :name, source`:
+
 ```ruby
 step :validate_order do
-  run do |order_id|
-    # Step implementation
-    order = Order.find(order_id)
-    raise "Order not found" unless order
+  argument :order_id, input(:order_id)
+
+  run do |args, _context|
+    order = Order.find(args[:order_id])
+    return Failure("Order not found") unless order
     Success({ order: order })
   end
 end
@@ -144,29 +147,22 @@ end
 
 ## Results
 
-Every reactor execution returns a comprehensive result object.
-<!-- 
-# TODO
-
-This is not true, update to use instance and what is stored
-```ruby
-result = OrderProcessingReactor.run(order_id: 123)
-
-# Overall status
-result.success?        # => true/false
-result.failure?        # => true/false
+`Reactor.run` returns one of four result types:
 
-# Step outputs
-result.step_results    # => { validate_order: {...}, process_payment: {...} }
-result.intermediate_results  # => Hash of all step outputs
+- **`RubyReactor::Success`** — `success?` is `true`. `value` holds the output of the step named in `returns`, or the full `intermediate_results` hash if no `returns` is declared.
+- **`RubyReactor::Failure`** — `failure?` is `true`. Readers include `error`, `step_name`, `reactor_name`, `step_arguments`, `inputs`, `exception_class`, `file_path`, `line_number`, `backtrace`, `validation_errors`, and `retryable?`.
+- **`RubyReactor::AsyncResult`** — returned by an async reactor or when a step hands off to a worker. Readers: `job_id`, `execution_id`, `intermediate_results`.
+- **`RubyReactor::InterruptResult`** — returned when an `interrupt` step pauses execution. Readers: `execution_id`, `correlation_id`, `status` (`:paused`), `timeout_at`, `intermediate_results`.
 
-# Execution tracking
-result.completed_steps # => #<Set: {:validate_order, :process_payment}>
-result.inputs          # => { order_id: 123 }
+Step-by-step state lives on the context, not the result object. Reload via `Reactor.find(execution_id)` to inspect:
 
-# Error information
-result.error           # => Exception object if failed
-``` -->
+```ruby
+reactor = OrderProcessingReactor.find(execution_id)
+reactor.context.intermediate_results # => { validate_order: {...}, ... }
+reactor.context.status               # => "completed" | "failed" | "paused" | "running"
+reactor.execution_trace              # ordered list of run/undo/compensate entries
+reactor.result                       # reconstructed Success/Failure/InterruptResult
+```
 
 ## Error Handling
 
@@ -178,14 +174,18 @@ When a step fails, execution stops and compensation begins:
 
 ```ruby
 step :process_payment do
-  run do
+  argument :amount, input(:amount)
+  argument :token, input(:card_token)
+
+  run do |args, _ctx|
     # This might fail
-    PaymentService.charge(amount, token)
+    PaymentService.charge(args[:amount], args[:token])
   end
 
-  compensate do |payment_id: nil, **|
-    # Undo the payment if it was created
-    PaymentService.refund(payment_id) if payment_id
+  compensate do |error, args, _ctx|
+    # Compensation receives (error, arguments, context)
+    # Best-effort cleanup specific to this step's failure
+    AuditService.log_payment_failure(args[:token], error.message)
   end
 end
 ```
@@ -349,22 +349,23 @@ result = Reactor.run(inputs)
 
 ### Asynchronous Execution
 
-<!-- TODO: review this part -->
-
 ```ruby
 async_result = Reactor.run(inputs)
 # Returns immediately
-# Check status later
-
-case async_result.status
-when :success
-  result = async_result.result
-when :failed
-  error = async_result.error
+async_result.execution_id # UUID to look up state later
+
+# Reload to inspect status / final result
+reactor = Reactor.find(async_result.execution_id)
+case reactor.context.status.to_s
+when "completed" then reactor.result.value
+when "failed"    then reactor.result.error
+when "paused"    then reactor.result.correlation_id
+when "running"   then :still_running
 end
 ```
 
 **Characteristics:**
+
 - Non-blocking execution
 - Background processing with Sidekiq
 - Retry capabilities
@@ -372,33 +373,38 @@ end
 
 ## Step Arguments
 
-Steps receive arguments through keyword arguments, with automatic dependency injection.
+`run` blocks always receive two positional arguments: the resolved arguments hash and the context. Declare each argument explicitly with `argument :name, source` — there is no implicit keyword injection.
+
+Sources you can use:
+
+- `input(:name)` — value from the reactor's inputs (the hash passed to `Reactor.run`).
+- `input(:name, :path)` — nested path access into a hash input.
+- `result(:step_name)` — full output of a previous step.
+- `result(:step_name, :path)` — nested path into a previous step's output.
+- `value(literal)` — a constant value.
 
 ```ruby
 step :validate_order do
-  run do |order_id:, customer_id:|
-    # Direct access to reactor inputs
-    order = Order.find_by(id: order_id, customer_id: customer_id)
+  argument :order_id, input(:order_id)
+  argument :customer_id, input(:customer_id)
+
+  run do |args, _context|
+    order = Order.find_by(id: args[:order_id], customer_id: args[:customer_id])
     Success({ order: order })
   end
 end
 
 step :process_payment do
-  argument :order_data, result(:validate_order)
+  argument :order, result(:validate_order, :order)
 
   run do |args, _context|
-    # Access results from previous steps
-    order = args[:order_data][:order]
-    payment = PaymentService.charge(order.total, order.card_token)
+    payment = PaymentService.charge(args[:order].total, args[:order].card_token)
     Success({ payment_id: payment.id })
   end
 end
 ```
 
-**Argument Resolution:**
-1. **Step Results**: Outputs from completed dependent steps
-2. **Reactor Inputs**: Original inputs passed to `run()`
-3. **Intermediate Results**: Accumulated outputs from all steps
+If a step declares no `argument`s, the reactor's raw inputs hash is passed as `args`.
 
 ## Undo
 
@@ -415,15 +421,16 @@ Unlike compensation which only runs for the failing step, undo is triggered duri
 
 ```ruby
 step :reserve_inventory do
-  run do |items:|
-    reservation_id = InventoryService.reserve(items)
+  argument :items, input(:items)
+
+  run do |args, _ctx|
+    reservation_id = InventoryService.reserve(args[:items])
     Success({ reservation_id: reservation_id })
   end
 
-  undo do |reservation_result, arguments, context|
+  undo do |result, arguments, context|
     # Undo receives the step's result, arguments, and full context
-    reservation_id = reservation_result[:reservation_id]
-    InventoryService.release(reservation_id)
+    InventoryService.release(result[:reservation_id])
     Success("Inventory reservation released")
   end
 end
@@ -438,9 +445,11 @@ Undo blocks receive three parameters:
 
 ```ruby
 step :complex_operation do
-  run do |input:|
+  argument :input, input(:payload)
+
+  run do |args, _ctx|
     # Complex operation that modifies external state
-    record = create_record(input)
+    record = create_record(args[:input])
     notification = send_notification(record)
     Success({ record_id: record.id, notification_id: notification.id })
   end
@@ -477,8 +486,10 @@ Compensation runs immediately when a step fails, before the broader rollback pro
 
 ```ruby
 step :reserve_inventory do
-  run do |items:|
-    reservation_id = InventoryService.reserve(items)
+  argument :items, input(:items)
+
+  run do |args, _ctx|
+    reservation_id = InventoryService.reserve(args[:items])
     Success({ reservation_id: reservation_id })
   end
 
@@ -501,9 +512,12 @@ Compensation blocks receive three parameters:
 
 ```ruby
 step :process_payment do
-  run do |order:, payment_method:|
+  argument :order, result(:validate_order)
+  argument :payment_method, input(:payment_method)
+
+  run do |args, _ctx|
     # Payment processing logic that might fail
-    PaymentService.charge(order.total, payment_method)
+    PaymentService.charge(args[:order].total, args[:payment_method])
   end
 
   compensate do |error, arguments, context|

data/documentation/examples/inventory_management.md

@@ -198,7 +198,6 @@ class InventoryManagementReactor < RubyReactor::Reactor
     argument :request_data, result(:validate_request)
     argument :replenishment_data, result(:check_replenishment)
 
-    idempotent true
     retries max_attempts: 3, backoff: :linear, base_delay: 5.seconds
 
     run do |args, _context|
@@ -283,7 +282,7 @@ class BulkInventoryReactor < RubyReactor::Reactor
           if result.success?
             results << { success: true, operation: op }
           else
-            results << { success: false, operation: op, error: result.error.message }
+            results << { success: false, operation: op, error: result.error.to_s }
           end
         rescue => e
           results << { success: false, operation: op, error: e.message }
@@ -629,7 +628,7 @@ RSpec.describe InventoryManagementReactor do
       )
 
       expect(result).to be_failure
-      expect(result.error.message).to include("Insufficient stock")
+      expect(result.error).to include("Insufficient stock")
     end
   end
 

data/documentation/examples/order_processing.md

@@ -46,28 +46,30 @@ class OrderProcessingReactor < RubyReactor::Reactor
   # Reactor-level retry defaults
   retry_defaults max_attempts: 3, backoff: :exponential, base_delay: 2.seconds
 
+  input :order_id do
+    required(:order_id).filled(:string)
+  end
+
   step :validate_order do
-    validate_args do
-      required(:order_id).filled(:string)
-    end
+    argument :order_id, input(:order_id)
 
-    run do |order_id:|
-      order = Order.find_by(id: order_id)
-      raise "Order not found" unless order
-      raise "Order already processed" if order.processed?
-      raise "Order cancelled" if order.cancelled?
+    run do |args, _ctx|
+      order = Order.find_by(id: args[:order_id])
+      return Failure("Order not found") unless order
+      return Failure("Order already processed") if order.processed?
+      return Failure("Order cancelled") if order.cancelled?
 
       Success({ order: order })
     end
   end
 
   step :check_inventory do
-    argument :order, result(:validate_order)
+    argument :order, result(:validate_order, :order)
 
-    run do |order:, **|
+    run do |args, _ctx|
       unavailable_items = []
 
-      order.items.each do |item|
+      args[:order].items.each do |item|
         product = Product.find(item.product_id)
         if product.inventory_count < item.quantity
           unavailable_items << {
@@ -78,35 +80,37 @@ class OrderProcessingReactor < RubyReactor::Reactor
         end
       end
 
-      raise "Insufficient inventory: #{unavailable_items}" unless unavailable_items.empty?
+      return Failure("Insufficient inventory: #{unavailable_items}") unless unavailable_items.empty?
 
       Success({ inventory_checked: true })
     end
   end
 
   step :reserve_inventory do
-    argument :order, result(:validate_order)
+    argument :order, result(:validate_order, :order)
 
-    run do |order:, **|
-      reservation_id = InventoryService.reserve_items(order.items)
-      raise "Inventory reservation failed" unless reservation_id
+    run do |args, _ctx|
+      reservation_id = InventoryService.reserve_items(args[:order].items)
+      return Failure("Inventory reservation failed") unless reservation_id
 
       Success({ reservation_id: reservation_id })
     end
 
-    undo do |reservation_id:, **|
-      # Release reservation on failure
-      InventoryService.release_reservation(reservation_id) if reservation_id
+    undo do |result, _args, _ctx|
+      # Release reservation when a later step fails
+      InventoryService.release_reservation(result[:reservation_id]) if result[:reservation_id]
+      Success()
     end
   end
 
   step :process_payment do
-    argument :order, result(:validate_order)
+    argument :order, result(:validate_order, :order)
 
     # Payment processing needs careful retry handling
     retries max_attempts: 2, backoff: :fixed, base_delay: 30.seconds
 
-    run do |order:, **|
+    run do |args, _ctx|
+      order = args[:order]
       payment_result = PaymentService.charge(
         amount: order.total,
         currency: order.currency,
@@ -114,44 +118,42 @@ class OrderProcessingReactor < RubyReactor::Reactor
         description: "Order ##{order.id}"
       )
 
-      raise "Payment failed: #{payment_result.error}" unless payment_result.success?
+      return Failure("Payment failed: #{payment_result.error}") unless payment_result.success?
 
       Success({ payment_id: payment_result.id, payment_amount: order.total })
     end
 
-    undo do |payment_id:, **|
-      # Refund payment on failure
-      PaymentService.refund(payment_id) if payment_id
+    undo do |result, _args, _ctx|
+      PaymentService.refund(result[:payment_id]) if result[:payment_id]
+      Success()
     end
   end
 
   step :update_inventory do
-    argument :order, result(:validate_order)
-    argument :reservation_id, result(:reserve_inventory)
+    argument :order, result(:validate_order, :order)
+    argument :reservation_id, result(:reserve_inventory, :reservation_id)
 
-    run do |order:, reservation_id:, **|
-      # Convert reservation to permanent inventory reduction
-      success = InventoryService.confirm_reservation(reservation_id)
-      raise "Inventory update failed" unless success
+    run do |args, _ctx|
+      success = InventoryService.confirm_reservation(args[:reservation_id])
+      return Failure("Inventory update failed") unless success
 
       Success({ inventory_updated: true })
     end
 
-    undo do |order:, reservation_id:, **|
-      # This shouldn't normally happen since payment succeeded
-      # But if it does, we need to restore inventory
-      InventoryService.restore_from_reservation(reservation_id) if reservation_id
+    undo do |_result, args, _ctx|
+      InventoryService.restore_from_reservation(args[:reservation_id]) if args[:reservation_id]
+      Success()
     end
   end
 
   step :update_order_status do
-    argument :order, result(:validate_order)
-    argument :payment_id, result(:process_payment)
+    argument :order, result(:validate_order, :order)
+    argument :payment_id, result(:process_payment, :payment_id)
 
-    run do |order:, payment_id:, **|
-      order.update!(
+    run do |args, _ctx|
+      args[:order].update!(
         status: :completed,
-        payment_id: payment_id,
+        payment_id: args[:payment_id],
         processed_at: Time.current
       )
 
@@ -160,23 +162,25 @@ class OrderProcessingReactor < RubyReactor::Reactor
   end
 
   step :send_confirmation do
-    argument :order, result(:validate_order)
-    argument :payment_id, result(:process_payment)
+    argument :order, result(:validate_order, :order)
+    argument :payment_id, result(:process_payment, :payment_id)
 
     retries max_attempts: 3, backoff: :linear, base_delay: 10.seconds
 
-    run do |order:, payment_id:, **|
+    run do |args, _ctx|
       email_result = EmailService.send_order_confirmation(
-        to: order.customer.email,
-        order: order,
-        payment_id: payment_id
+        to: args[:order].customer.email,
+        order: args[:order],
+        payment_id: args[:payment_id]
       )
 
-      raise "Confirmation email failed" unless email_result.success?
+      return Failure("Confirmation email failed") unless email_result.success?
 
       Success({ confirmation_sent: true })
     end
   end
+
+  returns :send_confirmation
 end
 ```
 
@@ -187,16 +191,21 @@ end
 ```ruby
 # Start order processing asynchronously
 async_result = OrderProcessingReactor.run(order_id: 12345)
+async_result.execution_id # UUID for state lookup
 
-# Check status later
-case async_result.status
-when :success
+# Reload state later (e.g. from a polling endpoint)
+reactor = OrderProcessingReactor.find(async_result.execution_id)
+case reactor.context.status.to_s
+when "completed"
   puts "Order processed successfully!"
-  result = async_result.result
-  puts "Payment ID: #{result.step_results[:process_payment][:payment_id]}"
-when :failed
-  puts "Order processing failed: #{async_result.error.message}"
+  payment_id = reactor.context.intermediate_results[:process_payment][:payment_id]
+  puts "Payment ID: #{payment_id}"
+when "failed"
+  failure = reactor.result # RubyReactor::Failure
+  puts "Order processing failed at #{failure.step_name}: #{failure.error}"
   # Could trigger manual review process
+when "running"
+  puts "Still processing..."
 end
 ```
 
@@ -204,14 +213,15 @@ end
 
 ```ruby
 # For testing or immediate processing
-result = OrderProcessingReactor.run(order_id: 12345)
+reactor = OrderProcessingReactor.new
+result = reactor.run(order_id: 12345)
 
 if result.success?
   puts "Order completed!"
-  puts "Steps completed: #{result.completed_steps.to_a}"
+  puts "Steps completed: #{reactor.context.intermediate_results.keys}"
 else
-  puts "Failed at step: #{result.error.step_name}"
-  puts "Error: #{result.error.message}"
+  puts "Failed at step: #{result.step_name}"
+  puts "Error: #{result.error}"
 end
 ```
 
@@ -256,10 +266,10 @@ RSpec.describe OrderProcessingReactor do
       allow(InventoryService).to receive(:confirm_reservation).and_return(true)
       allow(EmailService).to receive(:send_order_confirmation).and_return(successful_email)
 
-      result = OrderProcessingReactor.run(order_id: order.id)
+      subject = test_reactor(OrderProcessingReactor, order_id: order.id)
 
-      expect(result).to be_success
-      expect(result.completed_steps).to include(:send_confirmation)
+      expect(subject).to be_success
+      expect(subject).to have_run_step(:send_confirmation)
     end
   end
 
@@ -271,10 +281,10 @@ RSpec.describe OrderProcessingReactor do
 
       expect(InventoryService).to receive(:release_reservation).with("res_123")
 
-      result = OrderProcessingReactor.run(order_id: order.id)
+      subject = test_reactor(OrderProcessingReactor, order_id: order.id)
 
-      expect(result).to be_failure
-      expect(result.error.message).to include("Payment failed")
+      expect(subject).to be_failure
+      expect(subject.error).to include("Payment failed")
     end
   end
 end
@@ -315,15 +325,16 @@ email_delivery_failure_rate
 class PartialOrderProcessingReactor < OrderProcessingReactor
   # Override to allow partial fulfillment
   step :check_inventory do
-    run do |order:, **|
-      available_items, unavailable_items = partition_available_items(order.items)
+    argument :order, result(:validate_order, :order)
+
+    run do |args, _ctx|
+      available_items, unavailable_items = partition_available_items(args[:order].items)
 
       if available_items.any? && unavailable_items.any?
-        # Create partial order for available items
-        partial_order = create_partial_order(order, available_items)
+        partial_order = create_partial_order(args[:order], available_items)
         Success({ partial_order: partial_order, unavailable_items: unavailable_items })
       elsif available_items.empty?
-        raise "No items available"
+        Failure("No items available")
       else
         Success({ inventory_checked: true })
       end
@@ -336,23 +347,27 @@ end
 
 ```ruby
 class OrderCancellationReactor < RubyReactor::Reactor
+  input :order_id do
+    required(:order_id).filled(:string)
+  end
+
   step :load_order do
-    validate_args do
-      required(:order_id).filled(:string)
-    end
+    argument :order_id, input(:order_id)
 
-    run do |order_id:|
-      order = Order.find_by(id: order_id)
-      raise "Order not found" unless order
+    run do |args, _ctx|
+      order = Order.find_by(id: args[:order_id])
+      return Failure("Order not found") unless order
       Success({ order: order })
     end
   end
 
   step :cancel_order do
-    run do |order:, **|
+    argument :order, result(:load_order, :order)
+
+    run do |args, _ctx|
+      order = args[:order]
       # Only cancel if not already completed
       if order.completed?
-        # Initiate refund and inventory restoration
         PaymentService.refund(order.payment_id)
         InventoryService.restore_order_items(order)
       end