puppet 6.14.0-universal-darwin → 6.15.0-universal-darwin

data/lib/puppet/http/retry_after_handler.rb

@@ -1,12 +1,37 @@
 require 'date'
 require 'time'
 
+#
+# @api private
+#
+# Parse information relating to responses containing a Retry-After headers
+#
 class Puppet::HTTP::RetryAfterHandler
+  #
+  # @api private
+  #
+  # Create a handler to allow the system to sleep between HTTP requests
+  #
+  # @param [Integer] retry_limit number of retries allowed
+  # @param [Integer] max_sleep maximum sleep time allowed
+  #
   def initialize(retry_limit, max_sleep)
     @retry_limit = retry_limit
     @max_sleep = max_sleep
   end
 
+  #
+  # @api private
+  #
+  # Does the response from the server tell us to wait until we attempt the next
+  # retry?
+  #
+  # @param [Net::HTTP] request
+  # @param [Puppet::HTTP::Response] response
+  #
+  # @return [Boolean] Return true if the response code is 429 or 503, return
+  #   false otherwise
+  #
   def retry_after?(request, response)
     case response.code
     when 429, 503
@@ -16,6 +41,20 @@ class Puppet::HTTP::RetryAfterHandler
     end
   end
 
+  #
+  # @api private
+  #
+  # The amount of time to wait before attempting a retry
+  #
+  # @param [Net::HTTP] request
+  # @param [Puppet::HTTP::Response] response
+  # @param [Integer] retries number of retries attempted so far
+  #
+  # @return [Integer] the amount of time to wait
+  #
+  # @raise [Puppet::HTTP::TooManyRetryAfters] raise if we have hit our retry
+  #   limit
+  #
   def retry_after_interval(request, response, retries)
     raise Puppet::HTTP::TooManyRetryAfters.new(request.uri) if retries >= @retry_limit
 

data/lib/puppet/http/service.rb

@@ -1,9 +1,40 @@
+#
+# @api private
+#
+# Represents a puppet web service
+#
 class Puppet::HTTP::Service
+  # @api private
+  # @return [URI] the url associated with this service
   attr_reader :url
 
+  # @api private
+  # @return [Array<Symbol>] available services
   SERVICE_NAMES = [:ca, :fileserver, :puppet, :report].freeze
+
+  # @api private
+  # @return [Array<Symbol>] format types that are unsupported
   EXCLUDED_FORMATS = [:yaml, :b64_zlib_yaml, :dot].freeze
 
+  #
+  # @api private
+  #
+  # Create a new web service, which contains the URL used to connect to the
+  # service. The four services implemented are `:ca`, `:fileserver`, `:puppet`,
+  # and `:report`.
+  #
+  # The `:ca` and `:report` services handle certs and reports, respectively. The
+  # `:fileserver` service handles puppet file metadata and content requests. And
+  # the default service, `:puppet`, handles nodes, facts, and catalogs.
+  #
+  # @param [Puppet::HTTP::Client] client the owner of the session
+  # @param [Puppet::HTTP::Session] session the owner of the service
+  # @param [Symbol] name the type of service to create
+  # @param [<Type>] server optional, the server to connect to
+  # @param [<Type>] port optional, the port to connect to
+  #
+  # @return [Puppet::HTTP::Service] an instance of the service type requested
+  #
   def self.create_service(client, session, name, server = nil, port = nil)
     case name
     when :ca
@@ -19,24 +50,59 @@ class Puppet::HTTP::Service
     end
   end
 
+  #
+  # @api private
+  #
+  # Check if the service named is included in the list of available services.
+  #
+  # @param [Symbol] name
+  #
+  # @return [Boolean]
+  #
   def self.valid_name?(name)
     SERVICE_NAMES.include?(name)
   end
 
+  #
+  # @api private
+  #
+  # Create a new service
+  #
+  # @param [Puppet::HTTP::Client] client
+  # @param [Puppet::HTTP::Session] session
+  # @param [URI] url The url to connect to
+  #
   def initialize(client, session, url)
     @client = client
     @session = session
     @url = url
   end
 
+  #
+  # @api private
+  #
+  # Return the url with the given path encoded and appended
+  #
+  # @param [String] path the string to append to the base url
+  #
+  # @return [URI] the URI object containing the encoded path
+  #
   def with_base_url(path)
     u = @url.dup
     u.path += Puppet::Util.uri_encode(path)
     u
   end
 
+  #
+  # @api private
+  #
+  # Open a connection using the given ssl context
+  #
+  # @param [Puppet::SSL::SSLContext] ssl_context (nil) optional ssl context to
+  #   connect with
+  #
   def connect(ssl_context: nil)
-    @client.connect(@url, ssl_context: ssl_context)
+    @client.connect(@url, options: {ssl_context: ssl_context})
   end
 
   protected

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

@@ -1,24 +1,70 @@
+#
+# @api private
+#
+# The Ca service is used to handle certificate requests
+#
 class Puppet::HTTP::Service::Ca < Puppet::HTTP::Service
+  # @api private
+  # @return [Hash] default headers for the ca service
   HEADERS = { 'Accept' => 'text/plain' }.freeze
+
+  # @api private
+  # @return [String] default API for the ca service
   API = '/puppet-ca/v1'.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[:ca_server], port || Puppet[:ca_port])
     super(client, session, url)
   end
 
+  #
+  # @api private
+  #
+  # Submit a GET request to retrieve the named certificate from the server
+  #
+  # @param [String] name name of the certificate to request
+  # @param [Puppet::SSL::SSLContext] ssl_context
+  #
+  # @return [Array<Puppet::HTTP::Response, String>] An array containing the
+  #   request response and the stringified body of the request response
+  #
   def get_certificate(name, ssl_context: nil)
     response = @client.get(
       with_base_url("/certificate/#{name}"),
       headers: add_puppet_headers(HEADERS),
-      ssl_context: ssl_context
+      options: {ssl_context: ssl_context}
     )
 
     process_response(response)
 
-    response.body.to_s
+    [response, response.body.to_s]
   end
 
+  #
+  # @api private
+  #
+  # Submit a GET request to retrieve the certificate revocation list from the
+  #   server
+  #
+  # @param [Time] if_modified_since If not nil, only download the CRL if it has
+  #   been modified since the specified time.
+  # @param [Puppet::SSL::SSLContext] ssl_context
+  #
+  # @return [Array<Puppet::HTTP::Response, String>] An array containing the
+  #   request response and the stringified body of the request response
+  #
   def get_certificate_revocation_list(if_modified_since: nil, ssl_context: nil)
     headers = add_puppet_headers(HEADERS)
     headers['If-Modified-Since'] = if_modified_since.httpdate if if_modified_since
@@ -26,25 +72,41 @@ class Puppet::HTTP::Service::Ca < Puppet::HTTP::Service
     response = @client.get(
       with_base_url("/certificate_revocation_list/ca"),
       headers: headers,
-      ssl_context: ssl_context
+      options: {ssl_context: ssl_context}
     )
 
     process_response(response)
 
-    response.body.to_s
+    [response, response.body.to_s]
   end
 
+  #
+  # @api private
+  #
+  # Submit a PUT request to send a certificate request to the server
+  #
+  # @param [String] name The name of the certificate request being sent
+  # @param [OpenSSL::X509::Request] csr Certificate request to send to the
+  #   server
+  # @param [Puppet::SSL::SSLContext] ssl_context
+  #
+  # @return [Puppet::HTTP::Response] The request response
+  #
   def put_certificate_request(name, csr, ssl_context: nil)
+    headers = add_puppet_headers(HEADERS)
+    headers['Content-Type'] = 'text/plain'
+
     response = @client.put(
       with_base_url("/certificate_request/#{name}"),
-      headers: add_puppet_headers(HEADERS),
-      content_type: 'text/plain',
-      body: csr.to_pem,
-      ssl_context: ssl_context
+      csr.to_pem,
+      headers: headers,
+      options: {
+        ssl_context: ssl_context
+      }
     )
 
     process_response(response)
 
-    response.body.to_s
+    response
   end
 end

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

@@ -1,11 +1,46 @@
+#
+# @api private
+#
+# The Compiler service is used to submit and retrieve data from the
+# puppetserver.
+#
 class Puppet::HTTP::Service::Compiler < Puppet::HTTP::Service
+  # @api private
+  # @return [String] Default API for the Compiler 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[:server], port || Puppet[:masterport])
     super(client, session, url)
   end
 
+  #
+  # @api private
+  #
+  # Submit a GET request to retrieve a node from the server
+  #
+  # @param [String] name The name of the node being requested
+  # @param [String] environment The name of the environment we are operating in
+  # @param [String] configured_environment Optional, the name of the configured
+  #   environment. If unset, `environment` is used.
+  # @param [String] transaction_uuid An agent generated transaction uuid, used
+  #   for connecting catalogs and reports.
+  #
+  # @return [Array<Puppet::HTTP::Response, Puppet::Node>] An array containing
+  #   the request response and the deserialized requested node
+  #
   def get_node(name, environment:, configured_environment: nil, transaction_uuid: nil)
     headers = add_puppet_headers('Accept' => get_mime_types(Puppet::Node).join(', '))
 
@@ -21,9 +56,35 @@ class Puppet::HTTP::Service::Compiler < Puppet::HTTP::Service
 
     process_response(response)
 
-    deserialize(response, Puppet::Node)
+    [response, deserialize(response, Puppet::Node)]
   end
 
+  #
+  # @api private
+  #
+  # Submit a POST request to submit a catalog to the server
+  #
+  # @param [String] name The name of the catalog to be submitted
+  # @param [Puppet::Node::Facts] facts Facts for this catalog
+  # @param [String] environment The name of the environment we are operating in
+  # @param [String] configured_environment Optional, the name of the configured
+  #   environment. If unset, `environment` is used.
+  # @param [String] transaction_uuid An agent generated transaction uuid, used
+  #   for connecting catalogs and reports.
+  # @param [String] job_uuid A unique job identifier defined when the orchestrator
+  #   starts a puppet run via pxp-agent. This is used to correlate catalogs and
+  #   reports with the orchestrator job.
+  # @param [Boolean] static_catalog Indicates if the file metadata(s) are inlined
+  #   in the catalog. This informs the agent if it needs to make a second request
+  #   to retrieve metadata in addition to the initial catalog request.
+  # @param [Array<String>] checksum_type An array of accepted checksum type.
+  #   Currently defaults to `["md5", "sha256", "sha384", "sha512", "sha224"]`,
+  #   or `["sha256", "sha384", "sha512", "sha224"]` if fips is enabled.
+  #
+  # @return [Array<Puppet::HTTP::Response, Puppet::Resource::Catalog>] An array
+  #   containing the request response and the deserialized catalog returned by
+  #   the server
+  #
   def post_catalog(name, facts:, environment:, configured_environment: nil, transaction_uuid: nil, job_uuid: nil, static_catalog: true, checksum_type: Puppet[:supported_checksum_types])
     if Puppet[:preferred_serialization_format] == "pson"
       formatter = Puppet::Network::FormatHandler.format_for(:pson)
@@ -50,22 +111,36 @@ class Puppet::HTTP::Service::Compiler < Puppet::HTTP::Service
       "#{key}=#{Puppet::Util.uri_query_encode(value.to_s)}"
     end.join("&")
 
-    headers = add_puppet_headers('Accept' => get_mime_types(Puppet::Resource::Catalog).join(', '))
+    headers = add_puppet_headers(
+      'Accept' => get_mime_types(Puppet::Resource::Catalog).join(', '),
+      'Content-Type' => 'application/x-www-form-urlencoded'
+    )
 
     response = @client.post(
       with_base_url("/catalog/#{name}"),
+      body,
       headers: headers,
       # for legacy reasons we always send environment as a query parameter too
       params: { environment: environment },
-      content_type: 'application/x-www-form-urlencoded',
-      body: body,
     )
 
     process_response(response)
 
-    deserialize(response, Puppet::Resource::Catalog)
+    [response, deserialize(response, Puppet::Resource::Catalog)]
   end
 
+  #
+  # @api private
+  #
+  # Submit a GET request to retrieve the facts for the named node
+  #
+  # @param [String] name Name of the node to retrieve facts for
+  # @param [String] environment Name of the environment we are operating in
+  #
+  # @return [Array<Puppet::HTTP::Response, Puppet::Node::Facts>] An array
+  #   containing the request response and the deserialized facts for the
+  #   specified node
+  #
   def get_facts(name, environment:)
     headers = add_puppet_headers('Accept' => get_mime_types(Puppet::Node::Facts).join(', '))
 
@@ -77,27 +152,50 @@ class Puppet::HTTP::Service::Compiler < Puppet::HTTP::Service
 
     process_response(response)
 
-    deserialize(response, Puppet::Node::Facts)
+    [response, deserialize(response, Puppet::Node::Facts)]
   end
 
+  #
+  # @api private
+  #
+  # Submits a PUT request to submit facts for the node to the server
+  #
+  # @param [String] name Name of the node we are submitting facts for
+  # @param [String] environment Name of the environment we are operating in
+  # @param [Puppet::Node::Facts] facts Facts for the named node
+  #
+  # @return [Puppet::HTTP::Response] The request response
+  #
   def put_facts(name, environment:, facts:)
     formatter = Puppet::Network::FormatHandler.format_for(Puppet[:preferred_serialization_format])
 
-    headers = add_puppet_headers('Accept' => get_mime_types(Puppet::Node::Facts).join(', '))
+    headers = add_puppet_headers(
+      'Accept' => get_mime_types(Puppet::Node::Facts).join(', '),
+      'Content-Type' => formatter.mime
+    )
 
     response = @client.put(
       with_base_url("/facts/#{name}"),
+      serialize(formatter, facts),
       headers: headers,
       params: { environment: environment },
-      content_type: formatter.mime,
-      body: serialize(formatter, facts),
     )
 
     process_response(response)
 
-    true
+    response
   end
 
+  #
+  # @api private
+  #
+  # Submit a GET request to find the status of a compiler
+  #
+  # @param [String] name The name of the node that a status being requested for
+  #
+  # @return [Array<Puppet::HTTP::Response, Puppet::Status>] An array containing
+  #   the request response and the deserialized status returned from the server
+  #
   def get_status(name)
     headers = add_puppet_headers('Accept' => get_mime_types(Puppet::Status).join(', '))
 
@@ -112,6 +210,110 @@ class Puppet::HTTP::Service::Compiler < Puppet::HTTP::Service
 
     process_response(response)
 
-    deserialize(response, Puppet::Status)
+    [response, deserialize(response, Puppet::Status)]
+  end
+
+  #
+  # @api private
+  #
+  # Submit a GET request to retrieve a file stored with filebucket
+  #
+  # @param [String] path The request path, formatted by Puppet::FileBucket::Dipper
+  # @param [String] environment Name of the environment we are operating in.
+  #   This should not impact filebucket at all, but is included to be consistent
+  #   with legacy code.
+  # @param [String] bucket_path
+  # @param [String] diff_with a checksum to diff against if we are comparing
+  #   files that are both stored in the bucket
+  # @param [String] list_all
+  # @param [String] fromdate
+  # @param [String] todate
+  #
+  # @return [Array<Puppet::HTTP::Response, Puppet::FileBucket::File>] An array
+  #   containing the request response and the deserialized file returned from
+  #   the server.
+  #
+  def get_filebucket_file(path, environment:, bucket_path: nil, diff_with: nil, list_all: nil, fromdate: nil, todate: nil)
+    headers = add_puppet_headers('Accept' => 'application/octet-stream')
+
+    response = @client.get(
+      with_base_url("/file_bucket_file/#{path}"),
+      headers: headers,
+      params: {
+        environment: environment,
+        bucket_path: bucket_path,
+        diff_with: diff_with,
+        list_all: list_all,
+        fromdate: fromdate,
+        todate: todate
+      }
+    )
+
+    process_response(response)
+
+    [response, deserialize(response, Puppet::FileBucket::File)]
+  end
+
+  #
+  # @api private
+  #
+  # Submit a PUT request to store a file with filebucket
+  #
+  # @param [String] path The request path, formatted by Puppet::FileBucket::Dipper
+  # @param [String] body The contents of the file to be backed
+  # @param [String] environment Name of the environment we are operating in.
+  #   This should not impact filebucket at all, but is included to be consistent
+  #   with legacy code.
+  #
+  # @return [Puppet::HTTP::Response] The response request
+  #
+  def put_filebucket_file(path, body:, environment:)
+    headers = add_puppet_headers({
+      'Accept' => 'application/octet-stream',
+      'Content-Type' => 'application/octet-stream'
+      })
+
+    response = @client.put(
+      with_base_url("/file_bucket_file/#{path}"),
+      body,
+      headers: headers,
+      params: {
+        environment: environment
+      }
+    )
+
+    process_response(response)
+
+    response
+  end
+
+  #
+  # @api private
+  #
+  # Submit a HEAD request to check the status of a file stored with filebucket
+  #
+  # @param [String] path The request path, formatted by Puppet::FileBucket::Dipper
+  # @param [String] environment Name of the environment we are operating in.
+  #   This should not impact filebucket at all, but is included to be consistent
+  #   with legacy code.
+  # @param [String] bucket_path
+  #
+  # @return [Puppet::HTTP::Response] The request response
+  #
+  def head_filebucket_file(path, environment:, bucket_path: nil)
+    headers = add_puppet_headers('Accept' => 'application/octet-stream')
+
+    response = @client.head(
+      with_base_url("/file_bucket_file/#{path}"),
+      headers: headers,
+      params: {
+        environment: environment,
+        bucket_path: bucket_path
+      }
+    )
+
+    process_response(response)
+
+    response
   end
 end