cmdx 2.1.1 → 2.3.0

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,17 +148,18 @@ 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)
       callbacks = @task.class.callbacks
       return if callbacks.empty?
 
-      callbacks.process(event, @task)
+      signal = Callbacks::POST_WORK_EVENTS.include?(event) ? @signal : nil
+      callbacks.process(event, @task, signal)
     end
 
     def run_around(event, &)
@@ -169,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)
@@ -185,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
 
@@ -197,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
 
@@ -221,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

data/lib/cmdx/stores/memory.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+module CMDx
+  module Stores
+    # Process-local key/value store with optional per-key TTL. Thread-safe via
+    # an internal mutex. Suitable for tests and single-process dev; not shared
+    # across workers.
+    class Memory
+
+      def initialize
+        @mutex = Mutex.new
+        @entries = {}
+      end
+
+      # @param key [String, Symbol]
+      # @return [String, nil] stored value, or `nil` when missing or expired
+      def get(key)
+        key = Stores.key!(key)
+        @mutex.synchronize do
+          entry = @entries[key]
+          return unless entry
+          return if expired?(entry)
+
+          entry[:value]
+        end
+      end
+
+      # @param key [String, Symbol]
+      # @param value [#to_s]
+      # @param ttl [Integer, nil] seconds until expiry (`nil` = no expiry)
+      # @param nx [Boolean] set only when the key is absent
+      # @param xx [Boolean] set only when the key is present
+      # @return [Boolean] whether the value was written
+      # @raise [ArgumentError] when `nx` and `xx` are both true, or `ttl` is invalid
+      def set(key, value, ttl: nil, nx: false, xx: false)
+        key = Stores.key!(key)
+        ttl = Stores.ttl!(ttl) if ttl
+        Stores.nx_xx!(nx, xx)
+
+        expires_at = ttl ? Util.monotonic_now + ttl : nil
+        @mutex.synchronize do
+          entry = @entries[key]
+          present = entry && !expired?(entry)
+
+          return false if nx && present
+          return false if xx && !present
+
+          @entries[key] = { value: value.to_s, expires_at: }
+          true
+        end
+      end
+
+      # @param key [String, Symbol]
+      # @param ttl [Integer, nil] when set, refreshes expiry on every increment
+      # @return [Integer] value after increment
+      # @raise [ArgumentError] when `ttl` is invalid
+      def incr(key, ttl: nil)
+        key = Stores.key!(key)
+        ttl = Stores.ttl!(ttl) if ttl
+
+        @mutex.synchronize do
+          entry = @entries[key]
+          if entry && expired?(entry)
+            @entries.delete(key)
+            entry = nil
+          end
+
+          count = entry ? entry[:value].to_i + 1 : 1
+          expires_at = (Util.monotonic_now + ttl if ttl)
+
+          @entries[key] = { value: count.to_s, expires_at: }
+          count
+        end
+      end
+
+      # @param key [String, Symbol]
+      # @return [Integer, nil] whole seconds until expiry, or `nil` when missing or expired
+      def ttl(key)
+        key = Stores.key!(key)
+        @mutex.synchronize do
+          entry = @entries[key]
+          return unless entry
+          return if expired?(entry)
+
+          expires_at = entry[:expires_at]
+          return unless expires_at
+
+          remaining = expires_at - Util.monotonic_now
+          remaining.positive? ? remaining.ceil : nil
+        end
+      end
+
+      # @param key [String, Symbol]
+      # @return [Integer] value after decrement (floors at `0`, removing the key)
+      # @raise [ArgumentError] when `ttl` is invalid (only when `ttl` is passed)
+      def decr(key, ttl: nil)
+        key = Stores.key!(key)
+        Stores.ttl!(ttl) if ttl
+
+        @mutex.synchronize do
+          entry = @entries[key]
+          if entry && expired?(entry)
+            @entries.delete(key)
+            entry = nil
+          end
+
+          count = entry ? entry[:value].to_i : 0
+          count = count.positive? ? count - 1 : 0
+          expires_at = entry&.fetch(:expires_at, nil)
+
+          if count.zero?
+            @entries.delete(key)
+          else
+            @entries[key] = { value: count.to_s, expires_at: }
+          end
+
+          count
+        end
+      end
+
+      # @param key [String, Symbol]
+      # @return [Integer] `1` when a key was removed, `0` otherwise
+      def del(key)
+        key = Stores.key!(key)
+        @mutex.synchronize do
+          @entries.delete(key) ? 1 : 0
+        end
+      end
+
+      # @param key [String, Symbol]
+      # @param expected [#to_s]
+      # @return [Boolean] whether the key was removed
+      def del_if(key, expected)
+        key = Stores.key!(key)
+        expected = expected.to_s
+        @mutex.synchronize do
+          entry = @entries[key]
+          return false unless entry && !expired?(entry)
+          return false unless entry[:value] == expected
+
+          @entries.delete(key)
+          true
+        end
+      end
+
+      private
+
+      def expired?(entry)
+        expires_at = entry[:expires_at]
+        expires_at && Util.monotonic_now >= expires_at
+      end
+
+    end
+  end
+end