capistrano 1.4.2 → 2.0.0

data/lib/capistrano/task_definition.rb

@@ -0,0 +1,69 @@
+require 'capistrano/server_definition'
+
+module Capistrano
+  # Represents the definition of a single task.
+  class TaskDefinition
+    attr_reader :name, :namespace, :options, :body, :desc, :on_error
+
+    def initialize(name, namespace, options={}, &block)
+      @name, @namespace, @options = name, namespace, options
+      @desc = @options.delete(:desc)
+      @on_error = options.delete(:on_error)
+      @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

data/lib/capistrano/upload.rb

@@ -0,0 +1,146 @@
+require 'net/sftp'
+require 'net/sftp/operations/errors'
+require 'capistrano/errors'
+
+module Capistrano
+  unless ENV['SKIP_VERSION_CHECK']
+    require 'capistrano/version' 
+    require 'net/sftp/version'
+    sftp_version = [Net::SFTP::Version::MAJOR, Net::SFTP::Version::MINOR, Net::SFTP::Version::TINY]
+    required_version = [1,1,0]
+    if !Capistrano::Version.check(required_version, sftp_version)
+      raise "You have Net::SFTP #{sftp_version.join(".")}, but you need at least #{required_version.join(".")}. Net::SFTP will not be used."
+    end
+  end
+
+  # This class encapsulates a single file upload to be performed in parallel
+  # across multiple machines, using the SFTP protocol. Although it is intended
+  # to be used primarily from within Capistrano, it may also be used standalone
+  # if you need to simply upload a file to multiple servers.
+  #
+  # Basic Usage:
+  #
+  #   begin
+  #     uploader = Capistrano::Upload.new(sessions, "remote-file.txt",
+  #         :data => "the contents of the file to upload")
+  #     uploader.process!
+  #   rescue Capistrano::UploadError => e
+  #     warn "Could not upload the file: #{e.message}"
+  #   end
+  class Upload
+    def self.process(sessions, filename, options)
+      new(sessions, filename, options).process!
+    end
+  
+    attr_reader :sessions, :filename, :options
+    attr_reader :failed, :completed
+
+    # Creates and prepares a new Upload instance. The +sessions+ parameter
+    # must be an array of open Net::SSH sessions. The +filename+ is the name
+    # (including path) of the destination file on the remote server. The
+    # +options+ hash accepts the following keys (as symbols):
+    #
+    # * data: required. Should refer to a String containing the contents of
+    #   the file to upload.
+    # * mode: optional. The "mode" of the destination file. Defaults to 0660.
+    # * logger: optional. Should point to a Capistrano::Logger instance, if
+    #   given.
+    def initialize(sessions, filename, options)
+      raise ArgumentError, "you must specify the data to upload via the :data option" unless options[:data]
+
+      @sessions = sessions
+      @filename = filename
+      @options  = options
+
+      @completed = @failed = 0
+      @sftps = setup_sftp
+    end
+    
+    # Uploads to all specified servers in parallel. If any one of the servers
+    # fails, an exception will be raised (UploadError).
+    def process!
+      logger.debug "uploading #{filename}" if logger
+      while running?
+        @sftps.each do |sftp|
+          next if sftp.channel[:done]
+          begin
+            sftp.channel.connection.process(true)
+          rescue Net::SFTP::Operations::StatusException => error
+            logger.important "uploading failed: #{error.description}", sftp.channel[:server] if logger
+            failed!(sftp)
+          end
+        end
+        sleep 0.01 # a brief respite, to keep the CPU from going crazy
+      end
+      logger.trace "upload finished" if logger
+
+      if (failed = @sftps.select { |sftp| sftp.channel[:failed] }).any?
+        hosts = failed.map { |sftp| sftp.channel[:server] }
+        error = UploadError.new("upload of #{filename} failed on #{hosts.join(',')}")
+        error.hosts = hosts
+        raise error
+      end
+
+      self
+    end
+
+    private
+
+      def logger
+        options[:logger]
+      end
+
+      def setup_sftp
+        sessions.map do |session|
+          server = session.xserver
+          sftp = session.sftp
+          sftp.connect unless sftp.state == :open
+
+          sftp.channel[:server] = server
+          sftp.channel[:done] = false
+          sftp.channel[:failed] = false
+
+          real_filename = filename.gsub(/\$CAPISTRANO:HOST\$/, server.host)
+          sftp.open(real_filename, IO::WRONLY | IO::CREAT | IO::TRUNC, options[:mode] || 0660) do |status, handle|
+            break unless check_status(sftp, "open #{real_filename}", server, status)
+            
+            logger.info "uploading data to #{server}:#{real_filename}" if logger
+            sftp.write(handle, options[:data] || "") do |status|
+              break unless check_status(sftp, "write to #{server}:#{real_filename}", server, status)
+              sftp.close_handle(handle) do
+                logger.debug "done uploading data to #{server}:#{real_filename}" if logger
+                completed!(sftp)
+              end
+            end
+          end
+          
+          sftp
+        end
+      end
+      
+      def check_status(sftp, action, server, status)
+        return true if status.code == Net::SFTP::Session::FX_OK
+
+        logger.error "could not #{action} on #{server} (#{status.message})" if logger
+        failed!(sftp)
+
+        return false
+      end
+
+      def running?
+        completed < @sftps.length
+      end
+
+      def failed!(sftp)
+        completed!(sftp)
+        @failed += 1
+        sftp.channel[:failed] = true
+      end
+
+      def completed!(sftp)
+        @completed += 1
+        sftp.channel[:done] = true
+      end
+  end
+
+end

data/lib/capistrano/version.rb

@@ -1,26 +1,22 @@
 module Capistrano
   module Version #:nodoc:
-    # A method for comparing versions of required modules. It expects
-    # arrays as parameters, and returns true if the first is no less than the
-    # second, and strictly less than the third.
-    def self.check(actual, minimum, maximum) #:nodoc:
-      actual = actual[0] * 1_000_000 + actual[1] * 1_000 + actual[2]
-      minimum = minimum[0] * 1_000_000 + minimum[1] * 1_000 + minimum[2]
-      maximum = maximum[0] * 1_000_000 + maximum[1] * 1_000 + maximum[2]
-
-      return actual >= minimum && actual < maximum
+    # A method for comparing versions of required modules. It expects two
+    # arrays of integers as parameters, the first being the minimum version
+    # required, and the second being the actual version available. It returns
+    # true if the actual version is at least equal to the required version.
+    def self.check(required, actual) #:nodoc:
+      required = required.map { |v| "%06d" % v }.join(".")
+      actual   = actual.map { |v| "%06d" % v }.join(".")
+      return actual >= required
     end
 
-    MAJOR = 1
-    MINOR = 4
-    TINY  = 2
+    MAJOR = 2
+    MINOR = 0
+    TINY  = 0
 
     STRING = [MAJOR, MINOR, TINY].join(".")
     
-    MINIMUM_SSH_REQUIRED  = [1,0,10]
-    MAXIMUM_SSH_REQUIRED  = [1,99,0]
-
-    MINIMUM_SFTP_REQUIRED = [1,1,0]
-    MAXIMUM_SFTP_REQUIRED = [1,99,0]
+    SSH_REQUIRED = [1,0,10]
+    SFTP_REQUIRED = [1,1,0]
   end
 end

data/test/cli/execute_test.rb

@@ -0,0 +1,132 @@
+require "#{File.dirname(__FILE__)}/../utils"
+require 'capistrano/cli/execute'
+
+class CLIExecuteTest < Test::Unit::TestCase
+  class MockCLI
+    attr_reader :options
+
+    def initialize
+      @options = {}
+    end
+
+    include Capistrano::CLI::Execute
+  end
+
+  def setup
+    @cli = MockCLI.new
+    @logger = stub_everything
+    @config = stub(:logger => @logger)
+    @config.stubs(:set)
+    @config.stubs(:load)
+    @config.stubs(:trigger)
+    @cli.stubs(:instantiate_configuration).returns(@config)
+  end
+
+  def test_execute_should_set_logger_verbosity
+    @cli.options[:verbose] = 7
+    @logger.expects(:level=).with(7)
+    @cli.execute!
+  end
+
+  def test_execute_should_set_password
+    @cli.options[:password] = "nosoup4u"
+    @config.expects(:set).with(:password, "nosoup4u")
+    @cli.execute!
+  end
+
+  def test_execute_should_set_prevars_before_loading
+    @config.expects(:load).never
+    @config.expects(:set).with(:stage, "foobar")
+    @config.expects(:load).with("standard")
+    @cli.options[:pre_vars] = { :stage => "foobar" }
+    @cli.execute!
+  end
+
+  def test_execute_should_load_sysconf_if_sysconf_set_and_exists
+    @cli.options[:sysconf] = "/etc/capistrano.conf"
+    @config.expects(:load).with("/etc/capistrano.conf")
+    File.expects(:file?).with("/etc/capistrano.conf").returns(true)
+    @cli.execute!
+  end
+
+  def test_execute_should_not_load_sysconf_when_sysconf_set_and_not_exists
+    @cli.options[:sysconf] = "/etc/capistrano.conf"
+    File.expects(:file?).with("/etc/capistrano.conf").returns(false)
+    @cli.execute!
+  end
+
+  def test_execute_should_load_dotfile_if_dotfile_set_and_exists
+    @cli.options[:dotfile] = "/home/jamis/.caprc"
+    @config.expects(:load).with("/home/jamis/.caprc")
+    File.expects(:file?).with("/home/jamis/.caprc").returns(true)
+    @cli.execute!
+  end
+
+  def test_execute_should_not_load_dotfile_when_dotfile_set_and_not_exists
+    @cli.options[:dotfile] = "/home/jamis/.caprc"
+    File.expects(:file?).with("/home/jamis/.caprc").returns(false)
+    @cli.execute!
+  end
+
+  def test_execute_should_load_recipes_when_recipes_are_given
+    @cli.options[:recipes] = %w(config/deploy path/to/extra)
+    @config.expects(:load).with("config/deploy")
+    @config.expects(:load).with("path/to/extra")
+    @cli.execute!
+  end
+
+  def test_execute_should_set_vars_and_execute_tasks
+    @cli.options[:vars] = { :foo => "bar", :baz => "bang" }
+    @cli.options[:actions] = %w(first second)
+    @config.expects(:set).with(:foo, "bar")
+    @config.expects(:set).with(:baz, "bang")
+    @config.expects(:find_and_execute_task).with("first", :before => :start, :after => :finish)
+    @config.expects(:find_and_execute_task).with("second", :before => :start, :after => :finish)
+    @cli.execute!
+  end
+
+  def test_execute_should_call_load_and_exit_triggers
+    @cli.options[:actions] = %w(first second)
+    @config.expects(:find_and_execute_task).with("first", :before => :start, :after => :finish)
+    @config.expects(:find_and_execute_task).with("second", :before => :start, :after => :finish)
+    @config.expects(:trigger).never
+    @config.expects(:trigger).with(:load)
+    @config.expects(:trigger).with(:exit)
+    @cli.execute!
+  end
+
+  def test_execute_should_call_handle_error_when_exceptions_occur
+    @config.expects(:load).raises(Exception, "boom")
+    @cli.expects(:handle_error).with { |e,| Exception === e }
+    @cli.execute!
+  end
+
+  def test_execute_should_return_config_instance
+    assert_equal @config, @cli.execute!
+  end
+
+  def test_instantiate_configuration_should_return_new_configuration_instance
+    assert_instance_of Capistrano::Configuration, MockCLI.new.instantiate_configuration
+  end
+
+  def test_handle_error_with_auth_error_should_abort_with_message_including_user_name
+    @cli.expects(:abort).with { |s| s.include?("jamis") }
+    @cli.handle_error(Net::SSH::AuthenticationFailed.new("jamis"))
+  end
+
+  def test_handle_error_with_cap_error_should_abort_with_message
+    @cli.expects(:abort).with("Wish you were here")
+    @cli.handle_error(Capistrano::Error.new("Wish you were here"))
+  end
+
+  def test_handle_error_with_other_errors_should_reraise_error
+    other_error = Class.new(RuntimeError)
+    assert_raises(other_error) { @cli.handle_error(other_error.new("boom")) }
+  end
+
+  def test_class_execute_method_should_call_parse_and_execute_with_ARGV
+    cli = mock(:execute! => nil)
+    MockCLI.expects(:parse).with(ARGV).returns(cli)
+    MockCLI.execute
+  end
+end

data/test/cli/help_test.rb

@@ -0,0 +1,139 @@
+require "#{File.dirname(__FILE__)}/../utils"
+require 'capistrano/cli/help'
+
+class CLIHelpTest < Test::Unit::TestCase
+  class MockCLI
+    attr_reader :options, :called_original
+
+    def initialize
+      @options = {}
+      @called_original = false
+    end
+
+    def execute_requested_actions(config)
+      @called_original = config
+    end
+
+    include Capistrano::CLI::Help
+  end
+
+  def setup
+    @cli = MockCLI.new
+    @cli.options[:verbose] = 0
+    @ui = stub("ui", :output_cols => 80, :output_rows => 20, :page_at= => nil)
+    MockCLI.stubs(:ui).returns(@ui)
+  end
+
+  def test_execute_requested_actions_without_tasks_or_explain_should_call_original
+    @cli.execute_requested_actions(:config)
+    @cli.expects(:task_list).never
+    @cli.expects(:explain_task).never
+    assert_equal :config, @cli.called_original
+  end
+
+  def test_execute_requested_actions_with_tasks_should_call_task_list
+    @cli.options[:tasks] = true
+    @cli.expects(:task_list).with(:config)
+    @cli.expects(:explain_task).never
+    @cli.execute_requested_actions(:config)
+    assert !@cli.called_original
+  end
+
+  def test_execute_requested_actions_with_explain_should_call_explain_task
+    @cli.options[:explain] = "deploy_with_niftiness"
+    @cli.expects(:task_list).never
+    @cli.expects(:explain_task).with(:config, "deploy_with_niftiness")
+    @cli.execute_requested_actions(:config)
+    assert !@cli.called_original
+  end
+
+  def test_task_list_with_no_tasks_should_emit_warning
+    config = mock("config", :task_list => [])
+    @cli.expects(:warn)
+    @cli.task_list(config)
+  end
+
+  def test_task_list_should_query_all_tasks_in_all_namespaces
+    expected_max_len = 80 - 3 - MockCLI::LINE_PADDING
+    task_list = [task("c"), task("g", "c:g"), task("b", "c:b"), task("a")]
+    task_list.each { |t| t.expects(:brief_description).with(expected_max_len).returns(t.fully_qualified_name) }
+  
+    config = mock("config")
+    config.expects(:task_list).with(:all).returns(task_list)
+    @cli.stubs(:puts)
+    @cli.task_list(config)
+  end
+
+  def test_task_list_should_never_use_less_than_MIN_MAX_LEN_chars_for_descriptions
+    @ui.stubs(:output_cols).returns(20)
+    t = task("c")
+    t.expects(:brief_description).with(30).returns("hello")
+    config = mock("config", :task_list => [t])
+    @cli.stubs(:puts)
+    @cli.task_list(config)
+  end
+
+  def test_task_list_should_not_include_tasks_with_blank_description_or_internal_by_default
+    t1 = task("c")
+    t1.expects(:brief_description).returns("hello")
+    t2 = task("d", "d", "[internal] howdy")
+    t2.expects(:brief_description).never
+    t3 = task("e", "e", "")
+    t3.expects(:brief_description).never
+
+    config = mock("config", :task_list => [t1, t2, t3])
+    @cli.stubs(:puts)
+    @cli.expects(:puts).never.with { |s,| (s || "").include?("[internal]") || s =~ /#\s*$/ }
+    @cli.task_list(config)
+  end
+
+  def test_task_list_should_include_tasks_with_blank_descriptions_and_internal_when_verbose
+    t1 = task("c")
+    t1.expects(:brief_description).returns("hello")
+    t2 = task("d", "d", "[internal] howdy")
+    t2.expects(:brief_description).returns("[internal] howdy")
+    t3 = task("e", "e", "")
+    t3.expects(:brief_description).returns("")
+
+    config = mock("config", :task_list => [t1, t2, t3])
+    @cli.options[:verbose] = 1
+    @cli.stubs(:puts)
+    @cli.expects(:puts).with { |s,| (s || "").include?("[internal]") || s =~ /#\s*$/ }.at_least_once
+    @cli.task_list(config)
+  end
+
+  def test_explain_task_should_warn_if_task_does_not_exist
+    config = mock("config", :find_task => nil)
+    @cli.expects(:warn).with { |s,| s =~ /`deploy_with_niftiness'/ }
+    @cli.explain_task(config, "deploy_with_niftiness")
+  end
+
+  def test_explain_task_with_task_that_has_no_description_should_emit_stub
+    t = mock("task", :description => "")
+    config = mock("config")
+    config.expects(:find_task).with("deploy_with_niftiness").returns(t)
+    @cli.stubs(:puts)
+    @cli.expects(:puts).with("There is no description for this task.")
+    @cli.explain_task(config, "deploy_with_niftiness")
+  end
+
+  def test_explain_task_with_task_should_format_description
+    t = stub("task", :description => "line1\nline2\n\nline3")
+    config = mock("config", :find_task => t)
+    @cli.stubs(:puts)
+    @cli.explain_task(config, "deploy_with_niftiness")
+  end
+
+  def test_long_help_should_load_and_format_help_txt_file
+    File.expects(:dirname).returns "a/b/c"
+    File.expects(:read).with("a/b/c/help.txt").returns("text")
+    @ui.expects(:say).with("text\n")
+    @cli.long_help
+  end
+
+  private
+
+    def task(name, fqn=name, desc="a description")
+      stub("task", :name => name, :fully_qualified_name => fqn, :description => desc)
+    end
+end