From afcee036e72b30ef54b4521f6f996a024c7ae626 Mon Sep 17 00:00:00 2001 From: Samuel Williams Date: Thu, 13 Aug 2026 23:22:24 +1200 Subject: [PATCH] Document invoke_service extension hook --- lib/async/grpc/dispatcher.rb | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/lib/async/grpc/dispatcher.rb b/lib/async/grpc/dispatcher.rb index 2c4bc15..8672f7e 100644 --- a/lib/async/grpc/dispatcher.rb +++ b/lib/async/grpc/dispatcher.rb @@ -45,6 +45,25 @@ def register(service, name: service.service_name) 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)