ruby_reactor 0.7.0 → 0.8.0

data/lib/ruby_reactor/step.rb

@@ -1,36 +1,137 @@
 # frozen_string_literal: true
 
 module RubyReactor
-  module Step
-    def self.included(base)
-      base.extend(ClassMethods)
+  # The single inheritable base every class-based step derives from:
+  #
+  #   class MyStep < RubyReactor::Step
+  #     input :amount, :integer
+  #     def run = Success(charged: inputs[:amount])
+  #   end
+  #
+  # Lifecycle of every class-level call (`.run`/`.call`, `.undo`, `.compensate`):
+  #
+  # 1. Resolve `inputs`: the given arguments with the contract's defaults
+  #    applied. `run`, `undo`, and `compensate` all see the same values.
+  # 2. `.run` ONLY: enforce the declared input contract, raising
+  #    `Error::InputValidationError` before any instance exists. `.undo` and
+  #    `.compensate` NEVER enforce it: rollback must not fail on the very
+  #    inputs that may have caused the failure.
+  # 3. Build a FRESH instance, never reused across actions. An ivar set in
+  #    `run` is gone by the time `undo` runs on its own instance, so async
+  #    execution running `run` and `undo` in different processes behaves
+  #    identically to running both in one.
+  # 4. Invoke the matching instance method, translating any `StepSignals`
+  #    throw (`success!`/`skip!`/`fail!`/`halt!`) into its result wrapper.
+  #
+  # No `prepend`/`extend`/`define_method`/`method_missing` — every step in the
+  # class reads top to bottom as ordinary method calls.
+  class Step
+    include RubyReactor::StepSignals
+
+    attr_reader :inputs, :context, :result, :reason
+
+    def initialize(inputs, context, result: nil, reason: nil)
+      @inputs = inputs
+      @context = context
+      @result = result
+      @reason = reason
+    end
+
+    def run
+      raise NotImplementedError, "#{self.class} must implement #run"
+    end
+
+    def undo
+      RubyReactor.Skipped()
+    end
+
+    def compensate
+      RubyReactor.Skipped()
+    end
+
+    # rubocop:disable Naming/MethodName
+    def Success(value = nil)
+      RubyReactor.Success(value)
+    end
+
+    def Failure(...)
+      RubyReactor.Failure(...)
+    end
+
+    def Halt(reason: nil, **kwargs)
+      RubyReactor.Halt(reason: reason, **kwargs)
+    end
+
+    def Skipped(...)
+      RubyReactor.Skipped(...)
     end
+    # rubocop:enable Naming/MethodName
 
-    module ClassMethods
-      # rubocop:disable Naming/MethodName
-      def Success(value = nil)
-        RubyReactor::Success(value)
+    class << self
+      def run(arguments, context)
+        validated = enforce_contract!(arguments)
+        catch(StepSignals::TAG) { new(validated, context).run }
       end
+      alias call run
 
-      def Failure(error = nil)
-        RubyReactor::Failure(error)
+      # Same `inputs` as `.run` (defaults applied), but NEVER enforces the contract.
+      def undo(result, arguments, context)
+        catch(StepSignals::TAG) { new(with_defaults(arguments), context, result: result).undo }
       end
 
-      def Skipped(reason: nil, **kwargs)
-        RubyReactor.Skipped(reason: reason, **kwargs)
+      # Same `inputs` as `.run` (defaults applied), but NEVER enforces the contract.
+      def compensate(reason, arguments, context)
+        catch(StepSignals::TAG) { new(with_defaults(arguments), context, reason: reason).compensate }
       end
-      # rubocop:enable Naming/MethodName
 
-      def run(arguments, context)
-        raise NotImplementedError, "#{self} must implement .run method"
+      def input(...)
+        own_input_contract.input(...)
+        @input_contract = nil
+      end
+
+      def validate_inputs(...)
+        own_input_contract.validate_inputs(...)
+        @input_contract = nil
+      end
+
+      def input_contract
+        @input_contract ||=
+          if superclass.respond_to?(:declares_inputs?) && superclass.declares_inputs?
+            superclass.input_contract.merge(own_input_contract)
+          else
+            own_input_contract
+          end
+      end
+
+      def declared_inputs
+        input_contract.declarations
       end
 
-      def compensate(_reason, _arguments, _context)
-        RubyReactor.Success() # Default: accept failure and continue rollback
+      def required_input_names
+        input_contract.required_names
       end
 
-      def undo(_result, _arguments, _context)
-        RubyReactor.Success() # Default: no-op undo
+      def declares_inputs?
+        !input_contract.empty?
+      end
+
+      private
+
+      def own_input_contract
+        @own_input_contract ||= Step::InputContract.new(owner: self)
+      end
+
+      def with_defaults(arguments)
+        input_contract.apply_defaults(arguments)
+      end
+
+      def enforce_contract!(arguments)
+        return arguments unless declares_inputs?
+
+        input_contract.enforce!(arguments)
+      rescue Error::InputValidationError => e
+        e.step_name = name
+        raise
       end
     end
   end

data/lib/ruby_reactor/step_signals.rb

@@ -0,0 +1,37 @@
+# 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. For a class-based step, the catching
+  # `catch(StepSignals::TAG)` lives on RubyReactor::Step's own class-level
+  # `run`/`undo`/`compensate` (so every caller — the executor, the async
+  # worker, a direct call — gets identical translation for free); for an
+  # inline `run_block`/`compensate_block`/`undo_block` step, it lives at the
+  # invocation site in 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/step_worker.rb

@@ -56,6 +56,9 @@ module RubyReactor
       context = load_step_context
       return record_missing_parent unless context
 
+      # A fresh worker process has never run the reactor, so the inferred
+      # wiring for name-resolved inputs does not exist here yet.
+      context.reactor_class&.validate_definition!
       step_config = context.reactor_class&.steps&.[](@step_name)
       return record_missing_step unless step_config
 
@@ -113,6 +116,7 @@ module RubyReactor
       result =
         if step_config.has_run_block?
           args = arguments.empty? ? context.inputs : arguments
+          args = step_config.inline_contract.enforce!(args) if step_config.inline_contract
           step_config.run_block.call(args, context)
         elsif step_config.has_impl?
           step_config.impl.run(arguments, context)
@@ -121,6 +125,12 @@ module RubyReactor
         end
 
       normalize(result)
+    rescue Error::InputValidationError => e
+      # Same shape the executor builds, and never retried: the same arguments
+      # fail the same contract on every attempt.
+      RubyReactor.Failure(e, validation_errors: e.field_errors, step_name: @step_name,
+                             step_arguments: e.step_arguments || {}, reactor_name: @reactor_class_name,
+                             retryable: false)
     rescue StandardError => e
       RubyReactor.Failure(e, step_name: @step_name, reactor_name: @reactor_class_name)
     end
@@ -158,16 +168,21 @@ module RubyReactor
     # Write first, publish second. The record is the answer; the signal only
     # saves the reader a fallback interval.
     def complete(result, context)
-      storage.store_step_result(
-        @step_context_id, @step_name,
-        {
-          "status" => "completed",
-          "success" => result.success?,
-          "result" => ContextSerializer.serialize_value(result.success? ? result.value : result.to_h),
-          "completed_at" => Time.now.iso8601
-        },
-        @reactor_class_name
-      )
+      record = {
+        "status" => "completed",
+        "success" => result.success?,
+        "result" => ContextSerializer.serialize_value(result.success? ? result.value : result.to_h),
+        "completed_at" => Time.now.iso8601
+      }
+      # A `halt!` reports success? == true but carries no value, so without
+      # this the reader cannot tell it from an ordinary success returning nil.
+      # `skip!` needs nothing extra: Skipped keeps its value, and the reader is
+      # meant to see that value exactly as a same-process step would.
+      if result.is_a?(RubyReactor::Halt)
+        record["signal"] = "halt"
+        record["reason"] = result.reason
+      end
+      storage.store_step_result(@step_context_id, @step_name, record, @reactor_class_name)
       log(result.success? ? :info : :warn, result.success? ? "completed" : "completed_with_failure")
       storage.publish(RubyReactor.async_step_channel(@step_context_id, @step_name), "done")
       result

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/template/result.rb

@@ -76,7 +76,14 @@ module RubyReactor
         end
 
         value = ContextSerializer.deserialize_value(fetch(record, :result))
-        return value if fetch(record, :success)
+        if fetch(record, :success)
+          # Same rule as Failure below: a halt has no same-process equivalent
+          # for a reader to mirror, so hand over the signal itself.
+          return RubyReactor.Halt(reason: fetch(record, :reason), step_name: @step_name) if
+            fetch(record, :signal).to_s == "halt"
+
+          return value
+        end
 
         RubyReactor::Failure.new(value)
       end
@@ -175,7 +182,7 @@ module RubyReactor
 
       # Records round-trip through JSON, so a key may come back as a string.
       def fetch(hash, key)
-        hash[key] || hash[key.to_s]
+        Utils::FetchIndifferent.call(hash, key)
       end
 
       def extract_path(value, path)

data/lib/ruby_reactor/utils/fetch_indifferent.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module RubyReactor
+  module Utils
+    # Presence-aware symbol/string lookup: a supplied `false` is returned as
+    # `false`, never swallowed by an `a || b` fallback into `nil`.
+    class FetchIndifferent
+      def self.call(hash, key)
+        hash.key?(key.to_sym) ? hash[key.to_sym] : hash[key.to_s]
+      end
+    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.8.0"
 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