async-grpc-xds 0.0.1

data/xds/backend_server.rb

@@ -0,0 +1,68 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "async"
+require "async/http/server"
+require "async/http/endpoint"
+require "async/grpc/dispatcher"
+require "async/grpc/service"
+require_relative "../fixtures/async/grpc/test_interface"
+
+class TestBackendService < Async::GRPC::Service
+	def initialize(interface_class, service_name, backend_id)
+		super(interface_class, service_name)
+		@backend_id = backend_id
+	end
+	
+	def unary_call(input, output, call)
+		request = input.read
+		
+		# Include backend ID in response metadata (trailers)
+		call.response.headers["backend-id"] = @backend_id
+		
+		response = Protocol::GRPC::Fixtures::TestMessage.new(
+			value: "Response from #{@backend_id}: #{request&.value || 'no value'}"
+		)
+		
+		output.write(response)
+	end
+	
+	def say_hello(input, output, call)
+		request = input.read
+		
+		call.response.headers["backend-id"] = @backend_id
+		
+		response = Protocol::GRPC::Fixtures::TestMessage.new(
+			value: "Hello from #{@backend_id}, #{request.value}!"
+		)
+		
+		output.write(response)
+	end
+end
+
+port = ENV["PORT"] || "50051"
+backend_id = ENV["BACKEND_ID"] || "backend-unknown"
+service_name = ENV["SERVICE_NAME"] || "test.Service"
+
+Async do
+	# Create gRPC dispatcher
+	dispatcher = Async::GRPC::Dispatcher.new
+	service = TestBackendService.new(Async::GRPC::Fixtures::TestInterface, service_name, backend_id)
+	dispatcher.register(service)
+	
+	# Create endpoint (http for h2c - gRPC without TLS in docker)
+	endpoint = Async::HTTP::Endpoint.parse(
+		"http://0.0.0.0:#{port}",
+		protocol: Async::HTTP::Protocol::HTTP2
+	)
+	
+	# Start server
+	server = Async::HTTP::Server.new(dispatcher, endpoint)
+	
+	Console.info{"Starting backend server #{backend_id} on port #{port}"}
+	
+	server.run
+end

data/xds/docker-compose.yaml

@@ -0,0 +1,89 @@
+services:
+  # xDS control plane (using custom test server built with go-control-plane)
+  # This provides a simple xDS server for testing
+  xds-control-plane:
+    build:
+      context: .
+      dockerfile: Dockerfile.control-plane
+    ports:
+      - "18000:18000"
+      - "18001:18001"
+    environment:
+      - UPSTREAM=backend-1:50051,backend-2:50052,backend-3:50053
+    healthcheck:
+      test: ["CMD", "nc", "-z", "localhost", "18000"]
+      interval: 1s
+      timeout: 3s
+      retries: 30
+
+  # Backend gRPC server 1
+  backend-1:
+    build:
+      context: ..
+      dockerfile: xds/Dockerfile.backend
+    command: bundle exec ruby xds/backend_server.rb
+    environment:
+      - BUNDLE_WITHOUT=maintenance
+      - PORT=50051
+      - SERVICE_NAME=myservice
+      - BACKEND_ID=backend-1
+    ports:
+      - "50051:50051"
+    depends_on:
+      xds-control-plane:
+        condition: service_healthy
+
+  # Backend gRPC server 2
+  backend-2:
+    build:
+      context: ..
+      dockerfile: xds/Dockerfile.backend
+    command: bundle exec ruby xds/backend_server.rb
+    environment:
+      - BUNDLE_WITHOUT=maintenance
+      - PORT=50052
+      - SERVICE_NAME=myservice
+      - BACKEND_ID=backend-2
+    ports:
+      - "50052:50052"
+    depends_on:
+      xds-control-plane:
+        condition: service_healthy
+
+  # Backend gRPC server 3
+  backend-3:
+    build:
+      context: ..
+      dockerfile: xds/Dockerfile.backend
+    command: bundle exec ruby xds/backend_server.rb
+    environment:
+      - BUNDLE_WITHOUT=maintenance
+      - PORT=50053
+      - SERVICE_NAME=myservice
+      - BACKEND_ID=backend-3
+    ports:
+      - "50053:50053"
+    depends_on:
+      xds-control-plane:
+        condition: service_healthy
+
+  # Test runner
+  tests:
+    image: ruby:${RUBY_VERSION:-latest}
+    volumes:
+      - ../:/code
+    working_dir: /code
+    command: bash -c "bundle install && bundle exec sus xds/test"
+    environment:
+      - BUNDLE_GEMFILE=/code/gems.rb
+      - BUNDLE_WITHOUT=maintenance
+      - CONSOLE_OUTPUT=XTerm
+      - COVERAGE=${COVERAGE}
+      - XDS_ADMIN_URI=http://xds-control-plane:18001
+      - XDS_SERVER_URI=xds-control-plane:18000
+      - XDS_ENDPOINT_SCHEME=http
+    depends_on:
+      - xds-control-plane
+      - backend-1
+      - backend-2
+      - backend-3

data/xds/go.mod

@@ -0,0 +1,22 @@
+module xds-test-server
+
+go 1.21
+
+require (
+	github.com/envoyproxy/go-control-plane v0.12.0
+	google.golang.org/grpc v1.60.0
+)
+
+require (
+	github.com/census-instrumentation/opencensus-proto v0.4.1 // indirect
+	github.com/cncf/xds/go v0.0.0-20230607035331-e9ce68804cb4 // indirect
+	github.com/envoyproxy/protoc-gen-validate v1.0.2 // indirect
+	github.com/golang/protobuf v1.5.3 // indirect
+	golang.org/x/net v0.17.0 // indirect
+	golang.org/x/sys v0.13.0 // indirect
+	golang.org/x/text v0.13.0 // indirect
+	google.golang.org/genproto v0.0.0-20231002182017-d307bd883b97 // indirect
+	google.golang.org/genproto/googleapis/api v0.0.0-20231002182017-d307bd883b97 // indirect
+	google.golang.org/genproto/googleapis/rpc v0.0.0-20231002182017-d307bd883b97 // indirect
+	google.golang.org/protobuf v1.32.0 // indirect
+)

data/xds/go.sum

@@ -0,0 +1,82 @@
+cloud.google.com/go v0.26.0/go.mod h1:aQUYkXzVsufM+DwF1aE+0xfcU+56JwCaLick0ClmMTw=
+github.com/BurntSushi/toml v0.3.1/go.mod h1:xHWCNGjB5oqiDr8zfno3MHue2Ht5sIBksp03qcyfWMU=
+github.com/census-instrumentation/opencensus-proto v0.2.1/go.mod h1:f6KPmirojxKA12rnyqOA5BBL4O983OfeGPqjHWSTneU=
+github.com/census-instrumentation/opencensus-proto v0.4.1 h1:iKLQ0xPNFxR/2hzXZMrBo8f1j86j5WHzznCCQxV/b8g=
+github.com/census-instrumentation/opencensus-proto v0.4.1/go.mod h1:4T9NM4+4Vw91VeyqjLS6ao50K5bOcLKN6Q42XnYaRYw=
+github.com/client9/misspell v0.3.4/go.mod h1:qj6jICC3Q7zFZvVWo7KLAzC3yx5G7kyvSDkc90ppPyw=
+github.com/cncf/xds/go v0.0.0-20230607035331-e9ce68804cb4 h1:/inchEIKaYC1Akx+H+gqO04wryn5h75LSazbRlnya1k=
+github.com/cncf/xds/go v0.0.0-20230607035331-e9ce68804cb4/go.mod h1:eXthEFrGJvWHgFFCl3hGmgk+/aYT6PnTQLykKQRLhEs=
+github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
+github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/envoyproxy/go-control-plane v0.9.0/go.mod h1:YTl/9mNaCwkRvm6d1a2C3ymFceY/DCBVvsKhRF0iEA4=
+github.com/envoyproxy/go-control-plane v0.12.0 h1:4X+VP1GHd1Mhj6IB5mMeGbLCleqxjletLK6K0rbxyZI=
+github.com/envoyproxy/go-control-plane v0.12.0/go.mod h1:ZBTaoJ23lqITozF0M6G4/IragXCQKCnYbmlmtHvwRG0=
+github.com/envoyproxy/protoc-gen-validate v0.1.0/go.mod h1:iSmxcyjqTsJpI2R4NaDN7+kN2VEUnK/pcBlmesArF7c=
+github.com/envoyproxy/protoc-gen-validate v1.0.2 h1:QkIBuU5k+x7/QXPvPPnWXWlCdaBFApVqftFV6k087DA=
+github.com/envoyproxy/protoc-gen-validate v1.0.2/go.mod h1:GpiZQP3dDbg4JouG/NNS7QWXpgx6x8QiMKdmN72jogE=
+github.com/golang/glog v0.0.0-20160126235308-23def4e6c14b/go.mod h1:SBH7ygxi8pfUlaOkMMuAQtPIUF8ecWP5IEl/CR7VP2Q=
+github.com/golang/mock v1.1.1/go.mod h1:oTYuIxOrZwtPieC+H1uAHpcLFnEyAGVDL/k47Jfbm0A=
+github.com/golang/protobuf v1.2.0/go.mod h1:6lQm79b+lXiMfvg/cZm0SGofjICqVBUtrP5yJMmIC1U=
+github.com/golang/protobuf v1.3.2/go.mod h1:6lQm79b+lXiMfvg/cZm0SGofjICqVBUtrP5yJMmIC1U=
+github.com/golang/protobuf v1.5.0/go.mod h1:FsONVRAS9T7sI+LIUmWTfcYkHO4aIWwzhcaSAoJOfIk=
+github.com/golang/protobuf v1.5.3 h1:KhyjKVUg7Usr/dYsdSqoFveMYd5ko72D+zANwlG1mmg=
+github.com/golang/protobuf v1.5.3/go.mod h1:XVQd3VNwM+JqD3oG2Ue2ip4fOMUkwXdXDdiuN0vRsmY=
+github.com/google/go-cmp v0.2.0/go.mod h1:oXzfMopK8JAjlY9xF4vHSVASa0yLyX7SntLO5aqRK0M=
+github.com/google/go-cmp v0.5.5/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE=
+github.com/google/go-cmp v0.5.9 h1:O2Tfq5qg4qc4AmwVlvv0oLiVAGB7enBSJ2x2DqQFi38=
+github.com/google/go-cmp v0.5.9/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY=
+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
+github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/prometheus/client_model v0.0.0-20190812154241-14fe0d1b01d4/go.mod h1:xMI15A0UPsDsEKsMN9yxemIoYk6Tm2C1GtYGdfGttqA=
+github.com/stretchr/testify v1.8.4 h1:CcVxjf3Q8PM0mHUKJCdn+eZZtm5yQwehR5yeSVQQcUk=
+github.com/stretchr/testify v1.8.4/go.mod h1:sz/lmYIOXD/1dqDmKjjqLyZ2RngseejIcXlSw2iwfAo=
+golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2/go.mod h1:djNgcEr1/C05ACkg1iLfiJU5Ep61QUkGW8qpdssI0+w=
+golang.org/x/exp v0.0.0-20190121172915-509febef88a4/go.mod h1:CJ0aWSM057203Lf6IL+f9T1iT9GByDxfZKAQTCR3kQA=
+golang.org/x/lint v0.0.0-20181026193005-c67002cb31c3/go.mod h1:UVdnD1Gm6xHRNCYTkRU2/jEulfH38KcIWyp/GAMgvoE=
+golang.org/x/lint v0.0.0-20190227174305-5b3e6a55c961/go.mod h1:wehouNa3lNwaWXcvxsM5YxQ5yQlVC4a0KAMCusXpPoU=
+golang.org/x/lint v0.0.0-20190313153728-d0100b6bd8b3/go.mod h1:6SW0HCj/g11FgYtHlgUYUwCkIfeOF89ocIRzGO/8vkc=
+golang.org/x/net v0.0.0-20180724234803-3673e40ba225/go.mod h1:mL1N/T3taQHkDXs73rZJwtUhF3w3ftmwwsq0BUmARs4=
+golang.org/x/net v0.0.0-20180826012351-8a410e7b638d/go.mod h1:mL1N/T3taQHkDXs73rZJwtUhF3w3ftmwwsq0BUmARs4=
+golang.org/x/net v0.0.0-20190213061140-3a22650c66bd/go.mod h1:mL1N/T3taQHkDXs73rZJwtUhF3w3ftmwwsq0BUmARs4=
+golang.org/x/net v0.0.0-20190311183353-d8887717615a/go.mod h1:t9HGtf8HONx5eT2rtn7q6eTqICYqUVnKs3thJo3Qplg=
+golang.org/x/net v0.17.0 h1:pVaXccu2ozPjCXewfr1S7xza/zcXTity9cCdXQYSjIM=
+golang.org/x/net v0.17.0/go.mod h1:NxSsAGuq816PNPmqtQdLE42eU2Fs7NoRIZrHJAlaCOE=
+golang.org/x/oauth2 v0.0.0-20180821212333-d2e6202438be/go.mod h1:N/0e6XlmueqKjAGxoOufVs8QHGRruUQn6yWY3a++T0U=
+golang.org/x/sync v0.0.0-20180314180146-1d60e4601c6f/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
+golang.org/x/sync v0.0.0-20181108010431-42b317875d0f/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
+golang.org/x/sync v0.0.0-20190423024810-112230192c58/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
+golang.org/x/sys v0.0.0-20180830151530-49385e6e1522/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
+golang.org/x/sys v0.0.0-20190215142949-d0b11bdaac8a/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
+golang.org/x/sys v0.13.0 h1:Af8nKPmuFypiUBjVoU9V20FiaFXOcuZI21p0ycVYYGE=
+golang.org/x/sys v0.13.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ=
+golang.org/x/text v0.13.0 h1:ablQoSUd0tRdKxZewP80B+BaqeKJuVhuRxj/dkrun3k=
+golang.org/x/text v0.13.0/go.mod h1:TvPlkZtksWOMsz7fbANvkp4WM8x/WCo/om8BMLbz+aE=
+golang.org/x/tools v0.0.0-20190114222345-bf090417da8b/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ=
+golang.org/x/tools v0.0.0-20190226205152-f727befe758c/go.mod h1:9Yl7xja0Znq3iFh3HoIrodX9oNMXvdceNzlUR8zjMvY=
+golang.org/x/tools v0.0.0-20190311212946-11955173bddd/go.mod h1:LCzVGOaR6xXOjkQ3onu1FJEFr0SW1gC7cKk1uF8kGRs=
+golang.org/x/tools v0.0.0-20190524140312-2c0ae7006135/go.mod h1:RgjU9mgBXZiqYHBnxXauZ1Gv1EHHAz9KjViQ78xBX0Q=
+golang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
+google.golang.org/appengine v1.1.0/go.mod h1:EbEs0AVv82hx2wNQdGPgUI5lhzA/G0D9YwlJXL52JkM=
+google.golang.org/appengine v1.4.0/go.mod h1:xpcJRLb0r/rnEns0DIKYYv+WjYCduHsrkT7/EB5XEv4=
+google.golang.org/genproto v0.0.0-20180817151627-c66870c02cf8/go.mod h1:JiN7NxoALGmiZfu7CAH4rXhgtRTLTxftemlI0sWmxmc=
+google.golang.org/genproto v0.0.0-20190819201941-24fa4b261c55/go.mod h1:DMBHOl98Agz4BDEuKkezgsaosCRResVns1a3J2ZsMNc=
+google.golang.org/genproto v0.0.0-20231002182017-d307bd883b97 h1:SeZZZx0cP0fqUyA+oRzP9k7cSwJlvDFiROO72uwD6i0=
+google.golang.org/genproto v0.0.0-20231002182017-d307bd883b97/go.mod h1:t1VqOqqvce95G3hIDCT5FeO3YUc6Q4Oe24L/+rNMxRk=
+google.golang.org/genproto/googleapis/api v0.0.0-20231002182017-d307bd883b97 h1:W18sezcAYs+3tDZX4F80yctqa12jcP1PUS2gQu1zTPU=
+google.golang.org/genproto/googleapis/api v0.0.0-20231002182017-d307bd883b97/go.mod h1:iargEX0SFPm3xcfMI0d1domjg0ZF4Aa0p2awqyxhvF0=
+google.golang.org/genproto/googleapis/rpc v0.0.0-20231002182017-d307bd883b97 h1:6GQBEOdGkX6MMTLT9V+TjtIRZCw9VPD5Z+yHY9wMgS0=
+google.golang.org/genproto/googleapis/rpc v0.0.0-20231002182017-d307bd883b97/go.mod h1:v7nGkzlmW8P3n/bKmWBn2WpBjpOEx8Q6gMueudAmKfY=
+google.golang.org/grpc v1.19.0/go.mod h1:mqu4LbDTu4XGKhr4mRzUsmM4RtVoemTSY81AxZiDr8c=
+google.golang.org/grpc v1.23.0/go.mod h1:Y5yQAOtifL1yxbo5wqy6BxZv8vAUGQwXBOALyacEbxg=
+google.golang.org/grpc v1.25.1/go.mod h1:c3i+UQWmh7LiEpx4sFZnkU36qjEYZ0imhYfXVyQciAY=
+google.golang.org/grpc v1.60.0 h1:6FQAR0kM31P6MRdeluor2w2gPaS4SVNrD/DNTxrQ15k=
+google.golang.org/grpc v1.60.0/go.mod h1:OlCHIeLYqSSsLi6i49B5QGdzaMZK9+M7LXN2FKz4eGM=
+google.golang.org/protobuf v1.26.0-rc.1/go.mod h1:jlhhOSvTdKEhbULTjvd4ARK9grFBp09yW+WbY/TyQbw=
+google.golang.org/protobuf v1.26.0/go.mod h1:9q0QmTI4eRPtz6boOQmLYwt+qCgq0jsYwAQnmE0givc=
+google.golang.org/protobuf v1.32.0 h1:pPC6BG5ex8PDFnkbrGU3EixyhKcQ2aDuBS36lqK/C7I=
+google.golang.org/protobuf v1.32.0/go.mod h1:c6P6GXX6sHbq/GpV6MGZEdwhWPcYBgnhAHhKbcUYpos=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
+honnef.co/go/tools v0.0.0-20190102054323-c2f93a96b099/go.mod h1:rf3lG4BRIbNafJWhAfAdb/ePZxsR/4RtNHQocxwk9r4=
+honnef.co/go/tools v0.0.0-20190523083050-ea95bdfd59fc/go.mod h1:rf3lG4BRIbNafJWhAfAdb/ePZxsR/4RtNHQocxwk9r4=

data/xds/readme.md

@@ -0,0 +1,122 @@
+# xDS Integration Tests
+
+This directory contains Docker Compose configuration and test files for xDS integration testing, following the same pattern as `async-redis` (Sentinel and Cluster tests).
+
+## Setup
+
+The Docker Compose setup includes:
+- **xds-control-plane**: xDS control plane server (using go-control-plane)
+- **backend-1, backend-2, backend-3**: Multiple gRPC backend servers
+- **tests**: Test runner container
+
+## Running Tests
+
+### Start the environment
+
+```bash
+cd xds
+bundle install  # generates gems.locked for Docker build
+docker compose up -d
+```
+
+### Wait for services to be ready
+
+```bash
+docker compose ps
+```
+
+All services should show as "healthy" or "running".
+
+### Run tests
+
+```bash
+# Run tests in docker compose
+docker compose run --rm tests
+
+# Or run tests locally (if services are accessible)
+# Set XDS_SERVER_URI environment variable
+export XDS_SERVER_URI=xds-control-plane:18000
+bundle exec sus xds/test
+```
+
+### Cleanup
+
+```bash
+docker compose down
+```
+
+## Test Structure
+
+Tests are located in `xds/test/async/grpc/xds/` and follow the same pattern as other async-grpc tests:
+
+- `client.rb`: Tests for `Async::GRPC::XDS::Client`
+- Tests use `Sus::Fixtures::Async::ReactorContext` for async test support
+- Tests connect to docker compose services using service names (e.g., `xds-control-plane:18000`)
+
+## Environment Variables
+
+- `XDS_SERVER_URI`: xDS control plane server URI (default: `xds-control-plane:18000`)
+- `RUBY_VERSION`: Ruby version for test container (default: `latest`)
+- `COVERAGE`: Enable code coverage reporting
+
+## Backend Servers
+
+The backend servers (`backend-1`, `backend-2`, `backend-3`) are simple gRPC servers that:
+- Implement the test service interface
+- Include backend ID in response metadata
+- Can be used to test load balancing and failover
+
+See `backend_server.rb` for implementation details.
+
+## Mock xDS Control Plane
+
+For simpler unit testing, you can use a mock xDS server instead of the full Docker Compose setup. See the test files for examples of mocking xDS responses.
+
+## Troubleshooting
+
+### Services not starting
+
+Check logs:
+```bash
+docker compose logs xds-control-plane
+docker compose logs backend-1
+```
+
+### Tests failing to connect
+
+Ensure services are healthy:
+```bash
+docker compose ps
+```
+
+Check network connectivity:
+```bash
+docker compose exec tests ping xds-control-plane
+```
+
+## Protobuf Setup
+
+The xDS implementation uses Envoy protobuf definitions. Protos come from [envoyproxy/envoy](https://github.com/envoyproxy/envoy) (`api/`) or [envoyproxy/data-plane-api](https://github.com/envoyproxy/data-plane-api). Use **xDS v3** (v2 is deprecated).
+
+### Required protobuf files
+
+- `envoy/service/discovery/v3/discovery.proto` - DiscoveryRequest/Response.
+- `envoy/service/discovery/v3/ads.proto` - AggregatedDiscoveryService.
+- `envoy/config/cluster/v3/cluster.proto` - Cluster (CDS).
+- `envoy/config/endpoint/v3/endpoint.proto` - ClusterLoadAssignment (EDS).
+- `envoy/config/core/v3/base.proto` - Node, Locality, etc.
+- `google/protobuf/any.proto` - For Any type in DiscoveryResponse.
+
+### Generating Ruby code
+
+```bash
+protoc --ruby_out=lib \
+  --proto_path=vendor/envoy-api \
+  envoy/service/discovery/v3/discovery.proto \
+  envoy/service/discovery/v3/ads.proto \
+  envoy/config/cluster/v3/cluster.proto \
+  envoy/config/endpoint/v3/endpoint.proto \
+  envoy/config/core/v3/base.proto
+```
+
+Lock the Envoy API version (submodule tag or commit) for compatibility.

data/xds/test/async/grpc/xds/client.rb

@@ -0,0 +1,294 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "async/grpc/xds/client"
+require "async/grpc/xds/ads_stream"
+require "async/grpc/service"
+require "sus/fixtures/async"
+require "async/http/endpoint"
+require_relative "../../../../../fixtures/async/grpc/test_interface"
+require "json"
+require "net/http"
+require "set"
+require "uri"
+
+describe Async::GRPC::XDS::Client do
+	include Sus::Fixtures::Async::ReactorContext
+	
+	let(:xds_server_uri) {ENV["XDS_SERVER_URI"] || "xds-control-plane:18000"}
+	let(:xds_admin_uri) {ENV["XDS_ADMIN_URI"] || "http://xds-control-plane:18001"}
+	let(:service_name) {"myservice"}
+	
+	let(:bootstrap) do
+		{
+			xds_servers: [
+				{
+					server_uri: xds_server_uri,
+					channel_creds: [{type: "insecure"}]
+				}
+			],
+			node: {
+				id: "test-client-#{Process.pid}",
+				cluster: "test"
+			}
+		}
+	end
+	
+	let(:client) {subject.new(service_name, bootstrap: bootstrap)}
+	
+	def backend_id(response)
+		response.value[/Response from ([^:]+)/, 1]
+	end
+	
+	def call_backend_ids(stub, count: 6)
+		count.times.map do
+			request = Protocol::GRPC::Fixtures::TestMessage.new(value: "test")
+			backend_id(stub.unary_call(request))
+		end
+	end
+	
+	def post_admin(path, payload = {})
+		uri = URI.join("#{xds_admin_uri}/", path)
+		request = Net::HTTP::Post.new(uri)
+		request["Content-Type"] = "application/json"
+		request.body = JSON.dump(payload)
+		
+		response = Net::HTTP.start(uri.host, uri.port) do |http|
+			http.request(request)
+		end
+		
+		unless response.is_a?(Net::HTTPSuccess)
+			raise "Admin request failed: #{response.code} #{response.body}"
+		end
+		
+		JSON.parse(response.body)
+	end
+	
+	def set_control_plane_endpoints(*endpoints)
+		post_admin("endpoints", endpoints: endpoints)
+	end
+	
+	def reset_control_plane_streams
+		post_admin("reset-streams")
+	end
+	
+	def restore_control_plane_endpoints
+		set_control_plane_endpoints(
+			"backend-1:50051",
+			"backend-2:50052",
+			"backend-3:50053"
+		)
+	end
+	
+	def eventually(timeout: 15, interval: 0.1)
+		deadline = Time.now + timeout
+		last_error = nil
+		
+		while Time.now < deadline
+			begin
+				result = yield
+				return result if result
+			rescue => error
+				last_error = error
+			end
+			
+			sleep(interval)
+		end
+		
+		raise last_error if last_error
+		raise "Timed out waiting for condition"
+	end
+	
+	it "can stream updates" do
+		skip "Requires xDS control plane (XDS_SERVER_URI)" unless ENV["XDS_SERVER_URI"]
+		
+		received = []
+		delegate = Object.new
+		delegate.define_singleton_method(:discovery_response){|response, _stream| received << response}
+		
+		endpoint = Async::HTTP::Endpoint.parse(
+			"http://#{xds_server_uri}",
+			protocol: Async::HTTP::Protocol::HTTP2
+		)
+		http_client = Async::HTTP::Client.new(endpoint)
+		grpc_client = Async::GRPC::Client.new(http_client)
+		node = Envoy::Config::Core::V3::Node.new(id: "test-#{Process.pid}", cluster: "test")
+		
+		initial = Envoy::Service::Discovery::V3::DiscoveryRequest.new(
+			type_url: "type.googleapis.com/envoy.config.cluster.v3.Cluster",
+			resource_names: [service_name],
+			node: node
+		)
+		stream = Async::GRPC::XDS::ADSStream.new(grpc_client, node, delegate: delegate)
+		
+		stream_task = Async{stream.run(initial: initial)}
+		deadline = Time.now + 10
+		while received.empty? && Time.now < deadline
+			sleep(0.1)
+		end
+		stream_task.stop
+		
+		expect(received.size).to be >= 1
+	end
+	
+	it "can resolve endpoints" do
+		skip "Requires docker compose environment (XDS_SERVER_URI)" unless ENV["XDS_SERVER_URI"]
+		
+		endpoints = client.resolve_endpoints
+		
+		expect(endpoints.size).to be >= 1
+	end
+	
+	it "can make RPC calls through xDS" do
+		skip "Requires docker compose environment (XDS_SERVER_URI)" unless ENV["XDS_SERVER_URI"]
+		
+		stub = client.stub(Async::GRPC::Fixtures::TestInterface, service_name)
+		
+		request = Protocol::GRPC::Fixtures::TestMessage.new(value: "test")
+		response = stub.unary_call(request)
+		
+		expect(response).to be_a(Protocol::GRPC::Fixtures::TestMessage)
+		expect(response.value).to be(:include?, "test")
+	end
+	
+	it "load balances across multiple endpoints" do
+		skip "Requires docker compose environment (XDS_SERVER_URI)" unless ENV["XDS_SERVER_URI"]
+		
+		stub = client.stub(Async::GRPC::Fixtures::TestInterface, service_name)
+		endpoints_used = Set.new
+		
+		10.times do
+			request = Protocol::GRPC::Fixtures::TestMessage.new(value: "test")
+			response = stub.unary_call(request)
+			endpoints_used << response.value
+		end
+		
+		expect(endpoints_used.size).to be >= 1
+	end
+	
+	it "handles bootstrap configuration errors" do
+		expect{subject.new(service_name, bootstrap: {invalid: "config" })}.to raise_exception(Async::GRPC::XDS::Client::ConfigurationError)
+	end
+	
+	it "handles no endpoints available" do
+		skip "Requires docker compose environment (XDS_SERVER_URI)" unless ENV["XDS_SERVER_URI"]
+		
+		invalid_client = subject.new("nonexistent-service", bootstrap: bootstrap)
+		
+		expect{invalid_client.resolve_endpoints}.to raise_exception(Async::GRPC::XDS::Client::NoEndpointsError)
+	end
+	
+	it "evicts resolved promises to prevent unbounded growth" do
+		skip "Requires docker compose environment (XDS_SERVER_URI)" unless ENV["XDS_SERVER_URI"]
+		
+		xds_client = subject.new(service_name, bootstrap: bootstrap)
+		xds_client.resolve_endpoints
+		
+		context = xds_client.instance_variable_get(:@context)
+		# Resolved promises are evicted immediately; hashes stay bounded
+		expect(context.instance_variable_get(:@cluster_promises)).to be(:empty?)
+		expect(context.instance_variable_get(:@endpoint_promises)).to be(:empty?)
+	end
+	
+	it "clears promise caches on close to prevent memory growth" do
+		skip "Requires docker compose environment (XDS_SERVER_URI)" unless ENV["XDS_SERVER_URI"]
+		
+		xds_client = subject.new(service_name, bootstrap: bootstrap)
+		xds_client.resolve_endpoints
+		
+		context = xds_client.instance_variable_get(:@context)
+		xds_client.close
+		
+		# Close clears any remaining promises (e.g. unresolved for nonexistent services)
+		expect(context.instance_variable_get(:@cluster_promises)).to be(:empty?)
+		expect(context.instance_variable_get(:@endpoint_promises)).to be(:empty?)
+	end
+	
+	it "applies endpoint updates from the control plane" do
+		skip "Requires docker compose environment (XDS_SERVER_URI)" unless ENV["XDS_SERVER_URI"]
+		
+		begin
+			set_control_plane_endpoints("backend-1:50051")
+			
+			xds_client = subject.new(service_name, bootstrap: bootstrap)
+			stub = xds_client.stub(Async::GRPC::Fixtures::TestInterface, service_name)
+			
+			eventually do
+				ids = call_backend_ids(stub, count: 3)
+				ids.all?{|id| id == "backend-1"}
+			end
+			
+			set_control_plane_endpoints("backend-1:50051", "backend-2:50052")
+			
+			eventually do
+				ids = call_backend_ids(stub, count: 6)
+				ids.include?("backend-2")
+			end
+		ensure
+			xds_client&.close
+			restore_control_plane_endpoints
+		end
+	end
+	
+	it "removes and recovers endpoints from control plane updates" do
+		skip "Requires docker compose environment (XDS_SERVER_URI)" unless ENV["XDS_SERVER_URI"]
+		
+		begin
+			set_control_plane_endpoints("backend-1:50051", "backend-2:50052")
+			
+			xds_client = subject.new(service_name, bootstrap: bootstrap)
+			stub = xds_client.stub(Async::GRPC::Fixtures::TestInterface, service_name)
+			
+			eventually do
+				ids = call_backend_ids(stub, count: 6)
+				ids.include?("backend-1") && ids.include?("backend-2")
+			end
+			
+			set_control_plane_endpoints("backend-2:50052")
+			
+			eventually do
+				ids = call_backend_ids(stub, count: 4)
+				ids.all?{|id| id == "backend-2"}
+			end
+			
+			set_control_plane_endpoints("backend-1:50051", "backend-2:50052")
+			
+			eventually do
+				ids = call_backend_ids(stub, count: 6)
+				ids.include?("backend-1")
+			end
+		ensure
+			xds_client&.close
+			restore_control_plane_endpoints
+		end
+	end
+	
+	it "reconnects after the ADS stream is reset" do
+		skip "Requires docker compose environment (XDS_SERVER_URI)" unless ENV["XDS_SERVER_URI"]
+		
+		begin
+			set_control_plane_endpoints("backend-1:50051")
+			
+			xds_client = subject.new(service_name, bootstrap: bootstrap)
+			stub = xds_client.stub(Async::GRPC::Fixtures::TestInterface, service_name)
+			
+			eventually do
+				ids = call_backend_ids(stub, count: 3)
+				ids.all?{|id| id == "backend-1"}
+			end
+			
+			reset_control_plane_streams
+			set_control_plane_endpoints("backend-2:50052")
+			
+			eventually(timeout: 20) do
+				ids = call_backend_ids(stub, count: 4)
+				ids.all?{|id| id == "backend-2"}
+			end
+		ensure
+			xds_client&.close
+			restore_control_plane_endpoints
+		end
+	end
+end