capistrano 1.1.0

data/lib/capistrano/cli.rb

@@ -0,0 +1,295 @@
+require 'optparse'
+require 'capistrano'
+
+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 ST and
+  # preserve it's command-line semantics.
+  class CLI
+    # Invoke capistrano using the ARGV array as the option parameters. This
+    # is what the command-line capistrano utility does.
+    def self.execute!
+      new.execute!
+    end
+
+    # The following determines whether or not echo-suppression is available.
+    # This requires the termios library to be installed (which, unfortunately,
+    # is not available for Windows).
+    begin
+      if !defined?(USE_TERMIOS) || USE_TERMIOS
+        require 'termios'
+      else
+        raise LoadError
+      end
+
+      # Enable or disable stdin echoing to the terminal.
+      def self.echo(enable)
+        term = Termios::getattr(STDIN)
+
+        if enable
+          term.c_lflag |= (Termios::ECHO | Termios::ICANON)
+        else
+          term.c_lflag &= ~Termios::ECHO
+        end
+
+        Termios::setattr(STDIN, Termios::TCSANOW, term)
+      end
+    rescue LoadError
+      def self.echo(enable)
+      end
+    end
+
+    # execute the associated block with echo-suppression enabled. Note that
+    # if termios is not available, echo suppression will not be available
+    # either.
+    def self.with_echo
+      echo(false)
+      yield
+    ensure
+      echo(true)
+    end
+
+    # Prompt for a password using echo suppression.
+    def self.password_prompt(prompt="Password: ")
+      sync = STDOUT.sync
+      begin
+        with_echo do
+          STDOUT.sync = true
+          print(prompt)
+          STDIN.gets.chomp
+        end
+      ensure
+        STDOUT.sync = sync
+        puts
+      end
+    end
+
+    # The array of (unparsed) command-line options
+    attr_reader :args
+
+    # The hash of (parsed) command-line options
+    attr_reader :options
+
+    # 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 ST in a program):
+    #
+    #   require 'capistrano/cli'
+    #   Capistrano::CLI.new(%w(-vvvv -r config/deploy -a update_code)).execute!
+    #
+    # Note that you can also embed ST 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 "standard", "config/deploy"
+    #   config.actor.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 = ARGV)
+      @args = args
+      @options = { :recipes => [], :actions => [], :vars => {},
+        :pre_vars => {} }
+
+      OptionParser.new do |opts|
+        opts.banner = "Usage: #{$0} [options] [args]"
+
+        opts.separator ""
+        opts.separator "Recipe Options -----------------------"
+        opts.separator ""
+
+        opts.on("-a", "--action ACTION",
+          "An action to execute. Multiple actions may",
+          "be specified, and are loaded in the given order."
+        ) { |value| @options[:actions] << value }
+
+        opts.on("-p", "--password [PASSWORD]",
+          "The password to use when connecting. If the switch",
+          "is given without a password, the password will be",
+          "prompted for immediately. (Default: prompt for password",
+          "the first time it is needed.)"
+        ) { |value| @options[:password] = value }
+
+        opts.on("-r", "--recipe RECIPE",
+          "A recipe file to load. Multiple recipes may",
+          "be specified, and are loaded in the given order."
+        ) { |value| @options[:recipes] << value }
+
+        opts.on("-s", "--set NAME=VALUE",
+          "Specify a variable and it's value to set. This",
+          "will be set after loading all recipe files."
+        ) do |pair|
+          name, value = pair.split(/=/, 2)
+          @options[:vars][name.to_sym] = value
+        end
+
+        opts.on("-S", "--set-before NAME=VALUE",
+          "Specify a variable and it's value to set. This",
+          "will be set BEFORE loading all recipe files."
+        ) do |pair|
+          name, value = pair.split(/=/, 2)
+          @options[:pre_vars][name.to_sym] = value
+        end
+
+        opts.separator ""
+        opts.separator "Framework Integration Options --------"
+        opts.separator ""
+
+        opts.on("-A", "--apply-to DIRECTORY",
+          "Create a minimal set of scripts and recipes to use",
+          "capistrano with the application at the given",
+          "directory. (Currently only works with Rails apps.)"
+        ) { |value| @options[:apply_to] = value }
+
+        opts.separator ""
+        opts.separator "Miscellaneous Options ----------------"
+        opts.separator ""
+
+        opts.on("-h", "--help", "Display this help message") do
+          puts opts
+          exit
+        end
+
+        opts.on("-P", "--[no-]pretend",
+          "Run the task(s), but don't actually connect to or",
+          "execute anything on the servers. (For various reasons",
+          "this will not necessarily be an accurate depiction",
+          "of the work that will actually be performed.",
+          "Default: don't pretend.)"
+        ) { |value| @options[:pretend] = value }
+
+        opts.on("-q", "--quiet",
+          "Make the output as quiet as possible (the default)"
+        ) { @options[:verbose] = 0 }
+
+        opts.on("-v", "--verbose",
+          "Specify the verbosity of the output.",
+          "May be given multiple times. (Default: silent)"
+        ) { @options[:verbose] ||= 0; @options[:verbose] += 1 }
+
+        opts.on("-V", "--version",
+          "Display the version info for this utility"
+        ) do
+          require 'capistrano/version'
+          puts "Capistrano v#{Capistrano::Version::STRING}"
+          exit
+        end
+
+        opts.separator ""
+        opts.separator <<-DETAIL.split(/\n/)
+You can use the --apply-to switch to generate a minimal set of capistrano
+scripts and recipes for an application. Just specify the path to the application
+as the argument to --apply-to, like this:
+
+  capistrano --apply-to ~/projects/myapp
+
+You'll wind up with a sample deployment recipe in config/deploy.rb, some new
+rake tasks in config/tasks, and a capistrano script in your script directory.
+
+(Currently, --apply-to only works with Rails applications.)
+DETAIL
+
+        if args.empty?
+          puts opts
+          exit
+        else
+          opts.parse!(args)
+        end
+      end
+
+      check_options!
+
+      password_proc = Proc.new { self.class.password_prompt }
+
+      if !@options.has_key?(:password)
+        @options[:password] = password_proc
+      elsif !@options[:password]
+        @options[:password] = password_proc.call
+      end
+    end
+
+    # Beginning running Capistrano based on the configured options.
+    def execute!
+      if !@options[:recipes].empty?
+        execute_recipes!
+      elsif @options[:apply_to]
+        execute_apply_to!
+      end
+    end
+
+    private
+
+      # Load the recipes specified by the options, and execute the actions
+      # specified.
+      def execute_recipes!
+        config = Capistrano::Configuration.new
+        config.logger.level = options[:verbose]
+        config.set :password, options[:password]
+        config.set :pretend, options[:pretend]
+
+        options[:pre_vars].each { |name, value| config.set(name, value) }
+
+        # load the standard recipe definition
+        config.load "standard"
+
+        options[:recipes].each { |recipe| config.load(recipe) }
+        options[:vars].each { |name, value| config.set(name, value) }
+
+        actor = config.actor
+        options[:actions].each { |action| actor.send action }
+      end
+
+      # Load the Rails generator and apply it to the specified directory.
+      def execute_apply_to!
+        require 'capistrano/generators/rails/loader'
+        Generators::RailsLoader.load! @options
+      end
+
+      APPLY_TO_OPTIONS = [:apply_to]
+      RECIPE_OPTIONS   = [:password]
+      DEFAULT_RECIPES  = %w(Capfile capfile config/deploy.rb)
+
+      # A sanity check to ensure that a valid operation is specified.
+      def check_options!
+        # if no verbosity has been specified, be verbose
+        @options[:verbose] = 3 if !@options.has_key?(:verbose)
+
+        apply_to_given = !(@options.keys & APPLY_TO_OPTIONS).empty?
+        recipe_given   = !(@options.keys & RECIPE_OPTIONS).empty? ||
+                         !@options[:recipes].empty? ||
+                         !@options[:actions].empty?
+
+        if apply_to_given && recipe_given
+          abort "You cannot specify both recipe options and framework integration options."
+        elsif !apply_to_given
+          look_for_default_recipe_file! if @options[:recipes].empty?
+          look_for_raw_actions!
+          abort "You must specify at least one recipe" if @options[:recipes].empty?
+          abort "You must specify at least one action" if @options[:actions].empty?
+        else
+          @options[:application] = args.shift
+          @options[:recipe_file] = args.shift
+        end
+      end
+
+      def look_for_default_recipe_file!
+        DEFAULT_RECIPES.each do |file|
+          if File.exist?(file)
+            @options[:recipes] << file
+            break
+          end
+        end
+      end
+
+      def look_for_raw_actions!
+        @options[:actions].concat(@args)
+      end
+  end
+end

data/lib/capistrano/command.rb

@@ -0,0 +1,90 @@
+module Capistrano
+
+  # This class encapsulates a single command to be executed on a set of remote
+  # machines, in parallel.
+  class Command
+    attr_reader :servers, :command, :options, :actor
+
+    def initialize(servers, command, callback, options, actor) #:nodoc:
+      @servers = servers
+      @command = command.strip.gsub(/\r?\n/, "\\\n")
+      @callback = callback
+      @options = options
+      @actor = actor
+      @channels = open_channels
+    end
+
+    def logger #:nodoc:
+      actor.logger
+    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
+    # RuntimeError.
+    def process!
+      since = Time.now
+      loop do
+        active = 0
+        @channels.each do |ch|
+          next if ch[:closed]
+          active += 1
+          ch.connection.process(true)
+        end
+
+        break if active == 0
+        if Time.now - since >= 1
+          since = Time.now
+          @channels.each { |ch| ch.connection.ping! }
+        end
+        sleep 0.01 # a brief respite, to keep the CPU from going crazy
+      end
+
+      logger.trace "command finished"
+
+      if failed = @channels.detect { |ch| ch[:status] != 0 }
+        raise "command #{@command.inspect} failed on #{failed[:host]}"
+      end
+
+      self
+    end
+
+    private
+
+      def open_channels
+        @servers.map do |server|
+          @actor.sessions[server].open_channel do |channel|
+            channel[:host] = server
+            channel[:actor] = @actor # so callbacks can access the actor instance
+            channel.request_pty :want_reply => true
+
+            channel.on_success do |ch|
+              logger.trace "executing command", ch[:host]
+              ch.exec command
+              ch.send_data options[:data] if options[:data]
+            end
+
+            channel.on_failure do |ch|
+              logger.important "could not open channel", ch[:host]
+              ch.close
+            end
+
+            channel.on_data do |ch, data|
+              @callback[ch, :out, data] if @callback
+            end
+
+            channel.on_extended_data do |ch, type, data|
+              @callback[ch, :err, data] if @callback
+            end
+
+            channel.on_request do |ch, request, reply, data|
+              ch[:status] = data.read_long if request == "exit-status"
+            end
+
+            channel.on_close do |ch|
+              ch[:closed] = true
+            end
+          end
+        end
+      end
+  end
+end

data/lib/capistrano/configuration.rb

@@ -0,0 +1,243 @@
+require 'capistrano/actor'
+require 'capistrano/logger'
+require 'capistrano/scm/subversion'
+require 'capistrano/extensions'
+
+module Capistrano
+  # Represents a specific Capistrano configuration. A Configuration instance
+  # may be used to load multiple recipe files, define and describe tasks,
+  # define roles, create an actor, and set configuration variables.
+  class Configuration
+    Role = Struct.new(:host, :options)
+
+    DEFAULT_VERSION_DIR_NAME = "releases" #:nodoc:
+    DEFAULT_CURRENT_DIR_NAME = "current"  #:nodoc:
+    DEFAULT_SHARED_DIR_NAME  = "shared"   #:nodoc:
+
+    # The actor created for this configuration instance.
+    attr_reader :actor
+
+    # The list of Role instances defined for this configuration.
+    attr_reader :roles
+
+    # The logger instance defined for this configuration.
+    attr_reader :logger
+
+    # The load paths used for locating recipe files.
+    attr_reader :load_paths
+
+    # The time (in UTC) at which this configuration was created, used for
+    # determining the release path.
+    attr_reader :now
+
+    # The has of variables currently known by the configuration
+    attr_reader :variables
+
+    def initialize(actor_class=Actor) #:nodoc:
+      @roles = Hash.new { |h,k| h[k] = [] }
+      @actor = actor_class.new(self)
+      @logger = Logger.new
+      @load_paths = [".", File.join(File.dirname(__FILE__), "recipes")]
+      @variables = {}
+      @now = Time.now.utc
+
+      # for preserving the original value of Proc-valued variables
+      set :original_value, Hash.new
+
+      set :application, nil
+      set :repository,  nil
+      set :gateway,     nil
+      set :user,        nil
+      set :password,    nil
+      
+      set :ssh_options, Hash.new
+						
+      set(:deploy_to)   { "/u/apps/#{application}" }
+
+      set :version_dir, DEFAULT_VERSION_DIR_NAME
+      set :current_dir, DEFAULT_CURRENT_DIR_NAME
+      set :shared_dir,  DEFAULT_SHARED_DIR_NAME
+      set :scm,         :subversion
+
+      set(:revision)    { source.latest_revision }
+    end
+
+    # Set a variable to the given value.
+    def set(variable, value=nil, &block)
+      # if the variable is uppercase, then we add it as a constant to the
+      # actor. This is to allow uppercase "variables" to be set and referenced
+      # in recipes.
+      if variable.to_s[0].between?(?A, ?Z)
+        klass = @actor.metaclass
+        klass.send(:remove_const, variable) if klass.const_defined?(variable)
+        klass.const_set(variable, value)
+      end
+
+      value = block if value.nil? && block_given?
+      @variables[variable] = value
+    end
+
+    alias :[]= :set
+
+    # Access a named variable. If the value of the variable responds_to? :call,
+    # #call will be invoked (without parameters) and the return value cached
+    # and returned.
+    def [](variable)
+      if @variables[variable].respond_to?(:call)
+        self[:original_value][variable] = @variables[variable]
+        set variable, @variables[variable].call
+      end
+      @variables[variable]
+    end
+
+    # Based on the current value of the <tt>:scm</tt> variable, instantiate and
+    # return an SCM module representing the desired source control behavior.
+    def source
+      @source ||= case scm
+        when Class then
+          scm.new(self)
+        when String, Symbol then
+          require "capistrano/scm/#{scm.to_s.downcase}"
+          Capistrano::SCM.const_get(scm.to_s.downcase.capitalize).new(self)
+        else
+          raise "invalid scm specification: #{scm.inspect}"
+      end
+    end
+
+    # Load a configuration file or string into this configuration.
+    #
+    # Usage:
+    #
+    #   load("recipe"):
+    #     Look for and load the contents of 'recipe.rb' into this
+    #     configuration.
+    #
+    #   load(:file => "recipe"):
+    #     same as above
+    #
+    #   load(:string => "set :scm, :subversion"):
+    #     Load the given string as a configuration specification.
+    #
+    #   load { ... }
+    #     Load the block in the context of the configuration.
+    def load(*args, &block)
+      options = args.last.is_a?(Hash) ? args.pop : {}
+      args.each { |arg| load options.merge(:file => arg) }
+      return unless args.empty?
+
+      if block
+        raise "loading a block requires 0 parameters" unless args.empty?
+        load(options.merge(:proc => block))
+
+      elsif options[:file]
+        file = options[:file]
+        unless file[0] == ?/
+          load_paths.each do |path|
+            if File.file?(File.join(path, file))
+              file = File.join(path, file)
+              break
+            elsif File.file?(File.join(path, file) + ".rb")
+              file = File.join(path, file + ".rb")
+              break
+            end
+          end
+        end
+
+        load :string => File.read(file), :name => options[:name] || file
+
+      elsif options[:string]
+        logger.trace "loading configuration #{options[:name] || "<eval>"}"
+        instance_eval(options[:string], options[:name] || "<eval>")
+
+      elsif options[:proc]
+        logger.trace "loading configuration #{options[:proc].inspect}"
+        instance_eval(&options[:proc])
+
+      else
+        raise ArgumentError, "don't know how to load #{options.inspect}"
+      end
+    end
+
+    # Define a new role and its associated servers. You must specify at least
+    # one host for each role. Also, you can specify additional information
+    # (in the form of a Hash) which can be used to more uniquely specify the
+    # subset of servers specified by this specific role definition.
+    #
+    # Usage:
+    #
+    #   role :db, "db1.example.com", "db2.example.com"
+    #   role :db, "master.example.com", :primary => true
+    #   role :app, "app1.example.com", "app2.example.com"
+    def role(which, *args)
+      options = args.last.is_a?(Hash) ? args.pop : {}
+      raise ArgumentError, "must give at least one host" if args.empty?
+      args.each { |host| roles[which] << Role.new(host, options) }
+    end
+
+    # Describe the next task to be defined. The given text will be attached to
+    # the next task that is defined and used as its description.
+    def desc(text)
+      @next_description = text
+    end
+
+    # Define a new task. If a description is active (see #desc), it is added to
+    # the options under the <tt>:desc</tt> key. This method ultimately
+    # delegates to Actor#define_task.
+    def task(name, options={}, &block)
+      raise ArgumentError, "expected a block" unless block
+
+      if @next_description
+        options = options.merge(:desc => @next_description)
+        @next_description = nil
+      end
+
+      actor.define_task(name, options, &block)
+    end
+
+    # Require another file. This is identical to the standard require method,
+    # with the exception that it sets the reciever as the "current" configuration
+    # so that third-party task bundles can include themselves relative to
+    # that configuration.
+    def require(*args) #:nodoc:
+      original, Capistrano.configuration = Capistrano.configuration, self
+      super
+    ensure
+      # restore the original, so that require's can be nested
+      Capistrano.configuration = original
+    end
+
+    # Return the path into which releases should be deployed.
+    def releases_path
+      File.join(deploy_to, version_dir)
+    end
+
+    # Return the path identifying the +current+ symlink, used to identify the
+    # current release.
+    def current_path
+      File.join(deploy_to, current_dir)
+    end
+    
+    # Return the path into which shared files should be stored.
+    def shared_path
+      File.join(deploy_to, shared_dir)
+    end
+
+    # Return the full path to the named release. If a release is not specified,
+    # +now+ is used (the time at which the configuration was created).
+    def release_path(release=now.strftime("%Y%m%d%H%M%S"))
+      File.join(releases_path, release)
+    end
+
+    def respond_to?(sym) #:nodoc:
+      @variables.has_key?(sym) || super
+    end
+
+    def method_missing(sym, *args, &block) #:nodoc:
+      if args.length == 0 && block.nil? && @variables.has_key?(sym)
+        self[sym]
+      else
+        super
+      end
+    end
+  end
+end