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.

Defined Under Namespace

Classes: Cable, Deferred, LogContext, LogTags, Middleware, MiddlewareRegistry, OpenAPI, PublicFileServer, Server, Session, Telemetry

General Configuration collapse

Middleware Configuration collapse

Server Configuration collapse

Static File Server collapse

Cable Configuration collapse

OpenAPI Configuration collapse

Deferred Configuration collapse

Logging Context and Tags Configuration collapse

Telemetry Configuration collapse

Session Configuration 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


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

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

#cable ⇒ Rage::Configuration::Cable

Allows configuring Cable settings.

Returns:



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

def cable
  @cable ||= Cable.new
end

#deferred ⇒ Rage::Configuration::Deferred

Allows configuring Deferred settings.

Returns:



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

def deferred
  @deferred ||= Deferred.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>) 


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

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)



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

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:



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

def log_context
  @log_context ||= LogContext.new
end

#log_formatter ⇒ #call?

Returns the log formatter used by Rage.

Returns:

  • (#call, nil) 


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

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) 


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

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) 


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

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



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

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:



247
248
249
 
# File 'lib/rage/configuration.rb', line 247

def log_tags
  @log_tags ||= LogTags.new
end

#logger ⇒ Rage::Logger?

Returns the logger used by Rage.

Returns:



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

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


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

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:



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

def middleware
  @middleware ||= Middleware.new
end

#openapi ⇒ Rage::Configuration::OpenAPI

Allows configuring OpenAPI settings.

Returns:



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

def openapi
  @openapi ||= OpenAPI.new
end

#public_file_server ⇒ Rage::Configuration::PublicFileServer

Allows configuring the static file server used by Rage.

Returns:



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

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



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

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

#secret_key_base ⇒ String?

Returns the secret key base used for encrypting cookies.

Returns:

  • (String, nil) 


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

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



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

def secret_key_base=(key)
  @secret_key_base = key
end

#server ⇒ Rage::Configuration::Server

Allows configuring the built-in Rage server.

Returns:



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

def server
  @server ||= Server.new
end

#session ⇒ Rage::Configuration::Session

Allows configuring session settings.

Returns:



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

def session
  @session ||= Session.new
end

#telemetry ⇒ Rage::Configuration::Telemetry

Allows configuring telemetry settings.

Returns:



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

def telemetry
  @telemetry ||= Telemetry.new
end