falcon 0.54.3 → 0.55.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 22b09155428d4918e4f5b81cc0b809a8ca678f2509fbfb42f7e67cb2621d74dc
-  data.tar.gz: df9bbb12499685689dd38a38ede8807f5f09022394c13386766a178bc0760962
+  metadata.gz: 8aa8fb7fb61e5c4112b6e7e3423a59e27a0f00555edd04ab381ca58f064b10cd
+  data.tar.gz: a8a3a69df547475b9fd306f0bedd3e0f4836f1d3f42be43f1f6b1d53746b82e5
 SHA512:
-  metadata.gz: 8a483823b106bf170b158c70f797e3cbb1a233fc74b7be20d7deed8d8d0b690b1f5945330a64b9c5245978759f91fee7b14b1dbf35ede89021a0c6e902a652f2
-  data.tar.gz: 4707fbfbbe508fa06e32815c6ed5e0ba3d6ebc279af9f1460a9be633e86aecc8a05b49919f885ff848c50cd3bc2d8b058671622c44b7b95ee4119c91f1746155
+  metadata.gz: 2dca19722a68b6bd56f1caf3639cc5b4f952a6d908a5e2e36f10cf1e6a3e733d1d423c1713dab0ac8dc5e1adc595d2d6acb345a24d868c85e1b6ca706164fd00
+  data.tar.gz: 6d1ffeb9711b90027841489a348322fe955004cab78a2aa5a26a6ec61be6613013dc33d87b675776338b91aa2715cf3423959e05947e8e3ff42e886e50727666

data/context/deployment.md

@@ -24,7 +24,7 @@ Here is a basic example which hosts a rack application:
 
 require "falcon/environment/rack"
 require "falcon/environment/lets_encrypt_tls"
-require "falcon/environment/supervisor"
+require "async/service/supervisor"
 
 hostname = File.basename(__dir__)
 service hostname do
@@ -35,11 +35,11 @@ service hostname do
 	cache true
 	
 	# Connect to the supervisor for monitoring.
-	include Async::Container::Supervisor::Supervised
+	include Async::Service::Supervisor::Supervised
 end
 
 service "supervisor" do
-	include Falcon::Environment::Supervisor
+	include Async::Service::Supervisor::Environment
 	
 	monitors do
 		[
@@ -71,7 +71,7 @@ The environment configuration is defined in the `Falcon::Environment` module. Th
 # frozen_string_literal: true
 
 require "falcon/environment/rack"
-require "falcon/environment/supervisor"
+require "async/service/supervisor"
 
 hostname = File.basename(__dir__)
 service hostname do
@@ -86,7 +86,7 @@ service hostname do
 end
 
 service "supervisor" do
-	include Falcon::Environment::Supervisor
+	include Async::Service::Supervisor::Environment
 end
 ~~~
 

data/lib/falcon/command/host.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2019-2024, by Samuel Williams.
+# Copyright, 2019-2026, by Samuel Williams.
 
 require_relative "paths"
 require_relative "../version"
@@ -31,7 +31,7 @@ module Falcon
 			
 			# Prepare the environment and run the controller.
 			def call
-				Console.logger.info(self) do |buffer|
+				Console.info(self) do |buffer|
 					buffer.puts "Falcon Host v#{VERSION} taking flight!"
 					buffer.puts "- Configuration: #{@paths.join(', ')}"
 					buffer.puts "- To terminate: Ctrl-C or kill #{Process.pid}"

data/lib/falcon/command/paths.rb

@@ -1,9 +1,9 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2020-2024, by Samuel Williams.
+# Copyright, 2020-2026, by Samuel Williams.
 
-require_relative "../configuration"
+require "async/service/configuration"
 
 module Falcon
 	module Command
@@ -21,7 +21,7 @@ module Falcon
 			
 			# Build a configuration based on the resolved paths.
 			def configuration
-				configuration = Configuration.new
+				configuration = Async::Service::Configuration.new
 				
 				self.resolved_paths do |path|
 					path = File.expand_path(path)

data/lib/falcon/command/proxy.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2020-2024, by Samuel Williams.
+# Copyright, 2020-2026, by Samuel Williams.
 
 require_relative "../environment/proxy"
 require_relative "paths"
@@ -31,6 +31,9 @@ module Falcon
 			
 			include Paths
 			
+			# Create the environment for the proxy service.
+			# @parameter options [Hash] Additional options to pass to the environment.
+			# @returns [Async::Service::Environment] The configured proxy environment.
 			def environment(**options)
 				Async::Service::Environment.new(Falcon::Environment::Proxy).with(
 					root: Dir.pwd,
@@ -42,15 +45,17 @@ module Falcon
 				)
 			end
 			
+			# Build the service configuration for the proxy.
+			# @returns [Async::Service::Configuration] The service configuration.
 			def configuration
-				Configuration.for(
+				Async::Service::Configuration.for(
 					self.environment(environments: super.environments)
 				)
 			end
 			
 			# Prepare the environment and run the controller.
 			def call
-				Console.logger.info(self) do |buffer|
+				Console.info(self) do |buffer|
 					buffer.puts "Falcon Proxy v#{VERSION} taking flight!"
 					buffer.puts "- Binding to: #{@options[:bind]}"
 					buffer.puts "- To terminate: Ctrl-C or kill #{Process.pid}"

data/lib/falcon/command/redirect.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2020-2024, by Samuel Williams.
+# Copyright, 2020-2026, by Samuel Williams.
 
 require_relative "../environment/redirect"
 require_relative "paths"
@@ -10,6 +10,9 @@ require "samovar"
 
 module Falcon
 	module Command
+		# Implements the `falcon redirect` command.
+		#
+		# Manages a {Controller::Redirect} instance which redirects insecure HTTP traffic to secure HTTPS endpoints.
 		class Redirect < Samovar::Command
 			self.description = "Redirect from insecure HTTP to secure HTTP."
 			
@@ -29,6 +32,9 @@ module Falcon
 			
 			include Paths
 			
+			# Create the environment for the redirect service.
+			# @parameter options [Hash] Additional options to pass to the environment.
+			# @returns [Async::Service::Environment] The configured redirect environment.
 			def environment(**options)
 				Async::Service::Environment.new(Falcon::Environment::Redirect).with(
 					root: Dir.pwd,
@@ -41,15 +47,17 @@ module Falcon
 				)
 			end
 			
+			# Build the service configuration for the redirect.
+			# @returns [Async::Service::Configuration] The service configuration.
 			def configuration
-				Configuration.for(
+				Async::Service::Configuration.for(
 					self.environment(environments: super.environments)
 				)
 			end
 			
 			# Prepare the environment and run the controller.
 			def call
-				Console.logger.info(self) do |buffer|
+				Console.info(self) do |buffer|
 					buffer.puts "Falcon Redirect v#{VERSION} taking flight!"
 					buffer.puts "- Binding to: #{@options[:bind]}"
 					buffer.puts "- To terminate: Ctrl-C or kill #{Process.pid}"

data/lib/falcon/command/serve.rb

@@ -1,15 +1,15 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2018-2025, by Samuel Williams.
+# Copyright, 2018-2026, by Samuel Williams.
 # Copyright, 2018, by Mitsutaka Mimura.
 
 require_relative "../server"
 require_relative "../endpoint"
-require_relative "../configuration"
 require_relative "../service/server"
 require_relative "../environment/rackup"
 
+require "async/service/configuration"
 require "async/container"
 require "async/http/client"
 require "samovar"
@@ -49,18 +49,26 @@ module Falcon
 				option "--health-check-timeout <duration>", "Duration to wait for health check.", type: Float, default: 30.0
 			end
 			
+			# Extract container-related options from the command line options.
+			# @returns [Hash] Options for container configuration.
 			def container_options
 				@options.slice(:count, :forks, :threads, :restart, :health_check_timeout)
 			end
 			
+			# Extract endpoint-related options from the command line options.
+			# @returns [Hash] Options for endpoint configuration.
 			def endpoint_options
 				@options.slice(:hostname, :port, :timeout)
 			end
 			
+			# Get the name for the service, using hostname if available, otherwise the bind address.
+			# @returns [String] The service name.
 			def name
 				@options[:hostname] || @options[:bind]
 			end
 			
+			# Create the environment for the serve command.
+			# @returns [Async::Service::Environment] The configured server environment.
 			def environment
 				Async::Service::Environment.new(Falcon::Environment::Server).with(
 					Falcon::Environment::Rackup,
@@ -82,8 +90,10 @@ module Falcon
 				)
 			end
 			
+			# Build the service configuration for the serve command.
+			# @returns [Async::Service::Configuration] The service configuration.
 			def configuration
-				Configuration.new.tap do |configuration|
+				Async::Service::Configuration.new.tap do |configuration|
 					configuration.add(self.environment)
 				end
 			end
@@ -117,7 +127,7 @@ module Falcon
 			
 			# Prepare the environment and run the controller.
 			def call
-				Console.logger.info(self) do |buffer|
+				Console.info(self) do |buffer|
 					buffer.puts "Falcon v#{VERSION} taking flight! Using #{self.container_class} #{self.container_options}."
 					buffer.puts "- Running on #{RUBY_DESCRIPTION}"
 					buffer.puts "- Binding to: #{self.endpoint}"

data/lib/falcon/command/top.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2020-2025, by Samuel Williams.
+# Copyright, 2020-2026, by Samuel Williams.
 
 require_relative "serve"
 require_relative "host"
@@ -58,7 +58,7 @@ module Falcon
 			# @parameter encoding [Encoding] Defaults to `Encoding::UTF_8`.
 			def update_external_encoding!(encoding = Encoding::UTF_8)
 				if Encoding.default_external != encoding
-					Console.logger.warn(self) {"Updating Encoding.default_external from #{Encoding.default_external} to #{encoding}"}
+					Console.warn(self){"Updating Encoding.default_external from #{Encoding.default_external} to #{encoding}"}
 					Encoding.default_external = encoding
 				end
 			end

data/lib/falcon/command/virtual.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.
 
 require "async/service"
 
@@ -31,6 +31,8 @@ module Falcon
 			# @attribute [Array(String)]
 			many :paths
 			
+			# Create the environment for the virtual host service.
+			# @returns [Async::Service::Environment] The configured virtual environment.
 			def environment
 				Async::Service::Environment.new(Falcon::Environment::Virtual).with(
 					verbose: self.parent&.verbose?,
@@ -41,6 +43,8 @@ module Falcon
 				)
 			end
 			
+			# Build the service configuration for the virtual host.
+			# @returns [Async::Service::Configuration] The service configuration.
 			def configuration
 				Async::Service::Configuration.new.tap do |configuration|
 					configuration.add(self.environment)
@@ -49,7 +53,7 @@ module Falcon
 			
 			# Prepare the environment and run the controller.
 			def call
-				Console.logger.info(self) do |buffer|
+				Console.info(self) do |buffer|
 					buffer.puts "Falcon Virtual v#{VERSION} taking flight!"
 					buffer.puts "- Running on #{RUBY_DESCRIPTION}"
 					buffer.puts "- To terminate: Ctrl-C or kill #{Process.pid}"

data/lib/falcon/command.rb

@@ -1,12 +1,13 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2017-2025, by Samuel Williams.
+# Copyright, 2017-2026, by Samuel Williams.
 # Copyright, 2018, by Mitsutaka Mimura.
 
 require_relative "command/top"
 
 module Falcon
+	# @namespace
 	module Command
 		# The main entry point for the `falcon` executable.
 		# @parameter arguments [Array(String)] The command line arguments.

data/lib/falcon/composite_server.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2025, by Samuel Williams.
+# Copyright, 2026, by Samuel Williams.
 
 require "async"
 

data/lib/falcon/environment/configured.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2024, by Samuel Williams.
+# Copyright, 2024-2026, by Samuel Williams.
 
 module Falcon
 	module Environment
@@ -25,8 +25,10 @@ module Falcon
 				end
 			end
 			
+			# Load the configuration from all resolved configuration paths.
+			# @returns [Async::Service::Configuration] The loaded configuration.
 			def configuration
-				::Async::Service::Configuration.load(resolved_configuration_paths)
+				Async::Service::Configuration.load(resolved_configuration_paths)
 			end
 		end
 	end

data/lib/falcon/environment/lets_encrypt_tls.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2020-2024, by Samuel Williams.
+# Copyright, 2020-2026, by Samuel Williams.
 
 require_relative "tls"
 require_relative "../environment"
@@ -28,7 +28,5 @@ module Falcon
 				File.join(lets_encrypt_root, authority, "privkey.pem")
 			end
 		end
-		
-		LEGACY_ENVIRONMENTS[:lets_encrypt_tls] = LetsEncryptTLS
 	end
 end

data/lib/falcon/environment/proxy.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2020-2024, by Samuel Williams.
+# Copyright, 2020-2026, by Samuel Williams.
 
 require_relative "server"
 require_relative "../tls"
@@ -40,13 +40,8 @@ module Falcon
 					
 					# next unless environment.implements?(Falcon::Environment::Application)
 					if evaluator.key?(:authority) and evaluator.key?(:ssl_context) and evaluator.key?(:endpoint)
-						Console.info(self) {"Proxying #{self.url} to #{evaluator.authority} using #{evaluator.endpoint}"}
+						Console.info(self){"Proxying #{self.url} to #{evaluator.authority} using #{evaluator.endpoint}"}
 						hosts[evaluator.authority] = evaluator
-						
-						if RUBY_VERSION < "3.1"
-							# Ensure the SSL context is set up before forking - it's buggy on Ruby < 3.1:
-							evaluator.ssl_context
-						end
 					end
 				end
 				
@@ -60,13 +55,13 @@ module Falcon
 				hosts = self.hosts
 				
 				if host = hosts[hostname]
-					Console.logger.debug(self) {"Resolving #{hostname} -> #{host}"}
+					Console.debug(self){"Resolving #{hostname} -> #{host}"}
 					
 					socket.hostname = hostname
 					
 					return host.ssl_context
 				else
-					Console.logger.warn(self, hosts: hosts.keys) {"Unable to resolve #{hostname}!"}
+					Console.warn(self, hosts: hosts.keys){"Unable to resolve #{hostname}!"}
 					
 					return nil
 				end
@@ -97,11 +92,11 @@ module Falcon
 				)
 			end
 			
+			# Build the proxy middleware with the configured hosts.
+			# @returns [Middleware::Proxy] The proxy middleware instance.
 			def middleware
 				return Middleware::Proxy.new(Middleware::BadRequest, self.hosts)
 			end
 		end
-		
-		LEGACY_ENVIRONMENTS[:proxy] = Proxy
 	end
 end

data/lib/falcon/environment/rack.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2024, by Samuel Williams.
+# Copyright, 2024-2026, by Samuel Williams.
 
 require_relative "application"
 require_relative "rackup"
@@ -14,7 +14,5 @@ module Falcon
 			include Application
 			include Rackup
 		end
-		
-		LEGACY_ENVIRONMENTS[:rack] = Rack
 	end
 end

data/lib/falcon/environment/rackup.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2020-2024, by Samuel Williams.
+# Copyright, 2020-2026, by Samuel Williams.
 
 require "rack/builder"
 require_relative "../server"
@@ -10,14 +10,20 @@ module Falcon
 	module Environment
 		# Provides an environment for hosting loading a Rackup `config.ru` file.
 		module Rackup
+			# The path to the rackup configuration file.
+			# @returns [String] The absolute path to the rackup file.
 			def rackup_path
 				File.expand_path("config.ru", root)
 			end
 			
+			# Parse and load the rack application from the rackup file.
+			# @returns [Protocol::Rack::Adapter] The parsed rack application.
 			def rack_app
 				::Protocol::Rack::Adapter.parse_file(rackup_path)
 			end
 			
+			# Build the middleware stack for the rack application.
+			# @returns [Protocol::HTTP::Middleware] The middleware stack.
 			def middleware
 				::Falcon::Server.middleware(rack_app, verbose: verbose, cache: cache)
 			end

data/lib/falcon/environment/redirect.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2020-2025, by Samuel Williams.
+# Copyright, 2020-2026, by Samuel Williams.
 
 require_relative "server"
 require_relative "application"
@@ -13,10 +13,14 @@ module Falcon
 		module Redirect
 			include Server
 			
+			# The URL template to redirect to.
+			# @returns [String] The redirect URL template.
 			def redirect_url
 				"https://[::]:443"
 			end
 			
+			# Parse the redirect URL into an endpoint.
+			# @returns [Async::HTTP::Endpoint] The redirect endpoint.
 			def redirect_endpoint
 				Async::HTTP::Endpoint.parse(redirect_url)
 			end
@@ -27,6 +31,8 @@ module Falcon
 				[]
 			end
 			
+			# Build a hash of host authorities to their evaluators for redirect matching.
+			# @returns [Hash(String, Async::Service::Environment::Evaluator)] Map of host authorities to evaluators.
 			def hosts
 				hosts = {}
 				
@@ -34,7 +40,7 @@ module Falcon
 					evaluator = environment.evaluator
 					
 					if environment.implements?(Falcon::Environment::Application)
-						Console.info(self) {"Redirecting #{self.url} to #{evaluator.authority}"}
+						Console.info(self){"Redirecting #{self.url} to #{evaluator.authority}"}
 						hosts[evaluator.authority] = evaluator
 					end
 				end

data/lib/falcon/environment/self_signed_tls.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2019-2024, by Samuel Williams.
+# Copyright, 2019-2026, by Samuel Williams.
 
 require "localhost/authority"
 require_relative "tls"
@@ -39,7 +39,5 @@ module Falcon
 				end
 			end
 		end
-		
-		LEGACY_ENVIRONMENTS[:self_signed_tls] = SelfSignedTLS
 	end
 end

data/lib/falcon/environment/server.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2020-2025, by Samuel Williams.
+# Copyright, 2020-2026, by Samuel Williams.
 
 require "async/service/managed/environment"
 require "async/http/endpoint"
@@ -72,7 +72,7 @@ module Falcon
 			# @parameter endpoint [IO::Endpoint] The endpoint to bind to.
 			# @returns [Falcon::Server] The server instance.
 			def make_server(endpoint)
-				Falcon::Server.new(self.middleware, endpoint, protocol: self.endpoint.protocol, scheme: self.endpoint.scheme)
+				Falcon::Server.new(self.middleware, endpoint, protocol: self.endpoint.protocol, scheme: self.endpoint.scheme, utilization_registry: self[:utilization_registry])
 			end
 		end
 	end

data/lib/falcon/environment/tls.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2019-2024, by Samuel Williams.
+# Copyright, 2019-2026, by Samuel Williams.
 
 require_relative "../tls"
 require_relative "../environment"
@@ -92,6 +92,5 @@ module Falcon
 			end
 		end
 		
-		LEGACY_ENVIRONMENTS[:tls] = TLS
 	end
 end

data/lib/falcon/environment/virtual.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2024, by Samuel Williams.
+# Copyright, 2024-2026, by Samuel Williams.
 
 require_relative "configured"
 
@@ -9,6 +9,7 @@ require_relative "../service/virtual"
 
 module Falcon
 	module Environment
+		# Provides an environment for running virtual hosts with front-end proxy and redirect services.
 		module Virtual
 			include Configured
 			
@@ -18,6 +19,8 @@ module Falcon
 				Service::Virtual
 			end
 			
+			# The name of the virtual host service.
+			# @returns [String] The service class name.
 			def name
 				service_class.name
 			end

data/lib/falcon/environment.rb

@@ -1,13 +1,10 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2019-2024, by Samuel Williams.
+# Copyright, 2019-2026, by Samuel Williams.
 
 module Falcon
 	# Pre-defined environments for hosting web applications.
-	#
-	# See {Configuration::Loader#load} for more details.
 	module Environment
-		LEGACY_ENVIRONMENTS = {}
 	end
 end

data/lib/falcon/middleware/proxy.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.
 
 require "async/http/client"
 require "protocol/http/headers"
@@ -11,13 +11,18 @@ require "console/event/failure"
 require "traces/provider"
 
 module Falcon
+	# @namespace
 	module Middleware
 		# A static middleware which always returns a 400 bad request response.
 		module BadRequest
+			# Handle a request by returning a 400 bad request response.
+			# @parameter request [Protocol::HTTP::Request] The incoming request.
+			# @returns [Protocol::HTTP::Response] A 400 bad request response.
 			def self.call(request)
 				return Protocol::HTTP::Response[400, {}, []]
 			end
 			
+			# Close any resources used by this middleware.
 			def self.close
 			end
 		end

data/lib/falcon/middleware/redirect.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.
 
 require "async/http/client"
 
@@ -9,10 +9,14 @@ module Falcon
 	module Middleware
 		# A static middleware which always returns a 404 not found response.
 		module NotFound
+			# Handle a request by returning a 404 not found response.
+			# @parameter request [Protocol::HTTP::Request] The incoming request.
+			# @returns [Protocol::HTTP::Response] A 404 not found response.
 			def self.call(request)
 				return Protocol::HTTP::Response[404, {}, []]
 			end
 			
+			# Close any resources used by this middleware.
 			def self.close
 			end
 		end

data/lib/falcon/proxy_endpoint.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2019-2024, by Samuel Williams.
+# Copyright, 2019-2026, by Samuel Williams.
 
 require "io/endpoint/unix_endpoint"
 
@@ -16,6 +16,8 @@ module Falcon
 			@endpoint = endpoint
 		end
 		
+		# Generate a string representation of the proxy endpoint.
+		# @returns [String] A string representation including protocol and endpoint.
 		def to_s
 			"\#<#{self.class} protocol=#{self.protocol} endpoint=#{@endpoint}>"
 		end

data/lib/falcon/rackup/handler.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2024-2025, by Samuel Williams.
+# Copyright, 2024-2026, by Samuel Williams.
 
 require_relative "../../falcon"
 
@@ -9,6 +9,7 @@ require "kernel/sync"
 require "io/endpoint/host_endpoint"
 
 module Falcon
+	# @namespace
 	module Rackup
 		# The falcon adaptor for the `rackup` executable.
 		class Handler
@@ -51,6 +52,9 @@ module Falcon
 				end
 			end
 			
+			# Initialize the handler with a server and task.
+			# @parameter server [Falcon::Server] The server instance.
+			# @parameter task [Async::Task] The async task managing the server.
 			def initialize(server, task)
 				@server = server
 				@task = task
@@ -65,10 +69,12 @@ module Falcon
 				end
 			end
 			
+			# Signal the handler to stop the server.
 			def stop
 				@notification&.push(true)
 			end
 			
+			# Close the handler and clean up resources.
 			def close
 				@notification&.close
 				@notification = nil

data/lib/falcon/railtie.rb

@@ -1,9 +1,10 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2024, by Samuel Williams.
+# Copyright, 2024-2026, by Samuel Williams.
 
 module Falcon
+	# Rails integration for Falcon, configuring ActiveSupport to use fiber-based isolation.
 	class Railtie < Rails::Railtie
 		config.active_support.isolation_level = :fiber
 	end

data/lib/falcon/server.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.
 
 require "async/http/server"
 
@@ -9,6 +9,7 @@ require "protocol/http/middleware/builder"
 require "protocol/http/content_encoding"
 
 require "async/http/cache"
+require "async/utilization"
 require_relative "middleware/verbose"
 require "protocol/rack"
 
@@ -36,36 +37,36 @@ module Falcon
 			end
 		end
 		
-		def initialize(...)
-			super
+		# Initialize the server and set up statistics tracking.
+		#
+		# @parameter utilization_registry [Registry, nil] The utilization registry to use for metrics tracking.
+		#   If nil, a new registry instance is created.
+		def initialize(*arguments, utilization_registry: nil, **options)
+			super(*arguments, **options)
 			
-			@accept_count = 0
-			@connection_count = 0
+			utilization_registry ||= Async::Utilization::Registry.new
 			
-			@request_count = 0
-			@active_count = 0
+			# Get metric references for utilization tracking:
+			@connections_total_metric = utilization_registry.metric(:connections_total)
+			@connections_active_metric = utilization_registry.metric(:connections_active)
+			@requests_total_metric = utilization_registry.metric(:requests_total)
+			@requests_active_metric = utilization_registry.metric(:requests_active)
 		end
 		
-		attr :request_count
-		attr :accept_count
-		attr :connect_count
-		
+		# Accept a new connection and track connection statistics.
 		def accept(...)
-			@accept_count += 1
-			@connection_count += 1
-			
-			super
-		ensure
-			@connection_count -= 1
+			@connections_total_metric.increment
+			@connections_active_metric.track do
+				super
+			end
 		end
 		
+		# Handle a request and track request statistics.
 		def call(...)
-			@request_count += 1
-			@active_count += 1
-			
-			super
-		ensure
-			@active_count -= 1
+			@requests_total_metric.increment
+			@requests_active_metric.track do
+				super
+			end
 		end
 		
 		# Generates a human-readable string representing the current statistics.
@@ -80,7 +81,7 @@ module Falcon
 		#
 		# @returns [String] A string representing the current statistics.
 		def statistics_string
-			"C=#{format_count @connection_count}/#{format_count @accept_count} R=#{format_count @active_count}/#{format_count @request_count}"
+			"C=#{format_count @connections_active_metric.value}/#{format_count @connections_total_metric.value} R=#{format_count @requests_active_metric.value}/#{format_count @requests_total_metric.value}"
 		end
 		
 		private

data/lib/falcon/service/server.rb

@@ -1,18 +1,21 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2019-2025, by Samuel Williams.
+# Copyright, 2019-2026, by Samuel Williams.
 # Copyright, 2020, by Daniel Evans.
 
 require "async/service/managed/service"
-require "async/container/supervisor/supervised"
+require "async/service/supervisor/supervised"
 require "async/http/endpoint"
 
 require_relative "../server"
 
 module Falcon
+	# @namespace
 	module Service
+		# A managed service for running Falcon servers.
 		class Server < Async::Service::Managed::Service
+			# Initialize the server service.
 			def initialize(...)
 				super
 				
@@ -27,7 +30,7 @@ module Falcon
 					@bound_endpoint = @endpoint.bound
 				end
 				
-				Console.logger.info(self) {"Starting #{self.name} on #{@endpoint}"}
+				Console.info(self){"Starting #{self.name} on #{@endpoint}"}
 				
 				super
 			end

data/lib/falcon/tls.rb

@@ -1,9 +1,10 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2020-2023, by Samuel Williams.
+# Copyright, 2020-2026, by Samuel Williams.
 
 module Falcon
+	# TLS configuration and cipher suites for Falcon servers.
 	module TLS
 		# The list of supported ciphers.
 		#

data/lib/falcon/version.rb

@@ -1,8 +1,9 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2017-2025, by Samuel Williams.
+# Copyright, 2017-2026, by Samuel Williams.
 
+# @namespace
 module Falcon
-	VERSION = "0.54.3"
+	VERSION = "0.55.0"
 end

data/lib/falcon.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2017-2024, by Samuel Williams.
+# Copyright, 2017-2026, by Samuel Williams.
 
 require_relative "falcon/version"
 require_relative "falcon/server"

data/lib/rack/handler/falcon.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, 2019, by Bryan Powell.
 
 require "rack/handler"
@@ -10,7 +10,9 @@ require_relative "../../falcon/rackup/handler"
 
 # Generally speaking, you should not require this file directly, or assume the existance of the `Rack::Handler::Falcon` constant. Instead, use `Rack::Handler.get(:falcon)` to load and access the handler.
 
+# @namespace
 module Rack
+	# @namespace
 	module Handler
 		# Rack (v2) expects the constant to be in the `Rack::Handler` namespace, so we define a new handler class in the `Rack::Handler` namespace that inherits from `Falcon::Rackup::Handler`.
 		class Falcon < ::Falcon::Rackup::Handler

data/lib/rackup/handler/falcon.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2023-2025, by Samuel Williams.
+# Copyright, 2023-2026, by Samuel Williams.
 
 require "rackup/handler"
 
@@ -9,7 +9,9 @@ require_relative "../../falcon/rackup/handler"
 
 # Generally speaking, you should not require this file directly, or assume the existance of the `Rackup::Handler::Falcon` constant. Instead, use `Rackup::Handler.get(:falcon)` to load and access the handler.
 
+# @namespace
 module Rackup
+	# @namespace
 	module Handler
 		# Sinatra (and possibly others) try to extract the name using the final part of the class path, so we define a new class in the `Rack::Handler` namespace that inherits from `Falcon::Rackup::Handler`, that follows that convention.
 		class Falcon < ::Falcon::Rackup::Handler

data/license.md

@@ -1,6 +1,6 @@
 # MIT License
 
-Copyright, 2017-2025, by Samuel Williams.  
+Copyright, 2017-2026, by Samuel Williams.  
 Copyright, 2018, by Kent Gruber.  
 Copyright, 2018, by Janko Marohnić.  
 Copyright, 2018, by Tad Thorley.  

data/readme.md

@@ -47,6 +47,13 @@ Please see the [project documentation](https://socketry.github.io/falcon/) for m
 
 Please see the [project releases](https://socketry.github.io/falcon/releases/index) for all releases.
 
+### v0.55.0
+
+  - **Breaking**: Drop dependency on `async-container-supervisor`, you should migrate to `async-service-supervisor` instead.
+  - **Breaking**: Remove support for legacy environments, including `Falcon::Configuration`, now using `Async::Service::Configuration` directly.
+  - **Breaking**: `bake falcon:supervisor:restart` removed – superceeded by `async:service:supervisor:restart`.
+  - Add support for `async-utilization` metrics.
+
 ### v0.54.1
 
   - Fix handling of old style supervisors from `Async::Container::Supervisor`.
@@ -89,12 +96,6 @@ Please see the [project releases](https://socketry.github.io/falcon/releases/ind
 
   - Fix Falcon Supervisor implementation: due to invalid code, it was unable to start.
 
-### Compatibility Fixes
-
-During the `v0.44.0` release cycle, the workflows for testing older rack releases were accidentally dropped. As such, `v0.44.0` was not compatible with older versions of rack. This release restores compatibility with older versions of rack.
-
-Specifically, `protocol-rack` now provides `Protocol::Rack::Adapter.parse_file` to load Rack applications. Rack 2's `Rack::Builder.parse_file` returns both the application and a set of options (multi-value return). Rack 3 changed this to only return the application, as the prior multi-value return was confusing at best. This change allows `protocol-rack` to work with both versions of rack, and `falcon` adopts that interface.
-
 ## Contributing
 
 We welcome contributions to this project.

data/releases.md

@@ -1,5 +1,12 @@
 # Releases
 
+## v0.55.0
+
+  - **Breaking**: Drop dependency on `async-container-supervisor`, you should migrate to `async-service-supervisor` instead.
+  - **Breaking**: Remove support for legacy environments, including `Falcon::Configuration`, now using `Async::Service::Configuration` directly.
+  - **Breaking**: `bake falcon:supervisor:restart` removed – superceeded by `async:service:supervisor:restart`.
+  - Add support for `async-utilization` metrics.
+
 ## v0.54.1
 
   - Fix handling of old style supervisors from `Async::Container::Supervisor`.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: falcon
 version: !ruby/object:Gem::Version
-  version: 0.54.3
+  version: 0.55.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -94,61 +94,61 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0.20'
 - !ruby/object:Gem::Dependency
-  name: async-container-supervisor
+  name: async-http
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.6'
+        version: '0.75'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.6'
+        version: '0.75'
 - !ruby/object:Gem::Dependency
-  name: async-http
+  name: async-http-cache
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.75'
+        version: '0.4'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.75'
+        version: '0.4'
 - !ruby/object:Gem::Dependency
-  name: async-http-cache
+  name: async-service
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.4'
+        version: '0.19'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.4'
+        version: '0.19'
 - !ruby/object:Gem::Dependency
-  name: async-service
+  name: async-utilization
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.19'
+        version: '0.3'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.19'
+        version: '0.3'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -239,7 +239,6 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
-- bake/falcon/supervisor.rb
 - bin/falcon
 - bin/falcon-host
 - context/deployment.md
@@ -262,7 +261,6 @@ files:
 - lib/falcon/command/top.rb
 - lib/falcon/command/virtual.rb
 - lib/falcon/composite_server.rb
-- lib/falcon/configuration.rb
 - lib/falcon/endpoint.rb
 - lib/falcon/environment.rb
 - lib/falcon/environment/application.rb
@@ -274,7 +272,6 @@ files:
 - lib/falcon/environment/redirect.rb
 - lib/falcon/environment/self_signed_tls.rb
 - lib/falcon/environment/server.rb
-- lib/falcon/environment/supervisor.rb
 - lib/falcon/environment/tls.rb
 - lib/falcon/environment/virtual.rb
 - lib/falcon/middleware/proxy.rb
@@ -306,7 +303,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.2'
+      version: '3.3'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="

data/bake/falcon/supervisor.rb

@@ -1,8 +0,0 @@
-# frozen_string_literal: true
-
-# Released under the MIT License.
-# Copyright, 2020-2025, by Samuel Williams.
-
-def restart
-	context.lookup("async:container:supervisor:restart").call
-end

data/lib/falcon/configuration.rb

@@ -1,90 +0,0 @@
-# frozen_string_literal: true
-
-# Released under the MIT License.
-# Copyright, 2019-2025, by Samuel Williams.
-# Copyright, 2019, by Sho Ito.
-
-require "async/service"
-
-module Falcon
-	# Manages environments which describes how to host a specific application.
-	#
-	# Environments are key-value maps with lazy value resolution. An environment can inherit from a parent environment, which can provide defaults or shared configuration.
-	#
-	class Configuration < ::Async::Service::Configuration
-		# Load the specified configuration file. See {Loader#load_file} for more details.
-		def load_file(path)
-			Loader.load_file(self, path)
-		end
-		
-		# The domain specific language for loading configuration files.
-		class Loader < ::Async::Service::Loader
-			# Load specific features into the current configuration.
-			#
-			# @deprecated Use `require` instead.
-			# @parameter features [Array(Symbol)] The features to load.
-			def load(*features)
-				features.each do |feature|
-					case feature
-					when Symbol
-						require File.join(__dir__, "environment", "#{feature}.rb")
-					else
-						raise LoadError, "Unsure about how to load #{feature}!"
-					end
-				end
-			end
-			
-			# Define a host with the specified name.
-			# Adds `root` and `authority` keys.
-			# @deprecated Use `service` and `include Falcon::Environment::Server` instead.
-			# @parameter name [String] The name of the environment, usually a hostname.
-			def host(name, *parents, &block)
-				@configuration.add(
-					merge(*parents, name: name, root: @root, authority: name, &block)
-				)
-			end
-			
-			# Define a proxy with the specified name.
-			# Adds `root` and `authority` keys.
-			# @deprecated Use `service` and `include Falcon::Environment::Proxy` instead.
-			# @parameter name [String] The name of the environment, usually a hostname.
-			def proxy(name, *parents, &block)
-				@configuration.add(
-					merge(:proxy, *parents, name: name, root: @root, authority: name, &block)
-				)
-			end
-			
-			# Define a rack application with the specified name.
-			# Adds `root` and `authority` keys.
-			# @deprecated Use `service` and `include Falcon::Environment::Rack` instead.
-			# @parameter name [String] The name of the environment, usually a hostname.
-			def rack(name, *parents, &block)
-				@configuration.add(
-					merge(:rack, *parents, name: name, root: @root, authority: name, &block)
-				)
-			end
-			
-			# Define a supervisor instance
-			# @deprecated Use `service` and `include Falcon::Environment::Supervisor` instead.
-			def supervisor(&block)
-				name = File.join(@root, "supervisor")
-				
-				@configuration.add(
-					merge(:supervisor, name: name, root: @root, &block)
-				)
-			end
-			
-			private
-			
-			# Build a new environment with the specified name and the given parents.
-			# @parameter name [String]
-			# @parameter parents [Array(Symbol)]
-			# @yields {...} The block that will generate the environment.
-			def merge(*parents, **initial, &block)
-				facets = parents.map{|parent| Environment::LEGACY_ENVIRONMENTS.fetch(parent)}
-				
-				::Async::Service::Environment.build(*facets, **initial, &block)
-			end
-		end
-	end
-end

data/lib/falcon/environment/supervisor.rb

@@ -1,23 +0,0 @@
-# frozen_string_literal: true
-
-# Released under the MIT License.
-# Copyright, 2019-2025, by Samuel Williams.
-
-require_relative "../environment"
-
-require "async/container/supervisor"
-
-module Falcon
-	module Environment
-		# Provides an environment for hosting a supervisor which can monitor multiple applications.
-		module Supervisor
-			include Async::Container::Supervisor::Environment
-			
-			def monitors
-				[Async::Container::Supervisor::MemoryMonitor.new(interval: 10)]
-			end
-		end
-		
-		LEGACY_ENVIRONMENTS[:supervisor] = Supervisor
-	end
-end