cmdx 2.2.0 → 2.4.0

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/retry.rb

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

data/lib/cmdx/runtime.rb

@@ -3,8 +3,10 @@
 module CMDx
   # Orchestrates a task's full lifecycle: chain acquisition, middlewares,
   # telemetry, deprecation, callbacks, input resolution, `work` (wrapped in
-  # retry), output verification, rollback on failure, result finalization,
-  # and teardown (freeze + chain clear).
+  # {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!` /
@@ -49,7 +51,7 @@ module CMDx
       acquire_chain
 
       run_middlewares do
-        emit_telemetry(:task_started)
+        Telemetry.emit(@task, :task_started, root: @root)
         run_deprecation
         run_lifecycle
       end
@@ -84,7 +86,7 @@ module CMDx
 
       deprecation.execute(@task) do
         @deprecated = true
-        emit_telemetry(:task_deprecated)
+        Telemetry.emit(@task, :task_deprecated, root: @root)
       end
     end
 
@@ -127,7 +129,7 @@ module CMDx
         duration: @duration
       ).tap do |result|
         @root ? Chain.current.unshift(result) : Chain.current.push(result)
-        emit_telemetry(:task_executed, result:)
+        Telemetry.emit(@task, :task_executed, root: @root, result:)
         @task.logger.info do
           exclusions = @task.class.settings.log_exclusions
           exclusions.empty? ? result : result.to_h.except(*exclusions)
@@ -146,10 +148,10 @@ module CMDx
     end
 
     def measure_duration
-      start = Process.clock_gettime(Process::CLOCK_MONOTONIC, :float_millisecond)
+      start = Util.monotonic_now(:float_millisecond)
       yield
     ensure
-      @duration = Process.clock_gettime(Process::CLOCK_MONOTONIC, :float_millisecond) - start
+      @duration = Util.monotonic_now(:float_millisecond) - start
     end
 
     def run_callbacks(event)
@@ -170,8 +172,18 @@ module CMDx
     def perform_work
       @signal = catch(Signal::TAG) do
         resolve_inputs!
-        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
+
         Signal.success(nil, metadata: @task.metadata)
       rescue Fault => e
         Signal.echoed(e.result, cause: e, metadata: @task.metadata)
@@ -186,7 +198,7 @@ module CMDx
       return unless @task.respond_to?(:rollback)
 
       @rolled_back = true
-      emit_telemetry(:task_rolled_back)
+      Telemetry.emit(@task, :task_rolled_back, root: @root)
       @task.rollback
     end
 
@@ -198,10 +210,38 @@ 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?
+
+      breaker.process(@task, &)
+    end
+
+    def lock_execution(&)
+      lock = @task.class.lock_with
+      return yield unless lock.enabled?
+
+      lock.process(@task, &)
+    end
+
+    def idempotent_execution(&)
+      idem = @task.class.idempotent_by
+      return yield unless idem.enabled?
+
+      idem.process(@task, &)
+    end
+
     def retry_execution
       @task.class.retry_on.process(@task) do |attempt|
         @retries = attempt
-        emit_telemetry(:task_retried, attempt:) if attempt.positive?
+        Telemetry.emit(@task, :task_retried, root: @root, attempt:) if attempt.positive?
         yield
       end
 
@@ -222,13 +262,5 @@ module CMDx
       throw(Signal::TAG, Signal.failed(@task.errors.to_s, metadata: @task.metadata))
     end
 
-    def emit_telemetry(name, payload = EMPTY_HASH)
-      telemetry = @task.class.telemetry
-      return unless telemetry.subscribed?(name)
-
-      event = Telemetry::Event.build(@task, name, root: @root, payload:)
-      telemetry.emit(name, event)
-    end
-
   end
 end

data/lib/cmdx/store_key.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module CMDx
+  # 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.map! { |s| Stores.key!(s) }.join(":")
+    end
+
+    # Resolves a store key segment from a task. Used by {Idempotency},
+    # {CircuitBreaker}, and other store-backed declarations.
+    #
+    # @param task [Task]
+    # @param resolver [Symbol, String, Proc, #call]
+    # @param skip [Object, nil] when `resolver == skip`, returns `nil` without
+    #   reading context (for example {CLASS_KEY})
+    # @return [String, nil] non-empty segment, or `nil` when blank or skipped
+    def segment(task, resolver, skip: nil)
+      return if skip && resolver == skip
+
+      raw =
+        case resolver
+        when Symbol
+          task.context[resolver]
+        when Proc
+          task.instance_exec(task, &resolver)
+        else
+          return resolver.call(task) if resolver.respond_to?(:call)
+
+          resolver
+        end
+
+      str = raw&.to_s
+      str if str && !str.empty?
+    end
+
+    # 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

@@ -0,0 +1,158 @@
+# 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)
+
+        @mutex.synchronize do
+          entry = @entries[key]
+          return false unless entry && !expired?(entry)
+          return false unless entry[:value] == expected.to_s
+
+          @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