falcon 0.54.3 → 0.55.1

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,8 @@ require "protocol/http/middleware/builder"
 require "protocol/http/content_encoding"
 
 require "async/http/cache"
+require "async/utilization"
+require_relative "body/request_finished"
 require_relative "middleware/verbose"
 require "protocol/rack"
 
@@ -36,36 +38,41 @@ 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.
+		#
+		# Uses manual increment/decrement so requests_active stays elevated until the
+		# response body is closed (including rack.response_finished). The
+		# Body::RequestFinished wrapper runs the decrement after the body closes,
+		# so response_finished callbacks are counted as active.
 		def call(...)
-			@request_count += 1
-			@active_count += 1
+			@requests_total_metric.increment
+			@requests_active_metric.increment
 			
-			super
-		ensure
-			@active_count -= 1
+			return Body::RequestFinished.wrap(super, @requests_active_metric)
 		end
 		
 		# Generates a human-readable string representing the current statistics.
@@ -80,7 +87,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.1"
 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,17 @@ 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.1
+
+  - `requests_active` is decremented after the response body is closed, including `rack.response_finished` callbacks.
+
+### 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`.
@@ -85,16 +96,6 @@ Please see the [project releases](https://socketry.github.io/falcon/releases/ind
 
   - Improve compatibility of rackup handler w.r.t. sinatra.
 
-### v0.47.8
-
-  - 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,16 @@
 # Releases
 
+## v0.55.1
+
+  - `requests_active` is decremented after the response body is closed, including `rack.response_finished` callbacks.
+
+## 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.1
 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
@@ -253,6 +252,7 @@ files:
 - context/rails-integration.md
 - context/websockets.md
 - lib/falcon.rb
+- lib/falcon/body/request_finished.rb
 - lib/falcon/command.rb
 - lib/falcon/command/host.rb
 - lib/falcon/command/paths.rb
@@ -262,7 +262,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 +273,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 +304,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