puppet 6.14.0-universal-darwin → 6.19.0-universal-darwin

data/lib/puppet/http/service/file_server.rb

@@ -1,14 +1,58 @@
 require 'puppet/file_serving/metadata'
 
+#
+# @api private
+#
+# The FileServer service is used to retrieve file metadata and content
+#
 class Puppet::HTTP::Service::FileServer < Puppet::HTTP::Service
+  # @api private
+  # @return [String] Default API for the FileServer service
   API = '/puppet/v3'.freeze
+
+  # @api private
+  # @return [RegEx] RegEx used to determine if a path contains a leading slash
   PATH_REGEX = /^\//
 
+  #
+  # @api private
+  #
+  # @param [Puppet::HTTP::Client] client
+  # @param [Puppet::HTTP::Session] session
+  # @param [String] server (Puppet[:ca_server]) If an explicit server is given,
+  #   create a service using that server. If server is nil, the default value
+  #   is used to create the service.
+  # @param [Integer] port (Puppet[:ca_port]) If an explicit port is given, create
+  #   a service using that port. If port is nil, the default value is used to
+  #   create the service.
+  #
   def initialize(client, session, server, port)
-    url = build_url(API, server || Puppet[:server], port || Puppet[:masterport])
+    url = build_url(API, server || Puppet[:server], port || Puppet[:serverport])
     super(client, session, url)
   end
 
+  #
+  # @api private
+  #
+  # Submit a GET request to the server to retrieve the metadata for a specified
+  # file
+  #
+  # @param [String] path path to the file to retrieve data from
+  # @param [String] environment the name of the environment we are operating in
+  # @param [Symbol] links Can be one of either `:follow` or `:manage`, defines
+  #   how links are handled.
+  # @param [String] checksum_type The digest algorithm used to verify the file.
+  #   Currently if fips is enabled, this defaults to `sha256`. Otherwise, it
+  #   defaults to `md5`.
+  # @param [Symbol] source_permissions Can be one of `:use`, `:use_when_creating`,
+  #   or `:ignore`. This parameter tells the server if it should include the
+  #   file permissions in the response. If set to `:ignore`, the server will
+  #   return default permissions.
+  #
+  # @return [Array<Puppet::HTTP::Response, Puppet::FileServing::Metadata>] An
+  #   array with the request response and the deserialized metadata for the
+  #   file returned from the server
+  #
   def get_file_metadata(path:, environment:, links: :manage, checksum_type: Puppet[:digest_algorithm], source_permissions: :ignore)
     validate_path(path)
 
@@ -27,9 +71,41 @@ class Puppet::HTTP::Service::FileServer < Puppet::HTTP::Service
 
     process_response(response)
 
-    deserialize(response, Puppet::FileServing::Metadata)
+    [response, deserialize(response, Puppet::FileServing::Metadata)]
   end
 
+  #
+  # @api private
+  #
+  # Submit a GET request to the server to retrieve the metadata for multiple files
+  #
+  # @param [String] path path to the file(s) to retrieve data from
+  # @param [String] environment the name of the environment we are operating in
+  # @param [Symbol] recurse  Can be `:true`, `:false`, or `:remote`. Defines if
+  #   we recursively return the contents of the directory. Used in conjunction
+  #   with `:recurselimit`. See the reference documentation for the file type
+  #   for more details.
+  # @param [Integer] recurselimit When `recurse` is set, `recurselimit` defines
+  #   how far Puppet should descend into subdirectories. `0` is effectively the
+  #   same as `recurse => false`, `1` will return files and directories directly
+  #   inside the defined directory, `2` will return the direct content of the
+  #   directory as well as the contents of the _first_ level of subdirectories.
+  #   The pattern continues for each incremental value. See the reference
+  #   documentation for the file type for more details.
+  # @param [Array<String>] ignore An optional array of files to ignore, ie `['CVS', '.git', '.hg']`
+  # @param [Symbol] links Can be one of either `:follow` or `:manage`, defines
+  #   how links are handled.
+  # @param [String] checksum_type The digest algorithm used to verify the file.
+  #   Currently if fips is enabled, this defaults to `sha256`. Otherwise, it's `md5`.
+  # @param [Symbol] source_permissions Can be one of `:use`, `:use_when_creating`,
+  #   or `:ignore`. This parameter tells the server if it should include the
+  #   file permissions in the report. If set to `:ignore`, the server will return
+  #   default permissions.
+  #
+  # @return [Array<Puppet::HTTP::Response, Array<Puppet::FileServing::Metadata>>]
+  #   An array with the request response and an array of the deserialized
+  #   metadata for each file returned from the server
+  #
   def get_file_metadatas(path: nil, environment:, recurse: :false, recurselimit: nil, ignore: nil, links: :manage, checksum_type: Puppet[:digest_algorithm], source_permissions: :ignore)
     validate_path(path)
 
@@ -51,9 +127,21 @@ class Puppet::HTTP::Service::FileServer < Puppet::HTTP::Service
 
     process_response(response)
 
-    deserialize_multiple(response, Puppet::FileServing::Metadata)
+    [response, deserialize_multiple(response, Puppet::FileServing::Metadata)]
   end
 
+  #
+  # @api private
+  #
+  # Submit a GET request to the server to retrieve content of a file
+  #
+  # @param [String] path path to the file to retrieve data from
+  # @param [String] environment the name of the environment we are operating in
+  #
+  # @yield [Sting] Yields the body of the response returned from the server
+  #
+  # @return [Puppet::HTTP::Response] The request response
+  #
   def get_file_content(path:, environment:, &block)
     validate_path(path)
 
@@ -72,9 +160,22 @@ class Puppet::HTTP::Service::FileServer < Puppet::HTTP::Service
 
     process_response(response)
 
-    nil
+    response
   end
 
+  #
+  # @api private
+  #
+  # Submit a GET request to
+  #
+  # @param [String] path path to the file to retrieve data from
+  # @param [String] environment the name of the environment we are operating in
+  # @param [String] code_id Defines the version of the resource to return
+  #
+  # @yield [String] Yields the body of the response returned
+  #
+  # @return [Puppet::HTTP::Response] The request response
+  #
   def get_static_file_content(path:, environment:, code_id:, &block)
     validate_path(path)
 
@@ -94,7 +195,7 @@ class Puppet::HTTP::Service::FileServer < Puppet::HTTP::Service
 
     process_response(response)
 
-    nil
+    response
   end
 
   private

data/lib/puppet/http/service/puppetserver.rb

@@ -0,0 +1,39 @@
+# The puppetserver service.
+#
+# @api private
+#
+class Puppet::HTTP::Service::Puppetserver < Puppet::HTTP::Service
+  # @param [Puppet::HTTP::Client] client
+  # @param [Puppet::HTTP::Session] session
+  # @param [String] server If an explicit server is given,
+  #   create a service using that server. If server is nil, the default value
+  #   is used to create the service.
+  # @param [Integer] port If an explicit port is given, create
+  #   a service using that port. If port is nil, the default value is used to
+  #   create the service.
+  # @api private
+  #
+  def initialize(client, session, server, port)
+    url = build_url('', server || Puppet[:server], port || Puppet[:serverport])
+    super(client, session, url)
+  end
+
+  # Request the puppetserver's simple status
+  #
+  # @param [Puppet::SSL::SSLContext] ssl_context to use when establishing
+  # the connection.
+  # @return Puppet::HTTP::Response The HTTP response
+  # @api private
+  #
+  def get_simple_status(ssl_context: nil)
+    response = @client.get(
+      with_base_url("/status/v1/simple/master"),
+      headers: add_puppet_headers({}),
+      options: {ssl_context: ssl_context}
+    )
+
+    process_response(response)
+
+    [response, response.body.to_s]
+  end
+end

data/lib/puppet/http/service/report.rb

@@ -1,21 +1,54 @@
+#
+# @api private
+#
+# The Report service is used to submit run reports to the report server
+#
 class Puppet::HTTP::Service::Report < Puppet::HTTP::Service
+
+  # @api private
+  # @return [String] Default API for the report service
   API = '/puppet/v3'.freeze
 
+  #
+  # @api private
+  #
+  # @param [Puppet::HTTP::Client] client
+  # @param [Puppet::HTTP::Session] session
+  # @param [String] server (Puppet[:ca_server]) If an explicit server is given,
+  #   create a service using that server. If server is nil, the default value
+  #   is used to create the service.
+  # @param [Integer] port (Puppet[:ca_port]) If an explicit port is given, create
+  #   a service using that port. If port is nil, the default value is used to
+  #   create the service.
+  #
   def initialize(client, session, server, port)
     url = build_url(API, server || Puppet[:report_server], port || Puppet[:report_port])
     super(client, session, url)
   end
 
+  #
+  # @api private
+  #
+  # Submit a report to the report server
+  #
+  # @param [String] name the name of the report being submitted
+  # @param [Puppet::Transaction::Report] report run report to be submitted
+  # @param [String] environment name of the agent environment
+  #
+  # @return [Puppet::HTTP::Response] response returned by the server
+  #
   def put_report(name, report, environment:)
     formatter = Puppet::Network::FormatHandler.format_for(Puppet[:preferred_serialization_format])
-    headers = add_puppet_headers('Accept' => get_mime_types(Puppet::Transaction::Report).join(', '))
+    headers = add_puppet_headers(
+      'Accept' => get_mime_types(Puppet::Transaction::Report).join(', '),
+      'Content-Type' => formatter.mime
+    )
 
     response = @client.put(
       with_base_url("/report/#{name}"),
+      serialize(formatter, report),
       headers: headers,
       params: { environment: environment },
-      content_type: formatter.mime,
-      body: serialize(formatter, report)
     )
 
     # override parent's process_response handling

data/lib/puppet/http/session.rb

@@ -1,3 +1,8 @@
+#
+# @api private
+#
+# The session is the mechanism by which services may be connected to and accessed.
+#
 class Puppet::HTTP::Session
   # capabilities for a site
   CAP_LOCALES = 'locales'.freeze
@@ -9,14 +14,43 @@ class Puppet::HTTP::Session
   # puppet version where JSON was enabled by default
   SUPPORTED_JSON_DEFAULT = Gem::Version.new("5.0.0")
 
+  #
+  # @api private
+  #
+  # Create a new HTTP session. The session is the mechanism by which services
+  # may be connected to and accessed.
+  #
+  # @param [Puppet::HTTP::Client] client the container for this session
+  # @param [Array<Puppet::HTTP::Resolver>] resolvers array of resolver strategies
+  #   to implement.
+  #
   def initialize(client, resolvers)
     @client = client
     @resolvers = resolvers
     @resolved_services = {}
-    @resolution_exceptions = []
     @server_versions = {}
   end
 
+  #
+  # @api private
+  #
+  # If an explicit server and port are specified on the command line or
+  # configuration file, this method always returns a Service with that host and
+  # port. Otherwise, we walk the list of resolvers in priority order:
+  #     - DNS SRV
+  #     - Server List
+  #     - Puppet server/port settings
+  # If a given resolver fails to connect, it tries the next available resolver
+  # until a successful connection is found and returned. The successful service
+  # is cached and returned if `route_to` is called again.
+  #
+  # @param [Symbol] name the service to resolve
+  # @param [URI] url (nil) optional explicit url to use, if it is already known
+  # @param [Puppet::SSL::SSLContext] ssl_context ssl_context ssl context to be
+  #   used for connections
+  #
+  # @return [Puppet::HTTP::Service] the resolved service
+  #
   def route_to(name, url: nil, ssl_context: nil)
     raise ArgumentError, "Unknown service #{name}" unless Puppet::HTTP::Service.valid_name?(name)
 
@@ -30,26 +64,32 @@ class Puppet::HTTP::Session
     cached = @resolved_services[name]
     return cached if cached
 
-    @resolution_exceptions = []
+    canceled = false
+    canceled_handler  = lambda { |cancel| canceled = cancel }
 
     @resolvers.each do |resolver|
       Puppet.debug("Resolving service '#{name}' using #{resolver.class}")
-      service = resolver.resolve(self, name, ssl_context: ssl_context)
+      service = resolver.resolve(self, name, ssl_context: ssl_context, canceled_handler: canceled_handler)
       if service
         @resolved_services[name] = service
         Puppet.debug("Resolved service '#{name}' to #{service.url}")
         return service
+      elsif canceled
+        break
       end
     end
 
-    @resolution_exceptions.each { |e| Puppet.log_exception(e) }
     raise Puppet::HTTP::RouteError, "No more routes to #{name}"
   end
 
-  def add_exception(exception)
-    @resolution_exceptions << exception
-  end
-
+  #
+  # @api private
+  #
+  # Collect per-site server versions. This will allow us to modify future
+  # requests based on the version of puppetserver we are talking to.
+  #
+  # @param [Puppet::HTTP::Response] response the request response containing headers
+  #
   def process_response(response)
     version = response[Puppet::HTTP::HEADER_PUPPET_VERSION]
     if version
@@ -58,6 +98,18 @@ class Puppet::HTTP::Session
     end
   end
 
+  #
+  # @api private
+  #
+  # Determine if a session supports a capability. Depending on the server version
+  # we are talking to, we know certain features are available or not. These
+  # specifications are defined here so we can modify our requests appropriately.
+  #
+  # @param [Symbol] name name of the service to check
+  # @param [String] capability the capability, ie `locales` or `json`
+  #
+  # @return [Boolean]
+  #
   def supports?(name, capability)
     raise ArgumentError, "Unknown service #{name}" unless Puppet::HTTP::Service.valid_name?(name)
 

data/lib/puppet/indirector.rb

@@ -46,7 +46,7 @@ module Puppet::Indirector
 
     # instantiate the actual Terminus for that type and this name (:ldap, w/ args :node)
     # & hook the instantiated Terminus into this class (Node: @indirection = terminus)
-    @indirection = Puppet::Indirector::Indirection.new(self, indirection, options)
+    @indirection = Puppet::Indirector::Indirection.new(self, indirection, **options)
   end
 
   module ClassMethods

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

@@ -75,7 +75,7 @@ class Puppet::Resource::Catalog::Compiler < Puppet::Indirector::Code
 
   # Is our compiler part of a network, or are we just local?
   def networked?
-    Puppet.run_mode.master?
+    Puppet.run_mode.server?
   end
 
   private

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

@@ -15,7 +15,7 @@ class Puppet::Resource::Catalog::Rest < Puppet::Indirector::REST
 
     session = Puppet.lookup(:http_session)
     api = session.route_to(:puppet)
-    api.post_catalog(
+    _, catalog = api.post_catalog(
       request.key,
       facts: request.options[:facts_for_catalog],
       environment: request.environment.to_s,
@@ -25,6 +25,7 @@ class Puppet::Resource::Catalog::Rest < Puppet::Indirector::REST
       static_catalog: request.options[:static_catalog],
       checksum_type: checksum_type
     )
+    catalog
   rescue Puppet::HTTP::ResponseError => e
     if e.response.code == 404
       return nil unless request.options[:fail_on_404]

data/lib/puppet/indirector/exec.rb

@@ -22,7 +22,7 @@ class Puppet::Indirector::Exec < Puppet::Indirector::Terminus
     end
 
     if output =~ /\A\s*\Z/ # all whitespace
-      Puppet.debug "Empty response for #{name} from #{self.name} terminus"
+      Puppet.debug { "Empty response for #{name} from #{self.name} terminus" }
       return nil
     else
       return output

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

@@ -55,7 +55,7 @@ class Puppet::Node::Facts::Facter < Puppet::Indirector::Code
       if Puppet::Util::Log.sendlevel?(:info)
         Puppet.info _("Loading facts")
         Dir.glob("#{dir}/*.rb").each do |file|
-          Puppet.debug "Loading facts from #{file}"
+          Puppet.debug { "Loading facts from #{file}" }
         end
       end
 
@@ -71,7 +71,7 @@ class Puppet::Node::Facts::Facter < Puppet::Indirector::Code
     request.environment.modules.each do |m|
       if m.has_external_facts?
         dir = m.plugin_fact_directory
-        Puppet.debug "Loading external facts from #{dir}"
+        Puppet.debug { "Loading external facts from #{dir}" }
         dirs << dir
       end
     end
@@ -79,7 +79,7 @@ class Puppet::Node::Facts::Facter < Puppet::Indirector::Code
     # Add system external fact directory if it exists
     if FileTest.directory?(Puppet[:pluginfactdest])
       dir = Puppet[:pluginfactdest]
-      Puppet.debug "Loading external facts from #{dir}"
+      Puppet.debug { "Loading external facts from #{dir}" }
       dirs << dir
     end
 

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

@@ -9,10 +9,11 @@ class Puppet::Node::Facts::Rest < Puppet::Indirector::REST
 
     session = Puppet.lookup(:http_session)
     api = session.route_to(:puppet)
-    api.get_facts(
+    _, facts = api.get_facts(
       request.key,
       environment: request.environment.to_s
     )
+    facts
   rescue Puppet::HTTP::ResponseError => e
     if e.response.code == 404
       return nil unless request.options[:fail_on_404]