async-service-supervisor-envoy 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 50a07c8f84453334cdae213344ab37e44e8b4ec170fb0f8db3bb75b0385883c1
-  data.tar.gz: 897302227c2b0b8d760dac2156f6e4ba11f3d4b325dc4fd57bb3dbb0aa6972f9
+  metadata.gz: 15171bea49a1422dc4ef04dc7f04f904dcc28e050e97365d905c15348e19877d
+  data.tar.gz: 9ccfbff50bda3608571165db4dc9b12f46668cb1b84063d8515ef0f7f3059157
 SHA512:
-  metadata.gz: dfdb7eaa42d25f280a75a31c7aa8b45ab9497f0e7380ffca09b49e060639713076807cea5a9e1265b36c65931002f6b456963309fa41605cf8d309c459abee04
-  data.tar.gz: 5e52d5bd10c4f3a53b85de3962dd60bbaee07f86a9113524e87230854a740a7d306632c69e3ba46018e8368fe4635fe5dfecbdf19cfc3a903548289c695a471e
+  metadata.gz: e8ea8643b3ae68cdb1e318e2dbae4a3b51d8c3609b7e6c1f73713828c7c76aa9539a586f810e2a91371a39b766da44471fee0b66cb22d9dcdc66d3fce7f91bfd
+  data.tar.gz: 593ec4b29fd5b582b8727fcf18552263bc286666348de95bb43dcd772e283413c28a2fdc6801d6759791266efb5253ea4f29d494aa78ea3affe922b64fd70f94

data/context/getting-started.md

@@ -94,3 +94,34 @@ Async::Service::Supervisor::Envoy::Monitor.new(
 ```
 
 Disconnected workers are removed from EDS. Registered workers that fail the delegate health check remain in EDS with an unhealthy endpoint status.
+
+## Load-aware Balancing
+
+Enable out-of-band ORCA reporting to let Envoy weight independently bound workers using their current processor utilization and request throughput:
+
+``` ruby
+utilization_monitor = Async::Service::Supervisor::UtilizationMonitor.new(interval: 1)
+
+[
+	utilization_monitor,
+	Async::Service::Supervisor::Envoy::Monitor.new(
+		bind: "http://0.0.0.0:18000",
+		orca: true,
+		utilization_monitor: utilization_monitor,
+		interval: 1
+	)
+]
+```
+
+The supervisor utilization monitor manages each worker's shared-memory allocation and registration. The Envoy monitor samples it through `sample_by_worker`, combines each worker's `requests_total` counter with processor usage from `process-metrics`, and serves the resulting ORCA reports from the same HTTP/2 endpoint as ADS. It also configures each discovered cluster to use Envoy's client-side weighted-round-robin policy.
+
+The first sample establishes a baseline. Subsequent reports contain normalized `cpu_utilization` and `rps_fractional` values for each worker. Reports are removed immediately when a worker disconnects.
+
+Out-of-band ORCA requires:
+
+  - Envoy 1.39 or later.
+  - A fixed TCP port for the monitor's `bind` address.
+  - A supervisor utilization monitor registered alongside the Envoy monitor.
+  - Independently addressable TCP worker endpoints. Unix sockets and endpoints shared by several workers cannot provide distinct per-worker ORCA identities.
+
+The monitor address and worker addresses must be reachable from Envoy. In a sidecar deployment, binding the monitor to a fixed port in the shared network namespace satisfies this requirement.

data/lib/async/service/supervisor/envoy/monitor.rb

@@ -5,12 +5,17 @@
 
 require "async/http/endpoint"
 require "async/service/supervisor/monitor"
+require "async/service/supervisor/utilization_monitor"
+require "async/grpc/xds/client_side_weighted_round_robin"
 require "async/grpc/xds/control_plane"
 require "async/grpc/xds/server"
+require "process/metrics"
+require "xds/data/orca/v3/orca_load_report_pb"
 
 require_relative "delegate"
 require_relative "endpoint"
 require_relative "endpoint_group"
+require_relative "orca_service"
 
 module Async
 	module Service
@@ -23,21 +28,45 @@ module Async
 					# @parameter bind [String | Nil] The optional address for the xDS control plane server.
 					# @parameter delegate [Delegate] The delegate used to map supervisor state into Envoy endpoints.
 					# @parameter control_plane [Async::GRPC::XDS::ControlPlane] The xDS control plane to update.
+					# @parameter orca [Boolean] Whether to collect and serve per-worker ORCA load reports.
+					# @parameter processor [Process::Metrics::Processor | Nil] The optional process CPU sampler.
+					# @parameter utilization_monitor [Async::Service::Supervisor::UtilizationMonitor | Nil] The per-worker utilization monitor used for ORCA reporting.
+					# @parameter interval [Numeric] The endpoint reconciliation and ORCA reporting interval in seconds.
 					def initialize(
 						bind: nil,
 						delegate: Delegate.new,
 						control_plane: Async::GRPC::XDS::ControlPlane.new,
+						orca: false,
+						processor: nil,
+						utilization_monitor: nil,
+						interval: 1,
 						**options
 					)
-						super(**options)
+						super(interval: interval, **options)
 						
 						@bind = bind
 						@delegate = delegate
 						@control_plane = control_plane
+						@interval = interval
+						@orca = orca
 						@controllers = {}
 						@published_clusters = {}
 						@server_task = nil
 						@mutex = Mutex.new
+						
+						if @orca
+							raise ArgumentError, "ORCA reporting requires a TCP bind address!" unless @bind
+							raise ArgumentError, "ORCA reporting requires a utilization monitor!" unless utilization_monitor
+							
+							@orca_port = server_endpoint.url.port
+							raise ArgumentError, "ORCA reporting requires a fixed TCP port!" unless @orca_port&.positive?
+							
+							@processor = processor || Process::Metrics::Processor.new
+							@utilization_monitor = utilization_monitor
+							@request_totals = {}
+							@load_reports = {}
+							@authorities = {}
+						end
 					end
 					
 					# @attribute [Async::GRPC::XDS::ControlPlane] The xDS control plane receiving cluster and endpoint updates.
@@ -52,6 +81,7 @@ module Async
 					def register(supervisor_controller)
 						@mutex.synchronize do
 							@controllers[supervisor_controller.id] = supervisor_controller
+							@authorities[worker_hostname(supervisor_controller)] = supervisor_controller.id if @orca
 							reconcile
 						end
 					end
@@ -62,6 +92,12 @@ module Async
 					def remove(supervisor_controller)
 						@mutex.synchronize do
 							@controllers.delete(supervisor_controller.id)
+							if @orca
+								hostname = worker_hostname(supervisor_controller)
+								@authorities.delete(hostname)
+								@load_reports.delete(hostname)
+								@request_totals.delete(supervisor_controller.id)
+							end
 							reconcile
 						end
 					end
@@ -74,8 +110,9 @@ module Async
 						
 						if @bind
 							@server_task = parent.async do
-								endpoint = Async::HTTP::Endpoint.parse(@bind, protocol: Async::HTTP::Protocol::HTTP2)
-								Async::GRPC::XDS::Server.new(@control_plane).run(endpoint)
+								server = Async::GRPC::XDS::Server.new(@control_plane)
+								server.dispatcher.register(ORCAService.new(self, minimum_interval: @interval)) if @orca
+								server.run(server_endpoint)
 							end
 						end
 						
@@ -92,9 +129,29 @@ module Async
 						end
 					end
 					
+					# Determine whether an ORCA worker authority is currently registered.
+					# @parameter authority [String] The gRPC request authority.
+					# @returns [Boolean] Whether the authority identifies a live worker.
+					def worker?(authority)
+						return false unless @orca
+						
+						@mutex.synchronize{@authorities.key?(authority)}
+					end
+					
+					# Get the latest ORCA report for a worker authority.
+					# @parameter authority [String] The gRPC request authority.
+					# @returns [Xds::Data::Orca::V3::OrcaLoadReport | Nil] The latest valid report, if available.
+					def load_report(authority)
+						return unless @orca
+						
+						@mutex.synchronize{@load_reports[authority]}
+					end
+					
 					# Refresh endpoint health and publish updated EDS state.
 					# @returns [void]
 					def run_once
+						sample_load_reports if @orca
+						
 						@mutex.synchronize do
 							reconcile
 						end
@@ -102,6 +159,14 @@ module Async
 					
 					private
 					
+					def server_endpoint
+						@server_endpoint ||= Async::HTTP::Endpoint.parse(@bind, protocol: Async::HTTP::Protocol::HTTP2)
+					end
+					
+					def worker_hostname(supervisor_controller)
+						"worker-#{supervisor_controller.id}"
+					end
+					
 					def build_record(supervisor_controller, endpoint)
 						cluster = @delegate.cluster(supervisor_controller, endpoint)
 						return unless cluster
@@ -148,14 +213,24 @@ module Async
 					
 					def build_clusters(records_by_cluster = build_records_by_cluster)
 						records_by_cluster.transform_values do |records|
-							groups = {}
-							
-							records.each do |record|
-								group = groups[record[:endpoint]] ||= EndpointGroup.new(record[:endpoint])
-								group.add(record[:worker], healthy: record[:healthy])
+							if @orca
+								records.map do |record|
+									{
+										addresses: record[:endpoint].addresses,
+										healthy: record[:healthy],
+										hostname: worker_hostname(record[:worker]),
+									}
+								end
+							else
+								groups = {}
+								
+								records.each do |record|
+									group = groups[record[:endpoint]] ||= EndpointGroup.new(record[:endpoint])
+									group.add(record[:worker], healthy: record[:healthy])
+								end
+								
+								groups.each_value.map(&:as_json)
 							end
-							
-							groups.each_value.map(&:as_json)
 						end
 					end
 					
@@ -168,7 +243,71 @@ module Async
 						raise ArgumentError, "Envoy cluster contains no common protocols: #{protocols.inspect}" if common_protocols.empty?
 						raise ArgumentError, "HTTPS upstream endpoints are not yet supported!" if schemes.first == :https
 						
-						{protocol: envoy_protocol(common_protocols)}
+						configuration = {protocol: envoy_protocol(common_protocols)}
+						
+						if @orca
+							if records.any?{|record| record[:endpoint].addresses.any?{|address| address[:path]}}
+								raise ArgumentError, "Out-of-band ORCA reporting requires IP endpoints!"
+							end
+							
+							configuration[:load_balancing_policy] = Async::GRPC::XDS::ClientSideWeightedRoundRobin.build(
+								@orca_port,
+								reporting_period: @interval
+							)
+						end
+						
+						configuration
+					end
+					
+					def sample_load_reports
+						controllers = @mutex.synchronize{@controllers.dup}
+						workers = @utilization_monitor.sample_by_worker
+						process_ids = controllers.each_value.filter_map(&:process_id)
+						processor_samples = @processor.sample(process_ids)
+						request_totals = {}
+						
+						workers.each do |worker_id, worker|
+							requests_total = worker[:utilization][:requests_total]
+							if requests_total.is_a?(Numeric) && requests_total.finite?
+								request_totals[worker_id] = requests_total
+							end
+						end
+						
+						@mutex.synchronize do
+							controllers.each do |worker_id, controller|
+								next unless @controllers[worker_id].equal?(controller)
+								
+								hostname = worker_hostname(controller)
+								processor_sample = processor_samples[controller.process_id]
+								requests_total = request_totals[worker_id]
+								previous_requests_total = @request_totals[worker_id]
+								
+								if processor_sample && requests_total && previous_requests_total && requests_total >= previous_requests_total
+									rps = (requests_total - previous_requests_total).fdiv(processor_sample.duration)
+									cpu = processor_sample.utilization
+									
+									if rps.finite? && cpu.finite?
+										@load_reports[hostname] = Xds::Data::Orca::V3::OrcaLoadReport.new(
+											cpu_utilization: cpu,
+											rps_fractional: rps,
+											named_metrics: {"orca.heartbeat" => 0.0},
+										)
+										next
+									end
+								end
+								
+								@load_reports.delete(hostname)
+							end
+							
+							@request_totals = request_totals
+							
+							Console.debug(self, "Sampled ORCA load reports.",
+								workers: workers.keys,
+								processes: processor_samples.keys,
+								requests: request_totals,
+								reports: @load_reports.keys,
+							)
+						end
 					end
 					
 					def envoy_protocol(protocols)

data/lib/async/service/supervisor/envoy/orca_service.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "async/grpc/service"
+require "protocol/http/body/writable"
+require "xds/service/orca/v3/open_rca_service"
+
+module Async
+	module Service
+		module Supervisor
+			module Envoy
+				# Streams per-worker out-of-band ORCA load reports to Envoy.
+				class ORCAService < Async::GRPC::Service
+					SERVICE_NAME = "xds.service.orca.v3.OpenRcaService"
+					EMPTY_REPORT = Xds::Data::Orca::V3::OrcaLoadReport.new(
+						named_metrics: {"orca.heartbeat" => 0.0}
+					)
+					
+					# Initialize the ORCA service.
+					# @parameter monitor [Monitor] The monitor providing worker load reports.
+					# @parameter minimum_interval [Numeric] The minimum reporting interval in seconds.
+					def initialize(monitor, minimum_interval: 1)
+						super(Xds::Service::Orca::V3::OpenRcaService, SERVICE_NAME)
+						
+						@monitor = monitor
+						@minimum_interval = minimum_interval
+					end
+					
+					# Stream current load reports for the worker named by the request authority.
+					# @parameter input [Interface(:read)] The ORCA request stream.
+					# @parameter output [Interface(:write)] The ORCA report stream.
+					# @parameter call [Protocol::GRPC::Call] The gRPC call context.
+					# @asynchronous
+					def stream_core_metrics(input, output, call)
+						request = input.read
+						return unless request
+						
+						authority = call.request.authority
+						interval = [duration(request.report_interval), @minimum_interval].max
+						
+						while @monitor.worker?(authority)
+							output.write(@monitor.load_report(authority) || EMPTY_REPORT)
+							
+							sleep(interval)
+						end
+					rescue Protocol::HTTP::Body::Writable::Closed
+						# The client closed the reporting stream.
+					end
+					
+					private
+					
+					def duration(value)
+						return 0 unless value
+						
+						value.seconds + value.nanos.fdiv(1_000_000_000)
+					end
+				end
+			end
+		end
+	end
+end

data/lib/async/service/supervisor/envoy/version.rb

@@ -11,7 +11,7 @@ module Async
 		module Supervisor
 			# @namespace
 			module Envoy
-				VERSION = "0.2.0"
+				VERSION = "0.3.0"
 			end
 		end
 	end

data/lib/async/service/supervisor/envoy.rb

@@ -7,4 +7,5 @@ require_relative "envoy/version"
 require_relative "envoy/delegate"
 require_relative "envoy/endpoint"
 require_relative "envoy/monitor"
+require_relative "envoy/orca_service"
 require_relative "envoy/supervised"

data/readme.md

@@ -13,6 +13,7 @@ Provides an Envoy xDS monitor for `async-service-supervisor`.
   - **Multiple clusters** - Groups workers by `state[:name]` by default.
   - **Endpoint contract** - Converts concrete post-bind worker listeners into Envoy upstream endpoints, including grouped IP or Unix socket addresses.
   - **Delegate mapping** - Uses a delegate object for endpoint selection, cluster grouping, and health without active probing.
+  - **Load-aware balancing** - Optionally reports per-worker CPU utilization and request throughput to Envoy using out-of-band ORCA.
 
 ## Usage
 
@@ -24,6 +25,10 @@ Please see the [project documentation](https://socketry.github.io/async-service-
 
 Please see the [project releases](https://socketry.github.io/async-service-supervisor-envoy/releases/index) for all releases.
 
+### v0.3.0
+
+  - Add supervisor-driven out-of-band ORCA load reporting for independently addressable workers.
+
 ### v0.2.0
 
   - Accept the required Falcon listener as a positional worker preparation argument.

data/releases.md

@@ -1,5 +1,9 @@
 # Releases
 
+## v0.3.0
+
+  - Add supervisor-driven out-of-band ORCA load reporting for independently addressable workers.
+
 ## v0.2.0
 
   - Accept the required Falcon listener as a positional worker preparation argument.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: async-service-supervisor-envoy
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -58,14 +58,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.1'
+        version: '0.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.1'
+        version: '0.2'
 - !ruby/object:Gem::Dependency
   name: async-http
   requirement: !ruby/object:Gem::Requirement
@@ -86,14 +86,28 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.18'
+        version: '0.20'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.18'
+        version: '0.20'
+- !ruby/object:Gem::Dependency
+  name: process-metrics
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.12'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.12'
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -106,6 +120,7 @@ files:
 - lib/async/service/supervisor/envoy/endpoint.rb
 - lib/async/service/supervisor/envoy/endpoint_group.rb
 - lib/async/service/supervisor/envoy/monitor.rb
+- lib/async/service/supervisor/envoy/orca_service.rb
 - lib/async/service/supervisor/envoy/supervised.rb
 - lib/async/service/supervisor/envoy/version.rb
 - license.md