async-grpc-xds 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: fba6859fd43ebb2de75d228d4511125d1c7b36f08321fdda99eabf573fea900a
+  data.tar.gz: 2bca6eb3ec749a434703f0296f6a12c14e6d75f5518930618355e3abd8b37d83
+SHA512:
+  metadata.gz: 78f056024e2e5c0cfbf1e1ca67acf9edd9b6ca357659911cbd733eeb2fde2ff0d73c169724a2caebd1ea1860bfaa09ce07784d950a5e9908c9c1a07c2021e81d
+  data.tar.gz: 4e9a3490cfb4e8918994301ef300a2780929dffd31dec5278bf690f976e37681e9476f58899fc668f9799d3d9398fbc740654d42599a7ee8b01c265a47a70e7b

data/fixtures/async/grpc/test_interface.rb

@@ -0,0 +1,79 @@
+# 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

@@ -0,0 +1,56 @@
+# 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

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

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "async"
+require "async/grpc/client"
+require "envoy/service/discovery/v3/aggregated_discovery_service"
+require "envoy/service/discovery/v3/discovery_pb"
+require "envoy/config/core/v3/base_pb"
+
+module Async
+	module GRPC
+		module XDS
+			# Encapsulates a single ADS (Aggregated Discovery Service) bidirectional stream.
+			# Owns the stream lifecycle and delegates events to a delegate object.
+			class ADSStream
+				# Interface for ADSStream delegates. Implement these methods to receive stream events.
+				module Delegate
+					# Called when a DiscoveryResponse is received from the server.
+					# @parameter response [Envoy::Service::Discovery::V3::DiscoveryResponse] The discovery response
+					# @parameter stream [ADSStream] The stream instance; use stream.send(request) to send ACKs or new requests
+					def discovery_response(response, stream)
+					end
+				end
+				
+				def initialize(client, node, delegate:)
+					@client = client
+					@node = node
+					@delegate = delegate
+					@body = nil
+				end
+				
+				# Send a DiscoveryRequest on the stream. Call from within discovery_response to send ACKs.
+				# @parameter request [Envoy::Service::Discovery::V3::DiscoveryRequest] The request to send
+				def send(request)
+					@body&.write(request)
+				end
+				
+				# Run the ADS stream. Blocks until the stream completes or errors.
+				# @parameter initial [Object | Array | Nil] Initial message(s) to send (defaults to node-only request if nil/empty)
+				def run(initial: nil)
+					service = Envoy::Service::Discovery::V3::AggregatedDiscoveryService.new(
+						"envoy.service.discovery.v3.AggregatedDiscoveryService"
+					)
+					
+					initial = Array(initial).any? ? initial : [Envoy::Service::Discovery::V3::DiscoveryRequest.new(node: @node)]
+					
+					@client.invoke(service, :StreamAggregatedResources, nil, initial: initial) do |body, readable_body|
+						@body = body
+						@delegate.stream_opened(self) if @delegate.respond_to?(:stream_opened)
+						
+						begin
+							readable_body.each do |response|
+								@delegate.discovery_response(response, self)
+							end
+						ensure
+							@delegate.stream_closed(self) if @delegate.respond_to?(:stream_closed)
+							@body = nil
+						end
+					end
+				rescue => error
+					@delegate.stream_error(self, error) if @delegate.respond_to?(:stream_error)
+					Console.error(self, "Failed while streaming updates!", exception: error)
+					raise
+				end
+			end
+		end
+	end
+end

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

@@ -0,0 +1,255 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "async"
+require "async/http/client"
+require "async/http/endpoint"
+require "protocol/http"
+require "protocol/grpc"
+require "async/grpc/client"
+require "async/grpc/stub"
+require_relative "context"
+require_relative "load_balancer"
+
+module Async
+	module GRPC
+		module XDS
+			# Wrapper client for xDS-enabled gRPC connections
+			# Follows the same pattern as Async::Redis::SentinelClient and ClusterClient
+			class Client < Protocol::HTTP::Middleware
+				# Raised when xDS configuration cannot be loaded
+				ConfigurationError = Context::ConfigurationError
+				
+				# Raised when no endpoints are available
+				class NoEndpointsError < StandardError
+				end
+				
+				# Raised when cluster configuration cannot be reloaded
+				ReloadError = Context::ReloadError
+				
+				# Create a new xDS client
+				# @parameter service_name [String] Target service name (e.g., "myservice")
+				# @parameter bootstrap [Hash, String, nil] Bootstrap config (hash, file path, or nil for default)
+				# @parameter headers [Protocol::HTTP::Headers] Default headers
+				# @parameter options [Hash] Additional options passed to underlying clients
+				def initialize(service_name, bootstrap: nil, headers: Protocol::HTTP::Headers.new, node: nil, **options)
+					@service_name = service_name
+					@bootstrap = load_bootstrap(bootstrap)
+					@headers = headers
+					@options = options
+					
+					@context = Context.new(@bootstrap, node: node || @bootstrap[:node])
+					@load_balancer = nil
+					@clients = {}  # Cache clients per endpoint (like ClusterClient caches node.client)
+					@mutex = Mutex.new
+				end
+				
+				# Resolve endpoints lazily (like SentinelClient.resolve_address)
+				# @returns [Array<Async::HTTP::Endpoint>] Available endpoints
+				def resolve_endpoints
+					@mutex.synchronize do
+						unless @load_balancer
+							# Discover cluster via CDS
+							cluster = @context.discover_cluster(@service_name)
+							
+							# Discover endpoints via EDS
+							endpoints = @context.discover_endpoints(cluster)
+							
+							raise NoEndpointsError, "No endpoints discovered for #{@service_name}" if endpoints.empty?
+							
+							# Create load balancer
+							@load_balancer = LoadBalancer.new(cluster, endpoints)
+							
+							# Set load balancer reference in context for endpoint updates
+							@context.load_balancer = @load_balancer
+						end
+						
+						@load_balancer.healthy_endpoints
+					end
+				rescue Context::ReloadError => error
+					raise NoEndpointsError, "No endpoints discovered for #{@service_name}", cause: error
+				end
+				
+				# Get a client for making calls (like ClusterClient.client_for)
+				# Resolves endpoints lazily and picks one via load balancer
+				# @returns [Array(Async::GRPC::Client, Async::HTTP::Endpoint)] Client and endpoint for request tracking
+				def client_for_call
+					endpoints = resolve_endpoints
+					raise NoEndpointsError, "No endpoints available for #{@service_name}" if endpoints.empty?
+					
+					# Pick endpoint via load balancer
+					endpoint = @load_balancer.pick
+					raise NoEndpointsError, "No healthy endpoints available" unless endpoint
+					
+					# Cache client per endpoint (like ClusterClient caches node.client)
+					client = @clients[endpoint] ||= begin
+						http_client = Async::HTTP::Client.new(endpoint, **@options)
+						Async::GRPC::Client.new(http_client, headers: @headers)
+					end
+					[client, endpoint]
+				end
+				
+				# Implement Protocol::HTTP::Middleware interface
+				# This allows XDS::Client to be used anywhere Async::GRPC::Client is used
+				# @parameter request [Protocol::HTTP::Request] The HTTP request
+				# @returns [Protocol::HTTP::Response] The HTTP response
+				def call(request, attempts: 3)
+					client, endpoint = client_for_call
+					@load_balancer.record_request_start(endpoint)
+					begin
+						client.call(request)
+					rescue Protocol::GRPC::Error => error
+						# Handle endpoint changes (like ClusterClient handles MOVED/ASK)
+						if error.status_code == Protocol::GRPC::Status::UNAVAILABLE
+							Console.warn(self, error)
+							
+							# Invalidate cache, reload configuration
+							invalidate_cache!
+							
+							attempts -= 1
+							retry if attempts > 0
+						end
+						
+						raise
+					rescue => error
+						# Network errors might indicate endpoint failure
+						Console.warn(self, error)
+						
+						# Invalidate this specific endpoint
+						invalidate_endpoint(client)
+						
+						attempts -= 1
+						retry if attempts > 0
+						
+						raise
+					end
+				ensure
+					@load_balancer&.record_request_end(endpoint)
+				end
+				
+				# Create a stub for the given interface.
+				# Same API as Async::GRPC::Client - load balancing happens per RPC call.
+				# @parameter interface_class [Class] Interface class (subclass of Protocol::GRPC::Interface)
+				# @parameter service_name [String] Service name (e.g., "hello.Greeter")
+				# @returns [Async::GRPC::Stub] Stub object with methods for each RPC
+				def stub(interface_class, service_name)
+					interface = interface_class.new(service_name)
+					Stub.new(self, interface)
+				end
+				
+				# Invoke an RPC (called by Stub). Load balances per call.
+				# @parameter service [Protocol::GRPC::Interface] Interface instance
+				# @parameter method [Symbol, String] Method name
+				# @parameter request [Object | Nil] Request message
+				# @parameter metadata [Hash] Custom metadata headers
+				# @parameter timeout [Numeric | Nil] Optional timeout in seconds
+				# @parameter encoding [String | Nil] Optional compression encoding
+				# @parameter initial [Object | Array] Optional initial message(s) for bidirectional streaming
+				# @yields {|input, output| ...} Block for streaming calls
+				# @returns [Object | Protocol::GRPC::Body::ReadableBody] Response message or readable body
+				def invoke(service, method, request = nil, metadata: {}, timeout: nil, encoding: nil, initial: nil, attempts: 3, &block)
+					client, endpoint = client_for_call
+					@load_balancer.record_request_start(endpoint)
+					begin
+						client.invoke(service, method, request, metadata: metadata, timeout: timeout, encoding: encoding, initial: initial, &block)
+					rescue Protocol::GRPC::Error => error
+						if error.status_code == Protocol::GRPC::Status::UNAVAILABLE
+							Console.warn(self, error)
+							invalidate_cache!
+							attempts -= 1
+							retry if attempts > 0
+						end
+						raise
+					rescue => error
+						Console.warn(self, error)
+						invalidate_endpoint(client)
+						attempts -= 1
+						retry if attempts > 0
+						raise
+					end
+				ensure
+					@load_balancer&.record_request_end(endpoint)
+				end
+				
+				# Close xDS client and all connections
+				def close
+					@clients.each_value(&:close)
+					@clients.clear
+					@context.close
+					@load_balancer&.close
+				end
+				
+				private
+				
+				def load_bootstrap(bootstrap)
+					case bootstrap
+					when Hash
+						normalize_keys(bootstrap)
+					when String
+						load_bootstrap_file(bootstrap)
+					when nil
+						load_default_bootstrap
+					else
+						raise ArgumentError, "Invalid bootstrap: #{bootstrap.inspect}"
+					end
+				end
+				
+				def load_bootstrap_file(path)
+					raise ConfigurationError, "Bootstrap file not found: #{path}" unless File.exist?(path)
+					
+					require "json"
+					normalize_keys(JSON.parse(File.read(path), symbolize_names: true))
+				rescue JSON::ParserError => error
+					raise ConfigurationError, "Invalid bootstrap JSON: #{error.message}"
+				end
+				
+				def normalize_keys(object)
+					case object
+					when Hash
+						object.each_with_object({}) do |(key, value), result|
+							result[key.to_sym] = normalize_keys(value)
+						end
+					when Array
+						object.map{|value| normalize_keys(value)}
+					else
+						object
+					end
+				end
+				
+				def load_default_bootstrap
+					# Try environment variable first
+					if path = ENV["GRPC_XDS_BOOTSTRAP"]
+						return load_bootstrap_file(path)
+					end
+					
+					# Try default location
+					default_path = File.expand_path("~/.config/grpc/bootstrap.json")
+					if File.exist?(default_path)
+						return load_bootstrap_file(default_path)
+					end
+					
+					raise ConfigurationError, "No bootstrap configuration found"
+				end
+				
+				def invalidate_cache!
+					@mutex.synchronize do
+						@clients.each_value(&:close)
+						@clients.clear
+						@load_balancer = nil
+					end
+				end
+				
+				def invalidate_endpoint(client)
+					@mutex.synchronize do
+						endpoint = @clients.key(client)
+						@load_balancer&.mark_unhealthy(endpoint) if endpoint
+						@clients.delete_if{|_, cached_client| cached_client == client}
+						client.close
+					end
+				end
+			end
+		end
+	end
+end

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

@@ -0,0 +1,201 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "async"
+require_relative "discovery_client"
+require_relative "resource_cache"
+require_relative "resources"
+
+module Async
+	module GRPC
+		module XDS
+			# Manages xDS subscriptions and maintains discovered resource state
+			class Context
+				# Raised when configuration is invalid
+				class ConfigurationError < StandardError
+				end
+				
+				# Raised when cluster configuration cannot be reloaded
+				class ReloadError < StandardError
+				end
+				
+				# Initialize xDS context
+				# @parameter bootstrap [Hash] Bootstrap configuration
+				# @parameter node [Hash] Node information (id, cluster, metadata, locality)
+				def initialize(bootstrap, node: nil)
+					@bootstrap = bootstrap
+					xds_server = bootstrap[:xds_servers]&.first
+					raise ConfigurationError, "No xds_servers in bootstrap" unless xds_server
+					
+					@discovery_client = DiscoveryClient.new(xds_server, node: node)
+					@cache = ResourceCache.new
+					@subscriptions = {}  # Track active subscriptions
+					@load_balancer = nil  # Will be set by Client
+					@mutex = Mutex.new
+					@cluster_promises = {}  # service_name -> Async::Promise (level-triggered: resolved value persists)
+					@endpoint_promises = {}  # cluster_name -> Async::Promise
+				end
+				
+				# Set load balancer reference (called by Client)
+				# @parameter load_balancer [LoadBalancer] Load balancer instance
+				def load_balancer=(load_balancer)
+					@load_balancer = load_balancer
+				end
+				
+				# Discover cluster for service (like ClusterClient.reload_cluster!)
+				# @parameter service_name [String] Service to discover
+				# @returns [Resources::Cluster] Cluster configuration
+				def discover_cluster(service_name)
+					@mutex.synchronize do
+						# Check cache first
+						if cluster = @cache.get_cluster(service_name)
+							return cluster
+						end
+						
+						# Subscribe to CDS if not already subscribed
+						unless @subscriptions[:cds]
+							@subscriptions[:cds] = subscribe_cds(service_name)
+						end
+						
+						# Subscribe to EDS for same name up front (EDS clusters use service name as cluster name)
+						# This avoids 10s delay between CDS and EDS - both requests go out together
+						subscription_key = :"eds_#{service_name}"
+						unless @subscriptions[subscription_key]
+							@subscriptions[subscription_key] = subscribe_eds(service_name)
+						end
+					end
+					return @cache.get_cluster(service_name) if @cache.get_cluster(service_name)
+					
+					# Wait for cluster (CDS response)
+					cluster = wait_for_cluster(service_name, timeout: 10)
+					raise ReloadError, "Failed to discover cluster: #{service_name}" unless cluster
+					cluster
+				end
+				
+				# Discover endpoints for cluster (like ClusterClient discovers nodes)
+				# @parameter cluster [Resources::Cluster] Cluster configuration
+				# @returns [Array<Async::HTTP::Endpoint>] Discovered endpoints
+				def discover_endpoints(cluster)
+					cluster_name = cluster.name
+					@mutex.synchronize do
+						# Check cache first
+						if endpoints = @cache.get_endpoints(cluster_name)
+							return endpoints
+						end
+						
+						# Subscribe to EDS if not already subscribed
+						subscription_key = :"eds_#{cluster_name}"
+						unless @subscriptions[subscription_key]
+							@subscriptions[subscription_key] = subscribe_eds(cluster_name)
+						end
+					end
+					return @cache.get_endpoints(cluster_name) if @cache.get_endpoints(cluster_name)
+					
+					# Wait outside mutex so EDS callback can run and update cache
+					endpoints = wait_for_endpoints(cluster_name, timeout: 10)
+					raise ReloadError, "Failed to discover endpoints for cluster: #{cluster_name}" unless endpoints
+					endpoints
+				end
+				
+				# Subscribe to CDS (Cluster Discovery Service)
+				# @parameter service_name [String] Service name
+				# @returns [Async::Task] Subscription task
+				def subscribe_cds(service_name)
+					@discovery_client.subscribe(
+						DiscoveryClient::CLUSTER_TYPE,
+						[service_name]
+					) do |resources|
+						resources.each do |resource|
+							cluster = resource.is_a?(Resources::Cluster) ? resource : Resources::Cluster.from_proto(resource)
+							@cache.update_cluster(cluster)
+							resolve_cluster_promise(cluster.name, cluster)
+						end
+					end
+				end
+				
+				# Subscribe to EDS (Endpoint Discovery Service)
+				# @parameter cluster_name [String] Cluster name
+				# @returns [Async::Task] Subscription task
+				def subscribe_eds(cluster_name)
+					@discovery_client.subscribe(
+						DiscoveryClient::ENDPOINT_TYPE,
+						[cluster_name]
+					) do |resources|
+						resources.each do |resource|
+							assignment = resource.is_a?(Resources::ClusterLoadAssignment) ? resource : Resources::ClusterLoadAssignment.from_proto(resource)
+							endpoints = assignment.endpoints.select(&:healthy?).map do |endpoint|
+								Async::HTTP::Endpoint.parse(endpoint.uri, protocol: Async::HTTP::Protocol::HTTP2)
+							end
+							@cache.update_endpoints(cluster_name, endpoints)
+							resolve_endpoint_promise(cluster_name, endpoints) unless endpoints.empty?
+							@load_balancer&.update_endpoints(endpoints)
+						end
+					end
+				end
+				
+				# Close all subscriptions
+				def close
+					@mutex.synchronize do
+						@subscriptions.each_value do |task|
+							task.stop if task.respond_to?(:stop)
+						end
+						@subscriptions.clear
+						@cluster_promises.clear
+						@endpoint_promises.clear
+					end
+					@discovery_client.close
+				end
+				
+				private
+				
+				def wait_for_cluster(service_name, timeout:)
+					promise = cluster_promise_for(service_name)
+					return promise.value if promise.completed?
+					
+					begin
+						promise.wait(timeout: timeout)
+						promise.completed? ? promise.value : nil
+					rescue Async::TimeoutError
+						nil
+					end
+				end
+				
+				def wait_for_endpoints(cluster_name, timeout:)
+					promise = endpoint_promise_for(cluster_name)
+					return promise.value if promise.completed?
+					
+					begin
+						promise.wait(timeout: timeout)
+						promise.completed? ? promise.value : nil
+					rescue Async::TimeoutError
+						nil
+					end
+				end
+				
+				def cluster_promise_for(service_name)
+					@mutex.synchronize do
+						@cluster_promises[service_name] ||= Async::Promise.new
+					end
+				end
+				
+				def endpoint_promise_for(cluster_name)
+					@mutex.synchronize do
+						@endpoint_promises[cluster_name] ||= Async::Promise.new
+					end
+				end
+				
+				def resolve_cluster_promise(service_name, cluster)
+					cluster_promise_for(service_name).resolve(cluster)
+					@mutex.synchronize{@cluster_promises.delete(service_name)}
+				end
+				
+				def resolve_endpoint_promise(cluster_name, endpoints)
+					endpoint_promise_for(cluster_name).resolve(endpoints)
+					@mutex.synchronize{@endpoint_promises.delete(cluster_name)}
+				end
+			end
+		end
+	end
+end