ruby_reactor 0.3.1 → 0.4.0

data/lib/ruby_reactor/semaphore.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module RubyReactor
+  class Semaphore
+    class AcquisitionError < StandardError; end
+
+    attr_reader :key, :limit, :wait, :token
+
+    def initialize(key, limit: 1, wait: 0)
+      @key = "semaphore:#{key}"
+      @limit = limit
+      @wait = wait
+      @token = nil
+    end
+
+    def acquire # rubocop:disable Naming/PredicateMethod
+      ensure_initialized
+
+      token = adapter.semaphore_acquire(@key, timeout: @wait)
+      raise AcquisitionError, "Could not acquire semaphore '#{@key}' within #{@wait} seconds" unless token
+
+      @token = token
+      true
+    end
+
+    # Returns true if a held token was returned to the pool.
+    # Idempotent: a second release (or one without a prior acquire) is a no-op.
+    def release
+      return false unless @token
+
+      result = adapter.semaphore_release(@key, @token, @limit)
+      @token = nil
+      result
+    end
+
+    def synchronize
+      acquire
+      yield
+    ensure
+      release
+    end
+
+    private
+
+    def ensure_initialized
+      # Double-checked locking pattern optimized for Redis
+      # 1. Optimistic check (if key exists)
+      return if adapter.semaphore_exists?(@key)
+
+      # 2. Try to init
+      adapter.semaphore_init(@key, @limit)
+    end
+
+    def adapter
+      RubyReactor.configuration.storage_adapter
+    end
+  end
+end

data/lib/ruby_reactor/sidekiq_workers/worker.rb

@@ -17,8 +17,17 @@ module RubyReactor
         # Handle infrastructure failures (network, Redis, etc.)
       end
 
-      def perform(serialized_context, reactor_class_name = nil)
-        context = ContextSerializer.deserialize(serialized_context)
+      def perform(serialized_context, reactor_class_name = nil, snooze_count = 0)
+        begin
+          context = ContextSerializer.deserialize(serialized_context)
+        rescue RubyReactor::Error::DeserializationError,
+               RubyReactor::Error::SchemaVersionError => e
+          # Permanent failures — retrying the same blob will keep failing.
+          # Mark the context as failed (best-effort) and return so Sidekiq
+          # does not burn its retry budget.
+          handle_deserialization_failure(serialized_context, reactor_class_name, e)
+          return
+        end
 
         # If reactor_class_name is provided, use it to get the reactor class
         # This handles cases where the class can't be found via const_get
@@ -35,18 +44,128 @@ module RubyReactor
         # Mark that we're executing inline to prevent nested async calls
         context.inline_async_execution = true
 
-        # Resume execution from the failed step
-        executor = Executor.new(context.reactor_class, {}, context)
-        executor.resume_execution
-        executor.save_context
-        executor.result
+        begin
+          # Resume execution from the failed step
+          executor = Executor.new(context.reactor_class, {}, context)
+          executor.resume_execution
+          executor.save_context
+
+          # Return the executor (which now has the result stored in it)
+          executor
+        rescue RubyReactor::Lock::AcquisitionError,
+               RubyReactor::Semaphore::AcquisitionError,
+               RubyReactor::RateLimit::ExceededError => e
+          # Snooze on expected concurrency or rate contention. We avoid
+          # Sidekiq's native retry path so this doesn't burn the job's retry
+          # budget or appear as an error in dashboards. After the configured
+          # cap is reached we escalate by marking the reactor as failed.
+          handle_snooze(serialized_context, reactor_class_name, context, snooze_count, e)
+        end
       end
 
       private
 
+      def handle_snooze(serialized_context, reactor_class_name, context, snooze_count, error)
+        config = RubyReactor.configuration
+        max = config.lock_snooze_max_attempts
+
+        if max != :infinity && snooze_count >= max
+          escalate_snooze(context, snooze_count, error)
+          return
+        end
+
+        delay = compute_snooze_delay(config, error)
+        self.class.perform_in(delay, serialized_context, reactor_class_name, snooze_count + 1)
+      end
+
+      # Use the error's `retry_after_seconds` hint when available
+      # (RateLimit::ExceededError carries the time until the bucket rolls);
+      # otherwise fall back to the configured base + jitter for lock/semaphore
+      # contention which has no precise hint.
+      def compute_snooze_delay(config, error)
+        jitter = config.lock_snooze_jitter.to_f
+        jitter_amount = jitter.positive? ? rand(0.0..jitter) : 0.0
+
+        if error.respond_to?(:retry_after_seconds) && error.retry_after_seconds
+          [error.retry_after_seconds.to_f, 0.1].max + jitter_amount
+        else
+          config.lock_snooze_base_delay.to_f + jitter_amount
+        end
+      end
+
+      def escalate_snooze(context, snooze_count, error)
+        RubyReactor.configuration.logger.warn(
+          "RubyReactor snooze limit reached after #{snooze_count} attempts " \
+          "for context #{context.context_id}: #{error.message}"
+        )
+
+        context.status = :failed
+        context.failure_reason = {
+          message: error.message,
+          exception_class: error.class.name,
+          snooze_attempts: snooze_count
+        }
+
+        serialized = ContextSerializer.serialize(context)
+        reactor_class_name = context.reactor_class&.name || "AnonymousReactor"
+        RubyReactor.configuration.storage_adapter.store_context(
+          context.context_id,
+          serialized,
+          reactor_class_name
+        )
+      end
+
       def log_infrastructure_failure(msg, exception)
-        ::Sidekiq.logger.error("RubyReactor infrastructure failure: #{exception.message}")
-        ::Sidekiq.logger.error("Job details: #{msg.inspect}")
+        RubyReactor.configuration.logger.error("RubyReactor infrastructure failure: #{exception.message}")
+        RubyReactor.configuration.logger.error("Job details: #{msg.inspect}")
+      end
+
+      def handle_deserialization_failure(serialized_context, reactor_class_name, error)
+        metadata = extract_failure_metadata(serialized_context)
+        context_id = metadata[:context_id]
+        resolved_reactor_class_name = reactor_class_name || metadata[:reactor_class_name]
+
+        RubyReactor.configuration.logger.error(
+          "RubyReactor deserialization failure for context " \
+          "#{context_id || "unknown"}: #{error.class.name}: #{error.message}"
+        )
+
+        return unless context_id && resolved_reactor_class_name
+
+        payload = build_failed_context_payload(context_id, resolved_reactor_class_name, error)
+        RubyReactor.configuration.storage_adapter.store_context(
+          context_id,
+          payload,
+          resolved_reactor_class_name
+        )
+      rescue StandardError => e
+        # Don't let a persistence failure mask the original deserialization error.
+        RubyReactor.configuration.logger.error(
+          "RubyReactor failed to persist deserialization failure: #{e.class.name}: #{e.message}"
+        )
+      end
+
+      def extract_failure_metadata(serialized_context)
+        data = JSON.parse(serialized_context)
+        {
+          context_id: data["context_id"],
+          reactor_class_name: data["reactor_class"]
+        }
+      rescue StandardError
+        {}
+      end
+
+      def build_failed_context_payload(context_id, reactor_class_name, error)
+        JSON.generate(
+          "schema_version" => ContextSerializer::SCHEMA_VERSION,
+          "context_id" => context_id,
+          "reactor_class" => reactor_class_name,
+          "status" => "failed",
+          "failure_reason" => {
+            "message" => error.message,
+            "exception_class" => error.class.name
+          }
+        )
       end
     end
   end

data/lib/ruby_reactor/storage/redis_adapter.rb

@@ -6,6 +6,8 @@ require "json"
 module RubyReactor
   module Storage
     class RedisAdapter < Adapter
+      include RedisLocking
+
       def initialize(redis_config)
         super()
         @redis = Redis.new(redis_config)

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.4.0"
 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,13 @@
 --- !ruby/object:Gem::Specification
 name: ruby_reactor
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.4.0
 platform: ruby
 authors:
 - Artur
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-01-22 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: dry-validation
@@ -89,56 +88,15 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".release-please-config.json"
+- ".release-please-manifest.json"
 - ".rspec"
 - ".rubocop.yml"
+- ".tool-versions"
+- CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - README.md
 - Rakefile
-- documentation/DAG.md
-- documentation/README.md
-- documentation/async_reactors.md
-- documentation/composition.md
-- documentation/core_concepts.md
-- documentation/data_pipelines.md
-- documentation/examples/inventory_management.md
-- documentation/examples/order_processing.md
-- documentation/examples/payment_processing.md
-- documentation/getting_started.md
-- documentation/images/failed_order_processing.png
-- documentation/images/payment_workflow.png
-- documentation/interrupts.md
-- documentation/retry_configuration.md
-- documentation/testing.md
-- gui/.gitignore
-- gui/README.md
-- gui/eslint.config.js
-- gui/index.html
-- gui/package-lock.json
-- gui/package.json
-- gui/postcss.config.js
-- gui/public/vite.svg
-- gui/src/App.css
-- gui/src/App.tsx
-- gui/src/assets/react.svg
-- gui/src/components/DagVisualizer.tsx
-- gui/src/components/Dashboard.tsx
-- gui/src/components/ErrorBoundary.tsx
-- gui/src/components/ReactorDetail.tsx
-- gui/src/components/StepInspector.tsx
-- gui/src/components/__tests__/DagVisualizer.test.tsx
-- gui/src/components/__tests__/ReactorDetail.test.tsx
-- gui/src/components/__tests__/StepInspector.test.tsx
-- gui/src/globals.d.ts
-- gui/src/index.css
-- gui/src/lib/utils.ts
-- gui/src/main.tsx
-- gui/src/test/setup.ts
-- gui/tailwind.config.js
-- gui/tsconfig.app.json
-- gui/tsconfig.json
-- gui/tsconfig.node.json
-- gui/vite.config.ts
-- gui/vitest.config.ts
 - lib/ruby_reactor.rb
 - lib/ruby_reactor/configuration.rb
 - lib/ruby_reactor/context.rb
@@ -147,6 +105,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 +129,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 +137,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 +148,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 +160,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
@@ -226,7 +190,6 @@ metadata:
   homepage_uri: https://github.com/arturictus/ruby_reactor
   source_code_uri: https://github.com/arturictus/ruby_reactor
   changelog_uri: https://github.com/arturictus/ruby_reactor/blob/main/CHANGELOG.md
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -241,8 +204,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.19
-signing_key:
+rubygems_version: 4.0.10
 specification_version: 4
 summary: A dynamic, concurrent, dependency-resolving saga orchestrator for Ruby.
 test_files: []