async-grpc 0.1.0

data/readme.md

@@ -0,0 +1,52 @@
+# Async::GRPC
+
+Asynchronous gRPC client and server implementation built on top of `protocol-grpc` and `async-http`.
+
+[![Development Status](https://github.com/socketry/async-grpc/workflows/Test/badge.svg)](https://github.com/socketry/async-grpc/actions?workflow=Test)
+
+## Features
+
+`async-grpc` provides asynchronous networking and concurrency for gRPC:
+
+  - **Asynchronous client** - Wraps `Async::HTTP::Client` to provide gRPC-specific call methods with automatic message framing and status handling.
+  - **Method-based stubs** - Create type-safe stubs from `Protocol::GRPC::Interface` definitions. Accepts both PascalCase and snake\_case method names for convenience.
+  - **Server middleware** - `DispatcherMiddleware` routes requests to registered services based on path.
+  - **All RPC patterns** - Supports unary, server streaming, client streaming, and bidirectional streaming RPCs.
+  - **Interface-based services** - Define services using `Protocol::GRPC::Interface` with automatic PascalCase to snake\_case method name conversion for Ruby implementations.
+  - **HTTP/2 transport** - Built on `async-http` with automatic HTTP/2 multiplexing and connection pooling.
+
+## Usage
+
+Please see the [project documentation](https://socketry.github.io/async-grpc/) for more details.
+
+  - [Getting Started](https://socketry.github.io/async-grpc/guides/getting-started/index) - This guide explains how to get started with `Async::GRPC` for building gRPC clients and servers.
+
+## Releases
+
+Please see the [project releases](https://socketry.github.io/async-grpc/releases/index) for all releases.
+
+### v0.1.0
+
+## See Also
+
+  - [protocol-grpc](https://github.com/socketry/protocol-grpc) — Protocol abstractions for gRPC that this gem builds upon.
+  - [async-http](https://github.com/socketry/async-http) — Asynchronous HTTP client and server with HTTP/2 support.
+  - [protocol-http](https://github.com/socketry/protocol-http) — HTTP protocol abstractions.
+
+## Contributing
+
+We welcome contributions to this project.
+
+1.  Fork it.
+2.  Create your feature branch (`git checkout -b my-new-feature`).
+3.  Commit your changes (`git commit -am 'Add some feature'`).
+4.  Push to the branch (`git push origin my-new-feature`).
+5.  Create new Pull Request.
+
+### Developer Certificate of Origin
+
+In order to protect users of this project, we require all contributors to comply with the [Developer Certificate of Origin](https://developercertificate.org/). This ensures that all contributions are properly licensed and attributed.
+
+### Community Guidelines
+
+This project is best served by a collaborative and respectful environment. Treat each other professionally, respect differing viewpoints, and engage constructively. Harassment, discrimination, or harmful behavior is not tolerated. Communicate clearly, listen actively, and support one another. If any issues arise, please inform the project maintainers.

data/releases.md

@@ -0,0 +1,3 @@
+# Releases
+
+## v0.1.0

data/spanner_integration.md

@@ -0,0 +1,309 @@
+# Integrating async-grpc with Google Cloud Spanner
+
+## Current State Analysis
+
+### How ruby-spanner Uses gRPC
+
+Looking at `google-cloud-spanner/lib/google/cloud/spanner/service.rb`:
+
+```ruby
+def channel
+	require "grpc"
+	GRPC::Core::Channel.new host, chan_args, chan_creds
+end
+
+def chan_creds
+	return credentials if insecure?
+	require "grpc"
+	GRPC::Core::ChannelCredentials.new.compose \
+		GRPC::Core::CallCredentials.new credentials.client.updater_proc
+end
+
+def service
+	return mocked_service if mocked_service
+	@service ||=
+		V1::Spanner::Client.new do |config|
+			config.credentials = channel  # <-- Passes gRPC channel
+			config.quota_project = @quota_project
+			config.timeout = timeout if timeout
+			config.endpoint = host if host
+			config.universe_domain = @universe_domain
+			config.lib_name = lib_name_with_prefix
+			config.lib_version = Google::Cloud::Spanner::VERSION
+			config.metadata = { "google-cloud-resource-prefix" => "projects/#{@project}" }
+		end
+end
+```
+
+### Key Dependencies
+
+1. **gRPC C Extension** (`grpc` gem)
+   - `GRPC::Core::Channel` - connection management
+   - `GRPC::Core::ChannelCredentials` - TLS/SSL setup
+   - `GRPC::Core::CallCredentials` - per-call auth (OAuth2 tokens)
+
+2. **Generated Client Stubs** (from `google-cloud-spanner-v1` gem)
+   - `Google::Cloud::Spanner::V1::Spanner::Client`
+   - Generated by `protoc` with `grpc` plugin
+   - Expects a gRPC channel as credentials
+
+## Replacement Strategy
+
+### Option 1: Drop-In Channel Replacement (Most Feasible)
+
+Create an adapter that implements the `GRPC::Core::Channel` interface:
+
+```ruby
+module Async
+	module GRPC
+		# Adapter that makes Async::GRPC::Client compatible with
+		# Google's generated gRPC client stubs
+		class ChannelAdapter
+			def initialize(endpoint, channel_args = {}, channel_creds = nil)
+				@endpoint = endpoint
+				@client = Async::GRPC::Client.new(endpoint)
+				@channel_creds = channel_creds
+			end
+			
+			# Called by generated stubs to make RPC calls
+			# Must implement the gRPC::Core::Channel interface
+			def request_response(path, request, marshal, unmarshal, deadline: nil, metadata: {})
+				# Parse service/method from path
+				# path format: "/google.spanner.v1.Spanner/ExecuteStreamingSql"
+				parts = path.split("/").last(2)
+				service = parts[0].split(".").last
+				method = parts[1]
+				
+				# Add auth metadata
+				if @channel_creds
+					auth_metadata = @channel_creds.call(method)
+					metadata.merge!(auth_metadata)
+				end
+				
+				# Marshal request
+				request_data = marshal.call(request)
+				
+				# Make the call
+				response_data = Async do
+					@client.unary(
+						service,
+						method,
+						request_data,
+						metadata: metadata,
+						timeout: deadline
+					)
+				end.wait
+				
+				# Unmarshal response
+				unmarshal.call(response_data)
+			end
+			
+			# For server-streaming RPCs
+			def request_stream(path, request, marshal, unmarshal, deadline: nil, metadata: {})
+				# Similar but returns enumerator
+				Enumerator.new do |yielder|
+					Async do
+						@client.server_streaming do |response_data|
+							yielder << unmarshal.call(response_data)
+						end
+					end.wait
+				end
+			end
+			
+			# For client-streaming RPCs
+			def stream_request(path, marshal, unmarshal, deadline: nil, metadata: {})
+				# Returns [input_stream, output_future]
+			end
+			
+			# For bidirectional streaming RPCs
+			def stream_stream(path, marshal, unmarshal, deadline: nil, metadata: {})
+				# Returns [input_stream, output_enumerator]
+			end
+			
+			def close
+				@client.close
+			end
+		end
+	end
+end
+```
+
+### Option 2: Regenerate Client Stubs (More Invasive)
+
+Instead of using Google's generated stubs, regenerate them with our own generator:
+
+```bash
+# Generate Spanner service stubs using protocol-grpc
+bake protocol:grpc:generate google/spanner/v1/spanner.proto
+
+# This would generate:
+# - lib/google/spanner/v1/spanner_grpc.rb (client stubs)
+# - Compatible with Async::GRPC::Client
+```
+
+Then modify `service.rb`:
+
+```ruby
+require "google/spanner/v1/spanner_grpc"  # Our generated stubs
+
+def service
+	@service ||= begin
+		endpoint = Async::HTTP::Endpoint.parse("https://#{host}")
+		client = Async::GRPC::Client.new(endpoint)
+		
+		Google::Spanner::V1::SpannerClient.new(client)  # Our stub
+	end
+end
+```
+
+### Option 3: Monkey-Patch Mock Interface (Testing/Development Only)
+
+Use Spanner's built-in mocking capability:
+
+```ruby
+# In service.rb
+attr_accessor :mocked_service  # Already exists!
+
+# Our replacement
+class AsyncGRPCSpannerService
+	def initialize(client)
+		@client = client
+	end
+	
+	# Implement all Spanner RPC methods
+	def execute_streaming_sql(request, options = {})
+		# Call via async-grpc
+	end
+	
+	def begin_transaction(request, options = {})
+		# ...
+	end
+	
+	# ... implement all 20+ RPC methods
+end
+
+# Usage
+service = Google::Cloud::Spanner::Service.new
+service.mocked_service = AsyncGRPCSpannerService.new(async_grpc_client)
+```
+
+## Required Interface
+
+To make this work, `Async::GRPC::Client` would need to support:
+
+### 1. Raw Binary Messages
+
+```ruby
+# Currently: pass protobuf objects
+client.unary(service, method, request_object, response_class: MyReply)
+
+# Need to support: pass raw binary
+client.unary_binary(service, method, request_binary) # => response_binary
+```
+
+### 2. Marshal/Unmarshal Callbacks
+
+```ruby
+client.unary(
+		service,
+		method,
+		request,
+		marshal: ->(obj){obj.to_proto},
+		unmarshal: ->(data){MyReply.decode(data)}
+)
+```
+
+### 3. Compatible Metadata/Headers
+
+Google's stubs expect specific metadata format (OAuth2 tokens, quota project, etc.)
+
+## Recommendation
+
+**Option 1 (Channel Adapter) is most feasible** because:
+
+1. ✅ No need to regenerate all Google API stubs
+2. ✅ Works with existing `google-cloud-spanner-v1` gem
+3. ✅ Minimal changes to Spanner gem
+4. ✅ Can be done incrementally (test with one RPC at a time)
+5. ✅ Falls back to standard gRPC if issues arise
+
+## Implementation Plan
+
+### Phase 1: Proof of Concept
+
+1. Implement `Async::GRPC::ChannelAdapter`
+2. Test with simple unary RPC (e.g., `CreateSession`)
+3. Verify it works end-to-end
+
+### Phase 2: Full Interface
+
+1. Implement all four RPC types (unary, client streaming, server streaming, bidirectional)
+2. Handle auth metadata properly
+3. Support deadlines and cancellation
+
+### Phase 3: Production Ready
+
+1. Handle all gRPC edge cases
+2. Proper error mapping
+3. Connection pooling
+4. Performance testing
+
+## Challenges
+
+### 1. Generated Stub Format
+
+Google's generated stubs use Gapic (Google API Client) framework, which has its own conventions. We'd need to understand:
+- Exact method signatures expected
+- How streaming responses are yielded
+- Error handling patterns
+
+### 2. Authentication
+
+Google Cloud uses:
+- OAuth2 access tokens (refreshed automatically)
+- Per-RPC credentials (added as metadata)
+- Service account key files
+
+Our adapter must support this auth flow.
+
+### 3. Retry Logic
+
+Google's client has sophisticated retry logic:
+- Exponential backoff
+- Per-method retry policies
+- Idempotency detection
+
+We'd need to preserve this behavior.
+
+### 4. Observability
+
+Google's clients have built-in:
+- OpenTelemetry tracing
+- Metrics/logging
+- Quota tracking
+
+## Next Steps
+
+1. **Investigate Gapic internals**: Look at how `google-cloud-spanner-v1` generated code works
+2. **Find hook points**: Identify where we can inject our channel
+3. **Build minimal adapter**: Implement just enough to make one RPC work
+4. **Benchmark**: Compare performance async-grpc vs standard gRPC
+
+## Benefits if Successful
+
+- ✅ Pure Ruby implementation (no C extension)
+- ✅ Async-first design (better concurrency)
+- ✅ Easier debugging (no C stack traces)
+- ✅ Potentially better resource usage
+- ✅ Could work on platforms where C extensions are problematic (e.g., JRuby, TruffleRuby)
+
+## Risks
+
+- ❌ Incomplete gRPC protocol implementation
+- ❌ Performance might be worse than C extension
+- ❌ Maintenance burden (keep up with gRPC spec changes)
+- ❌ Edge cases we haven't thought of
+
+
+
+

metadata

@@ -0,0 +1,81 @@
+--- !ruby/object:Gem::Specification
+name: async-grpc
+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-http
+  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: protocol-grpc
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- code.md
+- context/getting-started.md
+- context/index.yaml
+- design.md
+- lib/async/grpc.rb
+- lib/async/grpc/client.rb
+- lib/async/grpc/dispatcher_middleware.rb
+- lib/async/grpc/service.rb
+- lib/async/grpc/stub.rb
+- lib/async/grpc/version.rb
+- license.md
+- readme.md
+- releases.md
+- spanner_integration.md
+homepage: https://github.com/socketry/async-grpc
+licenses:
+- MIT
+metadata:
+  documentation_uri: https://socketry.github.io/async-grpc/
+  source_code_uri: https://github.com/socketry/async-grpc.git
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Client and server implementation for gRPC using Async.
+test_files: []