net-http 0.3.2 → 0.4.0

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.
@@ -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.

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