capistrano 2.8.0 → 3.19.0

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 = proc 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

@@ -1,126 +1,111 @@
-require 'thread'
+require "capistrano/proc_helpers"
 
 module Capistrano
   class Configuration
-    module Variables
-      def self.included(base) #:nodoc:
-        %w(initialize respond_to? method_missing).each do |m|
-          base_name = m[/^\w+/]
-          punct     = m[/\W+$/]
-          base.send :alias_method, "#{base_name}_without_variables#{punct}", m
-          base.send :alias_method, m, "#{base_name}_with_variables#{punct}"
-        end
+    # 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
 
-      # The hash of variables that have been defined in this configuration
-      # instance.
-      attr_reader :variables
+      def untrusted!
+        @trusted = false
+        yield
+      ensure
+        @trusted = true
+      end
 
-      # Set a variable to the given value.
-      def set(variable, *args, &block)
-        if variable.to_s !~ /^[_a-z]/
-          raise ArgumentError, "invalid variable `#{variable}' (variables must begin with an underscore, or a lower-case letter)"
-        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
 
-        if !block_given? && args.empty? || block_given? && !args.empty?
-          raise ArgumentError, "you must specify exactly one of either a value or a block"
-        end
+      def fetch(key, default=nil, &block)
+        fetched_keys << key unless fetched_keys.include?(key)
+        peek(key, default, &block)
+      end
 
-        if args.length > 1
-          raise ArgumentError, "wrong number of arguments (#{args.length} for 1)"
+      # 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 = args.empty? ? block : args.first
-        sym = variable.to_sym
-        protect(sym) { @variables[sym] = value }
+        value
       end
 
-      alias :[]= :set
-
-      # Removes any trace of the given variable.
-      def unset(variable)
-        sym = variable.to_sym
-        protect(sym) do
-          @original_procs.delete(sym)
-          @variables.delete(sym)
-        end
+      def fetch_for(key, default, &block)
+        block ? values.fetch(key, &block) : values.fetch(key, default)
       end
 
-      # Returns true if the variable has been defined, and false otherwise.
-      def exists?(variable)
-        @variables.key?(variable.to_sym)
+      def delete(key)
+        values.delete(key)
       end
 
-      # If the variable was originally a proc value, it will be reset to it's
-      # original proc value. Otherwise, this method does nothing. It returns
-      # true if the variable was actually reset.
-      def reset!(variable)
-        sym = variable.to_sym
-        protect(sym) do
-          if @original_procs.key?(sym)
-            @variables[sym] = @original_procs.delete(sym)
-            true
-          else
-            false
-          end
-        end
+      def trusted_keys
+        @trusted_keys.dup
       end
 
-      # Access a named variable. If the value of the variable responds_to? :call,
-      # #call will be invoked (without parameters) and the return value cached
-      # and returned.
-      def fetch(variable, *args)
-        if !args.empty? && block_given?
-          raise ArgumentError, "you must specify either a default value or a block, but not both"
-        end
+      def untrusted_keys
+        keys - @trusted_keys
+      end
 
-        sym = variable.to_sym
-        protect(sym) do
-          if !@variables.key?(sym)
-            return args.first unless args.empty?
-            return yield(variable) if block_given?
-            raise IndexError, "`#{variable}' not found"
-          end
-
-          if @variables[sym].respond_to?(:call)
-            @original_procs[sym] = @variables[sym]
-            @variables[sym] = @variables[sym].call
-          end
-        end
+      def keys
+        values.keys
+      end
 
-        @variables[sym]
+      # Keys that have been set, but which have never been fetched.
+      def unused_keys
+        keys - fetched_keys
       end
 
-      def [](variable)
-        fetch(variable, nil)
+      # 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
 
-      def initialize_with_variables(*args) #:nodoc:
-        initialize_without_variables(*args)
-        @variables = {}
-        @original_procs = {}
-        @variable_locks = Hash.new { |h,k| h[k] = Mutex.new }
+      private
 
-        set :ssh_options, {}
-        set :logger, logger
-      end
-      private :initialize_with_variables
+      attr_reader :locations, :values, :fetched_keys
 
-      def protect(variable)
-        @variable_locks[variable.to_sym].synchronize { yield }
+      def trusted?
+        @trusted
       end
-      private :protect
 
-      def respond_to_with_variables?(sym, include_priv=false) #:nodoc:
-        @variables.has_key?(sym.to_sym) || respond_to_without_variables?(sym, include_priv)
+      def remember_location(key)
+        location = caller.find do |line|
+          IGNORED_LOCATIONS.none? { |i| line.include?(i) }
+        end
+        (locations[key] ||= []) << location
       end
 
-      def method_missing_with_variables(sym, *args, &block) #:nodoc:
-        if args.length == 0 && block.nil? && @variables.has_key?(sym)
-          self[sym]
-        else
-          method_missing_without_variables(sym, *args, &block)
-        end
+      def trace_set(key)
+        return unless fetch(:print_config_variables, false)
+        puts "Config variable set: #{key.inspect} => #{values[key].inspect}"
       end
     end
   end

data/lib/capistrano/configuration.rb

@@ -1,44 +1,189 @@
-require 'capistrano/logger'
-
-require 'capistrano/configuration/callbacks'
-require 'capistrano/configuration/connections'
-require 'capistrano/configuration/execution'
-require 'capistrano/configuration/loading'
-require 'capistrano/configuration/namespaces'
-require 'capistrano/configuration/roles'
-require 'capistrano/configuration/servers'
-require 'capistrano/configuration/variables'
-
-require 'capistrano/configuration/actions/file_transfer'
-require 'capistrano/configuration/actions/inspect'
-require 'capistrano/configuration/actions/invocation'
+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
-  # Represents a specific Capistrano configuration. A Configuration instance
-  # may be used to load multiple recipe files, define and describe tasks,
-  # define roles, and set configuration variables.
+  class ValidationError < RuntimeError; end
+
   class Configuration
-    # The logger instance defined for this configuration.
-    attr_accessor :debug, :logger, :dry_run, :preserve_roles
+    def self.env
+      @env ||= new
+    end
+
+    def self.reset!
+      @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_if_empty(key, value=nil, &block)
+      set(key, value, &block) unless keys.include?(key)
+    end
+
+    def append(key, *values)
+      set(key, Array(fetch(key)).concat(values))
+    end
 
-    def initialize(options={}) #:nodoc:
-      @debug = false
-      @dry_run = false
-      @preserve_roles = false
-      @logger = Logger.new(options)
+    def remove(key, *values)
+      set(key, Array(fetch(key)) - values)
     end
 
-    # make the DSL easier to read when using lazy evaluation via lambdas
-    alias defer lambda
+    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
 
-    # The includes must come at the bottom, since they may redefine methods
-    # defined in the base class.
-    include Connections, Execution, Loading, Namespaces, Roles, Servers, Variables
+      !value.nil?
+    end
+
+    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, "#{name} reserved name for role. Please choose another name"
+      end
+
+      servers.add_role(name, hosts, options)
+    end
+
+    def server(name, properties={})
+      servers.add_host(name, properties)
+    end
+
+    def roles_for(names)
+      servers.roles_for(names)
+    end
+
+    def role_properties_for(names, &block)
+      servers.role_properties_for(names, &block)
+    end
+
+    def primary(role)
+      servers.fetch_primary(role)
+    end
+
+    def backend
+      @backend ||= SSHKit
+    end
 
-    # Mix in the actions
-    include Actions::FileTransfer, Actions::Inspect, Actions::Invocation
+    attr_writer :backend
 
-    # Must mix last, because it hooks into previously defined methods
-    include Callbacks
+    def configure_backend
+      backend.configure do |sshkit|
+        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, {}))
+        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
+      @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
+
+    def add_cmdline_filter(type, values)
+      cmdline_filters << Filter.new(type, values)
+    end
+
+    def filter(list)
+      setup_filters if @filters.nil?
+      @filters.reduce(list) { |l, f| f.filter l }
+    end
+
+    def dry_run?
+      fetch(:sshkit_backend) == SSHKit::Backend::Printer
+    end
+
+    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
+
+    private
+
+    def cmdline_filters
+      @cmdline_filters ||= []
+    end
+
+    def installer
+      @installer ||= PluginInstaller.new
+    end
+
+    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/console.rb

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

data/lib/capistrano/defaults.rb

@@ -0,0 +1,36 @@
+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, :airbrussh
+set_if_empty :log_level, :debug
+
+set_if_empty :pty, false
+
+set_if_empty :local_user, -> { ENV["USER"] || ENV["LOGNAME"] || ENV["USERNAME"] }

data/lib/capistrano/deploy.rb

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

data/lib/capistrano/doctor/environment_doctor.rb

@@ -0,0 +1,19 @@
+require "capistrano/doctor/output_helpers"
+
+module Capistrano
+  module Doctor
+    class EnvironmentDoctor
+      include Capistrano::Doctor::OutputHelpers
+
+      def call
+        title("Environment")
+        puts <<-OUT.gsub(/^\s+/, "")
+          Ruby     #{RUBY_DESCRIPTION}
+          Rubygems #{Gem::VERSION}
+          Bundler  #{defined?(Bundler::VERSION) ? Bundler::VERSION : 'N/A'}
+          Command  #{$PROGRAM_NAME} #{ARGV.join(' ')}
+        OUT
+      end
+    end
+  end
+end

data/lib/capistrano/doctor/gems_doctor.rb

@@ -0,0 +1,45 @@
+require "capistrano/doctor/output_helpers"
+
+module Capistrano
+  module Doctor
+    # Prints table of all Capistrano-related gems and their version numbers. If
+    # there is a newer version of a gem available, call attention to it.
+    class GemsDoctor
+      include Capistrano::Doctor::OutputHelpers
+
+      def call
+        title("Gems")
+        table(all_gem_names) do |gem, row|
+          row.yellow if update_available?(gem)
+          row << gem
+          row << installed_gem_version(gem)
+          row << "(update available)" if update_available?(gem)
+        end
+      end
+
+      private
+
+      def installed_gem_version(gem_name)
+        Gem.loaded_specs[gem_name].version
+      end
+
+      def update_available?(gem_name)
+        latest = Gem.latest_version_for(gem_name)
+        return false if latest.nil?
+        latest > installed_gem_version(gem_name)
+      end
+
+      def all_gem_names
+        core_gem_names + plugin_gem_names
+      end
+
+      def core_gem_names
+        %w(capistrano airbrussh rake sshkit net-ssh) & Gem.loaded_specs.keys
+      end
+
+      def plugin_gem_names
+        (Gem.loaded_specs.keys - ["capistrano"]).grep(/capistrano/).sort
+      end
+    end
+  end
+end