utopia 3.0.3 → 3.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c16b554d772d132bd1820ec17f402bbdf2d3720a5c6965f8673c0f06054f1c29
-  data.tar.gz: d6d839b6d55e3aff38507b9c4324d2631eb5a6b7f64eaeddb7e6b30185409b0a
+  metadata.gz: '0314485e770b9085839422a7484c179a39e447d81b15b211d70fbb4361fdc8b2'
+  data.tar.gz: 6e583362bc02ce48424f8e3adf7b9528bfd0990ea4ff946879d4bfbc95a52624
 SHA512:
-  metadata.gz: ab0202e8f8259c62856341332dcc7f37532535e968e90b75dceb4e8370eee7092ac5e7cdc4e3a2072f0394ba87b39994c18fa2ca1f17864d9f04f5974847a9b2
-  data.tar.gz: 14260960ab36d1cea1cabc02b6c43c29661efefb6e3e1566ef7e61ce87ba9f6525e111f9182e3beeac0a973bf303c147a71d3edc65d1cb75153c3c7377e7f2a8
+  metadata.gz: 4a81a495790a61faea6d2ab3873fd4043807134a4dec40b50177318802eefc14484e8dc218373fbf32b8bfe441ff96038ccaa21093acda9610d1ebc3ad6e87bb
+  data.tar.gz: 35d548a73022d0307b8a631d3a8c755b1eef9fcb0edb3f7b224ac2ef57b2334018928f3c8a47e4fea6812882ce794973a639af563b5a941627f3cafcce8ca971

data/bake/utopia/components.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+NPM = ENV["NPM"] || "npm"
+
+# Update public components from production JavaScript packages.
+#
+# Packages are copied from their `dist` directory when present, or otherwise
+# from the package root. The `utopia.components` section of `package.json` can
+# specify per-package `include` patterns to select only required files.
+#
+# @parameter root [String] The project root directory.
+def update(root: context.root)
+	require "json"
+	require "open3"
+	require "utopia/components"
+	
+	components = Utopia::Components.new(root)
+	production_packages = fetch_production_packages(components.package_root)
+	
+	components.update(production_packages)
+end
+
+private
+
+def fetch_production_packages(package_root)
+	stdout, _status = Open3.capture2(NPM, "ls", "--production", "--json", chdir: package_root.to_s)
+	json = JSON.parse(stdout)
+	
+	flatten_package_dependencies(json).sort.uniq
+end
+
+def flatten_package_dependencies(json, into = [])
+	if json["dependencies"]
+		json["dependencies"].each do |name, details|
+			into << name
+			flatten_package_dependencies(details, into)
+		end
+	end
+	
+	return into
+end

data/context/integrating-with-javascript.md

@@ -17,7 +17,7 @@ $ npm install jquery
 Copy the distribution files to `public/_components`:
 
 ```bash
-$ bundle exec bake utopia:node:update
+$ bundle exec bake utopia:components:update
 ```
 
 This will copy the library's distribution files (typically from `node_modules/*/dist/`) to your `public/_components/` directory, making them available for local serving.

data/context/middleware.md

@@ -167,7 +167,7 @@ This template would typically be designed with supporting `_page.xnode` and `_he
 
 ## Session
 
-The {ruby Utopia::Session} middleware provides session storage using encrypted client-side cookies. The session management uses symmetric private key encryption to store data on the client and avoid tampering.
+The {ruby Utopia::Session} middleware provides session storage using authenticated, encrypted client-side cookies. The session management uses symmetric private key encryption to store data on the client and prevent tampering.
 
 ```ruby
 use Utopia::Session,
@@ -177,7 +177,7 @@ use Utopia::Session,
 	secure: true
 ```
 
-All session data is stored on the client, but it's encrypted with a salt and the secret key. It is impossible for the client to decrypt the data without the secret stored on the server.
+All session data is stored on the client, but it is encrypted and authenticated with a key derived from the secret. The client cannot read or modify the data without the secret stored on the server.
 
 When the middleware is installed, the session is available on the request:
 

data/lib/traces/provider/utopia/content/middleware.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require_relative "../../../../utopia/content/middleware"
+
+require "traces/provider"
+
+Traces::Provider(Utopia::Content::Middleware) do
+	def respond(link, request, localization: request.localization)
+		attributes = {
+			"link.key" => link.key,
+			"link.href" => link.href,
+			"link.locale" => localization&.locale,
+		}
+		
+		Traces.trace("utopia.content.respond", attributes: attributes){super}
+	end
+end

data/lib/traces/provider/utopia/static/middleware.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require_relative "../../../../utopia/static/middleware"
+
+require "traces/provider"
+
+Traces::Provider(Utopia::Static::Middleware) do
+	def respond(request, path, extension, content_type, localization: request.localization)
+		attributes = {
+			path: path,
+			locale: localization&.locale,
+		}
+		
+		Traces.trace("utopia.static.respond", attributes: attributes){super}
+	end
+end

data/lib/traces/provider/utopia.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require_relative "utopia/content/middleware"
+require_relative "utopia/static/middleware"

data/lib/utopia/components.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "fileutils"
+require "json"
+require "pathname"
+
+module Utopia
+	# Installs JavaScript packages from `node_modules` into the public components directory. Package contents are copied from `dist` when it exists, otherwise from the package root.
+	#
+	# By default, the complete source directory is installed. Projects can limit an individual package to a set of files using `utopia.components` in their `package.json` file.
+	class Components
+		# Initialize a component installer for the given project root.
+		#
+		# @parameter root [String | Pathname] The project root directory.
+		def initialize(root)
+			@root = Pathname.new(root)
+			@package_root = @root + "node_modules"
+			
+			@install_root = @root + "public/_components"
+			@configuration = load_configuration
+		end
+		
+		# @attribute [Pathname] The directory containing the installed JavaScript packages.
+		attr :package_root
+		
+		# Update the specified packages in the public components directory.
+		#
+		# @parameter package_names [Array(String)] The production package names to install.
+		def update(package_names)
+			expand_package_paths(@package_root).each do |package_path|
+				package_name = package_path.relative_path_from(@package_root).to_s
+				
+				if package_names.include?(package_name)
+					install(package_name, package_path)
+				end
+			end
+		end
+		
+		private
+		
+		# Load the optional per-package installation rules. A missing `package.json`, or a file without `utopia.components`, preserves the default behaviour of copying complete packages.
+		# @returns [Hash] The per-package installation rules.
+		def load_configuration
+			package_path = @root + "package.json"
+			
+			unless package_path.file?
+				return {}
+			end
+			
+			configuration = JSON.parse(package_path.read).dig("utopia", "components") || {}
+			
+			unless configuration.is_a?(Hash)
+				raise ArgumentError, "utopia.components must be an object!"
+			end
+			
+			return configuration
+		end
+		
+		# Install one package. Distribution directories are preferred because they generally contain the browser-ready form of a package.
+		# @parameter package_name [String] The package name relative to `node_modules`.
+		# @parameter package_path [Pathname] The package source directory.
+		def install(package_name, package_path)
+			install_path = @install_root + package_name
+			dist_path = package_path + "dist"
+			
+			if dist_path.directory?
+				source_path = dist_path
+			else
+				source_path = package_path
+			end
+			
+			configuration = @configuration[package_name]
+			
+			if configuration
+				install_selected(package_name, source_path, install_path, configuration)
+			else
+				FileUtils::Verbose.rm_rf(install_path)
+				FileUtils::Verbose.mkpath(install_path.dirname)
+				FileUtils::Verbose.cp_r(source_path, install_path)
+			end
+		end
+		
+		# Install only the files matched by the configured include patterns. Every pattern is resolved before removing the existing installation, so an invalid configuration cannot leave a package partially installed or remove a previously working copy.
+		# @parameter package_name [String] The package name relative to `node_modules`.
+		# @parameter source_path [Pathname] The package source directory.
+		# @parameter install_path [Pathname] The destination directory.
+		# @parameter configuration [Hash] The package installation rules.
+		def install_selected(package_name, source_path, install_path, configuration)
+			unless configuration.is_a?(Hash)
+				raise ArgumentError, "utopia.components.#{package_name}.include must be a non-empty array!"
+			end
+			
+			include_patterns = configuration["include"]
+			
+			unless include_patterns.is_a?(Array) && include_patterns.any?
+				raise ArgumentError, "utopia.components.#{package_name}.include must be a non-empty array!"
+			end
+			
+			paths = include_patterns.flat_map do |pattern|
+				included_paths(package_name, source_path, pattern)
+			end.uniq.sort
+			
+			FileUtils::Verbose.rm_rf(install_path)
+			
+			paths.each do |relative_path|
+				source_file = source_path + relative_path
+				install_file = install_path + relative_path
+				
+				FileUtils::Verbose.mkpath(install_file.dirname)
+				FileUtils::Verbose.cp(source_file, install_file)
+			end
+		end
+		
+		# Expand one include pattern into files relative to the package source. Directories are excluded so each result can be copied independently.
+		# @parameter package_name [String] The package name used in validation errors.
+		# @parameter source_path [Pathname] The package source directory.
+		# @parameter pattern [String] The include pattern to expand.
+		# @returns [Array(String)] The matching file paths relative to the package source.
+		def included_paths(package_name, source_path, pattern)
+			unless pattern.is_a?(String) && relative_pattern?(pattern)
+				raise ArgumentError, "Invalid include pattern for #{package_name}: #{pattern.inspect}"
+			end
+			
+			paths = Dir.glob(pattern, base: source_path.to_s).select do |relative_path|
+				(source_path + relative_path).file?
+			end
+			
+			if paths.empty?
+				raise ArgumentError, "Include pattern for #{package_name} matched no files: #{pattern.inspect}"
+			end
+			
+			return paths
+		end
+		
+		# Determine whether the pattern is contained within the package source. Absolute paths and parent traversal are rejected because they could otherwise copy arbitrary files from outside the package.
+		# @parameter pattern [String] The include pattern to validate.
+		# @returns [Boolean] Whether the pattern is relative and does not contain parent traversal.
+		def relative_pattern?(pattern)
+			path = Pathname.new(pattern)
+			
+			if path.absolute?
+				return false
+			end
+			
+			if path.each_filename.any?{|component| component == ".."}
+				return false
+			end
+			
+			return true
+		end
+		
+		# Enumerate packages in `node_modules`, descending through scoped package directories such as `@socketry` while preserving their scoped names.
+		# @parameter root [Pathname] The directory to enumerate.
+		# @parameter into [Array(Pathname)] The array into which package paths are appended.
+		# @returns [Array(Pathname)] The discovered package directories.
+		def expand_package_paths(root, into = [])
+			root.children.select(&:directory?).each do |path|
+				basename = path.basename.to_s
+				
+				# Handle organisation sub-directories which start with an '@' symbol:
+				if basename.start_with?("@")
+					expand_package_paths(path, into)
+				else
+					into << path
+				end
+			end
+			
+			return into
+		end
+	end
+end

data/lib/utopia/content/builder.rb

@@ -82,11 +82,7 @@ module Utopia
 			def text(content)
 				return unless content
 				
-				if content.respond_to?(:build_markup)
-					content.build_markup(self)
-				else
-					XRB::Markup.append(@output, content)
-				end
+				content.build_markup(self)
 			end
 			
 			# Write a complete tag to the output.

data/lib/utopia/content/links.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2015-2025, by Samuel Williams.
+# Copyright, 2015-2026, by Samuel Williams.
 
 require_relative "link"
 
@@ -204,8 +204,10 @@ module Utopia
 				def each(locale)
 					return to_enum(:each, locale) unless block_given?
 					
-					ordered.each do |links|
-						yield links.find{|link| link.locale == locale}
+					@named.each_key do |name|
+						if link = lookup(name, locale)
+							yield link
+						end
 					end
 				end
 				

data/lib/utopia/content/markup.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.
 
 require "xrb/parsers"
 require "xrb/entities"
@@ -108,9 +108,9 @@ module Utopia
 				# @returns [String] The resulting string.
 				def to_s
 					if @closing_tag
-						"#{start_location}: #{@opening_tag} was not closed!"
-					else
 						"#{start_location}: #{@opening_tag} was closed by #{@closing_tag}!"
+					else
+						"#{start_location}: #{@opening_tag} was not closed!"
 					end
 				end
 			end

data/lib/utopia/content/middleware.rb

@@ -16,7 +16,6 @@ require_relative "tags"
 
 require "xrb/template"
 require "concurrent/map"
-require "traces/provider"
 
 module Utopia
 	module Content
@@ -66,11 +65,7 @@ module Utopia
 			end
 			
 			attr :root
-			
-			# TODO we should remove this method and expose `@links` directly.
-			def links(path, **options)
-				@links.index(path, **options)
-			end
+			attr :links
 			
 			# Load and cache a content template.
 			# @parameter path [Utopia::Path | String] The path.
@@ -159,12 +154,7 @@ module Utopia
 			private
 			
 			def lookup_content(name, parent_path)
-				if String === name && name.index("/")
-					name = Path.create(name)
-				end
-				
 				if Path === name
-					name = parent_path + name
 					name_path = name.components.dup
 					name_path[-1] += XNODE_EXTENSION
 				else
@@ -195,6 +185,21 @@ module Utopia
 			end
 			
 			def content_tag(name, node, parent_path: node.parent_path)
+				# Preserve nested names while searching the physical content hierarchy:
+				if String === name
+					if name.index("/")
+						name = Path.create(name)
+					end
+				end
+				
+				if Path === name
+					cache_key = parent_path + name
+					
+					return @node_cache.fetch_or_store(cache_key) do
+						lookup_content(name, parent_path)
+					end
+				end
+				
 				full_path = parent_path + name
 				
 				name = full_path.pop
@@ -216,16 +221,5 @@ module Utopia
 			end
 		end
 		
-		Traces::Provider(Middleware) do
-			def respond(link, request, localization: request.localization)
-				attributes = {
-					"link.key" => link.key,
-					"link.href" => link.href,
-					"link.locale" => localization&.locale,
-				}
-				
-				Traces.trace("utopia.content.middleware.respond", attributes: attributes){super}
-			end
-		end
 	end
 end

data/lib/utopia/content/node.rb

@@ -51,14 +51,12 @@ module Utopia
 			def local_path(path = ".", base = nil)
 				path = Path[path]
 				
-				root = Pathname.new(@controller.root)
-				
-				if path.absolute?
-					return root.join(*path.components)
-				else
+				if path.relative?
 					base ||= uri_path.dirname
-					return root.join(*(base + path).components)
+					path = base + path
 				end
+				
+				return Pathname.new(path.to_url_path.local_path(@controller.root))
 			end
 			
 			# Resolve a path relative to this node's containing URI path.
@@ -84,7 +82,7 @@ module Utopia
 			def links(path = ".", **options, &block)
 				path = uri_path.dirname + Path[path]
 				
-				links = @controller.links(path, **options)
+				links = @controller.links.index(path, **options)
 				
 				if block_given?
 					links.each(&block)
@@ -96,7 +94,7 @@ module Utopia
 			# 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)
+				@controller.links.index(@uri_path.dirname, name: @uri_path.basename, indices: true)
 			end
 			
 			# Return the directory whose links are siblings of this node.
@@ -113,7 +111,7 @@ module Utopia
 			# @parameter options [Hash] The options.
 			# @returns [Array(Link)] The sibling links.
 			def sibling_links(**options)
-				return @controller.links(siblings_path, **options)
+				return @controller.links.index(siblings_path, **options)
 			end
 			
 			# Lookup the given tag which is being rendered within the given node. Invoked by {Document}.

data/lib/utopia/controller/rewrite.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2015-2025, by Samuel Williams.
+# Copyright, 2015-2026, by Samuel Williams.
 
 require_relative "../http"
 require_relative "../path/matcher"
@@ -48,6 +48,8 @@ module Utopia
 				# Freeze this object and its internal state.
 				# @returns [self] This object.
 				def freeze
+					return self if frozen?
+					
 					@matcher.freeze
 					@block.freeze
 					

data/lib/utopia/exceptions/application_errors.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+module Utopia
+	module Exceptions
+		# Exceptions raised by application code which can be safely handled and reported.
+		APPLICATION_ERRORS = [StandardError, ScriptError].freeze
+	end
+end

data/lib/utopia/exceptions/handler.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2014-2025, by Samuel Williams.
+# Copyright, 2014-2026, by Samuel Williams.
 # Copyright, 2025, by Olle Jonsson.
 
 require "console"
@@ -9,6 +9,7 @@ require "console"
 require_relative "../middleware"
 require_relative "../request"
 require_relative "../response"
+require_relative "application_errors"
 
 module Utopia
 	module Exceptions
@@ -37,7 +38,7 @@ module Utopia
 			def call(request)
 				begin
 					return @delegate.call(request)
-				rescue Exception => exception
+				rescue *APPLICATION_ERRORS => exception
 					Console.warn(self, "An error occurred while processing the request.", error: exception)
 					
 					begin
@@ -52,7 +53,7 @@ module Utopia
 						error_response.status = 500
 						
 						return error_response
-					rescue Exception => exception
+					rescue *APPLICATION_ERRORS => exception
 						# If redirection fails, we also finish with a fatal error:
 						Console.error(self, "An error occurred while invoking the error handler.", error: exception)
 						return Response[500, {"content-type" => "text/plain"}, ["An error occurred while processing the request."]]