async-grpc 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 13df5d80dfc403580a0b3efa15de081d71f285901a5f082bacb7cb840b23f66f
-  data.tar.gz: 59f811ca32b0beac56192f587be2e3184279c5d9160891b9b931b20229473033
+  metadata.gz: 2b2db42e03f75834e2259977d953d8c1688949e3c45c3ca972f9a9a0c6ca23b9
+  data.tar.gz: 1f7ce2103876bcb8fe0d716595668bee4904e1d2f35d0cb5ac86b246f84fd2e0
 SHA512:
-  metadata.gz: 2d85ab093902e64a2ea3877f788eeac19bd6ae005bf47d3ddfa52831d0fa8193255f6ae0158b7bbb6897f4f5cdd39935cf03d7b14b9139da8257ffef07e1258e
-  data.tar.gz: ee29fe46cf81d22298c94c5cb63b17a4783e4159f6110f70efc91444d507f47aec2bf14346d7e6187b9b40bee3f18a1e38c511afc0250c3f2fadbf88790495b7
+  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

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}

@@ -5,10 +5,18 @@
 
 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/version.rb

@@ -7,7 +7,7 @@
 module Async
 	# @namespace
 	module GRPC
-		VERSION = "0.7.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.

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.7.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
@@ -58,14 +72,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.11.0
+        version: 0.12.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.11.0
+        version: 0.12.0
 - !ruby/object:Gem::Dependency
   name: protocol-http
   requirement: !ruby/object:Gem::Requirement
@@ -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