Class: HTTPClient

Inherits:
Object
  • Object
show all
Includes:
Util
Defined in:
lib/httpclient.rb,
lib/httpclient/auth.rb,
lib/httpclient/util.rb,
lib/httpclient/session.rb,
lib/httpclient/timeout.rb,
lib/httpclient/version.rb,
lib/httpclient/connection.rb,
lib/httpclient/ssl_config.rb,
lib/httpclient/ssl_socket.rb,
lib/httpclient/include_client.rb,
lib/httpclient/webagent-cookie.rb,
lib/httpclient/jruby_ssl_socket.rb

Overview

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

  1. Create simple client.

    clnt = HTTPClient.new

  2. 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 and get_content.

  1. Get content of specified URL. It returns HTTP::Message object and calling ‘body’ method of it returns a content String.

    puts clnt.get('http://dev.ctor.org/').body

  2. For getting content directly, use get_content. It follows redirect response and returns a String of whole result.

    puts clnt.get_content('http://dev.ctor.org/')

  3. You can pass :follow_redirect option to follow redirect response in get.

    puts clnt.get('http://dev.ctor.org/', :follow_redirect => true)

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

  1. Do HEAD request.

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

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

    You can also use keyword argument style.

    res = clnt.get(uri, :query => { :keyword => 'ruby', :lang => 'en' })

How to POST

See post.

  1. Do POST a form data.

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

    Keyword argument style.

    res = clnt.post(uri, :body => ...)

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

  3. Do multipart with custom body.

    File.open('/tmp/post_data') do |file|
  body = [{ 'Content-Type' => 'application/atom+xml; charset=UTF-8',
            :content => '<entry>...</entry>' },
          { 'Content-Type' => 'video/mp4',
            'Content-Transfer-Encoding' => 'binary',
            :content => file }]
  res = clnt.post(uri, body)
end

Accessing via SSL

Ruby needs to be compiled with OpenSSL.

  1. Get content of specified URL via SSL. Just pass an URL which starts with ‘https://’.

    https_url = 'https://www.rsa.com'
clnt.get(https_url)

  2. Getting peer certificate from response.

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

  3. 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(https_url)

  4. Revocation check. On JRuby you can set following options to let HTTPClient to perform revocation check with CRL and OCSP:

    -J-Dcom.sun.security.enableCRLDP=true -J-Dcom.sun.net.ssl.checkRevocation=true
ex. jruby -J-Dcom.sun.security.enableCRLDP=true -J-Dcom.sun.net.ssl.checkRevocation=true app.rb
Revoked cert example: https://test-sspev.verisign.com:2443/test-SSPEV-revoked-verisign.html

    On other platform you can download CRL by yourself and set it via SSLConfig#add_crl.

Handling Cookies

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

    clnt = HTTPClient.new
res = clnt.get(url1) # receives Cookies.
res = clnt.get(url2) # sends Cookies if needed.
p res.cookies

  2. 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(url)
...
clnt.save_cookie_store

  3. Disabling Cookies.

    clnt = HTTPClient.new
clnt.cookie_manager = nil

Configuring authentication credentials

  1. 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('http://dev.ctor.org/http-access2/login').status

  2. 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(url)

Invoking HTTP methods with custom header

Pass a Hash or an Array for header argument.

header = { 'Accept' => 'text/html' }
clnt.get(uri, query, header)

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

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.body.read # res.body 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/

Direct Known Subclasses

HTTPAccess2::Client, JSONClient, OAuthClient

Defined Under Namespace

Modules: DebugSocket, IncludeClient, SocketWrap, Timeout, Util Classes: AuthBase, AuthFilterBase, BadResponseError, BasicAuth, ConfigurationError, ConnectTimeoutError, Connection, DigestAuth, KeepAliveDisconnected, LoopBackSocket, NegotiateAuth, OAuth, ProxyAuth, ProxyBasicAuth, ProxyDigestAuth, ReceiveTimeoutError, RetryableResponse, SSLConfig, SSLSocket, SSPINegotiateAuth, SendTimeoutError, Session, SessionManager, Site, TimeoutError, TimeoutScheduler, WWWAuth

Constant Summary collapse

RUBY_VERSION_STRING = 
"ruby #{RUBY_VERSION} (#{RUBY_RELEASE_DATE})"
LIB_NAME = 
"(#{VERSION}, #{RUBY_VERSION_STRING})"
PROPFIND_DEFAULT_EXTHEADER =

Default header for PROPFIND request.

{ 'Depth' => '0' }
DEFAULT_AGENT_NAME =

Default User-Agent header

'HTTPClient/1.0'
NTLMEnabled = 
false
SSPIEnabled = 
false
GSSAPIEnabled = 
false
VERSION = 
'2.7.1'
CookieManager = 
WebAgent::CookieManager

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Util

#argument_to_hash, hash_find_value, #http?, #https?, #keyword_argument, try_require, uri_dirname, uri_part_of, urify, #warning

Constructor Details

#initialize(*args, &block) ⇒ HTTPClient

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

HTTPClient.new takes optional arguments as a Hash.

* :proxy - proxy url string
* :agent_name - User-Agent String
* :from - from header String
* :base_url - base URL of resources
* :default_header - header Hash all HTTP requests should have
* :force_basic_auth - flag for sending Authorization header w/o gettin 401 first

User-Agent and From are embedded in HTTP request Header if given. From header is not set without setting it explicitly.

proxy = 'http://myproxy:8080'
agent_name = 'MyAgent/0.1'
from = '[email protected]'
HTTPClient.new(proxy, agent_name, from)

After you set :base_url, all resources you pass to get, post and other methods are recognized to be prefixed with base_url. Say base_url is ‘api.example.com/v1/, get(’users’) is the same as get(‘api.example.com/v1/users’) internally. You can also pass full URL from ‘http://’ even after setting base_url.

The expected base_url and path behavior is the following. Please take care of ‘/’ in base_url and path.

The last ‘/’ is important for base_url:

1. http://foo/bar/baz/ + path -> http://foo/bar/baz/path
2. http://foo/bar/baz + path -> http://foo/bar/path

Relative path handling:

3. http://foo/bar/baz/ + ../path -> http://foo/bar/path
4. http://foo/bar/baz + ../path -> http://foo/path
5. http://foo/bar/baz/ + ./path -> http://foo/bar/baz/path
6. http://foo/bar/baz + ./path -> http://foo/bar/path

The leading ‘/’ of path means absolute path:

7. http://foo/bar/baz/ + /path -> http://foo/path
8. http://foo/bar/baz + /path -> http://foo/path

:default_header is for providing default headers Hash that all HTTP requests should have, such as custom ‘Authorization’ header in API. You can override :default_header with :header Hash parameter in HTTP request methods.

:force_basic_auth turns on/off the BasicAuth force flag. Generally HTTP client must send Authorization header after it gets 401 error from server from security reason. But in some situation (e.g. API client) you might want to send Authorization from the beginning.



424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
 
# File 'lib/httpclient.rb', line 424

def initialize(*args, &block)
  proxy, agent_name, from, base_url, default_header, force_basic_auth =
    keyword_argument(args, :proxy, :agent_name, :from, :base_url, :default_header, :force_basic_auth)
  @proxy = nil        # assigned later.
  @no_proxy = nil
  @no_proxy_regexps = []
  @base_url = base_url
  @default_header = default_header || {}
  @www_auth = WWWAuth.new
  @proxy_auth = ProxyAuth.new
  @www_auth.basic_auth.force_auth = @proxy_auth.basic_auth.force_auth = force_basic_auth
  @request_filter = [@proxy_auth, @www_auth]
  @debug_dev = nil
  @redirect_uri_callback = method(:default_redirect_uri_callback)
  @test_loopback_response = []
  @session_manager = SessionManager.new(self)
  @session_manager.agent_name = agent_name || DEFAULT_AGENT_NAME
  @session_manager.from = from
  @session_manager.ssl_config = @ssl_config = SSLConfig.new(self)
  @cookie_manager = CookieManager.new
  @follow_redirect_count = 10
  load_environment
  self.proxy = proxy if proxy
  keep_webmock_compat
  instance_eval(&block) if block
end

Instance Attribute Details

#base_url ⇒ Object

Base url of resources.



338
339
340
 
# File 'lib/httpclient.rb', line 338

def base_url
  @base_url
end

#cookie_manager ⇒ Object

HTTPClient::CookieManager

Cookies configurator.



322
323
324
 
# File 'lib/httpclient.rb', line 322

def cookie_manager
  @cookie_manager
end

#default_header ⇒ Object

Default request header.



340
341
342
 
# File 'lib/httpclient.rb', line 340

def default_header
  @default_header
end

#follow_redirect_count ⇒ Object

How many times get_content and post_content follows HTTP redirect. 10 by default.



336
337
338
 
# File 'lib/httpclient.rb', line 336

def follow_redirect_count
  @follow_redirect_count
end

#proxy_auth ⇒ Object (readonly)

HTTPClient::ProxyAuth

Proxy authentication handler.



331
332
333
 
# File 'lib/httpclient.rb', line 331

def proxy_auth
  @proxy_auth
end

#request_filter ⇒ Object (readonly)

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



329
330
331
 
# File 'lib/httpclient.rb', line 329

def request_filter
  @request_filter
end

#ssl_config ⇒ Object (readonly)

HTTPClient::SSLConfig

SSL configurator.



320
321
322
 
# File 'lib/httpclient.rb', line 320

def ssl_config
  @ssl_config
end

#test_loopback_response ⇒ Object (readonly)

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.



326
327
328
 
# File 'lib/httpclient.rb', line 326

def test_loopback_response
  @test_loopback_response
end

#www_auth ⇒ Object (readonly)

HTTPClient::WWWAuth

WWW authentication handler.



333
334
335
 
# File 'lib/httpclient.rb', line 333

def www_auth
  @www_auth
end

Class Method Details

.timeout_scheduler ⇒ Object

CAUTION: caller must aware of race condition.



116
117
118
 
# File 'lib/httpclient/timeout.rb', line 116

def timeout_scheduler
  @timeout_scheduler ||= TimeoutScheduler.new
end

Instance Method Details

#cookies ⇒ Object

Returns stored cookies.



610
611
612
613
614
 
# File 'lib/httpclient.rb', line 610

def cookies
  if @cookie_manager
    @cookie_manager.cookies
  end
end

#debug_dev ⇒ Object

Returns debug device if exists. See debug_dev=.



467
468
469
 
# File 'lib/httpclient.rb', line 467

def debug_dev
  @debug_dev
end

#debug_dev=(dev) ⇒ Object

Sets debug device. Once debug device is set, all HTTP requests and responses are dumped to given device. dev must respond to << for dump.

Calling this method resets all existing sessions.



475
476
477
478
479
 
# File 'lib/httpclient.rb', line 475

def debug_dev=(dev)
  @debug_dev = dev
  reset_all
  @session_manager.debug_dev = dev
end

#default_redirect_uri_callback(uri, res) ⇒ Object

A default method for redirect uri callback. This method is used by HTTPClient instance by default. This callback allows relative redirect such as

Location: ../foo/

in HTTP header.



718
719
720
721
722
723
724
725
726
727
728
729
730
 
# File 'lib/httpclient.rb', line 718

def default_redirect_uri_callback(uri, res)
  newuri = urify(res.header['location'][0])
  if !http?(newuri) && !https?(newuri)
    warn("#{newuri}: a relative URI in location header which is not recommended")
    warn("'The field value consists of a single absolute URI' in HTTP spec")
    newuri = uri + newuri
  end
  if https?(uri) && !https?(newuri)
    raise BadResponseError.new("redirecting to non-https resource")
  end
  puts "redirect to: #{newuri}" if $DEBUG
  newuri
end

#delete(uri, *args, &block) ⇒ Object

Sends DELETE request to the specified URL. See request for arguments.



775
776
777
 
# File 'lib/httpclient.rb', line 775

def delete(uri, *args, &block)
  request(:delete, uri, argument_to_hash(args, :body, :header, :query), &block)
end

#delete_async(uri, *args) ⇒ Object

Sends DELETE request in async style. See request_async2 for arguments. It immediately returns a HTTPClient::Connection instance as a result.



909
910
911
 
# File 'lib/httpclient.rb', line 909

def delete_async(uri, *args)
  request_async2(:delete, uri, argument_to_hash(args, :body, :header, :query))
end

#force_basic_auth=(force_basic_auth) ⇒ Object

Turn on/off the BasicAuth force flag. Generally HTTP client must send Authorization header after it gets 401 error from server from security reason. But in some situation (e.g. API client) you might want to send Authorization from the beginning.



588
589
590
 
# File 'lib/httpclient.rb', line 588

def force_basic_auth=(force_basic_auth)
  @www_auth.basic_auth.force_auth = @proxy_auth.basic_auth.force_auth = force_basic_auth
end

#get(uri, *args, &block) ⇒ Object

Sends GET request to the specified URL. See request for arguments.



738
739
740
 
# File 'lib/httpclient.rb', line 738

def get(uri, *args, &block)
  request(:get, uri, argument_to_hash(args, :query, :header, :follow_redirect), &block)
end

#get_async(uri, *args) ⇒ Object

Sends GET request in async style. See request_async for arguments. It immediately returns a HTTPClient::Connection instance as a result.



870
871
872
 
# File 'lib/httpclient.rb', line 870

def get_async(uri, *args)
  request_async2(:get, uri, argument_to_hash(args, :query, :header))
end

#get_content(uri, *args, &block) ⇒ Object

Retrieves a web resource.

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

header

a Hash or an Array of extra headers. e.g. { ‘Accept’ => ‘text/html’ } 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.

get_content follows HTTP redirect status (see HTTP::Status.redirect?) internally and try to retrieve content from redirected URL. See redirect_uri_callback= how HTTP redirection is handled.

If you need to get full HTTP response including HTTP status and headers, use get method. get returns HTTP::Message as a response and you need to follow HTTP redirect by yourself if you need.



649
650
651
652
 
# File 'lib/httpclient.rb', line 649

def get_content(uri, *args, &block)
  query, header = keyword_argument(args, :query, :header)
  success_content(follow_redirect(:get, uri, query, nil, header || {}, &block))
end

#head(uri, *args) ⇒ Object

Sends HEAD request to the specified URL. See request for arguments.



733
734
735
 
# File 'lib/httpclient.rb', line 733

def head(uri, *args)
  request(:head, uri, argument_to_hash(args, :query, :header, :follow_redirect))
end

#head_async(uri, *args) ⇒ Object

Sends HEAD request in async style. See request_async for arguments. It immediately returns a HTTPClient::Connection instance as a result.



864
865
866
 
# File 'lib/httpclient.rb', line 864

def head_async(uri, *args)
  request_async2(:head, uri, argument_to_hash(args, :query, :header))
end

#keep_webmock_compat ⇒ Object

webmock 1.6.2 depends on HTTP::Message#body.content to work. let’s keep it work iif webmock is loaded for a while.



453
454
455
456
457
458
459
460
461
462
463
464
 
# File 'lib/httpclient.rb', line 453

def keep_webmock_compat
  if respond_to?(:do_get_block_with_webmock)
    ::HTTP::Message.module_eval do
      def body
        def (o = self.content).content
          self
        end
        o
      end
    end
  end
end

#no_proxy ⇒ Object

Returns NO_PROXY setting String if given.



517
518
519
 
# File 'lib/httpclient.rb', line 517

def no_proxy
  @no_proxy
end

#no_proxy=(no_proxy) ⇒ Object

Sets NO_PROXY setting String. no_proxy must be a comma separated String. Each entry must be ‘host’ or ‘host:port’ such as; HTTPClient#no_proxy = ‘example.com,example.co.jp:443’

‘localhost’ is treated as a no_proxy site regardless of explicitly listed. HTTPClient checks given URI objects before accessing it. ‘host’ is tail string match. No IP-addr conversion.

You can use environment variable ‘no_proxy’ or ‘NO_PROXY’ for it.

Calling this method resets all existing sessions.



532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
 
# File 'lib/httpclient.rb', line 532

def no_proxy=(no_proxy)
  @no_proxy = no_proxy
  @no_proxy_regexps.clear
  if @no_proxy
    @no_proxy.scan(/([^\s:,]+)(?::(\d+))?/) do |host, port|
      if host[0] == ?.
        regexp = /#{Regexp.quote(host)}\z/i
      else
        regexp = /(\A|\.)#{Regexp.quote(host)}\z/i
      end
      @no_proxy_regexps << [regexp, port]
    end
  end
  reset_all
end

#options(uri, *args, &block) ⇒ Object

Sends OPTIONS request to the specified URL. See request for arguments.



780
781
782
783
 
# File 'lib/httpclient.rb', line 780

def options(uri, *args, &block)
  new_args = argument_to_hash(args, :header, :query, :body)
  request(:options, uri, new_args, &block)
end

#options_async(uri, *args) ⇒ Object

Sends OPTIONS request in async style. See request_async2 for arguments. It immediately returns a HTTPClient::Connection instance as a result.



915
916
917
 
# File 'lib/httpclient.rb', line 915

def options_async(uri, *args)
  request_async2(:options, uri, argument_to_hash(args, :header, :query, :body))
end

#patch(uri, *args, &block) ⇒ Object

Sends PATCH request to the specified URL. See request for arguments.



743
744
745
746
747
748
749
750
 
# File 'lib/httpclient.rb', line 743

def patch(uri, *args, &block)
  if hashy_argument_has_keys(args, :query, :body)
    new_args = args[0]
  else
    new_args = argument_to_hash(args, :body, :header)
  end
  request(:patch, uri, new_args, &block)
end

#patch_async(uri, *args) ⇒ Object

Sends PATCH request in async style. See request_async2 for arguments. It immediately returns a HTTPClient::Connection instance as a result.



876
877
878
879
880
881
882
883
 
# File 'lib/httpclient.rb', line 876

def patch_async(uri, *args)
  if hashy_argument_has_keys(args, :query, :body)
    new_args = args[0]
  else
    new_args = argument_to_hash(args, :body, :header)
  end
  request_async2(:patch, uri, new_args)
end

#post(uri, *args, &block) ⇒ Object

Sends POST request to the specified URL. See request for arguments. You should not depend on :follow_redirect => true for POST method. It sends the same POST method to the new location which is prohibited in HTTP spec.



755
756
757
758
759
760
761
762
 
# File 'lib/httpclient.rb', line 755

def post(uri, *args, &block)
  if hashy_argument_has_keys(args, :query, :body)
    new_args = args[0]
  else
    new_args = argument_to_hash(args, :body, :header, :follow_redirect)
  end
  request(:post, uri, new_args, &block)
end

#post_async(uri, *args) ⇒ Object

Sends POST request in async style. See request_async for arguments. It immediately returns a HTTPClient::Connection instance as a result.



887
888
889
890
891
892
893
894
 
# File 'lib/httpclient.rb', line 887

def post_async(uri, *args)
  if hashy_argument_has_keys(args, :query, :body)
    new_args = args[0]
  else
    new_args = argument_to_hash(args, :body, :header)
  end
  request_async2(:post, uri, new_args)
end

#post_content(uri, *args, &block) ⇒ Object

Posts a content.

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 }

You can also send custom multipart by passing an array of hashes. Each part must have a :content attribute which can be a file, all other keys will become headers.

[{ 'Content-Type' => 'text/plain', :content => "some text" },
 { 'Content-Type' => 'video/mp4', :content => File.new('video.mp4') }]
=> <Two parts with custom Content-Type header>
header

a Hash or an Array of extra headers. e.g.

{ 'Accept' => 'text/html' }

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.

post_content follows HTTP redirect status (see HTTP::Status.redirect?) internally and try to post the content to redirected URL. See redirect_uri_callback= how HTTP redirection is handled. Bear in mind that you should not depend on post_content because it sends the same POST method to the new location which is prohibited in HTTP spec.

If you need to get full HTTP response including HTTP status and headers, use post method.



686
687
688
689
690
691
692
693
694
 
# File 'lib/httpclient.rb', line 686

def post_content(uri, *args, &block)
  if hashy_argument_has_keys(args, :query, :body)
    query, body, header = keyword_argument(args, :query, :body, :header)
  else
    query = nil
    body, header = keyword_argument(args, :body, :header)
  end
  success_content(follow_redirect(:post, uri, query, body, header || {}, &block))
end

#propfind(uri, *args, &block) ⇒ Object

Sends PROPFIND request to the specified URL. See request for arguments.



786
787
788
 
# File 'lib/httpclient.rb', line 786

def propfind(uri, *args, &block)
  request(:propfind, uri, argument_to_hash(args, :header), &block)
end

#propfind_async(uri, *args) ⇒ Object

Sends PROPFIND request in async style. See request_async2 for arguments. It immediately returns a HTTPClient::Connection instance as a result.



921
922
923
 
# File 'lib/httpclient.rb', line 921

def propfind_async(uri, *args)
  request_async2(:propfind, uri, argument_to_hash(args, :body, :header))
end

#proppatch(uri, *args, &block) ⇒ Object

Sends PROPPATCH request to the specified URL. See request for arguments.



791
792
793
 
# File 'lib/httpclient.rb', line 791

def proppatch(uri, *args, &block)
  request(:proppatch, uri, argument_to_hash(args, :body, :header), &block)
end

#proppatch_async(uri, *args) ⇒ Object

Sends PROPPATCH request in async style. See request_async2 for arguments. It immediately returns a HTTPClient::Connection instance as a result.



927
928
929
 
# File 'lib/httpclient.rb', line 927

def proppatch_async(uri, *args)
  request_async2(:proppatch, uri, argument_to_hash(args, :body, :header))
end

#proxy ⇒ Object

Returns URI object of HTTP proxy if exists.



482
483
484
 
# File 'lib/httpclient.rb', line 482

def proxy
  @proxy
end

#proxy=(proxy) ⇒ Object

Sets HTTP proxy used for HTTP connection. Given proxy can be an URI, a String or nil. You can set user/password for proxy authentication like HTTPClient#proxy = ‘user:passwd@myproxy:8080’

You can use environment variable ‘http_proxy’ or ‘HTTP_PROXY’ for it. You need to use ‘cgi_http_proxy’ or ‘CGI_HTTP_PROXY’ instead if you run HTTPClient from CGI environment from security reason. (HTTPClient checks ‘REQUEST_METHOD’ environment variable whether it’s CGI or not)

Calling this method resets all existing sessions.



496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
 
# File 'lib/httpclient.rb', line 496

def proxy=(proxy)
  if proxy.nil? || proxy.to_s.empty?
    @proxy = nil
    @proxy_auth.reset_challenge
  else
    @proxy = urify(proxy)
    if @proxy.scheme == nil or @proxy.scheme.downcase != 'http' or
        @proxy.host == nil or @proxy.port == nil
      raise ArgumentError.new("unsupported proxy #{proxy}")
    end
    @proxy_auth.reset_challenge
    if @proxy.user || @proxy.password
      @proxy_auth.set_auth(@proxy.user, @proxy.password)
    end
  end
  reset_all
  @session_manager.proxy = @proxy
  @proxy
end

#put(uri, *args, &block) ⇒ Object

Sends PUT request to the specified URL. See request for arguments.



765
766
767
768
769
770
771
772
 
# File 'lib/httpclient.rb', line 765

def put(uri, *args, &block)
  if hashy_argument_has_keys(args, :query, :body)
    new_args = args[0]
  else
    new_args = argument_to_hash(args, :body, :header)
  end
  request(:put, uri, new_args, &block)
end

#put_async(uri, *args) ⇒ Object

Sends PUT request in async style. See request_async2 for arguments. It immediately returns a HTTPClient::Connection instance as a result.



898
899
900
901
902
903
904
905
 
# File 'lib/httpclient.rb', line 898

def put_async(uri, *args)
  if hashy_argument_has_keys(args, :query, :body)
    new_args = args[0]
  else
    new_args = argument_to_hash(args, :body, :header)
  end
  request_async2(:put, uri, new_args)
end

#redirect_uri_callback=(redirect_uri_callback) ⇒ Object

Sets callback proc when HTTP redirect status is returned for get_content and post_content. default_redirect_uri_callback is used by default.

If you need strict implementation which does not allow relative URI redirection, set strict_redirect_uri_callback instead.

clnt.redirect_uri_callback = clnt.method(:strict_redirect_uri_callback)



624
625
626
 
# File 'lib/httpclient.rb', line 624

def redirect_uri_callback=(redirect_uri_callback)
  @redirect_uri_callback = redirect_uri_callback
end

#request(method, uri, *args, &block) ⇒ Object

Sends a request to the specified URL.

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 }

You can also send custom multipart by passing an array of hashes. Each part must have a :content attribute which can be a file, all other keys will become headers.

[{ 'Content-Type' => 'text/plain', :content => "some text" },
 { 'Content-Type' => 'video/mp4', :content => File.new('video.mp4') }]
=> <Two parts with custom Content-Type header>

See HTTP::Message.file? for actual condition of ‘a file’.

header

a Hash or an Array of extra headers. e.g. { ‘Accept’ => ‘text/html’ } 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.

You can also pass a String as a body. HTTPClient just sends a String as a HTTP request message body.

When you pass an IO as a body, HTTPClient sends it as a HTTP request with chunked encoding (Transfer-Encoding: chunked in HTTP header) if IO does not respond to :size. Bear in mind that some server application does not support chunked request. At least cgi.rb does not support it.



838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
 
# File 'lib/httpclient.rb', line 838

def request(method, uri, *args, &block)
  query, body, header, follow_redirect = keyword_argument(args, :query, :body, :header, :follow_redirect)
  if method == :propfind
    header ||= PROPFIND_DEFAULT_EXTHEADER
  else
    header ||= {}
  end
  uri = to_resource_url(uri)
  if block
    if block.arity == 1
      filtered_block = proc { |res, str|
        block.call(str)
      }
    else
      filtered_block = block
    end
  end
  if follow_redirect
    follow_redirect(method, uri, query, body, header, &block)
  else
    do_request(method, uri, query, body, header, &filtered_block)
  end
end

#request_async(method, uri, query = nil, body = nil, header = {}) ⇒ Object

Sends a request in async style. request method creates new Thread for HTTP connection and returns a HTTPClient::Connection instance immediately.

Arguments definition is the same as request.



941
942
943
944
 
# File 'lib/httpclient.rb', line 941

def request_async(method, uri, query = nil, body = nil, header = {})
  uri = to_resource_url(uri)
  do_request_async(method, uri, query, body, header)
end

#request_async2(method, uri, *args) ⇒ Object

new method that has same signature as ‘request’



947
948
949
950
951
952
953
954
955
956
957
958
959
 
# File 'lib/httpclient.rb', line 947

def request_async2(method, uri, *args)
  query, body, header = keyword_argument(args, :query, :body, :header)
  if [:post, :put].include?(method)
    body ||= ''
  end
  if method == :propfind
    header ||= PROPFIND_DEFAULT_EXTHEADER
  else
    header ||= {}
  end
  uri = to_resource_url(uri)
  do_request_async(method, uri, query, body, header)
end

#reset(uri) ⇒ Object

Resets internal session for the given URL. Keep-alive connection for the site (host-port pair) is disconnected if exists.



963
964
965
966
 
# File 'lib/httpclient.rb', line 963

def reset(uri)
  uri = to_resource_url(uri)
  @session_manager.reset(uri)
end

#reset_all ⇒ Object

Resets all of internal sessions. Keep-alive connections are disconnected.



969
970
971
 
# File 'lib/httpclient.rb', line 969

def reset_all
  @session_manager.reset_all
end

#save_cookie_store ⇒ Object

Try to save Cookies to the file specified in set_cookie_store. Unexpected error will be raised if you don’t call set_cookie_store first.



605
606
607
 
# File 'lib/httpclient.rb', line 605

def save_cookie_store
  @cookie_manager.save_cookies
end

#set_auth(domain, user, passwd) ⇒ Object

Sets credential for Web server authentication.

domain

a String or an URI to specify where HTTPClient should use this

credential.  If you set uri to nil, HTTPClient uses this credential
wherever a server requires it.
user

username String.

passwd

password String.

You can set multiple credentials for each uri.

clnt.set_auth('http://www.example.com/foo/', 'foo_user', 'passwd')
clnt.set_auth('http://www.example.com/bar/', 'bar_user', 'passwd')

Calling this method resets all existing sessions.



561
562
563
564
565
 
# File 'lib/httpclient.rb', line 561

def set_auth(domain, user, passwd)
  uri = to_resource_url(domain)
  @www_auth.set_auth(uri, user, passwd)
  reset_all
end

#set_basic_auth(domain, user, passwd) ⇒ Object

Deprecated. Use set_auth instead.



568
569
570
571
572
 
# File 'lib/httpclient.rb', line 568

def set_basic_auth(domain, user, passwd)
  uri = to_resource_url(domain)
  @www_auth.basic_auth.set(uri, user, passwd)
  reset_all
end

#set_cookie_store(filename) ⇒ Object

Sets the filename where non-volatile Cookies be saved by calling save_cookie_store. This method tries to load and managing Cookies from the specified file.

Calling this method resets all existing sessions.



597
598
599
600
601
 
# File 'lib/httpclient.rb', line 597

def set_cookie_store(filename)
  @cookie_manager.cookies_file = filename
  @cookie_manager.load_cookies if filename
  reset_all
end

#set_proxy_auth(user, passwd) ⇒ Object

Sets credential for Proxy authentication.

user

username String.

passwd

password String.

Calling this method resets all existing sessions.



579
580
581
582
 
# File 'lib/httpclient.rb', line 579

def set_proxy_auth(user, passwd)
  @proxy_auth.set_auth(user, passwd)
  reset_all
end

#strict_redirect_uri_callback(uri, res) ⇒ Object

A method for redirect uri callback. How to use:

clnt.redirect_uri_callback = clnt.method(:strict_redirect_uri_callback)

This callback does not allow relative redirect such as

Location: ../foo/

in HTTP header. (raises BadResponseError instead)



701
702
703
704
705
706
707
708
709
710
711
 
# File 'lib/httpclient.rb', line 701

def strict_redirect_uri_callback(uri, res)
  newuri = urify(res.header['location'][0])
  if https?(uri) && !https?(newuri)
    raise BadResponseError.new("redirecting to non-https resource")
  end
  if !http?(newuri) && !https?(newuri)
    raise BadResponseError.new("unexpected location: #{newuri}", res)
  end
  puts "redirect to: #{newuri}" if $DEBUG
  newuri
end

#trace(uri, *args, &block) ⇒ Object

Sends TRACE request to the specified URL. See request for arguments.



796
797
798
 
# File 'lib/httpclient.rb', line 796

def trace(uri, *args, &block)
  request('TRACE', uri, argument_to_hash(args, :query, :header), &block)
end

#trace_async(uri, *args) ⇒ Object

Sends TRACE request in async style. See request_async2 for arguments. It immediately returns a HTTPClient::Connection instance as a result.



933
934
935
 
# File 'lib/httpclient.rb', line 933

def trace_async(uri, *args)
  request_async2(:trace, uri, argument_to_hash(args, :query, :header))
end