falcon 0.54.3 → 0.55.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 22b09155428d4918e4f5b81cc0b809a8ca678f2509fbfb42f7e67cb2621d74dc
-  data.tar.gz: df9bbb12499685689dd38a38ede8807f5f09022394c13386766a178bc0760962
+  metadata.gz: 45c36302281a4c7947bc8c19869f93143254e821c0ab327b725aa8782dd710cb
+  data.tar.gz: c59ab82cc9babe0eea1a7ec74b2fdba4be6801dd7b1b05359fec6a2f8ec0db91
 SHA512:
-  metadata.gz: 8a483823b106bf170b158c70f797e3cbb1a233fc74b7be20d7deed8d8d0b690b1f5945330a64b9c5245978759f91fee7b14b1dbf35ede89021a0c6e902a652f2
-  data.tar.gz: 4707fbfbbe508fa06e32815c6ed5e0ba3d6ebc279af9f1460a9be633e86aecc8a05b49919f885ff848c50cd3bc2d8b058671622c44b7b95ee4119c91f1746155
+  metadata.gz: 2242015bc8980ebef3ae53fb2bf8db8040ef943bada60bb801cd65e849cfc68f8586b6a33e050053270cd9bd10ea9e5c778de117adb82353ecc47d24439bfb7f
+  data.tar.gz: 522154fa107e97fa4a8b72e997f71ab7afcf4e8a5699cb741f6d16aa2720b722a664dae052c82130df930af3430aa1d531a705ac59081658074008b4e58ded6a

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/body/request_finished.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+require "protocol/http/body/wrapper"
+
+module Falcon
+	# @namespace
+	module Body
+		# Wraps a response body and decrements a metric after the body is closed.
+		#
+		# Runs close on the underlying body first (which invokes rack.response_finished),
+		# then decrements the metric. Use this so requests_active stays elevated until
+		# the request is fully finished (including response_finished callbacks).
+		class RequestFinished < Protocol::HTTP::Body::Wrapper
+			# Wrap a response body with a metric. If the body is nil or empty, decrements immediately.
+			#
+			# @parameter message [Protocol::HTTP::Response] The response whose body to wrap.
+			# @parameter metric [Async::Utilization::Metric] The metric to decrement when the body is closed.
+			# @returns [Protocol::HTTP::Response] The message (modified in place).
+			def self.wrap(message, metric)
+				if body = message&.body and !body.empty?
+					message.body = new(body, metric)
+				else
+					metric.decrement
+				end
+				
+				message
+			end
+			
+			# @parameter body [Protocol::HTTP::Body::Readable] The body to wrap.
+			# @parameter metric [Async::Utilization::Metric] The metric to decrement on close.
+			def initialize(body, metric)
+				super(body)
+				
+				@metric = metric
+			end
+			
+			# @returns [Boolean] False, the wrapper does not support rewinding.
+			def rewindable?
+				false
+			end
+			
+			# @returns [Boolean] False, rewinding is not supported.
+			def rewind
+				false
+			end
+			
+			# Closes the underlying body (invoking rack.response_finished), then decrements the metric.
+			#
+			# @parameter error [Exception, nil] Optional error that caused the close.
+			def close(error = nil)
+				super
+				
+				@metric&.decrement
+				@metric = nil
+			end
+		end
+	end
+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