RubyGems - net-http - Versions diffs - 0.3.2 → 0.4.0 - Mend

net-http 0.3.2 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (22) hide show

checksums.yaml +4 -4
data/Gemfile +1 -0
data/Rakefile +0 -7
data/doc/net-http/examples.rdoc +2 -1
data/doc/net-http/included_getters.rdoc +3 -0
data/lib/net/http/backward.rb +1 -1
data/lib/net/http/exceptions.rb +1 -1
data/lib/net/http/generic_request.rb +91 -15
data/lib/net/http/header.rb +164 -67
data/lib/net/http/proxy_delta.rb +1 -1
data/lib/net/http/request.rb +50 -5
data/lib/net/http/requests.rb +31 -1
data/lib/net/http/response.rb +42 -22
data/lib/net/http/responses.rb +507 -55
data/lib/net/http/status.rb +7 -6
data/lib/net/http.rb +944 -464
data/lib/net/https.rb +1 -1
data/net-http.gemspec +9 -4
metadata +4 -6
data/.github/dependabot.yml +0 -6
data/.github/workflows/test.yml +0 -22
data/.gitignore +0 -7

checksums.yaml CHANGED Viewed

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d2201663415fa5809c53f6c1d8a06524739bcee246443e22175aa89cda45c92c
-  data.tar.gz: 971f571f8d9966a09baf43a5117d9f072ae78b890e6cc4991a958081728671c8
+  metadata.gz: a746ed42ea9e1e34ae2ae72383484b19ef4537fcf60a01cd92d17604573bd3b4
+  data.tar.gz: 4372f3a8601b83819d8f202af095bfbd2f4e3337e808c6e3488fba37e5b3c477
 SHA512:
-  metadata.gz: '086e4def849a69d4ecad94e1a13fe35eee82453f8748be247ea2c133b40ae7d3b419a0f71fa9dcd7efe783d0b725a13d527e287da1ccc406f7daa5700f2ec8e5'
-  data.tar.gz: 47a0f2d46fe8a9bc328241fb0fc90ea1c4285b0e46460998e40650a930bd96743051911e62b790d4502b39a007a5a04e260affe42d584bb73442ab414b51f1e3
+  metadata.gz: 22d42a16ac4309c1098bedf5bece45574cb19aec58b447defebb8f448c09a9398057086e508d8f88ee05fd91e8cf87d39126d973ec83a565fd3fb96e6f1fd7a2
+  data.tar.gz: ffd03e1e3db77772c38a31f00a10102c07ca1814c3572ceaec664a0bc03d7c8bac8a8bb5953e6603bf5f0b1d054bce6a565ee8a19810059a78e7731f26807f2d

data/Gemfile CHANGED Viewed

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

data/Rakefile CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 ADDED Viewed

@@ -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 CHANGED Viewed

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

data/lib/net/http/exceptions.rb CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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:
 #