ruby_reactor 0.7.0 → 0.7.1

data/lib/ruby_reactor/rspec/matchers.rb

@@ -264,18 +264,18 @@ module RubyReactor
         RubyReactor.configuration.storage_adapter
       end
 
-      # Distinguishes `RubyReactor::Skipped` from a plain `Success`. Works on
-      # any object with a `skipped?` predicate.
+      # Distinguishes `RubyReactor::Halt` (a clean halt) from a plain
+      # `Success`. Works on any object with a `halted?` 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
+      #   expect(result).to be_halted
+      #   expect(result).to be_halted.because(:period)
+      #   expect(result).to be_halted.at_step(:second)
+      ::RSpec::Matchers.define :be_halted 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 unless actual.respond_to?(:halted?) && actual.halted?
           next false if @expected_reason && actual.reason != @expected_reason
           next false if @expected_step && actual.step_name != @expected_step
 
@@ -292,12 +292,62 @@ module RubyReactor
 
         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}"
+          if !actual.respond_to?(:halted?) || !actual.halted?
+            "expected result to be Halt, got #{actual.class}"
           elsif @expected_reason && actual.reason != @expected_reason
-            "expected Skipped reason #{@expected_reason.inspect}, got #{actual.reason.inspect}"
+            "expected Halt reason #{@expected_reason.inspect}, got #{actual.reason.inspect}"
           else
-            "expected Skipped at_step #{@expected_step.inspect}, got #{actual.step_name.inspect}"
+            "expected Halt at_step #{@expected_step.inspect}, got #{actual.step_name.inspect}"
+          end
+        end
+
+        failure_message_when_negated do
+          "expected result not to be Halt"
+        end
+      end
+
+      # Asserts that a STEP was skipped — either the subject itself is a
+      # `RubyReactor::Skipped` result, or the execution trace records a
+      # `:skipped` entry (optionally for a specific step via `.at_step`). A
+      # halted run never satisfies this — halting and skipping are distinct.
+      #
+      # Examples:
+      #   expect(result).to be_skipped
+      #   expect(subject).to be_skipped.at_step(:maybe_sync)
+      ::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 if actual.respond_to?(:halted?) && actual.halted?
+
+          entries = skipped_trace_entries(subject)
+          next entries.any? { |e| e[:step].to_s == @expected_step.to_s } if @expected_step
+          next true if entries.any?
+
+          actual.respond_to?(:skipped?) && actual.skipped?
+        end
+
+        chain :at_step do |step|
+          @expected_step = step
+        end
+
+        def skipped_trace_entries(subject)
+          trace = if subject.respond_to?(:reactor_instance)
+                    subject.reactor_instance.context.execution_trace
+                  elsif subject.respond_to?(:execution_trace)
+                    subject.execution_trace
+                  else
+                    []
+                  end
+          trace.select { |e| e[:type].to_s == "skipped" }
+        end
+
+        failure_message do |subject|
+          actual = subject.respond_to?(:result) ? subject.result : subject
+          if @expected_step
+            "expected a skipped step named #{@expected_step.inspect}, found none in the execution trace"
+          else
+            "expected result to be Skipped, got #{actual.class}"
           end
         end
 

data/lib/ruby_reactor/rspec/test_subject.rb

@@ -300,8 +300,8 @@ module RubyReactor
                   end
                 end
           RubyReactor::Success.new(val)
-        when "skipped"
-          skipped_result(ctx)
+        when "halted", "skipped" # "skipped" is the legacy name for a halt
+          halted_result(ctx)
         when "running"
           # Try to determine if it is truly running or if we just missed the completion
           if @process_jobs && AsyncTestHelpers.active?
@@ -326,14 +326,14 @@ module RubyReactor
       end
 
       # A clean halt: either a `with_period` gate or a step returning
-      # `RubyReactor.Skipped(...)`. The sync run already produced the exact
-      # Skipped (reason/step intact) — surface it. For async runs the worker
+      # `RubyReactor.Halt(...)`. The sync run already produced the exact
+      # Halt (reason/step intact) — surface it. For async runs the worker
       # swallows the return value, so rebuild from the trace.
-      def skipped_result(ctx)
-        return @run_result if @run_result.is_a?(RubyReactor::Skipped)
+      def halted_result(ctx)
+        return @run_result if @run_result.is_a?(RubyReactor::Halt)
 
-        entry = ctx.execution_trace.reverse.find { |t| t[:type].to_s == "skipped" }
-        RubyReactor::Skipped.new(reason: entry&.dig(:reason), step_name: entry&.dig(:step))
+        entry = ctx.execution_trace.reverse.find { |t| t[:type].to_s == "halt" }
+        RubyReactor::Halt.new(reason: entry&.dig(:reason), step_name: entry&.dig(:step))
       end
 
       def success?

data/lib/ruby_reactor/step/map_step.rb

@@ -64,7 +64,7 @@ module RubyReactor
 
         def run_inline(arguments, context)
           results = execute_inline_map(arguments, context)
-          return results if results.is_a?(RubyReactor::Failure)
+          return results if results.is_a?(RubyReactor::Failure) || results.is_a?(RubyReactor::Halt)
 
           process_results(results, arguments[:collect_block], arguments[:fail_fast])
         end
@@ -76,6 +76,10 @@ module RubyReactor
           arguments[:source].each do |element|
             result = execute_single_element(element, arguments, context)
 
+            # An element-level Halt propagates as a run halt: stop immediately
+            # rather than being collected as a (nil) value.
+            return result if result.is_a?(RubyReactor::Halt)
+
             if fail_fast && result.failure?
               return result # Stop immediately on first failure
             end

data/lib/ruby_reactor/step.rb

@@ -7,6 +7,8 @@ module RubyReactor
     end
 
     module ClassMethods
+      include RubyReactor::StepSignals
+
       # rubocop:disable Naming/MethodName
       def Success(value = nil)
         RubyReactor::Success(value)
@@ -16,8 +18,12 @@ module RubyReactor
         RubyReactor::Failure(error)
       end
 
-      def Skipped(reason: nil, **kwargs)
-        RubyReactor.Skipped(reason: reason, **kwargs)
+      def Halt(reason: nil, **kwargs)
+        RubyReactor.Halt(reason: reason, **kwargs)
+      end
+
+      def Skipped(...)
+        RubyReactor.Skipped(...)
       end
       # rubocop:enable Naming/MethodName
 
@@ -26,11 +32,11 @@ module RubyReactor
       end
 
       def compensate(_reason, _arguments, _context)
-        RubyReactor.Success() # Default: accept failure and continue rollback
+        RubyReactor.Skipped() # Default: nothing defined, rollback continues
       end
 
       def undo(_result, _arguments, _context)
-        RubyReactor.Success() # Default: no-op undo
+        RubyReactor.Skipped() # Default: nothing defined, rollback continues
       end
     end
   end

data/lib/ruby_reactor/step_signals.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module RubyReactor
+  # `success!` / `skip!` / `fail!` / `halt!` — end a step body immediately
+  # with the matching signal, from any call depth. Mixed into both authoring
+  # surfaces (class steps and inline `run` blocks) so the helpers behave
+  # identically in either style (contracts/step-helpers.md).
+  #
+  # Implemented as throw/catch rather than an exception: a `throw` passes
+  # straight through `rescue Exception` while `ensure` blocks still run
+  # (verified in research.md R2), so a step's own broad rescue cannot swallow
+  # the author's intended outcome. The catching `catch(StepSignals::TAG)` lives
+  # at each step-body invocation site (step_executor.rb, compensation_manager.rb).
+  module StepSignals
+    TAG = :ruby_reactor_step_signal
+
+    def success!(value = nil)
+      throw TAG, RubyReactor.Success(value)
+    end
+
+    def skip!(...)
+      throw TAG, RubyReactor.Skipped(...)
+    end
+
+    def fail!(error, **opts)
+      throw TAG, RubyReactor.Failure(error, **opts)
+    end
+
+    def halt!(reason: nil, **kwargs)
+      throw TAG, RubyReactor.Halt(reason: reason, **kwargs)
+    end
+  end
+end

data/lib/ruby_reactor/storage/adapter.rb

@@ -88,6 +88,10 @@ module RubyReactor
         raise NotImplementedError
       end
 
+      def scan_reactors_page(pattern: "*", cursor: "0", count: 50, include_dispatched_children: false)
+        raise NotImplementedError
+      end
+
       def find_context_by_id(context_id)
         raise NotImplementedError
       end

data/lib/ruby_reactor/storage/redis_adapter.rb

@@ -10,6 +10,7 @@ module RubyReactor
       include RedisOrderedLocking
       include RedisStepResults
       include RedisPubSub
+      include RedisReactorScan
 
       def initialize(redis_config)
         super()
@@ -181,33 +182,6 @@ module RubyReactor
         @redis.expire(key, seconds)
       end
 
-      # New methods for API
-      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
-
       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}"
@@ -225,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)
@@ -315,34 +272,6 @@ module RubyReactor
         RubyReactor.configuration.context_ttl
       end
 
-      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")
-
       def context_key(context_id, reactor_class_name)
         "reactor:#{reactor_class_name}:context:#{context_id}"
       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/version.rb

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

data/lib/ruby_reactor/web/api.rb

@@ -5,7 +5,7 @@ require_relative "coordination_serializer"
 
 module RubyReactor
   module Web
-    # rubocop:disable Metrics/BlockLength
+    # rubocop:disable Metrics/BlockLength, Metrics/ClassLength
     class API < Roda
       plugin :json
       plugin :all_verbs
@@ -13,9 +13,19 @@ module RubyReactor
       route do |r|
         r.on "reactors" do
           r.is do
-            # GET /api/reactors
+            # GET /api/reactors?limit=N&cursor=C (default limit 50, capped at 500).
+            # Body stays a bare array (existing clients keep working unchanged);
+            # the next page's cursor rides in the X-Next-Cursor header ("0" means
+            # there is no next page). A client that wants every reactor pages
+            # through by re-requesting with ?cursor=<X-Next-Cursor> until it gets "0".
             r.get do
-              RubyReactor::Configuration.instance.storage_adapter.scan_reactors
+              limit = self.class.scan_limit(r.params["limit"])
+              cursor = r.params["cursor"] || "0"
+
+              adapter = RubyReactor::Configuration.instance.storage_adapter
+              page = adapter.scan_reactors_page(cursor: cursor, count: limit)
+              response.headers["X-Next-Cursor"] = page[:cursor]
+              page[:reactors]
             rescue StandardError => e
               response.status = 500
               { error: e.message, backtrace: e.backtrace.first(5) }
@@ -150,9 +160,16 @@ module RubyReactor
         end
       end
 
+      def self.scan_limit(raw)
+        limit = raw.to_i
+        return 50 unless limit.positive?
+
+        [limit, 500].min
+      end
+
       def self.reactor_status(data)
-        status = data[:status].to_s
-        return status if %w[failed paused completed running skipped pending].include?(status)
+        status = data[:status].to_s == "skipped" ? "halted" : data[:status].to_s
+        return status if %w[failed paused completed running halted pending].include?(status)
         return "cancelled" if data[:cancelled]
         return "running" if data[:current_step]
         return "completed" if execution_evidence?(data)
@@ -347,6 +364,6 @@ module RubyReactor
         }
       end
     end
-    # rubocop:enable Metrics/BlockLength
+    # rubocop:enable Metrics/BlockLength, Metrics/ClassLength
   end
 end