ruby_reactor 0.6.0 → 0.7.1

data/lib/ruby_reactor/storage/redis_adapter.rb

@@ -8,9 +8,13 @@ module RubyReactor
     class RedisAdapter < Adapter
       include RedisLocking
       include RedisOrderedLocking
+      include RedisStepResults
+      include RedisPubSub
+      include RedisReactorScan
 
       def initialize(redis_config)
         super()
+        @redis_config = redis_config
         @redis = Redis.new(redis_config)
       end
 
@@ -174,45 +178,10 @@ module RubyReactor
         @redis.del(key)
       end
 
-      def subscribe(channel, &block)
-        @redis.subscribe(channel, &block)
-      end
-
-      def publish(channel, message)
-        @redis.publish(channel, message)
-      end
-
       def expire(key, seconds)
         @redis.expire(key, seconds)
       end
 
-      # New methods for API
-      def scan_reactors(pattern: "reactor:*:context:*", count: 50)
-        # Use SCAN to find keys matching the pattern
-        results = []
-        batch_keys = []
-
-        # scan_each yields keys. We buffer them to use MGET efficiently.
-        # We request a batch size from Redis (count: 100) to reduce roundtrips.
-        @redis.scan_each(match: pattern, count: 100) do |key|
-          batch_keys << key
-
-          # specific batch size for MGET processing
-          if batch_keys.size >= 50
-            results.concat(fetch_and_filter_reactors(batch_keys))
-            batch_keys = []
-
-            # Stop if we have enough results
-            return results.take(count) if results.size >= count
-          end
-        end
-
-        # Process remaining keys
-        results.concat(fetch_and_filter_reactors(batch_keys)) if batch_keys.any?
-
-        results.take(count)
-      end
-
       def find_context_by_id(context_id)
         # We don't know the reactor class, so we search for the ID
         pattern = "reactor:*:context:#{context_id}"
@@ -230,23 +199,6 @@ module RubyReactor
         JSON.parse(json)
       end
 
-      def determine_status(data)
-        status = data["status"].to_s
-        return status if status && %w[failed paused completed running skipped pending].include?(status)
-        return "cancelled" if data["cancelled"]
-        # Heuristic
-        return "failed" if data["retry_count"]&.positive? && !data["current_step"].nil?
-        return "running" if data["current_step"]
-        return "completed" if execution_evidence?(data)
-
-        "pending"
-      end
-
-      def execution_evidence?(data)
-        (data["execution_trace"] || []).any? ||
-          (data["intermediate_results"] || {}).any?
-      end
-
       def store_map_element_context_id(map_id, context_id, reactor_class_name)
         key = map_element_contexts_key(map_id, reactor_class_name)
         @redis.rpush(key, context_id)
@@ -320,25 +272,6 @@ module RubyReactor
         RubyReactor.configuration.context_ttl
       end
 
-      def fetch_and_filter_reactors(keys)
-        return [] if keys.empty?
-
-        json_results = @redis.mget(*keys)
-
-        json_results.compact.map do |json|
-          data = JSON.parse(json)
-          next if data["parent_context_id"] # Skip nested reactors
-
-          {
-            id: data["context_id"],
-            class: data["reactor_class"],
-            status: determine_status(data),
-            created_at: data["started_at"],
-            failure: data["failure_reason"]
-          }
-        end.compact
-      end
-
       def context_key(context_id, reactor_class_name)
         "reactor:#{reactor_class_name}:context:#{context_id}"
       end

data/lib/ruby_reactor/storage/redis_locking.rb

@@ -123,6 +123,13 @@ module RubyReactor
         @redis.del("#{key}:init")
       end
 
+      # Whether a token is still checked out — used to re-adopt a slot held
+      # across a parked async wait.
+      def semaphore_held(key, token)
+        @redis.sismember("#{key}:held", token)
+      end
+      alias semaphore_held? semaphore_held
+
       def semaphore_acquire(key, timeout: 0)
         held_key = "#{key}:held"
 

data/lib/ruby_reactor/storage/redis_pub_sub.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module RubyReactor
+  module Storage
+    # The completion-signal channel behind the notified wait. Pure latency
+    # optimisation: at-most-once, unpersisted, never load-bearing — every waiting
+    # path ends at a durable record, so a lost signal costs a fallback interval
+    # and never correctness.
+    module RedisPubSub
+      # SUBSCRIBE puts a connection into subscriber mode — every other command on
+      # it then fails — so this MUST NOT use the shared client, or one waiter
+      # would poison storage for the whole process. A dedicated connection is
+      # opened per subscription and closed on the way out.
+      #
+      # Blocks the calling thread until the block returns truthy for a message
+      # (completion signals are one-shot) or the thread is killed.
+      def subscribe(channel, &block)
+        connection = Redis.new(@redis_config)
+        connection.subscribe(channel) do |on|
+          on.message { |_channel, message| connection.unsubscribe if block.call(message) }
+        end
+      ensure
+        connection&.close
+      end
+
+      def publish(channel, message)
+        @redis.publish(channel, message)
+      end
+    end
+  end
+end

data/lib/ruby_reactor/storage/redis_reactor_scan.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module RubyReactor
+  module Storage
+    # Listing/scanning reactor contexts for the dashboard/API: a capped
+    # single-shot scan (`scan_reactors`, used by the sweeper) and a
+    # cursor-paginated variant (`scan_reactors_page`, used by `GET /reactors`
+    # so a client can page through a large result set in batches instead of
+    # one capped call).
+    module RedisReactorScan
+      def scan_reactors(pattern: "reactor:*:context:*", count: 50, include_dispatched_children: false)
+        # Use SCAN to find keys matching the pattern
+        results = []
+        batch_keys = []
+
+        # scan_each yields keys. We buffer them to use MGET efficiently.
+        # We request a batch size from Redis (count: 100) to reduce roundtrips.
+        @redis.scan_each(match: pattern, count: 100) do |key|
+          batch_keys << key
+
+          # specific batch size for MGET processing
+          if batch_keys.size >= 50
+            results.concat(fetch_and_filter_reactors(batch_keys, include_dispatched_children))
+            batch_keys = []
+
+            # Stop if we have enough results
+            return results.take(count) if results.size >= count
+          end
+        end
+
+        # Process remaining keys
+        results.concat(fetch_and_filter_reactors(batch_keys, include_dispatched_children)) if batch_keys.any?
+
+        results.take(count)
+      end
+
+      # `cursor` is an offset into a freshly re-sorted full key scan ("0" for
+      # the first page); the returned `cursor` is "0" once there is nothing
+      # left to fetch.
+      #
+      # Redis's own SCAN cursor can't be windowed to exactly `count` items:
+      # one `SCAN` call is free to return far more matches than its `count`
+      # hint once the keyspace is small (as it is here), so slicing that
+      # single batch down to `count` and reporting the raw cursor as the next
+      # page silently drops the overflow — a real bug this replaced. Instead
+      # we scan the full matching keyspace every call (cheap at dashboard
+      # scale), sort it for a stable order across calls, and slice a plain
+      # offset window out of it. A page can come back shorter than `count`
+      # when some keys in its window get filtered out by
+      # `fetch_and_filter_reactors` (dispatched children, non-context keys)
+      # — the cursor still advances correctly since it tracks raw key
+      # position, not filtered result count.
+      def scan_reactors_page(pattern: "reactor:*:context:*", cursor: "0", count: 50, include_dispatched_children: false)
+        offset = cursor.to_i
+        offset = 0 if offset.negative?
+
+        all_keys = []
+        @redis.scan_each(match: pattern, count: 100) { |key| all_keys << key }
+        all_keys.sort!
+
+        window = all_keys[offset, count] || []
+        next_offset = offset + window.size
+        next_cursor = next_offset < all_keys.size ? next_offset.to_s : "0"
+
+        { reactors: fetch_and_filter_reactors(window, include_dispatched_children), cursor: next_cursor }
+      end
+
+      def determine_status(data)
+        status = data["status"].to_s == "skipped" ? "halted" : data["status"].to_s # "skipped" is the legacy halt name
+        return status if %w[failed paused completed running halted pending].include?(status)
+        return "cancelled" if data["cancelled"]
+        # Heuristic
+        return "failed" if data["retry_count"]&.positive? && !data["current_step"].nil?
+        return "running" if data["current_step"]
+        return "completed" if execution_evidence?(data)
+
+        "pending"
+      end
+
+      def execution_evidence?(data)
+        (data["execution_trace"] || []).any? ||
+          (data["intermediate_results"] || {}).any?
+      end
+
+      private
+
+      def fetch_and_filter_reactors(keys, include_dispatched_children = false)
+        return [] if keys.empty?
+
+        json_results = @redis.mget(*keys)
+
+        json_results.compact.map do |json|
+          data = JSON.parse(json)
+          next if data["parent_context_id"] && !(include_dispatched_children && dispatched_child?(data))
+          # Skip non-context records (e.g. async_step Step Result Records) whose
+          # keys are a "reactor:*:context:*" substring match on the SCAN glob
+          # (context:#{id}:step_result:#{name}) but aren't a reactor context.
+          next unless data["reactor_class"]
+
+          {
+            id: data["context_id"],
+            class: data["reactor_class"],
+            status: determine_status(data),
+            created_at: data["started_at"],
+            failure: data["failure_reason"]
+          }
+        end.compact
+      end
+
+      # An `async_reactor` child owns its own job, so a lost job strands it like
+      # a top-level reactor. Compose children (inline) and map elements
+      # (Map::Sweeper's) carry no marker, so neither is swept.
+      def dispatched_child?(data) = data.dig("private_data", "async_dispatched")
+    end
+  end
+end

data/lib/ruby_reactor/storage/redis_step_results.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module RubyReactor
+  module Storage
+    # The durable outcome of one `async_step`, keyed by (parent context, step
+    # name). It lives OUTSIDE the parent's serialized context blob on purpose: a
+    # worker writes it concurrently with the still-running parent, and two
+    # writers on one blob race.
+    #
+    # The `dispatched` record is written before the job is enqueued, so it also
+    # serves as the re-attach marker on recovery — "a record exists" is
+    # exactly the question "was this already dispatched?".
+    module RedisStepResults
+      def store_step_result(context_id, step_name, record, reactor_class_name)
+        key = step_result_key(context_id, step_name, reactor_class_name)
+        # Shares context_ttl with the parent: the record must not outlive what it
+        # belongs to, and must not expire before it either.
+        @redis.set(key, JSON.generate(record), ex: durability_ttl)
+      end
+
+      def retrieve_step_result(context_id, step_name, reactor_class_name)
+        json = @redis.get(step_result_key(context_id, step_name, reactor_class_name))
+        return nil unless json
+
+        JSON.parse(json)
+      end
+
+      # Every record, for StepSweeper — a unit whose job was lost leaves nothing
+      # else behind to find it by, since the parent only parks on the read side.
+      def scan_step_results(count: 1000)
+        records = []
+
+        @redis.scan_each(match: "reactor:*:context:*:step_result:*", count: 100) do |key|
+          json = @redis.get(key)
+          records << JSON.parse(json) if json
+          return records if records.size >= count
+        end
+
+        records
+      end
+
+      private
+
+      def step_result_key(context_id, step_name, reactor_class_name)
+        "reactor:#{reactor_class_name}:context:#{context_id}:step_result:#{step_name}"
+      end
+    end
+  end
+end

data/lib/ruby_reactor/sweeper.rb

@@ -17,6 +17,12 @@ module RubyReactor
   # race) and re-enqueued while its worker is actually alive, the duplicate hits
   # the live lock -> ContextLockContention -> uncapped snooze -> no double run.
   #
+  # `async_reactor` children ARE covered: each runs as its own job, so a lost
+  # job strands one exactly like a top-level reactor, and a fire-and-forget
+  # child has no parent left waiting to notice. They are identified by the
+  # `async_dispatched` marker rather than by absence of a parent, so compose
+  # children — same parent link, but run inline — are never re-enqueued.
+  #
   # Map fan-out (element/collector jobs) is NOT covered here — those contexts
   # carry parent_context_id and scan_reactors filters them out (F6). The map
   # sweeper (Phase 5) owns them.
@@ -41,7 +47,7 @@ module RubyReactor
     def run_once(limit: DEFAULT_LIMIT)
       reenqueued = 0
 
-      @storage.scan_reactors(count: limit).each do |reactor|
+      @storage.scan_reactors(count: limit, include_dispatched_children: true).each do |reactor|
         next unless reactor[:status] == "running" # non-terminal only
         next if @storage.lock_held?("async:#{reactor[:id]}") # worker alive -> leave alone
 

data/lib/ruby_reactor/sweeper_job.rb

@@ -38,6 +38,7 @@ module RubyReactor
     def run_sweeps(config)
       RubyReactor::Sweeper.run_once(limit: config.sweeper_limit)
       RubyReactor::Map::Sweeper.run_once(limit: config.sweeper_limit)
+      RubyReactor::StepSweeper.run_once(limit: config.sweeper_limit)
     rescue StandardError => e
       config.logger.error("RubyReactor sweeper sweep failed: #{e.class}: #{e.message}")
     end

data/lib/ruby_reactor/template/result.rb

@@ -11,15 +11,16 @@ module RubyReactor
         @path = path
       end
 
+      # For an ordinary step this is exactly what it always was: read the
+      # recorded result. The async branch only engages when there is no recorded
+      # result AND the context carries an async reference for this name, so a
+      # synchronous reference costs one extra hash lookup and nothing else.
       def resolve(context)
         value = context.get_result(@step_name)
+        value = resolve_async_reference(context) if value.nil?
         return nil if value.nil?
 
-        if @path
-          extract_path(value, @path)
-        else
-          value
-        end
+        @path ? extract_path(value, @path) : value
       end
 
       def inspect
@@ -30,8 +31,153 @@ module RubyReactor
         end
       end
 
+      # Seconds a WORKER-side reader blocks in-thread before parking. Long
+      # enough that a unit finishing "immediately" (the common case) resolves
+      # without a park round-trip; short enough that a genuinely slow unit
+      # frees the worker thread quickly. Not configurable — the tunable bounds
+      # are `async_wait_timeout` (blocking) and `async_park_timeout` (parked).
+      PARK_GRACE = 5.0
+
       private
 
+      # Block (bounded) until the dispatched unit is terminal,
+      # then inject its outcome.
+      def resolve_async_reference(context)
+        ref = async_reference(context)
+        return nil unless ref
+
+        case fetch(ref, :type).to_s
+        when "async_step_ref" then await_async_step(context, ref)
+        when "async_reactor_ref" then await_async_reactor(context, ref)
+        end
+      end
+
+      def async_reference(context)
+        ref = context.composed_contexts[@step_name] ||
+              context.composed_contexts[@step_name.to_s] ||
+              context.composed_contexts[@step_name.to_sym]
+        ref if ref.is_a?(Hash)
+      end
+
+      # Read semantics: on Success the reader gets the same raw
+      # deserialized value a same-process step would have produced. On Failure it
+      # gets the `Failure` OBJECT — a same-process failure would have halted the
+      # reactor before any reader ran, so there is no sync behavior to mirror,
+      # and handing over the Failure is precisely what lets the reader see it and
+      # decide whether to compensate.
+      def await_async_step(context, ref)
+        reactor_class_name = RubyReactor.reactor_storage_name(context.reactor_class)
+        record = awaited(
+          context, ref,
+          channel: RubyReactor.async_step_channel(context.context_id, @step_name)
+        ) do
+          stored = storage.retrieve_step_result(context.context_id, @step_name, reactor_class_name)
+          stored if stored && fetch(stored, :status).to_s == "completed"
+        end
+
+        value = ContextSerializer.deserialize_value(fetch(record, :result))
+        return value if fetch(record, :success)
+
+        RubyReactor::Failure.new(value)
+      end
+
+      # The child is an ordinary addressable reactor, so "terminal" is just its
+      # own context row reaching a terminal status — no extra storage primitive.
+      # A child PAUSED at an interrupt is deliberately not terminal: the reader
+      # keeps waiting (and may time out) unless the child is resumed.
+      def await_async_reactor(context, ref)
+        execution_id = fetch(ref, :execution_id)
+        reactor_class_name = fetch(ref, :reactor_class_name)
+
+        data = awaited(context, ref, channel: RubyReactor.async_reactor_channel(execution_id)) do
+          stored = storage.retrieve_context(execution_id, reactor_class_name)
+          stored if stored && terminal_status?(stored)
+        end
+
+        child_result(data)
+      end
+
+      # A synchronous caller (a request thread, a rake task) blocks in the
+      # notified wait, bounded tight by `async_wait_timeout` — it has a thread
+      # to spare and a host timeout to stay under. Inside a WORKER the same
+      # read must not pin the thread: after PARK_GRACE it raises
+      # `AsyncResultPending`, the executor keeps its locks held and the job
+      # re-enqueues itself, re-entering this method on redelivery. Total parked
+      # time is bounded by `async_park_timeout` measured from `dispatched_at`.
+      def awaited(context, ref, channel:, &check)
+        return RubyReactor::AsyncWaiter.new(channel: channel, &check).wait unless worker_process?(context)
+
+        begin
+          RubyReactor::AsyncWaiter.new(channel: channel, timeout: PARK_GRACE, &check).wait
+        rescue Error::AsyncWaitTimeoutError
+          raise park_expired_error(channel) if park_deadline_passed?(ref)
+
+          raise Error::AsyncResultPending.new(
+            "async result for '#{@step_name}' still pending on '#{channel}'; parking the caller",
+            channel: channel
+          )
+        end
+      end
+
+      def worker_process?(context)
+        (context.root_context || context).inline_async_execution
+      end
+
+      def park_deadline_passed?(ref)
+        limit = RubyReactor.configuration.async_park_timeout
+        return false if limit == :infinity
+
+        Time.now - park_clock_start(ref) >= limit
+      end
+
+      # `dispatched_at` round-trips through serialization, so it may come back
+      # as a string; an unparseable/missing stamp starts the clock at the first
+      # park rather than waiving the bound.
+      def park_clock_start(ref)
+        raw = fetch(ref, :dispatched_at)
+        return raw if raw.is_a?(Time)
+
+        begin
+          Time.parse(raw.to_s)
+        rescue ArgumentError, TypeError
+          ref[:dispatched_at] = Time.now
+        end
+      end
+
+      def park_expired_error(channel)
+        Error::AsyncWaitTimeoutError.new(
+          "Parked wait for '#{@step_name}' on '#{channel}' exceeded " \
+          "`RubyReactor.configuration.async_park_timeout` " \
+          "(#{RubyReactor.configuration.async_park_timeout}s since dispatch) without the unit " \
+          "reaching a terminal state — check that a worker is consuming the queue, or raise the " \
+          "timeout if this unit is legitimately slower."
+        )
+      end
+
+      def terminal_status?(data)
+        %w[completed failed cancelled skipped].include?(fetch(data, :status).to_s)
+      end
+
+      # The child's real Success/Failure, never the enqueue-time DispatchResult —
+      # the reader is supposed to inspect `.success?` / `.value` / `.error`.
+      def child_result(data)
+        context = RubyReactor::Context.deserialize_from_retry(data)
+        return context.failure_reason if context.failure_reason.is_a?(RubyReactor::Failure)
+        return RubyReactor::Failure.new(context.failure_reason || "child reactor failed") if context.failed?
+
+        return_step = context.reactor_class.respond_to?(:return_step) ? context.reactor_class.return_step : nil
+        RubyReactor::Success.new(return_step ? context.get_result(return_step) : nil)
+      end
+
+      def storage
+        RubyReactor.configuration.storage_adapter
+      end
+
+      # Records round-trip through JSON, so a key may come back as a string.
+      def fetch(hash, key)
+        hash[key] || hash[key.to_s]
+      end
+
       def extract_path(value, path)
         if path.is_a?(Symbol) && value.respond_to?(:[])
           value[path]

data/lib/ruby_reactor/version.rb

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