ruby_reactor 0.3.0 → 0.3.2

data/lib/ruby_reactor/{async_router.rb → sidekiq_adapter.rb}

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module RubyReactor
-  class AsyncRouter
+  class SidekiqAdapter
     def self.perform_async(serialized_context, reactor_class_name = nil, intermediate_results: {})
       job_id = SidekiqWorkers::Worker.perform_async(serialized_context, reactor_class_name)
       context = ContextSerializer.deserialize(serialized_context)
@@ -20,7 +20,7 @@ module RubyReactor
     def self.perform_map_element_async(map_id:, element_id:, index:, serialized_inputs:, reactor_class_info:,
                                        strict_ordering:, parent_context_id:, parent_reactor_class_name:, step_name:,
                                        batch_size: nil, serialized_context: nil, fail_fast: nil)
-      RubyReactor::SidekiqWorkers::MapElementWorker.perform_async(
+      job_id = RubyReactor::SidekiqWorkers::MapElementWorker.perform_async(
         {
           "map_id" => map_id,
           "element_id" => element_id,
@@ -36,6 +36,7 @@ module RubyReactor
           "fail_fast" => fail_fast
         }
       )
+      RubyReactor::AsyncResult.new(job_id: job_id)
     end
 
     def self.perform_map_element_in(delay, map_id:, element_id:, index:, serialized_inputs:, reactor_class_info:,
@@ -63,7 +64,7 @@ module RubyReactor
     # rubocop:disable Metrics/ParameterLists
     def self.perform_map_collection_async(parent_context_id:, map_id:, parent_reactor_class_name:, step_name:,
                                           strict_ordering:, timeout:)
-      RubyReactor::SidekiqWorkers::MapCollectorWorker.perform_async(
+      job_id = RubyReactor::SidekiqWorkers::MapCollectorWorker.perform_async(
         {
           "parent_context_id" => parent_context_id,
           "map_id" => map_id,
@@ -73,12 +74,15 @@ module RubyReactor
           "timeout" => timeout
         }
       )
+      RubyReactor::AsyncResult.new(job_id: job_id)
     end
-    # rubocop:enable Metrics/ParameterLists
 
+    # rubocop:enable Metrics/ParameterLists
+    # rubocop:disable Metrics/ParameterLists
     def self.perform_map_execution_async(map_id:, serialized_inputs:, reactor_class_info:, strict_ordering:,
                                          parent_context_id:, parent_reactor_class_name:, step_name:, fail_fast: nil)
-      RubyReactor::SidekiqWorkers::MapExecutionWorker.perform_async(
+      # rubocop:enable Metrics/ParameterLists
+      job_id = RubyReactor::SidekiqWorkers::MapExecutionWorker.perform_async(
         {
           "map_id" => map_id,
           "serialized_inputs" => serialized_inputs,
@@ -90,6 +94,7 @@ module RubyReactor
           "fail_fast" => fail_fast
         }
       )
+      RubyReactor::AsyncResult.new(job_id: job_id)
     end
   end
 end

data/lib/ruby_reactor/sidekiq_workers/worker.rb

@@ -17,7 +17,7 @@ module RubyReactor
         # Handle infrastructure failures (network, Redis, etc.)
       end
 
-      def perform(serialized_context, reactor_class_name = nil)
+      def perform(serialized_context, reactor_class_name = nil, snooze_count = 0)
         context = ContextSerializer.deserialize(serialized_context)
 
         # If reactor_class_name is provided, use it to get the reactor class
@@ -35,20 +35,80 @@ 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
+        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
+          # 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
     end
   end

data/lib/ruby_reactor/step/compose_step.rb

@@ -84,7 +84,6 @@ module RubyReactor
         def link_contexts(child_context, parent_context)
           child_context.parent_context = parent_context
           child_context.root_context = parent_context.root_context || parent_context
-          child_context.test_mode = parent_context.test_mode
           child_context.inline_async_execution = parent_context.inline_async_execution
         end
 

data/lib/ruby_reactor/step/map_step.rb

@@ -57,7 +57,9 @@ module RubyReactor
         private
 
         def should_run_async?(arguments, context)
-          arguments[:async] && !context.inline_async_execution
+          return false if context.inline_async_execution
+
+          arguments[:async]
         end
 
         def run_inline(arguments, context)
@@ -118,30 +120,21 @@ module RubyReactor
         def link_contexts(child_context, parent_context)
           child_context.parent_context = parent_context
           child_context.root_context = parent_context.root_context || parent_context
-          child_context.test_mode = parent_context.test_mode
           child_context.inline_async_execution = parent_context.inline_async_execution
         end
 
-        def process_results(results, collect_block, fail_fast = true)
+        def process_results(results, collect_block, _fail_fast = true)
           if collect_block
             begin
               # Collect block receives Result objects when fail_fast is false, values when true
-              RubyReactor::Success(collect_block.call(results))
+              return RubyReactor::Success(collect_block.call(results))
             rescue StandardError => e
-              RubyReactor::Failure(e)
+              return RubyReactor::Failure(e)
             end
-          elsif fail_fast
-            # Default behavior when no collect block
-            # Current behavior: results are already values
-            RubyReactor::Success(results)
-          else
-            # New behavior: extract successful values only
-            # New behavior: extract successful values only IF fail_fast is true behavior implies only values
-            # However, if fail_fast is false, we want to return results as is, or if logic dictates otherwise.
-            # wait, if fail_fast=false, we expect Result objects so we can check if success/failure.
-            # If we return only successes, we hide failures.
-            RubyReactor::Success(results)
           end
+
+          # Simplified: both branches returned Success(results)
+          RubyReactor::Success(results)
         end
 
         def extract_path(value, path)
@@ -203,7 +196,7 @@ module RubyReactor
               argument_mappings: arguments[:argument_mappings],
               strict_ordering: arguments[:strict_ordering],
               mapped_reactor_class: arguments[:mapped_reactor_class],
-              fail_fast: arguments[:fail_fast]
+              fail_fast: arguments[:fail_fast].nil? || arguments[:fail_fast]
             )
             queue_collector(map_id, context, step_name, arguments[:strict_ordering])
             "map:#{map_id}"
@@ -284,7 +277,7 @@ module RubyReactor
             map_id: map_id, serialized_inputs: serialized_inputs,
             reactor_class_info: reactor_class_info, strict_ordering: arguments[:strict_ordering],
             parent_context_id: context.context_id, parent_reactor_class_name: context.reactor_class.name,
-            step_name: step_name.to_s, fail_fast: arguments[:fail_fast]
+            step_name: step_name.to_s, fail_fast: arguments[:fail_fast].nil? || arguments[:fail_fast]
           )
         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.0"
+  VERSION = "0.3.2"
 end

data/lib/ruby_reactor/web/api.rb

@@ -24,39 +24,44 @@ module RubyReactor
           r.on String do |reactor_id|
             # GET /api/reactors/:id
             r.get do
-              data = RubyReactor::Configuration.instance.storage_adapter.find_context_by_id(reactor_id)
-              return { error: "Reactor not found" } unless data
+              raw_data = RubyReactor::Configuration.instance.storage_adapter.find_context_by_id(reactor_id)
+              return { error: "Reactor not found" } unless raw_data
 
-              reactor_class = data["reactor_class"] ? Object.const_get(data["reactor_class"]) : nil
+              # Clean data for API usage
+              data = ContextSerializer.deserialize_value(raw_data)
+
+              reactor_class = data[:reactor_class] ? Object.const_get(data[:reactor_class].to_s) : nil
               structure = {}
 
               structure = self.class.build_structure(reactor_class) if reactor_class.respond_to?(:steps)
 
-              {
-                id: data["context_id"],
-                class: data["reactor_class"],
-                status: if %w[failed paused completed running].include?(data["status"])
-                          data["status"]
-                        elsif data["cancelled"]
+              response_data = {
+                id: data[:context_id],
+                class: data[:reactor_class].to_s,
+                status: if %w[failed paused completed running].include?(data[:status].to_s)
+                          data[:status].to_s
+                        elsif data[:cancelled]
                           "cancelled"
                         else
-                          (data["current_step"] ? "running" : "completed")
+                          (data[:current_step] ? "running" : "completed")
                         end,
-                current_step: data["current_step"],
-                retry_count: data["retry_count"] || 0,
-                undo_stack: data["undo_stack"] || [],
-                step_attempts: data.dig("retry_context", "step_attempts") || {},
-                created_at: data["started_at"],
-                inputs: data["inputs"],
-                intermediate_results: data["intermediate_results"],
+                current_step: data[:current_step].to_s,
+                retry_count: data[:retry_count] || 0,
+                undo_stack: data[:undo_stack] || [],
+                step_attempts: data.dig(:retry_context, :step_attempts) || {},
+                created_at: data[:started_at],
+                inputs: data[:inputs],
+                intermediate_results: data[:intermediate_results],
                 structure: structure,
-                steps: data["execution_trace"] || [],
+                steps: data[:execution_trace] || [],
                 composed_contexts: self.class.hydrate_composed_contexts(
-                  data["composed_contexts"] || {},
-                  data["reactor_class"]
+                  data[:composed_contexts] || {},
+                  data[:reactor_class]&.to_s
                 ),
-                error: data["failure_reason"]
+                error: data[:failure_reason]
               }
+
+              ContextSerializer.simplify_for_api(response_data)
             end
 
             # POST /api/reactors/:id/retry
@@ -159,7 +164,8 @@ module RubyReactor
         return {} unless composed_contexts.is_a?(Hash)
 
         composed_contexts.transform_values do |value|
-          if ["map_ref", :map_ref].include?(value["type"])
+          type = value[:type] || value["type"]
+          if ["map_ref", :map_ref].include?(type)
             hydrate_map_ref(value, reactor_class_name)
           else
             value
@@ -169,10 +175,12 @@ module RubyReactor
 
       def self.hydrate_map_ref(ref_data, reactor_class_name)
         storage = RubyReactor.configuration.storage_adapter
-        map_id = ref_data["map_id"]
+        map_id = ref_data[:map_id] || ref_data["map_id"]
 
         # Use the specific element reactor class if available, otherwise fallback to parent
-        target_reactor_class = ref_data["element_reactor_class"] || reactor_class_name
+        target_reactor_class = ref_data[:element_reactor_class] ||
+                               ref_data["element_reactor_class"] ||
+                               reactor_class_name
 
         # 1. Check for specific failure (O(1))
         # Stored by ResultHandler when a map element fails