lumberjack 1.4.2 → 2.0.0

data/lib/lumberjack/device/null.rb

@@ -1,15 +1,33 @@
 # frozen_string_literal: true
 
 module Lumberjack
-  class Device
-    # This is a logging device that produces no output. It can be useful in
-    # testing environments when log file output is not useful.
-    class Null < Device
-      def initialize(*args)
-      end
+  # A logging device that discards all output. This device provides a silent
+  # logging implementation useful for testing environments, performance benchmarks,
+  # or production scenarios where logging needs to be temporarily disabled without
+  # changing logger configuration.
+  #
+  # The Null device implements the complete Device interface but performs no
+  # actual operations, making it both efficient and transparent. It accepts
+  # any constructor arguments for compatibility but ignores them all.
+  #
+  # @example Creating a silent logger
+  #   logger = Lumberjack::Logger.new(Lumberjack::Device::Null.new)
+  #   logger.info("This message is discarded")
+  #
+  # @example Using the convenience constructor
+  #   logger = Lumberjack::Logger.new(:null)
+  #   logger.error("This error is also discarded")
+  class Device::Null < Device
+    DeviceRegistry.add(:null, self)
 
-      def write(entry)
-      end
+    def initialize(*args)
+    end
+
+    # Discard the log entry without performing any operation.
+    #
+    # @param entry [Lumberjack::LogEntry] The log entry to discard.
+    # @return [void]
+    def write(entry)
     end
   end
 end

data/lib/lumberjack/device/size_rolling_log_file.rb

@@ -1,63 +1,22 @@
 # frozen_string_literal: true
 
 module Lumberjack
-  class Device
-    # This is a log device that appends entries to a file and rolls the file when it reaches a specified
-    # size threshold. When a file is rolled, it will have an number extension appended to the file name.
-    # For example, if the log file is named production.log, the first time it is rolled it will be renamed
-    # production.log.1, then production.log.2, etc.
-    class SizeRollingLogFile < RollingLogFile
-      attr_reader :max_size
+  # Deprecated device. Use LogFile instead.
+  #
+  # @deprecated Use Lumberjack::Device::LogFile
+  class Device::SizeRollingLogFile < Device::LogFile
+    attr_reader :max_size
 
-      # Create an new log device to the specified file. The maximum size of the log file is specified with
-      # the :max_size option. The unit can also be specified: "32K", "100M", "2G" are all valid.
-      def initialize(path, options = {})
-        @manual = options[:manual]
-        @max_size = options[:max_size]
-        if @max_size.is_a?(String)
-          if @max_size =~ /^(\d+(\.\d+)?)([KMG])?$/i
-            @max_size = $~[1].to_f
-            units = $~[3].to_s.upcase
-            case units
-            when "K"
-              @max_size *= 1024
-            when "M"
-              @max_size *= 1024**2
-            when "G"
-              @max_size *= 1024**3
-            end
-            @max_size = @max_size.round
-          else
-            raise ArgumentError.new("illegal value for :max_size (#{@max_size})")
-          end
-        end
+    # Create an new log device to the specified file. The maximum size of the log file is specified with
+    # the :max_size option. The unit can also be specified: "32K", "100M", "2G" are all valid.
+    def initialize(path, options = {})
+      Utils.deprecated("Lumberjack::Device::SizeRollingLogFile", "Lumberjack::Device::SizeRollingLogFile is deprecated and will be removed in version 2.1; use Lumberjack::Device::LogFile instead.")
 
-        super
-      end
+      @max_size = options[:max_size]
+      new_options = options.reject { |k, _| k == :max_size }.merge(shift_size: max_size)
+      new_options[:shift_age] = 10 unless options[:shift_age].is_a?(Integer) && options[:shift_age] >= 0
 
-      def archive_file_suffix
-        next_archive_number.to_s
-      end
-
-      def roll_file?
-        @manual || stream.stat.size > @max_size
-      rescue SystemCallError
-        false
-      end
-
-      protected
-
-      # Calculate the next archive file name extension.
-      def next_archive_number # :nodoc:
-        max = 0
-        Dir.glob("#{path}.*").each do |filename|
-          if /\.\d+\z/ =~ filename
-            suffix = filename.split(".").last.to_i
-            max = suffix if suffix > max
-          end
-        end
-        max + 1
-      end
+      super(path, new_options)
     end
   end
 end

data/lib/lumberjack/device/test.rb

@@ -0,0 +1,337 @@
+# frozen_string_literal: true
+
+module Lumberjack
+  # An in-memory logging device designed specifically for testing and debugging
+  # scenarios. This device captures log entries in a thread-safe buffer, allowing
+  # test code to make assertions about logged content, verify logging behavior,
+  # and inspect log entry details without writing to external outputs.
+  #
+  # The device provides matching capabilities through integration
+  # with LogEntryMatcher, supporting pattern matching on messages, severity levels,
+  # attributes, and program names. This makes it ideal for comprehensive logging
+  # verification in test suites.
+  #
+  # The buffer is automatically managed with configurable size limits to prevent
+  # memory issues during long-running tests, and provides both individual entry
+  # access and bulk matching operations.
+  #
+  # @example Basic test setup
+  #   logger = Lumberjack::Logger.new(Lumberjack::Device::Test.new)
+  #   logger.info("User logged in", user_id: 123)
+  #
+  #   expect(logger.device.entries.size).to eq(1)
+  #   expect(logger.device.last_entry.message).to eq("User logged in")
+  #
+  # @example Using convenience constructor
+  #   logger = Lumberjack::Logger.new(:test)
+  #   logger.warn("Something suspicious", ip: "192.168.1.100")
+  #
+  #   expect(logger.device).to include(severity: :warn, message: /suspicious/)
+  #   expect(logger.device).to include(attributes: {ip: "192.168.1.100"})
+  #
+  # @example Advanced pattern matching
+  #   logger = Lumberjack::Logger.new(:test)
+  #   logger.error("Database error: connection timeout",
+  #                database: "users", timeout: 30.5, retry_count: 3)
+  #
+  #   expect(logger.device).to include(
+  #     severity: :error,
+  #     message: /Database error/,
+  #     attributes: {
+  #       database: "users",
+  #       timeout: Float,
+  #       retry_count: be > 0
+  #     }
+  #   )
+  #
+  # @example Nested attribute matching
+  #   logger.info("Request completed", request: {method: "POST", path: "/users"})
+  #
+  #   expect(logger.device).to include(
+  #     attributes: {"request.method" => "POST", "request.path" => "/users"}
+  #   )
+  #
+  # @example Capturing logs to a file only for failed rspec tests
+  #   # Set up test logger (presumably in an initializer)
+  #   Application.logger = Lumberjack::Logger.new(:test)
+  #
+  #   # In your spec_helper or rails_helper.rb
+  #   RSpec.configure do |config|
+  #     failed_test_logs = Lumberjack::Logger.new("log/test.log")
+  #
+  #     config.around do |example|
+  #       Application.logger.device.clear
+  #
+  #       example.run
+  #
+  #       if example.exception
+  #         failed_test_logs.error("Test failed: #{example.full_description}")
+  #         Application.logger.device.write_to(failed_test_logs)
+  #       end
+  #     end
+  #   end
+  #
+  # @see LogEntryMatcher
+  class Device::Test < Device
+    DeviceRegistry.add(:test, self)
+
+    # @!attribute [rw] max_entries
+    #   @return [Integer] The maximum number of entries to retain in the buffer
+    attr_accessor :max_entries
+
+    # Configuration options passed to the constructor. While these don't affect
+    # device behavior, they can be useful in tests to verify that options are
+    # correctly passed through device creation and configuration pipelines.
+    #
+    # @return [Hash] A copy of the options hash passed during initialization
+    attr_reader :options
+
+    class << self
+      # Format a log entry or expectation hash into a more human readable format. This is
+      # intended for use in test failure messages to help diagnose why a match failed when
+      # calling +include?+ or +match+.
+      #
+      # @param expectation [Hash, Lumberjack::LogEntry] The expectation or log entry to format.
+      # @option severity [String, Symbol, Integer] The severity level to match.
+      # @option message [String, Regexp, Object] Pattern to match against log entry messages.
+      # @option attributes [Hash] Hash of attribute patterns to match against log entry attributes.
+      # @option progname [String, Regexp, Object] Pattern to match against the program name that generated the log entry.
+      # @param indent [Integer] The number of spaces to indent each line.
+      # @return [String] A formatted string representation of the expectation or log entry.
+      def formatted_expectation(expectation, indent: 0)
+        if expectation.is_a?(Lumberjack::LogEntry)
+          expectation = {
+            "severity" => expectation.severity_label,
+            "message" => expectation.message,
+            "progname" => expectation.progname,
+            "attributes" => expectation.attributes
+          }
+        end
+
+        expectation = expectation.transform_keys(&:to_s).compact
+        severity = Lumberjack::Severity.coerce(expectation["severity"]) if expectation.include?("severity")
+
+        message = []
+        indent_str = " " * indent
+        message << "#{indent_str}severity: #{Lumberjack::Severity.level_to_label(severity)}" if severity
+        message << "#{indent_str}message: #{expectation["message"]}" if expectation.include?("message")
+        message << "#{indent_str}progname: #{expectation["progname"]}" if expectation.include?("progname")
+        if expectation["attributes"].is_a?(Hash) && !expectation["attributes"].empty?
+          attributes = Lumberjack::Utils.flatten_attributes(expectation["attributes"])
+          label = "attributes:"
+          prefix = "#{indent_str}#{label}"
+          attributes.sort_by(&:first).each do |name, value|
+            message << "#{prefix} #{name}: #{value.inspect}"
+            prefix = "#{indent_str}#{" " * label.length}"
+          end
+        end
+        message.join(Lumberjack::LINE_SEPARATOR)
+      end
+    end
+
+    # Initialize a new Test device with configurable buffer management.
+    # The device creates a thread-safe in-memory buffer for capturing log
+    # entries with automatic size management to prevent memory issues.
+    #
+    # @param options [Hash] Configuration options for the test device
+    # @option options [Integer] :max_entries (1000) The maximum number of entries
+    #   to retain in the buffer. When this limit is exceeded, the oldest entries
+    #   are automatically removed to maintain the size limit.
+    def initialize(options = {})
+      @buffer = []
+      @max_entries = options[:max_entries] || 1000
+      @lock = Mutex.new
+      @options = options.dup
+    end
+
+    # Write a log entry to the in-memory buffer. The method is thread-safe and
+    # automatically manages buffer size by removing the oldest entries when
+    # the maximum capacity is exceeded. Entries are ignored if max_entries is
+    # set to less than 1.
+    #
+    # @param entry [Lumberjack::LogEntry] The log entry to store in the buffer
+    # @return [void]
+    def write(entry)
+      return if max_entries < 1
+
+      @lock.synchronize do
+        @buffer << entry
+
+        while @buffer.size > max_entries
+          @buffer.shift
+        end
+      end
+    end
+
+    # Return a thread-safe copy of all captured log entries. The returned array
+    # is a snapshot of the current buffer state and can be safely modified
+    # without affecting the internal buffer.
+    #
+    # @return [Array<Lumberjack::LogEntry>] A copy of all captured log entries
+    #   in chronological order (oldest first)
+    def entries
+      @lock.synchronize { @buffer.dup }
+    end
+
+    # Return the most recently captured log entry. This provides quick access
+    # to the latest logged information without needing to access the full
+    # entries array.
+    #
+    # @return [Lumberjack::LogEntry, nil] The most recent log entry, or nil
+    #   if no entries have been captured yet
+    def last_entry
+      @buffer.last
+    end
+
+    # Clear all captured log entries from the buffer. This method is useful
+    # for resetting the device state between tests or when you want to start
+    # fresh log capture without creating a new device instance.
+    #
+    # @return [void]
+    def clear
+      @buffer = []
+      nil
+    end
+
+    # Write the captured log entries out to another logger or device. This can be useful
+    # in testing scenarios where you want to preserve log output for failed tests.
+    #
+    # @param logger [Lumberjack::Logger, Lumberjack::Device] The target logger or device
+    #   to which captured entries should be written
+    # @return [void]
+    def write_to(logger)
+      device = (logger.is_a?(Lumberjack::Device) ? logger : logger.device)
+      entries.each do |entry|
+        device.write(entry)
+      end
+
+      nil
+    end
+
+    # Test whether any captured log entries match the specified criteria.
+    # This method provides a convenient interface for making assertions about
+    # logged content using flexible pattern matching capabilities.
+    #
+    # Severity can be specified as a numeric constant (Logger::WARN), symbol
+    # (:warn), or string ("warn"). Messages support exact string matching or
+    # regular expression patterns. Attributes support nested matching using
+    # dot notation and can use any matcher values supported by your test
+    # framework (e.g., RSpec's +anything+, +instance_of+, etc.).
+    #
+    # @param options [Hash] The matching criteria to test against captured entries
+    # @option options [String, Regexp, Object] :message Pattern to match against
+    #   log entry messages. Supports exact strings, regular expressions, or any
+    #   object that responds to case equality (===)
+    # @option options [String, Symbol, Integer] :severity The severity level to
+    #   match. Accepts symbols (:debug, :info, :warn, :error, :fatal), strings,
+    #   or numeric Logger constants
+    # @option options [Hash] :attributes Hash of attribute patterns to match.
+    #   Supports nested attributes using dot notation (e.g., "user.id" matches
+    #   { user: { id: value } }). Values can be exact matches or test framework matchers
+    # @option options [String, Regexp, Object] :progname Pattern to match against
+    #   the program name that generated the log entry
+    #
+    # @return [Boolean] True if any captured entries match all specified criteria,
+    #   false otherwise
+    #
+    # @example Basic message and severity matching
+    #   expect(device).to include(severity: :error, message: "Database connection failed")
+    #
+    # @example Regular expression message matching
+    #   expect(device).to include(severity: :info, message: /User \d+ logged in/)
+    #
+    # @example Attribute matching with exact values
+    #   expect(device).to include(attributes: {user_id: 123, action: "login"})
+    #
+    # @example Nested attribute matching
+    #   expect(device).to include(attributes: {"request.method" => "POST", "response.status" => 200})
+    #
+    # @example Using test framework matchers (RSpec example)
+    #   expect(device).to include(
+    #     severity: :warn,
+    #     message: start_with("Warning:"),
+    #     attributes: {duration: be_a(Float), retries: be > 0}
+    #   )
+    #
+    # @example Multiple criteria matching
+    #   expect(device).to include(
+    #     severity: :error,
+    #     message: /timeout/i,
+    #     progname: "DatabaseWorker",
+    #     attributes: {database: "users", timeout_seconds: be > 30}
+    #   )
+    def include?(options)
+      options = options.transform_keys(&:to_sym)
+      !!match(**options)
+    end
+
+    # Find and return the first captured log entry that matches the specified
+    # criteria. This method is useful when you need to inspect specific entry
+    # details or perform more complex assertions on individual entries.
+    #
+    # Uses the same flexible matching capabilities as include? but returns
+    # the actual LogEntry object instead of a boolean result.
+    #
+    # @param message [String, Regexp, Object, nil] Pattern to match against
+    #   log entry messages. Supports exact strings, regular expressions, or
+    #   any object that responds to case equality (===)
+    # @param severity [String, Symbol, Integer, nil] The severity level to match.
+    #   Accepts symbols, strings, or numeric Logger constants
+    # @param attributes [Hash, nil] Hash of attribute patterns to match against
+    #   log entry attributes. Supports nested matching using dot notation
+    # @param progname [String, Regexp, Object, nil] Pattern to match against
+    #   the program name that generated the log entry
+    #
+    # @return [Lumberjack::LogEntry, nil] The first matching log entry, or nil
+    #   if no entries match the specified criteria
+    #
+    # @example Finding a specific error entry
+    #   error_entry = device.match(severity: :error, message: /database/i)
+    #   expect(error_entry.attributes[:table_name]).to eq("users")
+    #   expect(error_entry.time).to be_within(1.second).of(Time.now)
+    #
+    # @example Finding entries with specific attributes
+    #   auth_entry = device.match(attributes: {user_id: 123, action: "login"})
+    #   expect(auth_entry.severity_label).to eq("INFO")
+    #   expect(auth_entry.progname).to eq("AuthService")
+    #
+    # @example Handling no matches
+    #   missing_entry = device.match(severity: :fatal)
+    #   expect(missing_entry).to be_nil
+    #
+    # @example Complex attribute matching
+    #   api_entry = device.match(
+    #     message: /API request/,
+    #     attributes: {"request.endpoint" => "/users", "response.status" => 200}
+    #   )
+    #   expect(api_entry.attributes["request.endpoint"]).to eq("/users")
+    def match(message: nil, severity: nil, attributes: nil, progname: nil)
+      matcher = LogEntryMatcher.new(message: message, severity: severity, attributes: attributes, progname: progname)
+      entries.detect { |entry| matcher.match?(entry) }
+    end
+
+    # Get the closest matching log entry from the captured entries based on a scoring system.
+    # This method evaluates how well each entry matches the specified criteria and
+    # returns the entry with the highest score, provided it meets a minimum threshold.
+    # If no entries meet the threshold, nil is returned.
+    #
+    # This method can be used in tests to return the best match when an assertion fails
+    # to aid in diagnosing why no entries met the criteria.
+    #
+    # @param message [String, Regexp, Object, nil] Pattern to match against
+    #   log entry messages. Supports exact strings, regular expressions, or
+    #   any object that responds to case equality (===)
+    # @param severity [String, Symbol, Integer, nil] The severity level to match.
+    #   Accepts symbols, strings, or numeric Logger constants
+    # @param attributes [Hash, nil] Hash of attribute patterns to match against
+    #   log entry attributes. Supports nested matching using dot notation
+    # @param progname [String, Regexp, Object, nil] Pattern to match against
+    #   the program name that generated the log entry
+    # @return [Lumberjack::LogEntry, nil] The closest matching log entry, or nil
+    #   if no entries meet the minimum score threshold
+    def closest_match(message: nil, severity: nil, attributes: nil, progname: nil)
+      matcher = LogEntryMatcher.new(message: message, severity: severity, attributes: attributes, progname: progname)
+      matcher.closest(entries)
+    end
+  end
+end