ruby_reactor 0.3.1 → 0.3.2

data/lib/ruby_reactor/storage/redis_locking.rb

@@ -0,0 +1,251 @@
+# frozen_string_literal: true
+
+module RubyReactor
+  module Storage
+    # Adapter contract uses non-`?` names for methods that return booleans
+    # (`lock_acquire`, `semaphore_release`, etc). Renaming would break the
+    # public storage adapter API, so silence the predicate-name cop here.
+    # rubocop:disable Naming/PredicateMethod
+    module RedisLocking
+      # Scripts for Lock Primitives
+      LOCK_ACQUIRE_SCRIPT = <<~LUA
+        local key = KEYS[1]
+        local owner = ARGV[1]
+        local ttl = tonumber(ARGV[2])
+
+        if redis.call('exists', key) == 0 then
+          redis.call('hset', key, 'owner', owner)
+          redis.call('hset', key, 'count', 1)
+          redis.call('expire', key, ttl)
+          return 1
+        elseif redis.call('hget', key, 'owner') == owner then
+          redis.call('hincrby', key, 'count', 1)
+          redis.call('expire', key, ttl)
+          return 1
+        else
+          return 0
+        end
+      LUA
+
+      LOCK_RELEASE_SCRIPT = <<~LUA
+        local key = KEYS[1]
+        local owner = ARGV[1]
+
+        if redis.call('hget', key, 'owner') == owner then
+          local new_count = redis.call('hincrby', key, 'count', -1)
+          if new_count <= 0 then
+            redis.call('del', key)
+          end
+          return 1
+        else
+          return 0
+        end
+      LUA
+
+      LOCK_EXTEND_SCRIPT = <<~LUA
+        local key = KEYS[1]
+        local owner = ARGV[1]
+        local ttl = tonumber(ARGV[2])
+
+        if redis.call('hget', key, 'owner') == owner then
+          redis.call('expire', key, ttl)
+          return 1
+        else
+          return 0
+        end
+      LUA
+
+      # Lock Primitives
+
+      def lock_acquire(key, owner, ttl)
+        result = @redis.eval(LOCK_ACQUIRE_SCRIPT, keys: [key], argv: [owner, ttl])
+        result == 1
+      end
+
+      def lock_release(key, owner)
+        result = @redis.eval(LOCK_RELEASE_SCRIPT, keys: [key], argv: [owner])
+        result == 1
+      end
+
+      def lock_extend(key, owner, ttl)
+        result = @redis.eval(LOCK_EXTEND_SCRIPT, keys: [key], argv: [owner, ttl])
+        result == 1
+      end
+
+      # Semaphore Primitives
+      #
+      # Storage layout:
+      #   LIST   <key>       — available token UUIDs
+      #   SET    <key>:held  — tokens currently checked out
+      #   STRING <key>:init  — sentinel marking that init has run; value = limit
+      #
+      # Tokens are unique UUIDs so release can verify the caller actually holds
+      # one before pushing it back, blocking double-release and over-cap RPUSH.
+
+      SEM_ACQUIRE_SCRIPT = <<~LUA
+        local list_key = KEYS[1]
+        local held_key = KEYS[2]
+        local token = redis.call('lpop', list_key)
+        if not token then return false end
+        redis.call('sadd', held_key, token)
+        return token
+      LUA
+
+      SEM_RELEASE_SCRIPT = <<~LUA
+        local list_key = KEYS[1]
+        local held_key = KEYS[2]
+        local limit = tonumber(ARGV[1])
+        local token = ARGV[2]
+        if redis.call('srem', held_key, token) == 0 then
+          return 0
+        end
+        if redis.call('llen', list_key) >= limit then
+          return 0
+        end
+        redis.call('rpush', list_key, token)
+        return 1
+      LUA
+
+      SEMAPHORE_TTL = 86_400
+
+      def semaphore_init(key, limit)
+        return false unless @redis.set("#{key}:init", limit, nx: true, ex: SEMAPHORE_TTL)
+
+        tokens = Array.new(limit) { SecureRandom.uuid }
+        @redis.rpush(key, tokens)
+        @redis.expire(key, SEMAPHORE_TTL)
+        true
+      end
+
+      def semaphore_reset(key)
+        @redis.del(key)
+        @redis.del("#{key}:held")
+        @redis.del("#{key}:init")
+      end
+
+      def semaphore_acquire(key, timeout: 0)
+        held_key = "#{key}:held"
+
+        token = if timeout.to_f.positive?
+                  result = @redis.blpop(key, timeout: timeout)
+                  next_token = result&.last
+                  @redis.sadd(held_key, next_token) if next_token
+                  next_token
+                else
+                  @redis.eval(SEM_ACQUIRE_SCRIPT, keys: [key, held_key], argv: [])
+                end
+
+        return nil unless token
+
+        @redis.expire(held_key, SEMAPHORE_TTL)
+        token
+      end
+
+      def semaphore_release(key, token, limit)
+        return false unless token
+
+        result = @redis.eval(
+          SEM_RELEASE_SCRIPT,
+          keys: [key, "#{key}:held"],
+          argv: [limit, token]
+        )
+        result == 1
+      end
+
+      def semaphore_exists?(key)
+        @redis.exists?("#{key}:init")
+      end
+
+      # Period Primitives — used by `with_period` to dedup bucketed runs.
+
+      def period_seen?(key)
+        @redis.exists?(key)
+      end
+
+      def period_mark(key, ttl)
+        @redis.set(key, "1", ex: ttl)
+      end
+
+      # Rate Limit Primitives — fixed-window counter, supports multiple
+      # windows in one atomic call. Two-pass inside Lua so a miss on the Nth
+      # window does not leave the previous N-1 incremented.
+      #
+      # ARGV layout: [now, period_1, limit_1, ttl_1, period_2, limit_2, ttl_2, ...]
+      # KEYS:        [bucket_key_1, bucket_key_2, ...]
+      # Returns:     [allowed (1|0), retry_after_seconds, failed_index]
+
+      RATE_LIMIT_SCRIPT = <<~LUA
+        local now = tonumber(ARGV[1])
+        local n = #KEYS
+
+        for i = 1, n do
+          local base = 2 + (i - 1) * 3
+          local period = tonumber(ARGV[base])
+          local lim = tonumber(ARGV[base + 1])
+          local count = tonumber(redis.call('get', KEYS[i]) or '0')
+          if count >= lim then
+            local retry_after = period - (now % period)
+            if retry_after <= 0 then retry_after = 1 end
+            return {0, retry_after, i}
+          end
+        end
+
+        for i = 1, n do
+          local base = 2 + (i - 1) * 3
+          local ttl = tonumber(ARGV[base + 2])
+          local count = redis.call('incr', KEYS[i])
+          if count == 1 then
+            redis.call('expire', KEYS[i], ttl)
+          end
+        end
+
+        return {1, 0, 0}
+      LUA
+
+      def rate_limit_check_and_increment(keys, argv)
+        @redis.eval(RATE_LIMIT_SCRIPT, keys: keys, argv: argv)
+      end
+
+      # Inspectors — used by RSpec matchers to assert on lock/semaphore/
+      # rate-limit/period state without leaking Redis-specific calls into
+      # test code.
+
+      # Returns { owner:, count: } for a held lock, or nil if free.
+      # `prefixed_key` is the full key (e.g. "lock:order:42").
+      def lock_info(prefixed_key)
+        return nil unless @redis.exists?(prefixed_key)
+
+        data = @redis.hgetall(prefixed_key)
+        return nil if data.empty?
+
+        { owner: data["owner"], count: data["count"].to_i }
+      end
+
+      # Returns { available:, held:, limit: } for a semaphore. `name` is the
+      # user-provided semaphore key (without the "semaphore:" prefix).
+      def semaphore_state(name)
+        prefix = "semaphore:#{name}"
+        {
+          available: @redis.llen(prefix),
+          held: @redis.scard("#{prefix}:held"),
+          limit: @redis.get("#{prefix}:init").to_i
+        }
+      end
+
+      # Current count for a rate-limit bucket. `key_base` is the user's
+      # `with_rate_limit` key, `every` is the period (symbol or seconds).
+      def rate_limit_count(key_base, every, now: Time.now.to_i)
+        period_seconds = RubyReactor::Period.period_seconds(every)
+        bucket = now / period_seconds
+        @redis.get("rate:#{key_base}:#{every}:#{bucket}").to_i
+      end
+
+      # Has a period bucket been marked? `key_base` is the user's
+      # `with_period` key, `every` is the period.
+      def period_marker?(key_base, every, now: Time.now.utc)
+        @redis.exists?(RubyReactor::Period.key(key_base, every, now: now))
+      end
+    end
+    # rubocop:enable Naming/PredicateMethod
+  end
+end

data/lib/ruby_reactor/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RubyReactor
-  VERSION = "0.3.1"
+  VERSION = "0.3.2"
 end

data/lib/ruby_reactor.rb

@@ -4,6 +4,11 @@ require "zeitwerk"
 require "pathname"
 require_relative "ruby_reactor/registry"
 require_relative "ruby_reactor/utils/code_extractor"
+require_relative "ruby_reactor/dsl/lockable" # Add this
+require_relative "ruby_reactor/lock"
+require_relative "ruby_reactor/semaphore"
+require_relative "ruby_reactor/period"
+require_relative "ruby_reactor/rate_limit"
 
 # Load dry-validation if available (for validation features)
 begin
@@ -40,11 +45,45 @@ module RubyReactor
       false
     end
 
+    def skipped?
+      false
+    end
+
     def to_h
       { success: true, value: @value }
     end
   end
 
+  # A "clean halt" signal. Two ways to produce one:
+  #
+  #   1. Implicitly, when a reactor's `with_period` gate finds the bucket has
+  #      already been claimed. The executor short-circuits before any step
+  #      runs.
+  #
+  #   2. Explicitly, by returning `RubyReactor.Skipped(reason: "...")` from a
+  #      step's `run` block. The reactor halts immediately — no further steps,
+  #      and crucially **no compensation** of already-completed steps. Use this
+  #      when a step discovers that the rest of the workflow is not needed
+  #      (e.g. "user already opted out", "nothing to do this round") and the
+  #      partial progress is still correct to keep.
+  #
+  # Subclass of Success so callers that only check `success?` continue to work;
+  # `skipped?` distinguishes it.
+  class Skipped < Success
+    attr_reader :reason, :period_key, :step_name
+
+    def initialize(reason: nil, period_key: nil, step_name: nil)
+      super(nil)
+      @reason = reason
+      @period_key = period_key
+      @step_name = step_name
+    end
+
+    def skipped?
+      true
+    end
+  end
+
   class Failure
     attr_reader :error, :retryable, :step_name, :inputs, :backtrace, :reactor_name, :step_arguments, :exception_class,
                 :file_path, :line_number, :code_snippet, :validation_errors
@@ -105,6 +144,10 @@ module RubyReactor
       @retryable
     end
 
+    def skipped?
+      false
+    end
+
     def invalid_payload?
       @invalid_payload
     end
@@ -271,6 +314,12 @@ module RubyReactor
     Failure.new(error, **kwargs)
   end
 
+  # Build a `Skipped` result. Return one from a step's `run` block to halt the
+  # reactor cleanly without triggering compensation of previous steps.
+  def self.Skipped(reason: nil, **kwargs)
+    Skipped.new(reason: reason, **kwargs)
+  end
+
   def self.configure
     yield(Configuration.instance) if block_given?
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ruby_reactor
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.3.2
 platform: ruby
 authors:
 - Artur
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-01-22 00:00:00.000000000 Z
+date: 2026-05-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: dry-validation
@@ -107,6 +107,7 @@ files:
 - documentation/images/failed_order_processing.png
 - documentation/images/payment_workflow.png
 - documentation/interrupts.md
+- documentation/locks_and_semaphores.md
 - documentation/retry_configuration.md
 - documentation/testing.md
 - gui/.gitignore
@@ -147,6 +148,7 @@ files:
 - lib/ruby_reactor/dsl/compose_builder.rb
 - lib/ruby_reactor/dsl/interrupt_builder.rb
 - lib/ruby_reactor/dsl/interrupt_step_config.rb
+- lib/ruby_reactor/dsl/lockable.rb
 - lib/ruby_reactor/dsl/map_builder.rb
 - lib/ruby_reactor/dsl/reactor.rb
 - lib/ruby_reactor/dsl/step_builder.rb
@@ -170,6 +172,7 @@ files:
 - lib/ruby_reactor/executor/retry_manager.rb
 - lib/ruby_reactor/executor/step_executor.rb
 - lib/ruby_reactor/interrupt_result.rb
+- lib/ruby_reactor/lock.rb
 - lib/ruby_reactor/map/collector.rb
 - lib/ruby_reactor/map/dispatcher.rb
 - lib/ruby_reactor/map/element_executor.rb
@@ -177,6 +180,8 @@ files:
 - lib/ruby_reactor/map/helpers.rb
 - lib/ruby_reactor/map/result_enumerator.rb
 - lib/ruby_reactor/max_retries_exhausted_failure.rb
+- lib/ruby_reactor/period.rb
+- lib/ruby_reactor/rate_limit.rb
 - lib/ruby_reactor/reactor.rb
 - lib/ruby_reactor/registry.rb
 - lib/ruby_reactor/retry_context.rb
@@ -186,6 +191,7 @@ files:
 - lib/ruby_reactor/rspec/matchers.rb
 - lib/ruby_reactor/rspec/step_executor_patch.rb
 - lib/ruby_reactor/rspec/test_subject.rb
+- lib/ruby_reactor/semaphore.rb
 - lib/ruby_reactor/sidekiq_adapter.rb
 - lib/ruby_reactor/sidekiq_workers/map_collector_worker.rb
 - lib/ruby_reactor/sidekiq_workers/map_element_worker.rb
@@ -197,6 +203,7 @@ files:
 - lib/ruby_reactor/storage/adapter.rb
 - lib/ruby_reactor/storage/configuration.rb
 - lib/ruby_reactor/storage/redis_adapter.rb
+- lib/ruby_reactor/storage/redis_locking.rb
 - lib/ruby_reactor/template/base.rb
 - lib/ruby_reactor/template/dynamic_source.rb
 - lib/ruby_reactor/template/element.rb