capistrano 2.8.0 → 3.19.0

data/lib/capistrano/doctor/output_helpers.rb

@@ -0,0 +1,79 @@
+module Capistrano
+  module Doctor
+    # Helper methods for pretty-printing doctor output to stdout. All output
+    # (other than `title`) is indented by four spaces to facilitate copying and
+    # pasting this output into e.g. GitHub or Stack Overflow to achieve code
+    # formatting.
+    module OutputHelpers
+      class Row
+        attr_reader :color
+        attr_reader :values
+
+        def initialize
+          @values = []
+        end
+
+        def <<(value)
+          values << value
+        end
+
+        def yellow
+          @color = :yellow
+        end
+      end
+
+      # Prints a table for a given array of records. For each record, the block
+      # is yielded two arguments: the record and a Row object. To print values
+      # for that record, add values using `row << "some value"`. A row can
+      # optionally be highlighted in yellow using `row.yellow`.
+      def table(records, &block)
+        return if records.empty?
+        rows = collect_rows(records, &block)
+        col_widths = calculate_column_widths(rows)
+
+        rows.each do |row|
+          line = row.values.each_with_index.map do |value, col|
+            value.to_s.ljust(col_widths[col])
+          end.join(" ").rstrip
+          line = color.colorize(line, row.color) if row.color
+          puts line
+        end
+      end
+
+      # Prints a title in blue with surrounding newlines.
+      def title(text)
+        # Use $stdout directly to bypass the indentation that our `puts` does.
+        $stdout.puts(color.colorize("\n#{text}\n", :blue))
+      end
+
+      # Prints text in yellow.
+      def warning(text)
+        puts color.colorize(text, :yellow)
+      end
+
+      # Override `Kernel#puts` to prepend four spaces to each line.
+      def puts(string=nil)
+        $stdout.puts(string.to_s.gsub(/^/, "    "))
+      end
+
+      private
+
+      def collect_rows(records)
+        records.map do |rec|
+          Row.new.tap { |row| yield(rec, row) }
+        end
+      end
+
+      def calculate_column_widths(rows)
+        num_columns = rows.map { |row| row.values.length }.max
+        Array.new(num_columns) do |col|
+          rows.map { |row| row.values[col].to_s.length }.max
+        end
+      end
+
+      def color
+        @color ||= SSHKit::Color.new($stdout)
+      end
+    end
+  end
+end

data/lib/capistrano/doctor/servers_doctor.rb

@@ -0,0 +1,105 @@
+require "capistrano/doctor/output_helpers"
+
+module Capistrano
+  module Doctor
+    class ServersDoctor
+      include Capistrano::Doctor::OutputHelpers
+
+      def initialize(env=Capistrano::Configuration.env)
+        @servers = env.servers.to_a
+      end
+
+      def call
+        title("Servers (#{servers.size})")
+        rwc = RoleWhitespaceChecker.new(servers)
+
+        table(servers) do |server, row|
+          sd = ServerDecorator.new(server)
+
+          row << sd.uri_form
+          row << sd.roles
+          row << sd.properties
+          row.yellow if rwc.any_has_whitespace?(server.roles)
+        end
+
+        if rwc.whitespace_roles.any?
+          warning "\nWhitespace detected in role(s) #{rwc.whitespace_roles_decorated}. " \
+            "This might be a result of a mistyped \"%w()\" array literal."
+        end
+        puts
+      end
+
+      private
+
+      attr_reader :servers
+
+      class RoleWhitespaceChecker
+        attr_reader :whitespace_roles, :servers
+
+        def initialize(servers)
+          @servers = servers
+          @whitespace_roles = find_whitespace_roles
+        end
+
+        def any_has_whitespace?(roles)
+          roles.any? { |role| include_whitespace?(role) }
+        end
+
+        def include_whitespace?(role)
+          role =~ /\s/
+        end
+
+        def whitespace_roles_decorated
+          whitespace_roles.map(&:inspect).join(", ")
+        end
+
+        private
+
+        def find_whitespace_roles
+          servers.map(&:roles).flat_map(&:to_a).uniq
+                 .select { |role| include_whitespace?(role) }
+        end
+      end
+
+      class ServerDecorator
+        def initialize(server)
+          @server = server
+        end
+
+        def uri_form
+          [
+            server.user,
+            server.user && "@",
+            server.hostname,
+            server.port && ":",
+            server.port
+          ].compact.join
+        end
+
+        def roles
+          server.roles.to_a.inspect
+        end
+
+        def properties
+          return "" unless server.properties.keys.any?
+          pretty_inspect(server.properties.to_h)
+        end
+
+        private
+
+        attr_reader :server
+
+        # Hashes with proper padding
+        def pretty_inspect(element)
+          return element.inspect unless element.is_a?(Hash)
+
+          pairs_string = element.keys.map do |key|
+            [pretty_inspect(key), pretty_inspect(element.fetch(key))].join(" => ")
+          end.join(", ")
+
+          "{ #{pairs_string} }"
+        end
+      end
+    end
+  end
+end

data/lib/capistrano/doctor/variables_doctor.rb

@@ -0,0 +1,74 @@
+require "capistrano/doctor/output_helpers"
+
+module Capistrano
+  module Doctor
+    # Prints a table of all Capistrano variables and their current values. If
+    # there are unrecognized variables, print warnings for them.
+    class VariablesDoctor
+      # These are keys that are recognized by Capistrano, but do not have values
+      # set by default.
+      WHITELIST = %i(
+        application
+        current_directory
+        linked_dirs
+        linked_files
+        releases_directory
+        repo_url
+        repo_tree
+        shared_directory
+      ).freeze
+      private_constant :WHITELIST
+
+      include Capistrano::Doctor::OutputHelpers
+
+      def initialize(env=Capistrano::Configuration.env)
+        @env = env
+      end
+
+      def call
+        title("Variables")
+        values = inspect_all_values
+
+        table(variables.keys.sort_by(&:to_s)) do |key, row|
+          row.yellow if suspicious_keys.include?(key)
+          row << key.inspect
+          row << values[key]
+        end
+
+        puts if suspicious_keys.any?
+
+        suspicious_keys.sort_by(&:to_s).each do |key|
+          warning("#{key.inspect} is not a recognized Capistrano setting "\
+                  "(#{location(key)})")
+        end
+      end
+
+      private
+
+      attr_reader :env
+
+      def variables
+        env.variables
+      end
+
+      def inspect_all_values
+        variables.keys.each_with_object({}) do |key, inspected|
+          inspected[key] = if env.is_question?(key)
+                             "<ask>"
+                           else
+                             variables.peek(key).inspect
+                           end
+        end
+      end
+
+      def suspicious_keys
+        (variables.untrusted_keys & variables.unused_keys) - WHITELIST
+      end
+
+      def location(key)
+        loc = variables.source_locations(key).first
+        loc && loc.sub(/^#{Regexp.quote(Dir.pwd)}/, "").sub(/:in.*/, "")
+      end
+    end
+  end
+end

data/lib/capistrano/doctor.rb

@@ -0,0 +1,6 @@
+require "capistrano/doctor/environment_doctor"
+require "capistrano/doctor/gems_doctor"
+require "capistrano/doctor/variables_doctor"
+require "capistrano/doctor/servers_doctor"
+
+load File.expand_path("../tasks/doctor.rake", __FILE__)

data/lib/capistrano/dotfile.rb

@@ -0,0 +1,2 @@
+dotfile = Pathname.new(File.join(Dir.home, ".capfile"))
+load dotfile if dotfile.file?

data/lib/capistrano/dsl/env.rb

@@ -0,0 +1,43 @@
+require "forwardable"
+
+module Capistrano
+  module DSL
+    module Env
+      extend Forwardable
+      def_delegators :env,
+                     :configure_backend, :fetch, :set, :set_if_empty, :delete,
+                     :ask, :role, :server, :primary, :validate, :append,
+                     :remove, :dry_run?, :install_plugin, :any?, :is_question?,
+                     :configure_scm, :scm_plugin_installed?
+
+      def roles(*names)
+        env.roles_for(names.flatten)
+      end
+
+      def role_properties(*names, &block)
+        env.role_properties_for(names, &block)
+      end
+
+      def release_roles(*names)
+        if names.last.is_a? Hash
+          names.last[:exclude] = :no_release
+        else
+          names << { exclude: :no_release }
+        end
+        roles(*names)
+      end
+
+      def env
+        Configuration.env
+      end
+
+      def release_timestamp
+        env.timestamp.strftime("%Y%m%d%H%M%S")
+      end
+
+      def asset_timestamp
+        env.timestamp.strftime("%Y%m%d%H%M.%S")
+      end
+    end
+  end
+end

data/lib/capistrano/dsl/paths.rb

@@ -0,0 +1,89 @@
+require "pathname"
+module Capistrano
+  module DSL
+    module Paths
+      def deploy_to
+        fetch(:deploy_to)
+      end
+
+      def deploy_path
+        Pathname.new(deploy_to)
+      end
+
+      def current_path
+        deploy_path.join(fetch(:current_directory, "current"))
+      end
+
+      def releases_path
+        deploy_path.join(fetch(:releases_directory, "releases"))
+      end
+
+      def release_path
+        fetch(:release_path) { current_path }
+      end
+
+      def set_release_path(timestamp=now)
+        set(:release_timestamp, timestamp)
+        set(:release_path, releases_path.join(timestamp))
+      end
+
+      def stage_config_path
+        Pathname.new fetch(:stage_config_path, "config/deploy")
+      end
+
+      def deploy_config_path
+        Pathname.new fetch(:deploy_config_path, "config/deploy.rb")
+      end
+
+      def repo_url
+        fetch(:repo_url)
+      end
+
+      def repo_path
+        Pathname.new(fetch(:repo_path, ->() { deploy_path.join("repo") }))
+      end
+
+      def shared_path
+        deploy_path.join(fetch(:shared_directory, "shared"))
+      end
+
+      def revision_log
+        deploy_path.join("revisions.log")
+      end
+
+      def now
+        env.timestamp.strftime("%Y%m%d%H%M%S")
+      end
+
+      def asset_timestamp
+        env.timestamp.strftime("%Y%m%d%H%M.%S")
+      end
+
+      def linked_dirs(parent)
+        paths = fetch(:linked_dirs)
+        join_paths(parent, paths)
+      end
+
+      def linked_files(parent)
+        paths = fetch(:linked_files)
+        join_paths(parent, paths)
+      end
+
+      def linked_file_dirs(parent)
+        map_dirnames(linked_files(parent))
+      end
+
+      def linked_dir_parents(parent)
+        map_dirnames(linked_dirs(parent))
+      end
+
+      def join_paths(parent, paths)
+        paths.map { |path| parent.join(path) }
+      end
+
+      def map_dirnames(paths)
+        paths.map(&:dirname).uniq
+      end
+    end
+  end
+end

data/lib/capistrano/dsl/stages.rb

@@ -0,0 +1,31 @@
+module Capistrano
+  module DSL
+    module Stages
+      RESERVED_NAMES = %w(deploy doctor install).freeze
+      private_constant :RESERVED_NAMES
+
+      def stages
+        names = Dir[stage_definitions].map { |f| File.basename(f, ".rb") }
+        assert_valid_stage_names(names)
+        names
+      end
+
+      def stage_definitions
+        stage_config_path.join("*.rb")
+      end
+
+      def stage_set?
+        !!fetch(:stage, false)
+      end
+
+      private
+
+      def assert_valid_stage_names(names)
+        invalid = names.find { |n| RESERVED_NAMES.include?(n) }
+        return if invalid.nil?
+
+        raise t("error.invalid_stage_name", name: invalid, path: stage_config_path.join("#{invalid}.rb"))
+      end
+    end
+  end
+end

data/lib/capistrano/dsl/task_enhancements.rb

@@ -0,0 +1,61 @@
+require "capistrano/upload_task"
+
+module Capistrano
+  module TaskEnhancements
+    def before(task, prerequisite, *args, &block)
+      prerequisite = Rake::Task.define_task(prerequisite, *args, &block) if block_given?
+      Rake::Task[task].enhance [prerequisite]
+    end
+
+    def after(task, post_task, *args, &block)
+      Rake::Task.define_task(post_task, *args, &block) if block_given?
+      task = Rake::Task[task]
+      task.enhance do
+        post = Rake.application.lookup(post_task, task.scope)
+        raise ArgumentError, "Task #{post_task.inspect} not found" unless post
+        post.invoke
+      end
+    end
+
+    def define_remote_file_task(task, target_roles)
+      Capistrano::UploadTask.define_task(task) do |t|
+        prerequisite_file = t.prerequisites.first
+        file = shared_path.join(t.name)
+
+        on roles(target_roles) do
+          unless test "[ -f #{file.to_s.shellescape} ]"
+            info "Uploading #{prerequisite_file} to #{file}"
+            upload! File.open(prerequisite_file), file
+          end
+        end
+      end
+    end
+
+    def ensure_stage
+      Rake::Task.define_task(:ensure_stage) do
+        unless stage_set?
+          puts t(:stage_not_set)
+          exit 1
+        end
+      end
+    end
+
+    def tasks_without_stage_dependency
+      stages + default_tasks
+    end
+
+    def default_tasks
+      %w{install}
+    end
+
+    def exit_deploy_because_of_exception(ex)
+      warn t(:deploy_failed, ex: ex.message)
+      invoke "deploy:failed"
+      exit(false)
+    end
+
+    def deploying?
+      fetch(:deploying, false)
+    end
+  end
+end

data/lib/capistrano/dsl.rb

@@ -0,0 +1,95 @@
+require "capistrano/dsl/task_enhancements"
+require "capistrano/dsl/paths"
+require "capistrano/dsl/stages"
+require "capistrano/dsl/env"
+require "capistrano/configuration/filter"
+
+module Capistrano
+  module DSL
+    include TaskEnhancements
+    include Env
+    include Paths
+    include Stages
+
+    def invoke(task_name, *args)
+      task = Rake::Task[task_name]
+      # NOTE: We access instance variable since the accessor was only added recently. Once Capistrano depends on rake 11+, we can revert the following line
+      if task && task.instance_variable_get(:@already_invoked)
+        file, line, = caller.first.split(":")
+        colors = SSHKit::Color.new($stderr)
+        $stderr.puts colors.colorize("Skipping task `#{task_name}'.", :yellow)
+        $stderr.puts "Capistrano tasks may only be invoked once. Since task `#{task}' was previously invoked, invoke(\"#{task_name}\") at #{file}:#{line} will be skipped."
+        $stderr.puts "If you really meant to run this task again, use invoke!(\"#{task_name}\")"
+        $stderr.puts colors.colorize("THIS BEHAVIOR MAY CHANGE IN A FUTURE VERSION OF CAPISTRANO. Please join the conversation here if this affects you.", :red)
+        $stderr.puts colors.colorize("https://github.com/capistrano/capistrano/issues/1686", :red)
+      end
+      task.invoke(*args)
+    end
+
+    def invoke!(task_name, *args)
+      task = Rake::Task[task_name]
+      task.reenable
+      task.invoke(*args)
+    end
+
+    def t(key, options={})
+      I18n.t(key, **options.merge(scope: :capistrano))
+    end
+
+    def scm
+      fetch(:scm)
+    end
+
+    def sudo(*args)
+      execute :sudo, *args
+    end
+
+    def revision_log_message
+      fetch(:revision_log_message,
+            t(:revision_log_message,
+              branch: fetch(:branch),
+              user: local_user,
+              sha: fetch(:current_revision),
+              release: fetch(:release_timestamp)))
+    end
+
+    def rollback_log_message
+      t(:rollback_log_message, user: local_user, release: fetch(:rollback_timestamp))
+    end
+
+    def local_user
+      fetch(:local_user)
+    end
+
+    def lock(locked_version)
+      VersionValidator.new(locked_version).verify
+    end
+
+    # rubocop:disable Security/MarshalLoad
+    def on(hosts, options={}, &block)
+      subset_copy = Marshal.dump(Configuration.env.filter(hosts))
+      SSHKit::Coordinator.new(Marshal.load(subset_copy)).each(options, &block)
+    end
+    # rubocop:enable Security/MarshalLoad
+
+    def run_locally(&block)
+      SSHKit::Backend::Local.new(&block).run
+    end
+
+    # Catch common beginner mistake and give a helpful error message on stderr
+    def execute(*)
+      file, line, = caller.first.split(":")
+      colors = SSHKit::Color.new($stderr)
+      $stderr.puts colors.colorize("Warning: `execute' should be wrapped in an `on' scope in #{file}:#{line}.", :red)
+      $stderr.puts
+      $stderr.puts "  task :example do"
+      $stderr.puts colors.colorize("    on roles(:app) do", :yellow)
+      $stderr.puts "      execute 'whoami'"
+      $stderr.puts colors.colorize("    end", :yellow)
+      $stderr.puts "  end"
+      $stderr.puts
+      raise NoMethodError, "undefined method `execute' for main:Object"
+    end
+  end
+end
+extend Capistrano::DSL

data/lib/capistrano/framework.rb

@@ -0,0 +1,2 @@
+load File.expand_path("../tasks/framework.rake", __FILE__)
+require "capistrano/install"

data/lib/capistrano/i18n.rb

@@ -0,0 +1,46 @@
+require "i18n"
+
+en = {
+  starting: "Starting",
+  capified: "Capified",
+  start: "Start",
+  update: "Update",
+  finalize: "Finalise",
+  finishing: "Finishing",
+  finished: "Finished",
+  stage_not_set: "Stage not set, please call something such as `cap production deploy`, where production is a stage you have defined.",
+  written_file: "create %{file}",
+  question: "Please enter %{key}: ",
+  question_default: "Please enter %{key} (%{default_value}): ",
+  question_prompt: "%{key}: ",
+  question_prompt_default: "%{key} (%{default_value}): ",
+  keeping_releases: "Keeping %{keep_releases} of %{releases} deployed releases on %{host}",
+  skip_cleanup: "Skipping cleanup of invalid releases on %{host}; unexpected foldername found (should be timestamp)",
+  wont_delete_current_release: "Current release was marked for being removed but it's going to be skipped on %{host}",
+  no_current_release: "There is no current release present on %{host}",
+  no_old_releases: "No old releases (keeping newest %{keep_releases}) on %{host}",
+  linked_file_does_not_exist: "linked file %{file} does not exist on %{host}",
+  cannot_rollback: "There are no older releases to rollback to",
+  cannot_found_rollback_release: "Cannot rollback because release %{release} does not exist",
+  mirror_exists: "The repository mirror is at %{at}",
+  revision_log_message: "Branch %{branch} (at %{sha}) deployed as release %{release} by %{user}",
+  rollback_log_message: "%{user} rolled back to release %{release}",
+  deploy_failed: "The deploy has failed with an error: %{ex}",
+  console: {
+    welcome: "capistrano console - enter command to execute on %{stage}",
+    bye: "bye"
+  },
+  error: {
+    invalid_stage_name: '"%{name}" is a reserved word and cannot be used as a stage. Rename "%{path}" to something else.',
+    user: {
+      does_not_exist: "User %{user} does not exists",
+      cannot_switch: "Cannot switch to user %{user}"
+    }
+  }
+}
+
+I18n.backend.store_translations(:en, capistrano: en)
+
+if I18n.respond_to?(:enforce_available_locales=)
+  I18n.enforce_available_locales = true
+end

data/lib/capistrano/immutable_task.rb

@@ -0,0 +1,30 @@
+module Capistrano
+  # This module extends a Rake::Task to freeze it to prevent it from being
+  # enhanced. This is used to prevent users from enhancing a task at the wrong
+  # point of Capistrano's boot process, which can happen if a Capistrano plugin
+  # is loaded in deploy.rb by mistake (instead of in the Capfile).
+  #
+  # Usage:
+  #
+  # task = Rake.application["load:defaults"]
+  # task.invoke
+  # task.extend(Capistrano::ImmutableTask) # prevent further modifications
+  #
+  module ImmutableTask
+    def self.extended(task)
+      task.freeze
+    end
+
+    def enhance(*args, &block)
+      $stderr.puts <<-MESSAGE
+ERROR: #{name} has already been invoked and can no longer be modified.
+Check that you haven't loaded a Capistrano plugin in deploy.rb or a stage
+(e.g. deploy/production.rb) by mistake.
+Plugins must be loaded in the Capfile to initialize properly.
+MESSAGE
+
+      # This will raise a frozen object error
+      super(*args, &block)
+    end
+  end
+end

data/lib/capistrano/install.rb

@@ -0,0 +1 @@
+load File.expand_path(File.join(File.dirname(__FILE__), "tasks/install.rake"))