async-grpc-xds 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fb5e9b5b4fbb4b738a33f5714254602767c65774e0d3cab49c0c7528042885c5
-  data.tar.gz: 7c1fc5b76c954ed6c2a61f6b2f3e154f1287492f9f81438cfccec0788d803beb
+  metadata.gz: 3f5ca6a95f124eec9df174142e956b1e5c619e22258ed905202526042e3519a9
+  data.tar.gz: af26002e1170beff3b9ba228d12f21f0c1fc6893d8d8c5cf3da30b1af3bced3e
 SHA512:
-  metadata.gz: ba0e68b3e2b1a7767ae5d3e62646818a746d5553d7a2187511914d2cb8cc37a491fae834865294936c6982abefff76b676b0b8bfb67ad93eca55eb3b9f6245d9
-  data.tar.gz: e973bf4dd5bbf1e54efd2c6fba9134960d879a66039e49c0361b47d6bacba1f9e458d0cbcd4c109fe2d134794fef3983c86911332564a3557244b39bb95fbdde
+  metadata.gz: d906ffc9d3874ae1430cf345ee0ec7cc6455266b55743e6fdaa9d9893c923188bb77612dfa8dd7e021940ba586bd06a3554d29dd0561ea3c6dbdb67a0629c0a5
+  data.tar.gz: 37aa45338885d4ed19a0f76d9c81da3c95391e694e9d6919d5cb8f00f0137e575bc982e0e72ca85a2bbe660cb1d7dd0e8d3f65ef861260bee54741087bba8b51

data/context/getting-started.md

@@ -0,0 +1,363 @@
+# Getting Started
+
+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.
+
+## Installation
+
+Add the gem to your project:
+
+~~~ bash
+$ bundle add async-grpc-xds
+~~~
+
+The gem provides both sides of an xDS integration:
+
+  - A control-plane server which publishes in-memory resources to Envoy over ADS or dedicated discovery services.
+  - An experimental Ruby gRPC client which discovers clusters and endpoints from an ADS server.
+
+## Core Concepts
+
+xDS separates logical proxy configuration from the concrete destinations which currently provide it:
+
+| API | Resource | Purpose |
+| --- | --- | --- |
+| CDS | `Cluster` | Describes an upstream service, protocol, health checks, load-balancing policy, and how to discover its endpoints. |
+| EDS | `ClusterLoadAssignment` | Supplies the concrete IP or Unix-socket endpoints for a cluster. |
+| RDS | `RouteConfiguration` | Maps incoming requests to clusters. |
+| LDS | `Listener` | Describes the addresses and network filters where Envoy accepts traffic. |
+
+`async-grpc-xds` currently builds and serves CDS and EDS resources. Routes and listeners normally remain in Envoy's bootstrap configuration or come from another control plane.
+
+Three names connect the configuration:
+
+  - The **management cluster** is a static Envoy cluster, such as `xds_cluster`, which reaches the Ruby xDS server.
+  - The **application cluster** is the logical upstream service, such as `application`.
+  - The EDS `service_name` and `ClusterLoadAssignment#cluster_name` identify the endpoint assignment used by that application cluster. They default to the application cluster name.
+
+The following diagram shows the dedicated CDS and EDS arrangement used throughout this guide:
+
+``` mermaid
+flowchart LR
+	Bootstrap[Envoy bootstrap] --> Management[xds_cluster]
+	Management -->|CDS stream| ControlPlane[Ruby control plane]
+	Management -->|EDS stream| ControlPlane
+	ControlPlane -->|Cluster| Application[application cluster]
+	ControlPlane -->|ClusterLoadAssignment| Workers[worker endpoints]
+	Traffic[Application traffic] --> Envoy
+	Envoy --> Application
+	Application --> Workers
+```
+
+## Serving Dedicated CDS and EDS
+
+Dedicated discovery services are a good fit when this control plane owns application clusters and their local workers, but should not claim Envoy's single ADS connection. Another control plane can then use ADS for coordinated listener, route, or other configuration.
+
+Create a control plane, publish an application cluster and its initial workers, then serve the dedicated CDS and EDS interfaces:
+
+``` ruby
+require "async"
+require "async/grpc/xds"
+require "async/http/endpoint"
+
+control_plane = Async::GRPC::XDS::ControlPlane.new(identifier: "application-supervisor")
+eds_config = Async::GRPC::XDS::ConfigSource.grpc("xds_cluster")
+health_check = Async::GRPC::XDS::HTTPHealthCheck.build(
+	"/health",
+	interval: 2,
+	timeout: 1
+)
+
+control_plane.update_cluster(
+	"application",
+	protocol: :http1,
+	eds_config: eds_config,
+	health_checks: [health_check]
+)
+
+control_plane.update_endpoints("application", [
+	{
+		hostname: "worker-1",
+		addresses: [{address: "127.0.0.1", port: 9292}],
+		healthy: true,
+	},
+	{
+		hostname: "worker-2",
+		addresses: [{address: "127.0.0.1", port: 9293}],
+		healthy: true,
+	},
+])
+
+server = Async::GRPC::XDS::Server.new(
+	control_plane,
+	services: [
+		Async::GRPC::XDS::ClusterDiscoveryService,
+		Async::GRPC::XDS::EndpointDiscoveryService,
+	]
+)
+
+endpoint = Async::HTTP::Endpoint.parse(
+	"http://0.0.0.0:18000",
+	protocol: Async::HTTP::Protocol::HTTP2
+)
+
+Sync do
+	server.run(endpoint)
+end
+```
+
+The management endpoint uses HTTP/2 because xDS is a gRPC protocol. This example uses plaintext HTTP/2 within a trusted local network; deployments can instead configure TLS on the endpoint.
+
+### Envoy Bootstrap
+
+Envoy must know how to reach the management server before it can discover anything else. Define `xds_cluster` statically and configure CDS to use it:
+
+``` yaml
+node:
+  id: application-proxy-1
+  cluster: application-proxies
+
+admin:
+  address:
+    socket_address:
+      address: 127.0.0.1
+      port_value: 19000
+
+dynamic_resources:
+  cds_config:
+    resource_api_version: V3
+    api_config_source:
+      api_type: GRPC
+      transport_api_version: V3
+      grpc_services:
+        - envoy_grpc:
+            cluster_name: xds_cluster
+
+static_resources:
+  listeners:
+    - name: ingress
+      address:
+        socket_address:
+          address: 0.0.0.0
+          port_value: 8080
+      filter_chains:
+        - filters:
+            - name: envoy.filters.network.http_connection_manager
+              typed_config:
+                "@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
+                stat_prefix: ingress_http
+                route_config:
+                  name: local_route
+                  validate_clusters: false
+                  virtual_hosts:
+                    - name: application
+                      domains: ["*"]
+                      routes:
+                        - match:
+                            prefix: "/"
+                          route:
+                            cluster: application
+                http_filters:
+                  - name: envoy.filters.http.router
+                    typed_config:
+                      "@type": type.googleapis.com/envoy.extensions.filters.http.router.v3.Router
+
+  clusters:
+    - name: xds_cluster
+      connect_timeout: 1s
+      type: STATIC
+      typed_extension_protocol_options:
+        envoy.extensions.upstreams.http.v3.HttpProtocolOptions:
+          "@type": type.googleapis.com/envoy.extensions.upstreams.http.v3.HttpProtocolOptions
+          explicit_http_config:
+            http2_protocol_options: {}
+      load_assignment:
+        cluster_name: xds_cluster
+        endpoints:
+          - lb_endpoints:
+              - endpoint:
+                  address:
+                    socket_address:
+                      address: 127.0.0.1
+                      port_value: 18000
+```
+
+The static route names `application` before CDS has delivered that cluster, so `validate_clusters: false` allows the bootstrap configuration to load. Envoy keeps the discovered cluster warming until its EDS assignment arrives.
+
+The `xds_cluster` name must match the name passed to {ruby Async::GRPC::XDS::ConfigSource.grpc}. The generated application cluster then opens its dedicated EDS stream through the same management cluster.
+
+## Publishing Endpoint Changes
+
+The control plane is thread-safe and immediately notifies connected discovery streams after a resource changes. Publish the complete current endpoint assignment whenever workers start, stop, or change health:
+
+``` ruby
+control_plane.update_endpoints("application", [
+	{
+		hostname: "worker-2",
+		addresses: [{address: "127.0.0.1", port: 9293}],
+		healthy: true,
+	},
+])
+```
+
+This implementation uses state-of-the-world discovery: each EDS response contains the complete assignment requested by Envoy. It does not currently implement the delta discovery RPCs.
+
+Every call to `update_cluster` or `update_endpoints` increments the version for that resource type, even if the generated resource is unchanged. Producers should therefore avoid publishing redundant updates.
+
+To remove a service completely, remove both resources:
+
+``` ruby
+control_plane.remove_endpoints("application")
+control_plane.remove_cluster("application")
+```
+
+### IP and Unix-Socket Addresses
+
+An endpoint must contain one or more addresses. An IP address uses `:address` and `:port`:
+
+``` ruby
+{
+	addresses: [{address: "127.0.0.1", port: 9292}],
+	healthy: true,
+}
+```
+
+A Unix domain socket uses `:path`:
+
+``` ruby
+{
+	addresses: [{path: "/run/application/worker-1.ipc"}],
+	healthy: true,
+}
+```
+
+Several addresses in one `:addresses` array describe alternative addresses for one logical load-balancer endpoint. The first becomes Envoy's primary address and the remainder become `additional_addresses`; they do not represent additional workers.
+
+### Health
+
+The `:healthy` value sets the EDS `health_status` for an endpoint. It accepts healthy, unhealthy, degraded, or unknown states; booleans map to healthy and unhealthy.
+
+This reported state is separate from active health checks. Adding a health check to the cluster tells Envoy to probe every published endpoint itself:
+
+``` ruby
+health_check = Async::GRPC::XDS::HTTPHealthCheck.build(
+	"/health",
+	interval: 2,
+	timeout: 1,
+	unhealthy_threshold: 2,
+	healthy_threshold: 1
+)
+
+control_plane.update_cluster(
+	"application",
+	protocol: :http1,
+	eds_config: Async::GRPC::XDS::ConfigSource.grpc("xds_cluster"),
+	health_checks: [health_check]
+)
+```
+
+Use reported health for information already known by the resource owner, such as whether a worker remains registered. Use active health checks when Envoy should independently verify that it can send application traffic to the endpoint.
+
+## ADS or Dedicated Services
+
+Both transports carry the same `DiscoveryRequest` and `DiscoveryResponse` messages. The difference is how Envoy organizes its streams and management servers:
+
+| | ADS | Dedicated CDS and EDS |
+| --- | --- | --- |
+| Streams | One aggregated stream for several resource types. | One stream per resource type. |
+| Coordination | Provides ordering across related resource types from one control plane. | Each resource type progresses independently. |
+| Ownership | Envoy has one ADS management server. | Each resource type can use its own configuration source. |
+| Best fit | One control plane owns coordinated proxy configuration. | A focused control plane owns only clusters or endpoints. |
+
+The default server exposes ADS:
+
+``` ruby
+control_plane = Async::GRPC::XDS::ControlPlane.new
+control_plane.update_cluster("application", protocol: :http1)
+control_plane.update_endpoints("application", endpoints)
+
+server = Async::GRPC::XDS::Server.new(control_plane)
+```
+
+{ruby Async::GRPC::XDS::Cluster.build} uses ADS for EDS by default, so no explicit `eds_config` is needed in this mode. Configure Envoy accordingly:
+
+``` yaml
+dynamic_resources:
+  ads_config:
+    api_type: GRPC
+    transport_api_version: V3
+    grpc_services:
+      - envoy_grpc:
+          cluster_name: xds_cluster
+  cds_config:
+    resource_api_version: V3
+    ads: {}
+```
+
+Do not use the default ADS EDS source when serving dedicated CDS and EDS. In that arrangement, pass `ConfigSource.grpc("xds_cluster")` while building or updating every application cluster.
+
+## Using the Ruby xDS Client
+
+{ruby Async::GRPC::XDS::Client} is an experimental gRPC client which discovers a named cluster and its healthy endpoints over ADS, then load-balances RPC calls between them.
+
+Supply bootstrap configuration directly:
+
+``` ruby
+bootstrap = {
+	xds_servers: [
+		{
+			server_uri: "127.0.0.1:18000",
+			channel_creds: [{type: "insecure"}],
+		}
+	],
+	node: {
+		id: "orders-client-1",
+		cluster: "orders-clients",
+	}
+}
+
+Sync do
+	client = Async::GRPC::XDS::Client.new("application", bootstrap: bootstrap)
+	
+	begin
+		stub = client.stub(Greeter::Interface, "example.Greeter")
+		response = stub.say_hello(Greeter::Request.new(name: "World"))
+	ensure
+		client.close
+	end
+end
+```
+
+Alternatively, pass the path to a JSON bootstrap file. When `bootstrap` is omitted, the client checks `GRPC_XDS_BOOTSTRAP` and then `~/.config/grpc/bootstrap.json`.
+
+The Ruby client currently consumes ADS, supports CDS and EDS, filters endpoints by reported health, and provides basic client-side load balancing and retry behavior. Dedicated CDS and EDS client streams are not yet implemented.
+
+## Operational Checks
+
+Envoy's admin interface shows whether it accepted the resources and whether the application cluster has usable members:
+
+~~~ bash
+$ curl -s http://127.0.0.1:19000/config_dump
+$ curl -s http://127.0.0.1:19000/clusters
+$ curl -s http://127.0.0.1:19000/stats | grep -E 'cluster\.application\.(warming|membership_healthy|update_rejected)'
+~~~
+
+When a cluster remains in `warming`, check:
+
+  - The `xds_cluster` address and port reach the Ruby server using HTTP/2.
+  - The management cluster name matches the name in every gRPC configuration source.
+  - The CDS cluster name, EDS service name, and `ClusterLoadAssignment#cluster_name` agree.
+  - A dedicated CDS cluster uses a dedicated EDS configuration source rather than `ads: {}`.
+  - Envoy has not incremented `update_rejected`; rejected responses are also returned to the control plane as NACKs and logged.
+
+## Current Scope
+
+`async-grpc-xds` currently provides:
+
+  - xDS v3 protobuf definitions.
+  - State-of-the-world ADS, CDS, and EDS server streams.
+  - In-memory cluster and endpoint resources with per-type versions.
+  - HTTP/1 and HTTP/2 upstream cluster configuration.
+  - IP, Unix-socket, health-status, active HTTP health-check, and out-of-band ORCA policy resource builders.
+  - An experimental ADS-based Ruby gRPC client.
+
+Delta discovery, complete NACK recovery, persistent resource storage, LDS/RDS serving, locality weighting, and complete routing semantics are not implemented yet.

data/context/index.yaml

@@ -0,0 +1,14 @@
+# Automatically generated context index for Utopia::Project guides.
+# Do not edit then files in this directory directly, instead edit the guides and then run `bake utopia:project:agent:context:update`.
+---
+description: xDS support for Async::GRPC clients.
+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
+files:
+- path: getting-started.md
+  title: Getting Started
+  description: 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.

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

@@ -6,9 +6,10 @@
 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"
 
+require_relative "config_source"
+
 module Async
 	module GRPC
 		module XDS
@@ -21,21 +22,20 @@ module Async
 				# Build an EDS cluster resource.
 				# @parameter name [String] The cluster name.
 				# @parameter service_name [String] The EDS service name.
+				# @parameter eds_config [Envoy::Config::Core::V3::ConfigSource] The source used to discover endpoint assignments.
 				# @parameter load_balancing_policy [Envoy::Config::Cluster::V3::LoadBalancingPolicy | Nil] The typed Envoy load-balancing policy.
 				# @parameter health_checks [Array(Envoy::Config::Core::V3::HealthCheck)] The active health checks applied to cluster endpoints.
 				# @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, health_checks: [], connect_timeout: 5, protocol: :http2)
+				def build(name, service_name: name, eds_config: ConfigSource.ads, load_balancing_policy: nil, health_checks: [], 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
-							)
+							eds_config: eds_config
 						),
 						connect_timeout: duration(connect_timeout),
 						health_checks: health_checks,

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

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "envoy/service/discovery/v3/discovery_pb"
+require "protocol/grpc/interface"
+
+require_relative "control_plane"
+require_relative "discovery_service"
+
+module Async
+	module GRPC
+		module XDS
+			# Serves Cluster Discovery Service requests from a {ControlPlane}.
+			class ClusterDiscoveryService < DiscoveryService
+				SERVICE_NAME = "envoy.service.cluster.v3.ClusterDiscoveryService"
+				RESOURCE_TYPE = ControlPlane::CLUSTER_TYPE
+				
+				# The gRPC interface for cluster discovery.
+				class Interface < Protocol::GRPC::Interface
+					rpc :StreamClusters,
+						request_class: Envoy::Service::Discovery::V3::DiscoveryRequest,
+						response_class: Envoy::Service::Discovery::V3::DiscoveryResponse,
+						streaming: :bidirectional
+					
+					rpc :DeltaClusters,
+						request_class: Envoy::Service::Discovery::V3::DeltaDiscoveryRequest,
+						response_class: Envoy::Service::Discovery::V3::DeltaDiscoveryResponse,
+						streaming: :bidirectional
+				end
+				
+				# Initialize a Cluster Discovery Service.
+				# @parameter control_plane [ControlPlane] The control plane that provides clusters.
+				def initialize(control_plane)
+					super(Interface, SERVICE_NAME, control_plane, resource_type: RESOURCE_TYPE)
+				end
+				
+				# Serve a state-of-the-world cluster discovery 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_clusters(input, output, call)
+					stream_resources(input, output)
+				end
+				
+				# Reject a delta cluster discovery stream, which is not supported.
+				# @raises [Protocol::GRPC::Error] Always raised because delta xDS is not implemented.
+				def delta_clusters(input, output, call)
+					delta_resources
+				end
+			end
+		end
+	end
+end

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

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "envoy/config/core/v3/config_source_pb"
+require "envoy/config/core/v3/grpc_service_pb"
+
+module Async
+	module GRPC
+		module XDS
+			# Builds Envoy xDS configuration sources.
+			module ConfigSource
+				extend self
+				
+				# Build a configuration source that uses the global ADS server.
+				# @returns [Envoy::Config::Core::V3::ConfigSource] The ADS configuration source.
+				def ads
+					Envoy::Config::Core::V3::ConfigSource.new(
+						ads: Envoy::Config::Core::V3::AggregatedConfigSource.new
+					)
+				end
+				
+				# Build a configuration source for a dedicated gRPC discovery service.
+				# @parameter cluster_name [String] The static Envoy cluster used to reach the management server.
+				# @returns [Envoy::Config::Core::V3::ConfigSource] The gRPC API configuration source.
+				def grpc(cluster_name)
+					Envoy::Config::Core::V3::ConfigSource.new(
+						resource_api_version: :V3,
+						api_config_source: Envoy::Config::Core::V3::ApiConfigSource.new(
+							api_type: :GRPC,
+							transport_api_version: :V3,
+							grpc_services: [
+								Envoy::Config::Core::V3::GrpcService.new(
+									envoy_grpc: Envoy::Config::Core::V3::GrpcService::EnvoyGrpc.new(
+										cluster_name: cluster_name.to_s
+									)
+								)
+							]
+						)
+					)
+				end
+			end
+		end
+	end
+end

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

@@ -19,7 +19,7 @@ require_relative "endpoint"
 module Async
 	module GRPC
 		module XDS
-			# Maintains xDS resource snapshots and notifies ADS streams when resources change.
+			# Maintains xDS resource snapshots and notifies discovery streams when resources change.
 			class ControlPlane
 				CLUSTER_TYPE = Cluster::TYPE_URL
 				ENDPOINT_TYPE = Endpoint::TYPE_URL
@@ -152,7 +152,7 @@ module Async
 				end
 				
 				# Register a stream to receive resource-change notifications.
-				# @parameter stream [Service::Stream] The stream to register.
+				# @parameter stream [Stream] The stream to register.
 				def register_stream(stream)
 					@mutex.synchronize do
 						@streams.add(stream)
@@ -160,7 +160,7 @@ module Async
 				end
 				
 				# Remove a registered stream.
-				# @parameter stream [Service::Stream] The stream to remove.
+				# @parameter stream [Stream] The stream to remove.
 				def remove_stream(stream)
 					@mutex.synchronize do
 						@streams.delete(stream)

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

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "async"
+require "async/grpc/service"
+require "protocol/grpc/error"
+require "protocol/grpc/status"
+
+require_relative "control_plane"
+require_relative "stream"
+
+module Async
+	module GRPC
+		module XDS
+			# Shared implementation for state-of-the-world xDS discovery services.
+			class DiscoveryService < Async::GRPC::Service
+				# Initialize a discovery service.
+				# @parameter interface [Class] The gRPC service interface.
+				# @parameter service_name [String] The fully qualified gRPC service name.
+				# @parameter control_plane [ControlPlane] The control plane that provides resources.
+				# @parameter resource_type [String | Nil] The fixed resource type, or `nil` for aggregated discovery.
+				def initialize(interface, service_name, control_plane, resource_type: nil)
+					super(interface, service_name)
+					
+					@control_plane = control_plane
+					@resource_type = resource_type
+				end
+				
+				# Serve a state-of-the-world discovery stream.
+				# @parameter input [Enumerable] The stream of discovery requests.
+				# @parameter output [Interface(:write)] The discovery response stream.
+				# @asynchronous
+				def stream_resources(input, output)
+					stream = Stream.new(@control_plane, output, resource_type: @resource_type)
+					@control_plane.register_stream(stream)
+					
+					reader = Async::Task.current.async do
+						input.each do |request|
+							stream.request(request)
+						end
+					end
+					
+					writer = Async::Task.current.async do
+						stream.run
+					end
+					
+					reader.wait
+				ensure
+					stream&.close
+					reader&.stop
+					writer&.stop
+					@control_plane.remove_stream(stream) if stream
+				end
+				
+				# Reject a delta discovery stream, which is not supported.
+				# @raises [Protocol::GRPC::Error] Always raised because delta xDS is not implemented.
+				def delta_resources
+					raise Protocol::GRPC::Error.new(
+						Protocol::GRPC::Status::UNIMPLEMENTED,
+						"Delta xDS is not implemented."
+					)
+				end
+				
+			end
+		end
+	end
+end

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

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "envoy/service/discovery/v3/discovery_pb"
+require "protocol/grpc/interface"
+
+require_relative "control_plane"
+require_relative "discovery_service"
+
+module Async
+	module GRPC
+		module XDS
+			# Serves Endpoint Discovery Service requests from a {ControlPlane}.
+			class EndpointDiscoveryService < DiscoveryService
+				SERVICE_NAME = "envoy.service.endpoint.v3.EndpointDiscoveryService"
+				RESOURCE_TYPE = ControlPlane::ENDPOINT_TYPE
+				
+				# The gRPC interface for endpoint discovery.
+				class Interface < Protocol::GRPC::Interface
+					rpc :StreamEndpoints,
+						request_class: Envoy::Service::Discovery::V3::DiscoveryRequest,
+						response_class: Envoy::Service::Discovery::V3::DiscoveryResponse,
+						streaming: :bidirectional
+					
+					rpc :DeltaEndpoints,
+						request_class: Envoy::Service::Discovery::V3::DeltaDiscoveryRequest,
+						response_class: Envoy::Service::Discovery::V3::DeltaDiscoveryResponse,
+						streaming: :bidirectional
+				end
+				
+				# Initialize an Endpoint Discovery Service.
+				# @parameter control_plane [ControlPlane] The control plane that provides endpoint assignments.
+				def initialize(control_plane)
+					super(Interface, SERVICE_NAME, control_plane, resource_type: RESOURCE_TYPE)
+				end
+				
+				# Serve a state-of-the-world endpoint discovery 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_endpoints(input, output, call)
+					stream_resources(input, output)
+				end
+				
+				# Reject a delta endpoint discovery stream, which is not supported.
+				# @raises [Protocol::GRPC::Error] Always raised because delta xDS is not implemented.
+				def delta_endpoints(input, output, call)
+					delta_resources
+				end
+			end
+		end
+	end
+end