gapic-generator-cloud 0.10.1 → 0.45.1

data/templates/cloud/wrapper_gem/{_main.erb → _main.text.erb}

@@ -14,16 +14,19 @@ require "google/cloud/config"
 
 # Set the default configuration
 ::Google::Cloud.configure.add_config! :<%= gem.google_cloud_short_name %> do |config|
-  config.add_field! :endpoint,      <%= gem.services.first&.client_endpoint.inspect %>, match: ::String
+  config.add_field! :endpoint,      nil, match: ::String
   config.add_field! :credentials,   nil, match: [::String, ::Hash, ::Google::Auth::Credentials]
   config.add_field! :scope,         nil, match: [::Array, ::String]
   config.add_field! :lib_name,      nil, match: ::String
   config.add_field! :lib_version,   nil, match: ::String
+<%- if gem.generate_grpc_clients? -%>
   config.add_field! :interceptors,  nil, match: ::Array
+<%- end -%>
   config.add_field! :timeout,       nil, match: ::Numeric
   config.add_field! :metadata,      nil, match: ::Hash
   config.add_field! :retry_policy,  nil, match: [::Hash, ::Proc]
   config.add_field! :quota_project, nil, match: ::String
+  config.add_field! :universe_domain, nil, match: ::String
 end
 <%- end -%>
 <% end %>
@@ -32,12 +35,21 @@ end
 # Create a new client object for <%= service.module_name %>.
 #
 # By default, this returns an instance of
-# <%= gem.docs_link version: gem.default_version, class_name: "#{service.module_name}::Client" %>
-# for version <%= gem.default_version.capitalize %> of the API.
-# However, you can specify specify a different API version by passing it in the
+# <%= gem.docs_link version: gem.default_version, class_name: service.client_suffix_for_default_transport %>
+# for a <%= gem.default_transport_name %> client for version <%= gem.default_version.capitalize %> of the API.
+# However, you can specify a different API version by passing it in the
 # `version` parameter. If the <%= service.module_name %> service is
 # supported by that API version, and the corresponding gem is available, the
 # appropriate versioned client will be returned.
+<%- if service.supports_multiple_transports? -%>
+# You can also specify a different transport by passing `:rest` or `:grpc` in
+# the `transport` parameter.
+<%- end -%>
+#
+# Raises an exception if the currently installed versioned client gem for the
+# given API version does not support the <% if service.supports_multiple_transports? %>given transport of the <% end %><%= service.module_name %> service.
+# You can determine whether the method will succeed by calling
+# {<%= gem.namespace %>.<%= service.factory_method_name %>_available?}.
 #
 <%- if service.doc_description -%>
 # ## About <%= service.module_name %>
@@ -47,17 +59,63 @@ end
 <%- end -%>
 # @param version [::String, ::Symbol] The API version to connect to. Optional.
 #   Defaults to `:<%= gem.default_version %>`.
-# @return [<%= service.module_name %>::Client] A client object for the specified version.
+<%- if service.supports_multiple_transports? -%>
+# @param transport [:grpc, :rest] The transport to use. Defaults to `<%= gem.default_transport.inspect %>`.
+<%- end -%>
+# @return [::Object] A client object for the specified version.
 #
-def self.<%= service.factory_method_name %> version: :<%= gem.default_version %>, &block
+def self.<%= service.factory_method_name %> version: :<%= gem.default_version %><% if service.supports_multiple_transports? %>, transport: <%= gem.default_transport.inspect %><% end %>, &block
   require "<%= gem.namespace_require %>/#{version.to_s.downcase}"
 
   package_name = <%= gem.namespace %>
                   .constants
                   .select { |sym| sym.to_s.downcase == version.to_s.downcase.tr("_", "") }
                   .first
-  package_module = <%= gem.namespace %>.const_get package_name
-  package_module.const_get(:<%= service.module_name %>).const_get(:Client).new(&block)
+  service_module = <%= gem.namespace %>.const_get(package_name).const_get(:<%= service.module_name %>)
+<%- if service.supports_multiple_transports? -%>
+  service_module = service_module.const_get(:Rest) if transport == :rest
+  service_module.const_get(:Client).new(&block)
+<%- else -%>
+  service_module<% if service.generate_rest_clients? %>.const_get(:Rest)<% end %>.const_get(:Client).new(&block)
+<%- end -%>
+end
+
+##
+# Determines whether the <%= service.module_name %> service is supported by the current client.
+# If true, you can retrieve a client object by calling {<%= gem.namespace %>.<%= service.factory_method_name %>}.
+# If false, that method will raise an exception. This could happen if the given
+# API version does not exist or does not support the <%= service.module_name %> service,
+# or if the versioned client gem needs an update to support the <%= service.module_name %> service.
+#
+# @param version [::String, ::Symbol] The API version to connect to. Optional.
+#   Defaults to `:<%= gem.default_version %>`.
+<%- if service.supports_multiple_transports? -%>
+# @param transport [:grpc, :rest] The transport to use. Defaults to `<%= gem.default_transport.inspect %>`.
+<%- end -%>
+# @return [boolean] Whether the service is available.
+#
+def self.<%= service.factory_method_name %>_available? version: :<%= gem.default_version %><% if service.supports_multiple_transports? %>, transport: <%= gem.default_transport.inspect %><% end %>
+  require "<%= gem.namespace_require %>/#{version.to_s.downcase}"
+  package_name = <%= gem.namespace %>
+                  .constants
+                  .select { |sym| sym.to_s.downcase == version.to_s.downcase.tr("_", "") }
+                  .first
+  return false unless package_name
+  service_module = <%= gem.namespace %>.const_get package_name
+  return false unless service_module.const_defined? :<%= service.module_name %>
+  service_module = service_module.const_get :<%= service.module_name %>
+<%- if service.supports_multiple_transports? -%>
+  if transport == :rest
+    return false unless service_module.const_defined? :Rest
+    service_module = service_module.const_get :Rest
+  end
+<%- elsif service.generate_rest_clients? -%>
+  return false unless service_module.const_defined? :Rest
+  service_module = service_module.const_get :Rest
+<%- end -%>
+  service_module.const_defined? :Client
+rescue ::LoadError
+  false
 end
 
 <%- end -%>
@@ -74,12 +132,14 @@ end
 #   The library name as recorded in instrumentation and logging.
 # * `lib_version` (*type:* `String`) -
 #   The library version as recorded in instrumentation and logging.
+<%- if gem.generate_grpc_clients? -%>
 # * `interceptors` (*type:* `Array<GRPC::ClientInterceptor>`) -
 #   An array of interceptors that are run before calls are executed.
+<%- end -%>
 # * `timeout` (*type:* `Numeric`) -
 #   Default timeout in seconds.
 # * `metadata` (*type:* `Hash{Symbol=>String}`) -
-#   Additional gRPC headers to be sent with the call.
+#   Additional headers to be sent with the call.
 # * `retry_policy` (*type:* `Hash`) -
 #   The retry policy. The value is a hash with the following keys:
 #     * `:initial_delay` (*type:* `Numeric`) - The initial delay in seconds.

data/templates/cloud/wrapper_gem/client_test.text.erb

@@ -0,0 +1,59 @@
+<%- assert_locals gem -%>
+<%= render partial: "shared/header" -%>
+
+require "helper"
+require "<%= gem.namespace_require %>"
+require "gapic/common"
+<%- if gem.generate_grpc_clients? -%>
+require "gapic/grpc"
+<%- end -%>
+<%- if gem.generate_rest_clients? -%>
+require "gapic/rest"
+<%- end -%>
+
+class <%= gem.namespace %>::ClientConstructionMinitest < Minitest::Test
+  class DummyStub
+    def endpoint
+      "endpoint.example.com"
+    end
+
+    def universe_domain
+      "example.com"
+    end
+
+    def stub_logger
+      nil
+    end
+
+    def logger
+      nil
+    end
+  end
+
+<%- start_line_spacer -%>
+<%- gem.services.each do |service| -%>
+<%- if service.generate_grpc_clients? -%>
+<%= line_spacer %>  def test_<%= service.factory_method_name %>_grpc
+    skip unless <%= gem.namespace %>.<%= service.factory_method_name %>_available?<% if service.supports_multiple_transports? %> transport: :grpc<% end %>
+    Gapic::ServiceStub.stub :new, DummyStub.new do
+      grpc_channel = GRPC::Core::Channel.new "localhost:8888", nil, :this_channel_is_insecure
+      client = <%= gem.namespace %>.<%= service.factory_method_name %><% if service.supports_multiple_transports? %> transport: :grpc<% end %> do |config|
+        config.credentials = grpc_channel
+      end
+      assert_kind_of <%= gem.namespaced_class "#{service.module_name}::#{service.client_name}", version: gem.default_version %>, client
+    end
+  end
+<%- end -%>
+<%- if service.generate_rest_clients? -%>
+<%= line_spacer %>  def test_<%= service.factory_method_name %>_rest
+    skip unless <%= gem.namespace %>.<%= service.factory_method_name %>_available?<% if service.supports_multiple_transports? %> transport: :rest<% end %>
+    Gapic::Rest::ClientStub.stub :new, DummyStub.new do
+      client = <%= gem.namespace %>.<%= service.factory_method_name %><% if service.supports_multiple_transports? %> transport: :rest<% end %> do |config|
+        config.credentials = :dummy_credentials
+      end
+      assert_kind_of <%= gem.namespaced_class "#{service.module_name}::Rest::#{service.client_name}", version: gem.default_version %>, client
+    end
+  end
+<%- end -%>
+<%- end -%>
+end

data/templates/cloud/wrapper_gem/gemfile.text.erb

@@ -0,0 +1,29 @@
+<%- assert_locals gem -%>
+source "https://rubygems.org"
+
+gemspec
+
+local_dependencies = <%= gem.versioned_gems.inspect %>
+
+main_spec = gemspecs.last || Bundler.load_gemspec(File.join __dir__, "<%= gem.name %>.gemspec")
+local_dependencies.each do |name|
+  spec_path = File.expand_path "../#{name}/#{name}.gemspec", __dir__
+  unless File.file? spec_path
+    warn "WARNING: Disabled local dependency for #{name} because gemspec not found."
+    next
+  end
+  version = Bundler.load_gemspec(spec_path).version
+  if main_spec.dependencies.any? { |dep| dep.name == name && !dep.requirement.satisfied_by?(version) }
+    warn "WARNING: Disabled local dependency for #{name} because the gemspec disallows version #{version}."
+    next
+  end
+  gem name, path: "../#{name}"
+end
+
+gem "google-style", "~> 1.30.1"
+gem "minitest", "~> 5.22"
+gem "minitest-focus", "~> 1.4"
+gem "minitest-rg", "~> 5.3"
+gem "rake", ">= 13.0"
+gem "redcarpet", "~> 3.6"
+gem "yard", "~> 0.9"

data/templates/cloud/wrapper_gem/{gemspec.erb → gemspec.text.erb}

@@ -10,7 +10,7 @@ Gem::Specification.new do |gem|
 
   gem.authors       = <%= gem.authors.inspect %>
   gem.email         = <%= gem.email.inspect %>
-  gem.description   = <%= gem.description.inspect %>
+  gem.description   = <%= gem.gemspec_description.inspect %>
   gem.summary       = <%= gem.summary.inspect %>
   gem.homepage      = <%= gem.homepage.inspect %>
   gem.license       = <%= gem.license_name.inspect %>
@@ -21,18 +21,9 @@ Gem::Specification.new do |gem|
                       <%= gem.extra_files.inspect %>
   gem.require_paths = ["lib"]
 
-  gem.required_ruby_version = ">= 2.5"
+  gem.required_ruby_version = ">= 3.0"
 
   <%- gem.dependency_list.each do |name, requirements| -%>
   gem.add_dependency <%= name.inspect %>, <%= requirements.map { |v| v.inspect }.join ", " %>
   <%- end -%>
-
-  gem.add_development_dependency "google-style", "~> 1.25.1"
-  gem.add_development_dependency "minitest", "~> 5.14"
-  gem.add_development_dependency "minitest-focus", "~> 1.1"
-  gem.add_development_dependency "minitest-rg", "~> 5.2"
-  gem.add_development_dependency "rake", ">= 12.0"
-  gem.add_development_dependency "redcarpet", "~> 3.0"
-  gem.add_development_dependency "simplecov", "~> 0.9"
-  gem.add_development_dependency "yard", "~> 0.9"
 end

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

@@ -17,43 +17,16 @@ Rake::TestTask.new do |t|
   t.warning = true
 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|
+  <%- if service && !gem.generic_endpoint? -%>
   project = args[:project]
   project ||=
     ENV["<%= gem.cloud_env_prefix %>_TEST_PROJECT"] ||
@@ -80,6 +53,7 @@ task :acceptance, :project, :keyfile do |t, args|
   ENV["<%= gem.cloud_env_prefix %>_TEST_PROJECT"] = project
   ENV["<%= gem.cloud_env_prefix %>_KEYFILE_JSON"] = keyfile
 
+  <%- end -%>
   Rake::Task["acceptance:run"].invoke
 end
 
@@ -92,10 +66,6 @@ namespace :acceptance do
     end
   end
 
-  desc "Run acceptance tests with coverage."
-  task :coverage do
-  end
-
   desc "Run acceptance cleanup."
   task :cleanup do
   end
@@ -148,11 +118,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/wrapper_gem/{readme.erb → readme.text.erb}

@@ -2,12 +2,16 @@
 
 <%= gem.summary %>
 
-<%= gem.description %>
+<%- if gem.summary != gem.description %>
+<% gem.readme_description.each do |line| %>
+<%= line %>
+<% end %>
+<%- end %>
 
 Actual client classes for the various versions of this API are defined in
 _versioned_ client gems, with names of the form `<%= gem.name %>-v*`.
 The gem `<%= gem.name %>` is the main client library that brings the
-verisoned gems in as dependencies, and provides high-level methods for
+versioned gems in as dependencies, and provides high-level methods for
 constructing clients. More information on versioned clients can be found below
 in the section titled *Which client should I use?*.
 
@@ -18,8 +22,7 @@ themselves can be found in the client library documentation for the versioned
 client gems:
 <%- last_index = gem.versioned_gems.size - 1 -%>
 <%- gem.versioned_gems.each_with_index do |name, i| -%>
-<%- sep = i == last_index ? "." : "," -%>
-[<%= name %>](https://googleapis.dev/ruby/<%= name %>/latest)<%= sep %>
+<%= gem.docs_link gem_name: name, text: name %><%= i == last_index ? "." : "," %>
 <%- end -%>
 
 <%- if gem.product_documentation_url -%>
@@ -47,7 +50,7 @@ In order to use this library, you first need to go through the following steps:
 <%- if gem.api_id -%>
 1. [Enable the API.](https://console.cloud.google.com/apis/library/<%= gem.api_id %>)
 <%- end -%>
-1. {file:AUTHENTICATION.md Set up authentication.}
+1. [Set up authentication.](AUTHENTICATION.md)
 
 <%- end -%>
 <%- if gem.migration? %>
@@ -60,42 +63,49 @@ versions of this library will likely require updates to use this version.
 See the {file:MIGRATING.md MIGRATING.md} document for more information.
 
 <%- end -%>
-## Enabling Logging
-
-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:
-
-```ruby
-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
-end
-```
+## 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.
+
+Debug logging also requires that the versioned clients for this service be
+sufficiently recent, released after about Dec 10, 2024. If logging is not
+working, try updating the versioned clients in your bundle or installed gems:
+<%- last_index = gem.versioned_gems.size - 1 -%>
+<%- gem.versioned_gems.each_with_index do |name, i| -%>
+<%= gem.docs_link gem_name: name, text: name %><%= i == last_index ? "." : "," %>
+<%- end -%>
 
 ## 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.
 
 ## Which client should I use?
 

data/templates/cloud/wrapper_gem/{version_test.erb → version_test.text.erb}

@@ -6,6 +6,6 @@ require "<%= gem.version_require %>"
 
 class <%= gem.namespace %>::VersionMinitest < Minitest::Test
   def test_has_a_version
-    refute_nil  <%= gem.version_name_full %>
+    refute_nil <%= gem.version_name_full %>
   end
 end

data/templates/cloud/wrapper_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