falcon 0.55.6 → 0.56.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9efae16cb2a08be54e0b1099559fdb943d7ef5a85d709b57f4caa2590d08ff8f
-  data.tar.gz: 4f03dd493732da1714b55ec9af8df3d1ec7e20ce0bd51e9ef48f5cee1e8141ed
+  metadata.gz: f7ba95aa9804ab5bccd97bdceb14467fc706c01bff4486e0ef8acac74a448567
+  data.tar.gz: b4a31ed06efddadc88a68de6d959a8b34310ec278edff5640b1b6149ce1bded3
 SHA512:
-  metadata.gz: c0301ea50dea981115c09258abe18b55e8327bfcf2a74d018a4b1b7a55c1567521f8afb38b16b52a4559dc181df922af0408901bd7b79c6ac61a6cbc16b6c8b7
-  data.tar.gz: 5270c593232e8d23d4157faa6b85176b5c95d220c4c0360871cb11e8990d04d1c2f508ef1681b1ff1e7c87fc408f5a68783d4fcf094812317ec8f241627d5a32
+  metadata.gz: 6ba9534e23c464859a54b955989c436fc1d0f639c17e621308098183fd477906db9a1348a52bb14b46ed02f16115913ee376da1e7886f782ce71ebb6869c538f
+  data.tar.gz: 4b3e498ac46f78a1f83d6fdcc2876dd91bc1ca8878f0c081579326f1fd757651d8baf02463a3038086a50f69a937e2d5cc84915c543a769ee74cddebeff99927

data/context/cluster-deployment.md

@@ -0,0 +1,197 @@
+# Dynamic Clusters with Envoy
+
+This guide explains how to run Falcon workers with independently bound endpoints and publish them dynamically to Envoy using xDS.
+
+## When to Use a Cluster
+
+A regular {ruby Falcon::Service::Server} binds one listener and shares it with every worker. This is the simplest design when Falcon accepts connections directly or sits behind a load balancer that targets one stable address.
+
+{ruby Falcon::Service::Cluster} instead gives each worker its own listener. Use it when an external load balancer needs to address, monitor, and remove workers individually. Because workers may bind ephemeral ports or Unix-domain sockets, the load balancer needs a dynamic source of viable endpoints rather than a static address list.
+
+| Service | Listener ownership | Upstream discovery |
+| --- | --- | --- |
+| `Falcon::Service::Server` | One listener shared by all workers | One stable address |
+| `Falcon::Service::Cluster` | One listener per worker | Dynamic worker endpoints |
+
+## Architecture
+
+Each cluster worker can bind to `localhost` with port `0`, allowing the operating system to assign an available port. Falcon describes the bound resource with a {ruby Falcon::Listener}, including its name, scheme, supported protocols, and concrete addresses.
+
+The worker registers that listener with `async-service-supervisor-envoy`. The supervisor publishes the current workers through an xDS control plane, and Envoy uses Endpoint Discovery Service (EDS) updates to maintain the upstream cluster.
+
+Requests arrive at Envoy's stable listener. Envoy selects one of the discovered worker endpoints and forwards the request to it:
+
+```mermaid
+flowchart LR
+	Client[Client] -->|HTTP on port 10000| Envoy
+
+	subgraph Network[Shared network namespace]
+		Envoy[Envoy]
+
+		subgraph Falcon[Falcon container]
+			Supervisor[Supervisor and xDS control plane]
+			Worker1[Falcon worker 1]
+			Worker2[Falcon worker 2]
+		end
+
+		Worker1 -.->|Register endpoint| Supervisor
+		Worker2 -.->|Register endpoint| Supervisor
+		Supervisor -.->|EDS over ADS on port 18000| Envoy
+		Envoy -->|HTTP on dynamic port| Worker1
+		Envoy -->|HTTP on dynamic port| Worker2
+	end
+```
+
+## Configuration
+
+Add Falcon and the Envoy supervisor integration to your `gems.rb`:
+
+```ruby
+gem "falcon", "~> 0.56.0"
+gem "async-service-supervisor-envoy", "~> 0.2"
+```
+
+Define a Falcon cluster service and an accompanying supervisor in `falcon.rb`:
+
+```ruby
+#!/usr/bin/env async-service
+# frozen_string_literal: true
+
+require "async/service/supervisor"
+require "async/service/supervisor/envoy"
+require "falcon/environment/cluster"
+
+service "cluster" do
+	include Falcon::Environment::Cluster
+	include Async::Service::Supervisor::Envoy::Supervised
+	
+	count 2
+	
+	def url
+		"http://localhost:0"
+	end
+	
+	middleware do
+		application = proc do |_env|
+			body = "Hello from worker #{Process.pid}!\n"
+			
+			[200, {
+				"content-type" => "text/plain",
+				"content-length" => body.bytesize.to_s,
+			}, [body]]
+		end
+		
+		Falcon::Server.middleware(application, cache: false)
+	end
+end
+
+service "supervisor" do
+	include Async::Service::Supervisor::Environment
+	
+	monitors do
+		[
+			Async::Service::Supervisor::Envoy::Monitor.new(
+				bind: "http://127.0.0.1:18000",
+			),
+		]
+	end
+end
+```
+
+The Falcon service name becomes the listener name, so the corresponding Envoy EDS cluster uses `cluster` as its service name. Configure Envoy to receive aggregated discovery updates from the supervisor:
+
+```yaml
+node:
+  id: falcon-cluster
+  cluster: falcon-cluster
+
+dynamic_resources:
+  ads_config:
+    api_type: GRPC
+    transport_api_version: V3
+    grpc_services:
+      - envoy_grpc:
+          cluster_name: xds_cluster
+
+static_resources:
+  listeners:
+    - name: listener_http
+      address:
+        socket_address:
+          address: 0.0.0.0
+          port_value: 10000
+      filter_chains:
+        - filters:
+            - name: envoy.filters.network.http_connection_manager
+              typed_config:
+                "@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
+                stat_prefix: ingress_http
+                route_config:
+                  name: local_route
+                  virtual_hosts:
+                    - name: falcon
+                      domains: ["*"]
+                      routes:
+                        - match:
+                            prefix: "/"
+                          route:
+                            cluster: cluster
+                http_filters:
+                  - name: envoy.filters.http.router
+                    typed_config:
+                      "@type": type.googleapis.com/envoy.extensions.filters.http.router.v3.Router
+
+  clusters:
+    - name: cluster
+      connect_timeout: 1s
+      type: EDS
+      lb_policy: ROUND_ROBIN
+      eds_cluster_config:
+        service_name: cluster
+        eds_config:
+          ads: {}
+          resource_api_version: V3
+
+    - name: xds_cluster
+      connect_timeout: 1s
+      type: STATIC
+      load_assignment:
+        cluster_name: xds_cluster
+        endpoints:
+          - lb_endpoints:
+              - endpoint:
+                  address:
+                    socket_address:
+                      address: 127.0.0.1
+                      port_value: 18000
+      typed_extension_protocol_options:
+        envoy.extensions.upstreams.http.v3.HttpProtocolOptions:
+          "@type": type.googleapis.com/envoy.extensions.upstreams.http.v3.HttpProtocolOptions
+          explicit_http_config:
+            http2_protocol_options: {}
+```
+
+The `xds_cluster` connection uses HTTP/2 because ADS is served over gRPC.
+
+## Worker Registration
+
+When each worker starts:
+
+1. Falcon binds the worker to an available loopback port.
+2. The worker registers its concrete addresses and supported protocols with the supervisor.
+3. The supervisor's Envoy monitor publishes the current worker endpoints as an EDS resource.
+4. Envoy receives the resource over its Aggregated Discovery Service (ADS) connection and updates its upstream cluster.
+
+The listener preserves all addresses returned by the bound endpoint. This allows the same interface to describe IP sockets, Unix-domain sockets, and endpoints with additional addresses.
+
+## Worker Restarts
+
+If a worker exits, its supervisor connection closes and the monitor publishes an EDS update without that endpoint. Falcon restarts the worker, which binds a new available port and registers it. The monitor then publishes another update, and Envoy receives both changes over its existing ADS stream without polling or restarting.
+
+This lifecycle is important when ports are ephemeral or a directory may contain stale Unix-domain socket paths: consumers should use the supervisor's current endpoint state as the source of truth.
+
+## Network Topology
+
+Falcon and Envoy can run in the same network namespace, allowing workers to bind to loopback addresses while remaining reachable by Envoy. With Docker Compose, `network_mode: service:falcon` gives the Envoy service access to Falcon's network namespace, so `127.0.0.1` and `localhost` refer to the same loopback interface for both processes.
+
+Without a shared network namespace, Envoy cannot connect to worker endpoints bound to Falcon's loopback interface. In a different deployment topology, bind workers to an interface that Envoy can reach and apply the appropriate network access controls.

data/context/index.yaml

@@ -18,6 +18,10 @@ files:
   description: This guide explains how to deploy applications using the Falcon web
     server. It covers the recommended deployment methods, configuration options, and
     examples for different environments, including systemd and kubernetes.
+- path: cluster-deployment.md
+  title: Dynamic Clusters with Envoy
+  description: This guide explains how to run Falcon workers with independently bound
+    endpoints and publish them dynamically to Envoy using xDS.
 - path: performance-tuning.md
   title: Performance Tuning
   description: This guide explains the performance characteristics of Falcon.

data/lib/falcon/environment/cluster.rb

@@ -0,0 +1,27 @@
+# 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
+		end
+	end
+end

data/lib/falcon/environment/server.rb

@@ -67,6 +67,14 @@ module Falcon
 				::Async::HTTP::Endpoint.parse(url)
 			end
 			
+			# Prepare a server worker after its listener has been bound.
+			#
+			# @parameter instance [Object] The container instance.
+			# @parameter listener [Falcon::Listener] The worker's bound listener.
+			def prepare_worker!(instance, listener)
+				prepare!(instance)
+			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.

data/lib/falcon/listener.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+module Falcon
+	# Describes a bound listener for a Falcon server.
+	class Listener
+		# Initialize a bound listener.
+		# @parameter name [String] The logical listener name.
+		# @parameter scheme [String] The application protocol scheme.
+		# @parameter protocols [Array(String)] The supported application protocol names.
+		# @parameter endpoint [IO::Endpoint::BoundEndpoint] The bound endpoint.
+		def initialize(name:, scheme:, protocols:, endpoint:)
+			@name = name
+			@scheme = scheme
+			@protocols = protocols.map(&:to_s).freeze
+			@endpoint = endpoint
+			@addresses = endpoint.sockets.map{|socket| socket.to_io.local_address}.freeze
+			freeze
+		end
+		
+		# @attribute [String] The logical listener name.
+		attr_reader :name
+		
+		# @attribute [String] The application protocol scheme.
+		attr_reader :scheme
+		
+		# @attribute [Array(String)] The supported application protocol names.
+		attr_reader :protocols
+		
+		# @attribute [IO::Endpoint::BoundEndpoint] The bound endpoint.
+		attr_reader :endpoint
+		
+		# @attribute [Array(Addrinfo)] The bound addresses.
+		attr_reader :addresses
+		
+		# Close the bound endpoint.
+		def close
+			@endpoint.close
+		end
+	end
+end

data/lib/falcon/service/cluster.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require_relative "server"
+
+module Falcon
+	# @namespace
+	module Service
+		# A managed service for running Falcon workers with independently bound endpoints.
+		class Cluster < Server
+			# Cluster workers bind independently in their own process.
+			def bind_endpoint
+			end
+			
+			# Bind and yield a listener owned by a cluster worker.
+			# @parameter evaluator [Environment::Evaluator] The environment evaluator.
+			# @yields {|listener| ...} The listener owned by the worker.
+			# 	@parameter listener [Falcon::Listener] The bound listener.
+			def with_listener(evaluator)
+				endpoint = evaluator.endpoint
+				bound_endpoint = endpoint.bound
+				listener = make_listener(evaluator, endpoint, bound_endpoint)
+				
+				yield listener
+			ensure
+				bound_endpoint&.close
+			end
+		end
+	end
+end

data/lib/falcon/service/server.rb

@@ -7,6 +7,7 @@
 require "async/service/managed/service"
 require "async/http/endpoint"
 
+require_relative "../listener"
 require_relative "../server"
 
 module Falcon
@@ -18,35 +19,99 @@ module Falcon
 			def initialize(...)
 				super
 				
-				@bound_endpoint = nil
+				@listener = nil
 			end
 			
-			# Prepare the bound endpoint for the server.
-			def start
+			# Build a listener from a configured and bound endpoint.
+			# @parameter evaluator [Environment::Evaluator] The environment evaluator.
+			# @parameter endpoint [Async::HTTP::Endpoint] The configured endpoint.
+			# @parameter bound_endpoint [IO::Endpoint::BoundEndpoint] The bound endpoint.
+			# @returns [Falcon::Listener] The bound listener.
+			def make_listener(evaluator, endpoint, bound_endpoint)
+				Listener.new(
+					name: evaluator.name,
+					scheme: endpoint.scheme,
+					protocols: endpoint.protocol.names,
+					endpoint: bound_endpoint,
+				)
+			end
+			
+			# Bind the endpoint used by each server worker.
+			def bind_endpoint
 				@endpoint = @evaluator.endpoint
 				
 				Sync do
-					@bound_endpoint = @endpoint.bound
+					bound_endpoint = @endpoint.bound
+					@listener = make_listener(@evaluator, @endpoint, bound_endpoint)
 				end
 				
 				Console.info(self){"Starting #{self.name} on #{@endpoint}"}
+			end
+			
+			# Prepare the bound endpoint for the server.
+			def start
+				bind_endpoint
 				
 				super
 			end
 			
+			# Yield the listener used by a server worker.
+			# @parameter evaluator [Environment::Evaluator] The environment evaluator.
+			# @yields {|listener| ...} The listener used by the worker.
+			# 	@parameter listener [Falcon::Listener] The bound listener.
+			def with_listener(evaluator)
+				yield @listener
+			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
+					evaluator = self.environment.evaluator
+					
+					with_listener(evaluator) do |listener|
+						Async do
+							server = nil
+							
+							health_checker(instance, health_check_timeout) do
+								if server
+									instance.name = format_title(evaluator, server)
+								end
+							end
+							
+							instance.status!("Preparing...")
+							evaluator.prepare_worker!(instance, listener)
+							emit_prepared(instance, clock)
+							
+							instance.status!("Running...")
+							server = run(instance, evaluator, listener)
+							instance.name = format_title(evaluator, server)
+							emit_running(instance, clock)
+							
+							instance.ready!
+						end
+					end
+				end
+			end
+			
 			# Run the service logic.
 			#
 			# @parameter instance [Object] The container instance.
 			# @parameter evaluator [Environment::Evaluator] The environment evaluator.
+			# @parameter listener [Falcon::Listener] The listener used by this worker.
 			# @returns [Falcon::Server] The server instance.
-			def run(instance, evaluator)
+			def run(instance, evaluator, listener = @listener)
 				if evaluator.respond_to?(:make_supervised_worker)
 					Console.warn(self, "Async::Container::Supervisor is replaced by Async::Service::Supervisor, please update your service definition.")
 					
 					evaluator.make_supervised_worker(instance).run
 				end
 				
-				server = evaluator.make_server(@bound_endpoint)
+				server = evaluator.make_server(listener.endpoint)
 				
 				Async do |task|
 					server.run
@@ -69,9 +134,9 @@ module Falcon
 			
 			# Close the bound endpoint.
 			def stop(...)
-				if @bound_endpoint
-					@bound_endpoint.close
-					@bound_endpoint = nil
+				if @listener
+					@listener.close
+					@listener = nil
 				end
 				
 				@endpoint = nil

data/lib/falcon/service/virtual.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2020-2024, by Samuel Williams.
+# Copyright, 2020-2026, by Samuel Williams.
 
 require "async/service/generic"
 require "console"

data/lib/falcon/version.rb

@@ -5,5 +5,5 @@
 
 # @namespace
 module Falcon
-	VERSION = "0.55.6"
+	VERSION = "0.56.0"
 end

data/lib/falcon.rb

@@ -4,6 +4,7 @@
 # Copyright, 2017-2026, by Samuel Williams.
 
 require_relative "falcon/version"
+require_relative "falcon/listener"
 require_relative "falcon/server"
 require_relative "falcon/composite_server"
 

data/readme.md

@@ -35,6 +35,8 @@ Please see the [project documentation](https://socketry.github.io/falcon/) for m
 
   - [Deployment](https://socketry.github.io/falcon/guides/deployment/index) - This guide explains how to deploy applications using the Falcon web server. It covers the recommended deployment methods, configuration options, and examples for different environments, including systemd and kubernetes.
 
+  - [Dynamic Clusters with Envoy](https://socketry.github.io/falcon/guides/cluster-deployment/index) - This guide explains how to run Falcon workers with independently bound endpoints and publish them dynamically to Envoy using xDS.
+
   - [Performance Tuning](https://socketry.github.io/falcon/guides/performance-tuning/index) - This guide explains the performance characteristics of Falcon.
 
   - [WebSockets](https://socketry.github.io/falcon/guides/websockets/index) - This guide explains how to use WebSockets with Falcon.
@@ -47,6 +49,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.56.0
+
+  - Add `Falcon::Environment::Cluster` and `Falcon::Service::Cluster` for running workers with independently bound endpoints.
+  - Add `Falcon::Listener` to describe bound listeners shared by regular server workers or owned by cluster workers.
+
 ### v0.55.6
 
   - Move Falcon middleware trace providers to `traces/provider/falcon/middleware`.
@@ -87,10 +94,6 @@ Please see the [project releases](https://socketry.github.io/falcon/releases/ind
 
   - Introduce `Falcon::CompositeServer` for hosting multiple server instances in a single worker.
 
-### v0.52.4
-
-  - Relax dependency on `async-container-supervisor` to allow `~> 0.6`.
-
 ## Contributing
 
 We welcome contributions to this project.

data/releases.md

@@ -1,5 +1,10 @@
 # Releases
 
+## v0.56.0
+
+  - Add `Falcon::Environment::Cluster` and `Falcon::Service::Cluster` for running workers with independently bound endpoints.
+  - Add `Falcon::Listener` to describe bound listeners shared by regular server workers or owned by cluster workers.
+
 ## v0.55.6
 
   - Move Falcon middleware trace providers to `traces/provider/falcon/middleware`.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: falcon
 version: !ruby/object:Gem::Version
-  version: 0.55.6
+  version: 0.56.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -101,14 +101,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.75'
+        version: '0.97'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.75'
+        version: '0.97'
 - !ruby/object:Gem::Dependency
   name: async-http-cache
   requirement: !ruby/object:Gem::Requirement
@@ -243,6 +243,7 @@ extra_rdoc_files: []
 files:
 - bin/falcon
 - bin/falcon-host
+- context/cluster-deployment.md
 - context/deployment.md
 - context/extended-features.md
 - context/getting-started.md
@@ -267,6 +268,7 @@ files:
 - lib/falcon/endpoint.rb
 - lib/falcon/environment.rb
 - lib/falcon/environment/application.rb
+- lib/falcon/environment/cluster.rb
 - lib/falcon/environment/configured.rb
 - lib/falcon/environment/lets_encrypt_tls.rb
 - lib/falcon/environment/proxy.rb
@@ -277,6 +279,7 @@ files:
 - lib/falcon/environment/server.rb
 - lib/falcon/environment/tls.rb
 - lib/falcon/environment/virtual.rb
+- lib/falcon/listener.rb
 - lib/falcon/middleware/proxy.rb
 - lib/falcon/middleware/redirect.rb
 - lib/falcon/middleware/verbose.rb
@@ -284,6 +287,7 @@ files:
 - lib/falcon/rackup/handler.rb
 - lib/falcon/railtie.rb
 - lib/falcon/server.rb
+- lib/falcon/service/cluster.rb
 - lib/falcon/service/server.rb
 - lib/falcon/service/virtual.rb
 - lib/falcon/tls.rb