falcon 0.55.6 → 0.57.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9efae16cb2a08be54e0b1099559fdb943d7ef5a85d709b57f4caa2590d08ff8f
-  data.tar.gz: 4f03dd493732da1714b55ec9af8df3d1ec7e20ce0bd51e9ef48f5cee1e8141ed
+  metadata.gz: 4d899d227cc38f6f4b766bfcef947ec0bd7a2a1396e695e96454ed707395e6eb
+  data.tar.gz: b72457b92c692a02e23be49d05734cda178c86bf5f983c2f2dd1b8f9788de40a
 SHA512:
-  metadata.gz: c0301ea50dea981115c09258abe18b55e8327bfcf2a74d018a4b1b7a55c1567521f8afb38b16b52a4559dc181df922af0408901bd7b79c6ac61a6cbc16b6c8b7
-  data.tar.gz: 5270c593232e8d23d4157faa6b85176b5c95d220c4c0360871cb11e8990d04d1c2f508ef1681b1ff1e7c87fc408f5a68783d4fcf094812317ec8f241627d5a32
+  metadata.gz: 99243d8b4f61bc2280b502e664c291184c36968b8783048587ec9e1ea38f7e659b261262b73f3839873c145f7c772c849e404db0482a401be8af1bba84a9ab74
+  data.tar.gz: dcc6b26e79a764d8c522713b2b61cc1ff9d4c981a03955a0e0743a5761fa1f11b77b11b456eb0167486d32d9f0929a91afd40fbea0791286b232e02e8895464b

data/context/cluster-deployment.md

@@ -0,0 +1,203 @@
+# Dynamic Clusters with Envoy
+
+This guide explains how to run Falcon workers with independently bound endpoints, publish them dynamically using xDS, and balance requests according to their current load using ORCA.
+
+## 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 and load-balancing policy through an xDS control plane. Envoy uses Cluster Discovery Service (CDS) and Endpoint Discovery Service (EDS) updates to maintain the upstream cluster.
+
+The supervisor also samples each worker's CPU utilization and request counter. It exposes those measurements using out-of-band Open Request Cost Aggregation (ORCA), which lets Envoy's client-side weighted-round-robin policy direct more requests to workers with more available capacity. This avoids coupling connection acceptance to a process-local token limiter while still responding to CPU-heavy work.
+
+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, xDS, and ORCA]
+			Worker1[Falcon worker 1]
+			Worker2[Falcon worker 2]
+		end
+
+		Worker1 -.->|Register endpoint| Supervisor
+		Worker2 -.->|Register endpoint| Supervisor
+		Supervisor -.->|Dedicated CDS and EDS streams| Envoy
+		Supervisor -.->|Per-worker ORCA reports| 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.5"
+```
+
+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.rack_middleware(application, cache: false)
+	end
+end
+
+service "supervisor" do
+	include Async::Service::Supervisor::Environment
+	
+	monitors do
+		utilization_monitor = Async::Service::Supervisor::UtilizationMonitor.new
+		
+		[
+			utilization_monitor,
+			Async::Service::Supervisor::Envoy::Monitor.new(
+				bind: "http://[::]:18000",
+				orca: true,
+				utilization_monitor: utilization_monitor,
+			),
+		]
+	end
+end
+```
+
+The Falcon service name becomes the listener name, so the corresponding Envoy cluster uses `cluster` as its service name. Configure Envoy to receive cluster and endpoint updates from the supervisor:
+
+```yaml
+node:
+  id: falcon-cluster
+  cluster: falcon-cluster
+
+dynamic_resources:
+  cds_config:
+    resource_api_version: V3
+    api_config_source:
+      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
+                  validate_clusters: false
+                  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: xds_cluster
+      connect_timeout: 1s
+      type: STATIC
+      load_assignment:
+        cluster_name: xds_cluster
+        endpoints:
+          - lb_endpoints:
+              - endpoint:
+                  address:
+                    socket_address:
+                      address: "::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 CDS and EDS are served over gRPC. The supervisor serves dedicated CDS and EDS streams together with ORCA on port `18000`; Envoy uses that as an alternative to each worker's HTTP port when opening ORCA streams. Envoy 1.39 or later is required for this alternative reporting-port configuration.
+
+## 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 cluster policy and current worker endpoints as CDS and EDS resources.
+4. Envoy receives the resources over dedicated CDS and EDS streams and updates its upstream cluster.
+5. The supervisor samples worker CPU time and request totals, then streams the current load reports to Envoy using ORCA.
+
+The first processor and request samples establish baselines. Load-aware weights become available after the next sampling interval. If a report is temporarily unavailable, Envoy retains its normal policy fallback rather than making the worker unreachable.
+
+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 removes both its endpoint and ORCA report. 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 EDS 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 loopback addresses refer to the same interface for both processes.
+
+The configuration binds the supervisor endpoint to the IPv6 wildcard address because `localhost` worker endpoints use IPv6 in the container. Envoy connects to CDS and EDS through `::1`; for each ORCA stream it uses the worker's address with the configured supervisor port `18000`. The supervisor listener must therefore be reachable using the same address family as every published worker endpoint.
+
+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/getting-started.md

@@ -44,6 +44,23 @@ Then run the application with:
 $ falcon serve
 ~~~
 
+#### Rack Applications Defined in Ruby Files
+
+Rack can load a Ruby file directly and infer the application constant from its filename. For example, `Rack::Builder.parse_file("app.rb")` requires the file and uses `::App` as the Rack application.
+
+Falcon reserves `.rb` serve configurations for protocol HTTP middleware. Existing Rack applications can be exposed through `config/serve.rb` using {ruby Protocol::Rack::Adapter}:
+
+~~~ ruby
+# config/serve.rb
+
+require "protocol/rack"
+require_relative "../app"
+
+run Protocol::Rack::Adapter.new(App)
+~~~
+
+Running `falcon serve` loads `config/serve.rb` as protocol HTTP middleware, while the adapter translates requests and responses for the existing Rack application. This replaces the older `falcon serve --config app.rb` convention without requiring changes to `App` itself.
+
 ## Running a Local Server
 
 For local application development, you can use the `falcon serve` command. This will start a local server on `https://localhost:9292`. Falcon generates self-signed certificates for `localhost`. This allows you to test your application with HTTPS locally.

data/context/index.yaml

@@ -18,6 +18,11 @@ 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, publish them dynamically using xDS, and balance requests according
+    to their current load using ORCA.
 - path: performance-tuning.md
   title: Performance Tuning
   description: This guide explains the performance characteristics of Falcon.

data/lib/falcon/command/serve.rb

@@ -8,7 +8,7 @@ require_relative "../server"
 require_relative "../endpoint"
 require_relative "../service/server"
 require_relative "../environment/server"
-require_relative "../environment/rackup"
+require_relative "../environment/serve"
 
 require "async/service/configuration"
 require "async/container"
@@ -32,7 +32,7 @@ module Falcon
 				option "-h/--hostname <hostname>", "Specify the hostname which would be used for certificates, etc."
 				option "-t/--timeout <duration>", "Specify the maximum time to wait for non-blocking operations.", type: Float, default: nil
 				
-				option "-c/--config <path>", "Rackup configuration file to load.", default: "config.ru"
+				option "-c/--config <path>", "Application configuration file to load."
 				option "--preload <path>", "Preload the specified path before creating containers."
 				
 				option "--cache", "Enable the response cache."
@@ -72,7 +72,7 @@ module Falcon
 			# @returns [Async::Service::Environment] The configured server environment.
 			def environment
 				Async::Service::Environment.new(Falcon::Environment::Server).with(
-					Falcon::Environment::Rackup,
+					Falcon::Environment::Serve,
 					root: Dir.pwd,
 					
 					verbose: self.parent&.verbose?,
@@ -81,7 +81,7 @@ module Falcon
 					container_options: self.container_options,
 					endpoint_options: self.endpoint_options,
 					
-					rackup_path: @options[:config],
+					configuration_path: @options[:config],
 					preload: [@options[:preload]].compact,
 					url: @options[:bind],
 					

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/rackup.rb

@@ -25,7 +25,7 @@ module Falcon
 			# Build the middleware stack for the rack application.
 			# @returns [Protocol::HTTP::Middleware] The middleware stack.
 			def middleware
-				::Falcon::Server.middleware(rack_app, verbose: verbose, cache: cache)
+				::Falcon::Server.rack_middleware(rack_app, verbose: verbose, cache: cache)
 			end
 		end
 	end

data/lib/falcon/environment/serve.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "protocol/http/middleware/builder"
+require "protocol/rack"
+
+require_relative "../server"
+
+module Falcon
+	module Environment
+		# Provides application configuration discovery and loading for `falcon serve`.
+		#
+		# When {#configuration_path} is `nil`, {#resolved_configuration_path} looks for
+		# `config/serve.rb` first and falls back to `config.ru`. An explicit
+		# {#configuration_path} bypasses this discovery order.
+		#
+		# The file extension selects the application interface:
+		#
+		# - `.rb` files are evaluated by {Protocol::HTTP::Middleware.load} using the
+		#   protocol HTTP middleware builder interface.
+		# - `.ru` files are parsed as Rack applications and wrapped with
+		#   {Protocol::Rack::Adapter}.
+		#
+		# Both application interfaces respond to `call`, so the configuration file
+		# extension is the explicit contract rather than inspecting the loaded object.
+		module Serve
+			# The explicitly specified application configuration path, if any.
+			# @returns [String | Nil]
+			def configuration_path
+				nil
+			end
+			
+			# Resolve the application configuration path.
+			# @returns [String] The absolute application configuration path.
+			def resolved_configuration_path
+				if configuration_path
+					return File.expand_path(configuration_path, root)
+				end
+				
+				serve_path = File.expand_path("config/serve.rb", root)
+				if File.file?(serve_path)
+					return serve_path
+				end
+				
+				rackup_path = File.expand_path("config.ru", root)
+				if File.file?(rackup_path)
+					return rackup_path
+				end
+				
+				raise ArgumentError, "Could not find config/serve.rb or config.ru in #{root}!"
+			end
+			
+			# Load and wrap the configured application.
+			# @returns [Protocol::HTTP::Middleware] The middleware stack.
+			def middleware
+				path = resolved_configuration_path
+				
+				case File.extname(path)
+				when ".rb"
+					application = ::Protocol::HTTP::Middleware.load(path)
+					return ::Falcon::Server.protocol_middleware(application, verbose: verbose, cache: cache)
+				when ".ru"
+					application = ::Protocol::Rack::Adapter.parse_file(path)
+					return ::Falcon::Server.rack_middleware(application, verbose: verbose, cache: cache)
+				else
+					raise ArgumentError, "Unsupported application configuration: #{path}!"
+				end
+			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/server.rb

@@ -17,11 +17,26 @@ require "protocol/rack"
 module Falcon
 	# A server listening on a specific endpoint, hosting a specific middleware.
 	class Server < Async::HTTP::Server
-		# Wrap a rack application into a middleware suitable the server.
+		# @deprecated Use {rack_middleware} instead.
+		def self.middleware(...)
+			warn("`Falcon::Server.middleware` is deprecated, use `.rack_middleware` instead.", uplevel: 1, category: :deprecated) if $VERBOSE
+			
+			return self.rack_middleware(...)
+		end
+		
+		# Wrap a Rack application with the standard server middleware.
 		# @parameter rack_app [Proc | Object] A rack application/middleware.
 		# @parameter verbose [Boolean] Whether to add the {Middleware::Verbose} middleware.
 		# @parameter cache [Boolean] Whether to add the {Async::HTTP::Cache} middleware.
-		def self.middleware(rack_app, verbose: false, cache: true)
+		def self.rack_middleware(rack_app, verbose: false, cache: true)
+			return self.protocol_middleware(::Protocol::Rack::Adapter.new(rack_app), verbose: verbose, cache: cache)
+		end
+		
+		# Wrap a protocol application with the standard server middleware.
+		# @parameter application [Protocol::HTTP::Middleware] The protocol application/middleware.
+		# @parameter verbose [Boolean] Whether to add the {Middleware::Verbose} middleware.
+		# @parameter cache [Boolean] Whether to add the {Async::HTTP::Cache} middleware.
+		def self.protocol_middleware(application, verbose: false, cache: true)
 			::Protocol::HTTP::Middleware.build do
 				if verbose
 					use Middleware::Verbose
@@ -32,9 +47,7 @@ module Falcon
 				end
 				
 				use ::Protocol::HTTP::ContentEncoding
-				
-				use ::Protocol::Rack::Adapter
-				run rack_app
+				run application
 			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.57.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, publish them dynamically using xDS, and balance requests according to their current load using ORCA.
+
   - [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,16 @@ 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.57.0
+
+  - Update the Envoy cluster example to use dedicated CDS and EDS services from `async-service-supervisor-envoy` v0.5.
+  - [Rack Compatibility](https://socketry.github.io/falcon/releases/index#rack-compatibility)
+
+### 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`.
@@ -83,14 +95,6 @@ Please see the [project releases](https://socketry.github.io/falcon/releases/ind
 
   - Fix handling of old style supervisors from `Async::Container::Supervisor`.
 
-### v0.54.0
-
-  - 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,20 @@
 # Releases
 
+## v0.57.0
+
+  - Update the Envoy cluster example to use dedicated CDS and EDS services from `async-service-supervisor-envoy` v0.5.
+
+### Rack Compatibility
+
+Falcon is shifting its application boundary from a Rack-centric design to {ruby Protocol::HTTP::Middleware}. `falcon serve` now prefers protocol HTTP middleware configured by `config/serve.rb`, while continuing to discover and run Rack `config.ru` applications through {ruby Protocol::Rack::Adapter}.
+
+Use {ruby Falcon::Server.protocol\_middleware} for protocol HTTP applications and {ruby Falcon::Server.rack\_middleware} for Rack applications. {ruby Falcon::Server.middleware} is deprecated. Explicit `.rb` serve configurations are now interpreted as {ruby Protocol::HTTP::Middleware}; Rack applications defined in Ruby files should use `config.ru` or wrap the application explicitly with {ruby Protocol::Rack::Adapter}.
+
+## 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.57.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
@@ -274,9 +276,11 @@ files:
 - lib/falcon/environment/rackup.rb
 - lib/falcon/environment/redirect.rb
 - lib/falcon/environment/self_signed_tls.rb
+- lib/falcon/environment/serve.rb
 - 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 +288,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