puppet 6.14.0-x86-mingw32 → 6.19.0-x86-mingw32

data/lib/puppet/http/redirector.rb

@@ -1,8 +1,30 @@
+#
+# @api private
+#
+# Handle HTTP redirects
+#
 class Puppet::HTTP::Redirector
+  #
+  # @api private
+  #
+  # Create a new redirect handler
+  #
+  # @param [Integer] redirect_limit maximum number of redirects allowed
+  #
   def initialize(redirect_limit)
     @redirect_limit = redirect_limit
   end
 
+  #
+  # @api private
+  #
+  # Determine of the HTTP response code indicates a redirect
+  #
+  # @param [Net::HTTP] request request that received the response
+  # @param [Puppet::HTTP::Response] response
+  #
+  # @return [Boolean] true if the response code is 301, 302, or 307.
+  #
   def redirect?(request, response)
     # Net::HTTPRedirection is not used because historically puppet
     # has only handled these, and we're not a browser
@@ -14,17 +36,23 @@ class Puppet::HTTP::Redirector
     end
   end
 
+  #
+  # @api private
+  #
+  # Implement the HTTP request redirection
+  #
+  # @param [Net::HTTP] request request that has been redirected
+  # @param [Puppet::HTTP::Response] response
+  # @param [Integer] redirects the current number of redirects
+  #
+  # @return [Net::HTTP] A new request based on the original request, but with
+  #   the redirected location
+  #
   def redirect_to(request, response, redirects)
     raise Puppet::HTTP::TooManyRedirects.new(request.uri) if redirects >= @redirect_limit
 
     location = parse_location(response)
-    if location.relative?
-      url = request.uri.dup
-      url.path = location.path
-    else
-      url = location.dup
-    end
-    url.query = request.uri.query
+    url = request.uri.merge(location)
 
     new_request = request.class.new(url)
     new_request.body = request.body
@@ -32,6 +60,14 @@ class Puppet::HTTP::Redirector
       new_request[header] = value
     end
 
+    # mimic private Net::HTTP#addr_port
+    new_request['Host'] = if (location.scheme == 'https' && location.port == 443) ||
+                             (location.scheme == 'http' && location.port == 80)
+                            location.host
+                          else
+                            "#{location.host}:#{location.port}"
+                          end
+
     new_request
   end
 

data/lib/puppet/http/resolver.rb

@@ -1,18 +1,58 @@
+#
+# @api private
+#
+# Resolver base class. Each resolver represents a different strategy for
+# resolving a service name into a list of candidate servers and ports.
+#
+# @abstract Subclass and override {#resolve} to create a new resolver.
+#
 class Puppet::HTTP::Resolver
+  #
+  # @api private
+  #
+  # Create a new resolver
+  #
+  # @param [Puppet::HTTP::Client] client
+  #
   def initialize(client)
     @client = client
   end
 
-  def resolve(session, name, ssl_context: nil)
+  #
+  # @api private
+  #
+  # Return a working server/port for the resolver. This is the base
+  # implementation and is meant to be a placeholder.
+  #
+  # @param [Puppet::HTTP::Session] session
+  # @param [Symbol] name the service to resolve
+  # @param [Puppet::SSL::SSLContext] ssl_context (nil) optional ssl context to
+  #   use when creating a connection
+  # @param [Proc] canceled_handler (nil) optional callback allowing a resolver
+  #   to cancel resolution.
+  #
+  # @raise [NotImplementedError] this base class is not implemented
+  #
+  def resolve(session, name, ssl_context: nil, canceled_handler: nil)
     raise NotImplementedError
   end
 
+  #
+  # @api private
+  #
+  # Check a given connection to establish if it can be relied on for future use
+  #
+  # @param [Puppet::HTTP::Session] session
+  # @param [Puppet::HTTP::Service] service
+  # @param [Puppet::SSL::SSLContext] ssl_context
+  #
+  # @return [Boolean] Returns true if a connection is successful, false otherwise
+  #
   def check_connection?(session, service, ssl_context: nil)
     service.connect(ssl_context: ssl_context)
     return true
   rescue Puppet::HTTP::ConnectionError => e
-    session.add_exception(e)
-    Puppet.debug("Connection to #{service.url} failed, trying next route: #{e.message}")
+    Puppet.log_exception(e, "Connection to #{service.url} failed, trying next route: #{e.message}")
     return false
   end
 end

data/lib/puppet/http/resolver/server_list.rb

@@ -1,4 +1,22 @@
+#
+# @api private
+#
+# Use the server_list setting to resolve a service. This resolver is only used
+# if server_list is set either on the command line or in the configuration file.
+#
 class Puppet::HTTP::Resolver::ServerList < Puppet::HTTP::Resolver
+  #
+  # @api private
+  #
+  # @param [Puppet::HTTP::Client] client
+  # @param [Array<String>] server_list_setting array of servers set via the
+  #   configuration or the command line
+  # @param [Integer] default_port if a port is not set for a server in
+  #   server_list, use this port
+  # @param [Array<Symbol>] services array of services that server_list can be
+  #   used to resolve. If a service is not included in this array, this resolver
+  #   will return nil.
+  #
   def initialize(client, server_list_setting:, default_port:, services: )
     @client = client
     @server_list_setting = server_list_setting
@@ -6,33 +24,57 @@ class Puppet::HTTP::Resolver::ServerList < Puppet::HTTP::Resolver
     @services = services
   end
 
-  def resolve(session, name, ssl_context: nil)
-    if @services.include?(name)
-      @server_list_setting.value.each do |server|
-        host = server[0]
-        port = server[1] || @default_port
-        uri = URI("https://#{host}:#{port}/status/v1/simple/master")
-        if get_success?(uri, session, ssl_context: ssl_context)
-          return Puppet::HTTP::Service.create_service(@client, session, name, host, port)
-        end
+  #
+  # @api private
+  #
+  # Walk the server_list to find a server and port that will connect successfully.
+  #
+  # @param [Puppet::HTTP::Session] session <description>
+  # @param [Symbol] name the name of the service being resolved
+  # @param [Puppet::SSL::SSLContext] ssl_context
+  # @param [Proc] canceled_handler (nil) optional callback allowing a resolver
+  #   to cancel resolution.
+  #
+  # @return [nil] return nil if the service to be resolved does not support
+  #   server_list
+  # @return [Puppet::HTTP::Service] a validated service to use for future HTTP
+  #   requests
+  #
+  # @raise [Puppet::Error] raise if none of the servers defined in server_list
+  #   are available
+  #
+  def resolve(session, name, ssl_context: nil, canceled_handler: nil)
+    # If we're configured to use an explicit service host, e.g. report_server
+    # then don't use server_list to resolve the `:report` service.
+    return nil unless @services.include?(name)
+
+    # If we resolved the URL already, use its host & port for the service
+    if @resolved_url
+      return Puppet::HTTP::Service.create_service(@client, session, name, @resolved_url.host, @resolved_url.port)
+    end
+
+    # Return the first simple service status endpoint we can connect to
+    @server_list_setting.value.each do |server|
+      host = server[0]
+      port = server[1] || @default_port
+
+      service = Puppet::HTTP::Service.create_service(@client, session, :puppetserver, host, port)
+      begin
+        service.get_simple_status(ssl_context: ssl_context)
+        @resolved_url = service.url
+        return Puppet::HTTP::Service.create_service(@client, session, name, @resolved_url.host, @resolved_url.port)
+      rescue Puppet::HTTP::ResponseError => detail
+        Puppet.log_exception(detail, _("Puppet server %{host}:%{port} is unavailable: %{code} %{reason}") %
+                             { host: service.url.host, port: service.url.port, code: detail.response.code, reason: detail.response.reason })
+      rescue Puppet::HTTP::HTTPError => detail
+        Puppet.log_exception(detail, _("Unable to connect to server from server_list setting: %{detail}") % {detail: detail})
       end
-      raise Puppet::Error, _("Could not select a functional puppet master from server_list: '%{server_list}'") % { server_list: @server_list_setting.print(@server_list_setting.value) }
-    else
-      return nil
     end
-  end
 
-  def get_success?(uri, session, ssl_context: nil)
-    response = @client.get(uri, ssl_context: ssl_context)
-    return true if response.success?
+    # don't fallback to other resolvers
+    canceled_handler.call(true) if canceled_handler
 
-    Puppet.debug(_("Puppet server %{host}:%{port} is unavailable: %{code} %{reason}") %
-                 { host: uri.host, port: uri.port, code: response.code, reason: response.reason })
-    return false
-  rescue => detail
-    session.add_exception(detail)
-    #TRANSLATORS 'server_list' is the name of a setting and should not be translated
-    Puppet.debug _("Unable to connect to server from server_list setting: %{detail}") % {detail: detail}
-    return false
+    # not found
+    nil
   end
 end

data/lib/puppet/http/resolver/settings.rb

@@ -1,5 +1,25 @@
+#
+# @api private
+#
+# Resolve a service using settings. This is the default resolver if none of the
+# other resolvers find a functional connection.
+#
 class Puppet::HTTP::Resolver::Settings < Puppet::HTTP::Resolver
-  def resolve(session, name, ssl_context: nil)
+  #
+  # @api private
+  #
+  # Resolve a service using the default server and port settings for this service.
+  #
+  # @param [Puppet::HTTP::Session] session
+  # @param [Symbol] name the name of the service to be resolved
+  # @param [Puppet::SSL::SSLContext] ssl_context
+  # @param [Proc] canceled_handler (nil) optional callback allowing a resolver
+  #   to cancel resolution.
+  #
+  # @return [Puppet::HTTP::Service] if the service successfully connects,
+  #   return it. Otherwise, return nil.
+  #
+  def resolve(session, name, ssl_context: nil, canceled_handler: nil)
     service = Puppet::HTTP::Service.create_service(@client, session, name)
     check_connection?(session, service, ssl_context: ssl_context) ? service : nil
   end

data/lib/puppet/http/resolver/srv.rb

@@ -1,11 +1,37 @@
+#
+# @api private
+#
+# Resolve a service using SRV
+#
 class Puppet::HTTP::Resolver::SRV < Puppet::HTTP::Resolver
+  #
+  # @api private
+  #
+  # @param [Puppet::HTTP::Client] client
+  # @param [String] domain srv domain
+  # @param [Resolv::DNS] dns
+  #
   def initialize(client, domain:, dns: Resolv::DNS.new)
     @client = client
     @srv_domain = domain
     @delegate = Puppet::Network::Resolver.new(dns)
   end
 
-  def resolve(session, name, ssl_context: nil)
+  #
+  # @api private
+  #
+  # Walk the available srv records and return the first that successfully connects
+  #
+  # @param [Puppet::HTTP::Session] session
+  # @param [Symbol] name the service being resolved
+  # @param [Puppet::SSL::SSLContext] ssl_context
+  # @param [Proc] canceled_handler (nil) optional callback allowing a resolver
+  #   to cancel resolution.
+  #
+  # @return [Puppet::HTTP::Service] if an available service is found, return
+  #   it. Return nil otherwise.
+  #
+  def resolve(session, name, ssl_context: nil, canceled_handler: nil)
     # Here we pass our HTTP service name as the DNS SRV service name
     # This is fine for :ca, but note that :puppet and :file are handled
     # specially in `each_srv_record`.
@@ -14,6 +40,6 @@ class Puppet::HTTP::Resolver::SRV < Puppet::HTTP::Resolver
       return service if check_connection?(session, service, ssl_context: ssl_context)
     end
 
-    return nil
+    nil
   end
 end

data/lib/puppet/http/response.rb

@@ -1,37 +1,118 @@
+#
+# @api private
+#
+# Represents the response returned from the server from an HTTP request
+#
 class Puppet::HTTP::Response
-  attr_reader :nethttp, :url
+  # @api private
+  # @return [Net::HTTP] the Net::HTTP response
+  attr_reader :nethttp
 
+  # @api private
+  # @return [URI] the response uri
+  attr_reader :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
     @url = url
   end
 
+  #
+  # @api private
+  #
+  # Extract the response code
+  #
+  # @return [Integer] Response code for the request
+  #
   def code
     @nethttp.code.to_i
   end
 
+  #
+  # @api private
+  #
+  # Extract the response message
+  #
+  # @return [String] Response message for the request
+  #
   def reason
     @nethttp.message
   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
+  #   same response.
+  #
+  # @return [String] Response body for the request
+  #
   def body
     @nethttp.body
   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
+  #   response.
+  #
+  # @yield [String] Streams the response body in chunks
+  #
+  # @raise [ArgumentError] raise if a block is not given
+  #
   def read_body(&block)
     raise ArgumentError, "A block is required" unless block_given?
 
     @nethttp.read_body(&block)
   end
 
+  #
+  # @api private
+  #
+  # Check if the request received a response of success
+  #
+  # @return [Boolean] Returns true if the response indicates success
+  #
   def success?
     @nethttp.is_a?(Net::HTTPSuccess)
   end
 
+  # @api private
+  #
+  # Get a header case-insensitively.
+  # @param [String] name The header name
+  # @return [String] The header value
+  #
   def [](name)
     @nethttp[name]
   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
+  #
+  def each_header(&block)
+    @nethttp.each_header(&block)
+  end
+
+  # @api private
+  #
+  # Drain the response body.
+  #
   def drain
     body
     true

data/lib/puppet/http/retry_after_handler.rb

@@ -1,12 +1,37 @@
 require 'date'
 require 'time'
 
+#
+# @api private
+#
+# Parse information relating to responses containing a Retry-After headers
+#
 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?
+  #
+  # @param [Net::HTTP] request
+  # @param [Puppet::HTTP::Response] response
+  #
+  # @return [Boolean] Return true if the response code is 429 or 503, return
+  #   false otherwise
+  #
   def retry_after?(request, response)
     case response.code
     when 429, 503
@@ -16,6 +41,20 @@ class Puppet::HTTP::RetryAfterHandler
     end
   end
 
+  #
+  # @api private
+  #
+  # The amount of time to wait before attempting a retry
+  #
+  # @param [Net::HTTP] request
+  # @param [Puppet::HTTP::Response] response
+  # @param [Integer] retries number of retries attempted so far
+  #
+  # @return [Integer] the amount of time to wait
+  #
+  # @raise [Puppet::HTTP::TooManyRetryAfters] raise if we have hit our retry
+  #   limit
+  #
   def retry_after_interval(request, response, retries)
     raise Puppet::HTTP::TooManyRetryAfters.new(request.uri) if retries >= @retry_limit