Better error handling.

Author: samuel-williams-shopify

async-grpc.gemspec

@@ -22,5 +22,5 @@ Gem::Specification.new do |spec|
 	spec.required_ruby_version = ">= 3.2"
 
 	spec.add_dependency "async-http"
-	spec.add_dependency "protocol-grpc", "~> 0.4"
+	spec.add_dependency "protocol-grpc", "~> 0.5"
 end

context/getting-started.md

@@ -169,3 +169,4 @@ Async do
 	server.run
 end
 ```
+

gems.rb

@@ -31,3 +31,4 @@
 	gem "bake-test"
 	gem "bake-test-external"
 end
+

lib/async/grpc/client.rb

@@ -16,6 +16,7 @@
 require "protocol/grpc/metadata"
 require "protocol/grpc/error"
 require_relative "stub"
+require_relative "remote_error"
 
 module Async
 	module GRPC
@@ -316,16 +317,14 @@ def bidirectional_call(path, headers, request_class, response_class, encoding, &
 			def check_status!(response)
 				status = Protocol::GRPC::Metadata.extract_status(response.headers)
 
-				# If status is UNKNOWN (not found), default to OK:
-				# This handles cases where trailers aren't available or status wasn't set
-				status = Protocol::GRPC::Status::OK if status == Protocol::GRPC::Status::UNKNOWN
-				
 				return if status == Protocol::GRPC::Status::OK
 
 				message = Protocol::GRPC::Metadata.extract_message(response.headers)
 				metadata = Protocol::GRPC::Methods.extract_metadata(response.headers)
 
-				raise Protocol::GRPC::Error.for(status, message, metadata: metadata)
+				remote_error = RemoteError.for(message, metadata)
+				
+				raise Protocol::GRPC::Error.for(status, metadata: metadata), cause: remote_error
 			end
 		end
 	end

lib/async/grpc/dispatcher_middleware.rb

@@ -61,7 +61,7 @@ def invoke_service(service, handler_method, input, output, call)
 
 					# Only add OK status if grpc-status hasn't been set by the handler:
 					unless call.response.headers["grpc-status"]
-						Protocol::GRPC::Metadata.add_status_trailer!(call.response.headers, status: Protocol::GRPC::Status::OK)
+						Protocol::GRPC::Metadata.add_status!(call.response.headers, status: Protocol::GRPC::Status::OK)
 					end
 				end
 			end

lib/async/grpc/remote_error.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+module Async
+	module GRPC
+		class RemoteError < StandardError
+			def self.for(message, metadata)
+				self.new(message).tap do |error|
+					if backtrace = metadata.delete("backtrace")
+						# Backtrace is always an array (Split header format):
+						error.set_backtrace(backtrace)
+					end
+				end
+			end
+		end
+	end
+end

lib/async/grpc/version.rb

@@ -10,3 +10,4 @@ module GRPC
 		VERSION = "0.1.0"
 	end
 end
+

releases.md

@@ -2,6 +2,9 @@
 
 ## Unreleased
 
+  - Added `Async::GRPC::RemoteError` class to encapsulate remote error details including message and backtrace extracted from response headers.
+  - Client-side error handling now extracts backtraces from response metadata and sets them on `RemoteError`, which is chained as the `cause` of `Protocol::GRPC::Error` for better debugging.
+  - Updated to use `Protocol::GRPC::Metadata.add_status!` instead of deprecated `add_status_trailer!` method.
   - Tidy up request and response body handling.
 
 ## v0.1.0

test/async/grpc/client.rb

@@ -78,6 +78,132 @@
 			stub.unknown_method(request)
 		end.to raise_exception(NoMethodError)
 	end
+	
+	with "error handling" do
+		let(:error_service_name) {"test.ErrorService"}
+		let(:error_interface_class) do
+			Class.new(Protocol::GRPC::Interface) do
+				rpc :ReturnError, request_class: Protocol::GRPC::Fixtures::TestMessage,
+					response_class: Protocol::GRPC::Fixtures::TestMessage, streaming: :unary
+			end
+		end
+		let(:error_service) do
+			Class.new(Async::GRPC::Service) do
+				define_method(:return_error) do |input, output, call|
+					request = input.read
+					
+					# Set error status and message based on request value
+					case request.value
+					when "internal"
+						status = Protocol::GRPC::Status::INTERNAL
+						message = "Internal server error"
+					when "not_found"
+						status = Protocol::GRPC::Status::NOT_FOUND
+						message = "Resource not found"
+					when "with_backtrace"
+						status = Protocol::GRPC::Status::INTERNAL
+						message = "Error with backtrace"
+						# Add backtrace to metadata (comma-separated string, Split header will parse into array)
+						call.response.headers["backtrace"] = "/path/to/file.rb:10:in `method', /path/to/file.rb:5:in `block'"
+					when "with_metadata"
+						status = Protocol::GRPC::Status::INVALID_ARGUMENT
+						message = "Invalid argument"
+						# Add custom metadata
+						call.response.headers["custom-key"] = "custom-value"
+					else
+						status = Protocol::GRPC::Status::UNKNOWN
+						message = "Unknown error"
+					end
+					
+					Protocol::GRPC::Metadata.add_status!(call.response.headers, status: status, message: message)
+				end
+			end.new(error_interface_class, error_service_name)
+		end
+		let(:app) {Async::GRPC::DispatcherMiddleware.new(services: { error_service_name => error_service })}
+		
+		it "raises Protocol::GRPC::Error with correct status code" do
+			grpc_client = Async::GRPC::Client.new(client)
+			stub = grpc_client.stub(error_interface_class, error_service_name)
+			
+			request = Protocol::GRPC::Fixtures::TestMessage.new(value: "internal")
+			
+			begin
+				stub.return_error(request)
+				expect(false).to be == true # Should not reach here
+			rescue Protocol::GRPC::Internal => error
+				expect(error.status_code).to be == Protocol::GRPC::Status::INTERNAL
+				# Message comes from RemoteError (cause), not the Protocol::GRPC::Error itself
+				expect(error.cause.message).to be == "Internal server error"
+			end
+		end
+		
+		it "raises correct error class for status code" do
+			grpc_client = Async::GRPC::Client.new(client)
+			stub = grpc_client.stub(error_interface_class, error_service_name)
+			
+			request = Protocol::GRPC::Fixtures::TestMessage.new(value: "not_found")
+			
+			begin
+				stub.return_error(request)
+				expect(false).to be == true # Should not reach here
+			rescue Protocol::GRPC::NotFound => error
+				expect(error.status_code).to be == Protocol::GRPC::Status::NOT_FOUND
+				expect(error.cause.message).to be == "Resource not found"
+			end
+		end
+		
+		it "extracts and sets backtrace from metadata on RemoteError" do
+			grpc_client = Async::GRPC::Client.new(client)
+			stub = grpc_client.stub(error_interface_class, error_service_name)
+			
+			request = Protocol::GRPC::Fixtures::TestMessage.new(value: "with_backtrace")
+			
+			begin
+				stub.return_error(request)
+				expect(false).to be == true # Should not reach here
+			rescue Protocol::GRPC::Internal => error
+				expect(error.cause).to be_a(Async::GRPC::RemoteError)
+				expect(error.cause.message).to be == "Error with backtrace"
+				# Backtrace comes as array from Split header format
+				backtrace = error.cause.backtrace
+				expect(backtrace).to be_a(Array)
+				# Split header splits comma-separated string into array
+				expect(backtrace.length).to be >= 1
+				expect(backtrace.any?{|line| line.include?("file.rb:10")}).to be == true
+				expect(backtrace.any?{|line| line.include?("file.rb:5")}).to be == true
+			end
+		end
+		
+		it "preserves metadata in error" do
+			grpc_client = Async::GRPC::Client.new(client)
+			stub = grpc_client.stub(error_interface_class, error_service_name)
+			
+			request = Protocol::GRPC::Fixtures::TestMessage.new(value: "with_metadata")
+			
+			begin
+				stub.return_error(request)
+				expect(false).to be == true # Should not reach here
+			rescue Protocol::GRPC::InvalidArgument => error
+				expect(error.metadata.key?("custom-key")).to be == true
+				expect(error.metadata["custom-key"]).to be == "custom-value"
+			end
+		end
+		
+		it "sets RemoteError as cause of Protocol::GRPC::Error" do
+			grpc_client = Async::GRPC::Client.new(client)
+			stub = grpc_client.stub(error_interface_class, error_service_name)
+			
+			request = Protocol::GRPC::Fixtures::TestMessage.new(value: "internal")
+			
+			begin
+				stub.return_error(request)
+				expect(false).to be == true # Should not reach here
+			rescue Protocol::GRPC::Internal => error
+				expect(error.cause).to be_a(Async::GRPC::RemoteError)
+				expect(error.cause.message).to be == "Internal server error"
+			end
+		end
+	end
 end
 
 describe Async::GRPC::Client do