utopia 2.32.0 → 3.0.0

data/lib/utopia/controller/rewrite.rb

@@ -15,12 +15,19 @@ module Utopia
 		# 		@user = User.find(@id)
 		# 	end
 		module Rewrite
+			# Extend a controller class with path-rewrite rules.
+			# @parameter base [Class] The controller class.
+			# @returns [Class] The extended controller class.
 			def self.prepended(base)
 				base.extend(ClassMethods)
 			end
 			
 			# A abstract rule which can match against a request path.
 			class Rule
+				# Copy named regular-expression captures into context instance variables.
+				# @parameter match_data [MatchData] The regular expression match.
+				# @parameter context [Object] The context.
+				# @returns [Array(String)] The capture names.
 				def apply_match_to_context(match_data, context)
 					match_data.names.each do |name|
 						context.instance_variable_set("@#{name}", match_data[name])
@@ -30,11 +37,16 @@ module Utopia
 			
 			# A rule which extracts a prefix pattern from the request path.
 			class ExtractPrefixRule < Rule
+				# Initialize a typed prefix-extraction rule.
+				# @parameter patterns [Hash] The path rewrite patterns.
+				# @parameter block [Proc] The block.
 				def initialize(patterns, block)
 					@matcher = Path::Matcher.new(patterns)
 					@block = block
 				end
 				
+				# Freeze this object and its internal state.
+				# @returns [self] This object.
 				def freeze
 					@matcher.freeze
 					@block.freeze
@@ -42,6 +54,11 @@ module Utopia
 					super
 				end
 				
+				# Apply this prefix rule and execute its callback when it matches.
+				# @parameter context [Object] The context.
+				# @parameter request [Utopia::Request] The request.
+				# @parameter path [Utopia::Path | String] The path.
+				# @returns [Path] The unmatched suffix, or the original path when the rule does not match.
 				def apply(context, request, path)
 					if match_data = @matcher.match(path)
 						apply_match_to_context(match_data, context)
@@ -59,16 +76,26 @@ module Utopia
 			
 			# Rewrite a request path based on a set of defined rules.
 			class Rewriter
+				# Initialize an empty rewrite rule sequence.
 				def initialize
 					@rules = []
 				end
 				
 				attr :rules
 				
+				# Add a rule that extracts a typed prefix from the request path.
+				# @parameter patterns [Hash] The path rewrite patterns.
+				# @yields {|request, path, match| ...} The request, original path, and match data when the rule matches.
+				# @returns [ExtractPrefixRule] The added rule.
 				def extract_prefix(**patterns, &block)
 					@rules << ExtractPrefixRule.new(patterns, block)
 				end
 				
+				# Apply every rewrite rule in order.
+				# @parameter context [Object] The context.
+				# @parameter request [Utopia::Request] The request.
+				# @parameter path [Utopia::Path | String] The path.
+				# @returns [Path] The rewritten path.
 				def apply(context, request, path)
 					@rules.each do |rule|
 						path = rule.apply(context, request, path)
@@ -77,6 +104,11 @@ module Utopia
 					return path
 				end
 				
+				# Rewrite a path's components in place.
+				# @parameter context [Object] The context.
+				# @parameter request [Utopia::Request] The request.
+				# @parameter path [Utopia::Path | String] The path.
+				# @returns [Array(String)] The rewritten components.
 				def call(context, request, path)
 					path.components = apply(context, request, path).components
 				end
@@ -84,10 +116,17 @@ module Utopia
 			
 			# Exposed to the controller class.
 			module ClassMethods
+				# Return this controller's path rewriter.
+				# @returns [Rewriter] The path rewriter.
 				def rewrite
 					@rewriter ||= Rewriter.new
 				end
 				
+				# Apply configured rewrite rules to the request path.
+				# @parameter controller [Utopia::Controller::Base] The controller instance.
+				# @parameter request [Utopia::Request] The request.
+				# @parameter path [Utopia::Path | String] The path.
+				# @returns [Array(String) | Nil] The rewritten components, or `nil` when no rewriter is configured.
 				def rewrite_request(controller, request, path)
 					if @rewriter
 						@rewriter.call(controller, request, path)

data/lib/utopia/controller/variables.rb

@@ -3,20 +3,24 @@
 # Released under the MIT License.
 # Copyright, 2014-2025, by Samuel Williams.
 
-require_relative "../middleware"
-
 module Utopia
 	module Controller
 		# Provides a stack-based instance variable lookup mechanism. It can flatten a stack of controllers into a single hash.
 		class Variables
+			# Initialize an empty controller stack.
 			def initialize
 				@controllers = []
 			end
 			
+			# Return the innermost controller.
+			# @returns [Controller::Base | Nil] The current controller.
 			def top
 				@controllers.last
 			end
 			
+			# Push a controller after copying variables from the previous controller.
+			# @parameter controller [Utopia::Controller::Base] The controller instance.
+			# @returns [self] This variables stack.
 			def << controller
 				if top = self.top
 					# This ensures that most variables will be at the top and controllers can naturally interactive with instance variables:
@@ -45,6 +49,8 @@ module Utopia
 				end
 			end
 			
+			# Convert the current controller's instance variables to attributes.
+			# @returns [Hash(Symbol, Object)] The current controller attributes.
 			def to_hash
 				attributes = {}
 				
@@ -59,13 +65,19 @@ module Utopia
 				return attributes
 			end
 			
+			# Fetch a variable from the innermost controller.
+			# @parameter key [String | Symbol] The lookup key.
+			# @returns [Object | Nil] The variable value, or `nil` when it is undefined.
 			def [] key
 				fetch("@#{key}".to_sym, nil)
 			end
 		end
 		
+		# Return the controller variables associated with the request.
+		# @parameter request [Utopia::Request] The application request.
+		# @returns [Variables | Nil] The current variables.
 		def self.[] request
-			request.env[VARIABLES_KEY]
+			request.variables
 		end
 	end
 end

data/lib/utopia/controller.rb

@@ -7,6 +7,8 @@ require_relative "controller/middleware"
 
 module Utopia
 	module Controller
+		# Construct controller middleware.
+		# @returns [Controller::Middleware] The controller middleware.
 		def self.new(...)
 			Middleware.new(...)
 		end

data/lib/utopia/exceptions/handler.rb

@@ -6,17 +6,23 @@
 
 require "console"
 
+require_relative "../middleware"
+require_relative "../request"
+require_relative "../response"
+
 module Utopia
 	module Exceptions
 		# A middleware which catches exceptions and performs an internal redirect.
-		class Handler
+		class Handler < Protocol::HTTP::Middleware
 			# @param location [String] Peform an internal redirect to this location when an exception is raised.
 			def initialize(app, location = "/errors/exception")
-				@app = app
+				super(app)
 				
 				@location = location
 			end
 			
+			# Freeze this object and its internal state.
+			# @returns [self] This object.
 			def freeze
 				return self if frozen?
 				
@@ -25,28 +31,31 @@ module Utopia
 				super
 			end
 			
-			def call(env)
+			# Convert application exceptions into internal-server-error responses.
+			# @parameter request [Utopia::Request] The request.
+			# @returns [Protocol::HTTP::Response] The application response or a generated error response.
+			def call(request)
 				begin
-					return @app.call(env)
+					return @delegate.call(request)
 				rescue Exception => exception
 					Console.warn(self, "An error occurred while processing the request.", error: exception)
 					
 					begin
 						# We do an internal redirection to the error location:
-						error_request = env.merge(
-							Rack::PATH_INFO => @location,
-							Rack::REQUEST_METHOD => Rack::GET,
-							"utopia.exception" => exception,
+						error_request = request.with(
+							method: "GET",
+							path: @location
 						)
+						error_request.exception = exception
 						
-						error_response = @app.call(error_request)
-						error_response[0] = 500
+						error_response = Response.wrap(@delegate.call(error_request))
+						error_response.status = 500
 						
 						return error_response
 					rescue Exception => exception
 						# If redirection fails, we also finish with a fatal error:
 						Console.error(self, "An error occurred while invoking the error handler.", error: exception)
-						return [500, {"content-type" => "text/plain"}, ["An error occurred while processing the request."]]
+						return Response[500, {"content-type" => "text/plain"}, ["An error occurred while processing the request."]]
 					end
 				end
 			end

data/lib/utopia/exceptions/mailer.rb

@@ -6,10 +6,14 @@
 require "net/smtp"
 require "mail"
 
+require_relative "../middleware"
+require_relative "../request"
+require_relative "handler"
+
 module Utopia
 	module Exceptions
-		# A middleware which catches all exceptions raised from the app it wraps and sends a useful email with the exception, stacktrace, and contents of the environment.
-		class Mailer
+		# A middleware which catches application exceptions and sends an email containing the exception, backtrace, request, and application state.
+		class Mailer < Protocol::HTTP::Middleware
 			# A basic local non-authenticated SMTP server.
 			LOCAL_SMTP = [:smtp, {
 				:address => "localhost",
@@ -24,9 +28,9 @@ module Utopia
 			# @param from [String] The from address for error reports.
 			# @param subject [String] The subject template which can access attributes defined by `#attributes_for`.
 			# @param delivery_method [Object] The delivery method as required by the mail gem.
-			# @param dump_environment [Boolean] Attach `env` as `environment.yaml` to the error report.
+			# @param dump_environment [Boolean] Attach request attributes as `attributes.yaml` to the error report.
 			def initialize(app, to: "postmaster", from: DEFAULT_FROM, subject: DEFAULT_SUBJECT, delivery_method: LOCAL_SMTP, dump_environment: false)
-				@app = app
+				super(app)
 				
 				@to = to
 				@from = from
@@ -35,6 +39,8 @@ module Utopia
 				@dump_environment = dump_environment
 			end
 			
+			# Freeze this object and its internal state.
+			# @returns [self] This object.
 			def freeze
 				return self if frozen?
 				
@@ -47,11 +53,15 @@ module Utopia
 				super
 			end
 			
-			def call(env)
+			# Report application exceptions by email before returning an error response.
+			# @parameter request [Utopia::Request] The request.
+			# @returns [Protocol::HTTP::Response] The application response or a generated error response.
+			def call(request)
 				begin
-					return @app.call(env)
+					return @delegate.call(request)
 				rescue => exception
-					send_notification exception, env
+					request.exception = exception
+					send_notification exception, request
 					
 					raise
 				end
@@ -59,28 +69,19 @@ module Utopia
 			
 			private
 			
-			REQUEST_KEYS = [
+			REQUEST_ATTRIBUTES = [
+				:method,
+				:scheme,
+				:authority,
+				:protocol,
+				:version,
 				:ip,
 				:referrer,
 				:path,
+				:request_path,
 				:user_agent,
 			]
 			
-			ENV_KEYS = [
-				"PATH_INFO",
-				"REQUEST_METHOD",
-				"REQUEST_PATH",
-				"REQUEST_URI",
-				"SCRIPT_NAME",
-				"QUERY_STRING",
-				"SERVER_PROTOCOL",
-				"SERVER_NAME",
-				"SERVER_PORT",
-				"REMOTE_ADDR",
-				"CONTENT_TYPE",
-				"CONTENT_LENGTH",
-			]
-			
 			def generate_backtrace(io, exception, prefix: "Exception")
 				io.puts "#{prefix} #{exception.class.name}: #{exception.to_s}"
 				
@@ -95,39 +96,33 @@ module Utopia
 				end
 			end
 			
-			def generate_body(exception, env)
+			def generate_body(exception, request)
 				io = StringIO.new
 				
-				# Dump out useful rack environment variables:
-				request = Rack::Request.new(env)
+				io.puts "#{request.method} #{request.url}"
 				
-				io.puts "#{request.request_method} #{request.url}"
-				
-				# TODO embed `rack.input` if it's textual?
+				# TODO embed the request body if it's textual?
 				# TODO dump and embed `utopia.variables`?
 				
 				io.puts
 				
-				REQUEST_KEYS.each do |key|
+				REQUEST_ATTRIBUTES.each do |key|
 					value = request.send(key)
 					io.puts "request.#{key}: #{value.inspect}"
 				end
 				
-				request.params.each do |key, value|
-					io.puts "request.params.#{key}: #{value.inspect}"
+				request.query_parameters.each do |key, value|
+					io.puts "request.query_parameters.#{key}: #{value.inspect}"
 				end
 				
 				io.puts
 				
-				ENV_KEYS.each do |key|
-					value = env[key]
-					io.puts "env[#{key.inspect}]: #{value.inspect}"
+				request.headers.each do |key, value|
+					io.puts "header[#{key.inspect}]: #{value.inspect}"
 				end
 				
-				io.puts
-				
-				env.select{|key,_| key.start_with? "HTTP_"}.each do |key, value|
-					io.puts "#{key}: #{value.inspect}"
+				self.current_state(request).each do |key, value|
+					io.puts "state.#{key}: #{value.inspect}"
 				end
 				
 				io.puts
@@ -137,7 +132,7 @@ module Utopia
 				return io.string
 			end
 			
-			def attributes_for(exception, env)
+			def attributes_for(exception, request)
 				{
 					exception: exception.class.name,
 					pid: $$,
@@ -145,29 +140,29 @@ module Utopia
 				}
 			end
 			
-			def generate_mail(exception, env)
+			def generate_mail(exception, request)
 				mail = Mail.new(
 					:from => @from,
 					:to => @to,
-					:subject => @subject % attributes_for(exception, env)
+					:subject => @subject % attributes_for(exception, request)
 				)
 				
 				mail.text_part = Mail::Part.new
-				mail.text_part.body = generate_body(exception, env)
+				mail.text_part.body = generate_body(exception, request)
 				
-				if body = extract_body(env) and body.size > 0
+				if body = extract_body(request) and body.size > 0
 					mail.attachments["body.bin"] = body
 				end
 				
 				if @dump_environment
-					mail.attachments["environment.yaml"] = YAML.dump(env)
+					mail.attachments["state.yaml"] = YAML.dump(self.current_state(request))
 				end
 				
 				return mail
 			end
 			
-			def send_notification(exception, env)
-				mail = generate_mail(exception, env)
+			def send_notification(exception, request)
+				mail = generate_mail(exception, request)
 				
 				mail.delivery_method(*@delivery_method) if @delivery_method
 				
@@ -177,10 +172,20 @@ module Utopia
 				$stderr.puts mail_exception.backtrace
 			end
 			
-			def extract_body(env)
-				if io = env["rack.input"]
-					io.rewind if io.respond_to?(:rewind)
-					io.read
+			def current_state(request)
+				{
+					session: request.session,
+					variables: request.variables,
+					localization: request.localization,
+					exception: request.exception,
+				}
+			end
+			
+			def extract_body(request)
+				body = request.body
+				
+				if body&.rewindable? && body.rewind
+					return body.join
 				end
 			end
 		end

data/lib/utopia/extensions/array_split.rb

@@ -4,8 +4,14 @@
 # Copyright, 2009-2025, by Samuel Williams.
 
 module Utopia
+	# @namespace
 	module Extensions
+		# Adds splitting helpers to arrays.
 		module ArraySplit
+			# Split the array around the first element matching the arguments or block.
+			# @parameter arguments [Array] The arguments accepted by {Array#index}.
+			# @yields {|element| ...} Each element until the block matches.
+			# @returns [Array(Array, Object, Array)] The elements before the match, the matching element, and the elements after it; the middle value is `nil` when no element matches.
 			def split_at(*arguments, &block)
 				if middle = index(*arguments, &block)
 					[self[0...middle], self[middle], self[middle+1..-1]]

data/lib/utopia/extensions/date_comparisons.rb

@@ -9,6 +9,9 @@ module Utopia
 	module Extensions
 		# Provides comparison operator extensions.
 		module TimeDateComparison
+			# Compare a time with a date-like or otherwise comparable value.
+			# @parameter other [Object] The object to compare.
+			# @returns [Integer | Nil] The comparison result.
 			def <=>(other)
 				if Date === other or DateTime === other
 					self.to_datetime <=> other
@@ -22,6 +25,9 @@ module Utopia
 		
 		# Provides comparison operator extensions.
 		module DateTimeComparison
+			# Compare a date with a time or otherwise comparable value.
+			# @parameter other [Object] The object to compare.
+			# @returns [Integer | Nil] The comparison result.
 			def <=>(other)
 				if Time === other
 					self.to_datetime <=> other.to_datetime

data/lib/utopia/http.rb

@@ -1,18 +1,13 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2010-2025, by Samuel Williams.
+# Copyright, 2010-2026, by Samuel Williams.
 
-require "rack"
-
-require "http/accept"
+require "protocol/http/status"
 
 module Utopia
 	# HTTP protocol implementation.
 	module HTTP
-		# Pull in {::HTTP::Accept} for parsing.
-		Accept = ::HTTP::Accept
-		
 		# A list of commonly used HTTP status codes.
 		# For help choosing the right status code, see http://racksburg.com/choosing-an-http-status-code/
 		STATUS_CODES = {
@@ -38,47 +33,16 @@ module Utopia
 			:unavailable => 503
 		}
 		
-		# A list of human readable descriptions for a given status code.
-		# For a more detailed description, see https://en.wikipedia.org/wiki/List_of_HTTP_status_codes
-		STATUS_DESCRIPTIONS = {
-			200 => "OK".freeze,
-			201 => "Created".freeze,
-			202 => "Accepted".freeze,
-			203 => "Non-Authoritive Information".freeze,
-			204 => "No Content".freeze,
-			205 => "Reset Content".freeze,
-			206 => "Partial Content".freeze,
-			300 => "Multiple Choices".freeze,
-			301 => "Moved Permanently".freeze,
-			302 => "Found".freeze,
-			303 => "See Other".freeze,
-			304 => "Not Modified".freeze,
-			305 => "Use Proxy".freeze,
-			307 => "Temporary Redirect".freeze,
-			308 => "Permanent Redirect".freeze,
-			400 => "Bad Request".freeze,
-			401 => "Permission Denied".freeze,
-			402 => "Payment Required".freeze,
-			403 => "Access Forbidden".freeze,
-			404 => "Resource Not Found".freeze,
-			405 => "Unsupported Method".freeze,
-			406 => "Not Acceptable".freeze,
-			408 => "Request Timeout".freeze,
-			409 => "Request Conflict".freeze,
-			410 => "Resource Removed".freeze,
-			416 => "Byte range unsatisfiable".freeze,
-			422 => "Unprocessible Entity".freeze,
-			500 => "Internal Server Error".freeze,
-			501 => "Not Implemented".freeze,
-			503 => "Service Unavailable".freeze
-		}.merge(Rack::Utils::HTTP_STATUS_CODES)
-		
 		CONTENT_TYPE = "content-type".freeze
 		LOCATION = "location".freeze
 		CACHE_CONTROL = "cache-control".freeze
 		
 		# A small HTTP status wrapper that verifies the status code within a given range.
 		class Status
+			# Initialize a validated HTTP status.
+			# @parameter code [Integer | Symbol] The numeric status or a key from {STATUS_CODES}.
+			# @parameter valid_range [Range] The accepted numeric status range.
+			# @raises [ArgumentError] If the resolved status is outside `valid_range`.
 			def initialize(code, valid_range = 100...600)
 				if code.is_a? Symbol
 					code = STATUS_CODES[code]
@@ -91,17 +55,16 @@ module Utopia
 				@code = code
 			end
 			
+			# Convert this value to an integer.
+			# @returns [Integer] The numeric status code.
 			def to_i
 				@code
 			end
 			
+			# Convert this object to a string.
+			# @returns [String] The resulting string.
 			def to_s
-				STATUS_DESCRIPTIONS[@code] || @code.to_s
-			end
-			
-			# Allow to be used for rack body:
-			def each
-				yield to_s
+				return Protocol::HTTP::Status.description(@code) || @code.to_s
 			end
 		end
 	end

data/lib/utopia/import_map.rb

@@ -76,6 +76,11 @@ module Utopia
 		# 		end
 		# 	end
 		class Builder
+			# Configure an import map using a scoped builder.
+			# @parameter import_map [Utopia::ImportMap] The import map to render.
+			# @parameter options [Hash] The options.
+			# @yields {|builder| ...} The builder, when the block accepts an argument; otherwise the block is evaluated in the builder's context.
+			# @returns [Builder] The configured builder.
 			def self.build(import_map, **options, &block)
 				builder = self.new(import_map, **options)
 				
@@ -88,6 +93,9 @@ module Utopia
 				return builder
 			end
 			
+			# Initialize a scoped builder for an import map.
+			# @parameter import_map [Utopia::ImportMap] The import map to render.
+			# @parameter base [Object] The base.
 			def initialize(import_map, base: nil)
 				@import_map = import_map
 				@base = Protocol::URL[base]
@@ -100,7 +108,7 @@ module Utopia
 			#
 			# @parameter specifier [String] The module specifier (e.g., "react", "@myapp/utils").
 			# @parameter value [String] The URL or path to resolve to.
-			# @parameter integrity [String, nil] Optional subresource integrity hash.
+			# @parameter integrity [String | Nil] Optional subresource integrity hash.
 			# @returns [Builder] Self for method chaining.
 			#
 			# @example With base URL.
@@ -170,7 +178,7 @@ module Utopia
 		# The builder supports both block parameter and instance_eval styles.
 		# The returned import map is frozen to prevent accidental mutation.
 		#
-		# @parameter base [String, nil] The base URI for resolving relative paths.
+		# @parameter base [String | Nil] The base URI for resolving relative paths.
 		# @yields {|builder| ...} If a block is given.
 		# 	@parameter builder [Builder] The import map builder, if the block takes an argument.
 		# @returns [ImportMap] A frozen import map instance.
@@ -199,7 +207,7 @@ module Utopia
 		# @parameter imports [Hash] The imports mapping.
 		# @parameter integrity [Hash] Integrity hashes for imports.
 		# @parameter scopes [Hash] Scoped import mappings.
-		# @parameter base [String, Protocol::URL, nil] The base URI for resolving relative paths.
+		# @parameter base [String | Protocol::URL | Nil] The base URI for resolving relative paths.
 		def initialize(imports = {}, integrity = {}, scopes = {}, base: nil)
 			@imports = imports
 			@integrity = integrity
@@ -216,14 +224,14 @@ module Utopia
 		# @attribute [Hash(String, Hash)] Scoped import mappings.
 		attr :scopes
 		
-		# @attribute [Protocol::URL::Absolute | Protocol::URL::Relative | nil] The parsed base URL for efficient resolution.
+		# @attribute [Protocol::URL::Absolute | Protocol::URL::Relative | Nil] The parsed base URL for efficient resolution.
 		attr :base
 		
 		# Add an import mapping.
 		#
 		# @parameter specifier [String] The import specifier (e.g., "react", "@myapp/utils").
 		# @parameter value [String] The URL or path to resolve to.
-		# @parameter integrity [String, nil] Optional subresource integrity hash for the resource.
+		# @parameter integrity [String | Nil] Optional subresource integrity hash for the resource.
 		# @returns [ImportMap] Self for method chaining.
 		def import(specifier, value, integrity: nil)
 			@imports[specifier] = value
@@ -249,7 +257,7 @@ module Utopia
 		# Create a new import map with paths relative to the given page path.
 		# This is useful for creating page-specific import maps from a global one.
 		#
-		# @parameter path [String] The absolute page path to make imports relative to.
+		# @parameter path [String | Protocol::URL::Path] The absolute page path to make imports relative to.
 		# @returns [ImportMap] A new import map with a relative base.
 		#
 		# @example Creating page-specific import maps.
@@ -262,8 +270,8 @@ module Utopia
 		def relative_to(path)
 			if @base
 				# Calculate the relative path from the page to the base
-				relative_base = Protocol::URL::Path.relative(@base.path, path)
-				resolved_base = Protocol::URL[relative_base]
+				relative_path = @base.path.relative(path)
+				resolved_base = Protocol::URL::Relative.new(relative_path)
 			else
 				resolved_base = nil
 			end
@@ -276,8 +284,8 @@ module Utopia
 		# Resolve a single import value considering base context.
 		#
 		# @parameter value [String] The import URL or path value.
-		# @parameter base [Protocol::URL, nil] The base URL context for resolving relative paths.
-		# @returns [Protocol::URL, String] The resolved URL object or original string.
+		# @parameter base [Protocol::URL | Nil] The base URL context for resolving relative paths.
+		# @returns [Protocol::URL | String] The resolved URL object or original string.
 		private def resolve_value(value, base)
 			if base
 				base + Protocol::URL[value]
@@ -289,7 +297,7 @@ module Utopia
 		# Resolve a hash of imports with the given base.
 		#
 		# @parameter imports [Hash] The imports hash to resolve.
-		# @parameter base [Protocol::URL, nil] The base URL context.
+		# @parameter base [Protocol::URL | Nil] The base URL context.
 		# @returns [Hash] The resolved imports with string values.
 		private def resolve_imports(imports, base)
 			result = {}