cmdx 2.2.0 → 2.3.0

data/lib/cmdx/idempotency.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+module CMDx
+  # Declared via {Task.idempotent_by}. After inputs resolve, claims a shared
+  # store slot and runs the `retry_on` loop inside that claim so duplicate
+  # invocations with the same logical key short-circuit before `work` repeats.
+  #
+  # Store keys are `namespace:TaskName:segment` (see {StoreKey.compose}). Values
+  # move `processing` → `completed` after the wrapped block returns (including
+  # output verification when invoked from {Runtime}); the key is deleted on
+  # `StandardError` or non-success signals (`skip!` / `fail!`) so retries can
+  # reclaim.
+  class Idempotency
+
+    PROCESSING = "processing"
+    COMPLETED  = "completed"
+
+    class << self
+
+      # @return [Idempotency] disabled configuration (no key)
+      def disabled
+        DISABLED
+      end
+
+    end
+
+    attr_reader :key
+
+    # @param key [Symbol, String, Proc, #call, nil] segment resolved per task;
+    #   `nil` disables idempotency. Symbols read from `context`; `Proc` /
+    #   blocks are `instance_exec`'d on the task (with `task` as the first
+    #   block argument, same as callbacks); other `#call`ables receive the
+    #   task. Blank segments skip claiming.
+    # @param options [Hash{Symbol => Object}]
+    # @option options [Integer] :ttl (300) expiry in seconds for store entries
+    # @option options [String] :namespace ("cmdx:idem") first segment of the store key
+    # @option options [Symbol] :on_duplicate (:skip) `:skip` or `:fail` when the
+    #   slot is already claimed
+    # @option options [Symbol, Proc, #call] :if gate `(task)` for claiming
+    # @option options [Symbol, Proc, #call] :unless gate `(task)` for claiming
+    def initialize(key, options = EMPTY_HASH)
+      @key     = key
+      @options = options.freeze
+    end
+
+    # @return [String]
+    def namespace
+      @options[:namespace] || "cmdx:idem"
+    end
+
+    # @return [Symbol] `:skip` or `:fail`
+    def on_duplicate
+      @options[:on_duplicate] || :skip
+    end
+
+    # @return [Integer]
+    def ttl
+      @options[:ttl] || 300
+    end
+
+    # @return [Symbol, Proc, #call, nil]
+    def condition_if
+      @options[:if]
+    end
+
+    # @return [Symbol, Proc, #call, nil]
+    def condition_unless
+      @options[:unless]
+    end
+
+    # @return [Boolean]
+    def enabled?
+      !key.nil?
+    end
+
+    # Returns a new Idempotency layering `new_options` onto the current one.
+    # When `new_key` is non-nil it replaces the resolver; when `new_key` is
+    # `nil` and only options change, the existing resolver is kept (option-only
+    # updates such as `idempotent_by ttl: 600`).
+    #
+    # @param new_key [Symbol, String, Proc, #call, nil]
+    # @param new_options [Hash{Symbol => Object}]
+    # @return [Idempotency]
+    def build(new_key, new_options)
+      return self if new_key.nil? && new_options.empty?
+
+      merged_key     = new_key.nil? ? @key : new_key
+      merged_options = @options.merge(new_options)
+
+      self.class.new(merged_key, merged_options)
+    end
+
+    # Runs the given block behind a store claim when {#enabled?} and gates pass.
+    # Releases the claim on `StandardError` or a non-returning exit (`skip!`,
+    # `fail!`) so `retry_on` can run `work` again; marks the slot `completed`
+    # after the block returns successfully.
+    #
+    # @param task [Task]
+    # @yield invoked when the claim succeeds or idempotency is inactive
+    # @yieldreturn [Object] return value from the wrapped work (ignored by callers)
+    # @return [Object] the block's return value
+    # @note On duplicate keys, signals `skip!` or `fail!` on `task` — control
+    #   does not return to the caller of {#process}.
+    # @raise [ArgumentError] when `on_duplicate` is not `:skip` or `:fail`
+    # @raise [IdempotencyError] when the store refuses the `completed` transition
+    def process(task)
+      return yield unless enabled?
+      return yield unless Util.satisfied?(condition_if, condition_unless, task)
+
+      segment = StoreKey.segment(task, key)
+      return yield if segment.nil?
+
+      store_key = StoreKey.compose(namespace, task.class.name, segment)
+
+      if Stores.set(store_key, PROCESSING, nx: true, ttl:)
+        Telemetry.emit(task, :idempotency_claimed, idempotency_key: store_key)
+
+        succeeded = false
+
+        begin
+          yield
+          succeeded = true
+        rescue StandardError
+          Stores.del(store_key)
+          raise
+        ensure
+          Stores.del(store_key) unless succeeded
+        end
+
+        mark_completed!(store_key, task)
+      else
+        duplicate!(task, store_key)
+      end
+    end
+
+    private
+
+    def mark_completed!(store_key, task)
+      if Stores.set(store_key, COMPLETED, xx: true, ttl:)
+        Telemetry.emit(task, :idempotency_completed, idempotency_key: store_key)
+        return
+      end
+
+      Stores.del(store_key)
+      raise IdempotencyError, "failed to mark idempotency key completed (#{store_key})"
+    end
+
+    def duplicate!(task, store_key)
+      state    = Stores.get(store_key)
+      message  = "duplicate request (state=#{state})"
+      metadata = { code: :duplicate, idempotency_key: store_key, state: }
+
+      Telemetry.emit(task, :idempotency_duplicate, **metadata)
+
+      case on_duplicate
+      when :fail
+        task.fail!(message, **metadata)
+      when :skip
+        task.skip!(message, **metadata)
+      else
+        raise ArgumentError, <<~MSG.chomp
+          idempotent_by on_duplicate must be :skip or :fail (got #{on_duplicate.inspect}).
+          See https://drexed.github.io/cmdx/idempotency/
+        MSG
+      end
+    end
+
+    DISABLED = new(nil).freeze
+    private_constant :DISABLED
+
+  end
+end

data/lib/cmdx/lock.rb

@@ -0,0 +1,191 @@
+# frozen_string_literal: true
+
+module CMDx
+  # Declared via {Task.lock_with}. After inputs resolve, acquires a store lease
+  # (`SET` with `nx: true`) and runs idempotency (when declared), the full
+  # `retry_on` loop, and output verification inside that lease.
+  #
+  # Store keys are `namespace:TaskName:segment` (see {StoreKey.compose}). The
+  # stored value is the holding task's `tid`. Release uses a conditional delete so
+  # a late releaser cannot drop a newer holder's lease after TTL expiry.
+  #
+  # After a successful acquire, the lease is released in `ensure` for any exit from
+  # the wrapped block (success, `skip!` / `fail!`, or uncaught error). The lease
+  # is not released between in-process `retry_on` attempts.
+  class Lock
+
+    class << self
+
+      # @return [Lock] disabled configuration (no key)
+      def disabled
+        DISABLED
+      end
+
+    end
+
+    attr_reader :key
+
+    # @param key [Symbol, String, Proc, #call, nil] segment resolved per task;
+    #   `nil` disables locking. Symbols read from `context`; `Proc` / blocks are
+    #   `instance_exec`'d on the task (with `task` as the first block argument,
+    #   same as callbacks); other `#call`ables receive the task. Blank segments
+    #   skip acquiring.
+    # @param options [Hash{Symbol => Object}]
+    # @option options [Integer] :ttl (300) lease expiry in seconds when the holder
+    #   does not release; size for worst-case hold time including the retry loop
+    # @option options [String] :namespace ("cmdx:lock") first segment of the store key
+    # @option options [Numeric, false, nil] :wait (0) max seconds to wait for the
+    #   lease; `0`, `nil`, or `false` try once
+    # @option options [Symbol] :on_busy (:fail) `:skip` or `:fail` when the lease
+    #   cannot be acquired within `:wait`
+    # @option options [Symbol, Proc, #call] :if gate `(task)` for acquiring
+    # @option options [Symbol, Proc, #call] :unless gate `(task)` for acquiring
+    def initialize(key, options = EMPTY_HASH)
+      @key     = key
+      @options = options.freeze
+    end
+
+    # @return [String]
+    def namespace
+      @options[:namespace] || "cmdx:lock"
+    end
+
+    # @return [Integer]
+    def ttl
+      @options[:ttl] || 300
+    end
+
+    # @return [Float]
+    def wait
+      raw = @options[:wait]
+      return 0.0 if raw.nil? || raw == false
+
+      Float(raw)
+    end
+
+    # @return [Symbol] `:skip` or `:fail`
+    def on_busy
+      @options[:on_busy] || :fail
+    end
+
+    # @return [Symbol, Proc, #call, nil]
+    def condition_if
+      @options[:if]
+    end
+
+    # @return [Symbol, Proc, #call, nil]
+    def condition_unless
+      @options[:unless]
+    end
+
+    # @return [Boolean]
+    def enabled?
+      !key.nil?
+    end
+
+    # Returns a new Lock layering `new_options` onto the current one.
+    #
+    # @param new_key [Symbol, String, Proc, #call, nil]
+    # @param new_options [Hash{Symbol => Object}]
+    # @return [Lock]
+    def build(new_key, new_options)
+      return self if new_key.nil? && new_options.empty?
+
+      merged_key     = new_key.nil? ? @key : new_key
+      merged_options = @options.merge(new_options)
+
+      self.class.new(merged_key, merged_options)
+    end
+
+    # Runs the given block behind a store lease when {#enabled?} and gates pass.
+    #
+    # @param task [Task]
+    # @yield invoked when the lease is acquired or locking is inactive
+    # @yieldreturn [Object] return value from the wrapped work
+    # @return [Object] the block's return value
+    # @note When the lease cannot be acquired, signals `skip!` or `fail!` on
+    #   `task` — control does not return to the caller of {#process}. Busy
+    #   metadata may include `:holder` and `:retry_after` when the backend
+    #   exposes the current value and TTL.
+    # @raise [ArgumentError] when `on_busy` is not `:skip` or `:fail`, or `wait`
+    #   is negative
+    def process(task)
+      return yield unless enabled?
+      return yield unless Util.satisfied?(condition_if, condition_unless, task)
+
+      segment = StoreKey.segment(task, key)
+      return yield if segment.nil?
+
+      store_key = StoreKey.compose(namespace, task.class.name, segment)
+      token = task.tid
+
+      if acquire_lock(store_key, token)
+        Telemetry.emit(task, :lock_acquired, lock_key: store_key)
+
+        begin
+          yield
+        ensure
+          release_lock(store_key, token)
+        end
+      else
+        busy!(task, store_key)
+      end
+    end
+
+    private
+
+    def acquire_lock(store_key, token) # rubocop:disable Naming/PredicateMethod -- returns whether the lease was taken
+      wait_seconds = wait
+      raise ArgumentError, "lock_with wait must be >= 0 (got #{wait_seconds})" if wait_seconds.negative?
+
+      deadline = (Util.monotonic_now + wait_seconds if wait_seconds.positive?)
+
+      loop do
+        return true if Stores.set(store_key, token, nx: true, ttl:)
+        return false unless deadline
+
+        break if Util.monotonic_now >= deadline
+
+        sleep_interval = [0.05, deadline - Util.monotonic_now].min
+        Kernel.sleep(sleep_interval) if sleep_interval.positive?
+      end
+
+      false
+    end
+
+    def release_lock(store_key, token)
+      Stores.del_if(store_key, token)
+    end
+
+    def busy!(task, store_key)
+      holder = Stores.get(store_key)
+      retry_after = Stores.remaining_ttl(store_key)
+
+      message = holder ? "lock held" : "lock not acquired"
+      metadata = {
+        code: :busy,
+        lock_key: store_key,
+        holder:,
+        retry_after:
+      }.compact
+
+      Telemetry.emit(task, :lock_busy, **metadata, on_busy:)
+
+      case on_busy
+      when :fail
+        task.fail!(message, **metadata)
+      when :skip
+        task.skip!(message, **metadata)
+      else
+        raise ArgumentError, <<~MSG.chomp
+          lock_with on_busy must be :skip or :fail (got #{on_busy.inspect}).
+          See https://drexed.github.io/cmdx/locks/
+        MSG
+      end
+    end
+
+    DISABLED = new(nil).freeze
+    private_constant :DISABLED
+
+  end
+end

data/lib/cmdx/pipeline.rb

@@ -151,7 +151,7 @@ module CMDx
         new_opts = old_opts.merge(rolled_back: true).freeze
         result.instance_variable_set(:@options, new_opts)
 
-        emit_telemetry(instance, :task_rolled_back)
+        Telemetry.emit(instance, :task_rolled_back, root: false)
 
         begin
           instance.rollback
@@ -166,14 +166,6 @@ module CMDx
       raise first_rollback_error if first_rollback_error
     end
 
-    def emit_telemetry(instance, name, payload = EMPTY_HASH)
-      telemetry = instance.class.telemetry
-      return unless telemetry.subscribed?(name)
-
-      event = Telemetry::Event.build(instance, name, root: false, payload:)
-      telemetry.emit(name, event)
-    end
-
     def aggregate(failures, continue:)
       return if failures.empty?
       return failures.first unless continue

data/lib/cmdx/retry.rb

@@ -4,9 +4,19 @@ module CMDx
   # Configurable retry-on-exception wrapper around a task's `work`. Supports
   # exception list, attempt `:limit`, base `:delay`, `:max_delay` cap, and
   # `:jitter` strategy (symbol, proc, or a configured block). Declared via
-  # `Task.retry_on` and accumulates across inheritance.
+  # {Task.retry_on} and accumulates across inheritance; {Task.retry_on} with
+  # `false` selects {Retry.disabled}.
   class Retry
 
+    class << self
+
+      # @return [Retry] disabled configuration (no exceptions)
+      def disabled
+        DISABLED
+      end
+
+    end
+
     attr_reader :exceptions
 
     # @param exceptions [Array<Class>] exceptions to retry on
@@ -67,6 +77,11 @@ module CMDx
       @options[:jitter] || @block
     end
 
+    # @return [Boolean]
+    def enabled?
+      !exceptions.empty?
+    end
+
     # Sleeps `attempt`'s jittered/bounded delay. No-op when the base delay is zero.
     #
     # Custom jitter callables (registry, task Symbol method, `Proc` / block via
@@ -125,7 +140,7 @@ module CMDx
     # @return [Object] the block's successful return value
     # @raise [Exception] the last caught exception once retries exhaust
     def process(task = nil, &)
-      return yield(0) if exceptions.empty? || !limit.positive?
+      return yield(0) if !enabled? || !limit.positive?
 
       prev_delay = nil
       (limit + 1).times do |attempt|
@@ -148,5 +163,8 @@ module CMDx
       end
     end
 
+    DISABLED = new([], EMPTY_HASH).freeze
+    private_constant :DISABLED
+
   end
 end

data/lib/cmdx/runtime.rb

@@ -3,8 +3,10 @@
 module CMDx
   # Orchestrates a task's full lifecycle: chain acquisition, middlewares,
   # telemetry, deprecation, callbacks, input resolution, `work` (wrapped in
-  # retry), output verification, rollback on failure, result finalization,
-  # and teardown (freeze + chain clear).
+  # {CircuitBreaker}, {Lock}, and {Idempotency} when declared, then {Retry};
+  # output verification runs inside the lock lease and idempotency claim when
+  # enabled),
+  # rollback on failure, result finalization, and teardown (freeze + chain clear).
   #
   # Signal propagation: `work` and the surrounding middleware/callback chain
   # both run inside `catch(Signal::TAG)`, so `success!` / `skip!` / `fail!` /
@@ -49,7 +51,7 @@ module CMDx
       acquire_chain
 
       run_middlewares do
-        emit_telemetry(:task_started)
+        Telemetry.emit(@task, :task_started, root: @root)
         run_deprecation
         run_lifecycle
       end
@@ -84,7 +86,7 @@ module CMDx
 
       deprecation.execute(@task) do
         @deprecated = true
-        emit_telemetry(:task_deprecated)
+        Telemetry.emit(@task, :task_deprecated, root: @root)
       end
     end
 
@@ -127,7 +129,7 @@ module CMDx
         duration: @duration
       ).tap do |result|
         @root ? Chain.current.unshift(result) : Chain.current.push(result)
-        emit_telemetry(:task_executed, result:)
+        Telemetry.emit(@task, :task_executed, root: @root, result:)
         @task.logger.info do
           exclusions = @task.class.settings.log_exclusions
           exclusions.empty? ? result : result.to_h.except(*exclusions)
@@ -146,10 +148,10 @@ module CMDx
     end
 
     def measure_duration
-      start = Process.clock_gettime(Process::CLOCK_MONOTONIC, :float_millisecond)
+      start = Util.monotonic_now(:float_millisecond)
       yield
     ensure
-      @duration = Process.clock_gettime(Process::CLOCK_MONOTONIC, :float_millisecond) - start
+      @duration = Util.monotonic_now(:float_millisecond) - start
     end
 
     def run_callbacks(event)
@@ -170,8 +172,16 @@ module CMDx
     def perform_work
       @signal = catch(Signal::TAG) do
         resolve_inputs!
-        retry_execution { @task.work }
-        verify_outputs!
+
+        circuit_execution do
+          lock_execution do
+            idempotent_execution do
+              retry_execution { @task.work }
+              verify_outputs!
+            end
+          end
+        end
+
         Signal.success(nil, metadata: @task.metadata)
       rescue Fault => e
         Signal.echoed(e.result, cause: e, metadata: @task.metadata)
@@ -186,7 +196,7 @@ module CMDx
       return unless @task.respond_to?(:rollback)
 
       @rolled_back = true
-      emit_telemetry(:task_rolled_back)
+      Telemetry.emit(@task, :task_rolled_back, root: @root)
       @task.rollback
     end
 
@@ -198,10 +208,31 @@ module CMDx
       signal_errors!
     end
 
+    def circuit_execution(&)
+      breaker = @task.class.circuit_breaker
+      return yield unless breaker.enabled?
+
+      breaker.process(@task, &)
+    end
+
+    def lock_execution(&)
+      lock = @task.class.lock_with
+      return yield unless lock.enabled?
+
+      lock.process(@task, &)
+    end
+
+    def idempotent_execution(&)
+      idem = @task.class.idempotent_by
+      return yield unless idem.enabled?
+
+      idem.process(@task, &)
+    end
+
     def retry_execution
       @task.class.retry_on.process(@task) do |attempt|
         @retries = attempt
-        emit_telemetry(:task_retried, attempt:) if attempt.positive?
+        Telemetry.emit(@task, :task_retried, root: @root, attempt:) if attempt.positive?
         yield
       end
 
@@ -222,13 +253,5 @@ module CMDx
       throw(Signal::TAG, Signal.failed(@task.errors.to_s, metadata: @task.metadata))
     end
 
-    def emit_telemetry(name, payload = EMPTY_HASH)
-      telemetry = @task.class.telemetry
-      return unless telemetry.subscribed?(name)
-
-      event = Telemetry::Event.build(@task, name, root: @root, payload:)
-      telemetry.emit(name, event)
-    end
-
   end
 end

data/lib/cmdx/store_key.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module CMDx
+  # Builds colon-separated store keys with the same non-empty coercion as
+  # {Stores.key!}. Used by {Idempotency} (`namespace:TaskName:segment`),
+  # {CircuitBreaker} (`namespace:TaskName` with `:failures` / `:open` suffixes),
+  # {Lock} (`namespace:TaskName:segment`), and other store-backed helpers.
+  module StoreKey
+
+    extend self
+
+    # @param segments [Array<Object>] key segments coerced with {Stores.key!}
+    # @return [String] joined key
+    # @raise [ArgumentError] when any segment is empty after coercion
+    def compose(*segments)
+      segments.filter_map { |s| Stores.key!(s) }.join(":")
+    end
+
+    # Resolves a store key segment from a task. Used by {Idempotency},
+    # {CircuitBreaker}, and other store-backed declarations.
+    #
+    # @param task [Task]
+    # @param resolver [Symbol, String, Proc, #call]
+    # @param skip [Object, nil] when `resolver == skip`, returns `nil` without
+    #   reading context (for example `CircuitBreaker::CLASS_KEY`)
+    # @return [String, nil] non-empty segment, or `nil` when blank or skipped
+    def segment(task, resolver, skip: nil)
+      return if skip && resolver == skip
+
+      raw =
+        case resolver
+        when Symbol
+          task.context[resolver]
+        when Proc
+          task.instance_exec(task, &resolver)
+        else
+          return resolver.call(task) if resolver.respond_to?(:call)
+
+          resolver
+        end
+
+      str = raw&.to_s
+      str if str && !str.empty?
+    end
+
+  end
+end