puppet 6.29.0 → 7.0.0

data/lib/puppet/http/response.rb

@@ -1,118 +1,100 @@
+# Represents the response returned from the server from an HTTP request.
 #
-# @api private
-#
-# Represents the response returned from the server from an HTTP request
-#
+# @api abstract
+# @api public
 class Puppet::HTTP::Response
-  # @api private
-  # @return [Net::HTTP] the Net::HTTP response
-  attr_reader :nethttp
-
-  # @api private
-  # @return [URI] the response uri
+  # @return [URI] the response url
   attr_reader :url
 
+  # Create a response associated with the URL.
   #
-  # @api private
-  #
-  # Object to represent the response returned from an HTTP request
-  #
-  # @param [Net::HTTP] nethttp the request response
   # @param [URI] url
-  #
-  def initialize(nethttp, url)
-    @nethttp = nethttp
+  # @param [Integer] HTTP status
+  # @param [String] HTTP reason
+  def initialize(url, code, reason)
     @url = url
+    @code = code
+    @reason = reason
   end
 
-  #
-  # @api private
-  #
-  # Extract the response code
+  # Return the response code.
   #
   # @return [Integer] Response code for the request
   #
+  # @api public
   def code
-    @nethttp.code.to_i
+    @code
   end
 
-  #
-  # @api private
-  #
-  # Extract the response message
+  # Return the response message.
   #
   # @return [String] Response message for the request
   #
+  # @api public
   def reason
-    @nethttp.message
+    @reason
   end
 
-  #
-  # @api private
-  #
   # Returns the entire response body. Can be used instead of
-  #   Puppet::HTTP::Response.read_body, but both methods cannot be used for the
+  #   `Puppet::HTTP::Response.read_body`, but both methods cannot be used for the
   #   same response.
   #
   # @return [String] Response body for the request
   #
+  # @api public
   def body
-    @nethttp.body
+    raise NotImplementedError
   end
 
-  #
-  # @api private
-  #
   # Streams the response body to the caller in chunks. Can be used instead of
-  #   Puppet::HTTP::Response.body, but both methods cannot be used for the same
+  #   `Puppet::HTTP::Response.body`, but both methods cannot be used for the same
   #   response.
   #
   # @yield [String] Streams the response body in chunks
   #
   # @raise [ArgumentError] raise if a block is not given
   #
+  # @api public
   def read_body(&block)
-    raise ArgumentError, "A block is required" unless block_given?
-
-    @nethttp.read_body(&block)
+    raise NotImplementedError
   end
 
-  #
-  # @api private
-  #
-  # Check if the request received a response of success
+  # Check if the request received a response of success (HTTP 2xx).
   #
   # @return [Boolean] Returns true if the response indicates success
   #
+  # @api public
   def success?
-    @nethttp.is_a?(Net::HTTPSuccess)
+    200 <= @code && @code < 300
   end
 
-  # @api private
-  #
   # Get a header case-insensitively.
+  #
   # @param [String] name The header name
   # @return [String] The header value
   #
+  # @api public
   def [](name)
-    @nethttp[name]
+    raise NotImplementedError
   end
 
-  # @api private
-  #
   # Yield each header name and value. Returns an enumerator if no block is given.
   #
   # @yieldparam [String] header name
   # @yieldparam [String] header value
   #
+  # @api public
   def each_header(&block)
-    @nethttp.each_header(&block)
+    raise NotImplementedError
   end
 
-  # @api private
-  #
-  # Drain the response body.
+  # Ensure the response body is fully read so that the server is not blocked
+  # waiting for us to read data from the socket. Also if the caller streamed
+  # the response, but didn't read the data, we need a way to drain the socket
+  # before adding the connection back to the connection pool, otherwise the
+  # unread response data would "leak" into the next HTTP request/response.
   #
+  # @api public
   def drain
     body
     true

data/lib/puppet/http/response_converter.rb

@@ -0,0 +1,24 @@
+module Puppet::HTTP::ResponseConverter
+  module_function
+
+  # Borrowed from puppetserver, see https://github.com/puppetlabs/puppetserver/commit/a1ebeaaa5af590003ccd23c89f808ba4f0c89609
+  def to_ruby_response(response)
+    str_code = response.code.to_s
+
+    # Copied from Net::HTTPResponse because it is private there.
+    clazz = Net::HTTPResponse::CODE_TO_OBJ[str_code] or
+      Net::HTTPResponse::CODE_CLASS_TO_OBJ[str_code[0,1]] or
+      Net::HTTPUnknownResponse
+    result = clazz.new(nil, str_code, nil)
+    result.body = response.body
+    # This is nasty, nasty.  But apparently there is no way to create
+    # an instance of Net::HttpResponse from outside of the library and have
+    # the body be readable, unless you do stupid things like this.
+    result.instance_variable_set(:@read, true)
+    response.each_header do |k,v|
+      result[k] = v
+    end
+    result
+  end
+end
+

data/lib/puppet/http/response_net_http.rb

@@ -0,0 +1,42 @@
+# Adapts Net::HTTPResponse to Puppet::HTTP::Response
+#
+# @api public
+class Puppet::HTTP::ResponseNetHTTP < Puppet::HTTP::Response
+
+  # Create a response associated with the URL.
+  #
+  # @param [URI] url
+  # @param [Net::HTTPResponse] nethttp The response
+  def initialize(url, nethttp)
+    super(url, nethttp.code.to_i, nethttp.message)
+
+    @nethttp = nethttp
+  end
+
+  # (see Puppet::HTTP::Response#body)
+  def body
+    @nethttp.body
+  end
+
+  # (see Puppet::HTTP::Response#read_body)
+  def read_body(&block)
+    raise ArgumentError, "A block is required" unless block_given?
+
+    @nethttp.read_body(&block)
+  end
+
+  # (see Puppet::HTTP::Response#success?)
+  def success?
+    @nethttp.is_a?(Net::HTTPSuccess)
+  end
+
+  # (see Puppet::HTTP::Response#[])
+  def [](name)
+    @nethttp[name]
+  end
+
+  # (see Puppet::HTTP::Response#each_header)
+  def each_header(&block)
+    @nethttp.each_header(&block)
+  end
+end

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/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,20 +53,13 @@ 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
   # @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 [Boolean] check_environment If true, request that the server check if
-  #   our `environment` matches the server-specified environment. If they do not
-  #   match, then the server may return an empty catalog in the server-specified
-  #   environment.
   # @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
@@ -81,15 +68,14 @@ 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
   #
-  def post_catalog(name, facts:, environment:, configured_environment: nil, check_environment: false, transaction_uuid: nil, job_uuid: nil, static_catalog: true, checksum_type: Puppet[:supported_checksum_types])
+  # @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)
       # must use 'pson' instead of 'text/pson'
@@ -107,7 +93,6 @@ class Puppet::HTTP::Service::Compiler < Puppet::HTTP::Service
       facts: Puppet::Util.uri_query_encode(facts_as_string),
       environment: environment,
       configured_environment: configured_environment || environment,
-      check_environment: !!check_environment,
       transaction_uuid: transaction_uuid,
       job_uuid: job_uuid,
       static_catalog: static_catalog,
@@ -134,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
@@ -215,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(', '))
 
@@ -229,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
@@ -240,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])
 
@@ -260,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.
@@ -307,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')
 
@@ -328,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
@@ -341,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',
@@ -361,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.
@@ -374,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')