puppet 6.23.0 → 7.0.0

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,79 +119,7 @@ class Puppet::HTTP::Service::Compiler < Puppet::HTTP::Service
     [response, deserialize(response, Puppet::Resource::Catalog)]
   end
 
-  #
-  # @api private
-  #
-  # Submit a POST request to request a catalog to the server using v4 endpoint
-  #
-  # @param [String] certname The name of the node for which to compile the catalog.
-  # @param [Hash] persistent A hash containing two required keys, facts and catalog,
-  #   which when set to true will cause the facts and reports to be stored in
-  #   PuppetDB, or discarded if set to false.
-  # @param [String] environment The name of the environment for which to compile the catalog.
-  # @param [Hash] facts A hash with a required values key, containing a hash of all the
-  #    facts for the node. If not provided, Puppet will attempt to fetch facts for the node
-  #    from PuppetDB.
-  # @param [Hash] trusted_facts A hash with a required values key containing a hash of
-  #    the trusted facts for a node
-  # @param [String] transaction_uuid The id for tracking the catalog compilation and
-  #    report submission.
-  # @param [String] job_id The id of the orchestrator job that triggered this run.
-  # @param [Hash] options A hash of options beyond direct input to catalogs. Options:
-  #    - prefer_requested_environment Whether to always override a node's classified 
-  #      environment with the one supplied in the request. If this is true and no environment
-  #      is supplied, fall back to the classified environment, or finally, 'production'.
-  #    - capture_logs Whether to return the errors and warnings that occurred during
-  #      compilation alongside the catalog in the response body.
-  #    - log_level The logging level to use during the compile when capture_logs is true.
-  #      Options are 'err', 'warning', 'info', and 'debug'.
-  #
-  # @return [Array<Puppet::HTTP::Response, Puppet::Resource::Catalog, Array<String>>] An array
-  #   containing the request response, the deserialized catalog returned by
-  #   the server and array containing logs (log array will be empty if capture_logs is false)
-  #
-  def post_catalog4(certname, persistence:, environment:, facts: nil, trusted_facts: nil, transaction_uuid: nil, job_id: nil, options: nil)
-    unless persistence.is_a?(Hash) && (missing = [:facts, :catalog] - persistence.keys.map(&:to_sym)).empty?
-      raise ArgumentError.new("The 'persistence' hash is missing the keys: #{missing.join(', ')}")
-    end
-    raise ArgumentError.new("Facts must be a Hash not a #{facts.class}") unless facts.nil? || facts.is_a?(Hash)
-    body = {
-      certname: certname,
-      persistence: persistence,
-      environment: environment,
-      transaction_uuid: transaction_uuid,
-      job_id: job_id,
-      options: options
-    }
-    body[:facts] = { values: facts } unless facts.nil?
-    body[:trusted_facts] = { values: trusted_facts } unless trusted_facts.nil?
-    headers = add_puppet_headers(
-      'Accept' => get_mime_types(Puppet::Resource::Catalog).join(', '),
-      'Content-Type' => 'application/json'
-    )
-
-    url = URI::HTTPS.build(host: @url.host, port: @url.port, path: Puppet::Util.uri_encode("/puppet/v4/catalog"))
-    response = @client.post(
-      url,
-      body.to_json,
-      headers: headers
-    )
-    process_response(response)
-    begin
-      response_body = JSON.parse(response.body)
-      catalog = Puppet::Resource::Catalog.from_data_hash(response_body['catalog'])
-    rescue => err
-      raise Puppet::HTTP::SerializationError.new("Failed to deserialize catalog from puppetserver response: #{err.message}", err)
-    end
-    
-    logs = response_body['logs'] || []
-    [response, catalog, logs]
-  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
@@ -210,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(', '))
 
@@ -224,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
@@ -235,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])
 
@@ -255,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.
@@ -302,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')
 
@@ -323,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
@@ -336,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',
@@ -356,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.
@@ -369,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')