gapic-common 0.4.1 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 407061663f535d2c1d6e4d156b63dc27d7e550a4e965574861d27bfb88abe51b
-  data.tar.gz: c009e26d53339c5be07d223a61db173fb2897dafe5fcd63ac1e9a72e9f89fa93
+  metadata.gz: 60a01e31b774ce16ba39c630c8a9e8271c18ae8a89de1bd6feddeff2c5027983
+  data.tar.gz: c173c35d2eeb3cbd1c7cf47769cba71deb464a95766a1939858027c22d766ed8
 SHA512:
-  metadata.gz: 305e7cdee55f87e69c966019e62b973247de377503ff6b45a42be1dcd9ac55e1a68c54da35e718c58938d5a490b5ce5bcaf8485b9ad980ae46dbdc5f83c65987
-  data.tar.gz: bc81ef2c7515b2630dd7e06b1ddc37e160ecc08b733a0670e8d42a3a48e41fadbcddf5d8facf3411cdc129935dd10a845edae7c38de38d7e28b0545bdd7a4b06
+  metadata.gz: ee846671cdebbd8d02bd0679f8e789005ea138d9cfcf10cbfac4c5e98b90e47e41a5abfbf165c0002276b8dfb6a5fe97924761eac02c8d3aa36c077a28f581da
+  data.tar.gz: a77e8a6feddae4cdb13859739d29901184cba2aa8431132cd4f3ebf5289434cd3b53289aaccca3f5eeaa648e4d988cb65f15a6c3cf7ba463e63e5a94649d5aaa

data/CHANGELOG.md

@@ -1,6 +1,20 @@
 # Release History
 
+### 0.5.0 / 2021-06-15
+
+* Provide a way to create `x-goog-api-client` headers with rest library version and/or without grpc library version
+
+### 0.4.3 / 2021-06-10
+
+* Fix file permissions.
+
+### 0.4.2 / 2021-06-07
+
+* Expand googleauth dependency to include 1.x
+* Add a REST PUT method helper to Gapic::Rest.
+
 ### 0.4.1 / 2021-04-15
+
 * Provide a default value for the 'body' in the REST POST method in Gapic::Rest.
 
 ### 0.4.0 / 2021-02-23

data/CONTRIBUTING.md

@@ -8,7 +8,7 @@ just a few small guidelines you need to follow.
 Contributions to this project must be accompanied by a Contributor License
 Agreement. You (or your employer) retain the copyright to your contribution;
 this simply gives us permission to use and redistribute your contributions as
-part of the project. Head over to <https://cla.developers.google.com/> to see
+part of the project. Head over to https://cla.developers.google.com/ to see
 your current agreements on file or to sign a new one.
 
 You generally only need to submit a CLA once, so if you've already submitted one

data/lib/gapic/common/version.rb

@@ -14,6 +14,6 @@
 
 module Gapic
   module Common
-    VERSION = "0.4.1".freeze
+    VERSION = "0.6.0".freeze
   end
 end

data/lib/gapic/headers.rb

@@ -26,17 +26,27 @@ module Gapic
     # @param gax_version [String] The Gapic version. Defaults to `Gapic::Common::VERSION`.
     # @param gapic_version [String] The Gapic version.
     # @param grpc_version [String] The GRPC version. Defaults to `GRPC::VERSION`.
-    def self.x_goog_api_client ruby_version: nil, lib_name: nil, lib_version: nil,
-                               gax_version: nil, gapic_version: nil, grpc_version: nil
+    # @param rest_version [String] The Rest Library (Faraday) version. Defaults to `Faraday::VERSION`.
+    # @param transports_version_send [Array] Which transports to send versions for.
+    #   Allowed values to contain are:
+    #     `:grpc` to send the GRPC library version (if defined)
+    #     `:rest` to send the REST library version (if defined)
+    #   Defaults to `[:grpc]`
+    def self.x_goog_api_client ruby_version: nil, lib_name: nil, lib_version: nil, gax_version: nil,
+                               gapic_version: nil, grpc_version: nil, rest_version: nil,
+                               transports_version_send: [:grpc]
+
       ruby_version ||= ::RUBY_VERSION
       gax_version  ||= ::Gapic::Common::VERSION
       grpc_version ||= ::GRPC::VERSION if defined? ::GRPC
+      rest_version ||= ::Faraday::VERSION if defined? ::Faraday
 
       x_goog_api_client_header = ["gl-ruby/#{ruby_version}"]
       x_goog_api_client_header << "#{lib_name}/#{lib_version}" if lib_name
       x_goog_api_client_header << "gax/#{gax_version}"
       x_goog_api_client_header << "gapic/#{gapic_version}" if gapic_version
-      x_goog_api_client_header << "grpc/#{grpc_version}" if grpc_version
+      x_goog_api_client_header << "grpc/#{grpc_version}" if grpc_version && transports_version_send.include?(:grpc)
+      x_goog_api_client_header << "rest/#{rest_version}" if rest_version && transports_version_send.include?(:rest)
       x_goog_api_client_header.join " ".freeze
     end
   end

data/lib/gapic/rest.rb

@@ -24,4 +24,6 @@ require "gapic/protobuf"
 require "gapic/rest/client_stub"
 require "gapic/rest/error"
 require "gapic/rest/faraday_middleware"
+require "gapic/rest/operation"
+require "gapic/rest/paged_enumerable"
 require "json"

data/lib/gapic/rest/client_stub.rb

@@ -76,6 +76,19 @@ module Gapic
         make_http_request :delete, uri: uri, body: nil, params: params, options: options
       end
 
+      ##
+      # Makes a PATCH request
+      #
+      # @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.
+      # @return [Faraday::Response]
+      def make_patch_request uri:, body:, params: {}, options: {}
+        make_http_request :patch, uri: uri, body: body, params: params, options: options
+      end
+
       ##
       # Makes a POST request
       #
@@ -90,7 +103,7 @@ module Gapic
       end
 
       ##
-      # Makes a PATCH request
+      # Makes a PUT request
       #
       # @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
@@ -98,8 +111,8 @@ module Gapic
       # @param options [::Gapic::CallOptions] 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
+      def make_put_request uri:, body: nil, params: {}, options: {}
+        make_http_request :put, uri: uri, body: body, params: params, options: options
       end
 
       protected

data/lib/gapic/rest/operation.rb

@@ -0,0 +1,33 @@
+# Copyright 2021 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
+    ##
+    # A base class for the wrappers over the long-running operations to the response of a REST LRO method.
+    #
+    # @attribute [r] operation
+    #   @return [Object] The wrapped operation object.
+    class BaseOperation
+      attr_reader :operation
+
+      ##
+      # @private
+      # @param operation [Object] The wrapped operation object.
+      def initialize operation
+        @operation = operation
+      end
+    end
+  end
+end

data/lib/gapic/rest/paged_enumerable.rb

@@ -0,0 +1,225 @@
+# Copyright 2021 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
+    ##
+    # A class to provide the Enumerable interface to the response of a REST paginated method.
+    # PagedEnumerable assumes response message holds a list of resources and the token to the next page.
+    #
+    # PagedEnumerable provides the enumerations over the resource data, and also provides the enumerations over the
+    # pages themselves.
+    #
+    # @example normal iteration over resources.
+    #   paged_enumerable.each { |resource| puts resource }
+    #
+    # @example per-page iteration.
+    #   paged_enumerable.each_page { |page| puts page }
+    #
+    # @example Enumerable over pages.
+    #   paged_enumerable.each_page do |page|
+    #     page.each { |resource| puts resource }
+    #   end
+    #
+    # @example more exact operations over pages.
+    #   while some_condition()
+    #     page = paged_enumerable.page
+    #     do_something(page)
+    #     break if paged_enumerable.next_page?
+    #     paged_enumerable.next_page
+    #   end
+    #
+    # @attribute [r] page
+    #   @return [Page] The current page object.
+    #
+    class PagedEnumerable
+      include Enumerable
+
+      attr_reader :page
+
+      ##
+      # @private
+      # @param service_stub [Object] The REST service_stub with the baseline implementation for the wrapped method.
+      # @param method_name [Symbol] The REST method name that is being wrapped.
+      # @param request [Object] The request object.
+      # @param response [Object] The response object.
+      # @param options [Gapic::CallOptions] The options for making the RPC call.
+      # @param format_resource [Proc] A Proc object to format the resource object. The Proc should accept response as an
+      #   argument, and return a formatted resource object. Optional.
+      #
+      def initialize service_stub, method_name, resource_field_name, request, response, options, format_resource: nil
+        @service_stub = service_stub
+        @method_name = method_name
+        @resource_field_name = resource_field_name
+        @request = request
+        @response = response
+        @options = options
+        @format_resource = format_resource
+
+        @page = Page.new response, resource_field_name, format_resource: @format_resource
+      end
+
+      ##
+      # Iterate over the individual resources, automatically requesting new pages as needed.
+      #
+      # @yield [Object] Gives the resource objects in the stream.
+      #
+      # @return [Enumerator] if no block is provided
+      #
+      def each &block
+        return enum_for :each unless block_given?
+
+        each_page do |page|
+          page.each(&block)
+        end
+      end
+
+      ##
+      # Iterate over the pages.
+      #
+      # @yield [Page] Gives the pages in the stream.
+      #
+      # @return [Enumerator] if no block is provided
+      #
+      def each_page
+        return enum_for :each_page unless block_given?
+
+        loop do
+          break if @page.nil?
+          yield @page
+          next_page!
+        end
+      end
+
+      ##
+      # True if there is at least one more page of results.
+      #
+      # @return [Boolean]
+      #
+      def next_page?
+        !next_page_token.nil? && !next_page_token.empty?
+      end
+
+      ##
+      # Load the next page and set it as the current page.
+      # If there is no next page, sets nil as a current page.
+      #
+      # @return [Page, nil] the new page object.
+      #
+      def next_page!
+        unless next_page?
+          @page = nil
+          return @page
+        end
+
+        next_request = @request.dup
+        next_request.page_token = @page.next_page_token
+
+        @response = @service_stub.send @method_name, next_request, @options
+        @page = Page.new @response, @resource_field_name, format_resource: @format_resource
+      end
+      alias next_page next_page!
+
+      ##
+      # The page token to be used for the next RPC call, or the empty string if there is no next page.
+      # nil if the iteration is complete.
+      #
+      # @return [String, nil]
+      #
+      def next_page_token
+        @page&.next_page_token
+      end
+
+      ##
+      # The current response object, for the current page.
+      # nil if the iteration is complete.
+      #
+      # @return [Object, nil]
+      #
+      def response
+        @page&.response
+      end
+
+      ##
+      # A class to represent a page in a PagedEnumerable. This also implements Enumerable, so it can iterate over the
+      # resource elements.
+      #
+      # @attribute [r] response
+      #   @return [Object] the response object for the page.
+      class Page
+        include Enumerable
+        attr_reader :response
+
+        ##
+        # @private
+        # @param response [Object] The response object for the page.
+        # @param resource_field [String] The name of the field in response which holds the resources.
+        # @param format_resource [Proc, nil] A Proc object to format the resource object. Default nil (no formatting).
+        # The Proc should accept response as an argument, and return a formatted resource object. Optional.
+        #
+        def initialize response, resource_field, format_resource: nil
+          @response = response
+          @resource_field = resource_field
+          @format_resource = format_resource
+        end
+
+        ##
+        # Iterate over the resources.
+        #
+        # @yield [Object] Gives the resource objects in the page.
+        #
+        # @return [Enumerator] if no block is provided
+        #
+        def each
+          return enum_for :each unless block_given?
+
+          # We trust that the field exists and is an Enumerable
+          resources.each do |resource|
+            resource = @format_resource.call resource if @format_resource
+            yield resource
+          end
+        end
+
+        ##
+        # The page token to be used for the next RPC call, or the empty string if there is no next page.
+        #
+        # @return [String]
+        #
+        def next_page_token
+          @response.next_page_token
+        end
+
+        ##
+        # Whether the next_page_token exists and is not empty
+        #
+        # @return [Boolean]
+        #
+        def next_page_token?
+          !next_page_token.empty?
+        end
+
+        ##
+        # Resources in this page presented as an array.
+        # When the iterable is a protobuf map, the `.each |item|` gives just the keys
+        # to iterate like a normal hash it should be converted to an array first
+        #
+        # @return [Array]
+        #
+        def resources
+          @resources ||= @response[@resource_field].to_a
+        end
+      end
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: gapic-common
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.6.0
 platform: ruby
 authors:
 - Google API Authors
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-04-16 00:00:00.000000000 Z
+date: 2021-07-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -33,7 +33,7 @@ dependencies:
         version: 1.3.11
     - - "<"
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: 2.a
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -43,7 +43,7 @@ dependencies:
         version: 1.3.11
     - - "<"
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: 2.a
 - !ruby/object:Gem::Dependency
   name: googleapis-common-protos-types
   requirement: !ruby/object:Gem::Requirement
@@ -53,7 +53,7 @@ dependencies:
         version: 1.0.6
     - - "<"
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: 2.a
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -63,47 +63,41 @@ dependencies:
         version: 1.0.6
     - - "<"
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: 2.a
 - !ruby/object:Gem::Dependency
   name: googleauth
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.15'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.15.1
+        version: 0.16.2
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: 2.a
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.15'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.15.1
+        version: 0.16.2
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: 2.a
 - !ruby/object:Gem::Dependency
   name: google-protobuf
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.15'
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 3.15.2
+        version: '3.14'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.15'
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 3.15.2
+        version: '3.14'
 - !ruby/object:Gem::Dependency
   name: grpc
   requirement: !ruby/object:Gem::Requirement
@@ -152,14 +146,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '5.10'
+        version: '5.14'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '5.10'
+        version: '5.14'
 - !ruby/object:Gem::Dependency
   name: minitest-autotest
   requirement: !ruby/object:Gem::Requirement
@@ -278,6 +272,8 @@ files:
 - lib/gapic/rest/client_stub.rb
 - lib/gapic/rest/error.rb
 - lib/gapic/rest/faraday_middleware.rb
+- lib/gapic/rest/operation.rb
+- lib/gapic/rest/paged_enumerable.rb
 - lib/gapic/stream_input.rb
 homepage: https://github.com/googleapis/gapic-generator-ruby
 licenses:
@@ -298,7 +294,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3
+rubygems_version: 3.1.6
 signing_key: 
 specification_version: 4
 summary: Common code for GAPIC-generated API clients