cmdx 2.1.1 → 2.3.0

data/lib/cmdx/circuit_breaker.rb

@@ -0,0 +1,234 @@
+# frozen_string_literal: true
+
+module CMDx
+  # Declared via {Task.circuit_breaker}. After inputs resolve, consults shared
+  # 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
+  # `:failures` and `:open` suffix segments (see {StoreKey.compose}).
+  class CircuitBreaker
+
+    OPEN      = "open"
+    FAILURES  = "failures"
+    CLASS_KEY = :class
+
+    class << self
+
+      # @return [CircuitBreaker] disabled configuration
+      def disabled
+        DISABLED
+      end
+
+    end
+
+    attr_reader :key
+
+    # @param key [Symbol, String, Proc, #call, nil] `:class` (default when
+    #   enabling via options only), context `Symbol`, static `String`, or
+    #   callable; `nil` disables the breaker
+    # @param options [Hash{Symbol => Object}]
+    # @option options [Integer] :threshold (5) failures before the circuit opens
+    # @option options [Integer] :cool_off (30) seconds the circuit stays open
+    # @option options [Integer] :window (60) sliding window for the failure counter
+    # @option options [String] :namespace ("cmdx:cb") first segment of store keys
+    # @option options [Symbol] :on_open (:fail) `:fail` or `:skip` when open
+    # @option options [Array<Class>] :on (`[StandardError]`) exception classes that
+    #   increment the failure counter
+    # @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:cb"
+    end
+
+    # @return [Integer]
+    def threshold
+      @options[:threshold] || 5
+    end
+
+    # @return [Integer]
+    def cool_off
+      @options[:cool_off] || 30
+    end
+
+    # @return [Integer]
+    def window
+      @options[:window] || 60
+    end
+
+    # @return [Array<Class>]
+    def on_exceptions
+      @options.fetch(:on) { [StandardError] }.flatten
+    end
+
+    # @return [Symbol] `:fail` or `:skip`
+    def on_open
+      @options[:on_open] || :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 CircuitBreaker 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. When the
+    # breaker was disabled and only options are passed, the resolver becomes
+    # `:class`.
+    #
+    # @param new_key [Symbol, String, Proc, #call, nil]
+    # @param new_options [Hash{Symbol => Object}]
+    # @return [CircuitBreaker]
+    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 : CLASS_KEY
+        else
+          new_key
+        end
+      merged_options = @options.merge(new_options)
+
+      self.class.new(merged_key, merged_options)
+    end
+
+    # Runs the given block when the circuit is closed (or inactive). Records
+    # failures for configured exception classes and clears the failure counter
+    # after a successful run.
+    #
+    # @param task [Task]
+    # @yield invoked when the circuit is closed or the breaker is inactive
+    # @yieldreturn [Object] return value from the wrapped work
+    # @return [Object] the block's return value
+    # @note When the circuit is open, signals `fail!` or `skip!` on `task` —
+    #   control does not return to the caller of {#process}.
+    # @raise [ArgumentError] when `on_open` is not `:fail` or `:skip`
+    def process(task)
+      return yield unless enabled?
+      return yield unless Util.satisfied?(condition_if, condition_unless, task)
+
+      base = store_base(task)
+      return yield if base.nil?
+
+      open_key     = StoreKey.compose(base, OPEN)
+      failures_key = StoreKey.compose(base, FAILURES)
+      open!(task, open_key) if circuit_open?(open_key)
+
+      begin
+        yield
+      rescue StandardError => e
+        record_failure(e, failures_key, open_key, task)
+        raise e
+      else
+        clear_failures(failures_key, task)
+      end
+    end
+
+    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
+      false
+    end
+
+    def record_failure(exception, failures_key, open_key, task)
+      return unless counts_as_failure?(exception)
+
+      trip_open(failures_key, open_key, task)
+    rescue StandardError
+      nil
+    end
+
+    def clear_failures(failures_key, task)
+      cleared = Stores.del(failures_key)
+      Telemetry.emit(task, :circuit_reset, failures_key:) if cleared
+    rescue StandardError
+      nil
+    end
+
+    def counts_as_failure?(exception)
+      list = on_exceptions
+      return false if list.empty?
+
+      list.any? { |klass| exception.is_a?(klass) }
+    end
+
+    def trip_open(failures_key, open_key, task)
+      count = Stores.incr(failures_key, ttl: window)
+      return unless count >= threshold
+
+      Stores.set(open_key, OPEN, ttl: cool_off)
+      Stores.del(failures_key)
+
+      Telemetry.emit(
+        task,
+        :circuit_tripped,
+        circuit_breaker_key: open_key,
+        failures_key:,
+        failure_count: count,
+        threshold:,
+        cool_off:
+      )
+    end
+
+    def open!(task, open_key)
+      message = "circuit open"
+      metadata = {
+        code: :circuit_open,
+        circuit_breaker_key: open_key
+      }
+
+      remaining = Stores.remaining_ttl(open_key)
+      metadata[:retry_after] = remaining if remaining
+
+      Telemetry.emit(task, :circuit_open, **metadata, on_open:)
+
+      case on_open
+      when :fail
+        task.fail!(message, **metadata)
+      when :skip
+        task.skip!(message, **metadata)
+      else
+        raise ArgumentError, <<~MSG.chomp
+          circuit_breaker on_open must be :fail or :skip (got #{on_open.inspect}).
+          See https://drexed.github.io/cmdx/circuit_breaker/
+        MSG
+      end
+    end
+
+    DISABLED = new(nil).freeze
+    private_constant :DISABLED
+
+  end
+end

data/lib/cmdx/coercions.rb

@@ -22,6 +22,7 @@ module CMDx
         complex: Coercions::Complex,
         date: Coercions::Date,
         date_time: Coercions::DateTime,
+        decimal: Coercions::BigDecimal,
         float: Coercions::Float,
         hash: Coercions::Hash,
         integer: Coercions::Integer,

data/lib/cmdx/configuration.rb

@@ -10,7 +10,7 @@ module CMDx
   class Configuration
 
     attr_accessor :middlewares, :callbacks, :coercions, :validators, :executors,
-      :mergers, :retriers, :deprecators, :telemetry, :correlation_id, :default_locale,
+      :mergers, :retriers, :deprecators, :telemetry, :store, :correlation_id, :default_locale,
       :strict_context, :backtrace_cleaner, :log_exclusions, :log_formatter,
       :log_level, :logger
 
@@ -24,6 +24,7 @@ module CMDx
       @retriers    = Retriers.new
       @deprecators = Deprecators.new
       @telemetry   = Telemetry.new
+      @store       = Stores::Memory.new
 
       @correlation_id    = nil
       @default_locale    = "en"

data/lib/cmdx/deprecation.rb

@@ -25,14 +25,14 @@ module CMDx
     # @raise [DeprecationError] when `value` is `:error`
     # @raise [ArgumentError] when `value` is an unsupported type
     def execute(task)
-      return if @value.nil?
-      return unless Util.satisfied?(@options[:if], @options[:unless], task)
+      return if @value.nil? || !Util.satisfied?(@options[:if], @options[:unless], task)
 
       yield
 
       case @value
       when Symbol
         registry = deprecators_registry(task)
+
         if registry.key?(@value)
           registry.lookup(@value).call(task)
         else

data/lib/cmdx/fault.rb

@@ -124,5 +124,43 @@ module CMDx
       @result.chain
     end
 
+    # Enriches the stdlib detailed message with validation errors and
+    # propagation context for IRB and other debug formatters. {#message} is
+    # unchanged.
+    #
+    # @param highlight [Boolean] forwarded to `Exception#detailed_message`
+    # @param order [Symbol] forwarded to `Exception#detailed_message`
+    # @return [String]
+    def detailed_message(highlight: true, order: :top)
+      lines = [super]
+      append_errors_lines(lines)
+      append_origin_line(lines)
+      lines.join("\n")
+    end
+
+    # @return [String] human-readable representation
+    def inspect
+      "#<#{self.class} task=#{task.name} tid=#{result.tid} cid=#{result.cid} xid=#{result.xid} reason=#{result.reason.inspect} errors=#{result.errors.to_h}>"
+    end
+
+    private
+
+    def append_errors_lines(lines)
+      return if result.errors.empty?
+
+      lines << "  errors:"
+      result.errors.each do |key, messages|
+        messages.each { |message| lines << "    #{key}: #{message}" }
+      end
+    end
+
+    def append_origin_line(lines)
+      origin = result.origin
+      return unless origin
+
+      reason = origin.reason || "no reason"
+      lines << "  origin: #{origin.task.name} (#{reason})"
+    end
+
   end
 end

data/lib/cmdx/idempotency.rb

@@ -0,0 +1,172 @@
+# 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` and only options change, the existing resolver is kept (option-only
+    # updates such as `idempotent_by ttl: 600`).
+    #
+    # @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)
+
+      segment = StoreKey.segment(task, key)
+      return yield if segment.nil?
+
+      store_key = StoreKey.compose(namespace, task.class.name, segment)
+
+      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 :skip or :fail (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/input.rb

@@ -22,6 +22,7 @@ module CMDx
     # @option options [Symbol, Proc, #call] :if
     # @option options [Symbol, Proc, #call] :unless
     # @option options [Boolean] :required
+    # @option options [Boolean] :allow_nil (see {#allow_nil})
     def initialize(name, children: EMPTY_ARRAY, **options)
       @name     = name.to_sym
       @children = children.freeze
@@ -78,6 +79,14 @@ module CMDx
       @options.fetch(:required, false)
     end
 
+    # When `true`, a `nil` value after defaults skips coercion, transform, and
+    # validation. Per-validator `:allow_nil` only skips individual rules.
+    #
+    # @return [Boolean]
+    def allow_nil
+      @options.fetch(:allow_nil, false)
+    end
+
     # Computed accessor/reader method name. Uses `:as` when provided,
     # otherwise combines `:prefix`, `name`, and `:suffix` around the source.
     #
@@ -131,7 +140,8 @@ module CMDx
     # @note "Required" here means "the key is present in the source"; an
     #   explicit `nil` under an existing key satisfies the required check
     #   and is then routed through `:default`. Combine with `:presence` /
-    #   `:validate` to reject explicit `nil` values.
+    #   `:validate` to reject explicit `nil` values, or `:allow_nil` (see
+    #   {#allow_nil}) to leave `nil` unresolved.
     #
     # @param task [Task]
     # @return [Object, nil] the resolved value (`nil` on failure)
@@ -189,7 +199,7 @@ module CMDx
       end
 
       value = apply_default(task) if value.nil?
-      return if value.nil? && !key_provided
+      return if value.nil? && (!key_provided || allow_nil)
 
       @coercions ||= task.class.coercions.extract(@options)
       value = task.class.coercions.coerce(task, accessor_name, value, @coercions)

data/lib/cmdx/inputs.rb

@@ -35,6 +35,7 @@ module CMDx
     # @option options [Symbol, Proc, #call] :if
     # @option options [Symbol, Proc, #call] :unless
     # @option options [Boolean] :required
+    # @option options [Boolean] :allow_nil (see {Input#allow_nil})
     # @option options [Object] :coerce forwarded with declaration (see {Coercions#extract})
     # @option options [Object] :validate forwarded with declaration (see {Validators#extract})
     # @return [Inputs] self for chaining
@@ -138,6 +139,7 @@ module CMDx
       # @option options [Symbol, Proc, #call] :if
       # @option options [Symbol, Proc, #call] :unless
       # @option options [Boolean] :required
+      # @option options [Boolean] :allow_nil (see {Input#allow_nil})
       # @option options [Object] :coerce forwarded with declaration (see {Coercions#extract})
       # @option options [Object] :validate forwarded with declaration (see {Validators#extract})
       # @yield nested child input DSL
@@ -162,6 +164,7 @@ module CMDx
       # @option options [Symbol, Proc, #call] :transform mutator applied after coercion
       # @option options [Symbol, Proc, #call] :if
       # @option options [Symbol, Proc, #call] :unless
+      # @option options [Boolean] :allow_nil (see {Input#allow_nil})
       # @option options [Object] :coerce forwarded with declaration (see {Coercions#extract})
       # @option options [Object] :validate forwarded with declaration (see {Validators#extract})
       # @yield nested child input DSL
@@ -185,6 +188,7 @@ module CMDx
       # @option options [Symbol, Proc, #call] :transform mutator applied after coercion
       # @option options [Symbol, Proc, #call] :if
       # @option options [Symbol, Proc, #call] :unless
+      # @option options [Boolean] :allow_nil (see {Input#allow_nil})
       # @option options [Object] :coerce forwarded with declaration (see {Coercions#extract})
       # @option options [Object] :validate forwarded with declaration (see {Validators#extract})
       # @yield nested child input DSL