legion-logging 1.5.19 → 1.5.21

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '037790df316dd01a4f090a1d02a4b07fab65feac2d0c70a501d949d57fd45276'
-  data.tar.gz: af6fda1d1af5fe004fe8e4b76c225aa997f4075aed19b8d557f4090cec9e7770
+  metadata.gz: c94ba448ab05d8309fd27afcd2672364c2d843ed277036f640cf798715fe97af
+  data.tar.gz: 146fa61ef555986daadc1e94996e53e936b34c47a71b8647fdad3c240808e107
 SHA512:
-  metadata.gz: 659f1952bc1c331c74528153276b9a593eb1d775c67fbd57797434e78f1f016612ca2a2e0322ab6ad041f7101efede0a94e803c388dedf96608727431b5c303c
-  data.tar.gz: 9f4150366ac4f64da3b1c14a429058820de2cb639dd810974f6448a5ca78fa7e32d5c13f23100eb0d21802143091df232b0ffd89263313f00b7df1355341b547
+  metadata.gz: 4391e8e771c4d747469af379d33b1b3f397f60426e6b750dbdc1a6de16e3fa88085abefe9a36760d058aed2ffef559f473e94a37f5bf1a1eb006f058fc3ac1db
+  data.tar.gz: e2d141523b19fe6f0c300d97b62fc28d6aeced3e9db8a8c276564cfd0fef5acdb0398aa1eac1542803df34ca12de171326103224739b1c3f500fda7e8dfe5a53

data/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Legion::Logging Changelog
 
+## [1.5.21] - 2026-10-30
+
+### Changed
+- Enforce a hard retained-byte cap for managed log files: split oversized writes before the per-file limit, trim existing oversized files to their newest bytes, and immediately prune excess archives.
+- Capture eligible inherited stdout/stderr through bounded kernel pipes, including raw descriptor and child-process writes; full pipes backpressure producers instead of allocating an unbounded byte queue.
+- Coordinate same-path file writers with persistent zero-byte lock sidecars and close regular data descriptors between operations so idle devices cannot pin deleted archives.
+- Fail closed on rotation or drain errors rather than append beyond the cap. The bound covers managed file contents, not filesystem metadata, snapshots, external writers, hardlink aliases, or externally retained descriptors.
+
+### Fixed
+- Include downstream raw-stdio drains in `stop_async_writer` deadlines, including synchronous and file-only module logging.
+- Preserve capture after pre-drain timeouts; wait for worker cleanup before reporting successful disable, and prevent inherited children from controlling parent workers or silently changing their retention policy.
+- Preserve existing instance loggers across process-capture disable/re-enable and close destinations if fail-closed descriptor reattachment itself fails.
+
+## [1.5.20] - 2026-10-29
+
+### Added
+- Size-based log rotation, on by default (100 MiB x 5 archives), configurable via `logging.rotation`
+  (`enabled`, `max_size_mb`, `max_files`, `stdio`) or `setup(rotation: {...})`; `rotation: false` disables it
+- `Legion::Logging::RotatingFile`: self-rotating append-mode device used for `log_file:`; reopens if another
+  process rotated the path
+- `Legion::Logging::StdioRotator`: rotates the file behind stdout/stderr when a supervisor (launchd
+  `StandardOutPath`, systemd `append:`) redirected them to an append-mode regular file, using `IO#reopen` so
+  raw stderr output follows the new file. Checks are logger-write-driven, not a hard disk quota.
+
+### Fixed
+- Preserve current async OutputLogger routing, lifecycle locks, shutdown deadlines, and forwarding settings while integrating rotation (PR #21).
+- Honor instance logger rotation overrides and opt-out; rotate distinct stderr files independently, including when stdout is a pipe.
+- Preserve nested Settings lookup guards, normalize invalid limits, and reopen remembered paths after external rotation.
+- Keep non-regular devices untouched and report rotation failures without discarding the incoming message.
+
 ## [1.5.19] - 2026-10-29
 
 ### Changed

data/CLAUDE.md

@@ -18,7 +18,8 @@ Legion::Logging (singleton module)
 ├── SIEMExporter      # PHI-redacting SIEM export (Splunk HEC, ELK)
 ├── Shipper           # Bounded batch-delivery worker (file/HTTP transports)
 ├── Redactor          # PII/PHI + secret pattern redaction (opt-in)
-└── MultiIO           # Synchronous, sequential writes to multiple destinations
+├── MultiIO           # Synchronous, sequential writes to multiple destinations
+└── Rotation          # RotatingFile (log_file) + shared StdioRotator (redirected stdout/stderr)
 
 # Module-level writer lambdas (pluggable forwarding slots)
 Legion::Logging.log_writer       # ->(event, routing_key:, headers:, properties:) {}
@@ -41,6 +42,7 @@ Legion::Logging.exception_writer # ->(event, routing_key:, headers:, properties:
 - **Forwarding levels** — `logging.transport.log_levels` accepts strings/symbols; absent or empty lists default to warn/error/fatal. Settings guards use defaults while Settings is unloaded rather than initializing it.
 - **Synchronous APIs** — `MultiIO`, direct transport delivery, SIEM export, and direct hook dispatch remain synchronous. Shipper filtering/redaction run on its caller; bounded batch delivery runs on its worker.
 - **EventBuilder** — Structured event hashes from log context (caller, exception, lex identity). `fingerprint` produces MD5 for dedup.
+- **Rotation** — Hard managed-content cap: 100 MiB per file plus five archives (600 MiB/path). `RotatingFile` splits writes, trims oversized existing files, prunes excess archives, and coordinates same-path/same-policy writers through a persistent zero-byte `.lock`. Regular data FDs close between operations. Eligible append-mode inherited stdout/stderr become bounded pipes drained by dedicated capped sinks, including raw-only and child writes; saturation blocks, errors fail closed. `stop_async_writer` drains both layers under one deadline, including sync/file-only module logging; call it after final raw writes. Capture is process-wide; disable only with quiescent producers. Pre-drain timeout keeps capture active; final cleanup failure/timeout requires restart. Instance loggers survive disable/re-enable. Forked children cannot control parent workers or change their policy. File contents are bounded, not filesystem metadata/snapshots, external writers/aliases, or externally held/inherited descriptors; a volume-level guarantee needs an OS quota.
 
 ## Role in LegionIO
 

data/README.md

@@ -2,7 +2,7 @@
 
 Logging module for the [LegionIO](https://github.com/LegionIO/LegionIO) framework. Provides colorized console output via Rainbow, structured JSON logging, multi-output IO, and a consistent logging interface across all Legion gems and extensions.
 
-**Version**: 1.5.19
+**Version**: 1.5.21
 
 ## Installation
 
@@ -31,6 +31,71 @@ Legion::Logging.error('something went wrong')
 Legion::Logging.fatal('critical failure')
 ```
 
+### Log Rotation
+
+Managed file contents have a hard byte bound: **100 MiB per file with five archives** by
+default (`legion.log`, `legion.log.1` through `legion.log.5`), or **600 MiB per managed path**.
+The bound is `max_bytes * (max_files + 1)`, where `max_bytes` is `max_size_mb * 1024 * 1024`,
+rounded down to a positive byte count. Separate stdout, stderr, and configured log paths
+each have their own retention budget.
+
+This covers `log_file:` and eligible stdout/stderr files inherited from launchd, systemd
+`append:`, or shell `>>` redirects. Only append-mode regular inherited files qualify;
+pipes, terminals, and non-append redirects (`>`) remain unchanged. Eligible stderr is captured
+independently even when stdout is a pipe. The actual descriptors become bounded kernel pipes,
+so raw writes and inherited child-process writes also pass through the capped sinks without
+needing a logger call. Full pipes block producers; there is no unbounded Ruby byte queue.
+Raw syscall callers must handle short writes, as with any pipe.
+
+Writes are split before a file exceeds its limit. Oversized records can cross archive,
+line, and UTF-8 character boundaries; concatenate archives oldest-first followed by the active
+file to read the retained byte stream. Enabling or tightening rotation trims each oversized
+existing file in place to its newest bytes and deletes archives beyond `max_files`.
+Rotation/drain failures do not fall back to uncapped appends; drain/control APIs surface errors.
+
+File writes use a stable, zero-byte `<path>.lock` sidecar to coordinate devices and processes.
+All cooperating writers must use the same canonical path and limits; do not delete the lock
+while writers are alive. Regular data descriptors close between operations so idle devices
+cannot retain deleted archives. External replacement is followed on the next write.
+
+This is a bound on **Legion-managed file contents**, not an OS/filesystem quota. Filesystem
+allocation overhead, snapshots, external writers, hardlink aliases, and descriptors retained
+outside these devices are outside the bound. A fork without exec during an in-flight file
+operation can inherit such a descriptor; close inherited descriptors or exec before leaving
+the child idle. A strict volume-level disk-space guarantee requires a filesystem quota.
+
+```json
+{
+  "logging": {
+    "rotation": { "enabled": true, "max_size_mb": 100, "max_files": 5, "stdio": true }
+  }
+}
+```
+
+```ruby
+Legion::Logging.setup(log_file: './legion.log', rotation: { max_size_mb: 50, max_files: 3 })
+Legion::Logging.setup(log_file: './legion.log', rotation: false) # disable
+Legion::Logging.setup(rotation: { stdio: false }) # leave inherited stdout/stderr alone
+logger = Legion::Logging::Logger.new(log_file: './extension.log', rotation: { max_size_mb: 25 })
+```
+
+Omitting `rotation:` reads `logging.rotation` from already-loaded Settings, otherwise uses the
+defaults above. Instance loggers honor the same overrides, including `rotation: false`.
+
+Inherited-stream capture is process-wide. Instance opt-out does not detach capture owned by
+another logger; module-level `setup(rotation: false)` or `setup(rotation: { stdio: false })`
+explicitly disables it. Quiesce raw producers, including children, before disabling capture.
+Pre-drain timeout leaves capture active; a failure or timeout during final handle cleanup
+leaves it fail-closed rather than restoring an uncapped fallback and requires process restart.
+Forked children may write through the inherited pipes but cannot drain/reset parent workers
+or request a different capture policy. Fork-without-exec children also retain pipe read ends,
+which can delay `EPIPE` after a parent drain failure until those children close them or exit.
+
+Captured stdio is asynchronous even with `async: false`: call `stop_async_writer(timeout: 2)`
+**after the final raw stdout/stderr writes** to drain both layers before exit. This does not
+detach capture, and abrupt process termination is not a delivery guarantee. Setup, explicit
+rotation, and retention changes remain synchronous control operations.
+
 ### Async Logging
 
 By default, `setup` enables async logging: log calls enqueue output for a background writer, including fatal messages. Async does not mean wait-free. The queue holds at most 10,000 entries by default, and producers wait for capacity when it fills.
@@ -48,7 +113,7 @@ Legion::Logging.setup(level: 'info', async: false)
 
 Bounded backpressure is intentional: saturation blocks callers rather than dropping logs or allowing unbounded memory growth. A stalled destination can therefore stall producers once the queue fills. Buffer capacity limits queued entries, not their total byte size, and does not guarantee delivery across process termination.
 
-Use `Legion::Logging.stop_async_writer(timeout: 2)` during shutdown. It closes admission and asks the worker to drain accepted entries, returning `true` only after that worker exits. A deadline expiry returns `false` without killing the worker or draining on the caller; release the blocked destination and retry shutdown. Calling shutdown from a writer callback requests closure but returns `false` rather than joining itself.
+Use `Legion::Logging.stop_async_writer(timeout: 2)` during shutdown, after the final raw stdio writes. It closes async admission and returns `true` only after the writer exits and relevant captured-stdio sinks finish their drain, within one shared deadline. It also drains captured stdio when async logging is disabled. A drain deadline returns `false` without killing workers or draining on the caller; release the blocked destination and retry. Calling shutdown from a writer callback requests closure but returns `false` rather than joining itself.
 
 A successful stop means queued entries have been processed, not that a sink durably stored them or an external service acknowledged them. AsyncWriter reports sink/callback failures locally and does not automatically retry them. The Shipper's retained-batch retry behavior is separate.
 

data/lib/legion/logging/builder.rb

@@ -3,6 +3,7 @@
 require 'fileutils'
 require 'monitor'
 require_relative 'output_logger'
+require_relative 'rotation'
 
 module Legion
   module Logging
@@ -123,36 +124,37 @@ module Legion
       end
 
       def output(**options)
-        set_log(logfile: options[:log_file], log_stdout: options[:log_stdout])
+        set_log(logfile: options[:log_file], log_stdout: options[:log_stdout], rotation: options[:rotation],
+                shutdown_timeout: options.fetch(:shutdown_timeout, 2))
       end
 
       def log
         @log ||= set_log
       end
 
-      def set_log(logfile: nil, log_stdout: nil, **)
+      # A nil rotation option reads loaded Settings; false disables rotation.
+      def set_log(logfile: nil, log_stdout: nil, rotation: nil, shutdown_timeout: 2, **)
         with_lifecycle_lock do
-          return false if @async_writer && stop_async_writer == false
+          deadline = ::Process.clock_gettime(::Process::CLOCK_MONOTONIC) + shutdown_timeout if shutdown_timeout
+          return false if @async_writer && stop_async_writer(timeout: shutdown_timeout) == false
 
           previous_log = @log
+          rotation_opts = Legion::Logging::Rotation.resolve(raw: rotation.nil? ? Legion::Logging::Rotation.from_settings : rotation)
+          remaining = [deadline - ::Process.clock_gettime(::Process::CLOCK_MONOTONIC), 0].max if deadline
+          stdout = stdout_target(rotation_opts: rotation_opts, uses_stdout: !logfile || log_stdout != false, timeout: remaining)
+          return false if stdout == false
 
           if logfile && log_stdout != false
-            path = prepare_log_path(logfile)
             require_relative 'multi_io'
-            file = File.new(path, 'a')
-            file.sync = true
-            io = MultiIO.new($stdout, file)
+            io = Legion::Logging::MultiIO.new(stdout, open_log_file(path: prepare_log_path(logfile), rotation_opts: rotation_opts))
             @log = Legion::Logging::OutputLogger.new(io)
           elsif logfile
-            file = File.new(prepare_log_path(logfile), 'a')
-            file.sync = true
-            @log = Legion::Logging::OutputLogger.new(file)
+            @log = Legion::Logging::OutputLogger.new(open_log_file(path: prepare_log_path(logfile), rotation_opts: rotation_opts))
           else
-            @log = Legion::Logging::OutputLogger.new($stdout)
+            @log = Legion::Logging::OutputLogger.new(stdout)
           end
 
           @log.async_writer = @async_writer
-
           close_replaced_log(previous_log)
           @log
         end
@@ -210,14 +212,52 @@ module Legion
 
       def stop_async_writer(timeout: 2)
         with_lifecycle_lock do
-          return true unless @async_writer
+          deadline = ::Process.clock_gettime(::Process::CLOCK_MONOTONIC) + timeout if timeout
+          return false if @async_writer && @async_writer.stop(timeout: timeout) == false
 
-          @async_writer.stop(timeout: timeout)
+          remaining = [deadline - ::Process.clock_gettime(::Process::CLOCK_MONOTONIC), 0].max if deadline
+          flush_stdio_output!(timeout: remaining)
         end
       end
 
       private
 
+      def open_log_file(path:, rotation_opts:)
+        if rotation_opts[:enabled]
+          return Legion::Logging::RotatingFile.new(path: path, max_bytes: rotation_opts[:max_bytes], max_files: rotation_opts[:max_files])
+        end
+
+        file = File.new(path, 'a')
+        file.sync = true
+        file
+      end
+
+      def stdout_target(rotation_opts:, uses_stdout:, timeout:)
+        if rotation_opts[:enabled] && rotation_opts[:stdio]
+          return $stdout unless uses_stdout || equal?(Legion::Logging)
+
+          return Legion::Logging::StdioRotator.shared(max_bytes: rotation_opts[:max_bytes], max_files: rotation_opts[:max_files]) || $stdout
+        end
+
+        return false if equal?(Legion::Logging) && !Legion::Logging::StdioRotator.reset!(timeout: timeout)
+
+        $stdout
+      end
+
+      def flush_stdio_output!(timeout:) # rubocop:disable Naming/PredicateMethod -- Performs a drain; false signals its deadline.
+        deadline = ::Process.clock_gettime(::Process::CLOCK_MONOTONIC) + timeout if timeout
+        device = @log&.instance_variable_get(:@logdev)&.dev
+        targets = defined?(Legion::Logging::MultiIO) && device.is_a?(Legion::Logging::MultiIO) ? device.targets : [device]
+        captures = targets.grep(Legion::Logging::StdioRotator)
+        current = Legion::Logging::StdioRotator.current
+        captures << current if equal?(Legion::Logging) && current && !captures.include?(current)
+        captures.each do |capture|
+          remaining = [deadline - ::Process.clock_gettime(::Process::CLOCK_MONOTONIC), 0].max if deadline
+          return false if capture.flush(timeout: remaining) == false
+        end
+        true
+      end
+
       def with_lifecycle_lock
         lock = LIFECYCLE_MUTEX.synchronize { @lifecycle_lock ||= Monitor.new }
         entered = lock.try_enter

data/lib/legion/logging/logger.rb

@@ -13,7 +13,7 @@ module Legion
 
       def initialize(level: 'info', log_file: nil, log_stdout: nil, lex: nil, trace: false, extended: false, trace_size: 4, format: :text, async: true, **opts)
         @lex = lex
-        set_log(logfile: log_file, log_stdout: log_stdout)
+        set_log(logfile: log_file, log_stdout: log_stdout, rotation: opts[:rotation])
         log_level(level)
         log_format(format: format, lex: lex, extended: extended, **opts)
         @color = opts[:color]

data/lib/legion/logging/multi_io.rb

@@ -3,8 +3,10 @@
 module Legion
   module Logging
     class MultiIO
+      attr_reader :targets
+
       def initialize(*targets)
-        @targets = targets.flatten
+        @targets = targets.flatten.freeze
       end
 
       def write(message)

data/lib/legion/logging/rotating_file.rb

@@ -0,0 +1,239 @@
+# frozen_string_literal: true
+
+module Legion
+  module Logging
+    # Every cooperating writer for a path must use the same limits. The stable
+    # lock file coordinates separate devices/processes and must not be removed.
+    class RotatingFile
+      BUFFER_BYTES = 64 * 1024
+
+      attr_reader :file_path, :max_bytes, :max_files
+
+      def initialize(path:, max_bytes:, max_files:)
+        unless max_bytes.is_a?(Integer) && max_bytes.positive? && max_files.is_a?(Integer) && max_files.positive?
+          raise ArgumentError, 'max_bytes and max_files must be positive integers'
+        end
+
+        @file_path = File.expand_path(path)
+        @max_bytes = max_bytes
+        @max_files = max_files
+        @mutex = Mutex.new
+        @archive_pattern = /\A#{Regexp.escape(File.basename(@file_path))}\.([1-9]\d*)\z/
+        @needs_normalization = true
+        @closed = false
+        synchronize_path { normalize_locked }
+      rescue StandardError
+        begin
+          @io&.close
+        ensure
+          @lock_io&.close
+        end
+        raise
+      end
+
+      def write(*messages)
+        raise ArgumentError, 'wrong number of arguments (given 0, expected 1+)' if messages.empty?
+
+        synchronize_path do
+          normalize_locked if @needs_normalization
+          next @io.write(*messages) unless @regular
+
+          trim_file(path: @file_path) if @io.size > @max_bytes
+          messages.sum { |message| write_message(message: message.to_s) }
+        end
+      end
+
+      def flush
+        @mutex.synchronize do
+          raise IOError, 'closed stream' if @closed
+
+          @io&.flush
+        end
+        self
+      end
+
+      def sync = true # rubocop:disable Naming/PredicateMethod -- IO#sync interface
+
+      def sync=(_value); end
+
+      def close
+        @mutex.synchronize do
+          return if @closed
+
+          @closed = true
+          begin
+            @io&.close
+          ensure
+            @lock_io.close if @lock_io && !@lock_io.closed?
+          end
+        end
+      end
+
+      def closed?
+        @mutex.synchronize { @closed }
+      end
+
+      def size
+        synchronize_path { @io.size }
+      end
+
+      def rotate!
+        synchronize_path do
+          normalize_locked if @needs_normalization
+          rotate_locked!
+        end
+      end
+
+      def configure(max_bytes:, max_files:)
+        unless max_bytes.is_a?(Integer) && max_bytes.positive? && max_files.is_a?(Integer) && max_files.positive?
+          raise ArgumentError, 'max_bytes and max_files must be positive integers'
+        end
+
+        synchronize_path do
+          @max_bytes = max_bytes
+          @max_files = max_files
+          @needs_normalization = true
+          normalize_locked
+        end
+        self
+      end
+
+      private
+
+      def open_file
+        file = File.new(@file_path, 'ab')
+        file.sync = true
+        file
+      end
+
+      def synchronize_path
+        @mutex.synchronize do
+          raise IOError, 'closed stream' if @closed
+
+          lock_path if @lock_io || File.file?(@file_path) || !File.exist?(@file_path)
+          begin
+            reopen_if_replaced
+            if @regular && !@lock_io
+              @io.close
+              @io = nil
+              lock_path
+              reopen_if_replaced
+            end
+            yield
+          ensure
+            begin
+              # Idle devices must not pin archives after another writer unlinks
+              # them. Release every regular data-file FD before the path lock.
+              if @regular && @io
+                @io.close
+                @io = nil
+              end
+            ensure
+              @lock_io&.flock(File::LOCK_UN)
+            end
+          end
+        end
+      end
+
+      def lock_path
+        # flock locks are inherited across fork with the open file description.
+        # Reopen in the child so its lock competes with its parent's lock.
+        if @lock_io && @lock_pid != ::Process.pid
+          @lock_io.close
+          @lock_io = nil
+        end
+        @lock_io ||= File.open("#{@file_path}.lock", File::RDWR | File::CREAT, 0o600)
+        @lock_pid = ::Process.pid
+        raise IOError, 'could not acquire log rotation lock' unless @lock_io.flock(File::LOCK_EX)
+      end
+
+      def reopen_if_replaced
+        if @io
+          current = @io.stat
+          target = File.stat(@file_path) if File.exist?(@file_path)
+          return if target && current.dev == target.dev && current.ino == target.ino
+        end
+
+        replace_io
+      end
+
+      def replace_io
+        previous = @io
+        @io = open_file
+        current = @io.stat
+        @regular = current.file?
+        @needs_normalization ||= @file_dev != current.dev || @file_ino != current.ino
+        @file_dev = current.dev
+        @file_ino = current.ino
+        previous&.close
+      end
+
+      def normalize_locked
+        if @regular
+          trim_file(path: @file_path)
+          directory = File.dirname(@file_path)
+          Dir.each_child(directory) do |name|
+            match = @archive_pattern.match(name)
+            next unless match
+
+            archive = File.join(directory, name)
+            if match[1].to_i > @max_files
+              File.unlink(archive)
+            else
+              trim_file(path: archive)
+            end
+          end
+        end
+        @needs_normalization = false
+      end
+
+      def trim_file(path:)
+        stat = File.stat(path)
+        return unless stat.file? && stat.size > @max_bytes
+
+        # Move the retained tail toward the beginning without a temporary file
+        # or a full-file allocation. Forward copies cannot overwrite unread data.
+        File.open(path, 'r+b') do |file|
+          source_offset = file.size - @max_bytes
+          offset = 0
+          buffer = +''.b
+          while offset < @max_bytes
+            file.seek(source_offset + offset)
+            chunk = file.read([BUFFER_BYTES, @max_bytes - offset].min, buffer)
+            raise IOError, 'log file changed while trimming its retained tail' if chunk.nil? || chunk.empty?
+
+            file.seek(offset)
+            offset += file.write(chunk)
+          end
+          file.truncate(@max_bytes)
+        end
+      end
+
+      def write_message(message:)
+        offset = 0
+        available = @max_bytes - @io.size
+        while offset < message.bytesize
+          unless available.positive?
+            rotate_locked!
+            available = @max_bytes
+          end
+          length = [message.bytesize - offset, available, BUFFER_BYTES].min
+          chunk = offset.zero? && length == message.bytesize ? message : message.byteslice(offset, length)
+          written = @io.write(chunk)
+          offset += written
+          available -= written
+        end
+        offset
+      end
+
+      def rotate_locked! # rubocop:disable Naming/PredicateMethod -- Renames files; false means a nonregular destination.
+        return false unless @regular
+
+        Rotation.shift_files(path: @file_path, max_files: @max_files)
+        replace_io
+        @needs_normalization = false
+        true
+      end
+    end
+  end
+end

data/lib/legion/logging/rotation.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+
+module Legion
+  module Logging
+    # Settings and descriptor detection shared by the byte-capped file and stdio sinks.
+    module Rotation
+      DEFAULTS = {
+        enabled:     true,
+        max_size_mb: 100,
+        max_files:   5,
+        stdio:       true
+      }.freeze
+
+      F_GETPATH = 50 # macOS fcntl(2) command; not exposed by the Fcntl module
+      MAXPATHLEN = 1024
+
+      class << self
+        # Normalizes rotation settings. Accepts nil, false (disabled), or a Hash
+        # with symbol or string keys. Missing keys fall back to DEFAULTS.
+        def resolve(raw:)
+          overrides = if raw == false
+                        { enabled: false }
+                      elsif raw.is_a?(Hash)
+                        raw.transform_keys(&:to_sym)
+                      else
+                        {}
+                      end
+          merged = DEFAULTS.merge(overrides.slice(*DEFAULTS.keys))
+          merged[:enabled] = merged[:enabled] != false
+          merged[:stdio] = merged[:stdio] != false
+          merged[:max_size_mb] = positive_number(merged[:max_size_mb], DEFAULTS[:max_size_mb])
+          merged[:max_files] = positive_number(merged[:max_files], DEFAULTS[:max_files]).to_i
+          merged[:max_files] = DEFAULTS[:max_files] unless merged[:max_files].positive?
+          bytes = merged[:max_size_mb] * 1024 * 1024
+          unless bytes.finite?
+            merged[:max_size_mb] = DEFAULTS[:max_size_mb]
+            bytes = merged[:max_size_mb] * 1024 * 1024
+          end
+          merged[:max_bytes] = [bytes.to_i, 1].max
+          merged
+        end
+
+        # Reads rotation settings from Legion::Settings once it has loaded.
+        # Guarded against re-entry because Settings may log while loading.
+        def from_settings
+          return nil unless defined?(Legion::Settings) && Legion::Settings.respond_to?(:[])
+          return nil if Thread.current[:legion_logging_rotation_lookup]
+
+          lookup_started = true
+          Thread.current[:legion_logging_rotation_lookup] = true
+          return nil if Legion::Settings.respond_to?(:loaded?) && !Legion::Settings.loaded?
+
+          logging = Legion::Settings[:logging]
+          logging[:rotation] if logging.is_a?(Hash)
+        rescue StandardError => e
+          warn("Legion::Logging::Rotation.from_settings failed: #{e.class}: #{e.message}")
+          nil
+        ensure
+          Thread.current[:legion_logging_rotation_lookup] = nil if lookup_started
+        end
+
+        # Shifts path.(n-1) -> path.n ... path -> path.1, dropping the oldest.
+        def shift_files(path:, max_files:)
+          oldest = "#{path}.#{max_files}"
+          FileUtils.rm(oldest, force: false) if File.exist?(oldest)
+          (max_files - 1).downto(1) do |i|
+            src = "#{path}.#{i}"
+            File.rename(src, "#{path}.#{i + 1}") if File.exist?(src)
+          end
+          File.rename(path, "#{path}.1") if File.exist?(path)
+        end
+
+        # Returns the filesystem path behind an IO if it is a regular file opened
+        # in append mode (launchd StandardOutPath, systemd append:, shell >>), or nil.
+        # Non-append redirects (shell >) are left alone.
+        def regular_file_path(io:)
+          return nil unless io.respond_to?(:stat) && io.stat.file?
+          return nil unless append_mode?(io: io)
+
+          path = fd_path(io)
+          return nil unless path && File.file?(path)
+          return nil unless same_file?(io: io, path: path)
+
+          path
+        rescue StandardError => e
+          warn("Legion::Logging::Rotation.regular_file_path failed: #{e.class}: #{e.message}")
+          nil
+        end
+
+        def same_file?(io:, path:)
+          return false unless File.exist?(path)
+
+          io_stat = io.stat
+          path_stat = File.stat(path)
+          io_stat.ino == path_stat.ino && io_stat.dev == path_stat.dev
+        rescue SystemCallError, IOError => e
+          warn("Legion::Logging::Rotation.same_file? path=#{path} failed: #{e.class}: #{e.message}")
+          false
+        end
+
+        def append_mode?(io:)
+          require 'fcntl'
+          io.fcntl(Fcntl::F_GETFL).anybits?(File::APPEND)
+        rescue NotImplementedError, SystemCallError, IOError => e
+          warn("Legion::Logging::Rotation.append_mode? failed: #{e.class}: #{e.message}")
+          false
+        end
+
+        private
+
+        def fd_path(io)
+          if io.respond_to?(:path)
+            path = File.expand_path(io.path)
+            return path if same_file?(io: io, path: path)
+          end
+
+          if RUBY_PLATFORM.include?('darwin')
+            require 'fcntl'
+            buf = "\0" * MAXPATHLEN
+            io.fcntl(F_GETPATH, buf)
+            buf.unpack1('Z*')
+          else
+            proc_link = "/proc/self/fd/#{io.fileno}"
+            File.readlink(proc_link) if File.symlink?(proc_link)
+          end
+        end
+
+        def positive_number(value, default)
+          number = Float(value)
+          number.positive? && number.finite? ? number : default
+        rescue ArgumentError, TypeError => e
+          warn("Legion::Logging::Rotation invalid numeric limit: #{e.class}: #{e.message}")
+          default
+        end
+      end
+    end
+  end
+end
+
+require_relative 'rotating_file'
+require_relative 'stdio_rotator'

data/lib/legion/logging/settings.rb

@@ -16,7 +16,13 @@ module Legion
           trace_size:         4,
           extended:           true,
           backtrace_limit:    nil,
-          forward_log_levels: DEFAULT_FORWARD_LOG_LEVELS
+          forward_log_levels: DEFAULT_FORWARD_LOG_LEVELS,
+          rotation:           {
+            enabled:     true,
+            max_size_mb: 100,
+            max_files:   5,
+            stdio:       true
+          }
         }
       end
 

data/lib/legion/logging/stdio_rotator.rb

@@ -0,0 +1,492 @@
+# frozen_string_literal: true
+
+module Legion
+  module Logging
+    # The descriptors themselves become pipe writers, including writes which do
+    # not pass through Ruby's Logger. Only the drain thread owns the file sink.
+    class StdioRotator
+      class << self
+        attr_reader :current
+
+        def shared(max_bytes:, max_files:)
+          inherited = @current
+          if inherited && !inherited.owned?
+            raise IOError, 'cannot change the policy of an inherited stdio capture' unless inherited.max_bytes == max_bytes && inherited.max_files == max_files
+
+            return inherited
+          end
+
+          @shared_mutex.synchronize do
+            return @current.configure(max_bytes: max_bytes, max_files: max_files) if @current
+
+            capture = new(max_bytes: max_bytes, max_files: max_files)
+            @current = capture if capture.capturing?
+          end
+        end
+
+        def reset!(timeout: 2)
+          return false unless timeout.nil? ? @shared_mutex.lock : @shared_mutex.try_lock
+
+          begin
+            return true unless @current
+            return false unless @current.shutdown(timeout: timeout)
+
+            @current = nil
+            true
+          ensure
+            @shared_mutex.unlock
+          end
+        end
+      end
+      @shared_mutex = Mutex.new
+
+      attr_reader :max_bytes, :max_files
+
+      def initialize(max_bytes:, max_files:, stdout: $stdout, stderr: $stderr)
+        @stdout = stdout
+        @streams = [stdout, stderr].uniq(&:object_id)
+        @lifecycle = Mutex.new
+        @captures = []
+        @closed = false
+        @owner_pid = ::Process.pid
+        @max_bytes = max_bytes
+        @max_files = max_files
+        eligible = @streams.filter_map do |stream|
+          path = Rotation.regular_file_path(io: stream)
+          stream.flush if path
+          [stream, path, stream.stat] if path
+        end
+        eligible.group_by { |_, _, stat| [stat.dev, stat.ino] }.each_value do |group|
+          @captures << StdioCapture.new(path: group.first[1], streams: group.map(&:first), max_bytes: max_bytes, max_files: max_files)
+        end
+        @captures.each(&:attach)
+        @captures.each(&:release_backups)
+      rescue StandardError
+        @captures.reverse_each(&:rollback)
+        raise
+      end
+
+      def capturing? = !@captures.empty? && !@closed
+
+      def owned? = @owner_pid == ::Process.pid
+
+      def configure(max_bytes:, max_files:)
+        raise IOError, 'cannot configure an inherited stdio capture' unless owned?
+
+        @lifecycle.synchronize do
+          raise IOError, 'closed stdio capture' if @closed
+
+          @captures.each { |capture| capture.command(type: :configure, arguments: { max_bytes: max_bytes, max_files: max_files }) }
+          @max_bytes = max_bytes
+          @max_files = max_files
+        end
+        self
+      end
+
+      def write(*messages)
+        if @closed
+          current = self.class.current
+          return current.write(*messages) if current && !current.equal?(self) && current.stdout.equal?(@stdout)
+
+          return @stdout.write(*messages)
+        end
+
+        @captures.each(&:check_failure!) if owned?
+        @stdout.write(*messages)
+      rescue IOError, SystemCallError
+        @captures.each(&:check_failure!) if owned? && !@closed
+        raise
+      end
+
+      def flush(timeout: 2)
+        return false unless owned?
+
+        if @closed
+          current = self.class.current
+          return current.flush(timeout: timeout) if current && !current.equal?(self) && current.stdout.equal?(@stdout)
+
+          @stdout.flush
+          return self
+        end
+
+        deadline = monotonic_time + timeout if timeout
+        @captures.each { |capture| return false unless capture.flush(deadline: deadline) }
+        @stdout.flush unless @captures.any? { |capture| capture.includes?(stream: @stdout) }
+        self
+      end
+
+      # Logger borrows process stdio. Only explicit shutdown/reset! detaches it.
+      def close; end
+
+      def closed? = @closed
+
+      def sync = true # rubocop:disable Naming/PredicateMethod -- IO#sync interface
+
+      def sync=(_value); end
+
+      def rotate!
+        raise IOError, 'cannot rotate an inherited stdio capture' unless owned?
+
+        @lifecycle.synchronize do
+          raise IOError, 'closed stdio capture' if @closed
+
+          @captures.each { |capture| capture.command(type: :rotate!, arguments: {}) }
+          !@captures.empty?
+        end
+      end
+
+      def shutdown(timeout: 2)
+        return false unless owned?
+        return false unless timeout.nil? ? @lifecycle.lock : @lifecycle.try_lock
+
+        deadline = monotonic_time + timeout if timeout
+        detached = false
+        begin
+          return true if @closed
+          return false unless @captures.all? { |capture| capture.pause(deadline: deadline) }
+
+          detached = true
+          @closed = drain_and_detach!(deadline: deadline)
+        ensure
+          begin
+            unless @closed
+              @captures.each(&:attach) if detached
+              @captures.each(&:resume)
+            end
+          ensure
+            @lifecycle.unlock
+          end
+        end
+      end
+
+      protected
+
+      attr_reader :stdout
+
+      private
+
+      def drain_and_detach!(deadline:)
+        @captures.each(&:restore)
+        @captures.each(&:resume)
+        # Include bytes written to the old descriptors during restoration.
+        return false unless @captures.all? { |capture| capture.pause(deadline: deadline) }
+
+        # A final drain may itself rotate: restore the current active inode.
+        @captures.each(&:restore)
+        @captures.all? { |capture| capture.finish!(deadline: deadline) }
+      end
+
+      def monotonic_time
+        ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
+      end
+    end
+
+    # One reader and one bounded control pipe per distinct inherited file.
+    # Commands occupy a single slot; bytes are never queued in Ruby.
+    class StdioCapture
+      READ_BYTES = 16 * 1024
+
+      def initialize(path:, streams:, max_bytes:, max_files:)
+        @path = path
+        @streams = streams
+        @state = Mutex.new
+        @changed = ConditionVariable.new
+        @requested_flush = 0
+        @completed_flush = 0
+        @backups = []
+        @properties = streams.map { |stream| [stream.sync, stream.close_on_exec?, stream.external_encoding, stream.internal_encoding] }
+        streams.each { |stream| @backups << stream.dup }
+        @sink = RotatingFile.new(path: path, max_bytes: max_bytes, max_files: max_files)
+        @reader, @writer = IO.pipe
+        @wake_reader, @wake_writer = IO.pipe
+        @writer.binmode
+        @writer.sync = true
+        @worker = Thread.new do
+          Thread.current.report_on_exception = false
+          drain
+        end
+      rescue StandardError
+        begin
+          close_handles
+        ensure
+          release_backups
+        end
+        raise
+      end
+
+      def includes?(stream:)
+        @streams.any? { |candidate| candidate.equal?(stream) }
+      end
+
+      def attach
+        writer = @state.synchronize { @writer.dup unless @writer.closed? }
+        unless writer
+          # A failure during shutdown must not leave restored regular-file
+          # descriptors as an uncapped fallback. A readerless pipe fails closed.
+          reader, writer = IO.pipe
+          reader.close
+        end
+        @streams.each_with_index do |stream, index|
+          next if stream.closed?
+
+          stream.reopen(writer)
+          apply_properties(stream: stream, index: index, captured: true)
+        end
+      rescue StandardError
+        # Construction still has original descriptors available for rollback.
+        raise unless @backups.empty?
+
+        # If even dup/reopen fails, close the destinations rather than leave a
+        # restored regular-file descriptor able to bypass the retention cap.
+        failure = nil
+        @streams.each do |stream|
+          stream.close unless stream.closed?
+        rescue StandardError => e
+          failure ||= e
+        end
+        raise failure if failure
+
+        raise
+      ensure
+        writer.close if writer && !writer.closed?
+      end
+
+      def restore
+        file = @state.synchronize do
+          prepared = @restore_file
+          @restore_file = nil
+          prepared
+        end
+        raise IOError, 'stdio restoration was not prepared' unless file
+
+        @streams.each_with_index do |stream, index|
+          next if stream.closed?
+
+          stream.reopen(file)
+          apply_properties(stream: stream, index: index, captured: false)
+        end
+      ensure
+        file&.close
+      end
+
+      def release_backups
+        failure = nil
+        @backups.each do |backup|
+          backup.close unless backup.closed?
+        rescue StandardError => e
+          failure ||= e
+        end
+        @backups.clear
+        raise failure if failure
+      end
+
+      def rollback
+        @streams.each_with_index do |stream, index|
+          stream.reopen(@backups[index])
+          apply_properties(stream: stream, index: index, captured: false)
+        end
+      ensure
+        begin
+          finish!
+        ensure
+          release_backups
+        end
+      end
+
+      def check_failure!
+        @state.synchronize do
+          raise @failure if @failure
+          raise IOError, 'stdio capture is stopping' if @stopping
+        end
+      end
+
+      def flush(deadline:)
+        wait_for_flush(deadline: deadline, pause: false)
+      end
+
+      def pause(deadline:)
+        wait_for_flush(deadline: deadline, pause: true)
+      end
+
+      def resume
+        file = @state.synchronize do
+          @pause_target = nil
+          prepared = @restore_file
+          @restore_file = nil
+          prepared
+        end
+        file&.close
+        @state.synchronize do
+          @paused = false
+          wake unless @failure || @stopping
+        end
+      end
+
+      def finish!(deadline: nil) # rubocop:disable Naming/PredicateMethod -- Stops and joins the worker; false signals its deadline.
+        @state.synchronize do
+          unless @stopping
+            @stopping = true
+            wake unless @failure
+          end
+        end
+        remaining = [deadline - ::Process.clock_gettime(::Process::CLOCK_MONOTONIC), 0].max if deadline
+        !@worker.join(remaining).nil?
+      end
+
+      def command(type:, arguments:)
+        @state.synchronize do
+          raise @failure if @failure
+          raise IOError, 'stdio capture is stopping' if @stopping
+
+          wait_until { !@command }
+
+          command = { type: type, arguments: arguments, complete: false }
+          @command = command
+          wake
+          wait_until { command[:complete] }
+          command[:result]
+        end
+      end
+
+      private
+
+      def apply_properties(stream:, index:, captured:)
+        sync, close_on_exec, external, internal = @properties[index]
+        stream.sync = captured || sync
+        stream.close_on_exec = close_on_exec
+        stream.set_encoding(external, internal) if external
+      end
+
+      def wait_for_flush(deadline:, pause:)
+        @state.synchronize do
+          raise @failure if @failure
+          raise IOError, 'stdio capture is stopping' if @stopping
+
+          target = @requested_flush += 1
+          @pause_target = target if pause
+          wake
+          wait_until(deadline: deadline) { @completed_flush >= target && (!pause || @paused) }
+        end
+      end
+
+      def wait_until(deadline: nil)
+        loop do
+          raise @failure if @failure
+          return true if yield
+
+          if deadline
+            remaining = deadline - ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
+            return false unless remaining.positive?
+          end
+
+          @changed.wait(@state, remaining)
+        end
+      end
+
+      def wake
+        return if @wake_pending
+
+        @wake_writer.write_nonblock('.')
+        @wake_pending = true
+      end
+
+      def next_action
+        @state.synchronize do
+          return [:stop] if @stopping
+          return [:wait] if @paused
+          return [:command, @command] if @command
+
+          # Only this thread completes flushes, after both the read and its
+          # corresponding sink write. A consumed chunk cannot hide from flush.
+          bytes = @reader.read_nonblock(READ_BYTES, exception: false)
+          return [:write, bytes] if bytes.is_a?(String)
+          return [:flush, @requested_flush] if @requested_flush > @completed_flush
+
+          [:wait]
+        end
+      end
+
+      def drain
+        loop do
+          action, payload = next_action
+          case action
+          when :stop then break
+          when :wait then wait_for_input
+          when :write then @sink.write(payload)
+          when :command then execute_command(command: payload)
+          when :flush then complete_flush(target: payload)
+          end
+        end
+      rescue StandardError => e
+        # Closing the read end wakes blocked producers with EPIPE. Never log a
+        # drain failure to stderr: stderr may be the pipe which just failed.
+        begin
+          @reader.close unless @reader.closed?
+        ensure
+          @state.synchronize do
+            @failure = e
+            @changed.broadcast
+          end
+        end
+        raise
+      ensure
+        close_handles
+      end
+
+      def wait_for_input
+        IO.select(@paused ? [@wake_reader] : [@reader, @wake_reader])
+        @state.synchronize do
+          @wake_reader.read_nonblock(READ_BYTES, exception: false)
+          @wake_pending = false
+        end
+      end
+
+      def execute_command(command:)
+        result = @sink.public_send(command[:type], **command[:arguments])
+        @state.synchronize do
+          command[:result] = result
+          command[:complete] = true
+          @command = nil
+          @changed.broadcast
+        end
+      end
+
+      def complete_flush(target:)
+        @sink.flush
+        prepare = @state.synchronize { @pause_target && target >= @pause_target }
+        file = File.new(@path, 'ab') if prepare
+        retained = false
+        @state.synchronize do
+          @completed_flush = target
+          if file && @pause_target && target >= @pause_target
+            @restore_file = file
+            @paused = true
+            retained = true
+          end
+          @changed.broadcast
+        end
+      ensure
+        file.close if file && !retained
+      end
+
+      def close_handles
+        failure = nil
+        [@reader, @writer, @wake_reader, @wake_writer, @restore_file, @sink].compact.each do |handle|
+          if handle.equal?(@writer)
+            @state.synchronize { handle.close unless handle.closed? }
+          else
+            handle.close unless handle.closed?
+          end
+        rescue StandardError => e
+          failure ||= e
+          @state.synchronize do
+            @failure ||= e
+            @changed.broadcast
+          end
+        end
+        raise failure if failure
+      end
+    end
+    private_constant :StdioCapture
+  end
+end

data/lib/legion/logging/version.rb

@@ -2,6 +2,6 @@
 
 module Legion
   module Logging
-    VERSION = '1.5.19'
+    VERSION = '1.5.21'
   end
 end

data/lib/legion/logging.rb

@@ -78,8 +78,11 @@ module Legion
 
       def setup(level: 'debug', format: :text, async: true, shutdown_timeout: 2, **options)
         with_lifecycle_lock do
+          deadline = ::Process.clock_gettime(::Process::CLOCK_MONOTONIC) + shutdown_timeout if shutdown_timeout
           return false if @async_writer && stop_async_writer(timeout: shutdown_timeout) == false
-          return false if output(**options) == false
+
+          remaining = [deadline - ::Process.clock_gettime(::Process::CLOCK_MONOTONIC), 0].max if deadline
+          return false if output(shutdown_timeout: remaining, **options) == false
 
           log_level(level)
           log_format(format: format, **options)
@@ -94,6 +97,7 @@ module Legion
             extended:    options.fetch(:extended, true),
             log_file:    options[:log_file],
             log_stdout:  options[:log_stdout],
+            rotation:    options[:rotation],
             include_pid: options.fetch(:include_pid, false),
             color:       @color
           }.freeze

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: legion-logging
 version: !ruby/object:Gem::Version
-  version: 1.5.19
+  version: 1.5.21
 platform: ruby
 authors:
 - Esity
@@ -72,11 +72,14 @@ files:
 - lib/legion/logging/multi_io.rb
 - lib/legion/logging/output_logger.rb
 - lib/legion/logging/redactor.rb
+- lib/legion/logging/rotating_file.rb
+- lib/legion/logging/rotation.rb
 - lib/legion/logging/settings.rb
 - lib/legion/logging/shipper.rb
 - lib/legion/logging/shipper/file_transport.rb
 - lib/legion/logging/shipper/http_transport.rb
 - lib/legion/logging/siem_exporter.rb
+- lib/legion/logging/stdio_rotator.rb
 - lib/legion/logging/tagged_logger.rb
 - lib/legion/logging/version.rb
 - lib/legion/service.rb