gapic-generator 0.7.5 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cbb07888e227a0e891359dd684e8ead50be011593929d56a929a9b1e226a8257
-  data.tar.gz: 1ef99fe476ca10728df3997f3a01a87e12cf3f681ecb7f1c07e17facbd3ecd7a
+  metadata.gz: 36abe40caa29f9c1368fc86632e1c57703d98346ab5dd70ad1a87ba7e73b277c
+  data.tar.gz: 60479a28e6d38873d21f06200f554e874ae2df926929e6eaef0a33e9b3099de5
 SHA512:
-  metadata.gz: 535fa4c595fc7c3074c9d554303f275039e8952a908f2b9295b62625f14173ed979e684fb11ed33b7dfbce751001cdb4aaa25e2d9f752252af258336a8ca45c3
-  data.tar.gz: d36e8866f75c418520142c1b883214540b40261b06e2386ea822fef42de79ebbde38368f21b2bcf726871f64bb12b1e4b4bf8be70d043e44e026f8c41f8ccf23
+  metadata.gz: 970f3a69d280a1cdad3bd53554d48d89524528ae65033e9a469ce4be3ccd9da83d8bd1bb4a28a6d45d9989456398b8421876eaaa39e1eaf179e28573b6ded107
+  data.tar.gz: 41b9678039126730f3295f63cdd20d298516060b3965091888c47cec944863f7dba01d7d5254327c13477053bdcc4425e500a42cf63e620befda2addb0e85c7b

data/CHANGELOG.md

@@ -1,5 +1,50 @@
 # Release History for gapic-generator
 
+### 0.10.0 / 2021-08-09
+
+* New: Enabled per-RPC configuration for generated REST libraries
+* New: Generated docs include the deprecated YARD tag for deprecated protos
+* New: Scopes can be passed to self-signed JWTs
+* Fixed: Generated gRPC clients honor the client-default timeout config
+* Fixed: Generated docs now use YARD example tags for inline samples related to configuration
+* Fixed: Generated REST clients now require google/cloud/errors
+* Generated libraries now require gapic-common 0.7.0 or later
+
+### 0.9.2 / 2021-07-27
+
+* REST libraries are now generated with pagination hepers
+* REST libraries are now generated with correct examples in README.md and other documentation files
+* It is now possible to generate inline snippets in yardocs
+* Fixed the require path in the generated standalone snippets so it reflects the recommended require root rather than the service-specific require path.
+* Prevent "duplicate" resources (with the same name but different namespaces) from producing duplicate helper methods.
+
+### 0.9.1 / 2021-07-07
+
+* Detect multiple resource parents for patterns used by multiple resources
+
+### 0.9.0 / 2021-06-29
+
+* Support for configuring the service/method used for the quickstart example
+* Allow generation of libraries with no custom env prefix
+* Add service override setting to the repo metadata
+* Wrapper gem dependencies on pre-GA versioned gems now allow both 0.x and 1.x versions
+* Scoped some String and Hash references to the global scope to avoid name collisions
+* Reformat some config code to avoid rubocop indentation churn
+* Bazel: Replace monolith deps with rules_gapic
+
+### 0.8.0 / 2021-06-16
+
+* Initial implementation of standalone snippet generation.
+* Updated gapic-common dependencies to require at least 0.5 and to support future 1.x versions.
+* Generated unit tests for REST clients.
+* Generated proper x-goog-api-client headers for REST clients.
+* Added generation arguments to generated repo metadata.
+* Allow multiple versions in the extra-dependency command line argument.
+* Fixed treatment of boolean-valued command line arguments to the generator.
+* Fixed behavior of wrapper-gem-override if given an empty value.
+* Fixed default env_prefix computation to avoid the version part of the proto namespace.
+* Fixed Bazel front-end to preserve file permissions.
+
 ### 0.7.5 / 2021-05-18
 
 * Bazel jobs now provide a prebuilt ruby binary.

data/lib/gapic/generator/version.rb

@@ -16,6 +16,6 @@
 
 module Gapic
   module Generator
-    VERSION = "0.7.5"
+    VERSION = "0.10.0"
   end
 end

data/lib/gapic/generators/default_generator.rb

@@ -60,10 +60,18 @@ module Gapic
             files << g("service/paths.erb",                  "lib/#{service.paths_file_path}",                   service: service) if service.paths?
             files << g("service/operations.erb",             "lib/#{service.operations_file_path}",              service: service) if service.lro? && !@api.generate_rest_clients?
             files << g("service/rest/client.erb",            "lib/#{service.rest.client_file_path}",             service: service) if @api.generate_rest_clients? and service.methods_rest_bindings?
-            files << g("service/rest/grpc_transcoding.erb",  "lib/#{service.rest.transcoding_helper_file_path}", service: service) if @api.generate_rest_clients? and service.methods_rest_bindings?
+            files << g("service/rest/service_stub.erb",      "lib/#{service.rest.service_stub_file_path}",       service: service) if @api.generate_rest_clients? and service.methods_rest_bindings?
+            files << g("service/rest/test/client.erb",       "test/#{service.rest.test_client_file_path}",       service: service) if @api.generate_rest_clients? and service.methods_rest_bindings?
             files << g("service/test/client.erb",            "test/#{service.test_client_file_path}",            service: service) unless @api.generate_rest_clients?
             files << g("service/test/client_paths.erb",      "test/#{service.test_paths_file_path}",             service: service) if service.paths?
             files << g("service/test/client_operations.erb", "test/#{service.test_client_operations_file_path}", service: service) if service.lro? && !@api.generate_rest_clients?
+
+            if @api.generate_standalone_snippets?
+              service.methods.each do |method|
+                snippet = method.snippet
+                files << g("snippets/standalone.erb", "snippets/#{snippet.snippet_file_path}", snippet: snippet)
+              end
+            end
           end
         end
 
@@ -82,6 +90,8 @@ module Gapic
         files << g("gem/entrypoint.erb",            "lib/#{gem.name}.rb",           gem: gem)
         files << g("gem/gapic_metadata_json.erb",   "gapic_metadata.json",          gem: gem) if @api.generate_metadata
 
+        files << g("snippets/gemfile.erb",          "snippets/Gemfile",             gem: gem) if @api.generate_standalone_snippets?
+
         gem.proto_files.each do |proto_file|
           files << g("proto_docs/proto_file.erb", "proto_docs/#{proto_file.docs_file_path}", file: proto_file)
         end

data/lib/gapic/generators/default_generator_parameters.rb

@@ -24,7 +24,9 @@ module Gapic
         ":gem.:free_tier",
         ":gem.:yard_strict",
         ":gem.:generic_endpoint",
-        ":generate_metadata"
+        ":generate_metadata",
+        ":generate_standalone_snippets",
+        ":generate_yardoc_snippets"
       ].freeze
 
       STRING_PARAMETERS = [

data/lib/gapic/presenters.rb

@@ -26,7 +26,9 @@ require "gapic/presenters/package_presenter"
 require "gapic/presenters/resource_presenter"
 require "gapic/presenters/sample_presenter"
 require "gapic/presenters/service_presenter"
+require "gapic/presenters/service_config_presenter"
 require "gapic/presenters/service_rest_presenter"
+require "gapic/presenters/snippet_presenter"
 
 module Gapic
   ##

data/lib/gapic/presenters/gem_presenter.rb

@@ -127,7 +127,7 @@ module Gapic
       end
 
       def env_prefix
-        (gem_config(:env_prefix) || name.split("-").last).upcase
+        gem_config(:env_prefix)&.upcase
       end
 
       def iam_dependency?
@@ -156,18 +156,26 @@ module Gapic
         gem_config :issue_tracker_url
       end
 
+      ##
+      # @return [Boolean]
+      #
       def free_tier?
-        # Default to false unless the config is explicitly set to "true"
-        gem_config(:free_tier) == "true"
+        gem_config(:free_tier) || false
       end
 
+      ##
+      # @return [Boolean]
+      #
       def yard_strict?
         # Default to true unless the config is explicitly set to "false"
-        gem_config(:yard_strict) != "false"
+        gem_config(:yard_strict).nil? || gem_config(:yard_strict)
       end
 
+      ##
+      # @return [Boolean]
+      #
       def generic_endpoint?
-        gem_config(:generic_endpoint) == "true"
+        gem_config(:generic_endpoint) || false
       end
 
       def entrypoint_require
@@ -183,11 +191,13 @@ module Gapic
       end
 
       def dependencies
-        deps = { "gapic-common" => "~> 0.4" }
-        deps["grpc-google-iam-v1"] = [">= 0.6.10", "< 2.0"] if iam_dependency?
-        extra_deps = gem_config :extra_dependencies
-        deps.merge! extra_deps if extra_deps
-        deps
+        @dependencies ||= begin
+          deps = { "gapic-common" => [">= 0.7", "< 2.a"] }
+          deps["grpc-google-iam-v1"] = [">= 0.6.10", "< 2.a"] if iam_dependency?
+          extra_deps = gem_config_dependencies
+          deps.merge! extra_deps if extra_deps
+          deps
+        end
       end
 
       def dependency_list
@@ -217,6 +227,29 @@ module Gapic
         JSON.pretty_generate first_package_drift_manifest
       end
 
+      ##
+      # The service to use for quick start samples. Normally this is simply the
+      # {#first_non_common_service}, but it can be overridden via a gem config.
+      #
+      # @return [Gapic::Presenters::ServicePresenter]
+      #
+      def quick_start_service
+        preferred_service = gem_config :quick_start_service
+        result = services.find { |svc| svc.name == preferred_service } if preferred_service
+        result || first_non_common_service
+      end
+
+      ##
+      # Whether the "Enabling (gRPC) Logging" section of the readme should
+      # appear. This is true if there is a quick-start service displayed in the
+      # readme, AND it uses gRPC.
+      #
+      # @return [Boolean]
+      #
+      def show_grpc_logging_docs?
+        packages? && quick_start_service.usable_service_presenter.is_a?(ServicePresenter)
+      end
+
       private
 
       def gem_config key
@@ -225,6 +258,26 @@ module Gapic
         @api.configuration[:gem][key]
       end
 
+      ##
+      # There is a special case (from PoV of generator parameters)
+      # in gem dependencies where a dependency needs to be an array of strings
+      # e.g. ">= 1.6", "< 2.a"
+      # Rather than creating a special generator param case for this I will special-case it here.
+      # '|' is the separator.
+      # The above would be represented as ">= 1.6|< 2.a"
+      #
+      # @return [Hash<String, String>, Hash{String=>Array<String>}, nil]
+      def gem_config_dependencies
+        return unless gem_config :extra_dependencies
+        gem_config(:extra_dependencies).map do |dep_name, dep_versions|
+          if dep_versions.include? "|"
+            [dep_name, dep_versions.split("|")]
+          else
+            [dep_name, dep_versions]
+          end
+        end.to_h
+      end
+
       def blacklist_protos
         blacklist = gem_config :blacklist
 

data/lib/gapic/presenters/method/rest_pagination_info.rb

@@ -0,0 +1,246 @@
+# frozen_string_literal: true
+
+# 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 Presenters
+    module Method
+      ##
+      # Pagination info determined from the proto method
+      #
+      class RestPaginationInfo
+        include Gapic::Helpers::NamespaceHelper
+        ##
+        # @param proto_method [Gapic::Schema::Method] the method to derive pagination info from
+        # @param api [Gapic::Schema::Api]
+        #
+        def initialize proto_method, api
+          @api = api
+          @request = proto_method.input
+          @response = proto_method.output
+          @server_streaming = proto_method.server_streaming
+        end
+
+        ##
+        # Whether the method should be generated as paged
+        #
+        # @return [Boolean]
+        def paged?
+          !server_streaming? && paged_request? && paged_response?
+        end
+
+        ##
+        # Name of the request's field used for page size
+        # For Regapic can be either `page_size` or `max_results`
+        #
+        # @return [String, nil]
+        def request_page_size_name
+          request_page_size_field&.name
+        end
+
+        ##
+        # Name of the repeated field in the response message
+        # For REST gapics can be either a vanilla repeated field or a map
+        #
+        # @return [String, nil]
+        def response_repeated_field_name
+          response_results_field&.name
+        end
+
+        ##
+        # Whether the repeated field in the response message is a map
+        #
+        # @return [Boolean, nil]
+        def repeated_field_is_a_map?
+          response_results_field&.map?
+        end
+
+        ##
+        # Proto type of the repeated field in the response message
+        #
+        # @return [String, nil]
+        def paged_element_doc_type
+          return nil if response_results_field.nil?
+          field_paginated_elem_doc_type response_results_field
+        end
+
+        private
+
+        # Whether the underlying proto rpc is a server streaming rpc
+        # @return [Boolean]
+        attr_accessor :server_streaming
+
+        ##
+        # Whether the underlying proto rpc is a server streaming rpc
+        #
+        # @return [Boolean]
+        def server_streaming?
+          @server_streaming
+        end
+
+        ##
+        # Whether the request message for the REGAPIC rpc satisfies the criteria
+        # for the rpc to be classified and implemented as paged
+        #
+        # @return [Boolean]
+        def paged_request?
+          # Has a String page_token field which specifies the actual (next) page to retrieve.
+          # Has an int32 page_size or int32 max_results field
+          # which defines the maximum number of paginated resources to return in the response.
+          !request_page_token_field.nil? && !request_page_size_field.nil?
+        end
+
+        ##
+        # The field in the request that holds a page_token
+        #
+        # @return[Gapic::Schema::Field, nil]
+        def request_page_token_field
+          # Has a String page_token field which specifies the actual (next) page to retrieve.
+          @request_page_token_field ||= @request.fields.find do |f|
+            f.name == "page_token" && f.type == Google::Protobuf::FieldDescriptorProto::Type::TYPE_STRING
+          end
+        end
+
+        ##
+        # The field in the request that holds a page_size
+        # For Regapic can have a name of either `page_size` or `max_results`
+        #
+        # @return[Gapic::Schema::Field, nil]
+        def request_page_size_field
+          @request_page_size_field ||=
+            begin
+              page_size_names = ["page_size", "max_results"]
+
+              # Has the int32 page_size or int32 max_results field
+              # which defines the maximum number of paginated resources to return in the response.
+              page_size_types = [
+                Google::Protobuf::FieldDescriptorProto::Type::TYPE_UINT32,
+                Google::Protobuf::FieldDescriptorProto::Type::TYPE_INT32
+              ]
+
+              field = @request.fields.find do |f|
+                page_size_names.include?(f.name) && page_size_types.include?(f.type)
+              end
+
+              field
+            end
+        end
+
+        ##
+        # Whether the response message for the REGAPIC rpc satisfies the criteria
+        # for the rpc to be classified and implemented as paged
+        #
+        # @return [Boolean]
+        def paged_response?
+          # Has the string next_page_token field to be used in the next request as page_token to retrieve the next page.
+          # Has only one repeated or map<string, ?> field containing a list of paginated resources.
+          !response_next_page_token_field.nil? && !response_results_field.nil?
+        end
+
+        ##
+        # The field in the response that holds a next page_token
+        #
+        # @return[Gapic::Schema::Field, nil]
+        def response_next_page_token_field
+          # Has the string next_page_token field to be used in the next request as page_token to retrieve the next page.
+          @response_next_page_token_field ||= @response.fields.find do |f|
+            f.name == "next_page_token" && f.type == Google::Protobuf::FieldDescriptorProto::Type::TYPE_STRING
+          end
+        end
+
+        ##
+        # The field in the response that holds the results
+        # For Regapic can be either a vanilla repeated field or a map
+        #
+        # @return [Gapic::Schema::Field, nil]
+        def response_results_field
+          @response_results_field ||= begin
+            map_fields = @response.fields.find_all(&:map?)
+            repeated_fields = @response.fields.find_all do |f|
+              !f.map? &&
+                f.label == Google::Protobuf::FieldDescriptorProto::Label::LABEL_REPEATED
+            end
+
+            if map_fields.count == 1
+              # If the response message has only one map<string, ?> field
+              # treat it as the one with paginated resources (i.e. ignore the repeated fields if any).
+              map_fields.first
+            elsif repeated_fields.count == 1 && map_fields.empty?
+              # If the response message contains only one repeated field,
+              # treat that field as the one containing the paginated resources.
+              repeated_fields.first
+            end
+            # If the response message contains more than one repeated field or does not have repeated fields at all
+            # but has more than one map<string, ?> field, do not generate any paginated methods for such rpc.
+          end
+        end
+
+        ##
+        # A helper to get a Ruby doc-type for a paginated element.
+        #
+        # @param field [Gapic::Schema::Field]
+        #
+        # @return [String]
+        def field_paginated_elem_doc_type field
+          return field_paginated_elem_map_type field if field.map?
+          if field.message?
+            message_ruby_type field.message
+          elsif field.enum?
+            # TODO: handle when arg message is nil and enum is the type
+            message_ruby_type field.enum
+          else
+            case field.type
+            when 1, 2                              then "::Float"
+            when 3, 4, 5, 6, 7, 13, 15, 16, 17, 18 then "::Integer"
+            when 9, 12                             then "::String"
+            when 8                                 then "::Boolean"
+            else
+              "::Object"
+            end
+          end
+        end
+
+        ##
+        # A helper to get a Ruby doc-type for a proto map's paginated element.
+        #
+        # @param field [Gapic::Schema::Field]
+        #
+        # @return [String]
+        def field_paginated_elem_map_type field
+          key_field = field.map_key_field
+          value_field = field.map_val_field
+
+          if key_field && value_field
+            key_type = field_paginated_elem_doc_type key_field
+            value_type = field_paginated_elem_doc_type value_field
+            "#{key_type}, #{value_type}"
+          else
+            class_name
+          end
+        end
+
+        ##
+        # A helper to get a Ruby type for a proto message.
+        #
+        # @param message [Gapic::Schema::Message]
+        #
+        # @return [String]
+        def message_ruby_type message
+          ruby_namespace @api, message.address.join(".")
+        end
+      end
+    end
+  end
+end