mbailey-capistrano 2.5.5

data/lib/capistrano/role.rb

@@ -0,0 +1,102 @@
+module Capistrano
+  class Role
+    include Enumerable
+
+    def initialize(*list)
+      @static_servers = []
+      @dynamic_servers = []
+      push(*list)
+    end
+
+    def each(&block)
+      servers.each &block
+    end
+
+    def push(*list)
+      options = list.last.is_a?(Hash) ? list.pop : {}
+      list.each do |item|
+        if item.respond_to?(:call)
+          @dynamic_servers << DynamicServerList.new(item, options)
+        else
+          @static_servers << self.class.wrap_server(item, options)
+        end
+      end
+    end
+    alias_method :<<, :push
+
+    def servers
+      @static_servers + dynamic_servers
+    end
+    alias_method :to_ary, :servers
+
+    def empty?
+      servers.empty?
+    end
+
+    def clear
+      @dynamic_servers.clear
+      @static_servers.clear
+    end
+
+    def include?(server)
+      servers.include?(server)
+    end
+
+    protected
+
+    # This is the combination of a block, a hash of options, and a cached value.
+    class DynamicServerList
+      def initialize (block, options)
+        @block = block
+        @options = options
+        @cached = []
+        @is_cached = false
+      end
+
+      # Convert to a list of ServerDefinitions
+      def to_ary
+        unless @is_cached
+          @cached = Role::wrap_list(@block.call(@options), @options)
+          @is_cached = true
+        end
+        @cached
+      end
+
+      # Clear the cached value
+      def reset!
+        @cached.clear
+        @is_cached = false
+      end
+    end
+
+    # Attribute reader for the cached results of executing the blocks in turn
+    def dynamic_servers
+      @dynamic_servers.inject([]) { |list, item| list.concat item }
+    end
+
+    # Wraps a string in a ServerDefinition, if it isn't already.
+    # This and wrap_list should probably go in ServerDefinition in some form.
+    def self.wrap_server (item, options)
+      item.is_a?(ServerDefinition) ? item : ServerDefinition.new(item, options)
+    end
+
+    # Turns a list, or something resembling a list, into a properly-formatted
+    # ServerDefinition list. Keep an eye on this one -- it's entirely too
+    # magical for its own good. In particular, if ServerDefinition ever inherits
+    # from Array, this will break.
+    def self.wrap_list (*list)
+      options = list.last.is_a?(Hash) ? list.pop : {}
+      if list.length == 1
+        if list.first.nil?
+          return []
+        elsif list.first.is_a?(Array)
+          list = list.first
+        end
+      end
+      options.merge! list.pop if list.last.is_a?(Hash)
+      list.map do |item|
+        self.wrap_server item, options
+      end
+    end
+  end
+end

data/lib/capistrano/server_definition.rb

@@ -0,0 +1,56 @@
+module Capistrano
+  class ServerDefinition
+    include Comparable
+
+    attr_reader :host
+    attr_reader :user
+    attr_reader :port
+    attr_reader :options
+
+    # The default user name to use when a user name is not explicitly provided
+    def self.default_user
+      ENV['USER'] || ENV['USERNAME'] || "not-specified"
+    end
+
+    def initialize(string, options={})
+      @user, @host, @port = string.match(/^(?:([^;,:=]+)@|)(.*?)(?::(\d+)|)$/)[1,3]
+
+      @options = options.dup
+      user_opt, port_opt = @options.delete(:user), @options.delete(:port)
+
+      @user ||= user_opt
+      @port ||= port_opt
+
+      @port = @port.to_i if @port
+    end
+
+    def <=>(server)
+      [host, port, user] <=> [server.host, server.port, server.user]
+    end
+
+    # Redefined, so that Array#uniq will work to remove duplicate server
+    # definitions, based solely on their host names.
+    def eql?(server)
+      host == server.host &&
+        user == server.user &&
+        port == server.port
+    end
+
+    alias :== :eql?
+
+    # Redefined, so that Array#uniq will work to remove duplicate server
+    # definitions, based on their connection information.
+    def hash
+      @hash ||= [host, user, port].hash
+    end
+
+    def to_s
+      @to_s ||= begin
+        s = host
+        s = "#{user}@#{s}" if user
+        s = "#{s}:#{port}" if port && port != 22
+        s
+      end
+    end
+  end
+end

data/lib/capistrano/shell.rb

@@ -0,0 +1,260 @@
+require 'thread'
+require 'capistrano/processable'
+
+module Capistrano
+  # The Capistrano::Shell class is the guts of the "shell" task. It implements
+  # an interactive REPL interface that users can employ to execute tasks and
+  # commands. It makes for a GREAT way to monitor systems, and perform quick
+  # maintenance on one or more machines.
+  class Shell
+    include Processable
+
+    # A Readline replacement for platforms where readline is either
+    # unavailable, or has not been installed.
+    class ReadlineFallback #:nodoc:
+      HISTORY = []
+
+      def self.readline(prompt)
+        STDOUT.print(prompt)
+        STDOUT.flush
+        STDIN.gets
+      end
+    end
+
+    # The configuration instance employed by this shell
+    attr_reader :configuration
+
+    # Instantiate a new shell and begin executing it immediately.
+    def self.run(config)
+      new(config).run!
+    end
+
+    # Instantiate a new shell
+    def initialize(config)
+      @configuration = config
+    end
+
+    # Start the shell running. This method will block until the shell
+    # terminates.
+    def run!
+      setup
+
+      puts <<-INTRO
+====================================================================
+Welcome to the interactive Capistrano shell! This is an experimental
+feature, and is liable to change in future releases. Type 'help' for
+a summary of how to use the shell.
+--------------------------------------------------------------------
+INTRO
+
+      loop do
+        break if !read_and_execute
+      end
+
+      @bgthread.kill
+    end
+
+    def read_and_execute
+      command = read_line
+
+      case command
+        when "?", "help" then help
+        when "quit", "exit" then
+          puts "exiting"
+          return false
+        when /^set -(\w)\s*(\S+)/
+          set_option($1, $2)
+        when /^(?:(with|on)\s*(\S+))?\s*(\S.*)?/i
+          process_command($1, $2, $3)
+        else
+          raise "eh?"
+      end
+
+      return true
+    end
+
+    private
+
+      # Present the prompt and read a single line from the console. It also
+      # detects ^D and returns "exit" in that case. Adds the input to the
+      # history, unless the input is empty. Loops repeatedly until a non-empty
+      # line is input.
+      def read_line
+        loop do
+          command = reader.readline("cap> ")
+
+          if command.nil?
+            command = "exit"
+            puts(command)
+          else
+            command.strip!
+          end
+
+          unless command.empty?
+            reader::HISTORY << command
+            return command
+          end
+        end
+      end
+
+      # Display a verbose help message.
+      def help
+        puts <<-HELP
+--- HELP! ---------------------------------------------------
+"Get me out of this thing. I just want to quit."
+-> Easy enough. Just type "exit", or "quit". Or press ctrl-D.
+
+"I want to execute a command on all servers."
+-> Just type the command, and press enter. It will be passed,
+   verbatim, to all defined servers.
+
+"What if I only want it to execute on a subset of them?"
+-> No problem, just specify the list of servers, separated by
+   commas, before the command, with the `on' keyword:
+
+   cap> on app1.foo.com,app2.foo.com echo ping
+
+"Nice, but can I specify the servers by role?"
+-> You sure can. Just use the `with' keyword, followed by the
+   comma-delimited list of role names:
+
+   cap> with app,db echo ping
+
+"Can I execute a Capistrano task from within this shell?"
+-> Yup. Just prefix the task with an exclamation mark:
+
+   cap> !deploy
+HELP
+      end
+
+      # Determine which servers the given task requires a connection to, and
+      # establish connections to them if necessary. Return the list of
+      # servers (names).
+      def connect(task)
+        servers = configuration.find_servers_for_task(task)
+        needing_connections = servers - configuration.sessions.keys
+        unless needing_connections.empty?
+          puts "[establishing connection(s) to #{needing_connections.join(', ')}]"
+          configuration.establish_connections_to(needing_connections)
+        end
+        servers
+      end
+
+      # Execute the given command. If the command is prefixed by an exclamation
+      # mark, it is assumed to refer to another capistrano task, which will
+      # be invoked. Otherwise, it is executed as a command on all associated
+      # servers.
+      def exec(command)
+        @mutex.synchronize do
+          if command[0] == ?!
+            exec_tasks(command[1..-1].split)
+          else
+            servers = connect(configuration.current_task)
+            exec_command(command, servers)
+          end
+        end
+      ensure
+        STDOUT.flush
+      end
+
+      # Given an array of task names, invoke them in sequence.
+      def exec_tasks(list)
+        list.each do |task_name|
+          task = configuration.find_task(task_name)
+          raise Capistrano::NoSuchTaskError, "no such task `#{task_name}'" unless task
+          connect(task)
+          configuration.execute_task(task)
+        end
+      rescue Capistrano::NoMatchingServersError, Capistrano::NoSuchTaskError => error
+        warn "error: #{error.message}"
+      end
+
+      # Execute a command on the given list of servers.
+      def exec_command(command, servers)
+        command = command.gsub(/\bsudo\b/, "sudo -p '#{configuration.sudo_prompt}'")
+        processor = configuration.sudo_behavior_callback(Configuration.default_io_proc)
+        sessions = servers.map { |server| configuration.sessions[server] }
+        options = configuration.add_default_command_options({})
+        cmd = Command.new(command, sessions, options.merge(:logger => configuration.logger), &processor)
+        previous = trap("INT") { cmd.stop! }
+        cmd.process!
+      rescue Capistrano::Error => error
+        warn "error: #{error.message}"
+      ensure
+        trap("INT", previous)
+      end
+
+      # Return the object that will be used to query input from the console.
+      # The returned object will quack (more or less) like Readline.
+      def reader
+        @reader ||= begin
+          require 'readline'
+          Readline
+        rescue LoadError
+          ReadlineFallback
+        end
+      end
+
+      # Prepare every little thing for the shell. Starts the background
+      # thread and generally gets things ready for the REPL.
+      def setup
+        configuration.logger.level = Capistrano::Logger::INFO
+
+        @mutex = Mutex.new
+        @bgthread = Thread.new do
+          loop do
+            @mutex.synchronize { process_iteration(0.1) }
+          end
+        end
+      end
+
+      # Set the given option to +value+.
+      def set_option(opt, value)
+        case opt
+          when "v" then
+            puts "setting log verbosity to #{value.to_i}"
+            configuration.logger.level = value.to_i
+          when "o" then
+            case value
+            when "vi" then
+              puts "using vi edit mode"
+              reader.vi_editing_mode
+            when "emacs" then
+              puts "using emacs edit mode"
+              reader.emacs_editing_mode
+            else
+              puts "unknown -o option #{value.inspect}"
+            end
+          else
+            puts "unknown setting #{opt.inspect}"
+        end
+      end
+
+      # Process a command. Interprets the scope_type (must be nil, "with", or
+      # "on") and the command. If no command is given, then the scope is made
+      # effective for all subsequent commands. If the scope value is "all",
+      # then the scope is unrestricted.
+      def process_command(scope_type, scope_value, command)
+        env_var = case scope_type
+            when "with" then "ROLES"
+            when "on"   then "HOSTS"
+          end
+
+        old_var, ENV[env_var] = ENV[env_var], (scope_value == "all" ? nil : scope_value) if env_var
+        if command
+          begin
+            exec(command)
+          ensure
+            ENV[env_var] = old_var if env_var
+          end
+        else
+          puts "scoping #{scope_type} #{scope_value}"
+        end
+      end
+    end
+
+    # All open sessions, needed to satisfy the Command::Processable include
+    def sessions
+      configuration.sessions.values
+    end
+end

data/lib/capistrano/ssh.rb

@@ -0,0 +1,99 @@
+begin
+  require 'rubygems'
+  gem 'net-ssh', ">= 2.0.10"
+rescue LoadError, NameError
+end
+
+require 'net/ssh'
+
+module Capistrano
+  # A helper class for dealing with SSH connections.
+  class SSH
+    # Patch an accessor onto an SSH connection so that we can record the server
+    # definition object that defines the connection. This is useful because
+    # the gateway returns connections whose "host" is 127.0.0.1, instead of
+    # the host on the other side of the tunnel.
+    module Server #:nodoc:
+      def self.apply_to(connection, server)
+        connection.extend(Server)
+        connection.xserver = server
+        connection
+      end
+
+      attr_accessor :xserver
+    end
+
+    # An abstraction to make it possible to connect to the server via public key
+    # without prompting for the password. If the public key authentication fails
+    # this will fall back to password authentication.
+    #
+    # +server+ must be an instance of ServerDefinition.
+    #
+    # If a block is given, the new session is yielded to it, otherwise the new
+    # session is returned.
+    #
+    # If an :ssh_options key exists in +options+, it is passed to the Net::SSH
+    # constructor. Values in +options+ are then merged into it, and any
+    # connection information in +server+ is added last, so that +server+ info
+    # takes precedence over +options+, which takes precendence over ssh_options.
+    def self.connect(server, options={})
+      connection_strategy(server, options) do |host, user, connection_options|
+        connection = Net::SSH.start(host, user, connection_options)
+        Server.apply_to(connection, server)
+      end
+    end
+
+    # Abstracts the logic for establishing an SSH connection (which includes
+    # testing for connection failures and retrying with a password, and so forth,
+    # mostly made complicated because of the fact that some of these variables
+    # might be lazily evaluated and try to do something like prompt the user,
+    # which should only happen when absolutely necessary.
+    #
+    # This will yield the hostname, username, and a hash of connection options
+    # to the given block, which should return a new connection.
+    def self.connection_strategy(server, options={}, &block)
+      methods = [ %w(publickey hostbased), %w(password keyboard-interactive) ]
+      password_value = nil
+
+      # construct the hash of ssh options that should be passed more-or-less
+      # directly to Net::SSH. This will be the general ssh options, merged with
+      # the server-specific ssh-options.
+      ssh_options = (options[:ssh_options] || {}).merge(server.options[:ssh_options] || {})
+
+      # load any SSH configuration files that were specified in the SSH options. This
+      # will load from ~/.ssh/config and /etc/ssh_config by default (see Net::SSH
+      # for details). Merge the explicitly given ssh_options over the top of the info
+      # from the config file.
+      ssh_options = Net::SSH.configuration_for(server.host, ssh_options.fetch(:config, true)).merge(ssh_options)
+
+      # Once we've loaded the config, we don't need Net::SSH to do it again.
+      ssh_options[:config] = false
+
+      user = server.user || options[:user] || ssh_options[:username] ||
+             ssh_options[:user] || ServerDefinition.default_user
+      port = server.port || options[:port] || ssh_options[:port]
+
+      # the .ssh/config file might have changed the host-name on us
+      host = ssh_options.fetch(:host_name, server.host) 
+
+      ssh_options[:port] = port if port
+
+      # delete these, since we've determined which username to use by this point
+      ssh_options.delete(:username)
+      ssh_options.delete(:user)
+
+      begin
+        connection_options = ssh_options.merge(
+          :password => password_value,
+          :auth_methods => ssh_options[:auth_methods] || methods.shift
+        )
+
+        yield host, user, connection_options
+      rescue Net::SSH::AuthenticationFailed
+        raise if methods.empty? || ssh_options[:auth_methods]
+        password_value = options[:password]
+        retry
+      end
+    end
+  end
+end

data/lib/capistrano/task_definition.rb

@@ -0,0 +1,70 @@
+require 'capistrano/server_definition'
+
+module Capistrano
+  # Represents the definition of a single task.
+  class TaskDefinition
+    attr_reader :name, :namespace, :options, :body, :desc, :on_error, :max_hosts
+
+    def initialize(name, namespace, options={}, &block)
+      @name, @namespace, @options = name, namespace, options
+      @desc = @options.delete(:desc)
+      @on_error = options.delete(:on_error)
+      @max_hosts = options[:max_hosts] && options[:max_hosts].to_i
+      @body = block or raise ArgumentError, "a task requires a block"
+      @servers = nil
+    end
+    
+    # Returns the task's fully-qualified name, including the namespace
+    def fully_qualified_name
+      @fully_qualified_name ||= begin
+        if namespace.default_task == self
+          namespace.fully_qualified_name
+        else
+          [namespace.fully_qualified_name, name].compact.join(":")
+        end
+      end
+    end
+
+    # Returns the description for this task, with newlines collapsed and
+    # whitespace stripped. Returns the empty string if there is no
+    # description for this task.
+    def description(rebuild=false)
+      @description = nil if rebuild
+      @description ||= begin
+        description = @desc || ""
+
+        indentation = description[/\A\s+/]
+        if indentation
+          reformatted_description = ""
+          description.strip.each_line do |line|
+            line = line.chomp.sub(/^#{indentation}/, "")
+            line = line.gsub(/#{indentation}\s*/, " ") if line[/^\S/]
+            reformatted_description << line << "\n"
+          end
+          description = reformatted_description
+        end
+
+        description.strip.gsub(/\r\n/, "\n")
+      end
+    end
+
+    # Returns the first sentence of the full description. If +max_length+ is
+    # given, the result will be truncated if it is longer than +max_length+,
+    # and an ellipsis appended.
+    def brief_description(max_length=nil)
+      brief = description[/^.*?\.(?=\s|$)/] || description
+
+      if max_length && brief.length > max_length
+        brief = brief[0,max_length-3] + "..."
+      end
+
+      brief
+    end
+
+    # Indicates whether the task wants to continue, even if a server has failed
+    # previously
+    def continue_on_error?
+      @on_error == :continue
+    end
+  end
+end