rage-rb 1.18.0 → 1.19.0

data/lib/rage/logger/logger.rb

@@ -51,18 +51,30 @@ require "logger"
 # end
 # ```
 class Rage::Logger
+  # @private
   METHODS_MAP = {
-    "debug" => Logger::DEBUG,
-    "info" => Logger::INFO,
-    "warn" => Logger::WARN,
-    "error" => Logger::ERROR,
-    "fatal" => Logger::FATAL,
-    "unknown" => Logger::UNKNOWN
+    debug: Logger::DEBUG,
+    info: Logger::INFO,
+    warn: Logger::WARN,
+    error: Logger::ERROR,
+    fatal: Logger::FATAL,
+    unknown: Logger::UNKNOWN
   }
-  private_constant :METHODS_MAP
 
   attr_reader :level, :formatter
 
+  # @private
+  attr_reader :dynamic_tags, :dynamic_context
+
+  # @private
+  attr_reader :external_logger
+
+  # @private
+  module External
+    Static = Data.define(:wrapped)
+    Dynamic = Data.define(:wrapped)
+  end
+
   # Create a new logger.
   #
   # @param log [Object] a filename (`String`), IO object (typically `STDOUT`, `STDERR`, or an open file), `nil` (it writes nothing) or `File::NULL` (same as `nil`)
@@ -73,7 +85,10 @@ class Rage::Logger
   # @param shift_period_suffix [String] the log file suffix format for daily, weekly or monthly rotation
   # @param binmode sets whether the logger writes in binary mode
   def initialize(log, level: Logger::DEBUG, formatter: Rage::TextFormatter.new, shift_age: 0, shift_size: 104857600, shift_period_suffix: "%Y%m%d", binmode: false)
-    @logdev = if log && log != File::NULL
+    @logdev = if log.class.name.start_with?("Rage::Logger::External::")
+      @external_logger = log
+      Logger::LogDevice.new(STDERR)
+    elsif log && log != File::NULL
       Logger::LogDevice.new(log, shift_age:, shift_size:, shift_period_suffix:, binmode:)
     end
 
@@ -83,17 +98,38 @@ class Rage::Logger
 
     @formatter = formatter
     @level = @logdev ? level : Logger::UNKNOWN
-    define_log_methods
+    rebuild!
   end
 
+  # Set the logging severity threshold.
+  # @param level [Integer] logging severity threshold
   def level=(level)
     @level = level
-    define_log_methods
+    rebuild!
   end
 
+  # Set the logging formatter.
+  # @param formatter [#call] logging formatter
   def formatter=(formatter)
     @formatter = formatter
-    define_log_methods
+    rebuild!
+  end
+
+  # Write the given `msg` to the log with no formatting.
+  def <<(msg)
+    @logdev&.write(msg)
+  end
+
+  # @private
+  def dynamic_tags=(dynamic_tags)
+    @dynamic_tags = dynamic_tags
+    rebuild!
+  end
+
+  # @private
+  def dynamic_context=(dynamic_context)
+    @dynamic_context = dynamic_context
+    rebuild!
   end
 
   # Add custom keys to an entry.
@@ -119,29 +155,37 @@ class Rage::Logger
 
   # Add a custom tag to an entry.
   #
-  # @param tag [String] the tag to add to an entry
+  # @param tags [String] the tag to add to an entry
   # @example
   #   Rage.logger.tagged("ApiCall") do
   #     Rage.logger.info "success"
   #   end
-  def tagged(tag)
-    (Thread.current[:rage_logger] ||= { tags: [], context: {} })[:tags] << tag
+  def tagged(*tags)
+    old_tags = (Thread.current[:rage_logger] ||= { tags: [], context: {} })[:tags]
+    Thread.current[:rage_logger][:tags] = old_tags + tags
     yield(self)
   ensure
-    Thread.current[:rage_logger][:tags].pop
+    Thread.current[:rage_logger][:tags] = old_tags
   end
 
   alias_method :with_tag, :tagged
 
+  # Check if the debug level is enabled.
   def debug? = @level <= Logger::DEBUG
+  # Check if the error level is enabled.
   def error? = @level <= Logger::ERROR
+  # Check if the fatal level is enabled.
   def fatal? = @level <= Logger::FATAL
+  # Check if the info level is enabled.
   def info? = @level <= Logger::INFO
+  # Check if the warn level is enabled.
   def warn? = @level <= Logger::WARN
+  # Check if the unknown level is enabled.
+  def unknown? = @level <= Logger::UNKNOWN
 
   private
 
-  def define_log_methods
+  def rebuild!
     methods = METHODS_MAP.map do |level_name, level_val|
       if @logdev.nil? || level_val < @level
         # logging is disabled or the log level is higher than the current one
@@ -150,25 +194,55 @@ class Rage::Logger
             false
           end
         RUBY
-      elsif @formatter.class.name.start_with?("Rage::")
-        # the call was made from within the application and a built-in formatter is used;
-        # in such case we use the `gen_timestamp` method which is much faster than `Time.now.strftime`;
-        # it's not a standard approach however, so it's used with built-in formatters only
-        <<-RUBY
+      elsif @external_logger.is_a?(External::Static)
+        # an object that implements Ruby's Logger interface is used as a logger
+        <<~RUBY
           def #{level_name}(msg = nil)
-            @logdev.write(
-              @formatter.call("#{level_name}".freeze, Iodine::Rack::Utils.gen_timestamp, nil, msg || yield)
-            )
+            #{with_dynamic_tags_and_context do
+              <<~RUBY
+                @external_logger.wrapped.#{level_name}(
+                  #{build_formatter_call(level_name, level_val)}
+                )
+              RUBY
+            end}
+          end
+        RUBY
+      elsif @external_logger.is_a?(External::Dynamic)
+        # a callable object is used as a logger
+        call_method = if @external_logger.wrapped.is_a?(Proc)
+          @external_logger.wrapped
+        else
+          @external_logger.wrapped.method(:call)
+        end
+
+        parameters = Rage::Internal.build_arguments(call_method, {
+          severity: ":#{level_name}",
+          tags: "logger[:tags].freeze",
+          context: "logger[:context].freeze",
+          message: "block_given? ? yield : msg",
+          request_info: "logger[:final].freeze"
+        })
+
+        <<~RUBY
+          def #{level_name}(msg = nil)
+            #{with_dynamic_tags_and_context do
+              <<~RUBY
+                logger = Thread.current[:rage_logger] || { tags: [], context: {} }
+                @external_logger.wrapped.call(#{parameters})
+              RUBY
+            end}
           end
         RUBY
       else
-        # the call was made from within the application and a custom formatter is used;
-        # stick to the standard approach of using one of the Log Level constants as sevetiry and `Time.now` as time
-        <<-RUBY
+        <<~RUBY
           def #{level_name}(msg = nil)
-            @logdev.write(
-              @formatter.call(#{level_val}, Time.now, nil, msg || yield)
-            )
+            #{with_dynamic_tags_and_context do
+              <<~RUBY
+                @logdev.write(
+                  #{build_formatter_call(level_name, level_val)}
+                )
+              RUBY
+            end}
           end
         RUBY
       end
@@ -176,4 +250,36 @@ class Rage::Logger
 
     self.class.class_eval(methods.join("\n"))
   end
+
+  def build_formatter_call(level_name, level_val)
+    if @formatter.class.name.start_with?("Rage::")
+      # a built-in formatter is used - use the `gen_timestamp` method which is much faster than `Time.now.strftime`;
+      # it's not a standard approach however, so it's used with built-in formatters only
+      <<~RUBY
+        @formatter.call("#{level_name}".freeze, Iodine::Rack::Utils.gen_timestamp, nil, block_given? ? yield : msg)
+      RUBY
+    else
+      # a custom formatter is used - stick to the standard approach of using one of the
+      # Log Level constants as severity and `Time.now` as time
+      <<~RUBY
+        @formatter.call(#{level_val}, Time.now, nil, block_given? ? yield : msg)
+      RUBY
+    end
+  end
+
+  def with_dynamic_tags_and_context
+    do_calls, end_calls = [], []
+
+    if @dynamic_tags
+      do_calls << "tagged(*@dynamic_tags.call) do"
+      end_calls << "end"
+    end
+
+    if @dynamic_context
+      do_calls << "with_context(@dynamic_context.call) do"
+      end_calls << "end"
+    end
+
+    "#{do_calls.join("\n")}\n#{yield}\n#{end_calls.join("\n")}"
+  end
 end

data/lib/rage/logger/text_formatter.rb

@@ -1,3 +1,20 @@
+##
+# Text formatter for Rage logger.
+#
+# Example log line:
+#
+# ```
+# [fecbba0735355738] timestamp=2025-10-19T11:12:56+00:00 pid=1825 level=info method=GET path=/api/v1/resource controller=Api::V1::ResourceController action=index status=200 duration=0.15
+# ```
+#
+# Use {Rage.configure Rage.configure} to set the formatter:
+#
+# ```ruby
+# Rage.configure do |config|
+#   config.log_formatter = Rage::TextFormatter.new
+# end
+# ```
+#
 class Rage::TextFormatter
   def initialize
     @pid = Process.pid
@@ -17,11 +34,13 @@ class Rage::TextFormatter
 
     if (final = logger[:final])
       params, env = final[:params], final[:env]
+      tags = tags.map { |tag| "[#{tag}]" }.join
+
       if params && params[:controller]
-        return "[#{tags[0]}] timestamp=#{timestamp} pid=#{@pid} level=info method=#{env["REQUEST_METHOD"]} path=#{env["PATH_INFO"]} controller=#{Rage::Router::Util.path_to_name(params[:controller])} action=#{params[:action]} #{context_msg}status=#{final[:response][0]} duration=#{final[:duration]}\n"
+        return "#{tags} timestamp=#{timestamp} pid=#{@pid} level=info method=#{env["REQUEST_METHOD"]} path=#{env["PATH_INFO"]} controller=#{Rage::Router::Util.path_to_name(params[:controller])} action=#{params[:action]} #{context_msg}status=#{final[:response][0]} duration=#{final[:duration]}\n"
       else
         # no controller/action keys are written if there are no params
-        return "[#{tags[0]}] timestamp=#{timestamp} pid=#{@pid} level=info method=#{env["REQUEST_METHOD"]} path=#{env["PATH_INFO"]} #{context_msg}status=#{final[:response][0]} duration=#{final[:duration]}\n"
+        return "#{tags} timestamp=#{timestamp} pid=#{@pid} level=info method=#{env["REQUEST_METHOD"]} path=#{env["PATH_INFO"]} #{context_msg}status=#{final[:response][0]} duration=#{final[:duration]}\n"
       end
     end
 

data/lib/rage/middleware/fiber_wrapper.rb

@@ -17,6 +17,14 @@ class Rage::FiberWrapper
   def call(env)
     fiber = Fiber.schedule do
       @app.call(env)
+    rescue Exception => e
+      exception_str = "#{e.class} (#{e.message}):\n#{e.backtrace.join("\n")}"
+      Rage.logger << exception_str
+      if Rage.env.development?
+        [500, {}, [exception_str]]
+      else
+        [500, {}, []]
+      end
     ensure
       # notify Iodine the request can now be resumed
       Iodine.publish(Fiber.current.__get_id, "", Iodine::PubSub::PROCESS)

data/lib/rage/middleware/reloader.rb

@@ -5,29 +5,24 @@ class Rage::Reloader
     Iodine.on_state(:on_start) do
       Rage.code_loader.check_updated!
     end
+
     @app = app
+    @mutex = Mutex.new
   end
 
   def call(env)
     with_reload do
       @app.call(env)
     end
-  rescue Exception => e
-    exception_str = "#{e.class} (#{e.message}):\n#{e.backtrace.join("\n")}"
-    puts(exception_str)
-    [500, {}, [exception_str]]
   end
 
   private
 
   def with_reload
-    if Rage.code_loader.check_updated!
-      Fiber.new(blocking: true) {
-        Rage.code_loader.reload
-        yield
-      }.resume
-    else
-      yield
+    @mutex.synchronize do
+      Rage.code_loader.reload if Rage.code_loader.check_updated!
     end
+
+    yield
   end
 end

data/lib/rage/request.rb

@@ -36,8 +36,11 @@ class Rage::Request
   KNOWN_HTTP_METHODS = (RFC2616 + RFC2518 + RFC3253 + RFC3648 + RFC3744 + RFC5323 + RFC4791 + RFC5789).to_set
 
   # @private
-  def initialize(env)
+  # @param env [Hash] Rack env
+  # @param controller [RageController::API]
+  def initialize(env, controller: nil)
     @env = env
+    @controller = controller
   end
 
   # Check if the request was made using TLS/SSL which is if http or https protocol is used inside the URL.
@@ -203,6 +206,20 @@ class Rage::Request
 
   alias_method :uuid, :request_id
 
+  # Get the route URI pattern matched for this request.
+  # @return [String] the route URI pattern
+  # @example
+  #   # For a route defined as:
+  #   #   get "/users/:id", to: "users#show"
+  #   request.route_uri_pattern # => "/users/:id"
+  def route_uri_pattern
+    if @controller
+      Rage::Router::Util.route_uri_pattern(@controller.class, @controller.action_name)
+    else
+      path
+    end
+  end
+
   private
 
   def rack_request

data/lib/rage/response.rb

@@ -16,7 +16,7 @@ class Rage::Response
   # Returns the content of the response as a string. This contains the contents of any calls to `render`.
   # @return [String]
   def body
-    @body[0]
+    @body[0] || ""
   end
 
   # Returns the headers for the response.

data/lib/rage/router/util.rb

@@ -31,6 +31,14 @@ class Rage::Router::Util
         @@names_map[str] = path_to_class(str).name
       end
     end
+
+    @@uri_patterns_map = Hash.new { |h, k| h[k] = {} }
+
+    def route_uri_pattern(controller_class, action_name)
+      @@uri_patterns_map[controller_class][action_name] ||= Rage.__router.routes.find { |route|
+        route[:meta][:controller_class] == controller_class && route[:meta][:action] == action_name
+      }[:path]
+    end
   end
 
   # @private

data/lib/rage/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Rage
-  VERSION = "1.18.0"
+  VERSION = "1.19.0"
 end

data/lib/rage-rb.rb

@@ -6,71 +6,115 @@ require "iodine"
 require "pathname"
 
 module Rage
+  # Builds the Rage application with the configured middlewares.
   def self.application
     with_middlewares(Application.new(__router), config.middleware.middlewares)
   end
 
+  # Builds the Rage application which delegates Rails requests to `Rails.application`.
   def self.multi_application
     Rage::Router::Util::Cascade.new(application, Rails.application)
   end
 
+  # Shorthand to access {Rage::Cable Rage::Cable}.
+  # @return [Rage::Cable]
   def self.cable
     Rage::Cable
   end
 
+  # Shorthand to access {Rage::OpenAPI Rage::OpenAPI}.
+  # @return [Rage::OpenAPI]
   def self.openapi
     Rage::OpenAPI
   end
 
+  # Shorthand to access {Rage::Deferred Rage::Deferred}.
+  # @return [Rage::Deferred]
   def self.deferred
     Rage::Deferred
   end
 
+  # Shorthand to access {Rage::Events Rage::Events}.
+  # @return [Rage::Events]
   def self.events
     Rage::Events
   end
 
+  # Configure routes for the Rage application.
+  # @return [Rage::Router::DSL::Handler]
+  # @example
+  #   Rage.routes.draw do
+  #     root to: "users#index"
+  #   end
   def self.routes
     Rage::Router::DSL.new(__router)
   end
 
+  # @private
   def self.__router
     @__router ||= Rage::Router::Backend.new
   end
 
+  # @private
+  def self.__log_processor
+    @__log_processor ||= Rage::LogProcessor.new
+  end
+
+  # Access the Rage configuration.
+  # @return [Rage::Configuration] the Rage configuration instance.
   def self.config
     @config ||= Rage::Configuration.new
   end
 
+  # Configure Rage using a block.
+  # @example
+  #   Rage.configure do |config|
+  #     config.log_level = :debug
+  #   end
   def self.configure(&)
     config.instance_eval(&)
     config.__finalize
   end
 
+  # Access the current Rage environment.
+  # @return [Rage::Env] the Rage environment instance
+  # @example
+  #   if Rage.env.development?
+  #     puts "Running in development mode"
+  #   end
   def self.env
     @__env ||= Rage::Env.new(ENV["RAGE_ENV"] || ENV["RAILS_ENV"] || ENV["RACK_ENV"] || "development")
   end
 
+  # Access the current Gem groups based on the Rage environment.
   def self.groups
     [:default, Rage.env.to_sym]
   end
 
+  # Access the root path of the Rage application.
+  # @return [Pathname] the root path
   def self.root
     @root ||= Pathname.new(".").expand_path
   end
 
+  # Access the Rage logger.
+  # @return [Rage::Logger] the Rage logger instance
   def self.logger
     @logger ||= config.logger
   end
 
+  # Load middlewares into the Rage application.
+  # @deprecated This method is deprecated and has been merged into `Rage.application`.
   def self.load_middlewares(_)
     puts "`Rage.load_middlewares` is deprecated and has been merged into `Rage.application`. Please remove this call."
   end
 
+  # @private
   def self.code_loader
     @code_loader ||= Rage::CodeLoader.new
   end
 
+  # @private
   def self.patch_active_record_connection_pool
     patch = proc do
       is_connected = ActiveRecord::Base.connection_pool rescue false
@@ -94,6 +138,7 @@ module Rage
     end
   end
 
+  # Load Rake tasks for the Rage application.
   def self.load_tasks
     Rage::Tasks.init
   end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: rage-rb
 version: !ruby/object:Gem::Version
-  version: 1.18.0
+  version: 1.19.0
 platform: ruby
 authors:
 - Roman Samoilov
 bindir: exe
 cert_chain: []
-date: 2025-10-29 00:00:00.000000000 Z
+date: 2025-12-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: thor
@@ -144,8 +144,8 @@ files:
 - lib/rage/cookies.rb
 - lib/rage/deferred/backends/disk.rb
 - lib/rage/deferred/backends/nil.rb
+- lib/rage/deferred/context.rb
 - lib/rage/deferred/deferred.rb
-- lib/rage/deferred/metadata.rb
 - lib/rage/deferred/proxy.rb
 - lib/rage/deferred/queue.rb
 - lib/rage/deferred/task.rb
@@ -159,6 +159,7 @@ files:
 - lib/rage/fiber_scheduler.rb
 - lib/rage/hooks.rb
 - lib/rage/internal.rb
+- lib/rage/log_processor.rb
 - lib/rage/logger/json_formatter.rb
 - lib/rage/logger/logger.rb
 - lib/rage/logger/text_formatter.rb

data/lib/rage/deferred/metadata.rb

@@ -1,43 +0,0 @@
-# frozen_string_literal: true
-
-##
-# Metadata for deferred tasks.
-# The class encapsulates the metadata associated with a deferred task, and allows to store it without modifying the task instance.
-#
-class Rage::Deferred::Metadata
-  def self.build(task, args, kwargs)
-    request_id = Thread.current[:rage_logger][:tags][0] if Thread.current[:rage_logger]
-
-    [
-      task,
-      args.empty? ? nil : args,
-      kwargs.empty? ? nil : kwargs,
-      nil,
-      request_id
-    ]
-  end
-
-  def self.get_task(metadata)
-    metadata[0]
-  end
-
-  def self.get_args(metadata)
-    metadata[1]
-  end
-
-  def self.get_kwargs(metadata)
-    metadata[2]
-  end
-
-  def self.get_attempts(metadata)
-    metadata[3]
-  end
-
-  def self.get_request_id(metadata)
-    metadata[4]
-  end
-
-  def self.inc_attempts(metadata)
-    metadata[3] = metadata[3].to_i + 1
-  end
-end