gapic-generator-cloud 0.1.7 → 0.2.0

data/templates/cloud/gem/rubocop.erb

@@ -4,9 +4,12 @@ inherit_gem:
 
 AllCops:
   Exclude:
+    - "<%= gem.name %>.gemspec"
     - "lib/**/*_pb.rb"
     - "proto_docs/**/*"
     - "test/**/*"
+    - "acceptance/**/*"
+    - "Rakefile"
 
 Metrics/AbcSize:
   Exclude:

data/templates/cloud/gem/yardopts.erb

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

data/templates/cloud/wrapper_gem/_main.erb

@@ -0,0 +1,75 @@
+<%- assert_locals gem -%>
+<% @requires = capture do %>
+<%- if gem.needs_dashed_ruby_file? -%>
+require "<%= gem.name %>"
+<%- end -%>
+<% end %>
+<%- gem.services.each do |service| -%>
+##
+# Create a new client object for <%= service.name %>.
+#
+# By default, this returns an instance of
+# <%= gem.docs_link version: gem.default_version, class_name: "#{service.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.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.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.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.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 -%>

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.name}::Client", version: gem.default_version %>, client
+    end
+  end
+
+<%- end -%>
+end

data/templates/cloud/wrapper_gem/dashed.erb

@@ -0,0 +1,22 @@
+<%- assert_locals gem -%>
+<%= render partial: "shared/header" -%>
+
+<%- if gem.google_cloud_short_name -%>
+gem "google-cloud-core"
+require "google/cloud" unless defined? Google::Cloud.new
+require "google/cloud/config"
+require "googleauth"
+
+# Set the default configuration
+Google::Cloud.configure.add_config! :<%= gem.google_cloud_short_name %> do |config|
+  config.add_field! :credentials,  nil, match: [String, Hash, Google::Auth::Credentials]
+  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]
+end
+
+<%- end -%>
+require "<%= gem.version_require %>"

data/templates/cloud/wrapper_gem/gemfile.erb

@@ -0,0 +1,17 @@
+<%- 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 -%>
+
+gem "rake"
+
+# Pin minitest to 5.11.x to avoid warnings emitted by 5.12.
+# See https://github.com/googleapis/google-cloud-ruby/issues/4110
+gem "minitest", "~> 5.11.3"

data/templates/cloud/wrapper_gem/gemspec.erb

@@ -0,0 +1,40 @@
+<%- 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 "autotest-suffix", "~> 1.1"
+  gem.add_development_dependency "google-style", "~> 1.24.0"
+  gem.add_development_dependency "minitest", "~> 5.10"
+  gem.add_development_dependency "minitest-autotest", "~> 1.0"
+  gem.add_development_dependency "minitest-focus", "~> 1.1"
+  gem.add_development_dependency "minitest-rg", "~> 5.2"
+  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_master"
+        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_master"
+        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

data/templates/cloud/wrapper_gem/readme.erb

@@ -0,0 +1,95 @@
+# Ruby Client for the <%= gem.title %> API
+
+<%= gem.summary %>
+
+<%= gem.description %>
+
+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 a convenience wrapper library that brings the
+verisoned gems in as dependencies, and provides high-level methods for
+constructing clients.
+
+View the [Client Library Documentation](<%= gem.library_documentation_url %>)
+for this library, <%= gem.name %>, to see the convenience methods for
+constructing client objects. Reference documentation for the client objects
+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 %>
+<%- end -%>
+
+<%- if gem.product_documentation_url -%>
+See also the [Product Documentation](<%= gem.product_documentation_url %>)
+for more usage information.
+
+<%- end -%>
+## Quick Start
+
+```
+$ gem install <%= gem.name %>
+```
+
+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.}
+
+<%- if gem.migration? %>
+## Migrating from <%= gem.pre_migration_version %> versions
+
+The <%= gem.migration_version %> release of the <%= gem.name %> client is a significant upgrade
+based on a [next-gen code generator](https://github.com/googleapis/gapic-generator-ruby),
+and includes substantial interface changes. Existing code written for earlier
+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 [Stackdriver 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.