wulffeld-capistrano 2.5.8

data/lib/capistrano/command.rb

@@ -0,0 +1,283 @@
+require 'capistrano/errors'
+require 'capistrano/processable'
+
+module Capistrano
+
+  # This class encapsulates a single command to be executed on a set of remote
+  # machines, in parallel.
+  class Command
+    include Processable
+
+    class Tree
+      attr_reader :configuration
+      attr_reader :branches
+      attr_reader :fallback
+
+      include Enumerable
+
+      class Branch
+        attr_accessor :command, :callback
+        attr_reader :options
+
+        def initialize(command, options, callback)
+          @command = command.strip.gsub(/\r?\n/, "\\\n")
+          @callback = callback || Capistrano::Configuration.default_io_proc
+          @options = options
+          @skip = false
+        end
+
+        def last?
+          options[:last]
+        end
+
+        def skip?
+          @skip
+        end
+
+        def skip!
+          @skip = true
+        end
+
+        def match(server)
+          true
+        end
+
+        def to_s
+          command.inspect
+        end
+      end
+
+      class ConditionBranch < Branch
+        attr_accessor :configuration
+        attr_accessor :condition
+
+        class Evaluator
+          attr_reader :configuration, :condition, :server
+
+          def initialize(config, condition, server)
+            @configuration = config
+            @condition = condition
+            @server = server
+          end
+
+          def in?(role)
+            configuration.roles[role].include?(server)
+          end
+
+          def result
+            eval(condition, binding)
+          end
+
+          def method_missing(sym, *args, &block)
+            if server.respond_to?(sym)
+              server.send(sym, *args, &block)
+            elsif configuration.respond_to?(sym)
+              configuration.send(sym, *args, &block)
+            else
+              super
+            end
+          end
+        end
+
+        def initialize(configuration, condition, command, options, callback)
+          @configuration = configuration
+          @condition = condition
+          super(command, options, callback)
+        end
+
+        def match(server)
+          Evaluator.new(configuration, condition, server).result
+        end
+
+        def to_s
+          "#{condition.inspect} :: #{command.inspect}"
+        end
+      end
+
+      def initialize(config)
+        @configuration = config
+        @branches = []
+        yield self if block_given?
+      end
+
+      def when(condition, command, options={}, &block)
+        branches << ConditionBranch.new(configuration, condition, command, options, block)
+      end
+
+      def else(command, &block)
+        @fallback = Branch.new(command, {}, block)
+      end
+
+      def branches_for(server)
+        seen_last = false
+        matches = branches.select do |branch|
+          success = !seen_last && !branch.skip? && branch.match(server)
+          seen_last = success && branch.last?
+          success
+        end
+
+        matches << fallback if matches.empty? && fallback
+        return matches
+      end
+
+      def each
+        branches.each { |branch| yield branch }
+        yield fallback if fallback
+        return self
+      end
+    end
+
+    attr_reader :tree, :sessions, :options
+
+    def self.process(tree, sessions, options={})
+      new(tree, sessions, options).process!
+    end
+
+    # Instantiates a new command object. The +command+ must be a string
+    # containing the command to execute. +sessions+ is an array of Net::SSH
+    # session instances, and +options+ must be a hash containing any of the
+    # following keys:
+    #
+    # * +logger+: (optional), a Capistrano::Logger instance
+    # * +data+: (optional), a string to be sent to the command via it's stdin
+    # * +env+: (optional), a string or hash to be interpreted as environment
+    #   variables that should be defined for this command invocation.
+    def initialize(tree, sessions, options={}, &block)
+      if String === tree
+        tree = Tree.new(nil) { |t| t.else(tree, &block) }
+      elsif block
+        raise ArgumentError, "block given with tree argument"
+      end
+
+      @tree = tree
+      @sessions = sessions
+      @options = options
+      @channels = open_channels
+    end
+
+    # Processes the command in parallel on all specified hosts. If the command
+    # fails (non-zero return code) on any of the hosts, this will raise a
+    # Capistrano::CommandError.
+    def process!
+      loop do
+        break unless process_iteration { @channels.any? { |ch| !ch[:closed] } }
+      end
+
+      logger.trace "command finished" if logger
+
+      if (failed = @channels.select { |ch| ch[:status] != 0 }).any?
+        commands = failed.inject({}) { |map, ch| (map[ch[:command]] ||= []) << ch[:server]; map }
+        message = commands.map { |command, list| "#{command.inspect} on #{list.join(',')}" }.join("; ")
+        error = CommandError.new("failed: #{message}")
+        error.hosts = commands.values.flatten
+        raise error
+      end
+
+      self
+    end
+
+    # Force the command to stop processing, by closing all open channels
+    # associated with this command.
+    def stop!
+      @channels.each do |ch|
+        ch.close unless ch[:closed]
+      end
+    end
+
+    private
+
+      def logger
+        options[:logger]
+      end
+
+      def open_channels
+        sessions.map do |session|
+          server = session.xserver
+          tree.branches_for(server).map do |branch|
+            session.open_channel do |channel|
+              channel[:server] = server
+              channel[:host] = server.host
+              channel[:options] = options
+              channel[:branch] = branch
+
+              request_pty_if_necessary(channel) do |ch, success|
+                if success
+                  logger.trace "executing command", ch[:server] if logger
+                  cmd = replace_placeholders(channel[:branch].command, ch)
+
+                  if options[:shell] == false
+                    shell = nil
+                  else
+                    shell = "#{options[:shell] || "sh"} -c"
+                    cmd = cmd.gsub(/[$\\`"]/) { |m| "\\#{m}" }
+                    cmd = "\"#{cmd}\""
+                  end
+
+                  command_line = [environment, shell, cmd].compact.join(" ")
+                  ch[:command] = command_line
+
+                  ch.exec(command_line)
+                  ch.send_data(options[:data]) if options[:data]
+                else
+                  # just log it, don't actually raise an exception, since the
+                  # process method will see that the status is not zero and will
+                  # raise an exception then.
+                  logger.important "could not open channel", ch[:server] if logger
+                  ch.close
+                end
+              end
+
+              channel.on_data do |ch, data|
+                ch[:branch].callback[ch, :out, data]
+              end
+
+              channel.on_extended_data do |ch, type, data|
+                ch[:branch].callback[ch, :err, data]
+              end
+
+              channel.on_request("exit-status") do |ch, data|
+                ch[:status] = data.read_long
+              end
+
+              channel.on_close do |ch|
+                ch[:closed] = true
+              end
+            end
+          end
+        end.flatten
+      end
+
+      def request_pty_if_necessary(channel)
+        if options[:pty]
+          channel.request_pty do |ch, success|
+            yield ch, success
+          end
+        else
+          yield channel, true
+        end
+      end
+
+      def replace_placeholders(command, channel)
+        command.gsub(/\$CAPISTRANO:HOST\$/, channel[:host])
+      end
+
+      # prepare a space-separated sequence of variables assignments
+      # intended to be prepended to a command, so the shell sets
+      # the environment before running the command.
+      # i.e.: options[:env] = {'PATH' => '/opt/ruby/bin:$PATH',
+      #                        'TEST' => '( "quoted" )'}
+      # environment returns:
+      # "env TEST=(\ \"quoted\"\ ) PATH=/opt/ruby/bin:$PATH"
+      def environment
+        return if options[:env].nil? || options[:env].empty?
+        @environment ||= if String === options[:env]
+            "env #{options[:env]}"
+          else
+            options[:env].inject("env") do |string, (name, value)|
+              value = value.to_s.gsub(/[ "]/) { |m| "\\#{m}" }
+              string << " #{name}=#{value}"
+            end
+          end
+      end
+  end
+end

data/lib/capistrano/configuration.rb

@@ -0,0 +1,43 @@
+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'
+
+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 Configuration
+    # The logger instance defined for this configuration.
+    attr_accessor :debug, :logger, :dry_run
+
+    def initialize #:nodoc:
+      @debug = false
+      @dry_run = false
+      @logger = Logger.new
+    end
+
+    # make the DSL easier to read when using lazy evaluation via lambdas
+    alias defer lambda
+
+    # 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
+
+    # Mix in the actions
+    include Actions::FileTransfer, Actions::Inspect, Actions::Invocation
+
+    # Must mix last, because it hooks into previously defined methods
+    include Callbacks
+  end
+end

data/lib/capistrano/configuration/actions/file_transfer.rb

@@ -0,0 +1,47 @@
+require 'capistrano/transfer'
+
+module Capistrano
+  class Configuration
+    module Actions
+      module FileTransfer
+
+        # Store the given data at the given location on all servers targetted
+        # by the current task. If <tt>:mode</tt> is specified it is used to
+        # set the mode on the file.
+        def put(data, path, options={})
+          opts = options.dup
+          upload(StringIO.new(data), path, opts)
+        end
+    
+        # Get file remote_path from FIRST server targeted by
+        # the current task and transfer it to local machine as path.
+        #
+        # get "#{deploy_to}/current/log/production.log", "log/production.log.web"
+        def get(remote_path, path, options={}, &block)
+          download(remote_path, path, options.merge(:once => true), &block)
+        end
+
+        def upload(from, to, options={}, &block)
+          mode = options.delete(:mode)
+          transfer(:up, from, to, options, &block)
+          if mode
+            mode = mode.is_a?(Numeric) ? mode.to_s(8) : mode.to_s
+            run "chmod #{mode} #{to}"
+          end
+        end
+
+        def download(from, to, options={}, &block)
+          transfer(:down, from, to, options, &block)
+        end
+
+        def transfer(direction, from, to, options={}, &block)
+          execute_on_servers(options) do |servers|
+            targets = servers.map { |s| sessions[s] }
+            Transfer.process(direction, from, to, targets, options.merge(:logger => logger), &block)
+          end
+        end
+
+      end
+    end
+  end
+end

data/lib/capistrano/configuration/actions/inspect.rb

@@ -0,0 +1,46 @@
+require 'capistrano/errors'
+
+module Capistrano
+  class Configuration
+    module Actions
+      module Inspect
+
+        # Streams the result of the command from all servers that are the
+        # target of the current task. All these streams will be joined into a
+        # single one, so you can, say, watch 10 log files as though they were
+        # one. Do note that this is quite expensive from a bandwidth
+        # perspective, so use it with care.
+        #
+        # The command is invoked via #invoke_command.
+        #
+        # Usage:
+        #
+        #   desc "Run a tail on multiple log files at the same time"
+        #   task :tail_fcgi, :roles => :app do
+        #     stream "tail -f #{shared_path}/log/fastcgi.crash.log"
+        #   end
+        def stream(command, options={})
+          invoke_command(command, options) do |ch, stream, out|
+            puts out if stream == :out
+            warn "[err :: #{ch[:server]}] #{out}" if stream == :err
+          end
+        end
+
+        # Executes the given command on the first server targetted by the
+        # current task, collects it's stdout into a string, and returns the
+        # string. The command is invoked via #invoke_command.
+        def capture(command, options={})
+          output = ""
+          invoke_command(command, options.merge(:once => true)) do |ch, stream, data|
+            case stream
+            when :out then output << data
+            when :err then warn "[err :: #{ch[:server]}] #{data}"
+            end
+          end
+          output
+        end
+
+      end
+    end
+  end
+end

data/lib/capistrano/configuration/actions/invocation.rb

@@ -0,0 +1,293 @@
+require 'capistrano/command'
+
+module Capistrano
+  class Configuration
+    module Actions
+      module Invocation
+        def self.included(base) #:nodoc:
+          base.extend(ClassMethods)
+
+          base.send :alias_method, :initialize_without_invocation, :initialize
+          base.send :alias_method, :initialize, :initialize_with_invocation
+
+          base.default_io_proc = Proc.new do |ch, stream, out|
+            level = stream == :err ? :important : :info
+            ch[:options][:logger].send(level, out, "#{stream} :: #{ch[:server]}")
+          end
+        end
+
+        module ClassMethods
+          attr_accessor :default_io_proc
+        end
+
+        def initialize_with_invocation(*args) #:nodoc:
+          initialize_without_invocation(*args)
+          set :default_environment, {}
+          set :default_run_options, {}
+        end
+
+        # Executes different commands in parallel. This is useful for commands
+        # that need to be different on different hosts, but which could be
+        # otherwise run in parallel.
+        #
+        # The +options+ parameter is currently unused.
+        #
+        # Example:
+        #
+        #   task :restart_everything do
+        #     parallel do |session|
+        #       session.when "in?(:app)", "/path/to/restart/mongrel"
+        #       session.when "in?(:web)", "/path/to/restart/apache"
+        #       session.when "in?(:db)", "/path/to/restart/mysql"
+        #     end
+        #   end
+        #
+        # Each command may have its own callback block, for capturing and
+        # responding to output, with semantics identical to #run:
+        #
+        #   session.when "in?(:app)", "/path/to/restart/mongrel" do |ch, stream, data|
+        #     # ch is the SSH channel for this command, used to send data
+        #     #    back to the command (e.g. ch.send_data("password\n"))
+        #     # stream is either :out or :err, for which stream the data arrived on
+        #     # data is a string containing data sent from the remote command
+        #   end
+        #
+        # Also, you can specify a fallback command, to use when none of the
+        # conditions match a server:
+        #
+        #   session.else "/execute/something/else"
+        #
+        # The string specified as the first argument to +when+ may be any valid
+        # Ruby code. It has access to the following variables and methods:
+        # 
+        # * +in?(role)+ returns true if the server participates in the given role
+        # * +server+ is the ServerDefinition object for the server. This can be
+        #   used to get the host-name, etc.
+        # * +configuration+ is the current Capistrano::Configuration object, which
+        #   you can use to get the value of variables, etc.
+        #
+        # For example:
+        #
+        #   session.when "server.host =~ /app/", "/some/command"
+        #   session.when "server.host == configuration[:some_var]", "/another/command"
+        #   session.when "in?(:web) || in?(:app)", "/more/commands"
+        #
+        # See #run for a description of the valid +options+.
+        def parallel(options={})
+          raise ArgumentError, "parallel() requires a block" unless block_given?
+          tree = Command::Tree.new(self) { |t| yield t }
+          run_tree(tree, options)
+        end
+
+        # Invokes the given command. If a +via+ key is given, it will be used
+        # to determine what method to use to invoke the command. It defaults
+        # to :run, but may be :sudo, or any other method that conforms to the
+        # same interface as run and sudo.
+        def invoke_command(cmd, options={}, &block)
+          options = options.dup
+          via = options.delete(:via) || :run
+          send(via, cmd, options, &block)
+        end
+
+        # Execute the given command on all servers that are the target of the
+        # current task. If a block is given, it is invoked for all output
+        # generated by the command, and should accept three parameters: the SSH
+        # channel (which may be used to send data back to the remote process),
+        # the stream identifier (<tt>:err</tt> for stderr, and <tt>:out</tt> for
+        # stdout), and the data that was received.
+        #
+        # The +options+ hash may include any of the following keys:
+        #
+        # * :hosts - this is either a string (for a single target host) or an array
+        #   of strings, indicating which hosts the command should run on. By default,
+        #   the hosts are determined from the task definition.
+        # * :roles - this is either a string or symbol (for a single target role) or
+        #   an array of strings or symbols, indicating which roles the command should
+        #   run on. If :hosts is specified, :roles will be ignored.
+        # * :only - specifies a condition limiting which hosts will be selected to
+        #   run the command. This should refer to values set in the role definition.
+        #   For example, if a role is defined with :primary => true, then you could
+        #   select only hosts with :primary true by setting :only => { :primary => true }.
+        # * :except - specifies a condition limiting which hosts will be selected to
+        #   run the command. This is the inverse of :only (hosts that do _not_ match
+        #   the condition will be selected).
+        # * :once - if true, only the first matching server will be selected. The default
+        #   is false (all matching servers will be selected).
+        # * :max_hosts - specifies the maximum number of hosts that should be selected
+        #   at a time. If this value is less than the number of hosts that are selected
+        #   to run, then the hosts will be run in groups of max_hosts. The default is nil,
+        #   which indicates that there is no maximum host limit.
+        # * :shell - says which shell should be used to invoke commands. This
+        #   defaults to "sh". Setting this to false causes Capistrano to invoke
+        #   the commands directly, without wrapping them in a shell invocation.
+        # * :data - if not nil (the default), this should be a string that will
+        #   be passed to the command's stdin stream.
+        # * :pty - if true, a pseudo-tty will be allocated for each command. The
+        #   default is false. Note that there are benefits and drawbacks both ways.
+        #   Empirically, it appears that if a pty is allocated, the SSH server daemon
+        #   will _not_ read user shell start-up scripts (e.g. bashrc, etc.). However,
+        #   if a pty is _not_ allocated, some commands will refuse to run in
+        #   interactive mode and will not prompt for (e.g.) passwords.
+        # * :env - a hash of environment variable mappings that should be made
+        #   available to the command. The keys should be environment variable names,
+        #   and the values should be their corresponding values. The default is
+        #   empty, but may be modified by changing the +default_environment+
+        #   Capistrano variable.
+        #
+        # Note that if you set these keys in the +default_run_options+ Capistrano
+        # variable, they will apply for all invocations of #run, #invoke_command,
+        # and #parallel.
+        def run(cmd, options={}, &block)
+          block ||= self.class.default_io_proc
+          tree = Command::Tree.new(self) { |t| t.else(cmd, &block) }
+          run_tree(tree, options)
+        end
+
+        # Executes a Capistrano::Command::Tree object. This is not for direct
+        # use, but should instead be called indirectly, via #run or #parallel,
+        # or #invoke_command.
+        def run_tree(tree, options={}) #:nodoc:
+          if tree.branches.empty? && tree.fallback
+            logger.debug "executing #{tree.fallback}"
+          elsif tree.branches.any?
+            logger.debug "executing multiple commands in parallel"
+            tree.each do |branch|
+              logger.trace "-> #{branch}"
+            end
+          else
+            raise ArgumentError, "attempt to execute without specifying a command"
+          end
+
+          return if dry_run || (debug && continue_execution(tree) == false)
+
+          options = add_default_command_options(options)
+
+          tree.each do |branch|
+            if branch.command.include?(sudo)
+              branch.callback = sudo_behavior_callback(branch.callback)
+            end
+          end
+
+          execute_on_servers(options) do |servers|
+            targets = servers.map { |s| sessions[s] }
+            Command.process(tree, targets, options.merge(:logger => logger))
+          end
+        end
+
+        # Returns the command string used by capistrano to invoke a comamnd via
+        # sudo.
+        #
+        #   run "#{sudo :as => 'bob'} mkdir /path/to/dir"
+        #
+        # It can also be invoked like #run, but executing the command via sudo.
+        # This assumes that the sudo password (if required) is the same as the
+        # password for logging in to the server.
+        #
+        #   sudo "mkdir /path/to/dir"
+        #
+        # Also, this method understands a <tt>:sudo</tt> configuration variable,
+        # which (if specified) will be used as the full path to the sudo
+        # executable on the remote machine:
+        #
+        #   set :sudo, "/opt/local/bin/sudo"
+        #
+        # If you know what you're doing, you can also set <tt>:sudo_prompt</tt>,
+        # which tells capistrano which prompt sudo should use when asking for
+        # a password. (This is so that capistrano knows what prompt to look for
+        # in the output.) If you set :sudo_prompt to an empty string, Capistrano
+        # will not send a preferred prompt.
+        def sudo(*parameters, &block)
+          options = parameters.last.is_a?(Hash) ? parameters.pop.dup : {}
+          command = parameters.first
+          user = options[:as] && "-u #{options.delete(:as)}"
+
+          sudo_prompt_option = "-p '#{sudo_prompt}'" unless sudo_prompt.empty?
+          sudo_command = [fetch(:sudo, "sudo"), sudo_prompt_option, user].compact.join(" ")
+
+          if command
+            command = sudo_command + " " + command
+            run(command, options, &block)
+          else
+            return sudo_command
+          end
+        end
+
+        # Returns a Proc object that defines the behavior of the sudo
+        # callback. The returned Proc will defer to the +fallback+ argument
+        # (which should also be a Proc) for any output it does not
+        # explicitly handle.
+        def sudo_behavior_callback(fallback) #:nodoc:
+          # in order to prevent _each host_ from prompting when the password
+          # was wrong, let's track which host prompted first and only allow
+          # subsequent prompts from that host.
+          prompt_host = nil
+
+          Proc.new do |ch, stream, out|
+            if out =~ /^Sorry, try again/
+              if prompt_host.nil? || prompt_host == ch[:server]
+                prompt_host = ch[:server]
+                logger.important out, "#{stream} :: #{ch[:server]}"
+                reset! :password
+              end
+            end
+
+            if out =~ /^#{Regexp.escape(sudo_prompt)}/
+              ch.send_data "#{self[:password]}\n"
+            elsif fallback
+              fallback.call(ch, stream, out)
+            end
+          end
+        end
+
+        # Merges the various default command options into the options hash and
+        # returns the result. The default command options that are understand
+        # are:
+        #
+        # * :default_environment: If the :env key already exists, the :env
+        #   key is merged into default_environment and then added back into
+        #   options.
+        # * :default_shell: if the :shell key already exists, it will be used.
+        #   Otherwise, if the :default_shell key exists in the configuration,
+        #   it will be used. Otherwise, no :shell key is added.
+        def add_default_command_options(options)
+          defaults = self[:default_run_options]
+          options = defaults.merge(options)
+
+          env = self[:default_environment]
+          env = env.merge(options[:env]) if options[:env]
+          options[:env] = env unless env.empty?
+
+          shell = options[:shell] || self[:default_shell]
+          options[:shell] = shell unless shell.nil?
+
+          options
+        end
+
+        # Returns the prompt text to use with sudo
+        def sudo_prompt
+          fetch(:sudo_prompt, "sudo password: ")
+        end
+        
+        def continue_execution(tree)
+          if tree.branches.length == 1
+            continue_execution_for_branch(tree.branches.first)
+          else
+            tree.each { |branch| branch.skip! unless continue_execution_for_branch(branch) }
+            tree.any? { |branch| !branch.skip? }
+          end
+        end
+
+        def continue_execution_for_branch(branch)
+          case Capistrano::CLI.debug_prompt(branch)
+            when "y"
+              true
+            when "n"
+              false
+            when "a"
+              exit(-1)
+          end
+        end
+      end
+    end
+  end
+end