grpc 0.5.0

data/lib/grpc/generic/bidi_call.rb

@@ -0,0 +1,221 @@
+# Copyright 2015, Google Inc.
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are
+# met:
+#
+#     * Redistributions of source code must retain the above copyright
+# notice, this list of conditions and the following disclaimer.
+#     * Redistributions in binary form must reproduce the above
+# copyright notice, this list of conditions and the following disclaimer
+# in the documentation and/or other materials provided with the
+# distribution.
+#     * Neither the name of Google Inc. nor the names of its
+# contributors may be used to endorse or promote products derived from
+# this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+# A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+# OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+# LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+require 'forwardable'
+require 'grpc/grpc'
+
+def assert_event_type(ev, want)
+  fail OutOfTime if ev.nil?
+  got = ev.type
+  fail("Unexpected rpc event: got #{got}, want #{want}") unless got == want
+end
+
+# GRPC contains the General RPC module.
+module GRPC
+  # The BiDiCall class orchestrates exection of a BiDi stream on a client or
+  # server.
+  class BidiCall
+    include Core::CompletionType
+    include Core::StatusCodes
+    include Core::TimeConsts
+
+    # Creates a BidiCall.
+    #
+    # BidiCall should only be created after a call is accepted.  That means
+    # different things on a client and a server.  On the client, the call is
+    # accepted after call.invoke. On the server, this is after call.accept.
+    #
+    # #initialize cannot determine if the call is accepted or not; so if a
+    # call that's not accepted is used here, the error won't be visible until
+    # the BidiCall#run is called.
+    #
+    # deadline is the absolute deadline for the call.
+    #
+    # @param call [Call] the call used by the ActiveCall
+    # @param q [CompletionQueue] the completion queue used to accept
+    #          the call
+    # @param marshal [Function] f(obj)->string that marshal requests
+    # @param unmarshal [Function] f(string)->obj that unmarshals responses
+    # @param deadline [Fixnum] the deadline for the call to complete
+    # @param finished_tag [Object] the object used as the call's finish tag,
+    def initialize(call, q, marshal, unmarshal, deadline, finished_tag)
+      fail(ArgumentError, 'not a call') unless call.is_a? Core::Call
+      unless q.is_a? Core::CompletionQueue
+        fail(ArgumentError, 'not a CompletionQueue')
+      end
+      @call = call
+      @cq = q
+      @deadline = deadline
+      @finished_tag = finished_tag
+      @marshal = marshal
+      @readq = Queue.new
+      @unmarshal = unmarshal
+    end
+
+    # Begins orchestration of the Bidi stream for a client sending requests.
+    #
+    # The method either returns an Enumerator of the responses, or accepts a
+    # block that can be invoked with each response.
+    #
+    # @param requests the Enumerable of requests to send
+    # @return an Enumerator of requests to yield
+    def run_on_client(requests, &blk)
+      enq_th = start_write_loop(requests)
+      loop_th = start_read_loop
+      replies = each_queued_msg
+      return replies if blk.nil?
+      replies.each { |r| blk.call(r) }
+      enq_th.join
+      loop_th.join
+    end
+
+    # Begins orchestration of the Bidi stream for a server generating replies.
+    #
+    # N.B. gen_each_reply is a func(Enumerable<Requests>)
+    #
+    # It takes an enumerable of requests as an arg, in case there is a
+    # relationship between the stream of requests and the stream of replies.
+    #
+    # 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_on_server(gen_each_reply)
+      replys = gen_each_reply.call(each_queued_msg)
+      enq_th = start_write_loop(replys, is_client: false)
+      loop_th = start_read_loop
+      loop_th.join
+      enq_th.join
+    end
+
+    private
+
+    END_OF_READS = :end_of_reads
+    END_OF_WRITES = :end_of_writes
+
+    # each_queued_msg yields each message on this instances readq
+    #
+    # - messages are added to the readq by #read_loop
+    # - iteration ends when the instance itself is added
+    def each_queued_msg
+      return enum_for(:each_queued_msg) unless block_given?
+      count = 0
+      loop do
+        logger.debug("each_queued_msg: msg##{count}")
+        count += 1
+        req = @readq.pop
+        throw req if req.is_a? StandardError
+        break if req.equal?(END_OF_READS)
+        yield req
+      end
+    end
+
+    # during bidi-streaming, read the requests to send from a separate thread
+    # read so that read_loop does not block waiting for requests to read.
+    def start_write_loop(requests, is_client: true)
+      Thread.new do  # TODO: run on a thread pool
+        write_tag = Object.new
+        begin
+          count = 0
+          requests.each do |req|
+            count += 1
+            payload = @marshal.call(req)
+            @call.start_write(Core::ByteBuffer.new(payload), write_tag)
+            ev = @cq.pluck(write_tag, INFINITE_FUTURE)
+            begin
+              assert_event_type(ev, WRITE_ACCEPTED)
+            ensure
+              ev.close
+            end
+          end
+          if is_client
+            @call.writes_done(write_tag)
+            ev = @cq.pluck(write_tag, INFINITE_FUTURE)
+            begin
+              assert_event_type(ev, FINISH_ACCEPTED)
+            ensure
+              ev.close
+            end
+            logger.debug("bidi-client: sent #{count} reqs, waiting to finish")
+            ev = @cq.pluck(@finished_tag, INFINITE_FUTURE)
+            begin
+              assert_event_type(ev, FINISHED)
+            ensure
+              ev.close
+            end
+            logger.debug('bidi-client: finished received')
+          end
+        rescue StandardError => e
+          logger.warn('bidi: write_loop failed')
+          logger.warn(e)
+        end
+      end
+    end
+
+    # starts the read loop
+    def start_read_loop
+      Thread.new do
+        begin
+          read_tag = Object.new
+          count = 0
+
+          # queue the initial read before beginning the loop
+          loop do
+            logger.debug("waiting for read #{count}")
+            count += 1
+            @call.start_read(read_tag)
+            ev = @cq.pluck(read_tag, INFINITE_FUTURE)
+            begin
+              assert_event_type(ev, READ)
+
+              # handle the next event.
+              if ev.result.nil?
+                @readq.push(END_OF_READS)
+                logger.debug('done reading!')
+                break
+              end
+
+              # push the latest read onto the queue and continue reading
+              logger.debug("received req: #{ev.result}")
+              res = @unmarshal.call(ev.result.to_s)
+              @readq.push(res)
+            ensure
+              ev.close
+            end
+          end
+
+        rescue StandardError => e
+          logger.warn('bidi: read_loop failed')
+          logger.warn(e)
+          @readq.push(e)  # let each_queued_msg terminate with this error
+        end
+      end
+    end
+  end
+end

data/lib/grpc/generic/client_stub.rb

@@ -0,0 +1,413 @@
+# Copyright 2015, Google Inc.
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are
+# met:
+#
+#     * Redistributions of source code must retain the above copyright
+# notice, this list of conditions and the following disclaimer.
+#     * Redistributions in binary form must reproduce the above
+# copyright notice, this list of conditions and the following disclaimer
+# in the documentation and/or other materials provided with the
+# distribution.
+#     * Neither the name of Google Inc. nor the names of its
+# contributors may be used to endorse or promote products derived from
+# this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+# A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+# OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+# LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+require 'grpc/generic/active_call'
+require 'xray/thread_dump_signal_handler'
+
+# GRPC contains the General RPC module.
+module GRPC
+  # ClientStub represents an endpoint used to send requests to GRPC servers.
+  class ClientStub
+    include Core::StatusCodes
+
+    # Default deadline is 5 seconds.
+    DEFAULT_DEADLINE = 5
+
+    # Creates a new ClientStub.
+    #
+    # Minimally, a stub is created with the just the host of the gRPC service
+    # it wishes to access, e.g.,
+    #
+    # my_stub = ClientStub.new(example.host.com:50505)
+    #
+    # Any arbitrary keyword arguments are treated as channel arguments used to
+    # configure the RPC connection to the host.
+    #
+    # There are some specific keyword args that are not used to configure the
+    # channel:
+    #
+    # - :channel_override
+    # when present, this must be a pre-created GRPC::Channel.  If it's
+    # present the host and arbitrary keyword arg areignored, and the RPC
+    # connection uses this channel.
+    #
+    # - :deadline
+    # when present, this is the default deadline used for calls
+    #
+    # - :update_metadata
+    # when present, this a func that takes a hash and returns a hash
+    # it can be used to update metadata, i.e, remove, change or update
+    # amend metadata values.
+    #
+    # @param host [String] the host the stub connects to
+    # @param q [Core::CompletionQueue] used to wait for events
+    # @param channel_override [Core::Channel] a pre-created channel
+    # @param deadline [Number] the default deadline to use in requests
+    # @param creds [Core::Credentials] the channel
+    # @param update_metadata a func that updates metadata as described above
+    # @param kw [KeywordArgs]the channel arguments
+    def initialize(host, q,
+                   channel_override:nil,
+                   deadline: DEFAULT_DEADLINE,
+                   creds: nil,
+                   update_metadata: nil,
+                   **kw)
+      unless q.is_a? Core::CompletionQueue
+        fail(ArgumentError, 'not a CompletionQueue')
+      end
+      @queue = q
+
+      # set the channel instance
+      if !channel_override.nil?
+        ch = channel_override
+        fail(ArgumentError, 'not a Channel') unless ch.is_a? Core::Channel
+      else
+        if creds.nil?
+          ch = Core::Channel.new(host, kw)
+        elsif !creds.is_a?(Core::Credentials)
+          fail(ArgumentError, 'not a Credentials')
+        else
+          ch = Core::Channel.new(host, kw, creds)
+        end
+      end
+      @ch = ch
+
+      @update_metadata = nil
+      unless update_metadata.nil?
+        unless update_metadata.is_a? Proc
+          fail(ArgumentError, 'update_metadata is not a Proc')
+        end
+        @update_metadata = update_metadata
+      end
+
+      @host = host
+      @deadline = deadline
+    end
+
+    # request_response sends a request to a GRPC server, and returns the
+    # response.
+    #
+    # == Flow Control ==
+    # This is a blocking call.
+    #
+    # * it does not return until a response is received.
+    #
+    # * the requests is sent only when GRPC core's flow control allows it to
+    #   be sent.
+    #
+    # == Errors ==
+    # An RuntimeError is raised if
+    #
+    # * the server responds with a non-OK status
+    #
+    # * the deadline is exceeded
+    #
+    # == Return Value ==
+    #
+    # If return_op is false, the call returns the response
+    #
+    # If return_op is true, the call returns an Operation, calling execute
+    # on the Operation returns the response.
+    #
+    # == Keyword Args ==
+    #
+    # Unspecified keyword arguments are treated as metadata to be sent to the
+    # server.
+    #
+    # @param method [String] the RPC method to call on the GRPC server
+    # @param req [Object] the request sent to the server
+    # @param marshal [Function] f(obj)->string that marshals requests
+    # @param unmarshal [Function] f(string)->obj that unmarshals responses
+    # @param deadline [Numeric] (optional) the max completion time in seconds
+    # @param return_op [true|false] return an Operation if true
+    # @return [Object] the response received from the server
+    def request_response(method, req, marshal, unmarshal, deadline = nil,
+                         return_op: false, **kw)
+      c = new_active_call(method, marshal, unmarshal, deadline || @deadline)
+      md = @update_metadata.nil? ? kw : @update_metadata.call(kw.clone)
+      return c.request_response(req, **md) unless return_op
+
+      # return the operation view of the active_call; define #execute as a
+      # new method for this instance that invokes #request_response.
+      op = c.operation
+      op.define_singleton_method(:execute) do
+        c.request_response(req, **md)
+      end
+      op
+    end
+
+    # client_streamer sends a stream of requests to a GRPC server, and
+    # returns a single response.
+    #
+    # requests provides an 'iterable' of Requests. I.e. it follows Ruby's
+    # #each enumeration protocol. In the simplest case, requests will be an
+    # array of marshallable objects; in typical case it will be an Enumerable
+    # that allows dynamic construction of the marshallable objects.
+    #
+    # == Flow Control ==
+    # This is a blocking call.
+    #
+    # * it does not return until a response is received.
+    #
+    # * each requests is sent only when GRPC core's flow control allows it to
+    #   be sent.
+    #
+    # == Errors ==
+    # An RuntimeError is raised if
+    #
+    # * the server responds with a non-OK status
+    #
+    # * the deadline is exceeded
+    #
+    # == Return Value ==
+    #
+    # If return_op is false, the call consumes the requests and returns
+    # the response.
+    #
+    # If return_op is true, the call returns the response.
+    #
+    # == Keyword Args ==
+    #
+    # Unspecified keyword arguments are treated as metadata to be sent to the
+    # server.
+    #
+    # @param method [String] the RPC method to call on the GRPC server
+    # @param requests [Object] an Enumerable of requests to send
+    # @param marshal [Function] f(obj)->string that marshals requests
+    # @param unmarshal [Function] f(string)->obj that unmarshals responses
+    # @param deadline [Numeric] the max completion time in seconds
+    # @param return_op [true|false] return an Operation if true
+    # @return [Object|Operation] the response received from the server
+    def client_streamer(method, requests, marshal, unmarshal, deadline = nil,
+                        return_op: false, **kw)
+      c = new_active_call(method, marshal, unmarshal, deadline || @deadline)
+      md = @update_metadata.nil? ? kw : @update_metadata.call(kw.clone)
+      return c.client_streamer(requests, **md) unless return_op
+
+      # return the operation view of the active_call; define #execute as a
+      # new method for this instance that invokes #client_streamer.
+      op = c.operation
+      op.define_singleton_method(:execute) do
+        c.client_streamer(requests, **md)
+      end
+      op
+    end
+
+    # server_streamer sends one request to the GRPC server, which yields a
+    # stream of responses.
+    #
+    # responses provides an enumerator over the streamed responses, i.e. it
+    # follows Ruby's #each iteration protocol.  The enumerator blocks while
+    # waiting for each response, stops when the server signals that no
+    # further responses will be supplied.  If the implicit block is provided,
+    # it is executed with each response as the argument and no result is
+    # returned.
+    #
+    # == Flow Control ==
+    # This is a blocking call.
+    #
+    # * the request is sent only when GRPC core's flow control allows it to
+    #   be sent.
+    #
+    # * the request will not complete until the server sends the final
+    #   response followed by a status message.
+    #
+    # == Errors ==
+    # An RuntimeError is raised if
+    #
+    # * the server responds with a non-OK status when any response is
+    # * retrieved
+    #
+    # * the deadline is exceeded
+    #
+    # == Return Value ==
+    #
+    # if the return_op is false, the return value is an Enumerator of the
+    # results, unless a block is provided, in which case the block is
+    # executed with each response.
+    #
+    # if return_op is true, the function returns an Operation whose #execute
+    # method runs server streamer call. Again, Operation#execute either
+    # calls the given block with each response or returns an Enumerator of the
+    # responses.
+    #
+    # == Keyword Args ==
+    #
+    # Unspecified keyword arguments are treated as metadata to be sent to the
+    # server.
+    #
+    # @param method [String] the RPC method to call on the GRPC server
+    # @param req [Object] the request sent to the server
+    # @param marshal [Function] f(obj)->string that marshals requests
+    # @param unmarshal [Function] f(string)->obj that unmarshals responses
+    # @param deadline [Numeric] the max completion time in seconds
+    # @param return_op [true|false]return an Operation if true
+    # @param blk [Block] when provided, is executed for each response
+    # @return [Enumerator|Operation|nil] as discussed above
+    def server_streamer(method, req, marshal, unmarshal, deadline = nil,
+                        return_op: false, **kw, &blk)
+      c = new_active_call(method, marshal, unmarshal, deadline || @deadline)
+      md = @update_metadata.nil? ? kw : @update_metadata.call(kw.clone)
+      return c.server_streamer(req, **md, &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
+      op = c.operation
+      op.define_singleton_method(:execute) do
+        c.server_streamer(req, **md, &blk)
+      end
+      op
+    end
+
+    # bidi_streamer sends a stream of requests to the GRPC server, and yields
+    # a stream of responses.
+    #
+    # This method takes an Enumerable of requests, and returns and enumerable
+    # of responses.
+    #
+    # == requests ==
+    #
+    # requests provides an 'iterable' of Requests. I.e. it follows Ruby's
+    # #each enumeration protocol. In the simplest case, requests will be an
+    # array of marshallable objects; in typical case it will be an
+    # Enumerable that allows dynamic construction of the marshallable
+    # objects.
+    #
+    # == responses ==
+    #
+    # This is an enumerator of responses.  I.e, its #next method blocks
+    # waiting for the next response.  Also, if at any point the block needs
+    # to consume all the remaining responses, this can be done using #each or
+    # #collect.  Calling #each or #collect should only be done if
+    # the_call#writes_done has been called, otherwise the block will loop
+    # forever.
+    #
+    # == Flow Control ==
+    # This is a blocking call.
+    #
+    # * the call completes when the next call to provided block returns
+    # * [False]
+    #
+    # * the execution block parameters are two objects for sending and
+    #   receiving responses, each of which blocks waiting for flow control.
+    #   E.g, calles to bidi_call#remote_send will wait until flow control
+    #   allows another write before returning; and obviously calls to
+    #   responses#next block until the next response is available.
+    #
+    # == Termination ==
+    #
+    # As well as sending and receiving messages, the block passed to the
+    # function is also responsible for:
+    #
+    # * calling bidi_call#writes_done to indicate no further reqs will be
+    #   sent.
+    #
+    # * returning false if once the bidi stream is functionally completed.
+    #
+    # Note that response#next will indicate that there are no further
+    # responses by throwing StopIteration, but can only happen either
+    # if bidi_call#writes_done is called.
+    #
+    # To terminate the RPC correctly the block:
+    #
+    # * must call bidi#writes_done and then
+    #
+    #    * either return false as soon as there is no need for other responses
+    #
+    #    * loop on responses#next until no further responses are available
+    #
+    # == Errors ==
+    # An RuntimeError is raised if
+    #
+    # * the server responds with a non-OK status when any response is
+    # * retrieved
+    #
+    # * the deadline is exceeded
+    #
+    #
+    # == Keyword Args ==
+    #
+    # Unspecified keyword arguments are treated as metadata to be sent to the
+    # server.
+    #
+    # == Return Value ==
+    #
+    # if the return_op is false, the return value is an Enumerator of the
+    # results, unless a block is provided, in which case the block is
+    # executed with each response.
+    #
+    # if return_op is true, the function returns an Operation whose #execute
+    # method runs the Bidi call. Again, Operation#execute either calls a
+    # given block with each response or returns an Enumerator of the
+    # responses.
+    #
+    # @param method [String] the RPC method to call on the GRPC server
+    # @param requests [Object] an Enumerable of requests to send
+    # @param marshal [Function] f(obj)->string that marshals requests
+    # @param unmarshal [Function] f(string)->obj that unmarshals responses
+    # @param deadline [Numeric] (optional) the max completion time in seconds
+    # @param blk [Block] when provided, is executed for each response
+    # @param return_op [true|false] return an Operation if true
+    # @return [Enumerator|nil|Operation] as discussed above
+    def bidi_streamer(method, requests, marshal, unmarshal, deadline = nil,
+                      return_op: false, **kw, &blk)
+      c = new_active_call(method, marshal, unmarshal, deadline || @deadline)
+      md = @update_metadata.nil? ? kw : @update_metadata.call(kw.clone)
+      return c.bidi_streamer(requests, **md, &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
+      op = c.operation
+      op.define_singleton_method(:execute) do
+        c.bidi_streamer(requests, **md, &blk)
+      end
+      op
+    end
+
+    private
+
+    # Creates a new active stub
+    #
+    # @param ch [GRPC::Channel] the channel used to create the stub.
+    # @param marshal [Function] f(obj)->string that marshals requests
+    # @param unmarshal [Function] f(string)->obj that unmarshals responses
+    # @param deadline [TimeConst]
+    def new_active_call(ch, marshal, unmarshal, deadline = nil)
+      absolute_deadline = Core::TimeConsts.from_relative_time(deadline)
+      # It should be OK to to pass the hostname:port to create_call, but at
+      # the moment this fails a security check.  This will be corrected.
+      #
+      # TODO: # remove this after create_call is updated
+      host = @host.split(':')[0]
+      call = @ch.create_call(ch, host, absolute_deadline)
+      ActiveCall.new(call, @queue, marshal, unmarshal, absolute_deadline,
+                     started: false)
+    end
+  end
+end