Class: Puppet::Network::HTTP::Connection

Inherits:
Object
  • Object
show all
Defined in:
lib/puppet/network/http/connection.rb

Overview

This class provides simple methods for issuing various types of HTTP requests. It’s interface is intended to mirror Ruby’s Net::HTTP object, but it provides a few important bits of additional functionality. Notably:

  • Any HTTPS requests made using this class will use Puppet’s SSL certificate configuration for their authentication, and

  • Provides some useful error handling for any SSL errors that occur during a request.

Constant Summary collapse

OPTION_DEFAULTS = 
{
  :use_ssl => true,
  :verify => nil, # Puppet::SSL::Validator is deprecated
  :verifier => nil,
  :redirect_limit => 10,
}

Instance Method Summary collapse

Constructor Details

#initialize(host, port, options = {}) ⇒ Connection

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Note:

the HTTP connection itself happens lazily only when #request, or one of the #get, #post, #delete, #head or #put is called

Note:

The correct way to obtain a connection is to use one of the factory methods on Puppet::Network::HttpPool

Creates a new HTTP client connection to ‘host`:`port`.

Parameters:

  • host (String) —

    the host to which this client will connect to

  • port (Integer) —

    the port to which this client will connect to

  • options (Hash) (defaults to: {}) —

    options influencing the properties of the created connection,

Options Hash (options):

  • :use_ssl (Boolean) —

    true to connect with SSL, false otherwise, defaults to true

  • :verify (#setup_connection) —

    An object that will configure any verification to do on the connection

  • :redirect_limit (Integer) —

    the number of allowed redirections, defaults to 10 passing any other option in the options hash results in a Puppet::Error exception

Raises:



51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
 
# File 'lib/puppet/network/http/connection.rb', line 51

def initialize(host, port, options = {})
  @host = host
  @port = port

  unknown_options = options.keys - OPTION_DEFAULTS.keys
  raise Puppet::Error, _("Unrecognized option(s): %{opts}") % { opts: unknown_options.map(&:inspect).sort.join(', ') } unless unknown_options.empty?

  options = OPTION_DEFAULTS.merge(options)
  @use_ssl = options[:use_ssl]
  if @use_ssl
    if options[:verifier]
      unless options[:verifier].is_a?(Puppet::SSL::Verifier)
        raise ArgumentError, _("Expected an instance of Puppet::SSL::Verifier but was passed a %{klass}") % { klass: options[:verifier].class }
      end

      @verifier = options[:verifier]
    else
      @verifier = Puppet::SSL::VerifierAdapter.new(options[:verify])
    end
  end
  @redirect_limit = options[:redirect_limit]
  @site = Puppet::Network::HTTP::Site.new(@use_ssl ? 'https' : 'http', host, port)
  @pool = Puppet.lookup(:http_pool)
end

Instance Method Details

#address ⇒ Object

The address to connect to.



169
170
171
 
# File 'lib/puppet/network/http/connection.rb', line 169

def address
  @site.host
end

#delete(path, headers = {'Depth' => 'Infinity'}, options = {}) ⇒ Object

options not recognized by this class will be ignored - no error will be thrown.

Parameters:

  • path (String)
  • headers (Hash{String => String}) (defaults to: {'Depth' => 'Infinity'})
  • options (Hash) (defaults to: {}) —

    options influencing the request made. Any

Options Hash (options):

  • :basic_auth (Hash{Symbol => String}) —

    The basic auth :username and :password to use for the request, :metric_id Ignored by this class - used by Puppet Server only. The metric id by which to track metrics on requests.



116
117
118
 
# File 'lib/puppet/network/http/connection.rb', line 116

def delete(path, headers = {'Depth' => 'Infinity'}, options = {})
  do_request(Net::HTTP::Delete.new(path, headers), options)
end

#get(path, headers = {}, options = {}) ⇒ Object

options not recognized by this class will be ignored - no error will be thrown.

Parameters:

  • path (String)
  • headers (Hash{String => String}) (defaults to: {})
  • options (Hash) (defaults to: {}) —

    options influencing the request made. Any

Options Hash (options):

  • :basic_auth (Hash{Symbol => String}) —

    The basic auth :username and :password to use for the request, :metric_id Ignored by this class - used by Puppet Server only. The metric id by which to track metrics on requests.



89
90
91
 
# File 'lib/puppet/network/http/connection.rb', line 89

def get(path, headers = {}, options = {})
  do_request(Net::HTTP::Get.new(path, headers), options)
end

#head(path, headers = {}, options = {}) ⇒ Object

options not recognized by this class will be ignored - no error will be thrown.

Parameters:

  • path (String)
  • headers (Hash{String => String}) (defaults to: {})
  • options (Hash) (defaults to: {}) —

    options influencing the request made. Any

Options Hash (options):

  • :basic_auth (Hash{Symbol => String}) —

    The basic auth :username and :password to use for the request, :metric_id Ignored by this class - used by Puppet Server only. The metric id by which to track metrics on requests.



108
109
110
 
# File 'lib/puppet/network/http/connection.rb', line 108

def head(path, headers = {}, options = {})
  do_request(Net::HTTP::Head.new(path, headers), options)
end

#port ⇒ Object

The port to connect to.



174
175
176
 
# File 'lib/puppet/network/http/connection.rb', line 174

def port
  @site.port
end

#post(path, data, headers = nil, options = {}) ⇒ Object

options not recognized by this class will be ignored - no error will be thrown.

Parameters:

  • path (String)
  • data (String)
  • headers (Hash{String => String}) (defaults to: nil)
  • options (Hash) (defaults to: {}) —

    options influencing the request made. Any

Options Hash (options):

  • :basic_auth (Hash{Symbol => String}) —

    The basic auth :username and :password to use for the request, :metric_id Ignored by this class - used by Puppet Server only. The metric id by which to track metrics on requests.



98
99
100
101
102
 
# File 'lib/puppet/network/http/connection.rb', line 98

def post(path, data, headers = nil, options = {})
  request = Net::HTTP::Post.new(path, headers)
  request.body = data
  do_request(request, options)
end

#put(path, data, headers = nil, options = {}) ⇒ Object

options not recognized by this class will be ignored - no error will be thrown.

Parameters:

  • path (String)
  • data (String)
  • headers (Hash{String => String}) (defaults to: nil)
  • options (Hash) (defaults to: {}) —

    options influencing the request made. Any

Options Hash (options):

  • :basic_auth (Hash{Symbol => String}) —

    The basic auth :username and :password to use for the request, :metric_id Ignored by this class - used by Puppet Server only. The metric id by which to track metrics on requests.



125
126
127
128
129
 
# File 'lib/puppet/network/http/connection.rb', line 125

def put(path, data, headers = nil, options = {})
  request = Net::HTTP::Put.new(path, headers)
  request.body = data
  do_request(request, options)
end

#request(method, *args) ⇒ Object 



131
132
133
 
# File 'lib/puppet/network/http/connection.rb', line 131

def request(method, *args)
  self.send(method, *args)
end

#request_get(*args, &block) ⇒ Object

TODO: These are proxies for the Net::HTTP#request_* methods, which are almost the same as the “get”, “post”, etc. methods that we’ve ported above, but they are able to accept a code block and will yield to it, which is necessary to stream responses, e.g. file content. For now we’re not funneling these proxy implementations through our #request method above, so they will not inherit the same error handling. In the future we may want to refactor these so that they are funneled through that method and do inherit the error handling.



143
144
145
146
147
148
149
 
# File 'lib/puppet/network/http/connection.rb', line 143

def request_get(*args, &block)
  with_connection(@site) do |http|
    resp = http.request_get(*args, &block)
    Puppet.debug("HTTP GET #{@site}#{args.first.split('?').first} returned #{resp.code} #{resp.message}")
    resp
  end
end

#request_head(*args, &block) ⇒ Object 



151
152
153
154
155
156
157
 
# File 'lib/puppet/network/http/connection.rb', line 151

def request_head(*args, &block)
  with_connection(@site) do |http|
    resp = http.request_head(*args, &block)
    Puppet.debug("HTTP HEAD #{@site}#{args.first.split('?').first} returned #{resp.code} #{resp.message}")
    resp
  end
end

#request_post(*args, &block) ⇒ Object 



159
160
161
162
163
164
165
 
# File 'lib/puppet/network/http/connection.rb', line 159

def request_post(*args, &block)
  with_connection(@site) do |http|
    resp = http.request_post(*args, &block)
    Puppet.debug("HTTP POST #{@site}#{args.first.split('?').first} returned #{resp.code} #{resp.message}")
    resp
  end
end

#use_ssl? ⇒ Boolean

Whether to use ssl

Returns:

  • (Boolean) 


179
180
181
 
# File 'lib/puppet/network/http/connection.rb', line 179

def use_ssl?
  @site.use_ssl?
end

#verifier ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



184
185
186
 
# File 'lib/puppet/network/http/connection.rb', line 184

def verifier
  @verifier
end