google-serverless-exec 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9649c833b15ac827ec528c9834a0c44e1fd4f0f39c98f849fac9da49b469aee6
+  data.tar.gz: 7d848bb54ede49bc2758d028a777a68c6c3e73704b7a0325474ffa26a6e87861
+SHA512:
+  metadata.gz: 621be644a9cc61b56697d6c8b28237e40c91cbda3105e73b3422714357698ee58afcbf7001ac669ae6d26785c462627acc8c6c59119d90ed52f814256d823102
+  data.tar.gz: '0568e46e630b6774612c7cc548e8d827eaeb975034ffefc53492c24eecb5baad3f7165d91c673fd8ef6d0644a70180e9ae268cf412517fa1aca91fe2fbe6c802'

data/.yardopts

@@ -0,0 +1,10 @@
+--no-private
+--title=Serverless Exec
+--markup markdown
+--markup-provider redcarpet
+--main=README.md
+./lib/**/*.rb
+-
+README.md
+CONTRIBUTING.md
+CHANGELOG.md

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+### v0.1.0 / 2021-08-04
+
+* Initial release

data/CONTRIBUTING.md

@@ -0,0 +1,27 @@
+Want to contribute? Great! First, read this page (including the small print at the end).
+
+### Before you contribute
+Before we can use your code, you must sign the
+[Google Individual Contributor License Agreement]
+(https://cla.developers.google.com/about/google-individual)
+(CLA), which you can do online. The CLA is necessary mainly because you own the
+copyright to your changes, even after your contribution becomes part of our
+codebase, so we need your permission to use and distribute your code. We also
+need to be sure of various other things—for instance that you'll tell us if you
+know that your code infringes on other people's patents. You don't have to sign
+the CLA until after you've submitted your code for review and a member has
+approved it, but you must do it before we can put your code into our codebase.
+Before you start working on a larger contribution, you should get in touch with
+us first through the issue tracker with your idea so that we can help out and
+possibly guide you. Coordinating up front makes it much easier to avoid
+frustration later on.
+
+### Code reviews
+All submissions, including submissions by project members, require review. We
+use Github pull requests for this purpose.
+
+### The small print
+Contributions made by corporations are covered by a different agreement than
+the one above, the
+[Software Grant and Corporate Contributor License Agreement]
+(https://cla.developers.google.com/about/google-corporate).

data/LICENSE

@@ -0,0 +1,202 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   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
+
+       http://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/README.md

@@ -0,0 +1,49 @@
+# Google Serverless Execution Tool
+
+This repository contains the "google-serverless-exec" gem, a library for serverless execution. This may be used for safe running of ops and maintenance tasks, such as database migrations in a production serverless environment. It is not required for deploying a Ruby application to Google serverless compute, but it provides a number of convenience tools for integrating into Google serverless environments.
+
+## Quickstart
+
+To install, include the "google-serverless-exec" gem in your `Gemfile`:
+
+```ruby
+# Gemfile
+gem "google-serverless-exec"
+```
+
+And then execute:
+
+```ruby
+$ bundle install
+```
+
+### Setting up serverless:exec execution
+
+This library provides rake tasks for serverless execution, allowing
+serverless applications to perform on-demand tasks in the serverless
+environment. This may be used for safe running of ops and maintenance tasks,
+such as database migrations, that access production cloud resources. 
+
+You can add the Rake tasks to your application by adding the following to your Rakefile:
+
+```ruby
+require "google/serverless/exec/tasks"
+```
+
+You can run a production database migration in a Rails app using:
+
+    bundle exec rake serverless:exec -- bundle exec rake db:migrate
+
+The migration would be run in containers on Google Cloud infrastructure, which
+is much easier and safer than running the task on a local workstation and
+granting that workstation direct access to your production database.
+
+## Development
+
+The source code for this gem is available on Github at https://github.com/GoogleCloudPlatform/serverless-exec-ruby
+
+The Ruby Serverless Exec is open source under the Apache 2.0 license.
+Contributions are welcome. Please see the contributing guide at
+https://github.com/GoogleCloudPlatform/serverless-exec-ruby/blob/main/CONTRIBUTING.md
+
+Report issues at https://github.com/GoogleCloudPlatform/serverless-exec-ruby/issues

data/lib/google/serverless/exec.rb

@@ -0,0 +1,914 @@
+# frozen_string_literal: true
+
+# Copyright 2021 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
+#
+#     http://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 "date"
+require "erb"
+require "json"
+require "net/http"
+require "securerandom"
+require "shellwords"
+require "tempfile"
+require "yaml"
+
+require "google/serverless/exec/gcloud"
+
+module Google
+  module Serverless
+    ##
+    # # Serverless execution tool
+    #
+    # This class provides a client for serverless execution, allowing
+    # Serverless applications to perform on-demand tasks in the serverless
+    # environment. This may be used for safe running of ops and maintenance
+    # tasks, such as database migrations, that access production cloud resources.
+    #
+    # ## About serverless execution tool
+    #
+    # Serverless execution spins up a one-off copy of a serverless app, and runs
+    # a command against it. For example, if your app runs on Ruby on Rails, then
+    # you might use serverless execution to run a command such as
+    # `bundle exec bin/rails db:migrate` in production infrastructure (to avoid
+    # having to connect directly to your production database from a local
+    # workstation).
+    #
+    # Serverless execution provides two strategies for generating that "one-off
+    # copy":
+    #
+    #  *  A `deployment` strategy, which deploys a temporary version of your app
+    #     to a single backend instance and runs the command there.
+    #  *  A `cloud_build` strategy, which deploys your application image to
+    #     Google Cloud Build and runs the command there.
+    #
+    # Both strategies are generally designed to emulate the runtime
+    # environment on cloud VMs similar to those used by actual deployments of
+    # your app. Both provide your application code and environment variables, and
+    # both provide access to Cloud SQL connections used by your app. However,
+    # they differ in what *version* of your app code they run against, and in
+    # certain other constraints and performance characteristics. More detailed
+    # information on using the two strategies is provided in the sections below.
+    #
+    # Apps deployed to the App Engine *flexible environment* and Cloud Run will use the
+    # `cloud_build` strategy by default. However, you can force an app to use the
+    # `deployment` strategy instead. (You might do so if you need to connect to a
+    # Cloud SQL database on a VPC using a private IP, because the `cloud_build`
+    # strategy does not support private IPs.) To force use of `deployment`, set
+    # the `strategy` parameter in the {Google::Serverless::Exec} constructor (or the
+    # corresponding `GAE_EXEC_STRATEGY` parameter in the Rake task). Note that
+    # the `deployment` strategy is usually significantly slower than
+    # `cloud_build` for apps in the flexible environment.
+    #
+    # Apps deployed to the App Engine *standard environment* will *always* use
+    # the `deployment` strategy. You cannot force use of the `cloud_build`
+    # strategy.
+    #
+    # ## Prerequisites
+    #
+    # To use this tool, you will need:
+    #
+    # * An app deployed to Google serverless compute, of course!
+    # * The [gcloud SDK](https://cloud.google.com/sdk/) installed and configured.
+    # * The `serverless` gem.
+    #
+    # You may use the `Google::Serverless::Exec` class to run commands directly. However,
+    # in most cases, it will be easier to run commands via the provided rake
+    # tasks (see {Google::Serverless::Tasks}).
+    #
+    # ## Using the "deployment" strategy
+    #
+    # The `deployment` strategy deploys a temporary version of your app to a
+    # single backend App Engine instance, runs the command there, and then
+    # deletes the temporary version when it is finished.
+    #
+    # This is the default strategy (and indeed the only option) for apps running
+    # on the App Engine standard environment. It can also be used for flexible
+    # environment apps, but this is not commonly done because deployment of
+    # flexible environment apps can take a long time.
+    #
+    # Because the `deployment` strategy deploys a temporary version of your app,
+    # it runs against the *current application code* present where the command
+    # was initiated (i.e. the code currently on your workstation if you run the
+    # rake task from your workstation, or the current code on the branch if you
+    # are running from a CI/CD system.) This may be different from the code
+    # actually running in production, so it is important that you run from a
+    # compatible code branch.
+    #
+    # ### Specifying the host application
+    #
+    # The `deployment` strategy works by deploying a temporary version of your
+    # app, so that it has access to your app's project and settings in App
+    # Engine. In most cases, it can determine this automatically, but depending
+    # on how your app or environment is structured, you may need to give it some
+    # help.
+    #
+    # By default, your Google Cloud project is taken from the current gcloud
+    # project. If you need to override this, set the `:project` parameter in the
+    # {Google::Serverless::Exec} constructor (or the corresponding `GAE_PROJECT`
+    # parameter in the Rake task).
+    #
+    # By default, the service name is taken from the App Engine config file.
+    # Serverless execution will assume this file is called `app.yaml` in the
+    # current directory. To use a different config file, set the `config_path`
+    # parameter in the {Google::Serverless::Exec} constructor (or the corresponding
+    # `GAE_CONFIG` parameter in the Rake task). You may also set the service name
+    # directly, using the `service` parameter (or `GAE_SERVICE` in Rake).
+    #
+    # ### Providing credentials
+    #
+    # Your command will effectively be a deployment of your serverless app
+    # itself, and will have access to the same credentials. For example, App
+    # Engine provides a service account by default for your app, or your app may
+    # be making use of its own service account key. In either case, make sure the
+    # service account has sufficient access for the command you want to run
+    # (such as database admin credentials).
+    #
+    # ### Other options
+    #
+    # You may also provide a timeout, which is the length of time that serverless
+    # execution will allow your command to run before it is considered to
+    # have stalled and is terminated. The timeout should be a string of the form
+    # `2h15m10s`. The default is `10m`.
+    #
+    # The timeout is set via the `timeout` parameter to the {Google::Serverless::Exec}
+    # constructor, or by setting the `GAE_TIMEOUT` environment variable when
+    # invoking using Rake.
+    #
+    # ### Resource usage and billing
+    #
+    # The `deployment` strategy deploys to a temporary instance of your app in
+    # order to run the command. You may be billed for that usage. However, the
+    # cost should be minimal, because it will then immediately delete that
+    # instance in order to minimize usage.
+    #
+    # If you interrupt the execution (or it crashes), it is possible that the
+    # temporary instance may not get deleted properly. If you suspect this may
+    # have happened, go to the App Engine tab in the cloud console, under
+    # "versions" of your service, and delete the temporary version manually. It
+    # will have a name matching the pattern `serverless-exec-<timestamp>`.
+    #
+    # ## Using the "cloud_build" strategy
+    #
+    # The `cloud_build` strategy takes the application image that App Engine or Cloud Run is
+    # actually using to run your app, and uses it to spin up a copy of your app
+    # in [Google Cloud Build](https://cloud.google.com/cloud-build) (along with
+    # an emulation layer that emulates certain serverless services such as Cloud
+    # SQL connection sockets). The command then gets run in the Cloud Build
+    # environment.
+    #
+    # This is the default strategy for apps running on the App Engine flexible and Cloud
+    # Run environments. (It is not available for standard environment apps.) Note that
+    # the `cloud_build` strategy cannot be used if your command needs to connect
+    # to a database over a [VPC](https://cloud.google.com/vpc/) private IP
+    # address. This is because it runs on virtual machines provided by the Cloud
+    # Build service, which are not part of your VPC. If your database can be
+    # accessed only over a private IP, you should use the `deployment` strategy
+    # instead.
+    #
+    # The Cloud Build log is output to the directory specified by
+    # "CLOUD_BUILD_GCS_LOG_DIR". (ex. "gs://BUCKET-NAME/FOLDER-NAME")
+    # By default, log directory name is
+    # "gs://[PROJECT_NUMBER].cloudbuild-logs.googleusercontent.com/".
+    #
+    # ### Specifying the host application
+    #
+    # The `cloud_build` strategy needs to know exactly which app, service, and
+    # version of your app, to identify the application image to use.
+    #
+    # By default, your Google Cloud project is taken from the current gcloud
+    # project. If you need to override this, set the `:project` parameter in the
+    # {Google::Serverless::Exec} constructor (or the corresponding `GAE_PROJECT`
+    # parameter in the Rake task).
+    #
+    # By default, the service name is taken from the App Engine config file.
+    # Serverless execution will assume this file is called `app.yaml` in the
+    # current directory. To use a different config file, set the `config_path`
+    # parameter in the {Google::Serverless::Exec} constructor (or the corresponding
+    # `GAE_CONFIG` parameter in the Rake task). You may also set the service name
+    # directly, using the `service` parameter (or `GAE_SERVICE` in Rake).
+    #
+    # By default, the image of the most recently deployed version of your app is
+    # used. (Note that this most recently deployed version may not be the same
+    # version that is currently receiving traffic: for example, if you deployed
+    # with `--no-promote`.) To use a different version, set the `version`
+    # parameter in the {Google::Serverless::Exec} constructor 
+    # (or the corresponding `GAE_VERSION` parameter in the Rake task).
+    #
+    # ### Providing credentials
+    #
+    # By default, the `cloud_build` strategy uses your project's Cloud Build
+    # service account for its credentials. Unless your command provides its own
+    # service account key, you may need to grant the Cloud Build service account
+    # any permissions needed to execute your command (such as access to your
+    # database). For most tasks, it is sufficient to grant Project Editor
+    # permissions to the service account. You can find the service account
+    # configuration in the IAM tab in the Cloud Console under the name
+    # `[your-project-number]@cloudbuild.gserviceaccount.com`.
+    #
+    # ### Other options
+    #
+    # You may also provide a timeout, which is the length of time that
+    # serverless execution will allow your command to run before it is considered to
+    # have stalled and is terminated. The timeout should be a string of the form
+    # `2h15m10s`. The default is `10m`.
+    #
+    # The timeout is set via the `timeout` parameter to the {Google::Serverless::Exec}
+    # constructor, or by setting the `GAE_TIMEOUT` environment variable when
+    # invoking using Rake.
+    #
+    # You can also set the wrapper image used to emulate the App Engine runtime
+    # environment, by setting the `wrapper_image` parameter to the constructor,
+    # or by setting the `GAE_EXEC_WRAPPER_IMAGE` environment variable. Generally,
+    # you will not need to do this unless you are testing a new wrapper image.
+    #
+    # ### Resource usage and billing
+    #
+    # The `cloud_build` strategy uses virtual machine resources provided by
+    # Google Cloud Build. Generally, a certain number of usage minutes per day is
+    # covered under a free tier, but additional compute usage beyond that time is
+    # billed to your Google Cloud account. For more details,
+    # see https://cloud.google.com/cloud-build/pricing
+    #
+    # If your command makes API calls or utilizes other cloud resources, you may
+    # also be billed for that usage. However, the `cloud_build` strategy (unlike
+    # the `deployment` strategy) does not use actual App Engine instances, and
+    # you will not be billed for additional App Engine instance usage.
+    #
+    class Exec
+      @default_timeout = "10m"
+      @default_service = "default"
+      @default_config_path = "./app.yaml"
+      @default_wrapper_image = "gcr.io/google-appengine/exec-wrapper:latest"
+
+      APP_ENGINE = :app_engine
+      CLOUD_RUN = :cloud_run
+  
+      ##
+      # Base class for exec-related usage errors.
+      #
+      class UsageError < ::StandardError
+      end
+  
+      ##
+      # Unsupported strategy
+      #
+      class UnsupportedStrategy < UsageError
+        def initialize strategy, app_env
+          @strategy = strategy
+          @app_env = app_env
+          super "Strategy \"#{strategy}\" not supported for the #{app_env}" \
+                " environment"
+        end
+        attr_reader :strategy
+        attr_reader :app_env
+      end
+  
+      ##
+      # Exception raised when a parameter is malformed.
+      #
+      class BadParameter < UsageError
+        def initialize param, value
+          @param_name = param
+          @value = value
+          super "Bad value for #{param}: #{value}"
+        end
+        attr_reader :param_name
+        attr_reader :value
+      end
+  
+      ##
+      # Exception raised when gcloud has no default project.
+      #
+      class NoDefaultProject < UsageError
+        def initialize
+          super "No default project set."
+        end
+      end
+  
+      ##
+      # Exception raised when the App Engine config file could not be found.
+      #
+      class ConfigFileNotFound < UsageError
+        def initialize config_path
+          @config_path = config_path
+          super "Config file #{config_path} not found."
+        end
+        attr_reader :config_path
+      end
+  
+      ##
+      # Exception raised when the App Engine config file could not be parsed.
+      #
+      class BadConfigFileFormat < UsageError
+        def initialize config_path
+          @config_path = config_path
+          super "Config file #{config_path} malformed."
+        end
+        attr_reader :config_path
+      end
+  
+      ##
+      # Exception raised when the given version could not be found, or no
+      # versions at all could be found for the given service.
+      #
+      class NoSuchVersion < UsageError
+        def initialize service, version = nil
+          @service = service
+          @version = version
+          if version
+            super "No such version \"#{version}\" for service \"#{service}\""
+          else
+            super "No versions found for service \"#{service}\""
+          end
+        end
+        attr_reader :service
+        attr_reader :version
+      end
+  
+      class << self
+        ## @return [String] Default command timeout.
+        attr_accessor :default_timeout
+  
+        ## @return [String] Default service name if the config doesn't specify.
+        attr_accessor :default_service
+  
+        ## @return [String] Path to default config file.
+        attr_accessor :default_config_path
+  
+        ## @return [String] Docker image that implements the app engine wrapper.
+        attr_accessor :default_wrapper_image
+  
+        ##
+        # Create an execution for a rake task.
+        #
+        # @param name [String] Name of the task
+        # @param args [Array<String>] Args to pass to the task
+        # @param env_args [Array<String>] Environment variable settings, each
+        #     of the form `NAME=value`.
+        # @param service [String,nil] Name of the service. If omitted, obtains
+        #     the service name from the config file.
+        # @param config_path [String,nil] App Engine config file to get the
+        #     service name from if the service name is not provided directly.
+        #     If omitted, defaults to the value returned by
+        #     {Google::Serverless::Exec.default_config_path}.
+        # @param version [String,nil] Version string. If omitted, defaults to the
+        #     most recently created version of the given service (which may not
+        #     be the one currently receiving traffic).
+        # @param timeout [String,nil] Timeout string. If omitted, defaults to the
+        #     value returned by {Google::Serverless::Exec.default_timeout}.
+        # @param wrapper_image [String,nil] The fully qualified name of the
+        #     wrapper image to use. (Applies only to the "cloud_build" strategy.)
+        # @param strategy [String,nil] The execution strategy to use, or `nil` to
+        #     choose a default based on the App Engine (flexible or standard) or Cloud  Run
+        #     environments. Allowed values are `nil`, `"deployment"` (which is the
+        #     default for App Engine Standard), and `"cloud_build"` (which is the default
+        #     for App Engine Flexible and Cloud Run).
+        # @param gcs_log_dir [String,nil] GCS bucket name of the cloud build log
+        #     when strategy is "cloud_build". (ex. "gs://BUCKET-NAME/FOLDER-NAME")
+        # @param product [Symbol] The serverless product to use. If omitted, defaults to
+        #     the value returned by {Google::Serverless::Exec#default_product}
+        def new_rake_task name, args: [], env_args: [],
+                          service: nil, config_path: nil, version: nil,
+                          timeout: nil, project: nil, wrapper_image: nil,
+                          strategy: nil, gcs_log_dir: nil, product: nil
+          escaped_args = args.map do |arg|
+            arg.gsub(/[,\[\]]/) { |m| "\\#{m}" }
+          end
+          name_with_args =
+            if escaped_args.empty?
+              name
+            else
+              "#{name}[#{escaped_args.join ','}]"
+            end
+          new ["bundle", "exec", "rake", name_with_args] + env_args,
+              service: service, config_path: config_path, version: version,
+              timeout: timeout, project: project, wrapper_image: wrapper_image,
+              strategy: strategy, gcs_log_dir: gcs_log_dir, product: product
+        end
+      end
+  
+      ##
+      # Create an execution for the given command.
+      #
+      # @param command [Array<String>] The command in array form.
+      # @param project [String,nil] ID of the project. If omitted, obtains
+      #     the project from gcloud.
+      # @param service [String,nil] Name of the service. If omitted, obtains
+      #     the service name from the config file.
+      # @param config_path [String,nil] App Engine config file to get the
+      #     service name from if the service name is not provided directly.
+      #     If omitted, defaults to the value returned by
+      #     {Google::Serverless::Exec.default_config_path}.
+      # @param version [String,nil] Version string. If omitted, defaults to the
+      #     most recently created version of the given service (which may not be
+      #     the one currently receiving traffic).
+      # @param timeout [String,nil] Timeout string. If omitted, defaults to the
+      #     value returned by {Google::Serverless::Exec.default_timeout}.
+      # @param wrapper_image [String,nil] The fully qualified name of the wrapper
+      #     image to use. (Applies only to the "cloud_build" strategy.)
+      # @param strategy [String,nil] The execution strategy to use, or `nil` to
+      #     choose a default based on the App Engine environment (flexible or standard) or
+      #     Cloud Run environments. Allowed values are `nil`, `"deployment"` (which is the
+      #     default for App Engine Standard), and `"cloud_build"` (which is the default for
+      #     App Engine Flexible and Cloud Run).
+      # @param gcs_log_dir [String,nil] GCS bucket name of the cloud build log
+      #     when strategy is "cloud_build". (ex. "gs://BUCKET-NAME/FOLDER-NAME")
+      # @param product [Symbol] The serverless product. If omitted, defaults to the
+      #     value returns by {Google::Serverless::Exec#default_product}.
+      #     Allowed values are {APP_ENGINE} and {CLOUD_RUN}.
+      #
+      def initialize command,
+                     project: nil, service: nil, config_path: nil, version: nil,
+                     timeout: nil, wrapper_image: nil, strategy: nil, gcs_log_dir: nil, product: nil
+        @command = command
+        @service = service
+        @config_path = config_path
+        @version = version
+        @timeout = timeout
+        @project = project
+        @wrapper_image = wrapper_image
+        @strategy = strategy
+        @gcs_log_dir = gcs_log_dir
+        @product = product
+  
+        yield self if block_given?
+      end
+  
+      ##
+      # @return [String] The project ID.
+      # @return [nil] if the default gcloud project should be used.
+      #
+      attr_accessor :project
+  
+      ##
+      # @return [String] The service name.
+      # @return [nil] if the service should be obtained from the app config.
+      #
+      attr_accessor :service
+  
+      ##
+      # @return [String] Path to the config file.
+      # @return [nil] if the default of `./app.yaml` should be used.
+      #
+      attr_accessor :config_path
+  
+      ##
+      # @return [String] Service version of the image to use.
+      # @return [nil] if the most recent should be used.
+      #
+      attr_accessor :version
+  
+      ##
+      # @return [String] The command timeout, in `1h23m45s` format.
+      # @return [nil] if the default of `10m` should be used.
+      #
+      attr_accessor :timeout
+  
+      ##
+      # The command to run.
+      #
+      # @return [String] if the command is a script to be run in a shell.
+      # @return [Array<String>] if the command is a posix command to be run
+      #     directly without a shell.
+      #
+      attr_accessor :command
+  
+      ##
+      # @return [String] Custom wrapper image to use.
+      # @return [nil] if the default should be used.
+      #
+      attr_accessor :wrapper_image
+  
+      ##
+      # @return [String] The execution strategy to use. Allowed values are
+      #     `"deployment"` and `"cloud_build"`.
+      # @return [nil] to choose a default based on the App Engine (flexible or standard)
+      #     or Cloud Run environments.
+      #
+      attr_accessor :strategy
+
+      ##
+      # @return [Symbol] The serverless product to use.
+      #     Allowed values are {APP_ENGINE} and {CLOUD_RUN}
+      #
+      attr_accessor :product
+  
+      ##
+      # Executes the command synchronously. Streams the logs back to standard out
+      # and does not return until the command has completed or timed out.
+      
+      def start
+        resolve_parameters
+        case @product
+        when APP_ENGINE
+          start_app_engine
+        when CLOUD_RUN
+          start_cloud_run
+        end
+      end
+
+      def start_app_engine
+        app_info = version_info @service, @version
+        resolve_strategy app_info["env"]
+        if @strategy == "cloud_build"
+          start_build_strategy app_info
+        else
+          start_deployment_strategy app_info
+        end
+      end
+
+      def start_cloud_run
+        app_info = version_info_cloud_run @service
+        start_build_strategy app_info
+      end
+  
+      private
+  
+      ##
+      # @private
+      # Resolves and canonicalizes all the parameters.
+      #
+      def resolve_parameters
+        @timestamp_suffix = ::Time.now.strftime "%Y%m%d%H%M%S"
+        @command = ::Shellwords.split @command.to_s unless @command.is_a? Array
+        @project ||= default_project
+        @service ||= service_from_config || Exec.default_service
+        @timeout ||= Exec.default_timeout
+        @timeout_seconds = parse_timeout @timeout
+        @wrapper_image ||= Exec.default_wrapper_image
+        @product ||= default_product
+        if @product == APP_ENGINE
+          @version ||= latest_version @service
+        end
+        self
+      end
+  
+      def resolve_strategy app_env
+        @strategy = @strategy.to_s.downcase
+        if @strategy.empty?
+          @strategy = app_env == "flexible" ? "cloud_build" : "deployment"
+        end
+        if app_env == "standard" && @strategy == "cloud_build" ||
+           @strategy != "cloud_build" && @strategy != "deployment"
+          raise UnsupportedStrategy.new @strategy, app_env
+        end
+        @strategy
+      end
+  
+      def service_from_config
+        return nil if !@config_path && @service
+        @config_path ||= Exec.default_config_path
+        ::YAML.load_file(config_path)["service"]
+      rescue ::Errno::ENOENT
+        raise ConfigFileNotFound, @config_path
+      rescue ::StandardError
+        raise BadConfigFileFormat, @config_path
+      end
+  
+      def default_project
+        result = Exec::Gcloud.execute \
+          ["config", "get-value", "project"],
+          capture: true, assert: false
+        result.strip!
+        raise NoDefaultProject if result.empty?
+        result
+      end
+
+      def default_product
+        File.file?("app.yaml") ? APP_ENGINE : CLOUD_RUN
+      end
+  
+      def parse_timeout timeout_str
+        matched = timeout_str =~ /^(?:(\d+)h)?(?:(\d+)m)?(?:(\d+)s?)?$/
+        raise BadParameter.new "timeout", timeout_str unless matched
+        hours = ::Regexp.last_match(1).to_i
+        minutes = ::Regexp.last_match(2).to_i
+        seconds = ::Regexp.last_match(3).to_i
+        hours * 3600 + minutes * 60 + seconds
+      end
+  
+      ##
+      # @private
+      # Returns the name of the most recently created version of the given
+      # service.
+      #
+      # @param service [String] Name of the service.
+      # @return [String] Name of the most recent version.
+      #
+      def latest_version service
+        result = Exec::Gcloud.execute \
+          [
+            "app", "versions", "list",
+            "--project", @project,
+            "--service", service,
+            "--format", "get(version.id)",
+            "--sort-by", "~version.createTime",
+            "--limit", "1"
+          ],
+          capture: true, assert: false
+        result = result.split.first
+        raise NoSuchVersion, service unless result
+        result
+      end
+  
+      ##
+      # @private
+      # Returns full information on the given version of the given service.
+      #
+      # @param service [String] Name of the service. If omitted, the service
+      #     "default" is used.
+      # @param version [String] Name of the version. If omitted, the most
+      #     recently deployed is used.
+      # @return [Hash] A collection of fields parsed from the JSON representation
+      #     of the version
+      # @return [nil] if the requested version doesn't exist.
+      #
+      def version_info service, version
+        service ||= "default"
+        version ||= latest_version service
+        result = Exec::Gcloud.execute \
+          [
+            "app", "versions", "describe", version,
+            "--project", @project,
+            "--service", service,
+            "--format", "json"
+          ],
+          capture: true, assert: false
+        result.strip!
+        raise NoSuchVersion.new(service, version) if result.empty?
+        ::JSON.parse result
+      end
+
+      def version_info_cloud_run service
+        service ||= "default"
+        result = Exec::Gcloud.execute \
+          [
+            "run", "services", "describe", service,
+            "--format", "json"
+          ],
+          capture: true, assert: false
+        result.strip!
+        ::JSON.parse result
+      end
+  
+      ##
+      # @private
+      # Performs exec on a GAE standard app.
+      #
+      def start_deployment_strategy app_info
+        describe_deployment_strategy
+        entrypoint_file = app_yaml_file = temp_version = nil
+        begin
+          puts "\n---------- DEPLOY COMMAND ----------"
+          secret = create_secret
+          entrypoint_file = copy_entrypoint secret
+          app_yaml_file = copy_app_yaml app_info, entrypoint_file
+          temp_version = deploy_temp_app app_yaml_file
+          puts "\n---------- EXECUTE COMMAND ----------"
+          puts "COMMAND: #{@command.inspect}\n\n"
+          exit_status = track_status temp_version, secret
+          puts "\nEXIT STATUS: #{exit_status}"
+        ensure
+          puts "\n---------- CLEANUP ----------"
+          ::File.unlink entrypoint_file if entrypoint_file
+          ::File.unlink app_yaml_file if app_yaml_file
+          delete_temp_version temp_version
+        end
+      end
+  
+      def describe_deployment_strategy
+        puts "\nUsing the `deployment` strategy for serverless:exec"
+        puts "(i.e. deploying a temporary version of your app)"
+        puts "PROJECT: #{@project}"
+        puts "SERVICE: #{@service}"
+        puts "TIMEOUT: #{@timeout}"
+      end
+  
+      def create_secret
+        ::SecureRandom.alphanumeric 20
+      end
+  
+      def copy_entrypoint secret
+        entrypoint_template =
+          ::File.join(::File.dirname(::File.dirname(__dir__)),
+                      "data", "exec_standard_entrypoint.rb.erb")
+        entrypoint_file = "appengine_exec_entrypoint_#{@timestamp_suffix}.rb"
+        erb = ::ERB.new ::File.read entrypoint_template
+        data = {
+          secret: secret.inspect, command: command.inspect
+        }
+        result = erb.result_with_hash data
+        ::File.open entrypoint_file, "w" do |file|
+          file.write result
+        end
+        entrypoint_file
+      end
+  
+      def copy_app_yaml app_info, entrypoint_file
+        yaml_data = {
+          "runtime"        => app_info["runtime"],
+          "service"        => @service,
+          "entrypoint"     => "ruby #{entrypoint_file}",
+          "env_variables"  => app_info["envVariables"],
+          "manual_scaling" => { "instances" => 1 }
+        }
+        if app_info["env"] == "flexible"
+          complete_flex_app_yaml yaml_data, app_info
+        else
+          complete_standard_app_yaml yaml_data, app_info
+        end
+        app_yaml_file = "appengine_exec_config_#{@timestamp_suffix}.yaml"
+        ::File.open app_yaml_file, "w" do |file|
+          ::Psych.dump yaml_data, file
+        end
+        app_yaml_file
+      end
+  
+      def complete_flex_app_yaml yaml_data, app_info
+        yaml_data["env"] = "flex"
+        orig_path = (app_info["betaSettings"] || {})["module_yaml_path"]
+        return unless orig_path
+        orig_yaml = ::YAML.load_file orig_path
+        copy_keys = ["skip_files", "resources", "network", "runtime_config",
+                     "beta_settings"]
+        copy_keys.each do |key|
+          yaml_data[key] = orig_yaml[key] if orig_yaml[key]
+        end
+      end
+  
+      def complete_standard_app_yaml yaml_data, app_info
+        yaml_data["instance_class"] = app_info["instanceClass"].sub(/^F/, "B")
+      end
+  
+      def deploy_temp_app app_yaml_file
+        temp_version = "appengine-exec-#{@timestamp_suffix}"
+        Exec::Gcloud.execute [
+          "app", "deploy", app_yaml_file,
+          "--project", @project,
+          "--version", temp_version,
+          "--no-promote", "--quiet"
+        ]
+        temp_version
+      end
+  
+      def track_status temp_version, secret
+        host = "#{temp_version}.#{@service}.#{@project}.appspot.com"
+        ::Net::HTTP.start host do |http|
+          outpos = errpos = 0
+          delay = 0.0
+          loop do
+            sleep delay
+            uri = URI("http://#{host}/#{secret}")
+            uri.query = ::URI.encode_www_form outpos: outpos, errpos: errpos
+            response = http.request_get uri
+            data = ::JSON.parse response.body
+            data["outlines"].each { |line| puts "[STDOUT] #{line}" }
+            data["errlines"].each { |line| puts "[STDERR] #{line}" }
+            outpos = data["outpos"]
+            errpos = data["errpos"]
+            return data["status"] if data["status"]
+            if data["time"] > @timeout_seconds
+              http.request_post "/#{secret}/kill", ""
+              return "timeout"
+            end
+            if data["outlines"].empty? && data["errlines"].empty?
+              delay += 0.1
+              delay = 1.0 if delay > 1.0
+            else
+              delay = 0.0
+            end
+          end
+        end
+      end
+  
+      def delete_temp_version temp_version
+        Exec::Gcloud.execute [
+          "app", "versions", "delete", temp_version,
+          "--project", @project,
+          "--service", @service,
+          "--quiet"
+        ]
+      end
+  
+      ##
+      # @private
+      # Performs exec on a GAE flexible and Cloud Run apps.
+      #
+      def start_build_strategy app_info
+        if @product == APP_ENGINE
+          env_variables = app_info["envVariables"] || {}
+          beta_settings = app_info["betaSettings"] || {}
+          cloud_sql_instances = beta_settings["cloud_sql_instances"] || []
+          container = app_info["deployment"]["container"]
+          image = container ? container["image"] : image_from_build(app_info)
+        else
+          env_variables = {}
+          app_env = app_info["spec"]["template"]["spec"]["containers"][0]["env"]
+          app_env&.each { |env| env_variables[env["name"]] = env["value"] }
+          metadata_annotations = app_info["spec"]["template"]["metadata"]["annotations"]
+          cloud_sql_instances = metadata_annotations["run.googleapis.com/cloudsql-instances"] || []
+          image = metadata_annotations["client.knative.dev/user-image"]
+        end
+  
+        describe_build_strategy
+  
+        config = build_config command, image, env_variables, cloud_sql_instances
+        file = ::Tempfile.new ["cloudbuild_", ".json"]
+        begin
+          ::JSON.dump config, file
+          file.flush
+          execute_command = [
+            "builds", "submit",
+            "--project", @project,
+            "--no-source",
+            "--config", file.path,
+            "--timeout", @timeout
+          ]
+          execute_command.concat ["--gcs-log-dir", @gcs_log_dir] unless @gcs_log_dir.nil?
+          Exec::Gcloud.execute execute_command
+        ensure
+          file.close!
+        end
+      end
+  
+      ##
+      # @private
+      # Workaround for https://github.com/GoogleCloudPlatform/appengine-ruby/issues/33
+      # Determines the image by looking it up in Cloud Build
+      #
+      def image_from_build app_info
+        create_time = ::DateTime.parse(app_info["createTime"]).to_time.utc
+        after_time = (create_time - 3600).strftime "%Y-%m-%dT%H:%M:%SZ"
+        before_time = (create_time + 3600).strftime "%Y-%m-%dT%H:%M:%SZ"
+        partial_uri = "gcr.io/#{@project}/appengine/#{@service}.#{@version}"
+        filter = "createTime>#{after_time} createTime<#{before_time} images[]:#{partial_uri}"
+        result = Exec::Gcloud.execute \
+          [
+            "builds", "list",
+            "--project", @project,
+            "--filter", filter,
+            "--format", "json"
+          ],
+          capture: true, assert: false
+        result.strip!
+        raise NoSuchVersion.new(@service, @version) if result.empty?
+        build_info = ::JSON.parse(result).first
+        build_info["images"].first
+      end
+  
+      def describe_build_strategy
+        puts "\nUsing the `cloud_build` strategy for serverless:exec"
+        puts "(i.e. running your app image in Cloud Build)"
+        puts "PROJECT: #{@project}"
+        puts "SERVICE: #{@service}"
+        puts "VERSION: #{@version}"
+        puts "TIMEOUT: #{@timeout}"
+        puts ""
+      end
+  
+      ##
+      # @private
+      # Builds a cloudbuild config as a data structure.
+      #
+      # @param command [Array<String>] The command in array form.
+      # @param image [String] The fully qualified image path.
+      # @param env_variables [Hash<String,String>] Environment variables.
+      # @param cloud_sql_instances [String,Array<String>] Names of cloud sql
+      #     instances to connect to.
+      #
+      def build_config command, image, env_variables, cloud_sql_instances
+        args = ["-i", image]
+        env_variables.each do |k, v|
+          v = v.gsub "$", "$$"
+          args << "-e" << "#{k}=#{v}"
+        end
+        unless cloud_sql_instances.empty?
+          cloud_sql_instances = Array(cloud_sql_instances)
+          cloud_sql_instances.each do |sql|
+            args << "-s" << sql
+          end
+        end
+        args << "--"
+        args += command
+  
+        {
+          "steps" => [
+            "name" => @wrapper_image,
+            "args" => args
+          ]
+        }
+      end
+    end
+  end
+end