Class: Rage::Configuration

Inherits:
Object
  • Object
show all
Defined in:
lib/rage/configuration.rb

Overview

Configuration class for Rage framework.

Use Rage.configure to access and modify the configuration.

Example:

Rage.configure do
  config.log_level = :warn
  config.server.port = 8080
end

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" 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.
  • RAGE_ENABLE_NON_BLOCKING_TIMEOUT - enables the non-blocking timeout_after method on the fiber scheduler, which allows timeouts to work cooperatively with fiber-based concurrency.

Defined Under Namespace

Classes: BlockingOperationPool, Cable, CodeLoader, Daemons, Deferred, ErrorReporters, LogContext, LogTags, Middleware, MiddlewareRegistry, OpenAPI, PublicFileServer, Router, Server, Session, Telemetry

General Configuration collapse

Middleware Configuration collapse

Server Configuration collapse

Static File Server collapse

Cable Configuration collapse

Error Reporter Configuration collapse

OpenAPI Configuration collapse

Deferred Configuration collapse

Logging Context and Tags Configuration collapse

Telemetry Configuration collapse

Session Configuration collapse

Router Configuration collapse

Code Loader Configuration collapse

Blocking Operation Pool Configuration collapse

Daemons collapse

Instance Method Details

#after_initialize(&block) ⇒ Object

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.

Examples:

Rage.config.after_initialize do
  SUPER_USER = User.find_by!(super: true)
end


140
141
142
 
# File 'lib/rage/configuration.rb', line 140

def after_initialize(&block)
  push_hook(block, :after_initialize)
end

#after_reload(&block) ⇒ Object

Schedule a block of code to run after Rage has reloaded the application code in development. Use this to reset state or re-initialize dependencies that cache application-level constants.

Examples:

Rage.config.after_reload do
  MyCache.clear
end


149
150
151
 
# File 'lib/rage/configuration.rb', line 149

def after_reload(&block)
  push_hook(block, :after_reload)
end

#blocking_operation_pool ⇒ Rage::Configuration::BlockingOperationPool

Allows configuring the thread pool for offloading native calls.

Returns:



328
329
330
 
# File 'lib/rage/configuration.rb', line 328

def blocking_operation_pool
  @blocking_operation_pool ||= BlockingOperationPool.new
end

#cable ⇒ Rage::Configuration::Cable

Allows configuring Cable settings.

Returns:



227
228
229
 
# File 'lib/rage/configuration.rb', line 227

def cable
  @cable ||= Cable.new
end

#code_loader ⇒ Rage::Configuration::CodeLoader

Allows configuring code loader settings.

Returns:



320
321
322
 
# File 'lib/rage/configuration.rb', line 320

def code_loader
  @code_loader ||= CodeLoader.new
end

#daemons ⇒ Rage::Configuration::Daemons

Allows configuring daemon settings.

Returns:



336
337
338
 
# File 'lib/rage/configuration.rb', line 336

def daemons
  @daemons ||= Daemons.new
end

#deferred ⇒ Rage::Configuration::Deferred

Allows configuring Deferred settings.

Returns:



251
252
253
 
# File 'lib/rage/configuration.rb', line 251

def deferred
  @deferred ||= Deferred.new
end

#error_reporters ⇒ Rage::Configuration::ErrorReporters

Allows configuring error reporters.

Returns:



235
236
237
 
# File 'lib/rage/configuration.rb', line 235

def error_reporters
  @error_reporters ||= ErrorReporters.new
end

#fallback_secret_key_base ⇒ Array<String>

Returns the fallback secret key base(s) used for decrypting cookies encrypted with old secrets.

Returns:

  • (Array<String>) 


131
132
133
 
# File 'lib/rage/configuration.rb', line 131

def fallback_secret_key_base
  Array(@fallback_secret_key_base || ENV["FALLBACK_SECRET_KEY_BASE"])
end

#fallback_secret_key_base=(key) ⇒ Object

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.

Parameters:

  • key (String, Array<String>) —

    the fallback secret key base(s)



125
126
127
 
# File 'lib/rage/configuration.rb', line 125

def fallback_secret_key_base=(key)
  @fallback_secret_key_base = key
end

#log_context ⇒ Rage::Configuration::LogContext

Allows configuring custom log context objects that will be included in every log entry.

Returns:



259
260
261
 
# File 'lib/rage/configuration.rb', line 259

def log_context
  @log_context ||= LogContext.new
end

#log_formatter ⇒ #call?

Returns the log formatter used by Rage.

Returns:

  • (#call, nil) 


80
81
82
 
# File 'lib/rage/configuration.rb', line 80

def log_formatter
  @log_formatter
end

#log_formatter=(formatter) ⇒ Object

Set the log formatter used by Rage. Built in options include Rage::TextFormatter and Rage::JSONFormatter.

Examples:

config.log_formatter = proc do |severity, datetime, progname, msg|
  "[#{datetime}] #{severity} -- #{progname}: #{msg}\n"
end

Parameters:

  • formatter (#call) —

    a callable object that formats log messages

Raises:

  • (ArgumentError) 


92
93
94
95
 
# File 'lib/rage/configuration.rb', line 92

def log_formatter=(formatter)
  raise ArgumentError, "Custom log formatter should respond to `#call`" unless formatter.respond_to?(:call)
  @log_formatter = formatter
end

#log_level ⇒ Integer?

Returns the log level used by Rage.

Returns:

  • (Integer, nil) 


99
100
101
 
# File 'lib/rage/configuration.rb', line 99

def log_level
  @log_level
end

#log_level=(level) ⇒ Object

Set the log level used by Rage.

Examples:

config.log_level = :info

Parameters:

  • level (:debug, :info, :warn, :error, :fatal, :unknown, Integer) —

    the log level



107
108
109
 
# File 'lib/rage/configuration.rb', line 107

def log_level=(level)
  @log_level = level.is_a?(Symbol) ? Logger.const_get(level.to_s.upcase) : level
end

#log_redact_keys=(keys) ⇒ Object

Allows configuring case-insensitive partial matches for redacting structured log context keys. Matching keys will have their values replaced with "[REDACTED]" before the log entry is written.

Examples:

Redact common secrets from structured logs

Rage.configure do
  config.log_redact_keys = [:password, :token, :secret]
end

Parameters:

  • keys (String, Symbol, Array<String, Symbol>, nil) —

    one or more keys to redact



277
278
279
280
281
282
283
284
285
 
# File 'lib/rage/configuration.rb', line 277

def log_redact_keys=(keys)
  @log_redact_keys = Array(keys).filter_map { |key|
    if !key.is_a?(String) && !key.is_a?(Symbol)
      raise ArgumentError, "log redact keys have to be strings or symbols"
    elsif !key.empty?
      key.to_s
    end
  }.uniq
end

#log_tags ⇒ Rage::Configuration::LogTags

Allows configuring custom log tags that will be included in every log entry.

Returns:



265
266
267
 
# File 'lib/rage/configuration.rb', line 265

def log_tags
  @log_tags ||= LogTags.new
end

#logger ⇒ Rage::Logger?

Returns the logger used by Rage.

Returns:



40
41
42
 
# File 'lib/rage/configuration.rb', line 40

def logger
  @logger
end

#logger=(logger) ⇒ Object #logger=(callable) ⇒ Object #logger=(nil) ⇒ Object

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, but if you provide a custom object, it will be used internally by Rage.logger.

Overloads:

  • #logger=(logger) ⇒ Object

    Set a standard logger

    Examples:

    config.logger = Rage::Logger.new(STDOUT)

    Parameters:

    • logger (#debug, #info, #warn, #error, #fatal, #unknown)
  • #logger=(callable) ⇒ Object

    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.

    Examples:

    config.logger = proc do |severity:, tags:, context:, message:, request_info:|
  # Custom logging logic here
end

    Parameters:

  • #logger=(nil) ⇒ Object

    Disable logging

    Examples:

    config.logger = nil


66
67
68
69
70
71
72
73
74
75
76
 
# File 'lib/rage/configuration.rb', line 66

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

#middleware ⇒ Rage::Configuration::Middleware

Allows configuring the middleware stack used by Rage.

Returns:



203
204
205
 
# File 'lib/rage/configuration.rb', line 203

def middleware
  @middleware ||= Middleware.new
end

#openapi ⇒ Rage::Configuration::OpenAPI

Allows configuring OpenAPI settings.

Returns:



243
244
245
 
# File 'lib/rage/configuration.rb', line 243

def openapi
  @openapi ||= OpenAPI.new
end

#public_file_server ⇒ Rage::Configuration::PublicFileServer

Allows configuring the static file server used by Rage.

Returns:



219
220
221
 
# File 'lib/rage/configuration.rb', line 219

def public_file_server
  @public_file_server ||= PublicFileServer.new
end

#renderer(name, &block) ⇒ Object

Register a custom renderer that generates overloads render on all controllers. The block receives the object passed to render together with any additional keyword arguments. The code inside the block is executed in the context of the controller instance, so you can access all usual controller methods in it. The return value of the block is used as the response body.

Examples:

Register an ERB renderer

Rage.configure do
  config.renderer(:erb) do |path, trim_mode: nil|
    headers["content-type"] = "text/html"
    template = File.read("app/views/#{path}.html.erb")

    ERB.new(template, trim_mode:).result(binding)
  end
end

Use in a controller

class ReportsController < RageController::API
  def index
    render erb: "reports/index"
  end
end

Pass arguments

class ReportsController < RageController::API
  def index
    render erb: "reports/index", trim_mode: "%<>"
  end
end

Set response status

class ReportsController < RageController::API
  def index
    render erb: "reports/index", status: 202
  end
end

Parameters:

  • name (Symbol, String) —

    the name of the renderer

  • block (Proc) —

    the rendering logic. The block is executed in the controller's context and its return value becomes the response body

Raises:

  • (ArgumentError) —

    if no block is given or if a renderer with the same name is already registered



189
190
191
192
193
194
195
196
197
 
# File 'lib/rage/configuration.rb', line 189

def renderer(name, &block)
  @renderers ||= {}
  raise ArgumentError, "renderer requires a block" unless block_given?
  name = name.to_sym
  if @renderers.key?(name)
    raise ArgumentError, "a renderer named :#{name} is already registered"
  end
  @renderers[name] = RendererEntry.new(block)
end

#router ⇒ Rage::Configuration::Router

Allows configuring router settings.

Returns:



312
313
314
 
# File 'lib/rage/configuration.rb', line 312

def router
  @router ||= Router.new
end

#secret_key_base ⇒ String?

Returns the secret key base used for encrypting cookies.

Returns:

  • (String, nil) 


119
120
121
 
# File 'lib/rage/configuration.rb', line 119

def secret_key_base
  @secret_key_base || ENV["SECRET_KEY_BASE"]
end

#secret_key_base=(key) ⇒ Object

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.

Parameters:

  • key (String) —

    the secret key base



113
114
115
 
# File 'lib/rage/configuration.rb', line 113

def secret_key_base=(key)
  @secret_key_base = key
end

#server ⇒ Rage::Configuration::Server

Allows configuring the built-in Rage server.

Returns:



211
212
213
 
# File 'lib/rage/configuration.rb', line 211

def server
  @server ||= Server.new
end

#session ⇒ Rage::Configuration::Session

Allows configuring session settings.

Returns:



304
305
306
 
# File 'lib/rage/configuration.rb', line 304

def session
  @session ||= Session.new
end

#telemetry ⇒ Rage::Configuration::Telemetry

Allows configuring telemetry settings.

Returns:



296
297
298
 
# File 'lib/rage/configuration.rb', line 296

def telemetry
  @telemetry ||= Telemetry.new
end