ruby_reactor 0.8.4 → 0.8.5

data/specs/007-execution-flow-analysis/evidence/probes/03_map.rb

@@ -0,0 +1,232 @@
+# frozen_string_literal: true
+
+# map: research H14–H18, user questions Q1 and Q3. Every element reactor runs
+# e1 → e2 and both declare undo/compensate; element i == 2 fails at e2.
+
+module P
+  FAILS_AT_TWO = ->(inputs) { inputs.i == 2 }
+  ITEMS = { items: [0, 1, 2, 3] }.freeze
+
+  class Elem < Base
+    tag "e"
+    input :i
+    input :from_a, optional: true
+    pstep :e1, idx: true
+    pstep :e2, after: :e1, idx: true, fail: FAILS_AT_TWO
+  end
+
+  class ElemOk < Base
+    tag "e"
+    input :i
+    input :from_a, optional: true
+    pstep :e1, idx: true
+    pstep :e2, after: :e1, idx: true
+  end
+
+  # Shared parent shape: a → map :m → b. Fan-out, fail_fast and whether b
+  # fails vary per probe. (Parameter names must not shadow the MapBuilder
+  # methods `fan_out` / `fail_fast` / `element` used inside the block.)
+  def self.map_parent(name, element_class, fanned: false, tolerant: false, b_fails: false)
+    klass = Class.new(Base) do
+      input :items
+      pstep :a
+      map :m, element_class do
+        source input(:items)
+        argument :i, element(:m)
+        argument :from_a, result(:a)
+        fan_out(fanned)
+        fail_fast(!tolerant)
+      end
+      pstep :b, after: :m, fail: b_fails
+    end
+    const_set(name, klass)
+  end
+
+  map_parent(:Map01, Elem)
+  map_parent(:Map02, Elem, tolerant: true)
+  map_parent(:Map03, ElemOk, b_fails: true)
+  map_parent(:Map04, Elem, fanned: true)
+  map_parent(:Map05, Elem, fanned: true, tolerant: true)
+  map_parent(:Map06, ElemOk, fanned: true, b_fails: true)
+
+  class ElemRetry < Base
+    tag "e"
+    input :i
+    input :from_a, optional: true
+    pstep :e1, idx: true
+    pstep :e2, after: :e1, idx: true, fail_times: 1, retries: { max_attempts: 2, base_delay: 0 }
+  end
+
+  map_parent(:Map09, ElemRetry, fanned: true)
+  map_parent(:Map10, ElemRetry)
+
+  class ElemHalts < Base
+    tag "e"
+    input :i
+    input :from_a, optional: true
+    pstep :e1, idx: true
+    pstep :e2, after: :e1, idx: true do
+      run do |inputs, _ctx|
+        Probe.rec("run:e.e2[#{inputs.i}]")
+        inputs.i == 1 ? RubyReactor.Halt(reason: "element done early") : RubyReactor.Success(inputs.i)
+      end
+    end
+  end
+
+  map_parent(:Map11, ElemHalts)
+
+  class ElemWithUnit < Base
+    tag "e"
+    input :i
+    input :from_a, optional: true
+    pstep :e1, idx: true
+    pstep :u, kind: :async_step, after: :e1, idx: true
+    pstep :e2, after: :e1, idx: true, fail: ->(inputs) { inputs.i == 1 }
+  end
+
+  map_parent(:Map12, ElemWithUnit, fanned: true)
+
+  class ChildWithMap < Base
+    tag "child"
+    input :items
+    pstep :c0
+    map :m, Elem do
+      source input(:items)
+      argument :i, element(:m)
+    end
+  end
+
+  class Map07 < Base
+    input :items
+    pstep :a
+    compose(:child, ChildWithMap) { argument :items, input(:items) }
+  end
+
+  class Kid < Base
+    tag "k"
+    pstep :k1
+  end
+
+  class ElemComposes < Base
+    tag "e"
+    input :i
+    pstep :e1, idx: true
+    compose :kid, Kid
+    pstep :e2, after: %i[e1 kid], idx: true, fail: FAILS_AT_TWO
+  end
+
+  class Map08 < Base
+    input :items
+    map :m, ElemComposes do
+      source input(:items)
+      argument :i, element(:m)
+    end
+  end
+end
+
+def elements(*indexes, fail_at: nil)
+  indexes.flat_map do |i|
+    base = ["run:e.e1[#{i}]", "run:e.e2[#{i}]"]
+    i == fail_at ? base + ["compensate:e.e2[#{i}]", "undo:e.e1[#{i}]"] : base
+  end
+end
+
+Probe.scenario "S-map-01", "a → map(4 elems, inline, fail_fast; elem 2 fails) → b   [Q1]",
+               mode: :inline,
+               expected: %w[run:a run:e.e1[0] run:e.e2[0] run:e.e1[1] run:e.e2[1] run:e.e1[2] run:e.e2[2]
+                            compensate:e.e2[2] undo:e.e1[2] undo:e.e2[1] undo:e.e1[1] undo:e.e2[0] undo:e.e1[0]
+                            undo:a => failure(m)] do
+  P::Map01.run(P::ITEMS)
+end
+
+Probe.scenario "S-map-02", "a → map(inline, fail_fast false; elem 2 fails) → b",
+               mode: :inline,
+               expected: ["run:a", *elements(0, 1, 2, 3, fail_at: 2), "run:b", "=>", "success"] do
+  P::Map02.run(P::ITEMS)
+end
+
+Probe.scenario "S-map-03", "a → map(inline, all ok) → b(fails)   [Q1: later failure]",
+               mode: :inline,
+               expected: %w[run:a run:e.e1[0] run:e.e2[0] run:e.e1[1] run:e.e2[1] run:e.e1[2] run:e.e2[2]
+                            run:e.e1[3] run:e.e2[3] run:b compensate:b undo:e.e2[3] undo:e.e1[3] undo:e.e2[2]
+                            undo:e.e1[2] undo:e.e2[1] undo:e.e1[1] undo:e.e2[0] undo:e.e1[0] undo:a =>
+                            failure(b)] do
+  P::Map03.run(P::ITEMS)
+end
+
+Probe.scenario "S-map-04", "a → map(fan_out, fail_fast; elem 2 fails) → b",
+               mode: :worker,
+               expected: %w[run:a run:e.e1[0] run:e.e2[0] run:e.e1[1] run:e.e2[1] run:e.e1[2] run:e.e2[2]
+                            compensate:e.e2[2] undo:e.e1[2] undo:e.e2[1] undo:e.e1[1] undo:e.e2[0] undo:e.e1[0]
+                            undo:a => failure(m)] do
+  Probe.run_async(P::Map04, P::ITEMS)
+end
+
+Probe.scenario "S-map-05", "a → map(fan_out, fail_fast false; elem 2 fails) → b",
+               mode: :worker,
+               expected: ["run:a", *elements(0, 1, 2, 3, fail_at: 2), "run:b", "=>", "success"] do
+  Probe.run_async(P::Map05, P::ITEMS)
+end
+
+Probe.scenario "S-map-06", "a → map(fan_out, all ok) → b(fails)",
+               mode: :worker,
+               expected: %w[run:a run:e.e1[0] run:e.e2[0] run:e.e1[1] run:e.e2[1] run:e.e1[2] run:e.e2[2]
+                            run:e.e1[3] run:e.e2[3] run:b compensate:b undo:e.e2[3] undo:e.e1[3] undo:e.e2[2]
+                            undo:e.e1[2] undo:e.e2[1] undo:e.e1[1] undo:e.e2[0] undo:e.e1[0] undo:a =>
+                            failure(b)] do
+  Probe.run_async(P::Map06, P::ITEMS)
+end
+
+Probe.scenario "S-map-07", "a → compose(c0 → map(elem 2 fails))",
+               mode: :inline,
+               expected: %w[run:a run:child.c0 run:e.e1[0] run:e.e2[0] run:e.e1[1] run:e.e2[1] run:e.e1[2]
+                            run:e.e2[2] compensate:e.e2[2] undo:e.e1[2] undo:e.e2[1] undo:e.e1[1] undo:e.e2[0]
+                            undo:e.e1[0] undo:child.c0 undo:a => failure(child)] do
+  P::Map07.run(P::ITEMS)
+end
+
+Probe.scenario "S-map-08", "map(elem: e1 → compose(k1) → e2; elem 2 fails)",
+               mode: :inline,
+               expected: %w[run:e.e1[0] run:k.k1 run:e.e2[0] run:e.e1[1] run:k.k1 run:e.e2[1] run:e.e1[2]
+                            run:k.k1 run:e.e2[2] compensate:e.e2[2] undo:k.k1 undo:e.e1[2] undo:e.e2[1]
+                            undo:k.k1 undo:e.e1[1] undo:e.e2[0] undo:k.k1 undo:e.e1[0] => failure(m)] do
+  P::Map08.run(P::ITEMS)
+end
+
+Probe.scenario "S-map-04b", "map(fan_out, fail_fast; elem 2 fails), element jobs performed 3,2,1,0",
+               mode: :worker,
+               expected: %w[run:a run:e.e1[3] run:e.e2[3] run:e.e1[2] run:e.e2[2] compensate:e.e2[2]
+                            undo:e.e1[2] undo:e.e2[3] undo:e.e1[3] undo:a => failure(m)] do
+  dispatched = P::Map04.run(P::ITEMS)
+  RubyReactor::Adapters::Sidekiq::MapElementWorker.jobs.reverse!
+  Probe.drain
+  P::Map04.find(dispatched.execution_id)
+end
+
+Probe.scenario "S-map-09", "a → map(fan_out; each e2 fails once, retries 2) → b",
+               mode: :worker,
+               expected: %w[run:a run:e.e1[0] run:e.e2[0] retry:e2#1 run:e.e1[1] run:e.e2[1] retry:e2#1
+                            run:e.e2[0] run:e.e2[1] run:b => success] do
+  Probe.run_async(P::Map09, { items: [0, 1] })
+end
+
+Probe.scenario "S-map-10", "a → map(inline; each e2 fails once, retries 2) → b",
+               mode: :inline,
+               expected: %w[run:a run:e.e1[0] run:e.e2[0] retry:e2#1 run:e.e2[0] run:e.e1[1] run:e.e2[1] retry:e2#1
+                            run:e.e2[1] run:b => success] do
+  P::Map10.run({ items: [0, 1] })
+end
+
+Probe.scenario "S-map-11", "a → map(inline; elem 1 returns Halt) → b",
+               mode: :inline, expected: %w[run:a run:e.e1[0] run:e.e2[0] run:e.e1[1] run:e.e2[1] => halt] do
+  P::Map11.run({ items: [0, 1, 2] })
+end
+
+Probe.scenario "S-map-12", "a → map(fan_out; element e1 → async_step u, e2; elem 1 fails) → b",
+               mode: :worker,
+               expected: %w[run:a run:e.e1[0] run:e.e2[0] run:e.e1[1] run:e.e2[1] compensate:e.e2[1]
+                            undo:e.e1[1] undo:e.e2[0] undo:e.e1[0] undo:a run:e.u[0] run:e.u[1] => failure(m)] do
+  result = Probe.run_async(P::Map12, { items: [0, 1] })
+  Probe.note("StepWorker jobs left after drain: #{RubyReactor::Adapters::Sidekiq::StepWorker.jobs.size}")
+  result
+end

data/specs/007-execution-flow-analysis/evidence/probes/04_async.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+# async_step / async_reactor: research H19–H22. Parents run inline; units run
+# in their own jobs. Reader scenarios use Sidekiq inline! (the unit completes at
+# enqueue) because a same-process reader in fake mode would wait out
+# async_wait_timeout for a job nobody performs.
+
+module P
+  # r reads result(:u); opts in to compensation by failing on a Failure.
+  module Reader
+    def reader(name, source)
+      pstep name do
+        argument :seen, result(source)
+        run do |inputs, _ctx|
+          Probe.rec("run:#{name}")
+          failed = inputs.seen.is_a?(RubyReactor::Failure)
+          failed ? RubyReactor.Failure("#{name} saw a failed unit") : RubyReactor.Success(inputs.seen)
+        end
+      end
+    end
+  end
+
+  class Async01 < Base
+    pstep :a
+    pstep :u, kind: :async_step, after: :a, fail: true
+    pstep :b, after: :a
+  end
+
+  class Async02 < Base
+    extend Reader
+
+    pstep :a
+    pstep :u, kind: :async_step, after: :a, fail: true
+    reader :r, :u
+  end
+
+  class Async03 < Base
+    pstep :a
+    pstep :u, kind: :async_step, after: :a
+    pstep :b, after: :a, fail: true
+  end
+
+  class Async04 < Base
+    pstep :a
+    async_reactor(:child, ChildFails) { argument :from_a, result(:a) }
+    pstep :b, after: :a
+  end
+
+  class Async05 < Base
+    extend Reader
+
+    pstep :a
+    async_reactor(:child, ChildFails) { argument :from_a, result(:a) }
+    reader :r, :child
+  end
+
+  class Async06 < Base
+    pstep :a
+    async_reactor(:child, ChildOk) { argument :from_a, result(:a) }
+    pstep :b, after: :a, fail: true
+  end
+
+  class Async07 < Base
+    pstep :a
+    pstep :u, kind: :async_step, after: :a, fail: true, retries: { max_attempts: 3, base_delay: 0 }
+    pstep :b, after: :a
+  end
+end
+
+Probe.scenario "S-async-01", "a → async_step u(fails), no reader; b",
+               mode: :"inline parent + drained StepWorker",
+               expected: %w[run:a run:b run:u compensate:u => success] do
+  result = P::Async01.run({})
+  Probe.drain
+  result
+end
+
+Probe.scenario "S-async-02", "a → async_step u(fails) → r reads u and fails",
+               mode: :"inline parent + Sidekiq inline!",
+               expected: %w[run:a run:u compensate:u run:r compensate:r undo:a => failure(r)] do
+  Probe.inline_jobs { P::Async02.run({}) }
+end
+
+Probe.scenario "S-async-03", "a → async_step u(ok); b(fails), no reader",
+               mode: :"inline parent + drained StepWorker",
+               expected: %w[run:a run:b compensate:b undo:a run:u => failure(b)] do
+  result = P::Async03.run({})
+  Probe.drain
+  result
+end
+
+Probe.scenario "S-async-04", "a → async_reactor child(c1 → c2 fails), no reader; b",
+               mode: :"inline parent + drained Worker",
+               expected: %w[run:a run:b run:child.c1 run:child.c2 compensate:child.c2 undo:child.c1 => success] do
+  result = P::Async04.run({})
+  Probe.drain
+  result
+end
+
+Probe.scenario "S-async-05", "a → async_reactor child(c1 → c2 fails) → r reads child and fails",
+               mode: :"inline parent + Sidekiq inline!",
+               expected: %w[run:a run:child.c1 run:child.c2 compensate:child.c2 undo:child.c1 run:r compensate:r
+                            undo:a => failure(r)] do
+  Probe.inline_jobs { P::Async05.run({}) }
+end
+
+Probe.scenario "S-async-06", "a → async_reactor child(ok); b(fails)",
+               mode: :"inline parent + drained Worker",
+               expected: %w[run:a run:b compensate:b undo:a run:child.c1 run:child.c2 => failure(b)] do
+  result = P::Async06.run({})
+  Probe.drain
+  result
+end
+
+Probe.scenario "S-async-07", "a → async_step u(always fails, retries 3), no reader; b",
+               mode: :"inline parent + drained StepWorker",
+               expected: %w[run:a run:b run:u run:u run:u compensate:u => success] do
+  result = P::Async07.run({})
+  Probe.drain
+  result
+end
+
+# Fake mode: nobody performs the unit, so the same-process reader waits out
+# async_wait_timeout (2s here). The unit is drained afterwards.
+Probe.scenario "S-async-08", "a → async_step u → r reads u; unit never finishes in time",
+               mode: :"inline parent + drained StepWorker (after)",
+               expected: %w[run:a undo:a run:u compensate:u => failure(r)] do
+  result = P::Async02.run({})
+  Probe.note("error=#{result.error.to_s.lines.first&.strip}")
+  Probe.drain
+  result
+end

data/specs/007-execution-flow-analysis/evidence/probes/05_background.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+# background: research H8, H23. The worker path (Worker#perform →
+# Executor#resume_execution) against the same shapes as the inline baseline.
+
+module P
+  class Bg01 < Base
+    background all: true
+    pstep :a
+    pstep :b, after: :a
+    pstep :c, after: :b, fail: true
+  end
+
+  class Bg02 < Base
+    pstep :a
+    pstep :b, after: :a
+    pstep :c, after: :b, fail: true
+    background after: :a
+  end
+
+  class Bg03 < Base
+    background all: true
+    pstep :a
+    pstep :b, after: :a, fail: true, retries: { max_attempts: 3, base_delay: 0 }
+  end
+
+  class Bg04 < Base
+    background all: true
+    pstep :a
+    pstep :b, after: :a, fail_times: 1, retries: { max_attempts: 2, base_delay: 0 }
+    pstep :c, after: :b
+  end
+end
+
+Probe.scenario "S-bg-01", "background all: a → b → c(fails)",
+               mode: :worker, expected: %w[run:a run:b run:c compensate:c undo:b undo:a => failure(c)] do
+  Probe.run_async(P::Bg01)
+end
+
+Probe.scenario "S-bg-02", "a | background after: :a | b → c(fails)   (a ran in the caller)",
+               mode: :"caller + worker", expected: %w[run:a run:b run:c compensate:c undo:b undo:a => failure(c)] do
+  P::Bg02.run({})
+  Probe.note("caller returned with #{Probe.pending_jobs} worker job(s) queued")
+  id = RubyReactor::Adapters::Sidekiq::Worker.jobs.first["args"].first
+  Probe.drain
+  P::Bg02.find(id)
+end
+
+Probe.scenario "S-bg-03", "background all: a → b(always fails, retries 3)",
+               mode: :worker,
+               expected: %w[run:a run:b retry:b#1 run:b retry:b#2 run:b compensate:b undo:a => failure(b)] do
+  Probe.run_async(P::Bg03)
+end
+
+Probe.scenario "S-bg-04", "background all: a → b(fails once, retries 2) → c",
+               mode: :worker, expected: %w[run:a run:b retry:b#1 run:b run:c => success] do
+  Probe.run_async(P::Bg04)
+end

data/specs/007-execution-flow-analysis/evidence/probes/06_coordination.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+# Locks, semaphores and retries relative to rollback: research H2, H7, H13,
+# H24, H25. Inline runs unless stated.
+
+module P
+  def self.hold_lock(key, owner)
+    RubyReactor::Lock.new(key, owner: owner, ttl: 60, wait: 0, auto_extend: false).acquire
+  end
+
+  def self.lock_count(key)
+    RubyReactor.configuration.storage_adapter.lock_info("lock:#{key}")&.fetch(:count)
+  end
+
+  class Lock01 < Base
+    with_lock { |_inputs| "rk" }
+    pstep :a
+    pstep :b, after: :a, fail: true
+  end
+
+  class Lock02 < Base
+    pstep :a
+    pstep(:b, after: :a) { with_lock { |_args| "sk" } }
+    pstep :c, after: :b, fail: true
+  end
+
+  class Lock03 < Base
+    pstep :a
+    pstep(:b, after: :a) { with_lock { |_args| "sk" } }
+  end
+
+  class Lock04 < Base
+    pstep :a
+    pstep(:b, after: :a) { with_semaphore(limit: 1) { |_args| "sem" } }
+    pstep :c, after: :b, fail: true
+  end
+
+  # c's body takes b's key as another owner (a concurrent forward run), so b's
+  # undo cannot re-take it within rollback_wait.
+  class Lock05 < Base
+    pstep :a
+    pstep(:b, after: :a) { with_lock(rollback_wait: 0.3) { |_args| "sk" } }
+    pstep :c, after: :b do
+      run do |_inputs, _ctx|
+        Probe.rec("run:c")
+        P.hold_lock("sk", "intruder")
+        RubyReactor.Failure("boom c")
+      end
+    end
+  end
+
+  class LockedChild < Base
+    tag "child"
+    with_lock { |_inputs| "rk" }
+    pstep :c1
+  end
+
+  class Lock06 < Base
+    with_lock { |_inputs| "rk" }
+    pstep :a
+    compose :child, LockedChild
+    pstep :b, after: :child do
+      run do |_inputs, _ctx|
+        Probe.rec("run:b(rk count=#{P.lock_count("rk")})")
+        RubyReactor.Failure("boom b")
+      end
+    end
+  end
+
+  class Retry01 < Base
+    pstep :a
+    pstep :b, after: :a, fail: true, retries: { max_attempts: 3, base_delay: 0 }
+  end
+
+  class Retry02 < Base
+    pstep :a
+    pstep :b, after: :a, retries: { max_attempts: 3, base_delay: 0 } do
+      run do |_inputs, _ctx|
+        Probe.rec("run:b")
+        fail!("permanent", retry: false)
+      end
+    end
+  end
+
+  class Retry03 < Base
+    pstep :a
+    pstep :b, after: :a, fail_times: 1, retries: { max_attempts: 2, base_delay: 0 }
+    pstep :c, after: :b
+  end
+
+  class Retry04 < Base
+    pstep :a
+    pstep :b, after: :a, fail: :raise, retries: { max_attempts: 2, base_delay: 0 }
+  end
+end
+
+Probe.scenario "S-lock-01", "reactor with_lock(rk): a → b(fails)",
+               mode: :inline,
+               expected: %w[lock_acquired:rk run:a run:b compensate:b undo:a lock_released:lock:rk => failure(b)] do
+  # Reactor-level lock_released reports the prefixed key; lock_acquired does not.
+  P::Lock01.run({})
+end
+
+Probe.scenario "S-lock-02", "a → b(step with_lock sk) → c(fails)",
+               mode: :inline,
+               expected: %w[run:a lock_acquired:sk run:b lock_released:sk run:c compensate:c lock_acquired:sk undo:b
+                            lock_released:sk undo:a => failure(c)] do
+  P::Lock02.run({})
+end
+
+Probe.scenario "S-lock-03", "a → b(step with_lock sk, key held by another owner)",
+               mode: :inline, expected: %w[run:a undo:a => failure(b)] do
+  P.hold_lock("sk", "someone-else")
+  P::Lock03.run({})
+end
+
+Probe.scenario "S-lock-04", "a → b(step with_semaphore limit 1) → c(fails)",
+               mode: :inline,
+               expected: %w[run:a semaphore_acquired:sem run:b semaphore_released:sem run:c compensate:c
+                            semaphore_acquired:sem undo:b semaphore_released:sem undo:a => failure(c)] do
+  P::Lock04.run({})
+end
+
+Probe.scenario "S-lock-05", "a → b(step lock sk, rollback_wait 0.3) → c(takes sk as intruder, fails)",
+               mode: :inline,
+               expected: %w[run:a lock_acquired:sk run:b lock_released:sk run:c compensate:c undo:a
+                            => failure(c)] do
+  Probe.rollback_note(P::Lock05.run({}))
+end
+
+Probe.scenario "S-lock-06", "reactor with_lock(rk): a → compose(child with_lock rk: c1) → b(fails)",
+               mode: :inline,
+               expected: ["lock_acquired:rk", "run:a", "lock_acquired:rk", "run:child.c1", "lock_released:lock:rk",
+                          "run:b(rk count=1)", "compensate:b", "undo:child.c1", "undo:a", "lock_released:lock:rk",
+                          "=>", "failure(b)"] do
+  P::Lock06.run({})
+end
+
+Probe.scenario "S-retry-01", "a → b(always fails, retries 3)",
+               mode: :inline,
+               expected: %w[run:a run:b retry:b#1 run:b retry:b#2 run:b compensate:b undo:a => failure(b)] do
+  P::Retry01.run({})
+end
+
+Probe.scenario "S-retry-02", "a → b(fail! retry: false, retries 3)",
+               mode: :inline, expected: %w[run:a run:b compensate:b undo:a => failure(b)] do
+  P::Retry02.run({})
+end
+
+Probe.scenario "S-retry-03", "a → b(fails once, retries 2) → c",
+               mode: :inline, expected: %w[run:a run:b retry:b#1 run:b run:c => success] do
+  P::Retry03.run({})
+end
+
+Probe.scenario "S-retry-04", "a → b(raises, retries 2)",
+               mode: :inline, expected: %w[run:a run:b retry:b#1 run:b compensate:b undo:a => failure(b)] do
+  P::Retry04.run({})
+end