mbailey-capistrano 2.5.5

data/lib/capistrano/cli/options.rb

@@ -0,0 +1,224 @@
+require 'optparse'
+
+module Capistrano
+  class CLI
+    module Options
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods
+        # Return a new CLI instance with the given arguments pre-parsed and
+        # ready for execution.
+        def parse(args)
+          cli = new(args)
+          cli.parse_options!
+          cli
+        end
+      end
+
+      # The hash of (parsed) command-line options
+      attr_reader :options
+
+      # Return an OptionParser instance that defines the acceptable command
+      # line switches for Capistrano, and what their corresponding behaviors
+      # are.
+      def option_parser #:nodoc:
+        @option_parser ||= OptionParser.new do |opts|
+          opts.banner = "Usage: #{File.basename($0)} [options] action ..."
+
+          opts.on("-d", "--debug",
+            "Prompts before each remote command execution."
+          ) { |value| options[:debug] = true }
+
+          opts.on("-e", "--explain TASK",
+            "Displays help (if available) for the task."
+          ) { |value| options[:explain] = value }
+
+          opts.on("-F", "--default-config",
+            "Always use default config, even with -f."
+          ) { options[:default_config] = true }
+
+          opts.on("-f", "--file FILE",
+            "A recipe file to load. May be given more than once."
+          ) { |value| options[:recipes] << value }
+
+          opts.on("-H", "--long-help", "Explain these options and environment variables.") do
+            long_help
+            exit
+          end
+
+          opts.on("-h", "--help", "Display this help message.") do
+            puts opts
+            exit
+          end
+
+          opts.on("-n", "--dry-run",
+            "Prints out commands without running them."
+          ) { |value| options[:dry_run] = true }
+
+          opts.on("-p", "--password",
+            "Immediately prompt for the password."
+          ) { options[:password] = nil }
+
+          opts.on("-q", "--quiet",
+            "Make the output as quiet as possible."
+          ) { options[:verbose] = 0 }
+
+          opts.on("-S", "--set-before NAME=VALUE",
+            "Set a variable before the recipes are loaded."
+          ) do |pair|
+            name, value = pair.split(/=/, 2)
+            options[:pre_vars][name.to_sym] = value
+          end
+
+          opts.on("-s", "--set NAME=VALUE",
+            "Set a variable after the recipes are loaded."
+          ) do |pair|
+            name, value = pair.split(/=/, 2)
+            options[:vars][name.to_sym] = value
+          end
+
+          opts.on("-T", "--tasks [PATTERN]",
+            "List all tasks (matching optional PATTERN) in the loaded recipe files."
+          ) do |value|
+            options[:tasks] = if value
+              value
+            else
+              true
+            end
+            options[:verbose] ||= 0
+          end
+
+          opts.on("-t", "--tool",
+            "Abbreviates the output of -T for tool integration."
+          ) { options[:tool] = true }
+
+          opts.on("-V", "--version",
+            "Display the Capistrano version, and exit."
+          ) do
+            require 'capistrano/version'
+            puts "Capistrano v#{Capistrano::Version::STRING}"
+            exit
+          end
+
+          opts.on("-v", "--verbose",
+            "Be more verbose. May be given more than once."
+          ) do
+            options[:verbose] ||= 0
+            options[:verbose] += 1
+          end
+
+          opts.on("-X", "--skip-system-config",
+            "Don't load the system config file (capistrano.conf)"
+          ) { options.delete(:sysconf) }
+
+          opts.on("-x", "--skip-user-config",
+            "Don't load the user config file (.caprc)"
+          ) { options.delete(:dotfile) }
+        end
+      end
+
+      # If the arguments to the command are empty, this will print the
+      # allowed options and exit. Otherwise, it will parse the command
+      # line and set up any default options.
+      def parse_options! #:nodoc:
+        @options = { :recipes => [], :actions => [],
+          :vars => {}, :pre_vars => {},
+          :sysconf => default_sysconf, :dotfile => default_dotfile }
+
+        if args.empty?
+          warn "Please specify at least one action to execute."
+          warn option_parser
+          exit
+        end
+
+        option_parser.parse!(args)
+
+        coerce_variable_types!
+
+        # if no verbosity has been specified, be verbose
+        options[:verbose] = 3 if !options.has_key?(:verbose)
+
+        look_for_default_recipe_file! if options[:default_config] || options[:recipes].empty?
+        extract_environment_variables!
+
+        options[:actions].concat(args)
+
+        password = options.has_key?(:password)
+        options[:password] = Proc.new { self.class.password_prompt }
+        options[:password] = options[:password].call if password
+      end
+
+      # Extracts name=value pairs from the remaining command-line arguments
+      # and assigns them as environment variables.
+      def extract_environment_variables! #:nodoc:
+        args.delete_if do |arg|
+          next unless arg.match(/^(\w+)=(.*)$/)
+          ENV[$1] = $2
+        end
+      end
+
+      # Looks for a default recipe file in the current directory.
+      def look_for_default_recipe_file! #:nodoc:
+        current = Dir.pwd
+
+        loop do
+          %w(Capfile capfile).each do |file|
+            if File.file?(file)
+              options[:recipes] << file
+              return
+            end
+          end
+
+          pwd = Dir.pwd
+          Dir.chdir("..")
+          break if pwd == Dir.pwd # if changing the directory made no difference, then we're at the top
+        end
+
+        Dir.chdir(current)
+      end
+
+      def default_sysconf #:nodoc:
+        File.join(sysconf_directory, "capistrano.conf")
+      end
+      
+      def default_dotfile #:nodoc:
+        File.join(home_directory, ".caprc")
+      end
+
+      def sysconf_directory #:nodoc:
+        # TODO if anyone cares, feel free to submit a patch that uses a more
+        # appropriate location for this file in Windows.
+        ENV["SystemRoot"] || '/etc'
+      end
+      
+      def home_directory #:nodoc:
+        ENV["HOME"] ||
+          (ENV["HOMEPATH"] && "#{ENV["HOMEDRIVE"]}#{ENV["HOMEPATH"]}") ||
+          "/"
+      end
+
+      def coerce_variable_types!
+        [:pre_vars, :vars].each do |collection|
+          options[collection].keys.each do |key|
+            options[collection][key] = coerce_variable(options[collection][key])
+          end
+        end
+      end
+
+      def coerce_variable(value)
+        case value
+        when /^"(.*)"$/ then $1
+        when /^'(.*)'$/ then $1
+        when /^\d+$/ then value.to_i
+        when /^\d+\.\d*$/ then value.to_f
+        when "true" then true
+        when "false" then false
+        when "nil" then nil
+        else value
+        end
+      end
+    end
+  end
+end

data/lib/capistrano/cli/ui.rb

@@ -0,0 +1,40 @@
+require 'highline'
+
+# work around problem where HighLine detects an eof on $stdin and raises an
+# error.
+HighLine.track_eof = false
+
+module Capistrano
+  class CLI
+    module UI
+      def self.included(base) #:nodoc:
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods
+        # Return the object that provides UI-specific methods, such as prompts
+        # and more.
+        def ui
+          @ui ||= HighLine.new
+        end
+
+        # Prompt for a password using echo suppression.
+        def password_prompt(prompt="Password: ")
+          ui.ask(prompt) { |q| q.echo = false }
+        end
+        
+        # Debug mode prompt
+        def debug_prompt(cmd)
+          ui.say("Preparing to execute command: #{cmd}")
+          prompt = "Execute ([Yes], No, Abort) "
+          ui.ask("#{prompt}?  ") do |q|
+            q.overwrite = false
+            q.default = 'y'
+            q.validate = /(y(es)?)|(no?)|(a(bort)?|\n)/i
+            q.responses[:not_valid] = prompt
+          end
+        end
+      end
+    end
+  end
+end

data/lib/capistrano/cli.rb

@@ -0,0 +1,47 @@
+require 'capistrano'
+require 'capistrano/cli/execute'
+require 'capistrano/cli/help'
+require 'capistrano/cli/options'
+require 'capistrano/cli/ui'
+
+module Capistrano
+  # The CLI class encapsulates the behavior of capistrano when it is invoked
+  # as a command-line utility. This allows other programs to embed Capistrano
+  # and preserve its command-line semantics.
+  class CLI
+    # The array of (unparsed) command-line options
+    attr_reader :args
+
+    # Create a new CLI instance using the given array of command-line parameters
+    # to initialize it. By default, +ARGV+ is used, but you can specify a
+    # different set of parameters (such as when embedded cap in a program):
+    #
+    #   require 'capistrano/cli'
+    #   Capistrano::CLI.parse(%w(-vvvv -r config/deploy update_code)).execute!
+    #
+    # Note that you can also embed cap directly by creating a new Configuration
+    # instance and setting it up, but you'll often wind up duplicating logic
+    # defined in the CLI class. The above snippet, redone using the Configuration
+    # class directly, would look like:
+    #
+    #   require 'capistrano'
+    #   require 'capistrano/cli'
+    #   config = Capistrano::Configuration.new
+    #   config.logger_level = Capistrano::Logger::TRACE
+    #   config.set(:password) { Capistrano::CLI.password_prompt }
+    #   config.load "config/deploy"
+    #   config.update_code
+    #
+    # There may be times that you want/need the additional control offered by
+    # manipulating the Configuration directly, but generally interfacing with
+    # the CLI class is recommended.
+    def initialize(args)
+      @args = args.dup
+      $stdout.sync = true # so that Net::SSH prompts show up
+    end
+
+    # Mix-in the actual behavior
+    include Execute, Options, UI
+    include Help # needs to be included last, because it overrides some methods
+  end
+end

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/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