Net::HTTPSession

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 641
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 414
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 355
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 336
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 371
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 419
def HTTP.http_default_port
  80
end
            

The default port to use for HTTPS requests; defaults to 443.

 
               # File net/http.rb, line 424
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 450
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 460
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 = nil
  @read_timeout = 60
  @debug_output = nil
  @use_ssl = false
  @ssl_context = nil
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 400
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 659
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 439
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 300
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 312
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 294
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 306
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 906
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 894
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 601
def finish
  raise IOError, 'HTTP session not yet started' unless started?
  do_finish
end
            

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
}

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

 
               # File net/http.rb, line 800
def head(path, initheader = nil) 
  res = request(Head.new(path, initheader))
  res.value unless @newimpl
  res
end
            

Sends a LOCK request to the path and gets a response, as an HTTPResponse object.

 
               # File net/http.rb, line 870
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 912
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 900
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 882
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 843
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 888
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 864
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 670
def proxy?
  self.class.proxy_class?
end
            

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

 
               # File net/http.rb, line 675
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 690
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 680
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 685
def proxy_user
  self.class.proxy_user
end
            

Setter for the #read_timeout attribute.

 
               # File net/http.rb, line 510
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 1033
def request(req, body = nil, &block)  # :yield: +response+
  unless started?
    start {
      req['connection'] ||= 'close'
      return request(req, body, &block)
    }
  end
  if proxy_user()
    unless use_ssl?
      req.proxy_basic_auth proxy_user(), proxy_pass()
    end
  end

  req.set_body_internal body
  begin_transport req
    req.exec @socket, @curr_http_version, edit_path(req.path)
    begin
      res = HTTPResponse.read_new(@socket)
    end while res.kind_of?(HTTPContinue)
    res.reading_body(@socket, req.response_body_permitted?) {
      yield res if block_given?
    }
  end_transport req, res

  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 947
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 961
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 991
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 1015
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 488
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 538
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 516
def started?
  @started
end
            

Sends a TRACE request to the path and gets a response, as an HTTPResponse object.

 
               # File net/http.rb, line 918
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 876
def unlock(path, body, initheader = nil)
  request(Unlock.new(path, initheader), body)
end
            

returns true if use SSL/TLS with HTTP.

 
               # File net/http.rb, line 525
def use_ssl?
  false   # redefined in net/https
end