Protocol
This library provides your program functions to access WWW documents via HTTP, Hyper Text Transfer Protocol version 1.1. For details of HTTP, refer [RFC2616] (www.ietf.org/rfc/rfc2616.txt).
Example #1: Simple GET+print
require 'net/http' Net::HTTP.get_print 'www.example.com', '/index.html'
Example #2: Simple GET+print by URL
require 'net/http' require 'uri' Net::HTTP.get_print URI.parse('http://www.example.com/index.html')
Example #3: More generic GET+print
require 'net/http' require 'uri' url = URI.parse('http://www.example.com/index.html') res = Net::HTTP.start(url.host, url.port) {|http| http.get('/index.html') } puts res.body
Example #4: More generic GET+print
require 'net/http' url = URI.parse('http://www.example.com/index.html') req = Net::HTTP::Get.new(url.path) res = Net::HTTP.start(url.host, url.port) {|http| http.request(req) } puts res.body
require 'net/http' require 'uri' #1: Simple POST res = Net::HTTP.post_form(URI.parse('http://www.example.com/search.cgi'), {'q' => 'ruby', 'max' => '50'}) puts res.body #2: POST with basic authentication res = Net::HTTP.post_form(URI.parse('http://jack:pass@www.example.com/todo.cgi'), {'from' => '2005-01-01', 'to' => '2005-03-31'}) puts res.body #3: Detailed control url = URI.parse('http://www.example.com/todo.cgi') req = Net::HTTP::Post.new(url.path) req.basic_auth 'jack', 'pass' req.set_form_data({'from' => '2005-01-01', 'to' => '2005-03-31'}, ';') res = Net::HTTP.new(url.host, url.port).start {|http| http.request(req) } case res when Net::HTTPSuccess, Net::HTTPRedirection # OK else res.error! end #4: Multiple values res = Net::HTTP.post_form(URI.parse('http://www.example.com/search.cgi'), {'q' => ['ruby', 'perl'], 'max' => '50'}) puts res.body
Net::HTTP.Proxy creates http proxy class. It has same methods of Net::HTTP but its instances always connect to proxy, instead of given host.
require 'net/http' proxy_addr = 'your.proxy.host' proxy_port = 8080 : Net::HTTP::Proxy(proxy_addr, proxy_port).start('www.example.com') {|http| # always connect to your.proxy.addr:8080 : }
Since Net::HTTP.Proxy returns Net::HTTP itself when proxy_addr is nil, there's no need to change code if there's proxy or not.
There are two additional parameters in Net::HTTP.Proxy which allow to specify proxy user name and password:
Net::HTTP::Proxy(proxy_addr, proxy_port, proxy_user = nil, proxy_pass = nil)
You may use them to work with authorization-enabled proxies:
require 'net/http' require 'uri' proxy_host = 'your.proxy.host' proxy_port = 8080 uri = URI.parse(ENV['http_proxy']) proxy_user, proxy_pass = uri.userinfo.split(/:/) if uri.userinfo Net::HTTP::Proxy(proxy_host, proxy_port, proxy_user, proxy_pass).start('www.example.com') {|http| # always connect to your.proxy.addr:8080 using specified username and password : }
Note that net/http never rely on HTTP_PROXY environment variable. If you want to use proxy, set it explicitly.
require 'net/http' require 'uri' def fetch(uri_str, limit = 10) # You should choose better exception. raise ArgumentError, 'HTTP redirect too deep' if limit == 0 response = Net::HTTP.get_response(URI.parse(uri_str)) case response when Net::HTTPSuccess then response when Net::HTTPRedirection then fetch(response['location'], limit - 1) else response.error! end end print fetch('http://www.ruby-lang.org')
Net::HTTPSuccess and Net::HTTPRedirection is a HTTPResponse class. All HTTPResponse objects belong to its own response class which indicate HTTP result status. For details of response classes, see section “HTTP Response Classes”.
require 'net/http' Net::HTTP.start('www.example.com') {|http| req = Net::HTTP::Get.new('/secret-page.html') req.basic_auth 'account', 'password' response = http.request(req) print response.body }
Here is HTTP request class hierarchy.
Net::HTTPRequest Net::HTTP::Get Net::HTTP::Head Net::HTTP::Post Net::HTTP::Put Net::HTTP::Proppatch Net::HTTP::Lock Net::HTTP::Unlock Net::HTTP::Options Net::HTTP::Propfind Net::HTTP::Delete Net::HTTP::Move Net::HTTP::Copy Net::HTTP::Mkcol Net::HTTP::Trace
Here is HTTP response class hierarchy. All classes are defined in Net module.
HTTPResponse HTTPUnknownResponse HTTPInformation # 1xx HTTPContinue # 100 HTTPSwitchProtocl # 101 HTTPSuccess # 2xx HTTPOK # 200 HTTPCreated # 201 HTTPAccepted # 202 HTTPNonAuthoritativeInformation # 203 HTTPNoContent # 204 HTTPResetContent # 205 HTTPPartialContent # 206 HTTPRedirection # 3xx HTTPMultipleChoice # 300 HTTPMovedPermanently # 301 HTTPFound # 302 HTTPSeeOther # 303 HTTPNotModified # 304 HTTPUseProxy # 305 HTTPTemporaryRedirect # 307 HTTPClientError # 4xx HTTPBadRequest # 400 HTTPUnauthorized # 401 HTTPPaymentRequired # 402 HTTPForbidden # 403 HTTPNotFound # 404 HTTPMethodNotAllowed # 405 HTTPNotAcceptable # 406 HTTPProxyAuthenticationRequired # 407 HTTPRequestTimeOut # 408 HTTPConflict # 409 HTTPGone # 410 HTTPLengthRequired # 411 HTTPPreconditionFailed # 412 HTTPRequestEntityTooLarge # 413 HTTPRequestURITooLong # 414 HTTPUnsupportedMediaType # 415 HTTPRequestedRangeNotSatisfiable # 416 HTTPExpectationFailed # 417 HTTPServerError # 5xx HTTPInternalServerError # 500 HTTPNotImplemented # 501 HTTPBadGateway # 502 HTTPServiceUnavailable # 503 HTTPGatewayTimeOut # 504 HTTPVersionNotSupported # 505
You can use net/http.rb 1.1 features (bundled with Ruby 1.6) by calling Net::HTTP.version_1_1. Calling Net::HTTP.version_1_2 allows you to use 1.2 features again.
# example Net::HTTP.start {|http1| ...(http1 has 1.2 features)... } Net::HTTP.version_1_1 Net::HTTP.start {|http2| ...(http2 has 1.1 features)... } Net::HTTP.version_1_2 Net::HTTP.start {|http3| ...(http3 has 1.2 features)... }
This function is NOT thread-safe.
Creates an HTTP proxy class. Arguments are address/port of proxy host and username/password if authorization on proxy server is required. You can replace the HTTP class with created proxy class.
If ADDRESS is nil, this method returns self (Net::HTTP).
# Example proxy_class = Net::HTTP::Proxy('proxy.example.com', 8080) : proxy_class.start('www.ruby-lang.org') {|http| # connecting proxy.foo.org:8080 : }
# File net/http.rb, line 666 def HTTP.Proxy(p_addr, p_port = nil, p_user = nil, p_pass = nil) return self unless p_addr delta = ProxyDelta proxyclass = Class.new(self) proxyclass.module_eval { include delta # with proxy @is_proxy_class = true @proxy_address = p_addr @proxy_port = p_port || default_port() @proxy_user = p_user @proxy_pass = p_pass } proxyclass end
The default port to use for HTTP requests; defaults to 80.
# File net/http.rb, line 427 def HTTP.default_port http_default_port() end
Send a GET request to the target and return the response as a string. The
target can either be specified as (uri
), or as
(host
, path
, port
= 80); so:
print Net::HTTP.get(URI.parse('http://www.example.com/index.html'))
or:
print Net::HTTP.get('www.example.com', '/index.html')
# File net/http.rb, line 368 def HTTP.get(uri_or_host, path = nil, port = nil) get_response(uri_or_host, path, port).body end
Get body from target and output it to +$stdout+. The target can either be
specified as (uri
), or as (host
,
path
, port
= 80); so:
Net::HTTP.get_print URI.parse('http://www.example.com/index.html')
or:
Net::HTTP.get_print 'www.example.com', '/index.html'
# File net/http.rb, line 349 def HTTP.get_print(uri_or_host, path = nil, port = nil) get_response(uri_or_host, path, port) {|res| res.read_body do |chunk| $stdout.print chunk end } nil end
Send a GET request to the target and return the response as a Net::HTTPResponse object. The target can
either be specified as (uri
), or as (host
,
path
, port
= 80); so:
res = Net::HTTP.get_response(URI.parse('http://www.example.com/index.html')) print res.body
or:
res = Net::HTTP.get_response('www.example.com', '/index.html') print res.body
# File net/http.rb, line 384 def HTTP.get_response(uri_or_host, path = nil, port = nil, &block) if path host = uri_or_host new(host, port || HTTP.default_port).start {|http| return http.request_get(path, &block) } else uri = uri_or_host new(uri.host, uri.port).start {|http| return http.request_get(uri.request_uri, &block) } end end
The default port to use for HTTP requests; defaults to 80.
# File net/http.rb, line 432 def HTTP.http_default_port 80 end
The default port to use for HTTPS requests; defaults to 443.
# File net/http.rb, line 437 def HTTP.https_default_port 443 end
Creates a new Net::HTTP object. If proxy_addr
is given,
creates an Net::HTTP object with proxy support. This method does not open
the TCP connection.
# File net/http.rb, line 463 def HTTP.new(address, port = nil, p_addr = nil, p_port = nil, p_user = nil, p_pass = nil) h = Proxy(p_addr, p_port, p_user, p_pass).newobj(address, port) h.instance_eval { @newimpl = ::Net::HTTP.version_1_2? } h end
Creates a new Net::HTTP object for the specified address
. This
method does not open the TCP connection.
# File net/http.rb, line 473 def initialize(address, port = nil) @address = address @port = (port || HTTP.default_port) @curr_http_version = HTTPVersion @no_keepalive_server = false @close_on_empty_response = false @socket = nil @started = false @open_timeout = nil @read_timeout = 60 @debug_output = nil @use_ssl = false @ssl_context = nil @enable_post_connection_check = true @compression = nil @sspi_enabled = false if defined?(SSL_ATTRIBUTES) SSL_ATTRIBUTES.each do |name| instance_variable_set "@#{name}", nil end end end
Posts HTML form data to the URL
. Form data must be represented
as a Hash of String to String, e.g:
{ "cmd" => "search", "q" => "ruby", "max" => "50" }
This method also does Basic Authentication iff URL
.user
exists.
Example:
require 'net/http' require 'uri' HTTP.post_form URI.parse('http://www.example.com/search.cgi'), { "q" => "ruby", "max" => "50" }
# File net/http.rb, line 413 def HTTP.post_form(url, params) req = Post.new(url.path) req.form_data = params req.basic_auth url.user, url.password if url.user new(url.host, url.port).start {|http| http.request(req) } end
returns true if self is a class which was created by HTTP::Proxy.
# File net/http.rb, line 684 def proxy_class? @is_proxy_class end
creates a new Net::HTTP object and opens its TCP connection and HTTP session. If the optional block is given, the newly created Net::HTTP object is passed to it and closed when the block finishes. In this case, the return value of this method is the return value of the block. If no block is given, the return value of this method is the newly created Net::HTTP object itself, and the caller is responsible for closing it upon completion.
# File net/http.rb, line 452 def HTTP.start(address, port = nil, p_addr = nil, p_port = nil, p_user = nil, p_pass = nil, &block) # :yield: +http+ new(address, port, p_addr, p_port, p_user, p_pass).start(&block) end
Turns on net/http 1.1 (ruby 1.6) features. Defaults to OFF in ruby 1.8.
# File net/http.rb, line 313 def HTTP.version_1_1 @newimpl = false end
true if net/http is in version 1.1 compatible mode. Defaults to true.
# File net/http.rb, line 325 def HTTP.version_1_1? not @newimpl end
Turns on net/http 1.2 (ruby 1.8) features. Defaults to ON in ruby 1.8.
I strongly recommend to call this method always.
require 'net/http' Net::HTTP.version_1_2
# File net/http.rb, line 307 def HTTP.version_1_2 @newimpl = true end
true if net/http is in version 1.2 mode. Defaults to true.
# File net/http.rb, line 319 def HTTP.version_1_2? @newimpl end
Sends a COPY request to the path
and gets a response, as an HTTPResponse object.
# File net/http.rb, line 965 def copy(path, initheader = nil) request(Copy.new(path, initheader)) end
Sends a DELETE request to the path
and gets a response, as an
HTTPResponse object.
# File net/http.rb, line 953 def delete(path, initheader = {'Depth' => 'Infinity'}) request(Delete.new(path, initheader)) end
Finishes HTTP session and closes TCP connection. Raises IOError if not started.
# File net/http.rb, line 626 def finish raise IOError, 'HTTP session not yet started' unless started? do_finish end
Gets data from path
on the connected-to host.
initheader
must be a Hash like { 'Accept' =>
'/', … }, and it defaults to an empty hash. If
initheader
doesn't have the key 'accept-encoding',
then a value of “gzip;q=1.0,deflate;q=0.6,identity;q=0.3” is used, so that
gzip compression is used in preference to deflate compression, which is
used in preference to no compression. Ruby doesn't have libraries to
support the compress (Lempel-Ziv) compression, so that is not supported.
The intent of this is to reduce bandwidth by default. If this routine
sets up compression, then it does the decompression also, removing the
header as well to prevent confusion. Otherwise it leaves the body as it
found it.
In version 1.1 (ruby 1.6), this method returns a pair of objects, a Net::HTTPResponse object and the entity body string. In version 1.2 (ruby 1.8), this method returns a Net::HTTPResponse object.
If called with a block, yields each fragment of the entity body in turn as a string as it is read from the socket. Note that in this case, the returned response object will not contain a (meaningful) body.
dest
argument is obsolete. It still works but you must not use
it.
In version 1.1, this method might raise an exception for 3xx (redirect). In this case you can get a HTTPResponse object by “anException.response”.
In version 1.2, this method never raises exception.
# version 1.1 (bundled with Ruby 1.6) response, body = http.get('/index.html') # version 1.2 (bundled with Ruby 1.8 or later) response = http.get('/index.html') # using block File.open('result.txt', 'w') {|f| http.get('/~foo/') do |str| f.write str end }
# File net/http.rb, line 806 def get(path, initheader = {}, dest = nil, &block) # :yield: +body_segment+ res = nil if HAVE_ZLIB unless initheader.keys.any?{|k| k.downcase == "accept-encoding"} initheader["accept-encoding"] = "gzip;q=1.0,deflate;q=0.6,identity;q=0.3" @compression = true end end request(Get.new(path, initheader)) {|r| if r.key?("content-encoding") and @compression @compression = nil # Clear it till next set. the_body = r.read_body dest, &block case r["content-encoding"] when "gzip" r.body= Zlib::GzipReader.new(StringIO.new(the_body)).read r.delete("content-encoding") when "deflate" r.body= Zlib::Inflate.inflate(the_body); r.delete("content-encoding") when "identity" ; # nothing needed else ; # Don't do anything dramatic, unless we need to later end else r.read_body dest, &block end res = r } unless @newimpl res.value return res, res.body end res end
Gets only the header from path
on the connected-to host.
header
is a Hash like { 'Accept' =>
'/', … }.
This method returns a Net::HTTPResponse object.
In version 1.1, this method might raise an exception for 3xx (redirect). On the case you can get a HTTPResponse object by “anException.response”. In version 1.2, this method never raises an exception.
response = nil Net::HTTP.start('some.www.server', 80) {|http| response = http.head('/index.html') } p response['content-type']
# File net/http.rb, line 859 def head(path, initheader = nil) res = request(Head.new(path, initheader)) res.value unless @newimpl res end
# File net/http.rb, line 496 def inspect "#<#{self.class} #{@address}:#{@port} open=#{started?}>" end
Sends a LOCK request to the path
and gets a response, as an HTTPResponse object.
# File net/http.rb, line 929 def lock(path, body, initheader = nil) request(Lock.new(path, initheader), body) end
Sends a MKCOL request to the path
and gets a response, as an
HTTPResponse object.
# File net/http.rb, line 971 def mkcol(path, body = nil, initheader = nil) request(Mkcol.new(path, initheader), body) end
Sends a MOVE request to the path
and gets a response, as an HTTPResponse object.
# File net/http.rb, line 959 def move(path, initheader = nil) request(Move.new(path, initheader)) end
Sends a OPTIONS request to the path
and gets a response, as an
HTTPResponse object.
# File net/http.rb, line 941 def options(path, initheader = nil) request(Options.new(path, initheader)) end
Posts data
(must be a String) to path
.
header
must be a Hash like { 'Accept' =>
'/', … }.
In version 1.1 (ruby 1.6), this method returns a pair of objects, a Net::HTTPResponse object and an entity body string. In version 1.2 (ruby 1.8), this method returns a Net::HTTPResponse object.
If called with a block, yields each fragment of the entity body in turn as a string as it are read from the socket. Note that in this case, the returned response object will not contain a (meaningful) body.
dest
argument is obsolete. It still works but you must not use
it.
In version 1.1, this method might raise an exception for 3xx (redirect). In this case you can get an HTTPResponse object by “anException.response”. In version 1.2, this method never raises exception.
# version 1.1 response, body = http.post('/cgi-bin/search.rb', 'query=foo') # version 1.2 response = http.post('/cgi-bin/search.rb', 'query=foo') # using block File.open('result.txt', 'w') {|f| http.post('/cgi-bin/search.rb', 'query=foo') do |str| f.write str end }
You should set Content-Type: header field for POST. If no Content-Type: field given, this method uses “application/x-www-form-urlencoded” by default.
# File net/http.rb, line 902 def post(path, data, initheader = nil, dest = nil, &block) # :yield: +body_segment+ res = nil request(Post.new(path, initheader), data) {|r| r.read_body dest, &block res = r } unless @newimpl res.value return res, res.body end res end
Sends a PROPFIND request to the path
and gets a response, as
an HTTPResponse object.
# File net/http.rb, line 947 def propfind(path, body = nil, initheader = {'Depth' => '0'}) request(Propfind.new(path, initheader), body) end
Sends a PROPPATCH request to the path
and gets a response, as
an HTTPResponse object.
# File net/http.rb, line 923 def proppatch(path, body, initheader = nil) request(Proppatch.new(path, initheader), body) end
True if self is a HTTP proxy class.
# File net/http.rb, line 695 def proxy? self.class.proxy_class? end
Address of proxy host. If self does not use a proxy, nil.
# File net/http.rb, line 700 def proxy_address self.class.proxy_address end
User password for accessing proxy. If self does not use a proxy, nil.
# File net/http.rb, line 715 def proxy_pass self.class.proxy_pass end
Port number of proxy host. If self does not use a proxy, nil.
# File net/http.rb, line 705 def proxy_port self.class.proxy_port end
User name for accessing proxy. If self does not use a proxy, nil.
# File net/http.rb, line 710 def proxy_user self.class.proxy_user end
Setter for the #read_timeout attribute.
# File net/http.rb, line 531 def read_timeout=(sec) @socket.read_timeout = sec if @socket @read_timeout = sec end
Sends an HTTPRequest object REQUEST to the HTTP server. This method also sends DATA string if REQUEST is a post/put request. Giving DATA for get/head request causes ArgumentError.
When called with a block, yields an HTTPResponse object. The body of this response will not have been read yet; the caller can process it using Net::HTTPResponse#read_body, if desired.
Returns a HTTPResponse object.
This method never raises Net::* exceptions.
# File net/http.rb, line 1092 def request(req, body = nil, &block) # :yield: +response+ unless started? start { req['connection'] ||= 'close' return request(req, body, &block) } end if proxy_user() req.proxy_basic_auth proxy_user(), proxy_pass() unless use_ssl? end req.set_body_internal body res = transport_request(req, &block) if sspi_auth?(res) sspi_auth(req) res = transport_request(req, &block) end res end
Sends a GET request to the path
and gets a response, as an HTTPResponse object.
When called with a block, yields an HTTPResponse object. The body of this response will not have been read yet; the caller can process it using Net::HTTPResponse#read_body, if desired.
Returns the response.
This method never raises Net::* exceptions.
response = http.request_get('/index.html') # The entity body is already read here. p response['content-type'] puts response.body # using block http.request_get('/index.html') {|response| p response['content-type'] response.read_body do |str| # read body now print str end }
# File net/http.rb, line 1006 def request_get(path, initheader = nil, &block) # :yield: +response+ request(Get.new(path, initheader), &block) end
Sends a HEAD request to the path
and gets a response, as an HTTPResponse object.
Returns the response.
This method never raises Net::* exceptions.
response = http.request_head('/index.html') p response['content-type']
# File net/http.rb, line 1020 def request_head(path, initheader = nil, &block) request(Head.new(path, initheader), &block) end
Sends a POST request to the path
and gets a response, as an HTTPResponse object.
When called with a block, yields an HTTPResponse object. The body of this response will not have been read yet; the caller can process it using Net::HTTPResponse#read_body, if desired.
Returns the response.
This method never raises Net::* exceptions.
# example response = http.request_post('/cgi-bin/nice.rb', 'datadatadata...') p response.status puts response.body # body is already read # using block http.request_post('/cgi-bin/nice.rb', 'datadatadata...') {|response| p response.status p response['content-type'] response.read_body do |str| # read body now print str end }
# File net/http.rb, line 1050 def request_post(path, data, initheader = nil, &block) # :yield: +response+ request Post.new(path, initheader), data, &block end
Sends an HTTP request to the HTTP server. This method also sends DATA string if DATA is given.
Returns a HTTPResponse object.
This method never raises Net::* exceptions.
response = http.send_request('GET', '/index.html') puts response.body
# File net/http.rb, line 1074 def send_request(name, path, data = nil, header = nil) r = HTTPGenericRequest.new(name,(data ? true : false),true,path,header) request r, data end
WARNING This method causes serious security hole. Never use this method in production code.
Set an output stream for debugging.
http = Net::HTTP.new http.set_debug_output $stderr http.start { .... }
# File net/http.rb, line 509 def set_debug_output(output) warn 'Net::HTTP#set_debug_output called after HTTP started' if started? @debug_output = output end
Opens TCP connection and HTTP session.
When this method is called with block, gives a HTTP object to the block and closes the TCP connection / HTTP session after the block executed.
When called with a block, returns the return value of the block; otherwise, returns self.
# File net/http.rb, line 559 def start # :yield: http raise IOError, 'HTTP session already opened' if @started if block_given? begin do_start return yield(self) ensure do_finish end end do_start self end
returns true if the HTTP session is started.
# File net/http.rb, line 537 def started? @started end
Sends a TRACE request to the path
and gets a response, as an
HTTPResponse object.
# File net/http.rb, line 977 def trace(path, initheader = nil) request(Trace.new(path, initheader)) end
Sends a UNLOCK request to the path
and gets a response, as an
HTTPResponse object.
# File net/http.rb, line 935 def unlock(path, body, initheader = nil) request(Unlock.new(path, initheader), body) end