gapic-generator 0.9.1 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 61762b2051b75312bfc67ef070e136d8cf95cad1635e1b22270ed8a5b6cfbc99
-  data.tar.gz: cd867c0065831c6b5252dc0b5097417f24a74716f4e15cd243a1371ac80e5a5d
+  metadata.gz: a8baa3144f849b60f36cb51b7c7bed258165e9b3a646816aad586912001e4ddc
+  data.tar.gz: f1dc6fb877e18c0eed6c461bf6937d3756409da0bb259484149c377244953a70
 SHA512:
-  metadata.gz: b8c833fe9bbb2d35c8fb0e7b307e1f0aeb0f5774fe0f174e2505bc0460fcc13ae06bf6e2761fe1e00d7e44079327fbc761f7423b72c51e58ef23c4f4220edebb
-  data.tar.gz: 89e7871eac1c9e01d870c2e367e67e16ac5c49580259d828c922324250a88955da88014496a8da7ff22964e18941046153158df4d8a023a7fb9a158a86c06cea
+  metadata.gz: 90b475c396bcdd3ecdadec8fb27e3e8089e6c8525ad75d2f83142525684b898a38765ebde17d22262e2acaac56b8452e6d77b6a6f2ccc4fab4c21ad3997c9019
+  data.tar.gz: 84b4aab4d800b042c4be22f3159ca77fa1cc3489a903b79844d239202c56ffb0c02db39957afa7c0bee28b168547ff1e5afda93d373450f5f8a0e14feb969147

data/CHANGELOG.md

@@ -1,5 +1,62 @@
 # Release History for gapic-generator
 
+### 0.11.0 / 2022-03-01
+
+* New: Added generation of nonstandard LRO wrapper calls (currently used for Compute)
+* Fixed: Examples in the doc comments for modules are now generated with `@example` tags
+* Fixed: proto files without a proto service can again be generated
+* Ruby prebuilt binaries used in Bazel rules updated to Ruby 2.6.6
+
+### 0.10.6 / 2022-02-02
+
+* Point default documentation URL to rubydoc.info.
+
+### 0.10.5 / 2022-01-20
+
+* No significant changes
+
+### 0.10.4 / 2022-01-07
+
+* Fixed: Set quota_project_id correctly for LRO clients
+* Fixed: Remove old cloud-rad configs and rake tasks
+* Fixed: Properly quote page titles in YARD configs
+
+### 0.10.3 / 2021-11-04
+
+* New: Enabled snippet-gen by default
+
+### 0.10.2 / 2021-11-01
+
+* New: Added support for service.yaml
+* New: New mixin implementation
+* New: Parse and generate explicit routing headers
+* New: Preliminary support for extended operations for REST LROs
+* Fixed: Potential failures in generated tests when routing headers reference sub-fields
+* Fixed: Renamed service_config to grpc_service_config
+
+### 0.10.1 / 2021-08-27
+
+* New: Compute REST libraries are now generated with LRO wrappers
+* Fixed: Rubocop is disabled for sample tests in generated versioned libraries
+
+### 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

data/lib/gapic/generator/version.rb

@@ -16,6 +16,6 @@
 
 module Gapic
   module Generator
-    VERSION = "0.9.1"
+    VERSION = "0.11.0"
   end
 end

data/lib/gapic/generators/default_generator.rb

@@ -59,8 +59,10 @@ module Gapic
             files << g("service/credentials.erb",            "lib/#{service.credentials_file_path}",             service: service) unless gem.generic_endpoint?
             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/nonstandard_lro.erb",        "lib/#{service.nonstandard_lro_file_path}",         service: service) if service.nonstandard_lro_provider? && !service.methods_rest_bindings?
+            files << g("service/nonstandard_lro.erb",        "lib/#{service.rest.nonstandard_lro_file_path}",    service: service) if service.nonstandard_lro_provider? && service.methods_rest_bindings?
             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?

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 = [
@@ -44,6 +46,7 @@ module Gapic
         ":gem.:factory_method_suffix",
         ":defaults.:service.:default_host",
         "grpc_service_config",
+        ":service_yaml",
         ":overrides.:wrapper_gem_name"
       ].freeze
 
@@ -82,7 +85,8 @@ module Gapic
         "gem-api-shortname"         => ":gem.:api_shortname",
         "gem-factory-method-suffix" => ":gem.:factory_method_suffix",
         "default-service-host"      => ":defaults.:service.:default_host",
-        "grpc-service-config"       => "grpc_service_config"
+        "grpc-service-config"       => "grpc_service_config",
+        "service-yaml"              => ":service_yaml"
       }.freeze
 
       ARRAY_PARAMETERS_ALIASES = {

data/lib/gapic/grpc_service_config/{service_config.rb → config.rb}

@@ -21,12 +21,12 @@ module Gapic
     # applied on the service level (to all the methods) and the configurations
     # applied to the specific methods
     #
-    class ServiceConfig
+    class Config
       attr_reader :service_level_configs
       attr_reader :service_method_level_configs
 
       ##
-      # Create new ServiceConfig.
+      # Create new GrpcServiceConfig.
       #
       # @param service_level_configs [Hash<String, Gapic::GrpcServiceConfig::MethodConfig>] service-level configs
       #   in a lookup hash by the service full grpc name

data/lib/gapic/grpc_service_config/parser.rb

@@ -14,7 +14,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-require "gapic/grpc_service_config/service_config"
+require "gapic/grpc_service_config/config"
 require "gapic/grpc_service_config/method_config"
 require "gapic/grpc_service_config/retry_policy"
 require "gapic/grpc_service_config/parsing_error"
@@ -67,18 +67,18 @@ module Gapic
       end.freeze
 
       ##
-      # Parses ServiceConfig from a json of a GRPC service config
+      # Parses GRPC service configuration from a json
       #
-      # @param service_config_json [Hash] a hash that results from JSON.parse
+      # @param config_json [Hash] a hash that results from JSON.parse
       #
-      # @return [Gapic::GrpcServiceConfig::ServiceConfig] parsed ServiceConfig
+      # @return [Gapic::GrpcServiceConfig::Config] parsed GrpcServiceConfig
       #
-      def self.parse service_config_json
+      def self.parse config_json
         service_level_result = {}
         service_method_level_result = {}
 
-        if !service_config_json.nil? && key?(service_config_json, METHOD_CONFIG_JSON_KEY)
-          method_configs_json = get service_config_json, METHOD_CONFIG_JSON_KEY
+        if !config_json.nil? && key?(config_json, METHOD_CONFIG_JSON_KEY)
+          method_configs_json = get config_json, METHOD_CONFIG_JSON_KEY
 
           method_configs_json.each do |method_config_json|
             method_config = parse_config method_config_json
@@ -99,7 +99,7 @@ module Gapic
           end
         end
 
-        ServiceConfig.new service_level_result, service_method_level_result
+        Config.new service_level_result, service_method_level_result
       end
 
       ##

data/lib/gapic/model/method/http_annotation.rb

@@ -0,0 +1,123 @@
+# 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.
+
+require "gapic/uri_template"
+
+module Gapic
+  module Model
+    module Method
+      ##
+      # The information used in the generation process that
+      # can be gathered from the `google.api.http` annotation.
+      # `google.api.http` is used in two distinct ways:
+      #   - the rest libs use it as part of the transcoding to set up the REST call
+      #   - both rest and grpc libs use it as a source of implicit routing headers
+      #
+      class HttpAnnotation
+        ##
+        # @param proto_method [Gapic::Schema::Method]
+        #
+        def initialize proto_method
+          @proto_method = proto_method
+        end
+
+        ##
+        # Whether a http verb is present for this method
+        #
+        # @return [Boolean]
+        def verb?
+          !verb.nil?
+        end
+
+        ##
+        # The http verb for this method
+        #
+        # @return [Symbol, Nil]
+        def verb
+          return nil if @proto_method.http.nil?
+
+          method = {
+            get:    @proto_method.http.get,
+            post:   @proto_method.http.post,
+            put:    @proto_method.http.put,
+            patch:  @proto_method.http.patch,
+            delete: @proto_method.http.delete
+          }.find { |_, value| !value.empty? }
+
+          method[0] unless method.nil?
+        end
+
+        ##
+        # Whether a method path is present and non-empty
+        #
+        # @return [Boolean]
+        def path?
+          !path.empty?
+        end
+
+        ##
+        # A method path or an empty string if not present
+        #
+        # @return [String]
+        def path
+          return "" if @proto_method.http.nil?
+
+          verb_path = [
+            @proto_method.http.get, @proto_method.http.post, @proto_method.http.put,
+            @proto_method.http.patch, @proto_method.http.delete
+          ].find { |x| !x.empty? }
+
+          verb_path || @proto_method.http.custom&.path || ""
+        end
+
+        ##
+        # Whether any routing params are present
+        #
+        # @return [Boolean]
+        def routing_params?
+          routing_params.any?
+        end
+
+        ##
+        # The segment key names.
+        #
+        # @return [Array<String>]
+        def routing_params
+          Gapic::UriTemplate.parse_arguments path
+        end
+
+        ##
+        # Whether method has body specified in proto
+        #
+        # @return [Boolean]
+        def body?
+          return false if @proto_method.http.nil?
+
+          !@proto_method.http.body.empty?
+        end
+
+        ##
+        # The body specified for the given method in proto
+        # or an empty string if not specified
+        #
+        # @return [String]
+        def body
+          @proto_method.http&.body || ""
+        end
+      end
+    end
+  end
+end

data/lib/gapic/model/method/lro.rb

@@ -0,0 +1,160 @@
+# 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.
+
+require "gapic/path_pattern"
+
+module Gapic
+  module Model
+    ##
+    # Method-level models
+    #
+    module Method
+      ##
+      # Nonstandard (AIP-151 nonconforming) long-running operation method-level  model
+      #
+      # @!attribute [r] service_full_name
+      #   @return [String] Full grpc name of the provider service for this method's LRO
+      #   e.g. `google.example.LroProvider`
+      #
+      # @!attribute [r] operation_request_fields
+      #   @return [Map<String, String>] Map of the field names of this method's request message
+      #   that should be saved and later used when constructing the LRO polling request.
+      #   The values are the names of the fields in the polling request.
+      #   The semantics are `from -> to`, e.g. `{"foo" => "bar"}` means that
+      #   when constructing a polling request, the following assignment should be carried out:
+      #   `lro_polling_request.bar = this_method_request.foo`.
+      #
+      class NonStandardLro
+        # @return [String]
+        attr_reader :service_full_name
+        # @return [Map<String, String>]
+        attr_reader :operation_request_fields
+
+        ##
+        # @param method [Gapic::Schema::Method]
+        # @param service_full_name [String] Full grpc name of the provider service for this method's LRO
+        def initialize method, service_full_name
+          @service_full_name = service_full_name
+
+          # optionally, there might be things to copy from this method's input object
+          # to the LRO service's input object (`operation_request_field` annotation)
+          ops_request_fields = method.input.fields.find_all do |f|
+            !f.operation_request_field.nil? && !f.operation_request_field.empty?
+          end
+
+          @operation_request_fields = ops_request_fields.map do |field|
+            [field.name, field.operation_request_field]
+          end.to_h
+        end
+
+        ##
+        # @return [Boolean] Whether this is a model for the nonstandard LRO
+        #
+        def nonstandard_lro?
+          true
+        end
+
+        ##
+        # @return [Boolean] Whether this is a model for the AIP-151 LRO
+        #
+        def aip_lro?
+          false
+        end
+      end
+
+      ##
+      # AIP-151 LRO Model
+      #
+      class AipLro
+        include Singleton
+        ##
+        # @return [Boolean] Whether this is a model for the nonstandard LRO
+        #
+        def nonstandard_lro?
+          false
+        end
+
+        ##
+        # @return [Boolean] Whether this is a model for the AIP-151 LRO
+        #
+        def aip_lro?
+          true
+        end
+      end
+
+      ##
+      # Method does not represent a long-running operation
+      #
+      class NoLro
+        include Singleton
+        ##
+        # @return [Boolean] Whether this is a model for the nonstandard LRO
+        #
+        def nonstandard_lro?
+          false
+        end
+
+        ##
+        # @return [Boolean] Whether this is a model for the AIP-151 LRO
+        #
+        def aip_lro?
+          false
+        end
+      end
+
+      class << self
+        ##
+        # Inspects the method and returns it's long-running operation model
+        #
+        # @param method [Gapic::Schema::Method]
+        # @param api [Gapic::Schema::Api]
+        #
+        # @raises [Gapic::Model::ModelError]
+        #
+        # @returns [Gapic::Model::Method::NonStandardLro, Gapic::Model::Method::AipLro, Gapic::Model::Method::NoLro]
+        #
+        def parse_lro method, api
+          is_aip_lro = method.output.full_name == "google.longrunning.Operation"
+          return AipLro.instance if is_aip_lro
+
+          # If a method is annotated with operation_service, this is a nonstandard LRO consumer method
+          is_nonstandard_lro = !method.operation_service.nil? && !method.operation_service.empty?
+          if is_nonstandard_lro
+            # LRO service name is given plain, so it has to be in the same package as this method's service
+            service_full_name = (method.address[0..-3] << method.operation_service).join "."
+            ops_service_lro = api.nonstandard_lro_model_for service_full_name
+            unless ops_service_lro.nonstandard_lro?
+              error_text = "A service #{service_full_name} specified as a nonstandard LRO service for " \
+              "the method #{method.full_name} was not found."
+              raise ModelError, error_text
+            end
+
+            unless method.output.full_name == ops_service_lro.lro_object_full_name
+              error_text = "A service #{service_full_name} specified as a nonstandard LRO service for " \
+              "the method #{method.full_name} has a different LRO object (#{ops_service_lro.lro_object_full_name}) " \
+              "from the method's return type (#{method.output.full_name})."
+              raise ModelError, error_text
+            end
+
+            return NonStandardLro.new method, service_full_name
+          end
+
+          NoLro.instance
+        end
+      end
+    end
+  end
+end