grpc 1.6.7 → 1.7.0.pre1

data/src/ruby/lib/grpc.rb

@@ -24,6 +24,7 @@ require_relative 'grpc/generic/active_call'
 require_relative 'grpc/generic/client_stub'
 require_relative 'grpc/generic/service'
 require_relative 'grpc/generic/rpc_server'
+require_relative 'grpc/generic/interceptors'
 
 begin
   file = File.open(ssl_roots_path)

data/src/ruby/lib/grpc/generic/active_call.rb

@@ -154,6 +154,15 @@ module GRPC
       Operation.new(self)
     end
 
+    ##
+    # Returns a restricted view of this ActiveCall for use in interceptors
+    #
+    # @return [InterceptableView]
+    #
+    def interceptable
+      InterceptableView.new(self)
+    end
+
     def receive_and_check_status
       batch_result = @call.run_batch(RECV_STATUS_ON_CLIENT => nil)
       set_input_stream_done
@@ -515,15 +524,27 @@ module GRPC
     # This does not mean that must necessarily be one.  E.g, the replies
     # produced by gen_each_reply could ignore the received_msgs
     #
-    # @param gen_each_reply [Proc] generates the BiDi stream replies
-    def run_server_bidi(gen_each_reply)
-      bd = BidiCall.new(@call,
-                        @marshal,
-                        @unmarshal,
-                        metadata_received: @metadata_received,
-                        req_view: MultiReqView.new(self))
-
-      bd.run_on_server(gen_each_reply, proc { set_input_stream_done })
+    # @param mth [Proc] generates the BiDi stream replies
+    # @param interception_ctx [InterceptionContext]
+    #
+    def run_server_bidi(mth, interception_ctx)
+      view = multi_req_view
+      bidi_call = BidiCall.new(
+        @call,
+        @marshal,
+        @unmarshal,
+        metadata_received: @metadata_received,
+        req_view: view
+      )
+      requests = bidi_call.read_next_loop(proc { set_input_stream_done }, false)
+      interception_ctx.intercept!(
+        :bidi_streamer,
+        call: view,
+        method: mth,
+        requests: requests
+      ) do
+        bidi_call.run_on_server(mth, requests)
+      end
     end
 
     # Waits till an operation completes
@@ -645,5 +666,9 @@ module GRPC
     Operation = view_class(:cancel, :cancelled?, :deadline, :execute,
                            :metadata, :status, :start_call, :wait, :write_flag,
                            :write_flag=, :trailing_metadata)
+
+    # InterceptableView further limits access to an ActiveCall's methods
+    # for use in interceptors on the client, exposing only the deadline
+    InterceptableView = view_class(:deadline)
   end
 end

data/src/ruby/lib/grpc/generic/bidi_call.rb

@@ -87,23 +87,32 @@ module GRPC
     # This does not mean that must necessarily be one.  E.g, the replies
     # produced by gen_each_reply could ignore the received_msgs
     #
-    # @param gen_each_reply [Proc] generates the BiDi stream replies.
-    # @param set_input_steam_done [Proc] call back to call when
-    #   the reads have been completely read through.
-    def run_on_server(gen_each_reply, set_input_stream_done)
+    # @param [Proc] gen_each_reply generates the BiDi stream replies.
+    # @param [Enumerable] requests The enumerable of requests to run
+    def run_on_server(gen_each_reply, requests)
+      replies = nil
+
       # Pass in the optional call object parameter if possible
       if gen_each_reply.arity == 1
-        replys = gen_each_reply.call(
-          read_loop(set_input_stream_done, is_client: false))
+        replies = gen_each_reply.call(requests)
       elsif gen_each_reply.arity == 2
-        replys = gen_each_reply.call(
-          read_loop(set_input_stream_done, is_client: false),
-          @req_view)
+        replies = gen_each_reply.call(requests, @req_view)
       else
         fail 'Illegal arity of reply generator'
       end
 
-      write_loop(replys, is_client: false)
+      write_loop(replies, is_client: false)
+    end
+
+    ##
+    # Read the next stream iteration
+    #
+    # @param [Proc] finalize_stream callback to call when the reads have been
+    #   completely read through.
+    # @param [Boolean] is_client If this is a client or server request
+    #
+    def read_next_loop(finalize_stream, is_client = false)
+      read_loop(finalize_stream, is_client: is_client)
     end
 
     private

data/src/ruby/lib/grpc/generic/client_stub.rb

@@ -89,17 +89,23 @@ module GRPC
     #     used within a gRPC server.
     # @param channel_args [Hash] the channel arguments. Note: this argument is
     #     ignored if the channel_override argument is provided.
+    # @param interceptors [Array<GRPC::ClientInterceptor>] An array of
+    #     GRPC::ClientInterceptor objects that will be used for
+    #     intercepting calls before they are executed
+    #     Interceptors are an EXPERIMENTAL API.
     def initialize(host, creds,
                    channel_override: nil,
                    timeout: nil,
                    propagate_mask: nil,
-                   channel_args: {})
+                   channel_args: {},
+                   interceptors: [])
       @ch = ClientStub.setup_channel(channel_override, host, creds,
                                      channel_args)
       alt_host = channel_args[Core::Channel::SSL_TARGET]
       @host = alt_host.nil? ? host : alt_host
       @propagate_mask = propagate_mask
       @timeout = timeout.nil? ? DEFAULT_TIMEOUT : timeout
+      @interceptors = InterceptorRegistry.new(interceptors)
     end
 
     # request_response sends a request to a GRPC server, and returns the
@@ -149,16 +155,29 @@ module GRPC
                           deadline: deadline,
                           parent: parent,
                           credentials: credentials)
-      return c.request_response(req, metadata: metadata) unless return_op
-
-      # return the operation view of the active_call; define #execute as a
-      # new method for this instance that invokes #request_response.
-      c.merge_metadata_to_send(metadata)
-      op = c.operation
-      op.define_singleton_method(:execute) do
-        c.request_response(req, metadata: metadata)
+      interception_context = @interceptors.build_context
+      intercept_args = {
+        method: method,
+        request: req,
+        call: c.interceptable,
+        metadata: metadata
+      }
+      if return_op
+        # return the operation view of the active_call; define #execute as a
+        # new method for this instance that invokes #request_response.
+        c.merge_metadata_to_send(metadata)
+        op = c.operation
+        op.define_singleton_method(:execute) do
+          interception_context.intercept!(:request_response, intercept_args) do
+            c.request_response(req, metadata: metadata)
+          end
+        end
+        op
+      else
+        interception_context.intercept!(:request_response, intercept_args) do
+          c.request_response(req, metadata: metadata)
+        end
       end
-      op
     end
 
     # client_streamer sends a stream of requests to a GRPC server, and
@@ -213,16 +232,29 @@ module GRPC
                           deadline: deadline,
                           parent: parent,
                           credentials: credentials)
-      return c.client_streamer(requests, metadata: metadata) unless return_op
-
-      # return the operation view of the active_call; define #execute as a
-      # new method for this instance that invokes #client_streamer.
-      c.merge_metadata_to_send(metadata)
-      op = c.operation
-      op.define_singleton_method(:execute) do
-        c.client_streamer(requests)
+      interception_context = @interceptors.build_context
+      intercept_args = {
+        method: method,
+        requests: requests,
+        call: c.interceptable,
+        metadata: metadata
+      }
+      if return_op
+        # return the operation view of the active_call; define #execute as a
+        # new method for this instance that invokes #client_streamer.
+        c.merge_metadata_to_send(metadata)
+        op = c.operation
+        op.define_singleton_method(:execute) do
+          interception_context.intercept!(:client_streamer, intercept_args) do
+            c.client_streamer(requests)
+          end
+        end
+        op
+      else
+        interception_context.intercept!(:client_streamer, intercept_args) do
+          c.client_streamer(requests, metadata: metadata)
+        end
       end
-      op
     end
 
     # server_streamer sends one request to the GRPC server, which yields a
@@ -292,16 +324,29 @@ module GRPC
                           deadline: deadline,
                           parent: parent,
                           credentials: credentials)
-      return c.server_streamer(req, metadata: metadata, &blk) unless return_op
-
-      # return the operation view of the active_call; define #execute
-      # as a new method for this instance that invokes #server_streamer
-      c.merge_metadata_to_send(metadata)
-      op = c.operation
-      op.define_singleton_method(:execute) do
-        c.server_streamer(req, &blk)
+      interception_context = @interceptors.build_context
+      intercept_args = {
+        method: method,
+        request: req,
+        call: c.interceptable,
+        metadata: metadata
+      }
+      if return_op
+        # return the operation view of the active_call; define #execute
+        # as a new method for this instance that invokes #server_streamer
+        c.merge_metadata_to_send(metadata)
+        op = c.operation
+        op.define_singleton_method(:execute) do
+          interception_context.intercept!(:server_streamer, intercept_args) do
+            c.server_streamer(req, &blk)
+          end
+        end
+        op
+      else
+        interception_context.intercept!(:server_streamer, intercept_args) do
+          c.server_streamer(req, metadata: metadata, &blk)
+        end
       end
-      op
     end
 
     # bidi_streamer sends a stream of requests to the GRPC server, and yields
@@ -405,17 +450,29 @@ module GRPC
                           deadline: deadline,
                           parent: parent,
                           credentials: credentials)
-      return c.bidi_streamer(requests, metadata: metadata,
-                             &blk) unless return_op
-
-      # return the operation view of the active_call; define #execute
-      # as a new method for this instance that invokes #bidi_streamer
-      c.merge_metadata_to_send(metadata)
-      op = c.operation
-      op.define_singleton_method(:execute) do
-        c.bidi_streamer(requests, &blk)
+      interception_context = @interceptors.build_context
+      intercept_args = {
+        method: method,
+        requests: requests,
+        call: c.interceptable,
+        metadata: metadata
+      }
+      if return_op
+        # return the operation view of the active_call; define #execute
+        # as a new method for this instance that invokes #bidi_streamer
+        c.merge_metadata_to_send(metadata)
+        op = c.operation
+        op.define_singleton_method(:execute) do
+          interception_context.intercept!(:bidi_streamer, intercept_args) do
+            c.bidi_streamer(requests, &blk)
+          end
+        end
+        op
+      else
+        interception_context.intercept!(:bidi_streamer, intercept_args) do
+          c.bidi_streamer(requests, metadata: metadata, &blk)
+        end
       end
-      op
     end
 
     private

data/src/ruby/lib/grpc/generic/interceptor_registry.rb

@@ -0,0 +1,53 @@
+# Copyright 2017 gRPC authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# GRPC contains the General RPC module.
+module GRPC
+  ##
+  # Represents a registry of added interceptors available for enumeration.
+  # The registry can be used for both server and client interceptors.
+  # This class is internal to gRPC and not meant for public usage.
+  #
+  class InterceptorRegistry
+    ##
+    # An error raised when an interceptor is attempted to be added
+    # that does not extend GRPC::Interceptor
+    #
+    class DescendantError < StandardError; end
+
+    ##
+    # Initialize the registry with an empty interceptor list
+    # This is an EXPERIMENTAL API.
+    #
+    def initialize(interceptors = [])
+      @interceptors = []
+      interceptors.each do |i|
+        base = GRPC::Interceptor
+        unless i.class.ancestors.include?(base)
+          fail DescendantError, "Interceptors must descend from #{base}"
+        end
+        @interceptors << i
+      end
+    end
+
+    ##
+    # Builds an interception context from this registry
+    #
+    # @return [InterceptionContext]
+    #
+    def build_context
+      InterceptionContext.new(@interceptors)
+    end
+  end
+end

data/src/ruby/lib/grpc/generic/interceptors.rb

@@ -0,0 +1,186 @@
+# Copyright 2017 gRPC authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+require_relative 'interceptor_registry'
+
+# GRPC contains the General RPC module.
+module GRPC
+  ##
+  # Base class for interception in GRPC
+  #
+  class Interceptor
+    ##
+    # @param [Hash] options A hash of options that will be used
+    #   by the interceptor. This is an EXPERIMENTAL API.
+    #
+    def initialize(options = {})
+      @options = options || {}
+    end
+  end
+
+  ##
+  # ClientInterceptor allows for wrapping outbound gRPC client stub requests.
+  # This is an EXPERIMENTAL API.
+  #
+  class ClientInterceptor < Interceptor
+    ##
+    # Intercept a unary request response call
+    #
+    # @param [Object] request
+    # @param [GRPC::ActiveCall] call
+    # @param [Method] method
+    # @param [Hash] metadata
+    #
+    def request_response(request:, call:, method:, metadata:)
+      GRPC.logger.debug "Intercepting request response method #{method}" \
+        " for request #{request} with call #{call} and metadata: #{metadata}"
+      yield
+    end
+
+    ##
+    # Intercept a client streaming call
+    #
+    # @param [Enumerable] requests
+    # @param [GRPC::ActiveCall] call
+    # @param [Method] method
+    # @param [Hash] metadata
+    #
+    def client_streamer(requests:, call:, method:, metadata:)
+      GRPC.logger.debug "Intercepting client streamer method #{method}" \
+       " for requests #{requests} with call #{call} and metadata: #{metadata}"
+      yield
+    end
+
+    ##
+    # Intercept a server streaming call
+    #
+    # @param [Object] request
+    # @param [GRPC::ActiveCall] call
+    # @param [Method] method
+    # @param [Hash] metadata
+    #
+    def server_streamer(request:, call:, method:, metadata:)
+      GRPC.logger.debug "Intercepting server streamer method #{method}" \
+        " for request #{request} with call #{call} and metadata: #{metadata}"
+      yield
+    end
+
+    ##
+    # Intercept a BiDi streaming call
+    #
+    # @param [Enumerable] requests
+    # @param [GRPC::ActiveCall] call
+    # @param [Method] method
+    # @param [Hash] metadata
+    #
+    def bidi_streamer(requests:, call:, method:, metadata:)
+      GRPC.logger.debug "Intercepting bidi streamer method #{method}" \
+        " for requests #{requests} with call #{call} and metadata: #{metadata}"
+      yield
+    end
+  end
+
+  ##
+  # ServerInterceptor allows for wrapping gRPC server execution handling.
+  # This is an EXPERIMENTAL API.
+  #
+  class ServerInterceptor < Interceptor
+    ##
+    # Intercept a unary request response call.
+    #
+    # @param [Object] request
+    # @param [GRPC::ActiveCall::SingleReqView] call
+    # @param [Method] method
+    #
+    def request_response(request:, call:, method:)
+      GRPC.logger.debug "Intercepting request response method #{method}" \
+        " for request #{request} with call #{call}"
+      yield
+    end
+
+    ##
+    # Intercept a client streaming call
+    #
+    # @param [GRPC::ActiveCall::MultiReqView] call
+    # @param [Method] method
+    #
+    def client_streamer(call:, method:)
+      GRPC.logger.debug "Intercepting client streamer method #{method}" \
+        " with call #{call}"
+      yield
+    end
+
+    ##
+    # Intercept a server streaming call
+    #
+    # @param [Object] request
+    # @param [GRPC::ActiveCall::SingleReqView] call
+    # @param [Method] method
+    #
+    def server_streamer(request:, call:, method:)
+      GRPC.logger.debug "Intercepting server streamer method #{method}" \
+        " for request #{request} with call #{call}"
+      yield
+    end
+
+    ##
+    # Intercept a BiDi streaming call
+    #
+    # @param [Enumerable<Object>] requests
+    # @param [GRPC::ActiveCall::MultiReqView] call
+    # @param [Method] method
+    #
+    def bidi_streamer(requests:, call:, method:)
+      GRPC.logger.debug "Intercepting bidi streamer method #{method}" \
+        " for requests #{requests} with call #{call}"
+      yield
+    end
+  end
+
+  ##
+  # Represents the context in which an interceptor runs. Used to provide an
+  # injectable mechanism for handling interception. This is an EXPERIMENTAL API.
+  #
+  class InterceptionContext
+    ##
+    # @param [Array<GRPC::Interceptor>]
+    #
+    def initialize(interceptors = [])
+      @interceptors = interceptors.dup
+    end
+
+    ##
+    # Intercept the call and fire out to interceptors in a FIFO execution.
+    # This is an EXPERIMENTAL API.
+    #
+    # @param [Symbol] type The request type
+    # @param [Hash] args The arguments for the call
+    #
+    def intercept!(type, args = {})
+      return yield if @interceptors.none?
+
+      i = @interceptors.pop
+      return yield unless i
+
+      i.send(type, args) do
+        if @interceptors.any?
+          intercept!(type, args) do
+            yield
+          end
+        else
+          yield
+        end
+      end
+    end
+  end
+end