puppet 6.19.1-universal-darwin → 7.0.0-universal-darwin

data/lib/puppet/http/resolver.rb

@@ -1,26 +1,17 @@
-#
-# @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.
-#
+# @api public
 class Puppet::HTTP::Resolver
   #
-  # @api private
-  #
-  # Create a new resolver
+  # Create a new resolver.
   #
   # @param [Puppet::HTTP::Client] client
-  #
   def initialize(client)
     @client = client
   end
 
-  #
-  # @api private
-  #
   # Return a working server/port for the resolver. This is the base
   # implementation and is meant to be a placeholder.
   #
@@ -33,14 +24,12 @@ class Puppet::HTTP::Resolver
   #
   # @raise [NotImplementedError] this base class is not implemented
   #
+  # @api public
   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
+  # 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
@@ -48,6 +37,7 @@ class Puppet::HTTP::Resolver
   #
   # @return [Boolean] Returns true if a connection is successful, false otherwise
   #
+  # @api public
   def check_connection?(session, service, ssl_context: nil)
     service.connect(ssl_context: ssl_context)
     return true

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

@@ -1,12 +1,10 @@
-#
-# @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.
 #
+# @api public
 class Puppet::HTTP::Resolver::ServerList < Puppet::HTTP::Resolver
-  #
-  # @api private
+
+  # Create a server list resolver.
   #
   # @param [Puppet::HTTP::Client] client
   # @param [Array<String>] server_list_setting array of servers set via the
@@ -24,15 +22,12 @@ class Puppet::HTTP::Resolver::ServerList < Puppet::HTTP::Resolver
     @services = services
   end
 
-  #
-  # @api private
-  #
   # Walk the server_list to find a server and port that will connect successfully.
   #
-  # @param [Puppet::HTTP::Session] session <description>
+  # @param [Puppet::HTTP::Session] session
   # @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
+  # @param [Proc] canceled_handler optional callback allowing a resolver
   #   to cancel resolution.
   #
   # @return [nil] return nil if the service to be resolved does not support
@@ -43,6 +38,7 @@ class Puppet::HTTP::Resolver::ServerList < Puppet::HTTP::Resolver
   # @raise [Puppet::Error] raise if none of the servers defined in server_list
   #   are available
   #
+  # @api public
   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.

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

@@ -1,24 +1,21 @@
-#
-# @api private
-#
 # Resolve a service using settings. This is the default resolver if none of the
 # other resolvers find a functional connection.
 #
+# @api public
 class Puppet::HTTP::Resolver::Settings < Puppet::HTTP::Resolver
-  #
-  # @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
+  # @param [Proc] canceled_handler optional callback allowing a resolver
   #   to cancel resolution.
   #
   # @return [Puppet::HTTP::Service] if the service successfully connects,
   #   return it. Otherwise, return nil.
   #
+  # @api public
   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

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

@@ -1,11 +1,9 @@
+# Resolve a service using DNS SRV records.
 #
-# @api private
-#
-# Resolve a service using SRV
-#
+# @api public
 class Puppet::HTTP::Resolver::SRV < Puppet::HTTP::Resolver
-  #
-  # @api private
+
+  # Create an DNS SRV resolver.
   #
   # @param [Puppet::HTTP::Client] client
   # @param [String] domain srv domain
@@ -14,23 +12,21 @@ class Puppet::HTTP::Resolver::SRV < Puppet::HTTP::Resolver
   def initialize(client, domain:, dns: Resolv::DNS.new)
     @client = client
     @srv_domain = domain
-    @delegate = Puppet::Network::Resolver.new(dns)
+    @delegate = Puppet::HTTP::DNS.new(dns)
   end
 
-  #
-  # @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
+  # @param [Proc] canceled_handler optional callback allowing a resolver
   #   to cancel resolution.
   #
   # @return [Puppet::HTTP::Service] if an available service is found, return
   #   it. Return nil otherwise.
   #
+  # @api public
   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

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.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