Net::HTTP (Class)

In: net/http.rb
Parent: Protocol

for backward compatibility

Constants

ProxyMod = ProxyDelta

External Aliases

new -> newobj
request_put -> put2

Attributes

address  [R]  The host name to connect to.
close_on_empty_response  [RW] 
open_timeout  [RW]  Seconds to wait until connection is opened. If the HTTP object cannot open a conection in this many seconds, it raises a TimeoutError exception.
port  [R]  The port number to connect to.
proxy_address  [R] 
proxy_pass  [R] 
proxy_port  [R] 
proxy_user  [R] 
read_timeout  [R]  Seconds to wait until reading one block (by one read(2) call). If the HTTP object cannot open a conection in this many seconds, it raises a TimeoutError exception.

Classes and Modules

Class Net::HTTP::Get
Class Net::HTTP::Head
Class Net::HTTP::Post
Class Net::HTTP::Put

Public Class methods

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

[Source]

# File net/http.rb, line 189
    def HTTP.version_1_2
      @@newimpl = true
    end

Turns on net/http 1.1 (ruby 1.6) features. Defaults to OFF in ruby 1.8.

[Source]

# File net/http.rb, line 195
    def HTTP.version_1_1
      @@newimpl = false
    end

true if net/http is in version 1.2 mode. Defaults to true.

[Source]

# File net/http.rb, line 201
    def HTTP.version_1_2?
      @@newimpl
    end

true if net/http is in version 1.1 compatible mode. Defaults to true.

[Source]

# File net/http.rb, line 207
    def HTTP.version_1_1?
      not @@newimpl
    end
is_version_1_1?()

Alias for version_1_1?

is_version_1_2?()

Alias for version_1_2?

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')

[Source]

# File net/http.rb, line 237
    def HTTP.get_print( arg1, arg2 = nil, port = nil )
      if arg2
        addr, path = arg1, arg2
      else
        uri = arg1
        addr = uri.host
        path = uri.request_uri
        port = uri.port
      end
      new(addr, port || HTTP.default_port).start {|http|
        http.get path, nil, $stdout
      }
      nil
    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')

[Source]

# File net/http.rb, line 262
    def HTTP.get( arg1, arg2 = nil, arg3 = nil )
      get_response(arg1,arg2,arg3).body
    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

[Source]

# File net/http.rb, line 278
    def HTTP.get_response( arg1, arg2 = nil, arg3 = nil )
      if arg2
        get_by_path(arg1, arg2, arg3)
      else
        get_by_uri(arg1)
      end
    end

The default port to use for HTTP requests; defaults to 80.

[Source]

# File net/http.rb, line 307
    def HTTP.default_port
      80
    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.

[Source]

# File net/http.rb, line 323
      def 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

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.

[Source]

# File net/http.rb, line 332
      def new( address, port = nil, p_addr = nil, p_port = nil, p_user = nil, p_pass = nil )
        obj = Proxy(p_addr, p_port, p_user, p_pass).newobj(address, port)
        setimplversion obj
        obj
      end

Creates a new Net::HTTP object for the specified address. This method does not open the TCP connection.

[Source]

# File net/http.rb, line 341
    def initialize( address, port = nil )
      @address = address
      @port    = port || HTTP.default_port

      @curr_http_version = HTTPVersion
      @seems_1_0_server = false
      @close_on_empty_response = false
      @socket  = nil
      @started = false

      @open_timeout = 30
      @read_timeout = 60

      @debug_output = nil
    end

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
                    :
    }

[Source]

# File net/http.rb, line 484
    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

returns true if self is a class which was created by HTTP::Proxy.

[Source]

# File net/http.rb, line 503
      def proxy_class?
        @is_proxy_class
      end

Public Instance methods

[Source]

# File net/http.rb, line 357
    def inspect
      "#<#{self.class} #{@address}:#{@port} open=#{started?}>"
    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 { .... }

[Source]

# File net/http.rb, line 370
    def set_debug_output( output )
      warn 'Net::HTTP#set_debug_output called after HTTP started' if started?
      @debug_output = output
    end

Setter for the read_timeout attribute.

[Source]

# File net/http.rb, line 392
    def read_timeout=( sec )
      @socket.read_timeout = sec if @socket
      @read_timeout = sec
    end

returns true if the HTTP session is started.

[Source]

# File net/http.rb, line 398
    def started?
      @started
    end
active?()

Alias for started?

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.

[Source]

# File net/http.rb, line 415
    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

Finishes HTTP session and closes TCP connection. Raises IOError if not started.

[Source]

# File net/http.rb, line 444
    def finish
      raise IOError, 'HTTP session not started yet' unless started?
      do_finish
    end

True if self is a HTTP proxy class

[Source]

# File net/http.rb, line 514
    def proxy?
      self.class.proxy_class?
    end

Address of proxy host. If self does not use a proxy, nil.

[Source]

# File net/http.rb, line 519
    def proxy_address
      self.class.proxy_address
    end

Port number of proxy host. If self does not use a proxy, nil.

[Source]

# File net/http.rb, line 524
    def proxy_port
      self.class.proxy_port
    end

User name for accessing proxy. If self does not use a proxy, nil.

[Source]

# File net/http.rb, line 529
    def proxy_user
      self.class.proxy_user
    end

User password for accessing proxy. If self does not use a proxy, nil.

[Source]

# File net/http.rb, line 534
    def proxy_pass
      self.class.proxy_pass
    end
proxyaddr()

Alias for proxy_address

proxyport()

Alias for proxy_port

Gets data from path on the connected-to host. 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 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
    }

[Source]

# File net/http.rb, line 616
    def get( path, initheader = nil, dest = nil, &block ) # :yield: +body_segment+

      res = nil
      request(Get.new(path, initheader)) {|r|
        r.read_body dest, &block
        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']

[Source]

# File net/http.rb, line 646
    def head( path, initheader = nil ) 
      res = request(Head.new(path, initheader))
      res.value unless @newimpl
      res
    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::HTTPReponse 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 is an alternative method of collecting the body. It must be an object responding to the "<<" operator (such as a String or an Array). Each fragment of the entity body will be "<<"-ed in turn onto dest if provided, and it will also become the body of the returned response object.

You must not provide both dest and a block; doing so will result in an ArgumentError.

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
    }

[Source]

# File net/http.rb, line 690
    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 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 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
    }

[Source]

# File net/http.rb, line 735
    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']

[Source]

# File net/http.rb, line 749
    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 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
    }

[Source]

# File net/http.rb, line 778
    def request_post( path, data, initheader = nil, &block ) # :yield: +response+

      request Post.new(path, initheader), data, &block
    end
get2( path, initheader = nil )

Alias for request_get

head2( path, initheader = nil, &block )

Alias for request_head

post2( path, data, initheader = nil )

Alias for request_post

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

[Source]

# File net/http.rb, line 802
    def send_request( name, path, data = nil, header = nil )
      r = HTTPGenericRequest.new(name,(data ? true : false),true,path,header)
      request r, data
    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 HTTPResponse#read_body, if desired.

Returns a HTTPResponse object.

This method never raises Net::* exceptions.

[Source]

# File net/http.rb, line 819
    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()
      end
        
      begin_transport req
          req.exec @socket, @curr_http_version, edit_path(req.path), body
          begin
            res = HTTPResponse.read_new(@socket)
          end while HTTPContinue === res
          res.reading_body(@socket, req.response_body_permitted?) {
            yield res if block_given?
          }
      end_transport req, res

      res
    end

[Validate]