puppet 6.14.0 → 6.19.0

data/lib/puppet/http.rb

@@ -11,6 +11,7 @@ module Puppet
     end
   end
 
+  # @api private
   module HTTP
     ACCEPT_ENCODING = "gzip;q=1.0,deflate;q=0.6,identity;q=0.3".freeze
     HEADER_PUPPET_VERSION = "X-Puppet-Version".freeze
@@ -21,6 +22,7 @@ module Puppet
     require 'puppet/http/service/ca'
     require 'puppet/http/service/compiler'
     require 'puppet/http/service/file_server'
+    require 'puppet/http/service/puppetserver'
     require 'puppet/http/service/report'
     require 'puppet/http/session'
     require 'puppet/http/resolver'
@@ -30,5 +32,6 @@ module Puppet
     require 'puppet/http/client'
     require 'puppet/http/redirector'
     require 'puppet/http/retry_after_handler'
+    require 'puppet/http/external_client'
   end
 end

data/lib/puppet/http/client.rb

@@ -1,7 +1,34 @@
+#
+# @api private
+#
+# The client contains a pool of persistent HTTP connections and creates HTTP
+# sessions.
+#
 class Puppet::HTTP::Client
+
+  # @api private
+  # @return [Puppet::Network::HTTP::Pool] the pool instance associated with
+  #   this client
   attr_reader :pool
 
-  def initialize(pool: Puppet::Network::HTTP::Pool.new, ssl_context: nil, system_ssl_context: nil, redirect_limit: 10, retry_limit: 100)
+  #
+  # @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
+  #   connections
+  # @param [Puppet::SSL::SSLContext] ssl_context ssl context to be used for
+  #   connections
+  # @param [Puppet::SSL::SSLContext] system_ssl_context the system ssl context
+  #   used if :include_system_store is set to true
+  # @param [Integer] redirect_limit default number of HTTP redirections to allow
+  #   in a given request. Can also be specified per-request.
+  # @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)
     @pool = pool
     @default_headers = {
       'X-Puppet-Version' => Puppet.version,
@@ -9,26 +36,50 @@ class Puppet::HTTP::Client
     }.freeze
     @default_ssl_context = ssl_context
     @default_system_ssl_context = system_ssl_context
-    @redirector = Puppet::HTTP::Redirector.new(redirect_limit)
+    @default_redirect_limit = redirect_limit
     @retry_after_handler = Puppet::HTTP::RetryAfterHandler.new(retry_limit, Puppet[:runinterval])
-    @resolvers = build_resolvers
   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
+  #
   def create_session
-    Puppet::HTTP::Session.new(self, @resolvers)
+    Puppet::HTTP::Session.new(self, build_resolvers)
   end
 
-  def connect(uri, ssl_context: nil, include_system_store: false, &block)
+  #
+  # @api private
+  #
+  # Open a connection to the given URI
+  #
+  # @param [URI] uri the connection destination
+  # @param [Hash] options
+  # @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
+  #
+  # @yield [Net::HTTP] If a block is given, yields an active http connection
+  #   from the pool
+  #
+  def connect(uri, options: {}, &block)
     start = Time.now
-    ctx = resolve_ssl_context(ssl_context, include_system_store)
-    site = Puppet::Network::HTTP::Site.from_uri(uri)
-    verifier = if site.use_ssl?
-                 Puppet::SSL::Verifier.new(site.host, ctx)
-               else
-                 nil
-               end
+    verifier = nil
     connected = false
 
+    site = Puppet::Network::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)
+      ctx = resolve_ssl_context(ssl_context, include_system_store)
+      verifier = Puppet::SSL::Verifier.new(site.host, ctx)
+    end
+
     @pool.with_connection(site, verifier) do |http|
       connected = true
       if block_given?
@@ -50,16 +101,32 @@ class Puppet::HTTP::Client
                 {uri: uri, elapsed: elapsed(start), message: e.message}, e, connected)
   end
 
-  def get(url, headers: {}, params: {}, user: nil, password: nil, ssl_context: nil, include_system_store: false, &block)
-    query = encode_params(params)
-    unless query.empty?
-      url = url.dup
-      url.query = query
-    end
+  #
+  # @api private
+  #
+  # 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.
+  #
+  # @yield [Puppet::HTTP::Response] if a block is given yields the response
+  #
+  # @return [String] if a block is not given, returns the response body
+  #
+  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, user: user, password: password, ssl_context: ssl_context, include_system_store: include_system_store) do |response|
+    execute_streaming(request, options: options) do |response|
       if block_given?
         yield response
       else
@@ -68,50 +135,100 @@ class Puppet::HTTP::Client
     end
   end
 
-  def head(url, headers: {}, params: {}, user: nil, password: nil, ssl_context: nil, include_system_store: false)
-    query = encode_params(params)
-    unless query.empty?
-      url = url.dup
-      url.query = query
-    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.
+  #
+  # @return [String] the body of the request response
+  #
+  def head(url, headers: {}, params: {}, options: {})
+    url = encode_query(url, params)
 
     request = Net::HTTP::Head.new(url, @default_headers.merge(headers))
 
-    execute_streaming(request, user: user, password: password, ssl_context: ssl_context, include_system_store: include_system_store) do |response|
+    execute_streaming(request, options: options) do |response|
       response.body
     end
   end
 
-  def put(url, headers: {}, params: {}, content_type:, body:, user: nil, password: nil, ssl_context: nil, include_system_store: false)
-    query = encode_params(params)
-    unless query.empty?
-      url = url.dup
-      url.query = query
-    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] 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.
+  #
+  # @return [String] the body of the request response
+  #
+  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)
 
     request = Net::HTTP::Put.new(url, @default_headers.merge(headers))
     request.body = body
-    request['Content-Length'] = body.bytesize
-    request['Content-Type'] = content_type
+    request.content_length = body.bytesize
 
-    execute_streaming(request, user: user, password: password, ssl_context: ssl_context, include_system_store: include_system_store) do |response|
+    raise ArgumentError, "'put' requires a 'content-type' header" unless request['Content-Type']
+
+    execute_streaming(request, options: options) do |response|
       response.body
     end
   end
 
-  def post(url, headers: {}, params: {}, content_type:, body:, user: nil, password: nil, ssl_context: nil, include_system_store: false, &block)
-    query = encode_params(params)
-    unless query.empty?
-      url = url.dup
-      url.query = query
-    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] 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.
+  #
+  # @return [String] the body of the request response
+  #
+  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)
 
     request = Net::HTTP::Post.new(url, @default_headers.merge(headers))
     request.body = body
-    request['Content-Length'] = body.bytesize
-    request['Content-Type'] = content_type
+    request.content_length = body.bytesize
 
-    execute_streaming(request, user: user, password: password, ssl_context: ssl_context, include_system_store: include_system_store) do |response|
+    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
@@ -120,35 +237,73 @@ class Puppet::HTTP::Client
     end
   end
 
-  def delete(url, headers: {}, params: {}, user: nil, password: nil, ssl_context: nil, include_system_store: false)
-    query = encode_params(params)
-    unless query.empty?
-      url = url.dup
-      url.query = query
-    end
+  #
+  # @api private
+  #
+  # 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.
+  #
+  # @return [String] the body of the request response
+  #
+  def delete(url, headers: {}, params: {}, options: {})
+    url = encode_query(url, params)
 
     request = Net::HTTP::Delete.new(url, @default_headers.merge(headers))
 
-    execute_streaming(request, user: user, password: password, ssl_context: ssl_context, include_system_store: include_system_store) do |response|
+    execute_streaming(request, options: options) do |response|
       response.body
     end
   end
 
+  #
+  # @api private
+  #
+  # Close persistent connections in the pool
+  #
   def close
     @pool.close
   end
 
+  protected
+
+  def encode_query(url, params)
+    return url if params.empty?
+
+    url = url.dup
+    url.query = encode_params(params)
+    url
+  end
+
   private
 
-  def execute_streaming(request, user: nil, password: nil, ssl_context:, include_system_store:, &block)
+  def execute_streaming(request, options: {}, &block)
+    redirector = Puppet::HTTP::Redirector.new(options.fetch(:redirect_limit, @default_redirect_limit))
+
+    basic_auth = options.fetch(:basic_auth, nil)
+    unless basic_auth
+      if request.uri.user && request.uri.password
+        basic_auth = { user: request.uri.user, password: request.uri.password }
+      end
+    end
+
     redirects = 0
     retries = 0
     response = nil
     done = false
 
     while !done do
-      connect(request.uri, ssl_context: ssl_context, include_system_store: include_system_store) do |http|
-        apply_auth(request, user, password)
+      connect(request.uri, options: options) do |http|
+        apply_auth(request, basic_auth)
 
         # don't call return within the `request` block
         http.request(request) do |nethttp|
@@ -156,8 +311,8 @@ class Puppet::HTTP::Client
           begin
             Puppet.debug("HTTP #{request.method.upcase} #{request.uri} returned #{response.code} #{response.reason}")
 
-            if @redirector.redirect?(request, response)
-              request = @redirector.redirect_to(request, response, redirects)
+            if redirector.redirect?(request, response)
+              request = redirector.redirect_to(request, response, redirects)
               redirects += 1
               next
             elsif @retry_after_handler.retry_after?(request, response)
@@ -256,9 +411,9 @@ class Puppet::HTTP::Client
     @default_system_ssl_context = ssl.create_system_context(cacerts: cacerts)
   end
 
-  def apply_auth(request, user, password)
-    if user && password
-      request.basic_auth(user, password)
+  def apply_auth(request, basic_auth)
+    if basic_auth
+      request.basic_auth(basic_auth[:user], basic_auth[:password])
     end
   end
 
@@ -283,7 +438,7 @@ class Puppet::HTTP::Client
         services.delete(:report)
       end
 
-      resolvers << Puppet::HTTP::Resolver::ServerList.new(self, server_list_setting: server_list_setting, default_port: Puppet[:masterport], services: services)
+      resolvers << Puppet::HTTP::Resolver::ServerList.new(self, server_list_setting: server_list_setting, default_port: Puppet[:serverport], services: services)
     end
 
     resolvers << Puppet::HTTP::Resolver::Settings.new(self)

data/lib/puppet/http/external_client.rb

@@ -0,0 +1,90 @@
+#
+# 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'
+
+    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'
+
+    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