utopia 2.32.0 → 3.0.0

data/lib/utopia/path.rb

@@ -3,6 +3,8 @@
 # Released under the MIT License.
 # Copyright, 2009-2025, by Samuel Williams.
 
+require "protocol/url/path"
+
 module Utopia
 	# Represents a path as an array of path components. Useful for efficient URL manipulation.
 	class Path
@@ -10,12 +12,16 @@ module Utopia
 		
 		SEPARATOR = "/"
 		
+		# Initialize a path from its individual components.
+		# @parameter components [Array(String)] The path components, including empty components that denote leading or trailing separators.
 		def initialize(components = [])
 			@components = components
 		end
 		
 		attr_accessor :components
 		
+		# Freeze this object and its internal state.
+		# @returns [self] This object.
 		def freeze
 			return self if frozen?
 			
@@ -24,20 +30,30 @@ module Utopia
 			super
 		end
 		
+		# Check whether this path has no components.
+		# @returns [Boolean] Whether the path has no components.
 		def empty?
 			@components.empty?
 		end
 		
+		# Construct the root path.
+		# @returns [Path] The root path.
 		def self.root
 			self.new([""])
 		end
 		
-		# Returns the length of the prefix which is shared by two strings.
+		# Compute the number of leading components shared by two sequences.
+		# @parameter a [Array] The first sequence.
+		# @parameter b [Array] The second sequence.
+		# @returns [Integer | Nil] The shared prefix length, or `nil` when every component in the shorter sequence matches.
 		def self.prefix_length(a, b)
 			[a.size, b.size].min.times{|i| return i if a[i] != b[i]}
 		end
 		
-		# Return the shortest relative path to get to path from root:
+		# Compute the shortest relative path from the containing directory of `root` to `path`.
+		# @parameter path [Path | String | Array] The destination path.
+		# @parameter root [Path | String | Array] The source path.
+		# @returns [Path] The shortest relative path.
 		def self.shortest_path(path, root)
 			path = self.create(path)
 			root = self.create(root).dirname
@@ -51,21 +67,32 @@ module Utopia
 			return self.create([".."] * up + path.components[i..-1])
 		end
 		
+		# Compute the shortest relative path from the containing directory of `root` to this path.
+		# @parameter root [Path | String | Array] The source path.
+		# @returns [Path] The shortest relative path.
 		def shortest_path(root)
 			self.class.shortest_path(self, root)
 		end
 		
-		# Converts '+' into whitespace and hex encoded characters into their equivalent characters.
+		# Decode URL-encoded path content, converting `+` to whitespace and percent-encoded bytes to their corresponding characters.
+		# @parameter string [String] The encoded content.
+		# @returns [String] The decoded content.
 		def self.unescape(string)
 			string.tr("+", " ").gsub(/((?:%[0-9a-fA-F]{2})+)/n) do
 				[$1.delete("%")].pack("H*")
 			end
 		end
 		
+		# Coerce the given value into a path.
+		# @parameter path [Utopia::Path | String] The path.
+		# @returns [Path | Nil] The coerced path.
 		def self.[] path
 			self.create(path)
 		end
 		
+		# Convert a path value into an array of components.
+		# @parameter path [Utopia::Path | String] The path.
+		# @returns [Array] The path components.
 		def self.split(path)
 			case path
 			when Path
@@ -79,19 +106,30 @@ module Utopia
 			end
 		end
 		
-		# This constructor takes a string and generates a relative path as efficiently as possible. This is a direct entry point for all controller invocations so it's designed to suit the requirements of that function.
+		# Construct a path from URL-encoded text. This is an optimized direct entry point used by controller invocations.
+		# @parameter string [String] The encoded path.
+		# @returns [Path] The decoded path.
 		def self.from_string(string)
 			self.new(unescape(string).split(SEPARATOR, -1))
 		end
 		
+		# Load a path from its serialized form.
+		# @parameter value [String | Nil] The serialized path.
+		# @returns [Path | Nil] The loaded path.
 		def self.load(value)
 			from_string(value) if value
 		end
 		
+		# Serialize a path.
+		# @parameter instance [Path | Nil] The path to serialize.
+		# @returns [String | Nil] The serialized path.
 		def self.dump(instance)
 			instance.to_s if instance
 		end
 		
+		# Coerce a value into a path.
+		# @parameter path [Path | Array | String | Object | Nil] The value to coerce.
+		# @returns [Path | Nil] The coerced path.
 		def self.create(path)
 			case path
 			when Path
@@ -107,22 +145,34 @@ module Utopia
 			end
 		end
 		
+		# Replace this path's components with a copy of another path's components.
+		# @parameter other_path [Path] The replacement path.
+		# @returns [Array(String)] The copied components.
 		def replace(other_path)
 			@components = other_path.components.dup
 		end
 		
+		# Check whether this collection includes the given value.
+		# @parameter arguments [Array] The arguments.
+		# @returns [Boolean] Whether any component matches the given argument.
 		def include?(*arguments)
 			@components.include?(*arguments)
 		end
 		
+		# Check whether this path denotes a directory.
+		# @returns [Boolean] Whether the path ends with a directory separator.
 		def directory?
 			return @components.last == ""
 		end
 		
+		# Check whether this path denotes a file.
+		# @returns [Boolean] Whether the path ends with a file component.
 		def file?
 			return @components.last != ""
 		end
 		
+		# Convert this path to a directory path.
+		# @returns [Path] A directory path.
 		def to_directory
 			if directory?
 				return self
@@ -131,14 +181,20 @@ module Utopia
 			end
 		end
 		
+		# Check whether this path is relative.
+		# @returns [Boolean] Whether the path is relative.
 		def relative?
 			@components.first != ""
 		end
 		
+		# Check whether this path is absolute.
+		# @returns [Boolean] Whether the path is absolute.
 		def absolute?
 			@components.first == ""
 		end
 		
+		# Convert this path to an absolute path.
+		# @returns [Path] An absolute path.
 		def to_absolute
 			if absolute?
 				return self
@@ -147,10 +203,14 @@ module Utopia
 			end
 		end
 		
+		# Remove the first component when this path is relative.
+		# @returns [String | Nil] The removed component, or `nil` when the path is absolute.
 		def to_relative!
 			@components.shift if relative?
 		end
 		
+		# Convert this object to a string.
+		# @returns [String] The resulting string.
 		def to_str
 			if @components == [""]
 				SEPARATOR
@@ -161,11 +221,28 @@ module Utopia
 		
 		alias to_s to_str
 		
+		# Encode this application path as a URL path.
+		# @returns [Protocol::URL::Path] The encoded URL path.
+		def to_url_path
+			# Preserve Utopia's compact representation of the absolute root:
+			if @components == [""]
+				return Protocol::URL::Path[SEPARATOR]
+			end
+			
+			return Protocol::URL::Path.for(
+				@components,
+				encoding: Protocol::URL::Encoding::System,
+			)
+		end
+		
+		# Convert this path to an array of components.
+		# @returns [Array] The resulting values.
 		def to_a
 			@components
 		end
 		
 		# @parameter other [Array(String)] The path components to append.
+		# @returns [Path] The joined and simplified path.
 		def join(other)
 			# Check whether other is an absolute path:
 			if other.first == ""
@@ -175,10 +252,16 @@ module Utopia
 			end
 		end
 		
+		# Resolve this path relative to a root path.
+		# @parameter root [Path] The root path.
+		# @returns [Path] The resolved path.
 		def expand(root)
 			root + self
 		end
 		
+		# Append path components and return the resulting path.
+		# @parameter other [Path | Array | String | Object] The value to append.
+		# @returns [Path] The joined and simplified path, or `other` when it is an absolute path.
 		def +(other)
 			if other.kind_of? Path
 				if other.absolute?
@@ -195,6 +278,9 @@ module Utopia
 			end
 		end
 		
+		# Prepend a path to this path.
+		# @parameter arguments [Array] The arguments accepted by {.create}.
+		# @returns [Path] The prefixed path.
 		def with_prefix(*arguments)
 			self.class.create(*arguments) + self
 		end
@@ -202,6 +288,8 @@ module Utopia
 		# Computes the difference of the path.
 		# /a/b/c - /a/b -> c
 		# a/b/c - a/b -> c
+		# @parameter other [Path] The prefix path to remove.
+		# @returns [Path] The remaining path.
 		def -(other)
 			i = 0
 			
@@ -214,6 +302,8 @@ module Utopia
 			return self.class.new(@components[i,@components.size])
 		end
 		
+		# Normalize current-directory, parent-directory, and repeated-separator components.
+		# @returns [Path] The normalized path.
 		def simplify
 			components = []
 			
@@ -245,7 +335,8 @@ module Utopia
 			return self.class.new(components)
 		end
 		
-		# Returns the first path component.
+		# Return the first path component, excluding the root marker.
+		# @returns [String | Nil] The first component.
 		def first
 			if absolute?
 				@components[1]
@@ -254,7 +345,8 @@ module Utopia
 			end
 		end
 		
-		# Returns the last path component.
+		# Return the last path component, excluding the root marker.
+		# @returns [String | Nil] The last component.
 		def last
 			if @components != [""]
 				@components.last
@@ -263,7 +355,8 @@ module Utopia
 		
 		alias last? file?
 		
-		# Pops the last path component.
+		# Remove the last path component without converting the root path to a relative path.
+		# @returns [String | Nil] The removed component.
 		def pop
 			# We don't want to convert an absolute path to a relative path.
 			if @components != [""]
@@ -271,30 +364,39 @@ module Utopia
 			end
 		end
 		
-		# @return [String] the last path component without any file extension.
+		# @returns [String] The last path component without its file extension.
 		def basename
 			basename, _ = @components.last.split(".", 2)
 			
 			return basename || ""
 		end
 		
-		# @return [String] the last path component's file extension.
+		# @returns [String | Nil] The last path component's file extension.
 		def extension
 			_, extension = @components.last.split(".", 2)
 			
 			return extension
 		end
 		
+		# Remove trailing path components.
+		# @parameter count [Integer] The number of components.
+		# @returns [Path] The containing path.
 		def dirname(count = 1)
 			path = self.class.new(@components[0...-count])
 			
 			return absolute? ? path.to_absolute : path
 		end
 		
+		# Format this path using a local filesystem separator.
+		# @parameter separator [String] The component separator.
+		# @returns [String] The local path.
 		def local_path(separator = File::SEPARATOR)
 			@components.join(separator)
 		end
 		
+		# Enumerate paths from the first component down to this path.
+		# @yields {|path| ...} Each successively longer path.
+		# @returns [Enumerator | Array] An enumerator when no block is given, otherwise the component array.
 		def descend(&block)
 			return to_enum(:descend) unless block_given?
 			
@@ -307,6 +409,9 @@ module Utopia
 			end
 		end
 		
+		# Enumerate paths from this path up to its first component.
+		# @yields {|path| ...} Each successively shorter path.
+		# @returns [Enumerator | Nil] An enumerator when no block is given.
 		def ascend(&block)
 			return to_enum(:ascend) unless block_given?
 			
@@ -319,6 +424,9 @@ module Utopia
 			end
 		end
 		
+		# Split this path around a component or component index.
+		# @parameter at [Integer | String] The component index or value at which to split.
+		# @returns [Array(Path, Path) | Nil] The paths before and after the matched component, or `nil` when it is not found.
 		def split(at)
 			if at.kind_of?(String)
 				at = @components.index(at)
@@ -331,22 +439,35 @@ module Utopia
 			end
 		end
 		
+		# Copy this path and its component array.
+		# @returns [Path] The copied path.
 		def dup
 			return Path.new(components.dup)
 		end
 		
+		# Compare this object with another object.
+		# @parameter other [Object] The object to compare.
+		# @returns [Integer | Nil] The comparison result.
 		def <=> other
 			@components <=> other.components
 		end
 		
+		# Check whether this object is equivalent to another object.
+		# @parameter other [Object] The object to compare.
+		# @returns [Boolean] Whether the paths have the same class and components.
 		def eql? other
 			self.class.eql?(other.class) and @components.eql?(other.components)
 		end
 		
+		# Compute the hash value for this object.
+		# @returns [Integer] The resulting integer.
 		def hash
 			@components.hash
 		end
 		
+		# Compare this object with another object.
+		# @parameter other [Object] The object to compare.
+		# @returns [Boolean] Whether the path is equivalent to the given string, array, or path.
 		def == other
 			return false unless other
 			
@@ -357,6 +478,9 @@ module Utopia
 			end
 		end
 		
+		# Check whether this path starts with the given path.
+		# @parameter other [Path] The possible prefix.
+		# @returns [Boolean] Whether this path starts with all components of `other`.
 		def start_with? other
 			other.components.each_with_index do |part, index|
 				return false if @components[index] != part
@@ -365,15 +489,24 @@ module Utopia
 			return true
 		end
 		
+		# Fetch one or more path components, excluding root and directory markers from indexing.
+		# @parameter index [Integer | Range] The component index or range.
+		# @returns [String | Array(String) | Nil] The selected component or components.
 		def [] index
 			return @components[component_offset(index)]
 		end
 		
-		# Replaces a named component, indexing as per 
+		# Replace one or more path components using the same root- and directory-marker-aware indexing as {#[]}.
+		# @parameter index [Integer | Range] The component index or range.
+		# @parameter value [String | Array(String)] The replacement component or components.
+		# @returns [String | Array(String)] The assigned value.
 		def []= index, value
 			return @components[component_offset(index)] = value
 		end
 		
+		# Delete a path component, excluding root and directory markers from indexing.
+		# @parameter index [Integer] The component index.
+		# @returns [String | Nil] The deleted component.
 		def delete_at(index)
 			@components.delete_at(component_offset(index))
 		end
@@ -400,6 +533,9 @@ module Utopia
 		end
 	end
 	
+	# Coerce a value into a {Path}.
+	# @parameter path [Utopia::Path | String] The path.
+	# @returns [Path | Nil] The coerced path.
 	def self.Path(path)
 		Path.create(path)
 	end

data/lib/utopia/redirection/client_redirect.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require_relative "../middleware"
+require_relative "../response"
+
+module Utopia
+	# A middleware which assists with redirecting from one path to another.
+	module Redirection
+		# We cache 301 redirects for 24 hours.
+		MAX_AGE = 3600*24
+		
+		# A basic client-side redirect.
+		class ClientRedirect < Protocol::HTTP::Middleware
+			# Initialize client-side redirection behavior.
+			# @parameter app [Interface(:call)] The downstream application.
+			# @parameter status [Integer] The status.
+			# @parameter max_age [Integer] The maximum cache age in seconds.
+			def initialize(app, status: 307, max_age: MAX_AGE)
+				super(app)
+				
+				@status = status
+				@max_age = max_age
+			end
+			
+			# Freeze this object and its internal state.
+			# @returns [self] This object.
+			def freeze
+				return self if frozen?
+				
+				@status.freeze
+				@max_age.freeze
+				
+				super
+			end
+			
+			attr :status
+			attr :max_age
+			
+			# Build the cache control header value.
+			# @returns [String] The cache-control value.
+			def cache_control
+				# http://jacquesmattheij.com/301-redirects-a-dangerous-one-way-street
+				"max-age=#{self.max_age}"
+			end
+			
+			# Build headers for a client redirect.
+			# @parameter location [String] The redirect location.
+			# @returns [Hash(String, String)] The redirect headers.
+			def make_headers(location)
+				{
+					HTTP::LOCATION => location,
+					HTTP::CACHE_CONTROL => self.cache_control
+				}
+			end
+			
+			# Build a redirect response for the given location.
+			# @parameter location [String] The redirect location.
+			# @returns [Protocol::HTTP::Response] The redirect response.
+			def redirect(location)
+				return Response[self.status, self.make_headers(location), []]
+			end
+			
+			# Resolve a normalized request path to a redirect response.
+			# @parameter path [String] The normalized request path.
+			# @returns [Protocol::HTTP::Response | false] The redirect response, or `false` by default.
+			def [] path
+				false
+			end
+			
+			# Redirect a normalized request path when it matches, otherwise invoke the application.
+			# @parameter request [Utopia::Request] The request.
+			# @returns [Protocol::HTTP::Response] The redirect or downstream response.
+			def call(request)
+				path = request.url.path.encoded
+				
+				if redirection = self[path]
+					return redirection
+				end
+				
+				return @delegate.call(request)
+			end
+		end
+	end
+end

data/lib/utopia/redirection/directory_index.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require_relative "client_redirect"
+
+module Utopia
+	module Redirection
+		# Redirect urls that end with a `/`, e.g. directories.
+		class DirectoryIndex < ClientRedirect
+			# Initialize directory-index redirection.
+			# @parameter app [Interface(:call)] The downstream application.
+			# @parameter index [Integer] The index.
+			def initialize(app, index: "index")
+				@index = index
+				
+				super(app)
+			end
+			
+			# Freeze this object and its internal state.
+			# @returns [self] This object.
+			def freeze
+				return self if frozen?
+				
+				@index.freeze
+				
+				return super
+			end
+			
+			# Redirect a directory path to its index path.
+			# @parameter path [String] The normalized request path.
+			# @returns [Protocol::HTTP::Response | Nil] The redirect response when the path ends with `/`.
+			def [] path
+				if path.end_with?("/")
+					return redirect(path + @index)
+				end
+			end
+		end
+	end
+end

data/lib/utopia/redirection/errors.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require_relative "../middleware"
+require_relative "../request"
+require_relative "../response"
+require_relative "request_failure"
+
+module Utopia
+	module Redirection
+		# A middleware which performs internal redirects based on error status codes.
+		#
+		# Place this middleware after client-visible redirection middleware in the
+		# application configuration. Internal error-document requests invoke the
+		# delegate directly, bypassing middleware configured before this one.
+		class Errors < Protocol::HTTP::Middleware
+			# @param codes [Hash<Integer,String>] The redirection path for a given error code.
+			def initialize(app, codes = {})
+				super(app)
+				
+				@codes = codes
+			end
+			
+			# Freeze this object and its internal state.
+			# @returns [self] This object.
+			def freeze
+				return self if frozen?
+				
+				@codes.freeze
+				
+				super
+			end
+			
+			# Check whether the response status requires error handling.
+			# @parameter response [Protocol::HTTP::Response] The response.
+			# @returns [Boolean] Whether the response is an error without handler-provided headers.
+			def unhandled_error?(response)
+				response.status >= 400 && response.headers.empty?
+			end
+			
+			# Replace an unhandled error response with its configured error document.
+			# @parameter request [Utopia::Request] The request.
+			# @returns [Protocol::HTTP::Response] The original or error-document response.
+			# @raises [RequestFailure] If the configured error document also fails.
+			def call(request)
+				response = Response.wrap(@delegate.call(request))
+				
+				if unhandled_error?(response) && location = @codes[response.status]
+					resource_status = response.status
+					
+					# The original response is replaced by the configured error document:
+					response.close
+					
+					error_request = request.with(method: "GET", path: location)
+					
+					error_response = Response.wrap(@delegate.call(error_request))
+					
+					if error_response.status >= 400
+						error = RequestFailure.new(request.url.path.encoded, resource_status, location, error_response.status)
+						
+						# The failed error document will not be returned to the server:
+						error_response.close(error)
+						
+						raise error
+					else
+						# Feed the error code back with the error document:
+						error_response.status = resource_status
+						return error_response
+					end
+				else
+					return response
+				end
+			end
+		end
+	end
+end

data/lib/utopia/redirection/moved.rb

@@ -0,0 +1,52 @@
+# 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 new prefix.
+		class Moved < ClientRedirect
+			# Initialize prefix redirection behavior.
+			# @parameter app [Interface(:call)] The downstream application.
+			# @parameter pattern [Regexp] The path pattern.
+			# @parameter prefix [String] The prefix.
+			# @parameter status [Integer] The status.
+			# @parameter flatten [bool] Whether to flatten the rewritten path.
+			def initialize(app, pattern, prefix, status: 301, flatten: false)
+				@pattern = pattern
+				@prefix = prefix
+				@flatten = flatten
+				
+				super(app, status: status)
+			end
+			
+			# Freeze this object and its internal state.
+			# @returns [self] This object.
+			def freeze
+				return self if frozen?
+				
+				@pattern.freeze
+				@prefix.freeze
+				@flatten.freeze
+				
+				return super
+			end
+			
+			# Redirect a matching path to the configured prefix.
+			# @parameter path [String] The normalized request path.
+			# @returns [Protocol::HTTP::Response | Nil] The redirect response when the pattern matches.
+			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