log_shout 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: cc4cc267c8eeb16ef1f1615f57a50189549a896c2d583eb74ab0540857812146
+  data.tar.gz: 487bb3371dbf862cb701e1e5278959d722765f424c3f70832cffdef30eb577dc
+SHA512:
+  metadata.gz: e85575c4a8cb47cabd352d1104326f07fb3c15f7ec486ae64de5b61cb75182235a3889a671b598a510aa5ed9f4c7a44df5cd062a743e86c0b5cefdbc46b71ae8
+  data.tar.gz: b45d29c88b91d0bacae4f55ce5864dd630847a544e680b6319bbf6b37c4a5c71c06a3ab412f3c4baefe61cf80c4e60486baad3455fd72319769158accb64abca

data/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## 0.1.0 (unreleased)
+
+Initial release candidate:
+
+- Fan out Ruby Logger messages to stdout, stderr, files, and memory through Ractors.
+- Configure named loggers and shared destinations with YAML.
+- Provide class and instance logger helpers and background job logging.
+- Require Ruby 4.0 or newer for Ractor::Port and Ractor#value.
+- Drain and close destinations during reconfiguration, reset, and shutdown.
+- Surface destination failures to callers of flush, read, and close.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matthew Christen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,285 @@
+# LogShout
+
+Fan-out logging for Ruby using Ractors. LogShout wraps Ruby's `::Logger` to write each log message to multiple destinations (stdout, stderr, files, in-memory) concurrently and safely.
+
+## WARNING
+
+Ractor support in Ruby is EXPERIMENTAL use at your own risk.
+
+## Installation
+
+Requires CRuby 4.0 or newer (`Ractor::Port` and `Ractor#value`).
+
+Add to your Gemfile and bundle:
+
+```ruby
+gem "log_shout", "~> 0.1"
+```
+
+```bash
+bundle install
+```
+
+## Quick start
+
+1. Optionally create a `log_shout.yml` alongside your app (or set `LOG_SHOUT_CONFIG_PATH`). If you skip this, LogShout will run with sane defaults (documented below). If you specify `LOG_SHOUT_CONFIG_PATH` and the file does not exist you will get a runtime error.
+
+```yaml
+---
+defaultLevel: info
+defaultHandlers: [stdout]
+extraHandlers:
+  app_file_log:
+    type: file
+    path: ./app.log
+loggers:
+  app:
+    level: debug
+    handlers: [stdout, app_file_log]
+```
+
+2. Use LogShout in your code:
+
+```ruby
+require "log_shout"
+
+logger = LogShout.get_logger(:app)
+logger.info("Hello from LogShout")
+# in your console
+# [2025-10-04 10:50:55.514722 #583620/583642] I -- app: Hello from LogShout
+```
+
+Tip: include the helper to get class/instance-level loggers.
+This will provide access to a logger named after the class via both a class and instance method named logger.
+
+```ruby
+module MyModule
+  class MyClass
+    include LogShout::Helper
+
+    def self.class_method
+      logger.debug("my message")
+    # [2025-10-04 10:50:55.514722 #583620/583642] D -- MyModule::MyClass: my message
+    end
+
+    def method
+      logger.debug("my message")
+    # [2025-10-04 10:50:55.514722 #583620/583642] D -- MyModule::MyClass: my message
+    end
+  end
+end
+
+```
+
+Tip: Run a job in its own Ractor with a Ractor safe logger
+This behavior is similar to the class based helpers but the API is different.
+
+If you have the following class
+
+```ruby
+class MyJob
+  def self.run(logger, p1, p2)
+    logger.debug("some background task #{p1} #{p2}")
+    p1+p2
+  end
+end
+```
+
+Then you can run the job as follows.
+
+```ruby
+r = LogShout::LoggingRactor.start(target: MyJob, name: :app, args: [1, 4])
+# [2025-10-04 10:50:55.514722 #583620/583642] D -- MyJob: some background task 1 4
+r.value # 5
+```
+
+## Configuration
+
+### Schema
+
+- defaultLevel: info|debug|warn|fatal
+- defaultHandlers: [stdout] # array of handler names that every logger inherits by default.
+- extraHandlers: map of name -> `{ type: stdout|stderr|file|memory, path?: string }` (file requires path).
+- loggers: map of logger name -> `{ level: string, handlers: [names...] }`.
+
+Notes:
+
+- Built-in handlers `stdout` and `stderr` cannot be overridden. eg. you cannot create a **new** handler named `:stdout`
+
+## Using without a config file (defaults)
+
+The configuration file is optional. These are the defaults.
+
+```yaml
+---
+defaultLevel: INFO
+defaultHandlers: [stdout]
+extraHandlers: {}
+loggers: {}
+```
+
+Runtime behavior of default config:
+
+- If you set `LOG_SHOUT_CONFIG_PATH` and that file doesn’t exist, `configure` will raise.
+- Any logger name you request (e.g., `get_logger(:anything)`) uses the default level and handlers when not explicitly configured.
+- By default only `stdout` is attached; to add `stderr`, `file`, or `memory`, define them in `extraHandlers` and reference by name in a logger’s `handlers`.
+
+Minimal example with defaults (no file present):
+
+```ruby
+require "log_shout"
+LogShout.get_logger(:any).info("goes to STDOUT at INFO level")
+```
+
+## Delivery, failure, and lifecycle
+
+`logger.info` and the other severity methods enqueue messages asynchronously.
+Returning from a log call does not mean a destination has written the message.
+Each destination processes its queue in order. Ordering across independent
+producers or different destinations is not guaranteed.
+
+```ruby
+LogShout.flush          # wait for earlier queued writes at every destination
+LogShout.close_handlers # drain queues, close destinations, wait for workers
+```
+
+`flush` flushes Ruby IO buffers; it does not call `fsync` or guarantee survival
+of a crash or power failure. Queues and memory destinations are unbounded:
+slow destinations or large volumes can consume significant memory. There is
+currently no backpressure, rotation, retry, or delivery guarantee after failure.
+
+Destinations are opened during configuration. If opening or writing fails,
+`Ractor::RemoteError` is raised by initialization or the next synchronous
+`flush`, `read`, or `close`; its `cause` contains the underlying IO exception.
+A failed worker wakes waiting callers. A live worker blocked in operating-system
+IO can still block a flush or shutdown; no IO timeout is imposed. Ruby Logger
+may report immediate write errors to stderr instead of propagating them, so use
+an explicit `LogShout.flush` where delivery needs to be checked.
+
+Calling `logger.close` flushes its shared destinations. Only
+`LogShout.close_handlers` closes them, and repeated shutdown is safe. An `at_exit`
+hook attempts shutdown and reports failures to stderr without masking an earlier
+application exception. For reliable delivery, explicitly stop producers and call
+`close_handlers` before exiting.
+
+`LogShout.configure(path: ...)` validates and opens the replacement destinations,
+drains and closes the previous handlers, and clears the logger cache. Invalid
+configuration or an opening failure preserves the current configuration.
+`LogShout.reset!` closes handlers and clears configuration; the next `get_logger`
+loads configuration again. Stop and join background jobs before reconfiguring,
+resetting, or closing. Discard old logger references and fetch fresh ones after
+reconfiguration. Configuration changes are intended for the main Ractor while
+producers are stopped; concurrent reconfiguration is unsupported.
+
+String and symbol logger names are equivalent. Use `LoggingRactor.start` to
+create loggers inside background Ractors rather than calling the module's global
+configuration methods from another Ractor. Join the returned job with `r.value`
+before flushing or closing destinations in the main Ractor.
+
+## Architecture: Logger I/O
+
+This shows how log messages flow from your code through Ruby’s `::Logger`, across `MultiIO`, into per-destination Ractors, and finally to underlying IOs.
+
+Key parts:
+
+- `LogShout.get_logger` in [lib/log_shout.rb](lib/log_shout.rb): builds `::Logger` with a custom logdev and default formatter.
+- `LogShout::MultiIO` in [lib/log_shout/multi_io.rb](lib/log_shout/multi_io.rb): fan-out logdev that forwards `write/flush/close` to all handlers.
+- `LogShout::IORactor` in [lib/log_shout/io_ractor.rb](lib/log_shout/io_ractor.rb): one ractor per handler; owns the actual IO (STDOUT/ERR/File/StringIO).
+- `LogShout::LoggingRactor` in [lib/log_shout/logging_ractor.rb](lib/log_shout/logging_ractor.rb): helper to run a job in its own ractor with a ready-to-use logger.
+- Default formatter in [lib/log_shout/formatters/default.rb](lib/log_shout/formatters/default.rb).
+
+`LogShout::IORactor` objects are pre-created for all handlers defined. These objects are shared between all loggers that are created. So if you create 20 loggers with the same handler, only one `LogShout::IORactor` will exist, and thus only one Ractor will be created.
+
+### Component view
+
+```mermaid
+flowchart LR
+  subgraph App
+    A["Your code"]
+  end
+
+  subgraph LogShout core
+    LS["get_logger(name)<br/>/log_shout.rb"]
+    L["Logger<br/> stdlib"]
+    M["LogShout::MultiIO<br/>/log_shout/multi_io.rb"]
+  end
+
+  subgraph "Handlers (per destination)"
+    direction TB
+    H1["LogShout::IORactor<br/>(stdout)<br/>/log_shout/io_ractor.rb"]
+    H2["LogShout::IORactor<br/>(stderr)<br/>/log_shout/io_ractor.rb"]
+    H3["LogShout::IORactor<br/>(file)<br/>/log_shout/io_ractor.rb"]
+    H4["LogShout::IORactor<br/>(memory)<br/>/log_shout/io_ractor.rb"]
+  end
+
+  subgraph "Ractor workers (one per handler)"
+    direction TB
+    R1["Ractor loop<br/>.for_fd(1)"]
+    R2["Ractor loop<br/>.for_fd(2)"]
+    R3["Ractor loop<br/>.open(path,'a')"]
+    R4["Ractor loop"]
+  end
+
+  A -->|"logger = LogShout.get_logger(:name)"| LS
+  LS -->|builds| L
+  L -->|logdev| M
+
+  M -->|write/flush/close| H1
+  M -->|write/flush/close| H2
+  M -->|write/flush/close| H3
+  M -->|write/flush/close| H4
+
+  H1 -->|"send [:op, ...]"| R1
+  H2 -->|"send [:op, ...]"| R2
+  H3 -->|"send [:op, ...]"| R3
+  H4 -->|"send [:op, ...]"| R4
+
+  R1 --> IO1[(STDOUT)]
+  R2 --> IO2[(STDERR)]
+  R3 --> IO3[(File)]
+  R4 --> IO4[(StringIO)]
+```
+
+### Sequence view (write/flush/close)
+
+```mermaid
+sequenceDiagram
+  participant App
+  participant Logger as ::Logger
+  participant MultiIO as LogShout::MultiIO
+  participant IO as LogShout::IORactor
+
+  App->>Logger: info("msg")
+  Logger->>Logger: format -> "s"
+  Logger->>MultiIO: write("s")
+  loop for each handler
+    MultiIO->>IO: write("s")
+  end
+```
+
+## Dev setup(with nix+direnv)
+
+The flake uses Ruby 4.0 from `nixos-unstable`, including the `Ractor::Port` API
+previously used from Ruby nightly. No local Ruby fork is needed. Bundix uses
+[the fork required by ruby-nix](https://github.com/inscapist/ruby-nix#global-bundix-installation-optional)
+for platform-dependent gems, built with the same Ruby as the project.
+
+```bash
+direnv allow
+bundix
+```
+
+Without Nix, install dependencies with a released Bundler:
+
+```bash
+gem install bundler -v 2.7.2
+bundle _2.7.2_ install
+```
+
+Run the tests and style checks with `bundle exec rake`; build with
+`bundle exec rake build`. Run `ruby script/check_package.rb` to install the
+built gem into a temporary gem home and check it through Bundler without the
+development dependencies. That check downloads runtime dependencies.
+
+See [CHANGELOG.md](CHANGELOG.md) and [RELEASING.md](RELEASING.md) for release status
+and publishing instructions. Licensed under the [MIT License](LICENSE).

data/RELEASING.md

@@ -0,0 +1,42 @@
+# Releasing LogShout
+
+## One-time account setup
+
+1. Confirm the gem name `log_shout` is available or owned by your RubyGems account.
+2. Enable MFA on that account. The gem declares `rubygems_mfa_required`.
+3. On RubyGems, create a pending trusted publisher for a first release (or a
+   trusted publisher on the existing gem):
+   - Gem: `log_shout`
+   - Repository owner: `mchristen`
+   - Repository: `log_shout`
+   - Workflow filename: `release.yml`
+   - Environment: `release`
+4. In the GitHub repository, create a `release` environment with required reviewer
+   approval if available for the repository, and protect your release branches.
+
+See the official [Trusted Publishing guide](https://guides.rubygems.org/trusted-publishing/).
+No long-lived RubyGems API token is needed by the workflow.
+
+## Each release
+
+1. Set `LogShout::VERSION` in `lib/log_shout/version.rb`. Update the matching
+   changelog entry with the release date and user-visible changes. Verify the
+   maintainer email and public metadata before the first release.
+2. If dependencies change, run `bundle _2.7.2_ lock`, regenerate `gemset.nix`
+   with `bundix`, and commit both lock representations.
+3. Run `bundle exec rake`, `bundle exec rake build`, and
+   `ruby script/check_package.rb`. Inspect the packaged file list. The package
+   check installs runtime dependencies from RubyGems into a temporary directory.
+4. Commit all release changes and ensure CI passes on Ruby 4.0.0 and the latest
+   4.0 patch release. Review the exact commit to publish.
+5. Create and push the matching version tag, for example `v0.1.0`, pointing at
+   that tested commit.
+6. In GitHub Actions, manually run **Release** from the default branch, entering
+   that existing tag. It verifies the tag matches the gemspec, reruns checks,
+   and publishes through RubyGems Trusted Publishing. Approve the `release`
+   environment deployment when configured.
+7. Verify the published version and its metadata on RubyGems, then create release
+   notes from the changelog. Published version numbers cannot be reused.
+
+The repository includes preparation and verification code only; account setup,
+pushing release tags, and publishing are deliberate maintainer actions.

data/lib/log_shout/formatters/default.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module LogShout
+  module Formatters
+    class Default < ::Logger::Formatter
+      FORMAT = "[%s #%d/%6s] %.1s -- %s: %s\n"
+      DATETIME_FORMAT = "%Y-%m-%d %H:%M:%S.%6N"
+
+      def call(severity, time, progname, msg)
+        thread_id = Thread.current.name || Thread.current.native_thread_id
+        sprintf(FORMAT, time.strftime(DATETIME_FORMAT), Process.pid, thread_id, severity, progname, msg2str(msg))
+      end
+    end
+  end
+end

data/lib/log_shout/helper.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module LogShout
+  module Helper
+    module ClassMethods
+      def logger(extra_name: nil)
+        logger_name = "#{name}::#{extra_name}" if extra_name
+        logger_name ||= name
+        LogShout.get_logger(logger_name.to_sym)
+      end
+    end
+
+    def logger(extra_name: nil)
+      self.class.logger(extra_name: extra_name)
+    end
+
+    def self.included(other)
+      other.extend(ClassMethods)
+    end
+  end
+end

data/lib/log_shout/io_ractor.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+module LogShout
+  class IORactor
+    def initialize(handler: {})
+      @handler = handler
+      @closed = false
+      @r = Ractor.new(handler) do |definition|
+        IORactor.execute_ractor(definition)
+      end
+      request(:ready)
+    end
+
+    def self.execute_ractor(handler)
+      io = case handler[:type]
+      when nil, :stdout
+        IO.for_fd(1, autoclose: false)
+      when :stderr
+        IO.for_fd(2, autoclose: false)
+      when :file
+        File.open(handler.fetch(:destination), "a")
+      when :memory
+        StringIO.new
+      else
+        raise ArgumentError, "Invalid handler definition: #{handler.inspect}"
+      end
+      io.sync = true if io.respond_to?(:sync=)
+
+      begin
+        loop do
+          op, arg, reply = Ractor.receive
+          result = case op
+          when :ready
+            nil
+          when :write
+            io.write(arg)
+          when :flush
+            io.flush
+            nil
+          when :read
+            io.is_a?(StringIO) ? io.string : nil
+          when :close
+            break
+          end
+          reply&.send([:ok, result])
+        end
+      ensure
+        io.close unless io.closed?
+      end
+      :closed
+    end
+
+    def name
+      @handler[:name]
+    end
+
+    def type
+      @handler[:type]
+    end
+
+    def destination
+      @handler[:destination]
+    end
+
+    def closed?
+      @closed || @r.default_port.closed?
+    end
+
+    def write(str)
+      raise IOError, "closed log handler" if closed?
+      s = String(str)
+      @r.send([:write, s])
+      s.bytesize
+    end
+
+    def flush(wait_for_flush = true)
+      if wait_for_flush
+        request(:flush)
+      else
+        @r.send([:flush])
+      end
+      nil
+    end
+
+    def read
+      request(:read)
+    end
+
+    def close
+      return if @closed
+      begin
+        begin
+          @r.send([:close])
+        rescue Ractor::ClosedError
+          # Join below still reports the worker's original failure.
+        end
+        @r.join
+      ensure
+        @closed = true
+      end
+      nil
+    end
+
+    private
+
+    # A fresh reply port belongs to the calling Ractor. Monitoring that same
+    # port also wakes the caller if the worker dies before replying.
+    def request(op)
+      raise IOError, "closed log handler" if @closed
+      reply = Ractor::Port.new
+      @r.monitor(reply)
+      begin
+        @r.send([op, nil, reply])
+      rescue Ractor::ClosedError
+        @r.join
+        raise IOError, "closed log handler"
+      end
+      response = reply.receive
+      unless response.is_a?(Array)
+        @r.join
+        raise IOError, "log handler terminated before replying"
+      end
+      response[1]
+    ensure
+      if reply
+        @r.unmonitor(reply)
+        reply.close
+      end
+    end
+  end
+end

data/lib/log_shout/logging_ractor.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module LogShout
+  class LoggingRactor
+    # caller passes a shareable target (Module/Class) and a method Symbol
+    def self.start(target:, method: :run, name: nil, args: [])
+      name ||= target.name
+      handlers = LogShout.get_handlers_for(name).freeze
+      level = ::Logger.const_get(LogShout.get_level_for_name(name).upcase)
+      logdev = LogShout::MultiIO.new(handlers)
+      r = Ractor.new(level, logdev, args, name: name) do |level, logdev, a|
+        logger = ::Logger.new(logdev,
+          level: level,
+          progname: Ractor.current.name,
+          formatter: LogShout::Formatters::Default.new)
+        # Call a shareable entrypoint; e.g., MyJob.run(logger, *a)
+        job = Ractor.receive     # receive [ModuleOrClass, :method]
+        receiver = Ractor.receive
+        job.public_send(receiver, logger, *a)
+      ensure
+        logdev.flush(false)
+      end
+
+      # Send the callable in a ractor-safe way (two shareable messages)
+      r.send(target)
+      r.send(method)
+      r
+    end
+  end
+end

data/lib/log_shout/multi_io.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module LogShout
+  class MultiIO
+    def initialize(targets)
+      @targets = targets
+    end
+
+    def write(message)
+      @targets.each { |t| t.write(message) }
+      nil
+    end
+
+    def close
+      # Destinations belong to LogShout and may be used by other loggers.
+      flush
+      nil
+    end
+
+    def flush(wait_for_flush = true)
+      @targets.each do |t|
+        t.flush(wait_for_flush)
+      end
+      nil
+    end
+
+    # only useful for debugging memory handler
+    def read(handler)
+      @targets.each do |t|
+        next unless t.name == handler
+        return t.read
+      end
+      nil
+    end
+  end
+end

data/lib/log_shout/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module LogShout
+  VERSION = "0.1.0"
+end

data/lib/log_shout.rb

@@ -0,0 +1,331 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "yaml"
+require "logger"
+require "stringio"
+
+require "log_shout/helper"
+require "log_shout/multi_io"
+require "log_shout/io_ractor"
+require "log_shout/logging_ractor"
+require "log_shout/version"
+require "log_shout/formatters/default"
+
+module LogShout
+  class LogShoutError < StandardError; end
+
+  # Replace the Sorbet enum with a plain Ruby value-object enum
+  class LogDestination
+    attr_reader :name
+    private_class_method :new
+
+    def initialize(name)
+      @name = name
+    end
+
+    def to_sym
+      @name
+    end
+
+    def to_s
+      @name.to_s
+    end
+
+    # Keep the same API used elsewhere
+    def serialize
+      @name
+    end
+
+    def ==(other)
+      other.is_a?(LogDestination) && other.name == name
+    end
+
+    alias_method :eql?, :==
+
+    def hash
+      name.hash
+    end
+
+    STD_OUT = new(:stdout)
+    STD_ERR = new(:stderr)
+    FILE = new(:file)
+    MEMORY = new(:memory)
+
+    ALL = [STD_OUT, STD_ERR, FILE, MEMORY].freeze
+
+    def self.from(value)
+      return value if value.is_a?(LogDestination)
+      sym = value.to_s.downcase.to_sym
+      ALL.find { |v| v.name == sym } || (raise ArgumentError, "Unknown destination: #{value.inspect}")
+    end
+  end
+
+  # Keep keyword-only constructors for the public configuration structs.
+
+  LogHandler = Struct.new(:name, :type, :destination, keyword_init: true) do # standard:disable Style/RedundantStructKeywordInit
+    def ==(other)
+      other.is_a?(LogHandler) && name == other.name
+    end
+
+    def serialize
+      {
+        name: name,
+        type: type.respond_to?(:serialize) ? type.serialize : type.to_sym,
+        destination: destination
+      }
+    end
+  end
+
+  LogConfig = Struct.new(:level, :handlers, keyword_init: true) do # standard:disable Style/RedundantStructKeywordInit
+    def ==(other)
+      other.is_a?(LogConfig) &&
+        level == other.level &&
+        handlers == other.handlers
+    end
+
+    def serialize
+      {
+        level: level,
+        handlers: handlers.map(&:serialize)
+      }
+    end
+  end
+
+  LogConfigFile = Struct.new(:loggers, :extraHandlers, :defaultLevel, :defaultHandlers, keyword_init: true) do # standard:disable Style/RedundantStructKeywordInit
+    def ==(other)
+      other.is_a?(LogConfigFile) &&
+        loggers == other.loggers &&
+        extraHandlers == other.extraHandlers &&
+        defaultLevel == other.defaultLevel &&
+        defaultHandlers == other.defaultHandlers
+    end
+
+    def serialize
+      {
+        loggers: loggers.transform_values(&:serialize),
+        extraHandlers: extraHandlers.transform_values(&:serialize),
+        defaultLevel: defaultLevel,
+        defaultHandlers: defaultHandlers.map(&:serialize)
+      }
+    end
+  end
+
+  BUILTIN_HANDLERS = {
+    stdout: LogHandler.new(name: :stdout, type: LogDestination::STD_OUT),
+    stderr: LogHandler.new(name: :stderr, type: LogDestination::STD_ERR)
+  }
+
+  DEFAULT_CONFIG = LogConfigFile.new(
+    defaultLevel: "INFO",
+    defaultHandlers: [BUILTIN_HANDLERS[:stdout]],
+    loggers: {},
+    extraHandlers: {}
+  )
+
+  @loggers = {}
+
+  def self.configure(path: nil)
+    default_path = File.expand_path("log_shout.yml", FileUtils.pwd)
+    requested_path = ENV.fetch("LOG_SHOUT_CONFIG_PATH", path)
+    config_file_path = requested_path || default_path
+    config = if File.exist?(config_file_path)
+      begin
+        validate_config(YAML.load_file(config_file_path, symbolize_names: true))
+      rescue Psych::SyntaxError => e
+        raise LogShoutError, "Failed to parse YAML configuration file at #{config_file_path}: #{e.message}"
+      end
+    elsif requested_path
+      raise LogShoutError, "Configuration file not found at #{config_file_path}"
+    else
+      DEFAULT_CONFIG
+    end
+    validated_config = config.serialize.freeze
+    handlers = build_handlers(validated_config)
+    begin
+      close_handlers
+    rescue
+      handlers.each_value(&:close)
+      raise
+    end
+    @config_file_path = config_file_path
+    @validated_config = validated_config
+    @handlers = handlers.freeze
+    @loggers = {}
+    @config_file_path
+  end
+
+  def self.build_handlers(config)
+    handlers = {}
+    definitions = config[:defaultHandlers] + config[:extraHandlers].values +
+      config[:loggers].values.flat_map { |logger| logger[:handlers] }
+    definitions.uniq { |handler| handler[:name] }.each do |handler|
+      handlers[handler[:name]] = create_handler(handler)
+    end
+    handlers
+  rescue
+    handlers.each_value(&:close)
+    raise
+  end
+  private_class_method :build_handlers
+
+  def self.create_handler(handler)
+    LogShout::IORactor.new(handler: handler) # must respond_to?(:write)
+  end
+
+  def self.validate_config(config)
+    raise LogShoutError, "Configuration must be a mapping" unless config.is_a?(Hash)
+    [:extraHandlers, :loggers].each do |key|
+      raise LogShoutError, "#{key} must be a mapping" unless config.fetch(key, {}).is_a?(Hash)
+    end
+    default_level = config.fetch(:defaultLevel, "INFO")
+    validate_level(default_level)
+    default_handler_names = config.fetch(:defaultHandlers, ["stdout"])
+    raise LogShoutError, "defaultHandlers must be an array" unless default_handler_names.is_a?(Array)
+    extra_handlers = config.fetch(:extraHandlers, {}).each_with_object({}) do |(name, config), obj|
+      if name === :stdout || name === :stderr
+        raise LogShoutError, "Cannot override built-in handler: #{name}"
+      end
+      raise LogShoutError, "Handler #{name} must be a mapping" unless config.is_a?(Hash)
+      handler = case config[:type]
+      when "memory"
+        LogHandler.new(name: name.to_sym, type: LogDestination::MEMORY)
+      when "file"
+        if !config[:path]
+          raise LogShoutError, "File handler #{name} requires a path"
+        end
+        LogHandler.new(name: name.to_sym, type: LogDestination::FILE, destination: config[:path])
+      when "stdout"
+        LogHandler.new(name: name.to_sym, type: LogDestination::STD_OUT)
+      when "stderr"
+        LogHandler.new(name: name.to_sym, type: LogDestination::STD_ERR)
+      else
+        raise LogShoutError, "Unknown handler type: #{config[:type]}"
+      end
+      obj[name.to_sym] = handler
+    end
+    default_handlers = default_handler_names.map do |name|
+      BUILTIN_HANDLERS[name.to_sym] || extra_handlers[name.to_sym] || (raise LogShoutError, "Unknown handler: #{name}")
+    end
+
+    loggers = config.fetch(:loggers, {}).each_with_object({}) do |(name, config), obj|
+      raise LogShoutError, "Logger #{name} must be a mapping" unless config.is_a?(Hash)
+      level = config.fetch(:level, default_level)
+      validate_level(level)
+      handler_names = config.fetch(:handlers, default_handler_names)
+      raise LogShoutError, "Logger #{name} handlers must be an array" unless handler_names.is_a?(Array)
+      handlers = handler_names.map do |name|
+        BUILTIN_HANDLERS[name.to_sym] || extra_handlers[name.to_sym] || (raise LogShoutError, "Unknown handler: #{name}")
+      end
+      obj[name.to_sym] = LogConfig.new(level: level, handlers: handlers)
+    end
+
+    LogConfigFile.new(
+      defaultLevel: config.fetch(:defaultLevel, "INFO"),
+      defaultHandlers: default_handlers,
+      extraHandlers: extra_handlers,
+      loggers: loggers
+    )
+  end
+
+  def self.validate_level(level)
+    unless level.is_a?(String) && %w[DEBUG INFO WARN ERROR FATAL UNKNOWN].include?(level.upcase)
+      raise LogShoutError, "Invalid log level: #{level.inspect}"
+    end
+  end
+  private_class_method :validate_level
+
+  def self.get_handler(name)
+    @handlers[name]
+  end
+
+  def self.get_handlers_for(logger_name)
+    config = configuration[:loggers].fetch(
+      logger_name.to_sym,
+      {
+        level: configuration[:defaultLevel],
+        handlers: configuration[:defaultHandlers]
+      }
+    )
+    config[:handlers].map do |h|
+      get_handler(h[:name])
+    end
+  end
+
+  def self.flush
+    return unless @handlers
+    @handlers.each_value do |handler|
+      handler.flush
+    end
+  end
+
+  def self.close_handlers
+    error = nil
+    (@handlers || {}).each_value do |handler|
+      handler.close
+    rescue => e
+      error ||= e
+    end
+    raise error if error
+    nil
+  end
+
+  def self.get_level_for_name(name)
+    configuration[:loggers].fetch(
+      name.to_sym,
+      {
+        level: configuration[:defaultLevel],
+        handlers: configuration[:defaultHandlers]
+      }
+    )[:level]
+  end
+
+  def self.get_logger(name)
+    configure unless @handlers
+    name = name.to_sym
+    if (logger = @loggers[name])
+      return logger
+    end
+
+    config = configuration[:loggers].fetch(
+      name,
+      {
+        level: configuration[:defaultLevel],
+        handlers: configuration[:defaultHandlers]
+      }
+    )
+
+    handlers = config[:handlers].map do |h|
+      get_handler(h[:name])
+    end
+
+    @loggers[name] = ::Logger.new(LogShout::MultiIO.new(handlers),
+      level: ::Logger.const_get(config[:level].upcase),
+      progname: name.to_s,
+      formatter: LogShout::Formatters::Default.new)
+  end
+
+  def self.configuration
+    @validated_config || DEFAULT_CONFIG.serialize.freeze
+  end
+
+  def self.config_file_path
+    @config_file_path
+  end
+
+  def self.reset!
+    close_handlers
+    @handlers = nil
+    @config_file_path = nil
+    @validated_config = nil
+    @loggers = {}
+  end
+end
+
+LogShout.configure
+
+at_exit do
+  LogShout.close_handlers
+rescue => e
+  warn "LogShout shutdown failed: #{e.class}: #{e.message}"
+end

metadata

@@ -0,0 +1,174 @@
+--- !ruby/object:Gem::Specification
+name: log_shout
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Matt Christen
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: logger
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+- !ruby/object:Gem::Dependency
+  name: standard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.53'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.53'
+- !ruby/object:Gem::Dependency
+  name: standard-performance
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+- !ruby/object:Gem::Dependency
+  name: ruby-lsp
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.23'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.23'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.26'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 5.26.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.26'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 5.26.1
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.1'
+- !ruby/object:Gem::Dependency
+  name: bundler-audit
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+- !ruby/object:Gem::Dependency
+  name: debug
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.11'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.11'
+description: Easy to configure ruby loggers. Multi-destination and configuration levels.
+email:
+- oss@christen.tech
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- RELEASING.md
+- lib/log_shout.rb
+- lib/log_shout/formatters/default.rb
+- lib/log_shout/helper.rb
+- lib/log_shout/io_ractor.rb
+- lib/log_shout/logging_ractor.rb
+- lib/log_shout/multi_io.rb
+- lib/log_shout/version.rb
+homepage: https://github.com/mchristen/log_shout
+licenses:
+- MIT
+metadata:
+  changelog_uri: https://github.com/mchristen/log_shout/blob/main/CHANGELOG.md
+  documentation_uri: https://github.com/mchristen/log_shout#readme
+  source_code_uri: https://github.com/mchristen/log_shout
+  bug_tracker_uri: https://github.com/mchristen/log_shout/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 4.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: Ruby loggers with flexibility.
+test_files: []