puppet 6.24.0-x64-mingw32 → 7.0.0-x64-mingw32

data/lib/puppet/functions/partition.rb

@@ -4,22 +4,14 @@
 # the second containing the rest.
 Puppet::Functions.create_function(:partition) do
   # @param collection A collection of things to partition.
-  # @example Partition array of empty strings, results in e.g. `[[''], [b, c]]`
-  #   ```puppet
+  # @example Partition array of empty strings, results in e.g. [[''], [b, c]]
   #   ['', b, c].partition |$s| { $s.empty }
-  #   ```
-  # @example Partition array of strings using index, results in e.g. `[['', 'ab'], ['b']]`
-  #   ```puppet
+  # @example Partition array of strings using index, results in e.g. [['', 'ab'], ['b']]
   #   ['', b, ab].partition |$i, $s| { $i == 2 or $s.empty }
-  #   ```
-  # @example Partition hash of strings by key-value pair, results in e.g. `[[['b', []]], [['a', [1, 2]]]]`
-  #   ```puppet
+  # @example Partition hash of strings by key-value pair, results in e.g. [[['b', []]], [['a', [1, 2]]]]
   #   { a => [1, 2], b => [] }.partition |$kv| { $kv[1].empty }
-  #   ```
-  # @example Partition hash of strings by key and value, results in e.g. `[[['b', []]], [['a', [1, 2]]]]`
-  #   ```puppet
+  # @example Partition hash of strings by key and value, results in e.g. [[['b', []]], [['a', [1, 2]]]]
   #   { a => [1, 2], b => [] }.partition |$k, $v| { $v.empty }
-  #   ```
   dispatch :partition_1 do
     required_param 'Collection', :collection
     block_param 'Callable[1,1]', :block

data/lib/puppet/functions/require.rb

@@ -4,13 +4,13 @@
 # The relationship metaparameters work well for specifying relationships
 # between individual resources, but they can be clumsy for specifying
 # relationships between classes.  This function is a superset of the
-# `include` function, adding a class relationship so that the requiring
+# 'include' function, adding a class relationship so that the requiring
 # class depends on the required class.
 #
-# Warning: using `require` in place of `include` can lead to unwanted dependency cycles.
+# Warning: using require in place of include can lead to unwanted dependency cycles.
 #
-# For instance, the following manifest, with `require` instead of `include`, would produce a nasty
-# dependence cycle, because `notify` imposes a `before` between `File[/foo]` and `Service[foo]`:
+# For instance the following manifest, with 'require' instead of 'include' would produce a nasty
+# dependence cycle, because notify imposes a before between File[/foo] and Service[foo]:
 #
 # ```puppet
 # class myservice {
@@ -32,7 +32,7 @@
 # resource and relationship expressions.
 #
 # - Since 4.0.0 Class and Resource types, absolute names
-# - Since 4.7.0 Returns an `Array[Type[Class]]` with references to the required classes
+# - Since 4.7.0 Returns an Array[Type[Class]] with references to the required classes
 #
 Puppet::Functions.create_function(:require, Puppet::Functions::InternalFunction) do
   dispatch :require_impl do

data/lib/puppet/functions/sort.rb

@@ -2,9 +2,9 @@
 # Please note: This function is based on Ruby String comparison and as such may not be entirely UTF8 compatible.
 # To ensure compatibility please use this function with Ruby 2.4.0 or greater - https://bugs.ruby-lang.org/issues/10085.
 #
-# This function is compatible with the function `sort()` in `stdlib`.
+# This function is compatible with the function sort() in stdlib.
 # * Comparison of characters in a string always uses a system locale and may not be what is expected for a particular locale
-# * Sorting is based on Ruby's `<=>` operator unless a lambda is given that performs the comparison.
+# * Sorting is based on Ruby's <=> operator unless a lambda is given that performs the comparison.
 #   * comparison of strings is case dependent (use lambda with `compare($a,$b)` to ignore case)
 #   * comparison of mixed data types raises an error (if there is the need to sort mixed data types use a lambda)
 #
@@ -49,7 +49,7 @@
 #   }
 # })
 # ```
-# Would notice `[2,3,'a','b']`
+# Would notice [2,3,'a','b']
 #
 # @since 6.0.0 - supporting a lambda to do compare
 #

data/lib/puppet/functions/strftime.rb

@@ -105,7 +105,6 @@
 # **Seconds since the Epoch:**
 #
 # | Format | Meaning |
-# | ------ | ------- |
 # | s | Number of seconds since 1970-01-01 00:00:00 UTC. |
 #
 # **Literal string:**

data/lib/puppet/functions/tree_each.rb

@@ -6,13 +6,13 @@
 #
 # 1. An `Array`, `Hash`, `Iterator`, or `Object` that the function will iterate over.
 # 2. An optional hash with the options:
-#    * `include_containers` => `Optional[Boolean]` # default `true` - if containers should be given to the lambda
-#    * `include_values` => `Optional[Boolean]` # default `true` - if non containers should be given to the lambda
-#    * `include_root` => `Optional[Boolean]` # default `true` - if the root container should be given to the lambda
+#    * `include_containers` => `Optional[Boolean]` # default true - if containers should be given to the lambda
+#    * `include_values` => `Optional[Boolean]` # default true - if non containers should be given to the lambda
+#    * `include_root` => `Optional[Boolean]` # default true - if the root container should be given to the lambda
 #    * `container_type` => `Optional[Type[Variant[Array, Hash, Object]]]` # a type that determines what a container is - can only
 #       be set to a type that matches the default `Variant[Array, Hash, Object]`.
 #    * `order` => `Enum[depth_first, breadth_first]` # default ´depth_first`, the order in which elements are visited
-#    * `include_refs` => `Optional[Boolean]` # default `false`, if attributes in objects marked as bing of `reference` kind
+#    * `include_refs` => Optional[Boolean] # default `false`, if attributes in objects marked as bing of `reference` kind
 #       should be included.
 # 3. An optional lambda, which the function calls for each element in the first argument. It must
 #    accept one or two arguments; either `$path`, and `$value`, or just `$value`.
@@ -46,12 +46,14 @@
 # [1, [2, 3], 4]
 # ```
 #
-# If containers are skipped, results in:
+# Results in:
+#
+# If containers are skipped:
 #
 # * `depth_first` order `1`, `2`, `3`, `4`
 # * `breadth_first` order `1`, `4`,`2`, `3`
 #
-# If containers and root are included, results in:
+# If containers and root, are included:
 #
 # * `depth_first` order `[1, [2, 3], 4]`, `1`, `[2, 3]`, `2`, `3`, `4`
 # * `breadth_first` order `[1, [2, 3], 4]`, `1`, `[2, 3]`, `4`, `2`, `3`
@@ -94,7 +96,7 @@
 #
 # Any Puppet Type system data type can be used to filter what is
 # considered to be a container, but it must be a narrower type than one of
-# the default `Array`, `Hash`, `Object` types - for example it is not possible to make a
+# the default Array, Hash, Object types - for example it is not possible to make a
 # `String` be a container type.
 #
 # @example Only `Array` as container type

data/lib/puppet/functions/type.rb

@@ -35,10 +35,10 @@
 #
 # Would notice the four values:
 #
-# 1. `Array[Numeric]`
-# 2. `Array[Numeric, 2, 2]`
-# 3. `Tuple[Float[3.14], Integer[42,42]]]`
-# 4. `Tuple[Float[3.14], Integer[42,42]]]`
+# 1. 'Array[Numeric]'
+# 2. 'Array[Numeric, 2, 2]'
+# 3. 'Tuple[Float[3.14], Integer[42,42]]]'
+# 4. 'Tuple[Float[3.14], Integer[42,42]]]'
 #
 # @since 4.4.0
 #

data/lib/puppet/functions/unwrap.rb

@@ -1,5 +1,4 @@
 # Unwraps a Sensitive value and returns the wrapped object.
-# Returns the Value itself, if it is not Sensitive.
 #
 # @example Usage of unwrap
 #
@@ -29,17 +28,12 @@
 # @since 4.0.0
 #
 Puppet::Functions.create_function(:unwrap) do
-  dispatch :from_sensitive do
+  dispatch :unwrap do
     param 'Sensitive', :arg
     optional_block_param
   end
 
-  dispatch :from_any do
-    param 'Any', :arg
-    optional_block_param
-  end
-
-  def from_sensitive(arg)
+  def unwrap(arg)
     unwrapped = arg.unwrap
     if block_given?
       yield(unwrapped)
@@ -47,13 +41,4 @@ Puppet::Functions.create_function(:unwrap) do
       unwrapped
     end
   end
-
-  def from_any(arg)
-    unwrapped = arg
-    if block_given?
-      yield(unwrapped)
-    else
-      unwrapped
-    end
-  end
 end

data/lib/puppet/functions/upcase.rb

@@ -22,14 +22,14 @@
 # 'hello'.upcase()
 # upcase('hello')
 # ```
-# Would both result in `"HELLO"`
+# Would both result in "HELLO"
 #
 # @example Converting an Array to upper case
 # ```puppet
 # ['a', 'b'].upcase()
 # upcase(['a', 'b'])
 # ```
-# Would both result in `['A', 'B']`
+# Would both result in ['A', 'B']
 #
 # @example Converting a Hash to upper case
 # ```puppet

data/lib/puppet/generate/models/type/type.rb

@@ -49,7 +49,10 @@ module Puppet
               ]
             end]
             @isomorphic = type.isomorphic?
-            @capability = type.is_capability?
+            # continue to emit capability as false when rendering the ERB
+            # template, so that pcore modules generated prior to puppet7 can be
+            # read by puppet7 and vice-versa.
+            @capability = false
           end
 
           def render(template)

data/lib/puppet/http.rb

@@ -1,23 +1,25 @@
 module Puppet
-  module Network
-    module HTTP
-      require 'puppet/network/http/site'
-      require 'puppet/network/http/session'
-      require 'puppet/network/http/factory'
-      require 'puppet/network/http/base_pool'
-      require 'puppet/network/http/nocache_pool'
-      require 'puppet/network/http/pool'
-      require 'puppet/network/resolver'
-    end
-  end
-
-  # @api private
+  # Contains an HTTP client for making network requests to puppet and other
+  # HTTP servers.
+  #
+  # @see Puppet::HTTP::Client
+  # @see Puppet::HTTP::HTTPError
+  # @see Puppet::HTTP::Response
+  # @api public
   module HTTP
     ACCEPT_ENCODING = "gzip;q=1.0,deflate;q=0.6,identity;q=0.3".freeze
     HEADER_PUPPET_VERSION = "X-Puppet-Version".freeze
 
     require 'puppet/http/errors'
+    require 'puppet/http/site'
+    require 'puppet/http/pool_entry'
+    require 'puppet/http/proxy'
+    require 'puppet/http/factory'
+    require 'puppet/http/pool'
+    require 'puppet/http/dns'
     require 'puppet/http/response'
+    require 'puppet/http/response_converter'
+    require 'puppet/http/response_net_http'
     require 'puppet/http/service'
     require 'puppet/http/service/ca'
     require 'puppet/http/service/compiler'
@@ -34,4 +36,11 @@ module Puppet
     require 'puppet/http/retry_after_handler'
     require 'puppet/http/external_client'
   end
+
+  # Legacy HTTP API
+  module Network
+    module HTTP
+      require 'puppet/network/http_pool'
+    end
+  end
 end

data/lib/puppet/http/client.rb

@@ -1,23 +1,96 @@
+# The HTTP client provides methods for making `GET`, `POST`, etc requests to
+# HTTP(S) servers. It also provides methods for resolving Puppetserver REST
+# service endpoints using SRV records and settings (such as `server_list`,
+# `server`, `ca_server`, etc). Once a service endpoint has been resolved, there
+# are methods for making REST requests (such as getting a node, sending facts,
+# etc).
 #
-# @api private
+# The client uses persistent HTTP connections by default unless the `Connection:
+# close` header is specified and supports streaming response bodies.
 #
-# The client contains a pool of persistent HTTP connections and creates HTTP
-# sessions.
+# By default the client only trusts the Puppet CA for HTTPS connections. However,
+# if the `include_system_store` request option is set to true, then Puppet will
+# trust certificates in the puppet-agent CA bundle.
 #
+# @example To access the HTTP client:
+#   client = Puppet.runtime[:http]
+#
+# @example To make an HTTP GET request:
+#   response = client.get(URI("http://www.example.com"))
+#
+# @example To make an HTTPS GET request, trusting the puppet CA and certs in Puppet's CA bundle:
+#   response = client.get(URI("https://www.example.com"), include_system_store: true)
+#
+# @example To use a URL containing special characters, such as spaces:
+#  response = client.get(URI(Puppet::Util.uri_encode("https://www.example.com/path to file")))
+#
+# @example To pass query parameters:
+#   response = client.get(URI("https://www.example.com"), query: {'q' => 'puppet'})
+#
+# @example To pass custom headers:
+#   response = client.get(URI("https://www.example.com"), headers: {'Accept-Content' => 'application/json'})
+#
+# @example To check if the response is successful (2xx):
+#   response = client.get(URI("http://www.example.com"))
+#   puts response.success?
+#
+# @example To get the response code and reason:
+#   response = client.get(URI("http://www.example.com"))
+#   unless response.success?
+#     puts "HTTP #{response.code} #{response.reason}"
+#    end
+#
+# @example To read response headers:
+#   response = client.get(URI("http://www.example.com"))
+#   puts response['Content-Type']
+#
+# @example To stream the response body:
+#   client.get(URI("http://www.example.com")) do |response|
+#     if response.success?
+#       response.read_body do |data|
+#         puts data
+#       end
+#     end
+#   end
+#
+# @example To handle exceptions:
+#   begin
+#     client.get(URI("https://www.example.com"))
+#   rescue Puppet::HTTP::ResponseError => e
+#     puts "HTTP #{e.response.code} #{e.response.reason}"
+#   rescue Puppet::HTTP::ConnectionError => e
+#     puts "Connection error #{e.message}"
+#   rescue Puppet::SSL::SSLError => e
+#     puts "SSL error #{e.message}"
+#   rescue Puppet::HTTP::HTTPError => e
+#     puts "General HTTP error #{e.message}"
+#   end
+#
+# @example To route to the `:puppet` service:
+#   session = client.create_session
+#   service = session.route_to(:puppet)
+#
+# @example To make a node request:
+#   node = service.get_node(Puppet[:certname], environment: 'production')
+#
+# @example To submit facts:
+#   facts = Puppet::Indirection::Facts.indirection.find(Puppet[:certname])
+#   service.put_facts(Puppet[:certname], environment: 'production', facts: facts)
+#
+# @example To submit a report to the `:report` service:
+#   report = Puppet::Transaction::Report.new
+#   service = session.route_to(:report)
+#   service.put_report(Puppet[:certname], report, environment: 'production')
+#
+# @api public
 class Puppet::HTTP::Client
 
-  # @api private
-  # @return [Puppet::Network::HTTP::Pool] the pool instance associated with
-  #   this client
   attr_reader :pool
 
+  # Create a new http client instance. Use `Puppet.runtime[:http]` to get
+  # the current client instead of creating an instance of this class.
   #
-  # @api private
-  #
-  # Create a new http client instance. The client contains a pool of persistent
-  # HTTP connections and creates HTTP sessions.
-  #
-  # @param [Puppet::Network::HTTP::Pool] pool pool of persistent Net::HTTP
+  # @param [Puppet::HTTP::Pool] pool pool of persistent Net::HTTP
   #   connections
   # @param [Puppet::SSL::SSLContext] ssl_context ssl context to be used for
   #   connections
@@ -28,7 +101,7 @@ class Puppet::HTTP::Client
   # @param [Integer] retry_limit number of HTTP reties allowed in a given
   #   request
   #
-  def initialize(pool: Puppet::Network::HTTP::Pool.new(Puppet[:http_keepalive_timeout]), ssl_context: nil, system_ssl_context: nil, redirect_limit: 10, retry_limit: 100)
+  def initialize(pool: Puppet::HTTP::Pool.new(Puppet[:http_keepalive_timeout]), ssl_context: nil, system_ssl_context: nil, redirect_limit: 10, retry_limit: 100)
     @pool = pool
     @default_headers = {
       'X-Puppet-Version' => Puppet.version,
@@ -40,22 +113,19 @@ class Puppet::HTTP::Client
     @retry_after_handler = Puppet::HTTP::RetryAfterHandler.new(retry_limit, Puppet[:runinterval])
   end
 
-  #
-  # @api private
-  #
   # Create a new HTTP session. A session is the object through which services
   # may be connected to and accessed.
   #
   # @return [Puppet::HTTP::Session] the newly created HTTP session
   #
+  # @api public
   def create_session
     Puppet::HTTP::Session.new(self, build_resolvers)
   end
 
-  #
-  # @api private
-  #
-  # Open a connection to the given URI
+  # Open a connection to the given URI. It is typically not necessary to call
+  # this method as the client will create connections as needed when a request
+  # is made.
   #
   # @param [URI] uri the connection destination
   # @param [Hash] options
@@ -63,16 +133,12 @@ class Puppet::HTTP::Client
   #   be used for connections
   # @option options [Boolean] :include_system_store (false) if we should include
   #   the system store for connection
-  #
-  # @yield [Net::HTTP] If a block is given, yields an active http connection
-  #   from the pool
-  #
   def connect(uri, options: {}, &block)
     start = Time.now
     verifier = nil
     connected = false
 
-    site = Puppet::Network::HTTP::Site.from_uri(uri)
+    site = Puppet::HTTP::Site.from_uri(uri)
     if site.use_ssl?
       ssl_context = options.fetch(:ssl_context, nil)
       include_system_store = options.fetch(:include_system_store, false)
@@ -101,88 +167,73 @@ class Puppet::HTTP::Client
                 {uri: uri, elapsed: elapsed(start), message: e.message}, e, connected)
   end
 
-  #
-  # @api private
-  #
+  # These options apply to all HTTP request methods
+  #
+  # @!macro [new] request_options
+  #   @param [Hash] options HTTP request options. Options not recognized by the
+  #     HTTP implementation will be ignored.
+  #   @option options [Puppet::SSL::SSLContext] :ssl_context (nil) ssl context to
+  #     be used for connections
+  #   @option options [Boolean] :include_system_store (false) if we should include
+  #     the system store for connection
+  #   @option options [Integer] :redirect_limit (10) The maximum number of HTTP
+  #     redirections to allow for this request.
+  #   @option options [Hash] :basic_auth A map of `:username` => `String` and
+  #     `:password` => `String`
+  #   @option options [String] :metric_id The metric id used to track metrics
+  #     on requests.
+
   # Submits a GET HTTP request to the given url
   #
   # @param [URI] url the location to submit the http request
   # @param [Hash] headers merged with the default headers defined by the client
   # @param [Hash] params encoded and set as the url query
-  # @param [Hash] options passed through to the request execution
-  # @option options [Puppet::SSL::SSLContext] :ssl_context (nil) ssl context to
-  #   be used for connections
-  # @option options [Boolean] :include_system_store (false) if we should include
-  #   the system store for connection
-  # @param options [Integer] :redirect_limit number of HTTP redirections to allow
-  #   for this request.
+  # @!macro request_options
   #
   # @yield [Puppet::HTTP::Response] if a block is given yields the response
   #
-  # @return [String] if a block is not given, returns the response body
+  # @return [Puppet::HTTP::Response] the response
   #
+  # @api public
   def get(url, headers: {}, params: {}, options: {}, &block)
     url = encode_query(url, params)
 
     request = Net::HTTP::Get.new(url, @default_headers.merge(headers))
 
-    execute_streaming(request, options: options) do |response|
-      if block_given?
-        yield response
-      else
-        response.body
-      end
-    end
+    execute_streaming(request, options: options, &block)
   end
 
-  #
-  # @api private
-  #
   # Submits a HEAD HTTP request to the given url
   #
   # @param [URI] url the location to submit the http request
   # @param [Hash] headers merged with the default headers defined by the client
   # @param [Hash] params encoded and set as the url query
-  # @param [Hash] options passed through to the request execution
-  # @option options [Puppet::SSL::SSLContext] :ssl_context (nil) ssl context to
-  #   be used for connections
-  # @option options [Boolean] :include_system_store (false) if we should include
-  #   the system store for connection
-  # @param options [Integer] :redirect_limit number of HTTP redirections to allow
-  #   for this request.
+  # @!macro request_options
   #
-  # @return [String] the body of the request response
+  # @return [Puppet::HTTP::Response] the response
   #
+  # @api public
   def head(url, headers: {}, params: {}, options: {})
     url = encode_query(url, params)
 
     request = Net::HTTP::Head.new(url, @default_headers.merge(headers))
 
-    execute_streaming(request, options: options) do |response|
-      response.body
-    end
+    execute_streaming(request, options: options)
   end
 
-  #
-  # @api private
-  #
   # Submits a PUT HTTP request to the given url
   #
   # @param [URI] url the location to submit the http request
   # @param [String] body the body of the PUT request
-  # @param [Hash] headers merged with the default headers defined by the client
+  # @param [Hash] headers merged with the default headers defined by the client. The
+  #   `Content-Type` header is required and should correspond to the type of data passed
+  #   as the `body` argument.
   # @param [Hash] params encoded and set as the url query
-  # @param [Hash] options passed through to the request execution
-  # @option options [String] :content_type the type of the body content
-  # @option options [Puppet::SSL::SSLContext] :ssl_context (nil) ssl context to
-  #   be used for connections
-  # @option options [Boolean] :include_system_store (false) if we should include
-  #   the system store for connection
-  # @param options [Integer] :redirect_limit number of HTTP redirections to allow
-  #   for this request.
+  # @!macro request_options
   #
-  # @return [String] the body of the request response
+  # @return [Puppet::HTTP::Response] the response
   #
+  # @api public
   def put(url, body, headers: {}, params: {}, options: {})
     raise ArgumentError, "'put' requires a string 'body' argument" unless body.is_a?(String)
     url = encode_query(url, params)
@@ -193,31 +244,24 @@ class Puppet::HTTP::Client
 
     raise ArgumentError, "'put' requires a 'content-type' header" unless request['Content-Type']
 
-    execute_streaming(request, options: options) do |response|
-      response.body
-    end
+    execute_streaming(request, options: options)
   end
 
-  #
-  # @api private
-  #
   # Submits a POST HTTP request to the given url
   #
   # @param [URI] url the location to submit the http request
   # @param [String] body the body of the POST request
-  # @param [Hash] headers merged with the default headers defined by the client
+  # @param [Hash] headers merged with the default headers defined by the client. The
+  #   `Content-Type` header is required and should correspond to the type of data passed
+  #   as the `body` argument.
   # @param [Hash] params encoded and set as the url query
-  # @param [Hash] options passed through to the request execution
-  # @option options [String] :content_type the type of the body content
-  # @option options [Puppet::SSL::SSLContext] :ssl_context (nil) ssl context to
-  #   be used for connections
-  # @option options [Boolean] :include_system_store (false) if we should include
-  #   the system store for connection
-  # @param options [Integer] :redirect_limit number of HTTP redirections to allow
-  #   for this request.
+  # @!macro request_options
   #
-  # @return [String] the body of the request response
+  # @yield [Puppet::HTTP::Response] if a block is given yields the response
+  #
+  # @return [Puppet::HTTP::Response] the response
   #
+  # @api public
   def post(url, body, headers: {}, params: {}, options: {}, &block)
     raise ArgumentError, "'post' requires a string 'body' argument" unless body.is_a?(String)
     url = encode_query(url, params)
@@ -228,48 +272,32 @@ class Puppet::HTTP::Client
 
     raise ArgumentError, "'post' requires a 'content-type' header" unless request['Content-Type']
 
-    execute_streaming(request, options: options) do |response|
-      if block_given?
-        yield response
-      else
-        response.body
-      end
-    end
+    execute_streaming(request, options: options, &block)
   end
 
-  #
-  # @api private
-  #
-  # Submits a DELETE HTTP request to the given url
+  # Submits a DELETE HTTP request to the given url.
   #
   # @param [URI] url the location to submit the http request
   # @param [Hash] headers merged with the default headers defined by the client
   # @param [Hash] params encoded and set as the url query
-  # @param [Hash] options options hash passed through to the request execution
-  # @option options [Puppet::SSL::SSLContext] :ssl_context (nil) ssl context to
-  #   be used for connections
-  # @option options [Boolean] :include_system_store (false) if we should include
-  #   the system store for connection
-  # @param options [Integer] :redirect_limit number of HTTP redirections to allow
-  #   for this request.
+  # @!macro request_options
   #
-  # @return [String] the body of the request response
+  # @return [Puppet::HTTP::Response] the response
   #
+  # @api public
   def delete(url, headers: {}, params: {}, options: {})
     url = encode_query(url, params)
 
     request = Net::HTTP::Delete.new(url, @default_headers.merge(headers))
 
-    execute_streaming(request, options: options) do |response|
-      response.body
-    end
+    execute_streaming(request, options: options)
   end
 
+  # Close persistent connections in the pool.
   #
-  # @api private
-  #
-  # Close persistent connections in the pool
+  # @return [void]
   #
+  # @api public
   def close
     @pool.close
   end
@@ -286,6 +314,21 @@ class Puppet::HTTP::Client
 
   private
 
+  # Connect or borrow a connection from the pool to the host and port associated
+  # with the request's URL. Then execute the HTTP request, retrying and
+  # following redirects as needed, and return the HTTP response. The response
+  # body will always be fully drained/consumed when this method returns.
+  #
+  # If a block is provided, then the response will be yielded to the caller,
+  # allowing the response body to be streamed.
+  #
+  # If the request/response did not result in an exception and the caller did
+  # not ask for the connection to be closed (via Connection: close), then the
+  # connection will be returned to the pool.
+  #
+  # @yieldparam [Puppet::HTTP::Response] response The final response, after
+  # following redirects and retrying
+  # @return [Puppet::HTTP::Response]
   def execute_streaming(request, options: {}, &block)
     redirector = Puppet::HTTP::Redirector.new(options.fetch(:redirect_limit, @default_redirect_limit))
 
@@ -307,7 +350,7 @@ class Puppet::HTTP::Client
 
         # don't call return within the `request` block
         http.request(request) do |nethttp|
-          response = Puppet::HTTP::Response.new(nethttp, request.uri)
+          response = Puppet::HTTP::ResponseNetHTTP.new(request.uri, nethttp)
           begin
             Puppet.debug("HTTP #{request.method.upcase} #{request.uri} returned #{response.code} #{response.reason}")
 
@@ -320,7 +363,7 @@ class Puppet::HTTP::Client
               retries += 1
               if interval
                 if http.started?
-                  Puppet.debug("Closing connection for #{Puppet::Network::HTTP::Site.from_uri(request.uri)}")
+                  Puppet.debug("Closing connection for #{Puppet::HTTP::Site.from_uri(request.uri)}")
                   http.finish
                 end
                 Puppet.warning(_("Sleeping for %{interval} seconds before retrying the request") % { interval: interval })
@@ -329,8 +372,15 @@ class Puppet::HTTP::Client
               end
             end
 
-            yield response
+            if block_given?
+              yield response
+            else
+              response.body
+            end
           ensure
+            # we need to make sure the response body is fully consumed before
+            # the connection is put back in the pool, otherwise the response
+            # for one request could leak into a future response.
             response.drain
           end