grpc
/
proposal
mirror of https://github.com/grpc/proposal.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
proposal/L11-ruby-interceptors.md

8.9 KiB
Raw Permalink Blame History

Title

Abstract

Ruby gRPC client stubs and servers will present an interceptor interface, which will allow configuration of interceptors that will execute on any inbound or outbound operation. The server and client interceptor APIs will behave similarly, using a compositional model for interceptors that allow for request-type-specific interception.

Background

The Ruby language implementation for gRPC does not currently have an interceptor interface, whereas other languages like Go and Java do. Application concerns and extensibility are currently closed in the Ruby implementation, making it difficult to extend the libraries for various application needs.

Related Proposals:

  • None

Proposal

Add both server and client interceptors to the Ruby gRPC implementation. Similar to the implementation in Go, interceptors are set at the initialization of the client stub and RPC server. They provide per-call interception for gRPC Ruby services and clients.

Client Interceptors

On the client side, interceptors inherit from GRPC::ClientInterceptor class. Interceptor objects are then instantiated and registered on the stub upon its initialization.

Illustrating Example

This interceptor naively logs outbound requests and the method they call, and injects a unique request_id metadata value into the metadata sent:

require 'securerandom'

class AppClientInterceptor < GRPC::ClientInterceptor
  def request_response(request:, call:, method:, metadata:)
    logger.info "Sending request/response to #{method}"
    metadata['request_id'] = generate_request_id
    yield
  end
  
  def client_streamer(requests:, call:, method:, metadata:)
    logger.info "Sending client streamer to #{method}"
    metadata['request_id'] = generate_request_id
    yield
  end
  
  def server_streamer(request:, call:, method:, metadata:)
    logger.info "Sending client streamer to #{method}"
    metadata['request_id'] = generate_request_id
    yield
  end
    
  def bidi_streamer(requests:, call:, method:, metadata:)
    logger.info "Sending bidi streamer to #{method}"
    metadata['request_id'] = generate_request_id
    yield
  end
  
  private
  
  def logger
    @logger ||= Logger.new(STDOUT)
  end
  
  def generate_request_id
    SecureRandom.uuid
  end
end

Each interceptor can choose then to combine functionality for different request types into a protected or private method, or handle each request type differently, based on the needs of the interceptor.

You'll also note that the interceptor must yield back in order to complete the call. Then the interceptor can be added to the stub via the initializer, which passes in an array of interceptors:

MyStub.new(
  '0.0.0.0:0', 
  :this_channel_is_insecure, 
  interceptors: [AppClientInterceptor.new]
)

Interceptors maintain order of insertion by using the FIFO execution order native to Ruby's Array. In other words, if multiple interceptors are added, they will intercept in the order they were set in the passed array.

Client Interception API

Client interceptors have four separate methods, one for each request type. Their arguments are similar; the only difference being if it is a streamed call, request will be requests and have an array of the requests that were sent.

For example, the arguments for a unary request/response call:

##
# @param [Object] request The protobuf request message
# @param [GRPC::ActiveCall::InterceptableView] call A restricted view of the active call object
# @param [Method] method The method being called
# @param [Hash] metadata The call's outbound metadata
def request_response(request:, call:, method:, metadata:)
  yield
end

The call object is a restricted view, which only exposes the deadline attribute that was set on the call.

Also, the metadata hash here is able to be updated and will propagate to the server when the call executes. This allows client interceptors to inject metadata for calls dynamically.

Server Interceptors

On the server side, interceptors inherit from GRPC::ServerInterceptor class and are then instantiated and registered on the RPCServer.

Illustrating Example

This interceptor logs incoming requests and the service and method they call:

class ServerRequestLogInterceptor < GRPC::ServerInterceptor
  def request_response(request:, call:, method:)
    response = yield
    log(method: method, response: response)
    response
  end
  
  def client_streamer(call:, method:)
    response = yield
    log(method: method, response: response)
    response
  end
  
  def server_streamer(request:, call:, method:)
    response = yield
    log(method: method, response: response)
    response
  end
  
  def bidi_streamer(requests:, call:, method:)
    response = yield
    log(method: method, response: response)
    response
  end
  
  private
  
  def log(method:, response:)
    mth = "#{method.owner.name}.#{method.name}"
    if response.is_a?(GRPC::BadStatus)
      logger.info "[GRPC::Ok] (#{mth})"
    else
      logger.error "[#{response.class.name}] (#{mth}) #{response.message}"
    end
  end
  
  def logger
    @logger ||= Logger.new(STDOUT)
  end
end

The interceptor can then be loaded via the initializer for the service:

server = GRPC::RpcServer.new(
  interceptors: [ServerRequestLogInterceptor.new] 
)
server.add_http2_port('0.0.0.0:0', :this_port_is_insecure)
server.handle(MyService)
server.run_till_terminated

This example will produce logs like:

[GRPC::Ok] (MyService.a_rpc_method)

[GRPC::Internal] (MyService.a_failing_rpc_method) An error occurred in my service!

Server Interception API

Server interceptors act as decorators around handlers. Similar to client interceptors, server interceptors have four separate methods, one for each request type.

Unary and server streamer interceptor calls will have a single request, SingleReqView view of the active call, and the method being requested. Client streamer interceptor calls have only the MultiReqView and method passed (similar to the handler). Finally, the bidi call will receive an enumerable of requests that are passed.

For example, the arguments for a unary request/response call:

##
# @param [Object] request The protobuf request message
# @param [GRPC::ActiveCall::SingleReqView] call A restricted view of the active call object
# @param [Method] method The method being called
def request_response(request:, call:, method:)
  yield
end

Trailing metadata is able to be modified as well in interceptors, via the normal call API:

call.output_metadata[:my_key] = 'my_value'

Rationale

To provide support for intercepting both at the client and server level, which is currently not supported, and to bring parity for Ruby with the other language implementations.

Methods per-request-type were done as opposed to a singular interceptor method (such as a intercept method on each interceptor) in order to clearly distinguish the type of request that is coming in. Interceptors can from that consolidate their behavior, but the separation makes for cleaner delineation between the types of requests and makes explicit the differences between each in the arguments.

Implementation

Implemented in: https://github.com/grpc/grpc/pull/12100

General Changes

  • Introduce a GRPC::Interceptor base class that client and server interceptors derive from, and provide the internal API for an options Hash in the interceptor class itself that derived interceptors can utilize
  • Introduce a new GRPC::InterceptorRegistry class that centrally handles the storage of the interceptors
  • Introduce an GRPC::InterceptionContext class that centralizes the logic required to recursively handle the interception of calls for both client and server interceptors
  • Refactor GRPC::Generic::BidiCall to return the replies generated so interceptors can receive it

Client Interceptor Changes

  • Add an interceptors argument that accepts an Array to the ClientStub initializer and builds a GRPC::InterceptorRegistry instance from it
  • Add an InterceptableView view that restricts access to the call to only be the deadline attribute and a new interceptable method to the ActiveCall object that returns the view
  • Add wrapping for each request type (such as request_response, client_streamer, etc) in the ClientStub class that builds an interception context and wraps the ActiveCall call in an interception block

Server Interceptor Changes

  • Add an interceptors argument that accepts an Array to the GRPC::RpcServer initializer and builds an GRPC::InterceptorRegistry instance from it
  • Update the handle_* methods in GRPC::Generic::RpcDesc to take in a GRPC::InterceptionContext instance, which then wraps the calls to the handler in an interception block