gapic-common 0.12.0 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0c3c4ee7ceef8f5caf7cf84304f6601ed730abd75089f3d7e5305bf2efaefed7
-  data.tar.gz: 424864e640f307cbfc00829fdcdcfd83899032b4babd9eabf5cbfdbf827b3da2
+  metadata.gz: 5b5964ec91020c76501e2424be598b345a114a16515fe209135e46f552100d4e
+  data.tar.gz: 4a08e08fe15b6c6d6a3ad3097895a7d01bcfe3377f1392946a0cfe671ca97fdf
 SHA512:
-  metadata.gz: fd2c71656a97d36f9f92f64c56cde7e6f9d8b63afa9602c12bbc0f9f8bfcf775e24729893839fc498de2e0629e592fcc56890d614d8ed8c0989c11d3dc11872c
-  data.tar.gz: c6bb5cdef2186ba06191504fcf5d04ae8aac41820d03da16695d9d4e1a891ff5bdad8338598c339c5963ae9ef6816c457d15a28f26e92e4cc72b91b6a3d39d1a
+  metadata.gz: a0270a8d4933fda1f6297233f3465ae4fed20d34ebbf4bb766f228fe13746b5508c97179eb7c0b763d104c52079f59765b514c32a1d6cb2d61196791f007595a
+  data.tar.gz: 437633278a8640eee28a975c7821270b11c2127c72970e0259c29b5b643db37b8d394ac5ae1cd80cb367e10c1384311cc018e0a276804dfda7d8a91f9fffb13a

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Release History
 
+### 0.13.0 (2022-10-26)
+
+#### Features
+
+* Implement server-side streaming support for REST calls in gapic-common ([#826](https://github.com/googleapis/gapic-generator-ruby/issues/826)) 
+
 ### 0.12.0 (2022-09-15)
 
 #### Features

data/lib/gapic/common/version.rb

@@ -14,6 +14,6 @@
 
 module Gapic
   module Common
-    VERSION = "0.12.0".freeze
+    VERSION = "0.13.0".freeze
   end
 end

data/lib/gapic/rest/client_stub.rb

@@ -127,8 +127,10 @@ module Gapic
       # @param params [Hash] query string parameters for the request
       # @param options [::Gapic::CallOptions,Hash] gapic options to be applied
       #     to the REST call. Currently only timeout and headers are supported.
+      # @param is_server_streaming [Boolean] flag if method is streaming
+      # @yieldparam chunk [String] The chunk of data received during server streaming.
       # @return [Faraday::Response]
-      def make_http_request verb, uri:, body:, params:, options:
+      def make_http_request verb, uri:, body:, params:, options:, is_server_streaming: false
         if @numeric_enums && (!params.key?("$alt") || params["$alt"] == "json")
           params = params.merge({ "$alt" => "json;enum-encoding=int" })
         end
@@ -138,6 +140,11 @@ module Gapic
           req.body = body unless body.nil?
           req.headers = req.headers.merge options.metadata
           req.options.timeout = options.timeout if options.timeout&.positive?
+          if is_server_streaming
+            req.options.on_data = proc do |chunk, _overall_received_bytes|
+              yield chunk
+            end
+          end
         end
       end
     end

data/lib/gapic/rest/server_stream.rb

@@ -0,0 +1,101 @@
+# Copyright 2022 Google LLC
+#
+# 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
+#
+#     https://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 "json"
+
+module Gapic
+  module Rest
+    ##
+    # A class to provide the Enumerable interface to the response of a REST server-streaming dmethod.
+    #
+    # ServerStream provides the enumerations over the individual response messages within the stream.
+    #
+    # @example normal iteration over resources.
+    #   server_stream.each { |response| puts response }
+    #
+    class ServerStream
+      include Enumerable
+
+      ##
+      # Initializes ServerStream object.
+      #
+      # @param message_klass [Class]
+      # @param json_enumerator [Enumerator<String>]
+      def initialize message_klass, json_enumerator
+        @json_enumerator = json_enumerator
+        @obj = ""
+        @message_klass = message_klass
+        @ready_objs = [] # List of strings
+      end
+
+      ##
+      # Iterate over JSON objects in the streamed response.
+      #
+      # @yield [Object] Gives one complete Message object.
+      #
+      # @return [Enumerator] if no block is provided
+      #
+      def each
+        return enum_for :each unless block_given?
+
+        loop do
+          while @ready_objs.length.zero?
+            begin
+              chunk = @json_enumerator.next
+              next unless chunk
+              next_json! chunk
+            rescue StopIteration
+              dangling_content = @obj.strip
+              error_expl = "Dangling content left after iterating through the stream. " \
+                           "This means that not all content was received or parsed correctly. " \
+                           "It is likely a result of server or network error."
+              error_text = "#{error_expl}\n Content left unparsed: #{dangling_content}"
+
+              raise Gapic::Common::Error, error_text unless dangling_content.empty?
+              return
+            end
+          end
+          yield @message_klass.decode_json @ready_objs.shift, ignore_unknown_fields: true
+        end
+      end
+
+      private
+
+      ##
+      # Builds the next JSON object of the server stream from chunk.
+      #
+      # @param chunk [String] Contains (partial) JSON object
+      #
+      def next_json! chunk
+        chunk.chars.each do |char|
+          # Invariant: @obj is always either a part of a single JSON object or the entire JSON object.
+          # Hence, it's safe to strip whitespace, commans and array brackets. These characters
+          # are only added before @obj is a complete JSON object and essentially can be flushed.
+          next if @obj.empty? && char != "{"
+          @obj += char
+          next unless char == "}"
+          begin
+            # Two choices here: append a Ruby object into
+            # ready_objs or a string. Going with the latter here.
+            JSON.parse @obj
+            @ready_objs.append @obj
+            @obj = ""
+          rescue JSON::ParserError
+            next
+          end
+        end
+      end
+    end
+  end
+end

data/lib/gapic/rest/threaded_enumerator.rb

@@ -0,0 +1,71 @@
+# Copyright 2022 Google LLC
+#
+# 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
+#
+#     https://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.
+
+
+module Gapic
+  module Rest
+    ##
+    # @private
+    # A class to provide the Enumerable interface to an incoming stream of data.
+    #
+    # ThreadedEnumerator provides the enumerations over the individual chunks of data received from the server.
+    #
+    # @example normal iteration over resources.
+    #   chunk = threaded_enumerator.next
+    #
+    # @attribute [r] in_q
+    #   @return [Queue] Input queue.
+    # @attribute [r] out_q
+    #   @return [Queue] Output queue.
+    class ThreadedEnumerator
+      attr_reader :in_q
+      attr_reader :out_q
+
+      # Spawns a new thread and does appropriate clean-up
+      # in case thread fails. Propagates exception back
+      # to main thread.
+      #
+      # @yieldparam in_q[Queue] input queue
+      # @yieldparam out_q[Queue] output queue
+      def initialize
+        @in_q = Queue.new
+        @out_q = Queue.new
+
+        Thread.new do
+          yield @in_q, @out_q
+        rescue StandardError => e
+          @out_q.push e
+        end
+      end
+
+      def next
+        @in_q.enq :next
+        chunk = @out_q.deq
+
+        if chunk.is_a? StandardError
+          @out_q.close
+          @in_q.close
+          raise chunk
+        end
+
+        if chunk.nil?
+          @out_q.close
+          @in_q.close
+          raise StopIteration
+        end
+        chunk
+      end
+    end
+  end
+end

data/lib/gapic/rest.rb

@@ -27,4 +27,6 @@ require "gapic/rest/faraday_middleware"
 require "gapic/rest/grpc_transcoder"
 require "gapic/rest/operation"
 require "gapic/rest/paged_enumerable"
+require "gapic/rest/server_stream"
+require "gapic/rest/threaded_enumerator"
 require "json"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: gapic-common
 version: !ruby/object:Gem::Version
-  version: 0.12.0
+  version: 0.13.0
 platform: ruby
 authors:
 - Google API Authors
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2022-09-16 00:00:00.000000000 Z
+date: 2022-10-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -314,6 +314,8 @@ files:
 - lib/gapic/rest/grpc_transcoder/http_binding.rb
 - lib/gapic/rest/operation.rb
 - lib/gapic/rest/paged_enumerable.rb
+- lib/gapic/rest/server_stream.rb
+- lib/gapic/rest/threaded_enumerator.rb
 - lib/gapic/stream_input.rb
 homepage: https://github.com/googleapis/gapic-generator-ruby
 licenses: