gapic-common 0.10.0 → 0.15.0

data/lib/gapic/rest/client_stub.rb

@@ -32,15 +32,17 @@ module Gapic
       # @param credentials [Google::Auth::Credentials]
       #   Credentials to send with calls in form of a googleauth credentials object.
       #   (see the [googleauth docs](https://googleapis.dev/ruby/googleauth/latest/index.html))
+      # @param numeric_enums [Boolean] Whether to signal the server to JSON-encode enums as ints
       #
       # @yield [Faraday::Connection]
       #
-      def initialize endpoint:, credentials:
+      def initialize endpoint:, credentials:, numeric_enums: false
         @endpoint = endpoint
         @endpoint = "https://#{endpoint}" unless /^https?:/.match? endpoint
         @endpoint = @endpoint.sub %r{/$}, ""
 
         @credentials = credentials
+        @numeric_enums = numeric_enums
 
         @connection = Faraday.new url: @endpoint do |conn|
           conn.headers = { "Content-Type" => "application/json" }
@@ -58,8 +60,8 @@ module Gapic
       #
       # @param uri [String] uri to send this request to
       # @param params [Hash] query string parameters for the request
-      # @param options [::Gapic::CallOptions] gapic options to be applied to the REST call.
-      #   Currently only timeout and headers are supported.
+      # @param options [::Gapic::CallOptions,Hash] gapic options to be applied
+      #     to the REST call. Currently only timeout and headers are supported.
       # @return [Faraday::Response]
       def make_get_request uri:, params: {}, options: {}
         make_http_request :get, uri: uri, body: nil, params: params, options: options
@@ -70,8 +72,8 @@ module Gapic
       #
       # @param uri [String] uri to send this request to
       # @param params [Hash] query string parameters for the request
-      # @param options [::Gapic::CallOptions] gapic options to be applied to the REST call.
-      #   Currently only timeout and headers are supported.
+      # @param options [::Gapic::CallOptions,Hash] gapic options to be applied
+      #     to the REST call. Currently only timeout and headers are supported.
       # @return [Faraday::Response]
       def make_delete_request uri:, params: {}, options: {}
         make_http_request :delete, uri: uri, body: nil, params: params, options: options
@@ -83,8 +85,8 @@ module Gapic
       # @param uri [String] uri to send this request to
       # @param body [String] a body to send with the request, nil for requests without a body
       # @param params [Hash] query string parameters for the request
-      # @param options [::Gapic::CallOptions] gapic options to be applied to the REST call.
-      #   Currently only timeout and headers are supported.
+      # @param options [::Gapic::CallOptions,Hash] gapic options to be applied
+      #     to the REST call. Currently only timeout and headers are supported.
       # @return [Faraday::Response]
       def make_patch_request uri:, body:, params: {}, options: {}
         make_http_request :patch, uri: uri, body: body, params: params, options: options
@@ -96,8 +98,8 @@ module Gapic
       # @param uri [String] uri to send this request to
       # @param body [String] a body to send with the request, nil for requests without a body
       # @param params [Hash] query string parameters for the request
-      # @param options [::Gapic::CallOptions] gapic options to be applied to the REST call.
-      #   Currently only timeout and headers are supported.
+      # @param options [::Gapic::CallOptions,Hash] gapic options to be applied
+      #     to the REST call. Currently only timeout and headers are supported.
       # @return [Faraday::Response]
       def make_post_request uri:, body: nil, params: {}, options: {}
         make_http_request :post, uri: uri, body: body, params: params, options: options
@@ -109,8 +111,8 @@ module Gapic
       # @param uri [String] uri to send this request to
       # @param body [String] a body to send with the request, nil for requests without a body
       # @param params [Hash] query string parameters for the request
-      # @param options [::Gapic::CallOptions] gapic options to be applied to the REST call.
-      #   Currently only timeout and headers are supported.
+      # @param options [::Gapic::CallOptions,Hash] gapic options to be applied
+      #     to the REST call. Currently only timeout and headers are supported.
       # @return [Faraday::Response]
       def make_put_request uri:, body: nil, params: {}, options: {}
         make_http_request :put, uri: uri, body: body, params: params, options: options
@@ -123,17 +125,84 @@ module Gapic
       # @param uri [String] uri to send this request to
       # @param body [String, nil] a body to send with the request, nil for requests without a body
       # @param params [Hash] query string parameters for the request
-      # @param options [::Gapic::CallOptions] gapic options to be applied to the REST call.
-      #   Currently only timeout and headers are supported.
+      # @param options [::Gapic::CallOptions,Hash] gapic options to be applied to the REST call.
+      # @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, &block
+        # Converts hash and nil to an options object
+        options = ::Gapic::CallOptions.new(**options.to_h) unless options.is_a? ::Gapic::CallOptions
+        deadline = calculate_deadline options
+        retried_exception = nil
+        next_timeout = get_timeout deadline
+
+        begin
+          base_make_http_request(verb,
+                                 uri: uri,
+                                 body: body,
+                                 params: params,
+                                 metadata: options.metadata,
+                                 timeout: next_timeout,
+                                 is_server_streaming: is_server_streaming,
+                                 &block)
+        rescue ::Faraday::Error => e
+          next_timeout = get_timeout deadline
+
+          if next_timeout&.positive? && options.retry_policy.call(e)
+            retried_exception = e
+            retry
+          end
+
+          unless next_timeout&.positive?
+            raise Gapic::GRPC::DeadlineExceededError.new e.message, root_cause: retried_exception
+          end
+
+          raise e
+        end
+      end
+
+      private
+
+      ##
+      # @private
+      # Sends a http request via Faraday
+      # @param verb [Symbol] http verb
+      # @param uri [String] uri to send this request to
+      # @param body [String, nil] a body to send with the request, nil for requests without a body
+      # @param params [Hash] query string parameters for the request
+      # @param metadata [Hash] additional headers for the request
+      # @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 base_make_http_request verb, uri:, body:, params:, metadata:, timeout:, is_server_streaming: false
+        if @numeric_enums && (!params.key?("$alt") || params["$alt"] == "json")
+          params = params.merge({ "$alt" => "json;enum-encoding=int" })
+        end
+
         @connection.send verb, uri do |req|
           req.params = params if params.any?
           req.body = body unless body.nil?
-          req.headers = req.headers.merge options.metadata
-          req.options.timeout = options.timeout if options.timeout&.positive?
+          req.headers = req.headers.merge metadata
+          req.options.timeout = timeout if timeout&.positive?
+          if is_server_streaming
+            req.options.on_data = proc do |chunk, _overall_received_bytes|
+              yield chunk
+            end
+          end
         end
       end
+
+      def calculate_deadline options
+        return if options.timeout.nil?
+        return if options.timeout.negative?
+
+        Process.clock_gettime(Process::CLOCK_MONOTONIC) + options.timeout
+      end
+
+      def get_timeout deadline
+        return if deadline.nil?
+        deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
     end
   end
 end

data/lib/gapic/rest/error.rb

@@ -19,16 +19,30 @@ module Gapic
   module Rest
     # Gapic REST exception class
     class Error < ::Gapic::Common::Error
-      # @return [Integer] the http status code for the error
+      # @return [Integer, nil] the http status code for the error
       attr_reader :status_code
+      # @return [Object, nil] the text representation of status as parsed from the response body
+      attr_reader :status
+      # @return [Object, nil] the details as parsed from the response body
+      attr_reader :details
+      # @return [Object, nil] the headers of the REST error
+      attr_reader :headers
+      # The Cloud error wrapper expect to see a `header` property
+      alias header headers
 
       ##
       # @param message [String, nil] error message
       # @param status_code [Integer, nil] HTTP status code of this error
+      # @param status [String, nil] The text representation of status as parsed from the response body
+      # @param details [Object, nil] Details data of this error
+      # @param headers [Object, nil] Http headers data of this error
       #
-      def initialize message, status_code
-        @status_code = status_code
+      def initialize message, status_code, status: nil, details: nil, headers: nil
         super message
+        @status_code = status_code
+        @status = status
+        @details = details
+        @headers = headers
       end
 
       class << self
@@ -37,36 +51,85 @@ module Gapic
         # it tries to parse and set a detailed message and an error code from
         # from the Google Cloud's response body
         #
+        # @param err [Faraday::Error] the Faraday error to wrap
+        #
+        # @return [ Gapic::Rest::Error]
         def wrap_faraday_error err
           message = err.message
           status_code = err.response_status
+          status = nil
+          details = nil
+          headers = err.response_headers
 
           if err.response_body
-            msg, code = try_parse_from_body err.response_body
+            msg, code, status, details = try_parse_from_body err.response_body
             message = "An error has occurred when making a REST request: #{msg}" unless msg.nil?
             status_code = code unless code.nil?
           end
 
-          Gapic::Rest::Error.new message, status_code
+          Gapic::Rest::Error.new message, status_code, status: status, details: details, headers: headers
         end
 
         private
 
         ##
+        # @private
         # Tries to get the error information from the JSON bodies
         #
         # @param body_str [String]
-        # @return [Array(String, String)]
+        # @return [Array(String, String, String, String)]
         def try_parse_from_body body_str
           body = JSON.parse body_str
-          return [nil, nil] unless body && body["error"].is_a?(Hash)
 
-          message = body["error"]["message"]
-          code = body["error"]["code"]
+          unless body.is_a?(::Hash) && body&.key?("error") && body["error"].is_a?(::Hash)
+            return [nil, nil, nil, nil]
+          end
+          error = body["error"]
+
+          message = error["message"] if error.key? "message"
+          code = error["code"] if error.key? "code"
+          status = error["status"] if error.key? "status"
+
+          details = parse_details error["details"] if error.key? "details"
 
-          [message, code]
+          [message, code, status, details]
         rescue JSON::ParserError
-          [nil, nil]
+          [nil, nil, nil, nil]
+        end
+
+        ##
+        # @private
+        # Parses the details data, trying to extract the Protobuf.Any objects
+        # from it, if it's an array of hashes. Otherwise returns it as is.
+        #
+        # @param details [Object, nil] the details object
+        #
+        # @return [Object, nil]
+        def parse_details details
+          # For rest errors details will contain json representations of `Protobuf.Any`
+          # decoded into hashes. If it's not an array, of its elements are not hashes,
+          # it's some other case
+          return details unless details.is_a? ::Array
+
+          details.map do |detail_instance|
+            next detail_instance unless detail_instance.is_a? ::Hash
+            # Next, parse detail_instance into a Proto message.
+            # There are three possible issues for the JSON->Any->message parsing
+            # - json decoding fails
+            # - the json belongs to a proto message type we don't know about
+            # - any unpacking fails
+            # If we hit any of these three issues we'll just return the original hash
+            begin
+              any = ::Google::Protobuf::Any.decode_json detail_instance.to_json
+              klass = ::Google::Protobuf::DescriptorPool.generated_pool.lookup(any.type_name)&.msgclass
+              next detail_instance if klass.nil?
+              unpack = any.unpack klass
+              next detail_instance if unpack.nil?
+              unpack
+            rescue ::Google::Protobuf::ParseError
+              detail_instance
+            end
+          end.compact
         end
       end
     end

data/lib/gapic/rest/faraday_middleware.rb

@@ -18,22 +18,43 @@ module Gapic
     # Registers the middleware with Faraday
     module FaradayMiddleware
       ##
+      # @private
       # Request middleware that constructs the Authorization HTTP header
       # using ::Google::Auth::Credentials
       #
       class GoogleAuthorization < Faraday::Middleware
         ##
+        # @private
         # @param app [#call]
-        # @param credentials [::Google::Auth::Credentials]
+        # @param credentials [Google::Auth::Credentials, Signet::OAuth2::Client, Symbol, Proc]
+        #   Provides the means for authenticating requests made by
+        #   the client. This parameter can be many types:
+        #   * A `Google::Auth::Credentials` uses a the properties of its represented keyfile for authenticating requests
+        #     made by this client.
+        #   * A `Signet::OAuth2::Client` object used to apply the OAuth credentials.
+        #   * A `Proc` will be used as an updater_proc for the auth token.
+        #   * A `Symbol` is treated as a signal that authentication is not required.
+        #
         def initialize app, credentials
-          @credentials = credentials
+          @updater_proc = case credentials
+                          when Symbol
+                            credentials
+                          else
+                            updater_proc = credentials.updater_proc if credentials.respond_to? :updater_proc
+                            updater_proc ||= credentials if credentials.is_a? Proc
+                            raise ArgumentError, "invalid credentials (#{credentials.class})" if updater_proc.nil?
+                            updater_proc
+                          end
           super app
         end
 
+        # @private
         # @param env [Faraday::Env]
         def call env
-          auth_hash = @credentials.client.apply({})
-          env.request_headers["Authorization"] = auth_hash[:authorization]
+          unless @updater_proc.is_a? Symbol
+            auth_hash = @updater_proc.call({})
+            env.request_headers["Authorization"] = auth_hash[:authorization]
+          end
 
           @app.call env
         end

data/lib/gapic/rest/grpc_transcoder/http_binding.rb

@@ -15,6 +15,7 @@
 module Gapic
   module Rest
     class GrpcTranscoder
+      ##
       # @private
       # A single binding for GRPC-REST transcoding of a request
       # It includes a uri template with bound field parameters, a HTTP method type,
@@ -25,7 +26,8 @@ module Gapic
       # @attribute [r] template
       #   @return [String] The URI template for the request.
       # @attribute [r] field_bindings
-      #   @return [Array<FieldBinding>] The field bindings for the URI template variables.
+      #   @return [Array<Gapic::Rest::GrpcTranscoder::HttpBinding::FieldBinding>]
+      #     The field bindings for the URI template variables.
       # @attribute [r] body
       #   @return [String] The body template for the request.
       class HttpBinding
@@ -41,6 +43,57 @@ module Gapic
           @body = body
         end
 
+        ##
+        # @private
+        # Creates a new HttpBinding.
+        #
+        # @param uri_method [Symbol] The rest verb for the binding.
+        # @param uri_template [String] The string with uri template for the binding.
+        #   This string will be expanded with the parameters from variable bindings.
+        # @param matches [Array<Array>] Variable bindings in an array. Every element
+        #   of the array is an [Array] triplet, where:
+        #   - the first element is a [String] field path (e.g. `foo.bar`) in the request
+        #     to bind to
+        #   - the second element is a [Regexp] to match the field value
+        #   - the third element is a [Boolean] whether the slashes in the field value
+        #     should be preserved (as opposed to escaped) when expanding the uri template.
+        # @param body [String, Nil] The body template, e.g. `*` or a field path.
+        #
+        # @return [Gapic::Rest::GrpcTranscoder::HttpBinding] The new binding.
+        def self.create_with_validation uri_method:, uri_template:, matches: [], body: nil
+          template = uri_template
+
+          matches.each do |name, _regex, _preserve_slashes|
+            unless uri_template =~ /({#{Regexp.quote name}})/
+              err_msg = "Binding configuration is incorrect: missing parameter in the URI template.\n" \
+                        "Parameter `#{name}` is specified for matching but there is no corresponding parameter " \
+                        "`{#{name}}` in the URI template."
+              raise ::Gapic::Common::Error, err_msg
+            end
+
+            template = template.gsub "{#{name}}", ""
+          end
+
+          if template =~ /{([a-zA-Z_.]+)}/
+            err_name = Regexp.last_match[1]
+            err_msg = "Binding configuration is incorrect: missing match configuration.\n" \
+                      "Parameter `{#{err_name}}` is specified in the URI template but there is no " \
+                      "corresponding match configuration for `#{err_name}`."
+            raise ::Gapic::Common::Error, err_msg
+          end
+
+          if body&.include? "."
+            raise ::Gapic::Common::Error,
+                  "Provided body template `#{body}` points to a field in a sub-message. This is not supported."
+          end
+
+          field_bindings = matches.map do |name, regex, preserve_slashes|
+            HttpBinding::FieldBinding.new name, regex, preserve_slashes
+          end
+
+          HttpBinding.new uri_method, uri_template, field_bindings, body
+        end
+
         # A single binding for a field of a request message.
         # @attribute [r] field_path
         #   @return [String] The path of the bound field, e.g. `foo.bar`.

data/lib/gapic/rest/grpc_transcoder.rb

@@ -44,36 +44,11 @@ module Gapic
       #
       # @return [Gapic::Rest::GrpcTranscoder] The updated transcoder.
       def with_bindings uri_method:, uri_template:, matches: [], body: nil
-        template = uri_template
-
-        matches.each do |name, _regex, _preserve_slashes|
-          unless uri_template =~ /({#{Regexp.quote name}})/
-            err_msg = "Binding configuration is incorrect: missing parameter in the URI template.\n" \
-                      "Parameter `#{name}` is specified for matching but there is no corresponding parameter" \
-                      " `{#{name}}` in the URI template."
-            raise ::Gapic::Common::Error, err_msg
-          end
-
-          template = template.gsub "{#{name}}", ""
-        end
-
-        if template =~ /{([a-zA-Z_.]+)}/
-          err_name = Regexp.last_match[1]
-          err_msg = "Binding configuration is incorrect: missing match configuration.\n" \
-                    "Parameter `{#{err_name}}` is specified in the URI template but there is no" \
-                    " corresponding match configuration for `#{err_name}`."
-          raise ::Gapic::Common::Error, err_msg
-        end
-
-        if body&.include? "."
-          raise ::Gapic::Common::Error,
-                "Provided body template `#{body}` points to a field in a sub-message. This is not supported."
-        end
-
-        field_bindings = matches.map do |name, regex, preserve_slashes|
-          HttpBinding::FieldBinding.new name, regex, preserve_slashes
-        end
-        GrpcTranscoder.new @bindings + [HttpBinding.new(uri_method, uri_template, field_bindings, body)]
+        binding = HttpBinding.create_with_validation(uri_method: uri_method,
+                                                     uri_template: uri_template,
+                                                     matches: matches,
+                                                     body: body)
+        GrpcTranscoder.new @bindings + [binding]
       end
 
       ##
@@ -108,12 +83,9 @@ module Gapic
           uri_values = bind_uri_values! http_binding, request_hash
           next if uri_values.any? { |_, value| value.nil? }
 
-          if http_binding.body && http_binding.body != "*"
-            # Note that the body template can only point to a top-level field,
-            # so there is no need to split the path.
-            body_binding_camel = camel_name_for http_binding.body
-            next unless request_hash.key? body_binding_camel
-          end
+          # Note that the body template can only point to a top-level field,
+          # so there is no need to split the path.
+          next if http_binding.body && http_binding.body != "*" && !(request.respond_to? http_binding.body.to_sym)
 
           method = http_binding.method
           uri = expand_template http_binding.template, uri_values
@@ -145,11 +117,7 @@ module Gapic
           field_value = extract_scalar_value! request_hash, field_path_camel, field_binding.regex
 
           if field_value
-            field_value = if field_binding.preserve_slashes
-                            field_value.split("/").map { |segment| percent_escape(segment) }.join("/")
-                          else
-                            percent_escape field_value
-                          end
+            field_value = field_value.split("/").map { |segment| percent_escape(segment) }.join("/")
           end
 
           [field_binding.field_path, field_value]
@@ -186,9 +154,15 @@ module Gapic
           #
           # The `request_hash_without_uri` at this point was mutated to delete these fields.
           #
-          # Note that the body template can only point to a top-level field
-          request_hash_without_uri.delete camel_name_for body_template
-          body = request.send(body_template.to_sym).to_json(emit_defaults: true)
+          # Note 1: body template can only point to a top-level field.
+          # Note 2: The field that body template points to can be null, in which case
+          # an empty string should be sent. E.g. `Compute.Projects.SetUsageExportBucket`.
+          request_body_field = request.send body_template.to_sym if request.respond_to? body_template.to_sym
+          if request_body_field
+            request_hash_without_uri.delete camel_name_for body_template
+            body = request_body_field.to_json emit_defaults: true
+          end
+
           query_params = build_query_params request_hash_without_uri
         else
           query_params = build_query_params request_hash_without_uri

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,72 @@
+# 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
+          @out_q.enq nil
+        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