net-http 0.3.2 → 0.6.0

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

data/lib/net/http/requests.rb

@@ -1,4 +1,4 @@
-# frozen_string_literal: false
+# frozen_string_literal: true
 
 # HTTP/1.1 methods --- RFC2616
 
@@ -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.
@@ -116,6 +124,11 @@ end
 # - {Idempotent}[https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Idempotent_methods]: yes.
 # - {Cacheable}[https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Cacheable_methods]: no.
 #
+# Related:
+#
+# - Net::HTTP.put: sends +PUT+ request, returns response object.
+# - Net::HTTP#put: sends +PUT+ request, returns response object.
+#
 class Net::HTTP::Put < Net::HTTPRequest
   METHOD = 'PUT'
   REQUEST_HAS_BODY = true
@@ -134,6 +147,8 @@ end
 #     http.request(req)
 #   end
 #
+# See {Request Headers}[rdoc-ref:Net::HTTPRequest@Request+Headers].
+#
 # Properties:
 #
 # - Request body: optional.
@@ -163,6 +178,8 @@ end
 #     http.request(req)
 #   end
 #
+# See {Request Headers}[rdoc-ref:Net::HTTPRequest@Request+Headers].
+#
 # Properties:
 #
 # - Request body: optional.
@@ -192,6 +209,8 @@ end
 #     http.request(req)
 #   end
 #
+# See {Request Headers}[rdoc-ref:Net::HTTPRequest@Request+Headers].
+#
 # Properties:
 #
 # - Request body: no.
@@ -224,6 +243,8 @@ end
 #     http.request(req)
 #   end
 #
+# See {Request Headers}[rdoc-ref:Net::HTTPRequest@Request+Headers].
+#
 # Properties:
 #
 # - Request body: yes.
@@ -257,6 +278,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 +301,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 +324,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 +347,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 +370,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 +393,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 +416,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.

data/lib/net/http/response.rb

@@ -1,6 +1,6 @@
-# frozen_string_literal: false
+# frozen_string_literal: true
 
-# 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
 #
@@ -224,13 +224,32 @@ class Net::HTTPResponse
   # Accept-Encoding header from the user.
   attr_accessor :decode_content
 
-  # The encoding to use for the response body. If Encoding, use that encoding.
-  # If other true value, attempt to detect the appropriate encoding, and use
-  # that.
+  # Returns the value set by body_encoding=, or +false+ if none;
+  # see #body_encoding=.
   attr_reader :body_encoding
 
-  # Set the encoding to use for the response body.  If given a String, find
-  # the related Encoding.
+  # Sets the encoding that should be used when reading the body:
+  #
+  # - If the given value is an Encoding object, that encoding will be used.
+  # - Otherwise if the value is a string, the value of
+  #   {Encoding#find(value)}[https://docs.ruby-lang.org/en/master/Encoding.html#method-c-find]
+  #   will be used.
+  # - Otherwise an encoding will be deduced from the body itself.
+  #
+  # Examples:
+  #
+  #   http = Net::HTTP.new(hostname)
+  #   req = Net::HTTP::Get.new('/')
+  #
+  #   http.request(req) do |res|
+  #     p res.body.encoding # => #<Encoding:ASCII-8BIT>
+  #   end
+  #
+  #   http.request(req) do |res|
+  #     res.body_encoding = "UTF-8"
+  #     p res.body.encoding # => #<Encoding:UTF-8>
+  #   end
+  #
   def body_encoding=(value)
     value = Encoding.find(value) if value.is_a?(String)
     @body_encoding = value
@@ -254,7 +273,7 @@ class Net::HTTPResponse
 
   def error!   #:nodoc:
     message = @code
-    message += ' ' + @message.dump if @message
+    message = "#{message} #{@message.dump}" if @message
     raise error_type().new(message, self)
   end
 
@@ -347,6 +366,7 @@ class Net::HTTPResponse
       @body = nil
     end
     @read = true
+    return if @body.nil?
 
     case enc = @body_encoding
     when Encoding, false, nil
@@ -362,26 +382,26 @@ class Net::HTTPResponse
     @body
   end
 
-  # Returns the full entity body.
+  # Returns the string response body;
+  # note that repeated calls for the unmodified body return a cached string:
   #
-  # Calling this method a second or subsequent time will return the
-  # string already read.
+  #   path = '/todos/1'
+  #   Net::HTTP.start(hostname) do |http|
+  #     res = http.get(path)
+  #     p res.body
+  #     p http.head(path).body # No body.
+  #   end
   #
-  #   http.request_get('/index.html') {|res|
-  #     puts res.body
-  #   }
+  # Output:
   #
-  #   http.request_get('/index.html') {|res|
-  #     p res.body.object_id   # 538149362
-  #     p res.body.object_id   # 538149362
-  #   }
+  #   "{\n  \"userId\": 1,\n  \"id\": 1,\n  \"title\": \"delectus aut autem\",\n  \"completed\": false\n}"
+  #   nil
   #
   def body
     read_body()
   end
 
-  # Because it may be necessary to modify the body, Eg, decompression
-  # this method facilitates that.
+  # Sets the body of the response to the given value.
   def body=(value)
     @body = value
   end
@@ -620,7 +640,7 @@ class Net::HTTPResponse
   end
 
   def stream_check
-    raise IOError, 'attempt to read body out of block' if @socket.closed?
+    raise IOError, 'attempt to read body out of block' if @socket.nil? || @socket.closed?
   end
 
   def procdest(dest, block)
@@ -629,7 +649,7 @@ class Net::HTTPResponse
     if block
       Net::ReadAdapter.new(block)
     else
-      dest || ''
+      dest || +''
     end
   end