gapic-generator-cloud 0.10.1 → 0.45.1

data/lib/gapic/presenters/cloud_gem_presenter.rb

@@ -23,6 +23,19 @@ module Gapic
     # A presenter subclass for cloud gems.
     #
     class CloudGemPresenter < GemPresenter
+      # @private
+      # A list of gem name patterns for gems that don't look like cloud but are
+      PSEUDO_CLOUD_GEMS = [
+        /^google-iam-credentials/,
+        /^google-identity-access_context_manager/,
+        /^grafeas/,
+        /^stackdriver/
+      ].freeze
+
+      # @private
+      # A list of gem name patterns for gems that look like cloud but aren't
+      NON_CLOUD_GEMS = [].freeze
+
       def license_name
         "Apache-2.0"
       end
@@ -56,23 +69,18 @@ module Gapic
         minfo ? minfo[1] : nil
       end
 
-      alias_method :readme_description, :description # rubocop:disable Style/Alias
-
       ##
-      # Overrides the gemspec description including a note that users should
-      # consider installing the wrapper instead of this versioned gem.
-      #
-      # Note: The method `readme_description` was aliased to the superclass
-      # method because the description without this note is used in the readme.
+      # Increments the original gemspec description for versioned gems, including a
+      # note that users should consider installing the wrapper gem instead.
       #
       # @return [String]
       #
-      def description
-        desc = readme_description
+      def gemspec_description
+        desc = super
         if has_wrapper?
-          desc += " Note that #{name} is a version-specific client library." \
-            " For most uses, we recommend installing the main client library" \
-            " #{wrapper_name} instead. See the readme for more details."
+          desc += " Note that #{name} is a version-specific client library. " \
+                  "For most uses, we recommend installing the main client library " \
+                  "#{wrapper_name} instead. See the readme for more details."
         end
         desc
       end
@@ -87,7 +95,7 @@ module Gapic
       #
       def generator_args_for_metadata
         result = {}
-        result["ruby-cloud-description"] = description
+        result["ruby-cloud-description"] = gemspec_description
         result["ruby-cloud-env-prefix"] = env_prefix if env_prefix
         result["ruby-cloud-product-url"] = product_documentation_url if product_documentation_url
         path_overrides = @api.overrides_of(:file_path).map { |k, v| "#{k}=#{v}" }.join ";"
@@ -98,6 +106,45 @@ module Gapic
         result["ruby-cloud-service-override"] = service_overrides unless service_overrides.empty?
         result
       end
+
+      ##
+      # Overrides the reference doc URL to point to either the cloud-rad page
+      # or the rubydoc.info page depending on whether it is a cloud product.
+      #
+      # @return [String]
+      #
+      def library_documentation_url
+        gem_config(:library_documentation_url) || begin
+          if cloud_product?
+            "https://cloud.google.com/ruby/docs/reference/#{name}/latest"
+          else
+            "https://rubydoc.info/gems/#{name}"
+          end
+        end
+      end
+
+      ##
+      # Whether this gem is for a cloud platform product. This controls, for
+      # example, whether the reference documentation appears under the
+      # cloud.google.com website.
+      #
+      # This first uses the `is_cloud_product` config. If that isn't set, it
+      # tries the overrides in the `PSEUDO_CLOUD_GEMS` and `NON_CLOUD_GEMS`
+      # constants. Finally, it looks for whether any services populate the
+      # `Google::Cloud` namespace.
+      #
+      # @return [boolean]
+      #
+      def cloud_product?
+        configured = gem_config :is_cloud_product
+        return configured unless configured.nil?
+        return @api.api_metadata.organization == "CLOUD" if @api.api_metadata.organization
+        return true if PSEUDO_CLOUD_GEMS.any? { |pattern| pattern === name }
+        return false if NON_CLOUD_GEMS.any? { |pattern| pattern === name }
+        services.any? do |service|
+          service.namespace =~ /^(::)?Google::Cloud::/
+        end
+      end
     end
 
     def self.cloud_gem_presenter api

data/lib/gapic/presenters/wrapper_gem_presenter.rb

@@ -14,6 +14,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+require "gapic/model/mixins"
 require "gapic/presenters"
 require "gapic/presenters/wrapper_service_presenter"
 
@@ -29,8 +30,11 @@ module Gapic
 
       def services
         @services ||= begin
-          files = @api.generate_files
-          files.map(&:services).flatten.map { |s| WrapperServicePresenter.new self, @api, s }
+          @api.generate_files
+              .map(&:services)
+              .flatten
+              .map { |s| WrapperServicePresenter.new self, @api, s }
+              .find_all { |s| !s.is_hosted_mixin? }
         end
       end
 
@@ -62,6 +66,18 @@ module Gapic
         gem_config :migration_version
       end
 
+      ##
+      # Generates a description text for README files, accounting for markdown
+      # rendering, properly escaping variables and disabling xrefs in the wrapper.
+      #
+      # @return [Array<String>] The description text as an array of lines.
+      #
+      def readme_description
+        has_markdown = description.strip.start_with? "#"
+        desc = has_markdown ? description.split("\n") : [description.gsub(/\s+/, " ").strip]
+        Gapic::FormattingUtils.format_doc_lines @api, desc, disable_xrefs: true
+      end
+
       # A description of the versions prior to the migration version.
       # Could be "a.x" if the migration version is 1.0 or later, otherwise
       # falls back to "pre-a.b".
@@ -132,15 +148,21 @@ module Gapic
         m[1].tr "-", "_"
       end
 
-      def docs_link version: nil, class_name: nil, text: nil
-        gem_name = version ? "#{name}-#{version}" : name
-        base_url = "https://googleapis.dev/ruby/#{gem_name}/latest"
+      def docs_link version: nil, class_name: nil, text: nil, gem_name: nil
+        gem_name ||= version ? "#{name}-#{version}" : name
+        base_url =
+          if cloud_product?
+            "https://cloud.google.com/ruby/docs/reference/#{gem_name}/latest"
+          else
+            "https://rubydoc.info/gems/#{gem_name}"
+          end
         if class_name
-          path = namespace.gsub "::", "/"
-          path = "#{path}/#{version.capitalize}" if version
-          class_path = class_name.gsub "::", "/"
+          separator = cloud_product? ? "-" : "/"
+          path = namespace.gsub "::", separator
+          path = "#{path}#{separator}#{version.capitalize}" if version
+          class_path = class_name.gsub "::", separator
           text ||= namespaced_class class_name, version: version
-          return "[#{text}](#{base_url}/#{path}/#{class_path}.html)"
+          return "[#{text}](#{base_url}/#{path}#{separator}#{class_path})"
         end
         "[#{text || name}](#{base_url})"
       end

data/lib/gapic/presenters/wrapper_service_presenter.rb

@@ -15,6 +15,7 @@
 # limitations under the License.
 
 require "gapic/presenters"
+require "gapic/presenters/wrapper_service_rest_presenter"
 require "gapic/ruby_info"
 
 module Gapic
@@ -23,13 +24,34 @@ module Gapic
     # A presenter for wrapper services.
     #
     class WrapperServicePresenter < ServicePresenter
+      def initialize *args, **kwargs
+        super(*args, **kwargs)
+        @rest = WrapperServiceRestPresenter.new self, @api
+      end
+
       def factory_method_name
         @factory_method_name ||= begin
           method_name = ActiveSupport::Inflector.underscore name
           suffix = gem.factory_method_suffix
           method_name = "#{method_name}#{suffix}" unless method_name.end_with? suffix
           method_name = "#{method_name}_client" if Gapic::RubyInfo.excluded_method_names.include? method_name
-          method_name
+          @api.fix_file_path method_name
+        end
+      end
+
+      ##
+      # Returns this service presenter if there is a grpc client. Otherwise,
+      # returns the corresponding rest service presenter if there isn't a grpc
+      # client but there is a rest client. Otherwise, returns nil if there is
+      # neither client.
+      #
+      # @return [WrapperServicePresenter,WrapperServiceRestPresenter,nil]
+      #
+      def usable_service_presenter
+        if generate_grpc_clients?
+          self
+        elsif generate_rest_clients?
+          rest
         end
       end
 

data/lib/gapic/presenters/wrapper_service_rest_presenter.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+# 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 "gapic/presenters"
+require "gapic/ruby_info"
+
+module Gapic
+  module Presenters
+    ##
+    # A presenter for wrapper services.
+    #
+    class WrapperServiceRestPresenter < ServiceRestPresenter
+      def factory_method_name
+        @factory_method_name ||= begin
+          method_name = ActiveSupport::Inflector.underscore main_service.name
+          suffix = main_service.gem.factory_method_suffix
+          method_name = "#{method_name}#{suffix}" unless method_name.end_with? suffix
+          method_name = "#{method_name}_client" if Gapic::RubyInfo.excluded_method_names.include? method_name
+          method_name
+        end
+      end
+
+      def create_client_call
+        "#{main_service.gem.namespace}.#{factory_method_name}"
+      end
+
+      def configure_client_call
+        "#{main_service.gem.namespace}.configure"
+      end
+
+      def credentials_class_xref
+        "`#{main_service.credentials_name_full}`"
+      end
+    end
+  end
+end

data/templates/cloud/gem/authentication.text.erb

@@ -0,0 +1,125 @@
+<%- assert_locals gem -%>
+<%- service = gem.first_non_common_service.usable_service_presenter -%>
+<%- assert_locals service -%>
+# Authentication
+
+The recommended way to authenticate to the <%= gem.name %> library is to use
+[Application Default Credentials (ADC)](https://cloud.google.com/docs/authentication/application-default-credentials).
+To review all of your authentication options, see [Credentials lookup](#credential-lookup).
+
+## Quickstart
+
+The following example shows how to set up authentication for a local development
+environment with your user credentials. 
+
+**NOTE:** This method is _not_ recommended for running in production. User credentials
+should be used only during development.
+
+1. [Download and install the Google Cloud CLI](https://cloud.google.com/sdk).
+2. Set up a local ADC file with your user credentials:
+
+```sh
+gcloud auth application-default login
+```
+
+3. Write code as if already authenticated.
+
+For more information about setting up authentication for a local development environment, see
+[Set up Application Default Credentials](https://cloud.google.com/docs/authentication/provide-credentials-adc#local-dev).
+
+## Credential Lookup
+
+The <%= gem.name %> library provides several mechanisms to configure your system.
+Generally, using Application Default Credentials to facilitate automatic 
+credentials discovery is the easist method. But if you need to explicitly specify
+credentials, there are several methods available to you.
+
+Credentials are accepted in the following ways, in the following order or precedence:
+
+1. Credentials specified in method arguments
+2. Credentials specified in configuration
+3. Credentials pointed to or included in environment variables
+4. Credentials found in local ADC file
+5. Credentials returned by the metadata server for the attached service account (GCP)
+
+### Configuration
+
+You can configure a path to a JSON credentials file, either for an individual client object or
+globally, for all client objects. The JSON file can contain credentials created for
+[workload identity federation](https://cloud.google.com/iam/docs/workload-identity-federation),
+[workforce identity federation](https://cloud.google.com/iam/docs/workforce-identity-federation), or a
+[service account key](https://cloud.google.com/docs/authentication/provide-credentials-adc#local-key).
+
+Note: Service account keys are a security risk if not managed correctly. You should
+[choose a more secure alternative to service account keys](https://cloud.google.com/docs/authentication#auth-decision-tree)
+whenever possible.
+
+To configure a credentials file for an individual client initialization:
+
+```ruby
+require "<%= gem.entrypoint_require %>"
+
+client = <%= service.create_client_call %> do |config|
+  config.credentials = "path/to/credentialfile.json"
+end
+```
+
+To configure a credentials file globally for all clients:
+
+```ruby
+require "<%= gem.entrypoint_require %>"
+
+<%= service.configure_client_call %> do |config|
+  config.credentials = "path/to/credentialfile.json"
+end
+
+client = <%= service.create_client_call %>
+```
+
+### Environment Variables
+
+You can also use an environment variable to provide a JSON credentials file.
+The environment variable can contain a path to the credentials file or, for
+environments such as Docker containers where writing files is not encouraged,
+you can include the credentials file itself.
+
+The JSON file can contain credentials created for
+[workload identity federation](https://cloud.google.com/iam/docs/workload-identity-federation),
+[workforce identity federation](https://cloud.google.com/iam/docs/workforce-identity-federation), or a
+[service account key](https://cloud.google.com/docs/authentication/provide-credentials-adc#local-key).
+
+Note: Service account keys are a security risk if not managed correctly. You should
+[choose a more secure alternative to service account keys](https://cloud.google.com/docs/authentication#auth-decision-tree)
+whenever possible.
+
+The environment variables that <%= gem.name %>
+checks for credentials are:
+
+* `GOOGLE_CLOUD_CREDENTIALS` - Path to JSON file, or JSON contents
+* `GOOGLE_APPLICATION_CREDENTIALS` - Path to JSON file
+
+```ruby
+require "<%= gem.entrypoint_require %>"
+
+ENV["GOOGLE_APPLICATION_CREDENTIALS"] = "path/to/credentialfile.json"
+
+client = <%= service.create_client_call %>
+```
+
+### Local ADC file
+
+You can set up a local ADC file with your user credentials for authentication during
+development. If credentials are not provided in code or in environment variables,
+then the local ADC credentials are discovered.
+
+Follow the steps in [Quickstart](#quickstart) to set up a local ADC file.
+
+### Google Cloud Platform environments
+
+When running on Google Cloud Platform (GCP), including Google Compute Engine
+(GCE), Google Kubernetes Engine (GKE), Google App Engine (GAE), Google Cloud
+Functions (GCF) and Cloud Run, credentials are retrieved from the attached
+service account automatically. Code should be written as if already authenticated.
+
+For more information, see
+[Set up ADC for Google Cloud services](https://cloud.google.com/docs/authentication/provide-credentials-adc#attached-sa).

data/templates/cloud/gem/{rakefile.erb → rakefile.text.erb}

@@ -16,40 +16,12 @@ Rake::TestTask.new do |t|
   t.warning = false
 end
 
-namespace :test do
-  desc "Runs tests with coverage."
-  task :coverage do
-    require "simplecov"
-    SimpleCov.start do
-      command_name "<%= gem.name %>"
-      track_files "lib/**/*.rb"
-      add_filter "test/"
-    end
-
-    Rake::Task[:test].invoke
-  end
-end
-
 desc "Runs the smoke tests."
 Rake::TestTask.new :smoke_test do |t|
   t.test_files = FileList["acceptance/**/*smoke_test.rb"]
   t.warning = false
 end
 
-namespace :smoke_test do
-  desc "Runs smoke tests with coverage."
-  task :coverage do
-    require "simplecov"
-    SimpleCov.start do
-      command_name "<%= gem.name %>"
-      track_files "lib/**/*.rb"
-      add_filter "test/"
-    end
-
-    Rake::Task[:smoke_test].invoke
-  end
-end
-
 # Acceptance tests
 desc "Run the <%= gem.name %> acceptance tests."
 task :acceptance, :project, :keyfile do |t, args|
@@ -93,10 +65,6 @@ namespace :acceptance do
     end
   end
 
-  desc "Run acceptance tests with coverage."
-  task :coverage do
-  end
-
   desc "Run acceptance cleanup."
   task :cleanup do
   end
@@ -149,11 +117,6 @@ task :doctest do
   puts "The <%= gem.name %> gem does not have doctest tests."
 end
 
-task :cloudrad do
-  ENV["CLOUDRAD_GEM_NAME"] = "<%= gem.name %>"
-  sh "bundle exec yard doc --fail-on-warning --yardopts .yardopts-cloudrad"
-end
-
 desc "Run the CI build"
 task :ci do
   header "BUILDING <%= gem.name %>"

data/templates/cloud/gem/{readme.erb → readme.text.erb}

@@ -2,7 +2,11 @@
 
 <%= gem.summary %>
 
-<%= gem.readme_description %>
+<%- if gem.summary != gem.description %>
+<% gem.readme_description.each do |line| %>
+<%= line %>
+<% end %>
+<%- end %>
 
 <%= gem.homepage %>
 
@@ -65,44 +69,62 @@ See also the [Product Documentation](<%= gem.product_documentation_url %>)
 for general usage information.
 
 <%- end -%>
-<%- if gem.show_grpc_logging_docs? -%>
-## Enabling Logging
+<%- if gem.show_logging_docs? -%>
+## Debug Logging
+
+This library comes with opt-in Debug Logging that can help you troubleshoot
+your application's integration with the API. When logging is activated, key
+events such as requests and responses, along with data payloads and metadata
+such as headers and client configuration, are logged to the standard error
+stream.
+
+**WARNING:** Client Library Debug Logging includes your data payloads in
+plaintext, which could include sensitive data such as PII for yourself or your
+customers, private keys, or other security data that could be compromising if
+leaked. Always practice good data hygiene with your application logs, and follow
+the principle of least access. Google also recommends that Client Library Debug
+Logging be enabled only temporarily during active debugging, and not used
+permanently in production.
+
+To enable logging, set the environment variable `GOOGLE_SDK_RUBY_LOGGING_GEMS`
+to the value `all`. Alternatively, you can set the value to a comma-delimited
+list of client library gem names. This will select the default logging behavior,
+which writes logs to the standard error stream. On a local workstation, this may
+result in logs appearing on the console. When running on a Google Cloud hosting
+service such as [Google Cloud Run](https://cloud.google.com/run), this generally
+results in logs appearing alongside your application logs in the
+[Google Cloud Logging](https://cloud.google.com/logging/) service.
 
-To enable logging for this library, set the logger for the underlying [gRPC](https://github.com/grpc/grpc/tree/master/src/ruby) library.
-The logger that you set may be a Ruby stdlib [`Logger`](https://ruby-doc.org/stdlib/libdoc/logger/rdoc/Logger.html) as shown below,
-or a [`Google::Cloud::Logging::Logger`](https://googleapis.dev/ruby/google-cloud-logging/latest)
-that will write logs to [Cloud Logging](https://cloud.google.com/logging/). See [grpc/logconfig.rb](https://github.com/grpc/grpc/blob/master/src/ruby/lib/grpc/logconfig.rb)
-and the gRPC [spec_helper.rb](https://github.com/grpc/grpc/blob/master/src/ruby/spec/spec_helper.rb) for additional information.
-
-Configuring a Ruby stdlib logger:
+<%- service = gem.quick_start_service.usable_service_presenter -%>
+<%- if service -%>
+You can customize logging by modifying the `logger` configuration when
+constructing a client object. For example:
 
 ```ruby
+require "<%= gem.entrypoint_require %>"
 require "logger"
 
-module MyLogger
-  LOGGER = Logger.new $stderr, level: Logger::WARN
-  def logger
-    LOGGER
-  end
-end
-
-# Define a gRPC module-level logger method before grpc/logconfig.rb loads.
-module GRPC
-  extend MyLogger
+client = <%= service.create_client_call %> do |config|
+  config.logger = Logger.new "my-app.log"
 end
 ```
-
 <%- end -%>
+<%- end -%>
+
+## Google Cloud Samples
+
+To browse ready to use code samples check [Google Cloud Samples](https://cloud.google.com/docs/samples).
+
 ## Supported Ruby Versions
 
-This library is supported on Ruby 2.5+.
+This library is supported on Ruby 3.0+.
 
 Google provides official support for Ruby versions that are actively supported
 by Ruby Core—that is, Ruby versions that are either in normal maintenance or
-in security maintenance, and not end of life. Currently, this means Ruby 2.5
-and later. Older versions of Ruby _may_ still work, but are unsupported and not
-recommended. See https://www.ruby-lang.org/en/downloads/branches/ for details
-about the Ruby support schedule.
+in security maintenance, and not end of life. Older versions of Ruby _may_
+still work, but are unsupported and not recommended. See
+https://www.ruby-lang.org/en/downloads/branches/ for details about the Ruby
+support schedule.
 <%- if gem.wrapper_name -%>
 
 ## Which client should I use?

data/templates/cloud/gem/{repo-metadata.erb → repo-metadata.text.erb}

@@ -3,8 +3,10 @@
 <%- if gem.api_id -%>
     "api_id": "<%= gem.api_id %>",
 <%- end -%>
+    "api_shortname": "<%= gem.api_shortname || 'unknown' %>",
     "client_documentation": "<%= gem.library_documentation_url %>",
     "distribution_name": "<%= gem.name %>",
+    "is_cloud": <%= gem.cloud_product? %>,
 <%- if gem.issue_tracker_url -%>
     "issue_tracker": "<%= gem.issue_tracker_url %>",
 <%- end -%>
@@ -16,6 +18,7 @@
 <%- if gem.product_documentation_url -%>
     "product_documentation": "<%= gem.product_documentation_url %>",
 <%- end -%>
+    "release_level": "unreleased",
     "repo": "googleapis/google-cloud-ruby",
     "requires_billing": <%= !gem.free_tier? %>,
 <%- gem.generator_args_for_metadata.each do |key, val| -%>

data/templates/cloud/gem/{rubocop.erb → rubocop.text.erb}

@@ -26,6 +26,9 @@ Metrics/ModuleLength:
   Enabled: false
 Metrics/PerceivedComplexity:
   Enabled: false
+Naming/AccessorMethodName:
+  Exclude:
+    - "snippets/**/*.rb"
 Naming/FileName:
   Exclude:
     - "lib/<%= gem.name %>.rb"

data/templates/cloud/gem/{yardopts.erb → yardopts.text.erb}

@@ -1,6 +1,6 @@
 <%- assert_locals gem -%>
 --no-private
---title=<%= gem.title %> API
+--title="<%= gem.title %> API"
 --exclude _pb\.rb$
 --markup markdown
 --markup-provider redcarpet

data/templates/cloud/service/rest/client/method/def/_rescue.text.erb

@@ -0,0 +1,3 @@
+ <%- assert_locals method -%>
+rescue ::Gapic::Rest::Error => e
+  raise ::Google::Cloud::Error.from_error(e)