utopia 3.0.4 → 3.0.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3e9f5a6eb41a075cebcde2daf0e8811e1af414776f7807a14e07e9ed228c7657
-  data.tar.gz: 1d566c0e5b68123699f6f33185857ce00e6eb3b1659eae5c0f0b896443a36527
+  metadata.gz: 29332f03b21ff72e75b4f372deb3b317469ff3a5f2991ad363214b144d68ee4d
+  data.tar.gz: 3e3405b9bc409eeaf96e575bbb4f61fceb16298630b63f6069c2f443c2264025
 SHA512:
-  metadata.gz: dc90dd50e914c27b28463992bbe33b0ef52eb077bd666519b876575202cee39babfed39720e2c22b66f3c456460bdcd16446876bb2827714b9665ed72c655ce0
-  data.tar.gz: 18b31ba92269e3340cc385e2a8b953bbe7b75b0db1f7323dd4e00d55faa03ebf71a097a940de69c84183a5115d2e982ba0a8aa2f480ca495a8d2119a93d2aa4f
+  metadata.gz: 4f376ca1d057b6a91002e1abcab1ef98c0754772203c8d44392eca14e41df72b59e79bdb37a81e29624a6e0dd696e71ae63623a3ede9afec76b400825a8063fd
+  data.tar.gz: 4c20f0613d97496fd0fe1c4584384a1022677378b84504173817cdb6f6eb1a5405c440319ee482222e7c1fe7c8eea9401e1f7df89871607be8eeb023c9bf6487

data/context/integrating-with-javascript.md

@@ -8,20 +8,45 @@ Import maps provide a modern way to manage JavaScript module dependencies. Utopi
 
 ### Installing JavaScript Libraries
 
-First, install the library using npm:
+Declare browser libraries as production dependencies in `package.json`. The `bake-node.packages` section selects the files that should be served and assigns their browser import names:
+
+```json
+{
+  "private": true,
+  "dependencies": {
+    "@socketry/syntax": "^0.6.1"
+  },
+  "bake-node": {
+    "packages": {
+      "@socketry/syntax": {
+        "include": [
+          "Syntax.js"
+        ],
+        "imports": {
+          "@socketry/syntax": "Syntax.js"
+        }
+      }
+    }
+  }
+}
+```
+
+Install the dependencies using the configured package manager, then generate the browser-facing package projection:
 
 ```bash
-$ npm install jquery
+$ bundle exec bake node:install
+$ bundle exec bake node:packages:static
 ```
 
-Copy the distribution files to `public/_components`:
+This installs dependencies into `node_modules/` and copies only the selected browser files into `public/_components/`. Treat both directories as generated projections rather than authored source.
+
+Use an immutable installation and verify the checked-in projection in CI:
 
 ```bash
-$ bundle exec bake utopia:components:update
+$ bundle exec bake node:install frozen=true
+$ bundle exec bake node:packages:check
 ```
 
-This will copy the library's distribution files (typically from `node_modules/*/dist/`) to your `public/_components/` directory, making them available for local serving.
-
 ### Creating the Import Map
 
 Create a global import map in `lib/my_website/import_map.rb`:
@@ -30,12 +55,12 @@ Create a global import map in `lib/my_website/import_map.rb`:
 require "utopia/import_map"
 
 module MyWebsite
-	IMPORT_MAP = Utopia::ImportMap.build(base: "/_components/") do |map|
-		map.import("jquery", "./jquery/jquery.js")
-	end
+	IMPORT_MAP = Utopia::ImportMap.load_manifest("public/_components")
 end
 ```
 
+This loads the generated package mappings directly, so the browser import map remains synchronized with `package.json`.
+
 Then load this in `lib/my_website.rb`:
 
 ```ruby
@@ -64,15 +89,16 @@ Once the import map is set up, you can import and use the library in your script
 ```xrb
 <script type="module">
 	// <![CDATA[
-	import $ from 'jquery';
+	import Syntax from '@socketry/syntax';
 	
-	$(document).ready(function() {
-		console.log("jQuery is ready!");
-	});
+	await Syntax.highlight();
 	// ]]>
 </script>
 ```
 
+Inspect the generated import map with `bundle exec bake node:importmap:show` when debugging package resolution.
+
+See the [Bake Node documentation](https://socketry.github.io/bake-node/) for workspace packages, package selection, and alternative package managers.
 
 ### Advanced Import Map Features
 

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/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."]]

data/lib/utopia/exceptions/mailer.rb

@@ -1,14 +1,17 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2016-2025, by Samuel Williams.
+# Copyright, 2016-2026, by Samuel Williams.
 
 require "net/smtp"
 require "mail"
+require "console"
+require "stringio"
+require "yaml"
 
 require_relative "../middleware"
 require_relative "../request"
-require_relative "handler"
+require_relative "application_errors"
 
 module Utopia
 	module Exceptions
@@ -23,20 +26,33 @@ module Utopia
 			
 			DEFAULT_FROM = (ENV["USER"] || "utopia").freeze
 			DEFAULT_SUBJECT = "%{exception} [PID %{pid} : %{cwd}]".freeze
+			ATTACHMENT_SIZE_LIMIT = 64*1024
+			SENSITIVE_FIELD = /authorization|cookie|credential|password|private[_-]?key|referer|referrer|secret|session|token|variables|api[_-]?key/i
+			REDACTED = "[REDACTED]".freeze
 			
 			# @param to [String] The address to email error reports to.
 			# @param from [String] The from address for error reports.
 			# @param subject [String] The subject template which can access attributes defined by `#attributes_for`.
 			# @param delivery_method [Object] The delivery method as required by the mail gem.
-			# @param dump_environment [Boolean] Attach request attributes as `attributes.yaml` to the error report.
-			def initialize(app, to: "postmaster", from: DEFAULT_FROM, subject: DEFAULT_SUBJECT, delivery_method: LOCAL_SMTP, dump_environment: false)
+			# @param dump_body [Boolean] Attach a bounded rewindable request body to the error report.
+			# @param dump_environment [Boolean] Include application state and attach it as `state.yaml`.
+			# @param attachment_size_limit [Integer] The maximum size of each attachment.
+			# @param redact [Regexp | Nil] A pattern matching structured field names whose values should be redacted.
+			def initialize(app, to: "postmaster", from: DEFAULT_FROM, subject: DEFAULT_SUBJECT, delivery_method: LOCAL_SMTP, dump_body: false, dump_environment: false, attachment_size_limit: ATTACHMENT_SIZE_LIMIT, redact: SENSITIVE_FIELD)
 				super(app)
 				
 				@to = to
 				@from = from
 				@subject = subject
 				@delivery_method = delivery_method
+				@dump_body = dump_body
 				@dump_environment = dump_environment
+				@attachment_size_limit = Integer(attachment_size_limit)
+				@redact = redact
+				
+				if @attachment_size_limit < 0
+					raise ArgumentError, "attachment_size_limit must not be negative!"
+				end
 			end
 			
 			# Freeze this object and its internal state.
@@ -48,7 +64,10 @@ module Utopia
 				@from.freeze
 				@subject.freeze
 				@delivery_method.freeze
+				@dump_body.freeze
 				@dump_environment.freeze
+				@attachment_size_limit.freeze
+				@redact.freeze
 				
 				super
 			end
@@ -59,7 +78,7 @@ module Utopia
 			def call(request)
 				begin
 					return @delegate.call(request)
-				rescue => exception
+				rescue *APPLICATION_ERRORS => exception
 					request.exception = exception
 					send_notification exception, request
 					
@@ -99,30 +118,32 @@ module Utopia
 			def generate_body(exception, request)
 				io = StringIO.new
 				
-				io.puts "#{request.method} #{request.url}"
-				
-				# TODO embed the request body if it's textual?
-				# TODO dump and embed `utopia.variables`?
+				# Do not include the raw query string, as it may contain sensitive values:
+				io.puts "#{request.method} #{request.url.path.encoded}"
 				
 				io.puts
 				
 				REQUEST_ATTRIBUTES.each do |key|
-					value = request.send(key)
+					value = redact(key, request.send(key))
 					io.puts "request.#{key}: #{value.inspect}"
 				end
 				
 				request.query_parameters.each do |key, value|
+					value = redact(key, value)
 					io.puts "request.query_parameters.#{key}: #{value.inspect}"
 				end
 				
 				io.puts
 				
 				request.headers.each do |key, value|
+					value = redact(key, value)
 					io.puts "header[#{key.inspect}]: #{value.inspect}"
 				end
 				
-				self.current_state(request).each do |key, value|
-					io.puts "state.#{key}: #{value.inspect}"
+				if @dump_environment
+					filtered_state(request).each do |key, value|
+						io.puts "state.#{key}: #{value.inspect}"
+					end
 				end
 				
 				io.puts
@@ -150,12 +171,14 @@ module Utopia
 				mail.text_part = Mail::Part.new
 				mail.text_part.body = generate_body(exception, request)
 				
-				if body = extract_body(request) and body.size > 0
-					mail.attachments["body.bin"] = body
+				if @dump_body
+					if body = extract_body(request, @attachment_size_limit)
+						mail.attachments["body.bin"] = body
+					end
 				end
 				
 				if @dump_environment
-					mail.attachments["state.yaml"] = YAML.dump(self.current_state(request))
+					attach(mail, "state.yaml", YAML.dump(filtered_state(request)))
 				end
 				
 				return mail
@@ -168,8 +191,7 @@ module Utopia
 				
 				mail.deliver
 			rescue => mail_exception
-				$stderr.puts mail_exception.to_s
-				$stderr.puts mail_exception.backtrace
+				Console.warn(self, "Failed to deliver exception notification.", error: mail_exception)
 			end
 			
 			def current_state(request)
@@ -181,11 +203,51 @@ module Utopia
 				}
 			end
 			
-			def extract_body(request)
+			def filtered_state(request)
+				redact(nil, current_state(request))
+			end
+			
+			def redact(name, value)
+				if @redact && name
+					if @redact.match?(name.to_s)
+						return REDACTED
+					end
+				end
+				
+				case value
+				when Hash
+					return value.to_h do |key, item|
+						[key, redact(key, item)]
+					end
+				when Array
+					return value.map{|item| redact(nil, item)}
+				else
+					return value
+				end
+			end
+			
+			def attach(mail, name, content)
+				if content.bytesize <= @attachment_size_limit
+					mail.attachments[name] = content
+				end
+			end
+			
+			def extract_body(request, size_limit)
 				body = request.body
 				
 				if body&.rewindable? && body.rewind
-					return body.join
+					buffer = String.new.b
+					
+					body.each do |chunk|
+						# Do not retain a partial body when the complete attachment would exceed the limit:
+						if chunk.bytesize > size_limit - buffer.bytesize
+							return nil
+						end
+						
+						buffer << chunk
+					end
+					
+					return buffer unless buffer.empty?
 				end
 			end
 		end

data/lib/utopia/import_map.rb

@@ -6,6 +6,7 @@
 require "json"
 require "xrb"
 require "protocol/url"
+require "bake/node/manifest"
 
 module Utopia
 	# Represents an import map for JavaScript modules with support for URI and relative path resolution.
@@ -55,6 +56,19 @@ module Utopia
 	# 	
 	# 	puts page_map.to_html
 	class ImportMap
+		# Load the import mappings from a Bake Node static package manifest.
+		# @parameter root [String | Pathname] The static package output directory.
+		# @returns [ImportMap] A frozen import map using the manifest's public base URL.
+		def self.load_manifest(root)
+			manifest = Bake::Node::Manifest.load(root)
+			base = Protocol::URL[manifest.data.fetch("base")]
+			imports = manifest.import_map.fetch("imports").transform_values do |value|
+				Protocol::URL[value].relative_to(base).to_s
+			end
+			
+			return self.new(imports, base: base).freeze
+		end
+		
 		# Builder class for constructing import maps with scoped base URIs.
 		#
 		# The builder supports nested `with(base:)` blocks where each base is resolved