rage-rb 1.17.1 → 1.19.0

data/lib/rage/configuration.rb

@@ -4,262 +4,363 @@ require "yaml"
 require "erb"
 
 ##
-# `Rage.configure` can be used to adjust the behavior of your Rage application:
+# Configuration class for Rage framework.
 #
+# Use {Rage.configure Rage.configure} to access and modify the configuration.
+#
+# **Example:**
 # ```ruby
 # Rage.configure do
-#   config.logger = Rage::Logger.new(STDOUT)
-#   config.server.workers_count = 2
-# end
-# ```
-#
-# # General Configuration
-#
-# • _config.logger_
-#
-# > The logger that will be used for `Rage.logger` and any related `Rage` logging. Custom loggers should implement Ruby's {https://ruby-doc.org/3.2.2/stdlibs/logger/Logger.html#class-Logger-label-Entries Logger} interface.
-#
-# • _config.log_formatter_
-#
-# > The formatter of the Rage logger. Built in options include `Rage::TextFormatter` and `Rage::JSONFormatter`. Defaults to an instance of `Rage::TextFormatter`.
-#
-# • _config.log_level_
-#
-# > Defines the verbosity of the Rage logger. This option defaults to `:debug` for all environments except production, where it defaults to `:info`. The available log levels are: `:debug`, `:info`, `:warn`, `:error`, `:fatal`, and `:unknown`.
-#
-# • _config.secret_key_base_
-#
-# > The `secret_key_base` is used as the input secret to the application's key generator, which is used to encrypt cookies. Rage will fall back to the `SECRET_KEY_BASE` environment variable if this is not set.
-#
-# • _config.fallback_secret_key_base_
-#
-# > Defines one or several old secrets that need to be rotated. Can accept a single key or an array of keys. Rage will fall back to the `FALLBACK_SECRET_KEY_BASE` environment variable if this is not set.
-#
-# • _config.after_initialize_
-#
-# > Schedule a block of code to run after Rage has finished loading the application code. Use this to reference application-level constants during the initialization process.
-# > ```
-# Rage.config.after_initialize do
-#   SUPER_USER = User.find_by!(super: true)
-# end
-# > ```
-#
-# # Middleware Configuration
-#
-# • _config.middleware.use_
-#
-# > Adds a middleware to the top of the middleware stack. **This is the recommended way of adding a middleware.**
-# > ```
-# config.middleware.use Rack::Cors do
-#   allow do
-#     origins "*"
-#     resource "*", headers: :any
-#   end
-# end
-# > ```
-#
-# • _config.middleware.insert_before_
-#
-# > Adds middleware at a specified position before another middleware. The position can be either an index or another middleware.
-#
-# > **_❗️Heads up:_** By default, Rage always uses the `Rage::FiberWrapper` middleware, which wraps every request in a separate fiber. Make sure to always have this middleware in the top of the stack. Placing other middlewares in front may lead to undefined behavior.
-#
-# > ```
-# config.middleware.insert_before Rack::Head, Magical::Unicorns
-# config.middleware.insert_before 0, Magical::Unicorns
-# > ```
-#
-# • _config.middleware.insert_after_
-#
-# > Adds middleware at a specified position after another middleware. The position can be either an index or another middleware.
-#
-# > ```
-# config.middleware.insert_after Rack::Head, Magical::Unicorns
-# > ```
-#
-# # Server Configuration
-#
-# _• config.server.max_clients_
-#
-# > Limits the number of simultaneous connections the server can accept. Defaults to the maximum number of open files.
-#
-# > **_❗️Heads up:_** Decreasing this number is almost never a good idea. Depending on your application specifics, you are encouraged to use other methods to limit the number of concurrent connections:
-#
-# > 1. If your application is exposed to the public, you may want to use a cloud rate limiter, like {https://developers.cloudflare.com/waf Cloudflare WAF} or {https://docs.fastly.com/en/ngwaf Fastly WAF}.
-# > 2. Otherwise, consider using tools like {https://github.com/rack/rack-attack Rack::Attack} or {https://github.com/mperham/connection_pool connection_pool}.
-#
-# > ```
-# # Limit the amount of connections your application can accept
-# config.middleware.use Rack::Attack
-# Rack::Attack.throttle("req/ip", limit: 300, period: 5.minutes) do |req|
-#   req.ip
-# end
-# #
-# # Limit the amount of connections to a specific resource
-# HTTP = ConnectionPool.new(size: 5, timeout: 5) { Net::HTTP }
-# HTTP.with do |conn|
-#   conn.get("/my-resource")
-# end
-# > ```
-#
-# • _config.server.port_
-#
-# > Specifies what port the server will listen on.
-#
-# • _config.server.workers_count_
-#
-# > Specifies the number of server processes to run. Defaults to 1 in development and to the number of available CPU cores in other environments.
-#
-# • _config.server.timeout_
-#
-# > Specifies connection timeout.
-#
-# # Static file server
-#
-# • _config.public_file_server.enabled_
-#
-# > Configures whether Rage should serve static files from the public directory. Defaults to `false`.
-#
-# # Cable Configuration
-#
-# • _config.cable.protocol_
-#
-# > Specifies the protocol the server will use. Supported values include {Rage::Cable::Protocols::ActioncableV1Json :actioncable_v1_json} and {Rage::Cable::Protocols::RawWebSocketJson :raw_websocket_json}. Defaults to {Rage::Cable::Protocols::ActioncableV1Json :actioncable_v1_json}.
-#
-# • _config.cable.allowed_request_origins_
-#
-# > Restricts the server to only accept requests from specified origins. The origins can be instances of strings or regular expressions, against which a check for the match will be performed.
-#
-# • _config.cable.disable_request_forgery_protection_
-#
-# > Allows requests from any origin.
-#
-# # OpenAPI Configuration
-# • _config.openapi.tag_resolver_
-#
-# > Specifies the proc to build tags for API operations. The proc accepts the controller class, the symbol name of the action, and the default tag built by Rage.
-#
-# > ```ruby
-# config.openapi.tag_resolver = proc do |controller, action, default_tag|
-#    # ...
+#   config.log_level = :warn
+#   config.server.port = 8080
 # end
-# > ```
-#
-# # Deferred Configuration
-# • _config.deferred.backend_
-#
-# > Specifies the backend for deferred tasks. Supported values are `:disk`, which uses disk storage, or `nil`, which disables persistence of deferred tasks.
-# > The `:disk` backend accepts the following options:
-# >
-# > - `:path` - the path to the directory where deferred tasks will be stored. Defaults to `storage`.
-# > - `:prefix` - the prefix for the deferred task files. Defaults to `deferred-`.
-# > - `:fsync_frequency` - the frequency of `fsync` calls in seconds. Defaults to `0.5`.
-#
-# > ```ruby
-# config.deferred.backend = :disk, { path: "storage" }
-# > ```
-#
-# • _config.deferred.backpressure_
-#
-# > Enables the backpressure for deferred tasks. The backpressure is used to limit the number of pending tasks in the queue. It accepts a hash with the following options:
-# >
-# > - `:high_water_mark` - the maximum number of pending tasks in the queue. Defaults to `1000`.
-# > - `:low_water_mark` - the minimum number of pending tasks in the queue before the backpressure is released. Defaults to `high_water_mark * 0.8`.
-# > - `:timeout` - the timeout for the backpressure in seconds. Defaults to `2`.
-#
-# > ```ruby
-# config.deferred.backpressure = { high_water_mark: 1000, low_water_mark: 800, timeout: 2 }
-# > ```
-#
-# > Additionally, you can set the backpressure value to `true` to use the default values:
-#
-# > ```ruby
-# config.deferred.backpressure = true
 # ```
 #
-# # Transient Settings
+# ## Transient Settings
 #
 # The settings described in this section should be configured using **environment variables** and are either temporary or will become the default in the future.
 #
-# • _RAGE_DISABLE_IO_WRITE_
-#
-# > Disables the `io_write` hook to fix the ["zero-length iov"](https://bugs.ruby-lang.org/issues/19640) error on Ruby < 3.3.
-#
-# • _RAGE_DISABLE_AR_POOL_PATCH_
-#
-# > Disables the `ActiveRecord::ConnectionPool` patch and makes Rage use the original ActiveRecord implementation.
-#
-# • _RAGE_DISABLE_AR_WEAK_CONNECTIONS_
-#
-# > Instructs Rage to not reuse Active Record connections between different fibers.
+# - _RAGE_DISABLE_IO_WRITE_ - disables the `io_write` hook to fix the ["zero-length iov"](https://bugs.ruby-lang.org/issues/19640) error on Ruby < 3.3.
+# - _RAGE_DISABLE_AR_POOL_PATCH_ - disables the `ActiveRecord::ConnectionPool` patch and makes Rage use the original ActiveRecord implementation.
+# - _RAGE_DISABLE_AR_WEAK_CONNECTIONS_ - instructs Rage to not reuse Active Record connections between different fibers. Only applies to Active Record < 7.2.
 #
 class Rage::Configuration
+  # @private
   include Hooks
 
-  attr_accessor :logger
-  attr_reader :log_formatter, :log_level
-  attr_writer :secret_key_base, :fallback_secret_key_base
-
+  # @private
   # used in DSL
   def config = self
 
+  # @!group General Configuration
+
+  # Returns the logger used by Rage.
+  # @return [Rage::Logger, nil]
+  def logger
+    @logger
+  end
+
+  # Set the logger used by Rage.
+  # Accepts a logger object that implements the `#debug`, `#info`, `#warn`, `#error`, `#fatal`, and `#unknown` methods, or `nil`. If set to `nil`, logging will be disabled.
+  # `Rage.logger` always returns an instance of {Rage::Logger Rage::Logger}, but if you provide a custom object, it will be used internally by `Rage.logger`.
+  #
+  # @overload logger=(logger)
+  #   Set a standard logger
+  #   @param logger [#debug, #info, #warn, #error, #fatal, #unknown]
+  #   @example
+  #     config.logger = Rage::Logger.new(STDOUT)
+  # @overload logger=(callable)
+  #   Set an external logger. This allows you to send Rage's raw structured logging data directly to external observability platforms without serializing it to text first.
+  #
+  #   The external logger receives pre-parsed structured data (severity, tags, context) rather than formatted strings. This differs from `config.log_formatter` in that formatters control how logs are formatted (text vs JSON), while the external logger controls where logs are sent and how they integrate with external platforms.
+  #   @param callable [ExternalLoggerInterface]
+  #   @example
+  #     config.logger = proc do |severity:, tags:, context:, message:, request_info:|
+  #       # Custom logging logic here
+  #     end
+  # @overload logger=(nil)
+  #  Disable logging
+  #  @example
+  #    config.logger = nil
+  def logger=(logger)
+    @logger = if logger.nil? || logger.is_a?(Rage::Logger)
+      logger
+    elsif Rage::Logger::METHODS_MAP.keys.all? { |method| logger.respond_to?(method) }
+      Rage::Logger.new(Rage::Logger::External::Static[logger])
+    elsif logger.respond_to?(:call)
+      Rage::Logger.new(Rage::Logger::External::Dynamic[logger])
+    else
+      raise ArgumentError, "Invalid logger: must be an instance of `Rage::Logger`, respond to `#call`, or implement all standard Ruby Logger methods (`#debug`, `#info`, `#warn`, `#error`, `#fatal`, `#unknown`)"
+    end
+  end
+
+  # Returns the log formatter used by Rage.
+  # @return [#call, nil]
+  def log_formatter
+    @log_formatter
+  end
+
+  # Set the log formatter used by Rage.
+  # Built in options include {Rage::TextFormatter Rage::TextFormatter} and {Rage::JSONFormatter Rage::JSONFormatter}.
+  #
+  # @param formatter [#call] a callable object that formats log messages
+  # @example
+  #   config.log_formatter = proc do |severity, datetime, progname, msg|
+  #     "[#{datetime}] #{severity} -- #{progname}: #{msg}\n"
+  #   end
   def log_formatter=(formatter)
     raise ArgumentError, "Custom log formatter should respond to `#call`" unless formatter.respond_to?(:call)
     @log_formatter = formatter
   end
 
+  # Returns the log level used by Rage.
+  # @return [Integer, nil]
+  def log_level
+    @log_level
+  end
+
+  # Set the log level used by Rage.
+  # @param level [:debug, :info, :warn, :error, :fatal, :unknown, Integer] the log level
+  # @example
+  #   config.log_level = :info
   def log_level=(level)
     @log_level = level.is_a?(Symbol) ? Logger.const_get(level.to_s.upcase) : level
   end
 
+  # The secret key base is used as the input secret to the application's key generator, which is used to encrypt cookies. Rage will fall back to the `SECRET_KEY_BASE` environment variable if this is not set.
+  # @param key [String] the secret key base
+  def secret_key_base=(key)
+    @secret_key_base = key
+  end
+
+  # Returns the secret key base used for encrypting cookies.
+  # @return [String, nil]
   def secret_key_base
     @secret_key_base || ENV["SECRET_KEY_BASE"]
   end
 
+  # Set one or several old secrets that need to be rotated. Can accept a single key or an array of keys. Rage will fall back to the `FALLBACK_SECRET_KEY_BASE` environment variable if this is not set.
+  # @param key [String, Array<String>] the fallback secret key base(s)
+  def fallback_secret_key_base=(key)
+    @fallback_secret_key_base = key
+  end
+
+  # Returns the fallback secret key base(s) used for decrypting cookies encrypted with old secrets.
+  # @return [Array<String>]
   def fallback_secret_key_base
     Array(@fallback_secret_key_base || ENV["FALLBACK_SECRET_KEY_BASE"])
   end
 
-  def server
-    @server ||= Server.new
+  # Schedule a block of code to run after Rage has finished loading the application code. Use this to reference application-level constants during the initialization process.
+  # @example
+  #   Rage.config.after_initialize do
+  #     SUPER_USER = User.find_by!(super: true)
+  #   end
+  def after_initialize(&block)
+    push_hook(block, :after_initialize)
   end
+  # @!endgroup
 
+  # @!group Middleware Configuration
+  # Allows configuring the middleware stack used by Rage.
+  # @return [Rage::Configuration::Middleware]
   def middleware
     @middleware ||= Middleware.new
   end
+  # @!endgroup
 
-  def cable
-    @cable ||= Cable.new
+  # @!group Server Configuration
+  # Allows configuring the built-in Rage server.
+  # @return [Rage::Configuration::Server]
+  def server
+    @server ||= Server.new
   end
+  # @!endgroup
 
+  # @!group Static File Server
+  # Allows configuring the static file server used by Rage.
+  # @return [Rage::Configuration::PublicFileServer]
   def public_file_server
     @public_file_server ||= PublicFileServer.new
   end
+  # @!endgroup
+
+  # @!group Cable Configuration
+  # Allows configuring Cable settings.
+  # @return [Rage::Configuration::Cable]
+  def cable
+    @cable ||= Cable.new
+  end
+  # @!endgroup
 
+  # @!group OpenAPI Configuration
+  # Allows configuring OpenAPI settings.
+  # @return [Rage::Configuration::OpenAPI]
   def openapi
     @openapi ||= OpenAPI.new
   end
+  # @!endgroup
 
+  # @!group Deferred Configuration
+  # Allows configuring Deferred settings.
+  # @return [Rage::Configuration::Deferred]
   def deferred
     @deferred ||= Deferred.new
   end
+  # @!endgroup
 
-  def internal
-    @internal ||= Internal.new
+  # @!group Logging Context and Tags Configuration
+  # Allows configuring custom log context objects that will be included in every log entry.
+  # @return [Rage::Configuration::LogContext]
+  def log_context
+    @log_context ||= LogContext.new
   end
 
-  def after_initialize(&block)
-    push_hook(block, :after_initialize)
+  # Allows configuring custom log tags that will be included in every log entry.
+  # @return [Rage::Configuration::LogTags]
+  def log_tags
+    @log_tags ||= LogTags.new
+  end
+  # @!endgroup
+
+  # @private
+  def internal
+    @internal ||= Internal.new
   end
 
+  # @private
   def run_after_initialize!
     run_hooks_for!(:after_initialize, self)
   end
 
+  class LogContext
+    # @private
+    def initialize
+      @objects = []
+    end
+
+    # @private
+    def objects
+      @objects.dup
+    end
+
+    # Add a new custom log context object. Each context object is evaluated independently and the results are merged into the final log entry.
+    # @overload <<(hash)
+    #   Add a static log context entry.
+    #   @param hash [Hash] a hash representing the log context
+    #   @example
+    #     Rage.configure do
+    #       config.log_context << { version: ENV["APP_VERSION"] }
+    #     end
+    # @overload <<(callable)
+    #   Add a dynamic log context entry. Dynamic context entries are executed on every log call to capture dynamic state like changing span IDs during request processing.
+    #   @param callable [#call] a callable object that returns a hash representing the log context or nil
+    #   @example
+    #     Rage.configure do
+    #       config.log_context << proc { { trace_id: MyObservabilitySDK.trace_id } if MyObservabilitySDK.active? }
+    #     end
+    #   @note Exceptions from dynamic context callables will cause the entire request to fail. Make sure to handle exceptions inside the callable if necessary.
+    def <<(block_or_hash)
+      validate_input!(block_or_hash)
+      @objects << block_or_hash
+      @objects.tap(&:flatten!).tap(&:uniq!)
+
+      self
+    end
+
+    alias_method :push, :<<
+
+    # Remove a custom log context object.
+    # @param block_or_hash [Hash, #call] the context object to remove
+    # @example
+    #   Rage.configure do
+    #     config.log_context.delete(MyObservabilitySDK::LOG_CONTEXT)
+    #   end
+    def delete(block_or_hash)
+      @objects.delete(block_or_hash)
+    end
+
+    private
+
+    def validate_input!(obj)
+      if obj.is_a?(Array)
+        obj.each { |item| validate_input!(item) }
+      elsif !obj.is_a?(Hash) && !obj.respond_to?(:call)
+        raise ArgumentError, "custom log context has to be a hash, an array of hashes, or respond to `#call`"
+      end
+    end
+  end
+
+  class LogTags < LogContext
+    # @!method <<(block_or_string)
+    #   Add a new custom log tag. Each tag is evaluated independently and the results are merged into the final log entry.
+    #   @overload <<(string)
+    #     Add a static log tag.
+    #     @param string [String] the log tag
+    #     @example
+    #       Rage.configure do
+    #         config.log_tags << Rage.env
+    #       end
+    #   @overload <<(callable)
+    #     Add a dynamic log tag. Dynamic tags are executed on every log call.
+    #     @param callable [#call] a callable object that returns a string representing the log tag, an array of log tags, or nil
+    #     @example
+    #       Rage.configure do
+    #         config.log_tags << proc { Current.tenant.slug }
+    #       end
+    #     @note Exceptions from dynamic tag callables will cause the entire request to fail. Make sure to handle exceptions inside the callable if necessary.
+
+    # @!method delete(block_or_string)
+    #   Remove a custom log tag object.
+    #   @param block_or_string [String, #call] the tag object to remove
+    #   @example
+    #     Rage.configure do
+    #       config.log_tags.delete(MyObservabilitySDK::LOG_TAGS)
+    #     end
+
+    # @private
+    private
+
+    def validate_input!(obj)
+      if obj.is_a?(Array)
+        obj.each { |item| validate_input!(item) }
+      elsif !obj.respond_to?(:to_str) && !obj.respond_to?(:call)
+        raise ArgumentError, "custom log tag has to be a string, an array of strings, or respond to `#call`"
+      end
+    end
+  end
+
   class Server
+    # @!attribute port
+    #   Specify the port the server will listen on.
+    #   @return [Integer]
+    #   @example Change the default port
+    #     Rage.configure do
+    #       config.server.port = 3001
+    #     end
+    #
+    # @!attribute workers_count
+    #   Specify the number of worker processes to spawn. Use `-1` to spawn one worker per CPU core.
+    #   @return [Integer]
+    #   @example Change the number of worker processes
+    #     Rage.configure do
+    #       config.server.workers_count = 4
+    #     end
+    #
+    # @!attribute timeout
+    #   Specify the connection timeout in seconds.
+    #   @return [Integer]
+    #   @example Change the connection timeout
+    #     Rage.configure do
+    #       config.server.timeout = 30
+    #     end
+    #
+    # @!attribute max_clients
+    #   Limit the number of simultaneous connections the server can accept. Defaults to the maximum number of open files.
+    #   @return [Integer]
+    #
+    #   @note Decreasing this number is almost never a good idea. Depending on your application specifics, you are encouraged to use other methods to limit the number of concurrent connections:
+    #
+    #     - If your application is exposed to the public, you may want to use a cloud rate limiter, like {https://developers.cloudflare.com/waf Cloudflare WAF} or {https://docs.fastly.com/en/ngwaf Fastly WAF}.
+    #     - Otherwise, consider using tools like {https://github.com/rack/rack-attack Rack::Attack} or {https://github.com/mperham/connection_pool connection_pool}.
+    #   @example Limit the amount of connections your application can accept
+    #     Rage.configure do
+    #       config.middleware.use Rack::Attack
+    #       Rack::Attack.throttle("req/ip", limit: 300, period: 5.minutes) do |req|
+    #         req.ip
+    #       end
+    #     end
+    #   @example Limit the amount of connections to a specific resource
+    #     HTTP = ConnectionPool.new(size: 5, timeout: 5) { Net::HTTP }
+    #     HTTP.with do |conn|
+    #       conn.get("/my-resource")
+    #     end
     attr_accessor :port, :workers_count, :timeout, :max_clients
+
+    # @private
     attr_reader :threads_count
 
+    # @private
     def initialize
       @threads_count = 1
       @workers_count = Rage.env.development? ? 1 : -1
@@ -268,16 +369,47 @@ class Rage::Configuration
   end
 
   class Middleware
+    # @private
     attr_reader :middlewares
 
+    # @private
     def initialize
       @middlewares = [[Rage::FiberWrapper]]
     end
 
+    # Add a new middleware to the end of the stack.
+    # @note This is the recommended way of adding a middleware.
+    # @param new_middleware [Class] the middleware class
+    # @param args [Array] arguments passed to the middleware initializer
+    # @param block [Proc] an optional block passed to the middleware initializer
+    # @example
+    #   Rage.configure do
+    #     config.middleware.use Rack::Cors do
+    #       allow do
+    #         origins "*"
+    #         resource "*", headers: :any
+    #       end
+    #     end
+    #   end
     def use(new_middleware, *args, &block)
       insert_after(@middlewares.length - 1, new_middleware, *args, &block)
     end
 
+    # Insert a new middleware before an existing middleware in the stack.
+    # @note Rage always uses the `Rage::FiberWrapper` middleware, which wraps every request in a separate fiber. Make sure to always have this middleware in the top of the stack. Placing other middlewares in front may lead to undefined behavior.
+    # @param existing_middleware [Class, Integer] the existing middleware class or its index in the stack
+    # @param new_middleware [Class] the new middleware class
+    # @param args [Array] arguments passed to the middleware initializer
+    # @param block [Proc] an optional block passed to the middleware initializer
+    # @example
+    #   Rage.configure do
+    #     config.middleware.insert_before Rack::Runtime, Rack::Cors do
+    #       allow do
+    #         origins "*"
+    #         resource "*", headers: :any
+    #       end
+    #     end
+    #   end
     def insert_before(existing_middleware, new_middleware, *args, &block)
       index = find_middleware_index(existing_middleware)
       if index == 0 && @middlewares[0][0] == Rage::FiberWrapper
@@ -286,11 +418,28 @@ class Rage::Configuration
       @middlewares = (@middlewares[0...index] + [[new_middleware, args, block]] + @middlewares[index..]).uniq(&:first)
     end
 
+    # Insert a new middleware after an existing middleware in the stack.
+    # @param existing_middleware [Class, Integer] the existing middleware class or its index in the stack
+    # @param new_middleware [Class] the new middleware class
+    # @param args [Array] arguments passed to the middleware initializer
+    # @param block [Proc] an optional block passed to the middleware initializer
+    # @example
+    #   Rage.configure do
+    #     config.middleware.insert_after Rack::Runtime, Rack::Cors do
+    #       allow do
+    #         origins "*"
+    #         resource "*", headers: :any
+    #       end
+    #     end
+    #   end
     def insert_after(existing_middleware, new_middleware, *args, &block)
       index = find_middleware_index(existing_middleware)
       @middlewares = (@middlewares[0..index] + [[new_middleware, args, block]] + @middlewares[index + 1..]).uniq(&:first)
     end
 
+    # Check if a middleware is included in the stack.
+    # @param middleware [Class, Integer] the middleware class or its index in the stack
+    # @return [Boolean]
     def include?(middleware)
       !!find_middleware_index(middleware) rescue false
     end
@@ -312,9 +461,24 @@ class Rage::Configuration
   end
 
   class Cable
+    # @!attribute allowed_request_origins
+    #   Restrict the server to only accept requests from specified origins. The origins can be strings or regular expressions. Defaults to `/localhost/` in development and test environments.
+    #   @return [Array<Regexp>, Regexp, Array<String>, String, nil]
+    #   @example
+    #     Rage.configure do
+    #       config.cable.allowed_request_origins = [/example\.com/, "myapp.com"]
+    #     end
+    #
+    # @!attribute disable_request_forgery_protection
+    #   Disable request forgery protection for WebSocket connections to allow requests from any origin.
+    #   @return [Boolean]
+    #   @example
+    #     Rage.configure do
+    #       config.cable.disable_request_forgery_protection = true
+    #     end
     attr_accessor :allowed_request_origins, :disable_request_forgery_protection
-    attr_reader :protocol
 
+    # @private
     def initialize
       @protocol = Rage::Cable::Protocols::ActioncableV1Json
       @allowed_request_origins = if Rage.env.development? || Rage.env.test?
@@ -322,6 +486,22 @@ class Rage::Configuration
       end
     end
 
+    # Returns the protocol the server will use.
+    # @return [Class] the protocol class
+    def protocol
+      @protocol
+    end
+
+    # Specify the protocol the server will use. Supported values include {Rage::Cable::Protocols::ActioncableV1Json :actioncable_v1_json} and {Rage::Cable::Protocols::RawWebSocketJson :raw_websocket_json}. Defaults to {Rage::Cable::Protocols::ActioncableV1Json :actioncable_v1_json}.
+    # @param protocol [:actioncable_v1_json, :raw_websocket_json] the protocol symbol
+    # @example Use the built-in ActionCable V1 JSON protocol
+    #   Rage.configure do
+    #     config.cable.protocol = :actioncable_v1_json
+    #   end
+    # @example Use the built-in Raw WebSocket JSON protocol
+    #   Rage.configure do
+    #     config.cable.protocol = :raw_websocket_json
+    #   end
     def protocol=(protocol)
       @protocol = case protocol
       when Class
@@ -350,6 +530,7 @@ class Rage::Configuration
       end
     end
 
+    # @private
     def config
       @config ||= begin
         config_file = Rage.root.join("config/cable.yml")
@@ -363,10 +544,12 @@ class Rage::Configuration
       end
     end
 
+    # @private
     def adapter_config
       config.except(:adapter)
     end
 
+    # @private
     def adapter
       case config[:adapter]
       when "redis"
@@ -376,20 +559,54 @@ class Rage::Configuration
   end
 
   class PublicFileServer
+    # @!attribute enabled
+    #  Configure whether Rage should serve static files from the `public` directory. Defaults to `false`.
+    #  @return [Boolean] whether the static file server is enabled
+    #  @example
+    #    Rage.configure do
+    #      config.public_file_server.enabled = true
+    #    end
     attr_accessor :enabled
   end
 
   class OpenAPI
-    attr_accessor :tag_resolver
+    # Specify the rules to customize how OpenAPI tags are generated for API operations.
+    # The method accepts a callable object that receives the controller class, the action name (as a symbol), and the original tag generated by Rage.
+    # The callable should return a string or an array of strings representing the tags to use for the API operation.
+    # This enables grouping endpoints in the OpenAPI documentation according to your application's needs.
+    # @param tag_resolver [#call] a callable object that resolves OpenAPI tags
+    # @example
+    #   Rage.configure do
+    #     config.openapi.tag_resolver = proc do |controller_class, action_name, default_tag|
+    #       if controller_class.name.start_with?("Admin::")
+    #         [default_tag, "Admin"]
+    #       else
+    #         [default_tag, "Public"]
+    #       end
+    #     end
+    #   end
+    def tag_resolver=(tag_resolver)
+      unless tag_resolver.respond_to?(:call)
+        raise ArgumentError, "Custom tag resolver should respond to `#call`"
+      end
+
+      @tag_resolver = tag_resolver
+    end
+
+    # Returns the OpenAPI tag resolver used by Rage.
+    # @return [#call, nil]
+    def tag_resolver
+      @tag_resolver
+    end
   end
 
   class Deferred
-    attr_reader :backpressure
-
+    # @private
     def initialize
       @configured = false
     end
 
+    # Returns the backend instance used by `Rage::Deferred`.
     def backend
       unless @backend_class
         @backend_class = Rage::Deferred::Backends::Disk
@@ -399,6 +616,27 @@ class Rage::Configuration
       @backend_class.new(**@backend_options)
     end
 
+    # Specify the backend used to persist deferred tasks. Supported values are `:disk`, which uses disk storage, or `nil`, which disables persistence of deferred tasks.
+    # @overload backend=(disk, options = {})
+    #   Use the disk backend.
+    #   @param options [Hash] additional backend options
+    #   @option options [Pathname, String] :path the directory where deferred tasks will be stored. Defaults to `storage/`
+    #   @option options [String] :prefix the prefix used for deferred task files. Defaults to `deferred-`
+    #   @option options [Integer] :fsync_frequency the frequency of `fsync` calls in seconds. Defaults to `0.5`
+    #   @example Use the disk backend with default options
+    #     Rage.configure do
+    #       config.deferred.backend = :disk
+    #     end
+    #   @example Use the disk backend with custom options
+    #     Rage.configure do
+    #       config.deferred.backend = :disk, path: "my_storage", fsync_frequency: 1000
+    #     end
+    # @overload backend=(nil)
+    #   Disable persistence of deferred tasks.
+    #   @example
+    #     Rage.configure do
+    #       config.deferred.backend = nil
+    #     end
     def backend=(config)
       @configured = true
 
@@ -422,6 +660,7 @@ class Rage::Configuration
     class Backpressure
       attr_reader :high_water_mark, :low_water_mark, :timeout, :sleep_interval, :timeout_iterations
 
+      # @private
       def initialize(high_water_mark = nil, low_water_mark = nil, timeout = nil)
         @high_water_mark = high_water_mark || 1_000
         @low_water_mark = low_water_mark || (@high_water_mark * 0.8).round
@@ -432,6 +671,38 @@ class Rage::Configuration
       end
     end
 
+    # Returns the backpressure configuration used by `Rage::Deferred`.
+    # @return [Backpressure, nil]
+    def backpressure
+      @backpressure
+    end
+
+    # Configure backpressure settings for `Rage::Deferred`. Backpressure is used to limit the number of pending tasks in the queue and is disabled by default.
+    #
+    # @overload backpressure=(true)
+    #   Enable backpressure with default settings.
+    #   @example
+    #     Rage.configure do
+    #       config.deferred.backpressure = true
+    #     end
+    #
+    # @overload backpressure=(false)
+    #   Disable backpressure.
+    #   @example
+    #     Rage.configure do
+    #       config.deferred.backpressure = false
+    #     end
+    #
+    # @overload backpressure=(config)
+    #   Enable backpressure with custom settings.
+    #   @param config [Hash] backpressure configuration
+    #   @option config [Integer] :high_water_mark the maximum number of deferred tasks allowed in the queue before applying backpressure. Defaults to `1000`.
+    #   @option config [Integer] :low_water_mark the minimum number of deferred tasks in the queue at which backpressure is lifted. Defaults to `80%` of `:high_water_mark`.
+    #   @option config [Integer] :timeout the maximum time in seconds to wait for the queue size to drop below `:low_water_mark` before raising the {Rage::Deferred::PushTimeout Rage::Deferred::PushTimeout} exception. Defaults to 2 seconds.
+    #   @example
+    #     Rage.configure do
+    #       config.deferred.backpressure = { high_water_mark: 2000, low_water_mark: 1500, timeout: 5 }
+    #     end
     def backpressure=(config)
       @configured = true
 
@@ -451,18 +722,22 @@ class Rage::Configuration
       @backpressure = Backpressure.new(high_water_mark, low_water_mark, timeout)
     end
 
+    # @private
     def default_disk_storage_path
       Pathname.new("storage")
     end
 
+    # @private
     def default_disk_storage_prefix
       "deferred-"
     end
 
+    # @private
     def has_default_disk_storage?
       default_disk_storage_path.glob("#{default_disk_storage_prefix}*").any?
     end
 
+    # @private
     def configured?
       @configured
     end
@@ -502,6 +777,14 @@ class Rage::Configuration
   class Internal
     attr_accessor :rails_mode
 
+    def initialized!
+      @initialized = true
+    end
+
+    def initialized?
+      !!@initialized
+    end
+
     def patch_ar_pool?
       !ENV["RAGE_DISABLE_AR_POOL_PATCH"] && !Rage.env.test?
     end
@@ -531,5 +814,52 @@ class Rage::Configuration
     else
       @logger = Rage::Logger.new(nil)
     end
+
+    if @log_formatter && @logger.external_logger.is_a?(Rage::Logger::External::Dynamic)
+      puts "WARNING: changing the log formatter via `config.log_formatter=` has no effect when using a custom external logger."
+    end
+
+    if @log_context
+      Rage.__log_processor.add_custom_context(@log_context.objects)
+      @logger.dynamic_context = Rage.__log_processor.dynamic_context
+    end
+
+    if @log_tags
+      Rage.__log_processor.add_custom_tags(@log_tags.objects)
+      @logger.dynamic_tags = Rage.__log_processor.dynamic_tags
+    end
   end
 end
+
+# @!parse [ruby]
+#   # @note This class does not exist at runtime and is used for documentation purposes only. Do not inherit external loggers from it.
+#   class ExternalLoggerInterface
+#     # Called whenever a log entry is created.
+#     #
+#     # Rage automatically detects which parameters your external logger's `#call` method accepts, and only passes those parameters. You can omit any of the described parameters in your implementation.
+#     #
+#     # @param severity [:debug, :info, :warn, :error, :fatal, :unknown] the log severity
+#     # @param tags [Array] the log tags submitted via {Rage::Logger#tagged Rage::Logger#tagged}. The first tag is always the request ID
+#     # @param context [Hash] the log context submitted via {Rage::Logger#with_context Rage::Logger#with_context}
+#     # @param message [String, nil] the log message. For request logs generated by Rage, this is always `nil`
+#     # @param request_info [Hash, nil] request-specific information. The value is `nil` for non-request logs; for request logs, contains the following keys:
+#     # @option request_info [Hash] :env the Rack env object
+#     # @option request_info [Hash] :params the request parameters
+#     # @option request_info [Array] :response the Rack response object
+#     # @option request_info [Float] :duration the duration of the request in milliseconds
+#     # @example
+#     #   Rage.configure do
+#     #     config.logger = proc do |severity:, tags:, context:, message:, request_info:|
+#     #       data = context.merge(tags:)
+#     #
+#     #       if request_info
+#     #         data[:path] = request_info[:env]["PATH_INFO"]
+#     #         MyLoggingSDK.info("Request completed", data)
+#     #       else
+#     #         MyLoggingSDK.public_send(severity, message, data)
+#     #       end
+#     #     end
+#     #   end
+#     def call(severity:, tags:, context:, message:, request_info:)
+#     end
+#   end