net-http 0.3.2 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d2201663415fa5809c53f6c1d8a06524739bcee246443e22175aa89cda45c92c
-  data.tar.gz: 971f571f8d9966a09baf43a5117d9f072ae78b890e6cc4991a958081728671c8
+  metadata.gz: cf933c8a700d19b030c85a6bbd7dc2d9dd5756d50076a13fabbc44284b76af6c
+  data.tar.gz: 6ed388df8dfe9f603c7a838a274d52940b2494fb35a7fe2eb5514fd0bfbc7e0f
 SHA512:
-  metadata.gz: '086e4def849a69d4ecad94e1a13fe35eee82453f8748be247ea2c133b40ae7d3b419a0f71fa9dcd7efe783d0b725a13d527e287da1ccc406f7daa5700f2ec8e5'
-  data.tar.gz: 47a0f2d46fe8a9bc328241fb0fc90ea1c4285b0e46460998e40650a930bd96743051911e62b790d4502b39a007a5a04e260affe42d584bb73442ab414b51f1e3
+  metadata.gz: cb250a681c61405474f625099b62ff0eaad5334e12ffaca3ce1ad9781bcfc61b289cae035fdbe7850f17255d117b918c2339c6b504b2783899dce64c14fc1291
+  data.tar.gz: 735ae93466d2c3e019b5c277549751a68708400a7d3ff88a55c1d17d3bfcc6c07d6147023f21cf138812dbca5a1a5b24ed5cd54b3c919a8723f24d88e69b8997

data/Gemfile

@@ -4,4 +4,5 @@ gemspec
 
 gem "rake"
 gem "test-unit"
+gem "test-unit-ruby-core"
 gem "webrick"

data/Rakefile

@@ -7,11 +7,4 @@ Rake::TestTask.new(:test) do |t|
   t.test_files = FileList["test/**/test_*.rb"]
 end
 
-task :sync_tool do
-  require 'fileutils'
-  FileUtils.cp "../ruby/tool/lib/core_assertions.rb", "./test/lib"
-  FileUtils.cp "../ruby/tool/lib/envutil.rb", "./test/lib"
-  FileUtils.cp "../ruby/tool/lib/find_executable.rb", "./test/lib"
-end
-
 task :default => :test

data/doc/net-http/examples.rdoc

@@ -10,9 +10,10 @@ Many code examples here use these example websites:
 
 Some examples also assume these variables:
 
-  uri = URI('https://jsonplaceholder.typicode.com')
+  uri = URI('https://jsonplaceholder.typicode.com/')
   uri.freeze # Examples may not modify.
   hostname = uri.hostname # => "jsonplaceholder.typicode.com"
+  path = uri.path         # => "/"
   port = uri.port         # => 443
 
 So that example requests may be written as:

data/doc/net-http/included_getters.rdoc

@@ -0,0 +1,3 @@
+This class also includes (indirectly) module Net::HTTPHeader,
+which gives access to its
+{methods for getting headers}[rdoc-ref:Net::HTTPHeader@Getters].

data/lib/net/http/backward.rb

@@ -1,4 +1,4 @@
-# frozen_string_literal: false
+# frozen_string_literal: true
 # for backward compatibility
 
 # :enddoc:

data/lib/net/http/exceptions.rb

@@ -1,4 +1,4 @@
-# frozen_string_literal: false
+# frozen_string_literal: true
 module Net
   # Net::HTTP exception class.
   # You cannot use Net::HTTPExceptions directly; instead, you must use

data/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.
+# frozen_string_literal: true
 #
-# 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
@@ -19,7 +23,7 @@ class Net::HTTPGenericRequest
       raise ArgumentError, "no host component for URI" unless (hostname && hostname.length > 0)
       @uri = uri_or_path.dup
       host = @uri.hostname.dup
-      host << ":".freeze << @uri.port.to_s if @uri.port != @uri.default_port
+      host << ":" << @uri.port.to_s if @uri.port != @uri.default_port
       @path = uri_or_path.request_uri
       raise ArgumentError, "no HTTP request path given" unless @path
     else
@@ -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
@@ -136,15 +212,15 @@ class Net::HTTPGenericRequest
     return unless @uri
 
     if ssl
-      scheme = 'https'.freeze
+      scheme = 'https'
       klass = URI::HTTPS
     else
-      scheme = 'http'.freeze
+      scheme = 'http'
       klass = URI::HTTP
     end
 
     if host = self['host']
-      host.sub!(/:.*/m, ''.freeze)
+      host.sub!(/:.*/m, '')
     elsif host = @uri.host
     else
      host = addr
@@ -240,7 +316,7 @@ class Net::HTTPGenericRequest
     boundary ||= SecureRandom.urlsafe_base64(40)
     chunked_p = chunked?
 
-    buf = ''
+    buf = +''
     params.each do |key, value, h={}|
       key = quote_string(key, charset)
       filename =
@@ -325,7 +401,7 @@ class Net::HTTPGenericRequest
     if /[\r\n]/ =~ reqline
       raise ArgumentError, "A Request-Line must not contain CR or LF"
     end
-    buf = ""
+    buf = +''
     buf << reqline << "\r\n"
     each_capitalized do |k,v|
       buf << "#{k}: #{v}\r\n"

data/lib/net/http/header.rb

@@ -1,4 +1,4 @@
-# frozen_string_literal: false
+# frozen_string_literal: true
 #
 # The \HTTPHeader module provides access to \HTTP headers.
 #
@@ -179,6 +179,8 @@
 # - #each_value: Passes each string field value to the block.
 #
 module Net::HTTPHeader
+  MAX_KEY_LENGTH = 1024
+  MAX_FIELD_LENGTH = 65536
 
   def initialize_http_header(initheader) #:nodoc:
     @header = {}
@@ -189,6 +191,12 @@ module Net::HTTPHeader
         warn "net/http: nil HTTP header: #{key}", uplevel: 3 if $VERBOSE
       else
         value = value.strip # raise error for invalid byte sequences
+        if key.to_s.bytesize > MAX_KEY_LENGTH
+          raise ArgumentError, "too long (#{key.bytesize} bytes) header: #{key[0, 30].inspect}..."
+        end
+        if value.to_s.bytesize > MAX_FIELD_LENGTH
+          raise ArgumentError, "header #{key} has too long field value: #{value.bytesize}"
+        end
         if value.count("\r\n") > 0
           raise ArgumentError, "header #{key} has field value #{value.inspect}, this cannot include CR/LF"
         end
@@ -691,10 +699,14 @@ module Net::HTTPHeader
   #   res.content_type    # => "application/json"
   #
   def content_type
-    return nil unless main_type()
-    if sub_type()
-    then "#{main_type()}/#{sub_type()}"
-    else main_type()
+    main = main_type()
+    return nil unless main
+
+    sub = sub_type()
+    if sub
+      "#{main}/#{sub}"
+    else
+      main
     end
   end
 
@@ -763,19 +775,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>.
+  #
+  # The resulting request is suitable for HTTP request +POST+ or +PUT+.
+  #
+  # Argument +params+ must be suitable for use as argument +enum+ to
+  # {URI.encode_www_form}[https://docs.ruby-lang.org/en/master/URI.html#method-c-encode_www_form].
+  #
+  # With only argument +params+ given,
+  # sets the body to a URL-encoded string with the default separator <tt>'&'</tt>:
   #
-  # Values are URL encoded as necessary and the content-type is set to
-  # application/x-www-form-urlencoded
+  #   req = Net::HTTP::Post.new('example.com')
   #
-  # Example:
+  #   req.set_form_data(q: 'ruby', lang: 'en')
+  #   req.body            # => "q=ruby&lang=en"
+  #   req['Content-Type'] # => "application/x-www-form-urlencoded"
   #
-  #    http.form_data = {"q" => "ruby", "lang" => "en"}
-  #    http.form_data = {"q" => ["ruby", "perl"], "lang" => "en"}
-  #    http.set_form_data({"q" => "ruby", "lang" => "en"}, ';')
+  #   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 = '&')
@@ -787,56 +818,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}[https://docs.ruby-lang.org/en/master/Enumerable.html#module-Enumerable-label-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
@@ -852,12 +935,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
@@ -867,6 +962,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}
@@ -874,6 +970,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}

data/lib/net/http/proxy_delta.rb

@@ -1,4 +1,4 @@
-# frozen_string_literal: false
+# frozen_string_literal: true
 module Net::HTTP::ProxyDelta   #:nodoc: internal use only
   private
 

data/lib/net/http/request.rb

@@ -1,10 +1,55 @@
-# frozen_string_literal: false
+# frozen_string_literal: true
 
-# 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:
 #