puppet 6.21.1 → 7.4.1

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, :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
@@ -52,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,23 +1,19 @@
-#
-# @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.
   #
@@ -26,10 +22,7 @@ class Puppet::HTTP::Service::Compiler < Puppet::HTTP::Service
     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')
 

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

@@ -1,28 +1,24 @@
 require 'puppet/file_serving/metadata'
 
+# The FileServer service is used to retrieve file metadata and content.
 #
-# @api private
-#
-# The FileServer service is used to retrieve file metadata and content
+# @api public
 #
 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
+  # Use `Puppet::HTTP::Session.route_to(:fileserver)` 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.
   #
@@ -31,19 +27,14 @@ class Puppet::HTTP::Service::FileServer < Puppet::HTTP::Service
     super(client, session, url)
   end
 
-  #
-  # @api private
-  #
-  # Submit a GET request to the server to retrieve the metadata for a specified
-  # file
+  # 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`.
+  #   Defaults to `sha256`.
   # @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
@@ -53,6 +44,8 @@ class Puppet::HTTP::Service::FileServer < Puppet::HTTP::Service
   #   array with the request response and the deserialized metadata for the
   #   file returned from the server
   #
+  # @api public
+  #
   def get_file_metadata(path:, environment:, links: :manage, checksum_type: Puppet[:digest_algorithm], source_permissions: :ignore)
     validate_path(path)
 
@@ -74,9 +67,6 @@ class Puppet::HTTP::Service::FileServer < Puppet::HTTP::Service
     [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
@@ -106,6 +96,8 @@ class Puppet::HTTP::Service::FileServer < Puppet::HTTP::Service
   #   An array with the request response and an array of the deserialized
   #   metadata for each file returned from the server
   #
+  # @api public
+  #
   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)
 
@@ -130,10 +122,7 @@ class Puppet::HTTP::Service::FileServer < Puppet::HTTP::Service
     [response, deserialize_multiple(response, Puppet::FileServing::Metadata)]
   end
 
-  #
-  # @api private
-  #
-  # Submit a GET request to the server to retrieve content of a file
+  # 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
@@ -142,6 +131,8 @@ class Puppet::HTTP::Service::FileServer < Puppet::HTTP::Service
   #
   # @return [Puppet::HTTP::Response] The request response
   #
+  # @api public
+  #
   def get_file_content(path:, environment:, &block)
     validate_path(path)
 
@@ -163,10 +154,8 @@ class Puppet::HTTP::Service::FileServer < Puppet::HTTP::Service
     response
   end
 
-  #
-  # @api private
-  #
-  # Submit a GET request to
+  # Submit a GET request to retrieve file content using the `static_file_content` API
+  # uniquely identified by (`code_id`, `environment`, `path`).
   #
   # @param [String] path path to the file to retrieve data from
   # @param [String] environment the name of the environment we are operating in
@@ -176,6 +165,8 @@ class Puppet::HTTP::Service::FileServer < Puppet::HTTP::Service
   #
   # @return [Puppet::HTTP::Response] The request response
   #
+  # @api public
+  #
   def get_static_file_content(path:, environment:, code_id:, &block)
     validate_path(path)