ruby_reactor 0.3.0 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 863c83e92cbfab470e39107c580ceabce444133973b723662a89e5bf0211c3ab
-  data.tar.gz: 1209b5587efc055bc787731694a6dc2b7eab8b3d5a6ff729728aa29ea601e2e0
+  metadata.gz: de5c91a5450cb522097965aa4348760438b60babd05da33f9f7ec1a07fe9bd07
+  data.tar.gz: d565e81c6ba6e057b56912311bf16dee95ce0c441eb76f2b893658b751568b2c
 SHA512:
-  metadata.gz: 146d14cd32b12c95764e493f2de2d826dbe074ec4e4b44613b788d748d52fe38644fd86f1590f6bb0b1a0d1840c2200ab29a6d8e78db27f8f6abf099faf74756
-  data.tar.gz: 3d5b7c43182ee2d1c5c06ba90b7e2177a3dffbecdc8fb3e91db14f99bcd02807ebfa98c0e240412b790ec1d69609dc30995d9ee1aea9c8cb8ecd69d4d0fb2ac7
+  metadata.gz: dde49e045303aeb4bcf414ea30b7d85d8fb8a782f873dd9ebb4a9d7d0524e74de37ba4e53ddc11ac6dea360bf1226f946d0c50e74e685da2ac70394065f436d6
+  data.tar.gz: 7b9b0b5bf75866876bdc1811dfc1118272963337431148f480d6570e19bfc2e9d93a6fdfd91a3629734501a590e23be579b98ff2e2f4f125831410351e0e6865

data/README.md

@@ -5,16 +5,16 @@
 
 # RubyReactor
 
+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)
+
 ## Why Ruby Reactor?
 
 Building complex business transactions often results in spaghetti code or brittle "god classes." Ruby Reactor solves this by implementing the **Saga Pattern** in a lightweight, developer-friendly package. It lets you define workflows as clear, dependency-driven steps without the boilerplate of heavy enterprise frameworks.
 
 The key value is **Reliability**: if any part of your workflow fails, Ruby Reactor automatically triggers compensation logic to undo previous steps, ensuring your system never ends up in a corrupted half-state. Whether you're coordinating microservices or monolith modules, you get atomic-like consistency with background processing built-in.
 
-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.
@@ -24,6 +24,7 @@ A dynamic, dependency-resolving saga orchestrator for Ruby. Ruby Reactor impleme
 - **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.
+- **Distributed Locks, Semaphores, Rate Limits & Periods**: Coordinate across processes with Redis-backed primitives — exclusive locks for at-most-one-runner, semaphores for capacity caps, fixed-window rate limits for external APIs (single or multi-window like "3/sec AND 100/min"), and `with_period` to dedup reactors to once per calendar bucket (once per day/month/year/etc). Async jobs snooze on contention with smart `retry_after` instead of consuming retry budget.
 
 ## Comparison
 
@@ -32,6 +33,7 @@ A dynamic, dependency-resolving saga orchestrator for Ruby. Ruby Reactor impleme
 | DAG/Parallel execution   | Yes          | No              | Limited     | Manual              |
 | Auto compensation/undo   | Yes          | No              | Manual      | Manual              |
 | Interrupts (pause/resume)| Yes          | No              | No          | Manual              |
+| Locks / sem / rate / per | Yes          | No              | No          | Manual              |
 | Built-in web dashboard   | Yes          | No              | No          | No                  |
 | Async with Sidekiq       | Yes          | No              | Limited     | Yes                 |
 
@@ -56,12 +58,14 @@ A dynamic, dependency-resolving saga orchestrator for Ruby. Ruby Reactor impleme
     - [Full Reactor Async](#full-reactor-async)
     - [Step-Level Async](#step-level-async)
   - [Interrupts (Pause & Resume)](#interrupts-pause--resume)
+  - [Locks & Semaphores](#locks--semaphores)
   - [Map & Parallel Execution](#map--parallel-execution)
     - [Map with Dynamic Source (ActiveRecord)](#map-with-dynamic-source-activerecord)
   - [Input Validation](#input-validation)
   - [Complex Workflows with Dependencies](#complex-workflows-with-dependencies)
   - [Error Handling and Compensation](#error-handling-and-compensation)
   - [Using Pre-defined Schemas](#using-pre-defined-schemas)
+  - [Testing](#testing)
 - [Documentation](#documentation)
 - [Future improvements](#future-improvements)
 - [Development](#development)
@@ -98,7 +102,14 @@ RubyReactor.configure do |config|
   # Sidekiq configuration for async execution
   config.sidekiq_queue = :default
   config.sidekiq_retry_count = 3
-  
+
+  # Lock contention snooze behavior for async reactors. When a Sidekiq worker
+  # cannot acquire a lock or semaphore, it re-enqueues itself with this delay
+  # (plus jitter) up to `lock_snooze_max_attempts` times before giving up.
+  config.lock_snooze_base_delay = 5
+  config.lock_snooze_jitter = 5
+  config.lock_snooze_max_attempts = 20
+
   # Logger configuration
   config.logger = Logger.new($stdout)
 end
@@ -158,7 +169,7 @@ class UserRegistrationReactor < RubyReactor::Reactor
 
     run do |args, context|
       if args[:email] && args[:email].include?('@')
-        Success(args[:email].trim)
+        Success(args[:email].strip)
       else
         Failure("Email must contain @")
       end
@@ -190,8 +201,9 @@ class UserRegistrationReactor < RubyReactor::Reactor
       Success(user)
     end
 
-    conpensate do |error, args, context|
+    compensate do |error, args, context|
       Notify.to(args[:email])
+      Success()
     end
   end
 
@@ -199,8 +211,8 @@ class UserRegistrationReactor < RubyReactor::Reactor
     argument :email, result(:validate_email)
     wait_for :create_user
 
-    run do |args, _context| 
-      Email.sent!(args[:email], "verify your email")
+    run do |args, _context|
+      Email.send!(args[:email], "verify your email")
       Success()
     end
 
@@ -325,6 +337,99 @@ ApprovalReactor.continue_by_correlation_id(
 )
 ```
 
+### Locks & Semaphores
+
+Coordinate across processes with Redis-backed primitives:
+
+- **`with_lock`** — at-most-one runner per key at a time (concurrency control).
+- **`with_semaphore`** — cap total concurrent runners per key (capacity control).
+- **`with_rate_limit`** — fixed-window rate limit, single or multi-window ("3/sec AND 100/min").
+- **`with_period`** — run at most once per calendar bucket (dedup / once-per-day, once-per-month, etc).
+
+```ruby
+class RefundOrderReactor < RubyReactor::Reactor
+  input :order_id
+
+  # Only one refund per order at a time. Auto-extend keeps the TTL fresh while
+  # the reactor runs, so long steps cannot let the lock expire mid-flight.
+  with_lock(ttl: 60) { |inputs| "order:#{inputs[:order_id]}" }
+
+  step :refund do
+    argument :order_id, input(:order_id)
+    run { |args| PaymentGateway.refund(args[:order_id]) }
+  end
+end
+
+class GeocodeReactor < RubyReactor::Reactor
+  input :address
+
+  # At most 5 geocode calls in flight across the fleet.
+  with_semaphore(limit: 5) { |inputs| "geocode_api" }
+
+  step :geocode do
+    argument :address, input(:address)
+    run { |args| Geocoder.lookup(args[:address]) }
+  end
+end
+
+class MonthlyBillingReactor < RubyReactor::Reactor
+  input :org_id
+
+  # Run at most once per UTC month per org. Subsequent calls in the same month
+  # return RubyReactor::Skipped without executing any step. Pair with
+  # with_lock for strict at-most-one even under concurrent racers.
+  with_period(every: :month) { |inputs| "monthly_billing:#{inputs[:org_id]}" }
+
+  step :build do
+    argument :org_id, input(:org_id)
+    run { |args| Billing.generate(args[:org_id]) }
+  end
+end
+
+class ChargeReactor < RubyReactor::Reactor
+  input :account_id
+
+  # Respect upstream Stripe rate limits: 3/sec and 100/min.
+  # Async workers snooze for exactly retry_after seconds instead of
+  # consuming Sidekiq retry budget.
+  with_rate_limit(
+    limits: { second: 3, minute: 100 }
+  ) { |inputs| "stripe:#{inputs[:account_id]}" }
+
+  step :charge do
+    argument :account_id, input(:account_id)
+    run { |args| Stripe.charge(args[:account_id]) }
+  end
+end
+```
+
+On contention:
+
+- **Inline** (`Reactor.run`) raises `RubyReactor::Lock::AcquisitionError` / `RubyReactor::Semaphore::AcquisitionError` / `RubyReactor::RateLimit::ExceededError`.
+- **Async** (Sidekiq) snoozes the job via `perform_in(delay, ...)`. For rate limits the delay is the error's `retry_after_seconds` (precise wakeup); for locks/semaphores it's `lock_snooze_base_delay + jitter`. Snoozes do not count against the Sidekiq retry budget. After `lock_snooze_max_attempts` snoozes the context is marked failed.
+
+On dedup hits (period gate already marked), the reactor returns a `RubyReactor::Skipped` result instead — no steps run, no exception:
+
+```ruby
+result = MonthlyBillingReactor.run(org_id: 42)
+result.success?  # true (Skipped is a Success subclass)
+result.skipped?  # true on dedup hit, false otherwise
+```
+
+A step's `run` block can also return `RubyReactor.Skipped(reason: "...")` to halt the reactor cleanly — remaining steps don't execute, **and already-completed steps are NOT compensated**. Use it when the rest of the workflow is unnecessary and partial progress should be kept (`Failure` is for "stop and roll back").
+
+```ruby
+step :ensure_active do
+  argument :user, result(:fetch_user)
+  run do |args|
+    next RubyReactor.Skipped(reason: "user_opted_out") if args[:user].opted_out?
+    RubyReactor.Success(args[:user])
+  end
+end
+```
+
+See [Locks, Semaphores, Rate Limits & Periods](documentation/locks_and_semaphores.md) for re-entrancy, auto-extend, multi-window quotas, bucket semantics, owner identity, snooze tuning, and operational notes.
+
 ### Map & Parallel Execution
 
 Process collections in parallel using the `map` step:
@@ -680,6 +785,29 @@ class SchemaValidatedReactor < RubyReactor::Reactor
 end
 ```
 
+### Testing
+
+RubyReactor provides testing utilities for RSpec. See the [Testing with RSpec](documentation/testing.md) guide for comprehensive documentation.
+
+```ruby
+RSpec.describe PaymentReactor do
+  it "processes payment successfully" do
+    subject = test_reactor(PaymentReactor, order_id: 123, amount: 99.99)
+    
+    expect(subject).to be_success
+    expect(subject).to have_run_step(:charge_card).after(:validate_order)
+    expect(subject.step_result(:charge_card)).to include(status: "completed")
+  end
+
+  it "handles payment failures with mocked steps" do
+    subject = test_reactor(PaymentReactor, order_id: 123, amount: 99.99)
+      .mock_step(:charge_card) { Failure("Card declined") }
+    
+    expect(subject).to be_failure
+    expect(subject.error).to include("Card declined")
+  end
+end
+```
 
 ## Documentation
 
@@ -706,6 +834,13 @@ Configure robust retry policies for your steps. This guide details the available
 ### [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.
 
+### [Testing with RSpec](documentation/testing.md)
+Comprehensive guide to testing reactors with RubyReactor's testing utilities. Learn about the `TestSubject` class for reactor execution and introspection, step mocking for isolating dependencies, testing nested and composed reactors, and custom RSpec matchers like `be_success`, `have_run_step`, and `have_retried_step`.
+
+### [Locks, Semaphores, Rate Limits & Periods](documentation/locks_and_semaphores.md)
+
+Coordinate access to shared resources across processes with Redis-backed primitives: exclusive locks (`with_lock`), concurrency-limiting semaphores (`with_semaphore`), fixed-window rate limits with multi-window quotas (`with_rate_limit`), and calendar-bucketed dedup (`with_period`, returning `Skipped` results). Covers re-entrancy across composed reactors, TTL auto-extend, inline-vs-async contention behavior, smart `retry_after` snoozes for rate limits, snooze tuning, the token-based semaphore safety model, and once-per-day/month/year scheduling patterns.
+
 ### Examples
 - [Order Processing](documentation/examples/order_processing.md) - Complete order processing workflow example
 - [Payment Processing](documentation/examples/payment_processing.md) - Payment handling with compensation
@@ -728,6 +863,7 @@ Learn how to pause and resume reactors to handle long-running processes, manual
   - [X] Sidekiq
   - [ ] ActiveJob
 - [ ] OpenTelemetry support
+- [X] locks
 
 ## Development
 

data/documentation/README.md

@@ -8,13 +8,15 @@ RubyReactor is a powerful Ruby framework for building reliable, sequential busin
 - [Core Concepts](core_concepts.md)
 - [DAG Execution and Saga Patterns](DAG.md)
 - [Async Reactors](async_reactors.md)
+- [Composition](composition.md)
+- [Data Pipelines](data_pipelines.md)
 - [Retry Configuration](retry_configuration.md)
-- [Migration Guide](migration_guide.md)
+- [Interrupts](interrupts.md)
+- [Testing with RSpec](testing.md)
 - [Examples](examples/)
   - [Order Processing](examples/order_processing.md)
   - [Payment Processing](examples/payment_processing.md)
   - [Inventory Management](examples/inventory_management.md)
-- [API Reference](api_reference.md)
 
 ## Quick Start
 
@@ -22,21 +24,30 @@ RubyReactor is a powerful Ruby framework for building reliable, sequential busin
 require 'ruby_reactor'
 
 class OrderProcessingReactor < RubyReactor::Reactor
+  input :order_id
+
   step :validate_order do
-    run { validate_order_logic }
+    argument :order_id, input(:order_id)
+    run { |args, _ctx| Success(Order.find(args[:order_id])) }
   end
 
   step :process_payment do
-    run { process_payment_logic }
+    argument :order, result(:validate_order)
+    run { |args, _ctx| Success(PaymentService.charge(args[:order])) }
   end
 
   step :send_confirmation do
-    run { send_email_confirmation }
+    argument :order, result(:validate_order)
+    run { |args, _ctx| Success(EmailService.send(args[:order])) }
   end
+
+  returns :process_payment
 end
 
 # Execute synchronously
 result = OrderProcessingReactor.run(order_id: 123)
+result.success? # => true
+result.value    # => payment result
 ```
 
 ## Key Features
@@ -106,9 +117,10 @@ RubyReactor provides comprehensive error handling:
 
 ## Requirements
 
-- Ruby 2.7+
-- Redis (for async execution)
+- Ruby 3.0+
+- Redis (for async execution and state persistence)
 - Sidekiq (for background processing)
+- dry-validation (optional, for input/payload validation)
 
 ## Installation
 
@@ -120,4 +132,4 @@ gem 'ruby_reactor'
 
 ## Contributing
 
-See [CONTRIBUTING.md](../CONTRIBUTING.md) for development setup and contribution guidelines.
+Bug reports and pull requests are welcome at <https://github.com/arturictus/ruby_reactor>. See the root [README](../README.md#contributing) for development setup.

data/documentation/async_reactors.md

@@ -41,20 +41,21 @@ end
 # Synchronous call returns immediately
 async_result = OrderProcessingReactor.run(order_id: 123)
 
-# Check status later
-case async_result.status
-when :pending
-  puts "Execution is queued"
-when :running
-  puts "Execution is in progress"
-when :success
-  puts "Execution completed successfully"
-  result = async_result.result
-when :failed
-  puts "Execution failed: #{async_result.error}"
+async_result.execution_id       # UUID for reloading state
+async_result.intermediate_results # Whatever was computed before handoff
+
+# Inspect status later by reloading from storage
+reactor = OrderProcessingReactor.find(async_result.execution_id)
+case reactor.context.status.to_s
+when "running"   then puts "Execution is in progress"
+when "completed" then puts "Done: #{reactor.result.value}"
+when "failed"    then puts "Failed: #{reactor.result.error}"
+when "paused"    then puts "Waiting on interrupt"
 end
 ```
 
+> **Note:** `AsyncResult` itself does not poll. It only carries the job handle and any results computed before handoff (`job_id`, `execution_id`, `intermediate_results`). To check progress, reload via `Reactor.find(execution_id)` and inspect `context.status`, or use the web dashboard.
+
 ### Architecture
 
 ```mermaid
@@ -85,26 +86,28 @@ Individual steps can be marked as `async: true`. Execution runs synchronously un
 class OrderProcessingReactor < RubyReactor::Reactor
   step :validate_order do
     # Runs synchronously
-    run { validate_order_logic }
+    run { |args, _ctx| validate_order_logic(args) }
   end
 
-  step :process_payment, async: true do
-    # First async step - triggers handoff to worker
-    run { process_payment_logic }
+  step :process_payment do
+    async true # First async step — triggers handoff to worker
+    run { |args, _ctx| process_payment_logic(args) }
   end
 
   step :update_inventory do
     # Runs in worker after handoff
-    run { update_inventory_logic }
+    run { |args, _ctx| update_inventory_logic(args) }
   end
 
   step :send_confirmation do
     # Runs in same worker
-    run { send_confirmation_logic }
+    run { |args, _ctx| send_confirmation_logic(args) }
   end
 end
 ```
 
+> **DSL note:** `async` is declared inside the step block (`async true`), not as a keyword on `step :name, async: true`. The `step` method only accepts a step name and an optional implementation class as positional arguments.
+
 ### Execution Flow
 
 ```ruby
@@ -244,17 +247,18 @@ class PaymentProcessingReactor < RubyReactor::Reactor
 
   step :validate_payment do
     retries max_attempts: 3, backoff: :exponential, base_delay: 1.second
-    run { validate_payment_logic }
+    run { |args, _ctx| validate_payment_logic(args) }
   end
 
-  step :charge_card, async: true do
+  step :charge_card do
+    async true
     retries max_attempts: 5, backoff: :linear, base_delay: 5.seconds
-    run { charge_card_logic }
+    run { |args, _ctx| charge_card_logic(args) }
   end
 
   step :update_records do
     # No retry - critical step
-    run { update_records_logic }
+    run { |args, _ctx| update_records_logic(args) }
   end
 end
 ```
@@ -298,25 +302,30 @@ class OrderProcessingReactor < RubyReactor::Reactor
   async true
 
   step :process_payment do
-    run { process_payment_logic }
+    argument :order, result(:validate_order)
+    run { |args, _ctx| process_payment_logic(args[:order]) }
 
-    undo do |payment_id:, **|
-      # Runs in worker if execution fails later
-      PaymentService.refund(payment_id)
+    undo do |result, _args, _ctx|
+      # Runs in worker when a LATER step fails
+      PaymentService.refund(result[:payment_id])
+      Success()
     end
 
-    compensate do |payment_id:, **|
-      # Runs in worker if execution fails later
-      PaymentService.refund(payment_id)
+    compensate do |error, args, _ctx|
+      # Runs in worker if THIS step fails
+      AuditService.log_payment_failure(args[:order].id, error.message)
+      Success()
     end
   end
 
   step :update_inventory do
-    run { update_inventory_logic }
+    argument :order, result(:validate_order)
+    run { |args, _ctx| update_inventory_logic(args[:order]) }
 
-    compensate do |order:, **|
+    compensate do |_error, args, _ctx|
       # Runs in worker on failure
-      InventoryService.restore(order)
+      InventoryService.restore(args[:order])
+      Success()
     end
   end
 end
@@ -337,16 +346,19 @@ Retries are visible in Sidekiq web UI with:
 ### Sidekiq Worker Setup
 
 ```ruby
-# config/sidekiq.rb
-require 'ruby_reactor/worker'
-
+# config/initializers/ruby_reactor.rb (Rails) or load before booting Sidekiq
 RubyReactor.configure do |config|
+  config.storage.adapter = :redis
+  config.storage.redis_url = ENV.fetch("REDIS_URL", "redis://localhost:6379/0")
+
   config.sidekiq_queue = :default
   config.sidekiq_retry_count = 3
   config.logger = Logger.new('log/ruby_reactor.log')
 end
 ```
 
+Sidekiq workers are loaded automatically via Zeitwerk when `ruby_reactor` is required — no extra `require` is needed.
+
 ## Performance Considerations
 
 ### Worker Pool Sizing