falcon 0.56.0 → 0.57.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f7ba95aa9804ab5bccd97bdceb14467fc706c01bff4486e0ef8acac74a448567
-  data.tar.gz: b4a31ed06efddadc88a68de6d959a8b34310ec278edff5640b1b6149ce1bded3
+  metadata.gz: 4d899d227cc38f6f4b766bfcef947ec0bd7a2a1396e695e96454ed707395e6eb
+  data.tar.gz: b72457b92c692a02e23be49d05734cda178c86bf5f983c2f2dd1b8f9788de40a
 SHA512:
-  metadata.gz: 6ba9534e23c464859a54b955989c436fc1d0f639c17e621308098183fd477906db9a1348a52bb14b46ed02f16115913ee376da1e7886f782ce71ebb6869c538f
-  data.tar.gz: 4b3e498ac46f78a1f83d6fdcc2876dd91bc1ca8878f0c081579326f1fd757651d8baf02463a3038086a50f69a937e2d5cc84915c543a769ee74cddebeff99927
+  metadata.gz: 99243d8b4f61bc2280b502e664c291184c36968b8783048587ec9e1ea38f7e659b261262b73f3839873c145f7c772c849e404db0482a401be8af1bba84a9ab74
+  data.tar.gz: dcc6b26e79a764d8c522713b2b61cc1ff9d4c981a03955a0e0743a5761fa1f11b77b11b456eb0167486d32d9f0929a91afd40fbea0791286b232e02e8895464b

data/context/cluster-deployment.md

@@ -1,6 +1,6 @@
 # Dynamic Clusters with Envoy
 
-This guide explains how to run Falcon workers with independently bound endpoints and publish them dynamically to Envoy using xDS.
+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
 
@@ -17,7 +17,9 @@ A regular {ruby Falcon::Service::Server} binds one listener and shares it with e
 
 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.
+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:
 
@@ -29,14 +31,15 @@ flowchart LR
 		Envoy[Envoy]
 
 		subgraph Falcon[Falcon container]
-			Supervisor[Supervisor and xDS control plane]
+			Supervisor[Supervisor, xDS, and ORCA]
 			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
+		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
@@ -48,7 +51,7 @@ Add Falcon and the Envoy supervisor integration to your `gems.rb`:
 
 ```ruby
 gem "falcon", "~> 0.56.0"
-gem "async-service-supervisor-envoy", "~> 0.2"
+gem "async-service-supervisor-envoy", "~> 0.5"
 ```
 
 Define a Falcon cluster service and an accompanying supervisor in `falcon.rb`:
@@ -81,7 +84,7 @@ service "cluster" do
 			}, [body]]
 		end
 		
-		Falcon::Server.middleware(application, cache: false)
+		Falcon::Server.rack_middleware(application, cache: false)
 	end
 end
 
@@ -89,16 +92,21 @@ 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://127.0.0.1:18000",
+				bind: "http://[::]:18000",
+				orca: true,
+				utilization_monitor: utilization_monitor,
 			),
 		]
 	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:
+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:
@@ -106,12 +114,14 @@ node:
   cluster: falcon-cluster
 
 dynamic_resources:
-  ads_config:
-    api_type: GRPC
-    transport_api_version: V3
-    grpc_services:
-      - envoy_grpc:
-          cluster_name: xds_cluster
+  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:
@@ -128,6 +138,7 @@ static_resources:
                 stat_prefix: ingress_http
                 route_config:
                   name: local_route
+                  validate_clusters: false
                   virtual_hosts:
                     - name: falcon
                       domains: ["*"]
@@ -142,16 +153,6 @@ static_resources:
                       "@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
@@ -162,7 +163,7 @@ static_resources:
               - endpoint:
                   address:
                     socket_address:
-                      address: 127.0.0.1
+                      address: "::1"
                       port_value: 18000
       typed_extension_protocol_options:
         envoy.extensions.upstreams.http.v3.HttpProtocolOptions:
@@ -171,7 +172,7 @@ static_resources:
             http2_protocol_options: {}
 ```
 
-The `xds_cluster` connection uses HTTP/2 because ADS is served over gRPC.
+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
 
@@ -179,19 +180,24 @@ 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.
+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 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.
+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 `127.0.0.1` and `localhost` refer to the same loopback interface for both processes.
+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

@@ -21,7 +21,8 @@ files:
 - 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.
+    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/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/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/version.rb

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

data/readme.md

@@ -35,7 +35,7 @@ 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.
+  - [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.
 
@@ -49,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.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.
@@ -90,10 +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.
-
 ## Contributing
 
 We welcome contributions to this project.

data/releases.md

@@ -1,5 +1,15 @@
 # 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.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: falcon
 version: !ruby/object:Gem::Version
-  version: 0.56.0
+  version: 0.57.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -276,6 +276,7 @@ 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