puppet 4.4.0-universal-darwin

data/lib/puppet/util/constant_inflector.rb

@@ -0,0 +1,24 @@
+# Created on 2008-02-12
+# Copyright Luke Kanies
+
+# NOTE: I think it might be worth considering moving these methods directly into Puppet::Util.
+
+# A common module for converting between constants and
+# file names.
+
+
+module Puppet
+  module Util
+    module ConstantInflector
+      def file2constant(file)
+        file.split("/").collect { |name| name.capitalize }.join("::").gsub(/_+(.)/) { |term| $1.capitalize }
+      end
+      module_function :file2constant
+
+      def constant2file(constant)
+        constant.to_s.gsub(/([a-z])([A-Z])/) { |term| $1 + "_#{$2}" }.gsub("::", "/").downcase
+      end
+      module_function :constant2file
+    end
+  end
+end

data/lib/puppet/util/diff.rb

@@ -0,0 +1,79 @@
+require 'tempfile'
+
+# Provide a diff between two strings.
+module Puppet::Util::Diff
+  include Puppet::Util::Execution
+  require 'tempfile'
+
+  def diff(old, new)
+    return '' unless diff_cmd = Puppet[:diff] and diff_cmd != ""
+
+    command = [diff_cmd]
+    if args = Puppet[:diff_args] and args != ""
+      args.split(' ').each do|arg|
+        command << arg
+      end
+    end
+    command << old << new
+    Puppet::Util::Execution.execute(command, :failonfail => false, :combine => false)
+  end
+
+  module_function :diff
+
+  # return diff string of two input strings
+  # format defaults to unified
+  # context defaults to 3 lines
+  def lcs_diff(data_old, data_new, format=:unified, context_lines=3)
+    unless Puppet.features.diff?
+      Puppet.warning "Cannot provide diff without the diff/lcs Ruby library"
+      return ""
+    end
+    data_old = data_old.split(/\n/).map! { |e| e.chomp }
+    data_new = data_new.split(/\n/).map! { |e| e.chomp }
+
+    output = ""
+
+    diffs = ::Diff::LCS.diff(data_old, data_new)
+    return output if diffs.empty?
+
+    oldhunk = hunk = nil
+    file_length_difference = 0
+
+    diffs.each do |piece|
+      begin
+
+        hunk = ::Diff::LCS::Hunk.new(
+          data_old, data_new, piece,
+            context_lines,
+
+            file_length_difference)
+        file_length_difference = hunk.file_length_difference
+      next unless oldhunk
+      # Hunks may overlap, which is why we need to be careful when our
+      # diff includes lines of context. Otherwise, we might print
+      # redundant lines.
+      if (context_lines > 0) and hunk.overlaps?(oldhunk)
+        hunk.unshift(oldhunk)
+      else
+        output << oldhunk.diff(format)
+      end
+      ensure
+        oldhunk = hunk
+        output << "\n"
+      end
+    end
+
+    # Handle the last remaining hunk
+    output << oldhunk.diff(format) << "\n"
+  end
+
+  def string_file_diff(path, string)
+    tempfile = Tempfile.new("puppet-diffing")
+    tempfile.open
+    tempfile.print string
+    tempfile.close
+    notice "\n" + diff(path, tempfile.path)
+    tempfile.delete
+  end
+end
+

data/lib/puppet/util/docs.rb

@@ -0,0 +1,128 @@
+# Some simple methods for helping manage automatic documentation generation.
+module Puppet::Util::Docs
+  # Specify the actual doc string.
+  def desc(str)
+    @doc = str
+  end
+
+  # Add a new autodoc block.  We have to define these as class methods,
+  # rather than just sticking them in a hash, because otherwise they're
+  # too difficult to do inheritance with.
+  def dochook(name, &block)
+    method = "dochook_#{name}"
+
+    meta_def method, &block
+  end
+
+  attr_writer :doc
+
+  # Generate the full doc string.
+  def doc
+    extra = methods.find_all { |m| m.to_s =~ /^dochook_.+/ }.sort.collect { |m|
+      self.send(m)
+    }.delete_if {|r| r.nil? }.collect {|r| "* #{r}"}.join("\n")
+
+    if @doc
+      scrub(@doc) + (extra.empty? ? '' : "\n\n#{extra}")
+    else
+      extra
+    end
+  end
+
+  # Build a table
+  def doctable(headers, data)
+    str = "\n\n"
+
+    lengths = []
+    # Figure out the longest field for all columns
+    data.each do |name, values|
+      [name, values].flatten.each_with_index do |value, i|
+        lengths[i] ||= 0
+        lengths[i] = value.to_s.length if value.to_s.length > lengths[i]
+      end
+    end
+
+    # The headers could also be longest
+    headers.each_with_index do |value, i|
+      lengths[i] = value.to_s.length if value.to_s.length > lengths[i]
+    end
+
+    # Add the header names
+    str += headers.zip(lengths).collect { |value, num| pad(value, num) }.join(" | ") + " |" + "\n"
+
+    # And the header row
+    str += lengths.collect { |num| "-" * num }.join(" | ") + " |" + "\n"
+
+    # Now each data row
+    data.sort { |a, b| a[0].to_s <=> b[0].to_s }.each do |name, rows|
+      str += [name, rows].flatten.zip(lengths).collect do |value, length|
+        pad(value, length)
+      end.join(" | ") + " |" + "\n"
+    end
+
+    str + "\n"
+  end
+
+  # There is nothing that would ever set this. It gets read in reference/type.rb, but will never have any value but nil.
+  attr_reader :nodoc
+  def nodoc?
+    nodoc
+  end
+
+  # Pad a field with spaces
+  def pad(value, length)
+    value.to_s + (" " * (length - value.to_s.length))
+  end
+
+  HEADER_LEVELS = [nil, "#", "##", "###", "####", "#####"]
+
+  def markdown_header(name, level)
+    "#{HEADER_LEVELS[level]} #{name}\n\n"
+  end
+
+  def markdown_definitionlist(term, definition)
+    lines = scrub(definition).split("\n")
+    str = "#{term}\n: #{lines.shift}\n"
+    lines.each do |line|
+      str << "  " if line =~ /\S/
+      str << "#{line}\n"
+    end
+    str << "\n"
+  end
+
+  # Strip indentation and trailing whitespace from embedded doc fragments.
+  #
+  # Multi-line doc fragments are sometimes indented in order to preserve the
+  # formatting of the code they're embedded in. Since indents are syntactic
+  # elements in Markdown, we need to make sure we remove any indent that was
+  # added solely to preserve surrounding code formatting, but LEAVE any indent
+  # that delineates a Markdown element (code blocks, multi-line bulleted list
+  # items). We can do this by removing the *least common indent* from each line.
+  #
+  # Least common indent is defined as follows:
+  #
+  # * Find the smallest amount of leading space on any line...
+  # * ...excluding the first line (which may have zero indent without affecting
+  #   the common indent)...
+  # * ...and excluding lines that consist solely of whitespace.
+  # * The least common indent may be a zero-length string, if the fragment is
+  #   not indented to match code.
+  # * If there are hard tabs for some dumb reason, we assume they're at least
+  #   consistent within this doc fragment.
+  #
+  # See tests in spec/unit/util/docs_spec.rb for examples.
+  def scrub(text)
+    # One-liners are easy! (One-liners may be buffered with extra newlines.)
+    return text.strip if text.strip !~ /\n/
+    excluding_first_line = text.partition("\n").last
+    indent = excluding_first_line.scan(/^[ \t]*(?=\S)/).min || '' # prevent nil
+    # Clean hanging indent, if any
+    if indent.length > 0
+      text = text.gsub(/^#{indent}/, '')
+    end
+    # Clean trailing space
+    text.lines.map{|line|line.rstrip}.join("\n").rstrip
+  end
+
+  module_function :scrub
+end

data/lib/puppet/util/errors.rb

@@ -0,0 +1,108 @@
+# Some helper methods for throwing and populating errors.
+#
+# @api public
+module Puppet::Util::Errors
+  # Throw a Puppet::DevError with the specified message.  Used for unknown or
+  # internal application failures.
+  #
+  # @param msg [String] message used in raised error
+  # @raise [Puppet::DevError] always raised with the supplied message
+  def devfail(msg)
+    self.fail(Puppet::DevError, msg)
+  end
+
+  # Add line and file info to the supplied exception if info is available from
+  # this object, is appropriately populated and the supplied exception supports
+  # it.  When other is supplied, the backtrace will be copied to the error
+  # object and the 'original' will be dropped from the error.
+  #
+  # @param error [Exception] exception that is populated with info
+  # @param other [Exception] original exception, source of backtrace info
+  # @return [Exception] error parameter
+  def adderrorcontext(error, other = nil)
+    error.line ||= self.line if error.respond_to?(:line=) and self.respond_to?(:line) and self.line
+    error.file ||= self.file if error.respond_to?(:file=) and self.respond_to?(:file) and self.file
+    error.original ||= other if error.respond_to?(:original=)
+
+    error.set_backtrace(other.backtrace) if other and other.respond_to?(:backtrace)
+    # It is not meaningful to keep the wrapped exception since its backtrace has already
+    # been adopted by the error. (The instance variable is private for good reasons).
+    error.instance_variable_set(:@original, nil)
+    error
+  end
+
+  # Return a human-readable string of this object's file and line attributes,
+  # if set.
+  #
+  # @return [String] description of file and line
+  def error_context
+    if file and line
+      " at #{file}:#{line}"
+    elsif line
+      " at line #{line}"
+    elsif file
+      " in #{file}"
+    else
+      ""
+    end
+  end
+
+  # Wrap a call in such a way that we always throw the right exception and keep
+  # as much context as possible.
+  #
+  # @param options [Hash<Symbol,Object>] options used to create error
+  # @option options [Class] :type error type to raise, defaults to
+  #   Puppet::DevError
+  # @option options [String] :message message to use in error, default mentions
+  #   the name of this class
+  # @raise [Puppet::Error] re-raised with extra context if the block raises it
+  # @raise [Error] of type options[:type], when the block raises other
+  #   exceptions
+  def exceptwrap(options = {})
+    options[:type] ||= Puppet::DevError
+    begin
+      return yield
+    rescue Puppet::Error => detail
+      raise adderrorcontext(detail)
+    rescue => detail
+      message = options[:message] || "#{self.class} failed with error #{detail.class}: #{detail}"
+
+      error = options[:type].new(message)
+      # We can't use self.fail here because it always expects strings,
+      # not exceptions.
+      raise adderrorcontext(error, detail)
+    end
+
+    retval
+  end
+
+  # Throw an error, defaulting to a Puppet::Error.
+  #
+  # @overload fail(message, ..)
+  #   Throw a Puppet::Error with a message concatenated from the given
+  #   arguments.
+  #   @param [String] message error message(s)
+  # @overload fail(error_klass, message, ..)
+  #   Throw an exception of type error_klass with a message concatenated from
+  #   the given arguments.
+  #   @param [Class] type of error
+  #   @param [String] message error message(s)
+  # @overload fail(error_klass, message, ..)
+  #   Throw an exception of type error_klass with a message concatenated from
+  #   the given arguments.
+  #   @param [Class] type of error
+  #   @param [String] message error message(s)
+  #   @param [Exception] original exception, source of backtrace info
+  def fail(*args)
+    if args[0].is_a?(Class)
+      type = args.shift
+    else
+      type = Puppet::Error
+    end
+
+    other = args.count > 1 ? args.pop : nil
+    error = adderrorcontext(type.new(args.join(" ")), other)
+
+    raise error
+  end
+end

data/lib/puppet/util/execution.rb

@@ -0,0 +1,356 @@
+require 'timeout'
+require 'puppet/file_system/uniquefile'
+
+module Puppet
+  require 'rbconfig'
+
+  require 'puppet/error'
+  # A command failed to execute.
+  # @api public
+  class ExecutionFailure < Puppet::Error
+  end
+end
+
+# This module defines methods for execution of system commands. It is intented for inclusion
+# in classes that needs to execute system commands.
+# @api public
+module Puppet::Util::Execution
+
+  # This is the full output from a process. The object itself (a String) is the
+  # stdout of the process.
+  #
+  # @api public
+  class ProcessOutput < String
+    # @return [Integer] The exit status of the process
+    # @api public
+    attr_reader :exitstatus
+
+    # @api private
+    def initialize(value,exitstatus)
+      super(value)
+      @exitstatus = exitstatus
+    end
+  end
+
+  # The command can be a simple string, which is executed as-is, or an Array,
+  # which is treated as a set of command arguments to pass through.
+  #
+  # In either case, the command is passed directly to the shell, STDOUT and
+  # STDERR are connected together, and STDOUT will be streamed to the yielded
+  # pipe.
+  #
+  # @param command [String, Array<String>] the command to execute as one string,
+  #   or as parts in an array. The parts of the array are joined with one
+  #   separating space between each entry when converting to the command line
+  #   string to execute.
+  # @param failonfail [Boolean] (true) if the execution should fail with
+  #   Exception on failure or not.
+  # @yield [pipe] to a block executing a subprocess
+  # @yieldparam pipe [IO] the opened pipe
+  # @yieldreturn [String] the output to return
+  # @raise [Puppet::ExecutionFailure] if the executed chiled process did not
+  #   exit with status == 0 and `failonfail` is `true`.
+  # @return [String] a string with the output from the subprocess executed by
+  #   the given block
+  #
+  # @see Kernel#open for `mode` values
+  # @api public
+  def self.execpipe(command, failonfail = true)
+    # Paste together an array with spaces.  We used to paste directly
+    # together, no spaces, which made for odd invocations; the user had to
+    # include whitespace between arguments.
+    #
+    # Having two spaces is really not a big drama, since this passes to the
+    # shell anyhow, while no spaces makes for a small developer cost every
+    # time this is invoked. --daniel 2012-02-13
+    command_str = command.respond_to?(:join) ? command.join(' ') : command
+
+    if respond_to? :debug
+      debug "Executing '#{command_str}'"
+    else
+      Puppet.debug "Executing '#{command_str}'"
+    end
+
+    # force the run of the command with
+    # the user/system locale to "C" (via environment variables LANG and LC_*)
+    # it enables to have non localized output for some commands and therefore
+    # a predictable output
+    english_env = ENV.to_hash.merge( {'LANG' => 'C', 'LC_ALL' => 'C'} )
+    output = Puppet::Util.withenv(english_env) do
+      open("| #{command_str} 2>&1") do |pipe|
+        yield pipe
+      end
+    end
+
+    if failonfail && exitstatus != 0
+      raise Puppet::ExecutionFailure, output
+    end
+
+    output
+  end
+
+  def self.exitstatus
+    $CHILD_STATUS.exitstatus
+  end
+  private_class_method :exitstatus
+
+  # Wraps execution of {execute} with mapping of exception to given exception (and output as argument).
+  # @raise [exception] under same conditions as {execute}, but raises the given `exception` with the output as argument
+  # @return (see execute)
+  # @api public
+  def self.execfail(command, exception)
+    output = execute(command)
+    return output
+  rescue Puppet::ExecutionFailure
+    raise exception, output, exception.backtrace
+  end
+
+  # Default empty options for {execute}
+  NoOptionsSpecified = {}
+
+  # Executes the desired command, and return the status and output.
+  # def execute(command, options)
+  # @param command [Array<String>, String] the command to execute. If it is
+  #   an Array the first element should be the executable and the rest of the
+  #   elements should be the individual arguments to that executable.
+  # @param options [Hash] a Hash of options
+  # @option options [Boolean]  :failonfail if this value is set to true, then this method will raise an error if the
+  #   command is not executed successfully.
+  # @option options [Integer, String] :uid (nil) the user id of the user that the process should be run as. Will be ignored if the
+  #   user id matches the effective user id of the current process.
+  # @option options [Integer, String] :gid (nil) the group id of the group that the process should be run as. Will be ignored if the
+  #   group id matches the effective group id of the current process.
+  # @option options [Boolean] :combine sets whether or not to combine stdout/stderr in the output, if false stderr output is discarded
+  # @option options [String] :stdinfile (nil) sets a file that can be used for stdin. Passing a string for stdin is not currently
+  #   supported.
+  # @option options [Boolean] :squelch (false) if true, ignore stdout / stderr completely.
+  # @option options [Boolean] :override_locale (true) by default (and if this option is set to true), we will temporarily override
+  #   the user/system locale to "C" (via environment variables LANG and LC_*) while we are executing the command.
+  #   This ensures that the output of the command will be formatted consistently, making it predictable for parsing.
+  #   Passing in a value of false for this option will allow the command to be executed using the user/system locale.
+  # @option options [Hash<{String => String}>] :custom_environment ({}) a hash of key/value pairs to set as environment variables for the duration
+  #   of the command.
+  # @return [Puppet::Util::Execution::ProcessOutput] output as specified by options
+  # @raise [Puppet::ExecutionFailure] if the executed chiled process did not exit with status == 0 and `failonfail` is
+  #   `true`.
+  # @note Unfortunately, the default behavior for failonfail and combine (since
+  #   0.22.4 and 0.24.7, respectively) depend on whether options are specified
+  #   or not. If specified, then failonfail and combine default to false (even
+  #   when the options specified are neither failonfail nor combine). If no
+  #   options are specified, then failonfail and combine default to true.
+  # @comment See commits efe9a833c and d32d7f30
+  # @api public
+  #
+  def self.execute(command, options = NoOptionsSpecified)
+    # specifying these here rather than in the method signature to allow callers to pass in a partial
+    # set of overrides without affecting the default values for options that they don't pass in
+    default_options = {
+        :failonfail => NoOptionsSpecified.equal?(options),
+        :uid => nil,
+        :gid => nil,
+        :combine => NoOptionsSpecified.equal?(options),
+        :stdinfile => nil,
+        :squelch => false,
+        :override_locale => true,
+        :custom_environment => {},
+    }
+
+    options = default_options.merge(options)
+
+    if command.is_a?(Array)
+      command = command.flatten.map(&:to_s)
+      str = command.join(" ")
+    elsif command.is_a?(String)
+      str = command
+    end
+
+    user_log_s = ''
+    if options[:uid]
+      user_log_s << " uid=#{options[:uid]}"
+    end
+    if options[:gid]
+      user_log_s << " gid=#{options[:gid]}"
+    end
+    if user_log_s != ''
+      user_log_s.prepend(' with')
+    end
+
+    if respond_to? :debug
+      debug "Executing#{user_log_s}: '#{str}'"
+    else
+      Puppet.debug "Executing#{user_log_s}: '#{str}'"
+    end
+
+    null_file = Puppet.features.microsoft_windows? ? 'NUL' : '/dev/null'
+
+    begin
+      stdin = File.open(options[:stdinfile] || null_file, 'r')
+      stdout = options[:squelch] ? File.open(null_file, 'w') : Puppet::FileSystem::Uniquefile.new('puppet')
+      stderr = options[:combine] ? stdout : File.open(null_file, 'w')
+
+      exec_args = [command, options, stdin, stdout, stderr]
+
+      if execution_stub = Puppet::Util::ExecutionStub.current_value
+        return execution_stub.call(*exec_args)
+      elsif Puppet.features.posix?
+        child_pid = nil
+        begin
+          child_pid = execute_posix(*exec_args)
+          exit_status = Process.waitpid2(child_pid).last.exitstatus
+          child_pid = nil
+        rescue Timeout::Error => e
+          # NOTE: For Ruby 2.1+, an explicit Timeout::Error class has to be
+          # passed to Timeout.timeout in order for there to be something for
+          # this block to rescue.
+          unless child_pid.nil?
+            Process.kill(:TERM, child_pid)
+            # Spawn a thread to reap the process if it dies.
+            Thread.new { Process.waitpid(child_pid) }
+          end
+
+          raise e
+        end
+      elsif Puppet.features.microsoft_windows?
+        process_info = execute_windows(*exec_args)
+        begin
+          exit_status = Puppet::Util::Windows::Process.wait_process(process_info.process_handle)
+        ensure
+          FFI::WIN32.CloseHandle(process_info.process_handle)
+          FFI::WIN32.CloseHandle(process_info.thread_handle)
+        end
+      end
+
+      [stdin, stdout, stderr].each {|io| io.close rescue nil}
+
+      # read output in if required
+      unless options[:squelch]
+        output = wait_for_output(stdout)
+        Puppet.warning "Could not get output" unless output
+      end
+
+      if options[:failonfail] and exit_status != 0
+        raise Puppet::ExecutionFailure, "Execution of '#{str}' returned #{exit_status}: #{output.strip}"
+      end
+    ensure
+      if !options[:squelch] && stdout
+        # if we opened a temp file for stdout, we need to clean it up.
+        stdout.close!
+      end
+    end
+
+    Puppet::Util::Execution::ProcessOutput.new(output || '', exit_status)
+  end
+
+  # Returns the path to the ruby executable (available via Config object, even if
+  # it's not in the PATH... so this is slightly safer than just using Puppet::Util.which)
+  # @return [String] the path to the Ruby executable
+  # @api private
+  #
+  def self.ruby_path()
+    File.join(RbConfig::CONFIG['bindir'],
+              RbConfig::CONFIG['ruby_install_name'] + RbConfig::CONFIG['EXEEXT']).
+      sub(/.*\s.*/m, '"\&"')
+  end
+
+  # Because some modules provide their own version of this method.
+  class << self
+    alias util_execute execute
+  end
+
+
+  # This is private method.
+  # @comment see call to private_class_method after method definition
+  # @api private
+  #
+  def self.execute_posix(command, options, stdin, stdout, stderr)
+    child_pid = Puppet::Util.safe_posix_fork(stdin, stdout, stderr) do
+
+      # We can't just call Array(command), and rely on it returning
+      # things like ['foo'], when passed ['foo'], because
+      # Array(command) will call command.to_a internally, which when
+      # given a string can end up doing Very Bad Things(TM), such as
+      # turning "/tmp/foo;\r\n /bin/echo" into ["/tmp/foo;\r\n", " /bin/echo"]
+      command = [command].flatten
+      Process.setsid
+      begin
+        Puppet::Util::SUIDManager.change_privileges(options[:uid], options[:gid], true)
+
+        # if the caller has requested that we override locale environment variables,
+        if (options[:override_locale]) then
+          # loop over them and clear them
+          Puppet::Util::POSIX::LOCALE_ENV_VARS.each { |name| ENV.delete(name) }
+          # set LANG and LC_ALL to 'C' so that the command will have consistent, predictable output
+          # it's OK to manipulate these directly rather than, e.g., via "withenv", because we are in
+          # a forked process.
+          ENV['LANG'] = 'C'
+          ENV['LC_ALL'] = 'C'
+        end
+
+        # unset all of the user-related environment variables so that different methods of starting puppet
+        # (automatic start during boot, via 'service', via /etc/init.d, etc.) won't have unexpected side
+        # effects relating to user / home dir environment vars.
+        # it's OK to manipulate these directly rather than, e.g., via "withenv", because we are in
+        # a forked process.
+        Puppet::Util::POSIX::USER_ENV_VARS.each { |name| ENV.delete(name) }
+
+        options[:custom_environment] ||= {}
+        Puppet::Util.withenv(options[:custom_environment]) do
+          Kernel.exec(*command)
+        end
+      rescue => detail
+        Puppet.log_exception(detail, "Could not execute posix command: #{detail}")
+        exit!(1)
+      end
+    end
+    child_pid
+  end
+  private_class_method :execute_posix
+
+
+  # This is private method.
+  # @comment see call to private_class_method after method definition
+  # @api private
+  #
+  def self.execute_windows(command, options, stdin, stdout, stderr)
+    command = command.map do |part|
+      part.include?(' ') ? %Q["#{part.gsub(/"/, '\"')}"] : part
+    end.join(" ") if command.is_a?(Array)
+
+    options[:custom_environment] ||= {}
+    Puppet::Util.withenv(options[:custom_environment], :windows) do
+      Puppet::Util::Windows::Process.execute(command, options, stdin, stdout, stderr)
+    end
+  end
+  private_class_method :execute_windows
+
+
+  # This is private method.
+  # @comment see call to private_class_method after method definition
+  # @api private
+  #
+  def self.wait_for_output(stdout)
+    # Make sure the file's actually been written.  This is basically a race
+    # condition, and is probably a horrible way to handle it, but, well, oh
+    # well.
+    # (If this method were treated as private / inaccessible from outside of this file, we shouldn't have to worry
+    #  about a race condition because all of the places that we call this from are preceded by a call to "waitpid2",
+    #  meaning that the processes responsible for writing the file have completed before we get here.)
+    2.times do |try|
+      if Puppet::FileSystem.exist?(stdout.path)
+        stdout.open
+        begin
+          return stdout.read
+        ensure
+          stdout.close
+          stdout.unlink
+        end
+      else
+        time_to_sleep = try / 2.0
+        Puppet.warning "Waiting for output; will sleep #{time_to_sleep} seconds"
+        sleep(time_to_sleep)
+      end
+    end
+    nil
+  end
+  private_class_method :wait_for_output
+end