ruby_reactor 0.5.0 → 0.5.2

data/lib/ruby_reactor/storage/redis_ordered_locking.rb

@@ -0,0 +1,382 @@
+# frozen_string_literal: true
+
+module RubyReactor
+  module Storage
+    # Ordered Lock Primitives — used by `with_ordered_lock` to enforce
+    # strict transaction ordering via a monotonically increasing nonce
+    # assigned at enqueue time. See `RubyReactor::OrderedLock`.
+    #
+    # Storage layout (hash-tagged so a Redis cluster keeps them on the same
+    # shard):
+    #   STRING  ordered_lock:{<key>}:next            — last-assigned nonce
+    #   STRING  ordered_lock:{<key>}:last_completed  — last-advanced nonce
+    #   HASH    ordered_lock:{<key>}:assigned_at     — { nonce => unix_ts }
+    #   STRING  ordered_lock:{<key>}:first_failed    — nonce of the FIRST run
+    #                                                  whose terminal status
+    #                                                  was Failure (strict mode
+    #                                                  poison marker; 0 / unset
+    #                                                  if no failure yet).
+    #   STRING  ordered_lock:{<key>}:epoch            — generation counter,
+    #                                                  bumped each time a fresh
+    #                                                  batch starts (nonce 1).
+    #                                                  Captured at assign and
+    #                                                  carried by every gate /
+    #                                                  advance call so a stale
+    #                                                  straggler from a drained
+    #                                                  batch (whose nonce numbers
+    #                                                  the next batch reuses)
+    #                                                  is fenced out as a no-op.
+    #
+    # When `last_completed == next`, the next/last_completed/assigned_at/
+    # first_failed keys are garbage-collected by the ADVANCE script and the next
+    # assign starts at 1 again — a fresh batch always starts un-poisoned. The
+    # `epoch` key is deliberately NOT GC'd (only TTL-expires when fully idle) so
+    # the generation keeps incrementing across back-to-back batches.
+    module RedisOrderedLocking # rubocop:disable Metrics/ModuleLength
+      ASSIGN_SCRIPT = <<~LUA
+        local next_key  = KEYS[1]
+        local last_key  = KEYS[2]
+        local at_key    = KEYS[3]
+        local epoch_key = KEYS[4]
+        local now       = ARGV[1]
+        local ttl       = tonumber(ARGV[2])
+
+        local nonce = redis.call('incr', next_key)
+        redis.call('expire', next_key, ttl)
+
+        if redis.call('exists', last_key) == 0 then
+          redis.call('set', last_key, 0, 'EX', ttl)
+        else
+          redis.call('expire', last_key, ttl)
+        end
+
+        -- nonce == 1 means `next` was absent (first ever, or GC'd after a full
+        -- drain), so this is the start of a fresh batch -> bump the generation.
+        -- Later nonces in the same batch read the epoch the nonce-1 caller set.
+        local epoch
+        if nonce == 1 then
+          epoch = redis.call('incr', epoch_key)
+        else
+          epoch = tonumber(redis.call('get', epoch_key) or '1')
+        end
+        redis.call('expire', epoch_key, ttl)
+
+        redis.call('hset', at_key, nonce, now)
+        redis.call('expire', at_key, ttl)
+        return {nonce, epoch}
+      LUA
+
+      CAN_PROCEED_SCRIPT = <<~LUA
+        local next_key  = KEYS[1]
+        local last_key  = KEYS[2]
+        local at_key    = KEYS[3]
+        local fail_key  = KEYS[4]
+        local epoch_key = KEYS[5]
+        local my        = tonumber(ARGV[1])
+        local now       = tonumber(ARGV[2])
+        local pp        = tonumber(ARGV[3])
+        local my_epoch  = tonumber(ARGV[4] or '0')
+
+        local last = tonumber(redis.call('get', last_key) or '0')
+        local first_failed = tonumber(redis.call('get', fail_key) or '0')
+
+        -- Stale-batch fence: a caller carrying an epoch from a drained batch
+        -- (whose nonce numbers the current batch reused) must not gate against
+        -- or poison-advance this batch. my_epoch == 0 is a legacy/no-epoch
+        -- caller (e.g. an in-flight job from before this field existed) — skip.
+        local cur_epoch = tonumber(redis.call('get', epoch_key) or '0')
+        if my_epoch > 0 and my_epoch ~= cur_epoch then
+          return {'stale', 0, last, first_failed}
+        end
+
+        -- Drained-batch fence: both counters absent means this caller's batch
+        -- fully drained and was GC'd (or wholly TTL-expired) while it slept —
+        -- e.g. a poison-passed straggler waking between the drain and the next
+        -- batch's first assign (epoch not yet bumped, so the stale fence can't
+        -- catch it). It may run late (poison semantics) but must NOT enter the
+        -- poison loop below: SET on the missing last_key would resurrect the
+        -- cursor with no TTL and let every nonce of the NEXT batch gate
+        -- straight through. Only both-absent is conclusive — a mid-batch
+        -- next_key TTL hiccup leaves last_key in place and proceeds normally.
+        -- Returns a DISTINCT 'drained_go' (not plain 'go') so the executor can
+        -- tell this apart: a genuine late straggler should run, but a Sidekiq
+        -- at-least-once redelivery of an already-terminal context must NOT
+        -- re-execute. The executor consults the stored context status to decide.
+        if redis.call('exists', next_key) == 0 and redis.call('exists', last_key) == 0 then
+          return {'drained_go', 0, last, first_failed}
+        end
+
+        -- Liveness heartbeat: a gate check proves this caller is alive (about
+        -- to run, or snoozing on lock/rate contention and re-checking), so
+        -- restamp its own assigned_at. assigned_at is otherwise set once at
+        -- ENQUEUE, meaning a job that merely sat in a deep queue longer than
+        -- poison_pill_timeout would be poison-passed the moment a successor
+        -- gates — this restamp gives it a full pp window from the time it
+        -- actually starts. hexists guard: never resurrect an entry that an
+        -- out-of-order terminal advance already deleted.
+        if my > last and redis.call('hexists', at_key, my) == 1 then
+          redis.call('hset', at_key, my, now)
+        end
+
+        if my <= last then
+          return {'go', 0, last, first_failed}
+        end
+
+        if my == last + 1 then
+          return {'go', 0, last, first_failed}
+        end
+
+        -- Drain consecutive poisoned blockers in one shot. Without this loop a
+        -- cluster of N dead blockers takes N snooze rounds to clear (one round
+        -- per blocker); with it, a single can_proceed call sweeps them all.
+        -- Bounded by `my` so the loop runs at most O(stream length) per call.
+        local advanced_via_poison = false
+        while last + 1 < my do
+          local blocker = last + 1
+          local at = tonumber(redis.call('hget', at_key, blocker) or '0')
+          -- Only a blocker with a recent assigned_at timestamp is genuinely in
+          -- flight; stop draining there. `at == 0` means the timer is gone (an
+          -- out-of-order advance deleted it, or the assigned_at hash expired),
+          -- so the blocker can never make progress on its own — advance past it
+          -- rather than stalling forever (the original `break` here was a
+          -- permanent head-of-line hang, the exact thing poison-pill prevents).
+          if at > 0 and (now - at) <= pp then
+            break
+          end
+          redis.call('set', last_key, blocker, 'KEEPTTL')
+          redis.call('hdel', at_key, blocker)
+          last = blocker
+          advanced_via_poison = true
+        end
+
+        if my <= last then
+          return {advanced_via_poison and 'poison_advance' or 'go', 0, last, first_failed}
+        end
+
+        if my == last + 1 then
+          return {advanced_via_poison and 'poison_advance' or 'go', 0, last, first_failed}
+        end
+
+        local blocker = last + 1
+        local blocker_assigned = tonumber(redis.call('hget', at_key, blocker) or '0')
+        local hint
+        if blocker_assigned > 0 then
+          hint = pp - (now - blocker_assigned)
+        else
+          hint = pp
+        end
+        if hint < 1 then hint = 1 end
+        return {'wait', hint, last, first_failed}
+      LUA
+
+      ADVANCE_SCRIPT = <<~LUA
+        local next_key  = KEYS[1]
+        local last_key  = KEYS[2]
+        local at_key    = KEYS[3]
+        local fail_key  = KEYS[4]
+        local epoch_key = KEYS[5]
+        local my        = tonumber(ARGV[1])
+        local failed    = tonumber(ARGV[2]) == 1
+        local ttl       = tonumber(ARGV[3])
+        local my_epoch  = tonumber(ARGV[4] or '0')
+
+        -- Stale-batch fence: an advance carrying an epoch from a drained batch
+        -- whose nonce numbers were reused must not mutate the current batch's
+        -- counters. This is the core protection against a slow straggler from a
+        -- prior batch corrupting a later one. my_epoch == 0 = legacy caller.
+        local cur_epoch = tonumber(redis.call('get', epoch_key) or '0')
+        if my_epoch > 0 and my_epoch ~= cur_epoch then
+          return tonumber(redis.call('get', last_key) or '0')
+        end
+
+        -- Drained-batch fence (mirrors CAN_PROCEED): a late terminal from a
+        -- batch that already drained and GC'd must be a complete no-op. Without
+        -- it, an in-order straggler advance (my == 0 + 1) would SET last_key
+        -- with KEEPTTL on a missing key — resurrecting a TTL-less cursor that
+        -- un-gates every nonce of the next batch — and a failed straggler
+        -- would write fail_key, strict-poisoning a batch that hasn't started.
+        if redis.call('exists', next_key) == 0 and redis.call('exists', last_key) == 0 then
+          return 0
+        end
+
+        local last = tonumber(redis.call('get', last_key) or '0')
+
+        -- Record the chain poison marker for ANY terminal failure ahead of the
+        -- cursor (my > last), not just the in-order successor; strict-mode
+        -- chain-skip relies on the SMALLEST failed nonce being recorded. A
+        -- failure at or behind the cursor (my <= last) is deliberately NOT
+        -- recorded: that guard is what keeps a Sidekiq duplicate redelivery of
+        -- an already-terminated failure from re-poisoning a chain that moved
+        -- on. Cost of the trade-off: a run the poison-advance already passed
+        -- (cursor moved beyond it) that later fails does NOT poison the chain
+        -- — by then ordering was already ceded for that nonce and successors
+        -- may have run.
+        if failed and my > last then
+          local existing = tonumber(redis.call('get', fail_key) or '0')
+          if existing == 0 or my < existing then
+            redis.call('set', fail_key, my, 'EX', ttl)
+          end
+        end
+
+        if my == last + 1 then
+          redis.call('set', last_key, my, 'KEEPTTL')
+          redis.call('hdel', at_key, my)
+          last = my
+
+          local nxt = tonumber(redis.call('get', next_key) or '0')
+          -- Guard with `nxt > 0` (mirroring SKIP_SCRIPT): a missing/expired
+          -- next_key reads as 0 and `last >= 0` would otherwise GC live
+          -- counters mid-sequence, resetting numbering and dropping the marker.
+          if last >= nxt and nxt > 0 then
+            redis.call('del', next_key)
+            redis.call('del', last_key)
+            redis.call('del', at_key)
+            redis.call('del', fail_key)
+          end
+          return last
+        end
+
+        redis.call('hdel', at_key, my)
+        return last
+      LUA
+
+      # Liveness restamp for a nonce that is actively executing its steps. The
+      # CAN_PROCEED heartbeat only fires when a job runs its gate; a blocker that
+      # passed the gate and is now running long steps never re-gates, so without
+      # this a successor would poison-advance past a still-running blocker once
+      # its steps outlast poison_pill_timeout — a silent ordering violation. A
+      # background thread calls this every pp/3 seconds while steps run.
+      #
+      # Guards: epoch-fenced (a stale-batch straggler must not touch the current
+      # batch) and hexists-guarded (never resurrect a timer a terminal advance
+      # already deleted — if we were already poison-passed, stay passed).
+      HEARTBEAT_SCRIPT = <<~LUA
+        local at_key    = KEYS[1]
+        local epoch_key = KEYS[2]
+        local my        = ARGV[1]
+        local now       = ARGV[2]
+        local my_epoch  = tonumber(ARGV[3] or '0')
+
+        local cur_epoch = tonumber(redis.call('get', epoch_key) or '0')
+        if my_epoch > 0 and my_epoch ~= cur_epoch then
+          return 0
+        end
+
+        if redis.call('hexists', at_key, my) == 1 then
+          redis.call('hset', at_key, my, now)
+          return 1
+        end
+        return 0
+      LUA
+
+      SKIP_SCRIPT = <<~LUA
+        local next_key = KEYS[1]
+        local last_key = KEYS[2]
+        local at_key   = KEYS[3]
+        local fail_key = KEYS[4]
+        local my       = tonumber(ARGV[1])
+
+        -- Drained-batch fence (mirrors CAN_PROCEED/ADVANCE): an ops `skip!` of a
+        -- nonce whose batch already drained must not SET last_key on a missing
+        -- key — KEEPTTL on an absent key would create a TTL-less cursor and
+        -- un-gate the next batch. Nothing to skip in a drained batch anyway.
+        if redis.call('exists', next_key) == 0 and redis.call('exists', last_key) == 0 then
+          return 0
+        end
+
+        local last = tonumber(redis.call('get', last_key) or '0')
+
+        if my > last then
+          -- KEEPTTL: forcing the cursor forward must not strip the sequence TTL
+          -- and leave a persistent key behind for a sequence that never drains.
+          redis.call('set', last_key, my, 'KEEPTTL')
+        end
+        redis.call('hdel', at_key, my)
+
+        last = tonumber(redis.call('get', last_key) or '0')
+        local nxt = tonumber(redis.call('get', next_key) or '0')
+        if last >= nxt and nxt > 0 then
+          redis.call('del', next_key)
+          redis.call('del', last_key)
+          redis.call('del', at_key)
+          redis.call('del', fail_key)
+        end
+        return last
+      LUA
+
+      # Returns `[nonce, epoch]`: the assigned nonce plus the generation it
+      # belongs to. The caller stashes both so later gate/advance calls can be
+      # fenced if the batch drains and its numbers get reused.
+      def ordered_lock_assign(key, ttl: 86_400, now: Time.now.to_i)
+        next_k, last_k, at_k, _fail_k, epoch_k = ordered_lock_keys(key)
+        nonce, epoch = @redis.eval(
+          ASSIGN_SCRIPT, keys: [next_k, last_k, at_k, epoch_k], argv: [now.to_s, ttl]
+        )
+        [nonce.to_i, epoch.to_i]
+      end
+
+      def ordered_lock_can_proceed(key, nonce:, poison_pill_timeout:, epoch: 0, now: Time.now.to_i)
+        state, retry_after, last_completed, first_failed = @redis.eval(
+          CAN_PROCEED_SCRIPT,
+          keys: ordered_lock_keys(key),
+          argv: [nonce.to_i, now.to_i, poison_pill_timeout.to_i, epoch.to_i]
+        )
+        [state.to_s, retry_after.to_i, last_completed.to_i, first_failed.to_i]
+      end
+
+      def ordered_lock_advance(key, nonce:, failed: false, epoch: 0, ttl: 86_400)
+        @redis.eval(
+          ADVANCE_SCRIPT,
+          keys: ordered_lock_keys(key),
+          argv: [nonce.to_i, failed ? 1 : 0, ttl.to_i, epoch.to_i]
+        ).to_i
+      end
+
+      def ordered_lock_skip(key, nonce:)
+        @redis.eval(SKIP_SCRIPT, keys: ordered_lock_keys(key), argv: [nonce.to_i]).to_i
+      end
+
+      # Restamp a running nonce's assigned_at to keep it from being poison-passed
+      # while its steps execute. Returns 1 if restamped, 0 if fenced (stale
+      # epoch) or the timer was already gone. `now` is injectable for testing.
+      def ordered_lock_heartbeat(key, nonce:, epoch: 0, now: Time.now.to_i)
+        _next_k, _last_k, at_k, _fail_k, epoch_k = ordered_lock_keys(key)
+        @redis.eval(
+          HEARTBEAT_SCRIPT, keys: [at_k, epoch_k], argv: [nonce.to_i, now.to_i, epoch.to_i]
+        ).to_i
+      end
+
+      def ordered_lock_reset(key)
+        @redis.del(*ordered_lock_keys(key))
+      end
+
+      def ordered_lock_peek(key)
+        next_k, last_k, at_k, fail_k = ordered_lock_keys(key)
+        next_v = @redis.get(next_k)
+        last_v = @redis.get(last_k)
+        fail_v = @redis.get(fail_k)
+        in_flight = @redis.hkeys(at_k).map(&:to_i).sort
+        {
+          next: next_v ? next_v.to_i : 0,
+          last_completed: last_v ? last_v.to_i : 0,
+          in_flight: in_flight,
+          first_failed: fail_v ? fail_v.to_i : 0
+        }
+      end
+
+      # Order matters: callers destructure positionally and some scripts take a
+      # subset. `epoch` is appended last so existing 4-key destructures keep
+      # working unchanged.
+      def ordered_lock_keys(key)
+        tag = "{#{key}}"
+        [
+          "ordered_lock:#{tag}:next",
+          "ordered_lock:#{tag}:last_completed",
+          "ordered_lock:#{tag}:assigned_at",
+          "ordered_lock:#{tag}:first_failed",
+          "ordered_lock:#{tag}:epoch"
+        ]
+      end
+    end
+  end
+end

data/lib/ruby_reactor/validation/base.rb

@@ -19,7 +19,10 @@ module RubyReactor
 
       def failure(errors)
         error = RubyReactor::Error::InputValidationError.new(errors)
-        RubyReactor.Failure(error)
+        # Carry the structured field errors on the Failure itself so every
+        # validation failure shape (reactor inputs via `run`, step args, step
+        # output) exposes `validation_errors` uniformly.
+        RubyReactor.Failure(error, validation_errors: errors)
       end
     end
   end

data/lib/ruby_reactor/validation/input_validator.rb

@@ -5,14 +5,16 @@ require "dry-validation"
 module RubyReactor
   module Validation
     class InputValidator < Base
-      attr_reader :schema
+      attr_reader :schema, :wrap_key
 
-      def initialize(schema)
+      def initialize(schema, wrap_key: nil)
         super()
         @schema = schema
+        @wrap_key = wrap_key
       end
 
       def call(data)
+        data = { @wrap_key => data } if @wrap_key
         result = schema.call(data)
 
         if result.success?

data/lib/ruby_reactor/validation/schema_builder.rb

@@ -12,6 +12,88 @@ module RubyReactor
       def self.build_contract_from_block(&block)
         Class.new(Dry::Validation::Contract, &block).new
       end
+
+      # Form 1 / 1b — a single named value with an optional type and predicates.
+      #
+      #   build_inline(:age, :integer, false, { gteq?: 18 })
+      #     => required(:age).filled(:integer, gteq?: 18)
+      #   build_inline(:user, User, false, {})
+      #     => required(:user).filled(type?: User)
+      #   build_inline(:bio, :string, true, { max_size?: 100 })
+      #     => optional(:bio).maybe(:string, max_size?: 100)
+      def self.build_inline(name, type, optional, predicates)
+        rules = [[name, type, optional, predicates]]
+        Dry::Schema.Params do
+          SchemaBuilder.apply_inline_rules(self, rules)
+        end
+      end
+
+      # Form 2 — the block receives the macro already bound to the name and
+      # optionality (`required(name)` / `optional(name)`). Because it is invoked
+      # as a block argument (not via instance_eval) the caller's `self` and
+      # lexical scope (class constants, helper methods) stay reachable.
+      def self.build_macro(name, optional, &block)
+        macro_method = optional ? :optional : :required
+        Dry::Schema.Params do
+          block.call(public_send(macro_method, name))
+        end
+      end
+
+      # Compose per-argument inline rules with an optional `validate_args`
+      # input (block or pre-built schema). Block/inline rules are applied first;
+      # a pre-built schema is merged last so its rules win.
+      def self.build_args(inline_rules, validate_input)
+        block = validate_input.is_a?(Proc) ? validate_input : nil
+        prebuilt = !validate_input.nil? && block.nil? ? schema_for(validate_input) : nil
+
+        composed = build_args_base(inline_rules, block)
+
+        if prebuilt && composed
+          composed.merge(prebuilt)
+        elsif prebuilt
+          prebuilt
+        else
+          composed
+        end
+      end
+
+      def self.build_args_base(inline_rules, block)
+        return Dry::Schema.Params(&block) if inline_rules.empty? && block
+        return nil if inline_rules.empty?
+
+        Dry::Schema.Params do
+          SchemaBuilder.apply_inline_rules(self, inline_rules)
+          instance_exec(&block) if block
+        end
+      end
+
+      # Apply a list of inline rules ([name, type, optional, predicates]) onto a
+      # dry-schema DSL context.
+      def self.apply_inline_rules(dsl, rules)
+        rules.each do |name, type, optional, predicates|
+          macro_method = optional ? :optional : :required
+          rule_method  = optional ? :maybe : :filled
+          positional   = type.is_a?(Symbol) ? [type] : []
+          kwargs       = type.is_a?(Module) ? { type?: type, **predicates } : predicates
+
+          macro = dsl.public_send(macro_method, name)
+          if kwargs.empty?
+            macro.public_send(rule_method, *positional)
+          else
+            macro.public_send(rule_method, *positional, **kwargs)
+          end
+        end
+      end
+
+      # Unwrap an InputValidator into its underlying dry-schema; pass dry-schemas
+      # through unchanged.
+      def self.schema_for(schema_or_validator)
+        if schema_or_validator.is_a?(RubyReactor::Validation::InputValidator)
+          schema_or_validator.schema
+        else
+          schema_or_validator
+        end
+      end
     end
   end
 end

data/lib/ruby_reactor/version.rb

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

data/lib/ruby_reactor.rb

@@ -6,6 +6,7 @@ require_relative "ruby_reactor/registry"
 require_relative "ruby_reactor/utils/code_extractor"
 require_relative "ruby_reactor/dsl/lockable" # Add this
 require_relative "ruby_reactor/lock"
+require_relative "ruby_reactor/ordered_lock"
 require_relative "ruby_reactor/semaphore"
 require_relative "ruby_reactor/period"
 require_relative "ruby_reactor/rate_limit"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby_reactor
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.5.2
 platform: ruby
 authors:
 - Artur
@@ -125,6 +125,7 @@ files:
 - lib/ruby_reactor/executor/compensation_manager.rb
 - lib/ruby_reactor/executor/graph_manager.rb
 - lib/ruby_reactor/executor/input_validator.rb
+- lib/ruby_reactor/executor/ordered_lock_support.rb
 - lib/ruby_reactor/executor/result_handler.rb
 - lib/ruby_reactor/executor/retry_manager.rb
 - lib/ruby_reactor/executor/step_executor.rb
@@ -139,8 +140,10 @@ files:
 - lib/ruby_reactor/middleware.rb
 - lib/ruby_reactor/middleware_runner.rb
 - lib/ruby_reactor/open_telemetry.rb
+- lib/ruby_reactor/ordered_lock.rb
 - lib/ruby_reactor/period.rb
 - lib/ruby_reactor/rate_limit.rb
+- lib/ruby_reactor/rate_limit_registry.rb
 - lib/ruby_reactor/reactor.rb
 - lib/ruby_reactor/registry.rb
 - lib/ruby_reactor/retry_context.rb
@@ -148,7 +151,9 @@ files:
 - lib/ruby_reactor/rspec.rb
 - lib/ruby_reactor/rspec/helpers.rb
 - lib/ruby_reactor/rspec/matchers.rb
+- lib/ruby_reactor/rspec/sidekiq_helpers.rb
 - lib/ruby_reactor/rspec/step_executor_patch.rb
+- lib/ruby_reactor/rspec/storage_reset.rb
 - lib/ruby_reactor/rspec/test_subject.rb
 - lib/ruby_reactor/semaphore.rb
 - lib/ruby_reactor/sidekiq_adapter.rb
@@ -162,6 +167,7 @@ files:
 - lib/ruby_reactor/storage/configuration.rb
 - lib/ruby_reactor/storage/redis_adapter.rb
 - lib/ruby_reactor/storage/redis_locking.rb
+- lib/ruby_reactor/storage/redis_ordered_locking.rb
 - lib/ruby_reactor/template/base.rb
 - lib/ruby_reactor/template/dynamic_source.rb
 - lib/ruby_reactor/template/element.rb