Ruby » Ruby master

  # Net::HTTP provides a rich library which can be used to build HTTP

  # user-agents.  For more details about HTTP see

  # [RFC2616](http://www.ietf.org/rfc/rfc2616.txt)

  # Net::HTTP is designed to work closely with URI.  URI::HTTP#host,

  # URI::HTTP#port and URI::HTTP#request_uri are designed to work with

  # Net::HTTP.

  # If you are only performing a few GET requests you should try OpenURI.

  # == How to use Net::HTTP

  # Net::HTTP provides several convenience methods for performing a GET on a

  # web server which are described below.

  #

  # All examples assume you have loaded Net::HTTP with:

  #

  #   require 'net/http'

  #

  # This will also require 'uri' so you don't need to require it separately.

  #

  # The following example code can be used as the basis of a HTTP user-agent

  # which will perform a variety of request types.

  #

  #   uri = URI.parse 'http://example.com/some_path?query=string'

  #

  #   Net::HTTP.start uri.host, uri.port do |http|

  #     request = Net::HTTP::Get.new uri.request_uri

  #

  #     response = http.request request # Net::HTTPResponse object

  #   end

  #

  # Net::HTTP::start immediately creates a connection to an HTTP server which

  # is kept open for the duration of the block.  The connection will remain

  # open for multiple requests in the block if the server indicates it

  # supports persistent connections.

  #

  # The request types Net::HTTP supports are listed below in the section "HTTP

  # Request Classes".

  #

  # If you wish to re-use a connection across multiple HTTP requests without

  # automatically closing it you can use ::new instead of ::start.  #request

  # will automatically open a connection to the server if one is not currently

  # open.  You can manually close the connection with #close.

  #

  # === Response Data

  #

  #   uri = URI.parse('http://example.com/index.html')

  #   res = Net::HTTP.get_response(uri)

  #

  #   # Headers

  #   res['Set-Cookie']            # => String

  #   res.get_fields('set-cookie') # => Array

  #   res.to_hash['set-cookie']    # => Array

  #   puts "Headers: #{res.to_hash.inspect}"

  #

  #   # Status

  #   puts res.code       # => '200'

  #   puts res.message    # => 'OK'

  #   puts res.class.name # => 'HTTPOK'

  #

  #   # Body

  #   puts res.body if res.response_body_permitted?

  #

  # === Following Redirection

  #

  # Each Net::HTTPResponse object belongs to a class for its response code.

  #

  # For example, all 2XX responses are instances of a Net::HTTPSuccess

  # subclass, a 3XX response is an instance of a Net::HTTPRedirection

  # subclass and a 200 response is an instance of the Net::HTTPOK class.  For

  # details of response classes, see the section "HTTP Response Classes"

  # below.

  #

  # Using a case statement you can handle various types of responses properly:

  #

  #   def fetch(uri_str, limit = 10)

  #     # You should choose a better exception.

  #     raise ArgumentError, 'too many HTTP redirects' if limit == 0

  #

  #     response = Net::HTTP.get_response(URI.parse(uri_str))

  #

  #     case response

  #     when Net::HTTPSuccess then

  #       response

  #     when Net::HTTPRedirection then

  #       location = response['location']

  #       warn "redirected to #{location}"

  #       fetch(location, limit - 1)

  #       # turns a response object into an error class and raises it

  #       response.error!

  #   end

  #   print fetch('http://www.ruby-lang.org')

  # === POST

  # A POST can be made using the Net::HTTP::Post request class.  This example

  # creates a urlencoded POST body:

  #   uri = URI.parse('http://www.example.com/todo.cgi')

  #   req = Net::HTTP::Post.new(uri.path)

  #   req.set_form_data('from' => '2005-01-01', 'to' => '2005-03-31')

  #   res = Net::HTTP.new(uri.hostname, uri.port).start do |http|

  #     http.request(req)

  #   end

  #   case res

  #   when Net::HTTPSuccess, Net::HTTPRedirection

  #     # OK

  #   else

  #     res.error!

  #   end

  # At this time Net::HTTP does not support multipart/form-data.  To send

  # multipart/form-data use Net::HTTPRequest#body= and

  # Net::HTTPRequest#content_type=:

  #

  #   req = Net::HTTP::Post.new(uri.path)

  #   req.body = multipart_data

  #   req.content_type = 'multipart/form-data'

  #

  # Other requests that can contain a body such as PUT can be created in the

  # same way using the corresponding request class (Net::HTTP::Put).

  #

  # === Setting Headers

  #

  # The following example performs a conditional GET using the

  # If-Modified-Since header.  If the files has not been modified since the

  # time in the header a Not Modified response will be returned.  See RFC 2616

  # section 9.3 for further details.

  #

  #   uri = URI.parse('http://example.com/cached_response')

  #   file = File.stat 'cached_response'

  #

  #   req = Net::HTTP::Get.new(uri.request_uri)

  #   req['If-Modified-Since'] = file.mtime.rfc2822

  #

  #   res = Net::HTTP.start(uri.hostname, uri.port) {|http|

  #     http.request(req)

  #   }

  #

  #   open 'cached_response', 'w' do |io|

  #     io.write res.body

  #   end if res.is_a?(Net::HTTPSuccess)

  #

  # === Basic Authentication

  #

  # Basic authentication is performed according to

  # [RFC2617](http://www.ietf.org/rfc/rfc2617.txt)

  # 

  #   uri = URI.parse('http://example.com/index.html?key=value')

  #

  #   req = Net::HTTP::Get.new(uri.request_uri)

  #   req.basic_auth 'user', 'pass'

  #

  #   res = Net::HTTP.start(uri.hostname, uri.port) {|http|

  #     http.request(req)

  #   }

  #   puts res.body

  #

  # === Streaming Response Bodies

  #

  # By default Net::HTTP reads an entire response into memory.  If you are

  # handling large files or wish to implement a progress bar you can instead

  # stream the body directly to an IO.

  #   uri = URI.parse 'http://example.com/large_file'

  #   Net::HTTP.start uri.host, uri.port do |http|

  #     request = Net::HTTP::Get.new uri.request_uri

  #

  #     http.request request do |response|

  #       open 'large_file', 'w' do |io|

  #         response.read_body do |chunk|

  #           io.write chunk

  #         end

  #   end

  #

  # === HTTPS

  #

  # HTTPS is enabled for an HTTP connection by Net::HTTP#use_ssl=.

  #

  #   uri = URI.parse 'https://secure.example.com/some_path?query=string'

  #

  #   Net::HTTP.new uri.host, uri.port

  #   http.use_ssl = uri.scheme == 'https'

  #

  #   http.start do

  #     request = Net::HTTP::Get.new uri.request_uri

  #

  #     response = http.request request # Net::HTTPResponse object

  #   end

  #

  # In previous versions of ruby you would need to require 'net/https' to use

  # HTTPS.  This is no longer true.

  #

  # === Proxies

  # Net::HTTP::Proxy has the same methods as Net::HTTP but its instances always

  # connect via the proxy, instead of given host.

  #

  #   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

  #   }

  #

  # Net::HTTP::Proxy returns a Net::HTTP instance when proxy_addr is nil so

  # there is no need for conditional code.

  #

  # See Net::HTTP::Proxy for further details and examples such as proxies that

  # require a username and password.

  #

  # == Simple Examples

  #

  # The Net::HTTP methods in the following examples do not persist

  # connections.  They are not recommended if you are performing many HTTP

  # requests.

  #

  # === GET

  #

  #   Net::HTTP.get('example.com', '/index.html') # => String

  #

  # === GET by URI

  #

  #   uri = URI.parse('http://example.com/index.html?count=10')

  #   Net::HTTP.get(uri) # => String

  #

  # === GET with Dynamic Parameters

  #

  #   uri = URI.parse('http://example.com/index.html')

  #   params = { :limit => 10, :page => 3 }

  #   uri.query = URI.encode_www_form(params)

  #

  #   res = Net::HTTP.get_response(uri)

  #   puts res.body if res.is_a?(Net::HTTPSuccess)

  #

  # === POST

  #

  #   uri = URI.parse('http://www.example.com/search.cgi')

  #   res = Net::HTTP.post_form(uri, 'q' => 'ruby', 'max' => '50')

  #   puts res.body

  #

  # === POST with Multiple Values

  #

  #   uri = URI.parse('http://www.example.com/search.cgi')

  #   res = Net::HTTP.post_form(uri, 'q' => ['ruby', 'perl'], 'max' => '50')

  #   puts res.body

  #

  # == HTTP Request Classes

  #

  # Here is the 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

  #

  # == HTTP Response Classes

  #

  # Here is HTTP response class hierarchy.  All classes are defined in Net

  # module and are subclasses of Net::HTTPResponse.

  #

  # HTTPUnknownResponse:: For unhandled HTTP extenensions

  # HTTPInformation::                    1xx

  #   HTTPContinue::                        100

  #   HTTPSwitchProtocol::                  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

  #

  # There is also the Net::HTTPBadResponse exception which is raised when

  # there is a protocol error.

  # You can use net/http.rb 1.1 features (bundled with Ruby 1.6) by calling

  # HTTP.version_1_1. Calling Net::HTTP.version_1_2 allows you to use 1.2

  # features again.  Do not confuse this with HTTP protocol features.

  #   # 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)... }

    # returns true if this session will use SSL or TLS.

    #

    # This flag must be set before starting a session.  If you change use_ssl

    # value after session started, a Net::HTTP object raises IOError.

    # Sets path of a CA certification file in PEM format.

    #

    # The file can contain several CA certificates.

    attr_accessor :ca_file

    # Sets path of a CA certification directory containing certifications in

    # PEM format.

    attr_accessor :ca_path

    # Sets an OpenSSL::X509::Certificate object as client certificate.

    # (This method is appeared in Michal Rokos's OpenSSL extension).

    attr_accessor :cert

    # Sets the X509::Store to verify peer certificate.

    attr_accessor :cert_store

    # Sets the available ciphers.  See OpenSSL::SSL::SSLContext#ciphers=

    attr_accessor :ciphers

    # Sets an OpenSSL::PKey::RSA or OpenSSL::PKey::DSA object.

    # (This method is appeared in Michal Rokos's OpenSSL extension.)

    attr_accessor :key

    # Sets the SSL timeout seconds.

    attr_accessor :ssl_timeout

    # Sets the SSL version.  See OpenSSL::SSL::SSLContext#ssl_version=

    attr_accessor :ssl_version

    # Sets the verify callback for the server certification verification.

    attr_accessor :verify_callback

    # Sets the maximum depth for the certificate chain verification.

    attr_accessor :verify_depth

    # Sets the flags for server the certification verification at beginning of

    # SSL/TLS session.

    #

    # OpenSSL::SSL::VERIFY_NONE or OpenSSL::SSL::VERIFY_PEER are acceptable.

    attr_accessor :verify_mode

    # Returns the X.509 certificates the server presented.

    #

    # if authorization on proxy server is required.  The proxy will use the

    # #default_port if no proxy port is provided.

    #

    #   # Example

    #   proxy_class = Net::HTTP::Proxy('proxy.example.com', 8080)

    #

    #   proxy_class.start('www.ruby-lang.org') {|http|

    #     # connecting proxy.foo.org:8080

    #   }

    #

    # You may use them to work with authorization-enabled proxies:

    #

    #   proxy_host = 'your.proxy.example'

    #   proxy_port = 8080

    #   uri = URI.parse(ENV['HTTP_PROXY'])

    #   proxy_user, proxy_pass = uri.userinfo.split(/:/) if uri.userinfo

    #

    #   proxy = Net::HTTP::Proxy(proxy_host, proxy_port, proxy_user, proxy_pass)

    #   proxy.start('www.example.com') { |http|

    #     # always connect to your.proxy.example:8080 using specified username

    #     # and password

    #   }

    #

    # Note that net/http does not use the HTTP_PROXY environment variable.

    # If you want to use a proxy, you must set it explicitly.

    # Set header fields and a body from HTML form data.  +params+ should be a

    # Hash containing HTML form data.  Optional argument +sep+ means data

    # record separator.

    # true if the response has a body.

    # raises this HTTPResponse as its matching exception type.  Note that you

    # may not raise an HTTPSuccess response subclass.

    def error!

  This file has been merged with net/http.  There is no longer any need to

  require 'net/https' to use HTTPS.