ruby_reactor 0.3.1 → 0.3.2

data/documentation/testing.md

@@ -16,6 +16,8 @@ end
 
 This will give you access to the `test_reactor` helper method and all custom matchers.
 
+> For reactors that use `with_lock`, `with_semaphore`, `with_rate_limit`, or `with_period`, see [Testing Coordination Primitives](#testing-coordination-primitives) — it covers the `be_skipped`, `be_locked`, `have_available_tokens`, `have_held_tokens`, `have_rate_limit_count`, and `be_period_marked` matchers, plus patterns for testing async snooze and escalation.
+
 ## Basic Usage
 
 ### The `test_reactor` Helper
@@ -543,6 +545,175 @@ end
 
 ---
 
+## Testing Coordination Primitives
+
+Reactors that declare `with_lock`, `with_semaphore`, `with_rate_limit`, or `with_period` can be tested with both vanilla execution assertions and dedicated state matchers that read the live Redis state via the configured storage adapter.
+
+### Test environment requirements
+
+The matchers ship with the standard test setup — once `RubyReactor::RSpec.configure(config)` runs in your `spec_helper.rb`, they're available. They require:
+
+- A real Redis (the in-memory test mode does not back the primitives).
+- A clean Redis between tests — typically `redis.flushdb` in a `before` block — so leftover lock owners, semaphore tokens, rate-limit counters and period markers don't leak across examples.
+
+### The `Skipped` result
+
+`RubyReactor::Skipped` is a `Success` subclass returned in two cases: a `with_period` bucket has already been claimed, or a step explicitly returns `RubyReactor.Skipped(reason: "...")` to halt cleanly (no compensation runs). Use `be_skipped` to distinguish it from a plain `Success`:
+
+```ruby
+result = MonthlyReportReactor.run(org_id: 7)
+expect(result).to be_skipped                       # any Skipped
+expect(result).to be_skipped.because(:period)      # gate hit
+expect(result).to be_skipped.at_step(:second)      # step return
+```
+
+`Skipped` still satisfies `success?`, so legacy `if result.success?` callers continue to work; `result.skipped?` discriminates.
+
+### Asserting lock state
+
+```ruby
+it "releases the lock after a successful run" do
+  RefundOrderReactor.run(order_id: 42)
+
+  expect("order:42").not_to be_locked
+end
+
+it "holds the lock for the duration of a long step" do
+  thread = Thread.new { LongRefundReactor.run(order_id: 42) }
+  # Give the executor a moment to acquire
+  sleep 0.05
+
+  expect("order:42").to be_locked
+  expect("order:42").to be_locked.by(thread.value.context.context_id)
+end
+
+it "raises when contention is hit inline" do
+  redis.hset("lock:order:42", "owner", "someone_else")
+  redis.hset("lock:order:42", "count", "1")
+
+  expect { RefundOrderReactor.run(order_id: 42) }
+    .to raise_error(RubyReactor::Lock::AcquisitionError)
+end
+```
+
+The `be_locked` matcher takes the **user-provided lock key** (without the internal `lock:` prefix). Use the `.by(owner)` chain to assert ownership — typically the `context_id` of the top-level execution.
+
+### Asserting semaphore state
+
+```ruby
+it "returns the token to the pool on success" do
+  3.times { ApiCallReactor.run }
+
+  expect("api_limit").to have_available_tokens(5)
+  expect("api_limit").to have_held_tokens(0)
+end
+
+it "exhausts capacity when held externally" do
+  s = RubyReactor::Semaphore.new("api_limit", limit: 2)
+  2.times { s.acquire }
+
+  expect("api_limit").to have_available_tokens(0)
+  expect("api_limit").to have_held_tokens(2)
+
+  expect { ApiCallReactor.run }.to raise_error(RubyReactor::Semaphore::AcquisitionError)
+end
+```
+
+Both matchers take the **user-provided semaphore name** (without the `semaphore:` prefix).
+
+### Asserting rate-limit state
+
+```ruby
+it "counts each call against the per-second window" do
+  3.times { ChargeReactor.run(account_id: 42) }
+
+  expect("stripe:42").to have_rate_limit_count(3).for(:second)
+end
+
+it "snoozes inline once the window is full" do
+  3.times { ChargeReactor.run(account_id: 42) }
+
+  expect { ChargeReactor.run(account_id: 42) }
+    .to raise_error(RubyReactor::RateLimit::ExceededError) do |e|
+      expect(e.period_name).to eq("second")
+      expect(e.retry_after_seconds).to be_between(1, 1)
+    end
+end
+```
+
+`have_rate_limit_count(n).for(period)` looks at the **current** bucket for the given `period` (use the same symbol or integer seconds you passed to `with_rate_limit`). For multi-window limits, assert each window separately:
+
+```ruby
+expect("stripe:42").to have_rate_limit_count(3).for(:second)
+expect("stripe:42").to have_rate_limit_count(3).for(:minute)
+```
+
+### Asserting period markers
+
+```ruby
+it "marks the bucket after the first successful run" do
+  MonthlyReportReactor.run(org_id: 7)
+  expect("monthly_report:7").to be_period_marked.for(:month)
+end
+
+it "does not mark the bucket when the run fails" do
+  FailingMonthlyReactor.run(org_id: 7)
+  expect("monthly_report:7").not_to be_period_marked.for(:month)
+end
+
+it "skips a second call in the same bucket" do
+  MonthlyReportReactor.run(org_id: 7)
+  result = MonthlyReportReactor.run(org_id: 7)
+
+  expect(result).to be_skipped.because(:period)
+end
+```
+
+`be_period_marked.for(period)` checks the marker at the **current** bucket. To verify the marker's TTL behavior, drop to direct Redis: `redis.ttl(RubyReactor::Period.key("monthly_report:7", :month))`.
+
+### Testing async snooze behavior
+
+The Sidekiq worker rescues `Lock::AcquisitionError`, `Semaphore::AcquisitionError`, and `RateLimit::ExceededError` and reschedules via `perform_in`. To test that wiring without spinning Sidekiq:
+
+```ruby
+it "reschedules with retry_after on rate limit hits" do
+  redis.set("rate:stripe:42:second:#{Time.now.to_i}", "999")
+
+  serialized = RubyReactor::ContextSerializer.serialize(
+    RubyReactor::Context.new({ account_id: 42 }, ChargeReactor)
+  )
+
+  expect(RubyReactor::SidekiqWorkers::Worker)
+    .to receive(:perform_in)
+    .with(a_value_between(1.0, 2.0), serialized, "ChargeReactor", 1)
+
+  RubyReactor::SidekiqWorkers::Worker.new.perform(serialized, "ChargeReactor")
+end
+```
+
+For lock/semaphore the same pattern works — the `perform_in` delay is `lock_snooze_base_delay + rand(0..lock_snooze_jitter)`. Pin those knobs to deterministic values (`jitter = 0`) in tests that assert on the exact delay.
+
+### Testing snooze escalation
+
+When the snooze cap (`lock_snooze_max_attempts`) is reached, the worker stops rescheduling and marks the context as failed:
+
+```ruby
+it "marks the context as failed after the snooze cap" do
+  RubyReactor.configuration.lock_snooze_max_attempts = 3
+
+  redis.hset("lock:order:42", "owner", "other")
+  redis.hset("lock:order:42", "count", "1")
+
+  context = RubyReactor::Context.new({ order_id: 42 }, RefundOrderReactor)
+  serialized = RubyReactor::ContextSerializer.serialize(context)
+
+  expect(RubyReactor::SidekiqWorkers::Worker).not_to receive(:perform_in)
+
+  RubyReactor::SidekiqWorkers::Worker.new
+    .perform(serialized, "RefundOrderReactor", 3)
+end
+```
+
 ## Complete Examples
 
 ### Testing a Payment Workflow
@@ -810,3 +981,14 @@ end
 | `have_retried_step(name)` | Assert step was retried |
 | `.times(count)` | Chain: assert retry count |
 | `have_validation_error(field)` | Assert input validation error on field |
+| `be_skipped` | Assert result is a `RubyReactor::Skipped` (period gate or step return) |
+| `.because(reason)` | Chain: assert the skip reason matches |
+| `.at_step(name)` | Chain: assert the halting step (step-returned Skipped only) |
+| `be_locked` | Assert an exclusive lock is currently held for the given key |
+| `.by(owner)` | Chain: assert the lock owner (typically a `context_id`) |
+| `have_available_tokens(n)` | Assert `n` semaphore tokens are still in the pool |
+| `have_held_tokens(n)` | Assert `n` semaphore tokens are currently checked out |
+| `have_rate_limit_count(n)` | Assert the current rate-limit bucket count |
+| `.for(period)` | Chain (required): which window to check (`:second`, `:minute`, …, or integer seconds) |
+| `be_period_marked` | Assert a `with_period` bucket has been marked |
+| `.for(period)` | Chain (required): which bucket granularity to check |

data/lib/ruby_reactor/configuration.rb

@@ -7,7 +7,8 @@ module RubyReactor
   class Configuration
     include Singleton
 
-    attr_writer :sidekiq_queue, :sidekiq_retry_count, :logger, :async_router
+    attr_writer :sidekiq_queue, :sidekiq_retry_count, :logger, :async_router,
+                :lock_snooze_base_delay, :lock_snooze_jitter, :lock_snooze_max_attempts
 
     def sidekiq_queue
       @sidekiq_queue ||= :default
@@ -17,6 +18,22 @@ module RubyReactor
       @sidekiq_retry_count ||= 3
     end
 
+    # Base seconds the Sidekiq worker waits before re-checking a contended lock.
+    def lock_snooze_base_delay
+      @lock_snooze_base_delay ||= 5
+    end
+
+    # Extra random seconds added to the base delay to avoid thundering herd.
+    def lock_snooze_jitter
+      @lock_snooze_jitter ||= 5
+    end
+
+    # How many times a single job can snooze on lock contention before it is
+    # marked as failed. Set to :infinity to never escalate.
+    def lock_snooze_max_attempts
+      @lock_snooze_max_attempts ||= 20
+    end
+
     def logger
       @logger ||= Logger.new($stderr)
     end

data/lib/ruby_reactor/dsl/lockable.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module RubyReactor
+  module Dsl
+    module Lockable
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods
+        attr_reader :lock_config, :semaphore_config, :period_config, :rate_limit_config
+
+        # Propagate lock/semaphore/period/rate-limit config to subclasses;
+        # without this a subclass of a configured reactor would silently lose
+        # those settings.
+        def inherited(subclass)
+          super
+          subclass.instance_variable_set(:@lock_config, @lock_config) if @lock_config
+          subclass.instance_variable_set(:@semaphore_config, @semaphore_config) if @semaphore_config
+          subclass.instance_variable_set(:@period_config, @period_config) if @period_config
+          subclass.instance_variable_set(:@rate_limit_config, @rate_limit_config) if @rate_limit_config
+        end
+
+        # Configure locking for this reactor
+        # @param ttl [Integer] Time to live in seconds (default: 60)
+        # @param wait [Integer] Time to wait for lock in seconds (default: 0)
+        # @param auto_extend [Boolean] When true (default), a background thread
+        #   refreshes the lock TTL every ttl/3 seconds while the reactor runs,
+        #   protecting steps that may legitimately outlast `ttl`. Pass `false`
+        #   to disable and rely solely on `ttl` for expiry.
+        # @yield [inputs] Block that returns the lock key string
+        def with_lock(ttl: 60, wait: 0, auto_extend: true, &block)
+          @lock_config = {
+            ttl: ttl,
+            wait: wait,
+            auto_extend: auto_extend,
+            key_proc: block
+          }
+        end
+
+        # Configure semaphore for this reactor
+        # @param limit [Integer] Maximum concurrent executions
+        # @param wait [Integer] Time to wait for a token in seconds (default: 0)
+        # @yield [inputs] Block that returns the semaphore key string
+        def with_semaphore(limit:, wait: 0, &block)
+          @semaphore_config = {
+            limit: limit,
+            wait: wait,
+            key_proc: block
+          }
+        end
+
+        # Configure a calendar-aligned dedup window for this reactor. The
+        # reactor will run at most once per bucket per key; subsequent calls
+        # in the same bucket return `RubyReactor::Skipped` without executing
+        # any steps.
+        #
+        # Note: `with_period` is *dedup*, not *concurrency*. Two concurrent
+        # racers can both see no marker and both run. Pair with `with_lock`
+        # for true at-most-one semantics within the bucket.
+        #
+        # @param every [Symbol, Integer] :minute / :hour / :day / :week /
+        #   :month / :year, or an integer number of seconds for a sliding
+        #   bucket (index = `time.to_i / every`).
+        # @yield [inputs] Block that returns the period key base. The final
+        #   Redis marker key is `period:<base>:<bucket_id>`.
+        def with_period(every:, &block)
+          # Validate eagerly so misconfiguration surfaces at class load time.
+          RubyReactor::Period.period_seconds(every)
+
+          @period_config = {
+            every: every,
+            key_proc: block
+          }
+        end
+
+        # Configure rate limiting for this reactor (fixed-window counter).
+        # Pass either a single window via `limit:` + `period:`, or a hash of
+        # windows via `limits:` for layered API quotas.
+        #
+        # @example Single window
+        #   with_rate_limit(limit: 3, period: :second) { |i| "stripe:#{i[:account_id]}" }
+        #
+        # @example Multi-window (3/sec AND 100/min AND 5000/hr)
+        #   with_rate_limit(
+        #     limits: { second: 3, minute: 100, hour: 5000 }
+        #   ) { |i| "stripe:#{i[:account_id]}" }
+        #
+        # @param limit [Integer] requests per period (single-window form)
+        # @param period [Symbol, Integer] :second / :minute / :hour / :day /
+        #   :week / :month / :year, or integer seconds (single-window form)
+        # @param limits [Hash{Symbol,Integer => Integer}] mapping of period
+        #   unit to limit (multi-window form)
+        # @yield [inputs] Block returning the rate-limit key base.
+        def with_rate_limit(limit: nil, period: nil, limits: nil, &block)
+          normalized = normalize_rate_limit_args(limit, period, limits)
+
+          @rate_limit_config = {
+            limits: normalized,
+            key_proc: block
+          }
+        end
+
+        private
+
+        def normalize_rate_limit_args(limit, period, limits)
+          if limits
+            raise ArgumentError, "with_rate_limit: use either :limits, or :limit + :period, not both" if limit || period
+
+            limits.map do |period_key, limit_val|
+              {
+                period_seconds: RubyReactor::Period.period_seconds(period_key),
+                limit: Integer(limit_val),
+                name: period_key.to_s
+              }
+            end
+          elsif limit && period
+            [{
+              period_seconds: RubyReactor::Period.period_seconds(period),
+              limit: Integer(limit),
+              name: period.to_s
+            }]
+          else
+            raise ArgumentError, "with_rate_limit requires :limit + :period, or :limits"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby_reactor/executor/result_handler.rb

@@ -14,6 +14,9 @@ module RubyReactor
 
       def handle_step_result(step_config, result, resolved_arguments)
         case result
+        when RubyReactor::Skipped
+          # Important: must come before the Success branch — Skipped < Success.
+          handle_skipped(step_config, result)
         when RubyReactor::Success
           handle_success(step_config, result, resolved_arguments)
         when RubyReactor::MaxRetriesExhaustedFailure
@@ -53,6 +56,22 @@ module RubyReactor
 
       private
 
+      # A step returned `RubyReactor.Skipped(...)`. Halt cleanly: record the
+      # event in the trace, do NOT push to the undo stack (so existing
+      # completed steps stay as-is — no compensation), and stamp the step
+      # name on the result so the caller can see who halted.
+      def handle_skipped(step_config, result)
+        @step_results[step_config.name] = result
+        result.instance_variable_set(:@step_name, step_config.name) if result.step_name.nil?
+        @context.execution_trace << {
+          type: :skipped,
+          step: step_config.name,
+          timestamp: Time.now,
+          reason: result.reason
+        }
+        result
+      end
+
       def handle_success(step_config, result, resolved_arguments)
         validate_step_output(step_config, result.value, resolved_arguments)
         @step_results[step_config.name] = result

data/lib/ruby_reactor/executor/step_executor.rb

@@ -33,6 +33,11 @@ module RubyReactor
             # If a step returns RetryQueuedResult, we need to stop and return it
             return result if result.is_a?(RetryQueuedResult)
 
+            # If a step returns Skipped, halt the reactor cleanly (no
+            # compensation). Must be checked BEFORE Failure / Success because
+            # Skipped is a Success subclass.
+            return result if result.is_a?(RubyReactor::Skipped)
+
             # If a step returns Failure, we need to stop execution and return it
             return result if result.is_a?(RubyReactor::Failure)
 

data/lib/ruby_reactor/executor.rb

@@ -34,9 +34,22 @@ module RubyReactor
         }
       )
       @result = nil
+      @acquired_lock = nil
+      @acquired_semaphore = nil
     end
 
     def execute
+      skipped = check_period_gate
+      if skipped
+        @result = skipped
+        update_context_status(@result)
+        save_context
+        return @result
+      end
+
+      check_rate_limit
+      acquire_locks
+
       input_validator = InputValidator.new(@reactor_class, @context)
       input_validator.validate!
 
@@ -49,18 +62,25 @@ module RubyReactor
 
       @result = @step_executor.execute_all_steps
       update_context_status(@result)
+      mark_period_on_success(@result)
       handle_interrupt(@result) if @result.is_a?(RubyReactor::InterruptResult)
       @result
+    rescue RubyReactor::Lock::AcquisitionError,
+           RubyReactor::Semaphore::AcquisitionError,
+           RubyReactor::RateLimit::ExceededError => e
+      raise e
     rescue StandardError => e
       @result = @result_handler.handle_execution_error(e)
       update_context_status(@result)
       @result
     ensure
+      release_locks
       save_context
     end
 
     def resume_execution
       @context.status = :running
+      acquire_locks
       prepare_for_resume
       save_context
 
@@ -71,15 +91,21 @@ module RubyReactor
                 end
 
       update_context_status(@result)
+      mark_period_on_success(@result)
 
       handle_interrupt(@result) if @result.is_a?(RubyReactor::InterruptResult)
 
       @result
+    rescue RubyReactor::Lock::AcquisitionError,
+           RubyReactor::Semaphore::AcquisitionError,
+           RubyReactor::RateLimit::ExceededError => e
+      raise e
     rescue StandardError => e
       handle_resume_error(e)
       update_context_status(@result)
       @result
     ensure
+      release_locks
       save_context
     end
 
@@ -110,12 +136,122 @@ module RubyReactor
 
     private
 
+    def acquire_locks
+      acquire_exclusive_lock if @reactor_class.respond_to?(:lock_config) && @reactor_class.lock_config
+      acquire_semaphore if @reactor_class.respond_to?(:semaphore_config) && @reactor_class.semaphore_config
+    end
+
+    # Consume one slot from each configured rate-limit window. Raises
+    # `RubyReactor::RateLimit::ExceededError` (carrying a `retry_after_seconds`
+    # hint) if any window is full. Only consulted on initial `execute`; resumes
+    # never re-check (a paused reactor must not block itself on resume).
+    def check_rate_limit
+      return unless @reactor_class.respond_to?(:rate_limit_config) && @reactor_class.rate_limit_config
+
+      config = @reactor_class.rate_limit_config
+      key_base = config[:key_proc].call(@context.inputs)
+
+      RubyReactor::RateLimit.new(key_base, limits: config[:limits]).check_and_increment!
+    end
+
+    # Returns a Skipped result if the period bucket is already marked, else nil.
+    # Only consulted on initial `execute`; resumes never re-check (a paused run
+    # must not skip itself when its own marker eventually appears).
+    def check_period_gate
+      return nil unless @reactor_class.respond_to?(:period_config) && @reactor_class.period_config
+
+      config = @reactor_class.period_config
+      key = period_key(config)
+      return nil unless RubyReactor.configuration.storage_adapter.period_seen?(key)
+
+      RubyReactor::Skipped.new(reason: :period, period_key: key)
+    end
+
+    def mark_period_on_success(result)
+      return unless @reactor_class.respond_to?(:period_config) && @reactor_class.period_config
+      return unless result.is_a?(RubyReactor::Success)
+      return if result.is_a?(RubyReactor::Skipped)
+
+      config = @reactor_class.period_config
+      ttl = RubyReactor::Period.ttl_seconds(config[:every])
+      RubyReactor.configuration.storage_adapter.period_mark(period_key(config), ttl)
+    end
+
+    def period_key(config)
+      base = config[:key_proc].call(@context.inputs)
+      RubyReactor::Period.key(base, config[:every])
+    end
+
+    def acquire_exclusive_lock
+      config = @reactor_class.lock_config
+      key = config[:key_proc].call(@context.inputs)
+
+      # Use root context ID as owner to allow re-entrancy across nested reactors
+      owner = (@context.root_context || @context).context_id
+
+      lock = RubyReactor::Lock.new(
+        key,
+        owner: owner,
+        ttl: config[:ttl],
+        wait: contention_wait(config[:wait]),
+        auto_extend: config.fetch(:auto_extend, true)
+      )
+      lock.acquire
+      @acquired_lock = lock
+    end
+
+    def acquire_semaphore
+      config = @reactor_class.semaphore_config
+      key = config[:key_proc].call(@context.inputs)
+      limit = config[:limit]
+
+      semaphore = RubyReactor::Semaphore.new(key, limit: limit, wait: contention_wait(config[:wait]))
+      semaphore.acquire
+      @acquired_semaphore = semaphore
+    end
+
+    # Inside a Sidekiq worker we'd rather snooze the job via perform_in than
+    # tie up the worker thread on a BLPOP / sleep loop. The non-blocking path
+    # fails fast and the Worker rescue branch reschedules.
+    def contention_wait(configured_wait)
+      return 0 if @context.inline_async_execution
+
+      configured_wait
+    end
+
+    def release_locks
+      release_one("semaphore", @acquired_semaphore) if @acquired_semaphore
+      @acquired_semaphore = nil
+
+      return unless @acquired_lock
+
+      release_one("lock", @acquired_lock)
+      @acquired_lock = nil
+    end
+
+    def release_one(kind, primitive)
+      released = primitive.release
+      return if released
+
+      RubyReactor.configuration.logger.warn(
+        "RubyReactor #{kind} '#{primitive.key}' was not held at release time " \
+        "(likely TTL expired or owner changed)"
+      )
+    rescue StandardError => e
+      # Never let release break the ensure chain — log and move on.
+      RubyReactor.configuration.logger.warn(
+        "RubyReactor failed to release #{kind} '#{primitive.key}': #{e.message}"
+      )
+    end
+
     def update_context_status(result)
       return unless result
 
       case result
       when RubyReactor::AsyncResult
         @context.status = :running
+      when RubyReactor::Skipped
+        @context.status = :skipped
       when RubyReactor::Success
         @context.status = :completed
       when RubyReactor::Failure
@@ -148,8 +284,15 @@ module RubyReactor
         @result = @step_executor.execute_all_steps
       else
         case result
-        when RetryQueuedResult, RubyReactor::Failure, RubyReactor::AsyncResult, RubyReactor::InterruptResult
-          # Step was requeued, failed, or handed off to async - return the result
+        # Skipped must be listed before Success (Skipped < Success) so the
+        # halt path wins over the "continue with remaining steps" path.
+        when RubyReactor::Skipped,
+             RetryQueuedResult,
+             RubyReactor::Failure,
+             RubyReactor::AsyncResult,
+             RubyReactor::InterruptResult
+          # Terminal: step was skipped, requeued, failed, paused, or handed
+          # off to async. Return the result as-is.
           @result = result
         when RubyReactor::Success
           # Step succeeded, continue with remaining steps