ruby_reactor 0.8.3 → 0.8.5

data/lib/ruby_reactor/step.rb

@@ -5,13 +5,14 @@ module RubyReactor
   #
   #   class MyStep < RubyReactor::Step
   #     input :amount, :integer
-  #     def run = Success(charged: inputs[:amount])
+  #     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.
+  #    applied. `run`, `undo`, and `compensate` all see the same values,
+  #    through a read-only `Step::Inputs` (`inputs.amount`).
   # 2. `.run` ONLY: enforce the declared input contract, raising
   #    `Error::InputValidationError` before any instance exists.
   # 2b. `.run` ONLY: step-scoped coordination (`with_lock` etc, if declared)
@@ -30,17 +31,20 @@ module RubyReactor
   #    throw (`success!`/`skip!`/`fail!`/`halt!`) into its result wrapper.
   #
   # No `prepend`/`define_method`/`method_missing` — every step in the class
-  # reads top to bottom as ordinary method calls. The one `extend` is
-  # `Dsl::Lockable::ClassMethods` (the five coordination macros), a
-  # self-contained module with no hooks of its own (Finding 9).
+  # reads top to bottom as ordinary method calls. The two `extend`s are
+  # `Dsl::Lockable::ClassMethods` (the five coordination macros) and
+  # `Dsl::Retryable` (`retries`), self-contained modules whose only hook is
+  # an `inherited` that copies their declarations down (Finding 9).
   class Step
     include RubyReactor::StepSignals
     extend RubyReactor::Dsl::Lockable::ClassMethods
+    extend RubyReactor::Dsl::Retryable
 
     attr_reader :inputs, :context, :result, :reason
 
     def initialize(inputs, context, result: nil, reason: nil)
-      @inputs = inputs
+      contract = self.class.input_contract if self.class.declares_inputs?
+      @inputs = Inputs.new(inputs, contract: contract, owner: self.class.name || self.class.inspect)
       @context = context
       @result = result
       @reason = reason
@@ -109,6 +113,13 @@ module RubyReactor
         catch(StepSignals::TAG) { new(with_defaults(arguments), context, reason: reason).compensate }
       end
 
+      # Whether `undo` also reverts a run cut short by an interruption. A
+      # plain step's body stopped mid-way, so no: only a construct whose undo
+      # replays the child work it completed (compose, map) says yes (008 R-16).
+      def undoes_partial_run?
+        false
+      end
+
       def input(...)
         own_input_contract.input(...)
         @input_contract = nil
@@ -163,11 +174,13 @@ module RubyReactor
         @own_input_contract ||= Step::InputContract.new(owner: self)
       end
 
+      # `to_h`: a step body may hand its own `Inputs` on (`OtherStep.run(inputs, context)`).
       def with_defaults(arguments)
-        input_contract.apply_defaults(arguments)
+        input_contract.apply_defaults(arguments.to_h)
       end
 
       def enforce_contract!(arguments)
+        arguments = arguments.to_h
         return arguments unless declares_inputs?
 
         input_contract.enforce!(arguments)

data/lib/ruby_reactor/step_worker.rb

@@ -88,7 +88,13 @@ module RubyReactor
       log(:error, "failed", error: "#{e.class}: #{e.message}")
       complete(RubyReactor.Failure(e, step_name: @step_name, reactor_name: @reactor_class_name, retryable: false),
                context)
-    rescue StandardError => e
+    # Arguments raised: the body never started, so it is neither retried nor
+    # compensated (008 R-06).
+    rescue Error::ArgumentResolutionError => e
+      log(:error, "failed", error: "#{e.class}: #{e.message}")
+      complete(RubyReactor.Failure(e, step_name: @step_name, reactor_name: @reactor_class_name, retryable: false,
+                                      exception_class: e.exception_class), context)
+    rescue Error::Rescuable => e
       # The unit's failure belongs in its record, where a reader can see it.
       # Raising instead would hand the job to the backend's retry machinery to
       # fail identically N more times while every reader waits out its timeout.
@@ -238,17 +244,7 @@ module RubyReactor
     end
 
     def run_step(context, step_config)
-      # A suppressed step never coordinates (FR-012) — decided before the
-      # arguments are validated or any hold is taken, exactly as
-      # `StepExecutor#execute_step_sync` orders it. `complete` persists the
-      # nil result, so the reader sees the same skipped unit a same-process
-      # step would produce.
-      unless step_config.should_run?(context)
-        log(:info, "skipped")
-        return RubyReactor.Success(nil)
-      end
-
-      arguments = resolve_arguments(step_config, context)
+      arguments = step_config.resolve_arguments(context)
       # Reactor-side `argument`/`validate_args` rules gate the step BEFORE its
       # coordination is acquired, exactly as `StepExecutor#execute_step_sync`
       # orders them — an async_step must not take a lock (or spend a rate-limit
@@ -289,9 +285,43 @@ module RubyReactor
         end
       end
 
+      compensate_unit(context, step_config, result, arguments)
       result
     end
 
+    # 008 R-09: the unit compensates ITSELF, once, here in its own job, after
+    # its final attempt failed — whether or not any step ever reads it, the
+    # way an `async_reactor` child rolls itself back. Never for a success,
+    # skip or halt, and never for a body that never started (invalid
+    # arguments), exactly the executor's rule. Same coordination re-take,
+    # middleware events and failure recording as an in-process compensate.
+    # The outcome goes on this unit's record (`complete`); the parent's
+    # context is never written here (single writer), so the in-memory trace
+    # entry the compensate appends stays local to this job.
+    def compensate_unit(context, step_config, result, arguments)
+      return unless result.is_a?(RubyReactor::Failure) && body_started?(result.error)
+
+      manager = Executor::CompensationManager.new(context)
+      outcome = manager.compensate(step_config, result.error, arguments)
+      @compensation = {
+        "status" => compensation_status(outcome),
+        "rollback_failures" => ContextSerializer.serialize_value(manager.rollback_failures),
+        "completed_at" => Time.now.iso8601
+      }
+    end
+
+    def body_started?(error)
+      return false if error.is_a?(Error::InputValidationError)
+
+      Executor::CompensationManager::NEVER_STARTED_ERROR_CLASSES.none? { |klass| error.is_a?(klass) }
+    end
+
+    def compensation_status(outcome)
+      return "failed" if outcome.is_a?(RubyReactor::Failure)
+
+      outcome.respond_to?(:skipped?) && outcome.skipped? ? "skipped" : "completed"
+    end
+
     # Same check and same structured, non-retryable shape `StepExecutor`
     # produces — the same arguments fail the same rules on every attempt.
     def validate_arguments(step_config, arguments)
@@ -330,7 +360,7 @@ module RubyReactor
                              retryable: false)
     rescue Executor::StepCoordination::Contended, Executor::StepCoordination::KeyError
       raise
-    rescue StandardError => e
+    rescue Error::Rescuable => e
       RubyReactor.Failure(e, step_name: @step_name, reactor_name: @reactor_class_name)
     end
 
@@ -356,14 +386,6 @@ module RubyReactor
       RubyReactor.Success(result)
     end
 
-    def resolve_arguments(step_config, context)
-      step_config.arguments.to_h do |arg_name, arg_config|
-        value = arg_config[:source].resolve(context)
-        value = arg_config[:transform].call(value) if arg_config[:transform]
-        [arg_name, value]
-      end
-    end
-
     # Write first, publish second. The record is the answer; the signal only
     # saves the reader a fallback interval.
     def complete(result, context)
@@ -394,8 +416,10 @@ module RubyReactor
 
     # This delivery's run, once the body was reached: `started_at`,
     # `arguments` (redacted, serialized) and `attempts`. Empty before that.
+    # Plus `compensation` when the unit compensated itself.
     def run_fields
-      @run || {}
+      fields = @run || {}
+      @compensation ? fields.merge("compensation" => @compensation) : fields
     end
 
     def record_missing_parent

data/lib/ruby_reactor/storage/adapter.rb

@@ -56,6 +56,10 @@ module RubyReactor
         raise NotImplementedError
       end
 
+      def decrement_map_counter_by(map_id, amount, reactor_class_name)
+        raise NotImplementedError
+      end
+
       def subscribe(channel, &block)
         raise NotImplementedError
       end

data/lib/ruby_reactor/storage/redis_adapter.rb

@@ -133,6 +133,15 @@ module RubyReactor
         @redis.decr(key)
       end
 
+      # Settles `amount` indices at once (a fail-fast dispatcher claiming the
+      # ones it never dispatched). Returns the count left.
+      def decrement_map_counter_by(map_id, amount, reactor_class_name)
+        key = map_counter_key(map_id, reactor_class_name)
+        left = @redis.decrby(key, amount)
+        @redis.expire(key, durability_ttl)
+        left
+      end
+
       def set_last_queued_index(map_id, index, reactor_class_name)
         key = map_last_queued_index_key(map_id, reactor_class_name)
         @redis.set(key, index, ex: durability_ttl)

data/lib/ruby_reactor/storage/redis_reactor_scan.rb

@@ -67,7 +67,7 @@ module RubyReactor
 
       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 status if %w[failed paused completed running halted pending aborted].include?(status)
         return "cancelled" if data["cancelled"]
         # Heuristic
         return "failed" if data["retry_count"]&.positive? && !data["current_step"].nil?

data/lib/ruby_reactor/version.rb

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

data/lib/ruby_reactor/web/api.rb

@@ -173,7 +173,7 @@ module RubyReactor
 
       def self.reactor_status(data)
         status = data[:status].to_s == "skipped" ? "halted" : data[:status].to_s
-        return status if %w[failed paused completed running halted pending].include?(status)
+        return status if %w[failed paused completed running halted pending aborted].include?(status)
         return "cancelled" if data[:cancelled]
         return "running" if data[:current_step]
         return "completed" if execution_evidence?(data)