net-http 0.3.0 → 0.3.1

data/lib/net/http/requests.rb

@@ -1,67 +1,241 @@
 # frozen_string_literal: false
-#
+
 # HTTP/1.1 methods --- RFC2616
-#
 
-# See Net::HTTPGenericRequest for attributes and methods.
-# See Net::HTTP for usage examples.
+# \Class for representing
+# {HTTP method GET}[https://en.wikipedia.org/w/index.php?title=Hypertext_Transfer_Protocol#GET_method]:
+#
+#   require 'net/http'
+#   uri = URI('http://example.com')
+#   hostname = uri.hostname # => "example.com"
+#   req = Net::HTTP::Get.new(uri) # => #<Net::HTTP::Get GET>
+#   res = Net::HTTP.start(hostname) do |http|
+#     http.request(req)
+#   end
+#
+# Properties:
+#
+# - Request body: optional.
+# - Response body: yes.
+# - {Safe}[https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Safe_methods]: yes.
+# - {Idempotent}[https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Idempotent_methods]: yes.
+# - {Cacheable}[https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Cacheable_methods]: yes.
+#
+# Related:
+#
+# - Net::HTTP.get: sends +GET+ request, returns response body.
+# - Net::HTTP#get: sends +GET+ request, returns response object.
+#
 class Net::HTTP::Get < Net::HTTPRequest
   METHOD = 'GET'
   REQUEST_HAS_BODY  = false
   RESPONSE_HAS_BODY = true
 end
 
-# See Net::HTTPGenericRequest for attributes and methods.
-# See Net::HTTP for usage examples.
+# \Class for representing
+# {HTTP method HEAD}[https://en.wikipedia.org/w/index.php?title=Hypertext_Transfer_Protocol#HEAD_method]:
+#
+#   require 'net/http'
+#   uri = URI('http://example.com')
+#   hostname = uri.hostname # => "example.com"
+#   req = Net::HTTP::Head.new(uri) # => #<Net::HTTP::Head HEAD>
+#   res = Net::HTTP.start(hostname) do |http|
+#     http.request(req)
+#   end
+#
+# Properties:
+#
+# - Request body: optional.
+# - Response body: no.
+# - {Safe}[https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Safe_methods]: yes.
+# - {Idempotent}[https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Idempotent_methods]: yes.
+# - {Cacheable}[https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Cacheable_methods]: yes.
+#
+# Related:
+#
+# - Net::HTTP#head: sends +HEAD+ request, returns response object.
+#
 class Net::HTTP::Head < Net::HTTPRequest
   METHOD = 'HEAD'
   REQUEST_HAS_BODY = false
   RESPONSE_HAS_BODY = false
 end
 
-# See Net::HTTPGenericRequest for attributes and methods.
-# See Net::HTTP for usage examples.
+# \Class for representing
+# {HTTP method POST}[https://en.wikipedia.org/w/index.php?title=Hypertext_Transfer_Protocol#POST_method]:
+#
+#   require 'net/http'
+#   uri = URI('http://example.com')
+#   hostname = uri.hostname # => "example.com"
+#   uri.path = '/posts'
+#   req = Net::HTTP::Post.new(uri) # => #<Net::HTTP::Post POST>
+#   req.body = '{"title": "foo","body": "bar","userId": 1}'
+#   req.content_type = 'application/json'
+#   res = Net::HTTP.start(hostname) do |http|
+#     http.request(req)
+#   end
+#
+# Properties:
+#
+# - Request body: yes.
+# - Response body: yes.
+# - {Safe}[https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Safe_methods]: no.
+# - {Idempotent}[https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Idempotent_methods]: no.
+# - {Cacheable}[https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Cacheable_methods]: yes.
+#
+# Related:
+#
+# - Net::HTTP.post: sends +POST+ request, returns response object.
+# - Net::HTTP#post: sends +POST+ request, returns response object.
+#
 class Net::HTTP::Post < Net::HTTPRequest
   METHOD = 'POST'
   REQUEST_HAS_BODY = true
   RESPONSE_HAS_BODY = true
 end
 
-# See Net::HTTPGenericRequest for attributes and methods.
-# See Net::HTTP for usage examples.
+# \Class for representing
+# {HTTP method PUT}[https://en.wikipedia.org/w/index.php?title=Hypertext_Transfer_Protocol#PUT_method]:
+#
+#   require 'net/http'
+#   uri = URI('http://example.com')
+#   hostname = uri.hostname # => "example.com"
+#   uri.path = '/posts'
+#   req = Net::HTTP::Put.new(uri) # => #<Net::HTTP::Put PUT>
+#   req.body = '{"title": "foo","body": "bar","userId": 1}'
+#   req.content_type = 'application/json'
+#   res = Net::HTTP.start(hostname) do |http|
+#     http.request(req)
+#   end
+#
+# Properties:
+#
+# - Request body: yes.
+# - Response body: yes.
+# - {Safe}[https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Safe_methods]: no.
+# - {Idempotent}[https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Idempotent_methods]: yes.
+# - {Cacheable}[https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Cacheable_methods]: no.
+#
 class Net::HTTP::Put < Net::HTTPRequest
   METHOD = 'PUT'
   REQUEST_HAS_BODY = true
   RESPONSE_HAS_BODY = true
 end
 
-# See Net::HTTPGenericRequest for attributes and methods.
-# See Net::HTTP for usage examples.
+# \Class for representing
+# {HTTP method DELETE}[https://en.wikipedia.org/w/index.php?title=Hypertext_Transfer_Protocol#DELETE_method]:
+#
+#   require 'net/http'
+#   uri = URI('http://example.com')
+#   hostname = uri.hostname # => "example.com"
+#   uri.path = '/posts/1'
+#   req = Net::HTTP::Delete.new(uri) # => #<Net::HTTP::Delete DELETE>
+#   res = Net::HTTP.start(hostname) do |http|
+#     http.request(req)
+#   end
+#
+# Properties:
+#
+# - Request body: optional.
+# - Response body: yes.
+# - {Safe}[https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Safe_methods]: no.
+# - {Idempotent}[https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Idempotent_methods]: yes.
+# - {Cacheable}[https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Cacheable_methods]: no.
+#
+# Related:
+#
+# - Net::HTTP#delete: sends +DELETE+ request, returns response object.
+#
 class Net::HTTP::Delete < Net::HTTPRequest
   METHOD = 'DELETE'
   REQUEST_HAS_BODY = false
   RESPONSE_HAS_BODY = true
 end
 
-# See Net::HTTPGenericRequest for attributes and methods.
+# \Class for representing
+# {HTTP method OPTIONS}[https://en.wikipedia.org/w/index.php?title=Hypertext_Transfer_Protocol#OPTIONS_method]:
+#
+#   require 'net/http'
+#   uri = URI('http://example.com')
+#   hostname = uri.hostname # => "example.com"
+#   req = Net::HTTP::Options.new(uri) # => #<Net::HTTP::Options OPTIONS>
+#   res = Net::HTTP.start(hostname) do |http|
+#     http.request(req)
+#   end
+#
+# Properties:
+#
+# - Request body: optional.
+# - Response body: yes.
+# - {Safe}[https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Safe_methods]: yes.
+# - {Idempotent}[https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Idempotent_methods]: yes.
+# - {Cacheable}[https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Cacheable_methods]: no.
+#
+# Related:
+#
+# - Net::HTTP#options: sends +OPTIONS+ request, returns response object.
+#
 class Net::HTTP::Options < Net::HTTPRequest
   METHOD = 'OPTIONS'
   REQUEST_HAS_BODY = false
   RESPONSE_HAS_BODY = true
 end
 
-# See Net::HTTPGenericRequest for attributes and methods.
+# \Class for representing
+# {HTTP method TRACE}[https://en.wikipedia.org/w/index.php?title=Hypertext_Transfer_Protocol#TRACE_method]:
+#
+#   require 'net/http'
+#   uri = URI('http://example.com')
+#   hostname = uri.hostname # => "example.com"
+#   req = Net::HTTP::Trace.new(uri) # => #<Net::HTTP::Trace TRACE>
+#   res = Net::HTTP.start(hostname) do |http|
+#     http.request(req)
+#   end
+#
+# Properties:
+#
+# - Request body: no.
+# - Response body: yes.
+# - {Safe}[https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Safe_methods]: yes.
+# - {Idempotent}[https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Idempotent_methods]: yes.
+# - {Cacheable}[https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Cacheable_methods]: no.
+#
+# Related:
+#
+# - Net::HTTP#trace: sends +TRACE+ request, returns response object.
+#
 class Net::HTTP::Trace < Net::HTTPRequest
   METHOD = 'TRACE'
   REQUEST_HAS_BODY = false
   RESPONSE_HAS_BODY = true
 end
 
+# \Class for representing
+# {HTTP method PATCH}[https://en.wikipedia.org/w/index.php?title=Hypertext_Transfer_Protocol#PATCH_method]:
 #
-# PATCH method --- RFC5789
+#   require 'net/http'
+#   uri = URI('http://example.com')
+#   hostname = uri.hostname # => "example.com"
+#   uri.path = '/posts'
+#   req = Net::HTTP::Patch.new(uri) # => #<Net::HTTP::Patch PATCH>
+#   req.body = '{"title": "foo","body": "bar","userId": 1}'
+#   req.content_type = 'application/json'
+#   res = Net::HTTP.start(hostname) do |http|
+#     http.request(req)
+#   end
+#
+# Properties:
+#
+# - Request body: yes.
+# - Response body: yes.
+# - {Safe}[https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Safe_methods]: no.
+# - {Idempotent}[https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Idempotent_methods]: no.
+# - {Cacheable}[https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Cacheable_methods]: no.
+#
+# Related:
+#
+# - Net::HTTP#patch: sends +PATCH+ request, returns response object.
 #
-
-# See Net::HTTPGenericRequest for attributes and methods.
 class Net::HTTP::Patch < Net::HTTPRequest
   METHOD = 'PATCH'
   REQUEST_HAS_BODY = true
@@ -72,49 +246,147 @@ end
 # WebDAV methods --- RFC2518
 #
 
-# See Net::HTTPGenericRequest for attributes and methods.
+# \Class for representing
+# {WebDAV method PROPFIND}[http://www.webdav.org/specs/rfc4918.html#METHOD_PROPFIND]:
+#
+#   require 'net/http'
+#   uri = URI('http://example.com')
+#   hostname = uri.hostname # => "example.com"
+#   req = Net::HTTP::Propfind.new(uri) # => #<Net::HTTP::Propfind PROPFIND>
+#   res = Net::HTTP.start(hostname) do |http|
+#     http.request(req)
+#   end
+#
+# Related:
+#
+# - Net::HTTP#propfind: sends +PROPFIND+ request, returns response object.
+#
 class Net::HTTP::Propfind < Net::HTTPRequest
   METHOD = 'PROPFIND'
   REQUEST_HAS_BODY = true
   RESPONSE_HAS_BODY = true
 end
 
-# See Net::HTTPGenericRequest for attributes and methods.
+# \Class for representing
+# {WebDAV method PROPPATCH}[http://www.webdav.org/specs/rfc4918.html#METHOD_PROPPATCH]:
+#
+#   require 'net/http'
+#   uri = URI('http://example.com')
+#   hostname = uri.hostname # => "example.com"
+#   req = Net::HTTP::Proppatch.new(uri) # => #<Net::HTTP::Proppatch PROPPATCH>
+#   res = Net::HTTP.start(hostname) do |http|
+#     http.request(req)
+#   end
+#
+# Related:
+#
+# - Net::HTTP#proppatch: sends +PROPPATCH+ request, returns response object.
+#
 class Net::HTTP::Proppatch < Net::HTTPRequest
   METHOD = 'PROPPATCH'
   REQUEST_HAS_BODY = true
   RESPONSE_HAS_BODY = true
 end
 
-# See Net::HTTPGenericRequest for attributes and methods.
+# \Class for representing
+# {WebDAV method MKCOL}[http://www.webdav.org/specs/rfc4918.html#METHOD_MKCOL]:
+#
+#   require 'net/http'
+#   uri = URI('http://example.com')
+#   hostname = uri.hostname # => "example.com"
+#   req = Net::HTTP::Mkcol.new(uri) # => #<Net::HTTP::Mkcol MKCOL>
+#   res = Net::HTTP.start(hostname) do |http|
+#     http.request(req)
+#   end
+#
+# Related:
+#
+# - Net::HTTP#mkcol: sends +MKCOL+ request, returns response object.
+#
 class Net::HTTP::Mkcol < Net::HTTPRequest
   METHOD = 'MKCOL'
   REQUEST_HAS_BODY = true
   RESPONSE_HAS_BODY = true
 end
 
-# See Net::HTTPGenericRequest for attributes and methods.
+# \Class for representing
+# {WebDAV method COPY}[http://www.webdav.org/specs/rfc4918.html#METHOD_COPY]:
+#
+#   require 'net/http'
+#   uri = URI('http://example.com')
+#   hostname = uri.hostname # => "example.com"
+#   req = Net::HTTP::Copy.new(uri) # => #<Net::HTTP::Copy COPY>
+#   res = Net::HTTP.start(hostname) do |http|
+#     http.request(req)
+#   end
+#
+# Related:
+#
+# - Net::HTTP#copy: sends +COPY+ request, returns response object.
+#
 class Net::HTTP::Copy < Net::HTTPRequest
   METHOD = 'COPY'
   REQUEST_HAS_BODY = false
   RESPONSE_HAS_BODY = true
 end
 
-# See Net::HTTPGenericRequest for attributes and methods.
+# \Class for representing
+# {WebDAV method MOVE}[http://www.webdav.org/specs/rfc4918.html#METHOD_MOVE]:
+#
+#   require 'net/http'
+#   uri = URI('http://example.com')
+#   hostname = uri.hostname # => "example.com"
+#   req = Net::HTTP::Move.new(uri) # => #<Net::HTTP::Move MOVE>
+#   res = Net::HTTP.start(hostname) do |http|
+#     http.request(req)
+#   end
+#
+# Related:
+#
+# - Net::HTTP#move: sends +MOVE+ request, returns response object.
+#
 class Net::HTTP::Move < Net::HTTPRequest
   METHOD = 'MOVE'
   REQUEST_HAS_BODY = false
   RESPONSE_HAS_BODY = true
 end
 
-# See Net::HTTPGenericRequest for attributes and methods.
+# \Class for representing
+# {WebDAV method LOCK}[http://www.webdav.org/specs/rfc4918.html#METHOD_LOCK]:
+#
+#   require 'net/http'
+#   uri = URI('http://example.com')
+#   hostname = uri.hostname # => "example.com"
+#   req = Net::HTTP::Lock.new(uri) # => #<Net::HTTP::Lock LOCK>
+#   res = Net::HTTP.start(hostname) do |http|
+#     http.request(req)
+#   end
+#
+# Related:
+#
+# - Net::HTTP#lock: sends +LOCK+ request, returns response object.
+#
 class Net::HTTP::Lock < Net::HTTPRequest
   METHOD = 'LOCK'
   REQUEST_HAS_BODY = true
   RESPONSE_HAS_BODY = true
 end
 
-# See Net::HTTPGenericRequest for attributes and methods.
+# \Class for representing
+# {WebDAV method UNLOCK}[http://www.webdav.org/specs/rfc4918.html#METHOD_UNLOCK]:
+#
+#   require 'net/http'
+#   uri = URI('http://example.com')
+#   hostname = uri.hostname # => "example.com"
+#   req = Net::HTTP::Unlock.new(uri) # => #<Net::HTTP::Unlock UNLOCK>
+#   res = Net::HTTP.start(hostname) do |http|
+#     http.request(req)
+#   end
+#
+# Related:
+#
+# - Net::HTTP#unlock: sends +UNLOCK+ request, returns response object.
+#
 class Net::HTTP::Unlock < Net::HTTPRequest
   METHOD = 'UNLOCK'
   REQUEST_HAS_BODY = true

data/lib/net/http/response.rb

@@ -1,20 +1,136 @@
 # frozen_string_literal: false
-# HTTP response class.
+
+# This class is the base class for \Net::HTTP request classes.
+#
+# == About the Examples
+#
+# :include: doc/net-http/examples.rdoc
+#
+# == Returned Responses
+#
+# \Method Net::HTTP.get_response returns
+# an instance of one of the subclasses of \Net::HTTPResponse:
+#
+#   Net::HTTP.get_response(uri)
+#   # => #<Net::HTTPOK 200 OK readbody=true>
+#   Net::HTTP.get_response(hostname, '/nosuch')
+#   # => #<Net::HTTPNotFound 404 Not Found readbody=true>
+#
+# As does method Net::HTTP#request:
+#
+#   req = Net::HTTP::Get.new(uri)
+#   Net::HTTP.start(hostname) do |http|
+#     http.request(req)
+#   end # => #<Net::HTTPOK 200 OK readbody=true>
+#
+# \Class \Net::HTTPResponse includes module Net::HTTPHeader,
+# which provides access to response header values via (among others):
+#
+# - \Hash-like method <tt>[]</tt>.
+# - Specific reader methods, such as +content_type+.
+#
+# Examples:
+#
+#   res = Net::HTTP.get_response(uri) # => #<Net::HTTPOK 200 OK readbody=true>
+#   res['Content-Type']               # => "text/html; charset=UTF-8"
+#   res.content_type                  # => "text/html"
+#
+# == Response Subclasses
+#
+# \Class \Net::HTTPResponse has a subclass for each
+# {HTTP status code}[https://en.wikipedia.org/wiki/List_of_HTTP_status_codes].
+# You can look up the response class for a given code:
+#
+#   Net::HTTPResponse::CODE_TO_OBJ['200'] # => Net::HTTPOK
+#   Net::HTTPResponse::CODE_TO_OBJ['400'] # => Net::HTTPBadRequest
+#   Net::HTTPResponse::CODE_TO_OBJ['404'] # => Net::HTTPNotFound
+#
+# And you can retrieve the status code for a response object:
+#
+#   Net::HTTP.get_response(uri).code                 # => "200"
+#   Net::HTTP.get_response(hostname, '/nosuch').code # => "404"
+#
+# The response subclasses (indentation shows class hierarchy):
+#
+# - Net::HTTPUnknownResponse (for unhandled \HTTP extensions).
+#
+# - Net::HTTPInformation:
+#
+#   - Net::HTTPContinue (100)
+#   - Net::HTTPSwitchProtocol (101)
+#   - Net::HTTPProcessing (102)
+#   - Net::HTTPEarlyHints (103)
+#
+# - Net::HTTPSuccess:
+#
+#   - Net::HTTPOK (200)
+#   - Net::HTTPCreated (201)
+#   - Net::HTTPAccepted (202)
+#   - Net::HTTPNonAuthoritativeInformation (203)
+#   - Net::HTTPNoContent (204)
+#   - Net::HTTPResetContent (205)
+#   - Net::HTTPPartialContent (206)
+#   - Net::HTTPMultiStatus (207)
+#   - Net::HTTPAlreadyReported (208)
+#   - Net::HTTPIMUsed (226)
+#
+# - Net::HTTPRedirection:
+#
+#   - Net::HTTPMultipleChoices (300)
+#   - Net::HTTPMovedPermanently (301)
+#   - Net::HTTPFound (302)
+#   - Net::HTTPSeeOther (303)
+#   - Net::HTTPNotModified (304)
+#   - Net::HTTPUseProxy (305)
+#   - Net::HTTPTemporaryRedirect (307)
+#   - Net::HTTPPermanentRedirect (308)
 #
-# This class wraps together the response header and the response body (the
-# entity requested).
+# - Net::HTTPClientError:
 #
-# It mixes in the HTTPHeader module, which provides access to response
-# header values both via hash-like methods and via individual readers.
+#   - Net::HTTPBadRequest (400)
+#   - Net::HTTPUnauthorized (401)
+#   - Net::HTTPPaymentRequired (402)
+#   - Net::HTTPForbidden (403)
+#   - Net::HTTPNotFound (404)
+#   - Net::HTTPMethodNotAllowed (405)
+#   - Net::HTTPNotAcceptable (406)
+#   - Net::HTTPProxyAuthenticationRequired (407)
+#   - Net::HTTPRequestTimeOut (408)
+#   - Net::HTTPConflict (409)
+#   - Net::HTTPGone (410)
+#   - Net::HTTPLengthRequired (411)
+#   - Net::HTTPPreconditionFailed (412)
+#   - Net::HTTPRequestEntityTooLarge (413)
+#   - Net::HTTPRequestURITooLong (414)
+#   - Net::HTTPUnsupportedMediaType (415)
+#   - Net::HTTPRequestedRangeNotSatisfiable (416)
+#   - Net::HTTPExpectationFailed (417)
+#   - Net::HTTPMisdirectedRequest (421)
+#   - Net::HTTPUnprocessableEntity (422)
+#   - Net::HTTPLocked (423)
+#   - Net::HTTPFailedDependency (424)
+#   - Net::HTTPUpgradeRequired (426)
+#   - Net::HTTPPreconditionRequired (428)
+#   - Net::HTTPTooManyRequests (429)
+#   - Net::HTTPRequestHeaderFieldsTooLarge (431)
+#   - Net::HTTPUnavailableForLegalReasons (451)
 #
-# Note that each possible HTTP response code defines its own
-# HTTPResponse subclass. All classes are defined under the Net module.
-# Indentation indicates inheritance.  For a list of the classes see Net::HTTP.
+# - Net::HTTPServerError:
 #
-# Correspondence <code>HTTP code => class</code> is stored in CODE_TO_OBJ
-# constant:
+#   - Net::HTTPInternalServerError (500)
+#   - Net::HTTPNotImplemented (501)
+#   - Net::HTTPBadGateway (502)
+#   - Net::HTTPServiceUnavailable (503)
+#   - Net::HTTPGatewayTimeOut (504)
+#   - Net::HTTPVersionNotSupported (505)
+#   - Net::HTTPVariantAlsoNegotiates (506)
+#   - Net::HTTPInsufficientStorage (507)
+#   - Net::HTTPLoopDetected (508)
+#   - Net::HTTPNotExtended (510)
+#   - Net::HTTPNetworkAuthenticationRequired (511)
 #
-#    Net::HTTPResponse::CODE_TO_OBJ['404'] #=> Net::HTTPNotFound
+# There is also the Net::HTTPBadResponse exception which is raised when
+# there is a protocol error.
 #
 class Net::HTTPResponse
   class << self