mbailey-capistrano 2.5.5

data/lib/capistrano/configuration/execution.rb

@@ -0,0 +1,132 @@
+require 'capistrano/errors'
+
+module Capistrano
+  class Configuration
+    module Execution
+      def self.included(base) #:nodoc:
+        base.send :alias_method, :initialize_without_execution, :initialize
+        base.send :alias_method, :initialize, :initialize_with_execution
+      end
+
+      # The call stack of the tasks. The currently executing task may inspect
+      # this to see who its caller was. The current task is always the last
+      # element of this stack.
+      attr_reader :task_call_frames
+
+      # The stack of tasks that have registered rollback handlers within the
+      # current transaction. If this is nil, then there is no transaction
+      # that is currently active.
+      attr_reader :rollback_requests
+
+      # A struct for representing a single instance of an invoked task.
+      TaskCallFrame = Struct.new(:task, :rollback)
+
+      def initialize_with_execution(*args) #:nodoc:
+        initialize_without_execution(*args)
+        @task_call_frames = []
+      end
+      private :initialize_with_execution
+
+      # Returns true if there is a transaction currently active.
+      def transaction?
+        !rollback_requests.nil?
+      end
+
+      # Invoke a set of tasks in a transaction. If any task fails (raises an
+      # exception), all tasks executed within the transaction are inspected to
+      # see if they have an associated on_rollback hook, and if so, that hook
+      # is called.
+      def transaction
+        raise ArgumentError, "expected a block" unless block_given?
+        raise ScriptError, "transaction must be called from within a task" if task_call_frames.empty?
+
+        return yield if transaction?
+
+        logger.info "transaction: start"
+        begin
+          @rollback_requests = []
+          yield
+          logger.info "transaction: commit"
+        rescue Object => e
+          rollback!
+          raise
+        ensure
+          @rollback_requests = nil
+        end
+      end
+
+      # Specifies an on_rollback hook for the currently executing task. If this
+      # or any subsequent task then fails, and a transaction is active, this
+      # hook will be executed.
+      def on_rollback(&block)
+        if transaction?
+          # don't note a new rollback request if one has already been set
+          rollback_requests << task_call_frames.last unless task_call_frames.last.rollback
+          task_call_frames.last.rollback = block
+        end
+      end
+
+      # Returns the TaskDefinition object for the currently executing task.
+      # It returns nil if there is no task being executed.
+      def current_task
+        return nil if task_call_frames.empty?
+        task_call_frames.last.task
+      end
+
+      # Executes the task with the given name, without invoking any associated
+      # callbacks.
+      def execute_task(task)
+        logger.debug "executing `#{task.fully_qualified_name}'"
+        push_task_call_frame(task)
+        invoke_task_directly(task)
+      ensure
+        pop_task_call_frame
+      end
+
+      # Attempts to locate the task at the given fully-qualified path, and
+      # execute it. If no such task exists, a Capistrano::NoSuchTaskError will
+      # be raised.
+      def find_and_execute_task(path, hooks={})
+        task = find_task(path) or raise NoSuchTaskError, "the task `#{path}' does not exist"
+
+        trigger(hooks[:before], task) if hooks[:before]
+        result = execute_task(task)
+        trigger(hooks[:after], task) if hooks[:after]
+
+        result
+      end
+
+    protected
+
+      def rollback!
+        # throw the task back on the stack so that roles are properly
+        # interpreted in the scope of the task in question.
+        rollback_requests.reverse.each do |frame|
+          begin
+            push_task_call_frame(frame.task)
+            logger.important "rolling back", frame.task.fully_qualified_name
+            frame.rollback.call
+          rescue Object => e
+            logger.info "exception while rolling back: #{e.class}, #{e.message}", frame.task.fully_qualified_name
+          ensure
+            pop_task_call_frame
+          end
+        end
+      end
+
+      def push_task_call_frame(task)
+        frame = TaskCallFrame.new(task)
+        task_call_frames.push frame
+      end
+
+      def pop_task_call_frame
+        task_call_frames.pop
+      end
+
+      # Invokes the task's body directly, without setting up the call frame.
+      def invoke_task_directly(task)
+        task.namespace.instance_eval(&task.body)
+      end
+    end
+  end
+end

data/lib/capistrano/configuration/loading.rb

@@ -0,0 +1,197 @@
+module Capistrano
+  class Configuration
+    module Loading
+      def self.included(base) #:nodoc:
+        base.send :alias_method, :initialize_without_loading, :initialize
+        base.send :alias_method, :initialize, :initialize_with_loading
+        base.extend ClassMethods
+      end
+
+      module ClassMethods
+        # Used by third-party task bundles to identify the capistrano
+        # configuration that is loading them. Its return value is not reliable
+        # in other contexts. If +require_config+ is not false, an exception
+        # will be raised if the current configuration is not set.
+        def instance(require_config=false)
+          config = Thread.current[:capistrano_configuration]
+          if require_config && config.nil?
+            raise LoadError, "Please require this file from within a Capistrano recipe"
+          end
+          config
+        end
+
+        # Used internally by Capistrano to specify the current configuration
+        # before loading a third-party task bundle.
+        def instance=(config)
+          Thread.current[:capistrano_configuration] = config
+        end
+
+        # Used internally by Capistrano to track which recipes have been loaded
+        # via require, so that they may be successfully reloaded when require
+        # is called again.
+        def recipes_per_feature
+          @recipes_per_feature ||= {}
+        end
+
+        # Used internally to determine what the current "feature" being
+        # required is. This is used to track which files load which recipes
+        # via require.
+        def current_feature
+          Thread.current[:capistrano_current_feature]
+        end
+
+        # Used internally to specify the current file being required, so that
+        # any recipes loaded by that file can be remembered. This allows
+        # recipes loaded via require to be correctly reloaded in different
+        # Configuration instances in the same Ruby instance.
+        def current_feature=(feature)
+          Thread.current[:capistrano_current_feature] = feature
+        end
+      end
+
+      # The load paths used for locating recipe files.
+      attr_reader :load_paths
+
+      def initialize_with_loading(*args) #:nodoc:
+        initialize_without_loading(*args)
+        @load_paths = [".", File.expand_path(File.join(File.dirname(__FILE__), "../recipes"))]
+        @loaded_features = []
+      end
+      private :initialize_with_loading
+
+      # 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 : {}
+
+        if block
+          raise ArgumentError, "loading a block requires 0 arguments" unless options.empty? && args.empty?
+          load(:proc => block)
+
+        elsif args.any?
+          args.each { |arg| load options.merge(:file => arg) }
+
+        elsif options[:file]
+          load_from_file(options[:file], options[:name])
+
+        elsif options[:string]
+          remember_load(options) unless options[:reloading]
+          instance_eval(options[:string], options[:name] || "<eval>")
+
+        elsif options[:proc]
+          remember_load(options) unless options[:reloading]
+          instance_eval(&options[:proc])
+
+        else
+          raise ArgumentError, "don't know how to load #{options.inspect}"
+        end
+      end
+
+      # Require another file. This is identical to the standard require method,
+      # with the exception that it sets the receiver as the "current" configuration
+      # so that third-party task bundles can include themselves relative to
+      # that configuration.
+      #
+      # This is a bit more complicated than an initial review would seem to
+      # necessitate, but the use case that complicates things is this: An
+      # advanced user wants to embed capistrano, and needs to instantiate
+      # more than one capistrano configuration at a time. They also want each
+      # configuration to require a third-party capistrano extension. Using a
+      # naive require implementation, this would allow the first configuration
+      # to successfully load the third-party extension, but the require would
+      # fail for the second configuration because the extension has already
+      # been loaded.
+      #
+      # To work around this, we do a few things:
+      #
+      # 1. Each time a 'require' is invoked inside of a capistrano recipe,
+      #    we remember the arguments (see "current_feature").
+      # 2. Each time a 'load' is invoked inside of a capistrano recipe, and
+      #    "current_feature" is not nil (meaning we are inside of a pending
+      #    require) we remember the options (see "remember_load" and
+      #    "recipes_per_feature").
+      # 3. Each time a 'require' is invoked inside of a capistrano recipe,
+      #    we check to see if this particular configuration has ever seen these
+      #    arguments to require (see @loaded_features), and if not, we proceed
+      #    as if the file had never been required. If the superclass' require
+      #    returns false (meaning, potentially, that the file has already been
+      #    required), then we look in the recipes_per_feature collection and
+      #    load any remembered recipes from there.
+      #
+      # It's kind of a bear, but it works, and works transparently. Note that
+      # a simpler implementation would just muck with $", allowing files to be
+      # required multiple times, but that will cause warnings (and possibly
+      # errors) if the file to be required contains constant definitions and
+      # such, alongside (or instead of) capistrano recipe definitions.
+      def require(*args) #:nodoc:
+        # look to see if this specific configuration instance has ever seen
+        # these arguments to require before
+        if @loaded_features.include?(args)
+          return false 
+        end
+        
+        @loaded_features << args
+        begin
+          original_instance, self.class.instance = self.class.instance, self
+          original_feature, self.class.current_feature = self.class.current_feature, args
+
+          result = super
+          if !result # file has been required previously, load up the remembered recipes
+            list = self.class.recipes_per_feature[args] || []
+            list.each { |options| load(options.merge(:reloading => true)) }
+          end
+
+          return result
+        ensure
+          # restore the original, so that require's can be nested
+          self.class.instance = original_instance
+          self.class.current_feature = original_feature
+        end
+      end
+
+      private
+
+        # Load a recipe from the named file. If +name+ is given, the file will
+        # be reported using that name.
+        def load_from_file(file, name=nil)
+          file = find_file_in_load_path(file) unless File.file?(file)
+          load :string => File.read(file), :name => name || file
+        end
+
+        def find_file_in_load_path(file)
+          load_paths.each do |path|
+            ["", ".rb"].each do |ext|
+              name = File.join(path, "#{file}#{ext}")
+              return name if File.file?(name)
+            end
+          end
+
+          raise LoadError, "no such file to load -- #{file}"
+        end
+
+        # If a file is being required, the options associated with loading a
+        # recipe are remembered in the recipes_per_feature archive under the
+        # name of the file currently being required.
+        def remember_load(options)
+          if self.class.current_feature
+            list = (self.class.recipes_per_feature[self.class.current_feature] ||= [])
+            list << options
+          end
+        end
+    end
+  end
+end

data/lib/capistrano/configuration/namespaces.rb

@@ -0,0 +1,197 @@
+require 'capistrano/task_definition'
+
+module Capistrano
+  class Configuration
+    module Namespaces
+      DEFAULT_TASK = :default
+
+      def self.included(base) #:nodoc:
+        base.send :alias_method, :initialize_without_namespaces, :initialize
+        base.send :alias_method, :initialize, :initialize_with_namespaces
+      end
+
+      # The name of this namespace. Defaults to +nil+ for the top-level
+      # namespace.
+      attr_reader :name
+
+      # The parent namespace of this namespace. Returns +nil+ for the top-level
+      # namespace.
+      attr_reader :parent
+
+      # The hash of tasks defined for this namespace.
+      attr_reader :tasks
+
+      # The hash of namespaces defined for this namespace.
+      attr_reader :namespaces
+
+      def initialize_with_namespaces(*args) #:nodoc:
+        @name = @parent = nil
+        initialize_without_namespaces(*args)
+        @tasks = {}
+        @namespaces = {}
+      end
+      private :initialize_with_namespaces
+
+      # Returns the top-level namespace (the one with no parent).
+      def top
+        return parent.top if parent
+        return self
+      end
+
+      # Returns the fully-qualified name of this namespace, or nil if the
+      # namespace is at the top-level.
+      def fully_qualified_name
+        return nil if name.nil?
+        [parent.fully_qualified_name, name].compact.join(":")
+      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
+
+      # Returns the value set by the last, pending "desc" call. If +reset+ is
+      # not false, the value will be reset immediately afterwards.
+      def next_description(reset=false)
+        @next_description
+      ensure
+        @next_description = nil if reset
+      end
+
+      # Open a namespace in which to define new tasks. If the namespace was
+      # defined previously, it will be reopened, otherwise a new namespace
+      # will be created for the given name.
+      def namespace(name, &block)
+        name = name.to_sym
+        raise ArgumentError, "expected a block" unless block_given?
+
+        namespace_already_defined = namespaces.key?(name)
+        if all_methods.any? { |m| m.to_sym == name } && !namespace_already_defined
+          thing = tasks.key?(name) ? "task" : "method"
+          raise ArgumentError, "defining a namespace named `#{name}' would shadow an existing #{thing} with that name"
+        end
+
+        namespaces[name] ||= Namespace.new(name, self)
+        namespaces[name].instance_eval(&block)
+
+        # make sure any open description gets terminated
+        namespaces[name].desc(nil)
+
+        if !namespace_already_defined
+          metaclass = class << self; self; end
+          metaclass.send(:define_method, name) { namespaces[name] }
+        end
+      end
+
+      # Describe a new task. If a description is active (see #desc), it is added
+      # to the options under the <tt>:desc</tt> key. The new task is added to
+      # the namespace.
+      def task(name, options={}, &block)
+        name = name.to_sym
+        raise ArgumentError, "expected a block" unless block_given?
+
+        task_already_defined = tasks.key?(name)
+        if all_methods.any? { |m| m.to_sym == name } && !task_already_defined
+          thing = namespaces.key?(name) ? "namespace" : "method"
+          raise ArgumentError, "defining a task named `#{name}' would shadow an existing #{thing} with that name"
+        end
+
+        tasks[name] = TaskDefinition.new(name, self, {:desc => next_description(:reset)}.merge(options), &block)
+
+        if !task_already_defined
+          metaclass = class << self; self; end
+          metaclass.send(:define_method, name) { execute_task(tasks[name]) }
+        end
+      end
+
+      # Find the task with the given name, where name is the fully-qualified
+      # name of the task. This will search into the namespaces and return
+      # the referenced task, or nil if no such task can be found. If the name
+      # refers to a namespace, the task in that namespace named "default"
+      # will be returned instead, if one exists.
+      def find_task(name)
+        parts = name.to_s.split(/:/)
+        tail = parts.pop.to_sym
+
+        ns = self
+        until parts.empty?
+          next_part = parts.shift
+          ns = next_part.empty? ? nil : ns.namespaces[next_part.to_sym]
+          return nil if ns.nil?
+        end
+
+        if ns.namespaces.key?(tail)
+          ns = ns.namespaces[tail]
+          tail = DEFAULT_TASK
+        end
+
+        ns.tasks[tail]
+      end
+
+      # Given a task name, this will search the current namespace, and all
+      # parent namespaces, looking for a task that matches the name, exactly.
+      # It returns the task, if found, or nil, if not.
+      def search_task(name)
+        name = name.to_sym
+        ns = self
+
+        until ns.nil?
+          return ns.tasks[name] if ns.tasks.key?(name)
+          ns = ns.parent
+        end
+
+        return nil
+      end
+
+      # Returns the default task for this namespace. This will be +nil+ if
+      # the namespace is at the top-level, and will otherwise return the
+      # task named "default". If no such task exists, +nil+ will be returned.
+      def default_task
+        return nil if parent.nil?
+        return tasks[DEFAULT_TASK]
+      end
+  
+      # Returns the tasks in this namespace as an array of TaskDefinition
+      # objects. If a non-false parameter is given, all tasks in all
+      # namespaces under this namespace will be returned as well.
+      def task_list(all=false)
+        list = tasks.values
+        namespaces.each { |name,space| list.concat(space.task_list(:all)) } if all
+        list
+      end
+
+      private
+
+        def all_methods
+          public_methods.concat(protected_methods).concat(private_methods)
+        end
+
+        class Namespace
+          def initialize(name, parent)
+            @parent = parent
+            @name = name
+          end
+
+          def role(*args)
+            raise NotImplementedError, "roles cannot be defined in a namespace"
+          end
+
+          def respond_to?(sym, include_priv=false)
+            super || parent.respond_to?(sym, include_priv)
+          end
+
+          def method_missing(sym, *args, &block)
+            if parent.respond_to?(sym)
+              parent.send(sym, *args, &block)
+            else
+              super
+            end
+          end
+
+          include Capistrano::Configuration::Namespaces
+          undef :desc, :next_description
+        end
+    end
+  end
+end

data/lib/capistrano/configuration/roles.rb

@@ -0,0 +1,73 @@
+require 'capistrano/server_definition'
+require 'capistrano/role'
+
+module Capistrano
+  class Configuration
+    module Roles
+      def self.included(base) #:nodoc:
+        base.send :alias_method, :initialize_without_roles, :initialize
+        base.send :alias_method, :initialize, :initialize_with_roles
+      end
+
+      # The hash of roles defined for this configuration. Each entry in the
+      # hash points to an array of server definitions that belong in that
+      # role.
+      attr_reader :roles
+
+      def initialize_with_roles(*args) #:nodoc:
+        initialize_without_roles(*args)
+        @roles = Hash.new { |h,k| h[k] = Role.new }
+      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"
+      #
+      # You can also encode the username and port number for each host in the
+      # server string, if needed:
+      #
+      #   role :web,  "www@web1.example.com"
+      #   role :file, "files.example.com:4144"
+      #   role :db,   "admin@db3.example.com:1234"
+      #
+      # Lastly, username and port number may be passed as options, if that is
+      # preferred; note that the options apply to all servers defined in
+      # that call to "role":
+      #
+      #   role :web, "web2", "web3", :user => "www", :port => 2345
+      def role(which, *args, &block)
+        options = args.last.is_a?(Hash) ? args.pop : {}
+        which = which.to_sym
+
+        # The roles Hash is defined so that unrecognized keys always auto-initialize
+        # to a new Role instance (see the assignment in the initialize_with_roles method,
+        # above). However, we explicitly assign here so that role declarations will
+        # vivify the role object even if there are no server arguments. (Otherwise,
+        # role(:app) won't actually instantiate a Role object for :app.)
+        roles[which] ||= Role.new
+
+        roles[which].push(block, options) if block_given?
+        args.each { |host| roles[which] << ServerDefinition.new(host, options) }
+      end
+
+      # An alternative way to associate servers with roles. If you have a server
+      # that participates in multiple roles, this can be a DRYer way to describe
+      # the relationships. Pass the host definition as the first parameter, and
+      # the roles as the remaining parameters:
+      #
+      #   server "master.example.com", :web, :app
+      def server(host, *roles)
+        options = roles.last.is_a?(Hash) ? roles.pop : {}
+        raise ArgumentError, "you must associate a server with at least one role" if roles.empty?
+        roles.each { |name| role(name, host, options) }
+      end
+    end
+  end
+end

data/lib/capistrano/configuration/servers.rb

@@ -0,0 +1,85 @@
+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.
+      #
+      # Yet additionally, if the HOSTFILTER environment variable is set, it
+      # will limit the result to hosts found in that (comma-separated) list.
+      #
+      # 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])
+        
+        if hosts.any?
+          filter_server_list(hosts.uniq)
+        else
+          roles  = role_list_from(ENV['ROLES'] || options[:roles] || self.roles.keys)
+          only   = options[:only] || {}
+          except = options[:except] || {}
+          
+          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 } }
+          filter_server_list(servers.uniq)
+        end
+      end
+
+    protected
+
+      def filter_server_list(servers)
+        return servers unless ENV['HOSTFILTER']
+        filters = ENV['HOSTFILTER'].split(/,/)
+        servers.select { |server| filters.include?(server.host) }
+      end
+
+      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