falcon 0.55.0 → 0.55.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8aa8fb7fb61e5c4112b6e7e3423a59e27a0f00555edd04ab381ca58f064b10cd
-  data.tar.gz: a8a3a69df547475b9fd306f0bedd3e0f4836f1d3f42be43f1f6b1d53746b82e5
+  metadata.gz: 3e901867477864a82832904cbaa1662105e6dce12190e057d457a666fa3dfe42
+  data.tar.gz: 523e181a6685bfe398bc5630076ab8e76642bf47181d4e20c62192813f121712
 SHA512:
-  metadata.gz: 2dca19722a68b6bd56f1caf3639cc5b4f952a6d908a5e2e36f10cf1e6a3e733d1d423c1713dab0ac8dc5e1adc595d2d6acb345a24d868c85e1b6ca706164fd00
-  data.tar.gz: 6d1ffeb9711b90027841489a348322fe955004cab78a2aa5a26a6ec61be6613013dc33d87b675776338b91aa2715cf3423959e05947e8e3ff42e886e50727666
+  metadata.gz: 0eb64a874478507caeafefb4c83b108cfa7b00326cf69ce7581ab534e9466048dea1572b66044f06ee19b21998fafad32cf5de3ea050f6ae0f32b1743424ef2e
+  data.tar.gz: 3f041a4ebdf07b1063373a27e7151b4f8380f4f440b34a773f27b0b6761d64f721209c5a7d2366f1210e1be1d3042d1e8bed117a77a7ce81d9335274636fe656

data/context/deployment.md

@@ -56,18 +56,22 @@ service "supervisor" do
 end
 ~~~
 
-These configuration blocks are evaluated using the [async-service](https://github.com/socketry/async-service) gem. The supervisor is an independent service which monitors the health of the application and can restart it if necessary. Other services like background job processors can be added to the configuration.
+These configuration blocks are evaluated using the [async-service](https://github.com/socketry/async-service) gem. This configuration will bind Falcon to an [IPC socket](https://en.wikipedia.org/wiki/Unix_domain_socket) and is designed to be used with a reverse proxy such as [`falcon virtual`](#falcon-virtual).
+
+The supervisor is an independent service which monitors the health of the application and can restart it if necessary. Other services like background job processors can be added to the configuration.
 
 ### Environments
 
 The service blocks define configuration that is loaded by the service layer to control how the service is run. The `service ... do` block defines the service name and the environment in which it runs. Different modules can be included to provide different functionality, such as `Falcon::Environment::Rack` for Rack applications, or `Falcon::Environment::LetsEncryptTLS` for automatic TLS certificate management.
 
+**NOTE**: Falcon does not provision or renew certificates automatically. Use a tool like [certbot](https://certbot.eff.org) to provision your certificate and the `LetsEncryptTLS` environment will automatically read it in.
+
 ### Application Configuration
 
 The environment configuration is defined in the `Falcon::Environment` module. The {ruby Falcon::Environment::Application} environment supports the generic virtual host functionality, but you can customise any parts of the configuration, e.g. to bind a production host to `localhost:3000` using plaintext HTTP/2:
 
 ~~~ ruby
-#!/usr/bin/env falcon host
+#!/usr/bin/env falcon-host
 # frozen_string_literal: true
 
 require "falcon/environment/rack"
@@ -76,12 +80,54 @@ require "async/service/supervisor"
 hostname = File.basename(__dir__)
 service hostname do
 	include Falcon::Environment::Rack
-	include Falcon::Environment::LetsEncryptTLS
 
 	endpoint do
 		Async::HTTP::Endpoint
 			.parse('http://localhost:3000')
-			.with(protocol: Async::HTTP::Protocol::HTTP2)
+			.with(
+				protocol: Async::HTTP::Protocol::HTTP2
+			)
+	end
+end
+
+service "supervisor" do
+	include Async::Service::Supervisor::Environment
+end
+~~~
+
+You can verify this is working using the [`nghttp2` client](https://nghttp2.org): `nghttp -v http://localhost:3000`. This will not work in a browser as they mandate TLS for HTTP/2 connections.
+
+#### Self-signed certificate
+
+You can use a self-signed certificate to test your server configuration locally. First, provision a certificate using the [`localhost` gem](https://github.com/socketry/localhost):
+
+```
+$ bundle exec bake localhost:install
+```
+
+You may be prompted for a password to install the certificate. This is the password for your local keychain.
+
+Then, add the `SelfSignedTLS` environment to your configuration and set up the SSL context:
+
+~~~ ruby
+#!/usr/bin/env falcon-host
+# frozen_string_literal: true
+
+require "falcon/environment/rack"
+require "async/service/supervisor"
+
+hostname = File.basename(__dir__)
+service hostname do
+	include Falcon::Environment::Rack
+	include Falcon::Environment::SelfSignedTLS
+
+	endpoint do
+		Async::HTTP::Endpoint
+			.parse('https://localhost:3000')
+			.with(
+				protocol: Async::HTTP::Protocol::HTTP2,
+				ssl_context: ssl_context
+			)
 	end
 end
 
@@ -90,7 +136,7 @@ service "supervisor" do
 end
 ~~~
 
-You can verify this is working using `nghttp -v http://localhost:3000`.
+You should now be able to access your server at `https://localhost:3000` in your browser.
 
 #### Application Configuration Example for Heroku
 

data/lib/falcon/body/request_finished.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, 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/server.rb

@@ -10,6 +10,7 @@ require "protocol/http/content_encoding"
 
 require "async/http/cache"
 require "async/utilization"
+require_relative "body/request_finished"
 require_relative "middleware/verbose"
 require "protocol/rack"
 
@@ -62,11 +63,16 @@ module Falcon
 		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(...)
 			@requests_total_metric.increment
-			@requests_active_metric.track do
-				super
-			end
+			@requests_active_metric.increment
+			
+			return Body::RequestFinished.wrap(super, @requests_active_metric)
 		end
 		
 		# Generates a human-readable string representing the current statistics.

data/lib/falcon/service/server.rb

@@ -5,7 +5,6 @@
 # Copyright, 2020, by Daniel Evans.
 
 require "async/service/managed/service"
-require "async/service/supervisor/supervised"
 require "async/http/endpoint"
 
 require_relative "../server"

data/lib/falcon/version.rb

@@ -5,5 +5,5 @@
 
 # @namespace
 module Falcon
-	VERSION = "0.55.0"
+	VERSION = "0.55.2"
 end

data/license.md

@@ -28,6 +28,7 @@ Copyright, 2024, by Ismael Celis.
 Copyright, 2025, by Pierre Montelle.  
 Copyright, 2025, by Jared Smith.  
 Copyright, 2025, by Yoji Shidara.  
+Copyright, 2026, by Ayush Newatia.  
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/readme.md

@@ -47,6 +47,14 @@ 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.2
+
+  - Remove unnecessary require for `async/service/supervisor/supervised`."
+
+### 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.
@@ -88,14 +96,6 @@ Please see the [project releases](https://socketry.github.io/falcon/releases/ind
   - [Falcon Server Container Health Checks](https://socketry.github.io/falcon/releases/index#falcon-server-container-health-checks)
   - [Falcon Server Process Title](https://socketry.github.io/falcon/releases/index#falcon-server-process-title)
 
-### v0.48.4
-
-  - 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.
-
 ## Contributing
 
 We welcome contributions to this project.

data/releases.md

@@ -1,5 +1,13 @@
 # Releases
 
+## v0.55.2
+
+  - Remove unnecessary require for `async/service/supervisor/supervised`."
+
+## 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.

data.tar.gz.sig

@@ -1,2 +1 @@
-��T�M�!�K�C�l׼�4uz�z�[�>2̢��C5&�$�d�~�~�7�	�{
-�Oz����E���8�o�g����E�$���m �B����^ᎆ�0M�\}`��ޏ�Ƽ���h�<�r~)W^['�]_�@�㪫N�g���U���w���ٯ�a�K�;㿂���d2���F.�a�I�f���[��X9�sүи��w�(L��c(����Fޅ.
&�a��M���u��FWn�
+q,4��_�:�=�"��ߙ����t!&sל�c\�q�bN�gL�>>S�}!!�Db�Y�,w����kC����U���������+'�'��[x٥�L���!�+�L��f��&`Go���XZ����^p�G`��

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: falcon
 version: !ruby/object:Gem::Version
-  version: 0.55.0
+  version: 0.55.2
 platform: ruby
 authors:
 - Samuel Williams
@@ -15,6 +15,7 @@ authors:
 - Peter Schrammel
 - Sho Ito
 - Adam Daniels
+- Ayush Newatia
 - Colby Swandale
 - Daniel Evans
 - Ismael Celis
@@ -252,6 +253,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