async-grpc 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2b2db42e03f75834e2259977d953d8c1688949e3c45c3ca972f9a9a0c6ca23b9
-  data.tar.gz: 1f7ce2103876bcb8fe0d716595668bee4904e1d2f35d0cb5ac86b246f84fd2e0
+  metadata.gz: 031cde64ff322b5e4d247cec205cdbe17219d455240866df154fca3f370e675c
+  data.tar.gz: d926dbe26788e37bbcb219cce9224c40f5c282bb0ed84c42fcbb6118472da69f
 SHA512:
-  metadata.gz: 61cfba13b45b83a390b41e2ede94ad6bf81286f3273630d8bc8336103e40d888fbb0d0c74f1f54c04c44d37a19fa493fcb0cf29e096388d855ff3b7fb626d187
-  data.tar.gz: 46dc51138f257f1768ddef3d81b42d1c040a53812a9970bd8bb7fee60a94a6e0d16f210069faa4c6b484f58994070f1e9ad04459685f57932fa89db40eb5bf8c
+  metadata.gz: 5a5cb6a72c70046df6b85f287d96f04b2ab12a807945025b5c38b924f6dcb5480b012444b42b4e857e63f1b535c5c6db9cd9c6fe6ad9f04c6f7976065cdcfbf5
+  data.tar.gz: dc65cc27dfcb838ce8b77f805012333edeb0813707e9d646a805c9776f9e7fae9d2dca78cd3a5dc29ceb27b99ff435cb9f84adcbeba131362aeb40ef7dc37020

data/context/getting-started.md

@@ -126,6 +126,49 @@ Async do
 end
 ```
 
+### Instrumentation
+
+Subclass the dispatcher and override {ruby Async::GRPC::Dispatcher#emit_completion} to record completion metrics or logs.
+The hook runs once per request after the final gRPC status is assigned, including routing failures and completed streaming calls:
+
+``` ruby
+class InstrumentedDispatcher < Async::GRPC::Dispatcher
+	protected
+	
+	def emit_completion(call, error = nil)
+		Console.info(self, "Request completed!", path: call.request.path, status: call.status)
+	end
+end
+```
+
+A cancelled request has a status of `Protocol::GRPC::Status::CANCELLED` and no `error`. Exceptions raised by the hook are logged and ignored.
+
+Translate expected application errors at the service boundary by raising {ruby Protocol::GRPC::Error}:
+
+``` ruby
+class ApplicationService < Async::GRPC::Service
+	def find_record(input, output, call)
+		output.write(Record.find(input.read.id))
+	rescue ActiveRecord::RecordNotFound => error
+		raise Protocol::GRPC::Error.new(Protocol::GRPC::Status::NOT_FOUND, error.message)
+	end
+end
+```
+
+Override {ruby Async::GRPC::Dispatcher#invoke_service} when you need middleware around service execution:
+
+``` ruby
+class ApplicationDispatcher < Async::GRPC::Dispatcher
+	protected
+	
+	def invoke_service(service, handler_method, input, output, call)
+		RequestContext.for(call.request) do
+			super
+		end
+	end
+end
+```
+
 ## Complete Example
 
 ``` ruby

data/context/index.yaml

@@ -3,6 +3,8 @@
 ---
 description: Client and server implementation for gRPC using Async.
 metadata:
+  bug_tracker_uri: https://github.com/socketry/async-grpc/issues
+  changelog_uri: https://github.com/socketry/async-grpc/blob/main/releases.md
   documentation_uri: https://socketry.github.io/async-grpc/
   source_code_uri: https://github.com/socketry/async-grpc.git
 files:

data/lib/async/grpc/client.rb

@@ -2,6 +2,7 @@
 
 # Released under the MIT License.
 # Copyright, 2025-2026, by Samuel Williams.
+# Copyright, 2026, by Alex Watt.
 
 require "async"
 require "async/http/client"
@@ -10,7 +11,6 @@ require "async/http/endpoint"
 require "protocol/http"
 require "protocol/grpc"
 require "protocol/grpc/interface"
-require "protocol/grpc/methods"
 require "protocol/grpc/body/readable_body"
 require "protocol/grpc/body/writable_body"
 require "protocol/grpc/metadata"
@@ -123,7 +123,7 @@ module Async
 				raise ArgumentError, "Unknown method: #{method}" unless rpc
 				
 				path = service.path(method)
-				headers = Protocol::GRPC::Methods.build_headers(
+				headers = Protocol::GRPC::Metadata.build(
 					metadata: metadata,
 					timeout: timeout,
 					content_type: "application/grpc+proto"
@@ -277,6 +277,7 @@ module Async
 			# @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
+			# Without a block, `initial` is sent as the complete request stream and the caller owns the returned readable body.
 			# @raises [Protocol::GRPC::Error] If the gRPC call fails
 			def bidirectional_call(path, headers, request_class, response_class, encoding, initial: nil, &block)
 				body = Protocol::GRPC::Body::WritableBody.new(
@@ -284,6 +285,7 @@ module Async
 					message_class: request_class
 				)
 				Array(initial).each{|message| body.write(message)}
+				body.close_write unless block_given?
 				
 				http_request = Protocol::HTTP::Request["POST", path, headers, body]
 				response = call(http_request)
@@ -298,6 +300,8 @@ module Async
 					)
 					
 					unless block_given?
+						# The caller owns the readable body and its underlying response:
+						response = nil
 						return readable_body
 					end
 					
@@ -328,7 +332,7 @@ module Async
 				return if status == Protocol::GRPC::Status::OK
 				
 				message = Protocol::GRPC::Metadata.extract_message(response.headers)
-				metadata = Protocol::GRPC::Methods.extract_metadata(response.headers)
+				metadata = Protocol::GRPC::Metadata.extract(response.headers)
 				
 				remote_error = RemoteError.for(message, metadata)
 				

data/lib/async/grpc/dispatcher.rb

@@ -2,14 +2,15 @@
 
 # Released under the MIT License.
 # Copyright, 2025-2026, by Samuel Williams.
+# Copyright, 2026, by Alex Watt.
 
 require "async"
 
 require_relative "error"
 
 require "protocol/grpc/middleware"
-require "protocol/grpc/methods"
 require "protocol/grpc/call"
+require "protocol/grpc/route"
 require "protocol/grpc/body/readable_body"
 require "protocol/grpc/body/writable_body"
 require "protocol/grpc/metadata"
@@ -45,11 +46,37 @@ module Async
 			
 			protected
 			
-			# Invoke a service handler, providing a protected extension point for middleware and instrumentation around service execution.
+			# Called once after the final gRPC status has been assigned.
 			#
-			# 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.
+			# Override this method to record request metrics or logs. The hook also runs for
+			# routing/setup failures and after streaming calls finish. A cancelled call has
+			# a status of `Protocol::GRPC::Status::CANCELLED` and no error.
 			#
-			# 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.
+			# Exceptions raised by this hook are ignored.
+			#
+			# @parameter call [Protocol::GRPC::Call] The call context, including the request and the response.
+			# @parameter error [Exception | Nil] The error which caused the call to fail, if any.
+			# @returns [void]
+			# @example Record the final gRPC status code
+			# 	def emit_completion(call, error = nil)
+			# 		service_name, method_name = Protocol::GRPC::Route.parse(call.request.path)
+			# 		metrics.increment("grpc.request", tags: {service: service_name, method: method_name, status: call.status})
+			# 	end
+			def emit_completion(call, error = nil)
+				# Implementation-defined.
+			end
+			
+			# Invoke a service handler.
+			#
+			# Override this method to establish request context or wrap handlers with
+			# application middleware. Overrides should call `super` to invoke the handler.
+			# Stream cleanup, trailer handling, and status assignment are performed by the
+			# dispatcher after this method returns or raises.
+			#
+			# This hook only surrounds service execution. Use {emit_completion} to observe
+			# every request, including routing/setup failures. A deadline expiring during
+			# service execution raises {DeadlineExceededError} through this hook before it is
+			# converted to `DEADLINE_EXCEEDED`.
 			#
 			# @parameter service [Async::GRPC::Service] The service containing the handler.
 			# @parameter handler_method [Symbol] The service method to invoke.
@@ -65,98 +92,183 @@ module Async
 			# 		end
 			# 	end
 			def invoke_service(service, handler_method, input, output, call)
+				service.send(handler_method, input, output, call)
+			end
+			
+			# Map an internal dispatcher error to the gRPC status and message reported to the client.
+			#
+			# @parameter error [Exception] The error which caused the call to fail.
+			# @returns [Tuple(Integer, String | Nil)] The gRPC status code and message.
+			private def status_for(error)
+				case error
+				when DeadlineExceededError
+					return Protocol::GRPC::Status::DEADLINE_EXCEEDED, "Deadline exceeded!"
+				when Protocol::GRPC::Error
+					return error.status_code, error.message
+				else
+					# A `nil` message defers to the message of the error itself:
+					return Protocol::GRPC::Status::INTERNAL, nil
+				end
+			end
+			
+			# Invoke the service with deadline enforcement and completion reporting.
+			#
+			# @parameter parent [Async::Task] The task used to enforce the call deadline.
+			def dispatch_to_service(service, handler_method, input, output, call, parent: Async::Task.current)
+				error = nil
+				cancellation = nil
+				
 				begin
-					service.send(handler_method, input, output, call)
-				ensure
-					# Close input stream:
-					input.close
+					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 => error
+					prepare_trailers(output, call)
+					assign_status(call, error)
+				rescue Async::Stop => cancellation
+					prepare_trailers(output, call)
 					
-					# Close output stream:
-					output.close_write unless output.closed?
+					# Cancellation has a fixed status and does not require error mapping:
+					if headers = call.response&.headers
+						Protocol::GRPC::Metadata.assign_status!(headers, status: Protocol::GRPC::Status::CANCELLED)
+					end
 					
-					# gRPC supports trailers-only responses, but only if there are no data frames. If at this point, there are data frames (which may or may not have been sent yet), we need to mark trailers:
-					if output.count > 0
-						call.response.headers.trailer!
+					raise
+				else
+					prepare_trailers(output, call)
+					
+					# Add status (if not already set by handler):
+					if headers = call.response&.headers
+						unless headers.key?("grpc-status")
+							Protocol::GRPC::Metadata.assign_status!(headers, status: Protocol::GRPC::Status::OK)
+						end
 					end
+				ensure
+					finalize_streams(input, output, call, error, cancellation)
 				end
-				
-				# Add status (if not already set by handler):
-				if headers = call.response&.headers
-					# Only add OK status if grpc-status hasn't been set by the handler:
-					unless headers.key?("grpc-status")
-						Protocol::GRPC::Metadata.assign_status!(headers, status: Protocol::GRPC::Status::OK)
-					end
+			end
+			
+			# Mark response headers as trailers when data was written.
+			def prepare_trailers(output, call)
+				if output.count > 0
+					call.response.headers.trailer!
 				end
 			end
 			
-			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
+			# Close the input and output streams.
+			def close_streams(input, output, call)
+				# Close input stream:
+				input.close
+			ensure
+				# Close output stream:
+				unless output.closed?
+					output.close_write
+				end
+			end
+			
+			# Close streams and report completion while preserving an active service error or cancellation.
+			private def finalize_streams(input, output, call, error, cancellation)
+				close_streams(input, output, call)
+			rescue => close_error
+				if error || cancellation
+					Console.warn(self, "Error during stream cleanup!", exception: close_error)
 				else
-					invoke_service(service, handler_method, input, output, call)
+					error = close_error
+					assign_status(call, error)
+					raise
 				end
-			rescue DeadlineExceededError => error
-				# Close input and output streams:
-				input.close
-				output.close_write unless output.closed?
-				
-				# Set DEADLINE_EXCEEDED status in trailers:
+			ensure
+				# Cancellation raises `Async::Stop`, not `StandardError`:
+				report_completion(call, error)
+			end
+			
+			# Assign the status for the given error to the response.
+			def assign_status(call, error)
 				if headers = call.response&.headers
-					Protocol::GRPC::Metadata.assign_status!(headers, status: Protocol::GRPC::Status::DEADLINE_EXCEEDED, message: "Deadline exceeded!", error: error)
+					begin
+						status, message = status_for(error)
+					rescue => internal_error
+						Console.warn(self, "Error during status mapping!", exception: internal_error)
+						
+						status = Protocol::GRPC::Status::INTERNAL
+						message = nil
+					end
+					
+					Protocol::GRPC::Metadata.assign_status!(headers, status: status, message: message, error: error)
 				end
 			end
 			
+			# Report completion without allowing instrumentation to affect the request.
+			private def report_completion(call, error = nil)
+				emit_completion(call, error)
+			rescue => error
+				Console.warn(self, "Error during emit completion!", exception: error)
+			end
+			
 			# Dispatch the request to the appropriate service.
 			# @parameter request [Protocol::HTTP::Request] The HTTP request
 			# @returns [Protocol::HTTP::Response] The HTTP response
-			# @raises [Protocol::GRPC::Error] If service or method is not found
 			def dispatch(request)
-				# Parse service and method from path:
-				service_name, method_name = Protocol::GRPC::Methods.parse_path(request.path)
-				
-				# Find service:
-				service = @services[service_name]
-				unless service
-					raise Protocol::GRPC::Error.new(Protocol::GRPC::Status::UNIMPLEMENTED, "Service not found: #{service_name}")
-				end
-				
-				# Verify service name matches:
-				unless service_name == service.service_name
-					raise Protocol::GRPC::Error.new(Protocol::GRPC::Status::UNIMPLEMENTED, "Service name mismatch: expected #{service.service_name}, got #{service_name}")
-				end
-				
-				# Get RPC descriptions from the service:
-				rpc_descriptor = service.rpc_descriptions[method_name]
-				unless rpc_descriptor
-					raise Protocol::GRPC::Error.new(Protocol::GRPC::Status::UNIMPLEMENTED, "Method not found: #{method_name}")
-				end
-				
-				handler_method = rpc_descriptor.method
-				request_class = rpc_descriptor.request_class
-				response_class = rpc_descriptor.response_class
-				
-				# Verify handler method exists:
-				unless service.respond_to?(handler_method, true)
-					raise Protocol::GRPC::Error.new(Protocol::GRPC::Status::UNIMPLEMENTED, "Handler method not implemented: #{handler_method}")
-				end
-				
-				# Create protocol-level objects for gRPC handling:
-				encoding = request.headers["grpc-encoding"]
-				input = Protocol::GRPC::Body::ReadableBody.new(request.body, message_class: request_class, encoding: encoding)
-				output = Protocol::GRPC::Body::WritableBody.new(message_class: response_class, encoding: encoding)
-				
 				# Create response headers:
+				encoding = request.headers["grpc-encoding"]
 				response_headers = Protocol::HTTP::Headers.new([], nil, policy: Protocol::GRPC::HEADER_POLICY)
 				response_headers["content-type"] = "application/grpc+proto"
 				response_headers["grpc-encoding"] = encoding if encoding
 				
-				# Create response object:
-				response = Protocol::HTTP::Response[200, response_headers, output]
+				# Assign the body after routing so setup failures are trailers-only:
+				response = Protocol::HTTP::Response[200, response_headers, nil]
+				call = nil
 				
-				# Create call context with request, response and deadline:
-				call = Protocol::GRPC::Call.for(request, response)
+				begin
+					# Create the call context:
+					call = Protocol::GRPC::Call.for(request, response)
+					
+					# Extract the routing information from the request path:
+					service_name, method_name = Protocol::GRPC::Route.parse(request.path)
+					
+					# Find service:
+					service = @services[service_name]
+					unless service
+						raise Protocol::GRPC::Error.new(Protocol::GRPC::Status::UNIMPLEMENTED, "Service not found: #{service_name}")
+					end
+					
+					# Verify service name matches:
+					unless service_name == service.service_name
+						raise Protocol::GRPC::Error.new(Protocol::GRPC::Status::UNIMPLEMENTED, "Service name mismatch: expected #{service.service_name}, got #{service_name}")
+					end
+					
+					# Get RPC descriptions from the service:
+					rpc_descriptor = service.rpc_descriptions[method_name]
+					unless rpc_descriptor
+						raise Protocol::GRPC::Error.new(Protocol::GRPC::Status::UNIMPLEMENTED, "Method not found: #{method_name}")
+					end
+					
+					handler_method = rpc_descriptor.method
+					request_class = rpc_descriptor.request_class
+					response_class = rpc_descriptor.response_class
+					
+					# Verify handler method exists:
+					unless service.respond_to?(handler_method, true)
+						raise Protocol::GRPC::Error.new(Protocol::GRPC::Status::UNIMPLEMENTED, "Handler method not implemented: #{handler_method}")
+					end
+					
+					# Create protocol-level objects for gRPC handling:
+					input = Protocol::GRPC::Body::ReadableBody.new(request.body, message_class: request_class, encoding: encoding)
+					output = Protocol::GRPC::Body::WritableBody.new(message_class: response_class, encoding: encoding)
+					response.body = output
+				rescue => error
+					# Routing/setup failures. {Protocol::GRPC::Call.for} can fail before the call context exists:
+					call ||= Protocol::GRPC::Call.new(request, response)
+					
+					assign_status(call, error)
+					report_completion(call, error)
+					
+					return response
+				end
 				
 				if rpc_descriptor.streaming?
 					Async do |task|

data/lib/async/grpc/error.rb

@@ -2,6 +2,7 @@
 
 # Released under the MIT License.
 # Copyright, 2025-2026, by Samuel Williams.
+# Copyright, 2026, by Alex Watt.
 
 module Async
 	module GRPC

data/lib/async/grpc/version.rb

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

data/lib/async/grpc.rb

@@ -2,6 +2,7 @@
 
 # Released under the MIT License.
 # Copyright, 2025, by Samuel Williams.
+# Copyright, 2026, by Alex Watt.
 
 require_relative "grpc/version"
 require_relative "grpc/error"

data/license.md

@@ -1,6 +1,7 @@
 # MIT License
 
 Copyright, 2025-2026, by Samuel Williams.  
+Copyright, 2026, by Alex Watt.  
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

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.9.0
+
+  - Added `Async::GRPC::Dispatcher#emit_completion` for once-per-request completion instrumentation, including routing failures, cancellations, and the final gRPC status.
+
 ### 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.
@@ -70,26 +74,26 @@ Please see the [project releases](https://socketry.github.io/async-grpc/releases
 
 We welcome contributions to this project.
 
-1.  Fork it.
+1.  Fork the repository.
 2.  Create your feature branch (`git checkout -b my-new-feature`).
-3.  Commit your changes (`git commit -am 'Add some 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.
+5.  Create a new pull request.
 
 ### Running Tests
 
 To run the test suite:
 
-``` shell
-bundle exec sus
+``` bash
+$ bundle exec sus
 ```
 
 ### Making Releases
 
 To make a new release:
 
-``` shell
-bundle exec bake gem:release:patch # or minor or major
+``` bash
+$ bundle exec bake gem:release:patch # or minor or major
 ```
 
 ### Developer Certificate of Origin

data/releases.md

@@ -1,5 +1,9 @@
 # Releases
 
+## v0.9.0
+
+  - Added `Async::GRPC::Dispatcher#emit_completion` for once-per-request completion instrumentation, including routing failures, cancellations, and the final gRPC status.
+
 ## 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.

metadata

@@ -1,10 +1,11 @@
 --- !ruby/object:Gem::Specification
 name: async-grpc
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.9.0
 platform: ruby
 authors:
 - Samuel Williams
+- Alex Watt
 bindir: bin
 cert_chain:
 - |
@@ -72,14 +73,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.12.0
+        version: 0.14.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.12.0
+        version: 0.14.0
 - !ruby/object:Gem::Dependency
   name: protocol-http
   requirement: !ruby/object:Gem::Requirement
@@ -116,6 +117,8 @@ homepage: https://github.com/socketry/async-grpc
 licenses:
 - MIT
 metadata:
+  bug_tracker_uri: https://github.com/socketry/async-grpc/issues
+  changelog_uri: https://github.com/socketry/async-grpc/blob/main/releases.md
   documentation_uri: https://socketry.github.io/async-grpc/
   source_code_uri: https://github.com/socketry/async-grpc.git
 rdoc_options: []