async-grpc-xds 0.2.0 → 0.4.0

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

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "google/protobuf/duration_pb"
+require "google/protobuf/wrappers_pb"
+
+require "envoy/config/core/v3/health_check_pb"
+
+module Async
+	module GRPC
+		module XDS
+			# Builds Envoy HTTP active health checks.
+			module HTTPHealthCheck
+				extend self
+				
+				# Build an HTTP active health check.
+				# @parameter path [String] The request path used to check each endpoint.
+				# @parameter interval [Numeric] The interval between checks in seconds.
+				# @parameter timeout [Numeric] The check timeout in seconds.
+				# @parameter unhealthy_threshold [Integer] The consecutive failures required to mark an endpoint unhealthy.
+				# @parameter healthy_threshold [Integer] The consecutive successes required to mark an endpoint healthy.
+				# @returns [Envoy::Config::Core::V3::HealthCheck] The generated health check.
+				def build(path, interval: 1, timeout: 1, unhealthy_threshold: 2, healthy_threshold: 1)
+					Envoy::Config::Core::V3::HealthCheck.new(
+						timeout: duration(timeout),
+						interval: duration(interval),
+						unhealthy_threshold: Google::Protobuf::UInt32Value.new(value: Integer(unhealthy_threshold)),
+						healthy_threshold: Google::Protobuf::UInt32Value.new(value: Integer(healthy_threshold)),
+						http_health_check: Envoy::Config::Core::V3::HealthCheck::HttpHealthCheck.new(path: path.to_s)
+					)
+				end
+				
+				private
+				
+				def duration(value)
+					seconds = value.to_i
+					
+					Google::Protobuf::Duration.new(
+						seconds: seconds,
+						nanos: ((value.to_f - seconds) * 1_000_000_000).to_i
+					)
+				end
+			end
+		end
+	end
+end

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

@@ -16,16 +16,22 @@ module Async
 			class Server
 				# Initialize an xDS server.
 				# @parameter control_plane [ControlPlane] The control plane to serve.
+				# @parameter services [Array(Class)] The discovery service classes to register.
 				# @parameter options [Hash] Default options forwarded to `Async::HTTP::Server`.
-				def initialize(control_plane = ControlPlane.new, **options)
+				def initialize(control_plane = ControlPlane.new, services: [Service], **options)
 					@control_plane = control_plane
 					@dispatcher = Async::GRPC::Dispatcher.new
-					@dispatcher.register(Service.new(@control_plane))
+					@services = services.map do |service|
+						service.new(@control_plane).tap do |instance|
+							@dispatcher.register(instance)
+						end
+					end
 					@options = options
 				end
 				
 				attr :control_plane
 				attr :dispatcher
+				attr :services
 				
 				# Run the xDS server on an endpoint.
 				# @parameter endpoint [Async::HTTP::Endpoint] The endpoint to bind.

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

@@ -3,29 +3,21 @@
 # Released under the MIT License.
 # Copyright, 2026, by Samuel Williams.
 
-require "async"
-require "async/queue"
-require "async/grpc/service"
-require "protocol/grpc/error"
-require "protocol/grpc/status"
-require "set"
-
 require "envoy/service/discovery/v3/aggregated_discovery_service"
 
-require_relative "control_plane"
+require_relative "discovery_service"
 
 module Async
 	module GRPC
 		module XDS
 			# Serves Envoy Aggregated Discovery Service requests from a {ControlPlane}.
-			class Service < Async::GRPC::Service
+			class Service < DiscoveryService
 				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
+					super(Envoy::Service::Discovery::V3::AggregatedDiscoveryService, SERVICE_NAME, control_plane)
 				end
 				
 				# Serve a state-of-the-world Aggregated Discovery Service stream.
@@ -34,25 +26,7 @@ module Async
 				# @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)
-					
-					reader = Async do
-						input.each do |request|
-							stream.request(request)
-						end
-					end
-					
-					writer = Async do
-						stream.run
-					end
-					
-					reader.wait
-				ensure
-					stream&.close
-					reader&.stop
-					writer&.stop
-					@control_plane.remove_stream(stream) if stream
+					stream_resources(input, output)
 				end
 				
 				# Reject a delta Aggregated Discovery Service stream, which is not supported.
@@ -61,79 +35,7 @@ module Async
 				# @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,
-						"Delta xDS is not implemented."
-					)
-				end
-				
-				# 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
-						@subscriptions = Hash.new{|hash, type_url| hash[type_url] = Set.new}
-						@versions = {}
-						@queue = Async::Queue.new
-						@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?
-						
-						if request.error_detail
-							Console.warn(self, "Received xDS NACK.", type_url: request.type_url, error_detail: request.error_detail)
-							return
-						end
-						
-						if request.resource_names.any?
-							@subscriptions[request.type_url].merge(request.resource_names)
-						else
-							@subscriptions[request.type_url]
-						end
-						
-						@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
-							flush(type_url)
-						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
-						
-						version = @control_plane.version(type_url)
-						return if @versions[type_url] == version
-						
-						response = @control_plane.response(type_url, names)
-						@output.write(response)
-						@versions[type_url] = version
-					end
-					
-					# Close the stream and stop waiting for changes.
-					def close
-						@closed = true
-						@queue.close
-					end
+					delta_resources
 				end
 			end
 		end

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

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "async/queue"
+require "protocol/grpc/error"
+require "protocol/grpc/status"
+require "set"
+
+module Async
+	module GRPC
+		module XDS
+			# Represents one discovery stream and its subscribed resources.
+			class Stream
+				# Initialize a discovery stream.
+				# @parameter control_plane [ControlPlane] The control plane that provides resources.
+				# @parameter output [Interface(:write)] The discovery response stream.
+				# @parameter resource_type [String | Nil] The fixed resource type, or `nil` for aggregated discovery.
+				def initialize(control_plane, output, resource_type: nil)
+					@control_plane = control_plane
+					@output = output
+					@resource_type = resource_type
+					@subscriptions = {}
+					@versions = {}
+					@queue = Async::Queue.new
+					@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)
+					type_url = request.type_url
+					
+					if @resource_type
+						if type_url.nil? || type_url.empty?
+							type_url = @resource_type
+						elsif type_url != @resource_type
+							raise Protocol::GRPC::Error.new(
+								Protocol::GRPC::Status::INVALID_ARGUMENT,
+								"Expected resource type #{@resource_type.inspect}, but received #{type_url.inspect}."
+							)
+						end
+					elsif type_url.nil? || type_url.empty?
+						return
+					end
+					
+					if request.error_detail
+						Console.warn(self, "Received xDS NACK.", type_url: type_url, error_detail: request.error_detail)
+						return
+					end
+					
+					names = Set.new(request.resource_names)
+					if @subscriptions[type_url] != names
+						@subscriptions[type_url] = names
+						@versions.delete(type_url)
+					end
+					
+					@queue << 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)
+					return if @resource_type && type_url != @resource_type
+					return unless @subscriptions.key?(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
+						flush(type_url)
+					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
+					
+					version = @control_plane.version(type_url)
+					return if @versions[type_url] == version
+					
+					response = @control_plane.response(type_url, names)
+					@output.write(response)
+					@versions[type_url] = version
+				end
+				
+				# Close the stream and stop waiting for changes.
+				def close
+					@closed = true
+					@queue.close
+				end
+			end
+		end
+	end
+end

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

@@ -9,7 +9,7 @@ module Async
 	module GRPC
 		# @namespace
 		module XDS
-			VERSION = "0.2.0"
+			VERSION = "0.4.0"
 		end
 	end
 end

data/lib/async/grpc/xds.rb

@@ -13,11 +13,17 @@ require_relative "xds/health_checker"
 require_relative "xds/load_balancer"
 require_relative "xds/context"
 require_relative "xds/client"
+require_relative "xds/config_source"
 require_relative "xds/cluster"
 require_relative "xds/endpoint"
+require_relative "xds/http_health_check"
 require_relative "xds/client_side_weighted_round_robin"
 require_relative "xds/control_plane"
+require_relative "xds/stream"
+require_relative "xds/discovery_service"
 require_relative "xds/service"
+require_relative "xds/cluster_discovery_service"
+require_relative "xds/endpoint_discovery_service"
 require_relative "xds/server"
 
 module Async

data/proto/readme.md

@@ -25,45 +25,29 @@ These files come from [envoyproxy/data-plane-api](https://github.com/envoyproxy/
 To update these files, run:
 
 ```bash
-./xds/update_protos.sh
+bundle exec bake update_protos
 ```
 
-Or manually:
-
-```bash
-# Clone envoy data-plane-api
-git clone --depth 1 https://github.com/envoyproxy/data-plane-api.git /tmp/envoy-api
-
-# Copy needed files
-cp -r /tmp/envoy-api/envoy proto/
-cp -r /tmp/envoy-api/google proto/
-
-# Cleanup
-rm -rf /tmp/envoy-api
-```
+This fetches the pinned upstream revisions defined in `bake.rb`, updates the vendored definitions, and regenerates the checked-in Ruby classes.
 
 ## Generating Ruby Code
 
 After updating proto files, generate Ruby classes:
 
 ```bash
-bundle exec bake async:grpc:xds:generate_protos
+bundle exec bake generate_protos
 ```
 
 ## Version
 
-These files are from the latest `main` branch of:
+The source repositories and revisions are defined by `PROTOBUF_SOURCES` in `bake.rb`. They include:
+
 - `envoyproxy/data-plane-api` - Envoy API definitions
 - `protocolbuffers/protobuf` - Google protobuf well-known types
 - `googleapis/api-common-protos` - Google RPC status
-
-To lock to a specific version, modify `xds/update_protos.sh` to check out specific tags:
-
-```bash
-cd /tmp/envoy-api
-git checkout v1.30.0  # Use specific Envoy version
-# Then copy files
-```
+- `cncf/xds` - xDS API definitions
+- `cncf/udpa` - UDPA annotations
+- `envoyproxy/protoc-gen-validate` - Validation annotations
 
 ## Note on Dependencies
 

data/readme.md

@@ -2,7 +2,7 @@
 
 xDS support for `async-grpc` clients.
 
-This gem contains the experimental xDS implementation extracted from `async-grpc`, including Envoy xDS protobuf definitions, ADS discovery, CDS/EDS resource handling, and client-side load balancing.
+This gem contains the experimental xDS implementation extracted from `async-grpc`, including Envoy xDS protobuf definitions, aggregated and resource-specific discovery, CDS/EDS resource handling, and client-side load balancing.
 
 [![Development Status](https://github.com/socketry/async-grpc-xds/workflows/Test/badge.svg)](https://github.com/socketry/async-grpc-xds/actions?workflow=Test)
 
@@ -10,22 +10,29 @@ This gem contains the experimental xDS implementation extracted from `async-grpc
 
 Please see the [project documentation](https://socketry.github.io/async-grpc-xds/) for more details.
 
-## Status
-
-This is an early implementation focused on ADS with CDS and EDS. LDS/RDS, full routing semantics, NACK handling, locality weighting, and delta xDS are not complete yet.
+  - [Getting Started](https://socketry.github.io/async-grpc-xds/guides/getting-started/index) - This guide explains how to use `async-grpc-xds` to publish CDS and EDS resources to Envoy, or to discover gRPC backends from Ruby using xDS.
 
 ## Testing
 
-The `xds/` directory contains a Docker Compose integration environment with a Go xDS control plane and Ruby gRPC backends.
+The `integration/` directory contains Docker Compose environments for testing the Ruby xDS client against a Go control plane and the Ruby control plane against Envoy.
 
 ``` bash
-docker compose -f xds/docker-compose.yaml up --build --exit-code-from tests
+bundle exec bake test:integration
 ```
 
 ## Releases
 
 Please see the [project releases](https://socketry.github.io/async-grpc-xds/releases/index) for all releases.
 
+### v0.4.0
+
+  - Add dedicated Cluster Discovery Service and Endpoint Discovery Service implementations, allowing resource-specific xDS streams without claiming ADS.
+  - Allow generated clusters to use a dedicated EDS configuration source instead of ADS.
+
+### v0.3.0
+
+  - Add Envoy HTTP active health-check resources and attach health checks to generated clusters.
+
 ### v0.2.0
 
   - Add ORCA load reporting messages, service interface, and client-side weighted-round-robin resources.

data/releases.md

@@ -1,5 +1,14 @@
 # Releases
 
+## v0.4.0
+
+  - Add dedicated Cluster Discovery Service and Endpoint Discovery Service implementations, allowing resource-specific xDS streams without claiming ADS.
+  - Allow generated clusters to use a dedicated EDS configuration source instead of ADS.
+
+## v0.3.0
+
+  - Add Envoy HTTP active health-check resources and attach health checks to generated clusters.
+
 ## v0.2.0
 
   - Add ORCA load reporting messages, service interface, and client-side weighted-round-robin resources.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: async-grpc-xds
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -126,23 +126,29 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- fixtures/async/grpc/test_interface.rb
-- fixtures/async/grpc/test_message.rb
+- context/getting-started.md
+- context/index.yaml
 - lib/async/grpc/xds.rb
 - lib/async/grpc/xds/ads_stream.rb
 - lib/async/grpc/xds/client.rb
 - lib/async/grpc/xds/client_side_weighted_round_robin.rb
 - lib/async/grpc/xds/cluster.rb
+- lib/async/grpc/xds/cluster_discovery_service.rb
+- lib/async/grpc/xds/config_source.rb
 - lib/async/grpc/xds/context.rb
 - lib/async/grpc/xds/control_plane.rb
 - lib/async/grpc/xds/discovery_client.rb
+- lib/async/grpc/xds/discovery_service.rb
 - lib/async/grpc/xds/endpoint.rb
+- lib/async/grpc/xds/endpoint_discovery_service.rb
 - lib/async/grpc/xds/health_checker.rb
+- lib/async/grpc/xds/http_health_check.rb
 - lib/async/grpc/xds/load_balancer.rb
 - lib/async/grpc/xds/resource_cache.rb
 - lib/async/grpc/xds/resources.rb
 - lib/async/grpc/xds/server.rb
 - lib/async/grpc/xds/service.rb
+- lib/async/grpc/xds/stream.rb
 - lib/async/grpc/xds/version.rb
 - lib/envoy.rb
 - lib/envoy/annotations/deprecation_pb.rb
@@ -365,21 +371,12 @@ files:
 - proto/xds/type/v3/typed_struct.proto
 - readme.md
 - releases.md
-- xds/Dockerfile.backend
-- xds/Dockerfile.control-plane
-- xds/backend_server.rb
-- xds/docker-compose.yaml
-- xds/go.mod
-- xds/go.sum
-- xds/readme.md
-- xds/test/async/grpc/xds/client.rb
-- xds/test/async/grpc/xds/control_plane.rb
-- xds/test_server.go
-- xds/update_protos.sh
 homepage: https://github.com/socketry/async-grpc-xds
 licenses:
 - MIT
 metadata:
+  bug_tracker_uri: https://github.com/socketry/async-grpc-xds/issues
+  changelog_uri: https://github.com/socketry/async-grpc-xds/blob/main/releases.md
   documentation_uri: https://socketry.github.io/async-grpc-xds/
   source_code_uri: https://github.com/socketry/async-grpc-xds.git
 rdoc_options: []

data/fixtures/async/grpc/test_interface.rb

@@ -1,79 +0,0 @@
-# frozen_string_literal: true
-
-# Released under the MIT License.
-# Copyright, 2026, by Samuel Williams.
-
-require "protocol/grpc/interface"
-require_relative "test_message"
-
-module Async
-	module GRPC
-		module Fixtures
-			# Test interface for unit tests
-			# RPC names use PascalCase to match .proto files
-			class TestInterface < Protocol::GRPC::Interface
-				rpc :UnaryCall, request_class: Protocol::GRPC::Fixtures::TestMessage,
-					response_class: Protocol::GRPC::Fixtures::TestMessage, streaming: :unary
-				rpc :ServerStreamingCall, request_class: Protocol::GRPC::Fixtures::TestMessage,
-					response_class: Protocol::GRPC::Fixtures::TestMessage, streaming: :server_streaming
-				rpc :SayHello, request_class: Protocol::GRPC::Fixtures::TestMessage,
-					response_class: Protocol::GRPC::Fixtures::TestMessage, streaming: :unary
-				rpc :BidirectionalCall, request_class: Protocol::GRPC::Fixtures::TestMessage,
-					response_class: Protocol::GRPC::Fixtures::TestMessage, streaming: :bidirectional
-				rpc :ClientStreamingCall, request_class: Protocol::GRPC::Fixtures::TestMessage,
-					response_class: Protocol::GRPC::Fixtures::TestMessage, streaming: :client_streaming
-				rpc :SlowCall
-			end
-			
-			# Test service implementation
-			# Method names use snake_case (Ruby convention)
-			class TestService < Async::GRPC::Service
-				def unary_call(input, output, _call)
-					request = input.read
-					response = Protocol::GRPC::Fixtures::TestMessage.new(value: "Response: #{request.value}")
-					output.write(response)
-				end
-				
-				def server_streaming_call(input, output, _call)
-					request = input.read
-					3.times do |i|
-						response = Protocol::GRPC::Fixtures::TestMessage.new(value: "Response #{i}: #{request.value}")
-						output.write(response)
-					end
-				end
-				
-				def say_hello(input, output, _call)
-					request = input.read
-					response = Protocol::GRPC::Fixtures::TestMessage.new(value: "Hello, #{request.value}!")
-					output.write(response)
-				end
-				
-				def bidirectional_call(input, output, _call)
-					# Read all input messages and echo them back with a prefix
-					input.each do |request|
-						response = Protocol::GRPC::Fixtures::TestMessage.new(value: "Echo: #{request.value}")
-						output.write(response)
-					end
-					output.close_write
-				end
-				
-				def client_streaming_call(input, output, _call)
-					# Read all input messages and return a summary
-					values = []
-					input.each do |request|
-						values << request.value
-					end
-					response = Protocol::GRPC::Fixtures::TestMessage.new(value: "Received: #{values.join(', ')}")
-					output.write(response)
-				end
-				
-				def slow_call(input, output, _call)
-					request = input.read
-					sleep 1 # Simulate a slow operation
-					response = Protocol::GRPC::Fixtures::TestMessage.new(value: "Slow response: #{request.value}")
-					output.write(response)
-				end
-			end
-		end
-	end
-end

data/fixtures/async/grpc/test_message.rb

@@ -1,56 +0,0 @@
-# frozen_string_literal: true
-
-# Released under the MIT License.
-# Copyright, 2026, by Samuel Williams.
-
-module Protocol
-	module GRPC
-		module Fixtures
-			# Simple test message for unit tests.
-			# Provides a basic protobuf-like message structure.
-			class TestMessage
-				# @attribute [String | Nil] The message value.
-				attr_accessor :value
-				
-				# Initialize a new test message.
-				# @parameter value [String | Nil] The message value
-				def initialize(value: nil)
-					@value = value
-				end
-				
-				# Serialize the message to a binary string.
-				# @returns [String] Binary representation of the message
-				def to_proto
-					# Simple serialization: length-prefixed value
-					value_data = (@value || "").dup.force_encoding(Encoding::BINARY)
-					[value_data.bytesize].pack("N") + value_data
-				end
-				
-				alias encode to_proto
-				
-				# Deserialize a binary string into a message.
-				# @parameter data [String] Binary representation of the message
-				# @returns [TestMessage] Deserialized message instance
-				def self.decode(data)
-					# Simple binary format: first 4 bytes are length, rest is value
-					length = data[0...4].unpack1("N")
-					value = data[4...(4 + length)].dup.force_encoding(Encoding::UTF_8)
-					new(value: value)
-				end
-				
-				# Check equality with another message.
-				# @parameter other [Object] The object to compare
-				# @returns [Boolean] `true` if values are equal
-				def ==(other)
-					other.is_a?(TestMessage) && @value == other.value
-				end
-				
-				# Get a string representation of the message.
-				# @returns [String] String representation
-				def inspect
-					"#<#{self.class.name} value=#{@value.inspect}>"
-				end
-			end
-		end
-	end
-end