async-grpc 0.6.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ea5b102766838b1d027771084f9696707e1cbf5dac9fdee9004daf4724b5a318
-  data.tar.gz: 105255db3b068be3a28f0234e1ce77600d5780a7220a15e848eb6ad9e855ddb2
+  metadata.gz: 2b2db42e03f75834e2259977d953d8c1688949e3c45c3ca972f9a9a0c6ca23b9
+  data.tar.gz: 1f7ce2103876bcb8fe0d716595668bee4904e1d2f35d0cb5ac86b246f84fd2e0
 SHA512:
-  metadata.gz: 7ff58e16e452b3c37ce7c4a8ded6ed7381580f1d2a8b046d644b3449b1b5d0df791f3463acb6fcfd8168d8a9c53cb094cc40988c82afded2478d9b58a5059499
-  data.tar.gz: 7b9e4e143f778688971dbee371c1e6ebfc049ad002dd942d570e19570880336c18a36a30e681692e267d561fda48f0b1060813efe951625b76e2a1fc51dd1f49
+  metadata.gz: 61cfba13b45b83a390b41e2ede94ad6bf81286f3273630d8bc8336103e40d888fbb0d0c74f1f54c04c44d37a19fa493fcb0cf29e096388d855ff3b7fb626d187
+  data.tar.gz: 46dc51138f257f1768ddef3d81b42d1c040a53812a9970bd8bb7fee60a94a6e0d16f210069faa4c6b484f58994070f1e9ad04459685f57932fa89db40eb5bf8c

data/lib/async/grpc/client.rb

@@ -16,7 +16,7 @@ require "protocol/grpc/body/writable_body"
 require "protocol/grpc/metadata"
 require "protocol/grpc/error"
 require_relative "stub"
-require_relative "remote_error"
+require_relative "error"
 
 module Async
 	module GRPC
@@ -113,11 +113,12 @@ module Async
 			# @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 | Nil] 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 for streaming
 			# @raises [ArgumentError] If method is unknown or streaming type is invalid
 			# @raises [Protocol::GRPC::Error] If the gRPC call fails
-			def invoke(service, method, request = nil, metadata: {}, timeout: nil, encoding: nil, &block)
+			def invoke(service, method, request = nil, metadata: {}, timeout: nil, encoding: nil, initial: nil, &block)
 				rpc = service.class.lookup_rpc(method)
 				raise ArgumentError, "Unknown method: #{method}" unless rpc
 				
@@ -141,7 +142,7 @@ module Async
 				when :client_streaming
 					client_streaming_call(path, headers, request_class, response_class, encoding, &block)
 				when :bidirectional
-					bidirectional_call(path, headers, request_class, response_class, encoding, &block)
+					bidirectional_call(path, headers, request_class, response_class, encoding, initial: initial, &block)
 				else
 					raise ArgumentError, "Unknown streaming type: #{streaming}"
 				end
@@ -273,14 +274,16 @@ module Async
 			# @parameter request_class [Class] Request message class
 			# @parameter response_class [Class] Response message class
 			# @parameter encoding [String | Nil] Compression encoding
+			# @parameter initial [Object | Array | Nil] Optional initial message(s) to write before waiting for the response
 			# @yields {|input, output| ...} Block to handle bidirectional streaming
 			# @returns [Protocol::GRPC::Body::ReadableBody] Readable body for streaming messages
 			# @raises [Protocol::GRPC::Error] If the gRPC call fails
-			def bidirectional_call(path, headers, request_class, response_class, encoding, &block)
+			def bidirectional_call(path, headers, request_class, response_class, encoding, initial: nil, &block)
 				body = Protocol::GRPC::Body::WritableBody.new(
 					encoding: encoding,
 					message_class: request_class
 				)
+				Array(initial).each{|message| body.write(message)}
 				
 				http_request = Protocol::HTTP::Request["POST", path, headers, body]
 				response = call(http_request)

data/lib/async/grpc/dispatcher.rb

@@ -4,7 +4,8 @@
 # Copyright, 2025-2026, by Samuel Williams.
 
 require "async"
-require "async/deadline"
+
+require_relative "error"
 
 require "protocol/grpc/middleware"
 require "protocol/grpc/methods"
@@ -44,6 +45,25 @@ module Async
 			
 			protected
 			
+			# Invoke a service handler, providing a protected extension point for middleware and instrumentation around service execution.
+			#
+			# Override this method to observe service outcomes, establish request context, or wrap handlers with application middleware. Overrides should call `super` to invoke the handler and preserve the dispatcher's stream cleanup, trailer handling, and successful status assignment.
+			#
+			# This hook only surrounds service handler execution. Errors raised earlier while routing or preparing the request do not pass through it. A call deadline that expires during service execution raises {DeadlineExceededError} through this hook before the dispatcher converts it to a `DEADLINE_EXCEEDED` response.
+			#
+			# @parameter service [Async::GRPC::Service] The service containing the handler.
+			# @parameter handler_method [Symbol] The service method to invoke.
+			# @parameter input [Protocol::GRPC::Body::ReadableBody] The decoded request stream.
+			# @parameter output [Protocol::GRPC::Body::WritableBody] The response stream.
+			# @parameter call [Protocol::GRPC::Call] The call context.
+			# @returns [Object | Nil] An internal dispatch result with no stable application-facing contract.
+			# @example Wrap service execution with application middleware
+			# 	def invoke_service(service, handler_method, input, output, call)
+			# 		context = RequestContext.new(call.request)
+			# 		middleware.call(context) do
+			# 			super
+			# 		end
+			# 	end
 			def invoke_service(service, handler_method, input, output, call)
 				begin
 					service.send(handler_method, input, output, call)
@@ -69,15 +89,15 @@ module Async
 				end
 			end
 			
-			def dispatch_to_service(service, handler_method, input, output, call, deadline, parent: Async::Task.current)
-				if deadline
-					parent.with_timeout(deadline.remaining) do
+			def dispatch_to_service(service, handler_method, input, output, call, parent: Async::Task.current)
+				if deadline = call.deadline
+					parent.with_timeout(deadline.remaining, DeadlineExceededError) do
 						invoke_service(service, handler_method, input, output, call)
 					end
 				else
 					invoke_service(service, handler_method, input, output, call)
 				end
-			rescue Async::TimeoutError => error
+			rescue DeadlineExceededError => error
 				# Close input and output streams:
 				input.close
 				output.close_write unless output.closed?
@@ -135,22 +155,16 @@ module Async
 				# Create response object:
 				response = Protocol::HTTP::Response[200, response_headers, output]
 				
-				# Parse deadline from timeout header:
-				timeout = Protocol::GRPC::Methods.parse_timeout(request.headers["grpc-timeout"])
-				deadline = if timeout
-					Async::Deadline.start(timeout)
-				end
-				
-				# Create call context with request and response:
-				call = Protocol::GRPC::Call.new(request, response, deadline: deadline)
+				# Create call context with request, response and deadline:
+				call = Protocol::GRPC::Call.for(request, response)
 				
 				if rpc_descriptor.streaming?
 					Async do |task|
-						dispatch_to_service(service, handler_method, input, output, call, deadline, parent: task)
+						dispatch_to_service(service, handler_method, input, output, call, parent: task)
 					end
 				else
 					# Unary call:
-					dispatch_to_service(service, handler_method, input, output, call, deadline)
+					dispatch_to_service(service, handler_method, input, output, call)
 				end
 				
 				return response

data/lib/async/grpc/{remote_error.rb → error.rb}

@@ -1,14 +1,22 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2025, by Samuel Williams.
+# Copyright, 2025-2026, by Samuel Williams.
 
 module Async
 	module GRPC
+		# Represents a generic async gRPC error.
+		class Error < StandardError
+		end
+		
+		# Raised when a gRPC call exceeds its deadline.
+		class DeadlineExceededError < Error
+		end
+		
 		# Represents an error that originated from a remote gRPC server.
 		# Used as the `cause` of {Protocol::GRPC::Error} when the client receives a non-OK status.
 		# The message and optional backtrace are extracted from response metadata.
-		class RemoteError < StandardError
+		class RemoteError < Error
 			# Create a RemoteError from server response metadata.
 			# @parameter message [String | Nil] The error message from `grpc-message` header.
 			# @parameter metadata [Hash] Response metadata (extracted from gRPC headers). If it contains a `"backtrace"` key (array of strings), it is set on the error and removed from the hash.

data/lib/async/grpc/stub.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2025, by Samuel Williams.
+# Copyright, 2025-2026, by Samuel Williams.
 
 require "protocol/grpc/interface"
 
@@ -36,7 +36,7 @@ module Async
 			# Uses snake_case method names (Ruby convention).
 			# @parameter method_name [Symbol] The method name to call (snake_case)
 			# @parameter args [Array] Positional arguments (first is the request message)
-			# @parameter options [Hash] Keyword arguments (metadata, timeout, encoding)
+			# @parameter options [Hash] Keyword arguments (metadata, timeout, encoding, initial)
 			# @yields {|input, output| ...} Block for streaming calls
 			# @returns [Object | Protocol::GRPC::Body::ReadableBody] Response message or readable body
 			# @raises [NoMethodError] If the method is not found
@@ -47,13 +47,14 @@ module Async
 					# Extract request from args (first positional argument):
 					request = args.first
 					
-					# Extract metadata, timeout, encoding from options:
+					# Extract metadata, timeout, encoding and initial messages from options:
 					metadata = options.delete(:metadata) || {}
 					timeout = options.delete(:timeout)
 					encoding = options.delete(:encoding)
+					initial = options.delete(:initial)
 					
 					# Delegate to client.invoke with PascalCase method name (for interface lookup):
-					@client.invoke(@interface, interface_method_name, request, metadata: metadata, timeout: timeout, encoding: encoding, &block)
+					@client.invoke(@interface, interface_method_name, request, metadata: metadata, timeout: timeout, encoding: encoding, initial: initial, &block)
 				else
 					super
 				end

data/lib/async/grpc/version.rb

@@ -7,7 +7,7 @@
 module Async
 	# @namespace
 	module GRPC
-		VERSION = "0.6.0"
+		VERSION = "0.8.0"
 	end
 end
 

data/lib/async/grpc.rb

@@ -4,6 +4,7 @@
 # Copyright, 2025, by Samuel Williams.
 
 require_relative "grpc/version"
+require_relative "grpc/error"
 require_relative "grpc/client"
 require_relative "grpc/service"
 require_relative "grpc/stub"

data/readme.md

@@ -24,6 +24,10 @@ Please see the [project documentation](https://socketry.github.io/async-grpc/) f
 
 Please see the [project releases](https://socketry.github.io/async-grpc/releases/index) for all releases.
 
+### v0.8.0
+
+  - Added `Async::GRPC::Error` as the base class for async gRPC errors, including `RemoteError` and the new `DeadlineExceededError` used to distinguish call deadline expiry from unrelated `Async::TimeoutError` failures.
+
 ### v0.6.0
 
   - Ensure `grpc-status` (and related metadata) is sent as a trailer, if data frames are written.
@@ -72,6 +76,22 @@ We welcome contributions to this project.
 4.  Push to the branch (`git push origin my-new-feature`).
 5.  Create new Pull Request.
 
+### Running Tests
+
+To run the test suite:
+
+``` shell
+bundle exec sus
+```
+
+### Making Releases
+
+To make a new release:
+
+``` shell
+bundle exec bake gem:release:patch # or minor or major
+```
+
 ### 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.

data/releases.md

@@ -1,5 +1,9 @@
 # Releases
 
+## v0.8.0
+
+  - Added `Async::GRPC::Error` as the base class for async gRPC errors, including `RemoteError` and the new `DeadlineExceededError` used to distinguish call deadline expiry from unrelated `Async::TimeoutError` failures.
+
 ## v0.6.0
 
   - Ensure `grpc-status` (and related metadata) is sent as a trailer, if data frames are written.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: async-grpc
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.8.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -38,6 +38,20 @@ cert_chain:
   -----END CERTIFICATE-----
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: async
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.38.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.38.0
 - !ruby/object:Gem::Dependency
   name: async-http
   requirement: !ruby/object:Gem::Requirement
@@ -53,33 +67,33 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: protocol-http
+  name: protocol-grpc
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.60'
+        version: 0.12.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.60'
+        version: 0.12.0
 - !ruby/object:Gem::Dependency
-  name: protocol-grpc
+  name: protocol-http
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.11.0
+        version: '0.60'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.11.0
+        version: '0.60'
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -90,7 +104,7 @@ files:
 - lib/async/grpc.rb
 - lib/async/grpc/client.rb
 - lib/async/grpc/dispatcher.rb
-- lib/async/grpc/remote_error.rb
+- lib/async/grpc/error.rb
 - lib/async/grpc/service.rb
 - lib/async/grpc/stub.rb
 - lib/async/grpc/version.rb
@@ -118,7 +132,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.3
+rubygems_version: 4.0.10
 specification_version: 4
 summary: Client and server implementation for gRPC using Async.
 test_files: []