cmdx 2.2.0 → 2.4.0

data/lib/cmdx/stores/redis.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module CMDx
+  module Stores
+    # Delegates to a Redis-compatible client (`redis-rb`, `MockRedis`, etc.).
+    # Optional `namespace` prefixes keys when Redis is shared with other 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] optional prefix for every key (trailing `:` added when
+      #   missing; empty string stores logical keys as-is, matching {Memory})
+      def initialize(redis:, namespace: EMPTY_STRING)
+        @redis = redis
+        @namespace = namespace_prefix(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)
+        deleted = @redis.eval(DEL_IF_SCRIPT, keys: [key], argv: [expected.to_s])
+        deleted.to_i.positive?
+      end
+
+      private
+
+      def prefixed(key)
+        "#{@namespace}#{Stores.key!(key)}"
+      end
+
+      def namespace_prefix(namespace)
+        str = namespace.to_s
+        return EMPTY_STRING if str.empty?
+
+        str.end_with?(":") ? str : "#{str}:"
+      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,10 @@
 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`, `rate_limit`,
+  # `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 +20,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 +37,155 @@ 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.disabled
+          end
+
+        @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
+
+        @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
-            Retry.new(exceptions, options, &)
+            @lock_with.build(key || block, options)
           end
+      end
 
-        return @retry_on if exceptions.empty?
+      # 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
 
-        @retry_on = @retry_on.build(exceptions, options, &)
+        @circuit_breaker =
+          if key == false
+            CircuitBreaker.disabled
+          else
+            @circuit_breaker.build(key || block, options)
+          end
+      end
+
+      # Declares a shared rate limit for the task. Builds on the superclass's
+      # {RateLimit}. 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
+      #   limit per task class; other forms resolve a store segment like
+      #   {Idempotency}; `false` disables rate limiting on this class
+      # @param options [Hash{Symbol => Object}] see {RateLimit#initialize}
+      # @option options [Integer] :max (see {RateLimit#initialize})
+      # @option options [Integer] :per (see {RateLimit#initialize})
+      # @option options [Symbol, #call] :limiter (see {RateLimit#initialize})
+      # @option options [Numeric] :cost (see {RateLimit#initialize})
+      # @option options [String] :namespace (see {RateLimit#initialize})
+      # @option options [Symbol] :on_limit (see {RateLimit#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 [RateLimit]
+      # @see RateLimit#process
+      # @see StoreKey.task_key
+      def rate_limit(key = nil, **options, &block)
+        @rate_limit ||=
+          if superclass.respond_to?(:rate_limit)
+            superclass.rate_limit
+          else
+            RateLimit.disabled
+          end
+
+        @rate_limit =
+          if key == false
+            RateLimit.disabled
+          else
+            @rate_limit.build(key || block, options)
+          end
       end
 
       # Reads or extends this class's {Settings}. Inherits from the superclass.
@@ -156,6 +301,16 @@ module CMDx
           end
       end
 
+      # @return [Limiters] cloned from superclass/configuration on first call
+      def limiters
+        @limiters ||=
+          if superclass.respond_to?(:limiters)
+            superclass.limiters.dup
+          else
+            CMDx.configuration.limiters.dup
+          end
+      end
+
       # @return [Deprecators] cloned from superclass/configuration on first call
       def deprecators
         @deprecators ||=
@@ -168,7 +323,7 @@ module CMDx
 
       # Dispatches to the appropriate registry's `register` method.
       #
-      # @param type [:middleware, :callback, :coercion, :validator, :executor, :merger, :retrier, :deprecator, :input, :output]
+      # @param type [:middleware, :callback, :coercion, :validator, :executor, :merger, :retrier, :limiter, :deprecator, :input, :output]
       # @return [Object] the registry's self
       # @raise [ArgumentError] when `type` is unknown
       def register(type, ...)
@@ -187,6 +342,8 @@ module CMDx
           mergers.register(...)
         when :retrier
           retriers.register(...)
+        when :limiter
+          limiters.register(...)
         when :deprecator
           deprecators.register(...)
         when :input
@@ -196,7 +353,7 @@ module CMDx
         else
           raise ArgumentError, <<~MSG.chomp
             unknown registry type #{type.inspect};
-            expected one of [:middleware, :callback, :coercion, :validator, :executor, :merger, :retrier, :deprecator, :input, :output].
+            expected one of [:middleware, :callback, :coercion, :validator, :executor, :merger, :retrier, :limiter, :deprecator, :input, :output].
             See https://drexed.github.io/cmdx/configuration/#registrations-register-deregister
           MSG
         end
@@ -204,7 +361,7 @@ module CMDx
 
       # Dispatches to the appropriate registry's `deregister` method.
       #
-      # @param type [:middleware, :callback, :coercion, :validator, :executor, :merger, :retrier, :deprecator, :input, :output]
+      # @param type [:middleware, :callback, :coercion, :validator, :executor, :merger, :retrier, :limiter, :deprecator, :input, :output]
       # @return [Object] the registry's self
       # @raise [ArgumentError] when `type` is unknown
       def deregister(type, ...)
@@ -223,6 +380,8 @@ module CMDx
           mergers.deregister(...)
         when :retrier
           retriers.deregister(...)
+        when :limiter
+          limiters.deregister(...)
         when :deprecator
           deprecators.deregister(...)
         when :input
@@ -232,7 +391,7 @@ module CMDx
         else
           raise ArgumentError, <<~MSG.chomp
             unknown registry type #{type.inspect};
-            expected one of [:middleware, :callback, :coercion, :validator, :executor, :merger, :retrier, :deprecator, :input, :output].
+            expected one of [:middleware, :callback, :coercion, :validator, :executor, :merger, :retrier, :limiter, :deprecator, :input, :output].
             See https://drexed.github.io/cmdx/configuration/#registrations-register-deregister
           MSG
         end

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,46 @@ 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
+      rate_limit_admitted
+      rate_limit_exceeded
     ].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.4.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)
@@ -120,6 +124,9 @@ require_relative "cmdx/validators/numeric"
 require_relative "cmdx/validators/presence"
 require_relative "cmdx/validators/validate"
 require_relative "cmdx/validators"
+require_relative "cmdx/stores/memory"
+require_relative "cmdx/stores/redis"
+require_relative "cmdx/stores"
 require_relative "cmdx/executors/thread"
 require_relative "cmdx/executors/fiber"
 require_relative "cmdx/executors"
@@ -135,6 +142,9 @@ require_relative "cmdx/retriers/linear"
 require_relative "cmdx/retriers/fibonacci"
 require_relative "cmdx/retriers/decorrelated_jitter"
 require_relative "cmdx/retriers"
+require_relative "cmdx/limiters/fixed_window"
+require_relative "cmdx/limiters/leaky_bucket"
+require_relative "cmdx/limiters"
 require_relative "cmdx/deprecators/log"
 require_relative "cmdx/deprecators/warn"
 require_relative "cmdx/deprecators/error"
@@ -147,7 +157,12 @@ require_relative "cmdx/callbacks"
 require_relative "cmdx/middlewares"
 require_relative "cmdx/telemetry"
 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/rate_limit"
 require_relative "cmdx/deprecation"
 require_relative "cmdx/context"
 require_relative "cmdx/chain"

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

@@ -101,11 +101,21 @@ 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 }
+  #   :rate_limit_admitted   { rate_limit_key:, limiter:, max:, per:, ... }
+  #   :rate_limit_exceeded   { code: :rate_limited, rate_limit_key:, limiter:, on_limit:, ... }
   #
   # Every event also carries: event.cid, event.xid, event.tid, event.task,
   # event.type, event.name, event.root, event.payload, event.timestamp.
@@ -154,6 +164,21 @@ CMDx.configure do |config|
   #   [delay * (2**(attempt - 1)), 30.0].min
   # end)
 
+  # ===========================================================================
+  # Limiters
+  # https://drexed.github.io/cmdx/rate_limit/
+  # ===========================================================================
+  # Limiters decide whether a `rate_limit` declaration admits an execution.
+  # Built-ins: :fixed_window, :leaky_bucket.
+  #
+  # config.limiters.register(:strict, proc do |quota|
+  #   count = CMDx::Stores.incr(quota.store_key, ttl: quota.per)
+  #   admitted = count <= quota.max
+  #   retry_after = admitted ? nil : CMDx::Stores.remaining_ttl(quota.store_key)
+  #
+  #   CMDx::RateLimit::Admission.new(admitted:, count:, level: nil, retry_after:, limiter: :strict)
+  # end)
+
   # ===========================================================================
   # Deprecators
   # https://drexed.github.io/cmdx/deprecation/
@@ -168,6 +193,17 @@ 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)
+  # config.store = CMDx::Stores::Redis.new(redis: Redis.current, namespace: "myapp:cmdx")
+
   # ===========================================================================
   # Executors
   # https://drexed.github.io/cmdx/workflows/#parallel-execution