utopia 2.32.0 → 3.0.0

data/lib/utopia/redirection/request_failure.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+module Utopia
+	module Redirection
+		# An error handler fails to redirect to a valid page.
+		class RequestFailure < StandardError
+			# Describe a failed attempt to render an error document.
+			# @parameter resource_path [Object] The resource path.
+			# @parameter resource_status [Object] The resource status.
+			# @parameter error_path [Object] The error path.
+			# @parameter error_status [Object] The error status.
+			def initialize(resource_path, resource_status, error_path, error_status)
+				@resource_path = resource_path
+				@resource_status = resource_status
+				
+				@error_path = error_path
+				@error_status = error_status
+				
+				super "Requested resource #{@resource_path} resulted in a #{@resource_status} error. Requested error handler #{@error_path} resulted in a #{@error_status} error."
+			end
+		end
+	end
+end

data/lib/utopia/redirection/rewrite.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require_relative "client_redirect"
+
+module Utopia
+	module Redirection
+		# Rewrite requests that match the given pattern to a single destination.
+		class Rewrite < ClientRedirect
+			# Initialize exact-path redirections.
+			# @parameter app [Interface(:call)] The downstream application.
+			# @parameter patterns [Hash] The path rewrite patterns.
+			# @parameter status [Integer] The status.
+			def initialize(app, patterns, status: 301)
+				@patterns = patterns
+				
+				super(app, status: status)
+			end
+			
+			# Freeze this object and its internal state.
+			# @returns [self] This object.
+			def freeze
+				return self if frozen?
+				
+				@patterns.freeze
+				
+				return super
+			end
+			
+			# Redirect a path found in the rewrite map.
+			# @parameter path [String] The normalized request path.
+			# @returns [Protocol::HTTP::Response | Nil] The redirect response when the path is mapped.
+			def [] path
+				if location = @patterns[path]
+					return redirect(location)
+				end
+			end
+		end
+	end
+end

data/lib/utopia/redirection.rb

@@ -1,169 +1,11 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2009-2025, by Samuel Williams.
+# Copyright, 2009-2026, by Samuel Williams.
 
-require_relative "middleware"
-
-module Utopia
-	# A middleware which assists with redirecting from one path to another.
-	module Redirection
-		# An error handler fails to redirect to a valid page.
-		class RequestFailure < StandardError
-			def initialize(resource_path, resource_status, error_path, error_status)
-				@resource_path = resource_path
-				@resource_status = resource_status
-				
-				@error_path = error_path
-				@error_status = error_status
-				
-				super "Requested resource #{@resource_path} resulted in a #{@resource_status} error. Requested error handler #{@error_path} resulted in a #{@error_status} error."
-			end
-		end
-		
-		# A middleware which performs internal redirects based on error status codes.
-		class Errors
-			# @param codes [Hash<Integer,String>] The redirection path for a given error code.
-			def initialize(app, codes = {})
-				@app = app
-				@codes = codes
-			end
-			
-			def freeze
-				return self if frozen?
-				
-				@codes.freeze
-				
-				super
-			end
-			
-			def unhandled_error?(response)
-				response[0] >= 400 && response[1].empty?
-			end
-			
-			def call(env)
-				response = @app.call(env)
-				
-				if unhandled_error?(response) && location = @codes[response[0]]
-					error_request = env.merge(Rack::PATH_INFO => location, Rack::REQUEST_METHOD => Rack::GET)
-					error_response = @app.call(error_request)
-					
-					if error_response[0] >= 400
-						raise RequestFailure.new(env[Rack::PATH_INFO], response[0], location, error_response[0])
-					else
-						# Feed the error code back with the error document:
-						error_response[0] = response[0]
-						return error_response
-					end
-				else
-					return response
-				end
-			end
-		end
-		
-		# We cache 301 redirects for 24 hours.
-		DEFAULT_MAX_AGE = 3600*24
-		
-		# A basic client-side redirect.
-		class ClientRedirect
-			def initialize(app, status: 307, max_age: DEFAULT_MAX_AGE)
-				@app = app
-				@status = status
-				@max_age = max_age
-			end
-			
-			def freeze
-				return self if frozen?
-				
-				@status.freeze
-				@max_age.freeze
-				
-				super
-			end
-			
-			attr :status
-			attr :max_age
-			
-			def cache_control
-				# http://jacquesmattheij.com/301-redirects-a-dangerous-one-way-street
-				"max-age=#{self.max_age}"
-			end
-			
-			def headers(location)
-				{HTTP::LOCATION => location, HTTP::CACHE_CONTROL => self.cache_control}
-			end
-			
-			def redirect(location)
-				return [self.status, self.headers(location), []]
-			end
-			
-			def [] path
-				false
-			end
-			
-			def call(env)
-				path = env[Rack::PATH_INFO]
-				
-				if redirection = self[path]
-					return redirection
-				end
-				
-				return @app.call(env)
-			end
-		end
-		
-		# Redirect urls that end with a `/`, e.g. directories.
-		class DirectoryIndex < ClientRedirect
-			def initialize(app, index: "index")
-				@app = app
-				@index = index
-				
-				super(app)
-			end
-			
-			def [] path
-				if path.end_with?("/")
-					return redirect(path + @index)
-				end
-			end
-		end
-		
-		# Rewrite requests that match the given pattern to a single destination.
-		class Rewrite < ClientRedirect
-			def initialize(app, patterns, status: 301)
-				@patterns = patterns
-				
-				super(app, status: status)
-			end
-			
-			def [] path
-				if location = @patterns[path]
-					return redirect(location)
-				end
-			end
-		end
-		
-		# Rewrite requests that match the given pattern to a new prefix.
-		class Moved < ClientRedirect
-			def initialize(app, pattern, prefix, status: 301, flatten: false)
-				@app = app
-				
-				@pattern = pattern
-				@prefix = prefix
-				@flatten = flatten
-				
-				super(app, status: status)
-			end
-			
-			def [] path
-				if path.start_with?(@pattern)
-					if @flatten
-						return redirect(@prefix)
-					else
-						return redirect(path.sub(@pattern, @prefix))
-					end
-				end
-			end
-		end
-	end
-end
+require_relative "redirection/request_failure"
+require_relative "redirection/errors"
+require_relative "redirection/client_redirect"
+require_relative "redirection/directory_index"
+require_relative "redirection/rewrite"
+require_relative "redirection/moved"

data/lib/utopia/request.rb

@@ -0,0 +1,202 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "stringio"
+require "protocol/http/request"
+require "protocol/url"
+require "protocol/url/form_data/parser"
+
+require_relative "path"
+
+module Utopia
+	# Utopia's application-facing request wrapper.
+	#
+	# Protocol request methods are delegated to the underlying request; parsing
+	# and application conveniences live here rather than on protocol-http itself.
+	class Request
+		# Build a Utopia request from the given protocol request arguments.
+		def self.[](*arguments)
+			self.new(Protocol::HTTP::Request[*arguments])
+		end
+		
+		# Initialize the request.
+		# @parameter delegate [Protocol::HTTP::Request] The underlying protocol request.
+		def initialize(delegate)
+			@delegate = delegate
+			
+			@url = nil
+			@session = nil
+			@variables = nil
+			@localization = nil
+			@exception = nil
+			
+			@query_parameters = nil
+			@cookies = nil
+		end
+		
+		# The underlying protocol request.
+		attr :delegate
+		
+		# The session associated with this request, if installed.
+		attr_accessor :session
+		
+		# The controller variables associated with this request, if installed.
+		attr_accessor :variables
+		
+		# The immutable localization preferences associated with this request, if installed.
+		attr_accessor :localization
+		
+		# The exception associated with this request, if any.
+		attr_accessor :exception
+		
+		private def parse_url
+			path, query = @delegate.path.split("?", 2)
+			
+			if scheme = @delegate.scheme and authority = @delegate.authority
+				Protocol::URL::Absolute.new(scheme, authority, path, query)
+			else
+				Protocol::URL::Relative.new(path, query)
+			end
+		end
+		
+		# The structured request URL.
+		# @returns [Protocol::URL::Absolute | Protocol::URL::Relative | Nil] The request URL.
+		def url
+			@url ||= self.parse_url.normalize!
+		end
+		
+		# @returns [Utopia::Path] The path components.
+		def path
+			Path.new(self.url.path.components(Protocol::URL::Encoding::System))
+		end
+		
+		# Assign the decoded application path while preserving the current query string.
+		# @parameter value [Utopia::Path | Protocol::URL::Path | String] The path.
+		def path= value
+			if value.is_a?(Protocol::URL::Path)
+				self.url.path = value
+			else
+				self.url.path = Path[value].to_url_path
+			end
+		end
+		
+		# Whether the request method is QUERY.
+		# @returns [Boolean] Whether the request method is QUERY.
+		def query?
+			@delegate.method == "QUERY"
+		end
+		
+		# Whether the request method is POST.
+		def post?
+			@delegate.method == "POST"
+		end
+		
+		# The normalized original request path, before any internal request rewrites.
+		# @returns [Utopia::Path] The decoded application path.
+		def request_path
+			path = @delegate.path.split("?", 2).first
+			path = Protocol::URL::Path[path].normalize.simplify
+			
+			return Path.new(path.components(Protocol::URL::Encoding::System))
+		end
+		
+		QUERY_PARSER = Protocol::URL::FormData::Parser.new
+		
+		private def parse_query_parameters(query)
+			if query
+				return QUERY_PARSER.parse(StringIO.new(query))
+			else
+				Hash.new
+			end
+		end
+		
+		# Decoded query arguments.
+		def query_parameters
+			@query_parameters ||= parse_query_parameters(self.url.query)
+		end
+		
+		private def parse_cookies(cookie_header)
+			cookies = {}
+			
+			return cookies unless cookie_header
+			
+			if cookie_header.respond_to?(:to_str)
+				cookie_header = cookie_header.to_str
+			else
+				cookie_header = cookie_header.to_s
+			end
+			
+			cookie_header.split(/;\s*/).each do |pair|
+				key, value = pair.split("=", 2)
+				cookies[key] = value || ""
+			end
+			
+			return cookies
+		end
+		
+		# Decoded request cookies.
+		def cookies
+			@cookies ||= parse_cookies(self.headers["cookie"])
+		end
+		
+		# The request user agent.
+		def user_agent
+			@delegate.headers["user-agent"]
+		end
+		
+		# The request referrer.
+		def referrer
+			@delegate.headers["referer"]
+		end
+		
+		# The remote peer IP address, if available.
+		def ip
+			@delegate.peer&.ip_address
+		end
+		
+		# Assign the structured request URL.
+		# @parameter url [Protocol::URL::Absolute | Protocol::URL::Relative | String | Nil] The request URL.
+		def url= url
+			@url = Protocol::URL[url]
+			@query_parameters = nil
+		end
+		
+		# Build a derived request with updated protocol fields.
+		def with(method: nil, path: self.path)
+			delegate = @delegate
+			
+			if method
+				delegate = @delegate.dup
+				delegate.method = method
+			end
+			
+			request = self.class.new(delegate)
+			request.session = @session
+			request.variables = @variables
+			request.localization = @localization
+			request.exception = @exception
+			request.path = path
+			
+			return request
+		end
+		
+		private
+		
+		# These inherited methods conflict with the protocol request interface, so remove them to allow delegation.
+		undef_method :method, :to_s
+		
+		def method_missing(name, ...)
+			if @delegate.respond_to?(name)
+				@delegate.public_send(name, ...)
+			else
+				super
+			end
+		end
+		
+		def respond_to_missing?(name, include_private = false)
+			@delegate.respond_to?(name) || super(name, include_private)
+		end
+	end
+end

data/lib/utopia/response.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "protocol/http/response"
+require "protocol/http/middleware"
+
+module Utopia
+	# Response helpers for Utopia applications.
+	#
+	# The canonical transport response remains {Protocol::HTTP::Response}. This
+	# module provides convenience constructors and normalization at the application
+	# boundary.
+	module Response
+		CONTENT_TYPE = "content-type".freeze
+		LOCATION = "location".freeze
+		
+		NotFound = Protocol::HTTP::Middleware::NotFound
+		
+		# Build a protocol HTTP response.
+		# @parameter status [Integer] The HTTP status code.
+		# @parameter headers [Hash | Protocol::HTTP::Headers | Nil] The response headers.
+		# @parameter body [Object] The response body.
+		# @parameter options [Hash] Additional options passed to `Protocol::HTTP::Response[]`.
+		# @returns [Protocol::HTTP::Response] The response object.
+		def self.[](status, headers = nil, body = nil, **options)
+			Protocol::HTTP::Response[status, headers, body, **options]
+		end
+		
+		# Normalize a response-like value to a protocol response.
+		# @parameter response [Object] The response-like value.
+		# @returns [Protocol::HTTP::Response] The normalized response.
+		# @raises [TypeError] If the response cannot be normalized.
+		def self.wrap(response)
+			return response if response.is_a?(Protocol::HTTP::Response)
+			
+			if response.respond_to?(:to_response)
+				response = response.to_response
+				return response if response.is_a?(Protocol::HTTP::Response)
+			end
+			
+			raise TypeError, "Expected a Protocol::HTTP::Response, but got #{response.class}!"
+		end
+		
+		# Build a redirect response.
+		# @parameter location [String] The redirect location.
+		# @parameter status [Integer] The redirect status code.
+		# @parameter headers [Hash] Additional response headers.
+		# @returns [Protocol::HTTP::Response] The redirect response.
+		def self.redirect(location, status = 302, headers = {})
+			self[status, headers.merge(LOCATION => location), []]
+		end
+		
+		# Build a plain text response.
+		# @parameter content [String] The response content.
+		# @parameter status [Integer] The response status.
+		# @parameter headers [Hash] Additional response headers.
+		# @returns [Protocol::HTTP::Response] The text response.
+		def self.text(content, status = 200, headers = {})
+			self[status, {CONTENT_TYPE => "text/plain; charset=utf-8"}.merge(headers), [content]]
+		end
+		
+		# Build an HTML response.
+		# @parameter content [String] The response content.
+		# @parameter status [Integer] The response status.
+		# @parameter headers [Hash] Additional response headers.
+		# @returns [Protocol::HTTP::Response] The HTML response.
+		def self.html(content, status = 200, headers = {})
+			self[status, {CONTENT_TYPE => "text/html; charset=utf-8"}.merge(headers), [content]]
+		end
+	end
+end

data/lib/utopia/session/lazy_hash.rb

@@ -1,12 +1,14 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2014-2022, by Samuel Williams.
+# Copyright, 2014-2026, by Samuel Williams.
 
 module Utopia
 	module Session
 		# A simple hash table which fetches it's values only when required.
 		class LazyHash
+			# Initialize a lazily loaded hash.
+			# @yields The block which loads the initial values.
 			def initialize(&block)
 				@changed = false
 				@values = nil
@@ -14,12 +16,21 @@ module Utopia
 				@loader = block
 			end
 			
+			# The loaded session values, if already loaded.
+			# @returns [Hash | Nil] The loaded values.
 			attr :values
 			
+			# Fetch a value by key, loading the hash if necessary.
+			# @parameter key [Object] The key.
+			# @returns [Object | Nil] The value.
 			def [] key
 				load![key]
 			end
 			
+			# Store a value by key.
+			# @parameter key [Object] The key.
+			# @parameter value [Object] The value.
+			# @returns [Object] The stored value.
 			def []= key, value
 				values = load!
 				
@@ -31,10 +42,16 @@ module Utopia
 				return value
 			end
 			
+			# Check whether the hash contains a key.
+			# @parameter key [Object] The key.
+			# @returns [Boolean] Whether the key exists.
 			def include?(key)
 				load!.include?(key)
 			end
 			
+			# Delete a value by key.
+			# @parameter key [Object] The key.
+			# @returns [Object | Nil] The deleted value.
 			def delete(key)
 				load!
 				
@@ -43,18 +60,27 @@ module Utopia
 				@values.delete(key)
 			end
 			
+			# Check whether any value has changed.
+			# @returns [Boolean] Whether the hash has changed.
 			def changed?
 				@changed
 			end
 			
+			# Load and return the underlying values.
+			# @returns [Hash] The loaded values.
 			def load!
 				@values ||= @loader.call
 			end
 			
+			# Check whether the underlying values have been loaded.
+			# @returns [Boolean] Whether the values are loaded.
 			def loaded?
 				!@values.nil?
 			end
 			
+			# Check whether the values should be persisted.
+			# @parameter timeout [Numeric | Nil] The maximum age before an update is required.
+			# @returns [Boolean] Whether an update is required.
 			def needs_update?(timeout = nil)
 				# If data has changed, we need update:
 				return true if @changed