Class: RightSupport::Net::HTTPClient

Inherits:
Object
  • Object
show all
Defined in:
lib/right_support/net/http_client.rb

Overview

A wrapper for the rest-client gem that provides timeouts that make it harder to misuse RestClient.

Even though this code relies on RestClient, the right_support gem does not depend on the rest-client gem because not all users of right_support will want to make use of this interface. If one of HTTPClient instance's method is called and RestClient is not available, an exception will be raised.

HTTPClient is a thin wrapper around the RestClient::Request class, with a few minor changes to its interface, namely:

  • initializer accepts some default request options that can be overridden per-request
  • it has discrete methods for get/put/post/delete, instead of a single "request" method
  • it supports explicit :query and :payload options for query-string and request-body, and understands the Rails convention for encoding a nested Hash into request parameters.

Request Parameters

You can include a query-string with your request by passing the :query option to any of the request methods. You can pass a Hash, which will be translated to a URL-encoded query string using the Rails convention for nesting. Or, you can pass a String which will be appended verbatim to the URL. (In this case, don't forget to CGI.escape your string!)

To include a form with your request, pass the :payload option to any request method. You can pass a Hash, which will be translated to an x-www-form-urlencoded request body using the Rails convention for nesting. Or, you can pass a String which will be appended verbatim to the URL. You can even use a binary String combined with a suitable request-content-type header to pass binary data in the payload. (In this case, be very careful about String encoding under Ruby 1.9!)

Usage Examples

Create an instance ot HTTPClient with some default request options

@client = HTTPClient.new()

Simple GET

xml = @client.get 'http://example.com/resource'

And, with timeout of 5 seconds...

jpg = @client.get 'http://example.com/resource', => 'image/jpg', :timeout => 5

Doing some client authentication and SSL.

@client.get 'https://user:[email protected]/private/resource'

The :query option will be encoded as a URL query-string using Rails

nesting convention (e.g. "a=c" for this case).

@client.get 'http://example.com', :query=>:a=>{:b=>'c'}

The :payload option specifies the request body. You can specify a raw

payload:

@client.post 'http://example.com/resource', :payload=>'hi hi hi lol lol'

Or, you can specify a Hash payload which will be translated to a

x-www-form-urlencoded request body using the Rails nesting convention.

(e.g. "a=c" for this case)

@client.post 'http://example.com/resource', :payload=>:d=>{:e=>'f'}

You can specify query and/or payload for any HTTP verb, even if it

defies convention (be careful!)

@client.post 'http://example.com/resource', :query => :query_string_param=>'hi' :payload => :form_param=>'hi', :timeout => 10

POST and PUT with raw payloads

@client.post 'http://example.com/resource', => 'the post body', :headers => {:content_type => 'text/plain'} @client.post 'http://example.com/resource.xml', => xml_doc @client.put 'http://example.com/resource.pdf', => File.read('my.pdf'), :headers => {:content_type => 'application/pdf'}

DELETE

@client.delete 'http://example.com/resource'

retrieve the response http code and headers

res = @client.get 'http://example.com/some.jpg' res.code # => 200 res.headers # => 'image/jpg'

Constant Summary collapse

DEFAULT_OPTIONS =

The default options for every request; can be overridden by options passed to #initialize or to the individual request methods (#get, #post, and so forth). NOTE: rest-client 1.6.7 doesn't pass down the ssl_version to Net::HTTP.
silently discarded. 1.7.0.alpha or later does.

{
  :timeout      => 5,
  :open_timeout => 2,
  :headers      => {},
  :ssl_version  => 'TLSv1'
}

Instance Method Summary collapse

Constructor Details

#initialize(defaults = {}) ⇒ HTTPClient

Returns a new instance of HTTPClient.



137
138
139
 
# File 'lib/right_support/net/http_client.rb', line 137

def initialize(defaults = {})
  @defaults = DEFAULT_OPTIONS.merge(defaults)
end

Instance Method Details

#delete(*args) ⇒ Object 



153
154
155
 
# File 'lib/right_support/net/http_client.rb', line 153

def delete(*args)
  request(:delete, *args)
end

#get(*args) ⇒ Object 



141
142
143
 
# File 'lib/right_support/net/http_client.rb', line 141

def get(*args)      
  request(:get, *args)
end

#patch(*args) ⇒ Object 



157
158
159
 
# File 'lib/right_support/net/http_client.rb', line 157

def patch(*args)
  request(:patch, *args)
end

#post(*args) ⇒ Object 



145
146
147
 
# File 'lib/right_support/net/http_client.rb', line 145

def post(*args)
  request(:post, *args)
end

#put(*args) ⇒ Object 



149
150
151
 
# File 'lib/right_support/net/http_client.rb', line 149

def put(*args)
  request(:put, *args)
end

#request(type, url, options = {}, &block) ⇒ Object

A very thin wrapper around RestClient::Request.execute.

Parameters

type(Symbol)

an HTTP verb, e.g. :get, :post, :put or :delete

url(String)

the URL to request, including any query-string parameters

Options

This method can accept any of the options that RestClient::Request can accept, since all options are proxied through after merging in defaults, etc. Interesting options:

  • :query - hash containing a query string (GET parameters) as a Hash or String
  • :payload - hash containing the request body (POST or PUT parameters) as a Hash or String
  • :headers - hash containing additional HTTP request headers
  • :cookies - will replace possible cookies in the :headers
  • :user and :password - for basic auth, will be replaced by a user/password available in the url
  • :raw_response - return a low-level RawResponse instead of a Response
  • :verify_ssl - enable ssl verification, possible values are constants from OpenSSL::SSL
    • OpenSSL::SSL::VERIFY_NONE (default)
    • OpenSSL::SSL::VERIFY_CLIENT_ONCE
    • OpenSSL::SSL::VERIFY_PEER
    • OpenSSL::SSL::VERIFY_FAIL_IF_NO_PEER_CERT
  • :timeout and :open_timeout - specify overall request timeout + socket connect timeout
  • :ssl_client_cert, :ssl_client_key, :ssl_ca_file

Block

If the request succeeds, this method will yield the response body to its block.



187
188
189
190
191
192
193
194
195
196
197
198
199
200
 
# File 'lib/right_support/net/http_client.rb', line 187

def request(type, url, options={}, &block)
  options = @defaults.merge(options)

  # Handle query-string option which is implemented by us, not by rest-client.
  # (rest-client version of this, :headers={:params=>...}) but it
  # is broken in many ways and not suitable for use!)
  if query = options.delete(:query)
    url = process_query_string(url, query)
  end

  options.merge!(:method => type, :url => url)

  request_internal(options, &block)
end