Class: HTTPClient
- Inherits:
-
Object
- Object
- HTTPClient
- 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/include_client.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.('/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 and get_content.
-
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
-
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/')
-
You can pass :follow_redirect option to follow redirect response in get.
puts clnt.get('http://dev.ctor.org/', :follow_redirect => true)
-
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.body
You can also use keyword argument style.
res = clnt.get(uri, :query => { :keyword => 'ruby', :lang => 'en' })
How to POST
See post.
-
Do POST a form data.
body = { 'keyword' => 'ruby', 'lang' => 'en' } res = clnt.post(uri, body)
Keyword argument style.
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
-
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.
-
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)
-
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(https_url)
Handling Cookies
-
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.
-
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.('/home/nahi/cookie.dat') clnt.get(url) ... clnt.
-
Disabling Cookies.
clnt = HTTPClient.new clnt. = 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('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(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
Defined Under Namespace
Modules: DebugSocket, IncludeClient, SocketWrap, Timeout, Util Classes: AuthFilterBase, BadResponseError, BasicAuth, ConfigurationError, ConnectTimeoutError, Connection, DigestAuth, KeepAliveDisconnected, LoopBackSocket, NegotiateAuth, OAuth, ProxyAuth, ProxyBasicAuth, ProxyDigestAuth, ReceiveTimeoutError, RetryableResponse, SSLConfig, SSLSocketWrap, 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.5.3'
Instance Attribute Summary collapse
-
#base_url ⇒ Object
Base url of resources.
-
#cookie_manager ⇒ Object
- WebAgent::CookieManager
-
Cookies configurator.
-
#default_header ⇒ Object
Defalut request header.
-
#follow_redirect_count ⇒ Object
How many times get_content and post_content follows HTTP redirect.
-
#proxy_auth ⇒ Object
readonly
- HTTPClient::ProxyAuth
-
Proxy authentication handler.
-
#request_filter ⇒ Object
readonly
An array of request filter which can trap HTTP request/response.
-
#ssl_config ⇒ Object
readonly
- HTTPClient::SSLConfig
-
SSL configurator.
-
#test_loopback_response ⇒ Object
readonly
An array of response HTTP message body String which is used for loop-back test.
-
#www_auth ⇒ Object
readonly
- HTTPClient::WWWAuth
-
WWW authentication handler.
Class Method Summary collapse
-
.timeout_scheduler ⇒ Object
CAUTION: caller must aware of race condition.
Instance Method Summary collapse
-
#cookies ⇒ Object
Returns stored cookies.
-
#debug_dev ⇒ Object
Returns debug device if exists.
-
#debug_dev=(dev) ⇒ Object
Sets debug device.
-
#default_redirect_uri_callback(uri, res) ⇒ Object
A default method for redirect uri callback.
-
#delete(uri, *args, &block) ⇒ Object
Sends DELETE request to the specified URL.
-
#delete_async(uri, *args) ⇒ Object
Sends DELETE request in async style.
-
#force_basic_auth=(force_basic_auth) ⇒ Object
Turn on/off the BasicAuth force flag.
-
#get(uri, *args, &block) ⇒ Object
Sends GET request to the specified URL.
-
#get_async(uri, *args) ⇒ Object
Sends GET request in async style.
-
#get_content(uri, *args, &block) ⇒ Object
Retrieves a web resource.
-
#head(uri, *args) ⇒ Object
Sends HEAD request to the specified URL.
-
#head_async(uri, *args) ⇒ Object
Sends HEAD request in async style.
-
#initialize(*args) ⇒ HTTPClient
constructor
Creates a HTTPClient instance which manages sessions, cookies, etc.
-
#keep_webmock_compat ⇒ Object
webmock 1.6.2 depends on HTTP::Message#body.content to work.
-
#no_proxy ⇒ Object
Returns NO_PROXY setting String if given.
-
#no_proxy=(no_proxy) ⇒ Object
Sets NO_PROXY setting String.
-
#options(uri, *args, &block) ⇒ Object
Sends OPTIONS request to the specified URL.
-
#options_async(uri, *args) ⇒ Object
Sends OPTIONS request in async style.
-
#post(uri, *args, &block) ⇒ Object
Sends POST request to the specified URL.
-
#post_async(uri, *args) ⇒ Object
Sends POST request in async style.
-
#post_content(uri, *args, &block) ⇒ Object
Posts a content.
-
#propfind(uri, *args, &block) ⇒ Object
Sends PROPFIND request to the specified URL.
-
#propfind_async(uri, *args) ⇒ Object
Sends PROPFIND request in async style.
-
#proppatch(uri, *args, &block) ⇒ Object
Sends PROPPATCH request to the specified URL.
-
#proppatch_async(uri, *args) ⇒ Object
Sends PROPPATCH request in async style.
-
#proxy ⇒ Object
Returns URI object of HTTP proxy if exists.
-
#proxy=(proxy) ⇒ Object
Sets HTTP proxy used for HTTP connection.
-
#put(uri, *args, &block) ⇒ Object
Sends PUT request to the specified URL.
-
#put_async(uri, *args) ⇒ Object
Sends PUT request in async style.
-
#redirect_uri_callback=(redirect_uri_callback) ⇒ Object
Sets callback proc when HTTP redirect status is returned for get_content and post_content.
-
#request(method, uri, *args, &block) ⇒ Object
Sends a request to the specified URL.
-
#request_async(method, uri, query = nil, body = nil, header = {}) ⇒ Object
Sends a request in async style.
-
#request_async2(method, uri, *args) ⇒ Object
new method that has same signature as ‘request’.
-
#reset(uri) ⇒ Object
Resets internal session for the given URL.
-
#reset_all ⇒ Object
Resets all of internal sessions.
-
#save_cookie_store ⇒ Object
Try to save Cookies to the file specified in set_cookie_store.
-
#set_auth(domain, user, passwd) ⇒ Object
Sets credential for Web server authentication.
-
#set_basic_auth(domain, user, passwd) ⇒ Object
Deprecated.
-
#set_cookie_store(filename) ⇒ Object
Sets the filename where non-volatile Cookies be saved by calling save_cookie_store.
-
#set_proxy_auth(user, passwd) ⇒ Object
Sets credential for Proxy authentication.
-
#strict_redirect_uri_callback(uri, res) ⇒ Object
A method for redirect uri callback.
-
#trace(uri, *args, &block) ⇒ Object
Sends TRACE request to the specified URL.
-
#trace_async(uri, *args) ⇒ Object
Sends TRACE request in async style.
Methods included from Util
#argument_to_hash, hash_find_value, #http?, #https?, #keyword_argument, try_require, uri_dirname, uri_part_of, urify
Constructor Details
#initialize(*args) ⇒ 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.
: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.
399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 |
# File 'lib/httpclient.rb', line 399 def initialize(*args) 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 = WebAgent::CookieManager.new @follow_redirect_count = 10 load_environment self.proxy = proxy if proxy keep_webmock_compat end |
Instance Attribute Details
#base_url ⇒ Object
Base url of resources.
328 329 330 |
# File 'lib/httpclient.rb', line 328 def base_url @base_url end |
#cookie_manager ⇒ Object
- WebAgent::CookieManager
-
Cookies configurator.
312 313 314 |
# File 'lib/httpclient.rb', line 312 def @cookie_manager end |
#default_header ⇒ Object
Defalut request header.
330 331 332 |
# File 'lib/httpclient.rb', line 330 def default_header @default_header end |
#follow_redirect_count ⇒ Object
How many times get_content and post_content follows HTTP redirect. 10 by default.
326 327 328 |
# File 'lib/httpclient.rb', line 326 def follow_redirect_count @follow_redirect_count end |
#proxy_auth ⇒ Object (readonly)
- HTTPClient::ProxyAuth
-
Proxy authentication handler.
321 322 323 |
# File 'lib/httpclient.rb', line 321 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.
319 320 321 |
# File 'lib/httpclient.rb', line 319 def request_filter @request_filter end |
#ssl_config ⇒ Object (readonly)
- HTTPClient::SSLConfig
-
SSL configurator.
310 311 312 |
# File 'lib/httpclient.rb', line 310 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.
316 317 318 |
# File 'lib/httpclient.rb', line 316 def test_loopback_response @test_loopback_response end |
#www_auth ⇒ Object (readonly)
- HTTPClient::WWWAuth
-
WWW authentication handler.
323 324 325 |
# File 'lib/httpclient.rb', line 323 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.
585 586 587 588 589 |
# File 'lib/httpclient.rb', line 585 def if @cookie_manager @cookie_manager. end end |
#debug_dev ⇒ Object
Returns debug device if exists. See debug_dev=.
441 442 443 |
# File 'lib/httpclient.rb', line 441 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.
449 450 451 452 453 |
# File 'lib/httpclient.rb', line 449 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.
693 694 695 696 697 698 699 700 701 702 703 704 705 |
# File 'lib/httpclient.rb', line 693 def default_redirect_uri_callback(uri, res) newuri = urify(res.header['location'][0]) if !http?(newuri) && !https?(newuri) newuri = uri + newuri warn("could be a relative URI in location header which is not recommended") warn("'The field value consists of a single absolute URI' in HTTP spec") 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.
740 741 742 |
# File 'lib/httpclient.rb', line 740 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.
863 864 865 |
# File 'lib/httpclient.rb', line 863 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.
562 563 564 |
# File 'lib/httpclient.rb', line 562 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.
713 714 715 |
# File 'lib/httpclient.rb', line 713 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.
835 836 837 |
# File 'lib/httpclient.rb', line 835 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.
624 625 626 627 |
# File 'lib/httpclient.rb', line 624 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.
708 709 710 |
# File 'lib/httpclient.rb', line 708 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.
829 830 831 |
# File 'lib/httpclient.rb', line 829 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.
427 428 429 430 431 432 433 434 435 436 437 438 |
# File 'lib/httpclient.rb', line 427 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.
491 492 493 |
# File 'lib/httpclient.rb', line 491 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.
506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 |
# File 'lib/httpclient.rb', line 506 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.
745 746 747 748 |
# File 'lib/httpclient.rb', line 745 def (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.
869 870 871 |
# File 'lib/httpclient.rb', line 869 def (uri, *args) request_async2(:options, uri, argument_to_hash(args, :header, :query, :body)) 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.
720 721 722 723 724 725 726 727 |
# File 'lib/httpclient.rb', line 720 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.
841 842 843 844 845 846 847 848 |
# File 'lib/httpclient.rb', line 841 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.
661 662 663 664 665 666 667 668 669 |
# File 'lib/httpclient.rb', line 661 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.
751 752 753 |
# File 'lib/httpclient.rb', line 751 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.
875 876 877 |
# File 'lib/httpclient.rb', line 875 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.
756 757 758 |
# File 'lib/httpclient.rb', line 756 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.
881 882 883 |
# File 'lib/httpclient.rb', line 881 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.
456 457 458 |
# File 'lib/httpclient.rb', line 456 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.
470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 |
# File 'lib/httpclient.rb', line 470 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.
730 731 732 733 734 735 736 737 |
# File 'lib/httpclient.rb', line 730 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.
852 853 854 855 856 857 858 859 |
# File 'lib/httpclient.rb', line 852 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)
599 600 601 |
# File 'lib/httpclient.rb', line 599 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.
803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 |
# File 'lib/httpclient.rb', line 803 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.
895 896 897 898 |
# File 'lib/httpclient.rb', line 895 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’
901 902 903 904 905 906 907 908 909 910 911 912 913 |
# File 'lib/httpclient.rb', line 901 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.
917 918 919 920 |
# File 'lib/httpclient.rb', line 917 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.
923 924 925 |
# File 'lib/httpclient.rb', line 923 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. (interface mismatch between WebAgent::CookieManager implementation)
580 581 582 |
# File 'lib/httpclient.rb', line 580 def @cookie_manager. 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.
535 536 537 538 539 |
# File 'lib/httpclient.rb', line 535 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.
542 543 544 545 546 |
# File 'lib/httpclient.rb', line 542 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.
571 572 573 574 575 |
# File 'lib/httpclient.rb', line 571 def (filename) @cookie_manager. = filename @cookie_manager. 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.
553 554 555 556 |
# File 'lib/httpclient.rb', line 553 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)
676 677 678 679 680 681 682 683 684 685 686 |
# File 'lib/httpclient.rb', line 676 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.
761 762 763 |
# File 'lib/httpclient.rb', line 761 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.
887 888 889 |
# File 'lib/httpclient.rb', line 887 def trace_async(uri, *args) request_async2(:trace, uri, argument_to_hash(args, :query, :header)) end |