U:RDoc::NormalClass[iI" HTTP:ETI"Net::HTTP;TI" Protocol;To:RDoc::Markup::Document: @parts[o;;[{S:RDoc::Markup::Heading: leveli: textI"!An HTTP client API for Ruby.;To:RDoc::Markup::BlankLineo:RDoc::Markup::Paragraph;[I"GNet::HTTP provides a rich library which can be used to build HTTP ;TI"3user-agents. For more details about HTTP see ;TI"3[RFC2616](http://www.ietf.org/rfc/rfc2616.txt);T@o; ;[I"FNet::HTTP is designed to work closely with URI. URI::HTTP#host, ;TI"HURI::HTTP#port and URI::HTTP#request_uri are designed to work with ;TI"Net::HTTP.;T@o; ;[I"JIf you are only performing a few GET requests you should try OpenURI.;T@S; ; i; I"Simple Examples;T@o; ;[I"8All examples assume you have loaded Net::HTTP with:;T@o:RDoc::Markup::Verbatim;[I"require 'net/http' ;T: @format0o; ;[I"MThis will also require 'uri' so you don't need to require it separately.;T@o; ;[I"CThe Net::HTTP methods in the following section do not persist ;TI"Lconnections. They are not recommended if you are performing many HTTP ;TI"requests.;T@S; ; i; I"GET;T@o;;[I"=Net::HTTP.get('example.com', '/index.html') # => String ;T;0S; ; i; I"GET by URI;T@o;;[I"9uri = URI('http://example.com/index.html?count=10') ;TI"$Net::HTTP.get(uri) # => String ;T;0S; ; i; I" GET with Dynamic Parameters;T@o;;[ I"0uri = URI('http://example.com/index.html') ;TI"+params = { :limit => 10, :page => 3 } ;TI"-uri.query = URI.encode_www_form(params) ;TI" ;TI"'res = Net::HTTP.get_response(uri) ;TI"2puts res.body if res.is_a?(Net::HTTPSuccess) ;T;0S; ; i; I" POST;T@o;;[I"4uri = URI('http://www.example.com/search.cgi') ;TI"Bres = Net::HTTP.post_form(uri, 'q' => 'ruby', 'max' => '50') ;TI"puts res.body ;T;0S; ; i; I"POST with Multiple Values;T@o;;[I"4uri = URI('http://www.example.com/search.cgi') ;TI"Lres = Net::HTTP.post_form(uri, 'q' => ['ruby', 'perl'], 'max' => '50') ;TI"puts res.body ;T;0S; ; i; I"How to use Net::HTTP;T@o; ;[I"NThe following example code can be used as the basis of a HTTP user-agent ;TI"Cwhich can perform a variety of request types using persistent ;TI"connections.;T@o;;[ I" String ;TI"-res.get_fields('set-cookie') # => Array ;TI"-res.to_hash['set-cookie'] # => Array ;TI",puts "Headers: #{res.to_hash.inspect}" ;TI" ;TI"# Status ;TI"$puts res.code # => '200' ;TI"#puts res.message # => 'OK' ;TI"'puts res.class.name # => 'HTTPOK' ;TI" ;TI" # Body ;TI"3puts res.body if res.response_body_permitted? ;T;0S; ; i; I"Following Redirection;T@o; ;[I"LEach Net::HTTPResponse object belongs to a class for its response code.;T@o; ;[ I"HFor example, all 2XX responses are instances of a Net::HTTPSuccess ;TI"Gsubclass, a 3XX response is an instance of a Net::HTTPRedirection ;TI"Osubclass and a 200 response is an instance of the Net::HTTPOK class. For ;TI"Jdetails of response classes, see the section "HTTP Response Classes" ;TI" below.;T@o; ;[I"OUsing a case statement you can handle various types of responses properly:;T@o;;[I"$def fetch(uri_str, limit = 10) ;TI"/ # You should choose a better exception. ;TI"D raise ArgumentError, 'too many HTTP redirects' if limit == 0 ;TI" ;TI"7 response = Net::HTTP.get_response(URI(uri_str)) ;TI" ;TI" case response ;TI"" when Net::HTTPSuccess then ;TI" response ;TI"& when Net::HTTPRedirection then ;TI") location = response['location'] ;TI"* warn "redirected to #{location}" ;TI"$ fetch(location, limit - 1) ;TI" else ;TI" response.value ;TI" end ;TI" end ;TI" ;TI"-print fetch('http://www.ruby-lang.org') ;T;0S; ; i; I" POST;T@o; ;[I"OA POST can be made using the Net::HTTP::Post request class. This example ;TI"$creates a urlencoded POST body:;T@o;;[I"2uri = URI('http://www.example.com/todo.cgi') ;TI"$req = Net::HTTP::Post.new(uri) ;TI"Ereq.set_form_data('from' => '2005-01-01', 'to' => '2005-03-31') ;TI" ;TI"=res = Net::HTTP.start(uri.hostname, uri.port) do |http| ;TI" http.request(req) ;TI" end ;TI" ;TI"case res ;TI"1when Net::HTTPSuccess, Net::HTTPRedirection ;TI" # OK ;TI" else ;TI" res.value ;TI" end ;T;0o; ;[I"KAt this time Net::HTTP does not support multipart/form-data. To send ;TI"8multipart/form-data use Net::HTTPRequest#body= and ;TI"$Net::HTTPRequest#content_type=:;T@o;;[I"$req = Net::HTTP::Post.new(uri) ;TI"req.body = multipart_data ;TI".req.content_type = 'multipart/form-data' ;T;0o; ;[I"NOther requests that can contain a body such as PUT can be created in the ;TI"Esame way using the corresponding request class (Net::HTTP::Put).;T@S; ; i; I"Setting Headers;T@o; ;[ I"@The following example performs a conditional GET using the ;TI"MIf-Modified-Since header. If the files has not been modified since the ;TI"Ptime in the header a Not Modified response will be returned. See RFC 2616 ;TI"%section 9.3 for further details.;T@o;;[I"5uri = URI('http://example.com/cached_response') ;TI"(file = File.stat 'cached_response' ;TI" ;TI"#req = Net::HTTP::Get.new(uri) ;TI"3req['If-Modified-Since'] = file.mtime.rfc2822 ;TI" ;TI";res = Net::HTTP.start(uri.hostname, uri.port) {|http| ;TI" http.request(req) ;TI"} ;TI" ;TI")open 'cached_response', 'w' do |io| ;TI" io.write res.body ;TI"(end if res.is_a?(Net::HTTPSuccess) ;T;0S; ; i; I"Basic Authentication;T@o; ;[I"4Basic authentication is performed according to ;TI"3[RFC2617](http://www.ietf.org/rfc/rfc2617.txt);T@o;;[I":uri = URI('http://example.com/index.html?key=value') ;TI" ;TI"#req = Net::HTTP::Get.new(uri) ;TI"#req.basic_auth 'user', 'pass' ;TI" ;TI";res = Net::HTTP.start(uri.hostname, uri.port) {|http| ;TI" http.request(req) ;TI"} ;TI"puts res.body ;T;0S; ; i; I"Streaming Response Bodies;T@o; ;[I"LBy default Net::HTTP reads an entire response into memory. If you are ;TI"Nhandling large files or wish to implement a progress bar you can instead ;TI"'stream the body directly to an IO.;T@o;;[I"0uri = URI('http://example.com/large_file') ;TI" ;TI"3Net::HTTP.start(uri.host, uri.port) do |http| ;TI"( request = Net::HTTP::Get.new uri ;TI" ;TI"* http.request request do |response| ;TI"( open 'large_file', 'w' do |io| ;TI") response.read_body do |chunk| ;TI" io.write chunk ;TI" end ;TI" end ;TI" end ;TI" end ;T;0S; ; i; I" HTTPS;T@o; ;[I"CHTTPS is enabled for an HTTP connection by Net::HTTP#use_ssl=.;T@o;;[ I"Duri = URI('https://secure.example.com/some_path?query=string') ;TI" ;TI"ENet::HTTP.start(uri.host, uri.port, :use_ssl => true) do |http| ;TI"( request = Net::HTTP::Get.new uri ;TI"B response = http.request request # Net::HTTPResponse object ;TI" end ;T;0o; ;[I"IOr if you simply want to make a GET request, you may pass in an URI ;TI"Fobject that has a HTTPS URL. Net::HTTP automatically turn on TLS ;TI"=verification if the URI object has a 'https' URI scheme.;T@o;;[I"'uri = URI('https://example.com/') ;TI"$Net::HTTP.get(uri) # => String ;T;0o; ;[I"OIn previous versions of Ruby you would need to require 'net/https' to use ;TI"#HTTPS. This is no longer true.;T@S; ; i; I" Proxies;T@o; ;[I"GNet::HTTP will automatically create a proxy from the +http_proxy+ ;TI"Menvironment variable if it is present. To disable use of +http_proxy+, ;TI"&pass +nil+ for the proxy address.;T@o; ;[I"(You may also create a custom proxy:;T@o;;[ I"$proxy_addr = 'your.proxy.host' ;TI"proxy_port = 8080 ;TI" ;TI"NNet::HTTP.new('example.com', nil, proxy_addr, proxy_port).start { |http| ;TI"/ # always proxy via your.proxy.addr:8080 ;TI"} ;T;0o; ;[I"MSee Net::HTTP.new for further details and examples such as proxies that ;TI"%require a username and password.;T@S; ; i; I"Compression;T@o; ;[I"NNet::HTTP automatically adds Accept-Encoding for compression of response ;TI"Obodies and automatically decompresses gzip and deflate responses unless a ;TI"Range header was sent.;T@o; ;[I"NCompression can be disabled through the Accept-Encoding: identity header.;T@S; ; i; I"HTTP Request Classes;T@o; ;[I".Here is the HTTP request class hierarchy.;T@o:RDoc::Markup::List: @type: BULLET: @items[o:RDoc::Markup::ListItem: @label0;[o; ;[I"Net::HTTPRequest;To;;;;[o;;0;[o; ;[I"Net::HTTP::Get;To;;0;[o; ;[I"Net::HTTP::Head;To;;0;[o; ;[I"Net::HTTP::Post;To;;0;[o; ;[I"Net::HTTP::Patch;To;;0;[o; ;[I"Net::HTTP::Put;To;;0;[o; ;[I"Net::HTTP::Proppatch;To;;0;[o; ;[I"Net::HTTP::Lock;To;;0;[o; ;[I"Net::HTTP::Unlock;To;;0;[o; ;[I"Net::HTTP::Options;To;;0;[o; ;[I"Net::HTTP::Propfind;To;;0;[o; ;[I"Net::HTTP::Delete;To;;0;[o; ;[I"Net::HTTP::Move;To;;0;[o; ;[I"Net::HTTP::Copy;To;;0;[o; ;[I"Net::HTTP::Mkcol;To;;0;[o; ;[I"Net::HTTP::Trace;T@S; ; i; I"HTTP Response Classes;T@o; ;[I"LHere is HTTP response class hierarchy. All classes are defined in Net ;TI"4module and are subclasses of Net::HTTPResponse.;T@o;;: NOTE;[?o;;[I"HTTPUnknownResponse;T;[o; ;[I""For unhandled HTTP extensions;To;;[I"HTTPInformation;T;[o; ;[I"1xx;To;;[I"HTTPContinue;T;[o; ;[I"100;To;;[I"HTTPSwitchProtocol;T;[o; ;[I"101;To;;[I"HTTPSuccess;T;[o; ;[I"2xx;To;;[I" HTTPOK;T;[o; ;[I"200;To;;[I"HTTPCreated;T;[o; ;[I"201;To;;[I"HTTPAccepted;T;[o; ;[I"202;To;;[I"$HTTPNonAuthoritativeInformation;T;[o; ;[I"203;To;;[I"HTTPNoContent;T;[o; ;[I"204;To;;[I"HTTPResetContent;T;[o; ;[I"205;To;;[I"HTTPPartialContent;T;[o; ;[I"206;To;;[I"HTTPMultiStatus;T;[o; ;[I"207;To;;[I"HTTPIMUsed;T;[o; ;[I"226;To;;[I"HTTPRedirection;T;[o; ;[I"3xx;To;;[I"HTTPMultipleChoices;T;[o; ;[I"300;To;;[I"HTTPMovedPermanently;T;[o; ;[I"301;To;;[I"HTTPFound;T;[o; ;[I"302;To;;[I"HTTPSeeOther;T;[o; ;[I"303;To;;[I"HTTPNotModified;T;[o; ;[I"304;To;;[I"HTTPUseProxy;T;[o; ;[I"305;To;;[I"HTTPTemporaryRedirect;T;[o; ;[I"307;To;;[I"HTTPClientError;T;[o; ;[I"4xx;To;;[I"HTTPBadRequest;T;[o; ;[I"400;To;;[I"HTTPUnauthorized;T;[o; ;[I"401;To;;[I"HTTPPaymentRequired;T;[o; ;[I"402;To;;[I"HTTPForbidden;T;[o; ;[I"403;To;;[I"HTTPNotFound;T;[o; ;[I"404;To;;[I"HTTPMethodNotAllowed;T;[o; ;[I"405;To;;[I"HTTPNotAcceptable;T;[o; ;[I"406;To;;[I"$HTTPProxyAuthenticationRequired;T;[o; ;[I"407;To;;[I"HTTPRequestTimeOut;T;[o; ;[I"408;To;;[I"HTTPConflict;T;[o; ;[I"409;To;;[I" HTTPGone;T;[o; ;[I"410;To;;[I"HTTPLengthRequired;T;[o; ;[I"411;To;;[I"HTTPPreconditionFailed;T;[o; ;[I"412;To;;[I"HTTPRequestEntityTooLarge;T;[o; ;[I"413;To;;[I"HTTPRequestURITooLong;T;[o; ;[I"414;To;;[I"HTTPUnsupportedMediaType;T;[o; ;[I"415;To;;[I"%HTTPRequestedRangeNotSatisfiable;T;[o; ;[I"416;To;;[I"HTTPExpectationFailed;T;[o; ;[I"417;To;;[I"HTTPUnprocessableEntity;T;[o; ;[I"422;To;;[I"HTTPLocked;T;[o; ;[I"423;To;;[I"HTTPFailedDependency;T;[o; ;[I"424;To;;[I"HTTPUpgradeRequired;T;[o; ;[I"426;To;;[I"HTTPPreconditionRequired;T;[o; ;[I"428;To;;[I"HTTPTooManyRequests;T;[o; ;[I"429;To;;[I"$HTTPRequestHeaderFieldsTooLarge;T;[o; ;[I"431;To;;[I"#HTTPUnavailableForLegalReasons;T;[o; ;[I"451;To;;[I"HTTPServerError;T;[o; ;[I"5xx;To;;[I"HTTPInternalServerError;T;[o; ;[I"500;To;;[I"HTTPNotImplemented;T;[o; ;[I"501;To;;[I"HTTPBadGateway;T;[o; ;[I"502;To;;[I"HTTPServiceUnavailable;T;[o; ;[I"503;To;;[I"HTTPGatewayTimeOut;T;[o; ;[I"504;To;;[I"HTTPVersionNotSupported;T;[o; ;[I"505;To;;[I"HTTPInsufficientStorage;T;[o; ;[I"507;To;;[I"&HTTPNetworkAuthenticationRequired;T;[o; ;[I"511;T@o; ;[I"KThere is also the Net::HTTPBadResponse exception which is raised when ;TI"there is a protocol error.;T: @fileI"lib/net/http.rb;T:0@omit_headings_from_table_of_contents_below0;0;0["[ I"proxy_address;TI"R;T: publicTI"lib/net/http.rb;T[ I"proxy_pass;TI"R;T;T@E[ I"proxy_port;TI"R;T;T@E[ I"proxy_user;TI"R;T;T@E[ I" address;TI"R;T;F@E[ I" ca_file;TI"RW;T;F@E[ I" ca_path;TI"RW;T;F@E[ I" cert;TI"RW;T;F@E[ I"cert_store;TI"RW;T;F@E[ I" ciphers;TI"RW;T;F@E[ I"close_on_empty_response;TI"RW;T;F@E[ I"continue_timeout;TI"R;T;F@E[ I"keep_alive_timeout;TI"RW;T;F@E[ I"key;TI"RW;T;F@E[ I"local_host;TI"RW;T;F@E[ I"local_port;TI"RW;T;F@E[ I"open_timeout;TI"RW;T;F@E[ I" port;TI"R;T;F@E[ I"proxy_address;TI"W;T;F@E[ I"proxy_from_env;TI"W;T;F@E[ I"proxy_pass;TI"W;T;F@E[ I"proxy_port;TI"W;T;F@E[ I"proxy_user;TI"W;T;F@E[ I"read_timeout;TI"R;T;F@E[ I"ssl_timeout;TI"RW;T;F@E[ I"ssl_version;TI"RW;T;F@E[ I"verify_callback;TI"RW;T;F@E[ I"verify_depth;TI"RW;T;F@E[ I"verify_mode;TI"RW;T;F@E[U:RDoc::Constant[iI"SSL_IVNAMES;FI"Net::HTTP::SSL_IVNAMES;T00o;;[;@@;0@@@cRDoc::NormalClass0U;[iI"SSL_ATTRIBUTES;FI"Net::HTTP::SSL_ATTRIBUTES;T00o;;[;@@;0@@@@¡0[[[I" class;T[[;[[I" Proxy;F@E[I"default_port;F@E[I"get;F@E[I"get_print;F@E[I"get_response;F@E[I"http_default_port;F@E[I"https_default_port;F@E[I"is_version_1_2?;F@E[I"new;F@E[I" newobj;F@E[I" post;F@E[I"post_form;F@E[I"proxy_class?;F@E[I" start;F@E[I"version_1_2;F@E[I"version_1_2?;F@E[:protected[[: private[[I" instance;T[[;[.[I" active?;F@E[I"continue_timeout=;F@E[I" copy;F@E[I" delete;F@E[I" finish;F@E[I"get;F@E[I" get2;F@E[I" head;F@E[I" head2;F@E[I" inspect;F@E[I" lock;F@E[I" mkcol;F@E[I" move;F@E[I" options;F@E[I" patch;F@E[I"peer_cert;F@E[I" post;F@E[I" post2;F@E[I" propfind;F@E[I"proppatch;F@E[I" proxy?;F@E[I"proxy_address;F@E[I"proxy_from_env?;F@E[I"proxy_pass;F@E[I"proxy_port;F@E[I"proxy_user;F@E[I"proxyaddr;F@E[I"proxyport;F@E[I"read_timeout=;F@E[I" request;F@E[I"request_get;F@E[I"request_head;F@E[I"request_post;F@E[I"send_request;F@E[I"set_debug_output;F@E[I" start;F@E[I" started?;F@E[I" trace;F@E[I" unlock;F@E[I" use_ssl=;F@E[I" use_ssl?;F@E[;[[;[[I"D;F@E[I"addr_port;F@E[I"begin_transport;F@E[I" connect;F@E[I"do_finish;F@E[I" do_start;F@E[I"edit_path;F@E[I"end_transport;F@E[I"keep_alive?;F@E[I"on_connect;F@E[I"send_entity;F@E[I"sspi_auth;F@E[I"sspi_auth?;F@E[I"transport_request;F@E[[U:RDoc::Context::Section[i0o;;[;0;0[ @@I"$lib/net/http/generic_request.rb;TI" lib/net/http/proxy_delta.rb;TI"lib/net/http/requests.rb;TI"lib/open-uri.rb;TI"#lib/rubygems/remote_fetcher.rb;TI"Net;FcRDoc::NormalModule