falcon 0.48.6 → 0.49.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2a6198414f38d568e93d77452b6efa9b4f9267a5beedb57b8c7a96bd72a174cd
-  data.tar.gz: 164f1aa2a4407eba29965a0c1acc85364ad734b6a2aa1215d408b3d1e67bd4f5
+  metadata.gz: 9e53a58574f18152b0d6a59ef2c20957cd09fe15e8dd3ab593f3692c9ecab092
+  data.tar.gz: 96abcd1f8fc3afd6d3f6065e25ecc0f201e28809651f4e16d456c3f0584e9e57
 SHA512:
-  metadata.gz: e6942fa58fda793327bfcb767a0e729f2417c90d4dcdb7bbdc9f1a8c81492575b95fc96ee294b69e555322d643f3dd8b0443b38f3efb92a3eb31f68d445ad34e
-  data.tar.gz: 8d4dcc4a530b7eaf74055e893fec7e101fa8e2419d9dc59713064f54fb679a566091f162220ecf5e25cbcf312db52a4f503dd65fb8398cf1f06c00dbab4ad39a
+  metadata.gz: 1002a1e4214a8d0bfda3bb03a5eb6cf29bbbde2559e600b0f40d0ae5e531ada93588138abc90e56b839a8b11e20591b4b9741b948bac0998d4baafe7158cd48f
+  data.tar.gz: 52c0ed26d2e5691c81490adeaf12d7eb078a88b0ce0a6dcbbea3f624be724cc619141e259c6da15c7114103b107e567900b6d26086f71c91c7c74cd041ec5cf4

data/lib/falcon/command/serve.rb

@@ -45,16 +45,22 @@ module Falcon
 				
 				option "--[no]-restart", "Enable/disable automatic restart.", default: true
 				option "--graceful-stop <timeout>", "Duration to wait for graceful stop.", type: Float, default: 1.0
+				
+				option "--health-check-timeout <duration>", "Duration to wait for health check.", type: Float, default: 30.0
 			end
 			
 			def container_options
-				@options.slice(:count, :forks, :threads, :restart)
+				@options.slice(:count, :forks, :threads, :restart, :health_check_timeout)
 			end
 			
 			def endpoint_options
 				@options.slice(:hostname, :port, :timeout)
 			end
 			
+			def name
+				@options[:hostname] || @options[:bind]
+			end
+			
 			def environment
 				Async::Service::Environment.new(Falcon::Environment::Server).with(
 					Falcon::Environment::Rackup,
@@ -71,7 +77,7 @@ module Falcon
 					preload: [@options[:preload]].compact,
 					url: @options[:bind],
 					
-					name: "server",
+					name: self.name,
 					
 					endpoint: ->{Endpoint.parse(url, **endpoint_options)}
 				)

data/lib/falcon/configuration.rb

@@ -9,21 +9,7 @@ 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
-	#
-	# A typical configuration file might look something like:
-	#
-	#	~~~ ruby
-	#	#!/usr/bin/env falcon-host
-	#	# frozen_string_literal: true
-	#	
-	#	load :rack, :self_signed_tls, :supervisor
-	#	
-	#	supervisor
-	#	
-	#	rack 'hello.localhost', :self_signed_tls do
-	#	end
-	#	~~~
+	# 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.

data/lib/falcon/environment/server.rb

@@ -33,7 +33,7 @@ module Falcon
 			
 			# Options to use when creating the container.
 			def container_options
-				{restart: true, count: self.count}.compact
+				{restart: true, count: self.count, health_check_timeout: 30}.compact
 			end
 			
 			# The host that this server will receive connections for.

data/lib/falcon/environment/supervisor.rb

@@ -12,6 +12,12 @@ module Falcon
 	module Environment
 		# Provides an environment for hosting a supervisor which can monitor multiple applications.
 		module Supervisor
+			# The service class to use for the supervisor.
+			# @returns [Class]
+			def service_class
+				::Falcon::Service::Supervisor
+			end
+			
 			# The name of the supervisor
 			# @returns [String]
 			def name
@@ -30,10 +36,9 @@ module Falcon
 				::IO::Endpoint.unix(ipc_path)
 			end
 			
-			# The service class to use for the supervisor.
-			# @returns [Class]
-			def service_class
-				::Falcon::Service::Supervisor
+			# Options to use when creating the container.
+			def container_options
+				{restart: true, count: 1, health_check_timeout: 30}
 			end
 		end
 		

data/lib/falcon/server.rb

@@ -35,5 +35,53 @@ module Falcon
 				run rack_app
 			end
 		end
+		
+		def initialize(...)
+			super
+			
+			@accept_count = 0
+			@connection_count = 0
+			
+			@request_count = 0
+			@active_count = 0
+		end
+		
+		attr :request_count
+		attr :accept_count
+		attr :connect_count
+		
+		def accept(...)
+			@accept_count += 1
+			@connection_count += 1
+			
+			super
+		ensure
+			@connection_count -= 1
+		end
+		
+		def call(...)
+			@request_count += 1
+			@active_count += 1
+			
+			super
+		ensure
+			@active_count -= 1
+		end
+		
+		def statistics_string
+			"C=#{format_count @connection_count}/#{format_count @accept_count} R=#{format_count @active_count}/#{format_count @request_count}"
+		end
+		
+		private
+		
+		def format_count(value)
+			if value > 1_000_000
+				"#{(value/1_000_000.0).round(2)}M"
+			elsif value > 1_000
+				"#{(value/1_000.0).round(2)}K"
+			else
+				value
+			end
+		end
 	end
 end

data/lib/falcon/service/server.rb

@@ -52,6 +52,7 @@ module Falcon
 			# @parameter container [Async::Container::Generic]
 			def setup(container)
 				container_options = @evaluator.container_options
+				health_check_timeout = container_options[:health_check_timeout]
 				
 				container.run(name: self.name, **container_options) do |instance|
 					evaluator = @environment.evaluator
@@ -63,6 +64,17 @@ module Falcon
 						
 						instance.ready!
 						
+						if health_check_timeout
+							Async(transient: true) do
+								while true
+									# We only update this if the health check is enabled. Maybe we should always update it?
+									instance.name = "#{self.name} (#{server.statistics_string} L=#{Fiber.scheduler.load.round(3)})"
+									sleep(health_check_timeout / 2)
+									instance.ready!
+								end
+							end
+						end
+						
 						task.children.each(&:wait)
 					end
 				end

data/lib/falcon/service/supervisor.rb

@@ -69,7 +69,10 @@ module Falcon
 			# Start the supervisor process which accepts connections from the bound endpoint and processes JSON formatted messages.
 			# @parameter container [Async::Container::Generic]
 			def setup(container)
-				container.run(name: self.name, restart: true, count: 1) do |instance|
+				container_options = @evaluator.container_options
+				health_check_timeout = container_options[:health_check_timeout]
+				
+				container.run(name: self.name, **container_options) do |instance|
 					Async do
 						@bound_endpoint.accept do |peer|
 							stream = ::IO::Stream(peer)
@@ -81,6 +84,15 @@ module Falcon
 						end
 						
 						instance.ready!
+						
+						if health_check_timeout
+							Async(transient: true) do
+								while true
+									sleep(health_check_timeout / 2)
+									instance.ready!
+								end
+							end
+						end
 					end
 				end
 				

data/lib/falcon/version.rb

@@ -4,5 +4,5 @@
 # Copyright, 2017-2024, by Samuel Williams.
 
 module Falcon
-	VERSION = "0.48.6"
+	VERSION = "0.49.0"
 end

data/readme.md

@@ -45,6 +45,11 @@ 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.49.0
+
+  - [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.
@@ -53,6 +58,39 @@ 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.
+
+### Falcon Serve Options
+
+In addition, `falcon serve` provides two new options:
+
+1.  `--[no]-restart` which controls what happens when `async-container` instances crash. By default, `falcon serve` will restart the container when it crashes. This can be disabled with `--no-restart`.
+
+2.  `--graceful-stop [timeout]` which allows you to specify a timeout for graceful shutdown. This is useful when you want to stop the server, but allow existing connections to finish processing before the server stops. This feature is highly experimental and doesn't work correctly in all cases yet, but we are aiming to improve it.
+
+### Falcon Host
+
+`async-service` is a new gem that exposes a generic service interface on top of `async-container`. Previously, `falcon host` used `async-container` directly and `build-environment` for configuration. In order to allow for more generic service definitions and configuration, `async-service` now provides a similar interface to `build-environment` and exposes this in a way that can be used for services other tha falcon. This makes it simpler to integrate multiple services into a single application.
+
+The current configuration format uses definitions like this:
+
+``` ruby
+rack 'hello.localhost', :self_signed_tls
+```
+
+This changes to:
+
+``` ruby
+service 'hello.localhost' do
+	include Falcon::Environment::Rack
+	include Falcon::Environment::SelfSignedTLS
+end
+```
+
 ## Contributing
 
 We welcome contributions to this project.

data/releases.md

@@ -1,5 +1,33 @@
 # Releases
 
+## v0.49.0
+
+### Falcon Server Container Health Checks
+
+{ruby Falcon::Service::Server} adds support for the {ruby Async::Container} health check which detects hung processes and restarts them. The default health check interval is 30 seconds.
+
+`falcon serve` introduces a new `--health-check-timeout` option to configure the health check timeout. `falcon.rb`/`falcon host` can be changed using the `health_check_timeout` key within the `container_options` configuration - these are passed directly to {ruby Async::Container}. If you don't want a health check, set `health_check_timeout` to `nil`.
+
+### Falcon Server Process Title
+
+The Falcon server process title is now updated periodically (alongside the health check) to include information about the numnber of connections and requests.
+
+    12211 ttys002    0:00.28 /Users/samuel/.gem/ruby/3.4.1/bin/falcon serve --bind http://localhost:8000      
+    12213 ttys002    0:04.14 http://localhost:8000 (C=2/2 R=0/49.45K L=0.353)
+    12214 ttys002    0:07.22 http://localhost:8000 (C=5/6 R=0/112.97K L=0.534)
+    12215 ttys002    0:05.41 http://localhost:8000 (C=3/3 R=0/71.7K L=0.439)
+    12216 ttys002    0:06.46 http://localhost:8000 (C=4/5 R=0/93.22K L=0.493)
+    12217 ttys002    0:02.58 http://localhost:8000 (C=1/1 R=0/24.9K L=0.251)
+    12218 ttys002    0:05.44 http://localhost:8000 (C=3/3 R=0/72.12K L=0.439)
+    12219 ttys002    0:06.47 http://localhost:8000 (C=4/4 R=0/93.13K L=0.493)
+    12220 ttys002    0:04.03 http://localhost:8000 (C=2/2 R=0/47.37K L=0.357)
+    12221 ttys002    0:06.41 http://localhost:8000 (C=4/4 R=0/92.46K L=0.494)
+    12222 ttys002    0:06.38 http://localhost:8000 (C=4/4 R=0/91.71K L=0.495)
+
+  - **C** – Connections: `(current/total)` connections accepted by the server
+  - **R** – Requests: `(current/total)` requests processed by the server
+  - **L** – Scheduler Load: A floating-point value representing the event loop load
+
 ## v0.48.4
 
   - Improve compatibility of rackup handler w.r.t. sinatra.
@@ -7,3 +35,40 @@
 ## v0.47.8
 
   - Fix Falcon Supervisor implementation: due to invalid code, it was unable to start.
+
+# v0.45.0
+
+## 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.
+
+## Falcon Serve Options
+
+In addition, `falcon serve` provides two new options:
+
+1.  `--[no]-restart` which controls what happens when `async-container` instances crash. By default, `falcon serve` will restart the container when it crashes. This can be disabled with `--no-restart`.
+
+2.  `--graceful-stop [timeout]` which allows you to specify a timeout for graceful shutdown. This is useful when you want to stop the server, but allow existing connections to finish processing before the server stops. This feature is highly experimental and doesn't work correctly in all cases yet, but we are aiming to improve it.
+
+# v0.44.0
+
+## Falcon Host
+
+`async-service` is a new gem that exposes a generic service interface on top of `async-container`. Previously, `falcon host` used `async-container` directly and `build-environment` for configuration. In order to allow for more generic service definitions and configuration, `async-service` now provides a similar interface to `build-environment` and exposes this in a way that can be used for services other tha falcon. This makes it simpler to integrate multiple services into a single application.
+
+The current configuration format uses definitions like this:
+
+``` ruby
+rack 'hello.localhost', :self_signed_tls
+```
+
+This changes to:
+
+``` ruby
+service 'hello.localhost' do
+	include Falcon::Environment::Rack
+	include Falcon::Environment::SelfSignedTLS
+end
+```

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: falcon
 version: !ruby/object:Gem::Version
-  version: 0.48.6
+  version: 0.49.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -60,7 +60,7 @@ cert_chain:
   Q2K9NVun/S785AP05vKkXZEFYxqG6EW012U4oLcFl5MySFajYXRYbuUpH6AY+HP8
   voD0MPg1DssDLKwXyt1eKD/+Fq0bFWhwVM/1XiAXL7lyYUyOq24KHgQ2Csg=
   -----END CERTIFICATE-----
-date: 2025-01-29 00:00:00.000000000 Z
+date: 2025-02-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: async
@@ -82,14 +82,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.18'
+        version: '0.20'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.18'
+        version: '0.20'
 - !ruby/object:Gem::Dependency
   name: async-http
   requirement: !ruby/object:Gem::Requirement
@@ -239,7 +239,6 @@ files:
 - bake/falcon/supervisor.rb
 - bin/falcon
 - bin/falcon-host
-- changes.md
 - lib/falcon.rb
 - lib/falcon/command.rb
 - lib/falcon/command/host.rb

data/changes.md

@@ -1,38 +0,0 @@
-# Changes
-
-# v0.45.0
-
-## 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.
-
-## Falcon Serve Options
-
-In addition, `falcon serve` provides two new options:
-
-1. `--[no]-restart` which controls what happens when `async-container` instances crash. By default, `falcon serve` will restart the container when it crashes. This can be disabled with `--no-restart`.
-
-2. `--graceful-stop [timeout]` which allows you to specify a timeout for graceful shutdown. This is useful when you want to stop the server, but allow existing connections to finish processing before the server stops. This feature is highly experimental and doesn't work correctly in all cases yet, but we are aiming to improve it.
-
-# v0.44.0
-
-## Falcon Host
-
-`async-service` is a new gem that exposes a generic service interface on top of `async-container`. Previously, `falcon host` used `async-container` directly and `build-environment` for configuration. In order to allow for more generic service definitions and configuration, `async-service` now provides a similar interface to `build-environment` and exposes this in a way that can be used for services other tha falcon. This makes it simpler to integrate multiple services into a single application.
-
-The current configuration format uses definitions like this:
-
-```ruby
-rack 'hello.localhost', :self_signed_tls
-```
-
-This changes to:
-
-```ruby
-service 'hello.localhost' do
-	include Falcon::Environment::Rack
-	include Falcon::Environment::SelfSignedTLS
-end
-```