cmdx 2.3.0 → 2.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3006157f5e5d98af8e442130f87f0427f15868e84e44db171c1f620d0f606ef5
-  data.tar.gz: 92e7a594a9ef6b4367bfbeb3fc71b807d7d495d9e977007af8a28b498c0730d9
+  metadata.gz: 140f9e96a60ea339e1fd9c95d26e4d06569a1286deab7cfa9851d97c84f69184
+  data.tar.gz: 2923f0db4e2bc30849fb703e9b614610d1b75361b944ab845b98bf41c2ad1d4f
 SHA512:
-  metadata.gz: 33ab98bd8eaa2d36c5f01cc790bb09ed644a1f4a01cd561545333c83059cfb1656f9349e684920f2377a99e8fe0fd5409f9e6199e8966358718f37c560cef911
-  data.tar.gz: 5276f8e49a7697ce9fca44f64d7bc393429b8e75636f3e8b5865a9388f14f6e96aa9c039f7c3e4efa583e9d7d5c0097a845ca4878dfd73e6a74ea76e1e5b72cf
+  metadata.gz: f2c85ae86fcc8f920e9685a2a9a99c00f16f794ffec743fed1b3def2355e1058b20b763ea03347a8d8a7e15d52211f661a3b33580043f1a1354f878c0205c1b6
+  data.tar.gz: 7b4396cf1ed6d3e5eadb2cb388c5ac01c8f5c8874b9d8ca6b0e0539f18c19081447555fa21d178def486248c17756b88150cece92d1c92411e80bc2d778f30a6

data/CHANGELOG.md

@@ -6,7 +6,17 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## UNRELEASED
 
-## [2.3.0] - UNRELEASED
+## [2.4.0] - 2026-10-22
+
+### Added
+- `Task.rate_limit` — admission control via `CMDx::Stores` once per `execute` (retries do not consume extra quota); built-in `:fixed_window` and `:leaky_bucket` limiters with `CMDx::Limiters` registry (register custom strategies globally or with `register :limiter`); `on_limit:` `:fail` / `:skip`, `if` / `unless` gates; runs after input resolution and before `circuit_breaker` in `Runtime`
+- Telemetry events `:rate_limit_admitted` and `:rate_limit_exceeded` for rate-limited tasks (gated by `Telemetry#subscribed?` like other store-backed helpers)
+
+### Changed
+- `Stores::Redis` — default `namespace` is now `""` so Redis keys match logical store keys (for example `cmdx:idem:MyTask:segment`); set `namespace` explicitly when sharing a Redis instance with non-CMDx data (previously defaulted to `cmdx:store`)
+- Move integration recipes from `examples/` into published docs under `docs/cookbook/` with a dedicated **Cookbook** site tab
+
+## [2.3.0] - 2026-10-20
 
 ### Added
 - `Task.lock_with` — distributed lease via `CMDx::Stores` so only one worker runs the same logical key at a time; optional `wait:` polling, `on_busy:` `:fail` / `:skip`, and `if` / `unless` gates; wraps `idempotent_by` and the `retry_on` loop in `Runtime`; pass `false` on a subclass to disable

data/lib/cmdx/circuit_breaker.rb

@@ -5,13 +5,12 @@ module CMDx
   # store counters before the `retry_on` loop; opens after repeated failures
   # and short-circuits until `cool_off` elapses.
   #
-  # Store keys are `namespace:TaskName` or `namespace:TaskName:segment`, with
+  # Store keys come from {StoreKey.task_key} with `class_scoped: true`, plus
   # `:failures` and `:open` suffix segments (see {StoreKey.compose}).
   class CircuitBreaker
 
-    OPEN      = "open"
-    FAILURES  = "failures"
-    CLASS_KEY = :class
+    OPEN     = "open"
+    FAILURES = "failures"
 
     class << self
 
@@ -101,7 +100,7 @@ module CMDx
 
       merged_key =
         if new_key.nil?
-          enabled? || new_options.empty? ? @key : CLASS_KEY
+          enabled? || new_options.empty? ? @key : StoreKey::CLASS_KEY
         else
           new_key
         end
@@ -125,11 +124,11 @@ module CMDx
       return yield unless enabled?
       return yield unless Util.satisfied?(condition_if, condition_unless, task)
 
-      base = store_base(task)
-      return yield if base.nil?
+      store_key = StoreKey.task_key(task, namespace:, resolver: key, class_scoped: true)
+      return yield if store_key.nil?
 
-      open_key     = StoreKey.compose(base, OPEN)
-      failures_key = StoreKey.compose(base, FAILURES)
+      open_key     = StoreKey.compose(store_key, OPEN)
+      failures_key = StoreKey.compose(store_key, FAILURES)
       open!(task, open_key) if circuit_open?(open_key)
 
       begin
@@ -144,18 +143,6 @@ module CMDx
 
     private
 
-    def store_base(task)
-      segment = StoreKey.segment(task, key, skip: CLASS_KEY)
-
-      if segment.nil?
-        return StoreKey.compose(namespace, task.class.name) if key == CLASS_KEY
-
-        return nil
-      end
-
-      StoreKey.compose(namespace, task.class.name, segment)
-    end
-
     def circuit_open?(open_key)
       Stores.get(open_key)
     rescue StandardError

data/lib/cmdx/configuration.rb

@@ -10,7 +10,7 @@ module CMDx
   class Configuration
 
     attr_accessor :middlewares, :callbacks, :coercions, :validators, :executors,
-      :mergers, :retriers, :deprecators, :telemetry, :store, :correlation_id, :default_locale,
+      :mergers, :retriers, :limiters, :deprecators, :telemetry, :store, :correlation_id, :default_locale,
       :strict_context, :backtrace_cleaner, :log_exclusions, :log_formatter,
       :log_level, :logger
 
@@ -22,6 +22,7 @@ module CMDx
       @executors   = Executors.new
       @mergers     = Mergers.new
       @retriers    = Retriers.new
+      @limiters    = Limiters.new
       @deprecators = Deprecators.new
       @telemetry   = Telemetry.new
       @store       = Stores::Memory.new
@@ -86,6 +87,7 @@ module CMDx
       @executors
       @mergers
       @retriers
+      @limiters
       @deprecators
       @telemetry
     ].freeze

data/lib/cmdx/idempotency.rb

@@ -75,8 +75,9 @@ module CMDx
 
     # 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`).
+    # `nil`, only options merge and the existing resolver is kept. A disabled
+    # config stays disabled when only options are passed (a key is still required
+    # to enable).
     #
     # @param new_key [Symbol, String, Proc, #call, nil]
     # @param new_options [Hash{Symbol => Object}]
@@ -84,7 +85,7 @@ module CMDx
     def build(new_key, new_options)
       return self if new_key.nil? && new_options.empty?
 
-      merged_key     = new_key.nil? ? @key : new_key
+      merged_key = new_key.nil? ? @key : new_key
       merged_options = @options.merge(new_options)
 
       self.class.new(merged_key, merged_options)
@@ -107,10 +108,8 @@ module CMDx
       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)
+      store_key = StoreKey.task_key(task, namespace:, resolver: key)
+      return yield if store_key.nil?
 
       if Stores.set(store_key, PROCESSING, nx: true, ttl:)
         Telemetry.emit(task, :idempotency_claimed, idempotency_key: store_key)
@@ -159,7 +158,7 @@ module CMDx
         task.skip!(message, **metadata)
       else
         raise ArgumentError, <<~MSG.chomp
-          idempotent_by on_duplicate must be :skip or :fail (got #{on_duplicate.inspect}).
+          idempotent_by on_duplicate must be :fail or :skip (got #{on_duplicate.inspect}).
           See https://drexed.github.io/cmdx/idempotency/
         MSG
       end

data/lib/cmdx/limiters/fixed_window.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module CMDx
+  class Limiters
+    # Fixed-window counter using {Stores.incr} with TTL refresh on each hit.
+    #
+    # @api private
+    module FixedWindow
+
+      extend self
+
+      # @param quota [RateLimit::Quota]
+      # @return [RateLimit::Admission]
+      def call(quota)
+        count       = Stores.incr(quota.store_key, ttl: quota.per)
+        admitted    = count <= quota.max.to_i
+        retry_after = admitted ? nil : Stores.remaining_ttl(quota.store_key)
+
+        RateLimit::Admission.new(
+          admitted:,
+          count:,
+          level: nil,
+          retry_after:,
+          limiter: :fixed_window
+        )
+      end
+
+    end
+  end
+end

data/lib/cmdx/limiters/leaky_bucket.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module CMDx
+  class Limiters
+    # Continuous leaky bucket backed by a single store key (`store_key:lb`).
+    # Leaks one unit every `per` seconds; admits when `level + cost <= max`.
+    #
+    # @api private
+    module LeakyBucket
+
+      extend self
+
+      # @param quota [RateLimit::Quota]
+      # @return [RateLimit::Admission]
+      def call(quota)
+        state_key = "#{quota.store_key}:lb"
+        now       = Time.now.to_f
+        level, last_at = parse_state(Stores.get(state_key), now)
+
+        leaked = (now - last_at) / quota.per
+        if leaked.positive?
+          level -= leaked
+          level = 0.0 if level.negative?
+        end
+
+        cost      = quota.cost
+        capacity  = quota.max
+        projected = level + cost
+        admitted  = projected <= capacity
+
+        level = projected if admitted
+
+        Stores.set(state_key, "#{level}:#{now}", ttl: bucket_ttl(quota))
+
+        retry_after =
+          unless admitted
+            overflow = projected - capacity
+            overflow = 0 if overflow.negative?
+            (overflow * quota.per).ceil
+          end
+
+        RateLimit::Admission.new(
+          admitted:,
+          count: nil,
+          level:,
+          retry_after:,
+          limiter: :leaky_bucket
+        )
+      end
+
+      private
+
+      def parse_state(raw, now)
+        return [0.0, now] if raw.nil? || raw.empty?
+
+        sep = raw.index(":")
+        unless sep
+          level = Float(raw, exception: false) || 0.0
+          return [level, now]
+        end
+
+        level   = Float(raw[0, sep], exception: false) || 0.0
+        last_at = Float(raw[(sep + 1)..], exception: false) || now
+        [level, last_at]
+      end
+
+      def bucket_ttl(quota)
+        base = quota.max * quota.per
+        ttl = base.positive? ? base * 2 : quota.per * 2
+        ttl.to_i
+      end
+
+    end
+  end
+end

data/lib/cmdx/limiters.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module CMDx
+  # Registry of named rate-limit strategies used by {RateLimit}. Ships with
+  # `:fixed_window` and `:leaky_bucket`. A limiter is any callable accepting
+  # a {RateLimit::Quota} and returning a {RateLimit::Admission}.
+  class Limiters
+
+    attr_reader :registry
+
+    def initialize
+      @registry = {
+        fixed_window: Limiters::FixedWindow,
+        leaky_bucket: Limiters::LeakyBucket
+      }
+    end
+
+    # @param source [Limiters] registry to duplicate
+    # @return [void]
+    def initialize_copy(source)
+      @registry = source.registry.dup
+    end
+
+    # Registers a named limiter, overwriting any existing entry.
+    #
+    # @param name [Symbol]
+    # @param callable [#call, nil] pass either this or a block
+    # @param block [#call, nil] limiter callable when `callable` is omitted
+    # @yieldparam quota [RateLimit::Quota]
+    # @yieldreturn [RateLimit::Admission]
+    # @return [Limiters] self for chaining
+    # @raise [ArgumentError] when both `callable` and a block are given, or
+    #   when the resolved limiter isn't callable
+    def register(name, callable = nil, &block)
+      limiter = callable || block
+
+      if callable && block
+        raise ArgumentError, "limiter: provide either a callable or a block, not both"
+      elsif !limiter.respond_to?(:call)
+        raise ArgumentError, <<~MSG.chomp
+          limiter must respond to #call (got #{limiter.class}).
+          See https://drexed.github.io/cmdx/rate_limit/#custom-limiters-via-the-limiters-registry
+        MSG
+      end
+
+      registry[name.to_sym] = limiter
+      self
+    end
+
+    # @param name [Symbol]
+    # @return [Limiters] self for chaining
+    def deregister(name)
+      registry.delete(name)
+      self
+    end
+
+    # @param name [Symbol]
+    # @return [Boolean] whether a limiter is registered under `name`
+    def key?(name)
+      registry.key?(name)
+    end
+
+    # @param name [Symbol]
+    # @return [#call] the registered limiter
+    # @raise [UnknownEntryError] when `name` isn't registered
+    def lookup(name)
+      registry[name] || begin
+        raise UnknownEntryError, <<~MSG.chomp
+          unknown limiter #{name.inspect}; registered: #{registry.keys.inspect}.
+          See https://drexed.github.io/cmdx/rate_limit/#built-in-limiters
+        MSG
+      end
+    end
+
+    # Resolves a `:limiter` spec to a concrete callable.
+    #
+    # @param spec [Symbol, #call, nil]
+    # @return [#call, nil]
+    # @raise [UnknownEntryError] when `spec` is an unknown symbol or not callable
+    def resolve(spec)
+      case spec
+      when NilClass
+        nil
+      when Symbol
+        lookup(spec)
+      else
+        return spec if spec.respond_to?(:call)
+
+        raise UnknownEntryError, <<~MSG.chomp
+          unknown limiter #{spec.inspect}; expected a Symbol from #{registry.keys.inspect} or a callable.
+          See https://drexed.github.io/cmdx/rate_limit/#built-in-limiters
+        MSG
+      end
+    end
+
+    # @return [Boolean]
+    def empty?
+      registry.empty?
+    end
+
+    # @return [Integer]
+    def size
+      registry.size
+    end
+
+  end
+end

data/lib/cmdx/lock.rb

@@ -83,7 +83,9 @@ module CMDx
       !key.nil?
     end
 
-    # Returns a new Lock layering `new_options` onto the current one.
+    # Returns a new Lock layering `new_options` onto the current one. When
+    # `new_key` is non-nil it replaces the resolver; when `new_key` is `nil`,
+    # only options merge and the existing resolver is kept.
     #
     # @param new_key [Symbol, String, Proc, #call, nil]
     # @param new_options [Hash{Symbol => Object}]
@@ -91,7 +93,7 @@ module CMDx
     def build(new_key, new_options)
       return self if new_key.nil? && new_options.empty?
 
-      merged_key     = new_key.nil? ? @key : new_key
+      merged_key = new_key.nil? ? @key : new_key
       merged_options = @options.merge(new_options)
 
       self.class.new(merged_key, merged_options)
@@ -113,10 +115,9 @@ module CMDx
       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.task_key(task, namespace:, resolver: key)
+      return yield if store_key.nil?
 
-      store_key = StoreKey.compose(namespace, task.class.name, segment)
       token = task.tid
 
       if acquire_lock(store_key, token)
@@ -178,7 +179,7 @@ module CMDx
         task.skip!(message, **metadata)
       else
         raise ArgumentError, <<~MSG.chomp
-          lock_with on_busy must be :skip or :fail (got #{on_busy.inspect}).
+          lock_with on_busy must be :fail or :skip (got #{on_busy.inspect}).
           See https://drexed.github.io/cmdx/locks/
         MSG
       end

data/lib/cmdx/rate_limit.rb

@@ -0,0 +1,244 @@
+# frozen_string_literal: true
+
+module CMDx
+  # Declared via {Task.rate_limit}. After inputs resolve, consults a shared
+  # limiter once per execution (retries do not consume additional quota) and
+  # short-circuits before the circuit breaker when the bucket is full.
+  #
+  # Store keys come from {StoreKey.task_key} with `class_scoped: true` — either
+  # `namespace:TaskName` for `{StoreKey::CLASS_KEY}` (`:class`) or
+  # `namespace:TaskName:segment` when a resolver yields a segment.
+  class RateLimit
+
+    # Limiter decision for one admission attempt.
+    #
+    # Built-in limiters set `count` for `:fixed_window` and `level` for
+    # `:leaky_bucket`; custom strategies may populate either or both. Omitted
+    # fields are stripped from telemetry and result metadata via `compact`.
+    #
+    # @attr admitted [Boolean] whether the run may proceed
+    # @attr count [Integer, nil] counter after increment (`:fixed_window`)
+    # @attr level [Float, nil] bucket fill after leak math (`:leaky_bucket`)
+    # @attr retry_after [Integer, nil] seconds until retry might succeed
+    # @attr limiter [Symbol, #call] strategy name or callable identity
+    Admission = Data.define(:admitted, :count, :level, :retry_after, :limiter) do
+      # @return [Boolean] same as `admitted`
+      def admitted?
+        admitted
+      end
+    end
+
+    # Inputs for a limiter callable (`CMDx::Limiters` or `limiter:` `Proc`).
+    #
+    # @attr task [Task] task being admitted
+    # @attr store_key [String] base store key (limiters may append suffixes)
+    # @attr max [Integer] capacity or window max from the declaration
+    # @attr per [Integer] window or leak interval in seconds
+    # @attr cost [Numeric] units charged when admitted (`:leaky_bucket`)
+    # @attr limiter [Symbol, #call] resolved strategy spec
+    # @attr options [Hash{Symbol => Object}] frozen declaration options
+    Quota = Data.define(:task, :store_key, :max, :per, :cost, :limiter, :options)
+
+    class << self
+
+      # @return [RateLimit] disabled configuration (no key)
+      def disabled
+        DISABLED
+      end
+
+    end
+
+    attr_reader :key
+
+    # @param key [Symbol, String, Proc, #call, nil] `:class`, context `Symbol`,
+    #   static `String`, or callable; `nil` disables rate limiting
+    # @param options [Hash{Symbol => Object}]
+    # @option options [Integer] :max maximum admissions per window or bucket capacity
+    # @option options [Integer] :per window length in seconds (`:fixed_window`) or
+    #   seconds to leak one unit (`:leaky_bucket`)
+    # @option options [Symbol, #call] :limiter (`:fixed_window`, `:leaky_bucket`, or custom)
+    # @option options [Numeric] :cost (1) units charged per admitted execution
+    # @option options [String] :namespace ("cmdx:rl") first segment of store keys
+    # @option options [Symbol] :on_limit (:fail) `:fail` or `:skip` when over limit
+    # @option options [Symbol, Proc, #call] :if gate `(task)` before checking
+    # @option options [Symbol, Proc, #call] :unless gate `(task)` before checking
+    def initialize(key, options = EMPTY_HASH)
+      @key     = key
+      @options = options.freeze
+    end
+
+    # @return [String]
+    def namespace
+      @options[:namespace] || "cmdx:rl"
+    end
+
+    # @return [Integer, nil]
+    def max
+      @options[:max]
+    end
+
+    # @return [Integer, nil]
+    def per
+      @options[:per]
+    end
+
+    # @return [Symbol]
+    def limiter
+      @options[:limiter] || :fixed_window
+    end
+
+    # @return [Numeric]
+    def cost
+      raw = @options[:cost]
+      return 1 if raw.nil?
+
+      Float(raw)
+    end
+
+    # @return [Symbol] `:fail` or `:skip`
+    def on_limit
+      @options[:on_limit] || :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 RateLimit layering `new_options` onto the current one.
+    #
+    # @param new_key [Symbol, String, Proc, #call, nil]
+    # @param new_options [Hash{Symbol => Object}]
+    # @return [RateLimit]
+    def build(new_key, new_options)
+      return self if new_key.nil? && new_options.empty?
+
+      merged_key =
+        if new_key.nil?
+          enabled? || new_options.empty? ? @key : StoreKey::CLASS_KEY
+        else
+          new_key
+        end
+      merged_options = @options.merge(new_options)
+
+      self.class.new(merged_key, merged_options)
+    end
+
+    # Runs the limiter once, then yields when admitted or inactive.
+    #
+    # @param task [Task]
+    # @yield invoked when admitted or rate limiting is inactive
+    # @yieldreturn [Object] return value from the wrapped work
+    # @return [Object] the block's return value
+    # @note When over limit, signals `skip!` or `fail!` on `task` — control does
+    #   not return to the caller of {#process}.
+    # @raise [ArgumentError] when `max` / `per` are missing or invalid, or
+    #   `on_limit` is not `:fail` or `:skip`
+    def process(task)
+      return yield unless enabled?
+      return yield unless Util.satisfied?(condition_if, condition_unless, task)
+
+      store_key = StoreKey.task_key(task, namespace:, resolver: key, class_scoped: true)
+      return yield if store_key.nil?
+
+      quota = Quota.new(
+        task:,
+        store_key:,
+        max: Integer(max),
+        per: Integer(per),
+        cost:,
+        limiter:,
+        options: @options
+      )
+
+      admission = invoke_limiter(task, quota)
+      if admission.admitted?
+        admitted!(task, store_key, admission, quota)
+        yield
+      else
+        exceeded!(task, store_key, admission, quota)
+      end
+    end
+
+    private
+
+    def invoke_limiter(task, quota)
+      callable =
+        if limiter.is_a?(Proc)
+          ->(q) { task.instance_exec(q, &limiter) }
+        else
+          limiters_registry(task).resolve(limiter)
+        end
+
+      callable.call(quota)
+    end
+
+    def limiters_registry(task)
+      if task.class.respond_to?(:limiters)
+        task.class.limiters
+      else
+        CMDx.configuration.limiters
+      end
+    end
+
+    def admitted!(task, store_key, admission, quota)
+      payload = admission_payload(store_key, admission, quota)
+
+      Telemetry.emit(task, :rate_limit_admitted, **payload)
+    end
+
+    def exceeded!(task, store_key, admission, quota)
+      message  = exceeded_message(admission, quota)
+      metadata = admission_payload(store_key, admission, quota).merge(code: :rate_limited)
+
+      Telemetry.emit(task, :rate_limit_exceeded, **metadata, on_limit:)
+
+      case on_limit
+      when :fail
+        task.fail!(message, **metadata)
+      when :skip
+        task.skip!(message, **metadata)
+      else
+        raise ArgumentError, <<~MSG.chomp
+          rate_limit on_limit must be :fail or :skip (got #{on_limit.inspect}).
+          See https://drexed.github.io/cmdx/rate_limit/
+        MSG
+      end
+    end
+
+    def exceeded_message(admission, quota)
+      parts = ["rate limited"]
+      parts << "#{admission.count}/#{quota.max}" if admission.count
+      parts << "level=#{admission.level}" if admission.level
+      parts << "per #{quota.per}s"
+      parts << "(#{quota.limiter})"
+      parts.join(" ")
+    end
+
+    def admission_payload(store_key, admission, quota)
+      {
+        rate_limit_key: store_key,
+        limiter: admission.limiter,
+        max: quota.max,
+        per: quota.per,
+        count: admission.count,
+        level: admission.level,
+        retry_after: admission.retry_after
+      }.compact
+    end
+
+    DISABLED = new(nil).freeze
+    private_constant :DISABLED
+
+  end
+end

data/lib/cmdx/runtime.rb

@@ -3,10 +3,10 @@
 module CMDx
   # Orchestrates a task's full lifecycle: chain acquisition, middlewares,
   # telemetry, deprecation, callbacks, input resolution, `work` (wrapped in
-  # {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).
+  # {RateLimit}, {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!` /
@@ -173,11 +173,13 @@ module CMDx
       @signal = catch(Signal::TAG) do
         resolve_inputs!
 
-        circuit_execution do
-          lock_execution do
-            idempotent_execution do
-              retry_execution { @task.work }
-              verify_outputs!
+        rate_limit_execution do
+          circuit_execution do
+            lock_execution do
+              idempotent_execution do
+                retry_execution { @task.work }
+                verify_outputs!
+              end
             end
           end
         end
@@ -208,6 +210,13 @@ module CMDx
       signal_errors!
     end
 
+    def rate_limit_execution(&)
+      limit = @task.class.rate_limit
+      return yield unless limit.enabled?
+
+      limit.process(@task, &)
+    end
+
     def circuit_execution(&)
       breaker = @task.class.circuit_breaker
       return yield unless breaker.enabled?

data/lib/cmdx/store_key.rb

@@ -1,19 +1,26 @@
 # 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.
+  # Shared store key helpers for store-backed task features ({Idempotency},
+  # {CircuitBreaker}, {Lock}, {RateLimit}, and others).
+  #
+  # {compose} joins colon-separated segments, each coerced with {Stores.key!}.
+  # {segment} resolves a per-invocation suffix from a declaration (symbol,
+  # proc, callable, or literal).
   module StoreKey
 
     extend self
 
+    # Resolver for one breaker or limiter per task class (see {CircuitBreaker},
+    # {RateLimit}). Not used for segment-required features ({Idempotency},
+    # {Lock}).
+    CLASS_KEY = :class
+
     # @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(":")
+      segments.map! { |s| Stores.key!(s) }.join(":")
     end
 
     # Resolves a store key segment from a task. Used by {Idempotency},
@@ -22,7 +29,7 @@ module CMDx
     # @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`)
+    #   reading context (for example {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
@@ -43,5 +50,29 @@ module CMDx
       str if str && !str.empty?
     end
 
+    # Builds the base store key for a task invocation.
+    #
+    # @param task [Task]
+    # @param namespace [String]
+    # @param resolver [Symbol, String, Proc, #call]
+    # @param class_scoped [Boolean] when true, {CLASS_KEY} (`:class`) resolves to
+    #   `namespace:TaskName` without reading context; blank segments for other
+    #   resolvers return `nil` instead of raising
+    # @return [String, nil] full key, or `nil` when the segment is blank
+    # @see RateLimit#process
+    # @see CircuitBreaker#process
+    def task_key(task, namespace:, resolver:, class_scoped: false)
+      skip = class_scoped ? CLASS_KEY : nil
+      segment_value = segment(task, resolver, skip:)
+
+      if segment_value.nil?
+        return compose(namespace, task.class.name) if class_scoped && resolver == CLASS_KEY
+
+        return nil
+      end
+
+      compose(namespace, task.class.name, segment_value)
+    end
+
   end
 end

data/lib/cmdx/stores/memory.rb

@@ -16,6 +16,7 @@ module CMDx
       # @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
@@ -77,6 +78,7 @@ module CMDx
       # @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
@@ -122,6 +124,7 @@ module CMDx
       # @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
@@ -132,11 +135,11 @@ module CMDx
       # @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
+          return false unless entry[:value] == expected.to_s
 
           @entries.delete(key)
           true

data/lib/cmdx/stores/redis.rb

@@ -3,7 +3,7 @@
 module CMDx
   module Stores
     # Delegates to a Redis-compatible client (`redis-rb`, `MockRedis`, etc.).
-    # Keys are prefixed to avoid collisions with unrelated application data.
+    # 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
@@ -17,10 +17,11 @@ module CMDx
       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")
+      # @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.end_with?(":") ? namespace : "#{namespace}:"
+        @namespace = namespace_prefix(namespace)
       end
 
       # @param key [String, Symbol]
@@ -95,8 +96,7 @@ module CMDx
       # @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 = @redis.eval(DEL_IF_SCRIPT, keys: [key], argv: [expected.to_s])
         deleted.to_i.positive?
       end
 
@@ -106,6 +106,13 @@ module CMDx
         "#{@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/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`, `idempotent_by`, `lock_with`, `circuit_breaker`, `deprecation`,
-  # and `settings`.
+  # `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,
@@ -150,6 +151,43 @@ module CMDx
           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.
       #
       # @param options [Hash{Symbol => Object}] merged onto the current settings
@@ -263,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 ||=
@@ -275,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, ...)
@@ -294,6 +342,8 @@ module CMDx
           mergers.register(...)
         when :retrier
           retriers.register(...)
+        when :limiter
+          limiters.register(...)
         when :deprecator
           deprecators.register(...)
         when :input
@@ -303,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
@@ -311,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, ...)
@@ -330,6 +380,8 @@ module CMDx
           mergers.deregister(...)
         when :retrier
           retriers.deregister(...)
+        when :limiter
+          limiters.deregister(...)
         when :deprecator
           deprecators.deregister(...)
         when :input
@@ -339,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

@@ -40,6 +40,8 @@ module CMDx
       circuit_open
       circuit_tripped
       circuit_reset
+      rate_limit_admitted
+      rate_limit_exceeded
     ].freeze
 
     class << self

data/lib/cmdx/version.rb

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

data/lib/cmdx.rb

@@ -124,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"
@@ -139,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"
@@ -150,15 +156,13 @@ 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/rate_limit"
 require_relative "cmdx/deprecation"
 require_relative "cmdx/context"
 require_relative "cmdx/chain"

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

@@ -114,6 +114,8 @@ CMDx.configure do |config|
   #   :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.
@@ -162,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/
@@ -184,7 +201,8 @@ CMDx.configure do |config|
   # 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")
+  # config.store = CMDx::Stores::Redis.new(redis: Redis.current)
+  # config.store = CMDx::Stores::Redis.new(redis: Redis.current, namespace: "myapp:cmdx")
 
   # ===========================================================================
   # Executors

data/mkdocs.yml

@@ -128,34 +128,61 @@ plugins:
           - outcomes/states.md: Execution lifecycle states (initialized, executing, complete, interrupted)
           - outcomes/statuses.md: Business outcome statuses (success, skipped, failed) and transitions
           - outcomes/errors.md: Structured per-attribute error container accumulated during input/output verification and exposed on result.errors
-        Attributes:
+        Contracts:
           - inputs/definitions.md: Attribute declarations (required/optional), validation, and type coercion
           - inputs/naming.md: Customizing accessor method names with prefixes and suffixes
           - inputs/coercions.md: Automatic type conversion for inputs (string to integer, date parsing, etc.)
           - inputs/validations.md: Input validation rules (presence, length, format, numeric, inclusion, exclusion)
           - inputs/defaults.md: Default values for optional inputs (static, dynamic, callable)
           - inputs/transformations.md: Value transformation after coercion but before validation
-        Features:
+          - outputs.md: Declaring expected context outputs that must be set after task execution
+        Hooks:
           - callbacks.md: Execution lifecycle callbacks (before_execution, on_success, on_failure, etc.)
           - middlewares.md: Cross-cutting concerns wrapping task execution (authentication, caching, timeouts)
-          - logging.md: Structured logging with multiple formatters (JSON, KeyValue, Logstash, Line, Raw)
-          - internationalization.md: Multi-language support for error messages and validations (90+ locales)
-          - retries.md: Automatic retry functionality for transient failures with jitter and selective retries
+        Composition:
+          - workflows.md: Composing multiple tasks into sequential pipelines with conditional execution
+          - deprecation.md: Managing deprecated tasks with logging, warnings, or execution prevention
+        Resilience:
+          - stores.md: Shared key/value store for idempotency, rate limits, locks, and cross-worker coordination
+          - locks.md: Single-flight leases via Stores so concurrent workers do not run the same logical work
           - idempotency.md: Preventing duplicate execution for retried jobs and webhooks with idempotent_by
+          - rate_limit.md: Admission control per window with fixed-window and leaky-bucket limiters
           - circuit_breaker.md: Automatic circuit breaking for failing dependencies with threshold, cool-off, and window options
-          - stores.md: Shared key/value store for idempotency, rate limits, and cross-worker coordination
-          - deprecation.md: Managing deprecated tasks with logging, warnings, or execution prevention
-          - outputs.md: Declaring expected context outputs that must be set after task execution
-          - workflows.md: Composing multiple tasks into sequential pipelines with conditional execution
-        More:
+          - retries.md: Automatic retry functionality for transient failures with jitter and selective retries
+        Observability:
+          - logging.md: Structured logging with multiple formatters (JSON, KeyValue, Logstash, Line, Raw)
+          - internationalization.md: Multi-language support for error messages and validations (90+ locales)
+        Adoption:
           - testing.md: Best practices for testing CMDx tasks and workflows with RSpec
           - tips_and_tricks.md: Best practices, patterns, and techniques for maintainable CMDx applications
           - comparison.md: Comparison with other command/service object frameworks
           - v2-migration.md: Migration guide from CMDx 1.x to 2.0
+        Ecosystem:
+          - ecosystem.md: Satellite gems (cmdx-i18n, cmdx-rspec)
+        References:
+          - references.md: API docs, llms.txt exports, and repository AI skills
+        Cookbook:
+          - cookbook/index.md: Integration recipes for jobs, Rails, auth, observability, and more
+        "Cookbook: Rails and Active Record":
+          - cookbook/active_record_database_transaction.md: Wrap task work in an Active Record transaction
+          - cookbook/active_record_query_tagging.md: Tag SQL queries with task metadata
+          - cookbook/paper_trail_whatdunnit.md: Paper Trail attribution for running tasks
+        "Cookbook: API and integration":
+          - cookbook/graphql_resolvers.md: Resolve GraphQL fields with CMDx tasks
+          - cookbook/openapi_schema_generation.md: Generate OpenAPI schemas from task inputs
+          - cookbook/pub_sub_task_chaining.md: Chain tasks from pub/sub events
+        "Cookbook: Cross-cutting concerns":
+          - cookbook/background_execution.md: Run tasks via Active Job or Sidekiq
+          - cookbook/store_wrappers.md: Test doubles and instrumented store wrappers
+          - cookbook/flipper_feature_flags.md: Gate tasks behind Flipper feature flags
+          - cookbook/pundit_authorization.md: Authorize tasks with Pundit before work runs
+          - cookbook/timeout_guard.md: Bound task execution time with a timeout guard
+          - cookbook/sentry_error_tracking.md: Report CMDx faults to Sentry
+          - cookbook/opentelemetry_tracing.md: Distributed tracing for task execution
 nav:
   - Home: index.md
   - Documentation:
-    - Getting Started: getting_started.md
+    - Getting started: getting_started.md
     - Configuration: configuration.md
     - Basics:
       - Setup: basics/setup.md
@@ -171,40 +198,61 @@ nav:
       - States: outcomes/states.md
       - Statuses: outcomes/statuses.md
       - Errors: outcomes/errors.md
-    - Inputs:
+    - Contracts:
       - Definitions: inputs/definitions.md
       - Naming: inputs/naming.md
       - Coercions: inputs/coercions.md
       - Validations: inputs/validations.md
       - Defaults: inputs/defaults.md
       - Transformations: inputs/transformations.md
-    - Features:
+      - Outputs: outputs.md
+    - Hooks:
       - Callbacks: callbacks.md
       - Middlewares: middlewares.md
-      - Logging: logging.md
-      - Internationalization: internationalization.md
-      - Retries: retries.md
-      - Idempotency: idempotency.md
+    - Composition:
+      - Workflows: workflows.md
+      - Deprecation: deprecation.md
+    - Resilience:
+      - Stores: stores.md
       - Locks: locks.md
+      - Idempotency: idempotency.md
+      - Rate limit: rate_limit.md
       - Circuit breaker: circuit_breaker.md
-      - Stores: stores.md
-      - Deprecation: deprecation.md
-      - Outputs: outputs.md
-      - Workflows: workflows.md
-    - More:
+      - Retries: retries.md
+    - Observability:
+      - Logging: logging.md
+      - Internationalization: internationalization.md
+    - Adoption:
       - Testing: testing.md
-      - Tips and Tricks: tips_and_tricks.md
+      - Tips and tricks: tips_and_tricks.md
       - Comparison: comparison.md
       - v1 → v2 Migration: v2-migration.md
-      - Examples: https://github.com/drexed/cmdx/blob/main/examples/index.md
+    - Ecosystem:
+      - cmdx-i18n: https://github.com/drexed/cmdx-i18n
+      - cmdx-rspec: https://github.com/drexed/cmdx-rspec
     - References:
       - API Documentation: https://drexed.github.io/cmdx/api/index.html
       - llms.txt: https://drexed.github.io/cmdx/llms.txt
       - llms-full.txt: https://drexed.github.io/cmdx/llms-full.txt
       - AI Skills: https://github.com/drexed/cmdx/blob/main/skills
-    - Ecosystem:
-      - cmdx-i18n: https://github.com/drexed/cmdx-i18n
-      - cmdx-rspec: https://github.com/drexed/cmdx-rspec
+  - Cookbook:
+    - Overview: cookbook/index.md
+    - Rails and Active Record:
+      - Active Record Database Transaction: cookbook/active_record_database_transaction.md
+      - Active Record Query Tagging: cookbook/active_record_query_tagging.md
+      - Paper Trail Whatdunnit: cookbook/paper_trail_whatdunnit.md
+    - API and integration:
+      - GraphQL Resolvers: cookbook/graphql_resolvers.md
+      - OpenAPI Schema Generation: cookbook/openapi_schema_generation.md
+      - PubSub Task Chaining: cookbook/pub_sub_task_chaining.md
+    - Cross-cutting concerns:
+      - Background Execution: cookbook/background_execution.md
+      - Store Wrappers: cookbook/store_wrappers.md
+      - Flipper Feature Flags: cookbook/flipper_feature_flags.md
+      - Pundit Authorization: cookbook/pundit_authorization.md
+      - Timeout Guard: cookbook/timeout_guard.md
+      - Sentry Error Tracking: cookbook/sentry_error_tracking.md
+      - OpenTelemetry Tracing: cookbook/opentelemetry_tracing.md
   - Blog: blog/index.md
 
 extra:

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cmdx
 version: !ruby/object:Gem::Version
-  version: 2.3.0
+  version: 2.4.0
 platform: ruby
 authors:
 - Juan Gomez
@@ -241,6 +241,9 @@ files:
 - lib/cmdx/idempotency.rb
 - lib/cmdx/input.rb
 - lib/cmdx/inputs.rb
+- lib/cmdx/limiters.rb
+- lib/cmdx/limiters/fixed_window.rb
+- lib/cmdx/limiters/leaky_bucket.rb
 - lib/cmdx/lock.rb
 - lib/cmdx/log_formatters/json.rb
 - lib/cmdx/log_formatters/key_value.rb
@@ -257,6 +260,7 @@ files:
 - lib/cmdx/outputs.rb
 - lib/cmdx/pipeline.rb
 - lib/cmdx/railtie.rb
+- lib/cmdx/rate_limit.rb
 - lib/cmdx/result.rb
 - lib/cmdx/retriers.rb
 - lib/cmdx/retriers/bounded_random.rb