capistrano 3.4.0 → 3.17.1

data/lib/capistrano/configuration/server.rb

@@ -1,4 +1,4 @@
-require 'set'
+require "set"
 module Capistrano
   class Configuration
     class Server < SSHKit::Host
@@ -25,19 +25,21 @@ module Capistrano
       end
 
       def select?(options)
-        options.each do |k,v|
-          callable = v.respond_to?(:call) ? v: ->(server){server.fetch(v)}
-          result = case k
-          when :filter, :select
-            callable.call(self)
-          when :exclude
-            !callable.call(self)
-          else
-            self.fetch(k) == v
-          end
+        options.each do |k, v|
+          callable = v.respond_to?(:call) ? v : ->(server) { server.fetch(v) }
+          result = \
+            case k
+            when :filter, :select
+              callable.call(self)
+            when :exclude
+              !callable.call(self)
+            else
+              fetch(k) == v
+            end
           return false unless result
         end
-        return true
+
+        true
       end
 
       def primary
@@ -54,7 +56,7 @@ module Capistrano
       end
 
       def netssh_options
-        @netssh_options ||= super.merge( fetch(:ssh_options) || {} )
+        @netssh_options ||= super.merge(fetch(:ssh_options) || {})
       end
 
       def roles_array
@@ -62,7 +64,8 @@ module Capistrano
       end
 
       def matches?(other)
-        hostname == other.hostname
+        # This matching logic must stay in sync with `Servers#add_host`.
+        hostname == other.hostname && port == other.port
       end
 
       private
@@ -76,18 +79,17 @@ module Capistrano
       end
 
       class Properties
-
         def initialize
           @properties = {}
         end
 
         def set(key, value)
           pval = @properties[key]
-          if pval.is_a? Hash and value.is_a? Hash
+          if pval.is_a?(Hash) && value.is_a?(Hash)
             pval.merge!(value)
-          elsif pval.is_a? Set and value.is_a? Set
+          elsif pval.is_a?(Set) && value.is_a?(Set)
             pval.merge(value)
-          elsif pval.is_a? Array and value.is_a? Array
+          elsif pval.is_a?(Array) && value.is_a?(Array)
             pval.concat value
           else
             @properties[key] = value
@@ -98,8 +100,8 @@ module Capistrano
           @properties[key]
         end
 
-        def respond_to?(method, include_all=false)
-          @properties.has_key?(method)
+        def respond_to_missing?(method, _include_all=false)
+          @properties.key?(method) || super
         end
 
         def roles
@@ -110,6 +112,7 @@ module Capistrano
           @properties.keys
         end
 
+        # rubocop:disable Style/MethodMissing
         def method_missing(key, value=nil)
           if value
             set(lvalue(key), value)
@@ -117,15 +120,18 @@ module Capistrano
             fetch(key)
           end
         end
+        # rubocop:enable Style/MethodMissing
+
+        def to_h
+          @properties
+        end
 
         private
 
         def lvalue(key)
-          key.to_s.chomp('=').to_sym
+          key.to_s.chomp("=").to_sym
         end
-
       end
-
     end
   end
 end

data/lib/capistrano/configuration/servers.rb

@@ -1,6 +1,6 @@
-require 'set'
-require 'capistrano/configuration'
-require 'capistrano/configuration/filter'
+require "set"
+require "capistrano/configuration"
+require "capistrano/configuration/filter"
 
 module Capistrano
   class Configuration
@@ -9,23 +9,28 @@ module Capistrano
 
       def add_host(host, properties={})
         new_host = Server[host]
-        if server = servers.find { |s| s.matches? new_host }
-          server.user = new_host.user if new_host.user
-          server.port = new_host.port if new_host.port
-          server.with(properties)
+        new_host.port = properties[:port] if properties.key?(:port)
+        # This matching logic must stay in sync with `Server#matches?`.
+        key = ServerKey.new(new_host.hostname, new_host.port)
+        existing = servers_by_key[key]
+        if existing
+          existing.user = new_host.user if new_host.user
+          existing.with(properties)
         else
-          servers << new_host.with(properties)
+          servers_by_key[key] = new_host.with(properties)
         end
       end
 
+      # rubocop:disable Security/MarshalLoad
       def add_role(role, hosts, options={})
         options_deepcopy = Marshal.dump(options.merge(roles: role))
         Array(hosts).each { |host| add_host(host, Marshal.load(options_deepcopy)) }
       end
+      # rubocop:enable Security/MarshalLoad
 
       def roles_for(names)
         options = extract_options(names)
-        s = Filter.new(:role, names).filter(servers)
+        s = Filter.new(:role, names).filter(servers_by_key.values)
         s.select { |server| server.select?(options) }
       end
 
@@ -38,12 +43,12 @@ module Capistrano
               if block_given?
                 yield host, role, props
               else
-                rps << (props || {}).merge( role: role, hostname: host.hostname )
+                rps << (props || {}).merge(role: role, hostname: host.hostname)
               end
             end
           end
         end
-        block_given? ? nil: rps
+        block_given? ? nil : rps
       end
 
       def fetch_primary(role)
@@ -52,13 +57,15 @@ module Capistrano
       end
 
       def each
-        servers.each { |server| yield server }
+        servers_by_key.values.each { |server| yield server }
       end
 
       private
 
-      def servers
-        @servers ||= []
+      ServerKey = Struct.new(:hostname, :port)
+
+      def servers_by_key
+        @servers_by_key ||= {}
       end
 
       def extract_options(array)

data/lib/capistrano/configuration/validated_variables.rb

@@ -0,0 +1,110 @@
+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 callable value or 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)
+        assert_value_or_block_not_both(value, block)
+
+        # Skip validation behavior if no validators are registered for this key
+        return super unless validators.key?(key)
+
+        value_to_evaluate = block || value
+
+        if callable_without_parameters?(value_to_evaluate)
+          super(key, assert_valid_later(key, value_to_evaluate), &nil)
+        else
+          assert_valid_now(key, value_to_evaluate)
+          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
+
+      # Given a callable that provides a value, wrap the callable with another
+      # object that responds to `call`. This new object will perform validation
+      # and then return the original callable's value.
+      #
+      # If the callable is a `Question`, the object returned by this method will
+      # also be a `Question` (a `ValidatedQuestion`, to be precise). This
+      # ensures that `is_a?(Question)` remains true even after the validation
+      # wrapper is applied. This is needed so that `Configuration#is_question?`
+      # works as expected.
+      #
+      def assert_valid_later(key, callable)
+        validation_callback = lambda do
+          value = callable.call
+          assert_valid_now(key, value)
+          value
+        end
+
+        if callable.is_a?(Question)
+          ValidatedQuestion.new(validation_callback)
+        else
+          validation_callback
+        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)
+        validators[key].each do |validator|
+          validator.call(key, value)
+        end
+      end
+
+      def assert_value_or_block_not_both(value, block)
+        return if value.nil? || block.nil?
+        raise Capistrano::ValidationError,
+              "Value and block both passed to Configuration#set"
+      end
+
+      class ValidatedQuestion < Question
+        def initialize(validator)
+          @validator = validator
+        end
+
+        def call
+          @validator.call
+        end
+      end
+    end
+  end
+end

data/lib/capistrano/configuration/variables.rb

@@ -0,0 +1,112 @@
+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.
+    class Variables
+      CAPISTRANO_LOCATION = File.expand_path("../..", __FILE__).freeze
+      IGNORED_LOCATIONS = [
+        "#{CAPISTRANO_LOCATION}/configuration/variables.rb:",
+        "#{CAPISTRANO_LOCATION}/configuration.rb:",
+        "#{CAPISTRANO_LOCATION}/dsl/env.rb:",
+        "/dsl.rb:",
+        "/forwardable.rb:"
+      ].freeze
+      private_constant :CAPISTRANO_LOCATION, :IGNORED_LOCATIONS
+
+      include Capistrano::ProcHelpers
+
+      def initialize(values={})
+        @trusted_keys = []
+        @fetched_keys = []
+        @locations = {}
+        @values = values
+        @trusted = true
+      end
+
+      def untrusted!
+        @trusted = false
+        yield
+      ensure
+        @trusted = true
+      end
+
+      def set(key, value=nil, &block)
+        @trusted_keys << key if trusted? && !@trusted_keys.include?(key)
+        remember_location(key)
+        values[key] = block || value
+        trace_set(key)
+        values[key]
+      end
+
+      def fetch(key, default=nil, &block)
+        fetched_keys << key unless fetched_keys.include?(key)
+        peek(key, default, &block)
+      end
+
+      # Internal use only.
+      def peek(key, default=nil, &block)
+        value = fetch_for(key, default, &block)
+        while callable_without_parameters?(value)
+          value = (values[key] = value.call)
+        end
+        value
+      end
+
+      def fetch_for(key, default, &block)
+        block ? values.fetch(key, &block) : values.fetch(key, default)
+      end
+
+      def delete(key)
+        values.delete(key)
+      end
+
+      def trusted_keys
+        @trusted_keys.dup
+      end
+
+      def untrusted_keys
+        keys - @trusted_keys
+      end
+
+      def keys
+        values.keys
+      end
+
+      # Keys that have been set, but which have never been fetched.
+      def unused_keys
+        keys - fetched_keys
+      end
+
+      # Returns an array of source file location(s) where the given key was
+      # assigned (i.e. where `set` was called). If the key was never assigned,
+      # returns `nil`.
+      def source_locations(key)
+        locations[key]
+      end
+
+      private
+
+      attr_reader :locations, :values, :fetched_keys
+
+      def trusted?
+        @trusted
+      end
+
+      def remember_location(key)
+        location = caller.find do |line|
+          IGNORED_LOCATIONS.none? { |i| line.include?(i) }
+        end
+        (locations[key] ||= []) << location
+      end
+
+      def trace_set(key)
+        return unless fetch(:print_config_variables, false)
+        puts "Config variable set: #{key.inspect} => #{values[key].inspect}"
+      end
+    end
+  end
+end

data/lib/capistrano/configuration.rb

@@ -1,15 +1,15 @@
-require_relative 'configuration/filter'
-require_relative 'configuration/question'
-require_relative 'configuration/server'
-require_relative 'configuration/servers'
+require_relative "configuration/filter"
+require_relative "configuration/question"
+require_relative "configuration/plugin_installer"
+require_relative "configuration/server"
+require_relative "configuration/servers"
+require_relative "configuration/validated_variables"
+require_relative "configuration/variables"
 
 module Capistrano
-  class Configuration
-
-    def initialize(config = nil)
-      @config ||= config
-    end
+  class ValidationError < RuntimeError; end
 
+  class Configuration
     def self.env
       @env ||= new
     end
@@ -18,38 +18,53 @@ module Capistrano
       @env = new
     end
 
+    extend Forwardable
+    attr_reader :variables
+    def_delegators :variables,
+                   :set, :fetch, :fetch_for, :delete, :keys, :validate
+
+    def initialize(values={})
+      @variables = ValidatedVariables.new(Variables.new(values))
+    end
+
     def ask(key, default=nil, options={})
       question = Question.new(key, default, options)
       set(key, question)
     end
 
-    def set(key, value)
-      config[key] = value
+    def set_if_empty(key, value=nil, &block)
+      set(key, value, &block) unless keys.include?(key)
     end
 
-    def set_if_empty(key, value)
-      config[key] = value unless config.has_key? key
+    def append(key, *values)
+      set(key, Array(fetch(key)).concat(values))
     end
 
-    def delete(key)
-      config.delete(key)
+    def remove(key, *values)
+      set(key, Array(fetch(key)) - values)
     end
 
-    def fetch(key, default=nil, &block)
-      value = fetch_for(key, default, &block)
-      while callable_without_parameters?(value)
-        value = set(key, value.call)
+    def any?(key)
+      value = fetch(key)
+      if value && value.respond_to?(:any?)
+        begin
+          return value.any?
+        rescue ArgumentError # rubocop:disable Lint/HandleExceptions
+          # Gracefully ignore values whose `any?` method doesn't accept 0 args
+        end
       end
-      return value
+
+      !value.nil?
     end
 
-    def keys
-      config.keys
+    def is_question?(key)
+      value = fetch_for(key, nil)
+      !value.nil? && value.is_a?(Question)
     end
 
     def role(name, hosts, options={})
       if name == :all
-        raise ArgumentError.new("#{name} reserved name for role. Please choose another name")
+        raise ArgumentError, "#{name} reserved name for role. Please choose another name"
       end
 
       servers.add_role(name, hosts, options)
@@ -79,27 +94,50 @@ module Capistrano
 
     def configure_backend
       backend.configure do |sshkit|
-        sshkit.format           = fetch(:format)
+        configure_sshkit_output(sshkit)
         sshkit.output_verbosity = fetch(:log_level)
         sshkit.default_env      = fetch(:default_env)
         sshkit.backend          = fetch(:sshkit_backend, SSHKit::Backend::Netssh)
         sshkit.backend.configure do |backend|
           backend.pty                = fetch(:pty)
           backend.connection_timeout = fetch(:connection_timeout)
-          backend.ssh_options        = (backend.ssh_options || {}).merge(fetch(:ssh_options,{}))
+          backend.ssh_options        = (backend.ssh_options || {}).merge(fetch(:ssh_options, {}))
         end
       end
     end
 
+    def configure_scm
+      Capistrano::Configuration::SCMResolver.new.resolve
+    end
+
     def timestamp
       @timestamp ||= Time.now.utc
     end
 
+    def add_filter(filter=nil, &block)
+      if block
+        raise ArgumentError, "Both a block and an object were given" if filter
+
+        filter = Object.new
+        def filter.filter(servers)
+          block.call(servers)
+        end
+      elsif !filter.respond_to? :filter
+        raise TypeError, "Provided custom filter <#{filter.inspect}> does " \
+                         "not have a public 'filter' method"
+      end
+      @custom_filters ||= []
+      @custom_filters << filter
+    end
+
     def setup_filters
-      @filters = cmdline_filters.clone
-      @filters << Filter.new(:role, ENV['ROLES']) if ENV['ROLES']
-      @filters << Filter.new(:host, ENV['HOSTS']) if ENV['HOSTS']
-      fh = fetch_for(:filter,{})
+      @filters = cmdline_filters
+      @filters += @custom_filters if @custom_filters
+      @filters << Filter.new(:role, ENV["ROLES"]) if ENV["ROLES"]
+      @filters << Filter.new(:host, ENV["HOSTS"]) if ENV["HOSTS"]
+      fh = fetch_for(:filter, {}) || {}
+      @filters << Filter.new(:host, fh[:hosts]) if fh[:hosts]
+      @filters << Filter.new(:role, fh[:roles]) if fh[:roles]
       @filters << Filter.new(:host, fh[:host]) if fh[:host]
       @filters << Filter.new(:role, fh[:role]) if fh[:role]
     end
@@ -108,35 +146,44 @@ module Capistrano
       cmdline_filters << Filter.new(type, values)
     end
 
-    def filter list
+    def filter(list)
       setup_filters if @filters.nil?
-      @filters.reduce(list) { |l,f| f.filter l }
+      @filters.reduce(list) { |l, f| f.filter l }
     end
 
-    private
+    def dry_run?
+      fetch(:sshkit_backend) == SSHKit::Backend::Printer
+    end
 
-    def cmdline_filters
-      @cmdline_filters ||= []
+    def install_plugin(plugin, load_hooks: true, load_immediately: false)
+      installer.install(plugin,
+                        load_hooks: load_hooks,
+                        load_immediately: load_immediately)
+    end
+
+    def scm_plugin_installed?
+      installer.scm_installed?
     end
 
     def servers
       @servers ||= Servers.new
     end
 
-    def config
-      @config ||= Hash.new
+    private
+
+    def cmdline_filters
+      @cmdline_filters ||= []
     end
 
-    def fetch_for(key, default, &block)
-      if block_given?
-        config.fetch(key, &block)
-      else
-        config.fetch(key, default)
-      end
+    def installer
+      @installer ||= PluginInstaller.new
     end
 
-    def callable_without_parameters?(x)
-      x.respond_to?(:call) && ( !x.respond_to?(:arity) || x.arity == 0)
+    def configure_sshkit_output(sshkit)
+      format_args = [fetch(:format)]
+      format_args.push(fetch(:format_options)) if any?(:format_options)
+
+      sshkit.use_format(*format_args)
     end
   end
 end

data/lib/capistrano/defaults.rb

@@ -1,14 +1,36 @@
-set_if_empty :scm, :git
-set_if_empty :branch, :master
+validate :application do |_key, value|
+  changed_value = value.gsub(/[^A-Z0-9\.\-]/i, "_")
+  if value != changed_value
+    warn %Q(The :application value "#{value}" is invalid!)
+    warn "Use only letters, numbers, hyphens, dots, and underscores. For example:"
+    warn "  set :application, '#{changed_value}'"
+    raise Capistrano::ValidationError
+  end
+end
+
+%i(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
+
+# We use a special :_default_git value so that SCMResolver can tell whether the
+# default has been replaced by the user via `set`.
+set_if_empty :scm, Capistrano::Configuration::SCMResolver::DEFAULT_GIT
+set_if_empty :branch, "master"
 set_if_empty :deploy_to, -> { "/var/www/#{fetch(:application)}" }
 set_if_empty :tmp_dir, "/tmp"
 
 set_if_empty :default_env, {}
 set_if_empty :keep_releases, 5
 
-set_if_empty :format, :pretty
+set_if_empty :format, :airbrussh
 set_if_empty :log_level, :debug
 
 set_if_empty :pty, false
 
-set_if_empty :local_user, -> { Etc.getlogin }
+set_if_empty :local_user, -> { ENV["USER"] || ENV["LOGNAME"] || ENV["USERNAME"] }

data/lib/capistrano/deploy.rb

@@ -1,3 +1,3 @@
-require 'capistrano/framework'
+require "capistrano/framework"
 
 load File.expand_path("../tasks/deploy.rake", __FILE__)