capistrano 1.4.2 → 2.0.0

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

@@ -0,0 +1,35 @@
+require 'capistrano/upload'
+
+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={})
+          execute_on_servers(options) do |servers|
+            targets = servers.map { |s| sessions[s] }
+            Upload.process(targets, path, :data => data, :mode => options[:mode], :logger => logger)
+          end
+        end
+    
+        # Get file remote_path from FIRST server targetted 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 = {})
+          execute_on_servers(options.merge(:once => true)) do |servers|
+            logger.info "downloading `#{servers.first.host}:#{remote_path}' to `#{path}'"
+            sftp = sessions[servers.first].sftp
+            sftp.connect unless sftp.state == :open
+            sftp.get_file remote_path, path
+            logger.debug "download finished" 
+          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 raise CaptureError, "error processing #{command.inspect}: #{data.inspect}"
+            end
+          end
+          output
+        end
+
+      end
+    end
+  end
+end

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

@@ -0,0 +1,127 @@
+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, {}
+        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.
+        def run(cmd, options={}, &block)
+          block ||= self.class.default_io_proc
+          logger.debug "executing #{cmd.strip.inspect}"
+
+          options = add_default_command_options(options)
+
+          execute_on_servers(options) do |servers|
+            targets = servers.map { |s| sessions[s] }
+            Command.process(cmd, targets, options.merge(:logger => logger), &block)
+          end
+        end
+
+        # Like #run, but executes the command via <tt>sudo</tt>. This assumes
+        # that the sudo password (if required) is the same as the password for
+        # logging in to the server.
+        #
+        # Also, this module accepts 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"
+        def sudo(command, options={}, &block)
+          block ||= self.class.default_io_proc
+
+          options = options.dup
+          as = options.delete(:as)
+
+          user = as && "-u #{as}"
+          command = [fetch(:sudo, "sudo"), user, command].compact.join(" ")
+
+          run(command, options, &sudo_behavior_callback(block))
+        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 =~ /password:/i
+              ch.send_data "#{self[:password]}\n"
+            elsif out =~ /try again/
+              if prompt_host.nil? || prompt_host == ch[:server]
+                prompt_host = ch[:server]
+                logger.important out, "#{stream} :: #{ch[:server]}"
+                reset! :password
+              end
+            else
+              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)
+          options = options.dup
+
+          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 if shell
+
+          options
+        end
+      end
+    end
+  end
+end

data/lib/capistrano/configuration/callbacks.rb

@@ -0,0 +1,148 @@
+require 'capistrano/callback'
+
+module Capistrano
+  class Configuration
+    module Callbacks
+      def self.included(base) #:nodoc:
+        %w(initialize execute_task).each do |method|
+          base.send :alias_method, "#{method}_without_callbacks", method
+          base.send :alias_method, method, "#{method}_with_callbacks"
+        end
+      end
+
+      # The hash of callbacks that have been registered for this configuration
+      attr_reader :callbacks
+
+      def initialize_with_callbacks(*args) #:nodoc:
+        initialize_without_callbacks(*args)
+        @callbacks = {}
+      end
+
+      def execute_task_with_callbacks(task) #:nodoc:
+        before = find_hook(task, :before)
+        execute_task(before) if before
+
+        trigger :before, task
+
+        result = execute_task_without_callbacks(task)
+
+        trigger :after, task
+
+        after = find_hook(task, :after)
+        execute_task(after) if after
+
+        return result
+      end
+
+      # Defines a callback to be invoked before the given task. You must
+      # specify the fully-qualified task name, both for the primary task, and
+      # for the task(s) to be executed before. Alternatively, you can pass a
+      # block to be executed before the given task.
+      #
+      #   before "deploy:update_code", :record_difference
+      #   before :deploy, "custom:log_deploy"
+      #   before :deploy, :this, "then:this", "and:then:this"
+      #   before :some_task do
+      #     puts "an anonymous hook!"
+      #   end
+      #
+      # This just provides a convenient interface to the more general #on method.
+      def before(task_name, *args, &block)
+        options = args.last.is_a?(Hash) ? args.pop : {}
+        args << options.merge(:only => task_name)
+        on :before, *args, &block
+      end
+
+      # Defines a callback to be invoked after the given task. You must
+      # specify the fully-qualified task name, both for the primary task, and
+      # for the task(s) to be executed after. Alternatively, you can pass a
+      # block to be executed after the given task.
+      #
+      #   after "deploy:update_code", :log_difference
+      #   after :deploy, "custom:announce"
+      #   after :deploy, :this, "then:this", "and:then:this"
+      #   after :some_task do
+      #     puts "an anonymous hook!"
+      #   end
+      #
+      # This just provides a convenient interface to the more general #on method.
+      def after(task_name, *args, &block)
+        options = args.last.is_a?(Hash) ? args.pop : {}
+        args << options.merge(:only => task_name)
+        on :after, *args, &block
+      end
+
+      # Defines one or more callbacks to be invoked in response to some event.
+      # Capistrano currently understands the following events:
+      #
+      # * :before, triggered before a task is invoked
+      # * :after, triggered after a task is invoked
+      # * :start, triggered before a top-level task is invoked via the command-line
+      # * :finish, triggered when a top-level task completes
+      # * :load, triggered after all recipes have loaded
+      # * :exit, triggered after all tasks have completed
+      #
+      # Specify the (fully-qualified) task names that you want invoked in
+      # response to the event. Alternatively, you can specify a block to invoke
+      # when the event is triggered. You can also pass a hash of options as the
+      # last parameter, which may include either of two keys:
+      #
+      # * :only, should specify an array of task names. Restricts this callback
+      #   so that it will only fire when the event applies to those tasks.
+      # * :except, should specify an array of task names. Restricts this callback
+      #   so that it will never fire when the event applies to those tasks.
+      #
+      # Usage:
+      #
+      #  on :before, "some:hook", "another:hook", :only => "deploy:update"
+      #  on :after, "some:hook", :except => "deploy:symlink"
+      #  on :before, "global:hook"
+      #  on :after, :only => :deploy do
+      #    puts "after deploy here"
+      #  end
+      def on(event, *args, &block)
+        options = args.last.is_a?(Hash) ? args.pop : {}
+        callbacks[event] ||= []
+
+        if args.empty? && block.nil?
+          raise ArgumentError, "please specify either a task name or a block to invoke"
+        elsif args.any? && block
+          raise ArgumentError, "please specify only a task name or a block, but not both"
+        elsif block
+          callbacks[event] << ProcCallback.new(block, options)
+        else
+          args.each do |name|
+            callbacks[event] << TaskCallback.new(self, name, options)
+          end
+        end
+      end
+
+      # Trigger the named event for the named task. All associated callbacks
+      # will be fired, in the order they were defined.
+      def trigger(event, task=nil)
+        pending = Array(callbacks[event]).select { |c| c.applies_to?(task) }
+        if pending.any?
+          msg = "triggering #{event} callbacks"
+          msg << " for `#{task.fully_qualified_name}'" if task
+          logger.trace(msg)
+          pending.each { |callback| callback.call }
+        end
+      end
+
+      private
+
+        # Looks for before_foo or after_foo tasks. This method of extending tasks
+        # is now discouraged (though not formally deprecated). You should use the
+        # before and after methods to declare hooks for such callbacks.
+        def find_hook(task, hook)
+          if task == task.namespace.default_task
+            result = task.namespace.search_task("#{hook}_#{task.namespace.name}")
+            return result if result
+          end
+
+          task.namespace.search_task("#{hook}_#{task.name}")
+        end
+
+    end
+  end
+end

data/lib/capistrano/configuration/connections.rb

@@ -0,0 +1,159 @@
+require 'capistrano/gateway'
+require 'capistrano/ssh'
+
+module Capistrano
+  class Configuration
+    module Connections
+      def self.included(base) #:nodoc:
+        base.send :alias_method, :initialize_without_connections, :initialize
+        base.send :alias_method, :initialize, :initialize_with_connections
+      end
+
+      # An adaptor for making the SSH interface look and act like that of the
+      # Gateway class.
+      class DefaultConnectionFactory #:nodoc:
+        def initialize(options)
+          @options = options
+        end
+
+        def connect_to(server)
+          SSH.connect(server, @options)
+        end
+      end
+
+      # A hash of the SSH sessions that are currently open and available.
+      # Because sessions are constructed lazily, this will only contain
+      # connections to those servers that have been the targets of one or more
+      # executed tasks.
+      attr_reader :sessions
+
+      def initialize_with_connections(*args) #:nodoc:
+        initialize_without_connections(*args)
+        @sessions = {}
+        @failed_sessions = []
+      end
+
+      # Indicate that the given server could not be connected to.
+      def failed!(server)
+        @failed_sessions << server
+      end
+
+      # Query whether previous connection attempts to the given server have
+      # failed.
+      def has_failed?(server)
+        @failed_sessions.include?(server)
+      end
+
+      # Used to force connections to be made to the current task's servers.
+      # Connections are normally made lazily in Capistrano--you can use this
+      # to force them open before performing some operation that might be
+      # time-sensitive.
+      def connect!(options={})
+        execute_on_servers(options) { }
+      end
+
+      # Returns the object responsible for establishing new SSH connections.
+      # The factory will respond to #connect_to, which can be used to
+      # establish connections to servers defined via ServerDefinition objects.
+      def connection_factory
+        @connection_factory ||= begin
+          if exists?(:gateway)
+            logger.debug "establishing connection to gateway `#{fetch(:gateway)}'"
+            Gateway.new(ServerDefinition.new(fetch(:gateway)), self)
+          else
+            DefaultConnectionFactory.new(self)
+          end
+        end
+      end
+
+      # Ensures that there are active sessions for each server in the list.
+      def establish_connections_to(servers)
+        failed_servers = []
+
+        # This attemps to work around the problem where SFTP uploads hang
+        # for some people. A bit of investigating seemed to reveal that the
+        # hang only occurred when the SSH connections were established async,
+        # so this setting allows people to at least work around the problem.
+        if fetch(:synchronous_connect, false)
+          logger.trace "synchronous_connect: true"
+          Array(servers).each { |server| safely_establish_connection_to(server, failed_servers) }
+        else
+          # force the connection factory to be instantiated synchronously,
+          # otherwise we wind up with multiple gateway instances, because
+          # each connection is done in parallel.
+          connection_factory
+
+          threads = Array(servers).map { |server| establish_connection_to(server, failed_servers) }
+          threads.each { |t| t.join }
+        end
+
+        if failed_servers.any?
+          errors = failed_servers.map { |h| "#{h[:server]} (#{h[:error].class}: #{h[:error].message})" }
+          error = ConnectionError.new("connection failed for: #{errors.join(', ')}")
+          error.hosts = failed_servers.map { |h| h[:server] }
+          raise error
+        end
+      end
+
+      # Determines the set of servers within the current task's scope and
+      # establishes connections to them, and then yields that list of
+      # servers.
+      def execute_on_servers(options={})
+        raise ArgumentError, "expected a block" unless block_given?
+
+        if task = current_task
+          servers = find_servers_for_task(task, options)
+
+          if servers.empty?
+            raise Capistrano::NoMatchingServersError, "`#{task.fully_qualified_name}' is only run for servers matching #{task.options.inspect}, but no servers matched"
+          end
+
+          if task.continue_on_error?
+            servers.delete_if { |s| has_failed?(s) }
+            return if servers.empty?
+          end
+        else
+          servers = find_servers(options)
+          raise Capistrano::NoMatchingServersError, "no servers found to match #{options.inspect}" if servers.empty?
+        end
+
+        servers = [servers.first] if options[:once]
+        logger.trace "servers: #{servers.map { |s| s.host }.inspect}"
+
+        # establish connections to those servers, as necessary
+        begin
+          establish_connections_to(servers)
+        rescue ConnectionError => error
+          raise error unless task && task.continue_on_error?
+          error.hosts.each do |h|
+            servers.delete(h)
+            failed!(h)
+          end
+        end
+
+        begin
+          yield servers
+        rescue RemoteError => error
+          raise error unless task && task.continue_on_error?
+          error.hosts.each { |h| failed!(h) }
+        end
+      end
+
+      private
+
+        # We establish the connection by creating a thread in a new method--this
+        # prevents problems with the thread's scope seeing the wrong 'server'
+        # variable if the thread just happens to take too long to start up.
+        def establish_connection_to(server, failures=nil)
+          Thread.new { safely_establish_connection_to(server, failures) }
+        end
+
+        def safely_establish_connection_to(server, failures=nil)
+          sessions[server] ||= connection_factory.connect_to(server)
+        rescue Exception => err
+          raise unless failures
+          failures << { :server => server, :error => err }
+        end
+    end
+  end
+end