utopia 2.32.0 → 3.0.0

data/lib/utopia/content/middleware.rb

@@ -1,10 +1,13 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2009-2025, by Samuel Williams.
+# Copyright, 2025-2026, by Samuel Williams.
 
 require_relative "../middleware"
-require_relative "../localization"
+require_relative "../localization/resolver"
+require_relative "../request"
+require_relative "../response"
+require_relative "../controller/variables"
 
 require_relative "links"
 require_relative "node"
@@ -18,7 +21,9 @@ require "traces/provider"
 module Utopia
 	module Content
 		# A middleware which serves dynamically generated content based on markup files.
-		class Middleware
+		class Middleware < Protocol::HTTP::Middleware
+			include Localization::Resolver
+			
 			CONTENT_NAMESPACE = "content".freeze
 			UTOPIA_NAMESPACE = "utopia".freeze
 			CONTENT_TAG_NAME = "utopia:content".freeze
@@ -26,7 +31,8 @@ module Utopia
 			# @param root [String] The content root where pages will be generated from.
 			# @param namespaces [Hash<String,Library>] Tag namespaces for dynamic tag lookup.
 			def initialize(app, root: Utopia::default_root, namespaces: {})
-				@app = app
+				super(app)
+				
 				@root = root
 				
 				@template_cache = Concurrent::Map.new
@@ -43,6 +49,8 @@ module Utopia
 				@namespaces[UTOPIA_NAMESPACE] ||= Tags
 			end
 			
+			# Freeze this object and its internal state.
+			# @returns [self] This object.
 			def freeze
 				return self if frozen?
 				
@@ -60,6 +68,9 @@ module Utopia
 				@links.index(path, **options)
 			end
 			
+			# Load and cache a content template.
+			# @parameter path [Utopia::Path | String] The path.
+			# @returns [XRB::Template] The parsed template.
 			def fetch_template(path)
 				@template_cache.fetch_or_store(path.to_s) do
 					XRB::Template.load_file(path)
@@ -82,6 +93,9 @@ module Utopia
 				)
 			end
 			
+			# Resolve a link to an existing content node.
+			# @parameter link [Utopia::Content::Link] The content link.
+			# @returns [Node | Nil] The content node when its backing file exists.
 			def resolve_link(link)
 				if full_path = link&.full_path(@root)
 					if File.exist?(full_path)
@@ -90,19 +104,26 @@ module Utopia
 				end
 			end
 			
-			def respond(link, request)
+			# Respond.
+			# @parameter link [Utopia::Content::Link] The content link.
+			# @parameter request [Utopia::Request] The application request.
+			# @parameter localization [Utopia::Localization::Preferences | Nil] The selected localization.
+			# @returns [Protocol::HTTP::Response] The response.
+			def respond(link, request, localization: request.localization)
 				if node = resolve_link(link)
-					attributes = request.env.fetch(VARIABLES_KEY, {}).to_hash
+					attributes = request.variables&.to_hash || {}
 					
-					return node.process!(request, attributes)
+					return node.process!(request, attributes, localization: localization)
 				elsif redirect_uri = link[:uri]
-					return [307, {HTTP::LOCATION => redirect_uri}, []]
+					return Utopia::Response[307, {HTTP::LOCATION => redirect_uri}, []]
 				end
 			end
 			
-			def call(env)
-				request = Rack::Request.new(env)
-				path = Path.create(request.path_info)
+			# Serve or redirect filesystem-backed content, otherwise invoke the application.
+			# @parameter request [Utopia::Request] The request.
+			# @returns [Protocol::HTTP::Response] The content, redirect, or downstream response.
+			def call(request)
+				path = request.path
 				
 				# Check if the request is to a non-specific index. This only works for requests with a given name:
 				basename = path.basename
@@ -111,18 +132,24 @@ module Utopia
 				# If the request for /foo/bar is actually a directory, rewrite it to /foo/bar/index:
 				if File.directory? directory_path
 					index_path = [basename, INDEX]
+					location = path.dirname.join(index_path).to_url_path.encoded
 					
-					return [307, {HTTP::LOCATION => path.dirname.join(index_path).to_s}, []]
+					return Utopia::Response[307, {HTTP::LOCATION => location}, []]
 				end
 				
-				locale = env[Localization::CURRENT_LOCALE_KEY]
-				if link = @links.for(path, locale)
-					if response = self.respond(link, request)
-						return response
+				response = resolve_localized(request) do |localization|
+					locale = localization&.locale
+					
+					if link = @links.for(path, locale, fallback: false)
+						self.respond(link, request, localization: localization)
 					end
 				end
 				
-				return @app.call(env)
+				if response
+					return response
+				end
+				
+				return @delegate.call(request)
 			end
 			
 			private
@@ -182,13 +209,14 @@ module Utopia
 		end
 		
 		Traces::Provider(Middleware) do
-			def respond(link, request)
+			def respond(link, request, localization: request.localization)
 				attributes = {
 					"link.key" => link.key,
-					"link.href" => link.href
+					"link.href" => link.href,
+					"link.locale" => localization&.locale,
 				}
 				
-				Traces.trace("utopia.content.middleware.respond", attributes: attributes) {super}
+				Traces.trace("utopia.content.middleware.respond", attributes: attributes){super}
 			end
 		end
 	end

data/lib/utopia/content/namespace.rb

@@ -1,12 +1,15 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2017-2022, by Samuel Williams.
+# Copyright, 2017-2026, by Samuel Williams.
 
 module Utopia
 	module Content
 		# A namespace which contains tags which can be rendered within a {Document}.
 		module Namespace
+			# Initialize tag mappings on an extended namespace.
+			# @parameter other [Module] The namespace being extended.
+			# @returns [Hash] The initialized tag mappings.
 			def self.extended(other)
 				other.class_exec do
 					@named = {}
@@ -15,6 +18,8 @@ module Utopia
 			
 			attr :named
 			
+			# Freeze this object and its internal state.
+			# @returns [self] This object.
 			def freeze
 				return self if frozen?
 				
@@ -24,6 +29,10 @@ module Utopia
 				super
 			end
 			
+			# Tag.
+			# @parameter name [String] The name.
+			# @parameter klass [Class] The class to configure.
+			# @returns [Class | Proc] The registered tag implementation.
 			def tag(name, klass = nil, &block)
 				@named[name] = klass || block
 			end

data/lib/utopia/content/node.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2009-2025, by Samuel Williams.
+# Copyright, 2009-2026, by Samuel Williams.
 # Copyright, 2015, by Huba Nagy.
 
 require_relative "markup"
@@ -15,6 +15,11 @@ module Utopia
 	module Content
 		# Represents an immutable node within the content hierarchy.
 		class Node
+			# Initialize a node within the filesystem-backed content hierarchy.
+			# @parameter controller [Utopia::Controller::Base] The controller instance.
+			# @parameter uri_path [Utopia::Path | String] The uri path.
+			# @parameter request_path [Utopia::Path | String] The request path.
+			# @parameter file_path [String] The filesystem path.
 			def initialize(controller, uri_path, request_path, file_path)
 				@controller = controller
 				
@@ -27,14 +32,22 @@ module Utopia
 			attr :uri_path
 			attr :file_path
 			
+			# Return the node's URI basename.
+			# @returns [String] The node name.
 			def name
 				@uri_path.basename
 			end
 			
+			# Resolve another node relative to this node's parent.
+			# @parameter path [Utopia::Path | String] The path.
+			# @returns [Node | Nil] The resolved node.
 			def lookup_node(path)
 				@controller.lookup_node(parent_path + Path[path])
 			end
 			
+			# Resolve a content path beneath the controller root.
+			# @parameter path [Utopia::Path | String] The path.
+			# @returns [Pathname] The local filesystem path.
 			def local_path(path = ".", base = nil)
 				path = Path[path]
 				
@@ -48,6 +61,9 @@ module Utopia
 				end
 			end
 			
+			# Resolve a path relative to this node's containing URI path.
+			# @parameter path [Utopia::Path | String] The path.
+			# @returns [Path] The resolved content path.
 			def relative_path(path = ".")
 				path = Path[path]
 				base = uri_path.dirname
@@ -55,10 +71,16 @@ module Utopia
 				return base + path
 			end
 			
+			# Return this node's containing URI path.
+			# @returns [Path] The parent URI path.
 			def parent_path
 				@uri_path.dirname
 			end
 			
+			# Enumerate or return links relative to this node.
+			# @parameter path [Utopia::Path | String] The path.
+			# @yields {|link| ...} Each matching link when a block is given.
+			# @returns [Array(Link)] The matching links.
 			def links(path = ".", **options, &block)
 				path = uri_path.dirname + Path[path]
 				
@@ -71,10 +93,14 @@ module Utopia
 				end
 			end
 			
+			# Return localized and indexed variants related to this node.
+			# @returns [Array(Link)] The related links.
 			def related_links
 				@controller.links(@uri_path.dirname, name: @uri_path.basename, indices: true)
 			end
 			
+			# Return the directory whose links are siblings of this node.
+			# @returns [Path] The sibling directory path.
 			def siblings_path
 				if @uri_path.basename == INDEX
 					@uri_path.dirname(2)
@@ -83,6 +109,9 @@ module Utopia
 				end
 			end
 			
+			# Return links that are siblings of this node.
+			# @parameter options [Hash] The options.
+			# @returns [Array(Link)] The sibling links.
 			def sibling_links(**options)
 				return @controller.links(siblings_path, **options)
 			end
@@ -106,12 +135,21 @@ module Utopia
 				document.parse_markup(markup)
 			end
 			
-			def process!(request, attributes = {})
-				Document.render(self, request, attributes).to_a
+			# Process the request and return the resulting response.
+			# @parameter request [Utopia::Request] The application request.
+			# @parameter attributes [Hash] The attributes.
+			# @parameter localization [Utopia::Localization::Preferences | Nil] The selected localization.
+			# @returns [Protocol::HTTP::Response] The response.
+			def process!(request, attributes = {}, localization: request&.localization)
+				Document.render(self, request, attributes, localization: localization).to_response
 			end
 			
 			# This is a special context in which a limited set of well defined methods are exposed in the content view.
 			Context = Struct.new(:document, :state) do
+				# Render or defer a partial content block.
+				# @parameter arguments [Array] The arguments.
+				# @yields {|document| ...} Deferred content, when a block is given.
+				# @returns [String] The deferred-content marker.
 				def partial(*arguments, &block)
 					if block_given?
 						state.defer(&block)
@@ -124,44 +162,68 @@ module Utopia
 				
 				alias deferred_tag partial
 				
+				# Return the controller associated with the document.
+				# @returns [Controller::Variables | Nil] The current controller variables.
 				def controller
 					document.controller
 				end
 				
+				# Return the document's localization preferences.
+				# @returns [Localization::Preferences | Nil] The localization preferences.
 				def localization
 					document.localization
 				end
 				
+				# Return the application request being rendered.
+				# @returns [Utopia::Request] The request.
 				def request
 					document.request
 				end
 				
+				# Return the document response being rendered.
+				# @returns [Document] The document response.
 				def response
 					document
 				end
 				
+				# Return attributes for the current rendering state.
+				# @returns [Hash] The current attributes.
 				def attributes
 					state.attributes
 				end
 				
+				# Fetch an attribute from the current state or document defaults.
+				# @parameter key [String | Symbol] The lookup key.
+				# @returns [Object | Nil] The state attribute, falling back to the document attribute.
 				def [] key
-					state.attributes.fetch(key) {document.attributes[key]}
+					state.attributes.fetch(key){document.attributes[key]}
 				end
 				
 				alias current state
 				
+				# Return the captured content of the current node.
+				# @returns [String] The captured content.
 				def content
 					document.content
 				end
 				
+				# Return the enclosing rendering state.
+				# @returns [Builder | Nil] The parent rendering state.
 				def parent
 					document.parent
 				end
 				
+				# Return the first rendering state in the document.
+				# @returns [Builder | Nil] The first rendering state.
 				def first
 					document.first
 				end
 				
+				# Return or enumerate links relative to the current node.
+				# @parameter arguments [Array] The arguments.
+				# @parameter options [Hash] The options.
+				# @yields {|link| ...} Each matching link when a block is given.
+				# @returns [Array(Link)] The matching links.
 				def links(*arguments, **options, &block)
 					state.node.links(*arguments, **options, &block)
 				end

data/lib/utopia/content/response.rb

@@ -3,9 +3,10 @@
 # Released under the MIT License.
 # Copyright, 2010-2025, by Samuel Williams.
 
+require_relative "../response"
+
 module Utopia
 	module Content
-		# Compatibility with older versions of rack:
 		EXPIRES = "expires".freeze
 		CACHE_CONTROL = "cache-control".freeze
 		CONTENT_TYPE = "content-type".freeze
@@ -13,6 +14,7 @@ module Utopia
 		
 		# A basic content response, including useful defaults for typical HTML5 content.
 		class Response
+			# Initialize an empty successful HTML response.
 			def initialize
 				@status = 200
 				@headers = {}
@@ -26,16 +28,23 @@ module Utopia
 			attr :headers
 			attr :body
 			
+			# Join the response body into rendered content.
+			# @returns [String] The rendered content.
 			def content
 				@body.join
 			end
 			
+			# Decline tag lookup by default.
+			# @parameter tag [Object] The tag.
+			# @returns [Nil] No tag is resolved.
 			def lookup(tag)
 				return nil
 			end
 			
-			def to_a
-				[@status, @headers, @body]
+			# Convert this value to a protocol HTTP response.
+			# @returns [Protocol::HTTP::Response] The response.
+			def to_response
+				Utopia::Response[@status, @headers, @body]
 			end
 			
 			# Specifies that the content shouldn't be cached. Overrides `cache!` if already called.

data/lib/utopia/content.rb

@@ -6,7 +6,10 @@
 require_relative "content/middleware"
 
 module Utopia
+	# Builds middleware for serving filesystem-backed dynamic content.
 	module Content
+		# Construct content middleware.
+		# @returns [Content::Middleware] The content middleware.
 		def self.new(...)
 			Middleware.new(...)
 		end

data/lib/utopia/controller/actions.md

@@ -25,24 +25,24 @@ on "new" do |request|
 	@user = User.new
 	
 	if request.post?
-		@user.update_attributes(request.params["user"])
+		@user.update_attributes(parse_body(request)["user"])
 		
 		redirect! "index"
 	end
 end
 
 on "edit" do |request|
-	@user = User.find(request.params["id"])
+	@user = User.find(request.query_parameters["id"])
 	
 	if request.post?
-		@user.update_attributes(request.params["user"])
+		@user.update_attributes(parse_body(request)["user"])
 		
 		redirect! "index"
 	end
 end
 
 on "delete" do |request|
-	User.find(request.params["id"]).destroy
+	User.find(request.query_parameters["id"]).destroy
 	
 	redirect! "index"
 end

data/lib/utopia/controller/actions.rb

@@ -10,15 +10,21 @@ module Utopia
 		# A controller layer which invokes functinality based on the request path.
 		# @example
 		# 	on '*' do |request, path|
-		# 		succeed! content: 'Hello World'
+		# 		succeed! 'Hello World'
 		# 	end
 		module Actions
+			# Extend a controller class with the action-definition DSL.
+			# @parameter base [Class] The controller class.
+			# @returns [Class] The extended controller class.
 			def self.prepended(base)
 				base.extend(ClassMethods)
 			end
 			
 			# A nested action lookup hash table.
 			class Action < Hash
+				# Initialize an action lookup node.
+				# @parameter options [Hash] Metadata associated with this action.
+				# @yields The action body when this node matches.
 				def initialize(options = {}, &block)
 					@options = options
 					@callback = block
@@ -28,18 +34,28 @@ module Utopia
 				
 				attr_accessor :callback, :options
 				
+				# Check whether this action has a callback.
+				# @returns [Boolean] Whether this action has a callback.
 				def callback?
 					@callback != nil
 				end
 				
+				# Check whether this object is equivalent to another object.
+				# @parameter other [Object] The object to compare.
+				# @returns [Boolean] Whether the action mappings, callback, and options are equal.
 				def eql? other
 					super and @callback.eql? other.callback and @options.eql? other.options
 				end
 				
+				# Compute the hash value for this object.
+				# @returns [Integer] The resulting integer.
 				def hash
 					[super, @callback, @options].hash
 				end
 				
+				# Compare this object with another object.
+				# @parameter other [Object] The object to compare.
+				# @returns [Boolean] Whether the action mappings, callback, and options are equal.
 				def == other
 					super and @callback == other.callback and @options == other.options
 				end
@@ -50,8 +66,11 @@ module Utopia
 				# Matches any 1 path component.
 				WILDCARD = "*".freeze
 				
-				# Given a path, iterate over all actions that match. Actions match from most specific to most general.
-				# @return nil if nothing matched, or true if something matched.
+				# Yield all actions matching a path, from most specific to most general.
+				# @parameter path [Array(String)] The path components.
+				# @parameter index [Integer] The component index currently being matched.
+				# @yields {|action| ...} Each matching action.
+				# @returns [Boolean | Nil] `true` if any action matched, otherwise `nil`.
 				def apply(path, index = -1, &block)
 					# ** is greedy, it always matches if possible and matches all remaining input.
 					if match_all = self[WILDCARD_GREEDY] and match_all.callback?
@@ -79,10 +98,18 @@ module Utopia
 					return matched
 				end
 				
+				# Collect the actions matching the given path.
+				# @parameter path [Utopia::Path | String] The path.
+				# @returns [Array(Action)] The matching actions.
 				def matching(path, &block)
 					to_enum(:apply, path).to_a
 				end
 				
+				# Define an action at the given path.
+				# @parameter path [Array(String)] The path components in reverse matching order.
+				# @parameter options [Hash] Metadata associated with the action.
+				# @yields The action body.
+				# @returns [Action] The defined action.
 				def define(path, **options, &callback)
 					# puts "Defining path: #{path.inspect}"
 					current = self
@@ -97,6 +124,8 @@ module Utopia
 					return current
 				end
 				
+				# Generate a debug representation of this object.
+				# @returns [String] The resulting string.
 				def inspect
 					if callback?
 						"<action " + super + ":#{callback.source_location}(#{options})>"
@@ -108,6 +137,9 @@ module Utopia
 			
 			# Exposed to the controller class.
 			module ClassMethods
+				# Initialize class-level state when this module is extended.
+				# @parameter klass [Class] The class to configure.
+				# @returns [Class] The configured controller class.
 				def self.extended(klass)
 					klass.instance_eval do
 						@actions = nil
@@ -115,10 +147,18 @@ module Utopia
 					end
 				end
 				
+				# Return the root of the action lookup tree.
+				# @returns [Action] The root action.
 				def actions
 					@actions ||= Action.new
 				end
 				
+				# Define an action for the given request path.
+				# @parameter first [Path | String | Symbol | Array] The first path pattern or named suffix.
+				# @parameter path [Array(String)] Additional path components.
+				# @parameter options [Hash] Metadata associated with the action.
+				# @yields The action body.
+				# @returns [Action] The defined action.
 				def on(first, *path, **options, &block)
 					if first.is_a? Symbol
 						first = ["**", first.to_s]
@@ -127,10 +167,18 @@ module Utopia
 					actions.define(Path.split(first) + path, **options, &block)
 				end
 				
+				# Define the fallback action.
+				# @yields The fallback action body.
+				# @returns [Proc] The fallback action body.
 				def otherwise(&block)
 					@otherwise = block
 				end
 				
+				# Dispatch the request to the first matching action.
+				# @parameter controller [Utopia::Controller::Base] The controller instance.
+				# @parameter request [Utopia::Request] The request.
+				# @parameter path [Utopia::Path | String] The path.
+				# @returns [Object | Nil] The result of the final matching action or fallback action.
 				def dispatch(controller, request, path)
 					if @actions
 						matched = @actions.apply(path.components) do |action|