async-service-supervisor-envoy 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 554c82adfbbf77fc5fe7e0ee5a0bbe9a67de5161cc7699eab8b98cf4c0cb5847
-  data.tar.gz: 44a9f2a1488f5108dc18b859b43f0ad3ec2709490784e0500587c240790d9749
+  metadata.gz: 531e6d8c0e35b0122bcec0c0234afe37be776bb8b1e56e8ee92f5d026f5739f5
+  data.tar.gz: 6b9d8f77dd753fbf1a26b076f88fecc37a1856a69ac4a0e82bc4611370fb90c8
 SHA512:
-  metadata.gz: 7752e3f6af3a6795a5f294867cb4cf11523cb4192d464ea29834278f4d7f799969c18c4a9cc9bbd70ddd035b34dc532378333be2aad12488b7822af761284954
-  data.tar.gz: a9abeeb77d2eb1ca67d219fdb9ef75820c841d7bf9c15b86ee012e4296702524ecacdd2780d9b21b1d2e3520873048741b960b1d92c5a0a0b91761bc8845ef97
+  metadata.gz: 4708ac696da72097ebf6888cf144b3076c72392e1a695cb8311d6b2046869b1522a47850ec59464beff2f588720d760ae427d7c556a75d25e36bb353535a9311
+  data.tar.gz: 3ffad268b3785b3625fc3cec1cde6dfb50d68904547ab531a19a99317cef32baa29d52ebb1d6795cebe302885598c742a9eaa18cbde2fb7ecd95c01dcfe4b04c

data/context/getting-started.md

@@ -41,16 +41,18 @@ state = {
 
 Workers without endpoint state are ignored by the Envoy monitor.
 
-Falcon cluster workers can register their concrete post-bind listener automatically:
+Falcon server workers can register their concrete bound listener automatically:
 
 ``` ruby
 service "application" do
-	include Falcon::Environment::Cluster
+	include Falcon::Environment::Server
 	include Async::Service::Supervisor::Envoy::Supervised
 end
 ```
 
-Falcon describes its bound server resource as a listener. The integration converts that listener into Envoy upstream endpoint state, including its name, scheme, supported protocols, and every concrete IP or Unix socket address. Addresses belonging to one listener remain grouped as one Envoy load-balancer endpoint.
+`Falcon::Environment::Server` reports one listener shared by all of its workers, while `Falcon::Environment::Cluster` reports the listener bound independently by each worker. Falcon describes either bound server resource as a listener. The integration converts that listener into Envoy upstream endpoint state, including its name, scheme, supported protocols, and every concrete IP or Unix socket address.
+
+Addresses belonging to one listener remain grouped as one Envoy load-balancer endpoint. When several workers report the same shared listener, the monitor publishes it once and keeps it available while any reporting worker is healthy.
 
 ## Monitor Usage
 

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

@@ -7,8 +7,23 @@ module Async
 	module Service
 		module Supervisor
 			module Envoy
-				# Represents one upstream endpoint published to Envoy EDS.
+				# Represents an upstream endpoint published to Envoy EDS.
 				class Endpoint
+					# Build an immutable endpoint.
+					# @parameter name [String] The upstream cluster name.
+					# @parameter scheme [String | Symbol] The upstream application scheme.
+					# @parameter protocols [Array(String)] The supported upstream HTTP protocol names.
+					# @parameter addresses [Array(Hash)] The grouped concrete addresses.
+					# @returns [Endpoint] The immutable endpoint.
+					def self.build(name:, scheme:, protocols:, addresses:)
+						new(
+							name.to_s,
+							scheme.to_sym,
+							protocols.map(&:to_s).uniq,
+							addresses,
+						).tap(&:freeze)
+					end
+					
 					# Wrap serialized endpoint state.
 					# @parameter value [Endpoint | Hash] The value to wrap.
 					# @returns [Endpoint] The endpoint value.
@@ -17,39 +32,26 @@ module Async
 						when self
 							value
 						when Hash
-							new(**value)
+							build(**value)
 						else
 							raise ArgumentError, "Invalid Envoy endpoint: #{value.inspect}"
 						end
 					end
 					
-					# Normalize a concrete endpoint address.
-					# @parameter value [Hash] The address value.
-					# @returns [Hash] A normalized IP or Unix address.
-					def self.normalize_address(value)
-						if path = value[:path]
-							raise ArgumentError, "A Unix endpoint cannot specify an IP address or port!" if value[:address] || value[:port]
-							
-							{path: path.to_s}.freeze
-						elsif value[:address] && value[:port]
-							{address: value[:address].to_s, port: Integer(value[:port])}.freeze
-						else
-							raise ArgumentError, "An endpoint address requires either path, or address and port: #{value.inspect}"
-						end
-					end
-					
 					# Initialize an endpoint.
 					# @parameter name [String] The upstream cluster name.
-					# @parameter scheme [String | Symbol] The upstream application scheme.
+					# @parameter scheme [Symbol] The upstream application scheme.
 					# @parameter protocols [Array(String)] The supported upstream HTTP protocol names.
 					# @parameter addresses [Array(Hash)] The grouped concrete addresses.
-					def initialize(name:, scheme:, protocols:, addresses:)
-						@name = name.to_s
-						@scheme = scheme.to_sym
-						@protocols = protocols.map(&:to_s).uniq.freeze
+					def initialize(name, scheme, protocols, addresses)
+						@name = name
+						@scheme = scheme
+						@protocols = protocols
 						raise ArgumentError, "An endpoint requires at least one protocol!" if @protocols.empty?
-						@addresses = addresses.map{|value| self.class.normalize_address(value)}.freeze
+						@addresses = addresses
 						raise ArgumentError, "An endpoint requires at least one address!" if @addresses.empty?
+						
+						@hash = nil
 					end
 					
 					# @attribute [String] The upstream cluster name.
@@ -64,6 +66,39 @@ module Async
 					# @attribute [Array(Hash)] The grouped concrete addresses.
 					attr :addresses
 					
+					# Freeze this endpoint and cache its value hash.
+					def freeze
+						return self if frozen?
+						
+						@name.freeze
+						@protocols.each(&:freeze).freeze
+						@addresses.each do |address|
+							address.each_value(&:freeze)
+							address.freeze
+						end.freeze
+						@hash = self.hash
+						
+						super
+					end
+					
+					# Compare this endpoint with another endpoint by value.
+					# @parameter other [Object] The object to compare.
+					# @returns [Boolean] Whether both endpoints have identical values.
+					def eql?(other)
+						other.instance_of?(self.class) &&
+							@name == other.name &&
+							@scheme == other.scheme &&
+							@protocols == other.protocols &&
+							@addresses == other.addresses
+					end
+					
+					alias == eql?
+					
+					# Compute the value hash used when grouping endpoints.
+					# @returns [Integer] The endpoint value hash.
+					def hash
+						@hash || [self.class, @name, @scheme, @protocols, @addresses].hash
+					end
 				end
 			end
 		end

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

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+module Async
+	module Service
+		module Supervisor
+			module Envoy
+				# Groups the workers reporting a single upstream endpoint.
+				class EndpointGroup
+					# Initialize an endpoint group.
+					# @parameter endpoint [Endpoint] The endpoint shared by the workers.
+					def initialize(endpoint)
+						@endpoint = endpoint
+						@workers = {}
+					end
+					
+					# @attribute [Endpoint] The endpoint shared by the workers.
+					attr :endpoint
+					
+					# Add or update a worker report.
+					# @parameter worker [SupervisorController] The worker reporting the endpoint.
+					# @parameter healthy [Boolean] Whether the worker considers the endpoint healthy.
+					def add(worker, healthy:)
+						@workers[worker.id] = healthy
+					end
+					
+					# Remove a worker report.
+					# @parameter worker [SupervisorController] The worker to remove.
+					# @returns [Boolean | Nil] The removed health value, if present.
+					def remove(worker)
+						@workers.delete(worker.id)
+					end
+					
+					# Count the workers reporting this endpoint.
+					# @returns [Integer] The number of reporting workers.
+					def size
+						@workers.size
+					end
+					
+					# Determine whether any workers report this endpoint.
+					# @returns [Boolean] Whether the group has no workers.
+					def empty?
+						@workers.empty?
+					end
+					
+					# Determine the aggregate endpoint health.
+					# @returns [Boolean] Whether any reporting worker is healthy.
+					def healthy?
+						@workers.each_value.any?
+					end
+					
+					# Convert the group to an xDS endpoint description.
+					# @returns [Hash] The endpoint addresses and aggregate health.
+					def as_json
+						{addresses: @endpoint.addresses, healthy: healthy?}
+					end
+				end
+			end
+		end
+	end
+end

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

@@ -10,6 +10,7 @@ require "async/grpc/xds/server"
 
 require_relative "delegate"
 require_relative "endpoint"
+require_relative "endpoint_group"
 
 module Async
 	module Service
@@ -108,6 +109,7 @@ module Async
 						{
 							cluster: cluster.to_s,
 							endpoint: endpoint,
+							worker: supervisor_controller,
 							healthy: @delegate.healthy?(supervisor_controller, endpoint),
 						}
 					end
@@ -146,9 +148,14 @@ module Async
 					
 					def build_clusters(records_by_cluster = build_records_by_cluster)
 						records_by_cluster.transform_values do |records|
-							records.map do |record|
-								{addresses: record[:endpoint].addresses, healthy: record[:healthy]}
+							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
 					end
 					

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

@@ -9,7 +9,7 @@ module Async
 	module Service
 		module Supervisor
 			module Envoy
-				# Registers post-bind cluster listeners with the supervisor.
+				# Registers bound Falcon listeners with the supervisor.
 				module Supervised
 					include Async::Service::Supervisor::Supervised
 					

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

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

data/readme.md

@@ -24,6 +24,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.1.0
+
+  - Deduplicate immutable endpoint values reported by multiple supervised workers and aggregate their health.
+
 ### v0.0.1
 
   - Register concrete Falcon cluster listeners as Envoy upstream endpoint state after binding.
@@ -32,7 +36,7 @@ Please see the [project releases](https://socketry.github.io/async-service-super
 
 ### v0.1.0
 
-  - Initial release.
+  - Deduplicate immutable endpoint values reported by multiple supervised workers and aggregate their health.
 
 ## See Also
 

data/releases.md

@@ -1,5 +1,9 @@
 # Releases
 
+## v0.1.0
+
+  - Deduplicate immutable endpoint values reported by multiple supervised workers and aggregate their health.
+
 ## v0.0.1
 
   - Register concrete Falcon cluster listeners as Envoy upstream endpoint state after binding.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: async-service-supervisor-envoy
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.1.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -104,6 +104,7 @@ files:
 - lib/async/service/supervisor/envoy.rb
 - lib/async/service/supervisor/envoy/delegate.rb
 - 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/supervised.rb
 - lib/async/service/supervisor/envoy/version.rb