utopia 2.32.0 → 3.0.0

data/lib/utopia/localization/locales.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+module Utopia
+	module Localization
+		# Matches configured locales against language ranges.
+		class Locales
+			# Expand a locale into progressively less specific language ranges.
+			# @parameter locale [String] The locale to expand.
+			# @parameter patterns [Hash] The destination language-range mapping.
+			def self.expand(locale, patterns)
+				parts = locale.split("-")
+				
+				while parts.any?
+					pattern = parts.join("-")
+					patterns[pattern] ||= locale
+					parts.pop
+				end
+			end
+			
+			# Initialize the configured locales.
+			# @parameter names [Array(String)] The locale names, in preference order.
+			def initialize(names)
+				@names = names
+				@patterns = {}
+				
+				@names.each do |name|
+					self.class.expand(name, @patterns)
+				end
+				
+				freeze
+			end
+			
+			# Freeze this object and its internal state.
+			# @returns [self] This object.
+			def freeze
+				return self if frozen?
+				
+				@names.freeze
+				@patterns.freeze
+				
+				return super
+			end
+			
+			attr :names
+			attr :patterns
+			
+			# Select configured locales matching the given language ranges.
+			# @parameter languages [Enumerable] Preferred language ranges.
+			# @returns [Array(String)] Matching locale names in language preference order.
+			def match(languages)
+				languages.filter_map do |language|
+					@patterns[language.name]
+				end
+			end
+		end
+	end
+end

data/lib/utopia/localization/middleware.rb

@@ -1,26 +1,30 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2009-2025, by Samuel Williams.
+# Copyright, 2025-2026, by Samuel Williams.
 
-require_relative "wrapper"
+require_relative "preferences"
+require_relative "locales"
+require_relative "../middleware"
+require_relative "../request"
+require_relative "../response"
+
+require "set"
+require "protocol/http/header/accept_language"
 
 module Utopia
 	module Localization
-		class Middleware
-			RESOURCE_NOT_FOUND = [400, {}, []].freeze
-			
-			HTTP_ACCEPT_LANGUAGE = "HTTP_ACCEPT_LANGUAGE".freeze
-			
+		# Computes localization preferences and rewrites locale-prefixed paths.
+		class Middleware < Protocol::HTTP::Middleware
 			# @param locales [Array<String>] An array of all supported locales.
 			# @param default_locale [String] The default locale if none is provided.
-			# @param default_locales [String] The locales to try in order if none is provided.
-			# @param hosts [Hash<Pattern, String>] Specify a mapping of the HTTP_HOST header to a given locale.
-			# @param ignore [Array<Pattern>] A list of patterns matched against PATH_INFO which will not be localized.
+			# @param default_locales [Array<String | Nil>] The locales to try in order if none is provided.
+			# @param hosts [Hash<Pattern, String>] Specify a mapping of request hosts to locales.
+			# @param ignore [Array<Pattern>] A list of patterns matched against request paths which will not be localized.
 			def initialize(app, locales:, default_locale: nil, default_locales: nil, hosts: {}, ignore: [])
-				@app = app
+				super(app)
 				
-				@all_locales = HTTP::Accept::Languages::Locales.new(locales)
+				@all_locales = Locales.new(locales)
 				
 				# Locales here are represented as an array of strings, e.g. ['en', 'ja', 'cn', 'de'] and are used in order if no locale is specified by the user.
 				unless @default_locales = default_locales
@@ -41,11 +45,11 @@ module Utopia
 				# Select a localization based on a request host name:
 				@hosts = hosts
 				
-				@ignore = ignore || options[:nonlocalized]
-				
-				@methods = methods
+				@ignore = ignore
 			end
 			
+			# Freeze this object and its internal state.
+			# @returns [self] This object.
 			def freeze
 				return self if frozen?
 				
@@ -61,112 +65,142 @@ module Utopia
 			attr :all_locales
 			attr :default_locale
 			
-			def preferred_locales(env)
-				return to_enum(:preferred_locales, env) unless block_given?
-				
+			# Compute the preferred locales for a request.
+			# @parameter request [Utopia::Request] The application request.
+			# @parameter path_locale [String | Nil] The locale extracted from the request path.
+			# @returns [Array(String | Nil)] The unique locales in preference order.
+			def preferred_locales(request, path_locale = nil)
 				# Keep track of what locales have been tried:
 				locales = Set.new
 				
-				host_preferred_locales(env) do |locale|
-					yield env.merge(CURRENT_LOCALE_KEY => locale) if locales.add? locale
+				if path_locale
+					locales.add(path_locale)
 				end
 				
-				request_preferred_locale(env) do |locale, path|
-					# We have extracted a locale from the path, so from this point on we should use the updated path:
-					env = env.merge(Rack::PATH_INFO => path.to_s)
-					
-					yield env.merge(CURRENT_LOCALE_KEY => locale) if locales.add? locale
+				host_preferred_locales(request) do |locale|
+					locales.add(locale)
 				end
 				
-				browser_preferred_locales(env).each do |locale|
-					yield env.merge(CURRENT_LOCALE_KEY => locale) if locales.add? locale
+				browser_preferred_locales(request).each do |locale|
+					locales.add(locale)
 				end
 				
 				@default_locales.each do |locale|
-					yield env.merge(CURRENT_LOCALE_KEY => locale) if locales.add? locale
+					locales.add(locale)
 				end
+				
+				return locales.to_a
 			end
 			
-			def host_preferred_locales(env)
-				http_host = env[Rack::HTTP_HOST]
-				
-				# Yield all hosts which match the incoming http_host:
+			# Infer preferred locales from the request authority.
+			# @parameter request [Utopia::Request] The application request.
+			# @yields {|locale| ...} Each locale whose host pattern matches the request authority.
+			# @returns [Hash] The configured host mappings.
+			def host_preferred_locales(request)
+				authority = request.authority.to_s
+				
+				# Yield all hosts which match the incoming authority:
 				@hosts.each do |pattern, locale|
-					yield locale if http_host[pattern]
+					if authority[pattern]
+						yield locale
+					end
 				end
 			end
 			
-			def request_preferred_locale(env)
-				path = Path[env[Rack::PATH_INFO]]
+			# Extract a locale prefix from the request path.
+			# @parameter request [Utopia::Request] The application request.
+			# @returns [Array(Utopia::Request, String | Nil)] The request and extracted locale.
+			def extract_path_locale(request)
+				path = request.url.path
+				
+				# Localization prefixes only apply to absolute application paths:
+				unless path.absolute?
+					return request, nil
+				end
 				
-				if request_locale = @all_locales.patterns[path.first]
-					# Remove the localization prefix:
-					path.delete_at(0)
+				if segment = path.segments[1]
+					# Decode only the component which may contain the locale:
+					component = Protocol::URL::Encoding::System.unescape(segment)
 					
-					yield request_locale, path
+					if request_locale = @all_locales.patterns[component]
+						# Remove the locale while preserving all other encoded segments:
+						segments = path.segments.dup
+						segments.delete_at(1)
+						
+						# Preserve the absolute root when the locale was the only component:
+						if segments == [""]
+							segments << ""
+						end
+						
+						path = Protocol::URL::Path.new(nil, segments)
+						
+						return request.with(path: path), request_locale
+					end
 				end
+				
+				return request, nil
 			end
 			
-			def browser_preferred_locales(env)
-				accept_languages = env[HTTP_ACCEPT_LANGUAGE]
+			# Parse the locales preferred by the browser.
+			# @parameter request [Utopia::Request] The application request.
+			# @returns [Array(String)] Supported locales accepted by the browser, in preference order.
+			def browser_preferred_locales(request)
+				accept_languages = request.headers["accept-language"]
 				
 				# No user prefered languages:
 				return [] unless accept_languages
 				
 				# Extract the ordered list of languages:
-				languages = HTTP::Accept::Languages.parse(accept_languages)
+				languages = accept_languages.preferred_languages
 				
 				# Returns available languages based on the order languages:
-				return @all_locales & languages
-			rescue HTTP::Accept::ParseError
+				return @all_locales.match(languages)
+			rescue Protocol::HTTP::Header::AcceptLanguage::ParseError
 				# If we fail to parse the browser Accept-Language header, we ignore it (silently).
 				return []
 			end
 			
-			def localized?(env)
+			# Check whether the request path includes a locale.
+			# @parameter request [Utopia::Request] The application request.
+			# @returns [Boolean] Whether the path is eligible for localization.
+			def localized?(request)
 				# Ignore requests which match the ignored paths:
-				path_info = env[Rack::PATH_INFO]
-				return false if @ignore.any?{|pattern| path_info[pattern] != nil}
+				path = request.url.path.encoded
+				return false if @ignore.any?{|pattern| path[pattern] != nil}
 				
 				return true
 			end
 			
-			# Set the Vary: header on the response to indicate that this response should include the header in the cache key.
-			def vary(env, response)
-				headers = response[1].to_a
+			# Mark the response as varying by language.
+			# @parameter response [Protocol::HTTP::Response] The response.
+			# @returns [Protocol::HTTP::Response] The response with localization headers.
+			def vary(response)
+				response = Response.wrap(response)
+				headers = response.headers
 				
 				# This response was based on the Accept-Language header:
-				headers << ["Vary", "Accept-Language"]
-				
-				# Althought this header is generally not supported, we supply it anyway as it is useful for debugging:
-				if locale = env[CURRENT_LOCALE_KEY]
-					# Set the Content-Location to point to the localized URI as requested:
-					headers["Content-Location"] = "/#{locale}" + env[Rack::PATH_INFO]
-				end
+				headers.add("vary", "Accept-Language")
 				
 				return response
 			end
 			
-			def call(env)
+			# Attach localization preferences and invoke the application once.
+			# @parameter request [Utopia::Request] The request.
+			# @returns [Protocol::HTTP::Response] The response with cache-variation headers.
+			def call(request)
 				# Pass the request through if it shouldn't be localized:
-				return @app.call(env) unless localized?(env)
-				
-				env[LOCALIZATION_KEY] = self
+				return @delegate.call(request) unless localized?(request)
 				
-				response = nil
+				request, path_locale = extract_path_locale(request)
+				locales = preferred_locales(request, path_locale)
 				
-				# We have a non-localized request, but there might be a localized resource. We return the best localization possible:
-				preferred_locales(env) do |localized_env|
-					# puts "Trying locale: #{localized_env[CURRENT_LOCALE_KEY]}: #{localized_env[Rack::PATH_INFO]}..."
-					
-					response = @app.call(localized_env)
-					
-					break unless response[0] >= 400
-					
-					response[2].close if response[2].respond_to?(:close)
-				end
+				request.localization = Preferences.new(
+					all_locales: @all_locales.names,
+					preferred_locales: locales,
+					default_locale: @default_locale,
+				)
 				
-				return vary(env, response)
+				return vary(@delegate.call(request))
 			end
 		end
 	end

data/lib/utopia/localization/preferences.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+module Utopia
+	module Localization
+		# Immutable localization preferences for a request or resolved resource.
+		class Preferences
+			# Initialize localization preferences.
+			# @parameter all_locales [Array(String)] All configured locales.
+			# @parameter preferred_locales [Array(String | Nil)] Locales in resolution order.
+			# @parameter default_locale [String | Nil] The configured default locale.
+			# @parameter locale [String | Nil] The currently selected locale.
+			def initialize(all_locales:, preferred_locales:, default_locale:, locale: preferred_locales.first)
+				@all_locales = all_locales
+				@preferred_locales = preferred_locales
+				@default_locale = default_locale
+				@locale = locale
+				
+				freeze
+			end
+			
+			# Freeze this object and its internal state.
+			# @returns [self] This object.
+			def freeze
+				return self if frozen?
+				
+				@all_locales.each(&:freeze)
+				@preferred_locales.each(&:freeze)
+				@default_locale.freeze
+				@locale.freeze
+				
+				@all_locales.freeze
+				@preferred_locales.freeze
+				
+				return super
+			end
+			
+			attr :all_locales
+			attr :preferred_locales
+			attr :default_locale
+			attr :locale
+			
+			# Whether localization is active.
+			# @returns [Boolean] `true` when locales are configured.
+			def localized?
+				!@all_locales.empty?
+			end
+			
+			# Build a path with the given locale prefix.
+			# @parameter path [Utopia::Path | String] The path.
+			# @parameter locale [String | Nil] The locale.
+			# @returns [String] The locale-prefixed path.
+			def localized_path(path, locale = @locale)
+				if locale
+					return "/#{locale}#{path}"
+				else
+					return path.to_s
+				end
+			end
+			
+			# Select a locale without changing the original preferences.
+			# @parameter locale [String | Nil] The selected locale.
+			# @returns [Preferences] A new localization preference object.
+			def with(locale:)
+				self.class.new(
+					all_locales: @all_locales,
+					preferred_locales: @preferred_locales,
+					default_locale: @default_locale,
+					locale: locale,
+				)
+			end
+		end
+	end
+end

data/lib/utopia/localization/resolver.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require_relative "../response"
+
+module Utopia
+	module Localization
+		# Resolves localized resources from immutable request preferences.
+		module Resolver
+			CONTENT_LANGUAGE = "content-language".freeze
+			CONTENT_LOCATION = "content-location".freeze
+			
+		private
+			
+			# Resolve a response by trying each preferred locale in order.
+			def resolve_localized(request)
+				if localization = request.localization
+					localization.preferred_locales.each do |locale|
+						selected = localization.with(locale: locale)
+						
+						if response = yield(selected)
+							return localized_response(request, response, selected)
+						end
+					end
+				else
+					return yield(nil)
+				end
+				
+				return nil
+			end
+			
+			# Describe the selected localized representation in its response metadata.
+			def localized_response(request, response, localization)
+				response = Response.wrap(response)
+				
+				if locale = localization.locale
+					response.headers[CONTENT_LANGUAGE] = locale
+					response.headers[CONTENT_LOCATION] = localization.localized_path(request.url.path.encoded)
+				end
+				
+				return response
+			end
+		end
+	end
+end

data/lib/utopia/localization.rb

@@ -3,10 +3,16 @@
 # Released under the MIT License.
 # Copyright, 2009-2025, by Samuel Williams.
 
+require_relative "localization/preferences"
+require_relative "localization/locales"
+require_relative "localization/resolver"
 require_relative "localization/middleware"
 
 module Utopia
+	# Computes request localization preferences and resolves localized resources.
 	module Localization
+		# Construct localization middleware.
+		# @returns [Localization::Middleware] The localization middleware.
 		def self.new(...)
 			Middleware.new(...)
 		end

data/lib/utopia/middleware.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2009-2025, by Samuel Williams.
+# Copyright, 2009-2026, by Samuel Williams.
+
+require "protocol/http/middleware"
 
 require_relative "http"
 require_relative "path"
@@ -10,9 +12,6 @@ module Utopia
 	# The default pages path for {Utopia::Content} middleware.
 	PAGES_PATH = "pages".freeze
 	
-	# This is used for shared controller variables which get consumed by the content middleware.
-	VARIABLES_KEY = "utopia.variables".freeze
-	
 	# The default root directory for middleware to operate within, e.g. the web-site directory. Convention over configuration.
 	# @param subdirectory [String] Appended to the default root to make a more specific path.
 	# @param pwd [String] The working directory for the current site.

data/lib/utopia/path/matcher.rb

@@ -15,6 +15,9 @@ module Utopia
 		class Matcher
 			# The result of matching against a {Path}.
 			class MatchData
+				# Initialize the named captures and unmatched path suffix.
+				# @parameter named_parts [Hash] The named match captures.
+				# @parameter post_match [String] The unmatched path suffix.
 				def initialize(named_parts, post_match)
 					@named_parts = named_parts
 					@post_match = Path[post_match]
@@ -26,10 +29,15 @@ module Utopia
 				# Any remaining part past the end of the explicitly matched components.
 				attr :post_match
 				
+				# Fetch a named capture.
+				# @parameter key [String | Symbol] The lookup key.
+				# @returns [Object | Nil] The named captured value.
 				def [] key
 					@named_parts[key]
 				end
 				
+				# Return the named captures.
+				# @returns [Array(String)] The capture names.
 				def names
 					@named_parts.keys
 				end
@@ -40,10 +48,17 @@ module Utopia
 				@patterns = patterns
 			end
 			
+			# Construct a matcher from typed named patterns.
+			# @parameter patterns [Hash] The path rewrite patterns.
+			# @returns [Matcher] The matcher.
 			def self.[](patterns)
 				self.new(patterns)
 			end
 			
+			# Coerce.
+			# @parameter klass [Class] The class to configure.
+			# @parameter value [String] The captured text.
+			# @returns [Object] The captured text coerced to `klass`.
 			def coerce(klass, value)
 				if klass == Integer
 					Integer(value)