async-grpc-compatible 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e1a8ff0cff0bfc7725848538d6bc490b6dff6e7ffdd5bcd96d0dc6461b6c918c
+  data.tar.gz: a0377f5efac4796f5f8bee1d1384ea19a0bd3e61a71a0eb758fe22a4ddf245ac
+SHA512:
+  metadata.gz: 6edb95034ed047c101473b1ec6a360d1e9832940273796c7f20bf8271304bb39e6e34a41ce825e062f2b91142767452c9aee23e0bc9631ce0fbf2f7c61854d9d
+  data.tar.gz: 8166f1fe7114ab3a62530b9b3c026208e797c54457186bbce318ce12d938378e6052863894649092b641c238aa6f2d8ee8860cb2a358c8ddc87f3ed3309d567a

data/lib/async/grpc/compatible/channel_credentials.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "io/endpoint/tls/configuration"
+
+module Async
+	module GRPC
+		module Compatible
+			# Maps gRPC channel credentials to transport-neutral TLS configurations.
+			module ChannelCredentials
+				# Create a TLS configuration using the positional arguments of `GRPC::Core::ChannelCredentials.new`.
+				# @parameter root_certificates [String | Nil] The trusted root certificates encoded as a PEM bundle, or nil to use the transport's default trust store.
+				# @parameter private_key [String | Nil] The client private key encoded as PEM.
+				# @parameter certificate_chain [String | Nil] The client certificate chain encoded as a PEM bundle, with the leaf certificate first.
+				# @returns [IO::Endpoint::TLS::Configuration] The transport-neutral TLS configuration.
+				# @raises [ArgumentError] If a certificate bundle is empty or the client certificate chain and private key are not supplied together.
+				# @raises [TypeError] If certificate or private key material is not a string.
+				def self.new(root_certificates = nil, private_key = nil, certificate_chain = nil)
+					trust_store = unless root_certificates.nil?
+						IO::Endpoint::TLS::TrustStore.parse(root_certificates)
+					end
+					
+					certificates = unless certificate_chain.nil?
+						IO::Endpoint::TLS::Certificates.parse(certificate_chain)
+					end
+					
+					IO::Endpoint::TLS::Configuration.new(
+						trust_store: trust_store,
+						certificate_chain: certificates,
+						private_key: private_key,
+						verification: :peer
+					)
+				end
+			end
+		end
+	end
+end

data/lib/async/grpc/compatible/client_stub.rb

@@ -0,0 +1,494 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "async/grpc"
+require "async/http/endpoint"
+require "async/http/protocol/http2"
+require "base64"
+require "openssl"
+require "grpc"
+require "io/endpoint/tls/configuration"
+require "protocol/grpc/body/readable"
+require "protocol/grpc/body/writable"
+require "protocol/grpc/metadata"
+require_relative "channel_credentials"
+require_relative "operation"
+
+::Thread.attr_accessor :async_grpc_compatible_shared_clients
+
+module Async
+	module GRPC
+		module Compatible
+			# Represents a reusable Async gRPC channel.
+			class Channel
+				# Initialize a channel for the given endpoint.
+				# @parameter endpoint [Async::HTTP::Endpoint | Nil] The remote HTTP/2 endpoint, inferred from a supplied Async client when possible.
+				# @parameter client [Async::GRPC::Client | Nil] An existing client to use.
+				def initialize(endpoint = nil, client: nil)
+					@endpoint = endpoint
+					if @endpoint.nil? && client.is_a?(Async::GRPC::Client) && client.delegate.respond_to?(:endpoint)
+						@endpoint = client.delegate.endpoint
+					end
+					@client = client || Async::GRPC::Client.open(endpoint)
+					@owned = client.nil?
+				end
+				
+				# @attribute [Async::HTTP::Endpoint | Nil] The remote endpoint.
+				attr_reader :endpoint
+				
+				# @attribute [Async::GRPC::Client] The shared Async gRPC client.
+				attr_reader :client
+				
+				# Close the underlying client when it is owned by this channel.
+				def close
+					@client.close if @owned
+				end
+			end
+			
+			# Represents a channel whose client is shared with other shared channels for the same URL and TLS configuration on the same thread.
+			#
+			# Each thread has its own client because an Async connection pool belongs to a single reactor.
+			class SharedChannel < Channel
+				# @returns [Hash] The current thread's shared clients, keyed by URL and TLS configuration.
+				def self.clients
+					::Thread.current.async_grpc_compatible_shared_clients ||= {}
+				end
+				
+				# Close the current thread's shared clients. Shared channels open new clients on their next call.
+				def self.close
+					# Detach the clients before closing them, since closing may yield to a call which opens a new client:
+					clients = ::Thread.current.async_grpc_compatible_shared_clients
+					::Thread.current.async_grpc_compatible_shared_clients = nil
+					
+					clients&.each_value(&:close)
+				end
+				
+				# Initialize a shared channel for the given URL and TLS configuration.
+				#
+				# The channel freezes a copy of the TLS configuration, so later changes by the caller do not affect shared clients.
+				#
+				# @parameter url [String] The remote `http` or `https` URL.
+				# @parameter tls_configuration [IO::Endpoint::TLS::Configuration | Nil] The TLS configuration for an `https` URL.
+				def initialize(url, tls_configuration = nil)
+					tls_configuration = tls_configuration&.dup&.freeze
+					@endpoint = Async::HTTP::Endpoint.parse(url, protocol: Async::HTTP::Protocol::HTTP2, tls_configuration: tls_configuration)
+					@key = ["#{@endpoint.scheme}://#{@endpoint.authority}", tls_configuration]
+				end
+				
+				# @attribute [Async::GRPC::Client] The current thread's client for this endpoint.
+				def client
+					self.class.clients[@key] ||= Async::GRPC::Client.open(@endpoint)
+				end
+				
+				# Leave the shared client open for other channels.
+				def close
+				end
+			end
+			
+			# Represents a subset of `GRPC::ClientStub` backed by {Async::GRPC::Client}.
+			class ClientStub
+				INSECURE_CREDENTIALS = :this_channel_is_insecure
+				LOCAL_SUBCHANNEL_POOL = "grpc.use_local_subchannel_pool"
+				DEFAULT_TIMEOUT = nil
+				
+				# Transport failures which end a call without a gRPC status. grpc-ruby reports these as `UNAVAILABLE`.
+				TRANSPORT_ERRORS = [
+					::Protocol::HTTP::RefusedError,
+					::Protocol::HTTP2::Error,
+					::Protocol::HPACK::Error,
+					IOError,
+					SocketError,
+					SystemCallError,
+					OpenSSL::SSL::SSLError,
+				].freeze
+				
+				# The gRPC status for each HTTP/2 stream reset code, from gRPC's HTTP/2 status mapping. Other codes map to `INTERNAL`.
+				STREAM_RESET_STATUSES = {
+					::Protocol::HTTP2::Error::REFUSED_STREAM => ::GRPC::Core::StatusCodes::UNAVAILABLE,
+					::Protocol::HTTP2::Error::CANCEL => ::GRPC::Core::StatusCodes::CANCELLED,
+					::Protocol::HTTP2::Error::ENHANCE_YOUR_CALM => ::GRPC::Core::StatusCodes::RESOURCE_EXHAUSTED,
+					::Protocol::HTTP2::Error::INADEQUATE_SECURITY => ::GRPC::Core::StatusCodes::PERMISSION_DENIED,
+				}.freeze
+				
+				# Build a compatible stub class for a generated GRPC::GenericService.
+				# @parameter service [Class] The generated service definition.
+				# @returns [Class] A client stub with methods for the service's unary RPCs.
+				def self.for(service)
+					Class.new(self) do
+						service.rpc_descs.each do |name, description|
+							method_name = ::GRPC::GenericService.underscore(name.to_s)
+							path = "/#{service.service_name}/#{name}"
+							marshal = description.marshal_proc
+							unmarshal = description.unmarshal_proc(:output)
+							define_method(method_name) do |request, **options|
+								raise NotImplementedError, "Streaming RPCs are not yet supported!" unless description.request_response?
+								request_response(path, request, marshal, unmarshal, **options)
+							end
+						end
+					end
+				end
+				
+				# Construct a compatible channel.
+				#
+				# Without an override, the channel shares connections with other stubs for the same target and TLS configuration on the current thread. Set the `grpc.use_local_subchannel_pool` channel argument to a non-zero value to use a client owned by this channel instead.
+				#
+				# @parameter channel_override [Channel, Async::GRPC::Client | Nil] An existing compatible channel or client.
+				# @parameter host [String] The gRPC target.
+				# @parameter credentials [IO::Endpoint::TLS::Configuration, Symbol] The channel TLS configuration or insecure marker.
+				# @parameter channel_arguments [Hash] gRPC channel arguments.
+				# @returns [Channel] The compatible channel.
+				def self.setup_channel(channel_override, host, credentials, channel_arguments = {})
+					case channel_override
+					when Channel
+						return channel_override
+					when Async::GRPC::Client
+						return Channel.new(client: channel_override)
+					when nil
+						# Continue constructing the channel:
+					else
+						raise TypeError, "Channel override must be an Async::GRPC::Compatible::Channel or Async::GRPC::Client!"
+					end
+					
+					# grpc-ruby accepts string and symbol keys. Only fall back on nil, so an explicit false is preserved:
+					local_pool = channel_arguments[LOCAL_SUBCHANNEL_POOL]
+					local_pool = channel_arguments[LOCAL_SUBCHANNEL_POOL.to_sym] if local_pool.nil?
+					
+					# gRPC uses integer boolean flags (0/1). Ruby treats 0 as truthy, so check it explicitly:
+					if local_pool && local_pool != 0
+						Channel.new(endpoint_for(host, credentials, channel_arguments))
+					else
+						SharedChannel.new(url_for(host, credentials), tls_configuration_for(credentials))
+					end
+				end
+				
+				# Construct an HTTP/2 endpoint for a gRPC target.
+				#
+				# Channels with a local subchannel pool use this endpoint. Shared channels are identified by their URL and TLS configuration, so they are constructed from {url_for} and {tls_configuration_for} instead.
+				#
+				# @parameter host [String] The gRPC target.
+				# @parameter credentials [IO::Endpoint::TLS::Configuration, Symbol] The channel TLS configuration or insecure marker.
+				# @parameter channel_arguments [Hash] gRPC channel arguments.
+				# @returns [Async::HTTP::Endpoint] The HTTP/2 endpoint.
+				def self.endpoint_for(host, credentials, channel_arguments = {})
+					Async::HTTP::Endpoint.parse(url_for(host, credentials), protocol: Async::HTTP::Protocol::HTTP2, tls_configuration: tls_configuration_for(credentials))
+				end
+				
+				# Construct the URL for a gRPC target.
+				# @parameter host [String] The gRPC target.
+				# @parameter credentials [IO::Endpoint::TLS::Configuration, Symbol] The channel TLS configuration or insecure marker.
+				# @returns [String] The `http` or `https` URL.
+				def self.url_for(host, credentials)
+					raise TypeError, "Host must be a String!" unless host.is_a?(String)
+					
+					scheme = scheme_for(credentials)
+					target = normalize_target(host)
+					
+					if target.match?(/\Ahttps?:\/\//)
+						url = target
+					else
+						url = "#{scheme}://#{target}"
+					end
+					
+					raise ArgumentError, "Target scheme must match the channel credentials!" unless url.start_with?("#{scheme}://")
+					
+					return url
+				end
+				
+				# Construct the TLS configuration for the given credentials.
+				# @parameter credentials [IO::Endpoint::TLS::Configuration, Symbol] The channel TLS configuration or insecure marker.
+				# @returns [IO::Endpoint::TLS::Configuration | Nil] The TLS configuration, or `nil` for insecure credentials.
+				def self.tls_configuration_for(credentials)
+					return nil if scheme_for(credentials) == "http"
+					
+					IO::Endpoint::TLS::Configuration.new(
+						trust_store: credentials.trust_store,
+						certificate_chain: credentials.certificate_chain,
+						private_key: credentials.private_key,
+						verification: credentials.verification || :peer
+					)
+				end
+				
+				# Determine the URL scheme for the given credentials.
+				# @parameter credentials [IO::Endpoint::TLS::Configuration, Symbol] The channel TLS configuration or insecure marker.
+				# @returns [String] Either `"http"` or `"https"`.
+				def self.scheme_for(credentials)
+					return "http" if credentials == INSECURE_CREDENTIALS
+					
+					if credentials.is_a?(IO::Endpoint::TLS::Configuration)
+						return "https"
+					end
+					
+					raise TypeError, "Credentials must be IO::Endpoint::TLS::Configuration or :this_channel_is_insecure; native gRPC credentials are unsupported!"
+				end
+				
+				# Normalize a grpc-ruby target into an HTTP authority.
+				# @parameter host [String] The gRPC target.
+				# @returns [String] The normalized target.
+				def self.normalize_target(host)
+					if host.start_with?("dns:///")
+						host.delete_prefix("dns:///")
+					elsif host.start_with?("dns://")
+						host.delete_prefix("dns://").delete_prefix("/")
+					elsif host.match?(/\A(?:unix|unix-abstract|ipv4|ipv6|xds|passthrough):/i)
+						raise ArgumentError, "Unsupported gRPC target: #{host.inspect}!"
+					else
+						host
+					end
+				end
+				
+				# Create a compatible client stub.
+				# @parameter host [String] The gRPC target.
+				# @parameter credentials [IO::Endpoint::TLS::Configuration, Symbol, Proc, Object, Nil] The channel TLS configuration, insecure marker, or Ruby authentication callback. Callbacks use a default verified TLS channel. Nil requires a channel override.
+				# @parameter channel_override [Channel, Async::GRPC::Client | Nil] An existing compatible channel or client.
+				# @parameter timeout [Numeric | Nil] The default relative timeout in seconds.
+				# @parameter propagate_mask [Integer | Nil] Reserved for grpc-ruby compatibility.
+				# @parameter channel_args [Hash] gRPC channel arguments.
+				# @parameter call_credentials [Proc | Object | Nil] An authentication callback or an object with updater_proc.
+				# @parameter interceptors [Array] grpc-ruby client interceptors, which are not yet supported.
+				def initialize(host, credentials,
+					channel_override: nil,
+					timeout: nil,
+					propagate_mask: nil,
+					channel_args: {},
+					interceptors: [],
+					call_credentials: nil)
+					raise NotImplementedError, "Client interceptors are not yet supported!" unless interceptors.empty?
+					
+					if credentials.respond_to?(:updater_proc) || credentials.respond_to?(:call)
+						raise ArgumentError, "Supply call credentials only once!" if call_credentials
+						call_credentials = credentials
+						credentials = IO::Endpoint::TLS::Configuration.new(verification: :peer)
+					end
+					self.class.scheme_for(credentials) unless credentials.nil? && channel_override
+					@call_credentials = call_credentials
+					channel_arguments = channel_args.dup
+					@channel = self.class.setup_channel(channel_override, host, credentials, channel_arguments)
+					@owned_channel = channel_override.nil?
+					@timeout = timeout
+					@propagate_mask = propagate_mask
+				end
+				
+				# @attribute [Channel] The compatible channel.
+				attr_reader :channel
+				attr_writer :propagate_mask
+				
+				# Send a unary request and return its response.
+				# @parameter method [String] The fully qualified RPC path.
+				# @parameter request [Object] The request object.
+				# @parameter marshal [Proc] A callable which encodes the request.
+				# @parameter unmarshal [Proc] A callable which decodes the response.
+				# @parameter deadline [Time | Nil] The absolute call deadline.
+				# @parameter return_op [Boolean] Whether to return an operation object.
+				# @parameter parent [Object | Nil] A parent server call.
+				# @parameter credentials [Object | Nil] Per-call credentials.
+				# @parameter metadata [Hash] Request metadata.
+				# @returns [Object] The decoded response.
+				# @raises [GRPC::BadStatus] If the call fails.
+				def request_response(method, request, marshal, unmarshal,
+					deadline: nil,
+					return_op: false,
+					parent: nil,
+					credentials: nil,
+					metadata: {})
+					raise NotImplementedError, "Parent call propagation is not yet supported!" if parent
+					
+					timeout = relative_timeout(deadline)
+					call_deadline = timeout && Time.now + timeout
+					operation = Operation.new(deadline: call_deadline) do |operation|
+						execute_request_response(method, request, marshal, unmarshal, metadata, credentials, operation)
+					end
+					return operation if return_op
+					
+					operation.execute
+				end
+				
+				# Close a channel created by this stub. Shared clients remain open for other stubs.
+				def close
+					@channel.close if @owned_channel
+				end
+				
+			private
+				
+				def execute_request_response(method, request, marshal, unmarshal, metadata, credentials, operation)
+					timeout = operation.deadline && operation.deadline - Time.now
+					raise_deadline_exceeded if timeout && timeout <= 0
+					
+					Sync do |task|
+						if timeout
+							task.with_timeout(timeout, Async::GRPC::DeadlineExceededError) do
+								metadata = update_metadata(metadata, credentials, method)
+								invoke_request_response(method, request, marshal, unmarshal, metadata, timeout, operation)
+							end
+						else
+							metadata = update_metadata(metadata, credentials, method)
+							invoke_request_response(method, request, marshal, unmarshal, metadata, nil, operation)
+						end
+					end
+				rescue Async::GRPC::DeadlineExceededError
+					raise_deadline_exceeded
+				rescue Async::GRPC::ResponseError => error
+					status = Protocol::GRPC::Status.for_http_status(error.response.status)
+					raise_bad_status(status, error.message, {}, cause: error)
+				rescue Protocol::GRPC::Error => error
+					raise_bad_status(error.status_code, error.cause&.message || error.message, error.metadata, cause: error)
+				end
+				
+				def update_metadata(metadata, credentials, method)
+					metadata = normalize_metadata(metadata)
+					[@call_credentials, credentials].compact.each do |updater|
+						updater = updater.updater_proc if updater.respond_to?(:updater_proc)
+						raise TypeError, "Call credentials must be callable or expose updater_proc!" unless updater.respond_to?(:call)
+						
+						endpoint = @channel.endpoint
+						raise ArgumentError, "Call credentials require a secure channel with a known endpoint!" unless endpoint && endpoint.scheme == "https"
+						service = normalize_method(method).rpartition("/").first
+						context = {jwt_aud_uri: "https://#{endpoint.authority}#{service}"}
+						attributes = updater.call(context)
+						next if attributes.nil?
+						raise TypeError, "Call credentials must return a Hash or nil!" unless attributes.is_a?(Hash)
+						
+						# Google updaters can return the context along with authentication headers.
+						attributes.each do |key, value|
+							key = key.to_s
+							metadata[key] = value unless key == "jwt_aud_uri"
+						end
+					end
+					metadata
+				end
+				
+				def invoke_request_response(method, request, marshal, unmarshal, metadata, timeout, operation)
+					body = Protocol::GRPC::Body::Writable.new
+					payload = marshal.call(request)
+					raise TypeError, "Marshal must return a String!" unless payload.is_a?(String)
+					
+					body.write(payload)
+					body.close_write
+					
+					timeout = operation.deadline && operation.deadline - Time.now
+					raise_deadline_exceeded if timeout && timeout <= 0
+					
+					headers = build_headers(
+						metadata: normalize_metadata(metadata),
+						timeout: timeout,
+						content_type: "application/grpc"
+					)
+					request = Protocol::HTTP::Request["POST", normalize_method(method), headers, body]
+					payload = perform_request(request, operation)
+					
+					payload ? unmarshal.call(payload) : nil
+				end
+				
+				# Send the request and read its response payload. Application callbacks run outside this method, so their errors are not treated as transport failures.
+				def perform_request(request, operation)
+					response = @channel.client.call(request)
+					
+					begin
+						operation.metadata = extract_metadata(Protocol::HTTP::Headers.new(response.headers.header.to_a, policy: Protocol::GRPC::HEADER_POLICY))
+						response_encoding = response.headers["grpc-encoding"]
+						response_body = Protocol::GRPC::Body::Readable.wrap(response, encoding: response_encoding)
+						payload = response_body&.read
+						response_body&.finish
+						
+						operation.trailing_metadata = extract_metadata(Protocol::HTTP::Headers.new(response.headers.trailer.to_a, policy: Protocol::GRPC::HEADER_POLICY))
+						operation.status = ::Struct::Status.new(
+							Protocol::GRPC::Metadata.extract_status(response.headers),
+							Protocol::GRPC::Metadata.extract_message(response.headers),
+							operation.trailing_metadata
+						)
+						check_status!(response)
+						
+						payload
+					ensure
+						response.close
+					end
+				rescue ::Protocol::HTTP2::StreamError => error
+					status = STREAM_RESET_STATUSES.fetch(error.code, ::GRPC::Core::StatusCodes::INTERNAL)
+					raise_bad_status(status, error.message, {}, cause: error)
+				rescue ::Protocol::HTTP::RemoteError => error
+					# The peer reset the stream with `INTERNAL_ERROR`:
+					raise_bad_status(::GRPC::Core::StatusCodes::INTERNAL, error.message, {}, cause: error)
+				rescue *TRANSPORT_ERRORS => error
+					raise_bad_status(::GRPC::Core::StatusCodes::UNAVAILABLE, error.message, {}, cause: error)
+				end
+				
+				def check_status!(response)
+					status = Protocol::GRPC::Metadata.extract_status(response.headers)
+					return if status == Protocol::GRPC::Status::OK
+					
+					details = Protocol::GRPC::Metadata.extract_message(response.headers)
+					metadata = extract_metadata(response.headers)
+					raise_bad_status(status, details, metadata)
+				end
+				
+				def build_headers(metadata:, timeout:, content_type:)
+					headers = Protocol::HTTP::Headers.new(policy: Protocol::GRPC::HEADER_POLICY)
+					headers["content-type"] = content_type
+					headers["te"] = "trailers"
+					headers["grpc-timeout"] = timeout if timeout
+					
+					metadata.each do |key, value|
+						headers[key] = if key.end_with?("-bin")
+							Base64.strict_encode64(value)
+						else
+							value.to_s
+						end
+					end
+					
+					return headers
+				end
+				
+				def extract_metadata(headers)
+					Protocol::GRPC::Metadata.extract(headers)
+				end
+				
+				def normalize_method(method)
+					method = method.to_s
+					method.start_with?("/") ? method : "/#{method}"
+				end
+				
+				def normalize_metadata(metadata)
+					metadata.to_h.each_with_object({}) do |(key, value), normalized|
+						normalized[key.to_s] = value
+					end
+				end
+				
+				def relative_timeout(deadline)
+					return relative_default_timeout if deadline.nil?
+					
+					if defined?(::GRPC::Core::TimeConsts::INFINITE_FUTURE) && deadline == ::GRPC::Core::TimeConsts::INFINITE_FUTURE
+						return nil
+					end
+					
+					if defined?(::GRPC::Core::TimeConsts::ZERO) && deadline == ::GRPC::Core::TimeConsts::ZERO
+						return 0
+					end
+					
+					if deadline.respond_to?(:to_time)
+						deadline.to_time - Time.now
+					elsif deadline.is_a?(Numeric)
+						deadline
+					else
+						raise TypeError, "Deadline must be a Time or Numeric value!"
+					end
+				end
+				
+				def relative_default_timeout
+					return nil if @timeout.nil? || @timeout < 0
+					
+					@timeout
+				end
+				
+				def raise_deadline_exceeded
+					raise_bad_status(::GRPC::Core::StatusCodes::DEADLINE_EXCEEDED, "Deadline exceeded!", {})
+				end
+				
+				def raise_bad_status(status, details, metadata, cause: nil)
+					error = ::GRPC::BadStatus.new_status_exception(status, details || "Unknown cause!", metadata)
+					raise error, cause: cause
+				end
+			end
+		end
+	end
+end

data/lib/async/grpc/compatible/gapic.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "gapic/grpc"
+require_relative "client_stub"
+
+module Async
+	module GRPC
+		module Compatible
+			# Represents a GAPIC service stub that preserves Ruby credential updaters.
+			class GapicServiceStub < ::Gapic::ServiceStub
+				# Initialize a GAPIC adapter for a generated service definition.
+				# @parameter service [Class] The generated GRPC::GenericService definition.
+				# @parameter channel [Channel | Nil] An optional shared Async channel.
+				# @parameter options [Hash] GAPIC service options, including credentials and endpoint.
+				def initialize(service, channel: nil, **options)
+					@service_name = service.service_name
+					@async_channel = channel
+					super(ClientStub.for(service), **options)
+				end
+				
+				# Construct the Async stub before GAPIC converts credentials into opaque native objects.
+				# @parameter grpc_stub_class [Class] The compatible stub class.
+				# @parameter endpoint [String] The service endpoint.
+				# @parameter credentials [Object] The original GAPIC credentials.
+				# @parameter channel_args [Hash | Nil] Channel arguments.
+				# @parameter interceptors [Array | Nil] Client interceptors.
+				def create_grpc_stub(grpc_stub_class, endpoint:, credentials:, channel_args: nil, interceptors: nil)
+					@grpc_stub = grpc_stub_class.new(endpoint, credentials,
+						channel_override: @async_channel,
+						channel_args: channel_args || {},
+						interceptors: interceptors || [])
+				end
+				
+				# Async::HTTP owns connection pooling; native GAPIC channel pools are unsupported.
+				def create_channel_pool(...)
+					raise ArgumentError, "Use a shared Async channel instead of a GAPIC channel pool!"
+				end
+				
+				# Close the underlying stub's owned connection pool, leaving shared clients open.
+				def close
+					@grpc_stub&.close
+				end
+				
+				# Supply a service identity for the anonymous generated stub class.
+				# @private
+				def setup_logging(system_name: nil, service: nil, **options)
+					super(system_name: "async-grpc-compatible", service: @service_name, **options)
+				end
+			end
+		end
+	end
+end

data/lib/async/grpc/compatible/operation.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require "async"
+require "grpc"
+
+module Async
+	module GRPC
+		module Compatible
+			# Represents a deferred unary call. Execute and cancel active calls in the same reactor.
+			class Operation
+				# Initialize a deferred call.
+				# @parameter deadline [Time | Nil] The absolute call deadline.
+				# @yields {|operation| ...} Executes the request and records its response.
+				def initialize(deadline: nil, &execute)
+					@deadline = deadline
+					@execute = execute
+					@mutex = Thread::Mutex.new
+					@executed = false
+					@finished = false
+					@cancelled = false
+					@task = nil
+					@thread = nil
+					@metadata = nil
+					@trailing_metadata = nil
+					@status = nil
+				end
+				
+				# @attribute [Time | Nil] The absolute call deadline.
+				attr_reader :deadline
+				# @attribute [Hash | Nil] The initial response metadata.
+				attr_accessor :metadata
+				# @attribute [Hash | Nil] The response trailers.
+				attr_accessor :trailing_metadata
+				# @attribute [Struct::Status | Nil] The completed call status.
+				attr_accessor :status
+				
+				# Execute this operation once, waiting for the response.
+				# @returns [Object] The decoded response.
+				# @raises [GRPC::BadStatus] If the RPC fails or is cancelled.
+				def execute
+					@mutex.synchronize do
+						raise RuntimeError, "Operation has already been executed!" if @executed
+						@executed = true
+					end
+					
+					begin
+						Sync do |parent|
+							task = @mutex.synchronize do
+								raise ::GRPC::Cancelled.new("Cancelled!") if @cancelled
+								@thread = Thread.current
+								@task = Async::Task.new(parent, finished: false){@execute.call(self)}
+							end
+							
+							task.run
+							result = task.wait
+							raise ::GRPC::Cancelled.new("Cancelled!") if cancelled?
+							result
+						ensure
+							task&.stop
+						end
+					rescue ::GRPC::BadStatus => error
+						@status = error.to_status
+						raise
+					ensure
+						@mutex.synchronize do
+							@finished = true
+							@task = nil
+						end
+						@execute = nil
+					end
+				end
+				
+				# Cancel a pending or active operation from its reactor.
+				def cancel
+					task = @mutex.synchronize do
+						return if @finished
+						raise ThreadError, "Cancel the operation from its reactor thread!" if @task && @thread != Thread.current
+						@cancelled = true
+						@task
+					end
+					task&.stop
+				end
+				
+				# Whether cancellation was requested or reported by the server.
+				# @returns [Boolean] Whether the operation was cancelled.
+				def cancelled?
+					@mutex.synchronize{@cancelled || @status&.code == ::GRPC::Core::StatusCodes::CANCELLED}
+				end
+			end
+		end
+	end
+end

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

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+# @namespace
+module Async
+	# @namespace
+	module GRPC
+		# @namespace
+		module Compatible
+			VERSION = "0.1.0"
+		end
+	end
+end

data/lib/async/grpc/compatible.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Samuel Williams.
+
+require_relative "compatible/version"
+require_relative "compatible/client_stub"
+
+module Async
+	module GRPC
+		# Provides grpc-ruby compatible client interfaces backed by {Async::GRPC}.
+		module Compatible
+		end
+	end
+end

data/license.md

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright, 2026, by Samuel Williams.  
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/readme.md

@@ -0,0 +1,189 @@
+# Async::GRPC::Compatible
+
+grpc-ruby compatible client interfaces backed by `async-grpc` and `async-http`.
+
+The gem is intended for generated clients which currently construct a `GRPC::ClientStub`, but need to make non-blocking calls inside an Async event loop. Connection pooling and HTTP/2 multiplexing remain the responsibility of `async-http`; stubs for the same target share its connection pool, as described in [Connection sharing](#connection-sharing).
+
+The gem depends on `grpc` for service definitions and error types. TLS configuration comes from `IO::Endpoint`, and requests use Async's connection pool.
+
+## Usage
+
+Please see the [project documentation](https://socketry.github.io/async-grpc-compatible/) for more details.
+
+## Current Compatibility
+
+The initial implementation supports:
+
+  - The grpc-ruby `GRPC::ClientStub.new` parameter shape.
+  - Unary `request_response` calls.
+  - Custom marshal and unmarshal callables.
+  - Request metadata and deadlines.
+  - Insecure endpoints and TLS using `IO::Endpoint::TLS::Configuration`, including custom trust roots and client certificates, with `Compatible::ChannelCredentials.new` mapping gRPC's positional PEM arguments.
+  - Translation of gRPC failures into `GRPC::BadStatus` subclasses.
+  - Deferred unary operations using `return_op: true`.
+  - Ruby credential updaters supplied through `call_credentials:`, `credentials:`, or a credential object with `updater_proc`.
+  - Unary stub generation from `GRPC::GenericService` definitions.
+  - Connection sharing between stubs for the same target, with `grpc.use_local_subchannel_pool` to opt out.
+
+The following are not yet supported:
+
+  - Client, server, or bidirectional streaming.
+  - grpc-ruby interceptors.
+  - Parent call propagation.
+  - Native `GRPC::Core::ChannelCredentials`, `GRPC::Core::CallCredentials`, composed credentials, and native channel overrides. These are rejected because their TLS configuration and authentication callbacks cannot be recovered through Ruby's public API.
+  - grpc-ruby channel arguments other than `grpc.use_local_subchannel_pool`.
+  - Non-DNS resolvers such as Unix sockets and xDS.
+
+Invalid HTTP responses become `GRPC::BadStatus` subclasses using the HTTP status mapping. The error details describe the invalid HTTP status and content type, and `error.cause` is an `Async::GRPC::ResponseError` whose `response` exposes the HTTP status, headers, and buffered body. Call `error.cause.response.read` to read that body.
+
+## Connection sharing
+
+Stubs constructed without a channel override share connections, similar to grpc-core's global subchannel pool. Stubs on the same thread use one `Async::GRPC::Client` when they connect to the same target with the same TLS configuration. TLS configurations are compared by value, so separately constructed but identical configurations share a client, and different trust roots, client certificates, or verification policies never do. Constructing a stub or GAPIC client per request or per job therefore reuses warm connections within the same Async reactor instead of performing a new TLS and HTTP/2 handshake.
+
+Each thread has its own shared client, because an Async connection pool belongs to a single reactor. The client is selected when each call runs, so a stub shared between threads uses the calling thread's connections. Connections do not outlive their reactor. Calls made outside a reactor each run in a temporary reactor, so run related calls inside one `Sync` or `Async` block to reuse connections.
+
+Closing a stub leaves shared clients open for other stubs. Call `Async::GRPC::Compatible::SharedChannel.close` to close the current thread's shared clients, for example when a worker thread shuts down; later calls open new clients. To give a stub a connection pool of its own, which `close` releases, set grpc's local subchannel pool argument:
+
+``` ruby
+stub = Async::GRPC::Compatible::ClientStub.new(
+	"grpc.example.com:443", IO::Endpoint::TLS::Configuration.new,
+	channel_args: {"grpc.use_local_subchannel_pool" => 1}
+)
+```
+
+Pass `channel_override:` (or `channel:` to `GapicServiceStub`) to control connection reuse explicitly. The caller owns a channel supplied this way. Shared channels are built from the target URL and TLS configuration alone, so subclasses which override `ClientStub.endpoint_for`, for example to connect through a custom transport, only take effect with a local subchannel pool; alternatively, pass `channel_override: Async::GRPC::Compatible::Channel.new(endpoint)`.
+
+## Operations and credentials
+
+Pass `return_op: true` to defer a unary call until `operation.execute`. An operation executes once and exposes `deadline`, `metadata`, `trailing_metadata`, `status`, `cancel`, and `cancelled?`. The deadline includes time spent waiting to execute. Cancel an active operation from the same Async reactor; cancelling it closes that call without closing a shared channel. Calling `cancel` after completion has no effect.
+
+Supply `call_credentials:` to the constructor for a default authentication callback, or `credentials:` to `request_response` for a per-call callback. Objects exposing `updater_proc`, such as Google authentication credentials, are also accepted. Callbacks run at execution time on every call, so token refreshes are used.
+
+Each callback receives a fresh authentication context containing `:jwt_aud_uri`, for example `https://grpc.example.com/example.Service`. The audience uses the actual channel's endpoint and RPC service path. Return a hash of authentication headers, or `nil` to add none. Returned headers are merged into a copy of the caller's metadata; per-call credentials run after constructor credentials. The audience context is never sent as a header.
+
+Authentication callbacks require a TLS channel with a known endpoint. A shared `Async::GRPC::Client` supplies its endpoint through its HTTP delegate; for a custom client, supply the endpoint explicitly when constructing `Compatible::Channel.new(endpoint, client: client)`.
+
+``` ruby
+stub = Async::GRPC::Compatible::ClientStub.new(
+	"grpc.example.com:443",
+	IO::Endpoint::TLS::Configuration.new,
+	call_credentials: credentials.updater_proc
+)
+```
+
+Passing an authentication callback as the constructor's second argument creates a default TLS channel with peer and hostname verification. For custom trust roots or mutual TLS, provide the TLS configuration separately:
+
+``` ruby
+tls = IO::Endpoint::TLS::Configuration.new(
+	trust_store: IO::Endpoint::TLS::TrustStore.load("ca.pem"),
+	certificate_chain: IO::Endpoint::TLS::Certificates.parse(File.read("client-chain.pem")),
+	private_key: File.read("client-key.pem")
+)
+
+stub = Async::GRPC::Compatible::ClientStub.new(
+	"grpc.example.com:443", tls,
+	call_credentials: credentials.updater_proc
+)
+```
+
+TLS channels verify peers and hostnames by default, including localhost. An explicit URL must match the selected transport: TLS credentials require `https://`, and `:this_channel_is_insecure` requires `http://`.
+
+### gRPC TLS configuration
+
+`Async::GRPC::Compatible::ChannelCredentials.new` accepts the same three optional positional PEM arguments as `GRPC::Core::ChannelCredentials.new` and returns an `IO::Endpoint::TLS::Configuration` directly:
+
+| gRPC constructor argument | TLS configuration |
+| --- | --- |
+| Root certificates | `trust_store`, containing only the supplied roots |
+| Client private key | `private_key` |
+| Client certificate chain | `certificate_chain`, split into individual certificates in the supplied order |
+
+``` ruby
+tls = Async::GRPC::Compatible::ChannelCredentials.new(
+	File.read("ca.pem"),
+	File.read("client-key.pem"),
+	File.read("client-chain.pem")
+)
+
+stub = Async::GRPC::Compatible::ClientStub.new("grpc.example.com:443", tls)
+```
+
+Use `ChannelCredentials.new` for the transport's default trust store, or `ChannelCredentials.new(root_pem)` for custom roots without a client identity. The client key and certificate chain must be supplied together. Peer and hostname verification are always enabled by this mapping. gRPC-specific default-root overrides are not read; supply those roots explicitly.
+
+Pass the returned TLS configuration to `ClientStub` or `GapicServiceStub` at construction. Existing native credential objects cannot be converted through Ruby's public API, so retain the PEM inputs at that boundary. Supply Ruby authentication callbacks separately using `call_credentials:` on `ClientStub`.
+
+## GAPIC and generated Google clients
+
+Require the optional adapter after installing your Google client gem (which provides `gapic-common`). `GapicServiceStub` accepts the generated service definition and preserves the original credential updater before GAPIC wraps it in native credentials. Its `call_rpc` path retains GAPIC's retry policies and yields the completed operation to the caller.
+
+``` ruby
+require "google/cloud/kms/v1"
+require "google/cloud/kms/v1/service_services_pb"
+require "async/grpc/compatible/gapic"
+
+credentials = Google::Auth.get_application_default(
+	["https://www.googleapis.com/auth/cloud-platform"]
+)
+
+Sync do
+	service = Async::GRPC::Compatible::GapicServiceStub.new(
+		Google::Cloud::Kms::V1::KeyManagementService::Service,
+		endpoint: "cloudkms.googleapis.com",
+		credentials: credentials
+	)
+	
+	begin
+		request = Google::Cloud::Kms::V1::EncryptRequest.new(
+			name: "projects/my-project/locations/global/keyRings/my-ring/cryptoKeys/my-key",
+			plaintext: "hello"
+		)
+		response = service.call_rpc(:encrypt, request, options: {timeout: 5}) do |response, operation|
+			puts operation.status.code
+		end
+		puts response.ciphertext.bytesize
+	ensure
+		service.close
+	end
+end
+```
+
+Without `channel:`, adapters share connections as described in [Connection sharing](#connection-sharing). For an existing Async connection pool, pass `channel:` to the adapter. The caller owns that channel. GAPIC native channel pools are unsupported because Async::HTTP already manages connections.
+
+Generated high-level Google clients construct `Gapic::ServiceStub` inside their constructors. Applications adapting those constructors can use `GapicServiceStub.new(Service, credentials: original_credentials, ...)` at that construction point. The adapter can also be called directly, as above, without replacing global GRPC constants. Keep the original Ruby credentials available at this boundary; credentials already composed into `GRPC::Core::ChannelCredentials` cannot be recovered.
+
+For generated services without GAPIC, use `ClientStub.for(Service)` to construct a stub class with unary RPC methods. Streaming methods raise `NotImplementedError`. This adapter supports the operation methods listed above; native operation controls such as `start_call`, `wait`, and write flags are not implemented.
+
+## Development
+
+Run the test suite:
+
+``` shell
+$ bundle exec sus
+```
+
+The integration suite includes a unary client fixture generated by
+NuevoProtobuf 2.5.4 and exercises it against an in-process Async HTTP/2 server.
+
+## Releases
+
+Please see the [project releases](https://socketry.github.io/async-grpc-compatible/releases/index) for all releases.
+
+### v0.1.0
+
+  - Send `application/grpc` and use shared metadata decoding, including unpadded binary metadata.
+  - Map invalid HTTP responses to grpc-ruby errors, preserving the native `ResponseError` and its buffered response as the cause.
+  - Support deferred unary operations with execution, cancellation, deadline, status, and response metadata access.
+  - Support Ruby authentication callbacks at stub construction and per call, evaluated on each execution with the service's JWT audience and merged into request metadata.
+  - Support custom trust roots and mutual TLS through `IO::Endpoint::TLS::Configuration`. Reject opaque native credentials, conflicting target schemes, and authentication callbacks on plaintext channels.
+  - Map grpc-ruby's TLS constructor arguments with `Compatible::ChannelCredentials.new(root_certificates, private_key, certificate_chain)`, returning an `IO::Endpoint::TLS::Configuration` with custom roots, client certificate chains, and peer verification enabled.
+  - Add `ClientStub.for(service)` and the optional `GapicServiceStub` adapter for generated services and GAPIC clients.
+  - Map transport failures to grpc-ruby errors, preserving the original exception as the cause. Connection, DNS, TLS, and HTTP/2 connection failures become `GRPC::Unavailable`, and HTTP/2 stream resets use gRPC's HTTP/2 status mapping.
+  - Share connections between stubs for the same target and TLS configuration on each thread, like grpc-core's global subchannel pool. Closing a stub leaves shared clients open; use `SharedChannel.close` to close the current thread's shared clients, or set `grpc.use_local_subchannel_pool` for a stub-owned connection pool.
+
+### v0.0.0
+
+  - Initial implementation of an Async-backed `GRPC::ClientStub` compatible unary client.
+
+## License
+
+Released under the MIT License.

data/releases.md

@@ -0,0 +1,17 @@
+# Releases
+
+## v0.1.0
+
+  - Send `application/grpc` and use shared metadata decoding, including unpadded binary metadata.
+  - Map invalid HTTP responses to grpc-ruby errors, preserving the native `ResponseError` and its buffered response as the cause.
+  - Support deferred unary operations with execution, cancellation, deadline, status, and response metadata access.
+  - Support Ruby authentication callbacks at stub construction and per call, evaluated on each execution with the service's JWT audience and merged into request metadata.
+  - Support custom trust roots and mutual TLS through `IO::Endpoint::TLS::Configuration`. Reject opaque native credentials, conflicting target schemes, and authentication callbacks on plaintext channels.
+  - Map grpc-ruby's TLS constructor arguments with `Compatible::ChannelCredentials.new(root_certificates, private_key, certificate_chain)`, returning an `IO::Endpoint::TLS::Configuration` with custom roots, client certificate chains, and peer verification enabled.
+  - Add `ClientStub.for(service)` and the optional `GapicServiceStub` adapter for generated services and GAPIC clients.
+  - Map transport failures to grpc-ruby errors, preserving the original exception as the cause. Connection, DNS, TLS, and HTTP/2 connection failures become `GRPC::Unavailable`, and HTTP/2 stream resets use gRPC's HTTP/2 status mapping.
+  - Share connections between stubs for the same target and TLS configuration on each thread, like grpc-core's global subchannel pool. Closing a stub leaves shared clients open; use `SharedChannel.close` to close the current thread's shared clients, or set `grpc.use_local_subchannel_pool` for a stub-owned connection pool.
+
+## v0.0.0
+
+  - Initial implementation of an Async-backed `GRPC::ClientStub` compatible unary client.

metadata

@@ -0,0 +1,118 @@
+--- !ruby/object:Gem::Specification
+name: async-grpc-compatible
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Samuel Williams
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: async-grpc
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.10'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.10'
+- !ruby/object:Gem::Dependency
+  name: async-http
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.100'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.100'
+- !ruby/object:Gem::Dependency
+  name: grpc
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: io-endpoint
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.19'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.19'
+- !ruby/object:Gem::Dependency
+  name: protocol-grpc
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.17'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.17'
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/async/grpc/compatible.rb
+- lib/async/grpc/compatible/channel_credentials.rb
+- lib/async/grpc/compatible/client_stub.rb
+- lib/async/grpc/compatible/gapic.rb
+- lib/async/grpc/compatible/operation.rb
+- lib/async/grpc/compatible/version.rb
+- license.md
+- readme.md
+- releases.md
+homepage: https://github.com/socketry/async-grpc-compatible
+licenses:
+- MIT
+metadata:
+  documentation_uri: https://socketry.github.io/async-grpc-compatible/
+  source_code_uri: https://github.com/socketry/async-grpc-compatible.git
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.16
+specification_version: 4
+summary: grpc-ruby compatible client interfaces using Async::GRPC.
+test_files: []