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, 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

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

#blocking_operation_pool ⇒ Rage::Configuration::BlockingOperationPool

Allows configuring the thread pool for offloading native calls.

Returns:



288
289
290
 
# File 'lib/rage/configuration.rb', line 288

def blocking_operation_pool
  @blocking_operation_pool ||= BlockingOperationPool.new
end

#cable ⇒ Rage::Configuration::Cable

Allows configuring Cable settings.

Returns:



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

def cable
  @cable ||= Cable.new
end

#daemons ⇒ Rage::Configuration::Daemons

Allows configuring daemon settings.

Returns:



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

def daemons
  @daemons ||= Daemons.new
end

#deferred ⇒ Rage::Configuration::Deferred

Allows configuring Deferred settings.

Returns:



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

def deferred
  @deferred ||= Deferred.new
end

#error_reporters ⇒ Rage::Configuration::ErrorReporters

Allows configuring error reporters.

Returns:



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

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:



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

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_tags ⇒ Rage::Configuration::LogTags

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

Returns:



256
257
258
 
# File 'lib/rage/configuration.rb', line 256

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:



194
195
196
 
# File 'lib/rage/configuration.rb', line 194

def middleware
  @middleware ||= Middleware.new
end

#openapi ⇒ Rage::Configuration::OpenAPI

Allows configuring OpenAPI settings.

Returns:



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

def openapi
  @openapi ||= OpenAPI.new
end

#public_file_server ⇒ Rage::Configuration::PublicFileServer

Allows configuring the static file server used by Rage.

Returns:



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

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



180
181
182
183
184
185
186
187
188
 
# File 'lib/rage/configuration.rb', line 180

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:



280
281
282
 
# File 'lib/rage/configuration.rb', line 280

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:



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

def server
  @server ||= Server.new
end

#session ⇒ Rage::Configuration::Session

Allows configuring session settings.

Returns:



272
273
274
 
# File 'lib/rage/configuration.rb', line 272

def session
  @session ||= Session.new
end

#telemetry ⇒ Rage::Configuration::Telemetry

Allows configuring telemetry settings.

Returns:



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

def telemetry
  @telemetry ||= Telemetry.new
end