ruby_reactor 0.8.4 → 0.8.5

data/lib/ruby_reactor/step/map_step.rb

@@ -3,6 +3,11 @@
 module RubyReactor
   class Step
     class MapStep < RubyReactor::Step
+      # Seconds a rollback waits for an element's liveness lock. The last
+      # element to settle triggers the collector before its own job releases
+      # that lock, so a short wait covers the gap.
+      ELEMENT_LOCK_WAIT = 2
+
       # Untyped, so no validation: declared only so `inputs.x` can read them.
       input :source
       input :mapped_reactor_class
@@ -26,11 +31,37 @@ module RubyReactor
         end
       end
 
+      # Compensating a failed map and undoing a completed one are the same work,
+      # as for compose: replay the undo stack of every element that COMPLETED
+      # (a failed element already rolled itself back; a halted or skipped one
+      # did nothing to undo), highest index first. Elements are found through
+      # the index both modes write, so nothing per element lives in the parent
+      # (008 R-02). Runs only once every element has settled (R-04), from the
+      # execution that owns the map, so it is the elements' only writer.
+      #
+      # ponytail: serial, in the process that detected the failure, so rollback
+      # time is linear in the number of completed elements. Fan the rollback
+      # out per element if that ever outgrows one job.
       def compensate
-        # TODO: Implement compensation for map steps
-        RubyReactor.Success()
+        step_name = context.current_step
+        map_id = "#{context.context_id}:#{step_name}"
+        failures = []
+
+        completed_elements(map_id, failures).each do |index, element_context|
+          tag = { map_step: step_name.to_sym, element_index: index }
+          failures.concat(rollback_element(map_id, index, element_context).map { |entry| entry.merge(tag) })
+        end
+
+        return RubyReactor.Success() if failures.empty?
+
+        RubyReactor.Failure("map :#{step_name} rollback incomplete", rollback_failures: failures)
       end
 
+      alias undo compensate
+
+      # An interrupted run is undone too: undo replays only each element's completed steps.
+      def self.undoes_partial_run? = true
+
       class << self
         def build_mapped_inputs(mappings, context, element)
           built = {}
@@ -79,6 +110,79 @@ module RubyReactor
 
       private
 
+      # Read from the map step's static declaration, not from the undo record,
+      # which a fan-out map leaves empty (R-03).
+      def element_class
+        context.reactor_class.steps[context.current_step].arguments[:mapped_reactor_class][:source].value
+      end
+
+      # `[[index, context], ...]` for every completed element, highest index
+      # first. An element whose row is gone (expired past `context_ttl`) is
+      # reported, never skipped silently.
+      def completed_elements(map_id, failures)
+        storage = RubyReactor.configuration.storage_adapter
+        storage_name = RubyReactor.reactor_storage_name(element_class)
+        # A parked or retried fan-out element registers its id again.
+        ids = storage.retrieve_map_element_context_ids(map_id, context.reactor_class.name).uniq
+        rows = ids.map { |id| storage.retrieve_context(id, storage_name) }
+        elements = rows.compact.map do |data|
+          element_context = RubyReactor::Context.deserialize_from_retry(data)
+          [Utils::FetchIndifferent.call(element_context.map_metadata || {}, :index).to_i, element_context]
+        end
+
+        report_unavailable(elements.map(&:first), rows.count(nil), failures)
+        # An `aborted` element (an inline run interrupted in it) kept the undo
+        # entries of the steps it completed.
+        elements.select { |_, element| %w[completed aborted].include?(element.status.to_s) }
+                .sort_by { |index, _| -index }
+      end
+
+      # The parent's map reference (in its own blob, so it lives as long as
+      # the parent) counts the elements that started: set per element inline,
+      # and to the total when a fan-out map completes. With it, every started
+      # index without a row is named, even when the index list itself expired;
+      # without it (a failed fan-out map skipped some indices), one unnamed
+      # entry per indexed row that is gone.
+      def report_unavailable(found_indexes, missing_rows, failures)
+        ref = Utils::FetchIndifferent.call(context.composed_contexts, context.current_step)
+        started = ref && Utils::FetchIndifferent.call(ref, :started)
+        missing = started ? (0...started).to_a - found_indexes : [nil] * missing_rows
+        missing.each { |index| failures << rollback_entry(index, :context_unavailable, "context expired") }
+      end
+
+      def rollback_entry(index, reason, message)
+        step_name = context.current_step.to_sym
+        { step: step_name, kind: :undo, key: nil, reason: reason, map_step: step_name, element_index: index,
+          message: "map element #{index} #{message}" }
+      end
+
+      # The element's own undo stack, replayed as `ComposeStep` replays its
+      # child's, under the element's liveness lock: a held lock after the map
+      # settled is a live duplicate delivery, which is left alone and reported.
+      def rollback_element(map_id, index, element_context)
+        lock = acquire_element_lock(map_id, index)
+        return [rollback_entry(index, :element_in_flight, "was still running at rollback time")] if lock == :held
+
+        executor = RubyReactor::Executor.new(element_class, {}, element_context)
+        executor.undo_all
+        executor.save_context
+        executor.compensation_manager.rollback_failures
+      ensure
+        lock.release if lock.respond_to?(:release)
+      end
+
+      def acquire_element_lock(map_id, index)
+        return nil if RubyReactor::Map::ElementExecutor.inline_testing_mode?
+
+        config = RubyReactor.configuration
+        lock = RubyReactor::Lock.new("map_element:#{map_id}:#{index}",
+                                     owner: SecureRandom.uuid, ttl: config.context_lock_ttl, wait: ELEMENT_LOCK_WAIT)
+        lock.acquire
+        lock
+      rescue RubyReactor::Lock::AcquisitionError
+        :held
+      end
+
       # Fans out anywhere except inside a map element: an element's result and
       # the map's completion counter are tracked by its own ElementExecutor job,
       # so a nested hand-off there would escape that tracking. A reactor worker
@@ -141,7 +245,8 @@ module RubyReactor
           name: context.current_step,
           type: :map_ref,
           map_id: map_id,
-          element_reactor_class: inputs.mapped_reactor_class.name
+          element_reactor_class: inputs.mapped_reactor_class.name,
+          started: index + 1
         }
 
         executor = RubyReactor::Executor.new(inputs.mapped_reactor_class, {}, child_context)
@@ -160,7 +265,7 @@ module RubyReactor
           begin
             # Collect block receives Result objects when fail_fast is false, values when true
             return RubyReactor::Success(collect_block.call(results))
-          rescue StandardError => e
+          rescue RubyReactor::Error::Rescuable => e
             return RubyReactor::Failure(e)
           end
         end

data/lib/ruby_reactor/step.rb

@@ -113,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

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.4"
+  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)