puppet 4.0.0 → 4.9.1

data/lib/puppet/type.rb

@@ -1,3 +1,4 @@
+# -*- coding: utf-8 -*-
 require 'puppet'
 require 'puppet/util/log'
 require 'puppet/util/metric'
@@ -74,6 +75,7 @@ module Puppet
 #
 #
 class Type
+  extend Puppet::CompilableResourceType
   include Puppet::Util
   include Puppet::Util::Errors
   include Puppet::Util::Logging
@@ -89,9 +91,9 @@ class Type
   # @see Comparable
   #
   def <=>(other)
-    # We only order against other types, not arbitrary objects.
-    return nil unless other.is_a? Puppet::Type
-    # Our natural order is based on the reference name we use when comparing
+    # Order is only maintained against other types, not arbitrary objects.
+    # The natural order is based on the reference name used when comparing
+    return nil unless other.is_a?(Puppet::CompilableResourceType) || other.class.is_a?(Puppet::CompilableResourceType)
     # against other type instances.
     self.ref <=> other.ref
   end
@@ -106,6 +108,25 @@ class Type
     attr_reader :properties
   end
 
+  # Allow declaring that a type is actually a capability
+  class << self
+    attr_accessor :is_capability
+
+    def is_capability?
+      c = is_capability
+      c.nil? ? false : c
+    end
+  end
+
+  # Returns whether this type represents an application instance; since
+  # only defined types, i.e., instances of Puppet::Resource::Type can
+  # represent application instances, this implementation always returns
+  # +false+. Having this method though makes code checking whether a
+  # resource is an application instance simpler
+  def self.application?
+      false
+  end
+
   # Returns all the attribute names of the type in the appropriate order.
   # The {key_attributes} come first, then the {provider}, then the {properties}, and finally
   # the {parameters} and {metaparams},
@@ -581,7 +602,7 @@ class Type
     validattr?(name)
   end
 
-  # @return [Boolean] Returns true if the wanted state of the resoure is that it should be absent (i.e. to be deleted).
+  # @return [Boolean] Returns true if the wanted state of the resource is that it should be absent (i.e. to be deleted).
   def deleting?
     obj = @parameters[:ensure] and obj.should == :absent
   end
@@ -639,7 +660,7 @@ class Type
   def []=(name,value)
     name = name.intern
 
-    fail("Invalid parameter #{name}") unless self.class.validattr?(name)
+    fail("no parameter named '#{name}'") unless self.class.validattr?(name)
 
     if name == :name && nv = name_var
       name = nv
@@ -722,7 +743,7 @@ class Type
     (prop = @parameters[name] and prop.is_a?(Puppet::Property)) ? prop.should : nil
   end
 
-  # Registers an attribute to this resource type insance.
+  # Registers an attribute to this resource type instance.
   # Requires either the attribute name or class as its argument.
   # This is a noop if the named property/parameter is not supported
   # by this resource. Otherwise, an attribute instance is created
@@ -842,7 +863,7 @@ class Type
     self.class.name
   end
 
-  # @todo Comment says "Return a specific value for an attribute.", as opposed to what "An upspecific value"???
+  # @todo Comment says "Return a specific value for an attribute.", as opposed to what "An unspecific value"???
   # @todo is this the 'is' or the 'should' value?
   # @todo why is the return restricted to things that respond to :value? (Only non structural basic data types
   #   supported?
@@ -875,7 +896,7 @@ class Type
   # See the overview of this class for a longer explanation of the concept _isomorphism_.
   # Defaults to true.
   #
-  # @return [Boolan] true, if this type's name is isomorphic with the object
+  # @return [Boolean] true, if this type's name is isomorphic with the object
   def self.isomorphic?
     if defined?(@isomorphic)
       return @isomorphic
@@ -1025,9 +1046,15 @@ class Type
     insync
   end
 
+  # Says if the ensure property should be retrieved if the resource is ensurable
+  # Defaults to true. Some resource type classes can override it
+  def self.needs_ensure_retrieved
+    true
+  end
+
   # Retrieves the current value of all contained properties.
   # Parameters and meta-parameters are not included in the result.
-  # @todo As oposed to all non contained properties? How is this different than any of the other
+  # @todo As opposed to all non contained properties? How is this different than any of the other
   #   methods that also "gets" properties/parameters/etc. ?
   # @return [Puppet::Resource] array of all property values (mix of types)
   # @raise [fail???] if there is a provider and it is not suitable for the host this is evaluated for.
@@ -1039,7 +1066,7 @@ class Type
     # Provide the name, so we know we'll always refer to a real thing
     result[:name] = self[:name] unless self[:name] == title
 
-    if ensure_prop = property(:ensure) or (self.class.validattr?(:ensure) and ensure_prop = newattr(:ensure))
+    if ensure_prop = property(:ensure) or (self.class.needs_ensure_retrieved and self.class.validattr?(:ensure) and ensure_prop = newattr(:ensure))
       result[:ensure] = ensure_state = ensure_prop.retrieve
     else
       ensure_state = nil
@@ -1127,7 +1154,7 @@ class Type
   # Retrieves all known instances.
   # @todo Retrieves them from where? Known to whom?
   # Either requires providers or must be overridden.
-  # @raise [Puppet::DevError] when there are no providers and the implementation has not overridded this method.
+  # @raise [Puppet::DevError] when there are no providers and the implementation has not overridden this method.
   def self.instances
     raise Puppet::DevError, "#{self.name} has no providers and has not overridden 'instances'" if provider_hash.empty?
 
@@ -1198,7 +1225,7 @@ class Type
   end
 
 
-  # Returns an array of strings representing the containment heirarchy
+  # Returns an array of strings representing the containment hierarchy
   # (types/classes) that make up the path to the resource from the root
   # of the catalog.  This is mostly used for logging purposes.
   #
@@ -1227,7 +1254,7 @@ class Type
       event _would_ have been sent.
 
       **Important note:**
-      [The `noop` setting](http://docs.puppetlabs.com/references/latest/configuration.html#noop)
+      [The `noop` setting](https://docs.puppetlabs.com/puppet/latest/reference/configuration.html#noop)
       allows you to globally enable or disable noop mode, but it will _not_ override
       the `noop` metaparameter on individual resources. That is, the value of the
       global `noop` setting will _only_ affect resources that do not have an explicit
@@ -1247,7 +1274,7 @@ class Type
       The value of this metaparameter must be the `name` of a `schedule`
       resource. This means you must declare a schedule resource, then
       refer to it by name; see
-      [the docs for the `schedule` type](http://docs.puppetlabs.com/references/latest/type.html#schedule)
+      [the docs for the `schedule` type](https://docs.puppetlabs.com/puppet/latest/reference/type.html#schedule)
       for more info.
 
           schedule { 'everyday':
@@ -1422,7 +1449,7 @@ class Type
           }
 
       Tags are useful for things like applying a subset of a host's configuration
-      with [the `tags` setting](/references/latest/configuration.html#tags)
+      with [the `tags` setting](/puppet/latest/reference/configuration.html#tags)
       (e.g. `puppet agent --test --tags bootstrap`)."
 
     munge do |tags|
@@ -1498,7 +1525,7 @@ class Type
         end
 
         # Are we requiring them, or vice versa?  See the method docs
-        # for futher info on this.
+        # for further info on this.
         if self.class.direction == :in
           source = related_resource
           target = @resource
@@ -1512,12 +1539,12 @@ class Type
             :event => self.class.events,
             :callback => method
           }
-          self.debug("subscribes to #{related_resource.ref}")
+          self.debug { "subscribes to #{related_resource.ref}" }
         else
           # If there's no callback, there's no point in even adding
           # a label.
           subargs = nil
-          self.debug("requires #{related_resource.ref}")
+          self.debug { "subscribes to #{related_resource.ref}" }
         end
 
         Puppet::Relationship.new(source, target, subargs)
@@ -1525,7 +1552,7 @@ class Type
     end
   end
 
-  # @todo document this, have no clue what this does... it retuns "RelationshipMetaparam.subclasses"
+  # @todo document this, have no clue what this does... it returns "RelationshipMetaparam.subclasses"
   #
   def self.relationship_params
     RelationshipMetaparam.subclasses
@@ -1533,13 +1560,13 @@ class Type
 
 
   # Note that the order in which the relationships params is defined
-  # matters.  The labelled params (notify and subcribe) must be later,
+  # matters.  The labeled params (notify and subscribe) must be later,
   # so that if both params are used, those ones win.  It's a hackish
   # solution, but it works.
 
   newmetaparam(:require, :parent => RelationshipMetaparam, :attributes => {:direction => :in, :events => :NONE}) do
     desc "One or more resources that this resource depends on, expressed as
-      [resource references](http://docs.puppetlabs.com/puppet/latest/reference/lang_datatypes.html#resource-references).
+      [resource references](https://docs.puppetlabs.com/puppet/latest/reference/lang_data_resource_reference.html).
       Multiple resources can be specified as an array of references. When this
       attribute is present:
 
@@ -1548,12 +1575,12 @@ class Type
       This is one of the four relationship metaparameters, along with
       `before`, `notify`, and `subscribe`. For more context, including the
       alternate chaining arrow (`->` and `~>`) syntax, see
-      [the language page on relationships](http://docs.puppetlabs.com/puppet/latest/reference/lang_relationships.html)."
+      [the language page on relationships](https://docs.puppetlabs.com/puppet/latest/reference/lang_relationships.html)."
   end
 
   newmetaparam(:subscribe, :parent => RelationshipMetaparam, :attributes => {:direction => :in, :events => :ALL_EVENTS, :callback => :refresh}) do
     desc "One or more resources that this resource depends on, expressed as
-      [resource references](http://docs.puppetlabs.com/puppet/latest/reference/lang_datatypes.html#resource-references).
+      [resource references](https://docs.puppetlabs.com/puppet/latest/reference/lang_data_resource_reference.html).
       Multiple resources can be specified as an array of references. When this
       attribute is present:
 
@@ -1566,12 +1593,12 @@ class Type
       This is one of the four relationship metaparameters, along with
       `before`, `require`, and `notify`. For more context, including the
       alternate chaining arrow (`->` and `~>`) syntax, see
-      [the language page on relationships](http://docs.puppetlabs.com/puppet/latest/reference/lang_relationships.html)."
+      [the language page on relationships](https://docs.puppetlabs.com/puppet/latest/reference/lang_relationships.html)."
   end
 
   newmetaparam(:before, :parent => RelationshipMetaparam, :attributes => {:direction => :out, :events => :NONE}) do
     desc "One or more resources that depend on this resource, expressed as
-      [resource references](http://docs.puppetlabs.com/puppet/latest/reference/lang_datatypes.html#resource-references).
+      [resource references](https://docs.puppetlabs.com/puppet/latest/reference/lang_data_resource_reference.html).
       Multiple resources can be specified as an array of references. When this
       attribute is present:
 
@@ -1580,12 +1607,12 @@ class Type
       This is one of the four relationship metaparameters, along with
       `require`, `notify`, and `subscribe`. For more context, including the
       alternate chaining arrow (`->` and `~>`) syntax, see
-      [the language page on relationships](http://docs.puppetlabs.com/puppet/latest/reference/lang_relationships.html)."
+      [the language page on relationships](https://docs.puppetlabs.com/puppet/latest/reference/lang_relationships.html)."
   end
 
   newmetaparam(:notify, :parent => RelationshipMetaparam, :attributes => {:direction => :out, :events => :ALL_EVENTS, :callback => :refresh}) do
     desc "One or more resources that depend on this resource, expressed as
-      [resource references](http://docs.puppetlabs.com/puppet/latest/reference/lang_datatypes.html#resource-references).
+      [resource references](https://docs.puppetlabs.com/puppet/latest/reference/lang_data_resource_reference.html).
       Multiple resources can be specified as an array of references. When this
       attribute is present:
 
@@ -1598,7 +1625,7 @@ class Type
       This is one of the four relationship metaparameters, along with
       `before`, `require`, and `subscribe`. For more context, including the
       alternate chaining arrow (`->` and `~>`) syntax, see
-      [the language page on relationships](http://docs.puppetlabs.com/puppet/latest/reference/lang_relationships.html)."
+      [the language page on relationships](https://docs.puppetlabs.com/puppet/latest/reference/lang_relationships.html)."
   end
 
   newmetaparam(:stage) do
@@ -1611,7 +1638,7 @@ class Type
       By default, all classes are declared in the `main` stage. To assign a class
       to a different stage, you must:
 
-      * Declare the new stage as a [`stage` resource](http://docs.puppetlabs.com/references/latest/type.html#stage).
+      * Declare the new stage as a [`stage` resource](https://docs.puppetlabs.com/puppet/latest/reference/type.html#stage).
       * Declare an order relationship between the new stage and the `main` stage.
       * Use the resource-like syntax to declare the class, and set the `stage`
         metaparameter to the name of the desired stage.
@@ -1628,6 +1655,57 @@ class Type
     }
   end
 
+  newmetaparam(:export, :parent => RelationshipMetaparam, :attributes => {:direction => :out, :events => :NONE}) do
+          desc <<EOS
+Export a capability resource.
+
+The value of this parameter must be a reference to a capability resource,
+or an array of such references. Each capability resource referenced here
+will be instantiated in the node catalog and exported to consumers of this
+resource. The title of the capability resource will be the title given in
+the reference, and all other attributes of the resource will be filled
+according to the corresponding produces statement.
+
+It is an error if this metaparameter references resources whose type is not
+a capability type, or of there is no produces clause for the type of the
+current resource and the capability resource mentioned in this parameter.
+
+For example:
+
+define web(..) { .. }
+Web produces Http { .. }
+web { server:
+  export => Http[main_server]
+}
+EOS
+  end
+
+  newmetaparam(:consume, :parent => RelationshipMetaparam, :attributes => {:direction => :in, :events => :NONE}) do
+          desc <<EOS
+Consume a capability resource.
+
+The value of this parameter must be a reference to a capability resource,
+or an array of such references. Each capability resource referenced here
+must have been exported by another resource in the same environment.
+
+The referenced capability resource(s) will be looked up, added to the
+current node catalog, and processed following the underlying consumes
+clause.
+
+It is an error if this metaparameter references resources whose type is not
+a capability type, or of there is no consumes clause for the type of the
+current resource and the capability resource mentioned in this parameter.
+
+For example:
+
+define web(..) { .. }
+Web consumes Sql { .. }
+web { server:
+  consume => Sql[my_db]
+}
+EOS
+end
+
   ###############################
   # All of the provider plumbing for the resource types.
   require 'puppet/provider'
@@ -1795,7 +1873,7 @@ class Type
   def self.providify
     return if @paramhash.has_key? :provider
 
-    newparam(:provider) do
+    param = newparam(:provider) do
       # We're using a hacky way to get the name of our type, since there doesn't
       # seem to be a correct way to introspect this at the time this code is run.
       # We expect that the class in which this code is executed will be something
@@ -1855,7 +1933,8 @@ class Type
           provider
         end
       end
-    end.parenttype = self
+    end
+    param.parenttype = self
   end
 
   # @todo this needs a better explanation
@@ -1982,7 +2061,7 @@ class Type
   end
 
   # Provides iteration over added auto-requirements (see {autorequire}).
-  # @yieldparam type [String] the name of the type to autoriquire an instance of
+  # @yieldparam type [String] the name of the type to autorequire an instance of
   # @yieldparam block [Proc] a block producing one or several dependencies to auto require (see {autorequire}).
   # @yieldreturn [void]
   # @return [void]
@@ -1994,7 +2073,7 @@ class Type
   end
 
   # Provides iteration over added auto-requirements (see {autobefore}).
-  # @yieldparam type [String] the name of the type to autoriquire an instance of
+  # @yieldparam type [String] the name of the type to autorequire an instance of
   # @yieldparam block [Proc] a block producing one or several dependencies to auto require (see {autobefore}).
   # @yieldreturn [void]
   # @return [void]
@@ -2006,7 +2085,7 @@ class Type
   end
 
   # Provides iteration over added auto-requirements (see {autosubscribe}).
-  # @yieldparam type [String] the name of the type to autoriquire an instance of
+  # @yieldparam type [String] the name of the type to autorequire an instance of
   # @yieldparam block [Proc] a block producing one or several dependencies to auto require (see {autosubscribe}).
   # @yieldreturn [void]
   # @return [void]
@@ -2018,7 +2097,7 @@ class Type
   end
 
   # Provides iteration over added auto-requirements (see {autonotify}).
-  # @yieldparam type [String] the name of the type to autoriquire an instance of
+  # @yieldparam type [String] the name of the type to autorequire an instance of
   # @yieldparam block [Proc] a block producing one or several dependencies to auto require (see {autonotify}).
   # @yieldreturn [void]
   # @return [void]
@@ -2055,8 +2134,10 @@ class Type
 
       # Collect the current prereqs
       list.each { |dep|
+        next if dep.nil?
+
         # Support them passing objects directly, to save some effort.
-        unless dep.is_a? Puppet::Type
+        unless dep.is_a?(Puppet::Type)
           # Skip autorelation that we aren't managing
           unless dep = rel_catalog.resource(type, dep)
             next
@@ -2113,7 +2194,7 @@ class Type
   # @comment - these two comments were floating around here, and turned up as documentation
   #  for the attribute "title", much to my surprise and amusement. Clearly these comments
   #  are orphaned ... I think they can just be removed as what they say should be covered
-  #  by the now added yardoc. <irony>(Yo! to quote some of the other actual awsome specific comments applicable
+  #  by the now added yardoc. <irony>(Yo! to quote some of the other actual awesome specific comments applicable
   #  to objects called from elsewhere, or not. ;-)</irony>
   #
   # @comment Types (which map to resources in the languages) are entirely composed of
@@ -2192,7 +2273,7 @@ class Type
   # Returns the name of this type (if specified) or the parent type #to_s.
   # The returned name is on the form "Puppet::Type::<name>", where the first letter of name is
   # capitalized.
-  # @return [String] the fully qualified name Puppet::Type::<name> where the first letter of name is captialized
+  # @return [String] the fully qualified name Puppet::Type::<name> where the first letter of name is capitalized
   #
   def self.to_s
     if defined?(@name)
@@ -2314,6 +2395,47 @@ class Type
       adderrorcontext(error, detail)
       raise error
     end
+
+    set_sensitive_parameters(resource.sensitive_parameters)
+  end
+
+  protected
+
+  # Mark parameters associated with this type as sensitive, based on the associated resource.
+  #
+  # Currently, only instances of `Puppet::Property` can be easily marked for sensitive data handling
+  # and information redaction is limited to redacting events generated while synchronizing
+  # properties. While support for redaction will be broadened in the future we can't automatically
+  # deduce how to redact arbitrary parameters, so if a parameter is marked for redaction the best
+  # we can do is warn that we can't handle treating that parameter as sensitive and move on.
+  #
+  # In some unusual cases a given parameter will be marked as sensitive but that sensitive context
+  # needs to be transferred to another parameter. In this case resource types may need to override
+  # this method in order to copy the sensitive context from one parameter to another (and in the
+  # process force the early generation of a parameter that might otherwise be lazily generated.)
+  # See `Puppet::Type.type(:file)#set_sensitive_parameters` for an example of this.
+  #
+  # @note This method visibility is protected since it should only be called by #initialize, but is
+  #   marked as public as subclasses may need to override this method.
+  #
+  # @api public
+  #
+  # @param sensitive_parameters [Array<Symbol>] A list of parameters to mark as sensitive.
+  #
+  # @return [void]
+  def set_sensitive_parameters(sensitive_parameters)
+    sensitive_parameters.each do |name|
+      p = parameter(name)
+      if p.is_a?(Puppet::Property)
+        p.sensitive = true
+      elsif p.is_a?(Puppet::Parameter)
+        warning("Unable to mark '#{name}' as sensitive: #{name} is a parameter and not a property, and cannot be automatically redacted.")
+      elsif self.class.attrclass(name)
+        warning("Unable to mark '#{name}' as sensitive: the property itself was not assigned a value.")
+      else
+        err("Unable to mark '#{name}' as sensitive: the property itself is not defined on #{type}.")
+      end
+    end
   end
 
   private
@@ -2464,14 +2586,14 @@ class Type
     end
   end
 
-  # Returns the title of this object, or its name if title was not explicetly set.
+  # Returns the title of this object, or its name if title was not explicitly set.
   # If the title is not already set, it will be computed by looking up the {#name_var} and using
   # that value as the title.
   # @todo it is somewhat confusing that if the name_var is a valid parameter, it is assumed to
   #  be the name_var called :name, but if it is a property, it uses the name_var.
   #  It is further confusing as Type in some respects supports multiple namevars.
   #
-  # @return [String] Returns the title of this object, or its name if title was not explicetly set.
+  # @return [String] Returns the title of this object, or its name if title was not explicitly set.
   # @raise [??? devfail] if title is not set, and name_var can not be found.
   def title
     unless @title

data/lib/puppet/util/autoload.rb

@@ -2,6 +2,15 @@ require 'pathname'
 require 'puppet/util/rubygems'
 require 'puppet/util/warnings'
 require 'puppet/util/methodhelper'
+require 'puppet/pops/adaptable'
+
+# An adapter that ties the module_directories cache to the environment where the modules are parsed. This
+# adapter ensures that the life-cycle of this cache doesn't exceed  the life-cycle of the environment.
+#
+# @api private
+class Puppet::Util::ModuleDirectoriesAdapter < Puppet::Pops::Adaptable::Adapter
+  attr_accessor :directories
+end
 
 # Autoload paths, either based on names or all at once.
 class Puppet::Util::Autoload
@@ -99,12 +108,6 @@ class Puppet::Util::Autoload
     end
 
     def module_directories(env)
-      # We're using a per-thread cache of module directories so that we don't
-      # scan the filesystem each time we try to load something. This is reset
-      # at the beginning of compilation and at the end of an agent run.
-      $env_module_directories ||= {}
-
-
       # This is a little bit of a hack.  Basically, the autoloader is being
       # called indirectly during application bootstrapping when we do things
       # such as check "features".  However, during bootstrapping, we haven't
@@ -129,11 +132,13 @@ class Puppet::Util::Autoload
 
         if env
           # if the app defaults have been initialized then it should be safe to access the module path setting.
-          $env_module_directories[env] ||= env.modulepath.collect do |dir|
-            Dir.entries(dir).reject { |f| f =~ /^\./ }.collect { |f| File.join(dir, f, "lib") }
-          end.flatten.find_all do |d|
-            FileTest.directory?(d)
-          end
+          Puppet::Util::ModuleDirectoriesAdapter.adapt(env) do |a|
+            a.directories ||= env.modulepath.collect do |dir|
+              Dir.entries(dir).reject { |f| f =~ /^\./ }.collect { |f| File.join(dir, f, "lib") }
+            end.flatten.find_all do |d|
+              FileTest.directory?(d)
+            end
+          end.directories
         else
           []
         end