utopia 2.32.0 → 3.0.0

data/lib/utopia/controller/base.rb

@@ -4,11 +4,14 @@
 # Copyright, 2014-2025, by Samuel Williams.
 
 require_relative "../http"
+require_relative "../path"
+require_relative "../response"
+require_relative "result"
+
+require "protocol/content/default"
 
 module Utopia
 	module Controller
-		CONTENT_TYPE = HTTP::CONTENT_TYPE
-		
 		# The base implementation of a controller class.
 		class Base
 			URI_PATH = nil
@@ -30,24 +33,34 @@ module Utopia
 				self.const_get(:CONTROLLER)
 			end
 			
+			# Generate a debug representation of this object.
+			# @returns [String] The resulting string.
 			def self.inspect
 				"#{super}#{self.uri_path}"
 			end
 			
+			# Convert this object to a string.
+			# @returns [String] The resulting string.
 			def self.to_s
 				self.inspect
 			end
 			
+			# Convert this object to a string.
+			# @returns [String] The resulting string.
 			def to_s
 				"\#<#{self.class}>"
 			end
 			
+			# Generate a debug representation of this object.
+			# @returns [String] The resulting string.
 			def inspect
 				details = self.instance_variables.map{|name| " #{name}=#{self.instance_variable_get(name)}"}
 				
 				"\#<#{self.class}#{details.join}>"
 			end
 			
+			# Freeze this object and its internal state.
+			# @returns [self] This object.
 			def self.freeze
 				# This ensures that all class variables are frozen.
 				self.instance_variables.each do |name|
@@ -57,17 +70,23 @@ module Utopia
 				super
 			end
 			
+			# Check whether the path refers directly to this controller.
+			# @parameter path [Utopia::Path | String] The path.
+			# @returns [Boolean] Whether the path is directly contained by this controller's URI path.
 			def self.direct?(path)
 				path.dirname == uri_path
 			end
 			
+			# Catch and return a response thrown while executing the block.
+			# @yields The controller operation that may throw a response.
+			# @returns [Protocol::HTTP::Response | Nil] The thrown response, or `nil` if the block completes.
 			def catch_response
 				catch(:response) do
 					yield and nil
 				end
 			end
 			
-			# Return nil if this controller didn't do anything. Request will keep on processing. Return a valid rack response if the controller can do so.
+			# Return nil if this controller didn't do anything. Request will keep on processing. Return a valid response if the controller can do so.
 			def process!(request, relative_path)
 				return nil
 			end
@@ -79,19 +98,48 @@ module Utopia
 				end
 			end
 			
-			# Call into the next app as defined by rack.
-			def call(env)
-				self.class.controller.app.call(env)
+			# Call into the next application.
+			def call(request)
+				self.class.controller.delegate.call(request)
+			end
+			
+			# Parse the request body according to its media type.
+			# @parameter request [Utopia::Request] The request containing the body.
+			# @parameter parser [Protocol::Content::Parser] The content parser.
+			# @yields {|name, value| ...} Form entries, including streaming uploads.
+			# @returns [Object | Nil] The parsed body, or nil when there is no body.
+			def parse_body(request, parser: Protocol::Content::Parser.default, &block)
+				body = request.body
+				return unless body
+				
+				input = body.to_io
+				error = nil
+				
+				begin
+					return parser.parse(request.headers["content-type"], input, &block)
+				rescue => error
+					raise
+				ensure
+					input.close_read(error)
+				end
 			end
 			
-			# This will cause the middleware to generate a response.
+			# Immediately respond with a complete protocol response.
+			# @parameter response [Protocol::HTTP::Response] The response.
+			# @returns [Object] This method does not return normally.
 			def respond!(response)
-				throw :response, response
+				throw :response, Utopia::Response.wrap(response)
 			end
 			
 			# Respond with the response, but only if it's not nil.
+			# @parameter response [Protocol::HTTP::Response | Nil] The optional response.
+			# @returns [Nil] This method returns `nil` when no response is provided.
 			def respond?(response)
-				respond!(response) if response
+				if response
+					return respond!(response)
+				end
+				
+				return nil
 			end
 			
 			# This will cause the controller middleware to pass on the request.
@@ -102,9 +150,14 @@ module Utopia
 			# Request relative redirect. Respond with a redirect to the given target.
 			def redirect!(target, status = 302)
 				status = HTTP::Status.new(status, 300...400)
-				location = target.to_s
 				
-				respond! [status.to_i, {HTTP::LOCATION => location}, [status.to_s]]
+				if target.is_a?(Utopia::Path)
+					location = target.to_url_path.encoded
+				else
+					location = target.to_s
+				end
+				
+				respond! Utopia::Response[status.to_i, {HTTP::LOCATION => location}, [status.to_s]]
 			end
 			
 			# Controller relative redirect.
@@ -117,28 +170,18 @@ module Utopia
 				status = HTTP::Status.new(error, 400...600)
 				
 				message ||= status.to_s
-				respond! [status.to_i, {}, [message]]
+				throw :response, Result.new(status.to_i, {}, message)
 			end
 			
-			# Succeed the request and immediately respond.
-			def succeed!(status: 200, headers: {}, type: nil, **options)
+			# Succeed the request with a semantic value awaiting response negotiation.
+			# @parameter value [Object] The semantic result value.
+			# @parameter status [Integer | Symbol] The successful response status.
+			# @parameter headers [Hash] Additional response headers.
+			# @returns [Object] This method does not return normally.
+			def succeed!(value = nil, status: 200, headers: {})
 				status = HTTP::Status.new(status, 200...300)
 				
-				if type
-					headers[CONTENT_TYPE] = type.to_s
-				end
-				
-				body = body_for(status, headers, options)
-				respond! [status.to_i, headers, body || []]
-			end
-			
-			# Generate the body for the given status, headers and options.
-			def body_for(status, headers, options)
-				if body = options[:body]
-					return body
-				elsif content = options[:content]
-					return [content]
-				end
+				throw :response, Result.new(status.to_i, headers, value)
 			end
 		end
 	end

data/lib/utopia/controller/middleware.rb

@@ -1,10 +1,12 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2009-2025, by Samuel Williams.
+# Copyright, 2025-2026, by Samuel Williams.
 
 require_relative "../path"
 require_relative "../middleware"
+require_relative "../request"
+require_relative "../response"
 
 require_relative "variables"
 require_relative "base"
@@ -17,14 +19,16 @@ require "concurrent/map"
 module Utopia
 	# A middleware which loads controller classes and invokes functionality based on the requested path.
 	module Controller
-		class Middleware
+		# Dispatches requests to filesystem-backed controller classes.
+		class Middleware < Protocol::HTTP::Middleware
 			# The controller filename.
 			CONTROLLER_RB = "controller.rb".freeze
 			
 			# @param root [String] The content root where controllers will be loaded from.
 			# @param base [Class] The base class for controllers.
 			def initialize(app, root: Utopia::default_root, base: Controller::Base)
-				@app = app
+				super(app)
+				
 				@root = root
 				
 				@controller_cache = Concurrent::Map.new
@@ -32,8 +36,8 @@ module Utopia
 				@base = base
 			end
 			
-			attr :app
-			
+			# Freeze this object and its internal state.
+			# @returns [self] This object.
 			def freeze
 				return self if frozen?
 				
@@ -82,7 +86,7 @@ module Utopia
 			
 			# Invoke the controller layer for a given request. The request path may be rewritten.
 			def invoke_controllers(request)
-				request_path = Path.from_string(request.path_info)
+				request_path = request.path
 				
 				# The request path must be absolute. We could handle this internally but it is probably better for this to be an error:
 				raise ArgumentError.new("Invalid request path #{request_path}") unless request_path.absolute?
@@ -91,7 +95,7 @@ module Utopia
 				controller_path = Path.new
 				
 				# Controller instance variables which eventually get processed by the view:
-				variables = request.env[VARIABLES_KEY]
+				variables = request.variables
 				
 				while request_path.components.any?
 					# We copy one path component from the relative path to the controller path at a time. The controller, when invoked, can modify the relative path (by assigning to relative_path.components). This allows for controller-relative rewrites, but only the remaining path postfix can be modified.
@@ -110,23 +114,24 @@ module Utopia
 					end
 				end
 				
-				# Controllers can directly modify relative_path, which is copied into controller_path. The controllers may have rewriten the path so we update the path info:
-				request.env[Rack::PATH_INFO] = controller_path.to_s
+				# Controllers can directly modify the remaining path. Preserve those rewrites at the request boundary:
+				request.path = controller_path
 				
 				# No controller gave a useful result:
 				return nil
 			end
 			
-			def call(env)
-				env[VARIABLES_KEY] ||= Variables.new
-				
-				request = Rack::Request.new(env)
+			# Attach controller variables while processing the request.
+			# @parameter request [Utopia::Request] The request.
+			# @returns [Protocol::HTTP::Response] The controller or downstream response.
+			def call(request)
+				request.variables ||= Variables.new
 				
 				if result = invoke_controllers(request)
-					return result
+					return Utopia::Response.wrap(result)
 				end
 				
-				return @app.call(env)
+				return @delegate.call(request)
 			end
 		end
 	end

data/lib/utopia/controller/respond.rb

@@ -4,62 +4,66 @@
 # Copyright, 2016-2025, by Samuel Williams.
 
 require_relative "../http"
+require_relative "../response"
 require_relative "responder"
 
 module Utopia
 	module Controller
 		# A controller layer which provides a convenient way to respond to different requested content types. The order in which you add converters matters, as it determines how the incoming Accept: header is mapped, e.g. the first converter is also defined as matching the media range */*.
 		module Respond
+			# Extend a controller class with response negotiation.
+			# @parameter base [Class] The controller class.
+			# @returns [Class] The extended controller class.
 			def self.prepended(base)
 				base.extend(ClassMethods)
 			end
 			
+			# Defines response handlers on controller classes.
 			module ClassMethods
+				# Return this controller's responder.
+				# @returns [Responder] The responder.
 				def responds
 					@responder ||= Responder.new
 				end
 				
-				alias respond responds
-				
-				def respond_to(context, request)
-					@responder&.respond_to(context, request)
-				end
-				
-				def response_for(context, request, response)
-					@responder&.respond_to(context, request).with(*response[2])
+				# Serialize a semantic value according to the request's accepted media types.
+				# @parameter context [Controller::Base] The controller context.
+				# @parameter request [Utopia::Request] The request.
+				# @parameter value [Object] The semantic value.
+				# @returns [Array(Object, Object) | Nil] The selected content type and body.
+				def response_for(context, request, value)
+					@responder&.call(context, request, value)
 				end
 			end
 			
-			def respond_to(request)
-				self.class.respond_to(self, request)
-			end
-			
-			def response_for(request, original_response)
-				response = catch(:response) do
-					self.class.response_for(self, request, original_response)
+			# Build a protocol response for a semantic controller result.
+			# @parameter request [Utopia::Request] The request.
+			# @parameter result [Controller::Result] The semantic controller result.
+			# @returns [Protocol::HTTP::Response] The response.
+			def response_for(request, result)
+				if response = self.class.response_for(self, request, result.value)
+					content_type, body = response
+					headers = result.headers.dup
 					
-					# If the above code did not throw a new response, we return the original:
-					return original_response
+					if content_type
+						headers[HTTP::CONTENT_TYPE] = content_type.to_s
+					end
+					
+					return Utopia::Response[result.status, headers, body]
 				end
 				
-				# If the user called {Base#ignore!}, it's possible response is nil:
-				if response
-					# There was an updated response so merge it:
-					return [original_response[0], original_response[1].merge(response[1]), response[2] || original_response[2]]
-				end
+				raise TypeError, "Could not negotiate a response for #{result.value.class}!"
 			end
 			
-			# Invokes super. If a response is generated, format it based on the Accept: header, unless the content type was already specified.
+			# Serialize semantic controller results, while passing complete protocol responses through unchanged.
 			def process!(request, path)
-				if response = super
-					headers = response[1]
-					
-					# Don't try to convert the response if a content type was explicitly specified.
-					if headers[HTTP::CONTENT_TYPE]
-						return response
-					else
-						return self.response_for(request, response)
-					end
+				result = super
+				
+				case result
+				when Result
+					return self.response_for(request, result)
+				else
+					return result
 				end
 			end
 		end

data/lib/utopia/controller/responder.rb

@@ -5,98 +5,159 @@
 
 require_relative "middleware"
 
+require "protocol/http/header/accept"
+require "protocol/media/map"
+require "protocol/media/type"
+require "protocol/media/range"
+
 module Utopia
 	module Controller
+		# @namespace
 		module Handlers
+			# Serializes controller values as JSON responses.
 			module JSON
-				APPLICATION_JSON = HTTP::Accept::ContentType.new("application", "json").freeze
-				
-				def self.split(*arguments)
-					APPLICATION_JSON.split(*arguments)
-				end
+				APPLICATION_JSON = Protocol::Media::Type.new("application", "json").freeze
 				
+				# Serialize an object as JSON.
+				# @parameter context [Object] The context.
+				# @parameter request [Utopia::Request] The request.
+				# @parameter media_range [Protocol::HTTP::Header::Accept::MediaRange] The negotiated media range.
+				# @parameter object [Object] The object.
+				# @parameter options [Hash] The options.
+				# @returns [String] The serialized JSON body.
 				def self.call(context, request, media_range, object, **options)
 					if version = media_range.parameters["version"]
 						options[:version] = version.to_s
 					end
 					
-					context.succeed! content: object.to_json(options), type: APPLICATION_JSON
+					return object.to_json(options)
+				end
+				
+				# The media type produced by this handler.
+				# @returns [Protocol::Media::Type] The JSON media type.
+				def self.content_type
+					APPLICATION_JSON
 				end
 			end
 			
+			# Passes response values through without transformation.
 			module Passthrough
-				WILDCARD = HTTP::Accept::MediaTypes::MediaRange.new("*", "*").freeze
+				WILDCARD = Protocol::Media::Range.new("*", "*").freeze
 				
-				def self.split(*arguments)
-					WILDCARD.split(*arguments)
+				# Pass an object through without transformation.
+				# @parameter context [Object] The context.
+				# @parameter request [Utopia::Request] The request.
+				# @parameter media_range [Protocol::HTTP::Header::Accept::MediaRange] The negotiated media range.
+				# @parameter object [Object] The object.
+				# @parameter options [Hash] The options.
+				# @returns [Object] The original body.
+				def self.call(context, request, media_range, object, **options)
+					return object
 				end
 				
-				def self.call(context, request, media_range, object, **options)
-					# Do nothing.
+				# The passthrough handler does not specify a response media type.
+				# @returns [Nil] No media type.
+				def self.content_type
+					return nil
 				end
 			end
 		end
 		
+		# Negotiates response content types and invokes the matching handler.
 		class Responder
+			# A content-type handler and its response block.
 			Handler = Struct.new(:content_type, :block) do
-				def split(*arguments)
-					self.content_type.split(*arguments)
-				end
-				
+				# Invoke this handler's block in the controller context.
+				# @parameter context [Object] The context.
+				# @parameter request [Utopia::Request] The request.
+				# @parameter media_range [Protocol::HTTP::Header::Accept::MediaRange] The negotiated media range.
+				# @parameter arguments [Array] The arguments.
+				# @parameter options [Hash] The options.
+				# @returns [Object] The handler block's result.
 				def call(context, request, media_range, *arguments, **options)
 					context.instance_exec(media_range, *arguments, **options, &self.block)
 				end
 			end
 			
-			Responds = Struct.new(:responder, :context, :request) do
-				# @todo Refactor `object` -> `*arguments`...
-				def with(object, **options)
-					responder.call(context, request, object, **options)
-				end
-			end
-			
-			def initialize
-				@handlers = HTTP::Accept::MediaTypes::Map.new
+			# Initialize a responder with a handler map.
+			# @parameter handlers [Protocol::Media::Map] The response handlers.
+			# @parameter passthrough [Object | Nil] The fallback response handler.
+			def initialize(handlers = Protocol::Media::Map.new, passthrough = nil)
+				@handlers = handlers
+				@passthrough = passthrough
 			end
 			
 			attr :handlers
 			
+			# Freeze this responder and compile its handler map.
+			# @returns [self] This responder.
 			def freeze
-				@handlers.freeze
-				
-				super
-			end
-			
-			def call(context, request, *arguments, **options)
-				# Parse the list of browser preferred content types and return ordered by priority:
-				media_types = HTTP::Accept::MediaTypes.browser_preferred_media_types(request.env)
+				return self if frozen?
 				
-				handler, media_range = @handlers.for(media_types)
+				@handlers.freeze
 				
-				if handler
-					handler.call(context, request, media_range, *arguments, **options)
-				end
+				return super
 			end
 			
-			# Add a converter for the specified content type. Call the block with the response content if the request accepts the specified content_type.
+			# Add a serializer for the specified content type.
+			# @parameter content_type [String | Protocol::Media::Type] The produced media type.
+			# @yields The response handler body.
+			# @returns [self] This responder.
 			def handle(content_type, &block)
-				@handlers << Handler.new(content_type, block)
-			end
-			
-			def respond_to(context, request)
-				Responds.new(self, context, request)
+				@handlers[content_type] = Handler.new(content_type, block).freeze
+				return self
 			end
 			
+			# Register the default JSON handler.
+			# @returns [self] This responder.
 			def with_json
-				@handlers << Handlers::JSON
+				@handlers[Handlers::JSON::APPLICATION_JSON] = Handlers::JSON
+				return self
 			end
 			
+			# Register the wildcard passthrough handler.
+			# @returns [self] This responder.
 			def with_passthrough
-				@handlers << Handlers::Passthrough
+				@passthrough = Handlers::Passthrough
+				return self
 			end
 			
+			# Add a serializer for the specified content type.
+			# @parameter content_type [String | Protocol::Media::Type] The produced media type.
+			# @yields The response handler body.
+			# @returns [self] This responder.
 			def with(content_type, &block)
-				handle(content_type, &block)
+				return handle(content_type, &block)
+			end
+			
+			# Negotiate the request's accepted media types and invoke the best handler.
+			# @parameter context [Object] The controller context.
+			# @parameter request [Utopia::Request] The request.
+			# @parameter arguments [Array] The arguments.
+			# @parameter options [Hash] The options.
+			# @returns [Array(Object, Object) | Nil] The selected content type and body, or `nil` if none matches.
+			def call(context, request, *arguments, **options)
+				accept = request.headers["accept"]
+				
+				# An absent or empty Accept header accepts any media type:
+				if accept.nil? || accept.empty?
+					media_ranges = [Handlers::Passthrough::WILDCARD]
+				else
+					media_ranges = accept.preferred_media_ranges
+				end
+				
+				if match = @handlers.for(media_ranges)
+					handler, media_range = match
+				elsif @passthrough
+					handler = @passthrough
+					media_range = media_ranges.first
+				end
+				
+				if handler
+					return handler.content_type, handler.call(context, request, media_range, *arguments, **options)
+				end
+				
+				return nil
 			end
 		end
 	end

data/lib/utopia/controller/result.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+module Utopia
+	module Controller
+		# A semantic controller result awaiting response negotiation.
+		Result = Data.define(:status, :headers, :value)
+	end
+end