puppet 3.0.2 → 3.1.0.rc1

data/lib/puppet/indirector/facts/couch.rb

@@ -2,6 +2,9 @@ require 'puppet/node/facts'
 require 'puppet/indirector/couch'
 class Puppet::Node::Facts::Couch < Puppet::Indirector::Couch
 
+  desc "Store facts in CouchDB. This should not be used with the inventory service;
+    it is for more obscure custom integrations. If you are wondering whether you
+    should use it, you shouldn't; use PuppetDB instead."
   # Return the facts object or nil if there is no document
   def find(request)
     doc = super

data/lib/puppet/indirector/facts/inventory_active_record.rb

@@ -6,6 +6,10 @@ require 'puppet/util/retryaction'
 
 class Puppet::Node::Facts::InventoryActiveRecord < Puppet::Indirector::ActiveRecord
 
+  desc "Medium-performance fact storage suitable for the inventory service.
+    Most users should use PuppetDB instead. Note: ActiveRecord-based storeconfigs
+    and inventory are deprecated. See http://links.puppetlabs.com/activerecord-deprecation"
+
   def initialize
     Puppet.deprecation_warning "ActiveRecord-based storeconfigs and inventory are deprecated. See http://links.puppetlabs.com/activerecord-deprecation"
     super

data/lib/puppet/indirector/facts/store_configs.rb

@@ -2,4 +2,7 @@ require 'puppet/node/facts'
 require 'puppet/indirector/store_configs'
 
 class Puppet::Node::Facts::StoreConfigs < Puppet::Indirector::StoreConfigs
+
+  desc %q{Part of the "storeconfigs" feature. Should not be directly set by end users.}
+
 end

data/lib/puppet/indirector/file_metadata/rest.rb

@@ -4,4 +4,6 @@ require 'puppet/indirector/rest'
 
 class Puppet::Indirector::FileMetadata::Rest < Puppet::Indirector::REST
   desc "Retrieve file metadata via a REST HTTP interface."
+
+  use_srv_service(:fileserver)
 end

data/lib/puppet/indirector/instrumentation_data/local.rb

@@ -1,6 +1,9 @@
 require 'puppet/indirector/instrumentation_data'
 
 class Puppet::Indirector::InstrumentationData::Local < Puppet::Indirector::Code
+
+  desc "Undocumented."
+
   def find(request)
     model.new(request.key)
   end

data/lib/puppet/indirector/instrumentation_data/rest.rb

@@ -2,4 +2,7 @@ require 'puppet/indirector/rest'
 require 'puppet/indirector/instrumentation_data'
 
 class Puppet::Indirector::InstrumentationData::Rest < Puppet::Indirector::REST
+
+  desc "Undocumented."
+
 end

data/lib/puppet/indirector/instrumentation_listener/local.rb

@@ -1,6 +1,9 @@
 require 'puppet/indirector/instrumentation_listener'
 
 class Puppet::Indirector::InstrumentationListener::Local < Puppet::Indirector::Code
+
+  desc "Undocumented."
+
   def find(request)
     Puppet::Util::Instrumentation[request.key]
   end

data/lib/puppet/indirector/instrumentation_listener/rest.rb

@@ -2,4 +2,7 @@ require 'puppet/indirector/instrumentation_listener'
 require 'puppet/indirector/rest'
 
 class Puppet::Indirector::InstrumentationListener::Rest < Puppet::Indirector::REST
+
+  desc "Undocumented."
+
 end

data/lib/puppet/indirector/instrumentation_probe/local.rb

@@ -3,6 +3,9 @@ require 'puppet/indirector/code'
 require 'puppet/util/instrumentation/indirection_probe'
 
 class Puppet::Indirector::InstrumentationProbe::Local < Puppet::Indirector::Code
+
+  desc "Undocumented."
+
   def find(request)
   end
 

data/lib/puppet/indirector/instrumentation_probe/rest.rb

@@ -2,4 +2,7 @@ require 'puppet/indirector/rest'
 require 'puppet/indirector/instrumentation_probe'
 
 class Puppet::Indirector::InstrumentationProbe::Rest < Puppet::Indirector::REST
+
+  desc "Undocumented."
+
 end

data/lib/puppet/indirector/node/active_record.rb

@@ -5,6 +5,9 @@ require 'puppet/node'
 class Puppet::Node::ActiveRecord < Puppet::Indirector::ActiveRecord
   use_ar_model Puppet::Rails::Host
 
+  desc "A component of ActiveRecord storeconfigs. ActiveRecord-based storeconfigs
+    and inventory are deprecated. See http://links.puppetlabs.com/activerecord-deprecation"
+
   def initialize
     Puppet.deprecation_warning "ActiveRecord-based storeconfigs and inventory are deprecated. See http://links.puppetlabs.com/activerecord-deprecation"
     super

data/lib/puppet/indirector/node/rest.rb

@@ -2,6 +2,6 @@ require 'puppet/node'
 require 'puppet/indirector/rest'
 
 class Puppet::Node::Rest < Puppet::Indirector::REST
-  desc "This will eventually be a REST-based mechanism for finding nodes.  It is currently non-functional."
-  # TODO/FIXME
+  desc "Get a node via REST. Puppet agent uses this to allow the puppet master
+    to override its environment."
 end

data/lib/puppet/indirector/node/store_configs.rb

@@ -2,4 +2,7 @@ require 'puppet/indirector/store_configs'
 require 'puppet/node'
 
 class Puppet::Node::StoreConfigs < Puppet::Indirector::StoreConfigs
+
+  desc %q{Part of the "storeconfigs" feature. Should not be directly set by end users.}
+
 end

data/lib/puppet/indirector/node/write_only_yaml.rb

@@ -0,0 +1,32 @@
+require 'puppet/node'
+require 'puppet/indirector/yaml'
+
+# This is a WriteOnlyYaml terminus that exists only for the purpose of being able to write
+# node cache data that later can be read by the YAML terminus.
+# The use case this supports is to make it possible to search among the "current nodes"
+# when Puppet DB (recommended) or other central storage of information is not available.
+#
+# @see puppet issue 16753
+# @see Puppet::Application::Master#setup_node_cache
+# @api private
+#
+class Puppet::Node::WriteOnlyYaml < Puppet::Indirector::Yaml
+  desc "Store node information as flat files, serialized using YAML,
+    does not deserialize (write only)."
+
+  # Overridden to always return nil. This is a write only terminus.
+  # @param [Object] request Ignored.
+  # @return [nil] This implementation always return nil'
+  # @api
+  def find(request)
+    nil
+  end
+
+  # Overridden to always return nil. This is a write only terminus.
+  # @param [Object] request Ignored.
+  # @return [nil] This implementation always return nil
+  # @api
+  def search(request)
+    nil
+  end
+end

data/lib/puppet/indirector/queue.rb

@@ -24,7 +24,6 @@ class Puppet::Indirector::Queue < Puppet::Indirector::Terminus
 
   def initialize(*args)
     super
-    raise ArgumentError, "Queueing requires pson support" unless Puppet.features.pson?
   end
 
   # Queue has no idiomatic "find"

data/lib/puppet/indirector/request.rb

@@ -16,8 +16,7 @@ class Puppet::Indirector::Request
 
   OPTION_ATTRIBUTES = [:ip, :node, :authenticated, :ignore_terminus, :ignore_cache, :instance, :environment]
 
-  # Load json before trying to register.
-  Puppet.features.pson? and ::PSON.register_document_type('IndirectorRequest',self)
+  ::PSON.register_document_type('IndirectorRequest',self)
 
   def self.from_pson(json)
     raise ArgumentError, "No indirection name provided in json data" unless indirection_name = json['type']

data/lib/puppet/indirector/resource/active_record.rb

@@ -1,6 +1,10 @@
 require 'puppet/indirector/active_record'
 
 class Puppet::Resource::ActiveRecord < Puppet::Indirector::ActiveRecord
+
+  desc "A component of ActiveRecord storeconfigs. ActiveRecord-based storeconfigs
+    and inventory are deprecated. See http://links.puppetlabs.com/activerecord-deprecation"
+
   def initialize
     Puppet.deprecation_warning "ActiveRecord-based storeconfigs and inventory are deprecated. See http://links.puppetlabs.com/activerecord-deprecation"
     super

data/lib/puppet/indirector/resource/ral.rb

@@ -1,4 +1,7 @@
 class Puppet::Resource::Ral < Puppet::Indirector::Code
+
+  desc "Manipulate resources with the resource abstraction layer. Only used internally."
+
   def find( request )
     # find by name
     res   = type(request).instances.find { |o| o.name == resource_name(request) }

data/lib/puppet/indirector/resource/rest.rb

@@ -2,4 +2,7 @@ require 'puppet/indirector/status'
 require 'puppet/indirector/rest'
 
 class Puppet::Resource::Rest < Puppet::Indirector::REST
+
+  desc "Maniuplate resources remotely? Undocumented."
+
 end

data/lib/puppet/indirector/resource/store_configs.rb

@@ -1,3 +1,6 @@
 require 'puppet/indirector/store_configs'
 class Puppet::Resource::StoreConfigs < Puppet::Indirector::StoreConfigs
+
+  desc %q{Part of the "storeconfigs" feature. Should not be directly set by end users.}
+
 end

data/lib/puppet/indirector/run/local.rb

@@ -2,6 +2,9 @@ require 'puppet/run'
 require 'puppet/indirector/code'
 
 class Puppet::Run::Local < Puppet::Indirector::Code
+
+  desc "Trigger a Puppet run locally. Only used internally."
+
   def save( request )
     request.instance.run
   end

data/lib/puppet/indirector/ssl_file.rb

@@ -82,13 +82,9 @@ class Puppet::Indirector::SslFile < Puppet::Indirector::Terminus
 
   # Find the file on disk, returning an instance of the model.
   def find(request)
-    path = path(request.key)
-
-    return nil unless FileTest.exist?(path) or rename_files_with_uppercase(path)
+    filename = rename_files_with_uppercase(path(request.key))
 
-    result = model.new(request.key)
-    result.read(path)
-    result
+    filename ? create_model(request.key, filename) : nil
   end
 
   # Save our file to disk.
@@ -106,16 +102,20 @@ class Puppet::Indirector::SslFile < Puppet::Indirector::Terminus
   # an instance for every file in the directory.
   def search(request)
     dir = collection_directory
-    Dir.entries(dir).reject { |file| file !~ /\.pem$/ }.collect do |file|
-      name = file.sub(/\.pem$/, '')
-      result = model.new(name)
-      result.read(File.join(dir, file))
-      result
-    end
+    Dir.entries(dir).
+      select  { |file| file =~ /\.pem$/ }.
+      collect { |file| create_model(file.sub(/\.pem$/, ''), File.join(dir, file)) }.
+      compact
   end
 
   private
 
+  def create_model(name, path)
+    result = model.new(name)
+    result.read(path)
+    result
+  end
+
   # Demeterish pointers to class info.
   def collection_directory
     self.class.collection_directory
@@ -135,6 +135,8 @@ class Puppet::Indirector::SslFile < Puppet::Indirector::Terminus
   # which we'll be EOL'ing at some point.  This method was added at 20080702
   # and should be removed at some point.
   def rename_files_with_uppercase(file)
+    return file if FileTest.exist?(file)
+
     dir, short = File.split(file)
     return nil unless FileTest.exist?(dir)
 
@@ -147,10 +149,10 @@ class Puppet::Indirector::SslFile < Puppet::Indirector::Terminus
 
     full_file = File.join(dir, real_file)
 
-    Puppet.notice "Fixing case in #{full_file}; renaming to #{file}"
+    Puppet.deprecation_warning "Automatic downcasing and renaming of ssl files is deprecated; please request the file using its correct case: #{full_file}"
     File.rename(full_file, file)
 
-    true
+    file
   end
 
   # Yield a filehandle set up appropriately, either with our settings doing

data/lib/puppet/indirector/status/local.rb

@@ -1,6 +1,9 @@
 require 'puppet/indirector/status'
 
 class Puppet::Indirector::Status::Local < Puppet::Indirector::Code
+
+  desc "Get status locally. Only used internally."
+
   def find( *anything )
     model.new
   end

data/lib/puppet/indirector/status/rest.rb

@@ -2,4 +2,8 @@ require 'puppet/indirector/status'
 require 'puppet/indirector/rest'
 
 class Puppet::Indirector::Status::Rest < Puppet::Indirector::REST
+
+  desc "Get puppet master's status via REST. Useful because it tests the health
+    of both the web server and the indirector."
+
 end

data/lib/puppet/interface.rb

@@ -4,6 +4,7 @@ require 'puppet/interface/documentation'
 require 'prettyprint'
 require 'semver'
 
+# @api public
 class Puppet::Interface
   include FullDocs
 
@@ -22,19 +23,38 @@ class Puppet::Interface
   class << self
     # This is just so we can search for actions.  We only use its
     # list of directories to search.
-    # Can't we utilize an external autoloader, or simply use the $LOAD_PATH? -pvb
+
+    # @api private
+    # @deprecated
     def autoloader
+      Puppet.deprecation_warning("Puppet::Interface.autoloader is deprecated; please use Puppet::Interface#loader instead")
       @autoloader ||= Puppet::Util::Autoload.new(:application, "puppet/face")
     end
 
+    # Lists all loaded faces
+    # @return [Array<Symbol>] The names of the loaded faces
     def faces
       Puppet::Interface::FaceCollection.faces
     end
 
+    # Register a face
+    # @param instance [Puppet::Interface] The face
+    # @return [void]
+    # @api private
     def register(instance)
       Puppet::Interface::FaceCollection.register(instance)
     end
 
+    # Defines a new Face.
+    # @todo Talk about using Faces DSL inside the block
+    #
+    # @param name [Symbol] the name of the face
+    # @param version [String] the version of the face (this should
+    #   conform to {http://semver.org/ Semantic Versioning})
+    # @overload define(name, version, {|| ... })
+    # @return [Puppet::Interface] The created face
+    # @api public
+    # @dsl Faces
     def define(name, version, &block)
       face = Puppet::Interface::FaceCollection[name, version]
       if face.nil? then
@@ -50,12 +70,30 @@ class Puppet::Interface
       return face
     end
 
+    # Retrieves a face by name and version. Use `:current` for the
+    # version to get the most recent available version.
+    #
+    # @param name [Symbol] the name of the face
+    # @param version [String, :current] the version of the face
+    #
+    # @return [Puppet::Interface] the face
+    #
+    # @api public
     def face?(name, version)
       Puppet::Interface::FaceCollection[name, version]
     end
 
+    # Retrieves a face by name and version
+    #
+    # @param name [Symbol] the name of the face
+    # @param version [String] the version of the face
+    #
+    # @return [Puppet::Interface] the face
+    #
+    # @api public
     def [](name, version)
       unless face = Puppet::Interface::FaceCollection[name, version]
+        # REVISIT (#18042) no sense in rechecking if version == :current -- josh
         if current = Puppet::Interface::FaceCollection[name, :current]
           raise Puppet::Error, "Could not find version #{version} of #{name}"
         else
@@ -66,6 +104,11 @@ class Puppet::Interface
       face
     end
 
+    # Retrieves an action for a face
+    # @param name [Symbol] The face
+    # @param action [Symbol] The action name
+    # @param version [String, :current] The version of the face
+    # @return [Puppet::Interface::Action] The action
     def find_action(name, action, version = :current)
       Puppet::Interface::FaceCollection.get_action_for_face(name, action, version)
     end
@@ -76,15 +119,35 @@ class Puppet::Interface
   # the same instance between build-time and the runtime instance.  When that
   # splits out this should merge into a module that both the action and face
   # include. --daniel 2011-04-17
+
+
+  # Returns the synopsis for the face. This shows basic usage and global
+  # options.
+  # @return [String] usage synopsis
+  # @api private
   def synopsis
     build_synopsis self.name, '<action>'
   end
 
 
   ########################################################################
-  attr_reader :name, :version, :loader
+
+  # The name of the face
+  # @return [Symbol]
+  # @api private
+  attr_reader :name
+
+  # The version of the face
+  # @return [SemVer]
+  attr_reader :version
+
+  # The autoloader instance for the face
+  # @return [Puppet::Util::Autoload]
+  # @api private
+  attr_reader :loader
   private :loader
 
+  # @api private
   def initialize(name, version, &block)
     unless SemVer.valid?(version)
       raise ArgumentError, "Cannot create face #{name.inspect} with invalid version number '#{version}'!"
@@ -103,11 +166,16 @@ class Puppet::Interface
     instance_eval(&block) if block_given?
   end
 
-  # Try to find actions defined in other files.
+  # Loads all actions defined in other files.
+  #
+  # @return [void]
+  # @api private
   def load_actions
     loader.loadall
   end
 
+  # Returns a string representation with the face's name and version
+  # @return [String]
   def to_s
     "Puppet::Face[#{name.inspect}, #{version.inspect}]"
   end
@@ -123,6 +191,8 @@ class Puppet::Interface
   # all this away, replace it with something nice, and work out if we should
   # be making this visible to the outside world... --daniel 2011-04-14
   private
+  # @return [void]
+  # @api private
   def __invoke_decorations(type, action, passed_args = [], passed_options = {})
     [:before, :after].member?(type) or fail "unknown decoration type #{type}"
 
@@ -142,10 +212,15 @@ class Puppet::Interface
     end
   end
 
+  # @return [void]
+  # @api private
   def __add_method(name, proc)
     meta_def(name, &proc)
     method(name).unbind
   end
+
+  # @return [void]
+  # @api private
   def self.__add_method(name, proc)
     define_method(name, proc)
     instance_method(name)