cmdx 1.21.0 → 2.0.0

data/lib/cmdx/runtime.rb

@@ -0,0 +1,251 @@
+# frozen_string_literal: true
+
+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).
+  #
+  # Signal propagation: Runtime wraps `work` in `catch(Signal::TAG)` so
+  # `success!` / `skip!` / `fail!` / `throw!` break out cleanly. Raised
+  # Faults are converted to echoed signals (carrying the upstream failed
+  # result as `:origin`); other `StandardError`s become failed signals with
+  # the exception as `:cause`. `execute!` (strict mode) re-raises on failure
+  # after the result is finalized, raising a {Fault} built from the deepest
+  # originating result so `fault.task` points at the leaf that failed.
+  #
+  # @note Always used via the class method; never new Runtime manually.
+  # @see Task.execute
+  # @see Task.execute!
+  class Runtime
+
+    class << self
+
+      # @param task [Task]
+      # @param strict [Boolean] when true, re-raise on failure (`execute!` semantics)
+      # @return [Result] the finalized, frozen result
+      # @raise [Fault, StandardError] only when `strict: true` and the task failed
+      def execute(task, strict: false)
+        new(task, strict:).execute
+      end
+
+    end
+
+    # @param task [Task]
+    # @param strict [Boolean]
+    def initialize(task, strict: false)
+      @task   = task
+      @strict = strict
+    end
+
+    # Runs the full lifecycle. Teardown runs in `ensure`, guaranteeing the
+    # task's context/errors get frozen and the fiber chain is cleared even
+    # when strict mode re-raises.
+    #
+    # @return [Result]
+    # @raise [Fault, StandardError] under strict mode on failure
+    def execute
+      acquire_chain
+
+      run_middlewares do
+        emit_telemetry(:task_started)
+        run_deprecation
+        run_lifecycle
+        finalize_result
+        raise_signal! if @strict
+      end
+
+      @result
+    ensure
+      run_teardown
+    end
+
+    private
+
+    def acquire_chain
+      @root = Chain.current.nil?
+      return unless @root
+
+      xid = @task.class.settings.correlation_id&.call
+      Chain.current = Chain.new(xid)
+    end
+
+    def run_middlewares(&)
+      middlewares = @task.class.middlewares
+      return yield if middlewares.empty?
+
+      middlewares.process(@task, &)
+    end
+
+    def run_deprecation
+      deprecation = @task.class.deprecation
+      return unless deprecation
+
+      deprecation.execute(@task) do
+        @deprecated = true
+        emit_telemetry(:task_deprecated)
+      end
+    end
+
+    def run_lifecycle
+      measure_duration do
+        run_callbacks(:before_execution)
+        run_around(:around_execution) do
+          run_callbacks(:before_validation)
+          perform_work
+          perform_rollback if @signal.failed?
+          run_callbacks(:after_execution)
+        end
+        run_callbacks(:"on_#{@signal.state}")
+        run_callbacks(:"on_#{@signal.status}")
+        run_callbacks(:on_ok) if @signal.ok?
+        run_callbacks(:on_ko) if @signal.ko?
+      end
+    end
+
+    def raise_signal!
+      return unless @result.failed?
+
+      cause = @signal.cause
+      raise cause if cause && !cause.is_a?(Fault)
+
+      raise Fault, @result.caused_failure
+    end
+
+    def finalize_result
+      @result = Result.new(
+        Chain.current,
+        @task,
+        @signal,
+        root: @root,
+        tid: @task.tid,
+        strict: @strict,
+        deprecated: @deprecated,
+        rolled_back: @rolled_back,
+        retries: @retries,
+        duration: @duration
+      ).tap do |result|
+        @root ? Chain.current.unshift(result) : Chain.current.push(result)
+        emit_telemetry(:task_executed, result:)
+        @task.logger.info do
+          exclusions = @task.class.settings.log_exclusions
+          exclusions.empty? ? result : result.to_h.except(*exclusions)
+        end
+      end
+    end
+
+    def run_teardown
+      @task.context.freeze if @root
+      @task.errors.freeze
+      @task.freeze
+      return unless @root
+
+      Chain.current.freeze
+      Chain.clear
+    end
+
+    def measure_duration
+      start = Process.clock_gettime(Process::CLOCK_MONOTONIC, :float_millisecond)
+      yield
+    ensure
+      @duration = Process.clock_gettime(Process::CLOCK_MONOTONIC, :float_millisecond) - start
+    end
+
+    # @param event [Symbol] callback event from {Callbacks::EVENTS}
+    # @return [void]
+    def run_callbacks(event)
+      callbacks = @task.class.callbacks
+      return if callbacks.empty?
+
+      callbacks.process(event, @task)
+    end
+
+    # @param event [Symbol] callback event from {Callbacks::EVENTS}
+    # @yield nested lifecycle segment wrapped by `around_execution` callbacks
+    # @return [Object] the wrapped block's return value
+    def run_around(event, &)
+      callbacks = @task.class.callbacks
+      return yield if callbacks.empty?
+
+      callbacks.around(event, @task, &)
+    end
+
+    def perform_work
+      @signal = catch(Signal::TAG) do
+        resolve_inputs!
+        retry_execution { @task.work }
+        verify_outputs!
+        Signal.success(nil, metadata: @task.metadata)
+      rescue Fault => e
+        Signal.echoed(e.result, cause: e, metadata: @task.metadata)
+      rescue Error => e
+        raise(e)
+      rescue StandardError => e
+        Signal.failed("[#{e.class}] #{e.message}", cause: e, metadata: @task.metadata)
+      end
+    end
+
+    def perform_rollback
+      return unless @task.respond_to?(:rollback)
+
+      @rolled_back = true
+      emit_telemetry(:task_rolled_back)
+      @task.rollback
+    end
+
+    def resolve_inputs!
+      inputs = @task.class.inputs
+      return if inputs.empty?
+
+      inputs.resolve(@task)
+      signal_errors!
+    end
+
+    def retry_execution
+      @task.class.retry_on.process(@task) do |attempt|
+        @retries = attempt
+        emit_telemetry(:task_retried, attempt:) if attempt.positive?
+        yield
+      end
+
+      signal_errors!
+    end
+
+    def verify_outputs!
+      outputs = @task.class.outputs
+      return if outputs.empty?
+
+      outputs.verify(@task)
+      signal_errors!
+    end
+
+    def signal_errors!
+      return if @task.errors.empty?
+
+      throw(Signal::TAG, Signal.failed(@task.errors.to_s, metadata: @task.metadata))
+    end
+
+    # @param name [Symbol] telemetry channel from {Telemetry::EVENTS}
+    # @param payload [Hash{Symbol => Object}] forwarded onto {Telemetry::Event#payload}
+    # @return [void]
+    def emit_telemetry(name, payload = EMPTY_HASH)
+      telemetry = @task.class.telemetry
+      return unless telemetry.subscribed?(name)
+
+      event = Telemetry::Event.new(
+        xid: Chain.current.xid,
+        cid: Chain.current.id,
+        root: @root,
+        type: @task.class.type,
+        task: @task.class,
+        tid: @task.tid,
+        name:,
+        payload:,
+        timestamp: Time.now.utc
+      )
+
+      telemetry.emit(name, event)
+    end
+
+  end
+end

data/lib/cmdx/settings.rb

@@ -1,225 +1,93 @@
 # frozen_string_literal: true
 
 module CMDx
-  # Value object encapsulating all per-task configuration. Registries are
-  # deep-duped on inheritance; scalar settings delegate to a parent Settings
-  # or to the global Configuration rather than eagerly copying values.
+  # Per-task configuration overrides. Options are frozen on construction;
+  # {#build} returns a new instance rather than mutating. Every getter falls
+  # back to {CMDx.configuration} when the option wasn't set on the task.
   class Settings
 
-    class << self
-
-      private
-
-      # Defines a reader that delegates to the parent Settings chain,
-      # falling through to Configuration when no parent exists.
-      #
-      # @param names [Array<Symbol>] Setting names to define
-      #
-      # @rbs (*Symbol names) -> void
-      def delegate_to_configuration(*names)
-        names.each do |name|
-          ivar = :"@#{name}"
-
-          attr_writer(name)
+    # @param options [Hash{Symbol => Object}] task-specific overrides
+    # @option options [Logger] :logger
+    # @option options [#call] :log_formatter
+    # @option options [Integer] :log_level
+    # @option options [#call] :backtrace_cleaner
+    # @option options [Array<Symbol>] :log_exclusions
+    # @option options [Array<Symbol, String>] :tags
+    # @option options [Boolean] :strict_context
+    def initialize(options = EMPTY_HASH)
+      @options = options.freeze
+    end
 
-          define_method(name) do
-            return instance_variable_get(ivar) if instance_variable_defined?(ivar)
+    # Returns a new Settings with `new_options` merged on top. Returns `self`
+    # unchanged when `new_options` is empty (used by Task inheritance).
+    #
+    # @param new_options [Hash{Symbol => Object}] overrides to layer on top
+    # @return [Settings] merged instance (or `self` when no changes)
+    def build(new_options)
+      return self if new_options.empty?
 
-            value = @parent ? @parent.public_send(name) : CMDx.configuration.public_send(name)
-            instance_variable_set(ivar, value)
+      self.class.new(@options.merge(new_options))
+    end
 
-            value
-          end
-        end
+    # @return [Logger] task-level logger or the global configuration's logger
+    def logger
+      @options.fetch(:logger) do
+        CMDx.configuration.logger
       end
+    end
 
-      # Defines a reader that delegates to the parent Settings only.
-      # Returns nil when the chain is exhausted.
-      #
-      # @param names [Array<Symbol>] Setting names to define
-      # @param with_fallback [Boolean] Whether to fall back to Configuration
-      #
-      # @rbs (*Symbol names, with_fallback: bool) -> void
-      def delegate_to_parent(*names, with_fallback: false)
-        names.each do |name|
-          ivar = :"@#{name}"
-
-          attr_writer(name)
-
-          define_method(name) do
-            return instance_variable_get(ivar) if instance_variable_defined?(ivar)
-
-            value = @parent&.public_send(name)
-            value ||= CMDx.configuration.public_send(name) if with_fallback
-            instance_variable_set(ivar, value)
-
-            value
-          end
-        end
+    # @return [#call] Logger formatter used when logging task results
+    def log_formatter
+      @options.fetch(:log_formatter) do
+        CMDx.configuration.log_formatter
       end
-
     end
 
-    # Returns the attribute registry for task parameters.
-    #
-    # @return [AttributeRegistry] The attribute registry
-    #
-    # @rbs @attributes: AttributeRegistry
-    attr_accessor :attributes
-
-    # Returns the callback registry for task lifecycle hooks.
-    #
-    # @return [CallbackRegistry] The callback registry
-    #
-    # @rbs @callbacks: CallbackRegistry
-    attr_accessor :callbacks
-
-    # Returns the coercion registry for type conversions.
-    #
-    # @return [CoercionRegistry] The coercion registry
-    #
-    # @rbs @coercions: CoercionRegistry
-    attr_accessor :coercions
-
-    # Returns the middleware registry for task execution.
-    #
-    # @return [MiddlewareRegistry] The middleware registry
-    #
-    # @rbs @middlewares: MiddlewareRegistry
-    attr_accessor :middlewares
-
-    # Returns the validator registry for attribute validation.
-    #
-    # @return [ValidatorRegistry] The validator registry
-    #
-    # @rbs @validators: ValidatorRegistry
-    attr_accessor :validators
-
-    # Returns the expected return keys after execution.
-    #
-    # @return [Array<Symbol>] Expected return keys after execution
-    #
-    # @rbs @returns: Array[Symbol]
-    attr_accessor :returns
-
-    # Returns the tags for task categorization.
-    #
-    # @return [Array<Symbol>] Tags for categorization
-    #
-    # @rbs @tags: Array[Symbol]
-    attr_accessor :tags
-
-    # @!attribute [rw] backtrace
-    #   @return [Boolean] true if backtraces should be logged
-    delegate_to_configuration :backtrace
-
-    # @!attribute [rw] dump_context
-    #   @return [Boolean] true if context should be included in Task#to_h
-    delegate_to_configuration :dump_context
-
-    # @!attribute [rw] rollback_on
-    #   @return [Array<String>] Statuses that trigger rollback
-    delegate_to_configuration :rollback_on
-
-    # @!attribute [rw] task_breakpoints
-    #   @return [Array<String>] Default task breakpoint statuses
-    delegate_to_configuration :task_breakpoints
-
-    # @!attribute [rw] workflow_breakpoints
-    #   @return [Array<String>] Default workflow breakpoint statuses
-    delegate_to_configuration :workflow_breakpoints
-
-    # @!attribute [rw] backtrace_cleaner
-    #   @return [Proc, nil] The backtrace cleaner proc
-    delegate_to_parent :backtrace_cleaner, with_fallback: true
-
-    # @!attribute [rw] breakpoints
-    #   @return [Array<String>, nil] Per-task breakpoints override
-    delegate_to_parent :breakpoints
-
-    # @!attribute [rw] deprecate
-    #   @return [Symbol, Proc, Boolean, nil] Deprecation behavior
-    delegate_to_parent :deprecate
-
-    # @!attribute [rw] exception_handler
-    #   @return [Proc, nil] The exception handler proc
-    delegate_to_parent :exception_handler, with_fallback: true
-
-    # @!attribute [rw] logger
-    #   @return [Logger] The logger instance
-    delegate_to_parent :logger, with_fallback: true
-
-    # @!attribute [rw] log_formatter
-    #   @return [Proc, nil] Per-task log formatter override
-    delegate_to_parent :log_formatter
-
-    # @!attribute [rw] log_level
-    #   @return [Integer, nil] Per-task log level override
-    delegate_to_parent :log_level
-
-    # @!attribute [rw] retries
-    #   @return [Integer, nil] Number of retries on failure
-    delegate_to_parent :retries
-
-    # @!attribute [rw] retry_jitter
-    #   @return [Numeric, Symbol, Proc, nil] Jitter between retries
-    delegate_to_parent :retry_jitter
-
-    # @!attribute [rw] retry_on
-    #   @return [Array<Class>, Class, nil] Exception classes to retry on
-    delegate_to_parent :retry_on
-
-    # Creates a new Settings instance, inheriting registries from a parent
-    # Settings or the global Configuration. Scalar settings are resolved
-    # lazily via delegation rather than eagerly copied.
-    #
-    # @param parent [Settings, nil] Parent settings to inherit from
-    # @param overrides [Hash] Field values to override after inheritance
-    #
-    # @example
-    #   Settings.new(parent: ParentTask.settings, deprecate: true)
-    #
-    # @rbs (?parent: Settings?, **untyped overrides) -> void
-    def initialize(parent: nil, **overrides)
-      @parent = parent
-
-      init_registries
-      init_collections
+    # @return [Integer] `Logger` severity level
+    def log_level
+      @options.fetch(:log_level) do
+        CMDx.configuration.log_level
+      end
+    end
 
-      overrides.each { |key, value| public_send(:"#{key}=", value) }
+    # @return [Array<Symbol>] keys to exclude from logging
+    def log_exclusions
+      @options.fetch(:log_exclusions) do
+        CMDx.configuration.log_exclusions
+      end
     end
 
-    private
+    # @return [#call, nil] callable that cleans fault backtrace frames
+    def backtrace_cleaner
+      @options.fetch(:backtrace_cleaner) do
+        CMDx.configuration.backtrace_cleaner
+      end
+    end
 
-    # Dups registries from the parent Settings or global Configuration
-    # so each task class gets its own mutable copy.
+    # Returns a fresh array each call so callers can mutate the result
+    # without affecting other tasks (or hitting `FrozenError` on the
+    # shared sentinel).
     #
-    # @rbs () -> void
-    def init_registries
-      if @parent
-        @middlewares = @parent.middlewares.dup
-        @callbacks = @parent.callbacks.dup
-        @coercions = @parent.coercions.dup
-        @validators = @parent.validators.dup
-        @attributes = @parent.attributes.dup
-      else
-        config = CMDx.configuration
+    # @return [Array<Symbol, String>] task tags, surfaced on result hashes
+    def tags
+      tags = @options[:tags]
+      tags ? tags.dup : []
+    end
 
-        @middlewares = config.middlewares.dup
-        @callbacks = config.callbacks.dup
-        @coercions = config.coercions.dup
-        @validators = config.validators.dup
-        @attributes = AttributeRegistry.new
+    # @return [Boolean] whether this task's {Context} should raise on
+    #   unknown dynamic reads; falls back to
+    #   {Configuration#strict_context}
+    def strict_context
+      @options.fetch(:strict_context) do
+        CMDx.configuration.strict_context
       end
     end
 
-    # Initializes array-valued settings that need their own copy
-    # to avoid cross-class mutation.
-    #
-    # @rbs () -> void
-    def init_collections
-      @returns = @parent&.returns&.dup || EMPTY_ARRAY
-      @tags = @parent&.tags&.dup || EMPTY_ARRAY
+    # @return [String, nil] correlation id or the global configuration's correlation id
+    def correlation_id
+      @options.fetch(:correlation_id) do
+        CMDx.configuration.correlation_id
+      end
     end
 
   end