Class: HTTPClient

The HTTPClient class provides several methods for accessing Web resources via HTTP.

HTTPClient instance is designed to be MT-safe. You can call a HTTPClient instance from several threads without synchronization after setting up an instance.

  clnt = HTTPClient.new
  clnt.set_cookie_store('/home/nahi/cookie.dat')
  urls.each do |url|
    Thread.new(url) do |u|
      p clnt.head(u).status
    end
  end

How to use

At first, how to create your client. See initialize for more detail.

Create simple client.
```
 clnt = HTTPClient.new
```
Accessing resources through HTTP proxy. You can use environment variable ‘http_proxy’ or ‘HTTP_PROXY’ instead.
```
 clnt = HTTPClient.new('http://myproxy:8080')
```

How to retrieve web resources

See get_content.

Get content of specified URL. It returns a String of whole result.
```
 puts clnt.get_content('http://dev.ctor.org/')
```

Get content as chunks of String. It yields chunks of String.

 clnt.get_content('http://dev.ctor.org/') do |chunk|
   puts chunk
 end

Invoking other HTTP methods

See head, get, post, put, delete, options, propfind, proppatch and trace. It returns a HTTP::Message instance as a response.

Do HEAD request.

 res = clnt.head(uri)
 p res.header['Last-Modified'][0]

Do GET request with query.

 query = { 'keyword' => 'ruby', 'lang' => 'en' }
 res = clnt.get(uri, query)
 p res.status
 p res.contenttype
 p res.header['X-Custom']
 puts res.content

How to POST

See post.

Do POST a form data.

 body = { 'keyword' => 'ruby', 'lang' => 'en' }
 res = clnt.post(uri, body)

Do multipart file upload with POST. No need to set extra header by yourself from httpclient/2.1.4.

 File.open('/tmp/post_data') do |file|
   body = { 'upload' => file, 'user' => 'nahi' }
   res = clnt.post(uri, body)
 end

Accessing via SSL

Ruby needs to be compiled with OpenSSL.

Get content of specified URL via SSL. Just pass an URL which starts with ‘https://’.
```
 https_url = 'https://www.rsa.com'
 clnt.get_content(https_url)
```

Getting peer certificate from response.

 res = clnt.get(https_url)
 p res.peer_cert #=> returns OpenSSL::X509::Certificate

Configuring OpenSSL options. See HTTPClient::SSLConfig for more details.

 user_cert_file = 'cert.pem'
 user_key_file = 'privkey.pem'
 clnt.ssl_config.set_client_cert_file(user_cert_file, user_key_file)
 clnt.get_content(https_url)

Handling Cookies

Using volatile Cookies. Nothing to do. HTTPClient handles Cookies.

 clnt = HTTPClient.new
 clnt.get_content(url1) # receives Cookies.
 clnt.get_content(url2) # sends Cookies if needed.

Saving non volatile Cookies to a specified file. Need to set a file at first and invoke save method at last.

 clnt = HTTPClient.new
 clnt.set_cookie_store('/home/nahi/cookie.dat')
 clnt.get_content(url)
 ...
 clnt.save_cookie_store

Disabling Cookies.

 clnt = HTTPClient.new
 clnt.cookie_manager = nil

Configuring authentication credentials

Authentication with Web server. Supports BasicAuth, DigestAuth, and Negotiate/NTLM (requires ruby/ntlm module).

 clnt = HTTPClient.new
 domain = 'http://dev.ctor.org/http-access2/'
 user = 'user'
 password = 'user'
 clnt.set_auth(domain, user, password)
 p clnt.get_content('http://dev.ctor.org/http-access2/login').status

Authentication with Proxy server. Supports BasicAuth and NTLM (requires win32/sspi)

 clnt = HTTPClient.new(proxy)
 user = 'proxy'
 password = 'proxy'
 clnt.set_proxy_auth(user, password)
 p clnt.get_content(url)

Invoking HTTP methods with custom header

Pass a Hash or an Array for extheader argument.

    extheader = { 'Accept' => '*/*' }
    clnt.get_content(uri, query, extheader)

    extheader = [['Accept', 'image/jpeg'], ['Accept', 'image/png']]
    clnt.get_content(uri, query, extheader)

Invoking HTTP methods asynchronously

See head_async, get_async, post_async, put_async, delete_async, options_async, propfind_async, proppatch_async, and trace_async. It immediately returns a HTTPClient::Connection instance as a returning value.

    connection = clnt.post_async(url, body)
    print 'posting.'
    while true
      break if connection.finished?
      print '.'
      sleep 1
    end
    puts '.'
    res = connection.pop
    p res.status
    p res.content.read # res.content is an IO for the res of async method.

Shortcut methods

You can invoke get_content, get, etc. without creating HTTPClient instance.

  ruby -rhttpclient -e 'puts HTTPClient.get_content(ARGV.shift)' http://dev.ctor.org/
  ruby -rhttpclient -e 'p HTTPClient.head(ARGV.shift).header["last-modified"]' http://dev.ctor.org/

Methods

debug_dev debug_dev= default_redirect_uri_callback delete delete_async get get_async get_content head head_async new no_proxy no_proxy= options options_async post post_async post_content propfind propfind_async proppatch proppatch_async proxy proxy= put put_async redirect_uri_callback= request request_async reset reset_all save_cookie_store set_auth set_basic_auth set_cookie_store set_proxy_auth strict_redirect_uri_callback timeout_scheduler trace trace_async

Classes and Modules

Module HTTPClient::DebugSocket
Module HTTPClient::SocketWrap
Module HTTPClient::Timeout
Module HTTPClient::Util
Class HTTPClient::AuthFilterBase
Class HTTPClient::BadResponseError
Class HTTPClient::BasicAuth
Class HTTPClient::ConfigurationError
Class HTTPClient::ConnectTimeoutError
Class HTTPClient::Connection
Class HTTPClient::DigestAuth
Class HTTPClient::LoopBackSocket
Class HTTPClient::NegotiateAuth
Class HTTPClient::ProxyAuth
Class HTTPClient::ReceiveTimeoutError
Class HTTPClient::SSLConfig
Class HTTPClient::SSLSocketWrap
Class HTTPClient::SSPINegotiateAuth
Class HTTPClient::SendTimeoutError
Class HTTPClient::Session
Class HTTPClient::SessionManager
Class HTTPClient::Site
Class HTTPClient::TimeoutError
Class HTTPClient::TimeoutScheduler
Class HTTPClient::WWWAuth

Constants

 true
 false
 true
 false
 true
 false
 '2.1.5'
 "ruby #{RUBY_VERSION} (#{RUBY_RELEASE_DATE}) [#{RUBY_PLATFORM}]"
 "(#{$1}/#{$2}, #{RUBY_VERSION_STRING})"
 Default extheader for PROPFIND request.
 ['localhost']

Attributes

cookie_manager

[RW]

WebAgent::CookieManager:

Cookies configurator.

follow_redirect_count [RW] How many times get_content and post_content follows HTTP redirect. 10 by default.

proxy_auth

[R]

HTTPClient::ProxyAuth:

Proxy authentication handler.

request_filter [R] An array of request filter which can trap HTTP request/response. See HTTPClient::WWWAuth to see how to use it.

ssl_config

[R]

HTTPClient::SSLConfig:

SSL configurator.

test_loopback_response [R] An array of response HTTP message body String which is used for loop-back test. See test/* to see how to use it. If you want to do loop-back test of HTTP header, use test_loopback_http_response instead.

www_auth

[R]

HTTPClient::WWWAuth:

WWW authentication handler.

Public Class methods

new(*args)

Creates a HTTPClient instance which manages sessions, cookies, etc.

HTTPClient.new takes 3 optional arguments for proxy url string, User-Agent String and From header String. User-Agent and From are embedded in HTTP request Header if given. No User-Agent and From header added without setting it explicitly.

  proxy = 'http://myproxy:8080'
  agent_name = 'MyAgent/0.1'
  from = 'from@example.com'
  HTTPClient.new(proxy, agent_name, from)

You can use a keyword argument style Hash. Keys are :proxy, :agent_name and :from.

  HTTPClient.new(:agent_name = 'MyAgent/0.1')

uri:	a String or an URI object which represents an URL of web resource.
query:	a Hash or an Array of query part of URL. e.g. { "a" => "b" } => ‘host/part?a=b’. Give an array to pass multiple value like ["a", "b"], ["a", "c"] => ‘host/part?a=b&a=c’.
extheader:	a Hash or an Array of extra headers. e.g. { ‘Accept’ => ’/’ } or [[‘Accept’, ‘image/jpeg’], [‘Accept’, ‘image/png’]].
&block:	Give a block to get chunked message-body of response like get_content(uri) { \|chunked_body\| … }. Size of each chunk may not be the same.

uri:	a String or an URI object which represents an URL of web resource.
body:	a Hash or an Array of body part. e.g. { "a" => "b" } => ‘a=b’. Give an array to pass multiple value like ["a", "b"], ["a", "c"] => ‘a=b&a=c’. When you pass a File as a value, it will be posted as a multipart/form-data. e.g. { ‘upload’ => file }
extheader:	a Hash or an Array of extra headers. e.g. { ‘Accept’ => ’/’ } or [[‘Accept’, ‘image/jpeg’], [‘Accept’, ‘image/png’]].
&block:	Give a block to get chunked message-body of response like post_content(uri) { \|chunked_body\| … }. Size of each chunk may not be the same.

method:	HTTP method to be sent. method.to_s.upcase is used.
uri:	a String or an URI object which represents an URL of web resource.
query:	a Hash or an Array of query part of URL. e.g. { "a" => "b" } => ‘host/part?a=b’ Give an array to pass multiple value like ["a", "b"], ["a", "c"] => ‘host/part?a=b&a=c‘
body:	a Hash or an Array of body part. e.g. { "a" => "b" } => ‘a=b’. Give an array to pass multiple value like ["a", "b"], ["a", "c"] => ‘a=b&a=c’. When the given method is ‘POST’ and the given body contains a file as a value, it will be posted as a multipart/form-data. e.g. { ‘upload’ => file } See HTTP::Message.file? for actual condition of ‘a file’.
extheader:	a Hash or an Array of extra headers. e.g. { ‘Accept’ => ’/’ } or [[‘Accept’, ‘image/jpeg’], [‘Accept’, ‘image/png’]].
&block:	Give a block to get chunked message-body of response like get(uri) { \|chunked_body\| … }. Size of each chunk may not be the same.

user:	username String.
passwd:	password String.

user:	username String.
passwd:	password String.