capistrano 1.4.2 → 2.0.0

data/lib/capistrano/configuration/servers.rb

@@ -0,0 +1,75 @@
+module Capistrano
+  class Configuration
+    module Servers
+      # Identifies all servers that the given task should be executed on.
+      # The options hash accepts the same arguments as #find_servers, and any
+      # preexisting options there will take precedence over the options in
+      # the task.
+      def find_servers_for_task(task, options={})
+        find_servers(task.options.merge(options))
+      end
+
+      # Attempts to find all defined servers that match the given criteria.
+      # The options hash may include a :hosts option (which should specify
+      # an array of host names or ServerDefinition instances), a :roles
+      # option (specifying an array of roles), an :only option (specifying
+      # a hash of key/value pairs that any matching server must match), and
+      # an :exception option (like :only, but the inverse).
+      #
+      # Additionally, if the HOSTS environment variable is set, it will take
+      # precedence over any other options. Similarly, the ROLES environment
+      # variable will take precedence over other options. If both HOSTS and
+      # ROLES are given, HOSTS wins.
+      #
+      # Usage:
+      #
+      #   # return all known servers
+      #   servers = find_servers
+      #
+      #   # find all servers in the app role that are not exempted from
+      #   # deployment
+      #   servers = find_servers :roles => :app,
+      #                :except => { :no_release => true }
+      #
+      #   # returns the given hosts, translated to ServerDefinition objects
+      #   servers = find_servers :hosts => "jamis@example.host.com"
+      def find_servers(options={})
+        hosts  = server_list_from(ENV['HOSTS'] || options[:hosts])
+        roles  = role_list_from(ENV['ROLES'] || options[:roles] || self.roles.keys)
+        only   = options[:only] || {}
+        except = options[:except] || {}
+
+        if hosts.any?
+          hosts.uniq
+        else
+          servers = roles.inject([]) { |list, role| list.concat(self.roles[role]) }
+          servers = servers.select { |server| only.all? { |key,value| server.options[key] == value } }
+          servers = servers.reject { |server| except.any? { |key,value| server.options[key] == value } }
+          servers.uniq
+        end
+      end
+
+    protected
+
+      def server_list_from(hosts)
+        hosts = hosts.split(/,/) if String === hosts
+        hosts = build_list(hosts)
+        hosts.map { |s| String === s ? ServerDefinition.new(s.strip) : s }
+      end
+
+      def role_list_from(roles)
+        roles = roles.split(/,/) if String === roles
+        roles = build_list(roles)
+        roles.map do |role|
+          role = String === role ? role.strip.to_sym : role
+          raise ArgumentError, "unknown role `#{role}'" unless self.roles.key?(role)
+          role
+        end
+      end
+
+      def build_list(list)
+        Array(list).map { |item| item.respond_to?(:call) ? item.call : item }.flatten
+      end
+    end
+  end
+end

data/lib/capistrano/configuration/variables.rb

@@ -0,0 +1,127 @@
+require 'thread'
+
+module Capistrano
+  class Configuration
+    module Variables
+      def self.included(base) #:nodoc:
+        %w(initialize respond_to? method_missing).each do |m|
+          base_name = m[/^\w+/]
+          punct     = m[/\W+$/]
+          base.send :alias_method, "#{base_name}_without_variables#{punct}", m
+          base.send :alias_method, m, "#{base_name}_with_variables#{punct}"
+        end
+      end
+
+      # The hash of variables that have been defined in this configuration
+      # instance.
+      attr_reader :variables
+
+      # Set a variable to the given value.
+      def set(variable, *args, &block)
+        if variable.to_s !~ /^[_a-z]/
+          raise ArgumentError, "invalid variable `#{variable}' (variables must begin with an underscore, or a lower-case letter)"
+        end
+
+        if !block_given? && args.empty? || block_given? && !args.empty?
+          raise ArgumentError, "you must specify exactly one of either a value or a block"
+        end
+
+        if args.length > 1
+          raise ArgumentError, "wrong number of arguments (#{args.length} for 1)"
+        end
+
+        value = args.empty? ? block : args.first
+        sym = variable.to_sym
+        protect(sym) { @variables[sym] = value }
+      end
+
+      alias :[]= :set
+
+      # Removes any trace of the given variable.
+      def unset(variable)
+        sym = variable.to_sym
+        protect(sym) do
+          @original_procs.delete(sym)
+          @variables.delete(sym)
+        end
+      end
+
+      # Returns true if the variable has been defined, and false otherwise.
+      def exists?(variable)
+        @variables.key?(variable.to_sym)
+      end
+
+      # If the variable was originally a proc value, it will be reset to it's
+      # original proc value. Otherwise, this method does nothing. It returns
+      # true if the variable was actually reset.
+      def reset!(variable)
+        sym = variable.to_sym
+        protect(sym) do
+          if @original_procs.key?(sym)
+            @variables[sym] = @original_procs.delete(sym)
+            true
+          else
+            false
+          end
+        end
+      end
+
+      # 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 fetch(variable, *args)
+        if !args.empty? && block_given?
+          raise ArgumentError, "you must specify either a default value or a block, but not both"
+        end
+
+        sym = variable.to_sym
+        protect(sym) do
+          if !@variables.key?(sym)
+            return args.first unless args.empty?
+            return yield(variable) if block_given?
+            raise IndexError, "`#{variable}' not found"
+          end
+
+          if @variables[sym].respond_to?(:call)
+            @original_procs[sym] = @variables[sym]
+            @variables[sym] = @variables[sym].call
+          end
+        end
+
+        @variables[sym]
+      end
+
+      def [](variable)
+        fetch(variable, nil)
+      end
+
+      def initialize_with_variables(*args) #:nodoc:
+        initialize_without_variables(*args)
+        @variables = {}
+        @original_procs = {}
+        @variable_locks = Hash.new { |h,k| h[k] = Mutex.new }
+
+        set :ssh_options, {}
+        set :logger, logger
+      end
+      private :initialize_with_variables
+
+      def protect(variable)
+        @variable_locks[variable.to_sym].synchronize { yield }
+      end
+      private :protect
+
+      def respond_to_with_variables?(sym) #:nodoc:
+        @variables.has_key?(sym) || respond_to_without_variables?(sym)
+      end
+
+      def method_missing_with_variables(sym, *args, &block) #:nodoc:
+        if args.length == 0 && block.nil? && @variables.has_key?(sym)
+          self[sym]
+        else
+          method_missing_without_variables(sym, *args, &block)
+        end
+      end
+    end
+  end
+end

data/lib/capistrano/errors.rb

@@ -0,0 +1,15 @@
+module Capistrano
+  class Error < RuntimeError; end
+
+  class CaptureError < Error; end
+  class NoSuchTaskError < Error; end
+  class NoMatchingServersError < Error; end
+  
+  class RemoteError < Error
+    attr_accessor :hosts
+  end
+
+  class ConnectionError < RemoteError; end
+  class UploadError < RemoteError; end
+  class CommandError < RemoteError; end
+end

data/lib/capistrano/extensions.rb

@@ -1,23 +1,35 @@
-require 'capistrano/actor'
-
 module Capistrano
-  class ExtensionProxy
-    def initialize(actor, mod)
-      @actor = actor
+  class ExtensionProxy #:nodoc:
+    def initialize(config, mod)
+      @config = config
       extend(mod)
     end
 
     def method_missing(sym, *args, &block)
-      @actor.send(sym, *args, &block)
+      @config.send(sym, *args, &block)
     end
   end
 
+  # Holds the set of registered plugins, keyed by name (where the name is a
+  # symbol).
   EXTENSIONS = {}
 
+  # Register the given module as a plugin with the given name. It will henceforth
+  # be available via a proxy object on Configuration instances, accessible by
+  # a method with the given name.
   def self.plugin(name, mod)
+    name = name.to_sym
     return false if EXTENSIONS.has_key?(name)
 
-    Capistrano::Actor.class_eval <<-STR, __FILE__, __LINE__+1
+    methods = Capistrano::Configuration.public_instance_methods +
+      Capistrano::Configuration.protected_instance_methods +
+      Capistrano::Configuration.private_instance_methods
+
+    if methods.include?(name.to_s)
+      raise Capistrano::Error, "registering a plugin named `#{name}' would shadow a method on Capistrano::Configuration with the same name"
+    end
+
+    Capistrano::Configuration.class_eval <<-STR, __FILE__, __LINE__+1
       def #{name}
         @__#{name}_proxy ||= Capistrano::ExtensionProxy.new(self, Capistrano::EXTENSIONS[#{name.inspect}])
       end
@@ -27,12 +39,19 @@ module Capistrano
     return true
   end
 
+  # Unregister the plugin with the given name.
   def self.remove_plugin(name)
+    name = name.to_sym
     if EXTENSIONS.delete(name)
-      Capistrano::Actor.send(:remove_method, name)
+      Capistrano::Configuration.send(:remove_method, name)
       return true
     end
 
     return false
   end
+
+  def self.configuration(*args) #:nodoc:
+    warn "[DEPRECATION] Capistrano.configuration is deprecated. Use Capistrano::Configuration.instance instead"
+    Capistrano::Configuration.instance(*args)
+  end
 end

data/lib/capistrano/gateway.rb

@@ -1,5 +1,18 @@
+if RUBY_VERSION == "1.8.6"
+  begin
+    require 'fastthread'
+  rescue LoadError
+    warn "You are running Ruby 1.8.6, which has a bug in its threading implementation."
+    warn "You are liable to encounter deadlocks running Capistrano, unless you install"
+    warn "the fastthread library, which is available as a gem:"
+    warn "   gem install fastthread"
+  end
+end
+
 require 'thread'
+require 'capistrano/errors'
 require 'capistrano/ssh'
+require 'capistrano/server_definition'
 
 Thread.abort_on_exception = true
 
@@ -9,17 +22,16 @@ module Capistrano
   # gateway server, through which connections to other servers may be
   # tunnelled.
   #
-  # It is used internally by Actor, but may be useful on its own, as well.
+  # It is used internally by Capistrano, but may be useful on its own, as well.
   #
   # Usage:
   #
-  #   config = Capistrano::Configuration.new
-  #   gateway = Capistrano::Gateway.new('gateway.example.com', config)
+  #   gateway = Capistrano::Gateway.new(Capistrano::ServerDefinition.new('gateway.example.com'))
   #
-  #   sess1 = gateway.connect_to('hidden.example.com')
-  #   sess2 = gateway.connect_to('other.example.com')
+  #   sess1 = gateway.connect_to(Capistrano::ServerDefinition.new('hidden.example.com'))
+  #   sess2 = gateway.connect_to(Capistrano::ServerDefinition.new('other.example.com'))
   class Gateway
-    # The thread inside which the gateway connection itself is running.
+    # The Thread instance driving the gateway connection.
     attr_reader :thread
 
     # The Net::SSH session representing the gateway connection.
@@ -28,8 +40,8 @@ module Capistrano
     MAX_PORT = 65535
     MIN_PORT = 1024
 
-    def initialize(server, config) #:nodoc:
-      @config = config
+    def initialize(server, options={}) #:nodoc:
+      @options = options
       @next_port = MAX_PORT
       @terminate_thread = false
       @port_guard = Mutex.new
@@ -37,30 +49,34 @@ module Capistrano
       mutex = Mutex.new
       waiter = ConditionVariable.new
 
-      @thread = Thread.new do
-        @config.logger.trace "starting connection to gateway #{server}"
-        SSH.connect(server, @config) do |@session|
-          @config.logger.trace "gateway connection established"
-          mutex.synchronize { waiter.signal }
-          @session.loop { !@terminate_thread }
+      mutex.synchronize do
+        @thread = Thread.new do
+          logger.trace "starting connection to gateway `#{server}'" if logger
+          SSH.connect(server, @options) do |@session|
+            logger.trace "gateway connection established" if logger
+            mutex.synchronize { waiter.signal }
+            @session.loop do
+              !@terminate_thread
+            end
+          end
         end
-      end
 
-      mutex.synchronize { waiter.wait(mutex) }
+        waiter.wait(mutex)
+      end
     end
 
     # Shuts down all forwarded connections and terminates the gateway.
     def shutdown!
       # cancel all active forward channels
-      @session.forward.active_locals.each do |lport, host, port|
-        @session.forward.cancel_local(lport)
+      session.forward.active_locals.each do |lport, host, port|
+        session.forward.cancel_local(lport)
       end
 
       # terminate the gateway thread
       @terminate_thread = true
 
       # wait for the gateway thread to stop
-      @thread.join
+      thread.join
     end
 
     # Connects to the given server by opening a forwarded port from the local
@@ -68,32 +84,41 @@ module Capistrano
     # Net::SSH connection via that port.
     def connect_to(server)
       connection = nil
-      @config.logger.trace "establishing connection to #{server} via gateway"
+      logger.debug "establishing connection to `#{server}' via gateway" if logger
       local_port = next_port
 
       thread = Thread.new do
         begin
-          user, server_stripped, port = SSH.parse_server(server)   
-          @config.ssh_options[:username] = user if user
-          remote_port = port || 22
-          @session.forward.local(local_port, server_stripped, remote_port)
-          connection = SSH.connect('127.0.0.1', @config, local_port)
-          @config.logger.trace "connection to #{server} via gateway established"
+          local_host = ServerDefinition.new("127.0.0.1", :user => server.user, :port => local_port)
+          session.forward.local(local_port, server.host, server.port || 22)
+          connection = SSH.connect(local_host, @options)
+          connection.xserver = server
+          logger.trace "connected: `#{server}' (via gateway)" if logger
         rescue Errno::EADDRINUSE
           local_port = next_port
           retry
         rescue Exception => e
-          puts e.class.name
-          puts e.backtrace.join("\n")
+          warn "#{e.class}: #{e.message}"
+          warn e.backtrace.join("\n")
         end
       end
 
       thread.join
-      connection or raise "Could not establish connection to #{server}"
+      if connection.nil?
+        error = ConnectionError.new("could not establish connection to `#{server}'")
+        error.hosts = [server]
+        raise error
+      end
+    
+      connection
     end
 
     private
 
+      def logger
+        @options[:logger]
+      end
+
       def next_port
         @port_guard.synchronize do
           port = @next_port

data/lib/capistrano/logger.rb

@@ -1,6 +1,7 @@
 module Capistrano
   class Logger #:nodoc:
     attr_accessor :level
+    attr_reader   :device
 
     IMPORTANT = 0
     INFO      = 1
@@ -10,13 +11,12 @@ module Capistrano
     MAX_LEVEL = 3
 
     def initialize(options={})
-      output = options[:output] || STDERR
-      case
-        when output.respond_to?(:puts)
-          @device = output
-        else
-          @device = File.open(output.to_str, "a")
-          @needs_close = true
+      output = options[:output] || $stderr
+      if output.respond_to?(:puts)
+        @device = output
+      else
+        @device = File.open(output.to_str, "a")
+        @needs_close = true
       end
 
       @options = options
@@ -24,17 +24,17 @@ module Capistrano
     end
 
     def close
-      @device.close if @needs_close
+      device.close if @needs_close
     end
 
     def log(level, message, line_prefix=nil)
       if level <= self.level
         indent = "%*s" % [MAX_LEVEL, "*" * (MAX_LEVEL - level)]
-        message.split(/\r?\n/).each do |line|
+        message.each do |line|
           if line_prefix
-            @device.print "#{indent} [#{line_prefix}] #{line.strip}\n"
+            device.puts "#{indent} [#{line_prefix}] #{line.strip}\n"
           else
-            @device.puts "#{indent} #{line.strip}\n"
+            device.puts "#{indent} #{line.strip}\n"
           end
         end
       end