capistrano 3.5.0 → 3.6.0

data/lib/capistrano/configuration/validated_variables.rb

@@ -0,0 +1,75 @@
+require "capistrano/proc_helpers"
+require "delegate"
+
+module Capistrano
+  class Configuration
+    # Decorates a Variables object to additionally perform an optional set of
+    # user-supplied validation rules. Each rule for a given key is invoked
+    # immediately whenever `set` is called with a value for that key.
+    #
+    # If `set` is called with a block, validation is not performed immediately.
+    # Instead, the validation rules are invoked the first time `fetch` is used
+    # to access the value.
+    #
+    # A rule is simply a block that accepts two arguments: key and value. It is
+    # up to the rule to raise an exception when it deems the value is invalid
+    # (or just print a warning).
+    #
+    # Rules can be registered using the DSL like this:
+    #
+    #   validate(:my_key) do |key, value|
+    #     # rule goes here
+    #   end
+    #
+    class ValidatedVariables < SimpleDelegator
+      include Capistrano::ProcHelpers
+
+      def initialize(variables)
+        super(variables)
+        @validators = {}
+      end
+
+      # Decorate Variables#set to add validation behavior.
+      def set(key, value=nil, &block)
+        if value.nil? && callable_without_parameters?(block)
+          super(key, nil, &assert_valid_later(key, &block))
+        else
+          assert_valid_now(key, block || value)
+          super
+        end
+      end
+
+      # Register a validation rule for the given key.
+      def validate(key, &validator)
+        vs = (validators[key] || [])
+        vs << validator
+        validators[key] = vs
+      end
+
+      private
+
+      attr_reader :validators
+
+      # Wrap a block with a proc that validates the value of the block. This
+      # allows us to defer validation until the time the value is requested.
+      def assert_valid_later(key)
+        lambda do
+          value = yield
+          assert_valid_now(key, value)
+          value
+        end
+      end
+
+      # Runs all validation rules registered for the given key against the
+      # user-supplied value for that variable. If no validator raises an
+      # exception, the value is assumed to be valid.
+      def assert_valid_now(key, value)
+        return unless validators.key?(key)
+
+        validators[key].each do |validator|
+          validator.call(key, value)
+        end
+      end
+    end
+  end
+end

data/lib/capistrano/configuration/variables.rb

@@ -1,9 +1,11 @@
+require "capistrano/proc_helpers"
+
 module Capistrano
   class Configuration
     # Holds the variables assigned at Capistrano runtime via `set` and retrieved
     # with `fetch`. Does internal bookkeeping to help identify user mistakes
     # like spelling errors or unused variables that may lead to unexpected
-    # behavior. Also allows validation rules to be registered with `validate`.
+    # behavior.
     class Variables
       CAPISTRANO_LOCATION = File.expand_path("../..", __FILE__).freeze
       IGNORED_LOCATIONS = [
@@ -15,6 +17,8 @@ module Capistrano
       ].freeze
       private_constant :CAPISTRANO_LOCATION, :IGNORED_LOCATIONS
 
+      include Capistrano::ProcHelpers
+
       def initialize(values={})
         @trusted_keys = []
         @fetched_keys = []
@@ -31,7 +35,7 @@ module Capistrano
       end
 
       def set(key, value=nil, &block)
-        invoke_validations(key, value, &block)
+        assert_value_or_block_not_both(value, block)
         @trusted_keys << key if trusted?
         remember_location(key)
         values[key] = block || value
@@ -61,12 +65,6 @@ module Capistrano
         values.delete(key)
       end
 
-      def validate(key, &validator)
-        vs = (validators[key] || [])
-        vs << validator
-        validators[key] = vs
-      end
-
       def trusted_keys
         @trusted_keys.dup
       end
@@ -106,25 +104,11 @@ module Capistrano
         (locations[key] ||= []) << location
       end
 
-      def callable_without_parameters?(x)
-        x.respond_to?(:call) && (!x.respond_to?(:arity) || x.arity == 0)
-      end
-
-      def validators
-        @validators ||= {}
-      end
-
-      def invoke_validations(key, value, &block)
+      def assert_value_or_block_not_both(value, block)
         unless value.nil? || block.nil?
           raise Capistrano::ValidationError,
                 "Value and block both passed to Configuration#set"
         end
-
-        return unless validators.key? key
-
-        validators[key].each do |validator|
-          validator.call(key, block || value)
-        end
       end
 
       def trace_set(key)

data/lib/capistrano/defaults.rb

@@ -8,6 +8,16 @@ validate :application do |_key, value|
   end
 end
 
+[:git_strategy, :hg_strategy, :svn_strategy].each do |strategy|
+  validate(strategy) do |key, _value|
+    warn(
+      "[Deprecation Warning] #{key} is deprecated and will be removed in "\
+      "Capistrano 3.7.0.\n"\
+      "https://github.com/capistrano/capistrano/blob/master/UPGRADING-3.7.md"
+    )
+  end
+end
+
 set_if_empty :scm, :git
 set_if_empty :branch, "master"
 set_if_empty :deploy_to, -> { "/var/www/#{fetch(:application)}" }

data/lib/capistrano/doctor.rb

@@ -1,5 +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/doctor/gems_doctor.rb

@@ -34,7 +34,7 @@ module Capistrano
       end
 
       def core_gem_names
-        %w(capistrano airbrussh rake sshkit) & Gem.loaded_specs.keys
+        %w(capistrano airbrussh rake sshkit net-ssh) & Gem.loaded_specs.keys
       end
 
       def plugin_gem_names

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).map(&:to_a).flatten.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

@@ -7,7 +7,7 @@ module Capistrano
     class VariablesDoctor
       # These are keys that have no default values in Capistrano, but are
       # nonetheless expected to be set.
-      WHITELIST = [:application, :repo_url].freeze
+      WHITELIST = [:application, :repo_url, :git_strategy, :hg_strategy, :svn_strategy].freeze
       private_constant :WHITELIST
 
       include Capistrano::Doctor::OutputHelpers
@@ -20,18 +20,17 @@ module Capistrano
         title("Variables")
         values = inspect_all_values
 
-        table(variables.keys.sort) do |key, row|
+        table(variables.keys.sort_by(&:to_s)) do |key, row|
           row.yellow if suspicious_keys.include?(key)
-          row << ":#{key}"
+          row << key.inspect
           row << values[key]
         end
 
         puts if suspicious_keys.any?
 
-        suspicious_keys.sort.each do |key|
-          warning(
-            ":#{key} is not a recognized Capistrano setting (#{location(key)})"
-          )
+        suspicious_keys.sort_by(&:to_s).each do |key|
+          warning("#{key.inspect} is not a recognized Capistrano setting "\
+                  "(#{location(key)})")
         end
       end
 

data/lib/capistrano/dsl.rb

@@ -11,8 +11,18 @@ module Capistrano
     include Paths
     include Stages
 
-    def invoke(task, *args)
-      Rake::Task[task].invoke(*args)
+    def invoke(task_name, *args)
+      task = Rake::Task[task_name]
+      if task && task.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, first call Rake::Task[\"#{task_name}\"].reenable"
+        $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 t(key, options={})
@@ -33,8 +43,7 @@ module Capistrano
               branch: fetch(:branch),
               user: local_user,
               sha: fetch(:current_revision),
-              release: fetch(:release_timestamp))
-           )
+              release: fetch(:release_timestamp)))
     end
 
     def rollback_log_message
@@ -57,6 +66,21 @@ module Capistrano
     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/dsl/paths.rb

@@ -11,7 +11,7 @@ module Capistrano
       end
 
       def current_path
-        deploy_path.join("current")
+        deploy_path.join(fetch(:current_directory, "current"))
       end
 
       def releases_path

data/lib/capistrano/dsl/stages.rb

@@ -1,8 +1,13 @@
 module Capistrano
   module DSL
     module Stages
+      RESERVED_NAMES = %w(deploy doctor install).freeze
+      private_constant :RESERVED_NAMES
+
       def stages
-        Dir[stage_definitions].map { |f| File.basename(f, ".rb") }
+        names = Dir[stage_definitions].map { |f| File.basename(f, ".rb") }
+        assert_valid_stage_names(names)
+        names
       end
 
       def stage_definitions
@@ -12,6 +17,15 @@ module Capistrano
       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

@@ -11,11 +11,16 @@ module Capistrano
       Rake::Task.define_task(post_task, *args, &block) if block_given?
       task = Rake::Task[task]
       task.enhance do
-        Rake.application.lookup(post_task, task.scope).invoke
+        post = Rake.application.lookup(post_task, task.scope)
+        raise ArgumentError, "Task #{post_task.inspect} not found" unless post
+        post.invoke
       end
     end
 
     def remote_file(task)
+      warn("[Deprecation Warning] `remote_file` is deprecated and will be "\
+           "removed in Capistrano 3.7.0")
+
       target_roles = task.delete(:roles) { :all }
       define_remote_file_task(task, target_roles)
     end

data/lib/capistrano/i18n.rb

@@ -15,6 +15,7 @@ en = {
   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}",
@@ -24,6 +25,7 @@ en = {
     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}"