ruby_reactor 0.3.1 → 0.4.0

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

data/lib/ruby_reactor/lock.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module RubyReactor
+  class Lock
+    class AcquisitionError < StandardError; end
+
+    # Minimum interval between auto-extend pings; protects very small TTLs.
+    MIN_EXTEND_INTERVAL = 1.0
+
+    attr_reader :key, :owner, :ttl, :wait, :auto_extend
+
+    def initialize(key, owner:, ttl: 60, wait: 0, auto_extend: true)
+      @key = "lock:#{key}"
+      @owner = owner
+      @ttl = ttl
+      @wait = wait
+      @auto_extend = auto_extend
+      @extender = nil
+      @extender_running = false
+    end
+
+    def acquire
+      start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+      loop do
+        if adapter.lock_acquire(@key, @owner, @ttl)
+          start_extender if @auto_extend
+          return true
+        end
+
+        if @wait.zero? || (Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time) >= @wait
+          raise AcquisitionError, "Could not acquire lock '#{@key}' for owner '#{@owner}'"
+        end
+
+        sleep 0.1
+      end
+    end
+
+    def release
+      stop_extender
+      adapter.lock_release(@key, @owner)
+    end
+
+    def synchronize
+      acquire
+      yield
+    ensure
+      release
+    end
+
+    private
+
+    def start_extender
+      return if @extender&.alive?
+
+      interval = [@ttl / 3.0, MIN_EXTEND_INTERVAL].max
+      @extender_running = true
+
+      @extender = Thread.new do
+        while @extender_running
+          sleep interval
+          break unless @extender_running
+
+          begin
+            adapter.lock_extend(@key, @owner, @ttl)
+          rescue StandardError => e
+            RubyReactor.configuration.logger.warn(
+              "Lock auto-extend failed for '#{@key}': #{e.message}"
+            )
+            break
+          end
+        end
+      end
+    end
+
+    def stop_extender
+      @extender_running = false
+      thread = @extender
+      @extender = nil
+      return unless thread
+
+      thread.wakeup if thread.alive?
+      thread.join(0.1)
+    rescue StandardError
+      # Best-effort shutdown; never let extender teardown break release.
+    end
+
+    def adapter
+      RubyReactor.configuration.storage_adapter
+    end
+  end
+end

data/lib/ruby_reactor/map/result_enumerator.rb

@@ -60,6 +60,7 @@ module RubyReactor
       end
 
       def [](index)
+        index += count if index.negative?
         return nil if index.negative? || index >= count
 
         results = @storage.retrieve_map_results_batch(
@@ -80,15 +81,15 @@ module RubyReactor
       end
 
       def last
-        self[count - 1]
+        self[-1]
       end
 
       def successes
-        lazy.select { |result| result.is_a?(RubyReactor::Success) }.map(&:value)
+        lazy.grep(RubyReactor::Success).map(&:value)
       end
 
       def failures
-        lazy.select { |result| result.is_a?(RubyReactor::Failure) }.map(&:error)
+        lazy.grep(RubyReactor::Failure).map(&:error)
       end
 
       private

data/lib/ruby_reactor/period.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module RubyReactor
+  # Calendar-aligned bucket helpers for `with_period` dedup gating.
+  #
+  # A *bucket* is a deterministic string derived from the current UTC time and
+  # the configured period. Two calls in the same bucket dedup to the same
+  # Redis marker key; calls that cross a calendar boundary land in different
+  # buckets and run again.
+  module Period
+    SYMBOLIC_PERIODS = {
+      second: 1,
+      minute: 60,
+      hour: 60 * 60,
+      day: 60 * 60 * 24,
+      week: 60 * 60 * 24 * 7,
+      month: 60 * 60 * 24 * 31,
+      year: 60 * 60 * 24 * 366
+    }.freeze
+
+    # Build the bucket id for a given period at a given moment. UTC, calendar
+    # aligned for symbolic periods, index-based for integer seconds.
+    def self.bucket_id(every, now: Time.now.utc)
+      case every
+      when :second then now.strftime("%Y-%m-%dT%H-%M-%S")
+      when :minute then now.strftime("%Y-%m-%dT%H-%M")
+      when :hour   then now.strftime("%Y-%m-%dT%H")
+      when :day    then now.strftime("%Y-%m-%d")
+      when :week   then now.strftime("%G-W%V")
+      when :month  then now.strftime("%Y-%m")
+      when :year   then now.strftime("%Y")
+      when Integer
+        raise ArgumentError, "Period seconds must be positive" unless every.positive?
+
+        "i#{now.to_i / every}"
+      else
+        raise ArgumentError, "Unknown period: #{every.inspect}"
+      end
+    end
+
+    # TTL for the marker. Twice the period length so the marker survives clock
+    # skew across the boundary and reliably dedups the very next attempt.
+    def self.ttl_seconds(every)
+      base = period_seconds(every)
+      base * 2
+    end
+
+    def self.period_seconds(every)
+      case every
+      when Symbol
+        SYMBOLIC_PERIODS.fetch(every) do
+          raise ArgumentError, "Unknown period: #{every.inspect}"
+        end
+      when Integer
+        raise ArgumentError, "Period seconds must be positive" unless every.positive?
+
+        every
+      else
+        raise ArgumentError, "Unknown period: #{every.inspect}"
+      end
+    end
+
+    def self.key(base, every, now: Time.now.utc)
+      "period:#{base}:#{bucket_id(every, now: now)}"
+    end
+  end
+end

data/lib/ruby_reactor/rate_limit.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module RubyReactor
+  # Distributed rate limiter (fixed-window counter, multi-window aware).
+  #
+  # A `RateLimit` is configured with one or more (period, limit) tuples.
+  # `check_and_increment!` atomically verifies every window has headroom and,
+  # if so, increments all of them. The check uses a single Lua script so
+  # nothing slips through between read and write.
+  #
+  # When any window is over-limit the call raises `ExceededError` carrying a
+  # `retry_after_seconds` hint (time until the tightest failing bucket rolls).
+  # The Sidekiq worker uses this hint to schedule a precise snooze.
+  class RateLimit
+    class ExceededError < StandardError
+      attr_reader :retry_after_seconds, :key_base, :limit, :period_seconds, :period_name
+
+      def initialize(message, retry_after_seconds:, key_base:, limit:, period_seconds:, period_name:) # rubocop:disable Metrics/ParameterLists
+        super(message)
+        @retry_after_seconds = retry_after_seconds
+        @key_base = key_base
+        @limit = limit
+        @period_seconds = period_seconds
+        @period_name = period_name
+      end
+    end
+
+    attr_reader :key_base, :limits
+
+    # @param key_base [String] caller-provided key (e.g. "stripe:account_42")
+    # @param limits [Array<Hash>] each hash needs :period_seconds, :limit,
+    #   and :name (used in the Redis bucket key and the error message)
+    def initialize(key_base, limits:)
+      @key_base = key_base
+      @limits = limits
+    end
+
+    def check_and_increment!
+      now = Time.now.to_i
+      keys = @limits.map { |spec| bucket_key(spec, now) }
+      argv = [now]
+      @limits.each do |spec|
+        argv << spec[:period_seconds]
+        argv << spec[:limit]
+        argv << (spec[:period_seconds] * 2) # TTL: generous, auto-cleans stale buckets
+      end
+
+      allowed, retry_after, failed_index = adapter.rate_limit_check_and_increment(keys, argv)
+      return true if allowed == 1
+
+      failed = @limits[failed_index - 1]
+      raise ExceededError.new(
+        "Rate limit '#{@key_base}' exceeded (#{failed[:limit]}/#{failed[:name]}); " \
+        "retry in #{retry_after}s",
+        retry_after_seconds: retry_after,
+        key_base: @key_base,
+        limit: failed[:limit],
+        period_seconds: failed[:period_seconds],
+        period_name: failed[:name]
+      )
+    end
+
+    private
+
+    def bucket_key(spec, now)
+      bucket_id = now / spec[:period_seconds]
+      "rate:#{@key_base}:#{spec[:name]}:#{bucket_id}"
+    end
+
+    def adapter
+      RubyReactor.configuration.storage_adapter
+    end
+  end
+end

data/lib/ruby_reactor/reactor.rb

@@ -4,6 +4,7 @@ module RubyReactor
   # rubocop:disable Metrics/ClassLength
   class Reactor
     include RubyReactor::Dsl::Reactor
+    include RubyReactor::Dsl::Lockable
 
     attr_reader :context, :result, :undo_trace, :execution_trace
 

data/lib/ruby_reactor/rspec/matchers.rb

@@ -2,20 +2,23 @@
 
 module RubyReactor
   module RSpec
+    # rubocop:disable Metrics/ModuleLength
     module Matchers
       # rubocop:disable Metrics/BlockLength
       ::RSpec::Matchers.define :be_success do
         match do |subject|
-          subject.ensure_executed!
+          subject.ensure_executed! if subject.respond_to?(:ensure_executed!)
           subject.success?
         end
 
         failure_message do |subject|
-          result = subject.result
+          result = subject.respond_to?(:result) ? subject.result : subject
           if result&.failure?
             format_failure_message(result)
-          else
+          elsif subject.respond_to?(:reactor_instance)
             "expected reactor to be success, but failed (Status: #{subject.reactor_instance.context.status})"
+          else
+            "expected #{subject.inspect} to be success"
           end
         end
 
@@ -62,7 +65,7 @@ module RubyReactor
 
       ::RSpec::Matchers.define :be_failure do
         match do |subject|
-          subject.ensure_executed!
+          subject.ensure_executed! if subject.respond_to?(:ensure_executed!)
           subject.failure?
         end
 
@@ -249,8 +252,172 @@ module RubyReactor
         end
       end
 
+      # ---------------------------------------------------------------------
+      # Lock / Semaphore / Rate-limit / Period state matchers
+      # ---------------------------------------------------------------------
+      #
+      # These assert against the live Redis state via the configured storage
+      # adapter, so they work for any test that has actually exercised the
+      # reactor (or interacted with the primitives directly).
+
+      def self.coordination_adapter
+        RubyReactor.configuration.storage_adapter
+      end
+
+      # Distinguishes `RubyReactor::Skipped` from a plain `Success`. Works on
+      # any object with a `skipped?` predicate.
+      #
+      # Examples:
+      #   expect(result).to be_skipped
+      #   expect(result).to be_skipped.because(:period)
+      #   expect(result).to be_skipped.at_step(:second)
+      ::RSpec::Matchers.define :be_skipped do
+        match do |subject|
+          subject.ensure_executed! if subject.respond_to?(:ensure_executed!)
+          actual = subject.respond_to?(:result) ? subject.result : subject
+          next false unless actual.respond_to?(:skipped?) && actual.skipped?
+          next false if @expected_reason && actual.reason != @expected_reason
+          next false if @expected_step && actual.step_name != @expected_step
+
+          true
+        end
+
+        chain :because do |reason|
+          @expected_reason = reason
+        end
+
+        chain :at_step do |step|
+          @expected_step = step
+        end
+
+        failure_message do |subject|
+          actual = subject.respond_to?(:result) ? subject.result : subject
+          if !actual.respond_to?(:skipped?) || !actual.skipped?
+            "expected result to be Skipped, got #{actual.class}"
+          elsif @expected_reason && actual.reason != @expected_reason
+            "expected Skipped reason #{@expected_reason.inspect}, got #{actual.reason.inspect}"
+          else
+            "expected Skipped at_step #{@expected_step.inspect}, got #{actual.step_name.inspect}"
+          end
+        end
+
+        failure_message_when_negated do
+          "expected result not to be Skipped"
+        end
+      end
+
+      # Asserts that an exclusive lock is currently held in Redis. Subject is
+      # the user-provided lock key (without the "lock:" prefix).
+      #
+      #   expect("order:42").to be_locked
+      #   expect("order:42").to be_locked.by("ctx-abc")
+      ::RSpec::Matchers.define :be_locked do
+        match do |key|
+          info = Matchers.coordination_adapter.lock_info("lock:#{key}")
+          next false unless info
+          next true unless @expected_owner
+
+          info[:owner] == @expected_owner
+        end
+
+        chain :by do |owner|
+          @expected_owner = owner
+        end
+
+        failure_message do |key|
+          info = Matchers.coordination_adapter.lock_info("lock:#{key}")
+          if info.nil?
+            "expected lock 'lock:#{key}' to be held, but it is free"
+          else
+            "expected lock 'lock:#{key}' to be held by #{@expected_owner.inspect}, " \
+              "but is held by #{info[:owner].inspect}"
+          end
+        end
+
+        failure_message_when_negated do |key|
+          info = Matchers.coordination_adapter.lock_info("lock:#{key}")
+          "expected lock 'lock:#{key}' not to be held, but is held by #{info[:owner].inspect}"
+        end
+      end
+
+      # Asserts the number of unallocated semaphore tokens. Subject is the
+      # user-provided semaphore name (without the "semaphore:" prefix).
+      #
+      #   expect("api_limit").to have_available_tokens(3)
+      ::RSpec::Matchers.define :have_available_tokens do |expected|
+        match do |name|
+          Matchers.coordination_adapter.semaphore_state(name)[:available] == expected
+        end
+
+        failure_message do |name|
+          state = Matchers.coordination_adapter.semaphore_state(name)
+          "expected semaphore '#{name}' to have #{expected} available tokens, " \
+            "got #{state[:available]} (held: #{state[:held]}, limit: #{state[:limit]})"
+        end
+      end
+
+      # Asserts the number of currently-checked-out semaphore tokens.
+      #
+      #   expect("api_limit").to have_held_tokens(2)
+      ::RSpec::Matchers.define :have_held_tokens do |expected|
+        match do |name|
+          Matchers.coordination_adapter.semaphore_state(name)[:held] == expected
+        end
+
+        failure_message do |name|
+          state = Matchers.coordination_adapter.semaphore_state(name)
+          "expected semaphore '#{name}' to have #{expected} held tokens, " \
+            "got #{state[:held]} (available: #{state[:available]}, limit: #{state[:limit]})"
+        end
+      end
+
+      # Asserts the current rate-limit counter for a (key_base, period) pair.
+      # Use `.for(period_unit)` to specify which window.
+      #
+      #   expect("stripe:42").to have_rate_limit_count(3).for(:second)
+      ::RSpec::Matchers.define :have_rate_limit_count do |expected|
+        match do |key_base|
+          raise ArgumentError, "have_rate_limit_count requires .for(period)" unless @period
+
+          Matchers.coordination_adapter.rate_limit_count(key_base, @period) == expected
+        end
+
+        chain :for do |period|
+          @period = period
+        end
+
+        failure_message do |key_base|
+          actual = Matchers.coordination_adapter.rate_limit_count(key_base, @period)
+          "expected rate-limit '#{key_base}' (#{@period}) count to be #{expected}, got #{actual}"
+        end
+      end
+
+      # Asserts that a `with_period` bucket has been marked. Use `.for(period)`.
+      #
+      #   expect("daily_report:7").to be_period_marked.for(:day)
+      ::RSpec::Matchers.define :be_period_marked do
+        match do |key_base|
+          raise ArgumentError, "be_period_marked requires .for(period)" unless @period
+
+          Matchers.coordination_adapter.period_marker?(key_base, @period)
+        end
+
+        chain :for do |period|
+          @period = period
+        end
+
+        failure_message do |key_base|
+          "expected period bucket #{RubyReactor::Period.key(key_base, @period).inspect} to be marked, but it is not"
+        end
+
+        failure_message_when_negated do |key_base|
+          "expected period bucket #{RubyReactor::Period.key(key_base, @period).inspect} not to be marked, but it is"
+        end
+      end
+
       # Add more matchers as per plan
       # rubocop:enable Metrics/BlockLength
     end
+    # rubocop:enable Metrics/ModuleLength
   end
 end