Add protocol HTTP application boundary.

.gitattributes

@@ -0,0 +1 @@
+*.body -text

bake/utopia/site.rb

@@ -18,7 +18,7 @@ def initialize(...)
 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", "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"]

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

config/external.yaml

@@ -1,6 +1,4 @@
 utopia-project:
   url: https://github.com/socketry/utopia-project.git
-  command: bundle exec bake test
-www.codeotaku.com:
-  url: https://github.com/ioquatix/www.codeotaku.com.git
+  branch: v3-protocol-application
   command: bundle exec bake test

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!
 

context/index.yaml

@@ -13,7 +13,7 @@ files:
     and deployment.
 - path: middleware.md
   title: Middleware
-  description: This guide gives an overview of the different Rack middleware used
+  description: This guide gives an overview of the different middleware used
     by Utopia.
 - path: server-setup.md
   title: Server Setup

context/middleware.md

@@ -1,10 +1,10 @@
 # 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,
@@ -36,7 +36,7 @@ use Utopia::Redirection::Errors,
 
 ## 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 +53,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
 
@@ -90,7 +90,7 @@ def passthrough(request, path)
 
 	# Succeed the request and immediately respond.
 	# def succeed!(status: 200, headers: {}, **options)
-	# options may include content: string or body: Enumerable (as per Rack specifications
+	# options may include content: String or body: Enumerable.
 
 	suceed!
 end
@@ -108,7 +108,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 +155,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
+```

gems.rb

@@ -21,7 +21,6 @@
 
 group :development do
 	gem "json"
-	gem "rackula"
 end
 
 group :test do
@@ -32,14 +31,13 @@
 	gem "rubocop-md"
 	gem "rubocop-socketry"
 
-	gem "falcon"
+	gem "falcon", "~> 0.57"
 	gem "async-websocket"
 	gem "sus-fixtures-async-http"
+	gem "sus-fixtures-protocol-http", "~> 0.1"
 
 	gem "bake-test"
 	gem "bake-test-external"
 
 	gem "benchmark-ips"
-
-	gem "rack-test"
 end

guides/getting-started/readme.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!
 

guides/middleware/readme.md

@@ -1,10 +1,10 @@
 # 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,
@@ -36,7 +36,7 @@ use Utopia::Redirection::Errors,
 
 ## 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 +53,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 +73,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 +85,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 +127,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 +174,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
+```

lib/utopia.rb

@@ -5,6 +5,7 @@
 
 require_relative "utopia/version"
 
+require_relative "utopia/application"
 require_relative "utopia/import_map"
 require_relative "utopia/content"
 require_relative "utopia/controller"