cmdx 2.2.0 → 2.4.0

data/lib/cmdx/idempotency.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+module CMDx
+  # Declared via {Task.idempotent_by}. After inputs resolve, claims a shared
+  # store slot and runs the `retry_on` loop inside that claim so duplicate
+  # invocations with the same logical key short-circuit before `work` repeats.
+  #
+  # Store keys are `namespace:TaskName:segment` (see {StoreKey.compose}). Values
+  # move `processing` → `completed` after the wrapped block returns (including
+  # output verification when invoked from {Runtime}); the key is deleted on
+  # `StandardError` or non-success signals (`skip!` / `fail!`) so retries can
+  # reclaim.
+  class Idempotency
+
+    PROCESSING = "processing"
+    COMPLETED  = "completed"
+
+    class << self
+
+      # @return [Idempotency] disabled configuration (no key)
+      def disabled
+        DISABLED
+      end
+
+    end
+
+    attr_reader :key
+
+    # @param key [Symbol, String, Proc, #call, nil] segment resolved per task;
+    #   `nil` disables idempotency. Symbols read from `context`; `Proc` /
+    #   blocks are `instance_exec`'d on the task (with `task` as the first
+    #   block argument, same as callbacks); other `#call`ables receive the
+    #   task. Blank segments skip claiming.
+    # @param options [Hash{Symbol => Object}]
+    # @option options [Integer] :ttl (300) expiry in seconds for store entries
+    # @option options [String] :namespace ("cmdx:idem") first segment of the store key
+    # @option options [Symbol] :on_duplicate (:skip) `:skip` or `:fail` when the
+    #   slot is already claimed
+    # @option options [Symbol, Proc, #call] :if gate `(task)` for claiming
+    # @option options [Symbol, Proc, #call] :unless gate `(task)` for claiming
+    def initialize(key, options = EMPTY_HASH)
+      @key     = key
+      @options = options.freeze
+    end
+
+    # @return [String]
+    def namespace
+      @options[:namespace] || "cmdx:idem"
+    end
+
+    # @return [Symbol] `:skip` or `:fail`
+    def on_duplicate
+      @options[:on_duplicate] || :skip
+    end
+
+    # @return [Integer]
+    def ttl
+      @options[:ttl] || 300
+    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 Idempotency 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. 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}]
+    # @return [Idempotency]
+    def build(new_key, new_options)
+      return self if new_key.nil? && new_options.empty?
+
+      merged_key = new_key.nil? ? @key : new_key
+      merged_options = @options.merge(new_options)
+
+      self.class.new(merged_key, merged_options)
+    end
+
+    # Runs the given block behind a store claim when {#enabled?} and gates pass.
+    # Releases the claim on `StandardError` or a non-returning exit (`skip!`,
+    # `fail!`) so `retry_on` can run `work` again; marks the slot `completed`
+    # after the block returns successfully.
+    #
+    # @param task [Task]
+    # @yield invoked when the claim succeeds or idempotency is inactive
+    # @yieldreturn [Object] return value from the wrapped work (ignored by callers)
+    # @return [Object] the block's return value
+    # @note On duplicate keys, signals `skip!` or `fail!` on `task` — control
+    #   does not return to the caller of {#process}.
+    # @raise [ArgumentError] when `on_duplicate` is not `:skip` or `:fail`
+    # @raise [IdempotencyError] when the store refuses the `completed` transition
+    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)
+      return yield if store_key.nil?
+
+      if Stores.set(store_key, PROCESSING, nx: true, ttl:)
+        Telemetry.emit(task, :idempotency_claimed, idempotency_key: store_key)
+
+        succeeded = false
+
+        begin
+          yield
+          succeeded = true
+        rescue StandardError
+          Stores.del(store_key)
+          raise
+        ensure
+          Stores.del(store_key) unless succeeded
+        end
+
+        mark_completed!(store_key, task)
+      else
+        duplicate!(task, store_key)
+      end
+    end
+
+    private
+
+    def mark_completed!(store_key, task)
+      if Stores.set(store_key, COMPLETED, xx: true, ttl:)
+        Telemetry.emit(task, :idempotency_completed, idempotency_key: store_key)
+        return
+      end
+
+      Stores.del(store_key)
+      raise IdempotencyError, "failed to mark idempotency key completed (#{store_key})"
+    end
+
+    def duplicate!(task, store_key)
+      state    = Stores.get(store_key)
+      message  = "duplicate request (state=#{state})"
+      metadata = { code: :duplicate, idempotency_key: store_key, state: }
+
+      Telemetry.emit(task, :idempotency_duplicate, **metadata)
+
+      case on_duplicate
+      when :fail
+        task.fail!(message, **metadata)
+      when :skip
+        task.skip!(message, **metadata)
+      else
+        raise ArgumentError, <<~MSG.chomp
+          idempotent_by on_duplicate must be :fail or :skip (got #{on_duplicate.inspect}).
+          See https://drexed.github.io/cmdx/idempotency/
+        MSG
+      end
+    end
+
+    DISABLED = new(nil).freeze
+    private_constant :DISABLED
+
+  end
+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

@@ -0,0 +1,192 @@
+# frozen_string_literal: true
+
+module CMDx
+  # Declared via {Task.lock_with}. After inputs resolve, acquires a store lease
+  # (`SET` with `nx: true`) and runs idempotency (when declared), the full
+  # `retry_on` loop, and output verification inside that lease.
+  #
+  # Store keys are `namespace:TaskName:segment` (see {StoreKey.compose}). The
+  # stored value is the holding task's `tid`. Release uses a conditional delete so
+  # a late releaser cannot drop a newer holder's lease after TTL expiry.
+  #
+  # After a successful acquire, the lease is released in `ensure` for any exit from
+  # the wrapped block (success, `skip!` / `fail!`, or uncaught error). The lease
+  # is not released between in-process `retry_on` attempts.
+  class Lock
+
+    class << self
+
+      # @return [Lock] disabled configuration (no key)
+      def disabled
+        DISABLED
+      end
+
+    end
+
+    attr_reader :key
+
+    # @param key [Symbol, String, Proc, #call, nil] segment resolved per task;
+    #   `nil` disables locking. Symbols read from `context`; `Proc` / blocks are
+    #   `instance_exec`'d on the task (with `task` as the first block argument,
+    #   same as callbacks); other `#call`ables receive the task. Blank segments
+    #   skip acquiring.
+    # @param options [Hash{Symbol => Object}]
+    # @option options [Integer] :ttl (300) lease expiry in seconds when the holder
+    #   does not release; size for worst-case hold time including the retry loop
+    # @option options [String] :namespace ("cmdx:lock") first segment of the store key
+    # @option options [Numeric, false, nil] :wait (0) max seconds to wait for the
+    #   lease; `0`, `nil`, or `false` try once
+    # @option options [Symbol] :on_busy (:fail) `:skip` or `:fail` when the lease
+    #   cannot be acquired within `:wait`
+    # @option options [Symbol, Proc, #call] :if gate `(task)` for acquiring
+    # @option options [Symbol, Proc, #call] :unless gate `(task)` for acquiring
+    def initialize(key, options = EMPTY_HASH)
+      @key     = key
+      @options = options.freeze
+    end
+
+    # @return [String]
+    def namespace
+      @options[:namespace] || "cmdx:lock"
+    end
+
+    # @return [Integer]
+    def ttl
+      @options[:ttl] || 300
+    end
+
+    # @return [Float]
+    def wait
+      raw = @options[:wait]
+      return 0.0 if raw.nil? || raw == false
+
+      Float(raw)
+    end
+
+    # @return [Symbol] `:skip` or `:fail`
+    def on_busy
+      @options[:on_busy] || :fail
+    end
+
+    # @return [Symbol, Proc, #call, nil]
+    def condition_if
+      @options[:if]
+    end
+
+    # @return [Symbol, Proc, #call, nil]
+    def condition_unless
+      @options[:unless]
+    end
+
+    # @return [Boolean]
+    def enabled?
+      !key.nil?
+    end
+
+    # Returns a new Lock layering `new_options` onto the current one. 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}]
+    # @return [Lock]
+    def build(new_key, new_options)
+      return self if new_key.nil? && new_options.empty?
+
+      merged_key = new_key.nil? ? @key : new_key
+      merged_options = @options.merge(new_options)
+
+      self.class.new(merged_key, merged_options)
+    end
+
+    # Runs the given block behind a store lease when {#enabled?} and gates pass.
+    #
+    # @param task [Task]
+    # @yield invoked when the lease is acquired or locking is inactive
+    # @yieldreturn [Object] return value from the wrapped work
+    # @return [Object] the block's return value
+    # @note When the lease cannot be acquired, signals `skip!` or `fail!` on
+    #   `task` — control does not return to the caller of {#process}. Busy
+    #   metadata may include `:holder` and `:retry_after` when the backend
+    #   exposes the current value and TTL.
+    # @raise [ArgumentError] when `on_busy` is not `:skip` or `:fail`, or `wait`
+    #   is negative
+    def process(task)
+      return yield unless enabled?
+      return yield unless Util.satisfied?(condition_if, condition_unless, task)
+
+      store_key = StoreKey.task_key(task, namespace:, resolver: key)
+      return yield if store_key.nil?
+
+      token = task.tid
+
+      if acquire_lock(store_key, token)
+        Telemetry.emit(task, :lock_acquired, lock_key: store_key)
+
+        begin
+          yield
+        ensure
+          release_lock(store_key, token)
+        end
+      else
+        busy!(task, store_key)
+      end
+    end
+
+    private
+
+    def acquire_lock(store_key, token) # rubocop:disable Naming/PredicateMethod -- returns whether the lease was taken
+      wait_seconds = wait
+      raise ArgumentError, "lock_with wait must be >= 0 (got #{wait_seconds})" if wait_seconds.negative?
+
+      deadline = (Util.monotonic_now + wait_seconds if wait_seconds.positive?)
+
+      loop do
+        return true if Stores.set(store_key, token, nx: true, ttl:)
+        return false unless deadline
+
+        break if Util.monotonic_now >= deadline
+
+        sleep_interval = [0.05, deadline - Util.monotonic_now].min
+        Kernel.sleep(sleep_interval) if sleep_interval.positive?
+      end
+
+      false
+    end
+
+    def release_lock(store_key, token)
+      Stores.del_if(store_key, token)
+    end
+
+    def busy!(task, store_key)
+      holder = Stores.get(store_key)
+      retry_after = Stores.remaining_ttl(store_key)
+
+      message = holder ? "lock held" : "lock not acquired"
+      metadata = {
+        code: :busy,
+        lock_key: store_key,
+        holder:,
+        retry_after:
+      }.compact
+
+      Telemetry.emit(task, :lock_busy, **metadata, on_busy:)
+
+      case on_busy
+      when :fail
+        task.fail!(message, **metadata)
+      when :skip
+        task.skip!(message, **metadata)
+      else
+        raise ArgumentError, <<~MSG.chomp
+          lock_with on_busy must be :fail or :skip (got #{on_busy.inspect}).
+          See https://drexed.github.io/cmdx/locks/
+        MSG
+      end
+    end
+
+    DISABLED = new(nil).freeze
+    private_constant :DISABLED
+
+  end
+end

data/lib/cmdx/pipeline.rb

@@ -151,7 +151,7 @@ module CMDx
         new_opts = old_opts.merge(rolled_back: true).freeze
         result.instance_variable_set(:@options, new_opts)
 
-        emit_telemetry(instance, :task_rolled_back)
+        Telemetry.emit(instance, :task_rolled_back, root: false)
 
         begin
           instance.rollback
@@ -166,14 +166,6 @@ module CMDx
       raise first_rollback_error if first_rollback_error
     end
 
-    def emit_telemetry(instance, name, payload = EMPTY_HASH)
-      telemetry = instance.class.telemetry
-      return unless telemetry.subscribed?(name)
-
-      event = Telemetry::Event.build(instance, name, root: false, payload:)
-      telemetry.emit(name, event)
-    end
-
     def aggregate(failures, continue:)
       return if failures.empty?
       return failures.first unless continue