http_request.rb

== Introduction

The HttpRequest class is based on the 'net/http' and 'net/ftp' libraries, so the return type is Net::HTTPResponse or Net::FTP when you call get or post or other methods by HttpRequest.xxx or HttpRequest.ftp

== Options

you can call like HttpRequest.get(options), the options parameter is a hash, support following keys: :url => String, the url you want to request :parameters => String or Hash, parameters will send to the url :redirect => Boolean, whether support redirect to, default is true :redirect_limits => Fixnum, maximal times for redirect if enabled :ssl_port => Fixnum, ssl port, default is 443 :headers => Hash, you can add some custom http headers :files => for upload files :ajax or :xhr => send request looks like AJAX calling (since 1.0.5)

# proxy settings
:proxy_addr       =>   String, proxy address 
:proxy_port       =>   Fixnum, proxy port
:proxy_user       =>   String, proxy username
:proxy_pass       =>   String, proxy password

== Examples for your ruby program:

include http_request.rb first require '/path/to/http_request.rb' or install it gem install http_request.rb, then require 'http_request'

get puts HttpRequest.get('http://github.com').body puts HttpRequest.get('https://github.com').body

get with query string, 4 are same puts HttpRequest.get('http://www.google.com/search?hl=en&q=ruby&start=0&sa=N').body puts HttpRequest.get('http://www.google.com/search', :parameters => 'hl=en&q=ruby&start=0&sa=N').body puts HttpRequest.get(:url => 'http://www.google.com/search', :parameters => 'hl=en&q=ruby&start=0&sa=N').body puts HttpRequest.get({:url => 'http://www.google.com/search', :parameters => 'hl=en&q=ruby&start=0&sa=N'}).body puts HttpRequest.get({:url => 'http://www.google.com/search', :parameters => {:hl => 'en', :q => 'ruby', :start => 0, :sa => 'N'}}).body

post with some parameters puts HttpRequest.get('http://localhost/test.php', :parameters => 'from=http_request.rb').body puts HttpRequest.get(:url => 'http://localhost/test.php', :parameters => {:name => 'Ruby', :time => 'Now'}).body

also support other http methods, such as put, delete, trace, options, move etc. HttpRequest.put(:url => 'http://www.example.com', :parameters => 'some=vars') HttpRequest.delete('http://www.example.com/article/1') HttpRequest.trace('http://www.example.com/')

basic authorization HttpRequest.get('http://admin:[e-mail]/secret/get/file')

proxy support HttpRequest.get(:url => 'http://www.example.com/', :proxy_addr => 'your.proxy.address', :proxy_port => 80) HttpRequest.get(:url => 'http://www.example.com/', :proxy_addr => 'your.proxy.address', :proxy_port => 80, :proxy_user => 'admin', :proxy_pass => '123123')

fetch headers HttpRequest.get('http://www.example.com/').each {|k, v| print "#{k} : #{v}" }

fetch cookies hr = HttpRequest.get('http://www.yahoo.com') hr.cookies.each {|k, v| puts "#{k} => #{v}" }

add cookies into header HttpRequest.get(:url => 'http://www.example.com/', :cookies => {:login => 'Yes', :userid => 101}) HttpRequest.get(:url => 'http://www.example.com/', :cookies => 'login=Yes; userId=101')

fetch cookies and add cookies hr = HttpRequest.get('http://www.example.com/homepage') hr = HttpRequest.post('http://www.example.com/login', :cookies => hr.cookies) hr = HttpRequest.get('http://www.example.com/logout', :cookies => hr.cookies)

store cookies with cookie jar (since v1.1.13) # default :cookie_jar is "default" hr1 = HttpRequest.post('http://hostname/request-cookies', :cookie_jar => 'user1') hr2 = HttpRequest.post('http://hostname/request-cookies', :cookie_jar => 'user2')

hr1 = HttpRequest.post('http://hostname/send-cookies', :cookie_jar => 'user1', :cookies => hr1.cookies)
hr2 = HttpRequest.post('http://hostname/send-cookies', :cookie_jar => 'user2', :cookies => hr2.cookies)

upload file by post method HttpRequest.post( :url => 'http://localhost/upload.php', :files => { :file_name => 'test.txt', # original file name, default is rand name such as 0cdex_0 :field_name => 'user_file', # input field name, default is "files[]" :content_type => 'text/plain', # content type, default is application/octet-stream :file_content => 'Have a nice day!' # file content } )

upload more than 1 file files = [ {:file_name => 'a.txt', :file_content => 'just for test'}, {:file_name => 'b.csv', :file_content => "a,b,c\nd,e,f"} ] HttpRequest.post( :url => 'http://localhost/upload.php', :files => files )

upload files with parameters HttpRequest.post( :url => 'http://localhost/upload.php', :parameters => {:name => 'zhou', :age => '?'}, :files => [{:file_content => 'so easy:-)'}] ) HttpRequest.post( :url => 'http://localhost/upload.php', :parameters => 'target=php&client=ruby', :files => [{:file_content => 'so easy:-)'}] )

want to upload a binary file such as photo? HttpRequest.post( :url => 'http://localhost/upload.php', :parameters => {:title => 'Nice photo', :description => 'some description here.'}, :files => [{:file_name => 'nice.jpg', :field_name => 'photo', :file_content => File.read('/path/to/nice.jpg')}] )

upload file by put method, more can check http://www.php.net/manual/en/features.file-upload.put-method.php HttpRequest.put( :url => 'http://localhost/upload.php', :parameters => 'file content here' )

== Examples in command line:

You need to do like "chmod +x http_request.rb" first. Usage: ./http_request.rb method url [parameters]

get a file and print the content $./http_request.rb get http://feeds.feedburner.com/RidingRails $./http_request.rb get 'http://www.google.com/search?hl=en&q=ruby&start=0&sa=N'

get but just print header $./http_request.rb get_only_header http://feeds.feedburner.com/RidingRails

get header and content $./http_request.rb get_with_header http://feeds.feedburner.com/RidingRails

download and save as a file $./http_request.rb http://rubyforge.org/frs/download.php/51094/RMagick-2.9.1.tar.bz2 > rmagick.tar.bz2

post $./http_request.rb post http://localhost/test.php 'name=Ruby&time=Now'

such as "get_only_header" and "get_with_header", post and other http methods also can do such as "post_only_header", "put_with_header" etc.

== Examples for FTP (since v1.0.1):

download and save to ftp = HttpRequest.ftp(:get, :url => 'ftp://user:[e-mail]/path/to/hello.mp3', :to => '/tmp/hello.mp3')

# get as string (since v1.0.2)
puts HttpRequest.ftp(:get_as_string, 'ftp://user:pass@localhost/path/to/file.txt')

upload from local ftp = HttpRequest.ftp(:put, :url => 'ftp://user:[e-mail]/path/to/hello.mp3', :from => '/tmp/hello.mp3')

get server info puts HttpRequest.ftp(:status, :url => 'ftp://user:[e-mail]/')

create a new directory (only for last directory) HttpRequest.ftp(:mkdir, :url => 'ftp://user:[e-mail]/path/to/newdir') HttpRequest.ftp(:mkdir, :url => 'ftp://user:[e-mail]/newdir')

remove a directory (only for last directory) HttpRequest.ftp(:mkdir, :url => 'ftp://user:[e-mail]/path/to/willbe_removed_dir')

list files puts HttpRequest.ftp(:list, :url => 'ftp://user:[e-mail]/')

list files as array HttpRequest.ftp(:nlst, :url => 'ftp://my.domain.name/', :username => 'user', :password => 'pass').each {|f| puts f }

anonymous login puts HttpRequest.ftp(:status, :url => 'ftp://my.domain.name/')

working as the "net/ftp" style, need set :close to false ftp = HttpRequest.ftp(:status, :url => 'ftp://user:[e-mail]/', :close => false) puts ftp.response # get status from the ftp server ftp.chdir('/musics') ftp.getbinaryfile('test.ogg', '/tmp/test.ogg') ftp.close

download multiple files from a directory ftp = HttpRequest.ftp('nlst', :url => 'ftp://user:[e-mail]/mp3/', :close => false) ftp.response.each {|f| puts "downloading....#{f}" ftp.get(f, '/tmp/downloads/' + File.basename(f)) } ftp.close

== Proc.call style (since v1.0.2)

HttpRequest.get('http://www.example.com/') {|http|
  puts http.body
  http.each_header {|k, v| puts "#{k} => #{v}" }
  http.cookies.each {|k, v| puts "#{k} => #{v}" }
}

HttpRequest.ftp(:get, {"ftp://user:pass@localhost/soft.zip", :to => '/path/to/soft.zip'}) {|ftp|
   puts ftp.ls
   ftp.chdir('soft')
   ftp.getbinaryfile('ruby.exe', '/path/to/local/ruby.exe');
}

== check the http status (since v1.0.3)

HttpRequest.get('http://www.example.com/it_doesnot_exists.page').code_4xx? # true HttpRequest.get('http://www.example.com/it_doesnot_exists.page').code_404? # true HttpRequest.get('http://www.rubyonrails.com/').code_404? # false HttpRequest.head('http://www.rubyonrails.com/').code_2xx? # true HttpRequest.head('http://www.ruby-lang.org/').code_200? # true

supported methods: code_1xx? code_2xx? code_3xx? code_4xx? code_5xx? code_101? code_200? ... or status_1xx? statux_2xx? ...

== check whether or not the remote site is available (since v1.0.3)

return true if can access to the website with socket connection even it is a 500 or 404 page, otherwise, return false

HttpRequest.available?('http://www.github.com/')

== send XML data via the post method (since v1.0.4)

xml = ' item one item two ' HttpRequest.post(:url => 'http://localhost/xml.php', :parameters = xml)

== More examples please check the test directory

== TODO

bug fixing, testing and testing...

== LATEST VERSION 1.1.14