gapic-generator-cloud 0.5.0

data/templates/cloud/gem/readme.erb

@@ -0,0 +1,93 @@
+# Ruby Client for the <%= gem.title %> API
+
+<%= gem.summary %>
+
+<%= gem.description %>
+
+<%= gem.homepage %>
+
+## Installation
+
+```
+$ gem install <%= gem.name %>
+```
+
+## Before You Begin
+
+In order to use this library, you first need to go through the following steps:
+
+1. [Select or create a Cloud Platform project.](https://console.cloud.google.com/project)
+<%- if gem.free_tier? -%>
+1. This API has a free tier. You may not need to
+   [enable billing](https://cloud.google.com/billing/docs/how-to/modify-project#enable_billing_for_a_project)
+   to get started.
+<%- else -%>
+1. [Enable billing for your project.](https://cloud.google.com/billing/docs/how-to/modify-project#enable_billing_for_a_project)
+<%- end -%>
+<%- if gem.api_id -%>
+1. [Enable the API.](https://console.cloud.google.com/apis/library/<%= gem.api_id %>.googleapis.com)
+<%- end -%>
+1. {file:AUTHENTICATION.md Set up authentication.}
+
+## Quick Start
+
+<%- if gem.packages? -%>
+```ruby
+require "<%= gem.entrypoint_require %>"
+<%- service = gem.packages.first.services.first -%>
+<%- method = service&.methods.first -%>
+<%- if service && method -%>
+
+client = <%= service.create_client_call %>
+request = my_create_request
+response = client.<%= method.name %> request
+<%- end -%>
+```
+
+<%- end -%>
+<%- unless gem.library_documentation_url.to_s.empty? -%>
+View the [Client Library Documentation](<%= gem.library_documentation_url %>)
+for class and method documentation.
+
+<%- end -%>
+<%- if gem.product_documentation_url -%>
+See also the [Product Documentation](<%= gem.product_documentation_url %>)
+for general usage 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
+```
+
+## Supported Ruby Versions
+
+This library is supported on Ruby 2.4+.
+
+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.4
+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.

data/templates/cloud/gem/repo-metadata.erb

@@ -0,0 +1,6 @@
+<%- assert_locals gem -%>
+{
+    "language": "ruby",
+    "distribution_name": "<%= gem.name %>",
+    "client_documentation": "https://googleapis.dev/ruby/<%= gem.name %>/latest"
+}

data/templates/cloud/gem/rubocop.erb

@@ -0,0 +1,36 @@
+<%- assert_locals gem -%>
+inherit_gem:
+  google-style: google-style.yml
+
+AllCops:
+  Exclude:
+    - "<%= gem.name %>.gemspec"
+    - "lib/**/*_pb.rb"
+    - "proto_docs/**/*"
+    - "test/**/*"
+    - "acceptance/**/*"
+    - "Rakefile"
+
+Metrics/AbcSize:
+  Enabled: false
+Metrics/ClassLength:
+  Enabled: false
+Metrics/CyclomaticComplexity:
+  Enabled: false
+Metrics/LineLength:
+  Enabled: false
+Metrics/MethodLength:
+  Enabled: false
+Metrics/ModuleLength:
+  Enabled: false
+Metrics/PerceivedComplexity:
+  Enabled: false
+Naming/FileName:
+  Exclude:
+    - "lib/<%= gem.name %>.rb"
+Style/CaseEquality:
+  Enabled: false
+Style/IfUnlessModifier:
+  Enabled: false
+Style/ModuleFunction:
+  Enabled: false

data/templates/cloud/gem/yardopts.erb

@@ -0,0 +1,13 @@
+<%- assert_locals gem -%>
+--no-private
+--title=<%= gem.title %> API
+--exclude _pb\.rb$
+--markup markdown
+--markup-provider redcarpet
+
+./lib/**/*.rb
+./proto_docs/**/*.rb
+-
+README.md
+LICENSE.md
+AUTHENTICATION.md

data/templates/cloud/service/client/_credentials.erb

@@ -0,0 +1,30 @@
+<%- assert_locals service -%>
+<% @requires = capture do %>
+require "googleauth"
+<% end %>
+# Credentials for the <%= service.name %> API.
+class <%= service.credentials_name %> < ::Google::Auth::Credentials
+  <%- if service.client_scopes.any? -%>
+  self.scope = [
+  <%- service.client_scopes.each_with_index do |client_scope, index| -%>
+    <%- comma = index == service.client_scopes.count - 1 ? "" : "," -%>
+    <%= client_scope.inspect %><%= comma %>
+  <%- end -%>
+  ]
+  <%- end -%>
+  self.env_vars = [
+    "<%= service.gem.env_prefix %>_CREDENTIALS",
+    "<%= service.gem.env_prefix %>_KEYFILE",
+    "GOOGLE_CLOUD_CREDENTIALS",
+    "GOOGLE_CLOUD_KEYFILE",
+    "GCLOUD_KEYFILE",
+    "<%= service.gem.env_prefix %>_CREDENTIALS_JSON",
+    "<%= service.gem.env_prefix %>_KEYFILE_JSON",
+    "GOOGLE_CLOUD_CREDENTIALS_JSON",
+    "GOOGLE_CLOUD_KEYFILE_JSON",
+    "GCLOUD_KEYFILE_JSON"
+  ]
+  self.paths = [
+    "~/.config/google_cloud/application_default_credentials.json"
+  ]
+end

data/templates/cloud/service/client/_requires.erb

@@ -0,0 +1,2 @@
+<%- assert_locals service -%>
+require "google/cloud/errors"

data/templates/cloud/service/client/_self_configure.erb

@@ -0,0 +1,15 @@
+<%- assert_locals service -%>
+@configure ||= begin
+  namespace = <%= service.namespace.split("::").reject(&:empty?).inspect %>
+  parent_config = while namespace.any?
+                    parent_name = namespace.join "::"
+                    parent_const = const_get parent_name
+                    break parent_const.configure if parent_const&.respond_to? :configure
+                    namespace.pop
+                  end
+  default_config = <%= service.client_name %>::Configuration.new parent_config
+  <%= render partial: "service/client/self_configure_defaults", locals: {service: service} %>
+  default_config
+end
+yield @configure if block_given?
+@configure

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

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

data/templates/cloud/service/client/method/docs/_error.erb

@@ -0,0 +1,2 @@
+<%- assert_locals method -%>
+# @raise [::Google::Cloud::Error] if the RPC is aborted.

data/templates/cloud/shared/_license.erb

@@ -0,0 +1,13 @@
+# Copyright <%= Time.now.year %> 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.

data/templates/cloud/wrapper_gem/_main.erb

@@ -0,0 +1,102 @@
+<%- assert_locals gem -%>
+<% @requires = capture do %>
+# Require this file early so that the version constant gets defined before
+# requiring "google/cloud". This is because google-cloud-core will load the
+# entrypoint (gem name) file, which in turn re-requires this file (hence
+# causing a require cycle) unless the version constant is already defined.
+require "<%= gem.version_require %>"
+
+require "googleauth"
+<%- if gem.needs_default_config_block? -%>
+gem "google-cloud-core"
+require "google/cloud" unless defined? ::Google::Cloud.new
+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! :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
+  config.add_field! :interceptors,  nil, match: ::Array
+  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
+end
+<%- end -%>
+<% end %>
+<%- gem.services.each do |service| -%>
+##
+# 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
+# `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.doc_description -%>
+# ## About <%= service.module_name %>
+#
+<%= indent service.doc_description(disable_xrefs: true), "# " %>
+#
+<%- 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.
+#
+def self.<%= service.factory_method_name %> version: :<%= gem.default_version %>, &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)
+end
+
+<%- end -%>
+<%- if gem.google_cloud_short_name -%>
+##
+# Configure the <%= gem.name %> library.
+#
+# The following configuration parameters are supported:
+#
+# * `credentials` (*type:* `String, Hash, Google::Auth::Credentials`) -
+#   The path to the keyfile as a String, the contents of the keyfile as a
+#   Hash, or a Google::Auth::Credentials object.
+# * `lib_name` (*type:* `String`) -
+#   The library name as recorded in instrumentation and logging.
+# * `lib_version` (*type:* `String`) -
+#   The library version as recorded in instrumentation and logging.
+# * `interceptors` (*type:* `Array<GRPC::ClientInterceptor>`) -
+#   An array of interceptors that are run before calls are executed.
+# * `timeout` (*type:* `Integer`) -
+#   Default timeout in milliseconds.
+# * `metadata` (*type:* `Hash{Symbol=>String}`) -
+#   Additional gRPC 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.
+#     * `:max_delay` (*type:* `Numeric`) - The max delay in seconds.
+#     * `:multiplier` (*type:* `Numeric`) - The incremental backoff multiplier.
+#     * `:retry_codes` (*type:* `Array<String>`) -
+#       The error codes that should trigger a retry.
+#
+# @return [::Google::Cloud::Config] The default configuration used by this library
+#
+def self.configure
+  yield ::Google::Cloud.configure.<%= gem.google_cloud_short_name %> if block_given?
+
+  ::Google::Cloud.configure.<%= gem.google_cloud_short_name %>
+end
+<%- end -%>
+<% @footer = capture do %>
+helper_path = ::File.join __dir__, "<%= gem.main_directory_name %>", "helpers.rb"
+require "<%= gem.helpers_require %>" if ::File.file? helper_path
+<% end %>

data/templates/cloud/wrapper_gem/client_test.erb

@@ -0,0 +1,22 @@
+<%- assert_locals gem -%>
+<%= render partial: "shared/header" -%>
+
+require "helper"
+require "<%= gem.namespace_require %>"
+require "gapic/common"
+require "gapic/grpc"
+
+class <%= gem.namespace %>::ClientConstructionMinitest < Minitest::Test
+<%- gem.services.each do |service| -%>
+  def test_<%= service.factory_method_name %>
+    Gapic::ServiceStub.stub :new, :stub do
+      grpc_channel = GRPC::Core::Channel.new "localhost:8888", nil, :this_channel_is_insecure
+      client = <%= gem.namespace %>.<%= service.factory_method_name %> do |config|
+        config.credentials = grpc_channel
+      end
+      assert_kind_of <%= gem.namespaced_class "#{service.module_name}::Client", version: gem.default_version %>, client
+    end
+  end
+
+<%- end -%>
+end

data/templates/cloud/wrapper_gem/entrypoint.erb

@@ -0,0 +1,4 @@
+<%- assert_locals gem -%>
+<%= render partial: "shared/header" -%>
+
+require "<%= gem.namespace_require %>" unless defined? <%= gem.namespace %>::VERSION

data/templates/cloud/wrapper_gem/gemfile.erb

@@ -0,0 +1,14 @@
+<%- assert_locals gem -%>
+source "https://rubygems.org"
+
+gemspec
+
+gem "google-cloud-core", path: "../google-cloud-core"
+gem "google-cloud-env", path: "../google-cloud-env"
+gem "google-cloud-errors", path: "../google-cloud-errors"
+<%- gem.gem_version_dependencies.each do |name, _requirement| -%>
+gem "<%= name %>", path: "../<%= name %>"
+<%- end -%>
+
+# google-protobuf 3.12.0 requires Ruby 2.5 or later, so pin to 3.11 on older Rubies
+gem "google-protobuf", (RUBY_VERSION < "2.5" ? "~> 3.11.4" : "~> 3.12")

data/templates/cloud/wrapper_gem/gemspec.erb

@@ -0,0 +1,39 @@
+<%- assert_locals gem -%>
+# -*- ruby -*-
+# encoding: utf-8
+
+require File.expand_path("lib/<%= gem.version_require %>", __dir__)
+
+Gem::Specification.new do |gem|
+  gem.name          = "<%= gem.name %>"
+  gem.version       = <%= gem.version_name_full %>
+
+  gem.authors       = <%= gem.authors.inspect %>
+  gem.email         = <%= gem.email.inspect %>
+  gem.description   = <%= gem.description.inspect %>
+  gem.summary       = <%= gem.summary.inspect %>
+  gem.homepage      = <%= gem.homepage.inspect %>
+  gem.license       = "Apache-2.0"
+
+  gem.platform      = Gem::Platform::RUBY
+
+  gem.files         = `git ls-files -- lib/*`.split("\n") +
+                      <%= gem.extra_files.inspect %>
+  gem.require_paths = ["lib"]
+
+  gem.required_ruby_version = ">= 2.4"
+
+  gem.add_dependency "google-cloud-core", "~> 1.5"
+  <%- gem.gem_version_dependencies.each do |name, requirement| -%>
+  gem.add_dependency "<%= name %>", "~> <%= requirement %>"
+  <%- end -%>
+
+  gem.add_development_dependency "google-style", "~> 1.24.0"
+  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/main.erb

@@ -0,0 +1,5 @@
+<%- assert_locals gem -%>
+<%= render partial: "wrapper_gem/main",
+           layout: "layouts/ruby",
+           locals: { gem: gem, namespace: gem.namespace }
+%>

data/templates/cloud/wrapper_gem/rakefile.erb

@@ -0,0 +1,190 @@
+<%- assert_locals gem -%>
+<%- service = gem.services.first -%>
+<%- assert_locals service -%>
+<%= render partial: "shared/header" -%>
+
+require "bundler/setup"
+require "bundler/gem_tasks"
+
+require "rubocop/rake_task"
+RuboCop::RakeTask.new
+
+require "rake/testtask"
+desc "Run tests."
+Rake::TestTask.new do |t|
+  t.libs << "test"
+  t.test_files = FileList["test/**/*_test.rb"]
+  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|
+  project = args[:project]
+  project ||=
+    ENV["<%= gem.env_prefix %>_TEST_PROJECT"] ||
+    ENV["GCLOUD_TEST_PROJECT"]
+  keyfile = args[:keyfile]
+  keyfile ||=
+    ENV["<%= gem.env_prefix %>_TEST_KEYFILE"] ||
+    ENV["GCLOUD_TEST_KEYFILE"]
+  if keyfile
+    keyfile = File.read keyfile
+  else
+    keyfile ||=
+      ENV["<%= gem.env_prefix %>_TEST_KEYFILE_JSON"] ||
+      ENV["GCLOUD_TEST_KEYFILE_JSON"]
+  end
+  if project.nil? || keyfile.nil?
+    fail "You must provide a project and keyfile. e.g. rake acceptance[test123, /path/to/keyfile.json] or <%= gem.env_prefix %>_TEST_PROJECT=test123 <%= gem.env_prefix %>_TEST_KEYFILE=/path/to/keyfile.json rake acceptance"
+  end
+  require "<%= service.credentials_require %>"
+  <%= service.credentials_name_full %>.env_vars.each do |path|
+    ENV[path] = nil
+  end
+  ENV["<%= gem.env_prefix %>_PROJECT"] = project
+  ENV["<%= gem.env_prefix %>_TEST_PROJECT"] = project
+  ENV["<%= gem.env_prefix %>_KEYFILE_JSON"] = keyfile
+
+  Rake::Task["acceptance:run"].invoke
+end
+
+namespace :acceptance do
+  task :run do
+    if File.directory? "acceptance"
+      Rake::Task[:smoke_test].invoke
+    else
+      puts "The <%= gem.name %> gem has no acceptance tests."
+    end
+  end
+
+  desc "Run acceptance tests with coverage."
+  task :coverage do
+  end
+
+  desc "Run acceptance cleanup."
+  task :cleanup do
+  end
+end
+
+task :samples do
+  Rake::Task["samples:latest"].invoke
+end
+
+namespace :samples do
+  task :latest do
+    if File.directory? "samples"
+      Dir.chdir "samples" do
+        Bundler.with_clean_env do
+          ENV["GOOGLE_CLOUD_SAMPLES_TEST"] = "not_master"
+          sh "bundle update"
+          sh "bundle exec rake test"
+        end
+      end
+    else
+      puts "The <%= gem.name %> gem has no samples to test."
+    end
+  end
+
+  task :master do
+    if File.directory? "samples"
+      Dir.chdir "samples" do
+        Bundler.with_clean_env do
+          ENV["GOOGLE_CLOUD_SAMPLES_TEST"] = "master"
+          sh "bundle update"
+          sh "bundle exec rake test"
+        end
+      end
+    else
+      puts "The <%= gem.name %> gem has no samples to test."
+    end
+  end
+end
+
+require "yard"
+require "yard/rake/yardoc_task"
+YARD::Rake::YardocTask.new do |y|
+<%- if gem.yard_strict? -%>
+  y.options << "--fail-on-warning"
+<%- end -%>
+end
+
+desc "Run yard-doctest example tests."
+task :doctest do
+  puts "The <%= gem.name %> gem does not have doctest tests."
+end
+
+desc "Run the CI build"
+task :ci do
+  header "BUILDING <%= gem.name %>"
+  header "<%= gem.name %> rubocop", "*"
+  Rake::Task[:rubocop].invoke
+  header "<%= gem.name %> yard", "*"
+  Rake::Task[:yard].invoke
+  header "<%= gem.name %> test", "*"
+  Rake::Task[:test].invoke
+end
+
+namespace :ci do
+  desc "Run the CI build, with smoke tests."
+  task :smoke_test do
+    Rake::Task[:ci].invoke
+    header "<%= gem.name %> smoke_test", "*"
+    Rake::Task[:smoke_test].invoke
+  end
+  desc "Run the CI build, with acceptance tests."
+  task :acceptance do
+    Rake::Task[:ci].invoke
+    header "<%= gem.name %> acceptance", "*"
+    Rake::Task[:acceptance].invoke
+  end
+  task :a do
+    # This is a handy shortcut to save typing
+    Rake::Task["ci:acceptance"].invoke
+  end
+end
+
+task default: :test
+
+def header str, token = "#"
+  line_length = str.length + 8
+  puts ""
+  puts token * line_length
+  puts "#{token * 3} #{str} #{token * 3}"
+  puts token * line_length
+  puts ""
+end