renuo-cli 4.27.0 → 4.29.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8b4a37d01ef907f898f0287766c0dd1be73c55a35516e54adda7b1b3c5b798c9
-  data.tar.gz: 12e28effd0aaf9a7aaf52dd297a7ef6412f24514ed3940c34649ecf9b968f27b
+  metadata.gz: ea0940fbcb4f6adcee05932e3706029dfd00c20aae778925992fd20c4e4122d7
+  data.tar.gz: d00eb2084014053724e2c8dfdc6e4b1595bdf3edbfd7d3185d6edcc628bbfdd1
 SHA512:
-  metadata.gz: e400a1dd7cc3d3287d478bd4b52ae5964af1dca75138b680368eb5192ae3c57fda3a1924ea168b8c1ec21bd9cc7ca63b23b787d2484361e6e6dfcc9ee8f768ed
-  data.tar.gz: 517ba241db1d5bee9ae502e1a71847e7196447c53e84721cd2ce92e3b1452c1630d3331aae76cc5ae085f22289a67a4a35ad7f85fe48bccb8ca4368e8ee06b06
+  metadata.gz: aee1f47d1bac9b8082fb450f6b14e4225d6af5b30233cc129fa6b1559871d0901b40924ebbbf163ab88ea493a124cddacb3725fb087acdab47b58fd8088906ab
+  data.tar.gz: 672f554707e987a99d6dae554b2585a0bf4e7add4f69187e8a06df303e61e94938d6af17e28a54f2c8aa4624b6bafb3f2a9c2b5d56de06a69b14e7ab7bbe4a64

data/lib/renuo/cli/commands/configure_semaphore.rb

@@ -53,8 +53,9 @@ class Renuo::Cli::Commands::ConfigureSemaphore
   end
 
   def create_semaphore_deployment_targets
-    system("sem create dt main -p #{project_name}")
-    system("sem create dt develop -p #{project_name}")
+    %w[main develop].each do |branch|
+      system("sem create dt #{branch} -p #{project_name} --object-rule branch,exact,#{branch}")
+    end
   end
 
   def render(template_file)

data/lib/renuo/cli/commands/release.rb

@@ -108,7 +108,9 @@ class Renuo::Cli::Commands::Release # rubocop:disable Metrics/ClassLength
   end
 
   def checkout_project
-    abort(">> Project not found.") unless system("#{MOVE_TO_TMP_FOLDER} && git clone git@#{@host}:#{@repo_path}.git")
+    # Blobless clone: file contents are only fetched when needed, so large files in the history are skipped
+    clone = "git clone --filter=blob:none git@#{@host}:#{@repo_path}.git"
+    abort(">> Project not found.") unless system("#{MOVE_TO_TMP_FOLDER} && #{clone}")
 
     system(cmd_in_folder("git checkout #{main_branch} && git pull origin #{main_branch} &&" \
                          "git checkout #{develop_branch} && git pull origin #{develop_branch}"))

data/lib/renuo/cli/commands/review_app/deploy.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require_relative "../../helpers/safe_review_app_name_contract"
+
+module Renuo::Cli::Commands::ReviewApp
+  class Deploy < Actor
+    include ReviewAppHelper
+    include Renuo::Cli::Services
+    include Contracts::Core
+
+    command "review-app:deploy" do |c|
+      c.syntax = "renuo review-app:deploy [options]"
+      c.summary = "Copies the origin Deploio app (matching the origin pattern) and its services " \
+                  "into a target review app for the current branch."
+      c.description = c.summary
+      c.option "-p", "--project <name>", String, "The name of the Deploio project"
+      c.option "-b", "--branch <name>", String, "The Git branch"
+      c.option "--origin-pattern <pattern>", String, "Name pattern identifying the origin app to copy from"
+      c.option "--start", "Start the app right away instead of waiting for its env variables to be configured"
+      c.option "--keep-envs <categories>", Array,
+               "Copied env categories (build or runtime) to keep instead of dropping " \
+               "(comma-separated): #{Renuo::Cli::Services::Deploio::CopyApp::ENV_CATEGORIES.join(",")}"
+      c.example "renuo review-app:deploy -p renuo-acme --branch feature/42-migrate-to-deploio --origin-pattern develop",
+                "Creates a review app tracking feature/42-migrate-to-deploio, copied from the develop app"
+      c.example "renuo review-app:deploy -p renuo-acme -b fix/1337-we-can-fix-everything111 --origin-pattern develop " \
+                "--keep-envs=#{Renuo::Cli::Services::Deploio::CopyApp::ENV_CATEGORIES.join(",")} --start",
+                "Creates a review app reusing all the origin's env variables and starts it right away"
+      c.action do |_args, options|
+        call(project: options.project, branch: options.branch, origin_pattern: options.origin_pattern,
+             start: options.start, keep_envs: options.keep_envs || [])
+      end
+    end
+
+    input :project,
+          must: { be_given: { is: ->(value) { value }, message: ->(**) { "missing project name" } } }
+    input :branch,
+          must: { be_given: { is: ->(value) { value }, message: ->(**) { "missing branch name" } } }
+    input :origin_pattern,
+          must: { be_given: { is: ->(value) { value }, message: ->(**) { "missing origin pattern name" } } }
+    input :start, default: false
+    input :keep_envs,
+          default: [],
+          must: {
+            be_known_categories: {
+              is: ->(value) { (value - Deploio::CopyApp::ENV_CATEGORIES).empty? },
+              message: (lambda do |value:, **|
+                "unknown env categories: #{(value - Deploio::CopyApp::ENV_CATEGORIES).join(", ")}"
+              end)
+            }
+          }
+
+    output :url
+
+    play :derive_target_app_name,
+         Deploio::InventorizeOriginResources,
+         :print_origin_resources,
+         Deploio::CopyApp
+
+    play Deploio::CreateDatabase,
+         Deploio::CopyDatabaseData,
+         if: ->(inventory) { inventory.origin_database_name }
+
+    play Deploio::CreateKvs,
+         if: ->(inventory) { inventory.origin_key_value_store_name }
+
+    play Deploio::CreateS3,
+         Deploio::CopyS3Data,
+         if: ->(inventory) { inventory.origin_bucket_name }
+
+    play :collect_target_envs,
+         Deploio::UpdateTargetAppEnv
+
+    play Deploio::StartTargetApp,
+         if: ->(result) { result.start }
+
+    play CmdTrail::Print,
+         :print_url
+
+    private
+
+    Contract Contracts::None => SafeReviewAppNameContract
+    def derive_target_app_name
+      result.target_app_name = review_app_name(branch).tap do |name|
+        abort "'#{name}' contains the origin pattern '#{origin_pattern}', aborting" if name.include?(origin_pattern)
+      end
+    end
+
+    def print_origin_resources
+      inventory_value = ->(key) { result.public_send(key) || "none" }
+
+      puts <<~INVENTORY
+        copying origin resources from project '#{result.project}':
+          app: #{result.origin_app_name}
+          database: #{inventory_value[:origin_database_name]}
+          database backup: #{inventory_value[:origin_backup_path]}
+          database backup bucket user: #{inventory_value[:origin_backup_bucket_user]}
+          key-value store: #{inventory_value[:origin_key_value_store_name]}
+          bucket: #{inventory_value[:origin_bucket_name]}
+          bucket user: #{inventory_value[:origin_bucket_user]}
+      INVENTORY
+    end
+
+    def collect_target_envs
+      result.envs = [result.database_env, result.kvs_env, result.s3_env].compact
+    end
+
+    def print_url
+      self.url = Deploio.fetch_resource("app", result.target_app_name, result.project)
+                        .dig("status", "atProvider", "defaultURLs", 0)
+      puts "\nthe review app will run at #{url || "<no URL assigned yet>"}"
+      puts "start it with: renuo review-app:start --project #{project} --branch #{branch}" unless start
+    end
+  end
+end

data/lib/renuo/cli/commands/review_app/name.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative "../../helpers/safe_review_app_name_contract"
+
+module Renuo::Cli::Commands::ReviewApp
+  class Name
+    include ReviewAppHelper
+    include Contracts::Core
+
+    command "review-app:name" do |c|
+      c.syntax = "renuo review-app:name [options]"
+      c.summary = "Prints the review app name derived from the branch."
+      c.description = c.summary
+      c.option "-b", "--branch <name>", String, "The Git branch"
+      c.example "nctl update app $(renuo review-app:name -b add-s3-to-docs) -p renuo-acme --env KEY=value",
+                "Sets an env variable on the branch's review app"
+      c.action { |_args, options| new(options).run }
+    end
+
+    def run
+      puts @name
+    end
+
+    private
+
+    def initialize(options)
+      branch = options.branch
+
+      abort "missing branch name" unless branch
+      @name = derive_name(branch)
+    end
+
+    Contract String => SafeReviewAppNameContract
+    def derive_name(branch)
+      review_app_name(branch)
+    end
+  end
+end

data/lib/renuo/cli/commands/review_app/purge.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require_relative "../../helpers/safe_review_app_name_contract"
+
+module Renuo::Cli::Commands::ReviewApp
+  class Purge
+    include ReviewAppHelper
+    include Contracts::Core
+    include Contracts::Invariants
+
+    RESOURCE_TYPES = %w[app postgresdatabase kvs bucket bucketuser].freeze
+
+    invariant(:name_pattern) { SafeReviewAppNameContract.valid?(@name_pattern) }
+
+    command "review-app:purge" do |c|
+      c.syntax = "renuo review-app:purge [options]"
+      c.summary = "Deletes all Deploio resources whose name contains the branch's review app name."
+      c.description = c.summary
+      c.option "-p", "--project <name>", String, "The name of the Deploio project"
+      c.option "-b", "--branch <name>", String, "The Git branch"
+      c.example "renuo review-app:purge -p renuo-acme -b feature/42-migrate-to-deploio",
+                "Deletes all review app resources named after the branch"
+      c.action { |_args, options| new(options).run }
+    end
+
+    def run
+      RESOURCE_TYPES.each { |type| purge_matching(type, @name_pattern) }
+      CmdTrail::Print.call
+    end
+
+    private
+
+    def initialize(options)
+      @project = options.project
+      branch = options.branch
+
+      abort "missing project name" unless @project
+      abort "missing branch name" unless branch
+      derive_name_pattern(branch)
+    end
+
+    Contract String => SafeReviewAppNameContract
+    def derive_name_pattern(branch)
+      @name_pattern = review_app_name(branch)
+    end
+
+    Contract Contracts::Enum[*RESOURCE_TYPES], SafeReviewAppNameContract => Contracts::Any
+    def purge_matching(type, name_pattern)
+      names = matching_names(type, name_pattern)
+      return puts "no #{type} matching '#{name_pattern}' found, skipping" if names.empty?
+
+      names.each do |name|
+        puts "deleting #{type} #{name}..."
+        system! "nctl delete #{type} #{name} -p #{@project} --force --wait"
+      end
+    end
+
+    def matching_names(type, name_pattern)
+      nctl_resources("nctl get #{type} -p #{@project} -o yaml").filter_map do |resource|
+        next if resource.dig("metadata", "labels", "nine.ch/owned-by") == "nine"
+
+        name = resource.dig("metadata", "name")
+        name if name.include?(name_pattern)
+      end
+    end
+  end
+end

data/lib/renuo/cli/commands/review_app/setup_semaphoreci.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module Renuo::Cli::Commands::ReviewApp
+  class SetupSemaphoreci
+    DEPLOY_PIPELINE_TEMPLATE_FILE = File.join(__dir__, "../../templates/semaphore/review-app-deploy.yml.erb")
+    PURGE_PIPELINE_TEMPLATE_FILE = File.join(__dir__, "../../templates/semaphore/review-app-purge.yml.erb")
+
+    DEPLOY_PIPELINE_TARGET_FILE = ".semaphore/review-app-deploy.yml"
+    PURGE_PIPELINE_TARGET_FILE = ".semaphore/review-app-purge.yml"
+
+    attr_reader :project, :origin_pattern
+
+    command "review-app:setup-semaphoreci" do |c|
+      c.syntax = "renuo review-app:setup-semaphoreci [options]"
+      c.summary = "Generates the pipeline files to deploy and purge Deploio review apps."
+      c.description = c.summary
+      c.option "-p", "--project <name>", String, "The name of the Deploio project"
+      c.option "--origin-pattern <pattern>", String, "Name pattern identifying the origin app to copy from"
+      c.action { |_args, options| new(options).run }
+    end
+
+    def run
+      FileUtils.mkdir_p File.dirname(DEPLOY_PIPELINE_TARGET_FILE)
+      write_or_warn DEPLOY_PIPELINE_TARGET_FILE,
+                    render(DEPLOY_PIPELINE_TEMPLATE_FILE, { project:, origin_pattern:, secret_name: })
+      write_or_warn PURGE_PIPELINE_TARGET_FILE, render(PURGE_PIPELINE_TEMPLATE_FILE, { project:, secret_name: })
+      print_instructions
+    end
+
+    private
+
+    def initialize(options)
+      @project = options.project || abort("missing project name")
+      @origin_pattern = options.origin_pattern || abort("missing origin pattern")
+    end
+
+    def secret_name
+      "nctl-#{project}-review-apps"
+    end
+
+    # Deploio project names are prefixed with the name of their organization.
+    def organization
+      project.split("-").first
+    end
+
+    def print_instructions
+      service_account_name = "review-apps"
+      say <<~INSTRUCTIONS
+
+        Create a service account restricted to the Deploio project #{project}:
+
+          nctl create asa #{service_account_name} --project #{project}
+
+        Register its credentials as the Semaphore secret #{secret_name}, used by both pipelines:
+
+          sem create secret #{secret_name} \\
+            -e NCTL_API_CLIENT_ID="$(nctl get asa #{service_account_name} --project #{project} --print-client-id)" \\
+            -e NCTL_API_CLIENT_SECRET="$(nctl get asa #{service_account_name} --project #{project} --print-client-secret)" \\
+            -e NCTL_ORGANIZATION=#{organization}
+
+        Add these promotions to .semaphore/semaphore.yml (no auto_promote, so they only run on click):
+
+          - name: review-app-deploy
+            pipeline_file: review-app-deploy.yml
+
+          - name: review-app-purge
+            pipeline_file: review-app-purge.yml
+
+        Both buttons appear on every branch workflow in Semaphore. Deploy and purge the review app
+        of a branch by clicking the promotion on that branch's workflow.
+      INSTRUCTIONS
+    end
+
+    def render(template_file, variables)
+      ERB.new(File.read(template_file)).result_with_hash(variables)
+    end
+
+    def write_or_warn(file_path, content)
+      if File.exist?(file_path)
+        warn("#{file_path} exists already. I will not overwrite it.")
+      else
+        File.write(file_path, content)
+        say("#{file_path} added.")
+      end
+    end
+  end
+end

data/lib/renuo/cli/commands/review_app/start.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require_relative "../../helpers/safe_review_app_name_contract"
+
+module Renuo::Cli::Commands::ReviewApp
+  class Start
+    include ReviewAppHelper
+    include Renuo::Cli::Services
+    include Contracts::Core
+    include Contracts::Invariants
+
+    invariant(:target_app_name) { SafeReviewAppNameContract.valid?(@target_app_name) }
+
+    command "review-app:start" do |c|
+      c.syntax = "renuo review-app:start [options]"
+      c.summary = "Starts the branch's review app once its env variables are configured."
+      c.description = c.summary
+      c.option "-p", "--project <name>", String, "The name of the Deploio project"
+      c.option "-b", "--branch <name>", String, "The Git branch"
+      c.example "renuo review-app:start -p renuo-acme -b feature/42-migrate-to-deploio",
+                "Builds and deploys the branch's review app"
+      c.action { |_args, options| new(options).run }
+    end
+
+    def run
+      Deploio::StartTargetApp.call(project: @project, target_app_name: @target_app_name, branch: @branch)
+      CmdTrail::Print.call
+      print_url
+    end
+
+    private
+
+    def print_url
+      url = Deploio.fetch_resource("app", @target_app_name, @project)
+                   .dig("status", "atProvider", "defaultURLs", 0)
+      puts "\nthe review app will run at #{url || "<no URL assigned yet>"}"
+    end
+
+    def initialize(options)
+      @project = options.project
+      @branch = options.branch
+
+      abort "missing project name" unless @project
+      abort "missing branch name" unless @branch
+      derive_target_app_name(@branch)
+    end
+
+    Contract String => SafeReviewAppNameContract
+    def derive_target_app_name(branch)
+      @target_app_name = review_app_name(branch)
+    end
+  end
+end

data/lib/renuo/cli/helpers/actor_contracts.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+# Lets service actors state contracts.ruby-style contracts (anything with .valid?) as must: checks.
+module ActorContracts
+  def satisfy(*contracts)
+    contracts.to_h do |contract|
+      raise ArgumentError, "#{contract.inspect} is not a contract (no .valid?)" unless contract.respond_to?(:valid?)
+
+      [:"satisfy_#{contract.name.demodulize.underscore}",
+       { is: ->(value) { contract.valid?(value) },
+         message: ->(value:, **) { "#{value.inspect} is not #{contract}" } }]
+    end
+  end
+end
+
+Actor.extend(ActorContracts)

data/lib/renuo/cli/helpers/cmd_trail.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+# Collects every CLI command a run executes so Print can show how to reproduce it.
+module CmdTrail
+  module_function
+
+  def record(command, env = {})
+    entries << { command: command, env: env }
+  end
+
+  def entries
+    @entries ||= []
+  end
+
+  def clear
+    entries.clear
+  end
+
+  class Print < Actor
+    SENSITIVE_KEY_PATTERN = /KEY|SECRET|TOKEN|PASSWORD/i
+    URL_PASSWORD_PATTERN = %r{(://[^:/@\s]*:)[^@\s]+@}
+
+    def call
+      return if CmdTrail.entries.empty?
+
+      puts "\nexecuted commands (rerun them to reproduce):"
+      CmdTrail.entries.each { |entry| puts "  #{line(entry)}" }
+    end
+
+    private
+
+    def line(entry)
+      [env_prefix(entry[:env]), redact(entry[:command])]
+        .reject(&:empty?).join(" ")
+    end
+
+    def redact(command)
+      command.sub(/--sensitive-env .*/, "--sensitive-env [redacted]").gsub(URL_PASSWORD_PATTERN, '\\1[redacted]@')
+    end
+
+    def env_prefix(env)
+      env.map { |key, value| "#{key}=#{SENSITIVE_KEY_PATTERN.match?(key) ? "[redacted]" : value}" }.join(" ")
+    end
+  end
+end

data/lib/renuo/cli/helpers/review_app_helper.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module ReviewAppHelper
+  HASH_LENGTH = 6
+  MAX_NUMBER_LENGTH = 10
+  NAME_PATTERN = /\Areview-app-(?:\d{1,#{MAX_NUMBER_LENGTH}}-)?\h{#{HASH_LENGTH}}\z/
+  MIN_PATTERN_LENGTH = 3
+
+  def review_app_name(branch)
+    number = branch[/\d+/]&.slice(0, MAX_NUMBER_LENGTH)
+    ["review-app", number, Digest::SHA256.hexdigest(branch)[0, HASH_LENGTH]].compact.join("-")
+  end
+
+  # nctl prints a YAML stream, a YAML list, "[]" or a plain-text banner, depending on version and match count
+  def nctl_resources(command)
+    stdout, = system!(command, quiet: true)
+    return [] if stdout.lines.first.to_s.match?(/No ".+" found/)
+
+    resources = Psych.load_stream(stdout).flatten.compact
+    return resources if resources.all?(Hash)
+
+    abort "'#{command}' printed no nctl resources:\n#{stdout}"
+  rescue Psych::SyntaxError
+    abort "'#{command}' printed no nctl resources:\n#{stdout}"
+  end
+
+  def system!(command, env = {}, quiet: false, abort_on_failure: true)
+    CmdTrail.record(command, env)
+    stdout, stderr, status = Open3.capture3(env, command)
+    puts stdout unless quiet || stdout.empty?
+    if !status.success? && abort_on_failure
+      abort "'#{command.split.first(2).join(" ")}' failed: #{stderr.presence || stdout}"
+    end
+    [stdout, stderr, status]
+  end
+
+  def aws_credentials(access_key, secret_key)
+    {
+      "AWS_ACCESS_KEY_ID" => access_key,
+      "AWS_SECRET_ACCESS_KEY" => secret_key,
+      "AWS_DEFAULT_REGION" => "us-east-1"
+    }
+  end
+end

data/lib/renuo/cli/helpers/safe_review_app_name_contract.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "contracts"
+
+# Module-wide contract: a name that may address review app resources on Deploio.
+# Commands establish it as a postcondition of name derivation and keep it as a
+# class invariant; the Deploio actors demand it as a precondition before touching
+# any resource. A violation always means a bug, never bad user input.
+class SafeReviewAppNameContract
+  def self.valid?(name)
+    name.is_a?(String) && name.match?(ReviewAppHelper::NAME_PATTERN)
+  end
+
+  def self.to_s
+    "a review app name matching #{ReviewAppHelper::NAME_PATTERN.inspect}"
+  end
+end

data/lib/renuo/cli/services/deploio/copy_app.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "shellwords"
+
+class Renuo::Cli::Services::Deploio
+  class CopyApp < Actor
+    include ReviewAppHelper
+    include Renuo::Cli::Services
+
+    ENV_CATEGORIES = %w[build sensitive-build runtime sensitive-runtime].freeze
+
+    input :project
+    input :target_app_name, must: satisfy(SafeReviewAppNameContract)
+    input :origin_app_name
+    input :branch
+    input :keep_envs, default: []
+
+    def call
+      if Deploio.resource_exists?("app", target_app_name, project)
+        puts "app #{target_app_name} already exists, skipping copy"
+      else
+        puts "copying app #{origin_app_name} to #{target_app_name}..."
+        system! "nctl copy app #{origin_app_name} -p #{project} --target-name #{target_app_name}"
+        reconfigure_copy
+      end
+    end
+
+    private
+
+    def reconfigure_copy
+      Kernel.sleep(1) # Deploio usually needs a moment to finish reconciling the fresh copy
+      flags = [delete_flag("--delete-env", dropped_keys("config", "env", kind: "runtime")),
+               delete_flag("--delete-build-env", dropped_keys("buildEnv", kind: "build"))].compact
+      dropping = flags.empty? ? "" : " and dropping the copied env variables"
+      puts "pointing #{target_app_name} at branch #{branch}#{dropping}..."
+      system! ["nctl update app #{target_app_name} -p #{project}",
+               "--git-revision #{Shellwords.escape(branch)} --skip-repo-access-check",
+               *flags].join(" ")
+    end
+
+    def delete_flag(flag, keys)
+      "#{flag} #{Shellwords.escape(keys.join(";"))}" unless keys.empty?
+    end
+
+    def dropped_keys(*path, kind:)
+      env = copied_spec.dig(*path) || []
+      env.reject { |variable| keep_envs.include?(variable["sensitive"] ? "sensitive-#{kind}" : kind) }
+         .pluck("name")
+    end
+
+    def copied_spec
+      @copied_spec ||= Deploio.fetch_resource("app", target_app_name, project).dig("spec", "forProvider") || {}
+    end
+  end
+end

data/lib/renuo/cli/services/deploio/copy_database_data.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "shellwords"
+
+class Renuo::Cli::Services::Deploio
+  class CopyDatabaseData < Actor
+    include ReviewAppHelper
+
+    BACKUP_FILE = File.join(Dir.tmpdir, "review-app-backup.sql.zst")
+    USER_TABLES_QUERY = "SELECT count(*) FROM pg_tables WHERE schemaname NOT IN ('pg_catalog', 'information_schema')"
+
+    input :target_app_name, must: satisfy(SafeReviewAppNameContract)
+    input :database_env
+    input :origin_backup_bucket
+    input :origin_backup_path
+    input :origin_backup_endpoint
+    input :origin_backup_access_key
+    input :origin_backup_secret_key
+
+    def call
+      return warn "no origin database backup found, leaving #{target_app_name} empty" unless origin_backup_path
+      return puts "database #{target_app_name} already holds tables, skipping backup restore" unless database_empty?
+
+      puts "restoring #{origin_backup_path} into #{target_app_name}..."
+      download_backup
+      system! "zstd -dfq #{BACKUP_FILE}"
+      restore_backup
+    ensure
+      FileUtils.rm_f([BACKUP_FILE, BACKUP_FILE.delete_suffix(".zst")])
+    end
+
+    private
+
+    def download_backup
+      system! "aws s3 cp s3://#{origin_backup_bucket}/#{origin_backup_path} #{BACKUP_FILE} " \
+              "--endpoint-url https://#{origin_backup_endpoint}",
+              aws_credentials(origin_backup_access_key, origin_backup_secret_key)
+    end
+
+    def database_empty?
+      stdout, = system!("psql #{database_url} -tAc #{Shellwords.escape(USER_TABLES_QUERY)}", quiet: true)
+      Integer(stdout.strip).zero?
+    end
+
+    # Despite their .sql.zst name, Deploio backups are pg_dump custom-format archives.
+    # A single transaction leaves the database empty on failure, so a rerun restores it again.
+    def restore_backup
+      system! "pg_restore --single-transaction --no-owner --no-privileges --no-comments " \
+              "-d #{database_url} " \
+              "#{BACKUP_FILE.delete_suffix(".zst")}"
+    end
+
+    def database_url
+      Shellwords.escape(database_env.fetch("DATABASE_URL"))
+    end
+  end
+end