cmdx 1.1.2 → 1.5.0

data/lib/cmdx/log_formatters/json.rb

@@ -2,36 +2,35 @@
 
 module CMDx
   module LogFormatters
-    # JSON log formatter that outputs structured log entries as JSON.
+    # Formats log messages as JSON for structured logging
     #
-    # This formatter converts log entries into JSON format, including metadata
-    # such as severity, process ID, and timestamp. Each log entry is output as
-    # a single line of JSON followed by a newline character.
-    class Json
+    # This formatter converts log entries into JSON format with standardized fields
+    # including severity, timestamp, program name, process ID, and formatted message.
+    # The output is suitable for log aggregation systems and structured analysis.
+    class JSON
 
-      # Formats a log entry as a JSON string.
+      # Formats a log entry as a JSON string
       #
-      # @param severity [String] the log severity level (e.g., "INFO", "ERROR")
-      # @param time [Time] the timestamp when the log entry was created
-      # @param task [Object] the task object associated with the log entry
-      # @param message [String] the log message content
+      # @param severity [String] The log level (e.g., "INFO", "ERROR", "DEBUG")
+      # @param time [Time] The timestamp when the log entry was created
+      # @param progname [String, nil] The program name or identifier
+      # @param message [Object] The log message content
       #
-      # @return [String] the formatted JSON log entry with trailing newline
+      # @return [String] A JSON-formatted log entry with a trailing newline
       #
-      # @raise [JSON::GeneratorError] if the log data cannot be serialized to JSON
-      #
-      # @example Formatting a log entry
-      #   formatter = CMDx::LogFormatters::Json.new
-      #   result = formatter.call("INFO", Time.now, task_object, "Task completed")
-      #   #=> "{\"severity\":\"INFO\",\"pid\":12345,\"timestamp\":\"2024-01-01T12:00:00Z\",\"message\":\"Task completed\"}\n"
-      def call(severity, time, task, message)
-        m = LoggerSerializer.call(severity, time, task, message).merge!(
+      # @example Basic usage
+      #   logger_formatter.call("INFO", Time.now, "MyApp", "User logged in")
+      #   # => '{"severity":"INFO","timestamp":"2024-01-15T10:30:45.123456Z","progname":"MyApp","pid":12345,"message":"User logged in"}\n'
+      def call(severity, time, progname, message)
+        hash = {
           severity:,
+          timestamp: time.utc.iso8601(6),
+          progname:,
           pid: Process.pid,
-          timestamp: Utils::LogTimestamp.call(time.utc)
-        )
+          message: Utils::Format.to_log(message)
+        }
 
-        JSON.dump(m) << "\n"
+        ::JSON.dump(hash) << "\n"
       end
 
     end

data/lib/cmdx/log_formatters/key_value.rb

@@ -2,37 +2,35 @@
 
 module CMDx
   module LogFormatters
-    # Key-value log formatter that outputs structured log entries as key=value pairs.
+    # Formats log messages as key-value pairs for structured logging
     #
-    # This formatter converts log entries into key-value format, including metadata
-    # such as severity, process ID, and timestamp. Each log entry is output as
-    # space-separated key=value pairs followed by a newline character.
+    # This formatter converts log entries into key-value format with standardized fields
+    # including severity, timestamp, program name, process ID, and formatted message.
+    # The output is suitable for log parsing tools and human-readable structured logs.
     class KeyValue
 
-      # Formats a log entry as a key=value string.
+      # Formats a log entry as a key-value string
       #
-      # @param severity [String] the log severity level (e.g., "INFO", "ERROR")
-      # @param time [Time] the timestamp when the log entry was created
-      # @param task [Object] the task object associated with the log entry
-      # @param message [String] the log message content
+      # @param severity [String] The log level (e.g., "INFO", "ERROR", "DEBUG")
+      # @param time [Time] The timestamp when the log entry was created
+      # @param progname [String, nil] The program name or identifier
+      # @param message [Object] The log message content
       #
-      # @return [String] the formatted key=value log entry with trailing newline
+      # @return [String] A key-value formatted log entry with a trailing newline
       #
-      # @raise [StandardError] if the log data cannot be serialized to key=value format
-      #
-      # @example Formatting a log entry
-      #   formatter = CMDx::LogFormatters::KeyValue.new
-      #   result = formatter.call("INFO", Time.now, task_object, "Task completed")
-      #   #=> "severity=INFO pid=12345 timestamp=2024-01-01T12:00:00Z message=Task completed\n"
-      def call(severity, time, task, message)
-        m = LoggerSerializer.call(severity, time, task, message).merge!(
+      # @example Basic usage
+      #   logger_formatter.call("INFO", Time.now, "MyApp", "User logged in")
+      #   # => "severity=INFO timestamp=2024-01-15T10:30:45.123456Z progname=MyApp pid=12345 message=User logged in\n"
+      def call(severity, time, progname, message)
+        hash = {
           severity:,
+          timestamp: time.utc.iso8601(6),
+          progname:,
           pid: Process.pid,
-          timestamp: Utils::LogTimestamp.call(time.utc)
-        )
+          message: Utils::Format.to_log(message)
+        }
 
-        m = m.map { |k, v| "#{k}=#{v}" }.join(" ") if m.is_a?(Hash)
-        m << "\n"
+        Utils::Format.to_str(hash) << "\n"
       end
 
     end

data/lib/cmdx/log_formatters/line.rb

@@ -2,34 +2,27 @@
 
 module CMDx
   module LogFormatters
-    # Line log formatter that outputs log entries in a traditional line format.
+    # Formats log messages as single-line text for human-readable logging
     #
-    # This formatter converts log entries into a human-readable line format,
-    # including metadata such as severity, process ID, and timestamp. Each log
-    # entry is output as a single line with structured information.
+    # This formatter converts log entries into a compact single-line format with
+    # severity abbreviation, ISO8601 timestamp, process ID, and formatted message.
+    # The output is optimized for human readability and traditional log file formats.
     class Line
 
-      # Formats a log entry as a line string.
+      # Formats a log entry as a single-line string
       #
-      # @param severity [String] the log severity level (e.g., "INFO", "ERROR")
-      # @param time [Time] the timestamp when the log entry was created
-      # @param task [Object] the task object associated with the log entry
-      # @param message [String] the log message content
+      # @param severity [String] The log level (e.g., "INFO", "ERROR", "DEBUG")
+      # @param time [Time] The timestamp when the log entry was created
+      # @param progname [String, nil] The program name or identifier
+      # @param message [Object] The log message content
       #
-      # @return [String] the formatted line log entry with trailing newline
+      # @return [String] A single-line formatted log entry with a trailing newline
       #
-      # @raise [NoMethodError] if the task object doesn't respond to expected methods
-      #
-      # @example Formatting a log entry
-      #   formatter = CMDx::LogFormatters::Line.new
-      #   result = formatter.call("INFO", Time.now, task_object, "Task completed")
-      #   #=> "I, [2024-01-01T12:00:00.000Z #12345] INFO -- TaskClass: Task completed\n"
-      def call(severity, time, task, message)
-        t = Utils::LogTimestamp.call(time.utc)
-        m = LoggerSerializer.call(severity, time, task, message)
-        m = m.map { |k, v| "#{k}=#{v}" }.join(" ") if m.is_a?(Hash)
-
-        "#{severity[0]}, [#{t} ##{Process.pid}] #{severity} -- #{task.class.name}: #{m}\n"
+      # @example Basic usage
+      #   logger_formatter.call("INFO", Time.now, "MyApp", "User logged in")
+      #   # => "I, [2024-01-15T10:30:45.123456Z #12345] INFO -- MyApp: User logged in\n"
+      def call(severity, time, progname, message)
+        "#{severity[0]}, [#{time.utc.iso8601(6)} ##{Process.pid}] #{severity} -- #{progname}: #{message}\n"
       end
 
     end

data/lib/cmdx/log_formatters/logstash.rb

@@ -2,38 +2,37 @@
 
 module CMDx
   module LogFormatters
-    # Logstash log formatter that outputs structured log entries in Logstash JSON format.
+    # Formats log messages as Logstash-compatible JSON for structured logging
     #
-    # This formatter converts log entries into Logstash-compatible JSON format, including
-    # required Logstash fields such as @version and @timestamp, along with metadata
-    # such as severity and process ID. Each log entry is output as a single line of
-    # JSON followed by a newline character.
+    # This formatter converts log entries into Logstash-compatible JSON format with
+    # standardized fields including @version, @timestamp, severity, program name,
+    # process ID, and formatted message. The output follows Logstash event format
+    # specifications for seamless integration with ELK stack and similar systems.
     class Logstash
 
-      # Formats a log entry as a Logstash-compatible JSON string.
+      # Formats a log entry as a Logstash-compatible JSON string
       #
-      # @param severity [String] the log severity level (e.g., "INFO", "ERROR")
-      # @param time [Time] the timestamp when the log entry was created
-      # @param task [Object] the task object associated with the log entry
-      # @param message [String] the log message content
+      # @param severity [String] The log level (e.g., "INFO", "ERROR", "DEBUG")
+      # @param time [Time] The timestamp when the log entry was created
+      # @param progname [String, nil] The program name or identifier
+      # @param message [Object] The log message content
       #
-      # @return [String] the formatted Logstash JSON log entry with trailing newline
+      # @return [String] A Logstash-compatible JSON-formatted log entry with a trailing newline
       #
-      # @raise [JSON::GeneratorError] if the log data cannot be serialized to JSON
-      #
-      # @example Formatting a log entry
-      #   formatter = CMDx::LogFormatters::Logstash.new
-      #   result = formatter.call("INFO", Time.now, task_object, "Task completed")
-      #   #=> "{\"severity\":\"INFO\",\"pid\":12345,\"@version\":\"1\",\"@timestamp\":\"2024-01-01T12:00:00.000Z\",\"message\":\"Task completed\"}\n"
-      def call(severity, time, task, message)
-        m = LoggerSerializer.call(severity, time, task, message).merge!(
+      # @example Basic usage
+      #   logger_formatter.call("INFO", Time.now, "MyApp", "User logged in")
+      #   # => '{"@version":"1","@timestamp":"2024-01-15T10:30:45.123456Z","severity":"INFO","progname":"MyApp","pid":12345,"message":"User logged in"}\n'
+      def call(severity, time, progname, message)
+        hash = {
+          "@version" => "1",
+          "@timestamp" => time.utc.iso8601(6),
           severity:,
+          progname:,
           pid: Process.pid,
-          "@version" => "1",
-          "@timestamp" => Utils::LogTimestamp.call(time.utc)
-        )
+          message: Utils::Format.to_log(message)
+        }
 
-        JSON.dump(m) << "\n"
+        ::JSON.dump(hash) << "\n"
       end
 
     end

data/lib/cmdx/log_formatters/raw.rb

@@ -2,34 +2,28 @@
 
 module CMDx
   module LogFormatters
-    # Raw log formatter that outputs log messages using inspect format.
+    # Formats log messages as raw text without additional formatting
     #
-    # This formatter provides a simple, unstructured log output by calling
-    # inspect on the message content. It ignores severity, time, and task
-    # metadata, focusing only on the raw message content. Each log entry
-    # is output as an inspected string followed by a newline character.
+    # This formatter outputs log messages in their original form with minimal
+    # processing, adding only a trailing newline. It's useful for scenarios
+    # where you want to preserve the exact message content without metadata
+    # or structured formatting.
     class Raw
 
-      # Formats a log entry as an inspected string.
+      # Formats a log entry as raw text
       #
-      # @param _severity [String] the log severity level (ignored)
-      # @param _time [Time] the timestamp when the log entry was created (ignored)
-      # @param _task [Object] the task object associated with the log entry (ignored)
-      # @param message [Object] the log message content to be inspected
+      # @param severity [String] The log level (e.g., "INFO", "ERROR", "DEBUG")
+      # @param time [Time] The timestamp when the log entry was created
+      # @param progname [String, nil] The program name or identifier
+      # @param message [Object] The log message content
       #
-      # @return [String] the inspected message with trailing newline
+      # @return [String] The raw message with a trailing newline
       #
-      # @example Formatting a log entry
-      #   formatter = CMDx::LogFormatters::Raw.new
-      #   result = formatter.call("INFO", Time.now, task_object, "Task completed")
-      #   #=> "\"Task completed\"\n"
-      #
-      # @example Formatting a complex object
-      #   formatter = CMDx::LogFormatters::Raw.new
-      #   result = formatter.call("DEBUG", Time.now, task_object, { status: :success, count: 42 })
-      #   #=> "{:status=>:success, :count=>42}\n"
-      def call(_severity, _time, _task, message)
-        message.inspect + "\n" # rubocop:disable Style/StringConcatenation
+      # @example Basic usage
+      #   logger_formatter.call("INFO", Time.now, "MyApp", "User logged in")
+      #   # => "User logged in\n"
+      def call(severity, time, progname, message)
+        "#{message}\n"
       end
 
     end

data/lib/cmdx/middleware_registry.rb

@@ -1,110 +1,106 @@
 # frozen_string_literal: true
 
 module CMDx
-  # Registry for managing middleware definitions and execution within tasks.
+  # Registry for managing middleware components in a task execution chain.
   #
-  # This registry handles the registration and execution of middleware that can
-  # wrap task execution, providing cross-cutting concerns like logging, timing,
-  # authentication, and error handling.
+  # The MiddlewareRegistry maintains an ordered list of middleware components
+  # that can be inserted, removed, and executed in sequence. Each middleware
+  # can be configured with specific options and is executed in the order
+  # they were registered.
   class MiddlewareRegistry
 
-    # @return [Hash] hash containing middleware classes/objects and their configurations
     attr_reader :registry
+    alias to_a registry
 
-    # Initializes a new middleware registry.
+    # Initialize a new middleware registry.
     #
-    # @param registry [Hash] optional hash of initial middleware configurations
+    # @param registry [Array] Initial array of middleware entries
     #
-    # @return [MiddlewareRegistry] a new middleware registry instance
+    # @example
+    #   registry = MiddlewareRegistry.new
+    #   registry = MiddlewareRegistry.new([[MyMiddleware, {option: 'value'}]])
+    def initialize(registry = [])
+      @registry = registry
+    end
+
+    # Create a duplicate of the registry with duplicated middleware entries.
     #
-    # @example Creating an empty registry
-    #   MiddlewareRegistry.new
+    # @return [MiddlewareRegistry] A new registry instance with duplicated entries
     #
-    # @example Creating a registry with initial middleware
-    #   MiddlewareRegistry.new(TimeoutMiddleware => [[], {timeout: 30}, nil])
-    def initialize(registry = {})
-      @registry = registry.to_h
+    # @example
+    #   new_registry = registry.dup
+    def dup
+      self.class.new(registry.map(&:dup))
     end
 
-    # Registers a middleware with the registry.
+    # Register a middleware component in the registry.
     #
-    # @param middleware [Class, Object] the middleware class or instance to register
-    # @param args [Array] positional arguments to pass to middleware initialization
-    # @param kwargs [Hash] keyword arguments to pass to middleware initialization
-    # @param block [Proc] optional block to pass to middleware initialization
+    # @param middleware [Object] The middleware object to register
+    # @param at [Integer] Position to insert the middleware (default: -1, end of list)
+    # @param options [Hash] Configuration options for the middleware
+    # @option options [Symbol] :key Configuration key for the middleware
+    # @option options [Object] :value Configuration value for the middleware
     #
-    # @return [MiddlewareRegistry] self for method chaining
+    # @return [MiddlewareRegistry] Returns self for method chaining
     #
-    # @example Register a middleware class
-    #   registry.register(TimeoutMiddleware, 30)
+    # @example
+    #   registry.register(LoggingMiddleware, at: 0, log_level: :debug)
+    #   registry.register(AuthMiddleware, at: -1, timeout: 30)
+    def register(middleware, at: -1, **options)
+      registry.insert(at, [middleware, options])
+      self
+    end
+
+    # Remove a middleware component from the registry.
+    #
+    # @param middleware [Object] The middleware object to remove
     #
-    # @example Register a middleware with keyword arguments
-    #   registry.register(LoggingMiddleware, level: :info)
+    # @return [MiddlewareRegistry] Returns self for method chaining
     #
-    # @example Register a middleware with a block
-    #   registry.register(CustomMiddleware) { |task| puts "Processing #{task.id}" }
-    def register(middleware, *args, **kwargs, &block)
-      registry[middleware] = [args, kwargs, block]
+    # @example
+    #   registry.deregister(LoggingMiddleware)
+    def deregister(middleware)
+      registry.reject! { |mw, _opts| mw == middleware }
       self
     end
 
-    # Executes all registered middleware around the provided task.
+    # Execute the middleware chain for a given task.
     #
-    # @param task [Task] the task instance to execute middleware around
-    # @param block [Proc] the block to execute after all middleware processing
+    # @param task [Object] The task object to process through middleware
     #
-    # @return [Object] the result of the middleware chain execution
+    # @yield [task] Block to execute after all middleware processing
+    # @yieldparam task [Object] The processed task object
     #
-    # @raise [ArgumentError] if no block is provided
+    # @return [Object] Result of the block execution
     #
-    # @example Execute middleware around a task
-    #   registry.call(task) { |task| task.process }
+    # @raise [ArgumentError] When no block is provided
     #
-    # @example Execute with early return if no middleware
-    #   registry.call(task) { |task| puts "No middleware to execute" }
-    def call(task, &)
+    # @example
+    #   result = registry.call!(my_task) do |processed_task|
+    #     processed_task.execute
+    #   end
+    def call!(task, &)
       raise ArgumentError, "block required" unless block_given?
 
-      return yield(task) if registry.empty?
-
-      build_chain(&).call(task)
-    end
-
-    # Returns a hash representation of the registry.
-    #
-    # @return [Hash] deep copy of registry with duplicated configuration arrays
-    # @option return [Array] args duplicated positional arguments array
-    # @option return [Hash] kwargs duplicated keyword arguments hash
-    # @option return [Proc, nil] block the original block reference (not duplicated)
-    #
-    # @example Getting registry hash
-    #   registry.to_h
-    #   #=> { TimeoutMiddleware => [[30], {}, nil] }
-    def to_h
-      registry.transform_values do |config|
-        args, kwargs, block = config
-        [args.dup, kwargs.dup, block]
-      end
+      recursively_call_middleware(0, task, &)
     end
 
     private
 
-    # Builds the middleware execution chain by wrapping middleware around the call block.
-    #
-    # @param call_block [Proc] the final block to execute after all middleware
-    #
-    # @return [Proc] the complete middleware chain as a callable proc
-    #
-    # @example Building a middleware chain (internal use)
-    #   build_chain { |task| task.process }
-    def build_chain(&call_block)
-      registry.reverse_each.reduce(call_block) do |next_callable, (middleware, config)|
-        proc do |task|
-          args, kwargs, block = config
-          instance = middleware.respond_to?(:new) ? middleware.new(*args, **kwargs, &block) : middleware
-          instance.call(task, next_callable)
-        end
-      end
+    # Recursively execute middleware in the chain.
+    #
+    # @param index [Integer] Current middleware index in the chain
+    # @param task [Object] The task object being processed
+    #
+    # @yield [task] Block to execute after middleware processing
+    # @yieldparam task [Object] The processed task object
+    #
+    # @return [Object] Result of the block execution or next middleware call
+    def recursively_call_middleware(index, task, &block)
+      return yield(task) if index >= registry.size
+
+      middleware, options = registry[index]
+      middleware.call(task, **options) { recursively_call_middleware(index + 1, task, &block) }
     end
 
   end