diff options
| author | nagachika <nagachika@ruby-lang.org> | 2023-12-16 10:21:21 +0900 |
|---|---|---|
| committer | nagachika <nagachika@ruby-lang.org> | 2023-12-16 10:48:39 +0900 |
| commit | 9e4b0c4c3f2354a30fe144c72400cfd6374ee7a7 (patch) | |
| tree | 447e9e3030a440dd9a30c7279a01a172e5d53e1c /lib | |
| parent | 74444d539dbb0c5c460f42cdaf0a23a59c10972f (diff) | |
merge revision(s) 35aba09e7f0d6b643c6446f44acdec654519ca64,8c8645f57895d97f5f3da06759c10853ba705a22,8f678d61a597fc2871031d7a38698f3dd63d8c29,44b7fd8d4fa842523813195dfb7255ce33fdf9ca,308942920f4e200468673be03c646f0645a84263,401aa9ddd1091f5b517dce37cd002bc2c37f5ac1,8250b4679453c095eab2f60d9147ca2fe4da32c6,fe7d4eed2511ff64f263d9f29cbf0dcbd4c3a026,d92289f6330c57b0fe970a654dbf33314bfd6203,3ebc80314cf1ce727dcc2ba4192ff5265d348206,5a9e2f142d9debfb44d7d23f6821b810607d9d15,3e5a77f1ae73f4a6bf7b2b868be674ab8c714c7a,faa4c2279aa018a2bb9bc09107adf8a8fcf5fd3d,6db79aefec27035583c5b236d98425748b428c49,06195e76037b500eac219b58506e34f0d852b472,a641f6422c97a72640dc295f6b1b3ec2b9da739e,2c7fe9c0a6a2cea1243dcb30e684bf8c016f1192,bc6e587e86a4a4a46af3b1c2fbe1ff3b399735a6,3c7d5ccdce5707d7964f01f974db505d5add590f,847a0df058a4adb60266213cb8db7bb537c1d09e,a49bc73e1f33e8a0e40ff0c3fef6c6fe749f8179,899fad907c32b533bb73206d5e19204e526621ba,4edb2a29f67957fc7027eaad0c08e8003cfde609,7c47c2617a091e2a7abaeff329fdef47d1f3f3f5,05f016cdad84481c084543c6fa8b32205c19431f,6e6992e5db49a238baf290d9b9b521f6b6be5a19:
[ruby/net-http] Adding links to references
https://github.com/ruby/net-http/commit/b85530e6b8
---
lib/net/http/responses.rb | 206 ++++++++++++++++++++++++++++++++++++++++------
1 file changed, 180 insertions(+), 26 deletions(-)
[ruby/net-http] [DOC] Adding links to references
(https://github.com/ruby/net-http/pull/97)
https://github.com/ruby/net-http/commit/768115167a
---
lib/net/http/responses.rb | 83 ++++++++++++++++++++++++++++++++++++++++-------
1 file changed, 72 insertions(+), 11 deletions(-)
[ruby/net-http] Adding links to references
https://github.com/ruby/net-http/commit/1c8151aaf3
---
lib/net/http/responses.rb | 16 ++++++++++++++++
1 file changed, 16 insertions(+)
[ruby/net-http] Enhanced RDoc for HTTPHeader
https://github.com/ruby/net-http/commit/6a282eccdd
---
lib/net/http/header.rb | 39 +++++++++++++++++++++++++++++----------
1 file changed, 29 insertions(+), 10 deletions(-)
[ruby/net-http] [DOC] Enhanced RDoc for set_form
(https://github.com/ruby/net-http/pull/103)
https://github.com/ruby/net-http/commit/f6506ff889
---
lib/net/http/header.rb | 152 +++++++++++++++++++++++++++++++++----------------
1 file changed, 102 insertions(+), 50 deletions(-)
[ruby/net-http] [DOC] Header doc
(https://github.com/ruby/net-http/pull/104)
https://github.com/ruby/net-http/commit/3308362d9b
---
lib/net/http/header.rb | 18 ++++++++++++++++--
1 file changed, 16 insertions(+), 2 deletions(-)
[ruby/net-http] Correct doc error
https://github.com/ruby/net-http/commit/dc006d8419
---
lib/net/http/response.rb | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
Manually merged https://github.com/ruby/net-http/pull/106
Co-authored-by: Peter Zhu <peter@peterzhu.ca>
Co-authored-by: BurdetteLamar <burdettelamar@yahoo.com>
---
lib/net/http.rb | 109 +++++++++++++++++++++++++++-----------------------------
1 file changed, 52 insertions(+), 57 deletions(-)
[ruby/net-http] [DOC] Enhanced RDoc for Net::HTTP
(https://github.com/ruby/net-http/pull/110)
https://github.com/ruby/net-http/commit/b098caa5e4
---
doc/net-http/examples.rdoc | 3 +-
lib/net/http.rb | 166 +++++++++++++++++++++------------------------
2 files changed, 78 insertions(+), 91 deletions(-)
[ruby/net-http] Redirection revision
https://github.com/ruby/net-http/commit/9a4e2d3a2a
---
lib/net/http.rb | 62 ++++++++++++++++++++++++++++-----------------------------
1 file changed, 30 insertions(+), 32 deletions(-)
[ruby/net-http] [DOC] Enhanced RDoc for HTTPGenericRequest
(https://github.com/ruby/net-http/pull/113)
https://github.com/ruby/net-http/commit/14c8405702
---
lib/net/http/generic_request.rb | 92 +++++++++++++++++++++++++++++++++++++----
1 file changed, 84 insertions(+), 8 deletions(-)
[ruby/net-http] Remarks on inclusions
https://github.com/ruby/net-http/commit/dfd060c583
---
doc/net-http/included_getters.rdoc | 3 +
doc/net-http/included_setters.rdoc | 3 +
lib/net/http/requests.rb | 30 ++++++++++
lib/net/http/responses.rb | 120 +++++++++++++++++++++++++++++++++++++
4 files changed, 156 insertions(+)
create mode 100644 doc/net-http/included_getters.rdoc
create mode 100644 doc/net-http/included_setters.rdoc
[ruby/net-http] [DOC] Enhanced RDoc for write_timeout
(https://github.com/ruby/net-http/pull/115)
https://github.com/ruby/net-http/commit/6da39b0461
---
lib/net/http.rb | 17 +++++++++++++++--
1 file changed, 15 insertions(+), 2 deletions(-)
[ruby/net-http] [DOC] Enhanced RDoc for Net::HTTP
(https://github.com/ruby/net-http/pull/116)
https://github.com/ruby/net-http/commit/22c0d34002
---
lib/net/http.rb | 78 +++++++++++++++++++++++++++++++++++++++++++--------------
1 file changed, 59 insertions(+), 19 deletions(-)
* remove trailing spaces. [ci skip]
---
lib/net/http.rb | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
[ruby/net-http] [DOC] Reorganize doc for proxy server
(https://github.com/ruby/net-http/pull/117)
https://github.com/ruby/net-http/commit/f8b6b76cba
---
lib/net/http.rb | 198 ++++++++++++++++++++++++++++----------------------------
1 file changed, 100 insertions(+), 98 deletions(-)
[ruby/net-http] Enhanced RDoc for Net::HTTP
https://github.com/ruby/net-http/commit/e65a3d9f11
---
lib/net/http.rb | 19 +++++++++++++------
1 file changed, 13 insertions(+), 6 deletions(-)
[ruby/net-http] Enhanced RDoc for Compression
https://github.com/ruby/net-http/commit/cff88acd70
---
lib/net/http.rb | 28 +++++++++++++++++++++++-----
1 file changed, 23 insertions(+), 5 deletions(-)
[ruby/net-http] [DOC] Enhanced RDoc for request headers
(https://github.com/ruby/net-http/pull/120)
https://github.com/ruby/net-http/commit/b4eb8a7932
---
doc/net-http/included_setters.rdoc | 3 ---
lib/net/http/request.rb | 53 +++++++++++++++++++++++++++++++++++---
lib/net/http/requests.rb | 30 ++++++++++-----------
3 files changed, 64 insertions(+), 22 deletions(-)
delete mode 100644 doc/net-http/included_setters.rdoc
[ruby/net-http] [DOC] Enhanced RDoc for Net::HTTP#get
(https://github.com/ruby/net-http/pull/121)
https://github.com/ruby/net-http/commit/51b9af1eed
---
lib/net/http.rb | 53 +++++++++++++++++++++++------------------------------
1 file changed, 23 insertions(+), 30 deletions(-)
[ruby/net-http] [DOC] Enhanced RDoc for Net::HTTP
(https://github.com/ruby/net-http/pull/122)
https://github.com/ruby/net-http/commit/06f79cda87
---
lib/net/http.rb | 91 ++++++++++++++++++++++++++++++++++++---------------------
1 file changed, 57 insertions(+), 34 deletions(-)
[ruby/net-http] [DOC] Enhanced RDoc for Net::HTTP
(https://github.com/ruby/net-http/pull/123)
https://github.com/ruby/net-http/commit/220ff3f741
---
lib/net/http.rb | 118 +++++++++++++++++++++++++++++++++++++++++++++-----------
1 file changed, 96 insertions(+), 22 deletions(-)
[ruby/net-http] [DOC] Enhanced RDoc for Net:HTTP
(https://github.com/ruby/net-http/pull/124)
https://github.com/ruby/net-http/commit/aaf26b21d6
---
lib/net/http.rb | 35 ++++++++++++++++-------------------
1 file changed, 16 insertions(+), 19 deletions(-)
[ruby/net-http] [DOC] Enhanced RDoc for Net::HTTP
(https://github.com/ruby/net-http/pull/125)
https://github.com/ruby/net-http/commit/2ea20380fc
---
lib/net/http.rb | 130 +++++++++++++++++++++++++++++++++++++-------------------
1 file changed, 87 insertions(+), 43 deletions(-)
[ruby/net-http] [DOC] Enhanced RDoc for Net::HTTP
(https://github.com/ruby/net-http/pull/126)
https://github.com/ruby/net-http/commit/4700d0660b
---
lib/net/http.rb | 87 +++++++++++++++++++++++++++++++-------------------
lib/net/http/status.rb | 2 +-
2 files changed, 55 insertions(+), 34 deletions(-)
[ruby/net-http] [DOC] Enhanced RDoc for Net::HTTP
(https://github.com/ruby/net-http/pull/127)
https://github.com/ruby/net-http/commit/07b2b88ef5
---
lib/net/http.rb | 65 +++++++++++++++++++++++++++++++--------------------------
1 file changed, 35 insertions(+), 30 deletions(-)
Diffstat (limited to 'lib')
| -rw-r--r-- | lib/net/http.rb | 1126 | ||||
| -rw-r--r-- | lib/net/http/generic_request.rb | 92 | ||||
| -rw-r--r-- | lib/net/http/header.rb | 209 | ||||
| -rw-r--r-- | lib/net/http/request.rb | 53 | ||||
| -rw-r--r-- | lib/net/http/requests.rb | 30 | ||||
| -rw-r--r-- | lib/net/http/response.rb | 2 | ||||
| -rw-r--r-- | lib/net/http/responses.rb | 425 | ||||
| -rw-r--r-- | lib/net/http/status.rb | 2 |
8 files changed, 1371 insertions, 568 deletions
diff --git a/lib/net/http.rb b/lib/net/http.rb index 47e62d6e70..521f576fbc 100644 --- a/lib/net/http.rb +++ b/lib/net/http.rb @@ -34,72 +34,70 @@ module Net #:nodoc: # \Class \Net::HTTP provides a rich library that implements the client # in a client-server model that uses the \HTTP request-response protocol. - # For information about \HTTP, see + # For information about \HTTP, see: # # - {Hypertext Transfer Protocol}[https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol]. # - {Technical overview}[https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Technical_overview]. # - # Note: If you are performing only a few GET requests, consider using - # {OpenURI}[rdoc-ref:OpenURI]; - # otherwise, read on. - # - # == Synopsis - # - # If you are already familiar with \HTTP, this synopsis may be helpful. - # - # {Session}[rdoc-ref:Net::HTTP@Sessions] with multiple requests for - # {HTTP methods}[https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Request_methods]: - # - # Net::HTTP.start(hostname) do |http| - # # Session started automatically before block execution. - # http.get(path_or_uri, headers = {}) - # http.head(path_or_uri, headers = {}) - # http.post(path_or_uri, data, headers = {}) # Can also have a block. - # http.put(path_or_uri, data, headers = {}) - # http.delete(path_or_uri, headers = {Depth: 'Infinity'}) - # http.options(path_or_uri, headers = {}) - # http.trace(path_or_uri, headers = {}) - # http.patch(path_or_uri, data, headers = {}) # Can also have a block. - # # Session finished automatically at block exit. - # end - # - # {Session}[rdoc-ref:Net::HTTP@Sessions] with multiple requests for - # {WebDAV methods}[https://en.wikipedia.org/wiki/WebDAV#Implementation]: - # - # Net::HTTP.start(hostname) do |http| - # # Session started automatically before block execution. - # http.copy(path_or_uri, headers = {}) - # http.lock(path_or_uri, body, headers = {}) - # http.mkcol(path_or_uri, body = nil, headers = {}) - # http.move(path_or_uri, headers = {}) - # http.propfind(path_or_uri, body = nil, headers = {'Depth' => '0'}) - # http.proppatch(path_or_uri, body, headers = {}) - # http.unlock(path_or_uri, body, headers = {}) - # # Session finished automatically at block exit. - # end - # - # Each of the following methods automatically starts and finishes - # a {session}[rdoc-ref:Net::HTTP@Sessions] that sends a single request: - # - # # Return string response body. - # Net::HTTP.get(hostname, path, port = 80) - # Net::HTTP.get(uri, headers = {}, port = 80) - # - # # Write string response body to $stdout. - # Net::HTTP.get_print(hostname, path_or_uri, port = 80) - # Net::HTTP.get_print(uri, headers = {}, port = 80) - # - # # Return response as Net::HTTPResponse object. - # Net::HTTP.get_response(hostname, path_or_uri, port = 80) - # Net::HTTP.get_response(uri, headers = {}, port = 80) - # - # Net::HTTP.post(uri, data, headers = {}) - # Net::HTTP.post_form(uri, params) - # # == About the Examples # # :include: doc/net-http/examples.rdoc # + # == Strategies + # + # - If you will make only a few GET requests, + # consider using {OpenURI}[rdoc-ref:OpenURI]. + # - If you will make only a few requests of all kinds, + # consider using the various singleton convenience methods in this class. + # Each of the following methods automatically starts and finishes + # a {session}[rdoc-ref:Net::HTTP@Sessions] that sends a single request: + # + # # Return string response body. + # Net::HTTP.get(hostname, path) + # Net::HTTP.get(uri) + # + # # Write string response body to $stdout. + # Net::HTTP.get_print(hostname, path) + # Net::HTTP.get_print(uri) + # + # # Return response as Net::HTTPResponse object. + # Net::HTTP.get_response(hostname, path) + # Net::HTTP.get_response(uri) + # data = '{"title": "foo", "body": "bar", "userId": 1}' + # Net::HTTP.post(uri, data) + # params = {title: 'foo', body: 'bar', userId: 1} + # Net::HTTP.post_form(uri, params) + # + # - If performance is important, consider using sessions, which lower request overhead. + # This {session}[rdoc-ref:Net::HTTP@Sessions] has multiple requests for + # {HTTP methods}[https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Request_methods] + # and {WebDAV methods}[https://en.wikipedia.org/wiki/WebDAV#Implementation]: + # + # Net::HTTP.start(hostname) do |http| + # # Session started automatically before block execution. + # http.get(path) + # http.head(path) + # body = 'Some text' + # http.post(path, body) # Can also have a block. + # http.put(path, body) + # http.delete(path) + # http.options(path) + # http.trace(path) + # http.patch(path, body) # Can also have a block. + # http.copy(path) + # http.lock(path, body) + # http.mkcol(path, body) + # http.move(path) + # http.propfind(path, body) + # http.proppatch(path, body) + # http.unlock(path, body) + # # Session finished automatically at block exit. + # end + # + # The methods cited above are convenience methods that, via their few arguments, + # allow minimal control over the requests. + # For greater control, consider using {request objects}[rdoc-ref:Net::HTTPRequest]. + # # == URIs # # On the internet, a URI @@ -183,7 +181,7 @@ module Net #:nodoc: # - May contain any number of requests. # - Is ended by instance method Net::HTTP#finish. # - # See example sessions at the {Synopsis}[rdoc-ref:Net::HTTP@Synopsis]. + # See example sessions at {Strategies}[rdoc-ref:Net::HTTP@Strategies]. # # === Session Using \Net::HTTP.start # @@ -264,66 +262,55 @@ module Net #:nodoc: # # == Following Redirection # - # Each Net::HTTPResponse object belongs to a class for its response code. - # - # For example, all 2XX responses are instances of a Net::HTTPSuccess - # subclass, a 3XX response is an instance of a Net::HTTPRedirection - # subclass and a 200 response is an instance of the Net::HTTPOK class. For - # details of response classes, see the section "HTTP Response Classes" - # below. + # Each returned response is an instance of a subclass of Net::HTTPResponse. + # See the {response class hierarchy}[rdoc-ref:Net::HTTPResponse@Response+Subclasses]. # - # Using a case statement you can handle various types of responses properly: + # In particular, class Net::HTTPRedirection is the parent + # of all redirection classes. + # This allows you to craft a case statement to handle redirections properly: # - # def fetch(uri_str, limit = 10) + # def fetch(uri, limit = 10) # # You should choose a better exception. - # raise ArgumentError, 'too many HTTP redirects' if limit == 0 - # - # response = Net::HTTP.get_response(URI(uri_str)) - # - # case response - # when Net::HTTPSuccess then - # response - # when Net::HTTPRedirection then - # location = response['location'] - # warn "redirected to #{location}" + # raise ArgumentError, 'Too many HTTP redirects' if limit == 0 + # + # res = Net::HTTP.get_response(URI(uri)) + # case res + # when Net::HTTPSuccess # Any success class. + # res + # when Net::HTTPRedirection # Any redirection class. + # location = res['Location'] + # warn "Redirected to #{location}" # fetch(location, limit - 1) - # else - # response.value + # else # Any other class. + # res.value # end # end # - # print fetch('http://www.ruby-lang.org') + # fetch(uri) # # == Basic Authentication # # Basic authentication is performed according to - # [RFC2617](http://www.ietf.org/rfc/rfc2617.txt). - # - # uri = URI('http://example.com/index.html?key=value') + # {RFC2617}[http://www.ietf.org/rfc/rfc2617.txt]: # # req = Net::HTTP::Get.new(uri) - # req.basic_auth 'user', 'pass' - # - # res = Net::HTTP.start(uri.hostname, uri.port) {|http| + # req.basic_auth('user', 'pass') + # res = Net::HTTP.start(hostname) do |http| # http.request(req) - # } - # puts res.body + # end # # == Streaming Response Bodies # - # By default Net::HTTP reads an entire response into memory. If you are + # By default \Net::HTTP reads an entire response into memory. If you are # handling large files or wish to implement a progress bar you can instead # stream the body directly to an IO. # - # uri = URI('http://example.com/large_file') - # - # Net::HTTP.start(uri.host, uri.port) do |http| - # request = Net::HTTP::Get.new uri - # - # http.request request do |response| - # open 'large_file', 'w' do |io| - # response.read_body do |chunk| - # io.write chunk + # Net::HTTP.start(hostname) do |http| + # req = Net::HTTP::Get.new(uri) + # http.request(req) do |res| + # open('t.tmp', 'w') do |f| + # res.read_body do |chunk| + # f.write chunk # end # end # end @@ -331,50 +318,141 @@ module Net #:nodoc: # # == HTTPS # - # HTTPS is enabled for an HTTP connection by Net::HTTP#use_ssl=. - # - # uri = URI('https://secure.example.com/some_path?query=string') + # HTTPS is enabled for an \HTTP connection by Net::HTTP#use_ssl=: # - # Net::HTTP.start(uri.host, uri.port, :use_ssl => true) do |http| - # request = Net::HTTP::Get.new uri - # response = http.request request # Net::HTTPResponse object + # Net::HTTP.start(hostname, :use_ssl => true) do |http| + # req = Net::HTTP::Get.new(uri) + # res = http.request(req) # end # - # Or if you simply want to make a GET request, you may pass in an URI - # object that has an HTTPS URL. Net::HTTP automatically turns on TLS - # verification if the URI object has a 'https' URI scheme. + # Or if you simply want to make a GET request, you may pass in a URI + # object that has an \HTTPS URL. \Net::HTTP automatically turns on TLS + # verification if the URI object has a 'https' URI scheme: + # + # uri # => #<URI::HTTPS https://jsonplaceholder.typicode.com/> + # Net::HTTP.get(uri) + # + # == Proxy Server + # + # An \HTTP object can have + # a {proxy server}[https://en.wikipedia.org/wiki/Proxy_server]. + # + # You can create an \HTTP object with a proxy server + # using method Net::HTTP.new or method Net::HTTP.start. + # + # The proxy may be defined either by argument +p_addr+ + # or by environment variable <tt>'http_proxy'</tt>. + # + # === Proxy Using Argument +p_addr+ as a \String + # + # When argument +p_addr+ is a string hostname, + # the returned +http+ has the given host as its proxy: + # + # http = Net::HTTP.new(hostname, nil, 'proxy.example') + # http.proxy? # => true + # http.proxy_from_env? # => false + # http.proxy_address # => "proxy.example" + # # These use default values. + # http.proxy_port # => 80 + # http.proxy_user # => nil + # http.proxy_pass # => nil + # + # The port, username, and password for the proxy may also be given: + # + # http = Net::HTTP.new(hostname, nil, 'proxy.example', 8000, 'pname', 'ppass') + # # => #<Net::HTTP jsonplaceholder.typicode.com:80 open=false> + # http.proxy? # => true + # http.proxy_from_env? # => false + # http.proxy_address # => "proxy.example" + # http.proxy_port # => 8000 + # http.proxy_user # => "pname" + # http.proxy_pass # => "ppass" + # + # === Proxy Using '<tt>ENV['http_proxy']</tt>' + # + # When environment variable <tt>'http_proxy'</tt> + # is set to a \URI string, + # the returned +http+ will have the server at that URI as its proxy; + # note that the \URI string must have a protocol + # such as <tt>'http'</tt> or <tt>'https'</tt>: + # + # ENV['http_proxy'] = 'http://example.com' + # http = Net::HTTP.new(hostname) + # http.proxy? # => true + # http.proxy_from_env? # => true + # http.proxy_address # => "example.com" + # # These use default values. + # http.proxy_port # => 80 + # http.proxy_user # => nil + # http.proxy_pass # => nil + # + # The \URI string may include proxy username, password, and port number: + # + # ENV['http_proxy'] = 'http://pname:ppass@example.com:8000' + # http = Net::HTTP.new(hostname) + # http.proxy? # => true + # http.proxy_from_env? # => true + # http.proxy_address # => "example.com" + # http.proxy_port # => 8000 + # http.proxy_user # => "pname" + # http.proxy_pass # => "ppass" + # + # === Filtering Proxies + # + # With method Net::HTTP.new (but not Net::HTTP.start), + # you can use argument +p_no_proxy+ to filter proxies: + # + # - Reject a certain address: + # + # http = Net::HTTP.new('example.com', nil, 'proxy.example', 8000, 'pname', 'ppass', 'proxy.example') + # http.proxy_address # => nil + # + # - Reject certain domains or subdomains: + # + # http = Net::HTTP.new('example.com', nil, 'my.proxy.example', 8000, 'pname', 'ppass', 'proxy.example') + # http.proxy_address # => nil + # + # - Reject certain addresses and port combinations: + # + # http = Net::HTTP.new('example.com', nil, 'proxy.example', 8000, 'pname', 'ppass', 'proxy.example:1234') + # http.proxy_address # => "proxy.example" # - # uri = URI('https://example.com/') - # Net::HTTP.get(uri) # => String + # http = Net::HTTP.new('example.com', nil, 'proxy.example', 8000, 'pname', 'ppass', 'proxy.example:8000') + # http.proxy_address # => nil # - # In previous versions of Ruby you would need to require 'net/https' to use - # HTTPS. This is no longer true. + # - Reject a list of the types above delimited using a comma: # - # == Proxies + # http = Net::HTTP.new('example.com', nil, 'proxy.example', 8000, 'pname', 'ppass', 'my.proxy,proxy.example:8000') + # http.proxy_address # => nil # - # Net::HTTP will automatically create a proxy from the +http_proxy+ - # environment variable if it is present. To disable use of +http_proxy+, - # pass +nil+ for the proxy address. + # http = Net::HTTP.new('example.com', nil, 'my.proxy', 8000, 'pname', 'ppass', 'my.proxy,proxy.example:8000') + # http.proxy_address # => nil # - # You may also create a custom proxy: + # == Compression and Decompression # - # proxy_addr = 'your.proxy.host' - # proxy_port = 8080 + # \Net::HTTP does not compress the body of a request before sending. # - # Net::HTTP.new('example.com', nil, proxy_addr, proxy_port).start { |http| - # # always proxy via your.proxy.addr:8080 - # } + # By default, \Net::HTTP adds header <tt>'Accept-Encoding'</tt> + # to a new {request object}[rdoc-ref:Net::HTTPRequest]: # - # See Net::HTTP.new for further details and examples such as proxies that - # require a username and password. + # Net::HTTP::Get.new(uri)['Accept-Encoding'] + # # => "gzip;q=1.0,deflate;q=0.6,identity;q=0.3" # - # == Compression + # This requests the server to zip-encode the response body if there is one; + # the server is not required to do so. # - # Net::HTTP automatically adds Accept-Encoding for compression of response - # bodies and automatically decompresses gzip and deflate responses unless a - # Range header was sent. + # \Net::HTTP does not automatically decompress a response body + # if the response has header <tt>'Content-Range'</tt>. # - # Compression can be disabled through the Accept-Encoding: identity header. + # Otherwise decompression (or not) depends on the value of header + # {Content-Encoding}[https://en.wikipedia.org/wiki/List_of_HTTP_header_fields#content-encoding-response-header]: + # + # - <tt>'deflate'</tt>, <tt>'gzip'</tt>, or <tt>'x-gzip'</tt>: + # decompresses the body and deletes the header. + # - <tt>'none'</tt> or <tt>'identity'</tt>: + # does not decompress the body, but deletes the header. + # - Any other value: + # leaves the body and header unchanged. # class HTTP < Protocol @@ -548,10 +626,10 @@ module Net #:nodoc: end # - # HTTP session management + # \HTTP session management # - # Returns intger +80+, the default port to use for HTTP requests: + # Returns integer +80+, the default port to use for \HTTP requests: # # Net::HTTP.default_port # => 80 # @@ -559,7 +637,7 @@ module Net #:nodoc: http_default_port() end - # Returns integer +80+, the default port to use for HTTP requests: + # Returns integer +80+, the default port to use for \HTTP requests: # # Net::HTTP.http_default_port # => 80 # @@ -585,14 +663,11 @@ module Net #:nodoc: # # Creates a new \Net::HTTP object, +http+, via \Net::HTTP.new: # - # Net::HTTP.new(address, port, p_addr, p_port, p_user, p_pass) - # - # - For arguments +hostname+ through +p_pass+, see Net::HTTP.new. + # - For arguments +address+ and +port+, see Net::HTTP.new. + # - For proxy-defining arguments +p_addr+ through +p_pass+, + # see {Proxy Server}[rdoc-ref:Net::HTTP@Proxy+Server]. # - For argument +opts+, see below. # - # Note: If +port+ is +nil+ and <tt>opts[:use_ssl]</tt> is a truthy value, - # the value passed to +new+ is Net::HTTP.https_default_port, not +port+. - # # With no block given: # # - Calls <tt>http.start</tt> with no block (see #start), @@ -665,6 +740,9 @@ module Net #:nodoc: # - #verify_mode # - #write_timeout # + # Note: If +port+ is +nil+ and <tt>opts[:use_ssl]</tt> is a truthy value, + # the value passed to +new+ is Net::HTTP.https_default_port, not +port+. + # def HTTP.start(address, *arg, &block) # :yield: +http+ arg.pop if opt = Hash.try_convert(arg[-1]) port, p_addr, p_port, p_user, p_pass = *arg @@ -691,12 +769,10 @@ module Net #:nodoc: alias newobj new # :nodoc: end - # Returns a new Net::HTTP object +http+ - # (but does not open a TCP connection or HTTP session). - # - # <b>No Proxy</b> + # Returns a new \Net::HTTP object +http+ + # (but does not open a TCP connection or \HTTP session). # - # With only string argument +hostname+ given + # With only string argument +address+ given # (and <tt>ENV['http_proxy']</tt> undefined or +nil+), # the returned +http+: # @@ -719,85 +795,8 @@ module Net #:nodoc: # # => #<Net::HTTP jsonplaceholder.typicode.com:8000 open=false> # http.port # => 8000 # - # <b>Proxy Using Argument +p_addr+ as a \String</b> - # - # When argument +p_addr+ is a string hostname, - # the returned +http+ has a proxy: - # - # http = Net::HTTP.new(hostname, nil, 'proxy.example') - # # => #<Net::HTTP jsonplaceholder.typicode.com:80 open=false> - # http.proxy? # => true - # http.proxy_address # => "proxy.example" - # # These use default values. - # http.proxy_port # => 80 - # http.proxy_user # => nil - # http.proxy_pass # => nil - # - # The port, username, and password for the proxy may also be given: - # - # http = Net::HTTP.new(hostname, nil, 'proxy.example', 8000, 'pname', 'ppass') - # # => #<Net::HTTP jsonplaceholder.typicode.com:80 open=false> - # http.proxy? # => true - # http.proxy_address # => "proxy.example" - # http.proxy_port # => 8000 - # http.proxy_user # => "pname" - # http.proxy_pass # => "ppass" - # - # <b>Proxy Using <tt>ENV['http_proxy']</tt></b> - # - # When environment variable <tt>'http_proxy'</tt> - # is set to a \URI string, - # the returned +http+ will have that URI as its proxy; - # note that the \URI string must have a protocol - # such as <tt>'http'</tt> or <tt>'https'</tt>: - # - # ENV['http_proxy'] = 'http://example.com' - # # => "http://example.com" - # http = Net::HTTP.new(hostname) - # # => #<Net::HTTP jsonplaceholder.typicode.com:80 open=false> - # http.proxy? # => true - # http.address # => "jsonplaceholder.typicode.com" - # http.proxy_address # => "example.com" - # - # The \URI string may include proxy username, password, and port number: - # - # ENV['http_proxy'] = 'http://pname:ppass@example.com:8000' - # # => "http://pname:ppass@example.com:8000" - # http = Net::HTTP.new(hostname) - # # => #<Net::HTTP jsonplaceholder.typicode.com:80 open=false> - # http.proxy_port # => 8000 - # http.proxy_user # => "pname" - # http.proxy_pass # => "ppass" - # - # <b>Argument +p_no_proxy+</b> - # - # You can use argument +p_no_proxy+ to reject certain proxies: - # - # - Reject a certain address: - # - # http = Net::HTTP.new('example.com', nil, 'proxy.example', 8000, 'pname', 'ppass', 'proxy.example') - # http.proxy_address # => nil - # - # - Reject certain domains or subdomains: - # - # http = Net::HTTP.new('example.com', nil, 'my.proxy.example', 8000, 'pname', 'ppass', 'proxy.example') - # http.proxy_address # => nil - # - # - Reject certain addresses and port combinations: - # - # http = Net::HTTP.new('example.com', nil, 'proxy.example', 8000, 'pname', 'ppass', 'proxy.example:1234') - # http.proxy_address # => "proxy.example" - # - # http = Net::HTTP.new('example.com', nil, 'proxy.example', 8000, 'pname', 'ppass', 'proxy.example:8000') - # http.proxy_address # => nil - # - # - Reject a list of the types above delimited using a comma: - # - # http = Net::HTTP.new('example.com', nil, 'proxy.example', 8000, 'pname', 'ppass', 'my.proxy,proxy.example:8000') - # http.proxy_address # => nil - # - # http = Net::HTTP.new('example.com', nil, 'my.proxy', 8000, 'pname', 'ppass', 'my.proxy,proxy.example:8000') - # http.proxy_address # => nil + # For proxy-defining arguments +p_addr+ through +p_no_proxy+, + # see {Proxy Server}[rdoc-ref:Net::HTTP@Proxy+Server]. # def HTTP.new(address, port = nil, p_addr = :ENV, p_port = nil, p_user = nil, p_pass = nil, p_no_proxy = nil) http = super address, port @@ -824,10 +823,10 @@ module Net #:nodoc: http end - # Creates a new Net::HTTP object for the specified server address, - # without opening the TCP connection or initializing the HTTP session. + # Creates a new \Net::HTTP object for the specified server address, + # without opening the TCP connection or initializing the \HTTP session. # The +address+ should be a DNS hostname or IP address. - def initialize(address, port = nil) + def initialize(address, port = nil) # :nodoc: @address = address @port = (port || HTTP.default_port) @ipaddr = nil @@ -927,21 +926,22 @@ module Net #:nodoc: @debug_output = output end - # The DNS host name or IP address to connect to. + # Returns the string host name or host IP given as argument +address+ in ::new. attr_reader :address - # The port number to connect to. + # Returns the integer port number given as argument +port+ in ::new. attr_reader :port - # The local host used to establish the connection. + # Sets or returns the string local host used to establish the connection; + # initially +nil+. attr_accessor :local_host - # The local port used to establish the connection. + # Sets or returns the integer local port used to establish the connection; + # initially +nil+. attr_accessor :local_port - # The encoding to use for the response body. If Encoding, uses the - # specified encoding. If other true value, tries to detect the response - # body encoding. + # Returns the encoding to use for the response body; + # see #response_body_encoding=. attr_reader :response_body_encoding # Sets the encoding to be used for the response body; @@ -967,10 +967,25 @@ module Net #:nodoc: @response_body_encoding = value end + # Sets whether to determine the proxy from environment variable + # '<tt>ENV['http_proxy']</tt>'; + # see {Proxy Using ENV['http_proxy']}[rdoc-ref:Net::HTTP@Proxy+Using+-27ENV-5B-27http_proxy-27-5D-27]. attr_writer :proxy_from_env + + # Sets the proxy address; + # see {Proxy Server}[rdoc-ref:Net::HTTP@Proxy+Server]. attr_writer :proxy_address + + # Sets the proxy port; + # see {Proxy Server}[rdoc-ref:Net::HTTP@Proxy+Server]. attr_writer :proxy_port + + # Sets the proxy user; + # see {Proxy Server}[rdoc-ref:Net::HTTP@Proxy+Server]. attr_writer :proxy_user + + # Sets the proxy password; + # see {Proxy Server}[rdoc-ref:Net::HTTP@Proxy+Server]. attr_writer :proxy_pass # Returns the IP address for the connection. @@ -1009,27 +1024,25 @@ module Net #:nodoc: @ipaddr = addr end - # Number of seconds to wait for the connection to open. Any number - # may be used, including Floats for fractional seconds. If the HTTP - # object cannot open a connection in this many seconds, it raises a - # Net::OpenTimeout exception. The default value is 60 seconds. + # Sets or returns the numeric (\Integer or \Float) number of seconds + # to wait for a connection to open; + # initially 60. + # If the connection is not made in the given interval, + # an exception is raised. attr_accessor :open_timeout - # Number of seconds to wait for one block to be read (via one read(2) - # call). Any number may be used, including Floats for fractional - # seconds. If the HTTP object cannot read data in this many seconds, - # it raises a Net::ReadTimeout exception. The default value is 60 seconds. + # Returns the numeric (\Integer or \Float) number of seconds + # to wait for one block to be read (via one read(2) call); + # see #read_timeout=. attr_reader :read_timeout - # Number of seconds to wait for one block to be written (via one write(2) - # call). Any number may be used, including Floats for fractional - # seconds. If the HTTP object cannot write data in this many seconds, - # it raises a Net::WriteTimeout exception. The default value is 60 seconds. - # Net::WriteTimeout is not raised on Windows. + # Returns the numeric (\Integer or \Float) number of seconds + # to wait for one block to be written (via one write(2) call); + # see #write_timeout=. attr_reader :write_timeout # Sets the maximum number of times to retry an idempotent request in case of - # Net::ReadTimeout, IOError, EOFError, Errno::ECONNRESET, + # \Net::ReadTimeout, IOError, EOFError, Errno::ECONNRESET, # Errno::ECONNABORTED, Errno::EPIPE, OpenSSL::SSL::SSLError, # Timeout::Error. # The initial value is 1. @@ -1048,6 +1061,8 @@ module Net #:nodoc: @max_retries = retries end + # Returns the maximum number of times to retry an idempotent request; + # see #max_retries=. attr_reader :max_retries # Sets the read timeout, in seconds, for +self+ to integer +sec+; @@ -1069,52 +1084,90 @@ module Net #:nodoc: # Sets the write timeout, in seconds, for +self+ to integer +sec+; # the initial value is 60. # - # Argument +sec+ must be a non-negative numeric value. + # Argument +sec+ must be a non-negative numeric value: + # + # _uri = uri.dup + # _uri.path = '/posts' + # body = 'bar' * 200000 + # data = <<EOF + # {"title": "foo", "body": "#{body}", "userId": "1"} + # EOF + # headers = {'content-type': 'application/json'} + # http = Net::HTTP.new(hostname) + # http.write_timeout # => 60 + # http.post(_uri.path, data, headers) + # # => #<Net::HTTPCreated 201 Created readbody=true> + # http.write_timeout = 0 + # http.post(_uri.path, data, headers) # Raises Net::WriteTimeout. # def write_timeout=(sec) @socket.write_timeout = sec if @socket @write_timeout = sec end - # Seconds to wait for 100 Continue response. If the HTTP object does not - # receive a response in this many seconds it sends the request body. The - # default value is +nil+. + # Returns the continue timeout value; + # see continue_timeout=. attr_reader :continue_timeout - # Setter for the continue_timeout attribute. + # Sets the continue timeout value, + # which is the number of seconds to wait for an expected 100 Continue response. + # If the \HTTP object does not receive a response in this many seconds + # it sends the request body. def continue_timeout=(sec) @socket.continue_timeout = sec if @socket @continue_timeout = sec end - # Seconds to reuse the connection of the previous request. - # If the idle time is less than this Keep-Alive Timeout, - # Net::HTTP reuses the TCP/IP socket used by the previous communication. - # The default value is 2 seconds. + # Sets or returns the numeric (\Integer or \Float) number of seconds + # to keep the connection open after a request is sent; + # initially 2. + # If a new request is made during the given interval, + # the still-open connection is used; + # otherwise the connection will have been closed + # and a new connection is opened. attr_accessor :keep_alive_timeout - # Whether to ignore EOF when reading response bodies with defined - # Content-Length headers. For backwards compatibility, the default is true. + # Sets or returns whether to ignore end-of-file when reading a response body + # with <tt>Content-Length</tt> headers; + # initially +true+. attr_accessor :ignore_eof - # Returns true if the HTTP session has been started. + # Returns +true+ if the \HTTP session has been started: + # + # http = Net::HTTP.new(hostname) + # http.started? # => false + # http.start + # http.started? # => true + # http.finish # => nil + # http.started? # => false + # + # Net::HTTP.start(hostname) do |http| + # http.started? + # end # => true + # http.started? # => false + # def started? @started end alias active? started? #:nodoc: obsolete + # Sets or returns whether to close the connection when the response is empty; + # initially +false+. attr_accessor :close_on_empty_response - # Returns true if SSL/TLS is being used with HTTP. + # Returns +true+ if +self+ uses SSL, +false+ otherwise. + # See Net::HTTP#use_ssl=. def use_ssl? @use_ssl end - # Turn on/off SSL. - # This flag must be set before starting session. - # If you change use_ssl value after session started, - # a Net::HTTP object raises IOError. + # Sets whether a new session is to use + # {Transport Layer Security}[https://en.wikipedia.org/wiki/Transport_Layer_Security]: + # + # Raises IOError if attempting to change during a session. + # + # Raises OpenSSL::SSL::SSLError if the port is not an HTTPS port. def use_ssl=(flag) flag = flag ? true : false if started? and @use_ssl != flag @@ -1139,7 +1192,7 @@ module Net #:nodoc: :@verify_depth, :@verify_mode, :@verify_hostname, - ] + ] # :nodoc: SSL_ATTRIBUTES = [ :ca_file, :ca_path, @@ -1156,64 +1209,67 @@ module Net #:nodoc: :verify_depth, :verify_mode, :verify_hostname, - ] + ] # :nodoc: - # Sets path of a CA certification file in PEM format. - # - # The file can contain several CA certificates. + # Sets or returns the path to a CA certification file in PEM format. attr_accessor :ca_file - # Sets path of a CA certification directory containing certifications in - # PEM format. + # Sets or returns the path of to CA directory + # containing certification files in PEM format. attr_accessor :ca_path - # Sets an OpenSSL::X509::Certificate object as client certificate. - # (This method is appeared in Michal Rokos's OpenSSL extension). + # Sets or returns the OpenSSL::X509::Certificate object + # to be used for client certification. attr_accessor :cert - # Sets the X509::Store to verify peer certificate. + # Sets or returns the X509::Store to be used for verifying peer certificate. attr_accessor :cert_store - # Sets the available ciphers. See OpenSSL::SSL::SSLContext#ciphers= + # Sets or returns the available SSL ciphers. + # See {OpenSSL::SSL::SSLContext#ciphers=}[rdoc-ref:OpenSSL::SSL::SSLContext#ciphers-3D]. attr_accessor :ciphers - # Sets the extra X509 certificates to be added to the certificate chain. - # See OpenSSL::SSL::SSLContext#extra_chain_cert= + # Sets or returns the extra X509 certificates to be added to the certificate chain. + # See {OpenSSL::SSL::SSLContext#add_certificate}[rdoc-ref:OpenSSL::SSL::SSLContext#add_certificate]. attr_accessor :extra_chain_cert - # Sets an OpenSSL::PKey::RSA or OpenSSL::PKey::DSA object. - # (This method is appeared in Michal Rokos's OpenSSL extension.) + # Sets or returns the OpenSSL::PKey::RSA or OpenSSL::PKey::DSA object. attr_accessor :key - # Sets the SSL timeout seconds. + # Sets or returns the SSL timeout seconds. attr_accessor :ssl_timeout - # Sets the SSL version. See OpenSSL::SSL::SSLContext#ssl_version= + # Sets or returns the SSL version. + # See {OpenSSL::SSL::SSLContext#ssl_version=}[rdoc-ref:OpenSSL::SSL::SSLContext#ssl_version-3D]. attr_accessor :ssl_version - # Sets the minimum SSL version. See OpenSSL::SSL::SSLContext#min_version= + # Sets or returns the minimum SSL version. + # See {OpenSSL::SSL::SSLContext#min_version=}[rdoc-ref:OpenSSL::SSL::SSLContext#min_version-3D]. attr_accessor :min_version - # Sets the maximum SSL version. See OpenSSL::SSL::SSLContext#max_version= + # Sets or returns the maximum SSL version. + # See {OpenSSL::SSL::SSLContext#max_version=}[rdoc-ref:OpenSSL::SSL::SSLContext#max_version-3D]. attr_accessor :max_version - # Sets the verify callback for the server certification verification. + # Sets or returns the callback for the server certification verification. attr_accessor :verify_callback - # Sets the maximum depth for the certificate chain verification. + # Sets or returns the maximum depth for the certificate chain verification. attr_accessor :verify_depth - # Sets the flags for server the certification verification at beginning of - # SSL/TLS session. - # + # Sets or returns the flags for server the certification verification + # at the beginning of the SSL/TLS session. # OpenSSL::SSL::VERIFY_NONE or OpenSSL::SSL::VERIFY_PEER are acceptable. attr_accessor :verify_mode - # Sets to check the server certificate is valid for the hostname. - # See OpenSSL::SSL::SSLContext#verify_hostname= + # Sets or returns whether to verify that the server certificate is valid + # for the hostname. + # See {OpenSSL::SSL::SSLContext#verify_hostname=}[rdoc-ref:OpenSSL::SSL::SSLContext#attribute-i-verify_mode]. attr_accessor :verify_hostname - # Returns the X.509 certificates the server presented. + # Returns the X509 certificate chain (an array of strings) + # for the session's socket peer, + # or +nil+ if none. def peer_cert if not use_ssl? or not @socket return nil @@ -1221,14 +1277,26 @@ module Net #:nodoc: @socket.io.peer_cert end - # Opens a TCP connection and HTTP session. + # Starts an \HTTP session. # - # When this method is called with a block, it passes the Net::HTTP - # object to the block, and closes the TCP connection and HTTP session - # after the block has been executed. + # Without a block, returns +self+: # - # When called with a block, it returns the return value of the - # block; otherwise, it returns self. + # http = Net::HTTP.new(hostname) + # # => #<Net::HTTP jsonplaceholder.typicode.com:80 open=false> + # http.start + # # => #<Net::HTTP jsonplaceholder.typicode.com:80 open=true> + # http.started? # => true + # http.finish + # + # With a block, calls the block with +self+, + # finishes the session when the block exits, + # and returns the block's value: + # + # http.start do |http| + # http + # end + # # => #<Net::HTTP jsonplaceholder.typicode.com:80 open=false> + # http.started? # => false # def start # :yield: http raise IOError, 'HTTP session already opened' if @started @@ -1364,8 +1432,15 @@ module Net #:nodoc: end private :on_connect - # Finishes the HTTP session and closes the TCP connection. - # Raises IOError if the session has not been started. + # Finishes the \HTTP session: + # + # http = Net::HTTP.new(hostname) + # http.start + # http.started? # => true + # http.finish # => nil + # http.started? # => false + # + # Raises IOError if not in a session. def finish raise IOError, 'HTTP session not yet started' unless started? do_finish @@ -1392,11 +1467,11 @@ module Net #:nodoc: @proxy_user = nil @proxy_pass = nil - # Creates an HTTP proxy class which behaves like Net::HTTP, but + # Creates an \HTTP proxy class which behaves like \Net::HTTP, but # performs all access via the specified proxy. # # This class is obsolete. You may pass these same parameters directly to - # Net::HTTP.new. See Net::HTTP.new for details of the arguments. + # \Net::HTTP.new. See Net::HTTP.new for details of the arguments. def HTTP.Proxy(p_addr = :ENV, p_port = nil, p_user = nil, p_pass = nil) #:nodoc: return self unless p_addr @@ -1424,26 +1499,32 @@ module Net #:nodoc: defined?(@is_proxy_class) ? @is_proxy_class : false end - # Address of proxy host. If Net::HTTP does not use a proxy, nil. + # Returns the address of the proxy host, or +nil+ if none; + # see Net::HTTP@Proxy+Server. attr_reader :proxy_address - # Port number of proxy host. If Net::HTTP does not use a proxy, nil. + # Returns the port number of the proxy host, or +nil+ if none; + # see Net::HTTP@Proxy+Server. attr_reader :proxy_port - # User name for accessing proxy. If Net::HTTP does not use a proxy, nil. + # Returns the user name for accessing the proxy, or +nil+ if none; + # see Net::HTTP@Proxy+Server. attr_reader :proxy_user - # User password for accessing proxy. If Net::HTTP does not use a proxy, - # nil. + # Returns the password for accessing the proxy, or +nil+ if none; + # see Net::HTTP@Proxy+Server. attr_reader :proxy_pass end - # True if requests for this connection will be proxied + # Returns +true+ if a proxy server is defined, +false+ otherwise; + # see {Proxy Server}[rdoc-ref:Net::HTTP@Proxy+Server]. def proxy? !!(@proxy_from_env ? proxy_uri : @proxy_address) end - # True if the proxy for this connection is determined from the environment + # Returns +true+ if the proxy server is defined in the environment, + # +false+ otherwise; + # see {Proxy Server}[rdoc-ref:Net::HTTP@Proxy+Server]. def proxy_from_env? @proxy_from_env end @@ -1457,7 +1538,8 @@ module Net #:nodoc: @proxy_uri || nil end - # The address of the proxy server, if one is configured. + # Returns the address of the proxy server, if defined, +nil+ otherwise; + # see {Proxy Server}[rdoc-ref:Net::HTTP@Proxy+Server]. def proxy_address if @proxy_from_env then proxy_uri&.hostname @@ -1466,7 +1548,8 @@ module Net #:nodoc: end end - # The port of the proxy server, if one is configured. + # Returns the port number of the proxy server, if defined, +nil+ otherwise; + # see {Proxy Server}[rdoc-ref:Net::HTTP@Proxy+Server]. def proxy_port if @proxy_from_env then proxy_uri&.port @@ -1475,7 +1558,8 @@ module Net #:nodoc: end end - # The username of the proxy server, if one is configured. + # Returns the user name of the proxy server, if defined, +nil+ otherwise; + # see {Proxy Server}[rdoc-ref:Net::HTTP@Proxy+Server]. def proxy_user if @proxy_from_env user = proxy_uri&.user @@ -1485,7 +1569,8 @@ module Net #:nodoc: end end - # The password of the proxy server, if one is configured. + # Returns the password of the proxy server, if defined, +nil+ otherwise; + # see {Proxy Server}[rdoc-ref:Net::HTTP@Proxy+Server]. def proxy_pass if @proxy_from_env pass = proxy_uri&.password @@ -1533,45 +1618,38 @@ module Net #:nodoc: public - # Retrieves data from +path+ on the connected-to host which may be an - # absolute path String or a URI to extract the path from. + # :call-seq: + # get(path, initheader = nil) {|res| ... } # - # +initheader+ must be a Hash like { 'Accept' => '*/*', ... }, - # and it defaults to an empty hash. - # If +initheader+ doesn't have the key 'accept-encoding', then - # a value of "gzip;q=1.0,deflate;q=0.6,identity;q=0.3" is used, - # so that gzip compression is used in preference to deflate - # compression, which is used in preference to no compression. - # Ruby doesn't have libraries to support the compress (Lempel-Ziv) - # compression, so that is not supported. The intent of this is - # to reduce bandwidth by default. If this routine sets up - # compression, then it does the decompression also, removing - # the header as well to prevent confusion. Otherwise - # it leaves the body as it found it. + # Sends a GET request to the server; + # returns an instance of a subclass of Net::HTTPResponse. # - # This method returns a Net::HTTPResponse object. + # The request is based on the Net::HTTP::Get object + # created from string +path+ and initial headers hash +initheader+. # - # 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. + # With a block given, calls the block with the response body: # - # +dest+ argument is obsolete. - # It still works but you must not use it. + # http = Net::HTTP.new(hostname) + # http.get('/todos/1') do |res| + # p res + # end # => #<Net::HTTPOK 200 OK readbody=true> # - # This method never raises an exception. + # Output: + # + # "{\n \"userId\": 1,\n \"id\": 1,\n \"title\": \"delectus aut autem\",\n \"completed\": false\n}" # - # response = http.get('/index.html') + # With no block given, simply returns the response object: # - # # using block - # File.open('result.txt', 'w') {|f| - # http.get('/~foo/') do |str| - # f.write str - # end - # } + # http.get('/') # => #<Net::HTTPOK 200 OK readbody=true> + # + # Related: + # + # - Net::HTTP::Get: request class for \HTTP method GET. + # - Net::HTTP.get: sends GET request, returns response body. # 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 @@ -1579,198 +1657,312 @@ module Net #:nodoc: 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. + # Sends a HEAD request to the server; + # returns an instance of a subclass of Net::HTTPResponse. # - # This method never raises an exception. + # The request is based on the Net::HTTP::Head object + # created from string +path+ and initial headers hash +initheader+: # - # response = nil - # Net::HTTP.start('some.www.server', 80) {|http| - # response = http.head('/index.html') - # } - # p response['content-type'] + # res = http.head('/todos/1') # => #<Net::HTTPOK 200 OK readbody=true> + # res.body # => nil + # res.to_hash.take(3) + # # => + # [["date", ["Wed, 15 Feb 2023 15:25:42 GMT"]], + # ["content-type", ["application/json; charset=utf-8"]], + # ["connection", ["close"]]] # def head(path, initheader = nil) request(Head.new(path, initheader)) end - # Posts +data+ (must be a String) to +path+. +header+ must be a Hash - # like { 'Accept' => '*/*', ... }. + # :call-seq: + # post(path, data, initheader = nil) {|res| ... } + # + # Sends a POST request to the server; + # returns an instance of a subclass of Net::HTTPResponse. + # + # The request is based on the Net::HTTP::Post object + # created from string +path+, string +data+, and initial headers hash +initheader+. # - # This method returns a Net::HTTPResponse object. + # With a block given, calls the block with the response body: # - # 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. + # data = '{"userId": 1, "id": 1, "title": "delectus aut autem", "completed": false}' + # http = Net::HTTP.new(hostname) + # http.post('/todos', data) do |res| + # p res + # end # => #<Net::HTTPCreated 201 Created readbody=true> + # + # Output: # - # +dest+ argument is obsolete. - # It still works but you must not use it. + # "{\n \"{\\\"userId\\\": 1, \\\"id\\\": 1, \\\"title\\\": \\\"delectus aut autem\\\", \\\"completed\\\": false}\": \"\",\n \"id\": 201\n}" # - # This method never raises exception. + # With no block given, simply returns the response object: # - # response = http.post('/cgi-bin/search.rb', 'query=foo') + # http.post('/todos', data) # => #<Net::HTTPCreated 201 Created readbody=true> # - # # using block - # File.open('result.txt', 'w') {|f| - # http.post('/cgi-bin/search.rb', 'query=foo') do |str| - # f.write str - # end - # } + # Related: # - # 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. + # - Net::HTTP::Post: request class for \HTTP method POST. + # - Net::HTTP.post: sends POST request, returns response body. # def post(path, data, initheader = nil, dest = nil, &block) # :yield: +body_segment+ send_entity(path, data, initheader, dest, Post, &block) end - # Sends a PATCH request to the +path+ and gets a response, - # as an HTTPResponse object. + # :call-seq: + # patch(path, data, initheader = nil) {|res| ... } + # + # Sends a PATCH request to the server; + # returns an instance of a subclass of Net::HTTPResponse. + # + # The request is based on the Net::HTTP::Patch object + # created from string +path+, string +data+, and initial headers hash +initheader+. + # + # With a block given, calls the block with the response body: + # + # data = '{"userId": 1, "id": 1, "title": "delectus aut autem", "completed": false}' + # http = Net::HTTP.new(hostname) + # http.patch('/todos/1', data) do |res| + # p res + # end # => #<Net::HTTPOK 200 OK readbody=true> + # + # Output: + # + # "{\n \"userId\": 1,\n \"id\": 1,\n \"title\": \"delectus aut autem\",\n \"completed\": false,\n \"{\\\"userId\\\": 1, \\\"id\\\": 1, \\\"title\\\": \\\"delectus aut autem\\\", \\\"completed\\\": false}\": \"\"\n}" + # + # With no block given, simply returns the response object: + # + # http.patch('/todos/1', data) # => #<Net::HTTPCreated 201 Created readbody=true> + # def patch(path, data, initheader = nil, dest = nil, &block) # :yield: +body_segment+ send_entity(path, data, initheader, dest, Patch, &block) end - def put(path, data, initheader = nil) #:nodoc: + # Sends a PUT request to the server; + # returns an instance of a subclass of Net::HTTPResponse. + # + # The request is based on the Net::HTTP::Put object + # created from string +path+, string +data+, and initial headers hash +initheader+. + # + # data = '{"userId": 1, "id": 1, "title": "delectus aut autem", "completed": false}' + # http = Net::HTTP.new(hostname) + # http.put('/todos/1', data) # => #<Net::HTTPOK 200 OK readbody=true> + # + def put(path, data, initheader = nil) request(Put.new(path, initheader), data) end - # Sends a PROPPATCH request to the +path+ and gets a response, - # as an HTTPResponse object. + # Sends a PROPPATCH request to the server; + # returns an instance of a subclass of Net::HTTPResponse. + # + # The request is based on the Net::HTTP::Proppatch object + # created from string +path+, string +body+, and initial headers hash +initheader+. + # + # data = '{"userId": 1, "id": 1, "title": "delectus aut autem", "completed": false}' + # http = Net::HTTP.new(hostname) + # http.proppatch('/todos/1', data) + # def proppatch(path, body, initheader = nil) request(Proppatch.new(path, initheader), body) end - # Sends a LOCK request to the +path+ and gets a response, - # as an HTTPResponse object. + # Sends a LOCK request to the server; + # returns an instance of a subclass of Net::HTTPResponse. + # + # The request is based on the Net::HTTP::Lock object + # created from string +path+, string +body+, and initial headers hash +initheader+. + # + # data = '{"userId": 1, "id": 1, "title": "delectus aut autem", "completed": false}' + # http = Net::HTTP.new(hostname) + # http.lock('/todos/1', data) + # def lock(path, body, initheader = nil) request(Lock.new(path, initheader), body) end - # Sends a UNLOCK request to the +path+ and gets a response, - # as an HTTPResponse object. + # Sends an UNLOCK request to the server; + # returns an instance of a subclass of Net::HTTPResponse. + # + # The request is based on the Net::HTTP::Unlock object + # created from string +path+, string +body+, and initial headers hash +initheader+. + # + # data = '{"userId": 1, "id": 1, "title": "delectus aut autem", "completed": false}' + # http = Net::HTTP.new(hostname) + # http.unlock('/todos/1', data) + # def unlock(path, body, initheader = nil) request(Unlock.new(path, initheader), body) end - # Sends a OPTIONS request to the +path+ and gets a response, - # as an HTTPResponse object. + # Sends an Options request to the server; + # returns an instance of a subclass of Net::HTTPResponse. + # + # The request is based on the Net::HTTP::Options object + # created from string +path+ and initial headers hash +initheader+. + # + # http = Net::HTTP.new(hostname) + # http.options('/') + # def options(path, initheader = nil) request(Options.new(path, initheader)) end - # Sends a PROPFIND request to the +path+ and gets a response, - # as an HTTPResponse object. + # Sends a PROPFIND request to the server; + # returns an instance of a subclass of Net::HTTPResponse. + # + # The request is based on the Net::HTTP::Propfind object + # created from string +path+, string +body+, and initial headers hash +initheader+. + # + # data = '{"userId": 1, "id": 1, "title": "delectus aut autem", "completed": false}' + # http = Net::HTTP.new(hostname) + # http.propfind('/todos/1', data) + # def propfind(path, body = nil, initheader = {'Depth' => '0'}) request(Propfind.new(path, initheader), body) end - # Sends a DELETE request to the +path+ and gets a response, - # as an HTTPResponse object. + # Sends a DELETE request to the server; + # returns an instance of a subclass of Net::HTTPResponse. + # + # The request is based on the Net::HTTP::Delete object + # created from string +path+ and initial headers hash +initheader+. + # + # http = Net::HTTP.new(hostname) + # http.delete('/todos/1') + # def delete(path, initheader = {'Depth' => 'Infinity'}) request(Delete.new(path, initheader)) end - # Sends a MOVE request to the +path+ and gets a response, - # as an HTTPResponse object. + # Sends a MOVE request to the server; + # returns an instance of a subclass of Net::HTTPResponse. + # + # The request is based on the Net::HTTP::Move object + # created from string +path+ and initial headers hash +initheader+. + # + # http = Net::HTTP.new(hostname) + # http.move('/todos/1') + # def move(path, initheader = nil) request(Move.new(path, initheader)) end - # Sends a COPY request to the +path+ and gets a response, - # as an HTTPResponse object. + # Sends a COPY request to the server; + # returns an instance of a subclass of Net::HTTPResponse. + # + # The request is based on the Net::HTTP::Copy object + # created from string +path+ and initial headers hash +initheader+. + # + # http = Net::HTTP.new(hostname) + # http.copy('/todos/1') + # def copy(path, initheader = nil) request(Copy.new(path, initheader)) end - # Sends a MKCOL request to the +path+ and gets a response, - # as an HTTPResponse object. + # Sends a MKCOL request to the server; + # returns an instance of a subclass of Net::HTTPResponse. + # + # The request is based on the Net::HTTP::Mkcol object + # created from string +path+, string +body+, and initial headers hash +initheader+. + # + # data = '{"userId": 1, "id": 1, "title": "delectus aut autem", "completed": false}' + # http.mkcol('/todos/1', data) + # http = Net::HTTP.new(hostname) + # def mkcol(path, body = nil, initheader = nil) request(Mkcol.new(path, initheader), body) end - # Sends a TRACE request to the +path+ and gets a response, - # as an HTTPResponse object. + # Sends a TRACE request to the server; + # returns an instance of a subclass of Net::HTTPResponse. + # + # The request is based on the Net::HTTP::Trace object + # created from string +path+ and initial headers hash +initheader+. + # + # http = Net::HTTP.new(hostname) + # http.trace('/todos/1') + # def trace(path, initheader = nil) request(Trace.new(path, initheader)) end - # Sends a GET request to the +path+. - # Returns the response as a Net::HTTPResponse object. + # Sends a GET request to the server; + # forms the response into a Net::HTTPResponse object. # - # When called with a block, passes an HTTPResponse object to the block. - # The body of the response will not have been read yet; - # the block can process it using HTTPResponse#read_body, - # if desired. + # The request is based on the Net::HTTP::Get object + # created from string +path+ and initial headers hash +initheader+. # - # Returns the response. + # With no block given, returns the response object: # - # This method never raises Net::* exceptions. + # http = Net::HTTP.new(hostname) + # http.request_get('/todos') # => #<Net::HTTPOK 200 OK readbody=true> # - # response = http.request_get('/index.html') - # # The entity body is already read in this case. - # p response['content-type'] - # puts response.body + # With a block given, calls the block with the response object + # and returns the response object: + # + # http.request_get('/todos') do |res| + # p res + # end # => #<Net::HTTPOK 200 OK readbody=true> + # + # Output: # - # # Using a block - # http.request_get('/index.html') {|response| - # p response['content-type'] - # response.read_body do |str| # read body now - # print str - # end - # } + # #<Net::HTTPOK 200 OK readbody=false> # def request_get(path, initheader = nil, &block) # :yield: +response+ request(Get.new(path, initheader), &block) end - # Sends a HEAD request to the +path+ and returns the response - # as a Net::HTTPResponse object. + # Sends a HEAD request to the server; + # returns an instance of a subclass of Net::HTTPResponse. # - # Returns the response. + # The request is based on the Net::HTTP::Head object + # created from string +path+ and initial headers hash +initheader+. # - # This method never raises Net::* exceptions. - # - # response = http.request_head('/index.html') - # p response['content-type'] + # http = Net::HTTP.new(hostname) + # http.head('/todos/1') # => #<Net::HTTPOK 200 OK readbody=true> # def request_head(path, initheader = nil, &block) request(Head.new(path, initheader), &block) end - # Sends a POST request to the +path+. + # Sends a POST request to the server; + # forms the response into a Net::HTTPResponse object. + # + # The request is based on the Net::HTTP::Post object + # created from string +path+, string +data+, and initial headers hash +initheader+. # - # Returns the response as a Net::HTTPResponse object. + # With no block given, returns the response object: # - # When called with a block, the block is passed an HTTPResponse - # object. The body of that response will not have been read yet; - # the block can process it using HTTPResponse#read_body, if desired. + # http = Net::HTTP.new(hostname) + # http.post('/todos', 'xyzzy') + # # => #<Net::HTTPCreated 201 Created readbody=true> # - # Returns the response. + # With a block given, calls the block with the response body + # and returns the response object: # - # This method never raises Net::* exceptions. + # http.post('/todos', 'xyzzy') do |res| + # p res + # end # => #<Net::HTTPCreated 201 Created readbody=true> # - # # example - # response = http.request_post('/cgi-bin/nice.rb', 'datadatadata...') - # p response.status - # puts response.body # body is already read in this case + # Output: # - # # 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 - # } + # "{\n \"xyzzy\": \"\",\n \"id\": 201\n}" # def request_post(path, data, initheader = nil, &block) # :yield: +response+ request Post.new(path, initheader), data, &block end + # Sends a PUT request to the server; + # returns an instance of a subclass of Net::HTTPResponse. + # + # The request is based on the Net::HTTP::Put object + # created from string +path+, string +data+, and initial headers hash +initheader+. + # + # http = Net::HTTP.new(hostname) + # http.put('/todos/1', 'xyzzy') + # # => #<Net::HTTPOK 200 OK readbody=true> + # def request_put(path, data, initheader = nil, &block) #:nodoc: request Put.new(path, initheader), data, &block end @@ -1780,16 +1972,25 @@ module Net #:nodoc: alias post2 request_post #:nodoc: obsolete alias put2 request_put #:nodoc: obsolete - - # Sends an HTTP request to the HTTP server. - # Also sends a DATA string if +data+ is given. + # Sends an \HTTP request to the server; + # returns an instance of a subclass of Net::HTTPResponse. # - # Returns a Net::HTTPResponse object. + # The request is based on the Net::HTTPRequest object + # created from string +path+, string +data+, and initial headers hash +header+. + # That object is an instance of the + # {subclass of Net::HTTPRequest}[rdoc-ref:Net::HTTPRequest@Request+Subclasses], + # that corresponds to the given uppercase string +name+, + # which must be + # an {HTTP request method}[https://en.wikipedia.org/wiki/HTTP#Request_methods] + # or a {WebDAV request method}[https://en.wikipedia.org/wiki/WebDAV#Implementation]. # - # This method never raises Net::* exceptions. + # Examples: # - # response = http.send_request('GET', '/index.html') - # puts response.body + # http = Net::HTTP.new(hostname) + # http.send_request('GET', '/todos/1') + # # => #<Net::HTTPOK 200 OK readbody=true> + # http.send_request('POST', '/todos', 'xyzzy') + # # => #<Net::HTTPCreated 201 Created readbody=true> # def send_request(name, path, data = nil, header = nil) has_response_body = name != 'HEAD' @@ -1797,20 +1998,35 @@ module Net #:nodoc: request r, data end - # Sends an HTTPRequest object +req+ to the HTTP server. + # Sends the given request +req+ to the server; + # forms the response into a Net::HTTPResponse object. # - # If +req+ is a Net::HTTP::Post or Net::HTTP::Put request containing - # data, the data is also sent. Providing data for a Net::HTTP::Head or - # Net::HTTP::Get request results in an ArgumentError. + # The given +req+ must be an instance of a + # {subclass of Net::HTTPRequest}[rdoc-ref:Net::HTTPRequest@Request+Subclasses]. + # Argument +body+ should be given only if needed for the request. # - # Returns an HTTPResponse object. + # With no block given, returns the response object: # - # When called with a block, passes an HTTPResponse object to the block. - # The body of the response will not have been read yet; - # the block can process it using HTTPResponse#read_body, - # if desired. + # http = Net::HTTP.new(hostname) + # + # req = Net::HTTP::Get.new('/todos/1') + # http.request(req) + # # => #<Net::HTTPOK 200 OK readbody=true> + # + # req = Net::HTTP::Post.new('/todos') + # http.request(req, 'xyzzy') + # # => #<Net::HTTPCreated 201 Created readbody=true> + # + # With a block given, calls the block with the response and returns the response: + # + # req = Net::HTTP::Get.new('/todos/1') + # http.request(req) do |res| + # p res + # end # => #<Net::HTTPOK 200 OK readbody=true> + # + # Output: # - # This method never raises Net::* exceptions. + # #<Net::HTTPOK 200 OK readbody=false> # def request(req, body = nil, &block) # :yield: +response+ unless started? diff --git a/lib/net/http/generic_request.rb b/lib/net/http/generic_request.rb index d56835c76f..8877cd04ae 100644 --- a/lib/net/http/generic_request.rb +++ b/lib/net/http/generic_request.rb @@ -1,14 +1,18 @@ # frozen_string_literal: false -# HTTPGenericRequest is the parent of the Net::HTTPRequest class. -# Do not use this directly; use a subclass of Net::HTTPRequest. # -# Mixes in the Net::HTTPHeader module to provide easier access to HTTP headers. +# \HTTPGenericRequest is the parent of the Net::HTTPRequest class. +# +# Do not use this directly; instead, use a subclass of Net::HTTPRequest. +# +# == About the Examples +# +# :include: doc/net-http/examples.rdoc # class Net::HTTPGenericRequest include Net::HTTPHeader - def initialize(m, reqbody, resbody, uri_or_path, initheader = nil) + def initialize(m, reqbody, resbody, uri_or_path, initheader = nil) # :nodoc: @method = m @request_has_body = reqbody @response_has_body = resbody @@ -53,15 +57,47 @@ class Net::HTTPGenericRequest @body_data = nil end + # Returns the string method name for the request: + # + # Net::HTTP::Get.new(uri).method # => "GET" + # Net::HTTP::Post.new(uri).method # => "POST" + # attr_reader :method + + # Returns the string path for the request: + # + # Net::HTTP::Get.new(uri).path # => "/" + # Net::HTTP::Post.new('example.com').path # => "example.com" + # attr_reader :path + + # Returns the URI object for the request, or +nil+ if none: + # + # Net::HTTP::Get.new(uri).uri + # # => #<URI::HTTPS https://jsonplaceholder.typicode.com/> + # Net::HTTP::Get.new('example.com').uri # => nil + # attr_reader :uri - # Automatically set to false if the user sets the Accept-Encoding header. - # This indicates they wish to handle Content-encoding in responses - # themselves. + # Returns +false+ if the request's header <tt>'Accept-Encoding'</tt> + # has been set manually or deleted + # (indicating that the user intends to handle encoding in the response), + # +true+ otherwise: + # + # req = Net::HTTP::Get.new(uri) # => #<Net::HTTP::Get GET> + # req['Accept-Encoding'] # => "gzip;q=1.0,deflate;q=0.6,identity;q=0.3" + # req.decode_content # => true + # req['Accept-Encoding'] = 'foo' + # req.decode_content # => false + # req.delete('Accept-Encoding') + # req.decode_content # => false + # attr_reader :decode_content + # Returns a string representation of the request: + # + # Net::HTTP::Post.new(uri).inspect # => "#<Net::HTTP::Post POST>" + # def inspect "\#<#{self.class} #{@method}>" end @@ -76,21 +112,45 @@ class Net::HTTPGenericRequest super key, val end + # Returns whether the request may have a body: + # + # Net::HTTP::Post.new(uri).request_body_permitted? # => true + # Net::HTTP::Get.new(uri).request_body_permitted? # => false + # def request_body_permitted? @request_has_body end + # Returns whether the response may have a body: + # + # Net::HTTP::Post.new(uri).response_body_permitted? # => true + # Net::HTTP::Head.new(uri).response_body_permitted? # => false + # def response_body_permitted? @response_has_body end - def body_exist? + def body_exist? # :nodoc: warn "Net::HTTPRequest#body_exist? is obsolete; use response_body_permitted?", uplevel: 1 if $VERBOSE response_body_permitted? end + # Returns the string body for the request, or +nil+ if there is none: + # + # req = Net::HTTP::Post.new(uri) + # req.body # => nil + # req.body = '{"title": "foo","body": "bar","userId": 1}' + # req.body # => "{\"title\": \"foo\",\"body\": \"bar\",\"userId\": 1}" + # attr_reader :body + # Sets the body for the request: + # + # req = Net::HTTP::Post.new(uri) + # req.body # => nil + # req.body = '{"title": "foo","body": "bar","userId": 1}' + # req.body # => "{\"title\": \"foo\",\"body\": \"bar\",\"userId\": 1}" + # def body=(str) @body = str @body_stream = nil @@ -98,8 +158,24 @@ class Net::HTTPGenericRequest str end + # Returns the body stream object for the request, or +nil+ if there is none: + # + # req = Net::HTTP::Post.new(uri) # => #<Net::HTTP::Post POST> + # req.body_stream # => nil + # require 'stringio' + # req.body_stream = StringIO.new('xyzzy') # => #<StringIO:0x0000027d1e5affa8> + # req.body_stream # => #<StringIO:0x0000027d1e5affa8> + # attr_reader :body_stream + # Sets the body stream for the request: + # + # req = Net::HTTP::Post.new(uri) # => #<Net::HTTP::Post POST> + # req.body_stream # => nil + # require 'stringio' + # req.body_stream = StringIO.new('xyzzy') # => #<StringIO:0x0000027d1e5affa8> + # req.body_stream # => #<StringIO:0x0000027d1e5affa8> + # def body_stream=(input) @body = nil @body_stream = input diff --git a/lib/net/http/header.rb b/lib/net/http/header.rb index 3c061abb83..b704860c90 100644 --- a/lib/net/http/header.rb +++ b/lib/net/http/header.rb @@ -771,19 +771,38 @@ module Net::HTTPHeader alias content_type= set_content_type - # Set header fields and a body from HTML form data. - # +params+ should be an Array of Arrays or - # a Hash containing HTML form data. - # Optional argument +sep+ means data record separator. + # Sets the request body to a URL-encoded string derived from argument +params+, + # and sets request header field <tt>'Content-Type'</tt> + # to <tt>'application/x-www-form-urlencoded'</tt>. # - # Values are URL encoded as necessary and the content-type is set to - # application/x-www-form-urlencoded + # The resulting request is suitable for HTTP request +POST+ or +PUT+. # - # Example: + # Argument +params+ must be suitable for use as argument +enum+ to + # {URI.encode_www_form}[rdoc-ref:URI.encode_www_form]. # - # http.form_data = {"q" => "ruby", "lang" => "en"} - # http.form_data = {"q" => ["ruby", "perl"], "lang" => "en"} - # http.set_form_data({"q" => "ruby", "lang" => "en"}, ';') + # With only argument +params+ given, + # sets the body to a URL-encoded string with the default separator <tt>'&'</tt>: + # + # req = Net::HTTP::Post.new('example.com') + # + # req.set_form_data(q: 'ruby', lang: 'en') + # req.body # => "q=ruby&lang=en" + # req['Content-Type'] # => "application/x-www-form-urlencoded" + # + # req.set_form_data([['q', 'ruby'], ['lang', 'en']]) + # req.body # => "q=ruby&lang=en" + # + # req.set_form_data(q: ['ruby', 'perl'], lang: 'en') + # req.body # => "q=ruby&q=perl&lang=en" + # + # req.set_form_data([['q', 'ruby'], ['q', 'perl'], ['lang', 'en']]) + # req.body # => "q=ruby&q=perl&lang=en" + # + # With string argument +sep+ also given, + # uses that string as the separator: + # + # req.set_form_data({q: 'ruby', lang: 'en'}, '|') + # req.body # => "q=ruby|lang=en" # # Net::HTTPHeader#form_data= is an alias for Net::HTTPHeader#set_form_data. def set_form_data(params, sep = '&') @@ -795,56 +814,108 @@ module Net::HTTPHeader alias form_data= set_form_data - # Set an HTML form data set. - # +params+ :: The form data to set, which should be an enumerable. - # See below for more details. - # +enctype+ :: The content type to use to encode the form submission, - # which should be application/x-www-form-urlencoded or - # multipart/form-data. - # +formopt+ :: An options hash, supporting the following options: - # :boundary :: The boundary of the multipart message. If - # not given, a random boundary will be used. - # :charset :: The charset of the form submission. All - # field names and values of non-file fields - # should be encoded with this charset. - # - # Each item of params should respond to +each+ and yield 2-3 arguments, - # or an array of 2-3 elements. The arguments yielded should be: - # - # - The name of the field. - # - The value of the field, it should be a String or a File or IO-like. - # - An options hash, supporting the following options - # (used only for file uploads); entries: - # - # - +:filename+: The name of the file to use. - # - +:content_type+: The content type of the uploaded file. - # - # Each item is a file field or a normal field. - # If +value+ is a File object or the +opt+ hash has a :filename key, - # the item is treated as a file field. - # - # If Transfer-Encoding is set as chunked, this sends the request using - # chunked encoding. Because chunked encoding is HTTP/1.1 feature, - # you should confirm that the server supports HTTP/1.1 before using - # chunked encoding. - # - # Example: - # - # req.set_form([["q", "ruby"], ["lang", "en"]]) - # - # req.set_form({"f"=>File.open('/path/to/filename')}, - # "multipart/form-data", - # charset: "UTF-8", - # ) - # - # req.set_form([["f", - # File.open('/path/to/filename.bar'), - # {filename: "other-filename.foo"} - # ]], - # "multipart/form-data", - # ) - # - # See also RFC 2388, RFC 2616, HTML 4.01, and HTML5 + # Stores form data to be used in a +POST+ or +PUT+ request. + # + # The form data given in +params+ consists of zero or more fields; + # each field is: + # + # - A scalar value. + # - A name/value pair. + # - An IO stream opened for reading. + # + # Argument +params+ should be an + # {Enumerable}[rdoc-ref:Enumerable@Enumerable+in+Ruby+Classes] + # (method <tt>params.map</tt> will be called), + # and is often an array or hash. + # + # First, we set up a request: + # + # _uri = uri.dup + # _uri.path ='/posts' + # req = Net::HTTP::Post.new(_uri) + # + # <b>Argument +params+ As an Array</b> + # + # When +params+ is an array, + # each of its elements is a subarray that defines a field; + # the subarray may contain: + # + # - One string: + # + # req.set_form([['foo'], ['bar'], ['baz']]) + # + # - Two strings: + # + # req.set_form([%w[foo 0], %w[bar 1], %w[baz 2]]) + # + # - When argument +enctype+ (see below) is given as + # <tt>'multipart/form-data'</tt>: + # + # - A string name and an IO stream opened for reading: + # + # require 'stringio' + # req.set_form([['file', StringIO.new('Ruby is cool.')]]) + # + # - A string name, an IO stream opened for reading, + # and an options hash, which may contain these entries: + # + # - +:filename+: The name of the file to use. + # - +:content_type+: The content type of the uploaded file. + # + # Example: + # + # req.set_form([['file', file, {filename: "other-filename.foo"}]] + # + # The various forms may be mixed: + # + # req.set_form(['foo', %w[bar 1], ['file', file]]) + # + # <b>Argument +params+ As a Hash</b> + # + # When +params+ is a hash, + # each of its entries is a name/value pair that defines a field: + # + # - The name is a string. + # - The value may be: + # + # - +nil+. + # - Another string. + # - An IO stream opened for reading + # (only when argument +enctype+ -- see below -- is given as + # <tt>'multipart/form-data'</tt>). + # + # Examples: + # + # # Nil-valued fields. + # req.set_form({'foo' => nil, 'bar' => nil, 'baz' => nil}) + # + # # String-valued fields. + # req.set_form({'foo' => 0, 'bar' => 1, 'baz' => 2}) + # + # # IO-valued field. + # require 'stringio' + # req.set_form({'file' => StringIO.new('Ruby is cool.')}) + # + # # Mixture of fields. + # req.set_form({'foo' => nil, 'bar' => 1, 'file' => file}) + # + # Optional argument +enctype+ specifies the value to be given + # to field <tt>'Content-Type'</tt>, and must be one of: + # + # - <tt>'application/x-www-form-urlencoded'</tt> (the default). + # - <tt>'multipart/form-data'</tt>; + # see {RFC 7578}[https://www.rfc-editor.org/rfc/rfc7578]. + # + # Optional argument +formopt+ is a hash of options + # (applicable only when argument +enctype+ + # is <tt>'multipart/form-data'</tt>) + # that may include the following entries: + # + # - +:boundary+: The value is the boundary string for the multipart message. + # If not given, the boundary is a random string. + # See {Boundary}[https://www.rfc-editor.org/rfc/rfc7578#section-4.1]. + # - +:charset+: Value is the character set for the form submission. + # Field names and values of non-file fields should be encoded with this charset. # def set_form(params, enctype='application/x-www-form-urlencoded', formopt={}) @body_data = params @@ -860,12 +931,24 @@ module Net::HTTPHeader end end - # Set the Authorization: header for "Basic" authorization. + # Sets header <tt>'Authorization'</tt> using the given + # +account+ and +password+ strings: + # + # req.basic_auth('my_account', 'my_password') + # req['Authorization'] + # # => "Basic bXlfYWNjb3VudDpteV9wYXNzd29yZA==" + # def basic_auth(account, password) @header['authorization'] = [basic_encode(account, password)] end - # Set Proxy-Authorization: header for "Basic" authorization. + # Sets header <tt>'Proxy-Authorization'</tt> using the given + # +account+ and +password+ strings: + # + # req.proxy_basic_auth('my_account', 'my_password') + # req['Proxy-Authorization'] + # # => "Basic bXlfYWNjb3VudDpteV9wYXNzd29yZA==" + # def proxy_basic_auth(account, password) @header['proxy-authorization'] = [basic_encode(account, password)] end @@ -875,6 +958,7 @@ module Net::HTTPHeader end private :basic_encode +# Returns whether the HTTP session is to be closed. def connection_close? token = /(?:\A|,)\s*close\s*(?:\z|,)/i @header['connection']&.grep(token) {return true} @@ -882,6 +966,7 @@ module Net::HTTPHeader false end +# Returns whether the HTTP session is to be kept alive. def connection_keep_alive? token = /(?:\A|,)\s*keep-alive\s*(?:\z|,)/i @header['connection']&.grep(token) {return true} diff --git a/lib/net/http/request.rb b/lib/net/http/request.rb index f3d32edb62..e900b8a17a 100644 --- a/lib/net/http/request.rb +++ b/lib/net/http/request.rb @@ -1,10 +1,55 @@ # frozen_string_literal: false -# This class is the base class for \Net::HTTP request classes; -# it wraps together the request path and the request headers. -# +# This class is the base class for \Net::HTTP request classes. # The class should not be used directly; -# instead you should use its subclasses. +# instead you should use its subclasses, listed below. +# +# == Creating a Request +# +# An request object may be created with either a URI or a string hostname: +# +# require 'net/http' +# uri = URI('https://jsonplaceholder.typicode.com/') +# req = Net::HTTP::Get.new(uri) # => #<Net::HTTP::Get GET> +# req = Net::HTTP::Get.new(uri.hostname) # => #<Net::HTTP::Get GET> +# +# And with any of the subclasses: +# +# req = Net::HTTP::Head.new(uri) # => #<Net::HTTP::Head HEAD> +# req = Net::HTTP::Post.new(uri) # => #<Net::HTTP::Post POST> +# req = Net::HTTP::Put.new(uri) # => #<Net::HTTP::Put PUT> +# # ... +# +# The new instance is suitable for use as the argument to Net::HTTP#request. +# +# == Request Headers +# +# A new request object has these header fields by default: +# +# req.to_hash +# # => +# {"accept-encoding"=>["gzip;q=1.0,deflate;q=0.6,identity;q=0.3"], +# "accept"=>["*/*"], +# "user-agent"=>["Ruby"], +# "host"=>["jsonplaceholder.typicode.com"]} +# +# See: +# +# - {Request header Accept-Encoding}[https://en.wikipedia.org/wiki/List_of_HTTP_header_fields#Accept-Encoding] +# and {Compression and Decompression}[rdoc-ref:Net::HTTP@Compression+and+Decompression]. +# - {Request header Accept}[https://en.wikipedia.org/wiki/List_of_HTTP_header_fields#accept-request-header]. +# - {Request header User-Agent}[https://en.wikipedia.org/wiki/List_of_HTTP_header_fields#user-agent-request-header]. +# - {Request header Host}[https://en.wikipedia.org/wiki/List_of_HTTP_header_fields#host-request-header]. +# +# You can add headers or override default headers: +# +# # res = Net::HTTP::Get.new(uri, {'foo' => '0', 'bar' => '1'}) +# +# This class (and therefore its subclasses) also includes (indirectly) +# module Net::HTTPHeader, which gives access to its +# {methods for setting headers}[rdoc-ref:Net::HTTPHeader@Setters]. +# +# == Request Subclasses # # Subclasses for HTTP requests: # diff --git a/lib/net/http/requests.rb b/lib/net/http/requests.rb index 294b8e8841..96cedcabcc 100644 --- a/lib/net/http/requests.rb +++ b/lib/net/http/requests.rb @@ -13,6 +13,8 @@ # http.request(req) # end # +# See {Request Headers}[rdoc-ref:Net::HTTPRequest@Request+Headers]. +# # Properties: # # - Request body: optional. @@ -43,6 +45,8 @@ end # http.request(req) # end # +# See {Request Headers}[rdoc-ref:Net::HTTPRequest@Request+Headers]. +# # Properties: # # - Request body: optional. @@ -75,6 +79,8 @@ end # http.request(req) # end # +# See {Request Headers}[rdoc-ref:Net::HTTPRequest@Request+Headers]. +# # Properties: # # - Request body: yes. @@ -108,6 +114,8 @@ end # http.request(req) # end # +# See {Request Headers}[rdoc-ref:Net::HTTPRequest@Request+Headers]. +# # Properties: # # - Request body: yes. @@ -134,6 +142,8 @@ end # http.request(req) # end # +# See {Request Headers}[rdoc-ref:Net::HTTPRequest@Request+Headers]. +# # Properties: # # - Request body: optional. @@ -163,6 +173,8 @@ end # http.request(req) # end # +# See {Request Headers}[rdoc-ref:Net::HTTPRequest@Request+Headers]. +# # Properties: # # - Request body: optional. @@ -192,6 +204,8 @@ end # http.request(req) # end # +# See {Request Headers}[rdoc-ref:Net::HTTPRequest@Request+Headers]. +# # Properties: # # - Request body: no. @@ -224,6 +238,8 @@ end # http.request(req) # end # +# See {Request Headers}[rdoc-ref:Net::HTTPRequest@Request+Headers]. +# # Properties: # # - Request body: yes. @@ -257,6 +273,8 @@ end # http.request(req) # end # +# See {Request Headers}[rdoc-ref:Net::HTTPRequest@Request+Headers]. +# # Related: # # - Net::HTTP#propfind: sends +PROPFIND+ request, returns response object. @@ -278,6 +296,8 @@ end # http.request(req) # end # +# See {Request Headers}[rdoc-ref:Net::HTTPRequest@Request+Headers]. +# # Related: # # - Net::HTTP#proppatch: sends +PROPPATCH+ request, returns response object. @@ -299,6 +319,8 @@ end # http.request(req) # end # +# See {Request Headers}[rdoc-ref:Net::HTTPRequest@Request+Headers]. +# # Related: # # - Net::HTTP#mkcol: sends +MKCOL+ request, returns response object. @@ -320,6 +342,8 @@ end # http.request(req) # end # +# See {Request Headers}[rdoc-ref:Net::HTTPRequest@Request+Headers]. +# # Related: # # - Net::HTTP#copy: sends +COPY+ request, returns response object. @@ -341,6 +365,8 @@ end # http.request(req) # end # +# See {Request Headers}[rdoc-ref:Net::HTTPRequest@Request+Headers]. +# # Related: # # - Net::HTTP#move: sends +MOVE+ request, returns response object. @@ -362,6 +388,8 @@ end # http.request(req) # end # +# See {Request Headers}[rdoc-ref:Net::HTTPRequest@Request+Headers]. +# # Related: # # - Net::HTTP#lock: sends +LOCK+ request, returns response object. @@ -383,6 +411,8 @@ end # http.request(req) # end # +# See {Request Headers}[rdoc-ref:Net::HTTPRequest@Request+Headers]. +# # Related: # # - Net::HTTP#unlock: sends +UNLOCK+ request, returns response object. diff --git a/lib/net/http/response.rb b/lib/net/http/response.rb index 83853ffd19..90c425b1a7 100644 --- a/lib/net/http/response.rb +++ b/lib/net/http/response.rb @@ -1,6 +1,6 @@ # frozen_string_literal: false -# This class is the base class for \Net::HTTP request classes. +# This class is the base class for \Net::HTTP response classes. # # == About the Examples # diff --git a/lib/net/http/responses.rb b/lib/net/http/responses.rb index b9071ca62f..6f6fb8d055 100644 --- a/lib/net/http/responses.rb +++ b/lib/net/http/responses.rb @@ -85,6 +85,8 @@ module Net # # A +Continue+ response indicates that the server has received the request headers. # + # :include: doc/net-http/included_getters.rdoc + # # References: # # - {Mozilla}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/100]. @@ -100,6 +102,8 @@ module Net # The <tt>Switching Protocol<tt> response indicates that the server has received # a request to switch protocols, and has agreed to do so. # + # :include: doc/net-http/included_getters.rdoc + # # References: # # - {Mozilla}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/101]. @@ -115,8 +119,11 @@ module Net # The +Processing+ response indicates that the server has received # and is processing the request, but no response is available yet. # + # :include: doc/net-http/included_getters.rdoc + # # References: # + # - {RFC 2518}[https://www.rfc-editor.org/rfc/rfc2518#section-10.1]. # - {Wikipedia}[https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#102]. # class HTTPProcessing < HTTPInformation @@ -129,9 +136,12 @@ module Net # and is processing the request, and contains certain headers; # the final response is not available yet. # + # :include: doc/net-http/included_getters.rdoc + # # References: # # - {Mozilla}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/103]. + # - {RFC 8297}[https://www.rfc-editor.org/rfc/rfc8297.html#section-2]. # - {Wikipedia}[https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#103]. # class HTTPEarlyHints < HTTPInformation @@ -143,6 +153,8 @@ module Net # The +OK+ response indicates that the server has received # a request and has responded successfully. # + # :include: doc/net-http/included_getters.rdoc + # # References: # # - {Mozilla}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200]. @@ -158,6 +170,8 @@ module Net # The +Created+ response indicates that the server has received # and has fulfilled a request to create a new resource. # + # :include: doc/net-http/included_getters.rdoc + # # References: # # - {Mozilla}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201]. @@ -173,6 +187,8 @@ module Net # The +Accepted+ response indicates that the server has received # and is processing a request, but the processing has not yet been completed. # + # :include: doc/net-http/included_getters.rdoc + # # References: # # - {Mozilla}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202]. @@ -190,6 +206,8 @@ module Net # that received a 200 OK response from its origin, # and is returning a modified version of the origin's response. # + # :include: doc/net-http/included_getters.rdoc + # # References: # # - {Mozilla}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/203]. @@ -205,6 +223,8 @@ module Net # The <tt>No Content</tt> response indicates that the server # successfully processed the request, and is not returning any content. # + # :include: doc/net-http/included_getters.rdoc + # # References: # # - {Mozilla}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204]. @@ -221,6 +241,8 @@ module Net # successfully processed the request, # asks that the client reset its document view, and is not returning any content. # + # :include: doc/net-http/included_getters.rdoc + # # References: # # - {Mozilla}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/205]. @@ -237,6 +259,8 @@ module Net # only part of the resource (byte serving) # due to a Range header in the request. # + # :include: doc/net-http/included_getters.rdoc + # # References: # # - {Mozilla}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/206]. @@ -253,8 +277,11 @@ module Net # has received the request, # and that the message body can contain a number of separate response codes. # + # :include: doc/net-http/included_getters.rdoc + # # References: # + # - {RFC 4818}[https://www.rfc-editor.org/rfc/rfc4918#section-11.1]. # - {Wikipedia}[https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#207]. # class HTTPMultiStatus < HTTPSuccess @@ -269,8 +296,11 @@ module Net # in a preceding part of the (multi-status) response, # and are not being included again. # + # :include: doc/net-http/included_getters.rdoc + # # References: # + # - {RFC 5842}[https://www.rfc-editor.org/rfc/rfc5842.html#section-7.1]. # - {Wikipedia}[https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#208]. # class HTTPAlreadyReported < HTTPSuccess @@ -283,8 +313,11 @@ module Net # for the resource, and the response is a representation of the result # of one or more instance-manipulations applied to the current instance. # + # :include: doc/net-http/included_getters.rdoc + # # References: # + # - {RFC 3229}[https://www.rfc-editor.org/rfc/rfc3229.html#section-10.4.1]. # - {Wikipedia}[https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#226]. # class HTTPIMUsed < HTTPSuccess @@ -296,6 +329,8 @@ module Net # The <tt>Multiple Choices</tt> response indicates that the server # offers multiple options for the resource from which the client may choose. # + # :include: doc/net-http/included_getters.rdoc + # # References: # # - {Mozilla}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/300]. @@ -312,6 +347,8 @@ module Net # The <tt>Moved Permanently</tt> response indicates that links or records # returning this response should be updated to use the given URL. # + # :include: doc/net-http/included_getters.rdoc + # # References: # # - {Mozilla}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/301]. @@ -327,6 +364,8 @@ module Net # The <tt>Found</tt> response indicates that the client # should look at (browse to) another URL. # + # :include: doc/net-http/included_getters.rdoc + # # References: # # - {Mozilla}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/302]. @@ -342,6 +381,8 @@ module Net # # The response to the request can be found under another URI using the GET method. # + # :include: doc/net-http/included_getters.rdoc + # # References: # # - {Mozilla}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/303]. @@ -357,6 +398,8 @@ module Net # Indicates that the resource has not been modified since the version # specified by the request headers. # + # :include: doc/net-http/included_getters.rdoc + # # References: # # - {Mozilla}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/304]. @@ -372,6 +415,8 @@ module Net # The requested resource is available only through a proxy, # whose address is provided in the response. # + # :include: doc/net-http/included_getters.rdoc + # # References: # # - {RFC 9110}[https://www.rfc-editor.org/rfc/rfc9110.html#name-305-use-proxy]. @@ -386,6 +431,8 @@ module Net # The request should be repeated with another URI; # however, future requests should still use the original URI. # + # :include: doc/net-http/included_getters.rdoc + # # References: # # - {Mozilla}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/307]. @@ -400,6 +447,8 @@ module Net # # This and all future requests should be directed to the given URI. # + # :include: doc/net-http/included_getters.rdoc + # # References: # # - {Mozilla}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/308]. @@ -413,7 +462,15 @@ module Net # Response class for <tt>Bad Request</tt> responses (status code 400). # # The server cannot or will not process the request due to an apparent client error. - # See {400 Bad Request}[https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#400]. + # + # :include: doc/net-http/included_getters.rdoc + # + # References: + # + # - {Mozilla}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400]. + # - {RFC 9110}[https://www.rfc-editor.org/rfc/rfc9110.html#name-400-bad-request]. + # - {Wikipedia}[https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#400]. + # class HTTPBadRequest < HTTPClientError HAS_BODY = true end @@ -421,7 +478,15 @@ module Net # Response class for <tt>Unauthorized</tt> responses (status code 401). # # Authentication is required, but either was not provided or failed. - # See {401 Unauthorized}[https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#401]. + # + # :include: doc/net-http/included_getters.rdoc + # + # References: + # + # - {Mozilla}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401]. + # - {RFC 9110}[https://www.rfc-editor.org/rfc/rfc9110.html#name-401-unauthorized]. + # - {Wikipedia}[https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#401]. + # class HTTPUnauthorized < HTTPClientError HAS_BODY = true end @@ -429,7 +494,15 @@ module Net # Response class for <tt>Payment Required</tt> responses (status code 402). # # Reserved for future use. - # See {402 Payment Required}[https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#402]. + # + # :include: doc/net-http/included_getters.rdoc + # + # References: + # + # - {Mozilla}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/402]. + # - {RFC 9110}[https://www.rfc-editor.org/rfc/rfc9110.html#name-402-payment-required]. + # - {Wikipedia}[https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#402]. + # class HTTPPaymentRequired < HTTPClientError HAS_BODY = true end @@ -438,7 +511,15 @@ module Net # # The request contained valid data and was understood by the server, # but the server is refusing action. - # See {403 Forbidden}[https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#403]. + # + # :include: doc/net-http/included_getters.rdoc + # + # References: + # + # - {Mozilla}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403]. + # - {RFC 9110}[https://www.rfc-editor.org/rfc/rfc9110.html#name-403-forbidden]. + # - {Wikipedia}[https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#403]. + # class HTTPForbidden < HTTPClientError HAS_BODY = true end @@ -446,7 +527,15 @@ module Net # Response class for <tt>Not Found</tt> responses (status code 404). # # The requested resource could not be found but may be available in the future. - # See {404 Not Found}[https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#404]. + # + # :include: doc/net-http/included_getters.rdoc + # + # References: + # + # - {Mozilla}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404]. + # - {RFC 9110}[https://www.rfc-editor.org/rfc/rfc9110.html#name-404-not-found]. + # - {Wikipedia}[https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#404]. + # class HTTPNotFound < HTTPClientError HAS_BODY = true end @@ -454,7 +543,15 @@ module Net # Response class for <tt>Method Not Allowed</tt> responses (status code 405). # # The request method is not supported for the requested resource. - # See {405 Method Not Allowed}[https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#405]. + # + # :include: doc/net-http/included_getters.rdoc + # + # References: + # + # - {Mozilla}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/405]. + # - {RFC 9110}[https://www.rfc-editor.org/rfc/rfc9110.html#name-405-method-not-allowed]. + # - {Wikipedia}[https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#405]. + # class HTTPMethodNotAllowed < HTTPClientError HAS_BODY = true end @@ -463,7 +560,15 @@ module Net # # The requested resource is capable of generating only content # that not acceptable according to the Accept headers sent in the request. - # See {406 Not Acceptable}[https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#406]. + # + # :include: doc/net-http/included_getters.rdoc + # + # References: + # + # - {Mozilla}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/406]. + # - {RFC 9110}[https://www.rfc-editor.org/rfc/rfc9110.html#name-406-not-acceptable]. + # - {Wikipedia}[https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#406]. + # class HTTPNotAcceptable < HTTPClientError HAS_BODY = true end @@ -471,7 +576,15 @@ module Net # Response class for <tt>Proxy Authentication Required</tt> responses (status code 407). # # The client must first authenticate itself with the proxy. - # See {407 Proxy Authentication Required}[https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#407]. + # + # :include: doc/net-http/included_getters.rdoc + # + # References: + # + # - {Mozilla}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/407]. + # - {RFC 9110}[https://www.rfc-editor.org/rfc/rfc9110.html#name-407-proxy-authentication-re]. + # - {Wikipedia}[https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#407]. + # class HTTPProxyAuthenticationRequired < HTTPClientError HAS_BODY = true end @@ -479,7 +592,15 @@ module Net # Response class for <tt>Request Timeout</tt> responses (status code 408). # # The server timed out waiting for the request. - # See {408 Request Timeout}[https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#408]. + # + # :include: doc/net-http/included_getters.rdoc + # + # References: + # + # - {Mozilla}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/408]. + # - {RFC 9110}[https://www.rfc-editor.org/rfc/rfc9110.html#name-408-request-timeout]. + # - {Wikipedia}[https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#408]. + # class HTTPRequestTimeout < HTTPClientError HAS_BODY = true end @@ -488,7 +609,15 @@ module Net # Response class for <tt>Conflict</tt> responses (status code 409). # # The request could not be processed because of conflict in the current state of the resource. - # See {409 Conflict}[https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#409]. + # + # :include: doc/net-http/included_getters.rdoc + # + # References: + # + # - {Mozilla}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409]. + # - {RFC 9110}[https://www.rfc-editor.org/rfc/rfc9110.html#name-409-conflict]. + # - {Wikipedia}[https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#409]. + # class HTTPConflict < HTTPClientError HAS_BODY = true end @@ -497,7 +626,15 @@ module Net # # The resource requested was previously in use but is no longer available # and will not be available again. - # See {410 Gone}[https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#410]. + # + # :include: doc/net-http/included_getters.rdoc + # + # References: + # + # - {Mozilla}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/410]. + # - {RFC 9110}[https://www.rfc-editor.org/rfc/rfc9110.html#name-410-gone]. + # - {Wikipedia}[https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#410]. + # class HTTPGone < HTTPClientError HAS_BODY = true end @@ -506,7 +643,15 @@ module Net # # The request did not specify the length of its content, # which is required by the requested resource. - # See {411 Length Required}[https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#411]. + # + # :include: doc/net-http/included_getters.rdoc + # + # References: + # + # - {Mozilla}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/411]. + # - {RFC 9110}[https://www.rfc-editor.org/rfc/rfc9110.html#name-411-length-required]. + # - {Wikipedia}[https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#411]. + # class HTTPLengthRequired < HTTPClientError HAS_BODY = true end @@ -515,7 +660,15 @@ module Net # # The server does not meet one of the preconditions # specified in the request headers. - # See {412 Precondition Failed}[https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#412]. + # + # :include: doc/net-http/included_getters.rdoc + # + # References: + # + # - {Mozilla}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412]. + # - {RFC 9110}[https://www.rfc-editor.org/rfc/rfc9110.html#name-412-precondition-failed]. + # - {Wikipedia}[https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#412]. + # class HTTPPreconditionFailed < HTTPClientError HAS_BODY = true end @@ -523,7 +676,15 @@ module Net # Response class for <tt>Payload Too Large</tt> responses (status code 413). # # The request is larger than the server is willing or able to process. - # See {413 Payload Too Large}[https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#413]. + # + # :include: doc/net-http/included_getters.rdoc + # + # References: + # + # - {Mozilla}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/413]. + # - {RFC 9110}[https://www.rfc-editor.org/rfc/rfc9110.html#name-413-content-too-large]. + # - {Wikipedia}[https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#413]. + # class HTTPPayloadTooLarge < HTTPClientError HAS_BODY = true end @@ -532,7 +693,15 @@ module Net # Response class for <tt>URI Too Long</tt> responses (status code 414). # # The URI provided was too long for the server to process. - # See {414 URI Too Long}[https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#414]. + # + # :include: doc/net-http/included_getters.rdoc + # + # References: + # + # - {Mozilla}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/414]. + # - {RFC 9110}[https://www.rfc-editor.org/rfc/rfc9110.html#name-414-uri-too-long]. + # - {Wikipedia}[https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#414]. + # class HTTPURITooLong < HTTPClientError HAS_BODY = true end @@ -542,7 +711,15 @@ module Net # Response class for <tt>Unsupported Media Type</tt> responses (status code 415). # # The request entity has a media type which the server or resource does not support. - # See {415 Unsupported Media Type}[https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#415]. + # + # :include: doc/net-http/included_getters.rdoc + # + # References: + # + # - {Mozilla}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/415]. + # - {RFC 9110}[https://www.rfc-editor.org/rfc/rfc9110.html#name-415-unsupported-media-type]. + # - {Wikipedia}[https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#415]. + # class HTTPUnsupportedMediaType < HTTPClientError HAS_BODY = true end @@ -550,7 +727,15 @@ module Net # Response class for <tt>Range Not Satisfiable</tt> responses (status code 416). # # The request entity has a media type which the server or resource does not support. - # See {416 Range Not Satisfiable}[https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#416]. + # + # :include: doc/net-http/included_getters.rdoc + # + # References: + # + # - {Mozilla}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/416]. + # - {RFC 9110}[https://www.rfc-editor.org/rfc/rfc9110.html#name-416-range-not-satisfiable]. + # - {Wikipedia}[https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#416]. + # class HTTPRangeNotSatisfiable < HTTPClientError HAS_BODY = true end @@ -559,7 +744,15 @@ module Net # Response class for <tt>Expectation Failed</tt> responses (status code 417). # # The server cannot meet the requirements of the Expect request-header field. - # See {417 Expectation Failed}[https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#417]. + # + # :include: doc/net-http/included_getters.rdoc + # + # References: + # + # - {Mozilla}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/417]. + # - {RFC 9110}[https://www.rfc-editor.org/rfc/rfc9110.html#name-417-expectation-failed]. + # - {Wikipedia}[https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#417]. + # class HTTPExpectationFailed < HTTPClientError HAS_BODY = true end @@ -572,7 +765,14 @@ module Net # Response class for <tt>Misdirected Request</tt> responses (status code 421). # # The request was directed at a server that is not able to produce a response. - # See {421 Misdirected Request}[https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#421]. + # + # :include: doc/net-http/included_getters.rdoc + # + # References: + # + # - {RFC 9110}[https://www.rfc-editor.org/rfc/rfc9110.html#name-421-misdirected-request]. + # - {Wikipedia}[https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#421]. + # class HTTPMisdirectedRequest < HTTPClientError HAS_BODY = true end @@ -580,7 +780,15 @@ module Net # Response class for <tt>Unprocessable Entity</tt> responses (status code 422). # # The request was well-formed but had semantic errors. - # See {422 Unprocessable Entity}[https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#422]. + # + # :include: doc/net-http/included_getters.rdoc + # + # References: + # + # - {Mozilla}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422]. + # - {RFC 9110}[https://www.rfc-editor.org/rfc/rfc9110.html#name-422-unprocessable-content]. + # - {Wikipedia}[https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#422]. + # class HTTPUnprocessableEntity < HTTPClientError HAS_BODY = true end @@ -588,7 +796,14 @@ module Net # Response class for <tt>Locked (WebDAV)</tt> responses (status code 423). # # The requested resource is locked. - # See {423 Locked (WebDAV)}[https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#423]. + # + # :include: doc/net-http/included_getters.rdoc + # + # References: + # + # - {RFC 4918}[https://www.rfc-editor.org/rfc/rfc4918#section-11.3]. + # - {Wikipedia}[https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#423]. + # class HTTPLocked < HTTPClientError HAS_BODY = true end @@ -597,6 +812,14 @@ module Net # # The request failed because it depended on another request and that request failed. # See {424 Failed Dependency (WebDAV)}[https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#424]. + # + # :include: doc/net-http/included_getters.rdoc + # + # References: + # + # - {RFC 4918}[https://www.rfc-editor.org/rfc/rfc4918#section-11.4]. + # - {Wikipedia}[https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#424]. + # class HTTPFailedDependency < HTTPClientError HAS_BODY = true end @@ -607,7 +830,15 @@ module Net # Response class for <tt>Upgrade Required</tt> responses (status code 426). # # The client should switch to the protocol given in the Upgrade header field. - # See {426 Upgrade Required}[https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#426]. + # + # :include: doc/net-http/included_getters.rdoc + # + # References: + # + # - {Mozilla}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/426]. + # - {RFC 9110}[https://www.rfc-editor.org/rfc/rfc9110.html#name-426-upgrade-required]. + # - {Wikipedia}[https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#426]. + # class HTTPUpgradeRequired < HTTPClientError HAS_BODY = true end @@ -615,7 +846,15 @@ module Net # Response class for <tt>Precondition Required</tt> responses (status code 428). # # The origin server requires the request to be conditional. - # See {428 Precondition Required}[https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#428]. + # + # :include: doc/net-http/included_getters.rdoc + # + # References: + # + # - {Mozilla}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/428]. + # - {RFC 6585}[https://www.rfc-editor.org/rfc/rfc6585#section-3]. + # - {Wikipedia}[https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#428]. + # class HTTPPreconditionRequired < HTTPClientError HAS_BODY = true end @@ -623,7 +862,15 @@ module Net # Response class for <tt>Too Many Requests</tt> responses (status code 429). # # The user has sent too many requests in a given amount of time. - # See {429 Too Many Requests}[https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#429]. + # + # :include: doc/net-http/included_getters.rdoc + # + # References: + # + # - {Mozilla}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429]. + # - {RFC 6585}[https://www.rfc-editor.org/rfc/rfc6585#section-4]. + # - {Wikipedia}[https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#429]. + # class HTTPTooManyRequests < HTTPClientError HAS_BODY = true end @@ -632,7 +879,15 @@ module Net # # An individual header field is too large, # or all the header fields collectively, are too large. - # See {431 Request Header Fields Too Large}[https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#431]. + # + # :include: doc/net-http/included_getters.rdoc + # + # References: + # + # - {Mozilla}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/431]. + # - {RFC 6585}[https://www.rfc-editor.org/rfc/rfc6585#section-5]. + # - {Wikipedia}[https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#431]. + # class HTTPRequestHeaderFieldsTooLarge < HTTPClientError HAS_BODY = true end @@ -641,7 +896,15 @@ module Net # # A server operator has received a legal demand to deny access to a resource or to a set of resources # that includes the requested resource. - # See {451 Unavailable For Legal Reasons}[https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#451]. + # + # :include: doc/net-http/included_getters.rdoc + # + # References: + # + # - {Mozilla}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/451]. + # - {RFC 7725}[https://www.rfc-editor.org/rfc/rfc7725.html#section-3]. + # - {Wikipedia}[https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#451]. + # class HTTPUnavailableForLegalReasons < HTTPClientError HAS_BODY = true end @@ -653,7 +916,15 @@ module Net # Response class for <tt>Internal Server Error</tt> responses (status code 500). # # An unexpected condition was encountered and no more specific message is suitable. - # See {500 Internal Server Error}[https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#500]. + # + # :include: doc/net-http/included_getters.rdoc + # + # References: + # + # - {Mozilla}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500]. + # - {RFC 9110}[https://www.rfc-editor.org/rfc/rfc9110.html#name-500-internal-server-error]. + # - {Wikipedia}[https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#500]. + # class HTTPInternalServerError < HTTPServerError HAS_BODY = true end @@ -662,7 +933,15 @@ module Net # # The server either does not recognize the request method, # or it lacks the ability to fulfil the request. - # See {501 Not Implemented}[https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#501]. + # + # :include: doc/net-http/included_getters.rdoc + # + # References: + # + # - {Mozilla}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/501]. + # - {RFC 9110}[https://www.rfc-editor.org/rfc/rfc9110.html#name-501-not-implemented]. + # - {Wikipedia}[https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#501]. + # class HTTPNotImplemented < HTTPServerError HAS_BODY = true end @@ -671,7 +950,15 @@ module Net # # The server was acting as a gateway or proxy # and received an invalid response from the upstream server. - # See {502 Bad Gateway}[https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#502]. + # + # :include: doc/net-http/included_getters.rdoc + # + # References: + # + # - {Mozilla}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/502]. + # - {RFC 9110}[https://www.rfc-editor.org/rfc/rfc9110.html#name-502-bad-gateway]. + # - {Wikipedia}[https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#502]. + # class HTTPBadGateway < HTTPServerError HAS_BODY = true end @@ -680,7 +967,15 @@ module Net # # The server cannot handle the request # (because it is overloaded or down for maintenance). - # See {503 Service Unavailable}[https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#503]. + # + # :include: doc/net-http/included_getters.rdoc + # + # References: + # + # - {Mozilla}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/503]. + # - {RFC 9110}[https://www.rfc-editor.org/rfc/rfc9110.html#name-503-service-unavailable]. + # - {Wikipedia}[https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#503]. + # class HTTPServiceUnavailable < HTTPServerError HAS_BODY = true end @@ -689,7 +984,15 @@ module Net # # The server was acting as a gateway or proxy # and did not receive a timely response from the upstream server. - # See {504 Gateway Timeout}[https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#504]. + # + # :include: doc/net-http/included_getters.rdoc + # + # References: + # + # - {Mozilla}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504]. + # - {RFC 9110}[https://www.rfc-editor.org/rfc/rfc9110.html#name-504-gateway-timeout]. + # - {Wikipedia}[https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#504]. + # class HTTPGatewayTimeout < HTTPServerError HAS_BODY = true end @@ -698,7 +1001,15 @@ module Net # Response class for <tt>HTTP Version Not Supported</tt> responses (status code 505). # # The server does not support the HTTP version used in the request. - # See {505 HTTP Version Not Supported}[https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#505]. + # + # :include: doc/net-http/included_getters.rdoc + # + # References: + # + # - {Mozilla}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/505]. + # - {RFC 9110}[https://www.rfc-editor.org/rfc/rfc9110.html#name-505-http-version-not-suppor]. + # - {Wikipedia}[https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#505]. + # class HTTPVersionNotSupported < HTTPServerError HAS_BODY = true end @@ -706,7 +1017,15 @@ module Net # Response class for <tt>Variant Also Negotiates</tt> responses (status code 506). # # Transparent content negotiation for the request results in a circular reference. - # See {506 Variant Also Negotiates}[https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#506]. + # + # :include: doc/net-http/included_getters.rdoc + # + # References: + # + # - {Mozilla}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/506]. + # - {RFC 2295}[https://www.rfc-editor.org/rfc/rfc2295#section-8.1]. + # - {Wikipedia}[https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#506]. + # class HTTPVariantAlsoNegotiates < HTTPServerError HAS_BODY = true end @@ -714,7 +1033,15 @@ module Net # Response class for <tt>Insufficient Storage (WebDAV)</tt> responses (status code 507). # # The server is unable to store the representation needed to complete the request. - # See {507 Insufficient Storage (WebDAV)}[https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#507]. + # + # :include: doc/net-http/included_getters.rdoc + # + # References: + # + # - {Mozilla}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/507]. + # - {RFC 4918}[https://www.rfc-editor.org/rfc/rfc4918#section-11.5]. + # - {Wikipedia}[https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#507]. + # class HTTPInsufficientStorage < HTTPServerError HAS_BODY = true end @@ -722,7 +1049,15 @@ module Net # Response class for <tt>Loop Detected (WebDAV)</tt> responses (status code 508). # # The server detected an infinite loop while processing the request. - # See {508 Loop Detected (WebDAV)}[https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#508]. + # + # :include: doc/net-http/included_getters.rdoc + # + # References: + # + # - {Mozilla}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/508]. + # - {RFC 5942}[https://www.rfc-editor.org/rfc/rfc5842.html#section-7.2]. + # - {Wikipedia}[https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#508]. + # class HTTPLoopDetected < HTTPServerError HAS_BODY = true end @@ -731,7 +1066,15 @@ module Net # Response class for <tt>Not Extended</tt> responses (status code 510). # # Further extensions to the request are required for the server to fulfill it. - # See {510 Not Extended}[https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#510]. + # + # :include: doc/net-http/included_getters.rdoc + # + # References: + # + # - {Mozilla}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/510]. + # - {RFC 2774}[https://www.rfc-editor.org/rfc/rfc2774.html#section-7]. + # - {Wikipedia}[https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#510]. + # class HTTPNotExtended < HTTPServerError HAS_BODY = true end @@ -739,7 +1082,15 @@ module Net # Response class for <tt>Network Authentication Required</tt> responses (status code 511). # # The client needs to authenticate to gain network access. - # See {511 Network Authentication Required}[https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#511]. + # + # :include: doc/net-http/included_getters.rdoc + # + # References: + # + # - {Mozilla}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/511]. + # - {RFC 6585}[https://www.rfc-editor.org/rfc/rfc6585#section-6]. + # - {Wikipedia}[https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#511]. + # class HTTPNetworkAuthenticationRequired < HTTPServerError HAS_BODY = true end diff --git a/lib/net/http/status.rb b/lib/net/http/status.rb index 8db3f7d9e3..f39fb64256 100644 --- a/lib/net/http/status.rb +++ b/lib/net/http/status.rb @@ -80,4 +80,4 @@ Net::HTTP::STATUS_CODES = { 508 => 'Loop Detected', 510 => 'Not Extended', 511 => 'Network Authentication Required', -} +} # :nodoc: |