gapic-generator-cloud 0.3.1

data/cloud-rubocop.yml

@@ -0,0 +1,14 @@
+# This file is to be used as the config for formatting the generated cloud files.
+# We can't reference the generated .rubocop.yml file because Rubocop is so clevar
+# that it won't find the google-style gem unless the file is referenced here.
+inherit_gem:
+  google-style: google-style.yml
+
+AllCops:
+  Exclude:
+    - "acceptance/**/*"
+    - "*.gemspec"
+    - "lib/**/*_pb.rb"
+    - "Rakefile"
+    - "support/**/*"
+    - "test/**/*"

data/lib/gapic/generator/cloud/version.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+# Copyright 2018 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.
+
+module Gapic
+  module Generator
+    module Cloud
+      VERSION = "0.3.1"
+    end
+  end
+end

data/lib/gapic/generators/cloud_generator.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+# Copyright 2018 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/generators/default_generator"
+require "gapic/presenters"
+require "gapic/presenters/wrapper_gem_presenter"
+
+module Gapic
+  module Generators
+    # The generator orchestrates the rendering of templates for Google Cloud
+    # projects.
+    class CloudGenerator < DefaultGenerator
+      # Initializes the generator.
+      #
+      # @param api [Gapic::Schema::Api] The API model/context to
+      #   generate.
+      def initialize api
+        gem_config = api.configuration[:gem] ||= {}
+        gem_config[:homepage] ||= "https://github.com/googleapis/google-cloud-ruby"
+
+        super
+
+        # Configure to use prefer Google Cloud templates
+        use_templates! File.join __dir__, "../../../templates/cloud"
+      end
+
+      # Generates all the files for the API.
+      #
+      # @return [Array<
+      #   Google::Protobuf::Compiler::CodeGeneratorResponse::File>]
+      #   The files that were generated for the API.
+      def generate
+        gem_config = @api.configuration[:gem] ||= {}
+        return generate_wrapper if gem_config[:version_dependencies]
+
+        orig_files = super
+
+        cloud_files = []
+
+        gem = Gapic::Presenters.gem_presenter @api
+
+        # Additional Gem level files
+        cloud_files << g("gem/repo-metadata.erb",  ".repo-metadata.json", gem: gem)
+        cloud_files << g("gem/authentication.erb", "AUTHENTICATION.md",   gem: gem) unless gem.services.empty?
+
+        format_files cloud_files
+
+        orig_files + cloud_files
+      end
+
+      # Disable Rubocop because we expect generate to grow and violate more
+      # and more style rules.
+      # rubocop:disable all
+
+      # Generates the files for a wrapper.
+      #
+      # @return [Array<Google::Protobuf::Compiler::CodeGeneratorResponse::File>]
+      #   The files that were generated for the API.
+      #
+      def generate_wrapper
+        files = []
+
+        gem = Gapic::Presenters.wrapper_gem_presenter @api
+
+        files << g("gem/gitignore.erb",            ".gitignore",                                    gem: gem)
+        files << g("gem/repo-metadata.erb",        ".repo-metadata.json",                           gem: gem)
+        files << g("wrapper_gem/rubocop.erb",      ".rubocop.yml",                                  gem: gem)
+        files << g("wrapper_gem/yardopts.erb",     ".yardopts",                                     gem: gem)
+        files << g("gem/authentication.erb",       "AUTHENTICATION.md",                             gem: gem)
+        files << g("gem/changelog.erb",            "CHANGELOG.md",                                  gem: gem)
+        files << g("wrapper_gem/gemfile.erb",      "Gemfile",                                       gem: gem)
+        files << g("gem/license.erb",              "LICENSE.md",                                    gem: gem)
+        files << g("wrapper_gem/rakefile.erb",     "Rakefile",                                      gem: gem)
+        files << g("wrapper_gem/readme.erb",       "README.md",                                     gem: gem)
+        files << g("wrapper_gem/gemspec.erb",      "#{gem.name}.gemspec",                           gem: gem)
+        files << g("wrapper_gem/entrypoint.erb",   "lib/#{gem.name}.rb",                            gem: gem) if gem.needs_entrypoint?
+        files << g("wrapper_gem/main.erb",         "lib/#{gem.namespace_file_path}",                gem: gem)
+        files << g("gem/version.erb",              "lib/#{gem.version_file_path}",                  gem: gem)
+        files << g("wrapper_gem/test_helper.erb",  "test/helper.rb",                                gem: gem)
+        files << g("wrapper_gem/client_test.erb",  "test/#{gem.namespace_require}/client_test.rb",  gem: gem)
+        files << g("wrapper_gem/version_test.erb", "test/#{gem.namespace_require}/version_test.rb", gem: gem)
+
+        format_files files
+
+        files
+      end
+
+      # rubocop:enable all
+
+      private
+
+      ##
+      # Override the default rubocop config file to be used.
+      def format_config
+        @api.configuration[:format_config] ||
+          google_style_config
+      end
+
+      ##
+      # Path to the rubocop file for this project, which uses google-style
+      def google_style_config
+        File.expand_path File.join __dir__, "../../../cloud-rubocop.yml"
+      end
+    end
+  end
+end

data/lib/gapic/presenters/wrapper_gem_presenter.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+# Copyright 2019 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/presenters/wrapper_service_presenter"
+
+module Gapic
+  module Presenters
+    ##
+    # A presenter for wrapper gems.
+    #
+    class WrapperGemPresenter < GemPresenter
+      def entrypoint_require
+        namespace_require
+      end
+
+      def services
+        @services ||= begin
+          files = @api.generate_files
+          files.map(&:services).flatten.map { |s| WrapperServicePresenter.new @api, s }
+        end
+      end
+
+      def namespace_require
+        ruby_file_path @api, namespace
+      end
+
+      def namespace_file_path
+        "#{namespace_require}.rb"
+      end
+
+      def needs_entrypoint?
+        name != namespace_file_path
+      end
+
+      def needs_default_config_block?
+        needs_entrypoint? && !google_cloud_short_name.nil?
+      end
+
+      def migration_version
+        gem_config :migration_version
+      end
+
+      def pre_migration_version
+        m = /^(\d)+\./.match migration_version.to_s
+        return nil unless m
+        "#{m[1].to_i - 1}.x"
+      end
+
+      def migration?
+        migration_version ? true : false
+      end
+
+      def extra_files
+        files = ["README.md", "AUTHENTICATION.md", "LICENSE.md", ".yardopts"]
+        files << "MIGRATING.md" if migration?
+        files
+      end
+
+      def factory_method_suffix
+        gem_config(:factory_method_suffix).to_s
+      end
+
+      def version_dependencies
+        gem_config(:version_dependencies).to_s.split(";").map { |str| str.split ":" }
+      end
+
+      def gem_version_dependencies
+        version_dependencies.sort_by { |version, _requirement| version }
+                            .map { |version, requirement| ["#{name}-#{version}", requirement] }
+      end
+
+      def versioned_gems
+        gem_version_dependencies.map { |name, _requirement| name }
+      end
+
+      def default_version
+        version_dependencies.first&.first
+      end
+
+      def google_cloud_short_name
+        m = /^google-cloud-(.*)$/.match name
+        return nil unless m
+        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"
+        if class_name
+          path = namespace.gsub "::", "/"
+          path = "#{path}/#{version.capitalize}" if version
+          class_path = class_name.gsub "::", "/"
+          text ||= namespaced_class class_name, version: version
+          return "[#{text}](#{base_url}/#{path}/#{class_path}.html)"
+        end
+        "[#{text || name}](#{base_url})"
+      end
+
+      def namespaced_class name, version: nil
+        base = version ? "#{namespace}::#{version.capitalize}" : namespace
+        "#{base}::#{name}"
+      end
+    end
+
+    def self.wrapper_gem_presenter api
+      WrapperGemPresenter.new api
+    end
+  end
+end

data/lib/gapic/presenters/wrapper_service_presenter.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+# Copyright 2019 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"
+
+module Gapic
+  module Presenters
+    ##
+    # A presenter for wrapper services.
+    #
+    class WrapperServicePresenter < ServicePresenter
+      def gem
+        WrapperGemPresenter.new @api
+      end
+
+      def factory_method_name
+        method_name = ActiveSupport::Inflector.underscore name
+        suffix = gem.factory_method_suffix
+        method_name = "#{method_name}#{suffix}" unless method_name.end_with? suffix
+        method_name
+      end
+
+      def create_client_call
+        "#{gem.namespace}.#{factory_method_name}"
+      end
+
+      def configure_client_call
+        "#{gem.namespace}.configure"
+      end
+
+      def credentials_class_xref
+        "`#{credentials_name_full}`"
+      end
+    end
+  end
+end

data/templates/cloud/gem/authentication.erb

@@ -0,0 +1,172 @@
+<%- assert_locals gem -%>
+<%- service = gem.services.first -%>
+<%- assert_locals service -%>
+# Authentication
+
+In general, the <%= gem.name %> library uses
+[Service Account](https://cloud.google.com/iam/docs/creating-managing-service-accounts)
+credentials to connect to Google Cloud services. When running within
+[Google Cloud Platform environments](#google-cloud-platform-environments) the
+credentials will be discovered automatically. When running on other
+environments, the Service Account credentials can be specified by providing the
+path to the
+[JSON keyfile](https://cloud.google.com/iam/docs/managing-service-account-keys)
+for the account (or the JSON itself) in
+[environment variables](#environment-variables). Additionally, Cloud SDK
+credentials can also be discovered automatically, but this is only recommended
+during development.
+
+## Quickstart
+
+1. [Create a service account and credentials](#creating-a-service-account).
+2. Set the [environment variable](#environment-variables).
+
+```sh
+export <%= gem.env_prefix %>_CREDENTIALS=path/to/keyfile.json
+```
+
+3. Initialize the client.
+
+```ruby
+require "<%= gem.entrypoint_require %>"
+
+client = <%= service.create_client_call %>
+```
+
+## Credential Lookup
+
+The <%= gem.name %> library aims to make authentication
+as simple as possible, and provides several mechanisms to configure your system
+without requiring **Service Account Credentials** directly in code.
+
+**Credentials** are discovered in the following order:
+
+1. Specify credentials in method arguments
+2. Specify credentials in configuration
+3. Discover credentials path in environment variables
+4. Discover credentials JSON in environment variables
+5. Discover credentials file in the Cloud SDK's path
+6. Discover GCP credentials
+
+### 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 discovered automatically.
+Code should be written as if already authenticated.
+
+### Environment Variables
+
+The **Credentials JSON** can be placed in environment variables instead of
+declaring them directly in code. Each service has its own environment variable,
+allowing for different service accounts to be used for different services. (See
+the READMEs for the individual service gems for details.) The path to the
+**Credentials JSON** file can be stored in the environment variable, or the
+**Credentials JSON** itself can be stored for environments such as Docker
+containers where writing files is difficult or not encouraged.
+
+The environment variables that <%= gem.name %>
+checks for credentials are configured on the service Credentials class (such as
+<%= service.credentials_class_xref %>):
+
+1. `<%= gem.env_prefix %>_CREDENTIALS` - Path to JSON file, or JSON contents
+2. `<%= gem.env_prefix %>_KEYFILE` - Path to JSON file, or JSON contents
+3. `GOOGLE_CLOUD_CREDENTIALS` - Path to JSON file, or JSON contents
+4. `GOOGLE_CLOUD_KEYFILE` - Path to JSON file, or JSON contents
+5. `GOOGLE_APPLICATION_CREDENTIALS` - Path to JSON file
+
+```ruby
+require "<%= gem.entrypoint_require %>"
+
+ENV["<%= gem.env_prefix %>_CREDENTIALS"] = "path/to/keyfile.json"
+
+client = <%= service.create_client_call %>
+```
+
+### Configuration
+
+The **Credentials JSON** can be configured instead of placing them in
+environment variables. Either on an individual client initialization:
+
+```ruby
+require "<%= gem.entrypoint_require %>"
+
+client = <%= service.create_client_call %> do |config|
+  config.credentials = "path/to/keyfile.json"
+end
+```
+
+Or configured globally for all clients:
+
+```ruby
+require "<%= gem.entrypoint_require %>"
+
+<%= service.configure_client_call %> do |config|
+  config.credentials = "path/to/keyfile.json"
+end
+
+client = <%= service.create_client_call %>
+```
+
+### Cloud SDK
+
+This option allows for an easy way to authenticate during development. If
+credentials are not provided in code or in environment variables, then Cloud SDK
+credentials are discovered.
+
+To configure your system for this, simply:
+
+1. [Download and install the Cloud SDK](https://cloud.google.com/sdk)
+2. Authenticate using OAuth 2.0 `$ gcloud auth login`
+3. Write code as if already authenticated.
+
+**NOTE:** This is _not_ recommended for running in production. The Cloud SDK
+*should* only be used during development.
+
+[gce-how-to]: https://cloud.google.com/compute/docs/authentication#using
+[dev-console]: https://console.cloud.google.com/project
+
+[enable-apis]: https://raw.githubusercontent.com/GoogleCloudPlatform/gcloud-common/master/authentication/enable-apis.png
+
+[create-new-service-account]: https://raw.githubusercontent.com/GoogleCloudPlatform/gcloud-common/master/authentication/create-new-service-account.png
+[create-new-service-account-existing-keys]: https://raw.githubusercontent.com/GoogleCloudPlatform/gcloud-common/master/authentication/create-new-service-account-existing-keys.png
+[reuse-service-account]: https://raw.githubusercontent.com/GoogleCloudPlatform/gcloud-common/master/authentication/reuse-service-account.png
+
+## Creating a Service Account
+
+Google Cloud requires **Service Account Credentials** to
+connect to the APIs. You will use the **JSON key file** to
+connect to most services with <%= gem.name %>.
+
+If you are not running this client within
+[Google Cloud Platform environments](#google-cloud-platform-environments), you
+need a Google Developers service account.
+
+1. Visit the [Google Developers Console][dev-console].
+2. Create a new project or click on an existing project.
+3. Activate the slide-out navigation tray and select **API Manager**. From
+   here, you will enable the APIs that your application requires.
+
+   ![Enable the APIs that your application requires][enable-apis]
+
+   *Note: You may need to enable billing in order to use these services.*
+
+4. Select **Credentials** from the side navigation.
+
+   You should see a screen like one of the following.
+
+   ![Create a new service account][create-new-service-account]
+
+   ![Create a new service account With Existing Keys][create-new-service-account-existing-keys]
+
+   Find the "Add credentials" drop down and select "Service account" to be
+   guided through downloading a new JSON key file.
+
+   If you want to re-use an existing service account, you can easily generate a
+   new key file. Just select the account you wish to re-use, and click "Generate
+   new JSON key":
+
+   ![Re-use an existing service account][reuse-service-account]
+
+   The key file you download will be used by this library to authenticate API
+   requests and should be stored in a secure location.