cmdx 2.0.0 → 2.1.0

data/lib/cmdx/input.rb

@@ -128,6 +128,11 @@ module CMDx
     # validation error to `task.errors`. Returns `nil` when coercion or any
     # validator fails (the failure message is recorded on `task.errors`).
     #
+    # @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.
+    #
     # @param task [Task]
     # @return [Object, nil] the resolved value (`nil` on failure)
     def resolve(task)
@@ -177,10 +182,6 @@ module CMDx
 
     private
 
-    # @param value [Object] candidate after source resolution
-    # @param key_provided [Boolean] whether the source reported an explicit key/value pair
-    # @param task [Task]
-    # @return [Object, nil]
     def run_pipeline(value, key_provided, task)
       if required?(task) && !key_provided
         task.errors.add(accessor_name, I18nProxy.t("cmdx.attributes.required"))
@@ -202,15 +203,13 @@ module CMDx
       value
     end
 
-    # @param task [Task]
-    # @return [Array(Object, Boolean)] `[value, key_provided]`
     def resolve_with_key(task)
       case source
       when :context
         [task.context[name], task.context.key?(name)]
       when Symbol
         obj = task.send(source)
-        return [nil, false] if obj.nil?
+        return [nil, false] unless obj
 
         fetch_by_name(obj)
       when Proc
@@ -218,20 +217,19 @@ module CMDx
       else
         return [source.call(task), true] if source.respond_to?(:call)
 
-        raise ArgumentError, "source must be a Symbol, Proc, or respond to #call"
+        raise ArgumentError, <<~MSG.chomp
+          input source must be a Symbol, Proc, or respond to #call (got #{source.class}).
+          See https://drexed.github.io/cmdx/inputs/definitions/#sources
+        MSG
       end
     end
 
-    # @param parent_value [#[], #key?, Object]
-    # @return [Array(Object, Boolean)] `[value, key_provided]`
     def resolve_from_parent_with_key(parent_value)
-      return [nil, false] unless parent_value.respond_to?(:[])
+      return [nil, false] unless parent_value.respond_to?(:[]) || parent_value.respond_to?(:fetch)
 
       fetch_by_name(parent_value)
     end
 
-    # @param obj [Object] source object (`Hash`, duck-typed reader, etc.)
-    # @return [Array(Object, Boolean)] `[value, key_provided]`
     def fetch_by_name(obj)
       if obj.respond_to?(name, true)
         [obj.send(name), true]
@@ -243,9 +241,15 @@ module CMDx
         else
           [nil, false]
         end
+      elsif obj.respond_to?(:fetch)
+        # Prefer #fetch with a sentinel so an explicit `nil` value is
+        # distinguishable from a missing key (Hash, Array, etc.).
+        value = obj.fetch(name) { obj.fetch(name.to_s) { EMPTY_SENTINEL } }
+        value.equal?(EMPTY_SENTINEL) ? [nil, false] : [value, true]
       elsif obj.respond_to?(:[])
-        # Without #key? we cannot distinguish "key absent" from "value is nil",
-        # so an explicit nil is treated as not provided (triggers default/required).
+        # Without #key? or #fetch we cannot distinguish "key absent" from
+        # "value is nil", so an explicit nil is treated as not provided
+        # (triggers default/required).
         value = obj[name] || obj[name.to_s]
         [value, !value.nil?]
       else
@@ -253,8 +257,6 @@ module CMDx
       end
     end
 
-    # @param task [Task]
-    # @return [Object, nil]
     def apply_default(task)
       return if default.nil?
 
@@ -270,9 +272,6 @@ module CMDx
       end
     end
 
-    # @param value [Object]
-    # @param task [Task]
-    # @return [Object]
     def apply_transform(value, task)
       case transform
       when Symbol
@@ -286,7 +285,10 @@ module CMDx
       else
         return transform.call(value, task) if transform.respond_to?(:call)
 
-        raise ArgumentError, "transform must be a Symbol, Proc, or respond to #call"
+        raise ArgumentError, <<~MSG.chomp
+          input transform must be a Symbol, Proc, or respond to #call (got #{transform.class}).
+          See https://drexed.github.io/cmdx/inputs/transformations/#declarations
+        MSG
       end
     end
 

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,20 +58,21 @@ 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
 
     private
 
-    # @param group [Workflow::ExecutionGroup]
-    # @return [Result, nil] failed result to halt on, or nil when the group succeeds
     def run_sequential(group)
       continue = group.options[:continue_on_failure]
       failures = group.tasks.each_with_object([]) do |task_class, bucket|
@@ -87,8 +88,6 @@ module CMDx
       aggregate(failures, continue:)
     end
 
-    # @param group [Workflow::ExecutionGroup]
-    # @return [Result, nil] failed result to halt on, or nil when the group succeeds
     def run_parallel(group)
       tasks     = group.tasks
       chain     = Chain.current
@@ -142,21 +141,39 @@ 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)
 
-        instance.rollback
-
         old_opts = result.instance_variable_get(:@options)
         new_opts = old_opts.merge(rolled_back: true).freeze
         result.instance_variable_set(:@options, new_opts)
+
+        emit_telemetry(instance, :task_rolled_back)
+
+        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)
+      telemetry = instance.class.telemetry
+      return unless telemetry.subscribed?(name)
+
+      event = Telemetry::Event.build(instance, name, root: false, payload:)
+      telemetry.emit(name, event)
     end
 
-    # @param failures [Array<Result>]
-    # @param continue [Boolean] when true, merges failures into the workflow's errors
-    # @return [Result, nil] first failure (echoed upstream), or nil when `failures` is empty
     def aggregate(failures, continue:)
       return if failures.empty?
       return failures.first unless continue

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