Separate internal error redirections.

Assisted-By: devx/b3414b50-d642-461b-95a8-8f773c4d087b

Author: samuel-williams-shopify

context/middleware.md

@@ -18,7 +18,7 @@ use Utopia::Static,
 
 ## Redirection
 
-The {ruby Utopia::Redirection} middleware is used for redirecting requests based on patterns and status codes.
+The {ruby Utopia::Redirection} middleware is used for redirecting requests based on paths.
 
 ~~~ ruby
 use Utopia::Redirection do |redirects|
@@ -30,12 +30,16 @@ use Utopia::Redirection do |redirects|
 
 	# Redirect matching path prefixes:
 	redirects.moved '/old/', '/new/'
-	
-	# Redirect error status codes to internal error documents:
-	redirects.error 404, '/errors/file-not-found'
 end
 ~~~
 
+The {ruby Utopia::Redirection::Errors} middleware maps unhandled error responses to internal error documents. It retains the original response status and does not issue a client-visible redirect:
+
+~~~ ruby
+use Utopia::Redirection::Errors,
+	404 => '/errors/file-not-found'
+~~~
+
 ## Localization
 
 The {ruby Utopia::Localization} middleware computes immutable localization preferences from the request path, host, and `accept-language` header. Localization-aware resource middleware, including {ruby Utopia::Static} and {ruby Utopia::Content}, resolves those preferences without invoking controllers more than once. Place the localization middleware before those resources in the middleware stack.

guides/middleware/readme.md

@@ -18,7 +18,7 @@ use Utopia::Static,
 
 ## Redirection
 
-The {ruby Utopia::Redirection} middleware is used for redirecting requests based on patterns and status codes.
+The {ruby Utopia::Redirection} middleware is used for redirecting requests based on paths.
 
 ~~~ ruby
 use Utopia::Redirection do |redirects|
@@ -30,12 +30,16 @@ use Utopia::Redirection do |redirects|
 
 	# Redirect matching path prefixes:
 	redirects.moved '/old/', '/new/'
-	
-	# Redirect error status codes to internal error documents:
-	redirects.error 404, '/errors/file-not-found'
 end
 ~~~
 
+The {ruby Utopia::Redirection::Errors} middleware maps unhandled error responses to internal error documents. It retains the original response status and does not issue a client-visible redirect:
+
+~~~ ruby
+use Utopia::Redirection::Errors,
+	404 => '/errors/file-not-found'
+~~~
+
 ## Localization
 
 The {ruby Utopia::Localization} middleware computes immutable localization preferences from the request path, host, and `accept-language` header. Localization-aware resource middleware, including {ruby Utopia::Static} and {ruby Utopia::Content}, resolves those preferences without invoking controllers more than once. Place the localization middleware before those resources in the middleware stack.

lib/utopia/redirection.rb

@@ -4,6 +4,7 @@
 # Copyright, 2009-2026, by Samuel Williams.
 
 require_relative "redirection/request_failure"
+require_relative "redirection/errors"
 require_relative "redirection/rule"
 require_relative "redirection/builder"
 require_relative "redirection/middleware"

lib/utopia/redirection/builder.rb

@@ -13,17 +13,12 @@ class Builder
 			# Initialize an empty redirection configuration.
 			def initialize
 				@rules = []
-				@errors = {}
 			end
 
 			# The configured request redirection rules.
 			# @returns [Array] The rules in declaration order.
 			attr :rules
 
-			# The configured error document paths indexed by response status.
-			# @returns [Hash(Integer, String)] The configured error documents.
-			attr :errors
-			
 			# Configure and freeze this builder.
 			# @yields {|builder| ...} The redirection configuration.
 			# @returns [self] This builder.
@@ -47,7 +42,6 @@ def freeze
 				return self if frozen?
 
 				@rules.freeze
-				@errors.freeze
 
 				return super
 			end
@@ -108,15 +102,6 @@ def moved(pattern, prefix, status: 301, flatten: false, max_age: MAX_AGE)
 				return self
 			end
 
-			# Replace an unhandled response status with an internal error document.
-			# @parameter status [Integer] The response status to handle.
-			# @parameter path [String] The internal error document path.
-			# @returns [self] This builder.
-			def error(status, path)
-				@errors[status] = path
-				return self
-			end
-			
 			private
 
 			def add(status, max_age, &resolver)

lib/utopia/redirection/errors.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2009-2026, by Samuel Williams.
+
+require_relative "../middleware"
+require_relative "../request"
+require_relative "../response"
+require_relative "request_failure"
+
+module Utopia
+	module Redirection
+		# Performs internal redirections for unhandled error responses.
+		class Errors < Protocol::HTTP::Middleware
+			# Initialize internal error redirections.
+			# @parameter delegate [Protocol::HTTP::Middleware] The downstream middleware.
+			# @parameter codes [Hash(Integer, String)] The internal path for each error status.
+			def initialize(delegate, codes = {})
+				super(delegate)
+				
+				@codes = codes
+			end
+			
+			# Freeze this object and its internal state.
+			# @returns [self] This object.
+			def freeze
+				return self if frozen?
+				
+				@codes.freeze
+				
+				return 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.
+			# @parameter response [Protocol::HTTP::Response] The unhandled error response.
+			# @parameter location [String] The configured error document path.
+			# @returns [Protocol::HTTP::Response] The error-document response.
+			# @raises [RequestFailure] If the configured error document also fails.
+			def replace_error(request, response, location)
+				resource_status = response.status
+				
+				# The original response is replaced by the configured error document:
+				response.close
+				
+				error_request = request.with(method: "GET", path_info: location)
+				error_response = Response.wrap(@delegate.call(error_request))
+				
+				if error_response.status >= 400
+					error = RequestFailure.new(request.path_info, resource_status, location, error_response.status)
+					
+					# The failed error document will not be returned to the server:
+					error_response.close(error)
+					
+					raise error
+				end
+				
+				# Feed the error code back with the error document:
+				error_response.status = resource_status
+				return error_response
+			end
+			
+			# Replace configured unhandled responses through an internal request.
+			# @parameter request [Utopia::Request] The request.
+			# @returns [Protocol::HTTP::Response] The original or error-document response.
+			def call(request)
+				response = Response.wrap(@delegate.call(request))
+				
+				if unhandled_error?(response) && location = @codes[response.status]
+					return replace_error(request, response, location)
+				end
+				
+				return response
+			end
+		end
+	end
+end

lib/utopia/redirection/middleware.rb

@@ -9,7 +9,7 @@
 
 module Utopia
 	module Redirection
-		# Applies configured request redirections and error documents.
+		# Applies configured request redirections.
 		class Middleware < Protocol::HTTP::Middleware
 			# Initialize redirection handling.
 			# @parameter delegate [Protocol::HTTP::Middleware] The downstream middleware.
@@ -18,7 +18,6 @@ def initialize(delegate, builder)
 				super(delegate)
 
 				@rules = builder.rules
-				@errors = builder.errors
 			end
 
 			# Build a redirect response for the given rule and location.
@@ -34,43 +33,7 @@ def redirect(rule, location)
 				return Response[rule.status, headers, []]
 			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.
-			# @parameter response [Protocol::HTTP::Response] The unhandled error response.
-			# @parameter location [String] The configured error document path.
-			# @returns [Protocol::HTTP::Response] The error-document response.
-			# @raises [RequestFailure] If the configured error document also fails.
-			def replace_error(request, response, location)
-				resource_status = response.status
-				
-				# The original response is replaced by the configured error document:
-				response.close
-				
-				error_request = request.with(method: "GET", path_info: location)
-				error_response = Response.wrap(@delegate.call(error_request))
-				
-				if error_response.status >= 400
-					error = RequestFailure.new(request.path_info, resource_status, location, error_response.status)
-					
-					# The failed error document will not be returned to the server:
-					error_response.close(error)
-					
-					raise error
-				end
-				
-				# Feed the error code back with the error document:
-				error_response.status = resource_status
-				return error_response
-			end
-			
-			# Apply request redirections, invoke the delegate, and handle error responses.
+			# Apply request redirections and invoke the delegate when none match.
 			# @parameter request [Utopia::Request] The request.
 			# @returns [Protocol::HTTP::Response] The resulting response.
 			def call(request)
@@ -83,13 +46,7 @@ def call(request)
 					end
 				end
 
-				response = Response.wrap(@delegate.call(request))
-				
-				if unhandled_error?(response) && location = @errors[response.status]
-					return replace_error(request, response, location)
-				end
-				
-				return response
+				return @delegate.call(request)
 			end
 		end
 	end

releases.md

@@ -4,7 +4,7 @@
 
   - **Security** Fix handling of redirects that start with `//` to prevent open redirect vulnerabilities.
   - Use `protocol-media` and `protocol-http` for response and language negotiation, removing the `http-accept` dependency.
-  - Combine request redirections and error documents into one configurable redirection middleware.
+  - Combine client-facing request redirections into one configurable middleware.
 
 ## v2.31.0
 

setup/site/config/application.rb

@@ -28,8 +28,8 @@
 	use Utopia::Redirection do |redirects|
 		redirects.rewrite "/" => "/welcome/index"
 		redirects.directory_index
-		redirects.error 404, "/errors/file-not-found"
 	end
+	use Utopia::Redirection::Errors, 404 => "/errors/file-not-found"
 
 	use Utopia::Session,
 		expires_after: 3600 * 24,

test/utopia/.performance/config/application.rb

@@ -14,8 +14,8 @@
 	use Utopia::Redirection do |redirects|
 		redirects.rewrite "/" => "/welcome/index"
 		redirects.directory_index
-		redirects.error 404, "/errors/file-not-found"
 	end
+	use Utopia::Redirection::Errors, 404 => "/errors/file-not-found"
 
 	use Utopia::Controller, root: ROOT
 	use Utopia::Static, root: ROOT

test/utopia/controller/respond.rb

@@ -154,9 +154,7 @@ def mock_request(path, headers = {})
 		root = File.expand_path(".respond", __dir__)
 
 		Utopia::Application.build(Protocol::HTTP::Middleware.for{|request| Utopia::Response[404, {}, []]}) do
-			use Utopia::Redirection do |redirects|
-				redirects.error 404, "/fail"
-			end
+			use Utopia::Redirection::Errors, 404 => "/fail"
 			use Utopia::Controller, root: root
 			use Utopia::Content, root: root
 		end