puppet 6.14.0 → 6.15.0

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])
     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/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,11 +64,12 @@ class Puppet::HTTP::Session
     cached = @resolved_services[name]
     return cached if cached
 
-    @resolution_exceptions = []
+    resolution_exceptions = []
+    error_handler = proc { |e| resolution_exceptions << e }
 
     @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, error_handler: error_handler)
       if service
         @resolved_services[name] = service
         Puppet.debug("Resolved service '#{name}' to #{service.url}")
@@ -42,14 +77,18 @@ class Puppet::HTTP::Session
       end
     end
 
-    @resolution_exceptions.each { |e| Puppet.log_exception(e) }
+    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 +97,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/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/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]

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

@@ -4,5 +4,53 @@ require 'puppet/file_bucket/file'
 module Puppet::FileBucketFile
   class Rest < Puppet::Indirector::REST
     desc "This is a REST based mechanism to send/retrieve file to/from the filebucket"
+
+    def head(request)
+      return super unless use_http_client?
+
+      session = Puppet.lookup(:http_session)
+      api = session.route_to(:puppet)
+      api.head_filebucket_file(
+        request.key,
+        environment: request.environment.to_s,
+        bucket_path: request.options[:bucket_path],
+      )
+    rescue Puppet::HTTP::ResponseError => e
+      return nil if e.response.code == 404
+      raise convert_to_http_error(e.response.nethttp)
+    end
+
+    def find(request)
+      return super unless use_http_client?
+
+      session = Puppet.lookup(:http_session)
+      api = session.route_to(:puppet)
+      _, filebucket_file = api.get_filebucket_file(
+        request.key,
+        environment: request.environment.to_s,
+        bucket_path: request.options[:bucket_path],
+        diff_with: request.options[:diff_with],
+        list_all: request.options[:list_all],
+        fromdate: request.options[:fromdate],
+        todate: request.options[:todate],
+      )
+      filebucket_file
+    rescue Puppet::HTTP::ResponseError => e
+      raise convert_to_http_error(e.response.nethttp)
+    end
+
+    def save(request)
+      return super unless use_http_client?
+
+      session = Puppet.lookup(:http_session)
+      api = session.route_to(:puppet)
+      api.put_filebucket_file(
+        request.key,
+        body: request.instance.render,
+        environment: request.environment.to_s,
+      )
+    rescue Puppet::HTTP::ResponseError => e
+      raise convert_to_http_error(e.response.nethttp)
+    end
   end
 end

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

@@ -14,13 +14,14 @@ class Puppet::Indirector::FileMetadata::Rest < Puppet::Indirector::REST
     session = Puppet.lookup(:http_session)
     api = session.route_to(:fileserver, url: url)
 
-    api.get_file_metadata(
+    _, file_metadata = api.get_file_metadata(
       path: URI.unescape(url.path),
       environment: request.environment.to_s,
       links: request.options[:links],
       checksum_type: request.options[:checksum_type],
       source_permissions: request.options[:source_permissions]
     )
+    file_metadata
   rescue Puppet::HTTP::ResponseError => e
     if e.response.code == 404
       return nil unless request.options[:fail_on_404]
@@ -40,7 +41,7 @@ class Puppet::Indirector::FileMetadata::Rest < Puppet::Indirector::REST
     session = Puppet.lookup(:http_session)
     api = session.route_to(:fileserver, url: url)
 
-    api.get_file_metadatas(
+    _, file_metadatas = api.get_file_metadatas(
       path: URI.unescape(url.path),
       environment: request.environment.to_s,
       recurse: request.options[:recurse],
@@ -50,6 +51,7 @@ class Puppet::Indirector::FileMetadata::Rest < Puppet::Indirector::REST
       checksum_type: request.options[:checksum_type],
       source_permissions: request.options[:source_permissions],
     )
+    file_metadatas
   rescue Puppet::HTTP::ResponseError => e
     # since it's search, return empty array instead of nil
     return [] if e.response.code == 404

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

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