puppet 4.2.3-x86-mingw32 → 4.3.0-x86-mingw32

data/lib/puppet/functions/map.rb

@@ -1,33 +1,68 @@
-# Applies a parameterized block to each element in a sequence of entries from the first
-# argument and returns an array with the result of each invocation of the parameterized block.
+# Applies a [lambda](http://docs.puppetlabs.com/puppet/latest/reference/lang_lambdas.html)
+# to every value in a data structure and returns an array containing the results.
 #
-# This function takes two mandatory arguments: the first should be an Array, Hash, or of Enumerable type
-# (integer, Integer range, or String), and the second a parameterized block as produced by the puppet syntax:
+# This function takes two mandatory arguments, in this order:
 #
-#       $a.map |$x| { ... }
-#       map($a) |$x| { ... }
+# 1. An array or hash the function will iterate over.
+# 2. A lambda, which the function calls for each element in the first argument. It can
+# request one or two parameters.
 #
-# When the first argument `$a` is an Array or of enumerable type, the block is called with each entry in turn.
-# When the first argument is a hash the entry is an array with `[key, value]`.
+# @example Using the `map` function
 #
-# @example Using map with two arguments
+# `$transformed_data = $data.map |$parameter| { <PUPPET CODE BLOCK> }`
 #
-#      # Turns hash into array of values
-#      $a.map |$x|{ $x[1] }
+# or
 #
-#      # Turns hash into array of keys
-#      $a.map |$x| { $x[0] }
+# `$transformed_data = map($data) |$parameter| { <PUPPET CODE BLOCK> }`
 #
-# When using a block with 2 parameters, the element's index (starting from 0) for an array, and the key for a hash
-# is given to the block's first parameter, and the value is given to the block's second parameter.args.
+# When the first argument (`$data` in the above example) is an array, Puppet passes each
+# value in turn to the lambda.
 #
-# @example Using map with two arguments
+# @example Using the `map` function with an array and a one-parameter lambda
 #
-#      # Turns hash into array of values
-#      $a.map |$key,$val|{ $val }
+# ~~~ puppet
+# # For the array $data, return an array containing each value multiplied by 10
+# $data = [1,2,3]
+# $transformed_data = $data.map |$items| { $items * 10 }
+# # $transformed_data contains [10,20,30]
+# ~~~
 #
-#      # Turns hash into array of keys
-#      $a.map |$key,$val|{ $key }
+# When the first argument is a hash, Puppet passes each key and value pair to the lambda
+# as an array in the form `[key, value]`.
+#
+# @example Using the `map` function with a hash and a one-parameter lambda
+#
+# ~~~ puppet
+# # For the hash $data, return an array containing the keys
+# $data = {'a'=>1,'b'=>2,'c'=>3}
+# $transformed_data = $data.map |$items| { $items[0] }
+# # $transformed_data contains ['a','b','c']
+# ~~~
+#
+# When the first argument is an array and the lambda has two parameters, Puppet passes the
+# array's indexes (enumerated from 0) in the first parameter and its values in the second
+# parameter.
+#
+# @example Using the `map` function with an array and a two-parameter lambda
+#
+# ~~~ puppet
+# # For the array $data, return an array containing the indexes
+# $data = [1,2,3]
+# $transformed_data = $data.map |$index,$value| { $index }
+# # $transformed_data contains [0,1,2]
+# ~~~
+#
+# When the first argument is a hash, Puppet passes its keys to the first parameter and its
+# values to the second parameter.
+#
+# @example Using the `map` function with a hash and a two-parameter lambda
+#
+# ~~~ puppet
+# # For the hash $data, return an array containing each value
+# $data = {'a'=>1,'b'=>2,'c'=>3}
+# $transformed_data = $data.map |$key,$value| { $value }
+# # $transformed_data contains [1,2,3]
+# ~~~
 #
 # @since 4.0.0
 #
@@ -57,7 +92,7 @@ Puppet::Functions.create_function(:map) do
   end
 
   def map_Hash_2(hash)
-      hash.map {|x, y| yield(x, y) }
+    hash.map {|x, y| yield(x, y) }
   end
 
   def map_Enumerable_1(enumerable)

data/lib/puppet/functions/match.rb

@@ -1,19 +1,36 @@
-# Returns the match result of matching a String or Array[String] with one of:
+# Matches a regular expression against a string and returns an array containing the match
+# and any matched capturing groups.
 #
-# * Regexp
-# * String - transformed to a Regexp
-# * Pattern type
-# * Regexp type
+# The first argument is a string or array of strings. The second argument is either a
+# regular expression, regular expression represented as a string, or Regex or Pattern
+# data type that the function matches against the first argument.
 #
-# Returns An Array with the entire match at index 0, and each subsequent submatch at index 1-n.
-# If there was no match, nil (ie. undef) is returned. If the value to match is an Array, a array
-# with mapped match results is returned.
+# The returned array contains the entire match at index 0, and each captured group at
+# subsequent index values. If the value or expression being matched is an array, the
+# function returns an array with mapped match results.
 #
-# @example matching
-#   "abc123".match(/([a-z]+)[1-9]+/)  # => ["abc"]
-#   "abc123".match(/([a-z]+)([1-9]+)/)  # => ["abc", "123"]
+# If the function doesn't find a match, it returns 'undef'.
+#
+# @example Matching a regular expression in a string
+#
+# ~~~ ruby
+# $matches = "abc123".match(/[a-z]+[1-9]+/)
+# # $matches contains [abc123]
+# ~~~
+#
+# @example Matching a regular expressions with grouping captures in a string
+#
+# ~~~ ruby
+# $matches = "abc123".match(/([a-z]+)([1-9]+)/)
+# # $matches contains [abc123, abc, 123]
+# ~~~
+#
+# @example Matching a regular expression with grouping captures in an array of strings
+#
+# ~~~ ruby
+# $matches = ["abc123","def456"].match(/([a-z]+)([1-9]+)/)
+# # $matches contains [[abc123, abc, 123], [def456, def, 456]]
 #
-# See the documentation for "The Puppet Type System" for more information about types.
 # @since 4.0.0
 #
 Puppet::Functions.create_function(:match) do

data/lib/puppet/functions/reduce.rb

@@ -1,61 +1,98 @@
-# Applies a parameterized block to each element in a sequence of entries from the first
-# argument (_the enumerable_) and returns the last result of the invocation of the parameterized block.
-#
-# This function takes two mandatory arguments: the first should be an Array, Hash, or something of
-# enumerable type, and the last a parameterized block as produced by the puppet syntax:
-#
-#       $a.reduce |$memo, $x| { ... }
-#       reduce($a) |$memo, $x| { ... }
-#
-# When the first argument is an Array or someting of an enumerable type, the block is called with each entry in turn.
-# When the first argument is a hash each entry is converted to an array with `[key, value]` before being
-# fed to the block. An optional 'start memo' value may be supplied as an argument between the array/hash
-# and mandatory block.
-#
-#       $a.reduce(start) |$memo, $x| { ... }
-#       reduce($a, start) |$memo, $x| { ... }
-#
-# If no 'start memo' is given, the first invocation of the parameterized block will be given the first and second
-# elements of the enumeration, and if the enumerable has fewer than 2 elements, the first
-# element is produced as the result of the reduction without invocation of the block.
-#
-# On each subsequent invocation, the produced value of the invoked parameterized block is given as the memo in the
-# next invocation.
-#
-# @example Using reduce
-#
-#       # Reduce an array
-#       $a = [1,2,3]
-#       $a.reduce |$memo, $entry| { $memo + $entry }
-#       #=> 6
-#
-#       # Reduce hash values
-#       $a = {a => 1, b => 2, c => 3}
-#       $a.reduce |$memo, $entry| { [sum, $memo[1]+$entry[1]] }
-#       #=> [sum, 6]
-#
-#       # reverse a string
-#       "abc".reduce |$memo, $char| { "$char$memo" }
-#       #=>"cbe"
-#
-# It is possible to provide a starting 'memo' as an argument.
-#
-# @example Using reduce with given start 'memo'
-#
-#       # Reduce an array
-#       $a = [1,2,3]
-#       $a.reduce(4) |$memo, $entry| { $memo + $entry }
-#       #=> 10
-#
-#       # Reduce hash values
-#       $a = {a => 1, b => 2, c => 3}
-#       $a.reduce([na, 4]) |$memo, $entry| { [sum, $memo[1]+$entry[1]] }
-#       #=> [sum, 10]
-#
-# @example Using reduce with an Integer range
-#
-#       Integer[1,4].reduce |$memo, $x| { $memo + $x }
-#       #=> 10
+# Applies a [lambda](https://docs.puppetlabs.com/puppet/latest/reference/lang_lambdas.html)
+# to every value in a data structure from the first argument, carrying over the returned
+# value of each iteration, and returns the result of the lambda's final iteration. This
+# lets you create a new value or data structure by combining values from the first
+# argument's data structure.
+#
+# This function takes two mandatory arguments, in this order:
+#
+# 1. An array or hash the function will iterate over.
+# 2. A lambda, which the function calls for each element in the first argument. It takes
+# two mandatory parameters:
+#     1. A memo value that is overwritten after each iteration with the iteration's result.
+#     2. A second value that is overwritten after each iteration with the next value in the
+#     function's first argument.
+#
+# @example Using the `reduce` function
+#
+# `$data.reduce |$memo, $value| { ... }`
+#
+# or
+#
+# `reduce($data) |$memo, $value| { ... }`
+#
+# You can also pass an optional "start memo" value as an argument, such as `start` below:
+#
+# `$data.reduce(start) |$memo, $value| { ... }`
+#
+# or
+#
+# `reduce($data, start) |$memo, $value| { ... }`
+#
+# When the first argument (`$data` in the above example) is an array, Puppet passes each
+# of the data structure's values in turn to the lambda's parameters. When the first
+# argument is a hash, Puppet converts each of the hash's values to an array in the form
+# `[key, value]`.
+#
+# If you pass a start memo value, Puppet executes the lambda with the provided memo value
+# and the data structure's first value. Otherwise, Puppet passes the structure's first two
+# values to the lambda.
+#
+# Puppet calls the lambda for each of the data structure's remaining values. For each
+# call, it passes the result of the previous call as the first parameter ($memo in the
+# above examples) and the next value from the data structure as the second parameter
+# ($value).
+#
+# If the structure has one value, Puppet returns the value and does not call the lambda.
+#
+# @example Using the `reduce` function
+#
+# ~~~ puppet
+# # Reduce the array $data, returning the sum of all values in the array.
+# $data = [1, 2, 3]
+# $sum = $data.reduce |$memo, $value| { $memo + $value }
+# # $sum contains 6
+#
+# # Reduce the array $data, returning the sum of a start memo value and all values in the
+# # array.
+# $data = [1, 2, 3]
+# $sum = $data.reduce(4) |$memo, $value| { $memo + $value }
+# # $sum contains 10
+#
+# # Reduce the hash $data, returning the sum of all values and concatenated string of all
+# # keys.
+# $data = {a => 1, b => 2, c => 3}
+# $combine = $data.reduce |$memo, $value| {
+#   $string = "${memo[0]}${value[0]}"
+#   $number = $memo[1] + $value[1]
+#   [$string, $number]
+# }
+# # $combine contains [abc, 6]
+# ~~~
+#
+# @example Using the `reduce` function with a start memo and two-parameter lambda
+#
+# ~~~ puppet
+# # Reduce the array $data, returning the sum of all values in the array and starting
+# # with $memo set to an arbitrary value instead of $data's first value.
+# $data = [1, 2, 3]
+# $sum = $data.reduce(4) |$memo, $value| { $memo + $value }
+# # At the start of the lambda's first iteration, $memo contains 4 and $value contains 1.
+# # After all iterations, $sum contains 10.
+#
+# # Reduce the hash $data, returning the sum of all values and concatenated string of
+# # all keys, and starting with $memo set to an arbitrary array instead of $data's first
+# # key-value pair.
+# $data = {a => 1, b => 2, c => 3}
+# $combine = $data.reduce( [d, 4] ) |$memo, $value| {
+#   $string = "${memo[0]}${value[0]}"
+#   $number = $memo[1] + $value[1]
+#   [$string, $number]
+# }
+# # At the start of the lambda's first iteration, $memo contains [d, 4] and $value
+# # contains [a, 1].
+# # $combine contains [dabc, 10]
+# ~~~
 #
 # @since 4.0.0
 #

data/lib/puppet/functions/versioncmp.rb

@@ -0,0 +1,36 @@
+require 'puppet/util/package'
+
+# Compares two version numbers.
+#
+# Prototype:
+#
+#     \$result = versioncmp(a, b)
+#
+# Where a and b are arbitrary version strings.
+#
+# This function returns:
+#
+# * `1` if version a is greater than version b
+# * `0` if the versions are equal
+# * `-1` if version a is less than version b
+#
+# @example
+#
+#     if versioncmp('2.6-1', '2.4.5') > 0 {
+#         notice('2.6-1 is > than 2.4.5')
+#     }
+#
+# This function uses the same version comparison algorithm used by Puppet's
+# `package` type.
+#
+Puppet::Functions.create_function(:versioncmp) do
+
+  dispatch :versioncmp do
+    param 'String', :a
+    param 'String', :b
+  end
+
+  def versioncmp(a, b)
+    Puppet::Util::Package.versioncmp(a, b)
+  end
+end

data/lib/puppet/functions/with.rb

@@ -1,12 +1,20 @@
-# Call a lambda with the given arguments. Since the parameters of the lambda
-# are local to the lambda's scope, this can be used to create private sections
-# of logic in a class so that the variables are not visible outside of the
-# class.
+# Call a [lambda](https://docs.puppetlabs.com/puppet/latest/reference/lang_lambdas.html)
+# with the given arguments and return the result. Since a lambda's scope is
+# [local](https://docs.puppetlabs.com/puppet/latest/reference/lang_lambdas.html#lambda-scope)
+# to the lambda, you can use the `with` function to create private blocks of code within a
+# class using variables whose values cannot be accessed outside of the lambda.
 #
-# @example Using with
+# @example Using `with`
 #
-#     # notices the array [1, 2, 'foo']
-#     with(1, 2, 'foo') |$x, $y, $z| { notice [$x, $y, $z] }
+# ~~~ puppet
+# # Concatenate three strings into a single string formatted as a list.
+# $fruit = with("apples", "oranges", "bananas") |$x, $y, $z| { 
+#   "${x}, ${y}, and ${z}" 
+# }
+# $check_var = $x
+# # $fruit contains "apples, oranges, and bananas"
+# # $check_var is undefined, as the value of $x is local to the lambda.
+# ~~~
 #
 # @since 4.0.0
 #

data/lib/puppet/indirector/catalog/compiler.rb

@@ -47,7 +47,7 @@ class Puppet::Resource::Catalog::Compiler < Puppet::Indirector::Code
     node = node_from_request(request)
     node.trusted_data = Puppet.lookup(:trusted_information) { Puppet::Context::TrustedInformation.local(node) }.to_h
 
-    if catalog = compile(node)
+    if catalog = compile(node, request.options[:code_id])
       return catalog
     else
       # This shouldn't actually happen; we should either return
@@ -82,7 +82,7 @@ class Puppet::Resource::Catalog::Compiler < Puppet::Indirector::Code
   end
 
   # Compile the actual catalog.
-  def compile(node)
+  def compile(node, code_id)
     str = "Compiled catalog for #{node.name}"
     str += " in environment #{node.environment}" if node.environment
     config = nil
@@ -90,7 +90,7 @@ class Puppet::Resource::Catalog::Compiler < Puppet::Indirector::Code
     benchmark(:notice, str) do
       Puppet::Util::Profiler.profile(str, [:compiler, :compile, node.environment, node.name]) do
         begin
-          config = Puppet::Parser::Compiler.compile(node)
+          config = Puppet::Parser::Compiler.compile(node, code_id)
         rescue Puppet::Error => detail
           Puppet.err(detail.to_s) if networked?
           raise

data/lib/puppet/indirector/catalog/static_compiler.rb

@@ -41,15 +41,17 @@ class Puppet::Resource::Catalog::StaticCompiler < Puppet::Resource::Catalog::Com
     raise "Did not get catalog back" unless catalog.is_a?(model)
 
     catalog.resources.find_all { |res| res.type == "File" }.each do |resource|
+      next if resource[:ensure] == 'absent'
+
       next unless source = resource[:source]
       next unless source =~ /^puppet:/
 
       file = resource.to_ral
 
       if file.recurse?
-        add_children(request.key, catalog, resource, file)
+        add_children(request, catalog, resource, file)
       else
-        find_and_replace_metadata(request.key, resource, file)
+        find_and_replace_metadata(request, resource, file)
       end
     end
 
@@ -65,10 +67,10 @@ class Puppet::Resource::Catalog::StaticCompiler < Puppet::Resource::Catalog::Com
   # from the resource, inserts the metadata into the file resource, and uploads
   # the file contents of the source to the file bucket.
   #
-  # @param host [String] The host name of the node requesting this catalog
+  # @param request [Puppet::Indirector::Request] The request for the catalog
   # @param resource [Puppet::Resource] The resource to replace the metadata in
   # @param file [Puppet::Type::File] The file RAL associated with the resource
-  def find_and_replace_metadata(host, resource, file)
+  def find_and_replace_metadata(request, resource, file)
     # We remove URL info from it, so it forces a local copy
     # rather than routing through the network.
     # Weird, but true.
@@ -77,7 +79,7 @@ class Puppet::Resource::Catalog::StaticCompiler < Puppet::Resource::Catalog::Com
 
     raise "Could not get metadata for #{resource[:source]}" unless metadata = file.parameter(:source).metadata
 
-    replace_metadata(host, resource, metadata)
+    replace_metadata(request, resource, metadata)
   end
 
   # Rewrite a given file resource with the metadata from a fileserver based file
@@ -85,13 +87,14 @@ class Puppet::Resource::Catalog::StaticCompiler < Puppet::Resource::Catalog::Com
   # This performs the actual metadata rewrite for the given file resource and
   # uploads the content of the source file to the filebucket.
   #
-  # @param host [String] The host name of the node requesting this catalog
+  # @param request [Puppet::Indirector::Request] The request for the catalog
   # @param resource [Puppet::Resource] The resource to add the metadata to
   # @param metadata [Puppet::FileServing::Metadata] The metadata of the given fileserver based file
-  def replace_metadata(host, resource, metadata)
-    [:mode, :owner, :group].each do |param|
-      resource[param] ||= metadata.send(param)
+  def replace_metadata(request, resource, metadata)
+    [:owner, :group].each do |param|
+      resource[param] ||= metadata.send(param).to_s
     end
+    resource[:mode] ||= metadata.send(:mode).to_s(8)
 
     resource[:ensure] = metadata.ftype
     if metadata.ftype == "file"
@@ -101,21 +104,26 @@ class Puppet::Resource::Catalog::StaticCompiler < Puppet::Resource::Catalog::Com
       end
     end
 
-    store_content(resource) if resource[:ensure] == "file"
+    store_content(request, resource) if resource[:ensure] == "file"
     old_source = resource.delete(:source)
-    Puppet.info "Metadata for #{resource} in catalog for '#{host}' added from '#{old_source}'"
+    Puppet.info "Metadata for #{resource} in catalog for '#{request.key}' added from '#{old_source}'"
   end
 
   # Generate children resources for a recursive file and add them to the catalog.
   #
-  # @param host [String] The host name of the node requesting this catalog
+  # @param request [Puppet::Indirector::Request] The request for the catalog
   # @param catalog [Puppet::Resource::Catalog]
   # @param resource [Puppet::Resource]
   # @param file [Puppet::Type::File] The file RAL associated with the resource
-  def add_children(host, catalog, resource, file)
-    file = resource.to_ral
-
-    children = get_child_resources(host, catalog, resource, file)
+  def add_children(request, catalog, resource, file)
+    children = get_child_resources(request, catalog, resource, file)
+    # get_child_resources() returned early because source is not
+    # a directory, but we still need to replace the metadata of the
+    # resource, so we do it here before returning.
+    if children.nil?
+      find_and_replace_metadata(request, resource, file)
+      return
+    end
 
     remove_existing_resources(children, catalog)
 
@@ -127,13 +135,13 @@ class Puppet::Resource::Catalog::StaticCompiler < Puppet::Resource::Catalog::Com
 
   # Given a recursive file resource, recursively generate its children resources
   #
-  # @param host [String] The host name of the node requesting this catalog
+  # @param request [Puppet::Indirector::Request] The request for the catalog
   # @param catalog [Puppet::Resource::Catalog]
   # @param resource [Puppet::Resource]
   # @param file [Puppet::Type::File] The file RAL associated with the resource
   #
   # @return [Array<Puppet::Resource>] The recursively generated File resources for the given resource
-  def get_child_resources(host, catalog, resource, file)
+  def get_child_resources(request, catalog, resource, file)
     sourceselect = file[:sourceselect]
     children = {}
 
@@ -158,44 +166,52 @@ class Puppet::Resource::Catalog::StaticCompiler < Puppet::Resource::Catalog::Com
       end
     end
 
+    parent_meta = nil
     total.each do |meta|
       # This is the top-level parent directory
       if meta.relative_path == "."
-        replace_metadata(host, resource, meta)
+        parent_meta = meta
         next
       end
-      children[meta.relative_path] ||= Puppet::Resource.new(:file, File.join(file[:path], meta.relative_path))
+      child = children[meta.relative_path] ||=
+        Puppet::Resource.new(:file, File.join(file[:path], meta.relative_path))
 
       # I think this is safe since it's a URL, not an actual file
-      children[meta.relative_path][:source] = source + "/" + meta.relative_path
+      child[:source] = source + "/" + meta.relative_path
       resource.each do |param, value|
         # These should never be passed to our children.
         unless [:parent, :ensure, :recurse, :recurselimit, :target, :alias, :source].include? param
-          children[meta.relative_path][param] = value
+          child[param] = value
         end
       end
-      replace_metadata(host, children[meta.relative_path], meta)
+      replace_metadata(request, child, meta)
     end
+    replace_metadata(request, resource, parent_meta)
 
     children
   end
 
-  # Remove any file resources in the catalog that will be duplicated by the
-  # given file resources.
+  # Remove any recursed file resources already in the catalog
   #
   # @param children [Array<Puppet::Resource>]
   # @param catalog [Puppet::Resource::Catalog]
   def remove_existing_resources(children, catalog)
-    existing_names = catalog.resources.collect { |r| r.to_s }
-    both = (existing_names & children.keys).inject({}) { |hash, name| hash[name] = true; hash }
-    both.each { |name| children.delete(name) }
+    relative_paths = children.keys
+    relative_paths.each do |relative_path|
+      child = children[relative_path]
+      if catalog.resource(child.ref)
+        Puppet.debug("Resource #{child.ref} already managed, removing from recursed children")
+        children.delete(relative_path)
+      end
+    end
   end
 
   # Retrieve the source of a file resource using a fileserver based source and
   # upload it to the filebucket.
   #
+  # @param request [Puppet::Indirector::Request] The request for the catalog
   # @param resource [Puppet::Resource]
-  def store_content(resource)
+  def store_content(request, resource)
     @summer ||= Puppet::Util::Checksums
 
     type = @summer.sumtype(resource[:content])
@@ -205,7 +221,7 @@ class Puppet::Resource::Catalog::StaticCompiler < Puppet::Resource::Catalog::Com
       Puppet.info "Content for '#{resource[:source]}' already exists"
     else
       Puppet.info "Storing content for source '#{resource[:source]}'"
-      content = Puppet::FileServing::Content.indirection.find(resource[:source])
+      content = Puppet::FileServing::Content.indirection.find(resource[:source], {:environment => request.environment})
       file = Puppet::FileBucket::File.new(content.content)
       Puppet::FileBucket::File.indirection.save(file)
     end