appengine 0.4.6 → 0.7.0

data/lib/appengine/tasks.rb

@@ -1,4 +1,6 @@
-# Copyright 2017 Google Inc. All rights reserved.
+# 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.
@@ -11,19 +13,14 @@
 # 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.
-;
 
-# This file should be loaded or required from a Rakefile to define AppEngine
-# related tasks.
 
 require "shellwords"
 
 require "appengine/util/gcloud"
 require "appengine/exec"
 
-
 module AppEngine
-
   ##
   # # App Engine Rake Tasks.
   #
@@ -66,6 +63,16 @@ module AppEngine
   #
   # The following environment variable parameters are supported:
   #
+  # #### GAE_TIMEOUT
+  #
+  # Amount of time to wait before appengine:exec terminates the command.
+  # Expressed as a string formatted like: "2h15m10s". Default is "10m".
+  #
+  # #### GAE_PROJECT
+  #
+  # The ID of your Google Cloud project. If not specified, uses the current
+  # project from gcloud.
+  #
   # #### GAE_CONFIG
   #
   # Path to the App Engine config file, used when your app has multiple
@@ -74,22 +81,47 @@ module AppEngine
   #
   # #### GAE_SERVICE
   #
-  # Name of the service to be used. If both `GAE_CONFIG` and `GAE_SERVICE` are
-  # provided and imply different service names, an error will be raised.
+  # Name of the service to be used. Overrides any service name specified in
+  # your config file.
+  #
+  # #### GAE_EXEC_STRATEGY
+  #
+  # The execution strategy to use. Valid values are "deployment" (which is the
+  # default for App Engine Standard apps) and "cloud_build" (which is the
+  # default for App Engine Flexible apps).
+  #
+  # Normally you should leave the strategy set to the default. The main reason
+  # to change it is if your app runs on the Flexible Environment and talks to
+  # a database over a VPC (using a private IP address). The "cloud_build"
+  # strategy used by default for Flexible apps cannot connect to a VPC, so you
+  # should use "deployment" in this case. (But note that, otherwise, the
+  # "deployment" strategy is significantly slower for apps on the Flexible
+  # environment.)
   #
   # #### GAE_VERSION
   #
   # The version of the service, used to identify which application image to
   # use to run your command. If not specified, uses the most recently created
   # version, regardless of whether that version is actually serving traffic.
+  # Applies only to the "cloud_build" strategy. (The "deployment" strategy
+  # deploys its own temporary version of your app.)
   #
-  # #### GAE_TIMEOUT
+  # #### GAE_EXEC_WRAPPER_IMAGE
   #
-  # Amount of time to wait before appengine:exec terminates the command.
-  # Expressed as a string formatted like: "2h15m10s". Default is "10m".
+  # The fully-qualified name of the wrapper image to use. (This is a Docker
+  # image that emulates the App Engine environment in Google Cloud Build for
+  # the "cloud_build" strategy, and applies only to that strategy.) Normally,
+  # you should not override this unless you are testing a new wrapper.
+  #
+  # #### CLOUD_BUILD_GCS_LOG_DIR
   #
+  # GCS bucket name of the cloud build log when GAE_STRATEGY is "cloud_build".
+  # (ex. "gs://BUCKET-NAME/FOLDER-NAME")
   module Tasks
-
+    ## @private
+    PROJECT_ENV = "GAE_PROJECT"
+    ## @private
+    STRATEGY_ENV = "GAE_EXEC_STRATEGY"
     ## @private
     CONFIG_ENV = "GAE_CONFIG"
     ## @private
@@ -100,11 +132,12 @@ module AppEngine
     TIMEOUT_ENV = "GAE_TIMEOUT"
     ## @private
     WRAPPER_IMAGE_ENV = "GAE_EXEC_WRAPPER_IMAGE"
+    ## @private
+    GCS_LOG_DIR = "CLOUD_BUILD_GCS_LOG_DIR"
 
     @defined = false
 
     class << self
-
       ##
       # @private
       # Define rake tasks.
@@ -123,189 +156,230 @@ module AppEngine
 
       def setup_exec_task
         ::Rake.application.last_description =
-            "Execute the given command in Google App Engine."
-        ::Rake::Task.define_task "appengine:exec", [:cmd] do |t, args|
+          "Execute the given command in Google App Engine."
+        ::Rake::Task.define_task "appengine:exec", [:cmd] do |_t, args|
           verify_gcloud_and_report_errors
-          if args[:cmd]
-            command = ::Shellwords.split args[:cmd]
-          else
-            i = (::ARGV.index{ |a| a.to_s == "--" } || -1) + 1
-            if i == 0
-              report_error <<-MESSAGE
-No command provided for appengine:exec.
-Did you remember to delimit it with two dashes? e.g.
-  bundle exec rake appengine:exec -- bundle exec ruby myscript.rb
-For detailed usage instructions, provide two dashes but no command:
-  bundle exec rake appengine:exec --
-              MESSAGE
-            end
-            command = ::ARGV[i..-1]
-            if command.empty?
-              show_usage
-              exit
-            end
-          end
-          app_exec = Exec.new \
-              command,
-              service: ::ENV[SERVICE_ENV],
-              config_path: ::ENV[CONFIG_ENV],
-              version: ::ENV[VERSION_ENV],
-              timeout: ::ENV[TIMEOUT_ENV],
-              wrapper_image: ::ENV[WRAPPER_IMAGE_ENV]
+          command = extract_command args[:cmd], ::ARGV
+          app_exec = Exec.new command,
+                              project:       ::ENV[PROJECT_ENV],
+                              service:       ::ENV[SERVICE_ENV],
+                              config_path:   ::ENV[CONFIG_ENV],
+                              version:       ::ENV[VERSION_ENV],
+                              timeout:       ::ENV[TIMEOUT_ENV],
+                              wrapper_image: ::ENV[WRAPPER_IMAGE_ENV],
+                              strategy:      ::ENV[STRATEGY_ENV],
+                              gcs_log_dir:   ::ENV[GCS_LOG_DIR]
           start_and_report_errors app_exec
           exit
         end
       end
 
+      def extract_command cmd, argv
+        if cmd
+          ::Shellwords.split cmd
+        else
+          i = (argv.index { |a| a.to_s == "--" } || -1) + 1
+          if i.zero?
+            report_error <<~MESSAGE
+              No command provided for appengine:exec.
+              Did you remember to delimit it with two dashes? e.g.
+              bundle exec rake appengine:exec -- bundle exec ruby myscript.rb
+              For detailed usage instructions, provide two dashes but no command:
+              bundle exec rake appengine:exec --
+            MESSAGE
+          end
+          command = ::ARGV[i..-1]
+          if command.empty?
+            show_usage
+            exit
+          end
+          command
+        end
+      end
+
       def show_usage
-        puts <<-USAGE
-rake appengine:exec
+        puts <<~USAGE
+          rake appengine:exec
+
+          This Rake task executes a given command in the context of an App Engine
+          application, using App Engine remote execution. For more information,
+          on this capability, see the AppEngine::Exec documentation at
+          http://www.rubydoc.info/gems/appengine/AppEngine/Exec
+
+          The command to be run may either be provided as a rake argument, or as
+          command line arguments delimited by two dashes `--`. (The dashes are
+          needed to separate your command from rake arguments and flags.)
+          For example, to run a production database migration, you can run either
+          of the following equivalent commands:
+
+              bundle exec rake "appengine:exec[bundle exec bin/rails db:migrate]"
+              bundle exec rake appengine:exec -- bundle exec bin/rails db:migrate
+
+          To display these usage instructions, provide two dashes but no command:
 
-This Rake task executes a given command in the context of an App Engine
-application, using App Engine remote execution. For more information,
-on this capability, see the AppEngine::Exec documentation at
-http://www.rubydoc.info/gems/appengine/AppEngine/Exec
+              bundle exec rake appengine:exec --
 
-The command to be run may either be provided as a rake argument, or as
-command line arguments delimited by two dashes `--`. (The dashes are
-needed to separate your command from rake arguments and flags.)
-For example, to run a production database migration, you can run either
-of the following equivalent commands:
+          You may customize the behavior of App Engine execution through a few
+          enviroment variable parameters. These are set via the normal mechanism at
+          the end of a rake command line but before the double dash. For example, to
+          set GAE_CONFIG:
 
-    bundle exec rake "appengine:exec[bundle exec bin/rails db:migrate]"
-    bundle exec rake appengine:exec -- bundle exec bin/rails db:migrate
+              bundle exec rake appengine:exec GAE_CONFIG=myservice.yaml -- bundle exec bin/rails db:migrate
 
-To display these usage instructions, provide two dashes but no command:
+          Be sure to set these parameters before the double dash. Any arguments
+          following the double dash are interpreted as part of the command itself.
 
-    bundle exec rake appengine:exec --
+          The following environment variable parameters are supported:
 
-You may customize the behavior of App Engine execution through a few
-enviroment variable parameters. These are set via the normal mechanism at
-the end of a rake command line. For example, to set GAE_CONFIG:
+          GAE_TIMEOUT
 
-    bundle exec rake appengine:exec GAE_CONFIG=myservice.yaml -- bundle exec bin/rails db:migrate
+            Amount of time to wait before appengine:exec terminates the command.
+            Expressed as a string formatted like: "2h15m10s". Default is "10m".
 
-Be sure to set these parameters before the double dash. Any arguments
-following the double dash are interpreted as part of the command itself.
+          GAE_PROJECT
 
-The following environment variable parameters are supported:
+            The ID of your Google Cloud project. If not specified, uses the current
+            project from gcloud.
 
-GAE_CONFIG
+          GAE_CONFIG
 
-  Path to the App Engine config file, used when your app has multiple
-  services, or the config file is otherwise not called `./app.yaml`. The
-  config file is used to determine the name of the App Engine service.
+            Path to the App Engine config file, used when your app has multiple
+            services, or the config file is otherwise not called `./app.yaml`. The
+            config file is used to determine the name of the App Engine service.
 
-GAE_SERVICE
+          GAE_SERVICE
 
-  Name of the service to be used. If both `GAE_CONFIG` and `GAE_SERVICE`
-  are provided and imply different service names, an error will be raised.
+            Name of the service to be used. Overrides any service name specified in
+            your config file.
 
-GAE_VERSION
+          GAE_EXEC_STRATEGY
 
-  The version of the service, used to identify which application image to
-  use to run your command. If not specified, uses the most recently created
-  version, regardless of whether that version is actually serving traffic.
+            The execution strategy to use. Valid values are "deployment" (which is the
+            default for App Engine Standard apps) and "cloud_build" (which is the
+            default for App Engine Flexible apps).
 
-GAE_TIMEOUT
+            Normally you should leave the strategy set to the default. The main reason
+            to change it is if your app runs on the Flexible Environment and talks to
+            a database over a VPC (using a private IP address). The "cloud_build"
+            strategy used by default for Flexible apps cannot connect to a VPC, so you
+            should use "deployment" in this case. (But note that, otherwise, the
+            "deployment" strategy is significantly slower for apps on the Flexible
+            environment.)
 
-  Amount of time to wait before appengine:exec terminates the command.
-  Expressed as a string formatted like: "2h15m10s". Default is "10m".
+          GAE_VERSION
 
-This rake task is provided by the "appengine" gem. To make these tasks
-available, add the following line to your Rakefile:
+            The version of the service, used to identify which application image to
+            use to run your command. If not specified, uses the most recently created
+            version, regardless of whether that version is actually serving traffic.
+            Applies only to the "cloud_build" strategy. (The "deployment" strategy
+            deploys its own temporary version of your app.)
 
-    require "appengine/tasks"
+          GAE_EXEC_WRAPPER_IMAGE
 
-If your app uses Ruby on Rails, the gem provides a railtie that adds its
-tasks automatically, so you don't have to do anything beyond adding the
-gem to your Gemfile.
+            The fully-qualified name of the wrapper image to use. (This is a Docker
+            image that emulates the App Engine environment in Google Cloud Build for
+            the "cloud_build" strategy, and applies only to that strategy.) Normally,
+            you should not override this unless you are testing a new wrapper.
 
-For more information or to report issues, visit the Github page:
-https://github.com/GoogleCloudPlatform/appengine-ruby
+          CLOUD_BUILD_GCS_LOG_DIR
+
+            GCS bucket name of the cloud build log when GAE_STRATEGY is "cloud_build".
+            (ex. "gs://BUCKET-NAME/FOLDER-NAME")
+
+          This rake task is provided by the "appengine" gem. To make these tasks
+          available, add the following line to your Rakefile:
+
+              require "appengine/tasks"
+
+          If your app uses Ruby on Rails, the gem provides a railtie that adds its
+          tasks automatically, so you don't have to do anything beyond adding the
+          gem to your Gemfile.
+
+          For more information or to report issues, visit the Github page:
+          https://github.com/GoogleCloudPlatform/appengine-ruby
         USAGE
       end
 
       def verify_gcloud_and_report_errors
         Util::Gcloud.verify!
       rescue Util::Gcloud::BinaryNotFound
-        report_error <<-MESSAGE
-Could not find the `gcloud` binary in your system path.
-This tool requires the Google Cloud SDK. To download and install it,
-visit https://cloud.google.com/sdk/downloads
+        report_error <<~MESSAGE
+          Could not find the `gcloud` binary in your system path.
+          This tool requires the Google Cloud SDK. To download and install it,
+          visit https://cloud.google.com/sdk/downloads
         MESSAGE
       rescue Util::Gcloud::GcloudNotAuthenticated
-        report_error <<-MESSAGE
-The gcloud authorization has not been completed. If you have not yet
-initialized the Google Cloud SDK, we recommend running the `gcloud init`
-command as described at https://cloud.google.com/sdk/docs/initializing
-Alternately, you may log in directly by running `gcloud auth login`.
+        report_error <<~MESSAGE
+          The gcloud authorization has not been completed. If you have not yet
+          initialized the Google Cloud SDK, we recommend running the `gcloud init`
+          command as described at https://cloud.google.com/sdk/docs/initializing
+          Alternately, you may log in directly by running `gcloud auth login`.
         MESSAGE
       rescue Util::Gcloud::ProjectNotSet
-        report_error <<-MESSAGE
-The gcloud project configuration has not been set. If you have not yet
-initialized the Google Cloud SDK, we recommend running the `gcloud init`
-command as described at https://cloud.google.com/sdk/docs/initializing
-Alternately, you may set the default project configuration directly by
-running `gcloud config set project <project-name>`.
+        report_error <<~MESSAGE
+          The gcloud project configuration has not been set. If you have not yet
+          initialized the Google Cloud SDK, we recommend running the `gcloud init`
+          command as described at https://cloud.google.com/sdk/docs/initializing
+          Alternately, you may set the default project configuration directly by
+          running `gcloud config set project <project-name>`.
         MESSAGE
       end
 
       def start_and_report_errors app_exec
         app_exec.start
-      rescue Exec::ConfigFileNotFound => ex
-        report_error <<-MESSAGE
-Could not determine which service should run this command because the App
-Engine config file "#{ex.config_path}" was not found.
-Specify the config file using the GAE_CONFIG argument. e.g.
-  bundle exec rake appengine:exec GAE_CONFIG=myapp.yaml -- myscript.sh
-Alternately, you may specify a service name directly with GAE_SERVICE. e.g.
-  bundle exec rake appengine:exec GAE_SERVICE=myservice -- myscript.sh
-MESSAGE
-      rescue Exec::BadConfigFileFormat => ex
-        report_error <<-MESSAGE
-Could not determine which service should run this command because the App
-Engine config file "#{ex.config_path}" was malformed.
-It must be a valid YAML file.
-Specify the config file using the GAE_CONFIG argument. e.g.
-  bundle exec rake appengine:exec GAE_CONFIG=myapp.yaml -- myscript.sh
-Alternately, you may specify a service name directly with GAE_SERVICE. e.g.
-  bundle exec rake appengine:exec GAE_SERVICE=myservice -- myscript.sh
-MESSAGE
-      rescue Exec::NoSuchVersion => ex
-        if ex.version
-          report_error <<-MESSAGE
-Could not find version "#{ex.version}" of service "#{ex.service}".
-Please double-check the version exists. To use the most recent version by
-default, omit the GAE_VERSION argument.
-MESSAGE
+      rescue Exec::ConfigFileNotFound => e
+        report_error <<~MESSAGE
+          Could not determine which service should run this command because the App
+          Engine config file "#{e.config_path}" was not found.
+          Specify the config file using the GAE_CONFIG argument. e.g.
+            bundle exec rake appengine:exec GAE_CONFIG=myapp.yaml -- myscript.sh
+          Alternately, you may specify a service name directly with GAE_SERVICE. e.g.
+            bundle exec rake appengine:exec GAE_SERVICE=myservice -- myscript.sh
+        MESSAGE
+      rescue Exec::BadConfigFileFormat => e
+        report_error <<~MESSAGE
+          Could not determine which service should run this command because the App
+          Engine config file "#{e.config_path}" was malformed.
+          It must be a valid YAML file.
+          Specify the config file using the GAE_CONFIG argument. e.g.
+            bundle exec rake appengine:exec GAE_CONFIG=myapp.yaml -- myscript.sh
+          Alternately, you may specify a service name directly with GAE_SERVICE. e.g.
+            bundle exec rake appengine:exec GAE_SERVICE=myservice -- myscript.sh
+        MESSAGE
+      rescue Exec::NoSuchVersion => e
+        if e.version
+          report_error <<~MESSAGE
+            Could not find version "#{e.version}" of service "#{e.service}".
+            Please double-check the version exists. To use the most recent version by
+            default, omit the GAE_VERSION argument.
+          MESSAGE
         else
-          report_error <<-MESSAGE
-Could not find any versions of service "#{ex.service}".
-Please double-check that you have deployed this service. If you want to run
-a command against a different service, you may provide a GAE_CONFIG argument
-pointing to your App Engine config file, or a GAE_SERVICE argument to specify
-a service directly.
-MESSAGE
+          report_error <<~MESSAGE
+            Could not find any versions of service "#{e.service}".
+            Please double-check that you have deployed this service. If you want to run
+            a command against a different service, you may provide a GAE_CONFIG argument
+            pointing to your App Engine config file, or a GAE_SERVICE argument to specify
+            a service directly.
+          MESSAGE
         end
-      rescue Exec::ServiceNameConflict => ex
-        report_error <<-MESSAGE
-The explicit service name "#{ex.service_name}" was requested
-but conflicts with the service "#{ex.config_name}" from the
-config file "#{ex.config_path}"
-You should specify either GAE_SERVICE or GAE_CONFIG but not both.
-MESSAGE
+      rescue Exec::NoDefaultProject
+        report_error <<~MESSAGE
+          Could not get the default project from gcloud.
+          Please either set the current project using
+            gcloud config set project my-project-id
+          or specify the project by setting the GAE_PROJECT argument. e.g.
+            bundle exec rake appengine:exec GAE_PROJECT=my-project-id -- myscript.sh
+        MESSAGE
+      rescue Exec::UsageError => e
+        report_error e.message
       end
 
       def report_error str
-        ::STDERR.puts str
+        warn str
         exit 1
       end
-
     end
-
   end
 end
 
-
 ::AppEngine::Tasks.define

data/lib/appengine/util/gcloud.rb

@@ -1,4 +1,6 @@
-# Copyright 2017 Google Inc. All rights reserved.
+# 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.
@@ -11,20 +13,18 @@
 # 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 "shellwords"
 
+require "shellwords"
+require "English"
 
 module AppEngine
   module Util
-
     ##
     # A collection of utility functions and classes for interacting with an
     # installation of the gcloud SDK.
     #
     module Gcloud
-
       ##
       # Base class for gcloud related errors.
       #
@@ -68,7 +68,6 @@ module AppEngine
       end
 
       class << self
-
         ##
         # @private
         # Returns the path to the gcloud binary, or nil if the binary could
@@ -78,12 +77,13 @@ module AppEngine
         #
         def binary_path
           unless defined? @binary_path
-            if Gem.win_platform?
-              @binary_path = `where gcloud` == '' ? nil : 'gcloud'
-            else
-              @binary_path = `which gcloud`.strip
-              @binary_path = nil if @binary_path.empty?
-            end
+            @binary_path =
+              if ::Gem.win_platform?
+                `where gcloud` == "" ? nil : "gcloud"
+              else
+                path = `which gcloud`.strip
+                path.empty? ? nil : path
+              end
           end
           @binary_path
         end
@@ -111,9 +111,10 @@ module AppEngine
         #
         def current_project
           unless defined? @current_project
-            @current_project = execute [
+            params = [
               "config", "list", "core/project", "--format=value(core.project)"
-            ], capture: true
+            ]
+            @current_project = execute params, capture: true
             @current_project = nil if @current_project.empty?
           end
           @current_project
@@ -147,7 +148,7 @@ module AppEngine
           binary_path!
           current_project!
           auths = execute ["auth", "list", "--format=value(account)"],
-              capture: true
+                          capture: true
           raise GcloudNotAuthenticated if auths.empty?
         end
 
@@ -166,13 +167,17 @@ module AppEngine
         #     depending on the value of the `capture` parameter.
         #
         def execute args, echo: false, capture: false, assert: true
-          joined_args = Gem.win_platform? ? args.join(" ") : Shellwords.join(args)
-
-          cmd = "#{binary_path!} #{joined_args}"
+          cmd_array = [binary_path!] + args
+          cmd =
+            if ::Gem.win_platform?
+              cmd_array.join " "
+            else
+              ::Shellwords.join cmd_array
+            end
           puts cmd if echo
           result = capture ? `#{cmd}` : system(cmd)
-          code = $?.exitstatus
-          raise GcloudFailed.new($?.exitstatus) if assert && code != 0
+          code = $CHILD_STATUS.exitstatus
+          raise GcloudFailed, code if assert && code != 0
           result
         end
 
@@ -187,9 +192,7 @@ module AppEngine
         def capture args
           execute args, capture: true
         end
-
       end
     end
-
   end
 end

data/lib/appengine/version.rb

@@ -1,4 +1,6 @@
-# Copyright 2016 Google Inc. All rights reserved.
+# 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.
@@ -11,11 +13,9 @@
 # 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 AppEngine
 
+module AppEngine
   # The current version of this gem, as a string.
-  VERSION = '0.4.6'.freeze
-
+  VERSION = "0.7.0"
 end

data/lib/appengine.rb

@@ -1,4 +1,6 @@
-# Copyright 2016 Google Inc. All rights reserved.
+# 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.
@@ -11,17 +13,22 @@
 # 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.
-;
 
-# # Google AppEngine integration
+
+##
+# ## Google AppEngine integration
 #
 # The AppEngine module includes optional tools helping Ruby applications to
 # integrate more closely with the Google App Engine environment.
-
+#
 module AppEngine
+  ##
+  # Internal utilities
+  #
+  module Util
+  end
 end
 
-
 require "appengine/version"
 require "appengine/env"
 require "appengine/exec"