cmdx 2.2.0 → 2.3.0

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

data/lib/cmdx/stores/redis.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module CMDx
+  module Stores
+    # Delegates to a Redis-compatible client (`redis-rb`, `MockRedis`, etc.).
+    # Keys are prefixed to avoid collisions with unrelated application data.
+    #
+    # The client must respond to `get`, `set`, `incr`, `expire`, `ttl`, `del`, and `eval`.
+    class Redis
+
+      DEL_IF_SCRIPT = <<~LUA
+        if redis.call('GET', KEYS[1]) == ARGV[1] then
+          return redis.call('DEL', KEYS[1])
+        else
+          return 0
+        end
+      LUA
+
+      # @param redis [#get, #set, #incr, #expire, #del, #eval] backing client
+      # @param namespace [String] prepended to every key (trailing `:` added when missing)
+      def initialize(redis:, namespace: "cmdx:store")
+        @redis = redis
+        @namespace = namespace.end_with?(":") ? namespace : "#{namespace}:"
+      end
+
+      # @param key [String, Symbol]
+      # @return [String, nil]
+      def get(key)
+        @redis.get(prefixed(key))
+      end
+
+      # @param key [String, Symbol]
+      # @param value [#to_s]
+      # @param ttl [Integer, nil]
+      # @param nx [Boolean]
+      # @param xx [Boolean]
+      # @return [Boolean]
+      # @raise [ArgumentError] when `nx` and `xx` are both true, or `ttl` is invalid
+      def set(key, value, ttl: nil, nx: false, xx: false) # rubocop:disable Naming/PredicateMethod -- Redis SET contract
+        key = prefixed(key)
+        ttl = Stores.ttl!(ttl) if ttl
+        Stores.nx_xx!(nx, xx)
+
+        options = {}
+        options[:ex] = ttl if ttl
+        options[:nx] = true if nx
+        options[:xx] = true if xx
+
+        if options.empty?
+          @redis.set(key, value.to_s)
+          true
+        else
+          !!@redis.set(key, value.to_s, **options)
+        end
+      end
+
+      # @param key [String, Symbol]
+      # @param ttl [Integer, nil]
+      # @return [Integer]
+      # @raise [ArgumentError] when `ttl` is invalid
+      def incr(key, ttl: nil)
+        key = prefixed(key)
+        ttl = Stores.ttl!(ttl) if ttl
+
+        count = @redis.incr(key)
+        @redis.expire(key, ttl) if ttl
+        count
+      end
+
+      # @param key [String, Symbol]
+      # @return [Integer, nil] seconds until expiry, or `nil` when missing or expired
+      def ttl(key)
+        key = prefixed(key)
+        seconds = @redis.ttl(key)
+        seconds if seconds.is_a?(Integer) && seconds.positive?
+      end
+
+      # @param key [String, Symbol]
+      # @return [Integer]
+      def decr(key, ttl: nil)
+        key = prefixed(key)
+        Stores.ttl!(ttl) if ttl
+
+        @redis.decr(key)
+      end
+
+      # @param key [String, Symbol]
+      # @return [Integer]
+      def del(key)
+        @redis.del(prefixed(key))
+      end
+
+      # @param key [String, Symbol]
+      # @param expected [#to_s]
+      # @return [Boolean] whether the key was removed
+      def del_if(key, expected) # rubocop:disable Naming/PredicateMethod -- store delete contract
+        key = prefixed(key)
+        expected = expected.to_s
+        deleted = @redis.eval(DEL_IF_SCRIPT, keys: [key], argv: [expected])
+        deleted.to_i.positive?
+      end
+
+      private
+
+      def prefixed(key)
+        "#{@namespace}#{Stores.key!(key)}"
+      end
+
+    end
+  end
+end

data/lib/cmdx/stores.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module CMDx
+  # Key/value scratch space for idempotency keys, locks, rate limits, circuit breakers,
+  # checkpoints, and cached results. {Stores} delegates to
+  # {Configuration#store}; swap the configured backend (for example
+  # {Stores::Memory} or {Stores::Redis}) at boot.
+  module Stores
+
+    extend self
+
+    # @param key [String, Symbol]
+    # @return [String, nil] stored value, or `nil` when missing or expired
+    # @raise [ArgumentError] when `key` is blank
+    # @see Configuration#store
+    def get(key)
+      CMDx.configuration.store.get(key)
+    end
+
+    # @param key [String, Symbol]
+    # @param value [#to_s]
+    # @param ttl [Integer, nil]
+    # @param nx [Boolean]
+    # @param xx [Boolean]
+    # @return [Boolean] whether the value was written
+    # @raise [ArgumentError] when `key` is blank, `ttl` is invalid, or `nx` and `xx` are both true
+    def set(key, value, ttl: nil, nx: false, xx: false)
+      CMDx.configuration.store.set(key, value, ttl:, nx:, xx:)
+    end
+
+    # @param key [String, Symbol]
+    # @param ttl [Integer, nil] when set, refreshes expiry on every increment
+    # @return [Integer] value after increment
+    # @raise [ArgumentError] when `key` is blank or `ttl` is invalid
+    def incr(key, ttl: nil)
+      CMDx.configuration.store.incr(key, ttl:)
+    end
+
+    # @param key [String, Symbol]
+    # @param ttl [Integer, nil] unused; accepted for API symmetry with {#incr}
+    # @return [Integer] value after decrement
+    # @raise [ArgumentError] when `key` is blank
+    def decr(key, ttl: nil)
+      CMDx.configuration.store.decr(key, ttl:)
+    end
+
+    # @param key [String, Symbol]
+    # @return [Integer] `1` when a key was removed, `0` otherwise
+    # @raise [ArgumentError] when `key` is blank
+    def del(key)
+      CMDx.configuration.store.del(key)
+    end
+
+    # @param key [String, Symbol]
+    # @param expected [#to_s] value that must match the stored string for deletion
+    # @return [Boolean] whether the key was removed
+    # @raise [ArgumentError] when `key` is blank
+    # @raise [NotImplementedError] when the configured store does not implement {#del_if}
+    def del_if(key, expected)
+      store = CMDx.configuration.store
+      raise NotImplementedError, "store must implement del_if(key, expected) for lock release" unless store.respond_to?(:del_if)
+
+      store.del_if(key, expected)
+    end
+
+    # @param key [String, Symbol]
+    # @return [Integer, nil] seconds until expiry when the backend supports
+    #   {#ttl}; `nil` when the key is missing, expired, or TTL is unavailable
+    # @raise [ArgumentError] when `key` is blank
+    def remaining_ttl(key)
+      store = CMDx.configuration.store
+      return unless store.respond_to?(:ttl)
+
+      seconds = store.ttl(key)
+      seconds if seconds.is_a?(Integer) && seconds.positive?
+    end
+
+    # @param key [String, Symbol]
+    # @return [String]
+    # @raise [ArgumentError] when `key` is blank
+    # @api private
+    def key!(key)
+      str = key.to_s
+      raise ArgumentError, "store key must be non-empty" if str.empty?
+
+      str
+    end
+
+    # @param ttl [Integer]
+    # @return [Integer]
+    # @raise [ArgumentError] when `ttl` is not a positive Integer
+    # @api private
+    def ttl!(ttl)
+      return ttl if ttl.is_a?(Integer) && ttl.positive?
+
+      raise ArgumentError, "store ttl must be a positive Integer (got #{ttl.inspect})"
+    end
+
+    # @param nx [Boolean]
+    # @param xx [Boolean]
+    # @return [void]
+    # @raise [ArgumentError] when both flags are true
+    # @api private
+    def nx_xx!(nx, xx)
+      return unless nx && xx
+
+      raise ArgumentError, "store set cannot use nx and xx together"
+    end
+
+  end
+end

data/lib/cmdx/task.rb

@@ -3,8 +3,9 @@
 module CMDx
   # Base class for all units of work. Subclasses override `#work` and
   # declare their contract via `required`, `optional`, `output`, `callbacks`,
-  # `retry_on`, `deprecation`, and `settings`. Invoked via {.execute} (safe)
-  # or {.execute!} (strict, raises on failure).
+  # `retry_on`, `idempotent_by`, `lock_with`, `circuit_breaker`, `deprecation`,
+  # and `settings`.
+  # Invoked via {.execute} (safe) or {.execute!} (strict, raises on failure).
   #
   # Inheritance: every registry accessor (middlewares, callbacks, coercions,
   # validators, executors, mergers, telemetry, inputs, outputs) lazily clones from the
@@ -18,9 +19,11 @@ module CMDx
     class << self
 
       # Declares exceptions to retry on. Builds on the superclass's `Retry`.
-      # Passing no exceptions returns the current (possibly inherited) Retry.
+      # Passing no exceptions and no options returns the current (possibly
+      # inherited) Retry. Pass `false` to disable retries on this class.
       #
-      # @param exceptions [Array<Class>]
+      # @param exceptions [Array<Class, false>] exception classes; `false` alone
+      #   disables retries on this class
       # @param options [Hash{Symbol => Object}] see {Retry#initialize}
       # @option options [Integer] :limit (see {Retry#initialize})
       # @option options [Float] :delay (see {Retry#initialize})
@@ -33,14 +36,118 @@ module CMDx
       def retry_on(*exceptions, **options, &)
         @retry_on ||=
           if superclass.respond_to?(:retry_on)
-            superclass.retry_on.build(exceptions, options, &)
+            superclass.retry_on
           else
-            Retry.new(exceptions, options, &)
+            Retry.disabled
           end
 
-        return @retry_on if exceptions.empty?
+        @retry_on =
+          if exceptions == [false]
+            Retry.disabled
+          else
+            @retry_on.build(exceptions, options, &)
+          end
+      end
+
+      # Declares a stable idempotency key from context (or a callable). Builds on
+      # the superclass's {Idempotency}. Passing no `key` and no options returns the
+      # current (possibly inherited) configuration. Pass `false` to disable.
+      #
+      # @param key [Symbol, String, Proc, #call, false, nil] context key or
+      #   resolver; `false` disables idempotency on this class
+      # @param options [Hash{Symbol => Object}] see {Idempotency#initialize}
+      # @option options [Integer] :ttl (see {Idempotency#initialize})
+      # @option options [String] :namespace (see {Idempotency#initialize})
+      # @option options [Symbol] :on_duplicate (see {Idempotency#initialize})
+      # @option options [Symbol, Proc, #call] :if gate `(task)` for claiming
+      # @option options [Symbol, Proc, #call] :unless gate `(task)` for claiming
+      # @yieldparam task [Task] optional first argument when the block is
+      #   `instance_exec`'d (same as callbacks)
+      # @return [Idempotency]
+      # @see Idempotency#process
+      def idempotent_by(key = nil, **options, &block)
+        @idempotent_by ||=
+          if superclass.respond_to?(:idempotent_by)
+            superclass.idempotent_by
+          else
+            Idempotency.disabled
+          end
 
-        @retry_on = @retry_on.build(exceptions, options, &)
+        @idempotent_by =
+          if key == false
+            Idempotency.disabled
+          else
+            @idempotent_by.build(key || block, options)
+          end
+      end
+
+      # Declares a distributed lock from context (or a callable). Builds on the
+      # superclass's {Lock}. Passing no `key` and no options returns the current
+      # (possibly inherited) configuration. Pass `false` to disable.
+      #
+      # @param key [Symbol, String, Proc, #call, false, nil] context key or
+      #   resolver; `false` disables locking on this class
+      # @param options [Hash{Symbol => Object}] see {Lock#initialize}
+      # @option options [Integer] :ttl (see {Lock#initialize})
+      # @option options [String] :namespace (see {Lock#initialize})
+      # @option options [Numeric, false, nil] :wait (see {Lock#initialize})
+      # @option options [Symbol] :on_busy (see {Lock#initialize})
+      # @option options [Symbol, Proc, #call] :if gate `(task)` for acquiring
+      # @option options [Symbol, Proc, #call] :unless gate `(task)` for acquiring
+      # @yieldparam task [Task] optional first argument when the block is
+      #   `instance_exec`'d (same as callbacks)
+      # @return [Lock]
+      # @see Lock#process
+      def lock_with(key = nil, **options, &block)
+        @lock_with ||=
+          if superclass.respond_to?(:lock_with)
+            superclass.lock_with
+          else
+            Lock.disabled
+          end
+
+        @lock_with =
+          if key == false
+            Lock.disabled
+          else
+            @lock_with.build(key || block, options)
+          end
+      end
+
+      # Declares a shared circuit breaker for the task. Builds on the
+      # superclass's {CircuitBreaker}. Passing no `key` and no options returns the
+      # current (possibly inherited) configuration. Pass `false` to disable.
+      #
+      # @param key [Symbol, String, Proc, #call, false, nil] `:class` scopes one
+      #   breaker per task class; other forms resolve a store segment like
+      #   {Idempotency}; `false` disables the breaker on this class
+      # @param options [Hash{Symbol => Object}] see {CircuitBreaker#initialize}
+      # @option options [Integer] :threshold (see {CircuitBreaker#initialize})
+      # @option options [Integer] :cool_off (see {CircuitBreaker#initialize})
+      # @option options [Integer] :window (see {CircuitBreaker#initialize})
+      # @option options [String] :namespace (see {CircuitBreaker#initialize})
+      # @option options [Symbol] :on_open (see {CircuitBreaker#initialize})
+      # @option options [Array<Class>] :on (see {CircuitBreaker#initialize})
+      # @option options [Symbol, Proc, #call] :if gate `(task)` before checking
+      # @option options [Symbol, Proc, #call] :unless gate `(task)` before checking
+      # @yieldparam task [Task] optional first argument when the block is
+      #   `instance_exec`'d (same as callbacks)
+      # @return [CircuitBreaker]
+      # @see CircuitBreaker#process
+      def circuit_breaker(key = nil, **options, &block)
+        @circuit_breaker ||=
+          if superclass.respond_to?(:circuit_breaker)
+            superclass.circuit_breaker
+          else
+            CircuitBreaker.disabled
+          end
+
+        @circuit_breaker =
+          if key == false
+            CircuitBreaker.disabled
+          else
+            @circuit_breaker.build(key || block, options)
+          end
       end
 
       # Reads or extends this class's {Settings}. Inherits from the superclass.

data/lib/cmdx/telemetry.rb

@@ -1,9 +1,10 @@
 # frozen_string_literal: true
 
 module CMDx
-  # Pub/sub for runtime lifecycle events (see {EVENTS}). Subscribers are
-  # callables receiving an {Event} data object. Runtime emits events only when
-  # subscribers are registered so telemetry has zero cost when unused.
+  # Pub/sub for runtime lifecycle and infrastructure events (see {EVENTS}).
+  # Subscribers are callables receiving an {Event} data object. {emit}
+  # dispatches only when subscribers are registered so telemetry has zero cost
+  # when unused.
   class Telemetry
 
     # Immutable event payload passed to subscribers.
@@ -23,15 +24,44 @@ module CMDx
       end
     end
 
-    # Lifecycle event names Runtime emits.
+    # Lifecycle and infrastructure event names the runtime and store-backed
+    # helpers emit.
     EVENTS = %i[
       task_started
       task_deprecated
       task_retried
       task_rolled_back
       task_executed
+      lock_acquired
+      lock_busy
+      idempotency_claimed
+      idempotency_completed
+      idempotency_duplicate
+      circuit_open
+      circuit_tripped
+      circuit_reset
     ].freeze
 
+    class << self
+
+      # Dispatches `payload` when `task`'s telemetry registry has subscribers
+      # for `name`. No-op when nothing is subscribed.
+      #
+      # @param task [Task]
+      # @param name [Symbol] one of {EVENTS}
+      # @param root [Boolean] whether this task started the active chain
+      # @param payload [Hash{Symbol => Object}] extra fields merged into the event payload
+      # @return [void]
+      def emit(task, name, root: false, **payload)
+        telemetry = task.class.telemetry
+        return unless telemetry.subscribed?(name)
+
+        event = Event.build(task, name, root:, payload:)
+        telemetry.emit(name, event)
+      end
+
+    end
+
     attr_reader :registry
 
     def initialize

data/lib/cmdx/util.rb

@@ -69,6 +69,13 @@ module CMDx
         unless?(condition_unless, receiver, *args)
     end
 
+    # Returns the current time in seconds since the process started.
+    #
+    # @return [Float]
+    def monotonic_now(unit = :float_second)
+      Process.clock_gettime(Process::CLOCK_MONOTONIC, unit)
+    end
+
     # Recursively merges two Hash-like trees. When both values at a key are
     # Hashes, they merge recursively; otherwise the right-hand value wins
     # (last-write-wins). When either top-level operand is not a Hash, returns

data/lib/cmdx/version.rb

@@ -3,6 +3,6 @@
 module CMDx
 
   # Gem version. Bumped on release; mirrored in the gemspec.
-  VERSION = "2.2.0"
+  VERSION = "2.3.0"
 
 end

data/lib/cmdx.rb

@@ -49,6 +49,10 @@ module CMDx
   # continuation, which would otherwise silently skip the task body.
   CallbackError = Class.new(Error)
 
+  # Raised when the idempotency store refuses to transition the key from
+  # `processing` to `completed`.
+  IdempotencyError = Class.new(Error)
+
   # Raised when a task or workflow attempts to define an input where an
   # accessor with the same name already exists.
   DefinitionError = Class.new(Error)
@@ -146,8 +150,15 @@ require_relative "cmdx/outputs"
 require_relative "cmdx/callbacks"
 require_relative "cmdx/middlewares"
 require_relative "cmdx/telemetry"
+require_relative "cmdx/stores/memory"
+require_relative "cmdx/stores/redis"
+require_relative "cmdx/stores"
 require_relative "cmdx/settings"
+require_relative "cmdx/store_key"
 require_relative "cmdx/retry"
+require_relative "cmdx/idempotency"
+require_relative "cmdx/lock"
+require_relative "cmdx/circuit_breaker"
 require_relative "cmdx/deprecation"
 require_relative "cmdx/context"
 require_relative "cmdx/chain"

data/lib/generators/cmdx/templates/install.rb

@@ -101,11 +101,19 @@ CMDx.configure do |config|
   # fires if nobody's listening, so unused events cost nothing.
   #
   # Events and their extra payload keys:
-  #   :task_started      {}
-  #   :task_deprecated   {}
-  #   :task_retried      { attempt: Integer }
-  #   :task_rolled_back  {}
-  #   :task_executed     { result: CMDx::Result }
+  #   :task_started          {}
+  #   :task_deprecated       {}
+  #   :task_retried          { attempt: Integer }
+  #   :task_rolled_back      {}
+  #   :task_executed         { result: CMDx::Result }
+  #   :lock_acquired         { lock_key: String }
+  #   :lock_busy             { code: :busy, lock_key:, holder:, retry_after:, on_busy: }
+  #   :idempotency_claimed   { idempotency_key: String }
+  #   :idempotency_completed { idempotency_key: String }
+  #   :idempotency_duplicate { code: :duplicate, idempotency_key:, state: }
+  #   :circuit_open          { code: :circuit_open, circuit_breaker_key:, retry_after:, on_open: }
+  #   :circuit_tripped       { circuit_breaker_key:, failures_key:, failure_count:, threshold:, cool_off: }
+  #   :circuit_reset         { failures_key: String }
   #
   # Every event also carries: event.cid, event.xid, event.tid, event.task,
   # event.type, event.name, event.root, event.payload, event.timestamp.
@@ -168,6 +176,16 @@ CMDx.configure do |config|
   #   Bugsnag.notify("Deprecated task invoked: #{task.class.name}")
   # end)
 
+  # ===========================================================================
+  # Store
+  # https://drexed.github.io/cmdx/configuration/#store
+  # ===========================================================================
+  # Shared key/value scratch space (`CMDx::Stores.get/set/incr/del`) for
+  # idempotency keys, rate limits, and similar cross-request state. Defaults to
+  # an in-memory adapter; point at Redis in production.
+  #
+  # config.store = CMDx::Stores::Redis.new(redis: Redis.current, namespace: "cmdx:store")
+
   # ===========================================================================
   # Executors
   # https://drexed.github.io/cmdx/workflows/#parallel-execution