capistrano 2.8.0 → 3.19.0

data/lib/capistrano/configuration/filter.rb

@@ -0,0 +1,26 @@
+require "capistrano/configuration"
+require "capistrano/configuration/empty_filter"
+require "capistrano/configuration/host_filter"
+require "capistrano/configuration/null_filter"
+require "capistrano/configuration/role_filter"
+
+module Capistrano
+  class Configuration
+    class Filter
+      def initialize(type, values=nil)
+        raise "Invalid filter type #{type}" unless %i(host role).include? type
+        av = Array(values)
+        @strategy = if av.empty? then EmptyFilter.new
+                    elsif av.include?(:all) || av.include?("all") then NullFilter.new
+                    elsif type == :host then HostFilter.new(values)
+                    elsif type == :role then RoleFilter.new(values)
+                    else NullFilter.new
+                    end
+      end
+
+      def filter(servers)
+        @strategy.filter servers
+      end
+    end
+  end
+end

data/lib/capistrano/configuration/host_filter.rb

@@ -0,0 +1,29 @@
+module Capistrano
+  class Configuration
+    class HostFilter
+      def initialize(values)
+        av = Array(values).dup
+        av = av.flat_map { |v| v.is_a?(String) && v =~ /^(?<name>[-A-Za-z0-9.]+)(,\g<name>)*$/ ? v.split(",") : v }
+        @rex = regex_matcher(av)
+      end
+
+      def filter(servers)
+        Array(servers).select { |s| @rex.match s.to_s }
+      end
+
+      private
+
+      def regex_matcher(values)
+        values.map! do |v|
+          case v
+          when Regexp then v
+          else
+            vs = v.to_s
+            vs =~ /^[-A-Za-z0-9.]+$/ ? /^#{Regexp.quote(vs)}$/ : Regexp.new(vs)
+          end
+        end
+        Regexp.union values
+      end
+    end
+  end
+end

data/lib/capistrano/configuration/null_filter.rb

@@ -0,0 +1,9 @@
+module Capistrano
+  class Configuration
+    class NullFilter
+      def filter(servers)
+        servers
+      end
+    end
+  end
+end

data/lib/capistrano/configuration/plugin_installer.rb

@@ -0,0 +1,51 @@
+# Encapsulates the logic for installing plugins into Capistrano. Plugins must
+# simply conform to a basic API; the PluginInstaller takes care of invoking the
+# API at appropriate times.
+#
+# This class is not used directly; instead it is typically accessed via the
+# `install_plugin` method of the Capistrano DSL.
+#
+module Capistrano
+  class Configuration
+    class PluginInstaller
+      # "Installs" a Plugin into Capistrano by loading its tasks, hooks, and
+      # defaults at the appropriate time. The hooks in particular can be
+      # skipped, if you want full control over when and how the plugin's tasks
+      # are executed. Simply pass `load_hooks:false` to opt out.
+      #
+      # The plugin class or instance may be provided. These are equivalent:
+      #
+      # install(Capistrano::SCM::Git)
+      # install(Capistrano::SCM::Git.new)
+      #
+      # Note that the :load_immediately flag is for internal use only and will
+      # be removed in an upcoming release.
+      #
+      def install(plugin, load_hooks: true, load_immediately: false)
+        plugin = plugin.is_a?(Class) ? plugin.new : plugin
+
+        plugin.define_tasks
+        plugin.register_hooks if load_hooks
+        @scm_installed ||= provides_scm?(plugin)
+
+        if load_immediately
+          plugin.set_defaults
+        else
+          Rake::Task.define_task("load:defaults") do
+            plugin.set_defaults
+          end
+        end
+      end
+
+      def scm_installed?
+        @scm_installed
+      end
+
+      private
+
+      def provides_scm?(plugin)
+        plugin.respond_to?(:scm?) && plugin.scm?
+      end
+    end
+  end
+end

data/lib/capistrano/configuration/question.rb

@@ -0,0 +1,76 @@
+module Capistrano
+  class Configuration
+    class Question
+      def initialize(key, default, options={})
+        @key = key
+        @default = default
+        @options = options
+      end
+
+      def call
+        ask_question
+        value_or_default
+      end
+
+      private
+
+      attr_reader :key, :default, :options
+
+      def ask_question
+        $stdout.print question
+        $stdout.flush
+      end
+
+      def value_or_default
+        if response.empty?
+          default
+        else
+          response
+        end
+      end
+
+      def response
+        return @response if defined? @response
+
+        @response = (gets || "").chomp
+      end
+
+      def gets
+        return unless stdin.tty?
+
+        if echo?
+          stdin.gets
+        else
+          stdin.noecho(&:gets).tap { $stdout.print "\n" }
+        end
+      rescue Errno::EIO
+        # when stdio gets closed
+        return
+      end
+
+      def question
+        if prompt && default.nil?
+          I18n.t(:question_prompt, key: prompt, scope: :capistrano)
+        elsif prompt
+          I18n.t(:question_prompt_default, key: prompt, default_value: default, scope: :capistrano)
+        elsif default.nil?
+          I18n.t(:question, key: key, scope: :capistrano)
+        else
+          I18n.t(:question_default, key: key, default_value: default, scope: :capistrano)
+        end
+      end
+
+      def echo?
+        (options || {}).fetch(:echo, true)
+      end
+
+      def stdin
+        (options || {}).fetch(:stdin, $stdin)
+      end
+
+      def prompt
+        (options || {}).fetch(:prompt, nil)
+      end
+    end
+  end
+end

data/lib/capistrano/configuration/role_filter.rb

@@ -0,0 +1,29 @@
+module Capistrano
+  class Configuration
+    class RoleFilter
+      def initialize(values)
+        av = Array(values).dup
+        av = av.flat_map { |v| v.is_a?(String) ? v.split(",") : v }
+        @rex = regex_matcher(av)
+      end
+
+      def filter(servers)
+        Array(servers).select { |s| s.is_a?(String) ? false : s.roles.any? { |r| @rex.match r } }
+      end
+
+      private
+
+      def regex_matcher(values)
+        values.map! do |v|
+          case v
+          when Regexp then v
+          else
+            vs = v.to_s
+            vs =~ %r{^/(.+)/$} ? Regexp.new($1) : /^#{Regexp.quote(vs)}$/
+          end
+        end
+        Regexp.union values
+      end
+    end
+  end
+end

data/lib/capistrano/configuration/scm_resolver.rb

@@ -0,0 +1,149 @@
+module Capistrano
+  class Configuration
+    # In earlier versions of Capistrano, users would specify the desired SCM
+    # implementation using `set :scm, :git`, for example. Capistrano would then
+    # load the matching .rb file based on this variable.
+    #
+    # Now we expect users to explicitly `require` and call `new` on the desired
+    # SCM implementation in their Capfile. The `set` technique is deprecated.
+    #
+    # This SCMResolver class takes care of managing the transition from the old
+    # to new system. It maintains the legacy behavior, but prints deprecation
+    # warnings when it is used.
+    #
+    # To maintain backwards compatibility, the resolver will load the Git SCM by
+    # if default it determines that no SCM has been explicitly specified or
+    # loaded. To force no SCM to be used at all, use `set :scm, nil`. This hack
+    # won't be necessary once backwards compatibility is removed in a future
+    # version.
+    #
+    # TODO: Remove this class entirely in Capistrano 4.0.
+    #
+    class SCMResolver
+      DEFAULT_GIT = :"default-git"
+
+      include Capistrano::DSL
+
+      def resolve
+        return if scm_name.nil?
+        set(:scm, :git) if using_default_scm?
+
+        print_deprecation_warnings_if_applicable
+
+        # Note that `scm_plugin_installed?` comes from Capistrano::DSL
+        if scm_plugin_installed?
+          delete(:scm)
+          return
+        end
+
+        if built_in_scm_name?
+          load_built_in_scm
+        else
+          # Compatibility with existing 3.x third-party SCMs
+          register_legacy_scm_hooks
+          load_legacy_scm_by_name
+        end
+      end
+
+      private
+
+      def using_default_scm?
+        return @using_default_scm if defined? @using_default_scm
+        @using_default_scm = (fetch(:scm) == DEFAULT_GIT)
+      end
+
+      def scm_name
+        fetch(:scm)
+      end
+
+      def load_built_in_scm
+        require "capistrano/scm/#{scm_name}"
+        scm_class = Object.const_get(built_in_scm_plugin_class_name)
+        # We use :load_immediately because we are initializing the SCM plugin
+        # late in the load process and therefore can't use the standard
+        # load:defaults technique.
+        install_plugin(scm_class, load_immediately: true)
+      end
+
+      def load_legacy_scm_by_name
+        load("capistrano/#{scm_name}.rb")
+      end
+
+      def third_party_scm_name?
+        !built_in_scm_name?
+      end
+
+      def built_in_scm_name?
+        %w(git hg svn).include?(scm_name.to_s.downcase)
+      end
+
+      def built_in_scm_plugin_class_name
+        "Capistrano::SCM::#{scm_name.to_s.capitalize}"
+      end
+
+      # rubocop:disable Style/GuardClause
+      def register_legacy_scm_hooks
+        if Rake::Task.task_defined?("deploy:new_release_path")
+          after "deploy:new_release_path", "#{scm_name}:create_release"
+        end
+
+        if Rake::Task.task_defined?("deploy:check")
+          before "deploy:check", "#{scm_name}:check"
+        end
+
+        if Rake::Task.task_defined?("deploy:set_current_revision")
+          before "deploy:set_current_revision",
+                 "#{scm_name}:set_current_revision"
+        end
+      end
+      # rubocop:enable Style/GuardClause
+
+      def print_deprecation_warnings_if_applicable
+        if using_default_scm?
+          warn_add_git_to_capfile unless scm_plugin_installed?
+        elsif built_in_scm_name?
+          warn_set_scm_is_deprecated
+        elsif third_party_scm_name?
+          warn_third_party_scm_must_be_upgraded
+        end
+      end
+
+      def warn_set_scm_is_deprecated
+        $stderr.puts(<<-MESSAGE)
+[Deprecation Notice] `set :scm, #{scm_name.inspect}` is deprecated.
+To ensure your project is compatible with future versions of Capistrano,
+remove the :scm setting and instead add these lines to your Capfile after
+`require "capistrano/deploy"`:
+
+    require "capistrano/scm/#{scm_name}"
+    install_plugin #{built_in_scm_plugin_class_name}
+
+MESSAGE
+      end
+
+      def warn_add_git_to_capfile
+        $stderr.puts(<<-MESSAGE)
+[Deprecation Notice] Future versions of Capistrano will not load the Git SCM
+plugin by default. To silence this deprecation warning, add the following to
+your Capfile after `require "capistrano/deploy"`:
+
+    require "capistrano/scm/git"
+    install_plugin Capistrano::SCM::Git
+
+MESSAGE
+      end
+
+      def warn_third_party_scm_must_be_upgraded
+        $stderr.puts(<<-MESSAGE)
+[Deprecation Notice] `set :scm, #{scm_name.inspect}` is deprecated.
+To ensure this custom SCM will work with future versions of Capistrano,
+please upgrade it to a version that uses the new SCM plugin mechanism
+documented here:
+
+http://capistranorb.com/documentation/advanced-features/custom-scm
+
+MESSAGE
+      end
+    end
+  end
+end

data/lib/capistrano/configuration/server.rb

@@ -0,0 +1,137 @@
+require "set"
+module Capistrano
+  class Configuration
+    class Server < SSHKit::Host
+      extend Forwardable
+      def_delegators :properties, :roles, :fetch, :set
+
+      def self.[](host)
+        host.is_a?(Server) ? host : new(host)
+      end
+
+      def add_roles(roles)
+        Array(roles).each { |role| add_role(role) }
+        self
+      end
+      alias roles= add_roles
+
+      def add_role(role)
+        roles.add role.to_sym
+        self
+      end
+
+      def has_role?(role)
+        roles.include? role.to_sym
+      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
+              fetch(k) == v
+            end
+          return false unless result
+        end
+
+        true
+      end
+
+      def primary
+        self if fetch(:primary)
+      end
+
+      def with(properties)
+        properties.each { |key, value| add_property(key, value) }
+        self
+      end
+
+      def properties
+        @properties ||= Properties.new
+      end
+
+      def netssh_options
+        @netssh_options ||= super.merge(fetch(:ssh_options) || {})
+      end
+
+      def roles_array
+        roles.to_a
+      end
+
+      def matches?(other)
+        # This matching logic must stay in sync with `Servers#add_host`.
+        hostname == other.hostname && port == other.port
+      end
+
+      private
+
+      def add_property(key, value)
+        if respond_to?("#{key}=")
+          send("#{key}=", value)
+        else
+          set(key, value)
+        end
+      end
+
+      class Properties
+        def initialize
+          @properties = {}
+        end
+
+        def set(key, value)
+          pval = @properties[key]
+          if pval.is_a?(Hash) && value.is_a?(Hash)
+            pval.merge!(value)
+          elsif pval.is_a?(Set) && value.is_a?(Set)
+            pval.merge(value)
+          elsif pval.is_a?(Array) && value.is_a?(Array)
+            pval.concat value
+          else
+            @properties[key] = value
+          end
+        end
+
+        def fetch(key)
+          @properties[key]
+        end
+
+        def respond_to_missing?(method, _include_all=false)
+          @properties.key?(method) || super
+        end
+
+        def roles
+          @roles ||= Set.new
+        end
+
+        def keys
+          @properties.keys
+        end
+
+        # rubocop:disable Style/MethodMissing
+        def method_missing(key, value=nil)
+          if value
+            set(lvalue(key), value)
+          else
+            fetch(key)
+          end
+        end
+        # rubocop:enable Style/MethodMissing
+
+        def to_h
+          @properties
+        end
+
+        private
+
+        def lvalue(key)
+          key.to_s.chomp("=").to_sym
+        end
+      end
+    end
+  end
+end

data/lib/capistrano/configuration/servers.rb

@@ -1,115 +1,75 @@
+require "set"
+require "capistrano/configuration"
+require "capistrano/configuration/filter"
+
 module Capistrano
   class Configuration
-    module Servers
-      # Identifies all servers that the given task should be executed on.
-      # The options hash accepts the same arguments as #find_servers, and any
-      # preexisting options there will take precedence over the options in
-      # the task.
-      def find_servers_for_task(task, options={})
-        find_servers(task.options.merge(options))
-      end
+    class Servers
+      include Enumerable
 
-      # Attempts to find all defined servers that match the given criteria.
-      # The options hash may include a :hosts option (which should specify
-      # an array of host names or ServerDefinition instances), a :roles
-      # option (specifying an array of roles), an :only option (specifying
-      # a hash of key/value pairs that any matching server must match), 
-      # an :exception option (like :only, but the inverse), and a 
-      # :skip_hostfilter option to ignore the HOSTFILTER environment variable
-      # described below.
-      #
-      # Additionally, if the HOSTS environment variable is set, it will take
-      # precedence over any other options. Similarly, the ROLES environment
-      # variable will take precedence over other options. If both HOSTS and
-      # ROLES are given, HOSTS wins.
-      #
-      # Yet additionally, if the HOSTFILTER environment variable is set, it
-      # will limit the result to hosts found in that (comma-separated) list.
-      #
-      # If the HOSTROLEFILTER environment variable is set, it will limit the
-      # result to hosts found in that (comma-separated) list of roles 
-      #
-      # Usage:
-      #
-      #   # return all known servers
-      #   servers = find_servers
-      #
-      #   # find all servers in the app role that are not exempted from
-      #   # deployment
-      #   servers = find_servers :roles => :app,
-      #                :except => { :no_release => true }
-      #
-      #   # returns the given hosts, translated to ServerDefinition objects
-      #   servers = find_servers :hosts => "jamis@example.host.com"
-      def find_servers(options={})
-        return [] if options.key?(:hosts) && (options[:hosts].nil? || [] == options[:hosts])
-        return [] if options.key?(:roles) && (options[:roles].nil? || [] == options[:roles])
-        
-        hosts  = server_list_from(ENV['HOSTS'] || options[:hosts])
-        
-        if hosts.any?
-          if options[:skip_hostfilter]
-            hosts.uniq
-          else
-            filter_server_list(hosts.uniq)
-          end
+      def add_host(host, properties={})
+        new_host = Server[host]
+        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
-					roles = role_list_from(ENV['ROLES'] || options[:roles] || self.roles.keys)
-					roles = roles & Array(options[:roles]) if preserve_roles && !options[:roles].nil?
-
-          only   = options[:only] || {}
-          except = options[:except] || {}
-          
-          servers = roles.inject([]) { |list, role| list.concat(self.roles[role]) }
-          servers = servers.select { |server| only.all? { |key,value| server.options[key] == value } }
-          servers = servers.reject { |server| except.any? { |key,value| server.options[key] == value } }
-
-          if options[:skip_hostfilter]
-            servers.uniq
-          else
-            filter_server_list(servers.uniq)
-          end
+          servers_by_key[key] = new_host.with(properties)
         end
       end
 
-    protected
+      # 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 filter_server_list(servers)
-        return servers unless ENV['HOSTFILTER'] or ENV['HOSTROLEFILTER']
-        if ENV['HOSTFILTER']
-          filters = ENV['HOSTFILTER'].split(/,/)
-          servers.select { |server| filters.include?(server.host) }
-        elsif ENV['HOSTROLEFILTER']
-          filters = ENV['HOSTROLEFILTER'].split(/,/).map do |role|
-            local_roles = roles[role.to_sym]
-            if local_roles.is_a? Array
-              roles[role.to_sym]
-            else
-              roles[role.to_sym].servers
+      def roles_for(names)
+        options = extract_options(names)
+        s = Filter.new(:role, names).filter(servers_by_key.values)
+        s.select { |server| server.select?(options) }
+      end
+
+      def role_properties_for(rolenames)
+        roles = rolenames.to_set
+        rps = Set.new unless block_given?
+        roles_for(rolenames).each do |host|
+          host.roles.intersection(roles).each do |role|
+            [host.properties.fetch(role)].flatten(1).each do |props|
+              if block_given?
+                yield host, role, props
+              else
+                rps << (props || {}).merge(role: role, hostname: host.hostname)
+              end
             end
-          end.flatten
-          servers.select { |server| filters.include?(server) }
+          end
         end
+        block_given? ? nil : rps
       end
 
-      def server_list_from(hosts)
-        hosts = hosts.split(/,/) if String === hosts
-        hosts = build_list(hosts)
-        hosts.map { |s| String === s ? ServerDefinition.new(s.strip) : s }
+      def fetch_primary(role)
+        hosts = roles_for([role])
+        hosts.find(&:primary) || hosts.first
       end
 
-      def role_list_from(roles)
-        roles = roles.split(/,/) if String === roles
-        roles = build_list(roles)
-        roles.map do |role|
-          role = String === role ? role.strip.to_sym : role
-          raise ArgumentError, "unknown role `#{role}'" unless self.roles.key?(role)
-          role
-        end
+      def each
+        servers_by_key.values.each { |server| yield server }
+      end
+
+      private
+
+      ServerKey = Struct.new(:hostname, :port)
+
+      def servers_by_key
+        @servers_by_key ||= {}
       end
 
-      def build_list(list)
-        Array(list).map { |item| item.respond_to?(:call) ? item.call : item }.flatten
+      def extract_options(array)
+        array.last.is_a?(::Hash) ? array.pop : {}
       end
     end
   end