puppet 3.2.4 → 3.3.0.rc2

data/lib/puppet/transaction/additional_resource_generator.rb

@@ -0,0 +1,126 @@
+# Adds additional resources to the catalog and relationship graph that are
+# generated by existing resources. There are two ways that a resource can
+# generate additional resources, either through the #generate method or the
+# #eval_generate method.
+#
+# @api private
+class Puppet::Transaction::AdditionalResourceGenerator
+  def initialize(catalog, relationship_graph, prioritizer)
+    @catalog = catalog
+    @relationship_graph = relationship_graph
+    @prioritizer = prioritizer
+  end
+
+  def generate_additional_resources(resource)
+    return unless resource.respond_to?(:generate)
+    begin
+      generated = resource.generate
+    rescue => detail
+      resource.log_exception(detail, "Failed to generate additional resources using 'generate': #{detail}")
+    end
+    return unless generated
+    generated = [generated] unless generated.is_a?(Array)
+    generated.collect do |res|
+      @catalog.resource(res.ref) || res
+    end.each do |res|
+      priority = @prioritizer.generate_priority_contained_in(resource, res)
+      add_resource(res, resource, priority)
+
+      add_conditional_directed_dependency(resource, res)
+      generate_additional_resources(res)
+    end
+  end
+
+  def eval_generate(resource)
+    return false unless resource.respond_to?(:eval_generate)
+    raise Puppet::DevError,"Depthfirst resources are not supported by eval_generate" if resource.depthfirst?
+    begin
+      generated = replace_duplicates_with_catalog_resources(resource.eval_generate)
+      return false if generated.empty?
+    rescue => detail
+      resource.log_exception(detail, "Failed to generate additional resources using 'eval_generate: #{detail}")
+      return false
+    end
+    add_resources(generated, resource)
+
+    made = Hash[generated.map(&:name).zip(generated)]
+    contain_generated_resources_in(resource, made)
+    connect_resources_to_ancestors(resource, made)
+
+    true
+  end
+
+  private
+
+  def replace_duplicates_with_catalog_resources(generated)
+    generated.collect do |generated_resource|
+      @catalog.resource(generated_resource.ref) || generated_resource
+    end
+  end
+
+  def contain_generated_resources_in(resource, made)
+    sentinel = Puppet::Type.type(:whit).new(:name => "completed_#{resource.title}", :catalog => resource.catalog)
+    priority = @prioritizer.generate_priority_contained_in(resource, sentinel)
+    @relationship_graph.add_vertex(sentinel, priority)
+
+    redirect_edges_to_sentinel(resource, sentinel, made)
+
+    made.values.each do |res|
+      # This resource isn't 'completed' until each child has run
+      add_conditional_directed_dependency(res, sentinel, Puppet::Graph::RelationshipGraph::Default_label)
+    end
+
+    # This edge allows the resource's events to propagate, though it isn't
+    # strictly necessary for ordering purposes
+    add_conditional_directed_dependency(resource, sentinel, Puppet::Graph::RelationshipGraph::Default_label)
+  end
+
+  def redirect_edges_to_sentinel(resource, sentinel, made)
+    @relationship_graph.adjacent(resource, :direction => :out, :type => :edges).each do |e|
+      next if made[e.target.name]
+
+      @relationship_graph.add_relationship(sentinel, e.target, e.label)
+      @relationship_graph.remove_edge! e
+    end
+  end
+
+  def connect_resources_to_ancestors(resource, made)
+    made.values.each do |res|
+      # Depend on the nearest ancestor we generated, falling back to the
+      # resource if we have none
+      parent_name = res.ancestors.find { |a| made[a] and made[a] != res }
+      parent = made[parent_name] || resource
+
+      add_conditional_directed_dependency(parent, res)
+    end
+  end
+
+  def add_resources(generated, resource)
+    generated.each do |res|
+      priority = @prioritizer.generate_priority_contained_in(resource, res)
+      add_resource(res, resource, priority)
+    end
+  end
+
+  def add_resource(res, parent_resource, priority)
+    if @catalog.resource(res.ref).nil?
+      res.tag(*parent_resource.tags)
+      @catalog.add_resource(res)
+      @relationship_graph.add_vertex(res, priority)
+      @catalog.add_edge(@catalog.container_of(parent_resource), res)
+      res.finish
+    end
+  end
+
+  # Copy an important relationships from the parent to the newly-generated
+  # child resource.
+  def add_conditional_directed_dependency(parent, child, label=nil)
+    @relationship_graph.add_vertex(child)
+    edge = parent.depthfirst? ? [child, parent] : [parent, child]
+    if @relationship_graph.edge?(*edge.reverse)
+      parent.debug "Skipping automatic relationship to #{child}"
+    else
+      @relationship_graph.add_relationship(edge[0],edge[1],label)
+    end
+  end
+end

data/lib/puppet/transaction/event.rb

@@ -26,6 +26,7 @@ class Puppet::Transaction::Event
 
   def initialize(options = {})
     @audited = false
+
     set_options(options)
     @time = Time.now
   end
@@ -37,12 +38,26 @@ class Puppet::Transaction::Event
     @desired_value = data['desired_value']
     @historical_value = data['historical_value']
     @message = data['message']
-    @name = data['name'].intern
+    @name = data['name'].intern if data['name']
     @status = data['status']
     @time = data['time']
     @time = Time.parse(@time) if @time.is_a? String
   end
 
+  def to_pson
+    {
+      'audited' => @audited,
+      'property' => @property,
+      'previous_value' => @previous_value,
+      'desired_value' => @desired_value,
+      'historical_value' => @historical_value,
+      'message' => @message,
+      'name' => @name,
+      'status' => @status,
+      'time' => @time.iso8601(9),
+    }.to_pson
+  end
+
   def property=(prop)
     @property = prop.to_s
   end

data/lib/puppet/transaction/report.rb

@@ -44,6 +44,10 @@ class Puppet::Transaction::Report
   # @return [???] the configuration version
   attr_accessor :configuration_version
 
+  # An agent generated transaction uuid, useful for connecting catalog and report
+  # @return [String] uuid
+  attr_accessor :transaction_uuid
+
   # The host name for which the report is generated
   # @return [String] the host name
   attr_accessor :host
@@ -58,7 +62,7 @@ class Puppet::Transaction::Report
   attr_reader :resource_statuses
 
   # A list of log messages.
-  # @return [Array<String>] logged messages
+  # @return [Array<Puppet::Util::Log>] logged messages
   attr_reader :logs
 
   # A hash of metric name to metric value.
@@ -88,26 +92,22 @@ class Puppet::Transaction::Report
   #
   attr_reader :puppet_version
 
-  # @return [Integer] (3) a report format version number
-  # @todo Unclear what this is - a version?
+  # @return [Integer] report format version number.  This value is constant for
+  #    a given version of Puppet; it is incremented when a new release of Puppet
+  #    changes the API for the various objects that make up a report.
   #
   attr_reader :report_format
 
-  # This is necessary since Marshal doesn't know how to
-  # dump hash with default proc (see below "@records") ?
-  # @todo there is no "@records" to see below, uncertain what this is for.
-  # @api private
-  #
-  def self.default_format
-    :yaml
-  end
-
   def self.from_pson(data)
     obj = self.allocate
     obj.initialize_from_hash(data)
     obj
   end
 
+  def as_logging_destination(&block)
+    Puppet::Util::Log.with_destination(self, &block)
+  end
+
   # @api private
   def <<(msg)
     @logs << msg
@@ -165,7 +165,7 @@ class Puppet::Transaction::Report
   end
 
   # @api private
-  def initialize(kind, configuration_version=nil, environment=nil)
+  def initialize(kind, configuration_version=nil, environment=nil, transaction_uuid=nil)
     @metrics = {}
     @logs = []
     @resource_statuses = {}
@@ -173,9 +173,10 @@ class Puppet::Transaction::Report
     @host = Puppet[:node_name_value]
     @time = Time.now
     @kind = kind
-    @report_format = 3
+    @report_format = 4
     @puppet_version = Puppet.version
     @configuration_version = configuration_version
+    @transaction_uuid = transaction_uuid
     @environment = environment
     @status = 'failed' # assume failed until the report is finalized
   end
@@ -185,6 +186,7 @@ class Puppet::Transaction::Report
     @puppet_version = data['puppet_version']
     @report_format = data['report_format']
     @configuration_version = data['configuration_version']
+    @transaction_uuid = data['transaction_uuid']
     @environment = data['environment']
     @status = data['status']
     @host = data['host']
@@ -214,6 +216,24 @@ class Puppet::Transaction::Report
     end
   end
 
+  def to_pson
+    {
+      'host' => @host,
+      'time' => @time.iso8601(9),
+      'configuration_version' => @configuration_version,
+      'transaction_uuid' => @transaction_uuid,
+      'report_format' => @report_format,
+      'puppet_version' => @puppet_version,
+      'kind' => @kind,
+      'status' => @status,
+      'environment' => @environment,
+
+      'logs' => @logs,
+      'metrics' => @metrics,
+      'resource_statuses' => @resource_statuses,
+    }.to_pson
+  end
+
   # @return [String] the host name
   # @api public
   #

data/lib/puppet/transaction/resource_harness.rb

@@ -29,13 +29,12 @@ class Puppet::Transaction::ResourceHarness
   end
 
   def perform_changes(resource)
-    current = resource.retrieve_resource
+    current_values = resource.retrieve_resource.to_hash
 
-    cache resource, :checked, Time.now
+    cache(resource, :checked, Time.now)
 
     return [] if ! allow_changes?(resource)
 
-    current_values = current.to_hash
     historical_values = Puppet::Util::Storage.cache(resource).dup
     desired_values = {}
     resource.properties.each do |property|
@@ -133,33 +132,31 @@ class Puppet::Transaction::ResourceHarness
   end
 
   def evaluate(resource)
-    start = Time.now
     status = Puppet::Resource::Status.new(resource)
 
-    perform_changes(resource).each do |event|
-      status << event
-    end
+    begin
+      perform_changes(resource).each do |event|
+        status << event
+      end
 
-    if status.changed? && ! resource.noop?
-      cache(resource, :synced, Time.now)
-      resource.flush if resource.respond_to?(:flush)
+      if status.changed? && ! resource.noop?
+        cache(resource, :synced, Time.now)
+        resource.flush if resource.respond_to?(:flush)
+      end
+    rescue => detail
+      status.failed_because(detail)
+    ensure
+      status.evaluation_time = Time.now - status.time
     end
 
-    return status
-  rescue => detail
-    resource.fail "Could not create resource status: #{detail}" unless status
-    resource.log_exception(detail, "Could not evaluate: #{detail}")
-    status.failed = true
-    return status
-  ensure
-    (status.evaluation_time = Time.now - start) if status
+    status
   end
 
   def initialize(transaction)
     @transaction = transaction
   end
 
-  def scheduled?(status, resource)
+  def scheduled?(resource)
     return true if Puppet[:ignoreschedules]
     return true unless schedule = schedule(resource)
 

data/lib/puppet/type.rb

@@ -7,7 +7,6 @@ require 'puppet/util'
 require 'puppet/util/autoload'
 require 'puppet/metatype/manager'
 require 'puppet/util/errors'
-require 'puppet/util/log_paths'
 require 'puppet/util/logging'
 require 'puppet/util/tagging'
 
@@ -77,7 +76,6 @@ module Puppet
 class Type
   include Puppet::Util
   include Puppet::Util::Errors
-  include Puppet::Util::LogPaths
   include Puppet::Util::Logging
   include Puppet::Util::Tagging
 
@@ -303,7 +301,7 @@ class Type
   # @param metaparam [??? Puppet::Parameter] the meta-parameter to get documentation for.
   # @return [String] the documentation associated with the given meta-parameter, or nil of not such documentation
   #   exists.
-  # @raises [?] if the given metaparam is not a meta-parameter in this type
+  # @raise if the given metaparam is not a meta-parameter in this type
   #
   def self.metaparamdoc(metaparam)
     @@metaparamhash[metaparam].doc
@@ -354,11 +352,10 @@ class Type
   # Returns parameters that act as a key.
   # All parameters that return true from #isnamevar? or is named `:name` are included in the returned result.
   # @todo would like a better explanation
-  # @return Array<??? Puppet::Parameter>
-  #
+  # @return [Array<Puppet::Parameter>] WARNING: this return type is uncertain
   def self.key_attribute_parameters
     @key_attribute_parameters ||= (
-      params = @parameters.find_all { |param|
+      @parameters.find_all { |param|
         param.isnamevar? or param.name == :name
       }
     )
@@ -748,6 +745,13 @@ class Type
     @parameters[name] = klass.new(:resource => self)
   end
 
+  # Returns a string representation of the resource's containment path in
+  # the catalog.
+  # @return [String]
+  def path
+    @path ||= '/' + pathbuilder.join('/')
+  end
+
   # Returns the value of this object's parameter given by name
   # @param name [String] the name of the parameter
   # @return [Object] the value
@@ -1003,7 +1007,7 @@ class Type
   # 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
   #   methods that also "gets" properties/parameters/etc. ?
-  # @return [Array<Object>] array of all property values (mix of types)
+  # @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.
   def retrieve
     fail "Provider #{provider.class.name} is not functional on this host" if self.provider.is_a?(Puppet::Provider) and ! provider.class.suitable?
@@ -1031,12 +1035,16 @@ class Type
     result
   end
 
-  # ???
-  # @todo what does this do? It seems to create a new Resource based on the result of calling #retrieve
-  #  and if that is a Hash, else this method produces nil.
-  # @return [Puppet::Resource, nil] a new Resource, or nil, if this object did not produce a Hash as the
-  #   result from #retrieve
+  # Retrieve the current state of the system as a Puppet::Resource. For
+  # the base Puppet::Type this does the same thing as #retrieve, but
+  # specific types are free to implement #retrieve as returning a hash,
+  # and this will call #retrieve and convert the hash to a resource.
+  # This is used when determining when syncing a resource.
+  #
+  # @return [Puppet::Resource] A resource representing the current state
+  #   of the system.
   #
+  # @api private
   def retrieve_resource
     resource = retrieve
     resource = Resource.new(type, title, :parameters => resource) if resource.is_a? Hash
@@ -1044,7 +1052,7 @@ class Type
   end
 
   # Returns a hash of the current properties and their values.
-  # If a resource is absent, it's value is the symbol `:absent`
+  # If a resource is absent, its value is the symbol `:absent`
   # @return [Hash{Puppet::Property => Object}] mapping of property instance to its value
   #
   def currentpropvalues
@@ -1097,7 +1105,7 @@ class Type
     # Put the default provider first, then the rest of the suitable providers.
     provider_instances = {}
     providers_by_source.collect do |provider|
-      all_properties = self.properties.find_all do |property|
+      self.properties.find_all do |property|
         provider.supports_parameter?(property)
       end.collect do |property|
         property.name
@@ -1138,7 +1146,7 @@ class Type
 
   # Converts a simple hash into a Resource instance.
   # @todo as opposed to a complex hash? Other raised exceptions?
-  # @param [Hash{Symbol, String => Object}] resource attribute to value map to initialize the created resource from
+  # @param [Hash{Symbol, String => Object}] hash resource attribute to value map to initialize the created resource from
   # @return [Puppet::Resource] the resource created from the hash
   # @raise [Puppet::Error] if a title is missing in the given hash
   def self.hash2resource(hash)
@@ -1152,12 +1160,7 @@ class Type
 
     # Now create our resource.
     resource = Puppet::Resource.new(self.name, title)
-    [:catalog].each do |attribute|
-      if value = hash[attribute]
-        hash.delete(attribute)
-        resource.send(attribute.to_s + "=", value)
-      end
-    end
+    resource.catalog = hash.delete(:catalog)
 
     hash.each do |param, value|
       resource[param] = value
@@ -1165,10 +1168,12 @@ class Type
     resource
   end
 
-  # Creates the path for logging and such.
-  # @todo "and such?", what?
-  # @api private
+
+  # Returns an array of strings representing the containment heirarchy
+  # (types/classes) that make up the path to the resource from the root
+  # of the catalog.  This is mostly used for logging purposes.
   #
+  # @api private
   def pathbuilder
     if p = parent
       [p.pathbuilder, self.ref].flatten
@@ -1284,43 +1289,43 @@ class Type
   end
 
   newmetaparam(:alias) do
-    desc "Creates an alias for the object.  Puppet uses this internally when you
-      provide a symbolic title:
+    desc %q{Creates an alias for the resource.  Puppet uses this internally when you
+      provide a symbolic title and an explicit namevar value:
 
           file { 'sshdconfig':
             path => $operatingsystem ? {
-              solaris => \"/usr/local/etc/ssh/sshd_config\",
-              default => \"/etc/ssh/sshd_config\"
+              solaris => '/usr/local/etc/ssh/sshd_config',
+              default => '/etc/ssh/sshd_config',
             },
-            source => \"...\"
+            source => '...'
           }
 
           service { 'sshd':
-            subscribe => File['sshdconfig']
+            subscribe => File['sshdconfig'],
           }
 
       When you use this feature, the parser sets `sshdconfig` as the title,
       and the library sets that as an alias for the file so the dependency
       lookup in `Service['sshd']` works.  You can use this metaparameter yourself,
-      but note that only the library can use these aliases; for instance,
-      the following code will not work:
+      but note that aliases generally only work for creating relationships; anything
+      else that refers to an existing resource (such as amending or overriding
+      resource attributes in an inherited class) must use the resource's exact
+      title. For example, the following code will not work:
 
-          file { \"/etc/ssh/sshd_config\":
+          file { '/etc/ssh/sshd_config':
             owner => root,
             group => root,
-            alias => 'sshdconfig'
+            alias => 'sshdconfig',
           }
 
-          file { 'sshdconfig':
-            mode => 644
+          File['sshdconfig'] {
+            mode => 644,
           }
 
       There's no way here for the Puppet parser to know that these two stanzas
       should be affecting the same file.
 
-      See the [Language Guide](http://docs.puppetlabs.com/guides/language_guide.html) for more information.
-
-      "
+      }
 
     munge do |aliases|
       aliases = [aliases] unless aliases.is_a?(Array)
@@ -1408,7 +1413,7 @@ class Type
       @value.each do |ref|
         unless @resource.catalog.resource(ref.to_s)
           description = self.class.direction == :in ? "dependency" : "dependent"
-          fail "Could not find #{description} #{ref} for #{resource.ref}"
+          fail ResourceError, "Could not find #{description} #{ref} for #{resource.ref}"
         end
       end
     end
@@ -1459,7 +1464,7 @@ class Type
           self.debug("requires #{related_resource.ref}")
         end
 
-        rel = Puppet::Relationship.new(source, target, subargs)
+        Puppet::Relationship.new(source, target, subargs)
       end
     end
   end
@@ -1809,7 +1814,7 @@ class Type
       end
 
       # @todo this does what? where and how?
-      # @returns [String] the name of the provider
+      # @return [String] the name of the provider
       defaultto {
         prov = @resource.class.defaultprovider
         prov.name if prov
@@ -1819,7 +1824,7 @@ class Type
         provider_class = provider_class[0] if provider_class.is_a? Array
         provider_class = provider_class.class.name if provider_class.is_a?(Puppet::Provider)
 
-        unless provider = @resource.class.provider(provider_class)
+        unless @resource.class.provider(provider_class)
           raise ArgumentError, "Invalid #{@resource.class.name} provider '#{provider_class}'"
         end
       end
@@ -1942,8 +1947,9 @@ class Type
   # Adds dependencies to the catalog from added autorequirements.
   # See {autorequire} for how to add an auto-requirement.
   # @todo needs details - see the param rel_catalog, and type of this param
-  # @param rel_catalog [Puppet::Catalog, nil] the catalog to add dependencies to. Defaults to the
-  #   catalog (TODO: what is the type of the catalog).
+  # @param rel_catalog [Puppet::Resource::Catalog, nil] the catalog to
+  #   add dependencies to. Defaults to the current catalog (set when the
+  #   type instance was added to a catalog)
   # @raise [Puppet::DevError] if there is no catalog
   #
   def autorequire(rel_catalog = nil)
@@ -1953,7 +1959,7 @@ class Type
     reqs = []
     self.class.eachautorequire { |type, block|
       # Ignore any types we can't find, although that would be a bit odd.
-      next unless typeobj = Puppet::Type.type(type)
+      next unless Puppet::Type.type(type)
 
       # Retrieve the list of names from the block.
       next unless list = self.instance_eval(&block)
@@ -2104,7 +2110,6 @@ class Type
   #
   def self.validate(&block)
     define_method(:validate, &block)
-    #@validate = block
   end
 
   # @return [String] The file from which this type originates from
@@ -2157,8 +2162,8 @@ class Type
   #   resources; one that causes the title to be set to resource.title, and one that
   #   causes the title to be resource.ref ("for components") - what is a component?
   #
-  # @overaload initialize(hsh)
-  #   @param hsh [Hash]
+  # @overload initialize(hash)
+  #   @param [Hash] hash
   #   @raise [Puppet::ResourceError] when the type validation raises
   #     Puppet::Error or ArgumentError
   # @overload initialize(resource)
@@ -2351,14 +2356,14 @@ class Type
     end
   end
 
-  # Returns the title of this object, or it's name if title was not explicetly set.
+  # Returns the title of this object, or its name if title was not explicetly 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 it's name if title was not explicetly set.
+  # @return [String] Returns the title of this object, or its name if title was not explicetly set.
   # @raise [??? devfail] if title is not set, and name_var can not be found.
   def title
     unless @title
@@ -2406,14 +2411,15 @@ class Type
   def exported?; !!@exported; end
 
   # @return [Boolean] Returns whether the resource is applicable to `:device`
-  # @todo Explain what this means
+  # Returns true if a resource of this type can be evaluated on a 'network device' kind
+  # of hosts.
   # @api private
   def appliable_to_device?
     self.class.can_apply_to(:device)
   end
 
   # @return [Boolean] Returns whether the resource is applicable to `:host`
-  # @todo Explain what this means
+  # Returns true if a resource of this type can be evaluated on a regular generalized computer (ie not an appliance like a network device)
   # @api private
   def appliable_to_host?
     self.class.can_apply_to(:host)