Add Falcon cluster service environment

Author: samuel-williams-shopify

lib/falcon/environment/cluster.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require_relative "server"
+require_relative "../service/cluster"
+
+module Falcon
+	module Environment
+		# Provides an environment for hosting a cluster of Falcon server workers, where each worker binds its own endpoint.
+		module Cluster
+			include Server
+			
+			# The service class to use for the cluster.
+			# @returns [Class]
+			def service_class
+				Service::Cluster
+			end
+			
+			# The host that this server will receive connections for.
+			def url
+				"http://[::]:0"
+			end
+			
+			# The endpoint bound by the current worker.
+			# @returns [IO::Endpoint::BoundEndpoint | Nil]
+			def bound_endpoint
+				@bound_endpoint
+			end
+			
+			# Set the endpoint bound by the current worker.
+			# @parameter bound_endpoint [IO::Endpoint::BoundEndpoint]
+			def bound_endpoint=(bound_endpoint)
+				@bound_endpoint = bound_endpoint
+			end
+			
+			# The first socket address bound by the current worker.
+			# @returns [Addrinfo | Nil]
+			def bound_address
+				@bound_endpoint&.sockets&.first&.to_io&.local_address
+			end
+			
+			# The port bound by the current worker.
+			# @returns [Integer | Nil]
+			def bound_port
+				bound_address&.ip_port
+			end
+		end
+	end
+end

lib/falcon/service/cluster.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "async/service/generic"
+
+require_relative "server"
+
+module Falcon
+	# @namespace
+	module Service
+		# A managed service for running Falcon workers with independently bound endpoints.
+		class Cluster < Server
+			# Start the service without binding the endpoint in the parent process.
+			def start
+				preload!
+				
+				Async::Service::Generic.instance_method(:start).bind_call(self)
+			end
+			
+			# Setup the service into the specified container.
+			# @parameter container [Async::Container] The container to configure.
+			def setup(container)
+				container_options = @evaluator.container_options
+				health_check_timeout = container_options[:health_check_timeout]
+				
+				container.run(**container_options) do |instance|
+					clock = Async::Clock.start
+					
+					Async do
+						evaluator = self.environment.evaluator
+						server = nil
+						
+						health_checker(instance, health_check_timeout) do
+							if server
+								instance.name = format_title(evaluator, server)
+							end
+						end
+						
+						instance.status!("Preparing...")
+						
+						bound_endpoint = evaluator.endpoint.bound
+						evaluator.bound_endpoint = bound_endpoint
+						
+						evaluator.prepare!(instance)
+						emit_prepared(instance, clock)
+						
+						instance.status!("Running...")
+						server = run(instance, evaluator, bound_endpoint)
+						instance.name = format_title(evaluator, server)
+						emit_running(instance, clock)
+						
+						instance.ready!
+					end
+				end
+			end
+			
+			# Run the service logic.
+			#
+			# @parameter instance [Object] The container instance.
+			# @parameter evaluator [Environment::Evaluator] The environment evaluator.
+			# @parameter bound_endpoint [IO::Endpoint] The endpoint bound by this worker.
+			# @returns [Falcon::Server] The server instance.
+			def run(instance, evaluator, bound_endpoint)
+				server = evaluator.make_server(bound_endpoint)
+				
+				Async do |task|
+					server.run
+					
+					task.children&.each(&:wait)
+				end
+				
+				server
+			end
+		end
+	end
+end

releases.md

@@ -2,6 +2,7 @@
 
 ## Unreleased
 
+  - Add `Falcon::Environment::Cluster` and `Falcon::Service::Cluster` for running workers with independently bound endpoints.
   - Move Falcon middleware trace providers to `traces/provider/falcon/middleware`.
 
 ## v0.55.5

test/falcon/environment/cluster.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "falcon/environment/cluster"
+require "async/service/environment"
+
+describe Falcon::Environment::Cluster do
+	let(:evaluator) do
+		Async::Service::Environment.build(subject, name: "localhost").evaluator
+	end
+	
+	it "provides default cluster settings" do
+		expect(evaluator).to have_attributes(
+			service_class: be == Falcon::Service::Cluster,
+			url: be == "http://[::]:0",
+			authority: be == "localhost",
+			bound_endpoint: be == nil,
+			bound_address: be == nil,
+			bound_port: be == nil,
+		)
+	end
+end

test/falcon/service/cluster.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "falcon/service/cluster"
+require "falcon/environment/cluster"
+require "async/container"
+require "async/service/environment"
+require "fileutils"
+require "net/http"
+require "protocol/http/middleware"
+
+describe Falcon::Service::Cluster do
+	let(:ports_path) {File.expand_path(".cluster/ports.txt", __dir__)}
+	
+	let(:recorder) do
+		path = ports_path
+		
+		Module.new do
+			def middleware
+				Protocol::HTTP::Middleware::HelloWorld
+			end
+			
+			def container_options
+				super.merge(restart: false)
+			end
+			
+			define_method(:prepare!) do |instance|
+				super(instance)
+				
+				File.open(path, "a") do |file|
+					file.puts(bound_port)
+				end
+			end
+		end
+	end
+	
+	let(:environment) do
+		Async::Service::Environment.new(Falcon::Environment::Cluster).with(
+			recorder,
+			name: "hello",
+			root: File.expand_path(".cluster/hello", __dir__),
+			url: "http://127.0.0.1:0",
+			count: 2,
+		)
+	end
+	
+	let(:server) do
+		subject.new(environment)
+	end
+	
+	before do
+		FileUtils.rm_rf(File.dirname(ports_path))
+		FileUtils.mkdir_p(File.dirname(ports_path))
+	end
+	
+	after do
+		FileUtils.rm_rf(File.dirname(ports_path))
+	end
+	
+	it "binds a unique port for each worker before preparing the instance" do
+		container = Async::Container.new
+		
+		server.start
+		server.setup(container)
+		container.wait_until_ready
+		
+		ports = File.readlines(ports_path, chomp: true).map(&:to_i)
+		
+		expect(ports).to have_attributes(size: be == 2)
+		expect(ports).to have_value(be > 0)
+		expect(ports.uniq).to be == ports
+		
+		ports.each do |port|
+			response = Net::HTTP.get_response(URI("http://127.0.0.1:#{port}/"))
+			
+			expect(response).to have_attributes(code: be == "200")
+		end
+	ensure
+		server.stop
+		container&.stop
+	end
+end