falcon 0.50.0 → 0.51.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6b5612e05c65dc847f524f1e20345fcffb037c459c493e2cb5d73a1b4964e8b0
-  data.tar.gz: cbc83ab219046f20cd04f6b99bc438554b76d5b25fe0f2a462cbc3bc0859659d
+  metadata.gz: c9ecf3850f21fa9285cc2c274629a706829cbe25d5d8db5773548421cba3619d
+  data.tar.gz: 6d9fcd1a57350ce6746a959ee72da073c7c5b6332b3e5686a168d86201c1d7b7
 SHA512:
-  metadata.gz: 6357075c07a05e8a7cc85eeda99fb4b7cf276c1a2590d5c7ce3e4578bbc0e08fd47b4a713873a98ed9c033aac293f6d5239970a56de8db403b79afee78bdee2c
-  data.tar.gz: 8728f7d6aa88546d3cf9de9713400447f41510bc7d5005ed9e77b266d0d9b7c4a285f6056d41f88e1ddb17d82b8ae36d2f9e626893b99919be4d4f8e50836538
+  metadata.gz: 4f19565cfe07b0c6281698f9815090419799176b546134be71829a75bac552b0d007cbfc6718448c4e73af0870055672d449ac808cf4a68c5c21b1d666a696aa
+  data.tar.gz: 386fbecdf6b82bdccc771d7c0221fc883762998a3233722343d3db190b3868ec57b9b675840a356ab0b3461bf33e6194414aa25edfc97401315017d41eef1423

data/bake/falcon/supervisor.rb

@@ -4,7 +4,5 @@
 # Copyright, 2020-2025, by Samuel Williams.
 
 def restart
-	require_relative "../../lib/falcon/command/supervisor"
-	
-	Falcon::Command::Supervisor["restart"].call
+	context.lookup("async:container:supervisor:restart").call
 end

data/lib/falcon/command/top.rb

@@ -8,7 +8,6 @@ require_relative "host"
 require_relative "virtual"
 require_relative "proxy"
 require_relative "redirect"
-require_relative "supervisor"
 
 require_relative "../version"
 
@@ -38,7 +37,6 @@ module Falcon
 				"virtual" => Virtual,
 				"proxy" => Proxy,
 				"redirect" => Redirect,
-				"supervisor" => Supervisor,
 			}, default: "serve"
 			
 			# Whether verbose logging is enabled.

data/lib/falcon/environment/server.rb

@@ -45,14 +45,16 @@ module Falcon
 				"http://[::]:9292"
 			end
 			
+			# The timeout used for client connections.
 			def timeout
 				nil
 			end
 			
+			# Options to use when creating the endpoint.
 			def endpoint_options
 				{
 					reuse_address: true,
-					timeout: timeout,
+					timeout: self.timeout,
 				}
 			end
 			
@@ -62,22 +64,36 @@ module Falcon
 				::Async::HTTP::Endpoint.parse(url).with(**endpoint_options)
 			end
 			
+			# Whether to enable verbose logging.
 			def verbose
 				false
 			end
 			
+			# Whether to enable the HTTP cache for this server.
 			def cache
 				false
 			end
 			
+			# A client endpoint that can be used to connect to the server.
+			# @returns [Async::HTTP::Endpoint] The client endpoint.
 			def client_endpoint
 				::Async::HTTP::Endpoint.parse(url)
 			end
 			
 			# Any scripts to preload before starting the server.
+			#
+			# @returns [Array(String)] The list of scripts to preload.
 			def preload
 				[]
 			end
+			
+			# Make a server instance using the given endpoint. The endpoint may be a bound endpoint, so we take care to specify the protocol and scheme as per the original endpoint.
+			#
+			# @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)
+			end
 		end
 	end
 end

data/lib/falcon/environment/supervisor.rb

@@ -3,42 +3,18 @@
 # Released under the MIT License.
 # Copyright, 2019-2024, by Samuel Williams.
 
-require_relative "../service/supervisor"
 require_relative "../environment"
 
-require "io/endpoint/unix_endpoint"
+require "async/container/supervisor"
 
 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
-				"supervisor"
-			end
-			
-			# The IPC path to use for communication with the supervisor.
-			# @returns [String]
-			def ipc_path
-				::File.expand_path("supervisor.ipc", root)
-			end
-			
-			# The endpoint the supervisor will bind to.
-			# @returns [::IO::Endpoint::Generic]
-			def endpoint
-				::IO::Endpoint.unix(ipc_path)
-			end
+			include Async::Container::Supervisor::Environment
 			
-			# Options to use when creating the container.
-			def container_options
-				{restart: true, count: 1, health_check_timeout: 30}
+			def monitors
+				[Async::Container::Supervisor::MemoryMonitor.new(interval: 10)]
 			end
 		end
 		

data/lib/falcon/service/server.rb

@@ -5,6 +5,7 @@
 # Copyright, 2020, by Daniel Evans.
 
 require "async/service/generic"
+require "async/container/supervisor/supervised"
 require "async/http/endpoint"
 
 require_relative "../server"
@@ -58,7 +59,11 @@ module Falcon
 					evaluator = @environment.evaluator
 					
 					Async do |task|
-						server = Falcon::Server.new(evaluator.middleware, @bound_endpoint, protocol: @endpoint.protocol, scheme: @endpoint.scheme)
+						if @environment.implements?(Async::Container::Supervisor::Supervised)
+							evaluator.make_supervised_worker(instance).run
+						end
+						
+						server = evaluator.make_server(@bound_endpoint)
 						
 						server.run
 						

data/lib/falcon/version.rb

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

data/readme.md

@@ -45,6 +45,15 @@ 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.51.0
+
+  - Introduce <code class="language-ruby">Falcon::Environment::Server\#make\_server</code> which gives you full control over the server creation process.
+  - [Introduce `Async::Container::Supervisor`.](https://socketry.github.io/falcon/releases/index#introduce-async::container::supervisor.)
+
+### v0.50.0
+
+  - Add <code class="language-ruby">Falcon::Environment::Server\#endpoint\_options</code> to allow configuration of the endpoint options more easily.
+
 ### v0.49.0
 
   - [Falcon Server Container Health Checks](https://socketry.github.io/falcon/releases/index#falcon-server-container-health-checks)

data/releases.md

@@ -1,5 +1,40 @@
 # Releases
 
+## v0.51.0
+
+  - Introduce {ruby Falcon::Environment::Server\#make\_server} which gives you full control over the server creation process.
+
+### Introduce `Async::Container::Supervisor`.
+
+`Async::Container::Supervisor` is a new supervisor implementation that replaces Falcon's own supervisor. This allows you to use the same supervisor for all your services, and provides a more consistent interface for managing services. The supervisor is now a separate gem, `async-container-supervisor`.
+
+By default, the supervisor does not perform any monitoring, but you may add monitoring by defining them in the service definition. For example:
+
+``` ruby
+service "hello.localhost" do
+	# Configure server...
+	
+	include Async::Container::Supervisor::Supervised
+end
+
+service "supervisor" do
+	include Async::Container::Supervisor::Environment
+	
+	monitors do
+		[
+			# Limit total memory usage to 512MiB:
+			Async::Container::Supervisor::MemoryMonitor.new(interval: 10, limit: 1024 * 1024 * 512),
+		]
+	end
+end
+```
+
+We retain the `falcon:supervisor:restart` task, but you may prefer to use `async:container:supervisor:restart` directly.
+
+## v0.50.0
+
+  - Add {ruby Falcon::Environment::Server\#endpoint\_options} to allow configuration of the endpoint options more easily.
+
 ## v0.49.0
 
 ### Falcon Server Container Health Checks

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: falcon
 version: !ruby/object:Gem::Version
-  version: 0.50.0
+  version: 0.51.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -60,7 +60,7 @@ cert_chain:
   Q2K9NVun/S785AP05vKkXZEFYxqG6EW012U4oLcFl5MySFajYXRYbuUpH6AY+HP8
   voD0MPg1DssDLKwXyt1eKD/+Fq0bFWhwVM/1XiAXL7lyYUyOq24KHgQ2Csg=
   -----END CERTIFICATE-----
-date: 2025-02-11 00:00:00.000000000 Z
+date: 2025-03-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: async
@@ -90,6 +90,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.20'
+- !ruby/object:Gem::Dependency
+  name: async-container-supervisor
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.5.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.5.0
 - !ruby/object:Gem::Dependency
   name: async-http
   requirement: !ruby/object:Gem::Requirement
@@ -174,20 +188,6 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.0'
-- !ruby/object:Gem::Dependency
-  name: process-metrics
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.2'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.2'
 - !ruby/object:Gem::Dependency
   name: protocol-http
   requirement: !ruby/object:Gem::Requirement
@@ -246,7 +246,6 @@ files:
 - lib/falcon/command/proxy.rb
 - lib/falcon/command/redirect.rb
 - lib/falcon/command/serve.rb
-- lib/falcon/command/supervisor.rb
 - lib/falcon/command/top.rb
 - lib/falcon/command/virtual.rb
 - lib/falcon/configuration.rb
@@ -272,7 +271,6 @@ files:
 - lib/falcon/railtie.rb
 - lib/falcon/server.rb
 - lib/falcon/service/server.rb
-- lib/falcon/service/supervisor.rb
 - lib/falcon/service/virtual.rb
 - lib/falcon/tls.rb
 - lib/falcon/version.rb

data/lib/falcon/command/supervisor.rb

@@ -1,73 +0,0 @@
-# frozen_string_literal: true
-
-# Released under the MIT License.
-# Copyright, 2019-2024, by Samuel Williams.
-
-require "samovar"
-require "async"
-require "json"
-
-require "io/endpoint/unix_endpoint"
-require "io/stream"
-
-module Falcon
-	module Command
-		# Implements the `falcon supervisor` command.
-		#
-		# Talks to an instance of the supervisor to issue commands and print results.
-		class Supervisor < Samovar::Command
-			self.description = "Control and query a specific supervisor."
-			
-			# The command line options.
-			# @attribute [Samovar::Options]
-			options do
-				option "--path <path>", "The control IPC path.", default: "supervisor.ipc"
-			end
-			
-			# Implements the `falcon supervisor restart` command.
-			class Restart < Samovar::Command
-				self.description = "Restart the process group."
-				
-				# Send the restart message to the supervisor.
-				def call(stream)
-					stream.puts({please: "restart"}.to_json, separator: "\0")
-				end
-			end
-			
-			# Implements the `falcon supervisor metrics` command.
-			class Metrics < Samovar::Command
-				self.description = "Show metrics about the falcon processes."
-				
-				# Send the metrics message to the supervisor and print the results.
-				def call(stream)
-					stream.puts({please: "metrics"}.to_json, separator: "\0", chomp: true)
-					response = JSON.parse(stream.read_until("\0"), symbolize_names: true)
-					
-					$stdout.puts response
-				end
-			end
-			
-			# The nested command to execute.
-			# @name nested
-			# @attribute [Command]
-			nested :command, {
-				"restart" => Restart,
-				"metrics" => Metrics,
-			}, default: "metrics"
-			
-			# The endpoint the supervisor is bound to.
-			def endpoint
-				::IO::Endpoint.unix(@options[:path])
-			end
-			
-			# Connect to the supervisor and execute the requested command.
-			def call
-				Sync do
-					endpoint.connect do |socket|
-						@command.call(IO::Stream(socket))
-					end
-				end
-			end
-		end
-	end
-end

data/lib/falcon/service/supervisor.rb

@@ -1,123 +0,0 @@
-# frozen_string_literal: true
-
-# Released under the MIT License.
-# Copyright, 2019-2024, by Samuel Williams.
-
-require "process/metrics"
-require "json"
-
-require "async/service/generic"
-
-require "io/endpoint/bound_endpoint"
-require "io/stream"
-
-module Falcon
-	module Service
-		# Implements a host supervisor which can restart the host services and provide various metrics about the running processes.
-		class Supervisor < Async::Service::Generic
-			# Initialize the supervisor using the given environment.
-			# @parameter environment [Build::Environment]
-			def initialize(...)
-				super
-				
-				@bound_endpoint = nil
-			end
-			
-			# The endpoint which the supervisor will bind to.
-			# Typically a unix pipe in the same directory as the host.
-			def endpoint
-				@evaluator.endpoint
-			end
-			
-			# Restart the process group that the supervisor belongs to.
-			def do_restart(message)
-				# Tell the parent of this process group to spin up a new process group/container.
-				# Wait for that to start accepting new connections.
-				# Stop accepting connections.
-				# Wait for existing connnections to drain.
-				# Terminate this process group.
-				signal = message[:signal] || :INT
-				
-				Process.kill(signal, Process.ppid)
-			end
-			
-			# Capture process metrics relating to the process group that the supervisor belongs to.
-			def do_metrics(message)
-				Process::Metrics::General.capture(pid: Process.ppid, ppid: Process.ppid)
-			end
-			
-			# Handle an incoming request.
-			# @parameter message [Hash] The decoded message.
-			def handle(message)
-				case message[:please]
-				when "restart"
-					self.do_restart(message)
-				when "metrics"
-					self.do_metrics(message)
-				end
-			end
-			
-			# Bind the supervisor to the specified endpoint.
-			def start
-				Console.logger.info(self) {"Binding to #{self.endpoint}..."}
-				
-				@bound_endpoint = Sync{self.endpoint.bound}
-				
-				super
-			end
-			
-			# 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_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)
-							
-							while message = stream.read_until("\0")
-								response = handle(JSON.parse(message, symbolize_names: true))
-								stream.puts(response.to_json, separator: "\0")
-							end
-						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
-				
-				super
-			end
-			
-			# Release the bound endpoint.
-			def stop
-				@bound_endpoint&.close
-				@bound_endpoint = nil
-				
-				super
-			end
-			
-			def invoke(command)
-				@bound_endpoint.local_address_endpoint.connect do |peer|
-					stream = ::IO::Stream(peer)
-					
-					stream.puts(command.to_json, separator: "\0")
-					
-					response = JSON.parse(stream.read_until("\0"), symbolize_names: true)
-					
-					return response
-				end
-			end
-		end
-	end
-end