puppet 3.2.4 → 3.3.0.rc2

data/lib/puppet/network/http/handler.rb

@@ -14,8 +14,32 @@ module Puppet::Network::HTTP::Handler
   include Puppet::Network::Authorization
   include Puppet::Network::Authentication
 
-  attr_reader :server, :handler
+  # These shouldn't be allowed to be set by clients
+  # in the query string, for security reasons.
+  DISALLOWED_KEYS = ["node", "ip"]
+
+  class HTTPError < Exception
+    attr_reader :status
+
+    def initialize(message, status)
+      super(message)
+      @status = status
+    end
+  end
+
+  class HTTPNotAcceptableError < HTTPError
+    def initialize(message)
+      super("Not Acceptable: " + message, 406)
+    end
+  end
 
+  class HTTPNotFoundError < HTTPError
+    def initialize(message)
+      super("Not Found: " + message, 404)
+    end
+  end
+
+  attr_reader :server, :handler
 
   # Retrieve all headers from the http request, as a hash with the header names
   # (lower-cased) as the keys
@@ -33,29 +57,12 @@ module Puppet::Network::HTTP::Handler
     raise NotImplementedError
   end
 
-  # Which format to use when serializing our response or interpreting the request.
-  # IF the client provided a Content-Type use this, otherwise use the Accept header
-  # and just pick the first value.
-  def format_to_use(request)
-    unless header = accept_header(request)
-      raise ArgumentError, "An Accept header must be provided to pick the right format"
-    end
-
-    format = nil
-    header.split(/,\s*/).each do |name|
-      next unless format = Puppet::Network::FormatHandler.format(name)
-      next unless format.suitable?
-      return format
-    end
-
-    raise "No specified acceptable formats (#{header}) are functional on this machine"
-  end
-
   def request_format(request)
     if header = content_type_header(request)
       header.gsub!(/\s*;.*$/,'') # strip any charset
       format = Puppet::Network::FormatHandler.mime(header)
       raise "Client sent a mime-type (#{header}) that doesn't correspond to a format we support" if format.nil?
+      report_if_deprecated(format)
       return format.name.to_s if format.suitable?
     end
 
@@ -89,6 +96,8 @@ module Puppet::Network::HTTP::Handler
     end
   rescue SystemExit,NoMemoryError
     raise
+  rescue HTTPError => e
+    return do_exception(response, e.message, e.status)
   rescue Exception => e
     return do_exception(response, e)
   ensure
@@ -111,9 +120,13 @@ module Puppet::Network::HTTP::Handler
       # for authorization issues
       status = 403 if status == 400
     end
+
     if exception.is_a?(Exception)
       Puppet.log_exception(exception)
+    else
+      Puppet.notice(exception.to_s)
     end
+
     set_content_type(response, "text/plain")
     set_response(response, exception.to_s, status)
   end
@@ -125,21 +138,18 @@ module Puppet::Network::HTTP::Handler
 
   # Execute our find.
   def do_find(indirection_name, key, params, request, response)
-    unless result = model(indirection_name).indirection.find(key, params)
-      Puppet.info("Could not find #{indirection_name} for '#{key}'")
-      return do_exception(response, "Could not find #{indirection_name} #{key}", 404)
+    model_class = model(indirection_name)
+    unless result = model_class.indirection.find(key, params)
+      raise HTTPNotFoundError, "Could not find #{indirection_name} #{key}"
     end
 
-    # The encoding of the result must include the format to use,
-    # and it needs to be used for both the rendering and as
-    # the content type.
-    format = format_to_use(request)
+    format = accepted_response_formatter_for(model_class, request)
     set_content_type(response, format)
 
     rendered_result = result
     if result.respond_to?(:render)
       Puppet::Util::Profiler.profile("Rendered result in #{format}") do
-       rendered_result = result.render(format)
+        rendered_result = result.render(format)
       end
     end
 
@@ -151,8 +161,7 @@ module Puppet::Network::HTTP::Handler
   # Execute our head.
   def do_head(indirection_name, key, params, request, response)
     unless self.model(indirection_name).indirection.head(key, params)
-      Puppet.info("Could not find #{indirection_name} for '#{key}'")
-      return do_exception(response, "Could not find #{indirection_name} #{key}", 404)
+      raise HTTPNotFoundError, "Could not find #{indirection_name} #{key}"
     end
 
     # No need to set a response because no response is expected from a
@@ -165,10 +174,10 @@ module Puppet::Network::HTTP::Handler
     result = model.indirection.search(key, params)
 
     if result.nil?
-      return do_exception(response, "Could not find instances in #{indirection_name} with '#{key}'", 404)
+      raise HTTPNotFoundError, "Could not find instances in #{indirection_name} with '#{key}'"
     end
 
-    format = format_to_use(request)
+    format = accepted_response_formatter_for(model, request)
     set_content_type(response, format)
 
     set_response(response, model.render_multiple(format, result))
@@ -176,20 +185,25 @@ module Puppet::Network::HTTP::Handler
 
   # Execute our destroy.
   def do_destroy(indirection_name, key, params, request, response)
-    result = model(indirection_name).indirection.destroy(key, params)
+    model_class = model(indirection_name)
+    formatter = accepted_response_formatter_or_yaml_for(model_class, request)
 
-    return_yaml_response(response, result)
+    result = model_class.indirection.destroy(key, params)
+
+    set_content_type(response, formatter)
+    set_response(response, formatter.render(result))
   end
 
   # Execute our save.
   def do_save(indirection_name, key, params, request, response)
-    data = body(request).to_s
-    raise ArgumentError, "No data to save" if !data or data.empty?
+    model_class = model(indirection_name)
+    formatter = accepted_response_formatter_or_yaml_for(model_class, request)
+    sent_object = read_body_into_model(model_class, request)
 
-    format = request_format(request)
-    obj = model(indirection_name).convert_from(format, data)
-    result = model(indirection_name).indirection.save(obj, key)
-    return_yaml_response(response, result)
+    result = model_class.indirection.save(sent_object, key)
+
+    set_content_type(response, formatter)
+    set_response(response, formatter.render(result))
   end
 
   # resolve node name from peer's ip address
@@ -205,9 +219,41 @@ module Puppet::Network::HTTP::Handler
 
   private
 
-  def return_yaml_response(response, body)
-    set_content_type(response, Puppet::Network::FormatHandler.format("yaml"))
-    set_response(response, body.to_yaml)
+  def report_if_deprecated(format)
+    if format.name == :yaml || format.name == :b64_zlib_yaml
+      Puppet.deprecation_warning("YAML in network requests is deprecated and will be removed in a future version. See http://links.puppetlabs.com/deprecate_yaml_on_network")
+    end
+  end
+
+  def accepted_response_formatter_for(model_class, request)
+    accepted_formats = accept_header(request) or raise HTTPNotAcceptableError, "Missing required Accept header"
+    response_formatter_for(model_class, request, accepted_formats)
+  end
+
+  def accepted_response_formatter_or_yaml_for(model_class, request)
+    accepted_formats = accept_header(request) || "yaml"
+    response_formatter_for(model_class, request, accepted_formats)
+  end
+
+  def response_formatter_for(model_class, request, accepted_formats)
+    formatter = Puppet::Network::FormatHandler.most_suitable_format_for(
+      accepted_formats.split(/\s*,\s*/),
+      model_class.supported_formats)
+
+    if formatter.nil?
+      raise HTTPNotAcceptableError, "No supported formats are acceptable (Accept: #{accepted_formats})"
+    end
+
+    report_if_deprecated(formatter)
+    formatter
+  end
+
+  def read_body_into_model(model_class, request)
+    data = body(request).to_s
+    raise ArgumentError, "No data to save" if !data or data.empty?
+
+    format = request_format(request)
+    model_class.convert_from(format, data)
   end
 
   def get?(request)
@@ -253,30 +299,45 @@ module Puppet::Network::HTTP::Handler
   end
 
   def decode_params(params)
-    params.inject({}) do |result, ary|
+    params.select { |key, _| allowed_parameter?(key) }.inject({}) do |result, ary|
       param, value = ary
-      next result if param.nil? || param.empty?
-
-      param = param.to_sym
-
-      # These shouldn't be allowed to be set by clients
-      # in the query string, for security reasons.
-      next result if param == :node
-      next result if param == :ip
-      value = CGI.unescape(value)
-      if value =~ /^---/
-        value = YAML.load(value, :safe => true, :deserialize_symbols => true)
-      else
-        value = true if value == "true"
-        value = false if value == "false"
-        value = Integer(value) if value =~ /^\d+$/
-        value = value.to_f if value =~ /^\d+\.\d+$/
-      end
-      result[param] = value
+      result[param.to_sym] = parse_parameter_value(param, value)
       result
     end
   end
 
+  def allowed_parameter?(name)
+    not (name.nil? || name.empty? || DISALLOWED_KEYS.include?(name))
+  end
+
+  def parse_parameter_value(param, value)
+    case value
+    when /^---/
+      Puppet.debug("Found YAML while processing request parameter #{param} (value: <#{value}>)")
+      Puppet.deprecation_warning("YAML in network requests is deprecated and will be removed in a future version. See http://links.puppetlabs.com/deprecate_yaml_on_network")
+      YAML.load(value, :safe => true, :deserialize_symbols => true)
+    when Array
+      value.collect { |v| parse_primitive_parameter_value(v) }
+    else
+      parse_primitive_parameter_value(value)
+    end
+  end
+
+  def parse_primitive_parameter_value(value)
+    case value
+    when "true"
+      true
+    when "false"
+      false
+    when /^\d+$/
+      Integer(value)
+    when /^\d+\.\d+$/
+      value.to_f
+    else
+      value
+    end
+  end
+
   def configure_profiler(request_headers, request_params)
     if (request_headers.has_key?(Puppet::Network::HTTP::HEADER_ENABLE_PROFILING.downcase) or Puppet[:profile])
       Puppet::Util::Profiler.current = Puppet::Util::Profiler::WallClock.new(Puppet.method(:debug), request_params.object_id)

data/lib/puppet/network/http/rack/rest.rb

@@ -51,7 +51,7 @@ class Puppet::Network::HTTP::RackREST < Puppet::Network::HTTP::RackHttpHandler
   # Retrieve all headers from the http request, as a map.
   def headers(request)
     request.env.select {|k,v| k.start_with? 'HTTP_'}.inject({}) do |m, (k,v)|
-      m[k.sub(/^HTTP_/, '').downcase] = v
+      m[k.sub(/^HTTP_/, '').gsub('_','-').downcase] = v
       m
     end
   end

data/lib/puppet/network/http/webrick/rest.rb

@@ -15,9 +15,15 @@ class Puppet::Network::HTTP::WEBrickREST < WEBrick::HTTPServlet::AbstractServlet
 
   # Retrieve the request parameters, including authentication information.
   def params(request)
-    result = request.query
-    result = decode_params(result)
-    result.merge(client_information(request))
+    params = request.query || {}
+
+    params = Hash[params.collect do |key, value|
+      all_values = value.list
+      [key, all_values.length == 1 ? value : all_values]
+    end]
+
+    params = decode_params(params)
+    params.merge(client_information(request))
   end
 
   # WEBrick uses a service method to respond to requests.  Simply delegate to the handler response method.

data/lib/puppet/network/http_pool.rb

@@ -12,8 +12,8 @@ module Puppet::Network::HttpPool
 
   # Retrieve a cached http instance if caching is enabled, else return
   # a new one.
-  def self.http_instance(host, port, use_ssl = true)
-    Puppet::Network::HTTP::Connection.new(host, port, use_ssl)
+  def self.http_instance(host, port, use_ssl = true, verify_peer = true)
+    Puppet::Network::HTTP::Connection.new(host, port, :use_ssl => use_ssl, :verify_peer => verify_peer)
   end
 
 end

data/lib/puppet/network/resolver.rb

@@ -18,6 +18,7 @@ module Puppet::Network::Resolver
       when :ca     then service = '_x-puppet-ca'
       when :report then service = '_x-puppet-report'
       when :file   then service = '_x-puppet-fileserver'
+      else              service = "_x-puppet-#{service_name.to_s}"
     end
     srv_record = "#{service}._tcp.#{domain}"
 

data/lib/puppet/network/server.rb

@@ -1,114 +1,38 @@
 require 'puppet/network/http'
-require 'puppet/util/pidlock'
 require 'puppet/network/http/webrick'
 
+#
+# @api private
 class Puppet::Network::Server
   attr_reader :address, :port
 
-  # TODO: does anything actually call this?  It seems like it's a duplicate of
-  # the code in Puppet::Daemon, but that it's not actually called anywhere.
-
-  # Put the daemon into the background.
-  def daemonize
-    if pid = fork
-      Process.detach(pid)
-      exit(0)
-    end
-
-    # Get rid of console logging
-    Puppet::Util::Log.close(:console)
-
-    Process.setsid
-    Dir.chdir("/")
-  end
-
-  def close_streams()
-    Puppet::Daemon.close_streams()
-  end
-
-  # Create a pidfile for our daemon, so we can be stopped and others
-  # don't try to start.
-  def create_pidfile
-    Puppet::Util.synchronize_on(Puppet.run_mode.name,Sync::EX) do
-      raise "Could not create PID file: #{pidfile}" unless Puppet::Util::Pidlock.new(pidfile).lock
-    end
-  end
-
-  # Remove the pid file for our daemon.
-  def remove_pidfile
-    Puppet::Util.synchronize_on(Puppet.run_mode.name,Sync::EX) do
-      Puppet::Util::Pidlock.new(pidfile).unlock
-    end
-  end
-
-  # Provide the path to our pidfile.
-  def pidfile
-    Puppet[:pidfile]
-  end
-
-  def initialize(address, port, handlers = nil)
+  def initialize(address, port)
     @port = port
     @address = address
     @http_server = Puppet::Network::HTTP::WEBrick.new
 
     @listening = false
-    @routes = {}
-    self.register(handlers) if handlers
 
     # Make sure we have all of the directories we need to function.
     Puppet.settings.use(:main, :ssl, :application)
   end
 
-  # Register handlers for REST networking, based on the Indirector.
-  def register(*indirections)
-    raise ArgumentError, "Indirection names are required." if indirections.empty?
-    indirections.flatten.each do |name|
-      Puppet::Indirector::Indirection.model(name) || raise(ArgumentError, "Cannot locate indirection '#{name}'.")
-      @routes[name.to_sym] = true
-    end
-  end
-
-  # Unregister Indirector handlers.
-  def unregister(*indirections)
-    raise "Cannot unregister indirections while server is listening." if listening?
-    indirections = @routes.keys if indirections.empty?
-
-    indirections.flatten.each do |i|
-      raise(ArgumentError, "Indirection [#{i}] is unknown.") unless @routes[i.to_sym]
-    end
-
-    indirections.flatten.each do |i|
-      @routes.delete(i.to_sym)
-    end
-  end
-
   def listening?
     @listening
   end
 
-  def listen
+  def start
     raise "Cannot listen -- already listening." if listening?
     @listening = true
     @http_server.listen(address, port)
   end
 
-  def unlisten
+  def stop
     raise "Cannot unlisten -- not currently listening." unless listening?
     @http_server.unlisten
     @listening = false
   end
 
-  def start
-    create_pidfile
-    close_streams if Puppet[:daemonize]
-    listen
-  end
-
-  def stop
-    unlisten
-    remove_pidfile
-  end
-
   def wait_for_shutdown
     @http_server.wait_for_shutdown
   end

data/lib/puppet/node/environment.rb

@@ -7,10 +7,61 @@ require 'puppet/parser/parser_factory'
 class Puppet::Node
 end
 
-# Model the environment that a node can operate in.  This class just
-# provides a simple wrapper for the functionality around environments.
+# Puppet::Node::Environment acts as a container for all configuration
+# that is expected to vary between environments.
+#
+# ## Thread local variables
+#
+# The Puppet::Node::Environment uses a number of `Thread.current` variables.
+# Since all web servers that Puppet runs on are single threaded these
+# variables are effectively global.
+#
+# ### `Thread.current[:environment]`
+#
+# The 'environment' thread variable represents the current environment that's
+# being used in the compiler.
+#
+# ### `Thread.current[:known_resource_types]`
+#
+# The 'known_resource_types' thread variable represents a singleton instance
+# of the Puppet::Resource::TypeCollection class. The variable is discarded
+# and regenerated if it is accessed by an environment that doesn't match the
+# environment of the 'known_resource_types'
+#
+# This behavior of discarding the known_resource_types every time the
+# environment changes is not ideal. In the best case this can cause valid data
+# to be discarded and reloaded. If Puppet is being used with numerous
+# environments then this penalty will be repeatedly incurred.
+#
+# In the worst case (#15106) demonstrates that if a different environment is
+# accessed during catalog compilation, for whatever reason, the
+# known_resource_types can be discarded which loses information that cannot
+# be recovered and can cause a catalog compilation to completely fail.
+#
+# ## The root environment
+#
+# In addition to normal environments that are defined by the user,there is a
+# special 'root' environment. It is defined as an instance variable on the
+# Puppet::Node::Environment metaclass. The environment name is `*root*` and can
+# be accessed by calling {Puppet::Node::Environment.root}.
+#
+# The primary purpose of the root environment is to contain parser functions
+# that are not bound to a specific environment. The main case for this is for
+# logging functions. Logging functions are attached to the 'root' environment
+# when {Puppet::Parser::Functions.reset} is called.
+#
+# The root environment is also used as a fallback environment when the
+# current environment has been requested by {Puppet::Node::Environment.current}
+# requested and no environment was set by {Puppet::Node::Environment.current=}
 class Puppet::Node::Environment
+
+  # This defines a mixin for classes that have an environment. It implements
+  # `environment` and `environment=` that respects the semantics of the
+  # Puppet::Node::Environment class
+  #
+  # @api public
   module Helper
+
     def environment
       Puppet::Node::Environment.new(@environment)
     end
@@ -26,9 +77,34 @@ class Puppet::Node::Environment
 
   include Puppet::Util::Cacher
 
+  # @!attribute seen
+  #   @scope class
+  #   @api private
+  #   @return [Hash<Symbol, Puppet::Node::Environment>] All memoized environments
   @seen = {}
 
-  # Return an existing environment instance, or create a new one.
+  # Create a new environment with the given name, or return an existing one
+  #
+  # The environment class memoizes instances so that attempts to instantiate an
+  # environment with the same name with an existing environment will return the
+  # existing environment.
+  #
+  # @overload self.new(environment)
+  #   @param environment [Puppet::Node::Environment]
+  #   @return [Puppet::Node::Environment] the environment passed as the param,
+  #     this is implemented so that a calling class can use strings or
+  #     environments interchangeably.
+  #
+  # @overload self.new(string)
+  #   @param string [String, Symbol]
+  #   @return [Puppet::Node::Environment] An existing environment if it exists,
+  #     else a new environment with that name
+  #
+  # @overload self.new()
+  #   @return [Puppet::Node::Environment] The environment as set by
+  #     Puppet.settings[:environment]
+  #
+  # @api public
   def self.new(name = nil)
     return name if name.is_a?(self)
     name ||= Puppet.settings.value(:environment)
@@ -44,35 +120,92 @@ class Puppet::Node::Environment
     @seen[symbol] = obj
   end
 
+  # Retrieve the environment for the current thread
+  #
+  # @note This should only used when a catalog is being compiled.
+  #
+  # @api private
+  #
+  # @return [Puppet::Node::Environment] the currently set environment if one
+  #   has been explicitly set, else it will return the '*root*' environment
   def self.current
     Thread.current[:environment] || root
   end
 
+  # Set the environment for the current thread
+  #
+  # @note This should only set when a catalog is being compiled. Under normal
+  #   This value is initially set in {Puppet::Parser::Compiler#environment}
+  #
+  # @note Setting this affects global state during catalog compilation, and
+  #   changing the current environment during compilation can cause unexpected
+  #   and generally very bad behaviors.
+  #
+  # @api private
+  #
+  # @param env [Puppet::Node::Environment]
   def self.current=(env)
     Thread.current[:environment] = new(env)
   end
 
+
+  # @return [Puppet::Node::Environment] The `*root*` environment.
+  #
+  # This is only used for handling functions that are not attached to a
+  # specific environment.
+  #
+  # @api private
   def self.root
     @root
   end
 
+  # Clear all memoized environments and the 'current' environment
+  #
+  # @api private
   def self.clear
     @seen.clear
     Thread.current[:environment] = nil
   end
 
+  # @!attribute [r] name
+  #   @api public
+  #   @return [Symbol] the human readable environment name that serves as the
+  #     environment identifier
   attr_reader :name
 
-  # Return an environment-specific setting.
+  # Return an environment-specific Puppet setting.
+  #
+  # @api public
+  #
+  # @param param [String, Symbol] The environment setting to look up
+  # @return [Object] The resolved setting value
   def [](param)
     Puppet.settings.value(param, self.name)
   end
 
+  # Instantiate a new environment
+  #
+  # @note {Puppet::Node::Environment.new} is overridden to return memoized
+  #   objects, so this will not be invoked with the normal Ruby initialization
+  #   semantics.
+  #
+  # @param name [Symbol] The environment name
   def initialize(name)
     @name = name
     extend MonitorMixin
   end
 
+  # The current global TypeCollection
+  #
+  # @note The environment is loosely coupled with the {Puppet::Resource::TypeCollection}
+  #   class. While there is a 1:1 relationship between an environment and a
+  #   TypeCollection instance, there is only one TypeCollection instance available
+  #   at any given time. It is stored in the Thread.current collection as
+  #   'known_resource_types'. 'known_resource_types' is accessed as an instance
+  #   method, but is global to all environment variables.
+  #
+  # @api public
+  # @return [Puppet::Resource::TypeCollection] The current global TypeCollection
   def known_resource_types
     # This makes use of short circuit evaluation to get the right thread-safe
     # per environment semantics with an efficient most common cases; we almost
@@ -89,7 +222,8 @@ class Puppet::Node::Environment
     }
   end
 
-  # Yields each modules' plugin directory.
+  # Yields each modules' plugin directory if the plugin directory (modulename/lib)
+  # is present on the filesystem.
   #
   # @yield [String] Yields the plugin directory from each module to the block.
   # @api public
@@ -100,10 +234,22 @@ class Puppet::Node::Environment
     end
   end
 
+  # Locate a module instance by the module name alone.
+  #
+  # @api public
+  #
+  # @param name [String] The module name
+  # @return [Puppet::Module, nil] The module if found, else nil
   def module(name)
     modules.find {|mod| mod.name == name}
   end
 
+  # Locate a module instance by the full forge name (EG authorname/module)
+  #
+  # @api public
+  #
+  # @param forge_name [String] The module name
+  # @return [Puppet::Module, nil] The module if found, else nil
   def module_by_forge_name(forge_name)
     author, modname = forge_name.split('/')
     found_mod = self.module(modname)
@@ -112,17 +258,34 @@ class Puppet::Node::Environment
       nil
   end
 
-  # Cache the modulepath, so that we aren't searching through
-  # all known directories all the time.
+  # @!attribute [r] modulepath
+  #   Return all existent directories in the modulepath for this environment
+  #   @note This value is cached so that the filesystem doesn't have to be
+  #     re-enumerated every time this method is invoked, since that
+  #     enumeration could be a costly operation and this method is called
+  #     frequently. The cache expiry is determined by `Puppet[:filetimeout]`.
+  #   @see Puppet::Util::Cacher.cached_attr
+  #   @api public
+  #   @return [Array<String>] All directories present in the modulepath
   cached_attr(:modulepath, Puppet[:filetimeout]) do
     dirs = self[:modulepath].split(File::PATH_SEPARATOR)
     dirs = ENV["PUPPETLIB"].split(File::PATH_SEPARATOR) + dirs if ENV["PUPPETLIB"]
     validate_dirs(dirs)
   end
 
-  # Return all modules from this environment, in the order they appear
-  # in the modulepath
-  # Cache the list, because it can be expensive to create.
+  # @!attribute [r] modules
+  #   Return all modules for this environment in the order they appear in the
+  #   modulepath.
+  #   @note If multiple modules with the same name are present they will
+  #     both be added, but methods like {#module} and {#module_by_forge_name}
+  #     will return the first matching entry in this list.
+  #   @note This value is cached so that the filesystem doesn't have to be
+  #     re-enumerated every time this method is invoked, since that
+  #     enumeration could be a costly operation and this method is called
+  #     frequently. The cache expiry is determined by `Puppet[:filetimeout]`.
+  #   @see Puppet::Util::Cacher.cached_attr
+  #   @api public
+  #   @return [Array<Puppet::Module>] All modules for this environment
   cached_attr(:modules, Puppet[:filetimeout]) do
     module_references = []
     seen_modules = {}
@@ -140,12 +303,18 @@ class Puppet::Node::Environment
     module_references.collect do |reference|
       begin
         Puppet::Module.new(reference[:name], reference[:path], self)
-      rescue Puppet::Module::Error => e
+      rescue Puppet::Module::Error
         nil
       end
     end.compact
   end
 
+  # Generate a warning if the given directory in a module path entry is named `lib`.
+  #
+  # @api private
+  #
+  # @param path [String] The module directory containing the given directory
+  # @param name [String] The directory name
   def warn_about_mistaken_path(path, name)
     if name == "lib"
       Puppet.debug("Warning: Found directory named 'lib' in module path ('#{path}/lib'); unless " +
@@ -155,6 +324,14 @@ class Puppet::Node::Environment
   end
 
   # Modules broken out by directory in the modulepath
+  #
+  # @note This method _changes_ the current working directory while enumerating
+  #   the modules. This seems rather dangerous.
+  #
+  # @api public
+  #
+  # @return [Hash<String, Array<Puppet::Module>>] A hash whose keys are file
+  #   paths, and whose values is an array of Puppet Modules for that path
   def modules_by_path
     modules_by_path = {}
     modulepath.each do |path|
@@ -170,6 +347,33 @@ class Puppet::Node::Environment
     modules_by_path
   end
 
+  # All module requirements for all modules in the environment modulepath
+  #
+  # @api public
+  #
+  # @comment This has nothing to do with an environment. It seems like it was
+  #   stuffed into the first convenient class that vaguely involved modules.
+  #
+  # @example
+  #   environment.module_requirements
+  #   # => {
+  #   #   'username/amodule' => [
+  #   #     {
+  #   #       'name'    => 'username/moduledep',
+  #   #       'version' => '1.2.3',
+  #   #       'version_requirement' => '>= 1.0.0',
+  #   #     },
+  #   #     {
+  #   #       'name'    => 'username/anotherdep',
+  #   #       'version' => '4.5.6',
+  #   #       'version_requirement' => '>= 3.0.0',
+  #   #     }
+  #   #   ]
+  #   # }
+  #   #
+  #
+  # @return [Hash<String, Array<Hash<String, String>>>] See the method example
+  #   for an explanation of the return value.
   def module_requirements
     deps = {}
     modules.each do |mod|
@@ -191,21 +395,40 @@ class Puppet::Node::Environment
     deps
   end
 
+  # @return [String] The stringified value of the `name` instance variable
+  # @api public
   def to_s
     name.to_s
   end
 
+  # @return [Symbol] The `name` value, cast to a string, then cast to a symbol.
+  #
+  # @api public
+  #
+  # @note the `name` instance variable is a Symbol, but this casts the value
+  #   to a String and then converts it back into a Symbol which will needlessly
+  #   create an object that needs to be garbage collected
   def to_sym
     to_s.to_sym
   end
 
+  # Return only the environment name when serializing.
+  #
   # The only thing we care about when serializing an environment is its
   # identity; everything else is ephemeral and should not be stored or
   # transmitted.
+  #
+  # @api public
   def to_zaml(z)
     self.to_s.to_zaml(z)
   end
 
+  # Validate a list of file paths and return the paths that are directories on the filesystem
+  #
+  # @api private
+  #
+  # @param dirs [Array<String>] The file paths to validate
+  # @return [Array<String>] All file paths that exist and are directories
   def validate_dirs(dirs)
     dirs.collect do |dir|
       File.expand_path(dir)
@@ -216,6 +439,22 @@ class Puppet::Node::Environment
 
   private
 
+  # Reparse the manifests for the given environment
+  #
+  # There are two sources that can be used for the initial parse:
+  #
+  #   1. The value of `Puppet.settings[:code]`: Puppet can take a string from
+  #     its settings and parse that as a manifest. This is used by various
+  #     Puppet applications to read in a manifest and pass it to the
+  #     environment as a side effect. This is attempted first.
+  #   2. The contents of `Puppet.settings[:manifest]`: Puppet will try to load
+  #     the environment manifest. By default this is `$manifestdir/site.pp`
+  #
+  # @note This method will return an empty hostclass if
+  #   `Puppet.settings[:ignoreimport]` is set to true.
+  #
+  # @return [Puppet::Parser::AST::Hostclass] The AST hostclass object
+  #   representing the 'main' hostclass
   def perform_initial_import
     return empty_parse_result if Puppet.settings[:ignoreimport]
 #    parser = Puppet::Parser::Parser.new(self)
@@ -236,9 +475,13 @@ class Puppet::Node::Environment
     raise error
   end
 
+  # Return an empty toplevel hostclass to indicate that no file was loaded
+  #
+  # This is used as the return value of {#perform_initial_import} when
+  # `Puppet.settings[:ignoreimport]` is true.
+  #
+  # @return [Puppet::Parser::AST::Hostclass]
   def empty_parse_result
-    # Return an empty toplevel hostclass to use as the result of
-    # perform_initial_import when no file was actually loaded.
     return Puppet::Parser::AST::Hostclass.new('')
   end