capistrano-distribution 0.2.0

data/lib/capistrano/distribution/distributor/abstract_git.rb

@@ -0,0 +1,56 @@
+require 'capistrano/distribution/distributor/abstract'
+
+module Capistrano
+class Distribution
+module Distributor
+
+##
+# @abstract Subclass and override {#check} and {#distribute} to create a
+#   distributor that uses Git to distribute code from a Git repository.
+#
+# An abstract distributor that operates on Git repositories.
+class AbstractGit < Abstract
+  ##
+  # The identifier for a Git commit that will be distributed.
+  attr_reader :revision
+
+  ##
+  # @param url [URI, String] a URL to be used for fetching the artifact to be
+  #   distributed
+  # @param revision [String] a commit identifier (revision SHA or ref) to be
+  #   distributed
+  def initialize(context, url, revision, opts = {})
+    super(context, url, opts)
+    @revision = revision
+    @subtree = opts[:subtree]
+  end
+
+  private
+
+  ##
+  # A subtree of the repository to distribute.
+  attr_reader :subtree
+
+  ##
+  # Extracts the content of the commit at {#revision} from the local mirror of
+  # the repository to {#release_path}.
+  #
+  # @return [nil]
+  def release
+    context.execute 'mkdir', '-p', release_path
+
+    if subtree
+      path = subtree.slice %r#^/?(.*?)/?$#, 1
+      components = path.split('/').size
+      context.execute :git, '--git-dir', repo_path, :archive, revision, path, "| tar -x --strip-components #{components} -f - -C", release_path
+    else
+      context.execute :git, '--git-dir', repo_path, :archive, revision, '| tar -x -f - -C', release_path
+    end
+
+    nil
+  end
+end
+
+end
+end
+end

data/lib/capistrano/distribution/distributor/curl_tar.rb

@@ -0,0 +1,36 @@
+require 'capistrano/distribution/distributor/abstract_curl'
+require 'capistrano/distribution/distributor/tar_helper'
+
+module Capistrano
+class Distribution
+module Distributor
+
+##
+# Deploys Tar files downloadable using the +curl+ command.
+class CurlTar < AbstractCurl
+  include TarHelper
+
+  ##
+  # Extracts the content rooted under {#subtree} within the Tar file indicated
+  # by {#url} to the location indicated by {#release_path}.  The Tar file is
+  # extracted as it is downloaded, so no local copy of the Tar file itself is
+  # ever created.
+  #
+  # @return [nil]
+  #
+  # @see Archiver#distribute
+  def distribute
+    context.execute 'mkdir', '-p', release_path
+    context.execute 'curl', '--fail', '--location', '--silent', url, '|',
+                    'tar', '-x',
+                    compression_opt,
+                    strip_components_opt,
+                    '-C', release_path,
+                    subtree
+    nil
+  end
+end
+
+end
+end
+end

data/lib/capistrano/distribution/distributor/curl_zip.rb

@@ -0,0 +1,40 @@
+require 'capistrano/distribution/distributor/abstract_curl'
+
+module Capistrano
+class Distribution
+module Distributor
+
+##
+# Deploys ZIP files downloadable using the +curl+ command.
+class CurlZip < AbstractCurl
+  ##
+  # Extracts the content rooted under {#subtree} within the ZIP file indicated
+  # by {#url} to the location indicated by {#release_path}.  Because the +unzip+
+  # utility is unable to extract a ZIP file over a pipe, a local copy of the
+  # entire ZIP file is made during the extraction process and then removed.
+  #
+  # @return [nil]
+  #
+  # @see Archiver#distribute
+  def distribute
+    zip_path = repo_path.to_s + '.zip'
+
+    context.execute 'curl', '--fail', '--location', '--silent',
+                    '--output', zip_path, url
+
+    context.execute 'mkdir', '-p', repo_path
+    context.execute 'unzip', '-q',
+                    '-d', repo_path,
+                    zip_path,
+                    subtree.join('\\*')
+    context.execute 'mv', repo_path.join(subtree), release_path
+
+    context.execute 'rm', '-rf', zip_path, repo_path
+
+    nil
+  end
+end
+
+end
+end
+end

data/lib/capistrano/distribution/distributor/git_pull.rb

@@ -0,0 +1,67 @@
+require 'capistrano/distribution/distributor/abstract_git'
+
+module Capistrano
+class Distribution
+module Distributor
+
+##
+# Distributes by mirroring a remote Git repository on each target host and then
+# extracting the content from a revision to the release location.
+class GitPull < AbstractGit
+  ##
+  # Tests that the Git repository at {#url} is readable.
+  #
+  # @return [Boolean] +true+ if the repository is readable; otherwise, +false+
+  def check
+    context.test 'git', 'ls-remote', url
+  end
+
+  ##
+  # Creates a mirror of the Git repository at {#url} if necessary, pulls updates
+  # into it, and finally extracts the revision to the release area.  The Git
+  # repository is left in place in order to speed up future deployments by
+  # avoiding the need to pull *all* revision history again.
+  #
+  # @return [nil]
+  #
+  # @raise [exception] when distribution fails.
+  def distribute
+    clone
+    update
+    release
+  end
+
+  private
+
+  ##
+  # Creates a mirror of the repository at {#url} in {#repo_path} if it does not
+  # already exist.
+  #
+  # @return [nil]
+  #
+  # @raise [exception] when mirror creation fails.
+  def clone
+    if context.test '[', '!', '-e', repo_path.join('HEAD'), ']'
+      context.execute 'rm', '-rf', repo_path
+      context.execute 'git', 'clone', '--mirror', url, repo_path
+    end
+    nil
+  end
+
+  ##
+  # Updates the Git mirror.
+  #
+  # @return [nil]
+  #
+  # @raise [exception] when updating the mirror fails.
+  def update
+    context.execute 'git', '--git-dir', repo_path,
+                    'remote', 'set-url', 'origin', url
+    context.execute 'git', '--git-dir', repo_path, 'remote', 'update', '--prune'
+    nil
+  end
+end
+
+end
+end
+end

data/lib/capistrano/distribution/distributor/git_push.rb

@@ -0,0 +1,73 @@
+require 'capistrano/distribution/distributor/abstract_git'
+
+module Capistrano
+class Distribution
+module Distributor
+
+##
+# Distributes by pushing a local Git repository into a clone on each target host
+# and then extracting the content from a revision to the release location.
+class GitPush < AbstractGit
+  ##
+  # Always returns +true+ because this distributor does not pull content but
+  # rather relies on the distribute step to push the content up.
+  #
+  # @return [true]
+  def check
+    true
+  end
+
+  ##
+  # Prepares a Git repository if necessary, pushes the selected revision to the
+  # Git repository, and finally extracts the revision to the release area.  The
+  # Git repository is left in place in order to speed up future deployments by
+  # avoiding the need to upload *all* revision history again.
+  #
+  # @return [nil]
+  #
+  # @raise [exception] when distribution fails.
+  def distribute
+    init
+    push
+    release
+    nil
+  end
+
+  private
+
+  ##
+  # Initializes a bare Git repository in {#repo_path} if a repository does not
+  # already exist there.
+  #
+  # @return [nil]
+  #
+  # @raise [exception] when repository creation fails.
+  def init
+    if context.test '[', '!', '-e', repo_path.join('HEAD'), ']'
+      context.execute 'rm', '-rf', repo_path
+      context.execute 'git', 'init', '--bare', repo_path
+    end
+    nil
+  end
+
+  ##
+  # Pushes {#revision} and all its history to the Git repository within
+  # {#repo_path}.
+  #
+  # @raise [exception] when the push to the repository fails.
+  def push
+    user = context.host.user
+    hostname = context.host.hostname
+    repo_path = self.repo_path
+    revision = self.revision
+    context.run_locally do
+      execute 'git', 'push',
+              "ssh://#{user}@#{hostname}/#{repo_path}",
+              "+#{revision}:refs/tags/deploy"
+    end
+  end
+end
+
+end
+end
+end

data/lib/capistrano/distribution/distributor/tar.rb

@@ -0,0 +1,35 @@
+require 'capistrano/distribution/distributor/abstract_archiver'
+require 'capistrano/distribution/distributor/tar_helper'
+
+module Capistrano
+class Distribution
+module Distributor
+
+##
+# Deploys locally available Tar files.
+class Tar < AbstractArchiver
+  include TarHelper
+
+  ##
+  # Extracts the content rooted under {#subtree} within the Tar file indicated
+  # by {#url} to the location indicated by {#release_path}.
+  #
+  # @return [nil]
+  #
+  # @see Abstract#distribute
+  def distribute
+    context.execute 'mkdir', '-p', release_path
+    context.execute 'tar', '-x',
+                    compression_opt,
+                    strip_components_opt,
+                    '-C', release_path,
+                    '-f', url.path,
+                    subtree
+
+    nil
+  end
+end
+
+end
+end
+end

data/lib/capistrano/distribution/distributor/tar_helper.rb

@@ -0,0 +1,40 @@
+module Capistrano
+class Distribution
+module Distributor
+
+##
+# A mixin containing methods useful for distributors that extract Tar files.
+module TarHelper
+  private
+
+  ##
+  # @return [String] the tar compression option to use based on the
+  #   {Abstract#url} attribute
+  #
+  # @raise [RuntimeError] if the compression option cannot be guessed.
+  def compression_opt
+    case url.path
+    when %r{\.(tar\.gz|tgz)$}
+      '-z'
+    when %r{\.(tar\.bz2|tbz2)$}
+      '-j'
+    when %r{\.tar$}
+      ''
+    else
+      raise "Unable to guess decompression option for URL: #{url}"
+    end
+  end
+
+  ##
+  # @return [String] the component stripping option based on the number of path
+  #   elements in the {AbstractArchiver#subtree} attribute
+  def strip_components_opt
+    path = subtree.to_s.slice %r#^/?(.*?)/?$#, 1
+    components = path.split('/').size
+    "--strip-components #{components}"
+  end
+end
+
+end
+end
+end

data/lib/capistrano/distribution/distributor/zip.rb

@@ -0,0 +1,31 @@
+require 'capistrano/distribution/distributor/abstract_archiver'
+
+module Capistrano
+class Distribution
+module Distributor
+
+##
+# Deploys locally available ZIP files.
+class Zip < AbstractArchiver
+  ##
+  # Extracts the content rooted under {#subtree} within the ZIP file indicated
+  # by {#url} to the location indicated by {#release_path}.
+  #
+  # @return [nil]
+  #
+  # @see Abstract#distribute
+  def distribute
+    context.execute 'mkdir', '-p', repo_path
+    context.execute 'unzip', '-q',
+                    '-d', repo_path,
+                    url.path,
+                    subtree.join('\\*')
+    context.execute 'mv', repo_path.join(subtree), release_path
+
+    nil
+  end
+end
+
+end
+end
+end

data/lib/capistrano/distribution/distributor.rb

@@ -0,0 +1,102 @@
+require 'digest'
+require 'pathname'
+require 'uri'
+
+module Capistrano
+class Distribution
+
+##
+# This module is a factory for creating distributor objects that are able to
+# fetch distributable artifacts from various sources and deploy them to a
+# target host.
+module Distributor
+  ##
+  # Create a concrete distributor object based on _definition_.
+  #
+  # When _definition_ is a String, it is assumed to be a URL that is used to
+  # guess about the type of distributor to create.  For instance, URLs that
+  # end with `.git` will elicit the Git::Pull distributor.  A URL without a
+  # scheme and ending with .tgz will elicit the Tar distributor.
+  #
+  # When _definition_ is an Array and the first element is a String, the
+  # distributor class is guessed using that String as in the case when
+  # _definition_ is simply a String itself.  The remaining members of the
+  # array are passed to the selected class' initializer as arguments.
+  #
+  # When _definition_ is an Array and the first element is a Symbol, the
+  # Symbol is assumed to map to the class of the distributor to instantiate.
+  # The Symbol +:curl_tar+ maps to the Curl::Tar distributor for example.  The
+  # remaining members of the array are passed to the selected class'
+  # initializer as arguments.
+  #
+  # When _definition_ is anything else, it is returned directly under the
+  # assumption that the configuration explicitly created a distributor.
+  #
+  # @param context [{#test, #execute}] a Capistrano context used to run
+  #   commands.
+  # @param definition [String, Array, other] a distributor definition.
+  #
+  # @return a distributor
+  def self.create(context, definition)
+    case definition
+    when String
+      type = type_from_url(definition)
+      constantize(type).new(context, definition)
+    when Array
+      if Symbol === definition.first
+        type, *args = definition
+      else
+        type = type_from_url(definition.first)
+        args = definition
+      end
+      constantize(type).new(context, *args)
+    else
+      definition
+    end
+  end
+
+  private
+
+  ##
+  # Return a distributor type based on _url_.
+  #
+  # @param url [URI] a URL denoting the location of the artifact to be
+  #   deployed.
+  #
+  # @return [Symbol] a distributor type
+  def self.type_from_url(url)
+    url = URI.parse(url.to_s)
+
+    type =
+      if url.scheme == 'git' || url.path =~ %r{\.git$}
+        :git_pull
+      elsif url.scheme.nil? || url.scheme == 'file'
+        if url.path =~ %r{\.(tar(\.(gz|bzip2))?|tgz|tbz2)$}i
+          :tar
+        elsif url.path =~ %r{\.zip$}i
+          :zip
+        end
+      elsif url.path =~ %r{\.(tar(\.(gz|bzip2))?|tgz|tbz2)$}i
+        :curl_tar
+      elsif url.path =~ %r{\.zip$}i
+        :curl_zip
+      end
+
+    raise "Unable to guess distributor type for URL: #{url}" if type.nil?
+    type
+  end
+
+  ##
+  # Finds the class to use for a distributor given a Symbol.
+  #
+  # @param type [Symbol] maps to a distributor class.
+  #
+  # @return a distributor class.
+  def self.constantize(type)
+    require "capistrano/distribution/distributor/#{type}"
+    const_get(type.to_s.split('_').map(&:capitalize).join)
+  end
+end
+
+end
+end

data/lib/capistrano/distribution/version.rb

@@ -0,0 +1,9 @@
+module Capistrano
+
+class Distribution
+  ##
+  # The release version of this gem.
+  VERSION = '0.2.0'
+end
+
+end

data/lib/capistrano/distribution.rb

@@ -0,0 +1,68 @@
+require 'capistrano/distribution/distributor'
+load File.expand_path('../tasks/distribution.cap', __FILE__)
+
+module Capistrano
+
+##
+# A list of distributors to run.
+class Distribution
+  ##
+  # Creates the list of distributors to run based on the definition found in the
+  # +:distribution+ key of _context_.  The value associated the +distribution+
+  # can be 1 of 3 types:
+  # * String
+  # * Array of Arrays of distributor initialization arguments
+  # * Array of distributor instances
+  #
+  # @param context [{#fetch, #repo_path, #release_path}] a Capistrano deployment
+  #   context.
+  #
+  # @return [Distribution] an instance of this class.
+  def initialize(context)
+    @context = context
+    distributor_list = context.fetch(:distribution)
+
+    case distributor_list
+    when String
+      distributor_list = [[distributor_list]]
+    when Array
+      unless distributor_list.all? { |distributor| Array === distributor }
+        distributor_list = [distributor_list]
+      end
+    end
+
+    @distributors = distributor_list.map do |distributor|
+      Distributor.create(context, distributor)
+    end
+  end
+
+  ##
+  # An identifier for a release.
+  def release_id
+    context.fetch(:release_id)
+  end
+
+  ##
+  # Calls the #check method of each distributor in the list.
+  def check
+    distributors.all? { |distributor| distributor.check }
+  end
+
+  ##
+  # Calls the #distribute method of each distributor in the list.
+  def distribute
+    distributors.each { |distributor| distributor.distribute }
+  end
+
+  private
+
+  ##
+  # The list of distributors.
+  attr_reader :distributors
+
+  ##
+  # The Capistrano context object.
+  attr_reader :context
+end
+
+end

data/lib/capistrano/tasks/distribution.cap

@@ -0,0 +1,33 @@
+namespace :distribution do
+  def distribution
+    @distribution ||= Capistrano::Distribution.new(self)
+  end
+
+  desc 'Confirm that all required distributables are available'
+  task :check do
+    on release_roles(:all), fetch(:distribution_runner_opts) do
+      exit 1 unless distribution.check
+    end
+  end
+
+  desc 'Distribute the artifacts'
+  task :create_release do
+    on release_roles(:all), fetch(:distribution_runner_opts) do
+      within repo_path do
+        distribution.distribute
+      end
+    end
+  end
+
+  desc 'Set a revision identifier'
+  task :set_current_revision do
+    set(:current_revision, distribution.release_id)
+  end
+end
+
+namespace :load do
+  task :defaults do
+    puts 'foo'
+    set :distribution_runner_opts, {}
+  end
+end