hecks 3.5.0 → 3.6.0

data/lib/hecks/runtime/saga_interpreter/compensation.rb

@@ -0,0 +1,90 @@
+module Hecks
+  module Runtime
+    class SagaInterpreter
+      # The compensation ledger of a saga instance: legs that completed compensably are recorded
+      # as they dispatch, popped back off if their own attempt fails, and replayed newest-first
+      # when a later leg is refused. Mixed into {SagaInterpreter}.
+      module Compensation
+        private
+
+        # Recorded before dispatching, not after `@door.reenter` returns —
+        # reenter can recursively re-enter this interpreter and refuse
+        # before ever returning here, and recording only on success would
+        # be too late for that nested refusal to see this leg's own
+        # compensation. Popped back off in the rescues if this leg's own attempt is the one
+        # that failed.
+        def record_compensation(leg, spec, ledger)
+          return unless spec.compensates && !ledger.recorded
+
+          resolved = dispatch_args(leg.process_manager, spec.compensates, leg.event, leg.instance, leg.correlation)
+          leg.instance[:completed_compensations] << { command_name: spec.compensates.command_name, args: resolved }
+          checkpoint_leg(leg)
+          ledger.recorded = true
+        end
+
+        # `.pop`, not search-and-delete — nothing else can have pushed after
+        # this leg's own entry without this leg's own `reenter` having
+        # already returned first.
+        def unrecord_compensation(leg)
+          leg.instance[:completed_compensations].pop
+          checkpoint_leg(leg)
+        end
+
+        # Derived compensations run newest-first, before any hand-written
+        # `on :refused` dispatches. Drained (popped), not just read —
+        # that's what keeps a re-entrant `on :refused` from running twice.
+        def drain_derived_compensations(leg)
+          compensations = leg.instance[:completed_compensations] || []
+          deliver_derived_compensation(leg, compensations.pop) until compensations.empty?
+          checkpoint_leg(leg)
+        end
+
+        # `entry[:args]` is already resolved, so this skips `dispatch_args`
+        # and goes straight to delivery. Never re-enters `unwind` on its own
+        # failure — `compensation_failed: true` tags a refused compensation
+        # distinctly rather than as an ordinary failed delivery.
+        def deliver_derived_compensation(leg, entry)
+          record = { process_manager: leg.process_manager.name, instance: leg.correlation,
+                     dispatch: entry[:command_name] }
+          attempts = 0
+          loop do
+            error = compensate_once(leg, entry, record)
+            return unless error
+
+            attempts += 1
+            return abandon_compensation(leg, entry, record, error, attempts) if attempts > MAX_DEFECT_RETRIES
+
+            log_compensation_retry(record, error, attempts)
+          end
+        end
+
+        # One try. Answers nil once the compensation has settled (delivered or refused), or the
+        # crash that stopped it.
+        def compensate_once(leg, entry, record)
+          reenter_command(leg, entry[:command_name], entry[:args], explicit: true, source_receiver: nil)
+          @registry.saga_log << record.merge(delivered: true, compensation: true)
+          nil
+        rescue *DOMAIN_REFUSALS => e
+          @registry.saga_log << record.merge(delivered: false, reason: e.message, compensation: true,
+                                             compensation_failed: true)
+          nil
+        rescue StandardError => e
+          e
+        end
+
+        def log_compensation_retry(record, error, attempt)
+          @registry.saga_log << record.merge(delivered: false, reason: error.message, compensation: true,
+                                             defect: true, error_class: error.class.name,
+                                             attempt: attempt, retrying: true)
+        end
+
+        def abandon_compensation(leg, entry, record, error, attempt)
+          warn "[hecks] defect compensating saga #{leg.process_manager.name} — instance #{leg.correlation.inspect} " \
+               "dispatching #{entry[:command_name]} after #{attempt} attempts: #{error.class}: #{error.message}"
+          @registry.saga_log << record.merge(delivered: false, reason: error.message, compensation: true,
+                                             defect: true, error_class: error.class.name, compensation_failed: true)
+        end
+      end
+    end
+  end
+end

data/lib/hecks/runtime/saga_interpreter/correlation.rb

@@ -12,18 +12,10 @@ module Hecks
         # A dotted path (`:"end_to_end.value"`) names one scalar; a whole value object
         # has no single unambiguous rendering as a key.
         def saga_correlation(process_manager, event)
-          path  = process_manager.correlates_by.to_s.split(".")
-          # A downstream event may carry the bare scalar already. Strings respond to `[]`,
-          # so test for Hash/Value explicitly rather than `respond_to?(:[])`.
-          value = path.reduce(event.payload) do |held, segment|
-            held.is_a?(Hash) || held.is_a?(Value) ? held[segment.to_sym] : held
-          end
+          value = payload_correlation(process_manager, event)
           return value unless value.to_s.empty?
 
-          # The stamp `deliver_saga_dispatch` puts on its own event, for legs whose command
-          # carries no correlation field. Keyed by `correlation_head` so another saga
-          # correlating on a different field cannot misread it.
-          stamped = event.correlation && event.correlation[process_manager.correlation_head.to_s]
+          stamped = stamped_correlation(process_manager, event)
           return stamped unless stamped.nil? || stamped.to_s.empty?
 
           # A self-referencing leg correlates by `event.id`: routing keys never ride in the
@@ -33,6 +25,23 @@ module Hecks
           self_identified?(process_manager, event) ? event.id : nil
         end
 
+        # The payload path's own value. A downstream event may carry the bare scalar already.
+        # Strings respond to `[]`, so test for Hash/Value explicitly rather than
+        # `respond_to?(:[])`.
+        def payload_correlation(process_manager, event)
+          path = process_manager.correlates_by.to_s.split(".")
+          path.reduce(event.payload) do |held, segment|
+            held.is_a?(Hash) || held.is_a?(Value) ? held[segment.to_sym] : held
+          end
+        end
+
+        # The stamp `deliver_saga_dispatch` puts on its own event, for legs whose command
+        # carries no correlation field. Keyed by `correlation_head` so another saga
+        # correlating on a different field cannot misread it.
+        def stamped_correlation(process_manager, event)
+          event.correlation && event.correlation[process_manager.correlation_head.to_s]
+        end
+
         def self_identified?(process_manager, event)
           domain, bare_name = event.aggregate.to_s.split("::", 2)
           return false unless bare_name

data/lib/hecks/runtime/saga_interpreter/delivery.rb

@@ -0,0 +1,147 @@
+require_relative "../errors"
+require_relative "../reaction_invocation"
+require_relative "../value"
+
+module Hecks
+  module Runtime
+    class SagaInterpreter
+      # Delivers the commands a saga leg dispatches: the retries of a crash and the unwinding of a
+      # refusal. Mixed into {SagaInterpreter}, which owns the checkpointing and the transitions.
+      module Delivery
+        # How many times one dispatch has been tried, and whether its compensation is on the
+        # ledger, so a retry records it afresh and a failure pops it back off.
+        Ledger = Struct.new(:attempts, :recorded)
+
+        private
+
+        # Delivers one command a saga leg dispatches: resolves its arguments, logs the inputs they
+        # were bound from, then runs the checkpoint/dispatch/compensation ledger protocol with the
+        # retries a crash gets.
+        # rubocop:disable-next Metrics/ParameterLists -- spec/runtime/reaction_invocation_spec.rb calls it by name
+        def deliver_saga_dispatch(process_manager, spec, event, instance, correlation, domain)
+          leg    = Leg.new(process_manager, event, domain, correlation, nil, instance)
+          args   = dispatch_args(process_manager, spec, event, instance, correlation)
+          record = { process_manager: process_manager.name, instance: correlation, dispatch: spec.command_name }
+
+          log_dispatch_inputs(leg, spec, args) unless spec.with_spec.to_a.empty?
+          return refuse_at_depth_ceiling(leg, record) if @door.reaction_depth_reached?
+
+          attempt_dispatch(leg, spec, args, record)
+        end
+
+        # Raw inputs captured alongside the resolved result — never
+        # re-derived later from saga_instances, which only ever holds the
+        # final memory, not what it was at the moment this dispatch fired.
+        def log_dispatch_inputs(leg, spec, args)
+          process_manager = leg.process_manager
+          @registry.saga_dispatch_log << { process_manager: process_manager.name, instance: leg.correlation,
+                                           dispatch: spec.command_name,
+                                           on: leg.event.name, correlation_head: process_manager.correlation_head,
+                                           event_payload: leg.event.payload,
+                                           memory: Value.materialize(leg.instance[:memory]),
+                                           with_spec: spec.with_spec, args: args }
+        end
+
+        # Not a domain decision, but unambiguous — the leg didn't run, so
+        # it unwinds like a refusal rather than stranding the instance.
+        def refuse_at_depth_ceiling(leg, record)
+          @registry.saga_log << record.merge(delivered: false,
+                                             reason:    "reaction depth #{@door.max_reaction_depth} reached")
+          unwind(leg)
+        end
+
+        # Runs the dispatch until it settles: delivered, refused (the leg unwinds), or crashed
+        # past `MAX_DEFECT_RETRIES`.
+        def attempt_dispatch(leg, spec, args, record)
+          ledger = Ledger.new(0, false)
+          loop do
+            error = dispatch_once(leg, spec, args, record, ledger)
+            return unless error
+
+            ledger.attempts += 1
+            return abandon_dispatch(leg, spec, record, error, ledger.attempts) if ledger.attempts > MAX_DEFECT_RETRIES
+
+            log_defect_retry(record, error, ledger.attempts)
+          end
+        end
+
+        # One try. Answers nil once the dispatch has settled (delivered, or refused and unwound),
+        # or the crash that stopped it.
+        def dispatch_once(leg, spec, args, record, ledger)
+          record_compensation(leg, spec, ledger)
+          reenter_dispatch(leg, spec, args)
+          @registry.saga_log << record.merge(delivered: true)
+          nil
+        rescue *DOMAIN_REFUSALS => e
+          settle_refusal(leg, record, ledger, e)
+        rescue StandardError => e
+          unrecord_compensation(leg) if ledger.recorded
+          ledger.recorded = false
+          e
+        end
+
+        def reenter_dispatch(leg, spec, args)
+          reenter_command(leg, spec.command_name, args,
+                          explicit:        ReactionInvocation.projection_declared?(spec),
+                          source_receiver: { aggregate: leg.event.aggregate, identity: leg.event.id })
+        end
+
+        # A refusal by the target is a recorded outcome, and the leg
+        # that raised it unwinds and runs its own compensation there.
+        def settle_refusal(leg, record, ledger, error)
+          unrecord_compensation(leg) if ledger.recorded
+          @registry.saga_log << record.merge(delivered: false, reason: error.message)
+          unwind(leg)
+          nil
+        end
+
+        # Dispatches `command_name` through the door, stamped with this saga's correlation.
+        def reenter_command(leg, command_name, projected, explicit:, source_receiver:)
+          head = leg.process_manager.correlation_head
+          verb = qualified(command_name, leg.domain)
+          invocation = ReactionInvocation.build(registry: @registry, verb: verb, projected: projected,
+                                                explicit: explicit, passthrough: [head],
+                                                source_receiver: source_receiver)
+          @door.reenter(verb, saga_correlation: { head.to_s => leg.correlation }, **invocation)
+        end
+
+        # Unlike a refusal, a crash isn't a domain decision, so it
+        # doesn't unwind on the first failure — MAX_DEFECT_RETRIES lets a
+        # transient failure clear on retry.
+        def log_defect_retry(record, error, attempt)
+          @registry.saga_log << record.merge(delivered: false, reason: error.message,
+                                             defect: true, error_class: error.class.name,
+                                             attempt: attempt, retrying: true)
+        end
+
+        # `defect_compensated: true` tags an exhausted retry distinctly, so the log never
+        # misrepresents a crash as a decision the domain made.
+        def abandon_dispatch(leg, spec, record, error, attempt)
+          warn "[hecks] defect in saga #{leg.process_manager.name} — instance #{leg.correlation.inspect} " \
+               "dispatching #{spec.command_name} after #{attempt} attempts: #{error.class}: #{error.message}"
+          @registry.saga_log << record.merge(delivered: false, reason: error.message, defect: true,
+                                             error_class: error.class.name, defect_compensated: true)
+          unwind(leg)
+        end
+
+        def dispatch_args(process_manager, spec, event, instance, correlation)
+          ReactionInvocation.resolve_mapping(
+            with_spec: spec.with_spec,
+            scopes:    [["current event payload", event.payload], ["opening event memory", instance[:memory]]],
+            bindings:  { process_manager.correlation_head => correlation },
+            label:     "#{process_manager.name}'s dispatch #{spec.command_name}"
+          )
+        end
+
+        # Unconditionally the saga's own home domain, never inferred from
+        # `command_name`'s shape — unlike a policy's explicit `target_domain`
+        # (set by `across`), a saga's `dispatch`/`compensates` has no such
+        # field, and every command a saga fires lands inside its own
+        # bluebook chapter.
+        def qualified(command_name, domain)
+          "#{domain}::#{command_name}"
+        end
+      end
+    end
+  end
+end

data/lib/hecks/runtime/saga_interpreter/lifecycle.rb

@@ -0,0 +1,63 @@
+module Hecks
+  module Runtime
+    class SagaInterpreter
+      # Where a saga instance begins and ends: born on the event a process manager starts on,
+      # forgotten on the one it ends on. Mixed into {SagaInterpreter}.
+      module Lifecycle
+        private
+
+        def begin_saga(process_manager, event, domain)
+          return unless event.name == process_manager.starts_on
+
+          correlation = saga_correlation(process_manager, event)
+          return log_unborn(process_manager, event) if correlation.to_s.empty?
+          return unless instantiate_saga?(process_manager, event, domain, correlation)
+
+          @registry.saga_log << { process_manager: process_manager.name, on: event.name,
+                                  instance: correlation, born: true, state: process_manager.states.first }
+        end
+
+        def log_unborn(process_manager, event)
+          @registry.saga_log << { process_manager: process_manager.name, on: event.name,
+                                  born: false, reason: "no #{process_manager.correlates_by} in the payload" }
+        end
+
+        # Whether this call created the instance: false when one already remembers the correlation.
+        def instantiate_saga?(process_manager, event, domain, correlation)
+          @registry.saga_mutex.synchronize do
+            next false if @registry.saga_instances[process_manager.name].key?(correlation)
+
+            # `.dup` — a fresh saga's own memory starts as a copy of the
+            # starting event's payload, never the frozen payload itself,
+            # since memory is written into over the saga's lifetime.
+            instance = { state: process_manager.states.first, memory: event.payload.dup, completed_compensations: [] }
+            @registry.saga_instances[process_manager.name][correlation] = instance
+            checkpoint(process_manager, correlation, instance, domain)
+            true
+          end
+        end
+
+        def end_saga(process_manager, event, domain)
+          return unless event.name == process_manager.ends_on
+
+          correlation = saga_correlation(process_manager, event)
+          return if correlation.to_s.empty?
+          return unless forget_saga?(process_manager, domain, correlation)
+
+          @registry.saga_log << { process_manager: process_manager.name, on: event.name,
+                                  instance: correlation, ended: true }
+        end
+
+        # Whether this call ended the instance: false when no instance remembered the correlation.
+        def forget_saga?(process_manager, domain, correlation)
+          @registry.saga_mutex.synchronize do
+            next false unless @registry.saga_instances[process_manager.name].delete(correlation)
+
+            @registry.saga_persistence(domain).delete_saga(process_manager: process_manager.name, correlation: correlation)
+            true
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/runtime/saga_interpreter/transitions.rb

@@ -0,0 +1,112 @@
+module Hecks
+  module Runtime
+    class SagaInterpreter
+      # Moves a saga instance between states: takes the leg an event selects, checkpoints it under
+      # the mutex, then settles it by running the leg's dispatches. Mixed into {SagaInterpreter}.
+      module Transitions
+        private
+
+        def advance_saga(process_manager, event, domain)
+          return unless process_manager.handles?(event.name)
+
+          correlation = saga_correlation(process_manager, event)
+          return if correlation.to_s.empty?
+
+          record = { process_manager: process_manager.name, on: event.name, instance: correlation }
+          leg    = Leg.new(process_manager, event, domain, correlation, record)
+          return unless @registry.saga_mutex.synchronize { remembered_leg_taken?(leg) }
+
+          settle_transition(leg)
+        end
+
+        # The mutex covers only the check-mutate-checkpoint step, never the
+        # dispatch cascade that follows — `deliver_saga_dispatch`'s
+        # `@door.reenter` can recursively re-enter this interpreter on the
+        # same thread, and `Mutex` is not reentrant.
+        def remembered_leg_taken?(leg)
+          leg.instance = @registry.saga_instances[leg.process_manager.name][leg.correlation]
+          unless leg.instance
+            log_leg(leg, advanced: false, reason: "no conversation remembers #{leg.correlation.inspect}")
+            return false
+          end
+
+          leg_taken?(leg, leg.event.name)
+        end
+
+        # Leg chosen by (event, current state) — read under the mutex so
+        # two legs on the same event pick based on the state that's
+        # actually current right now. Answers whether a leg was taken.
+        def leg_taken?(leg, trigger)
+          handler = leg.process_manager.handler_for(trigger, leg.instance[:state])
+          unless handler
+            log_leg(leg, advanced: false, reason: leg_mismatch(leg.process_manager, trigger, leg.instance[:state]))
+            return false
+          end
+
+          leg.take(handler)
+          checkpoint_leg(leg, pending: leg.pending_marker)
+          true
+        end
+
+        def leg_mismatch(process_manager, event_name, state)
+          expected = process_manager.handlers_for(event_name).map { |h| h.from_state.inspect }.uniq
+          "in #{state.inspect}, not #{expected.join(" or ")}"
+        end
+
+        # The shared tail of `advance_saga` and `unwind`, both of which guard,
+        # mutate and checkpoint under the mutex before calling this.
+        def settle_transition(leg, drain_compensations: false)
+          # from:/to: read back from `instance` itself, never re-derived from
+          # `handler.from_state`/`to_state` — otherwise a log entry checked
+          # against that same handler object could never actually disagree
+          # with it, no matter what the runtime did.
+          log_leg(leg, advanced: true, from: leg.pre_state, to: leg.instance[:state])
+
+          drain_derived_compensations(leg) if drain_compensations
+          leg.handler.dispatches.each do |spec|
+            deliver_saga_dispatch(leg.process_manager, spec, leg.event, leg.instance, leg.correlation, leg.domain)
+          end
+          clear_pending_marker(leg)
+        end
+
+        # Guarded by `.equal?` (not `==`): `deliver_saga_dispatch`'s own
+        # `reenter` can trigger this correlation's `ends_on` as a nested
+        # reaction, deleting this row before this line runs. Clearing
+        # unconditionally would resurrect an already-ended saga, or stamp
+        # a reborn instance with a stale one's state.
+        def clear_pending_marker(leg)
+          @registry.saga_mutex.synchronize do
+            next unless @registry.saga_instances[leg.process_manager.name][leg.correlation].equal?(leg.instance)
+
+            checkpoint_leg(leg, pending: nil)
+          end
+        end
+
+        # A refused leg unwinds by running its own declared `on :refused`
+        # handler, where compensation lives — also the destination for a
+        # leg that hit the reaction-depth ceiling or exhausted its defect
+        # retries.
+        #
+        # A compensation that is itself refused does not unwind again: the
+        # state moves to the compensating leg's to_state before its
+        # dispatches run, so a second refusal finds the instance already
+        # out of from_state and records that instead.
+        def unwind(leg)
+          process_manager = leg.process_manager
+          return unless leg.instance && process_manager.handles?(REFUSED)
+
+          record  = { process_manager: process_manager.name, on: REFUSED, instance: leg.correlation }
+          refused = Leg.new(process_manager, leg.event, leg.domain, leg.correlation, record, leg.instance)
+
+          # Same non-reentrancy reasoning as `remembered_leg_taken?`'s own comment —
+          # the mutex covers only the check-mutate-checkpoint step.
+          return unless @registry.saga_mutex.synchronize { leg_taken?(refused, REFUSED) }
+
+          # `drain_compensations: true` only here — `advance_saga`'s own call
+          # never fires derived compensation.
+          settle_transition(refused, drain_compensations: true)
+        end
+      end
+    end
+  end
+end