pocketknife 0.1.0 → 0.2.0

data/lib/pocketknife/node.rb

@@ -3,16 +3,16 @@ class Pocketknife
   #
   # A node represents a remote computer that will be managed with Pocketknife and <tt>chef-solo</tt>. It can connect to a node, execute commands on it, install the stack, and upload and apply configurations to it.
   class Node
-    # String name of the node.
+    # @return [String] Name of the node.
     attr_accessor :name
 
-    # Instance of a {Pocketknife}.
+    # @return [Pocketknife] The Pocketknife this node is associated with.
     attr_accessor :pocketknife
 
-    # Instance of Rye::Box connection, cached by {#connection}.
+    # @return [Rye::Box] The Rye::Box connection, cached by {#connection}.
     attr_accessor :connection_cache
 
-    # Hash with information about platform, cached by {#platform}.
+    # @return [Hash{Symbol => String, Numeric}] Information about platform, cached by {#platform}.
     attr_accessor :platform_cache
 
     # Initialize a new node.
@@ -25,9 +25,11 @@ class Pocketknife
       self.connection_cache = nil
     end
 
-    # Returns a Rye::Box connection.
+    # Returns a connection.
     #
     # Caches result to {#connection_cache}.
+    #
+    # @return [Rye::Box]
     def connection
       return self.connection_cache ||= begin
           rye = Rye::Box.new(self.name, :user => "root")
@@ -40,6 +42,7 @@ class Pocketknife
     #
     # @param [String] message The message to display.
     # @param [Boolean] importance How important is this? +true+ means important, +nil+ means normal, +false+ means unimportant.
+    # @return [void]
     def say(message, importance=nil)
       self.pocketknife.say("* #{self.name}: #{message}", importance)
     end
@@ -57,7 +60,7 @@ class Pocketknife
     # @return [Boolean] Has executable?
     def has_executable?(executable)
       begin
-        self.connection.execute(%{which "#{executable}" && test -x `which "#{executable}"`})
+        self.connection.execute(%{which #{executable.shellescape} && test -x `which #{executable.shellescape}`})
         return true
       rescue Rye::Err
         return false
@@ -68,14 +71,14 @@ class Pocketknife
     #
     # The information is formatted similar to this:
     #   {
-    #     :distributor=>"Ubuntu", # String with distributor name
-    #     :codename=>"maverick", # String with release codename
-    #     :release=>"10.10", # String with release number
-    #     :version=>10.1 # Float with release number
+    #     :distributor => "Ubuntu", # String with distributor name
+    #     :codename => "maverick", # String with release codename
+    #     :release => "10.10", # String with release number
+    #     :version => 10.1 # Float with release number
     #   }
     #
-    # @return [Hash<String, Object] Return a hash describing the node, see above.
-    # @raise [UnsupportedInstallationPlatform] Raised if there's no installation information for this platform.
+    # @return [Hash{Symbol => String, Numeric}] Return a hash describing the node, see above.
+    # @raise [UnsupportedInstallationPlatform] Don't know how to install on this platform.
     def platform
       return self.platform_cache ||= begin
         lsb_release = "/etc/lsb-release"
@@ -100,8 +103,9 @@ class Pocketknife
 
     # Installs Chef and its dependencies on a node if needed.
     #
-    # @raise [NotInstalling] Raised if Chef isn't installed, but user didn't allow installation.
-    # @raise [UnsupportedInstallationPlatform] Raised if there's no installation information for this platform.
+    # @return [void]
+    # @raise [NotInstalling] Can't install because user Chef isn't already present and user forbade automatic installation.
+    # @raise [UnsupportedInstallationPlatform] Don't know how to install on this platform.
     def install
       unless self.has_executable?("chef-solo")
         case self.pocketknife.can_install
@@ -136,6 +140,8 @@ class Pocketknife
     end
 
     # Installs Chef on the remote node.
+    #
+    # @return [void]
     def install_chef
       self.say("Installing chef...")
       self.execute("gem install --no-rdoc --no-ri chef", true)
@@ -143,6 +149,8 @@ class Pocketknife
     end
 
     # Installs Rubygems on the remote node.
+    #
+    # @return [void]
     def install_rubygems
       self.say("Installing rubygems...")
       self.execute(<<-HERE, true)
@@ -158,6 +166,8 @@ cd /root &&
     end
 
     # Installs Ruby on the remote node.
+    #
+    # @return [void]
     def install_ruby
       command = \
         case self.platform[:distributor].downcase
@@ -184,21 +194,26 @@ cd /root &&
     #     mynode.upload
     #   end
     #
-    # @yield [] Prepares the upload, executes the block, and cleans up the upload when done.
+    # @yield to execute the block, will prepare upload before block is invoked, and cleanup the temporary files afterwards.
+    # @return [void]
     def self.prepare_upload(&block)
+      # TODO make this an instance method so it can avoid creating a tarball if using :rsync
       begin
         # TODO either do this in memory or scope this to the PID to allow concurrency
         TMP_SOLO_RB.open("w") {|h| h.write(SOLO_RB_CONTENT)}
         TMP_CHEF_SOLO_APPLY.open("w") {|h| h.write(CHEF_SOLO_APPLY_CONTENT)}
         TMP_TARBALL.open("w") do |handle|
+          items = [
+            VAR_POCKETKNIFE_COOKBOOKS.basename,
+            VAR_POCKETKNIFE_SITE_COOKBOOKS.basename,
+            VAR_POCKETKNIFE_ROLES.basename,
+            VAR_POCKETKNIFE_DATA_BAGS.basename,
+            TMP_SOLO_RB,
+            TMP_CHEF_SOLO_APPLY
+          ].reject { |o| not File.exist?(o) }.map {|o| o.to_s}
+
           Archive::Tar::Minitar.pack(
-            [
-              VAR_POCKETKNIFE_COOKBOOKS.basename.to_s,
-              VAR_POCKETKNIFE_SITE_COOKBOOKS.basename.to_s,
-              VAR_POCKETKNIFE_ROLES.basename.to_s,
-              TMP_SOLO_RB.to_s,
-              TMP_CHEF_SOLO_APPLY.to_s
-            ],
+            items,
             handle
           )
         end
@@ -217,7 +232,10 @@ cd /root &&
     end
 
     # Cleans up cache of shared files uploaded to all nodes. This cache is created by the {prepare_upload} method.
+    #
+    # @return [void]
     def self.cleanup_upload
+      # TODO make this an instance method so it can avoid creating a tarball if using :rsync
       [
         TMP_TARBALL,
         TMP_SOLO_RB,
@@ -227,52 +245,120 @@ cd /root &&
       end
     end
 
+    # Rsync files to a node.
+    #
+    # @param [Array] args Arguments to sent to +rsync+, e.g. options, filenames, and target.
+    # @return [void]
+    # @raise [RsyncError] Something went wrong with the rsync.
+    def rsync(*args)
+      command = ['rsync', *args.map{|o| o.shellescape}]
+      unless system *command
+        raise Pocketknife::RsyncError.new(command.join(' '), self.name)
+      end
+    end
+
+    # Rsync a file to a node with options: <tt>--update --copy-links</tt>
+    #
+    # @param [Array] args Arguments to sent to +rsync+, e.g. options, filename, and target.
+    # @return [void]
+    # @raise [RsyncError] Something went wrong with the rsync.
+    def rsync_file(*args)
+      self.rsync("-uL", *args)
+    end
+
+    # Rsync directory to a node with options: <tt>--recursive --update --copy-links --delete</tt>
+    #
+    # @param [Array] args Arguments to sent to +rsync+, e.g. options, directory name, and target.
+    # @return [void]
+    # @raise [RsyncError] Something went wrong with the rsync.
+    def rsync_directory(*args)
+      self.rsync("-ruL", "--delete", *args)
+    end
+
     # Uploads configuration information to node.
     #
     # IMPORTANT: You must first call {prepare_upload} to create the shared files that will be uploaded.
+    #
+    # @return [void]
     def upload
       self.say("Uploading configuration...")
 
       self.say("Removing old files...", false)
       self.execute <<-HERE
 umask 0377 &&
-  rm -rf "#{ETC_CHEF}" "#{VAR_POCKETKNIFE}" "#{VAR_POCKETKNIFE_CACHE}" "#{CHEF_SOLO_APPLY}" "#{CHEF_SOLO_APPLY_ALIAS}" &&
-  mkdir -p "#{ETC_CHEF}" "#{VAR_POCKETKNIFE}" "#{VAR_POCKETKNIFE_CACHE}" "#{CHEF_SOLO_APPLY.dirname}"
+  rm -rf #{ETC_CHEF.shellescape} #{VAR_POCKETKNIFE.shellescape} #{VAR_POCKETKNIFE_CACHE.shellescape} #{CHEF_SOLO_APPLY.shellescape} #{CHEF_SOLO_APPLY_ALIAS.shellescape} &&
+  mkdir -p #{ETC_CHEF.shellescape} #{VAR_POCKETKNIFE.shellescape} #{VAR_POCKETKNIFE_CACHE.shellescape} #{CHEF_SOLO_APPLY.dirname.shellescape}
       HERE
 
-      self.say("Uploading new files...", false)
-      self.connection.file_upload(self.local_node_json_pathname.to_s, NODE_JSON.to_s)
-      self.connection.file_upload(TMP_TARBALL.to_s, VAR_POCKETKNIFE_TARBALL.to_s)
+      case self.pocketknife.transfer_mechanism
+      when :tar
+        self.say("Uploading new files...", false)
+        self.connection.file_upload(self.local_node_json_pathname.to_s, NODE_JSON.to_s)
+        self.connection.file_upload(TMP_TARBALL.to_s, VAR_POCKETKNIFE_TARBALL.to_s)
 
-      self.say("Installing new files...", false)
-      self.execute <<-HERE, true
-cd "#{VAR_POCKETKNIFE_CACHE}" &&
-  tar xf "#{VAR_POCKETKNIFE_TARBALL}" &&
+        self.say("Installing new files...", false)
+        self.execute <<-HERE, true
+cd #{VAR_POCKETKNIFE_CACHE.shellescape} &&
+  tar xf #{VAR_POCKETKNIFE_TARBALL.shellescape} &&
   chmod -R u+rwX,go= . &&
   chown -R root:root . &&
-  mv "#{TMP_SOLO_RB}" "#{SOLO_RB}" &&
-  mv "#{TMP_CHEF_SOLO_APPLY}" "#{CHEF_SOLO_APPLY}" &&
-  chmod u+x "#{CHEF_SOLO_APPLY}" &&
-  ln -s "#{CHEF_SOLO_APPLY.basename}" "#{CHEF_SOLO_APPLY_ALIAS}" &&
-  rm "#{VAR_POCKETKNIFE_TARBALL}" &&
-  mv * "#{VAR_POCKETKNIFE}"
-      HERE
+  mv #{TMP_SOLO_RB.shellescape} #{SOLO_RB.shellescape} &&
+  mv #{TMP_CHEF_SOLO_APPLY.shellescape} #{CHEF_SOLO_APPLY.shellescape} &&
+  chmod u+x #{CHEF_SOLO_APPLY.shellescape} &&
+  ln -s #{CHEF_SOLO_APPLY.basename.shellescape} #{CHEF_SOLO_APPLY_ALIAS.shellescape} &&
+  rm #{VAR_POCKETKNIFE_TARBALL.shellescape} &&
+  mv * #{VAR_POCKETKNIFE.shellescape}
+        HERE
+
+      when :rsync
+        self.say("Uploading new files...", false)
+
+        self.rsync_file("#{self.local_node_json_pathname}", "root@#{self.name}:#{NODE_JSON}")
+
+        %w[SOLO_RB CHEF_SOLO_APPLY].each do |fragment|
+          source = self.class.const_get("TMP_#{fragment}")
+          target = self.class.const_get(fragment)
+          self.rsync_file("#{source}", "root@#{self.name}:#{target}")
+        end
+
+        %w[COOKBOOKS SITE_COOKBOOKS ROLES DATA_BAGS].each do |fragment|
+          target = self.class.const_get("VAR_POCKETKNIFE_#{fragment}")
+          source = target.basename
+          next unless source.exist?
+          self.rsync_directory("#{source}/", "root@#{self.name}:#{target}")
+        end
+
+        self.say("Modifying new files...", false)
+        self.execute <<-HERE, true
+cd #{VAR_POCKETKNIFE_CACHE.shellescape} &&
+  chmod u+x #{CHEF_SOLO_APPLY.shellescape} &&
+  ln -s #{CHEF_SOLO_APPLY.basename.shellescape} #{CHEF_SOLO_APPLY_ALIAS.shellescape}
+        HERE
+
+      else
+        raise InvalidTransferMechanism.new(self.pocketknife.transfer_mechanism)
+      end
 
       self.say("Finished uploading!", false)
     end
 
     # Applies the configuration to the node. Installs Chef, Ruby and Rubygems if needed.
+    #
+    # @return [void]
     def apply
       self.install
 
       self.say("Applying configuration...", true)
-      command = "chef-solo -j #{NODE_JSON}"
+      command = "chef-solo -j #{NODE_JSON.shellescape}"
+      command << " -o #{self.pocketknife.runlist}" if self.pocketknife.runlist
       command << " -l debug" if self.pocketknife.verbosity == true
       self.execute(command, true)
       self.say("Finished applying!")
     end
 
     # Deploys the configuration to the node, which calls {#upload} and {#apply}.
+    #
+    # @return [void]
     def deploy
       self.upload
       self.apply
@@ -283,7 +369,7 @@ cd "#{VAR_POCKETKNIFE_CACHE}" &&
     # @param [String] commands Shell commands to execute.
     # @param [Boolean] immediate Display execution information immediately to STDOUT, rather than returning it as an object when done.
     # @return [Rye::Rap] A result object describing the completed execution.
-    # @raise [ExecutionError] Raised if something goes wrong with execution.
+    # @raise [ExecutionError] Something went wrong with the execution, the cause is described in the exception.
     def execute(commands, immediate=false)
       self.say("Executing:\n#{commands}", false)
       if immediate
@@ -323,12 +409,17 @@ cd "#{VAR_POCKETKNIFE_CACHE}" &&
     # Remote path to pocketknife's roles
     # @private
     VAR_POCKETKNIFE_ROLES = VAR_POCKETKNIFE + "roles"
+    # Remote path to pocketknife's databags
+    # @private
+    VAR_POCKETKNIFE_DATA_BAGS = VAR_POCKETKNIFE + "data_bags"
+
     # Content of the solo.rb file
     # @private
     SOLO_RB_CONTENT = <<-HERE
 file_cache_path "#{VAR_POCKETKNIFE_CACHE}"
 cookbook_path ["#{VAR_POCKETKNIFE_COOKBOOKS}", "#{VAR_POCKETKNIFE_SITE_COOKBOOKS}"]
 role_path "#{VAR_POCKETKNIFE_ROLES}"
+data_bag_path "#{VAR_POCKETKNIFE_DATA_BAGS}"
     HERE
     # Remote path to chef-solo-apply
     # @private

data/lib/pocketknife/node_manager.rb

@@ -3,16 +3,16 @@ class Pocketknife
   #
   # This class finds, validates and manages {Pocketknife::Node} instances for a {Pocketknife}.
   class NodeManager
-    # Instance of a Pocketknife.
+    # @return [Pocketknife] The Pocketknife instance to manage.
     attr_accessor :pocketknife
 
-    # Hash of Node instances by their name.
+    # @return [Hash{String => Pocketknife::Node}] Node instances by their name.
     attr_accessor :nodes
 
-    # Array of known nodes, used as cache by {#known_nodes}.
+    # @return [Array<Pocketknife::Node>] Known nodes, cached by {#known_nodes}.
     attr_accessor :known_nodes_cache
 
-    # Instantiate a new manager.
+    # Instantiates a new manager.
     #
     # @param [Pocketknife] pocketknife
     def initialize(pocketknife)
@@ -21,7 +21,7 @@ class Pocketknife
       self.known_nodes_cache = nil
     end
 
-    # Return a node. Uses cached value in {#known_nodes_cache} if available.
+    # Returns a node. Uses cached value in {#known_nodes_cache} if available.
     #
     # @param [String] name A node name to find, can be an abbrevation.
     # @return [Pocketknife::Node]
@@ -38,9 +38,9 @@ class Pocketknife
     #
     # The abbreviated node name given must match only one node exactly. For example, you'll get a {Pocketknife::NoSuchNode} if you ask for an abbreviated node by the name of <tt>giovanni</tt> when there are nodes called <tt>giovanni.boldini.it</tt> and <tt>giovanni.bellini.it</tt> -- you'd need to ask using a more specific name, such as <tt>giovanni.boldini</tt>.
     #
-    # @param [String] abbreviated_name A node name, which may be abbreviated, e.g. "henrietta".
-    # @return [String] The complete node name, e.g. "henrietta.swa.gov.it"
-    # @raise [NoSuchNode] A hostname could not be found for this node, either because the node doesn't exist or the abbreviated form isn't unique enough.
+    # @param [String] abbreviated_name A node name, which may be abbreviated, e.g. <tt>henrietta</tt>.
+    # @return [String] The complete node name, e.g. <tt>henrietta.swa.gov.it</tt>.
+    # @raise [NoSuchNode] Couldn't find this node, either because it doesn't exist or the abbreviation isn't unique.
     def hostname_for(abbreviated_name)
       if self.known_nodes.include?(abbreviated_name)
         return abbreviated_name
@@ -59,8 +59,9 @@ class Pocketknife
 
     # Asserts that the specified nodes are known to Pocketknife.
     #
-    # @param [Array<String>] nodes A list of node names.
-    # @raise [Pocketknife::NoSuchNode] Raised if there's an unknown node.
+    # @param [Array<String>] names A list of node names.
+    # @return [void]
+    # @raise [Pocketknife::NoSuchNode] Couldn't find a node.
     def assert_known(names)
       for name in names
         # This will raise a NoSuchNode exception if there's a problem.
@@ -73,7 +74,7 @@ class Pocketknife
     # Caches results to {#known_nodes_cache}.
     #
     # @return [Array<String>] The node names.
-    # @raise [Errno::ENOENT] Raised if can't find the +nodes+ directory.
+    # @raise [Errno::ENOENT] Can't find the +nodes+ directory.
     def known_nodes
       return(self.known_nodes_cache ||= begin
           dir = Pathname.new("nodes")

data/lib/pocketknife/version.rb

@@ -3,11 +3,16 @@ class Pocketknife
   #
   # Information about the Pocketknife version.
   module Version
+    # @return [Integer] Major version.
     MAJOR = 0
-    MINOR = 1
+    # @return [Integer] Minor version.
+    MINOR = 2
+    # @return [Integer] Patch version.
     PATCH = 0
+    # @return [Integer] Build version.
     BUILD = nil
 
+    # @return [String] The version as a string.
     STRING = [MAJOR, MINOR, PATCH, BUILD].compact.join('.')
   end
 end

data/lib/shellwords.rb

@@ -0,0 +1,153 @@
+#
+# shellwords.rb: Manipulates strings a la UNIX Bourne shell
+#
+
+#
+# This module manipulates strings according to the word parsing rules
+# of the UNIX Bourne shell.
+#
+# The shellwords() function was originally a port of shellwords.pl,
+# but modified to conform to POSIX / SUSv3 (IEEE Std 1003.1-2001).
+#
+# Authors:
+#   - Wakou Aoyama
+#   - Akinori MUSHA <knu@iDaemons.org>
+#
+# Contact:
+#   - Akinori MUSHA <knu@iDaemons.org> (current maintainer)
+#
+module Shellwords
+  # Splits a string into an array of tokens in the same way the UNIX
+  # Bourne shell does.
+  #
+  #   argv = Shellwords.split('here are "two words"')
+  #   argv #=> ["here", "are", "two words"]
+  #
+  # String#shellsplit is a shorthand for this function.
+  #
+  #   argv = 'here are "two words"'.shellsplit
+  #   argv #=> ["here", "are", "two words"]
+  def shellsplit(line)
+    words = []
+    field = ''
+    line.scan(/\G\s*(?>([^\s\\\'\"]+)|'([^\']*)'|"((?:[^\"\\]|\\.)*)"|(\\.?)|(\S))(\s|\z)?/m) do
+      |word, sq, dq, esc, garbage, sep|
+      raise ArgumentError, "Unmatched double quote: #{line.inspect}" if garbage
+      field << (word || sq || (dq || esc).gsub(/\\(.)/, '\\1'))
+      if sep
+        words << field
+        field = ''
+      end
+    end
+    words
+  end
+
+  alias shellwords shellsplit
+
+  module_function :shellsplit, :shellwords
+
+  class << self
+    alias split shellsplit
+  end
+
+  # Escapes a string so that it can be safely used in a Bourne shell
+  # command line.
+  #
+  # Note that a resulted string should be used unquoted and is not
+  # intended for use in double quotes nor in single quotes.
+  #
+  #   open("| grep #{Shellwords.escape(pattern)} file") { |pipe|
+  #     # ...
+  #   }
+  #
+  # String#shellescape is a shorthand for this function.
+  #
+  #   open("| grep #{pattern.shellescape} file") { |pipe|
+  #     # ...
+  #   }
+  #
+  # It is caller's responsibility to encode the string in the right
+  # encoding for the shell environment where this string is used.
+  # Multibyte characters are treated as multibyte characters, not
+  # bytes.
+  def shellescape(str)
+    # An empty argument will be skipped, so return empty quotes.
+    return "''" if str.empty?
+
+    str = str.dup
+
+    # Treat multibyte characters as is.  It is caller's responsibility
+    # to encode the string in the right encoding for the shell
+    # environment.
+    str.gsub!(/([^A-Za-z0-9_\-.,:\/@\n])/, "\\\\\\1")
+
+    # A LF cannot be escaped with a backslash because a backslash + LF
+    # combo is regarded as line continuation and simply ignored.
+    str.gsub!(/\n/, "'\n'")
+
+    return str
+  end
+
+  module_function :shellescape
+
+  class << self
+    alias escape shellescape
+  end
+
+  # Builds a command line string from an argument list +array+ joining
+  # all elements escaped for Bourne shell and separated by a space.
+  #
+  #   open('|' + Shellwords.join(['grep', pattern, *files])) { |pipe|
+  #     # ...
+  #   }
+  #
+  # Array#shelljoin is a shorthand for this function.
+  #
+  #   open('|' + ['grep', pattern, *files].shelljoin) { |pipe|
+  #     # ...
+  #   }
+  #
+  def shelljoin(array)
+    array.map { |arg| shellescape(arg) }.join(' ')
+  end
+
+  module_function :shelljoin
+
+  class << self
+    alias join shelljoin
+  end
+end
+
+# @!visibility private
+class String
+  # call-seq:
+  #   str.shellsplit => array
+  #
+  # Splits +str+ into an array of tokens in the same way the UNIX
+  # Bourne shell does.  See Shellwords::shellsplit for details.
+  def shellsplit
+    Shellwords.split(self)
+  end
+
+  # call-seq:
+  #   str.shellescape => string
+  #
+  # Escapes +str+ so that it can be safely used in a Bourne shell
+  # command line.  See Shellwords::shellescape for details.
+  def shellescape
+    Shellwords.escape(self)
+  end
+end
+
+# @!visibility private
+class Array
+  # call-seq:
+  #   array.shelljoin => string
+  #
+  # Builds a command line string from an argument list +array+ joining
+  # all elements escaped for Bourne shell and separated by a space.
+  # See Shellwords::shelljoin for details.
+  def shelljoin
+    Shellwords.join(self)
+  end
+end