makit 0.0.168 → 0.0.169

data/lib/makit/logging/sinks/unified_file_sink.rb

@@ -1,296 +1,296 @@
-# frozen_string_literal: true
-
-require_relative "base"
-require_relative "../format_registry"
-require "fileutils"
-
-module Makit
-  module Logging
-    module Sinks
-      # Unified file sink with configurable multiple outputs
-      #
-      # This sink replaces the need for multiple separate sinks by providing
-      # a single, highly configurable sink that can write to multiple files
-      # with different formats, filtering, and options. It supports console
-      # output, file logging, and structured logging through configuration.
-      #
-      # @example Basic usage with console and file output
-      #   sink = UnifiedFileSink.new(
-      #     configurations: [
-      #       { file: $stdout, format: :console },
-      #       { file: "logs/app.log", format: :json }
-      #     ]
-      #   )
-      #
-      # @example Advanced configuration with filtering and formatting
-      #   sink = UnifiedFileSink.new(
-      #     configurations: [
-      #       {
-      #         file: $stdout,
-      #         format: :console,
-      #         show_timestamp: true,
-      #         show_level: true
-      #       },
-      #       {
-      #         file: "logs/debug.log",
-      #         format: :text,
-      #         min_level: :debug,
-      #         include_context: true
-      #       },
-      #       {
-      #         file: "logs/audit.log",
-      #         format: :json,
-      #         min_level: :info,
-      #         include_metadata: true
-      #       }
-      #     ]
-      #   )
-      class UnifiedFileSink < Base
-        # @return [Array<Hash>] list of output configurations
-        attr_reader :configurations
-
-        # Initialize unified file sink
-        #
-        # @param configurations [Array<Hash>] list of output configurations
-        def initialize(configurations: [])
-          @configurations = validate_configurations(configurations)
-          @formatters = {}
-          @files = {}
-
-          # Pre-initialize formatters and files
-          initialize_formatters
-          initialize_files
-        end
-
-        # Execute sink logic to write log entry to configured outputs
-        #
-        # @param log_request [LogRequest] the log request to process
-        # @yield [LogRequest] yields the processed log request to the next sink
-        # @yieldreturn [LogRequest] the processed log request
-        # @return [LogRequest] the final processed log request
-        def call(log_request, &block)
-          write_to_outputs(log_request)
-          block&.call(log_request) if block_given?
-          log_request
-        end
-
-        # Get sink configuration
-        #
-        # @return [Hash] sink configuration
-        def config
-          {
-            name: self.class.name.split("::").last,
-            configurations_count: @configurations.length,
-            configurations: @configurations.map { |config| sanitize_config(config) },
-          }
-        end
-
-        private
-
-        # Validate configuration array
-        #
-        # @param configurations [Array<Hash>] configurations to validate
-        # @return [Array<Hash>] validated configurations
-        # @raise [ArgumentError] if configuration is invalid
-        def validate_configurations(configurations)
-          raise ArgumentError, "configurations must be an array" unless configurations.is_a?(Array)
-          raise ArgumentError, "at least one configuration is required" if configurations.empty?
-
-          configurations.each_with_index do |config, index|
-            validate_single_configuration(config, index)
-          end
-
-          configurations
-        end
-
-        # Validate a single configuration
-        #
-        # @param config [Hash] configuration to validate
-        # @param index [Integer] configuration index for error messages
-        # @raise [ArgumentError] if configuration is invalid
-        def validate_single_configuration(config, index)
-          raise ArgumentError, "configuration #{index} must be a hash" unless config.is_a?(Hash)
-
-          required_keys = %i[file format]
-          missing_keys = required_keys - config.keys
-          unless missing_keys.empty?
-            raise ArgumentError,
-                  "configuration #{index} missing required keys: #{missing_keys.join(", ")}"
-          end
-
-          # Validate file
-          file = config[:file]
-          unless file.is_a?(String) || file.is_a?(IO) || file.respond_to?(:write)
-            raise ArgumentError, "configuration #{index} file must be a String path, IO object, or writable object"
-          end
-
-          # Validate format
-          format = config[:format]
-          unless format.is_a?(Symbol) || format.is_a?(String)
-            raise ArgumentError, "configuration #{index} format must be a Symbol or String"
-          end
-
-          # Validate log levels if specified
-          if config[:min_level] && !valid_log_level?(config[:min_level])
-            raise ArgumentError, "configuration #{index} min_level must be a valid log level"
-          end
-
-          return unless config[:max_level] && !valid_log_level?(config[:max_level])
-
-          raise ArgumentError, "configuration #{index} max_level must be a valid log level"
-        end
-
-        # Check if log level is valid
-        #
-        # @param level [Symbol] log level to check
-        # @return [Boolean] true if valid
-        def valid_log_level?(level)
-          %i[debug info warn error fatal success].include?(level)
-        end
-
-        # Initialize formatters for each configuration
-        #
-        # @return [void]
-        def initialize_formatters
-          @configurations.each_with_index do |config, index|
-            format = config[:format].to_sym
-            formatter_options = config[:formatter_options] || {}
-
-            # Merge configuration options into formatter options
-            formatter_options[:include_context] = config[:include_context] if config.key?(:include_context)
-            formatter_options[:include_metadata] = config[:include_metadata] if config.key?(:include_metadata)
-            formatter_options[:show_timestamp] = config[:show_timestamp] if config.key?(:show_timestamp)
-            formatter_options[:show_level] = config[:show_level] if config.key?(:show_level)
-
-            begin
-              formatter_class = FormatRegistry.get(format)
-
-              # Handle different formatter initialization patterns
-              @formatters[index] = if formatter_class == Formatters::ConsoleFormatter
-                  # ConsoleFormatter expects keyword arguments
-                  formatter_class.new(
-                    show_timestamp: formatter_options[:show_timestamp] || false,
-                    show_level: formatter_options[:show_level] || false,
-                  )
-                elsif formatter_class == Formatters::TextFormatter
-                  # TextFormatter expects keyword arguments
-                  formatter_class.new(
-                    timestamp_format: formatter_options[:timestamp_format] || "%Y-%m-%d %H:%M:%S",
-                    include_context: formatter_options[:include_context] || false,
-                  )
-                elsif formatter_class == Formatters::JsonFormatter
-                  # JsonFormatter expects keyword arguments
-                  formatter_class.new(
-                    options: formatter_options,
-                  )
-                elsif formatter_class == Formatters::PlainTextFormatter
-                  # PlainTextFormatter expects keyword arguments
-                  formatter_class.new(
-                    include_context: formatter_options[:include_context] || false,
-                  )
-                elsif formatter_options.empty?
-                  # Other formatters expect hash or no arguments
-                  formatter_class.new
-                else
-                  formatter_class.new(formatter_options)
-                end
-            rescue ArgumentError => e
-              raise ArgumentError, "configuration #{index} has invalid format '#{format}': #{e.message}"
-            end
-          end
-        end
-
-        # Initialize file handles for each configuration
-        #
-        # @return [void]
-        def initialize_files
-          @configurations.each_with_index do |config, index|
-            file = config[:file]
-
-            if file.is_a?(String)
-              # Ensure directory exists
-              FileUtils.mkdir_p(File.dirname(file)) unless File.dirname(file) == "."
-
-              # Open file with appropriate mode
-              mode = config[:append] == false ? "w" : "a"
-              @files[index] = File.open(file, mode)
-            else
-              # Use IO object directly
-              @files[index] = file
-            end
-          end
-        end
-
-        # Write log request to all applicable outputs
-        #
-        # @param log_request [LogRequest] the log request to write
-        def write_to_outputs(log_request)
-          @configurations.each_with_index do |config, index|
-            next unless should_output?(log_request, config)
-
-            formatter = @formatters[index]
-            file = @files[index]
-
-            formatted_message = formatter.format(log_request)
-            file.write(formatted_message)
-            file.write("\n") unless config[:no_newline]
-            file.flush
-          end
-        end
-
-        # Check if log request should be output to this configuration
-        #
-        # @param log_request [LogRequest] the log request
-        # @param config [Hash] the output configuration
-        # @return [Boolean] true if should output
-        def should_output?(log_request, config)
-          # Check level filtering
-          return false if config[:min_level] && !level_greater_or_equal?(log_request.level, config[:min_level])
-
-          return false if config[:max_level] && !level_less_or_equal?(log_request.level, config[:max_level])
-
-          # Check custom condition
-          return false if config[:condition] && !config[:condition].call(log_request)
-
-          true
-        end
-
-        # Check if log level is greater than or equal to minimum level
-        #
-        # @param level [Symbol] log level to check
-        # @param min_level [Symbol] minimum level
-        # @return [Boolean] true if level >= min_level
-        def level_greater_or_equal?(level, min_level)
-          levels = %i[debug info warn error fatal success]
-          levels.index(level) >= levels.index(min_level)
-        end
-
-        # Check if log level is less than or equal to maximum level
-        #
-        # @param level [Symbol] log level to check
-        # @param max_level [Symbol] maximum level
-        # @return [Boolean] true if level <= max_level
-        def level_less_or_equal?(level, max_level)
-          levels = %i[debug info warn error fatal success]
-          levels.index(level) <= levels.index(max_level)
-        end
-
-        # Sanitize configuration for display (remove sensitive data)
-        #
-        # @param config [Hash] configuration to sanitize
-        # @return [Hash] sanitized configuration
-        def sanitize_config(config)
-          sanitized = config.dup
-
-          # Remove condition procs and other non-serializable items
-          sanitized.delete(:condition)
-
-          # Convert IO objects to string representation
-          sanitized[:file] = "<#{sanitized[:file].class.name}>" if sanitized[:file].is_a?(IO)
-
-          sanitized
-        end
-      end
-    end
-  end
-end
+# frozen_string_literal: true
+
+require_relative "base"
+require_relative "../format_registry"
+require "fileutils"
+
+module Makit
+  module Logging
+    module Sinks
+      # Unified file sink with configurable multiple outputs
+      #
+      # This sink replaces the need for multiple separate sinks by providing
+      # a single, highly configurable sink that can write to multiple files
+      # with different formats, filtering, and options. It supports console
+      # output, file logging, and structured logging through configuration.
+      #
+      # @example Basic usage with console and file output
+      #   sink = UnifiedFileSink.new(
+      #     configurations: [
+      #       { file: $stdout, format: :console },
+      #       { file: "logs/app.log", format: :json }
+      #     ]
+      #   )
+      #
+      # @example Advanced configuration with filtering and formatting
+      #   sink = UnifiedFileSink.new(
+      #     configurations: [
+      #       {
+      #         file: $stdout,
+      #         format: :console,
+      #         show_timestamp: true,
+      #         show_level: true
+      #       },
+      #       {
+      #         file: "logs/debug.log",
+      #         format: :text,
+      #         min_level: :debug,
+      #         include_context: true
+      #       },
+      #       {
+      #         file: "logs/audit.log",
+      #         format: :json,
+      #         min_level: :info,
+      #         include_metadata: true
+      #       }
+      #     ]
+      #   )
+      class UnifiedFileSink < Base
+        # @return [Array<Hash>] list of output configurations
+        attr_reader :configurations
+
+        # Initialize unified file sink
+        #
+        # @param configurations [Array<Hash>] list of output configurations
+        def initialize(configurations: [])
+          @configurations = validate_configurations(configurations)
+          @formatters = {}
+          @files = {}
+
+          # Pre-initialize formatters and files
+          initialize_formatters
+          initialize_files
+        end
+
+        # Execute sink logic to write log entry to configured outputs
+        #
+        # @param log_request [LogRequest] the log request to process
+        # @yield [LogRequest] yields the processed log request to the next sink
+        # @yieldreturn [LogRequest] the processed log request
+        # @return [LogRequest] the final processed log request
+        def call(log_request, &block)
+          write_to_outputs(log_request)
+          block&.call(log_request) if block_given?
+          log_request
+        end
+
+        # Get sink configuration
+        #
+        # @return [Hash] sink configuration
+        def config
+          {
+            name: self.class.name.split("::").last,
+            configurations_count: @configurations.length,
+            configurations: @configurations.map { |config| sanitize_config(config) },
+          }
+        end
+
+        private
+
+        # Validate configuration array
+        #
+        # @param configurations [Array<Hash>] configurations to validate
+        # @return [Array<Hash>] validated configurations
+        # @raise [ArgumentError] if configuration is invalid
+        def validate_configurations(configurations)
+          raise ArgumentError, "configurations must be an array" unless configurations.is_a?(Array)
+          raise ArgumentError, "at least one configuration is required" if configurations.empty?
+
+          configurations.each_with_index do |config, index|
+            validate_single_configuration(config, index)
+          end
+
+          configurations
+        end
+
+        # Validate a single configuration
+        #
+        # @param config [Hash] configuration to validate
+        # @param index [Integer] configuration index for error messages
+        # @raise [ArgumentError] if configuration is invalid
+        def validate_single_configuration(config, index)
+          raise ArgumentError, "configuration #{index} must be a hash" unless config.is_a?(Hash)
+
+          required_keys = %i[file format]
+          missing_keys = required_keys - config.keys
+          unless missing_keys.empty?
+            raise ArgumentError,
+                  "configuration #{index} missing required keys: #{missing_keys.join(", ")}"
+          end
+
+          # Validate file
+          file = config[:file]
+          unless file.is_a?(String) || file.is_a?(IO) || file.respond_to?(:write)
+            raise ArgumentError, "configuration #{index} file must be a String path, IO object, or writable object"
+          end
+
+          # Validate format
+          format = config[:format]
+          unless format.is_a?(Symbol) || format.is_a?(String)
+            raise ArgumentError, "configuration #{index} format must be a Symbol or String"
+          end
+
+          # Validate log levels if specified
+          if config[:min_level] && !valid_log_level?(config[:min_level])
+            raise ArgumentError, "configuration #{index} min_level must be a valid log level"
+          end
+
+          return unless config[:max_level] && !valid_log_level?(config[:max_level])
+
+          raise ArgumentError, "configuration #{index} max_level must be a valid log level"
+        end
+
+        # Check if log level is valid
+        #
+        # @param level [Symbol] log level to check
+        # @return [Boolean] true if valid
+        def valid_log_level?(level)
+          %i[debug info warn error fatal success].include?(level)
+        end
+
+        # Initialize formatters for each configuration
+        #
+        # @return [void]
+        def initialize_formatters
+          @configurations.each_with_index do |config, index|
+            format = config[:format].to_sym
+            formatter_options = config[:formatter_options] || {}
+
+            # Merge configuration options into formatter options
+            formatter_options[:include_context] = config[:include_context] if config.key?(:include_context)
+            formatter_options[:include_metadata] = config[:include_metadata] if config.key?(:include_metadata)
+            formatter_options[:show_timestamp] = config[:show_timestamp] if config.key?(:show_timestamp)
+            formatter_options[:show_level] = config[:show_level] if config.key?(:show_level)
+
+            begin
+              formatter_class = FormatRegistry.get(format)
+
+              # Handle different formatter initialization patterns
+              @formatters[index] = if formatter_class == Formatters::ConsoleFormatter
+                  # ConsoleFormatter expects keyword arguments
+                  formatter_class.new(
+                    show_timestamp: formatter_options[:show_timestamp] || false,
+                    show_level: formatter_options[:show_level] || false,
+                  )
+                elsif formatter_class == Formatters::TextFormatter
+                  # TextFormatter expects keyword arguments
+                  formatter_class.new(
+                    timestamp_format: formatter_options[:timestamp_format] || "%Y-%m-%d %H:%M:%S",
+                    include_context: formatter_options[:include_context] || false,
+                  )
+                elsif formatter_class == Formatters::JsonFormatter
+                  # JsonFormatter expects keyword arguments
+                  formatter_class.new(
+                    options: formatter_options,
+                  )
+                elsif formatter_class == Formatters::PlainTextFormatter
+                  # PlainTextFormatter expects keyword arguments
+                  formatter_class.new(
+                    include_context: formatter_options[:include_context] || false,
+                  )
+                elsif formatter_options.empty?
+                  # Other formatters expect hash or no arguments
+                  formatter_class.new
+                else
+                  formatter_class.new(formatter_options)
+                end
+            rescue ArgumentError => e
+              raise ArgumentError, "configuration #{index} has invalid format '#{format}': #{e.message}"
+            end
+          end
+        end
+
+        # Initialize file handles for each configuration
+        #
+        # @return [void]
+        def initialize_files
+          @configurations.each_with_index do |config, index|
+            file = config[:file]
+
+            if file.is_a?(String)
+              # Ensure directory exists
+              FileUtils.mkdir_p(File.dirname(file)) unless File.dirname(file) == "."
+
+              # Open file with appropriate mode
+              mode = config[:append] == false ? "w" : "a"
+              @files[index] = File.open(file, mode)
+            else
+              # Use IO object directly
+              @files[index] = file
+            end
+          end
+        end
+
+        # Write log request to all applicable outputs
+        #
+        # @param log_request [LogRequest] the log request to write
+        def write_to_outputs(log_request)
+          @configurations.each_with_index do |config, index|
+            next unless should_output?(log_request, config)
+
+            formatter = @formatters[index]
+            file = @files[index]
+
+            formatted_message = formatter.format(log_request)
+            file.write(formatted_message)
+            file.write("\n") unless config[:no_newline]
+            file.flush
+          end
+        end
+
+        # Check if log request should be output to this configuration
+        #
+        # @param log_request [LogRequest] the log request
+        # @param config [Hash] the output configuration
+        # @return [Boolean] true if should output
+        def should_output?(log_request, config)
+          # Check level filtering
+          return false if config[:min_level] && !level_greater_or_equal?(log_request.level, config[:min_level])
+
+          return false if config[:max_level] && !level_less_or_equal?(log_request.level, config[:max_level])
+
+          # Check custom condition
+          return false if config[:condition] && !config[:condition].call(log_request)
+
+          true
+        end
+
+        # Check if log level is greater than or equal to minimum level
+        #
+        # @param level [Symbol] log level to check
+        # @param min_level [Symbol] minimum level
+        # @return [Boolean] true if level >= min_level
+        def level_greater_or_equal?(level, min_level)
+          levels = %i[debug info warn error fatal success]
+          levels.index(level) >= levels.index(min_level)
+        end
+
+        # Check if log level is less than or equal to maximum level
+        #
+        # @param level [Symbol] log level to check
+        # @param max_level [Symbol] maximum level
+        # @return [Boolean] true if level <= max_level
+        def level_less_or_equal?(level, max_level)
+          levels = %i[debug info warn error fatal success]
+          levels.index(level) <= levels.index(max_level)
+        end
+
+        # Sanitize configuration for display (remove sensitive data)
+        #
+        # @param config [Hash] configuration to sanitize
+        # @return [Hash] sanitized configuration
+        def sanitize_config(config)
+          sanitized = config.dup
+
+          # Remove condition procs and other non-serializable items
+          sanitized.delete(:condition)
+
+          # Convert IO objects to string representation
+          sanitized[:file] = "<#{sanitized[:file].class.name}>" if sanitized[:file].is_a?(IO)
+
+          sanitized
+        end
+      end
+    end
+  end
+end