utopia 2.32.1 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 39b95a5f8c45c77816846900c9d99e7bb306bdbc589c60b10e71d045260d6107
-  data.tar.gz: 1c82a315db0de1c3738c6a03a4569fadaaf0aa031850f672976b29f71fd70087
+  metadata.gz: b0a73ea69813127b09be72632c42f1ce6a6a4e94678c823575125223ae19b520
+  data.tar.gz: 8c50126b47f9184bce9237dade14818cf70d959f0aae2fb34f8fb486a22a0d0d
 SHA512:
-  metadata.gz: 01e866be2be3f5465b69a1de18ef976b2e4edbaa5facc9a168291e87965039afdc149df0157b7f50236ecd453a86b2ad93d34e548809dc3ae08b44c4a21a62f6
-  data.tar.gz: d8c87f177f7572795bf416c9ec6b560e2b3e357446c86d0853b8f47094d56e46413b112953b53bfa2cc27b6abc15baa3973f2862d21928f8056b46947cd66419
+  metadata.gz: 12bf144743c5b6cae0f147e60d37815c081025a86c6ac7c4146fbb392087819ddafa80c431579855ddd1e7b565fbc24a00902df3bc56222e6d218e48e5eade98
+  data.tar.gz: 76d0216724af21e389d71b6236ab36ebf5810f6365a536f000e6601d83c8df03a451a9e5eecc2cdcb045c8c1b206018a02a4762433e2e6b227a1508dd6df34f2

checksums.yaml.gz.sig

@@ -1 +1 @@
-�Vҿ�Op�ғ����9�ر5��Z�m��Jn#jP���":���9q[�#����e]e�b��ܿ�ۤ���� ԁ��9	ſj�\�1����]MV?C�K�t=�V���P//�
+<,z��x��f�����e�>z�r<��(���nI7r�_`���8ҍ��,+8�/���N�",4RD���0�I7T�]Ձ2]�%�0��q�E��2�P�ډ��/xA{coXK������)bѐ�9I(?�!}?~2qOҿt���}�mTcv%+�u���n��0X������n�z����{ʣA�/U���޽�M���nw_�+�md�3G�9'T87�GeA|��*�e�6J�[
>��2L�Z,7TC���p��&U-�x�%ۤ�c<#����d�4DŽ�������Hé�\�

data/bake/utopia/environment.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2018-2025, by Samuel Williams.
+# Copyright, 2018-2026, by Samuel Williams.
 
 # Update environment variables in config/environment.yaml
 def initialize(...)
@@ -24,7 +24,7 @@ end
 # @parameter root [String] The root directory of the project.
 def defaults(name, root: context.root)
 	update_environment(root, name) do |store|
-		Console.info(self) {"Setting up defaults for environment #{name}..."}
+		Console.info(self){"Setting up defaults for environment #{name}..."}
 		# Set some useful defaults for the environment.
 		store["UTOPIA_SESSION_SECRET"] ||= SecureRandom.hex(40)
 	end
@@ -40,10 +40,10 @@ def update(name, root: context.root, **variables)
 			key = key.to_s
 			
 			if value && !value.empty?
-				Console.info(self) {"ENV[#{key.inspect}] will default to #{value.inspect} unless otherwise specified."}
+				Console.info(self){"ENV[#{key.inspect}] will default to #{value.inspect} unless otherwise specified."}
 				store[key] = value
 			else
-				Console.info(self) {"ENV[#{key.inspect}] will be unset unless otherwise specified."}
+				Console.info(self){"ENV[#{key.inspect}] will be unset unless otherwise specified."}
 				store.delete(key)
 			end
 		end
@@ -63,10 +63,10 @@ def read(name, root: context.root)
 	environment_path = self.environment_path(root, name)
 	
 	if File.exist?(environment_path)
-		Console.debug(self) {"Loading environment #{name} from #{environment_path}..."}
+		Console.debug(self){"Loading environment #{name} from #{environment_path}..."}
 		YAML.load_file(environment_path)
 	else
-		Console.debug(self) {"No environment #{name} found at #{environment_path}."}
+		Console.debug(self){"No environment #{name} found at #{environment_path}."}
 		{}
 	end
 end

data/bake/utopia/server.rb

@@ -31,7 +31,10 @@ SERVER_ROOT = File.join(SETUP_ROOT, "server")
 def update(root: context.root)
 	# It's okay to call this on an existing repo, it will only update config as required to enable --shared.
 	# --shared allows multiple users to access the site with the same group.
-	system("git", "init", "--shared", chdir: root) or fail "could not initialize repository"
+	arguments = ["git", "init", "--shared"]
+	arguments << "--initial-branch=main" unless File.exist?(File.join(root, ".git"))
+	
+	system(*arguments, chdir: root) or fail "could not initialize repository"
 	
 	system("git", "config", "receive.denyCurrentBranch", "ignore", chdir: root) or fail "could not set configuration"
 	system("git", "config", "core.worktree", root, chdir: root) or fail "could not set configuration"

data/bake/utopia/site.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2017-2025, by Samuel Williams.
+# Copyright, 2017-2026, by Samuel Williams.
 # Copyright, 2020, by Michael Adams.
 
 def initialize(...)
@@ -18,20 +18,20 @@ end
 SETUP_ROOT = File.expand_path("../../setup", __dir__)
 
 # Configuration files which should be installed/updated:
-CONFIGURATION_FILES = [".gitignore", "config.ru", "config/environment.rb", "falcon.rb", "gems.rb", "Guardfile", "bake.rb", "test/website.rb", "fixtures/website.rb"]
+CONFIGURATION_FILES = [".gitignore", "config/application.rb", "config/environment.rb", "config/serve.rb", "falcon.rb", "gems.rb", "bake.rb", "test/website.rb", "fixtures/website.rb"]
 
 # Directories that should exist:
 DIRECTORIES = ["config", "lib", "pages", "public", "bake", "fixtures", "test"]
 
 # Directories that should be removed during upgrade process:
-OLD_PATHS = ["access_log", "cache", "tmp", "Rakefile", "tasks", ".bowerrc"]
+OLD_PATHS = ["access_log", "cache", "tmp", "Rakefile", "tasks", ".bowerrc", "Guardfile"]
 
 # The root directory of the template site:
 SITE_ROOT = File.join(SETUP_ROOT, "site")
 
 # Create a new local Utopia website using the default template.
 def create(root: context.root)
-	Console.debug(self) {"Setting up site in #{root} for Utopia v#{Utopia::VERSION}..."}
+	Console.debug(self){"Setting up site in #{root} for Utopia v#{Utopia::VERSION}..."}
 	
 	DIRECTORIES.each do |directory|
 		FileUtils.mkdir_p(File.join(root, directory))
@@ -57,9 +57,9 @@ def create(root: context.root)
 		
 		if File.exist?(destination_path)
 			buffer = File.read(destination_path).gsub("$UTOPIA_VERSION", Utopia::VERSION)
-			File.open(destination_path, "w") {|file| file.write(buffer)}
+			File.open(destination_path, "w"){|file| file.write(buffer)}
 		else
-			Console.warn(self) {"Could not open #{destination_path}, maybe it should be removed from CONFIGURATION_FILES?"}
+			Console.warn(self){"Could not open #{destination_path}, maybe it should be removed from CONFIGURATION_FILES?"}
 		end
 	end
 	
@@ -67,10 +67,10 @@ def create(root: context.root)
 	
 	context.lookup("utopia:environment:setup").call(root: root)
 	
-	if !File.exist?(".git")
-		Console.info(self) {"Setting up git repository..."}
+	if !File.exist?(File.join(root, ".git"))
+		Console.info(self){"Setting up git repository..."}
 		
-		system("git", "init", chdir: root) or warn "could not create git repository"
+		system("git", "init", "--initial-branch=main", chdir: root) or warn "could not create git repository"
 		system("git", "add", ".", chdir: root) or warn "could not add all files"
 		system("git", "commit", "-q", "-m", "Initial Utopia v#{Utopia::VERSION} site.", chdir: root) or warn "could not commit files"
 	end
@@ -95,7 +95,7 @@ end
 def upgrade(root: context.root)
 	message = "Upgrade to utopia v#{Utopia::VERSION}."
 	
-	Console.info(self) {"Upgrading #{root}..."}
+	Console.info(self){"Upgrading #{root}..."}
 	
 	commit_changes(root, message) do
 		DIRECTORIES.each do |directory|
@@ -106,7 +106,7 @@ def upgrade(root: context.root)
 			path = File.join(root, path)
 			
 			if File.exist?(path)
-				Console.info(self) {"Removing #{path}..."}
+				Console.info(self){"Removing #{path}..."}
 				FileUtils.rm_rf(path)
 			end
 		end
@@ -115,11 +115,11 @@ def upgrade(root: context.root)
 			source_path = File.join(SITE_ROOT, configuration_file)
 			destination_path = File.join(root, configuration_file)
 			
-			Console.info(self) {"Updating #{destination_path}..."}
+			Console.info(self){"Updating #{destination_path}..."}
 			
 			FileUtils.copy_entry(source_path, destination_path)
 			buffer = File.read(destination_path).gsub("$UTOPIA_VERSION", Utopia::VERSION)
-			File.open(destination_path, "w") {|file| file.write(buffer)}
+			File.open(destination_path, "w"){|file| file.write(buffer)}
 		end
 		
 		context.lookup("utopia:environment:setup").call(root: root)
@@ -166,7 +166,7 @@ def move_static!(root)
 		if File.lstat(new_static_path).symlink?
 			FileUtils.rm_f new_static_path
 		else
-			Console.warn(self) {"Can't move pages/_static to public/_static, destination already exists."}
+			Console.warn(self){"Can't move pages/_static to public/_static, destination already exists."}
 			return
 		end
 	end

data/bake/utopia/static.rb

@@ -3,22 +3,29 @@
 # Released under the MIT License.
 # Copyright, 2017-2025, by Samuel Williams.
 
-def generate(output_path: "static")
+# Generate a static copy of the application.
+# @parameter output_path [String] The output path for the generated site.
+# @parameter application_path [String] The application configuration path.
+# @parameter public_path [String] The public assets path.
+# @parameter force [Boolean] Remove the output directory before generating the site.
+def generate(output_path: "static", application_path: "config/application.rb", public_path: "public", force: true)
 	require "falcon/server"
-	require "async/io"
 	require "async/http/endpoint"
 	require "async/container"
+	require "fileutils"
+	require "utopia/application"
 	
-	config_path = File.join(Dir.pwd, "config.ru")
+	application_path = File.expand_path(application_path, Dir.pwd)
+	public_path = File.expand_path(public_path, Dir.pwd)
 	container_class = Async::Container::Threaded
 	server_port = 9090
 	
-	app, options = Rack::Builder.parse_file(config_path)
+	app = Utopia::Application.load(application_path)
 	
-	container = container_class.run(count: 2) do
+	container = container_class.run(count: 1) do
 		Async do
 			server = Falcon::Server.new(
-				Falcon::Server.middleware(app),
+				Falcon::Server.protocol_middleware(app),
 				Async::HTTP::Endpoint.parse("http://localhost:#{server_port}")
 			)
 			
@@ -28,17 +35,23 @@ def generate(output_path: "static")
 	
 	output_path = File.expand_path(output_path, Dir.pwd)
 	
-	# Delete any existing stuff:
-	FileUtils.rm_rf(output_path)
+	# Delete existing output when explicitly requested:
+	if force
+		FileUtils.rm_rf(output_path)
+	end
 	
 	# Copy all public assets:
 	FileUtils::Verbose.mkpath(output_path)
-	Dir.glob(File.join(Dir.pwd, "public/*")) do |path|
+	Dir.glob(File.join(public_path, "*")) do |path|
 		FileUtils::Verbose.cp_r(path, output_path)
 	end
 	
-	# Generate HTML pages:
-	system("wget", "--mirror", "--recursive", "--continue", "--convert-links", "--adjust-extension", "--no-host-directories", "--directory-prefix", output_path.to_s, "http://localhost:#{server_port}")
-	
-	container.stop
+	begin
+		# Generate HTML pages:
+		unless system("wget", "--mirror", "--recursive", "--continue", "--convert-links", "--adjust-extension", "--no-host-directories", "--directory-prefix", output_path.to_s, "http://localhost:#{server_port}")
+			raise "Static site generation failed!"
+		end
+	ensure
+		container.stop
+	end
 end

data/bake/utopia.rb

@@ -15,5 +15,5 @@ end
 def development
 	self.environment
 	
-	exec("guard", "-g", "development")
+	exec("falcon", "serve")
 end

data/context/getting-started.md

@@ -4,7 +4,7 @@ This guide explains how to set up a `utopia` website for local development and d
 
 ## Installation
 
-Utopia is built on Ruby and Rack. Therefore, Ruby (suggested 2.0+) should be installed and working. Then, to install `utopia` and all required dependencies, run:
+Utopia is built on Ruby. Therefore, Ruby should be installed and working. Then, to install `utopia` and all required dependencies, run:
 
 ~~~ bash
 $ gem install utopia
@@ -32,10 +32,12 @@ You will now have a basic template site running on `https://localhost:9292`.
 Utopia includes a redirection middleware to redirect all root-level requests to a given URI. The default being `/welcome/index`:
 
 ```ruby
-# in config.ru
+# in config/application.rb
 
-use Utopia::Redirection::Rewrite,
-	"/" => "/welcome/index"
+Application = Utopia::Application.build do
+	use Utopia::Redirection::Rewrite,
+		"/" => "/welcome/index"
+end
 ```
 
 The content for this page is stored in `pages/welcome/index.xnode`. The format of this page is a subset of HTML5 - open and close tags are strictly enforced.
@@ -84,7 +86,7 @@ website
 
 Least Coverage:
 pages/_page.xnode: 6 lines not executed!
-config.ru: 4 lines not executed!
+config/application.rb: 4 lines not executed!
 pages/welcome/index.xnode: 2 lines not executed!
 pages/_heading.xnode: 1 lines not executed!
 

data/context/index.yaml

@@ -13,8 +13,7 @@ files:
     and deployment.
 - path: middleware.md
   title: Middleware
-  description: This guide gives an overview of the different Rack middleware used
-    by Utopia.
+  description: This guide gives an overview of the different middleware used by Utopia.
 - path: server-setup.md
   title: Server Setup
   description: This guide explains how to deploy a `utopia` web application.

data/context/middleware.md

@@ -1,16 +1,16 @@
 # Middleware
 
-This guide gives an overview of the different Rack middleware used by Utopia.
+This guide gives an overview of the different middleware used by Utopia.
 
 ## Static
 
-The {ruby Utopia::Static} middleware services static files efficiently. By default, it works with `Rack::Sendfile` and supports `ETag` based caching. Normally, you'd prefer to put static files into `public/_static` but it's also acceptable to put static content into `pages/` if it makes sense.
+The {ruby Utopia::Static} middleware services static files efficiently and supports `ETag` based caching. Normally, you'd prefer to put static files into `public/_static` but it's also acceptable to put static content into `pages/` if it makes sense.
 
 ~~~ ruby
 use Utopia::Static,
 	# The root path to serve files from:
 	root: "path/to/root",
-	# The mime-types to recognize/serve:
+	# The file extension groups to recognize/serve:
 	types: [:default, :xiph],
 	# Cache-Control header for files:
 	cache_control: 'public, max-age=7200'
@@ -29,14 +29,18 @@ use Utopia::Redirection::Rewrite,
 use Utopia::Redirection::DirectoryIndex,
 	index: 'index.html'
 
-# Redirect (error) status codes to actual pages:
+~~~
+
+Place {ruby Utopia::Redirection::Errors} after all client-visible redirection middleware. It maps unhandled error responses to internal error documents while retaining the original response status. Because its internal requests invoke the downstream application directly, redirects configured before it are bypassed:
+
+~~~ ruby
 use Utopia::Redirection::Errors,
 	404 => '/errors/file-not-found'
 ~~~
 
 ## Localization
 
-The {ruby Utopia::Localization} middleware provides non-intrusive localization on top of the controller and view layers. The middleware uses the `accept-language` header to guess the preferred locale out of the given options. If a request path maps to a resource, that resource is returned. Otherwise, a non-localized request is made.
+The {ruby Utopia::Localization} middleware computes immutable localization preferences from the request path, host, and `accept-language` header. Localization-aware resource middleware, including {ruby Utopia::Static} and {ruby Utopia::Content}, resolves those preferences without invoking controllers more than once. Place the localization middleware before those resources in the middleware stack.
 
 ~~~ ruby
 use Utopia::Localization,
@@ -53,7 +57,7 @@ pages/index.ja.xnode
 pages/index.zh.xnode
 ~~~
 
-You can also access the current locale in the view via {ruby Utopia::Content::Node::Context#localization}.
+You can access the selected locale in a view using `localization.locale`. Controllers can inspect the request preferences using `request.localization`.
 
 ## Controller
 
@@ -73,7 +77,7 @@ A controller is a file within the specified root directory (typically `pages`) w
 def passthrough(request, path)
 	# Call one of:
 	
-	# This will cause the middleware to generate a response.
+	# Respond immediately with a complete Protocol::HTTP::Response.
 	# def respond!(response)
 	
 	# This will cause the controller to skip the request.
@@ -85,17 +89,36 @@ def passthrough(request, path)
 	# Controller relative redirect.
 	# def goto!(target, status = 302)
 	
-	# Respond with an error which indiciates some kind of failure.
+	# Respond with an error which indicates some kind of failure.
 	# def fail!(error = 400, message = nil)
 	
-	# Succeed the request and immediately respond.
-	# def succeed!(status: 200, headers: {}, **options)
-	# options may include content: string or body: Enumerable (as per Rack specifications
+	# Succeed with a semantic value which the Respond layer serializes.
+	# def succeed!(value = nil, status: 200, headers: {})
 	
-	suceed!
+	succeed!
 end
 ```
 
+Controllers which return semantic values should prepend {ruby Utopia::Controller::Respond} and configure serializers. Serializer blocks return wire-ready response bodies, so they can return streaming {ruby Protocol::HTTP::Body::Readable} objects without buffering them.
+
+```ruby
+prepend Utopia::Controller::Respond, Utopia::Controller::Actions
+
+responds.with("application/json") do |media_range, value|
+	JSON.dump(value)
+end
+
+on "show" do
+	succeed!({"name" => "Samuel"})
+end
+```
+
+Use `respond!` when a controller has already constructed a complete response and no content negotiation is required:
+
+```ruby
+respond! Utopia::Response[200, {"content-type" => "text/plain"}, ["Hello World"]]
+```
+
 The controller layer can do more complex operations by prepending modules into it.
 
 ```ruby
@@ -108,7 +131,7 @@ end
 
 on "edit" do |request, path|
 	if request.post?
-		@user.update_attributes(request[:user])
+		@user.update_attributes(parse_body(request)["user"])
 	end
 end
 
@@ -155,3 +178,9 @@ use Utopia::Session,
 ```
 
 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.
+
+When the middleware is installed, the session is available on the request:
+
+```ruby
+request.session[:user_id] = user.id
+```

data/lib/utopia/application.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "protocol/http/middleware"
+require "protocol/http/middleware/builder"
+
+require_relative "request"
+require_relative "response"
+
+module Utopia
+	# The protocol-facing entrypoint for a Utopia application.
+	#
+	# This object accepts {Protocol::HTTP::Request} instances, dispatches to the
+	# Utopia application stack, and normalizes the result back to a
+	# {Protocol::HTTP::Response}.
+	class Application < Protocol::HTTP::Middleware
+		PATH = "config/application.rb".freeze
+		
+		# Build a Utopia application stack using the protocol HTTP middleware builder.
+		# @parameter default_app [Protocol::HTTP::Middleware] The default application used when the block does not call `run`.
+		# @parameter block [Proc] The middleware builder block.
+		# @returns [Application] The protocol-facing Utopia application.
+		def self.build(default_app = Response::NotFound, &block)
+			builder = Protocol::HTTP::Middleware::Builder.new(default_app)
+			
+			if block
+				if block.arity.zero?
+					builder.instance_exec(&block)
+				else
+					block.call(builder)
+				end
+			end
+			
+			return self.new(builder.to_app)
+		end
+		
+		# Build the default Utopia application.
+		# @returns [Application] The default protocol-facing Utopia application.
+		def self.default
+			self.build
+		end
+		
+		# Load a Utopia application from a conventional configuration file.
+		#
+		# If the file defines an `Application` constant, it will be returned
+		# directly. If the constant is a class, it will be instantiated.
+		# If the file does not exist, or does not define `Application`, the default
+		# application is returned.
+		#
+		# @parameter path [String] The application configuration path.
+		# @parameter options [Hash] Options passed to the application constructor.
+		# @returns [Protocol::HTTP::Middleware] The loaded protocol-facing application.
+		def self.load(path = PATH, **options)
+			if File.exist?(path)
+				top = Module.new
+				top.class_eval(File.read(path), path)
+				
+				if top.const_defined?(:Application, false)
+					application = top.const_get(:Application)
+					
+					if application.is_a?(Class)
+						return application.new(**options)
+					else
+						return application
+					end
+				end
+			end
+			
+			return self.default
+		end
+		
+		# Process a protocol HTTP request.
+		# @parameter request [Protocol::HTTP::Request] The incoming protocol request.
+		# @returns [Protocol::HTTP::Response] The normalized protocol response.
+		def call(request)
+			request = Request.new(request)
+			
+			return Response.wrap(super(request))
+		end
+	end
+end

data/lib/utopia/content/builder.rb

@@ -11,6 +11,11 @@ module Utopia
 		
 		# A builder for rendering Utopia content that extends XRB::Builder with Utopia-specific functionality.
 		class Builder < XRB::Builder
+			# Initialize rendering state for a content node.
+			# @parameter parent [Builder | Nil] The enclosing builder state.
+			# @parameter tag [XRB::Tag | Nil] The tag that opened this state.
+			# @parameter node [Utopia::Content::Node] The content node.
+			# @parameter attributes [Hash] The attributes.
 			def initialize(parent, tag, node, attributes = tag.to_hash, **options)
 				super(**options)
 				
@@ -35,16 +40,26 @@ module Utopia
 			
 			attr :deferred
 			
+			# Insert a deferred-content marker and retain its rendering block.
+			# @parameter value [Object | Nil] An unused compatibility argument.
+			# @yields {|document| ...} The deferred rendering operation.
+			# @returns [String] The closed deferred-content tag.
 			def defer(value = nil, &block)
 				@deferred << block
 				
 				XRB::Tag.closed(DEFERRED_TAG_NAME, :id => @deferred.size - 1)
 			end
 			
+			# Fetch an attribute for the current content node.
+			# @parameter key [String | Symbol] The lookup key.
+			# @returns [Object | Nil] The attribute value.
 			def [](key)
 				@attributes[key]
 			end
 			
+			# Render this node's captured content into a document.
+			# @parameter document [Utopia::Content::Document] The content document.
+			# @returns [String] The rendered output buffer.
 			def call(document)
 				@content = @output.dup
 				@output.clear
@@ -74,6 +89,9 @@ module Utopia
 				end
 			end
 			
+			# Write a complete tag to the output.
+			# @parameter tag [XRB::Tag] The tag.
+			# @returns [String] The output buffer.
 			def tag_complete(tag)
 				tag.write(@output)
 			end
@@ -83,11 +101,18 @@ module Utopia
 				@tags.empty?
 			end
 			
+			# Tag begin.
+			# @parameter tag [XRB::Tag] The opening tag.
+			# @returns [String] The output buffer.
 			def tag_begin(tag)
 				@tags << tag
 				tag.write_opening_tag(@output)
 			end
 			
+			# Tag end.
+			# @parameter tag [XRB::Tag] The closing tag.
+			# @returns [String] The output buffer.
+			# @raises [UnbalancedTagError] If the closing tag does not match the most recent opening tag.
 			def tag_end(tag)
 				raise UnbalancedTagError.new(tag) unless @tags.pop.name == tag.name
 				tag.write_closing_tag(@output)