async-grpc-xds 0.0.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fba6859fd43ebb2de75d228d4511125d1c7b36f08321fdda99eabf573fea900a
-  data.tar.gz: 2bca6eb3ec749a434703f0296f6a12c14e6d75f5518930618355e3abd8b37d83
+  metadata.gz: 49d59879d476dd4d2e5f134a637371d29e1d0f352b35f22494630e424919e64d
+  data.tar.gz: 8a6898813f97f84ef507a4bd001f8fc224912d297296cc3439f523853bf43f44
 SHA512:
-  metadata.gz: 78f056024e2e5c0cfbf1e1ca67acf9edd9b6ca357659911cbd733eeb2fde2ff0d73c169724a2caebd1ea1860bfaa09ce07784d950a5e9908c9c1a07c2021e81d
-  data.tar.gz: 4e9a3490cfb4e8918994301ef300a2780929dffd31dec5278bf690f976e37681e9476f58899fc668f9799d3d9398fbc740654d42599a7ee8b01c265a47a70e7b
+  metadata.gz: 0f19714dcf5dd780cdfa9e7df25dcc52aa921ece5f168d10b0e8b2b34896a171098f4c907590e0ca27f8e43bf01e0e737faeb41bb2a746770762bb7dd807d1dd
+  data.tar.gz: a5c9b8d7e1cfff638f626c03f7643c5e27385365e30cb9bdaaf7802c3ba8655fd71dff1523506f2cb96ab70d9230a86ec9040bccf1c446b4de9ea15eb6788990

data/lib/async/grpc/xds/ads_stream.rb

@@ -24,6 +24,10 @@ module Async
 					end
 				end
 				
+				# Initialize an ADS stream.
+				# @parameter client [Async::GRPC::Client] The gRPC client used to open the stream.
+				# @parameter node [Envoy::Config::Core::V3::Node] The xDS node identity.
+				# @parameter delegate [Delegate] The object that receives stream events.
 				def initialize(client, node, delegate:)
 					@client = client
 					@node = node

data/lib/async/grpc/xds/client_side_weighted_round_robin.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "google/protobuf/any_pb"
+require "google/protobuf/duration_pb"
+require "google/protobuf/wrappers_pb"
+
+require "envoy/config/cluster/v3/cluster_pb"
+require "envoy/extensions/load_balancing_policies/client_side_weighted_round_robin/v3/client_side_weighted_round_robin_pb"
+
+module Async
+	module GRPC
+		module XDS
+			# Builds Envoy's client-side weighted-round-robin policy with out-of-band ORCA reporting.
+			module ClientSideWeightedRoundRobin
+				# Build the typed load-balancing policy.
+				# @parameter port [Integer] The alternative TCP port hosting the ORCA service.
+				# @parameter reporting_period [Numeric] The requested ORCA reporting interval in seconds.
+				# @returns [Envoy::Config::Cluster::V3::LoadBalancingPolicy] The typed load-balancing policy.
+				def self.build(port, reporting_period: 1)
+					seconds = reporting_period.to_i
+					duration = Google::Protobuf::Duration.new(
+						seconds: seconds,
+						nanos: ((reporting_period.to_f - seconds) * 1_000_000_000).to_i
+					)
+					configuration = Envoy::Extensions::LoadBalancingPolicies::ClientSideWeightedRoundRobin::V3::ClientSideWeightedRoundRobin.new(
+						enable_oob_load_report: Google::Protobuf::BoolValue.new(value: true),
+						oob_reporting_period: duration,
+						oob_reporting_config: Envoy::Extensions::LoadBalancingPolicies::Common::V3::OrcaOobReportingConfig.new(
+							port_value: Integer(port)
+						)
+					)
+					
+					Envoy::Config::Cluster::V3::LoadBalancingPolicy.new(
+						policies: [
+							Envoy::Config::Cluster::V3::LoadBalancingPolicy::Policy.new(
+								typed_extension_config: Envoy::Config::Core::V3::TypedExtensionConfig.new(
+									name: "envoy.load_balancing_policies.client_side_weighted_round_robin",
+									typed_config: Google::Protobuf::Any.new(
+										type_url: "type.googleapis.com/#{configuration.class.descriptor.name}",
+										value: configuration.to_proto
+									)
+								)
+							)
+						]
+					)
+				end
+			end
+		end
+	end
+end

data/lib/async/grpc/xds/cluster.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "google/protobuf/duration_pb"
+
+require "envoy/config/cluster/v3/cluster_pb"
+require "envoy/config/core/v3/config_source_pb"
+require "envoy/config/core/v3/protocol_pb"
+
+module Async
+	module GRPC
+		module XDS
+			# Builds Envoy cluster resources.
+			module Cluster
+				extend self
+				
+				TYPE_URL = "type.googleapis.com/envoy.config.cluster.v3.Cluster"
+				
+				# Build an EDS cluster resource.
+				# @parameter name [String] The cluster name.
+				# @parameter service_name [String] The EDS service name.
+				# @parameter load_balancing_policy [Envoy::Config::Cluster::V3::LoadBalancingPolicy | Nil] The typed Envoy load-balancing policy.
+				# @parameter connect_timeout [Numeric] The upstream connection timeout in seconds.
+				# @parameter protocol [Symbol] The canonical upstream protocol, either `:http1` or `:http2`.
+				# @returns [Envoy::Config::Cluster::V3::Cluster] The generated cluster resource.
+				# @raises [ArgumentError] If the upstream protocol is unsupported.
+				def build(name, service_name: name, load_balancing_policy: nil, connect_timeout: 5, protocol: :http2)
+					options = {
+						name: name.to_s,
+						type: Envoy::Config::Cluster::V3::Cluster::DiscoveryType::EDS,
+						eds_cluster_config: Envoy::Config::Cluster::V3::Cluster::EdsClusterConfig.new(
+							service_name: service_name.to_s,
+							eds_config: Envoy::Config::Core::V3::ConfigSource.new(
+								ads: Envoy::Config::Core::V3::AggregatedConfigSource.new
+							)
+						),
+						connect_timeout: duration(connect_timeout),
+					}
+					
+					options[:load_balancing_policy] = load_balancing_policy if load_balancing_policy
+					
+					case protocol
+					when :http1
+						# Envoy uses HTTP/1 by default.
+					when :http2
+						options[:http2_protocol_options] = Envoy::Config::Core::V3::Http2ProtocolOptions.new
+					else
+						raise ArgumentError, "Unsupported upstream protocol: #{protocol.inspect}"
+					end
+					
+					Envoy::Config::Cluster::V3::Cluster.new(**options)
+				end
+				
+				private
+				
+				# Convert seconds to a protobuf duration.
+				# @parameter seconds [Numeric] The duration in seconds.
+				# @returns [Google::Protobuf::Duration] The protobuf duration.
+				# @private
+				def duration(seconds)
+					whole_seconds = seconds.to_i
+					nanos = ((seconds.to_f - whole_seconds) * 1_000_000_000).to_i
+					
+					Google::Protobuf::Duration.new(seconds: whole_seconds, nanos: nanos)
+				end
+			end
+		end
+	end
+end

data/lib/async/grpc/xds/control_plane.rb

@@ -10,17 +10,22 @@ require "async/queue"
 
 require "envoy/config/core/v3/base_pb"
 require "envoy/service/discovery/v3/discovery_pb"
+require "google/protobuf/any_pb"
+require "google/protobuf/well_known_types"
 
-require_relative "resource_builder"
+require_relative "cluster"
+require_relative "endpoint"
 
 module Async
 	module GRPC
 		module XDS
 			# Maintains xDS resource snapshots and notifies ADS streams when resources change.
 			class ControlPlane
-				CLUSTER_TYPE = ResourceBuilder::CLUSTER_TYPE
-				ENDPOINT_TYPE = ResourceBuilder::ENDPOINT_TYPE
+				CLUSTER_TYPE = Cluster::TYPE_URL
+				ENDPOINT_TYPE = Endpoint::TYPE_URL
 				
+				# Initialize an empty control plane.
+				# @parameter identifier [String] The identifier reported in discovery responses.
 				def initialize(identifier: "async-grpc-xds")
 					@identifier = identifier
 					@resources = Hash.new{|hash, type_url| hash[type_url] = {}}
@@ -31,27 +36,42 @@ module Async
 				
 				attr :identifier
 				
+				# Add or replace a cluster resource.
+				# @parameter name [String] The cluster name.
+				# @parameter resource [Envoy::Config::Cluster::V3::Cluster | Nil] An existing cluster resource, or `nil` to build one from `options`.
+				# @parameter options [Hash] Options forwarded to {Cluster.build}.
 				def update_cluster(name, resource = nil, **options)
-					resource ||= ResourceBuilder.cluster(name, **options)
+					resource ||= Cluster.build(name, **options)
 					update_resource(CLUSTER_TYPE, name.to_s, resource)
 				end
 				
+				# Add or replace the endpoint assignment for a cluster.
+				# @parameter cluster_name [String] The cluster name.
+				# @parameter endpoints [Array(Hash)] The normalized endpoint states.
 				def update_endpoints(cluster_name, endpoints)
 					update_resource(
 						ENDPOINT_TYPE,
 						cluster_name.to_s,
-						ResourceBuilder.cluster_load_assignment(cluster_name, endpoints)
+						Endpoint.build(cluster_name, endpoints)
 					)
 				end
 				
+				# Remove a cluster resource.
+				# @parameter name [String] The cluster name.
 				def remove_cluster(name)
 					remove_resource(CLUSTER_TYPE, name.to_s)
 				end
 				
+				# Remove the endpoint assignment for a cluster.
+				# @parameter cluster_name [String] The cluster name.
 				def remove_endpoints(cluster_name)
 					remove_resource(ENDPOINT_TYPE, cluster_name.to_s)
 				end
 				
+				# Add or replace an xDS resource and notify subscribed streams.
+				# @parameter type_url [String] The xDS resource type URL.
+				# @parameter name [String] The resource name.
+				# @parameter resource [Google::Protobuf::MessageExts] The protobuf resource.
 				def update_resource(type_url, name, resource)
 					notify = false
 					
@@ -64,6 +84,9 @@ module Async
 					notify_streams(type_url) if notify
 				end
 				
+				# Remove an xDS resource and notify subscribed streams.
+				# @parameter type_url [String] The xDS resource type URL.
+				# @parameter name [String] The resource name.
 				def remove_resource(type_url, name)
 					notify = false
 					
@@ -77,12 +100,19 @@ module Async
 					notify_streams(type_url) if notify
 				end
 				
+				# Get the available resource names for a type.
+				# @parameter type_url [String] The xDS resource type URL.
+				# @returns [Array(String)] The resource names.
 				def resource_names(type_url)
 					@mutex.synchronize do
 						@resources[type_url].keys
 					end
 				end
 				
+				# Get resources of a given type.
+				# @parameter type_url [String] The xDS resource type URL.
+				# @parameter names [Array(String) | Nil] The requested resource names, or `nil` for all resources.
+				# @returns [Array(Google::Protobuf::MessageExts)] The matching resources.
 				def resources(type_url, names = nil)
 					@mutex.synchronize do
 						resources = @resources[type_url]
@@ -95,31 +125,42 @@ module Async
 					end
 				end
 				
+				# Get the current version for a resource type.
+				# @parameter type_url [String] The xDS resource type URL.
+				# @returns [String] The monotonically increasing version.
 				def version(type_url)
 					@mutex.synchronize do
 						@versions[type_url].to_s
 					end
 				end
 				
+				# Build a discovery response for a resource type.
+				# @parameter type_url [String] The xDS resource type URL.
+				# @parameter names [Array(String) | Nil] The requested resource names, or `nil` for all resources.
+				# @returns [Envoy::Service::Discovery::V3::DiscoveryResponse] The current discovery response.
 				def response(type_url, names = nil)
 					resources = self.resources(type_url, names)
 					version = self.version(type_url)
 					
 					Envoy::Service::Discovery::V3::DiscoveryResponse.new(
 						version_info: version,
-						resources: resources.map{|resource| ResourceBuilder.pack(resource)},
+						resources: resources.map{|resource| Google::Protobuf::Any.pack(resource)},
 						type_url: type_url,
 						nonce: "#{type_url}:#{version}:#{SecureRandom.hex(8)}",
 						control_plane: Envoy::Config::Core::V3::ControlPlane.new(identifier: @identifier)
 					)
 				end
 				
+				# Register a stream to receive resource-change notifications.
+				# @parameter stream [Service::Stream] The stream to register.
 				def register_stream(stream)
 					@mutex.synchronize do
 						@streams.add(stream)
 					end
 				end
 				
+				# Remove a registered stream.
+				# @parameter stream [Service::Stream] The stream to remove.
 				def remove_stream(stream)
 					@mutex.synchronize do
 						@streams.delete(stream)

data/lib/async/grpc/xds/discovery_client.rb

@@ -16,6 +16,9 @@ require "envoy/config/cluster/v3/cluster_pb"
 require "envoy/config/endpoint/v3/endpoint_pb"
 require "google/protobuf/any_pb"
 
+require_relative "cluster"
+require_relative "endpoint"
+
 module Async
 	module GRPC
 		module XDS
@@ -27,8 +30,8 @@ module Async
 				# xDS API type URLs (v3 API)
 				LISTENER_TYPE = "type.googleapis.com/envoy.config.listener.v3.Listener"
 				ROUTE_TYPE = "type.googleapis.com/envoy.config.route.v3.RouteConfiguration"
-				CLUSTER_TYPE = "type.googleapis.com/envoy.config.cluster.v3.Cluster"
-				ENDPOINT_TYPE = "type.googleapis.com/envoy.config.endpoint.v3.ClusterLoadAssignment"
+				CLUSTER_TYPE = Cluster::TYPE_URL
+				ENDPOINT_TYPE = Endpoint::TYPE_URL
 				SECRET_TYPE = "type.googleapis.com/envoy.extensions.transport_sockets.tls.v3.Secret"
 				
 				# Initialize xDS discovery client
@@ -152,15 +155,22 @@ module Async
 			# ADSStream::Delegate interface - must be public for ADSStream to call
 			public
 				
+				# Record that an ADS stream has opened and unblock pending subscriptions.
+				# @parameter stream [ADSStream] The opened stream.
 				def stream_opened(stream)
 					@mutex.synchronize{@ads_stream = stream}
 					@stream_ready_promise&.resolve(stream)
 				end
 				
+				# Record that an ADS stream has closed.
+				# @parameter stream [ADSStream] The closed stream.
 				def stream_closed(stream)
 					@mutex.synchronize{@ads_stream = nil}
 				end
 				
+				# Process a discovery response received by an ADS stream.
+				# @parameter response [Envoy::Service::Discovery::V3::DiscoveryResponse] The received response.
+				# @parameter stream [ADSStream] The stream that received the response.
 				def discovery_response(response, stream)
 					process_response(response, stream)
 				end

data/lib/async/grpc/xds/endpoint.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "envoy/config/core/v3/address_pb"
+require "envoy/config/endpoint/v3/endpoint_pb"
+require "envoy/config/endpoint/v3/endpoint_components_pb"
+
+module Async
+	module GRPC
+		module XDS
+			# Builds Envoy endpoint resources.
+			module Endpoint
+				extend self
+				
+				TYPE_URL = "type.googleapis.com/envoy.config.endpoint.v3.ClusterLoadAssignment"
+				
+				# Build an EDS cluster load assignment from normalized endpoint state.
+				# @parameter cluster_name [String] The cluster name.
+				# @parameter endpoints [Array(Hash)] The endpoints, each containing `:addresses` and `:healthy`.
+				# @returns [Envoy::Config::Endpoint::V3::ClusterLoadAssignment] The generated endpoint resource.
+				def build(cluster_name, endpoints)
+					Envoy::Config::Endpoint::V3::ClusterLoadAssignment.new(
+						cluster_name: cluster_name.to_s,
+						endpoints: [
+							Envoy::Config::Endpoint::V3::LocalityLbEndpoints.new(
+								lb_endpoints: endpoints.map{|endpoint| load_balancer_endpoint(endpoint)}
+							)
+						]
+					)
+				end
+				
+				private
+				
+				# Build an Envoy load-balancer endpoint from normalized endpoint state.
+				# @parameter endpoint [Hash] The endpoint containing `:addresses` and `:healthy`.
+				# @returns [Envoy::Config::Endpoint::V3::LbEndpoint] The generated load-balancer endpoint.
+				# @raises [KeyError] If required endpoint state is missing.
+				# @raises [ArgumentError] If the endpoint has no addresses.
+				# @private
+				def load_balancer_endpoint(endpoint)
+					addresses, healthy = endpoint.fetch_values(:addresses, :healthy)
+					raise ArgumentError, "An endpoint requires at least one address!" if addresses.empty?
+					
+					address, *additional_addresses = addresses
+					
+					Envoy::Config::Endpoint::V3::LbEndpoint.new(
+						endpoint: Envoy::Config::Endpoint::V3::Endpoint.new(
+							address: build_address(address),
+							hostname: endpoint[:hostname],
+							additional_addresses: additional_addresses.map do |additional_address|
+								Envoy::Config::Endpoint::V3::Endpoint::AdditionalAddress.new(
+									address: build_address(additional_address)
+								)
+							end
+						),
+						health_status: health_status_value(healthy)
+					)
+				end
+				
+				# Build an Envoy address from a normalized IP or Unix address.
+				# @parameter address [Hash] An IP `:address` and `:port`, or a Unix `:path`.
+				# @returns [Envoy::Config::Core::V3::Address] The generated Envoy address.
+				# @raises [KeyError] If required IP address state is missing.
+				# @private
+				def build_address(address)
+					if path = address[:path]
+						Envoy::Config::Core::V3::Address.new(
+							pipe: Envoy::Config::Core::V3::Pipe.new(path: path)
+						)
+					else
+						Envoy::Config::Core::V3::Address.new(
+							socket_address: Envoy::Config::Core::V3::SocketAddress.new(
+								protocol: Envoy::Config::Core::V3::SocketAddress::Protocol::TCP,
+								address: address.fetch(:address),
+								port_value: address.fetch(:port)
+							)
+						)
+					end
+				end
+				
+				# Convert an endpoint health status to its Envoy enum value.
+				# @parameter healthy [Boolean | Symbol | String] The normalized health status.
+				# @returns [Integer] The Envoy health-status enum value.
+				# @private
+				def health_status_value(healthy)
+					case healthy
+					when :healthy, :HEALTHY, "healthy", "HEALTHY", true
+						Envoy::Config::Core::V3::HealthStatus::HEALTHY
+					when :unhealthy, :UNHEALTHY, "unhealthy", "UNHEALTHY", false
+						Envoy::Config::Core::V3::HealthStatus::UNHEALTHY
+					when :degraded, :DEGRADED, "degraded", "DEGRADED"
+						Envoy::Config::Core::V3::HealthStatus::DEGRADED
+					else
+						Envoy::Config::Core::V3::HealthStatus::UNKNOWN
+					end
+				end
+			end
+		end
+	end
+end

data/lib/async/grpc/xds/resource_cache.rb

@@ -9,6 +9,7 @@ module Async
 			# Caches discovered xDS resources
 			# Thread-safe cache for clusters and endpoints
 			class ResourceCache
+				# Initialize an empty resource cache.
 				def initialize
 					@clusters = {}
 					@endpoints = {}

data/lib/async/grpc/xds/resources.rb

@@ -6,6 +6,7 @@
 module Async
 	module GRPC
 		module XDS
+			# @namespace
 			module Resources
 				# Represents a discovered cluster
 				# Based on envoy.config.cluster.v3.Cluster
@@ -40,6 +41,8 @@ module Async
 						new(proto)
 					end
 					
+					# Determine whether this cluster uses the Endpoint Discovery Service.
+					# @returns [Boolean] `true` if the cluster uses EDS.
 					def eds_cluster?
 						@type == :EDS
 					end
@@ -216,6 +219,8 @@ module Async
 				class Endpoint
 					attr_reader :address, :port, :health_status, :metadata
 					
+					# Initialize an endpoint from a protobuf message or hash.
+					# @parameter load_balancer_endpoint [Envoy::Config::Endpoint::V3::LbEndpoint | Hash] The load-balancer endpoint representation.
 					def initialize(load_balancer_endpoint)
 						if load_balancer_endpoint.is_a?(Hash)
 							endpoint_data = load_balancer_endpoint[:endpoint] || {}
@@ -235,10 +240,14 @@ module Async
 						end
 					end
 					
+					# Determine whether this endpoint is eligible to receive traffic.
+					# @returns [Boolean] `true` if the endpoint is healthy or has unknown health.
 					def healthy?
 						@health_status == :HEALTHY || @health_status == :UNKNOWN
 					end
 					
+					# Build the HTTP URI for this endpoint.
+					# @returns [String] The endpoint URI.
 					def uri
 						# Use http for insecure/docker environments (gRPC h2c)
 						scheme = ENV["XDS_ENDPOINT_SCHEME"] || "http"

data/lib/async/grpc/xds/server.rb

@@ -14,6 +14,9 @@ module Async
 		module XDS
 			# Convenience wrapper for serving an xDS control plane over gRPC.
 			class Server
+				# Initialize an xDS server.
+				# @parameter control_plane [ControlPlane] The control plane to serve.
+				# @parameter options [Hash] Default options forwarded to `Async::HTTP::Server`.
 				def initialize(control_plane = ControlPlane.new, **options)
 					@control_plane = control_plane
 					@dispatcher = Async::GRPC::Dispatcher.new
@@ -24,6 +27,10 @@ module Async
 				attr :control_plane
 				attr :dispatcher
 				
+				# Run the xDS server on an endpoint.
+				# @parameter endpoint [Async::HTTP::Endpoint] The endpoint to bind.
+				# @parameter options [Hash] Options forwarded to `Async::HTTP::Server`.
+				# @asynchronous
 				def run(endpoint, **options)
 					server = Async::HTTP::Server.new(@dispatcher, endpoint, **@options, **options)
 					server.run

data/lib/async/grpc/xds/service.rb

@@ -21,11 +21,18 @@ module Async
 			class Service < Async::GRPC::Service
 				SERVICE_NAME = "envoy.service.discovery.v3.AggregatedDiscoveryService"
 				
+				# Initialize an Aggregated Discovery Service.
+				# @parameter control_plane [ControlPlane] The control plane that provides resources.
 				def initialize(control_plane)
 					super(Envoy::Service::Discovery::V3::AggregatedDiscoveryService, SERVICE_NAME)
 					@control_plane = control_plane
 				end
 				
+				# Serve a state-of-the-world Aggregated Discovery Service stream.
+				# @parameter input [Enumerable] The stream of discovery requests.
+				# @parameter output [Interface(:write)] The discovery response stream.
+				# @parameter call [Object] The gRPC call context.
+				# @asynchronous
 				def stream_aggregated_resources(input, output, call)
 					stream = Stream.new(@control_plane, output)
 					@control_plane.register_stream(stream)
@@ -48,6 +55,11 @@ module Async
 					@control_plane.remove_stream(stream) if stream
 				end
 				
+				# Reject a delta Aggregated Discovery Service stream, which is not supported.
+				# @parameter input [Enumerable] The stream of delta discovery requests.
+				# @parameter output [Interface(:write)] The delta discovery response stream.
+				# @parameter call [Object] The gRPC call context.
+				# @raises [Protocol::GRPC::Error] Always raised because delta xDS is not implemented.
 				def delta_aggregated_resources(input, output, call)
 					raise Protocol::GRPC::Error.new(
 						Protocol::GRPC::Status::UNIMPLEMENTED,
@@ -57,6 +69,9 @@ module Async
 				
 				# Represents one ADS stream and its subscribed resources.
 				class Stream
+					# Initialize an ADS stream.
+					# @parameter control_plane [ControlPlane] The control plane that provides resources.
+					# @parameter output [Interface(:write)] The discovery response stream.
 					def initialize(control_plane, output)
 						@control_plane = control_plane
 						@output = output
@@ -66,6 +81,8 @@ module Async
 						@closed = false
 					end
 					
+					# Process a discovery request and update the stream's subscriptions.
+					# @parameter request [Envoy::Service::Discovery::V3::DiscoveryRequest] The discovery request.
 					def request(request)
 						return if request.type_url.nil? || request.type_url.empty?
 						
@@ -83,10 +100,14 @@ module Async
 						@queue << request.type_url
 					end
 					
+					# Schedule a resource type for delivery after it changes.
+					# @parameter type_url [String] The changed xDS resource type URL.
 					def changed(type_url)
 						@queue << type_url unless @closed
 					end
 					
+					# Deliver scheduled resource updates until the stream closes.
+					# @asynchronous
 					def run
 						until @closed
 							type_url = @queue.dequeue
@@ -94,6 +115,8 @@ module Async
 						end
 					end
 					
+					# Deliver the latest resource version for a subscribed type.
+					# @parameter type_url [String] The xDS resource type URL.
 					def flush(type_url)
 						names = @subscriptions[type_url]
 						return unless names
@@ -106,6 +129,7 @@ module Async
 						@versions[type_url] = version
 					end
 					
+					# Close the stream and stop waiting for changes.
 					def close
 						@closed = true
 						@queue.close

data/lib/async/grpc/xds/version.rb

@@ -3,10 +3,13 @@
 # Released under the MIT License.
 # Copyright, 2026, by Samuel Williams.
 
+# @namespace
 module Async
+	# @namespace
 	module GRPC
+		# @namespace
 		module XDS
-			VERSION = "0.0.1"
+			VERSION = "0.2.0"
 		end
 	end
 end

data/lib/async/grpc/xds.rb

@@ -13,7 +13,9 @@ require_relative "xds/health_checker"
 require_relative "xds/load_balancer"
 require_relative "xds/context"
 require_relative "xds/client"
-require_relative "xds/resource_builder"
+require_relative "xds/cluster"
+require_relative "xds/endpoint"
+require_relative "xds/client_side_weighted_round_robin"
 require_relative "xds/control_plane"
 require_relative "xds/service"
 require_relative "xds/server"

data/lib/envoy/config/common/mutation_rules/v3/mutation_rules_pb.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# source: envoy/config/common/mutation_rules/v3/mutation_rules.proto
+
+require "google/protobuf"
+
+require "envoy/config/core/v3/base_pb"
+require "envoy/type/matcher/v3/regex_pb"
+require "envoy/type/matcher/v3/string_pb"
+require "google/protobuf/wrappers_pb"
+require "udpa/annotations/status_pb"
+require "validate/validate_pb"
+
+
+descriptor_data = "\n:envoy/config/common/mutation_rules/v3/mutation_rules.proto\x12%envoy.config.common.mutation_rules.v3\x1a\x1f\x65nvoy/config/core/v3/base.proto\x1a!envoy/type/matcher/v3/regex.proto\x1a\"envoy/type/matcher/v3/string.proto\x1a\x1egoogle/protobuf/wrappers.proto\x1a\x1dudpa/annotations/status.proto\x1a\x17validate/validate.proto\"\x9c\x03\n\x13HeaderMutationRules\x12\x35\n\x11\x61llow_all_routing\x18\x01 \x01(\x0b\x32\x1a.google.protobuf.BoolValue\x12/\n\x0b\x61llow_envoy\x18\x02 \x01(\x0b\x32\x1a.google.protobuf.BoolValue\x12\x33\n\x0f\x64isallow_system\x18\x03 \x01(\x0b\x32\x1a.google.protobuf.BoolValue\x12\x30\n\x0c\x64isallow_all\x18\x04 \x01(\x0b\x32\x1a.google.protobuf.BoolValue\x12=\n\x10\x61llow_expression\x18\x05 \x01(\x0b\x32#.envoy.type.matcher.v3.RegexMatcher\x12@\n\x13\x64isallow_expression\x18\x06 \x01(\x0b\x32#.envoy.type.matcher.v3.RegexMatcher\x12\x35\n\x11\x64isallow_is_error\x18\x07 \x01(\x0b\x32\x1a.google.protobuf.BoolValue\"\xaf\x02\n\x0eHeaderMutation\x12\x1d\n\x06remove\x18\x01 \x01(\tB\x0b\xfa\x42\x08r\x06\xc0\x01\x02\xc8\x01\x00H\x00\x12\x39\n\x06\x61ppend\x18\x02 \x01(\x0b\x32\'.envoy.config.core.v3.HeaderValueOptionH\x00\x12^\n\x0fremove_on_match\x18\x03 \x01(\x0b\x32\x43.envoy.config.common.mutation_rules.v3.HeaderMutation.RemoveOnMatchH\x00\x1aT\n\rRemoveOnMatch\x12\x43\n\x0bkey_matcher\x18\x01 \x01(\x0b\x32$.envoy.type.matcher.v3.StringMatcherB\x08\xfa\x42\x05\x8a\x01\x02\x10\x01\x42\r\n\x06\x61\x63tion\x12\x03\xf8\x42\x01\x42\xb2\x01\n3io.envoyproxy.envoy.config.common.mutation_rules.v3B\x12MutationRulesProtoP\x01Z]github.com/envoyproxy/go-control-plane/envoy/config/common/mutation_rules/v3;mutation_rulesv3\xba\x80\xc8\xd1\x06\x02\x10\x02\x62\x06proto3"
+
+pool = ::Google::Protobuf::DescriptorPool.generated_pool
+pool.add_serialized_file(descriptor_data)
+
+module Envoy
+	module Config
+		module Common
+			module MutationRules
+				module V3
+					HeaderMutationRules = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("envoy.config.common.mutation_rules.v3.HeaderMutationRules").msgclass
+					HeaderMutation = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("envoy.config.common.mutation_rules.v3.HeaderMutation").msgclass
+					HeaderMutation::RemoveOnMatch = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("envoy.config.common.mutation_rules.v3.HeaderMutation.RemoveOnMatch").msgclass
+				end
+			end
+		end
+	end
+end