cmdx 2.0.1 → 2.1.0

data/lib/cmdx/inputs.rb

@@ -51,14 +51,17 @@ module CMDx
       self
     end
 
-    # Removes inputs and their accessor readers from `klass`.
+    # Removes inputs and their accessor readers from `klass`. Unknown names
+    # are silently ignored (matching {Outputs#deregister} semantics).
     #
     # @param klass [Class]
     # @param names [Array<Symbol>]
     # @return [Inputs] self for chaining
     def deregister(klass, *names)
       names.each do |name|
-        input = registry.delete(name.to_sym)
+        input = registry.delete(name)
+        next if input.nil?
+
         klass.send(:undefine_input_reader, input)
       end
 
@@ -90,10 +93,6 @@ module CMDx
 
     private
 
-    # @param input [Input] parent input whose children should be resolved
-    # @param parent_value [Object] resolved parent value child inputs read from
-    # @param task [Task]
-    # @return [void]
     def resolve_children(input, parent_value, task)
       return if input.children.empty? || parent_value.nil?
 
@@ -149,6 +148,9 @@ module CMDx
       alias input inputs
 
       # Declares optional child inputs (equivalent to `inputs ..., required: false`).
+      # An explicit `required:` in `options` is ignored — use {#inputs} when
+      # you need to set the flag dynamically.
+      #
       # @param names [Array<Symbol>]
       # @param options [Hash{Symbol => Object}] forwarded to {Input#initialize}
       # @option options [String] :description (also accepts `:desc`)
@@ -165,10 +167,13 @@ module CMDx
       # @yield nested child input DSL
       # @return [Array<Input>]
       def optional(*names, **options, &)
-        build(*names, required: false, **options, &)
+        build(*names, **options, required: false, &)
       end
 
       # Declares required child inputs (equivalent to `inputs ..., required: true`).
+      # An explicit `required:` in `options` is ignored — use {#inputs} when
+      # you need to set the flag dynamically.
+      #
       # @param names [Array<Symbol>]
       # @param options [Hash{Symbol => Object}] forwarded to {Input#initialize}
       # @option options [String] :description (also accepts `:desc`)
@@ -185,31 +190,14 @@ module CMDx
       # @yield nested child input DSL
       # @return [Array<Input>]
       def required(*names, **options, &)
-        build(*names, required: true, **options, &)
+        build(*names, **options, required: true, &)
       end
 
       private
 
-      # @param names [Array<Symbol>]
-      # @param block [#call, nil]
-      # @param options [Hash{Symbol => Object}] forwarded to {Input#initialize}
-      # @option options [String] :description (also accepts `:desc`)
-      # @option options [Symbol] :as overrides the accessor name
-      # @option options [Boolean, String] :prefix prefix for the accessor name
-      # @option options [Boolean, String] :suffix suffix for the accessor name
-      # @option options [Symbol, Proc, #call] :source (`:context`) where to fetch from
-      # @option options [Object, Symbol, Proc, #call] :default
-      # @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] :required
-      # @option options [Object] :coerce forwarded with declaration (see {Coercions#extract})
-      # @option options [Object] :validate forwarded with declaration (see {Validators#extract})
-      # @return [Array<Input>]
-      # @yield nested child input DSL
       def build(*names, **options, &block)
         nested = block ? self.class.build(&block) : EMPTY_ARRAY
-        names.map { |name| children << Input.new(name, children: nested, **options) }
+        names.each { |name| children << Input.new(name, children: nested, **options) }
       end
 
     end

data/lib/cmdx/log_formatters/json.rb

@@ -4,7 +4,10 @@ module CMDx
   module LogFormatters
     # `Logger` formatter that emits one JSON object per line with `severity`,
     # ISO8601 `timestamp`, `progname`, `pid`, and `message` (rendered via
-    # `#to_h` when available — Result instances serialize themselves).
+    # `#to_h` when available — Result instances serialize themselves). Falls
+    # back to `message.inspect` if the original `JSON.dump` raises (e.g. for
+    # non-JSON-encodable or cyclic structures) so logging never crashes the
+    # caller.
     class JSON
 
       # @param severity [String] Logger severity name
@@ -21,6 +24,10 @@ module CMDx
           message: message.respond_to?(:to_h) ? message.to_h : message
         }
 
+        ::JSON.dump(hash) << "\n"
+      rescue StandardError => e
+        hash[:message] = message.inspect
+        hash[:logerr]  = Util.to_error_s(e)
         ::JSON.dump(hash) << "\n"
       end
 

data/lib/cmdx/log_formatters/logstash.rb

@@ -3,7 +3,9 @@
 module CMDx
   module LogFormatters
     # `Logger` formatter that produces one JSON line per entry in the shape
-    # expected by Logstash (`@version` + `@timestamp`).
+    # expected by Logstash (`@version` + `@timestamp`). Falls back to
+    # `message.inspect` if `JSON.dump` raises (e.g. cyclic / non-encodable
+    # payload) so logging never crashes the caller.
     class Logstash
 
       # @param severity [String] Logger severity name
@@ -21,6 +23,10 @@ module CMDx
           "@timestamp" => time.utc.iso8601(6)
         }
 
+        ::JSON.dump(hash) << "\n"
+      rescue StandardError => e
+        hash[:message] = message.inspect
+        hash[:logerr]  = Util.to_error_s(e)
         ::JSON.dump(hash) << "\n"
       end
 

data/lib/cmdx/mergers.rb

@@ -36,9 +36,12 @@ module CMDx
       merger = callable || block
 
       if callable && block
-        raise ArgumentError, "provide either a callable or a block, not both"
+        raise ArgumentError, "merger: provide either a callable or a block, not both"
       elsif !merger.respond_to?(:call)
-        raise ArgumentError, "merger must respond to #call"
+        raise ArgumentError, <<~MSG.chomp
+          merger must respond to #call (got #{merger.class}).
+          See https://drexed.github.io/cmdx/workflows/#merge-strategies
+        MSG
       end
 
       registry[name.to_sym] = merger
@@ -48,16 +51,25 @@ module CMDx
     # @param name [Symbol]
     # @return [Mergers] self for chaining
     def deregister(name)
-      registry.delete(name.to_sym)
+      registry.delete(name)
       self
     end
 
+    # @param name [Symbol]
+    # @return [Boolean] whether a merger is registered under `name`
+    def key?(name)
+      registry.key?(name)
+    end
+
     # @param name [Symbol]
     # @return [#call] the registered merger
-    # @raise [ArgumentError] when `name` isn't registered
+    # @raise [UnknownEntryError] when `name` isn't registered
     def lookup(name)
       registry[name] || begin
-        raise ArgumentError, "unknown merger: #{name.inspect}"
+        raise UnknownEntryError, <<~MSG.chomp
+          unknown merger #{name.inspect}; registered: #{registry.keys.inspect}.
+          See https://drexed.github.io/cmdx/workflows/#merge-strategies
+        MSG
       end
     end
 
@@ -67,7 +79,7 @@ module CMDx
     #
     # @param spec [Symbol, #call, nil]
     # @return [#call]
-    # @raise [ArgumentError] when `spec` is an unknown symbol or not callable
+    # @raise [UnknownEntryError] when `spec` is an unknown symbol or not callable
     def resolve(spec)
       case spec
       when NilClass
@@ -77,7 +89,10 @@ module CMDx
       else
         return spec if spec.respond_to?(:call)
 
-        raise ArgumentError, "unknown merger: #{spec.inspect}"
+        raise UnknownEntryError, <<~MSG.chomp
+          unknown merger #{spec.inspect}; expected a Symbol from #{registry.keys.inspect} or a callable.
+          See https://drexed.github.io/cmdx/workflows/#merge-strategies
+        MSG
       end
     end
 

data/lib/cmdx/middlewares.rb

@@ -37,11 +37,17 @@ module CMDx
       at = options.delete(:at)
 
       if callable && block
-        raise ArgumentError, "provide either a callable or a block, not both"
+        raise ArgumentError, "middleware: provide either a callable or a block, not both"
       elsif !middleware.respond_to?(:call)
-        raise ArgumentError, "middleware must respond to #call"
+        raise ArgumentError, <<~MSG.chomp
+          middleware must respond to #call (got #{middleware.class}).
+          See https://drexed.github.io/cmdx/middlewares/#signature
+        MSG
       elsif !at.nil? && !at.is_a?(Integer)
-        raise ArgumentError, "at must be an Integer"
+        raise ArgumentError, <<~MSG.chomp
+          middleware :at must be an Integer (got #{at.class}).
+          See https://drexed.github.io/cmdx/middlewares/#ordering
+        MSG
       end
 
       entry = [middleware, options.freeze]
@@ -49,8 +55,7 @@ module CMDx
       if at.nil?
         registry << entry
       else
-        at = [at.clamp(-registry.size - 1, registry.size), registry.size].min
-        registry.insert(at, entry)
+        registry.insert(at.clamp(-registry.size - 1, registry.size), entry)
       end
 
       self
@@ -65,11 +70,14 @@ module CMDx
     #   or when `:at` isn't an Integer
     def deregister(middleware = nil, at: nil)
       if at.nil? && middleware.nil?
-        raise ArgumentError, "provide either a middleware or an at: index"
+        raise ArgumentError, "middleware: provide either a middleware or an at: index"
       elsif !at.nil? && !middleware.nil?
-        raise ArgumentError, "provide either a middleware or an at: index, not both"
+        raise ArgumentError, "middleware: provide either a middleware or an at: index, not both"
       elsif !at.nil? && !at.is_a?(Integer)
-        raise ArgumentError, "at must be an Integer"
+        raise ArgumentError, <<~MSG.chomp
+          middleware :at must be an Integer (got #{at.class}).
+          See https://drexed.github.io/cmdx/middlewares/#ordering
+        MSG
       end
 
       if at.nil?
@@ -94,6 +102,10 @@ module CMDx
     # Walks the middleware chain around `task`'s lifecycle. The final link
     # yields to `block`, which is expected to run the actual lifecycle.
     #
+    # Built as an iterative reverse-reduce (matching {Callbacks#around}),
+    # avoiding the per-link recursive lambda invocation of the previous
+    # implementation while preserving identical semantics.
+    #
     # @param task [Task]
     # @yield the innermost link — the task's lifecycle body
     # @return [void]
@@ -101,26 +113,30 @@ module CMDx
     #   which would otherwise silently skip the task
     def process(task)
       processed = false
-      count = registry.size
-
-      chain = lambda do |i|
-        if i == count
-          processed = true
-          yield
-        else
-          mw, opts = registry[i]
-
-          if Util.satisfied?(opts[:if], opts[:unless], task)
-            mw.call(task) { chain.call(i + 1) }
-          else
-            chain.call(i + 1)
-          end
+      last_invoked = nil
+
+      innermost = lambda do
+        processed = true
+        yield
+      end
+
+      chain = registry.reverse_each.reduce(innermost) do |succ, (mw, opts)|
+        lambda do
+          next succ.call unless Util.satisfied?(opts[:if], opts[:unless], task)
+
+          last_invoked = mw
+          mw.call(task) { succ.call }
         end
       end
-      chain.call(0)
+
+      chain.call
 
       processed || begin
-        raise MiddlewareError, "middleware did not yield the next_link"
+        offender = last_invoked.is_a?(Class) ? last_invoked : last_invoked.class
+        raise MiddlewareError, <<~MSG.chomp
+          middleware #{offender} did not yield to next_link.
+          See https://drexed.github.io/cmdx/middlewares/#safety
+        MSG
       end
     end
 

data/lib/cmdx/output.rb

@@ -75,6 +75,11 @@ module CMDx
     #    supplied a value (every declared output is implicitly required).
     # 4. Writes the resolved value back to `task.context[name]`.
     #
+    # @note "Missing" here means "the key was never written"; an explicit `nil`
+    #   under an existing key is treated as "present" and the value remains
+    #   `nil` (unless `:default` overrides it). To reject explicit `nil`, write
+    #   a non-nil value or set a non-nil `:default`.
+    #
     # @param task [Task] the running task whose context is inspected and mutated
     # @return [void]
     def verify(task)
@@ -94,8 +99,6 @@ module CMDx
 
     private
 
-    # @param task [Task]
-    # @return [Object, nil]
     def apply_default(task)
       return if default.nil?
 

data/lib/cmdx/pipeline.rb

@@ -58,13 +58,16 @@ module CMDx
           when :parallel
             run_parallel(group)
           else
-            raise ArgumentError, "invalid strategy: #{strategy.inspect}"
+            raise ArgumentError, <<~MSG.chomp
+              invalid pipeline strategy #{strategy.inspect}; expected one of [:sequential, :parallel].
+              See https://drexed.github.io/cmdx/workflows/#group-options
+            MSG
           end
 
         next unless halt
 
         rollback_executed!
-        @workflow.send(:throw!, halt)
+        @workflow.throw!(halt)
       end
     end
 
@@ -138,6 +141,8 @@ module CMDx
     end
 
     def rollback_executed!
+      first_rollback_error = nil
+
       @executed.reverse_each do |instance, result|
         next unless result.success?
         next unless instance.respond_to?(:rollback)
@@ -147,8 +152,18 @@ module CMDx
         result.instance_variable_set(:@options, new_opts)
 
         emit_telemetry(instance, :task_rolled_back)
-        instance.rollback
+
+        begin
+          instance.rollback
+        rescue StandardError => e
+          first_rollback_error ||= e
+          instance.logger.error do
+            "rollback for #{instance.class} (#{instance.tid}) raised: #{Util.to_error_s(e)}"
+          end
+        end
       end
+
+      raise first_rollback_error if first_rollback_error
     end
 
     def emit_telemetry(instance, name, payload = EMPTY_HASH)

data/lib/cmdx/railtie.rb

@@ -10,6 +10,7 @@ module CMDx
 
     initializer("cmdx.configure_rails") do |app|
       available_locales = app.config.i18n.available_locales.join(",")
+      available_locales = "*" if available_locales.empty?
       locale_path = File.expand_path("../locales/{#{available_locales}}.yml", __dir__)
       ::I18n.load_path += Dir[locale_path]
 

data/lib/cmdx/result.rb

@@ -52,7 +52,9 @@ module CMDx
       task.type
     end
 
-    # @return [String, nil] correlation id or the global configuration's correlation id
+    # @return [String, nil] resolved correlation id from this result's chain
+    #   (produced by the configured `correlation_id` callable when the root
+    #   chain was acquired)
     def xid
       chain.xid
     end
@@ -142,12 +144,14 @@ module CMDx
     #     .on(:success) { |r| deliver(r.context) }
     #     .on(:failed)  { |r| alert(r.reason) }
     def on(*keys)
-      raise ArgumentError, "block required" unless block_given?
+      raise ArgumentError, "Result#on requires a block" unless block_given?
 
       yield(self) if keys.any? do |k|
         unless EVENTS.include?(k.to_sym)
-          raise ArgumentError,
-            "unknown event #{k.inspect}, must be one of #{EVENTS.join(', ')}"
+          raise ArgumentError, <<~MSG.chomp
+            unknown Result#on event #{k.inspect}, must be one of #{EVENTS.to_a.inspect}.
+            See https://drexed.github.io/cmdx/outcomes/result/#predicate-dispatch
+          MSG
         end
 
         public_send(:"#{k}?")
@@ -180,6 +184,20 @@ module CMDx
       @signal.cause
     end
 
+    # Convenience accessor that returns the underlying exception when the
+    # failure was produced by a rescued exception, otherwise the human
+    # `reason`. `nil` for non-failed results. Useful for telemetry adapters
+    # (Sentry, Bugsnag, ...) that branch on whether an exception is
+    # available without forcing every subscriber to repeat the
+    # `cause || reason` dance.
+    #
+    # @return [Exception, String, nil]
+    def error
+      return unless failed?
+
+      cause || reason
+    end
+
     # The originating failed result at the bottom of the propagation chain.
     # Walks `origin` recursively. `self` when this result is the originator;
     # `nil` when not failed.
@@ -346,8 +364,6 @@ module CMDx
 
     private
 
-    # @param key [Symbol] reader name such as `:caused_failure` or `:threw_failure`
-    # @return [Hash{Symbol => Object}, nil] compact `{task:, tid:}` map for graph hints
     def hash_for_failure(key)
       r = public_send(key)
       return if r.nil?

data/lib/cmdx/retriers/decorrelated_jitter.rb

@@ -3,9 +3,12 @@
 module CMDx
   class Retriers
     # AWS-recommended decorrelated jitter. Produces a uniform delay in
-    # `[delay, prev_delay * 3]`, threading state across attempts via
-    # `prev_delay`. When no previous delay exists the upper bound collapses
-    # to `3 * delay`, matching the AWS reference implementation.
+    # `[delay, max(prev_delay * 3, delay)]`, threading state across attempts
+    # via `prev_delay`. When no previous delay exists the upper bound
+    # collapses to `3 * delay`, matching the AWS reference implementation.
+    # The lower bound is pinned at `delay` even when `prev_delay * 3 < delay`
+    # (e.g. after `:max_delay` clamping or mixed strategies), guaranteeing
+    # the returned value is never below the configured base.
     #
     # @see https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/
     # @api private
@@ -17,10 +20,12 @@ module CMDx
       # @param delay [Float] base delay in seconds (also the lower bound)
       # @param prev_delay [Float, nil] previous computed delay; falls back to
       #   `delay` so the first call samples in `[delay, 3*delay]`
-      # @return [Float] computed delay
+      # @return [Float] computed delay, never less than `delay`
       def call(_attempt, delay, prev_delay = nil)
         base = prev_delay || delay
-        delay + (rand * ((base * 3) - delay))
+        high = base * 3
+        high = delay if high < delay
+        delay + (rand * (high - delay))
       end
 
     end

data/lib/cmdx/retriers/exponential.rb

@@ -3,19 +3,27 @@
 module CMDx
   class Retriers
     # Exponential backoff. Doubles the base delay every attempt:
-    # `delay * (2 ** attempt)`.
+    # `delay * (2 ** attempt)`. The shift is saturated at {MAX_SHIFT} to keep
+    # the math (and resulting sleep) bounded; pair with `:max_delay` to set
+    # the true upper bound.
     #
     # @api private
     module Exponential
 
       extend self
 
+      # Hard cap on the doubling exponent. `2 ** 30 ≈ 1.07e9` so paired with
+      # any sensible base delay the unclamped result is large enough to be
+      # noticed but never blows up into Bignum allocations or `Infinity`.
+      MAX_SHIFT = 30
+
       # @param attempt [Integer] zero-based retry attempt
       # @param delay [Float] base delay in seconds
       # @param _prev_delay [Float, nil] ignored
       # @return [Float] computed delay
       def call(attempt, delay, _prev_delay = nil)
-        delay * (2**attempt)
+        shift = [attempt, MAX_SHIFT].min
+        delay * (1 << shift)
       end
 
     end

data/lib/cmdx/retriers/fibonacci.rb

@@ -11,27 +11,44 @@ module CMDx
 
       extend self
 
+      # Hard cap on the index to keep multipliers/integer allocations bounded.
+      # `fib(78) < 2**63`, well past any realistic retry attempt. Pair with
+      # `:max_delay` for the actual sleep ceiling.
+      MAX_INDEX = 78
+
+      # Cache of computed Fibonacci numbers. Shared across calls so consecutive
+      # retries reuse prior work instead of recomputing from zero. Reads are
+      # lock-free; growth is performed on a local dup and swapped atomically
+      # under the mutex.
+      @cache = [0, 1].freeze
+      @mutex = Mutex.new
+
       # @param attempt [Integer] zero-based retry attempt
       # @param delay [Float] base delay in seconds
       # @param _prev_delay [Float, nil] ignored
       # @return [Float] computed delay
       def call(attempt, delay, _prev_delay = nil)
-        delay * sequence(attempt + 1)
+        index = attempt + 1
+        index = MAX_INDEX if index > MAX_INDEX
+        delay * fib(index)
       end
 
       private
 
-      # Iterative Fibonacci. `sequence(1) == 1`, `sequence(2) == 1`,
-      # `sequence(3) == 2`, ...
-      #
-      # @param n [Integer] one-based index into the Fibonacci sequence
-      # @return [Integer]
-      # @api private
-      def sequence(n)
-        a = 0
-        b = 1
-        n.times { a, b = b, a + b }
-        a
+      def fib(n)
+        cache = @cache
+        return cache[n] if n < cache.size
+
+        @mutex.synchronize do
+          cache = @cache
+          if cache.size <= n
+            grown = cache.dup
+            grown << (grown[-1] + grown[-2]) while grown.size <= n
+            @cache = grown.freeze
+          end
+        end
+
+        @cache[n]
       end
 
     end

data/lib/cmdx/retriers.rb

@@ -41,9 +41,12 @@ module CMDx
       retrier = callable || block
 
       if callable && block
-        raise ArgumentError, "provide either a callable or a block, not both"
+        raise ArgumentError, "retrier: provide either a callable or a block, not both"
       elsif !retrier.respond_to?(:call)
-        raise ArgumentError, "retrier must respond to #call"
+        raise ArgumentError, <<~MSG.chomp
+          retrier must respond to #call (got #{retrier.class}).
+          See https://drexed.github.io/cmdx/retries/#custom-strategies-via-the-retriers-registry
+        MSG
       end
 
       registry[name.to_sym] = retrier
@@ -53,22 +56,25 @@ module CMDx
     # @param name [Symbol]
     # @return [Retriers] self for chaining
     def deregister(name)
-      registry.delete(name.to_sym)
+      registry.delete(name)
       self
     end
 
     # @param name [Symbol]
     # @return [Boolean] whether a retrier is registered under `name`
     def key?(name)
-      registry.key?(name.to_sym)
+      registry.key?(name)
     end
 
     # @param name [Symbol]
     # @return [#call] the registered retrier
-    # @raise [ArgumentError] when `name` isn't registered
+    # @raise [UnknownEntryError] when `name` isn't registered
     def lookup(name)
       registry[name] || begin
-        raise ArgumentError, "unknown retrier: #{name.inspect}"
+        raise UnknownEntryError, <<~MSG.chomp
+          unknown retrier #{name.inspect}; registered: #{registry.keys.inspect}.
+          See https://drexed.github.io/cmdx/retries/#built-in-strategies
+        MSG
       end
     end
 
@@ -78,7 +84,7 @@ module CMDx
     #
     # @param spec [Symbol, #call, nil]
     # @return [#call, nil]
-    # @raise [ArgumentError] when `spec` is an unknown symbol or not callable
+    # @raise [UnknownEntryError] when `spec` is an unknown symbol or not callable
     def resolve(spec)
       case spec
       when NilClass
@@ -88,7 +94,10 @@ module CMDx
       else
         return spec if spec.respond_to?(:call)
 
-        raise ArgumentError, "unknown retrier: #{spec.inspect}"
+        raise UnknownEntryError, <<~MSG.chomp
+          unknown retrier #{spec.inspect}; expected a Symbol from #{registry.keys.inspect} or a callable.
+          See https://drexed.github.io/cmdx/retries/#built-in-strategies
+        MSG
       end
     end