puppet 6.16.0-universal-darwin → 7.0.0-universal-darwin

data/lib/puppet/http/retry_after_handler.rb

@@ -1,28 +1,20 @@
 require 'date'
 require 'time'
 
-#
-# @api private
-#
 # Parse information relating to responses containing a Retry-After headers
 #
+# @api private
 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?
   #
@@ -32,6 +24,7 @@ class Puppet::HTTP::RetryAfterHandler
   # @return [Boolean] Return true if the response code is 429 or 503, return
   #   false otherwise
   #
+  # @api private
   def retry_after?(request, response)
     case response.code
     when 429, 503
@@ -41,9 +34,6 @@ class Puppet::HTTP::RetryAfterHandler
     end
   end
 
-  #
-  # @api private
-  #
   # The amount of time to wait before attempting a retry
   #
   # @param [Net::HTTP] request
@@ -55,6 +45,7 @@ class Puppet::HTTP::RetryAfterHandler
   # @raise [Puppet::HTTP::TooManyRetryAfters] raise if we have hit our retry
   #   limit
   #
+  # @api private
   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,24 +1,17 @@
+# Represents an abstract Puppet web service.
 #
-# @api private
-#
-# Represents a puppet web service
-#
+# @abstract Subclass and implement methods for the service's REST APIs.
+# @api public
 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
+  SERVICE_NAMES = [:ca, :fileserver, :puppet, :puppetserver, :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`.
@@ -35,6 +28,7 @@ class Puppet::HTTP::Service
   #
   # @return [Puppet::HTTP::Service] an instance of the service type requested
   #
+  # @api private
   def self.create_service(client, session, name, server = nil, port = nil)
     case name
     when :ca
@@ -43,6 +37,8 @@ class Puppet::HTTP::Service
       Puppet::HTTP::Service::FileServer.new(client, session, server, port)
     when :puppet
       ::Puppet::HTTP::Service::Compiler.new(client, session, server, port)
+    when :puppetserver
+      ::Puppet::HTTP::Service::Puppetserver.new(client, session, server, port)
     when :report
       Puppet::HTTP::Service::Report.new(client, session, server, port)
     else
@@ -50,57 +46,49 @@ 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]
   #
+  # @api private
   def self.valid_name?(name)
     SERVICE_NAMES.include?(name)
   end
 
-  #
-  # @api private
-  #
-  # Create a new service
+  # Create a new service. Services should be created by calling `Puppet::HTTP::Session#route_to`.
   #
   # @param [Puppet::HTTP::Client] client
   # @param [Puppet::HTTP::Session] session
   # @param [URI] url The url to connect to
   #
+  # @api private
   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
   #
+  # @api public
   def with_base_url(path)
     u = @url.dup
     u.path += Puppet::Util.uri_encode(path)
     u
   end
 
+  # Open a connection using the given ssl context.
   #
-  # @api private
-  #
-  # Open a connection using the given ssl context
-  #
-  # @param [Puppet::SSL::SSLContext] ssl_context (nil) optional ssl context to
-  #   connect with
+  # @param [Puppet::SSL::SSLContext] ssl_context An optional ssl context to connect with
+  # @return [void]
   #
+  # @api public
   def connect(ssl_context: nil)
     @client.connect(@url, options: {ssl_context: ssl_context})
   end

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

@@ -1,26 +1,21 @@
+# The CA service is used to handle certificate related REST requests.
 #
-# @api private
-#
-# The Ca service is used to handle certificate requests
-#
+# @api public
 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
+  # Use `Puppet::HTTP::Session.route_to(:ca)` to create or get an instance of this class.
   #
   # @param [Puppet::HTTP::Client] client
   # @param [Puppet::HTTP::Session] session
-  # @param [String] server (Puppet[:ca_server]) If an explicit server is given,
+  # @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
+  # @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.
   #
@@ -29,10 +24,7 @@ class Puppet::HTTP::Service::Ca < Puppet::HTTP::Service
     super(client, session, url)
   end
 
-  #
-  # @api private
-  #
-  # Submit a GET request to retrieve the named certificate from the server
+  # 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
@@ -40,6 +32,7 @@ class Puppet::HTTP::Service::Ca < Puppet::HTTP::Service
   # @return [Array<Puppet::HTTP::Response, String>] An array containing the
   #   request response and the stringified body of the request response
   #
+  # @api public
   def get_certificate(name, ssl_context: nil)
     response = @client.get(
       with_base_url("/certificate/#{name}"),
@@ -52,11 +45,8 @@ class Puppet::HTTP::Service::Ca < Puppet::HTTP::Service
     [response, response.body.to_s]
   end
 
-  #
-  # @api private
-  #
   # Submit a GET request to retrieve the certificate revocation list from the
-  #   server
+  #   server.
   #
   # @param [Time] if_modified_since If not nil, only download the CRL if it has
   #   been modified since the specified time.
@@ -65,6 +55,7 @@ class Puppet::HTTP::Service::Ca < Puppet::HTTP::Service
   # @return [Array<Puppet::HTTP::Response, String>] An array containing the
   #   request response and the stringified body of the request response
   #
+  # @api public
   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
@@ -80,10 +71,7 @@ class Puppet::HTTP::Service::Ca < Puppet::HTTP::Service
     [response, response.body.to_s]
   end
 
-  #
-  # @api private
-  #
-  # Submit a PUT request to send a certificate request to the server
+  # 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
@@ -92,6 +80,7 @@ class Puppet::HTTP::Service::Ca < Puppet::HTTP::Service
   #
   # @return [Puppet::HTTP::Response] The request response
   #
+  # @api public
   def put_certificate_request(name, csr, ssl_context: nil)
     headers = add_puppet_headers(HEADERS)
     headers['Content-Type'] = 'text/plain'

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

@@ -1,35 +1,28 @@
-#
-# @api private
-#
 # The Compiler service is used to submit and retrieve data from the
 # puppetserver.
 #
+# @api public
 class Puppet::HTTP::Service::Compiler < Puppet::HTTP::Service
-  # @api private
   # @return [String] Default API for the Compiler service
   API = '/puppet/v3'.freeze
 
-  #
-  # @api private
+  # Use `Puppet::HTTP::Session.route_to(:puppet)` to create or get an instance of this class.
   #
   # @param [Puppet::HTTP::Client] client
   # @param [Puppet::HTTP::Session] session
-  # @param [String] server (Puppet[:ca_server]) If an explicit server is given,
+  # @param [String] server (`Puppet[: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
+  # @param [Integer] port (`Puppet[:masterport]`) 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 retrieve a node from the server
+  # 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
@@ -41,6 +34,7 @@ class Puppet::HTTP::Service::Compiler < Puppet::HTTP::Service
   # @return [Array<Puppet::HTTP::Response, Puppet::Node>] An array containing
   #   the request response and the deserialized requested node
   #
+  # @api public
   def get_node(name, environment:, configured_environment: nil, transaction_uuid: nil)
     headers = add_puppet_headers('Accept' => get_mime_types(Puppet::Node).join(', '))
 
@@ -59,10 +53,7 @@ class Puppet::HTTP::Service::Compiler < Puppet::HTTP::Service
     [response, deserialize(response, Puppet::Node)]
   end
 
-  #
-  # @api private
-  #
-  # Submit a POST request to submit a catalog to the server
+  # 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
@@ -77,14 +68,13 @@ class Puppet::HTTP::Service::Compiler < Puppet::HTTP::Service
   # @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.
+  # @param [Array<String>] checksum_type An array of accepted checksum types.
   #
   # @return [Array<Puppet::HTTP::Response, Puppet::Resource::Catalog>] An array
   #   containing the request response and the deserialized catalog returned by
   #   the server
   #
+  # @api public
   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)
@@ -129,10 +119,7 @@ class Puppet::HTTP::Service::Compiler < Puppet::HTTP::Service
     [response, deserialize(response, Puppet::Resource::Catalog)]
   end
 
-  #
-  # @api private
-  #
-  # Submit a GET request to retrieve the facts for the named node
+  # 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
@@ -141,6 +128,7 @@ class Puppet::HTTP::Service::Compiler < Puppet::HTTP::Service
   #   containing the request response and the deserialized facts for the
   #   specified node
   #
+  # @api public
   def get_facts(name, environment:)
     headers = add_puppet_headers('Accept' => get_mime_types(Puppet::Node::Facts).join(', '))
 
@@ -155,10 +143,7 @@ class Puppet::HTTP::Service::Compiler < Puppet::HTTP::Service
     [response, deserialize(response, Puppet::Node::Facts)]
   end
 
-  #
-  # @api private
-  #
-  # Submits a PUT request to submit facts for the node to the server
+  # 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
@@ -166,6 +151,7 @@ class Puppet::HTTP::Service::Compiler < Puppet::HTTP::Service
   #
   # @return [Puppet::HTTP::Response] The request response
   #
+  # @api public
   def put_facts(name, environment:, facts:)
     formatter = Puppet::Network::FormatHandler.format_for(Puppet[:preferred_serialization_format])
 
@@ -186,39 +172,9 @@ class Puppet::HTTP::Service::Compiler < Puppet::HTTP::Service
     response
   end
 
+  # Submit a GET request to retrieve a file stored with filebucket.
   #
-  # @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(', '))
-
-    response = @client.get(
-      with_base_url("/status/#{name}"),
-      headers: headers,
-      params: {
-        # environment is required, but meaningless, default to production
-        environment: 'production'
-      },
-    )
-
-    process_response(response)
-
-    [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] 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.
@@ -233,6 +189,7 @@ class Puppet::HTTP::Service::Compiler < Puppet::HTTP::Service
   #   containing the request response and the deserialized file returned from
   #   the server.
   #
+  # @api public
   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')
 
@@ -254,12 +211,9 @@ class Puppet::HTTP::Service::Compiler < Puppet::HTTP::Service
     [response, deserialize(response, Puppet::FileBucket::File)]
   end
 
+  # Submit a PUT request to store a file with filebucket.
   #
-  # @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] 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
@@ -267,6 +221,7 @@ class Puppet::HTTP::Service::Compiler < Puppet::HTTP::Service
   #
   # @return [Puppet::HTTP::Response] The response request
   #
+  # @api public
   def put_filebucket_file(path, body:, environment:)
     headers = add_puppet_headers({
       'Accept' => 'application/octet-stream',
@@ -287,12 +242,9 @@ class Puppet::HTTP::Service::Compiler < Puppet::HTTP::Service
     response
   end
 
+  # Submit a HEAD request to check the status of a file stored with filebucket.
   #
-  # @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] 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.
@@ -300,6 +252,7 @@ class Puppet::HTTP::Service::Compiler < Puppet::HTTP::Service
   #
   # @return [Puppet::HTTP::Response] The request response
   #
+  # @api public
   def head_filebucket_file(path, environment:, bucket_path: nil)
     headers = add_puppet_headers('Accept' => 'application/octet-stream')