puppet 6.14.0 → 6.15.0

data/lib/puppet/http/external_client.rb

@@ -0,0 +1,96 @@
+#
+# Adapts an external http_client_class to the HTTP client API. The former
+# is typically registered by puppetserver and only implements a subset of
+# the Puppet::Network::HTTP::Connection methods. As a result, only the
+# `get` and `post` methods are supported. Calling `delete`, etc will
+# raise a NotImplementedError.
+#
+# @api private
+class Puppet::HTTP::ExternalClient < Puppet::HTTP::Client
+  # Create an external http client
+  #
+  # @param [Class] http_client_class The class to create to handle the request
+  # @api private
+  def initialize(http_client_class)
+    @http_client_class = http_client_class
+  end
+
+  # (see Puppet::HTTP::Client#get)
+  # @api private
+  def get(url, headers: {}, params: {}, options: {}, &block)
+    url = encode_query(url, params)
+
+    options[:use_ssl] = url.scheme == 'https'
+    if options[:user] && options[:password]
+      options[:basic_auth] = { user: options[:user], password: options[:password] }
+    end
+
+    client = @http_client_class.new(url.host, url.port, options)
+    response = Puppet::HTTP::Response.new(client.get(url.request_uri, headers, options), url)
+
+    if block_given?
+      yield response
+    else
+      response
+    end
+  rescue Puppet::HTTP::HTTPError
+    raise
+  rescue => e
+    raise Puppet::HTTP::HTTPError.new(e.message, e)
+  end
+
+  # (see Puppet::HTTP::Client#post)
+  # @api private
+  def post(url, body, headers: {}, params: {}, options: {}, &block)
+    raise ArgumentError.new("'post' requires a string 'body' argument") unless body.is_a?(String)
+    url = encode_query(url, params)
+
+    options[:use_ssl] = url.scheme == 'https'
+    if options[:user] && options[:password]
+      options[:basic_auth] = { user: options[:user], password: options[:password] }
+    end
+
+    client = @http_client_class.new(url.host, url.port, options)
+    response = Puppet::HTTP::Response.new(client.post(url.request_uri, body, headers, options), url)
+
+    if block_given?
+      yield response
+    else
+      response
+    end
+  rescue Puppet::HTTP::HTTPError, ArgumentError
+    raise
+  rescue => e
+    raise Puppet::HTTP::HTTPError.new(e.message, e)
+  end
+
+  # Close the external http client.
+  #
+  # @api private
+  def close
+    # This is a noop as puppetserver doesn't provide a way to close its http client.
+  end
+
+  # The following are intentionally not documented
+
+  def create_session
+    raise NotImplementedError
+  end
+
+  def connect(uri, options: {}, &block)
+    raise NotImplementedError
+  end
+
+  def head(url, headers: {}, params: {}, options: {})
+    raise NotImplementedError
+  end
+
+  def put(url, headers: {}, params: {}, options: {})
+    raise NotImplementedError
+  end
+
+  def delete(url, headers: {}, params: {}, options: {})
+    raise NotImplementedError
+  end
+
+end

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,6 +36,18 @@ 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
 

data/lib/puppet/http/resolver.rb

@@ -1,17 +1,60 @@
+#
+# @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] error_handler (nil) optional callback for each error
+  #   encountered while resolving a route.
+  #
+  # @raise [NotImplementedError] this base class is not implemented
+  #
+  def resolve(session, name, ssl_context: nil, error_handler: nil)
     raise NotImplementedError
   end
 
-  def check_connection?(session, service, ssl_context: nil)
+  #
+  # @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
+  # @param [Proc] error_handler (nil) optional callback for each error
+  #   encountered while resolving a route.
+  #
+  # @return [Boolean] Returns true if a connection is successful, false otherwise
+  #
+  def check_connection?(session, service, ssl_context: nil, error_handler: nil)
     service.connect(ssl_context: ssl_context)
     return true
   rescue Puppet::HTTP::ConnectionError => e
-    session.add_exception(e)
+    error_handler.call(e) if error_handler
     Puppet.debug("Connection to #{service.url} failed, trying next route: #{e.message}")
     return false
   end

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

@@ -1,36 +1,96 @@
+#
+# @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
     @default_port = default_port
     @services = services
+    @resolved_url = nil
   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] error_handler (nil) optional callback for each error
+  #   encountered while resolving a route.
+  #
+  # @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, error_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
+      uri = URI("https://#{host}:#{port}/status/v1/simple/master")
+      if get_success?(uri, session, ssl_context: ssl_context, error_handler: error_handler)
+        @resolved_url = uri
+        return Puppet::HTTP::Service.create_service(@client, session, name, host, port)
       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
+
+    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) }
   end
 
-  def get_success?(uri, session, ssl_context: nil)
-    response = @client.get(uri, ssl_context: ssl_context)
+  #
+  # @api private
+  #
+  # Check if a server and port is available
+  #
+  # @param [URI] uri A URI created from the server and port to test
+  # @param [Puppet::HTTP::Session] session
+  # @param [Puppet::SSL::SSLContext] ssl_context
+  # @param [Proc] error_handler (nil) optional callback for each error
+  #   encountered while resolving a route.
+  #
+  # @return [Boolean] true if a successful response is returned by the server,
+  #   false otherwise
+  #
+  def get_success?(uri, session, ssl_context: nil, error_handler: nil)
+    response = @client.get(uri, options: {ssl_context: ssl_context})
     return true if response.success?
 
     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)
+    error_handler.call(detail) if error_handler
     #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

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

@@ -1,6 +1,26 @@
+#
+# @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] error_handler (nil) optional callback for each error
+  #   encountered while resolving a route.
+  #
+  # @return [Puppet::HTTP::Service] if the service successfully connects,
+  #   return it. Otherwise, return nil.
+  #
+  def resolve(session, name, ssl_context: nil, error_handler: nil)
     service = Puppet::HTTP::Service.create_service(@client, session, name)
-    check_connection?(session, service, ssl_context: ssl_context) ? service : nil
+    check_connection?(session, service, ssl_context: ssl_context, error_handler: error_handler) ? service : nil
   end
 end

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

@@ -1,17 +1,43 @@
+#
+# @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] error_handler (nil) optional callback for each error
+  #   encountered while resolving a route.
+  #
+  # @return [Puppet::HTTP::Service] if an available service is found, return
+  #   it. Return nil otherwise.
+  #
+  def resolve(session, name, ssl_context: nil, error_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`.
     @delegate.each_srv_record(@srv_domain, name) do |server, port|
       service = Puppet::HTTP::Service.create_service(@client, session, name, server, port)
-      return service if check_connection?(session, service, ssl_context: ssl_context)
+      return service if check_connection?(session, service, ssl_context: ssl_context, error_handler: error_handler)
     end
 
     return nil

data/lib/puppet/http/response.rb

@@ -1,37 +1,99 @@
+#
+# @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
   def [](name)
     @nethttp[name]
   end
 
+  # @api private
   def drain
     body
     true