net-http 0.3.1 → 0.3.2

data/lib/net/http.rb

@@ -379,7 +379,7 @@ module Net   #:nodoc:
   class HTTP < Protocol
 
     # :stopdoc:
-    VERSION = "0.3.1"
+    VERSION = "0.3.2"
     Revision = %q$Revision$.split[1]
     HTTPVersion = '1.1'
     begin
@@ -452,6 +452,11 @@ module Net   #:nodoc:
     #   headers = {'Content-type' => 'application/json; charset=UTF-8'}
     #   Net::HTTP.get(uri, headers)
     #
+    # Related:
+    #
+    # - Net::HTTP::Get: request class for \HTTP method +GET+.
+    # - Net::HTTP#get: convenience method for \HTTP method +GET+.
+    #
     def HTTP.get(uri_or_host, path_or_headers = nil, port = nil)
       get_response(uri_or_host, path_or_headers, port).body
     end
@@ -460,7 +465,7 @@ module Net   #:nodoc:
     #   Net::HTTP.get_response(hostname, path, port = 80) -> http_response
     #   Net::HTTP:get_response(uri, headers = {}, port = uri.port) -> http_response
     #
-    # Like Net::HTTP.get, but returns an Net::HTTPResponse object
+    # Like Net::HTTP.get, but returns a Net::HTTPResponse object
     # instead of the body string.
     def HTTP.get_response(uri_or_host, path_or_headers = nil, port = nil, &block)
       if path_or_headers && !path_or_headers.is_a?(Hash)
@@ -479,16 +484,31 @@ module Net   #:nodoc:
       end
     end
 
-    # Posts data to the specified URI object.
+    # Posts data to a host; returns a Net::HTTPResponse object.
     #
-    # Example:
+    # Argument +url+ must be a URL;
+    # argument +data+ must be a string:
     #
-    #   require 'net/http'
-    #   require 'uri'
+    #   _uri = uri.dup
+    #   _uri.path = '/posts'
+    #   data = '{"title": "foo", "body": "bar", "userId": 1}'
+    #   headers = {'content-type': 'application/json'}
+    #   res = Net::HTTP.post(_uri, data, headers) # => #<Net::HTTPCreated 201 Created readbody=true>
+    #   puts res.body
     #
-    #   Net::HTTP.post URI('http://www.example.com/api/search'),
-    #                  { "q" => "ruby", "max" => "50" }.to_json,
-    #                  "Content-Type" => "application/json"
+    # Output:
+    #
+    #   {
+    #     "title": "foo",
+    #     "body": "bar",
+    #     "userId": 1,
+    #     "id": 101
+    #   }
+    #
+    # Related:
+    #
+    # - Net::HTTP::Post: request class for \HTTP method +POST+.
+    # - Net::HTTP#post: convenience method for \HTTP method +POST+.
     #
     def HTTP.post(url, data, header = nil)
       start(url.hostname, url.port,
@@ -497,22 +517,25 @@ module Net   #:nodoc:
       }
     end
 
-    # Posts HTML form data to the specified URI object.
-    # The form data must be provided as a Hash mapping from String to String.
-    # Example:
+    # Posts data to a host; returns a Net::HTTPResponse object.
     #
-    #   { "cmd" => "search", "q" => "ruby", "max" => "50" }
+    # Argument +url+ must be a URI;
+    # argument +data+ must be a hash:
     #
-    # This method also does Basic Authentication if and only if +url+.user exists.
-    # But userinfo for authentication is deprecated (RFC3986).
-    # So this feature will be removed.
+    #   _uri = uri.dup
+    #   _uri.path = '/posts'
+    #   data = {title: 'foo', body: 'bar', userId: 1}
+    #   res = Net::HTTP.post_form(_uri, data) # => #<Net::HTTPCreated 201 Created readbody=true>
+    #   puts res.body
     #
-    # Example:
-    #
-    #   require 'net/http'
+    # Output:
     #
-    #   Net::HTTP.post_form URI('http://www.example.com/search.cgi'),
-    #                       { "q" => "ruby", "max" => "50" }
+    #   {
+    #     "title": "foo",
+    #     "body": "bar",
+    #     "userId": "1",
+    #     "id": 101
+    #   }
     #
     def HTTP.post_form(url, params)
       req = Post.new(url)
@@ -528,17 +551,26 @@ module Net   #:nodoc:
     # HTTP session management
     #
 
-    # The default port to use for HTTP requests; defaults to 80.
+    # Returns intger +80+, the default port to use for HTTP requests:
+    #
+    #   Net::HTTP.default_port # => 80
+    #
     def HTTP.default_port
       http_default_port()
     end
 
-    # The default port to use for HTTP requests; defaults to 80.
+    # Returns integer +80+, the default port to use for HTTP requests:
+    #
+    #   Net::HTTP.http_default_port # => 80
+    #
     def HTTP.http_default_port
       80
     end
 
-    # The default port to use for HTTPS requests; defaults to 443.
+    # Returns integer +443+, the default port to use for HTTPS requests:
+    #
+    #   Net::HTTP.https_default_port # => 443
+    #
     def HTTP.https_default_port
       443
     end
@@ -548,19 +580,42 @@ module Net   #:nodoc:
     end
 
     # :call-seq:
-    #   HTTP.start(address, port, p_addr, p_port, p_user, p_pass) {|http| ... }
-    #   HTTP.start(address, port=nil, p_addr=:ENV, p_port=nil, p_user=nil, p_pass=nil, opt) {|http| ... }
-    # Creates a new \Net::HTTP object,
-    # opens a TCP connection and \HTTP session.
+    #   HTTP.start(address, port = nil, p_addr = :ENV, p_port = nil, p_user = nil, p_pass = nil, opts) -> http
+    #   HTTP.start(address, port = nil, p_addr = :ENV, p_port = nil, p_user = nil, p_pass = nil, opts) {|http| ... } -> object
     #
-    # Argument +address+ is the hostname or IP address of the server.
+    # 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 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),
+    #   which opens a TCP connection and \HTTP session.
+    # - Returns +http+.
+    # - The caller should call #finish to close the session:
+    #
+    #     http = Net::HTTP.start(hostname)
+    #     http.started? # => true
+    #     http.finish
+    #     http.started? # => false
     #
     # With a block given:
     #
-    # - Passes the object to the given block,
-    #   which may make any number of requests to the host.
-    # - Closes the \HTTP session on block exit.
-    # - Returns the block's value.
+    # - Calls <tt>http.start</tt> with the block (see #start), which:
+    #
+    #   - Opens a TCP connection and \HTTP session.
+    #   - Calls the block,
+    #     which may make any number of requests to the host.
+    #   - Closes the \HTTP session and TCP connection on block exit.
+    #   - Returns the block's value +object+.
+    #
+    # - Returns +object+.
     #
     # Example:
     #
@@ -585,19 +640,7 @@ module Net   #:nodoc:
     #     "completed": false
     #   }
     #
-    # With no block given, returns the \Net::HTTP object;
-    # the caller should call #finish to close the session.
-    #
-    # Other arguments:
-    #
-    # - +port+: Server port number.
-    # - +p_addr+: Proxy address.
-    # - +p_port+: Proxy port.
-    # - +p_user+: Proxy user name.
-    # - +p_pass+: Proxy password.
-    # - +opts+: Optional options hash.
-    #
-    # The options hash +opts+ sets certain values,
+    # If the last argument given is a hash, it is the +opts+ hash,
     # where each key is a method or accessor to be called,
     # and its value is the value to be set.
     #
@@ -648,25 +691,113 @@ module Net   #:nodoc:
       alias newobj new # :nodoc:
     end
 
-    # Creates a new Net::HTTP object without opening a TCP connection or
-    # HTTP session.
+    # Returns a new Net::HTTP object +http+
+    # (but does not open a TCP connection or HTTP session).
+    #
+    # <b>No Proxy</b>
+    #
+    # With only string argument +hostname+ given
+    # (and <tt>ENV['http_proxy']</tt> undefined or +nil+),
+    # the returned +http+:
+    #
+    # - Has the given address.
+    # - Has the default port number, Net::HTTP.default_port (80).
+    # - Has no proxy.
+    #
+    # Example:
+    #
+    #   http = Net::HTTP.new(hostname)
+    #   # => #<Net::HTTP jsonplaceholder.typicode.com:80 open=false>
+    #   http.address # => "jsonplaceholder.typicode.com"
+    #   http.port    # => 80
+    #   http.proxy?  # => false
+    #
+    # With integer argument +port+ also given,
+    # the returned +http+ has the given port:
+    #
+    #   http = Net::HTTP.new(hostname, 8000)
+    #   # => #<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:
     #
-    # The +address+ should be a DNS hostname or IP address, the +port+ is the
-    # port the server operates on.  If no +port+ is given the default port for
-    # HTTP or HTTPS is used.
+    #     http = Net::HTTP.new('example.com', nil, 'my.proxy.example', 8000, 'pname', 'ppass', 'proxy.example')
+    #     http.proxy_address # => nil
     #
-    # If none of the +p_+ arguments are given, the proxy host and port are
-    # taken from the +http_proxy+ environment variable (or its uppercase
-    # equivalent) if present.  If the proxy requires authentication you must
-    # supply it by hand.  See URI::Generic#find_proxy for details of proxy
-    # detection from the environment.  To disable proxy detection set +p_addr+
-    # to nil.
+    # - Reject certain addresses and port combinations:
     #
-    # If you are connecting to a custom proxy, +p_addr+ specifies the DNS name
-    # or IP address of the proxy host, +p_port+ the port to use to access the
-    # proxy, +p_user+ and +p_pass+ the username and password if authorization
-    # is required to use the proxy, and p_no_proxy hosts which do not
-    # use the proxy.
+    #     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
     #
     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
@@ -733,6 +864,11 @@ module Net   #:nodoc:
       end
     end
 
+    # Returns a string representation of +self+:
+    #
+    #   Net::HTTP.new(hostname).inspect
+    #   # => "#<Net::HTTP jsonplaceholder.typicode.com:80 open=false>"
+    #
     def inspect
       "#<#{self.class} #{@address}:#{@port} open=#{started?}>"
     end
@@ -740,11 +876,51 @@ module Net   #:nodoc:
     # *WARNING* This method opens a serious security hole.
     # Never use this method in production code.
     #
-    # Sets an output stream for debugging.
+    # Sets the output stream for debugging:
     #
     #   http = Net::HTTP.new(hostname)
-    #   http.set_debug_output $stderr
-    #   http.start { .... }
+    #   File.open('t.tmp', 'w') do |file|
+    #     http.set_debug_output(file)
+    #     http.start
+    #     http.get('/nosuch/1')
+    #     http.finish
+    #   end
+    #   puts File.read('t.tmp')
+    #
+    # Output:
+    #
+    #   opening connection to jsonplaceholder.typicode.com:80...
+    #   opened
+    #   <- "GET /nosuch/1 HTTP/1.1\r\nAccept-Encoding: gzip;q=1.0,deflate;q=0.6,identity;q=0.3\r\nAccept: */*\r\nUser-Agent: Ruby\r\nHost: jsonplaceholder.typicode.com\r\n\r\n"
+    #   -> "HTTP/1.1 404 Not Found\r\n"
+    #   -> "Date: Mon, 12 Dec 2022 21:14:11 GMT\r\n"
+    #   -> "Content-Type: application/json; charset=utf-8\r\n"
+    #   -> "Content-Length: 2\r\n"
+    #   -> "Connection: keep-alive\r\n"
+    #   -> "X-Powered-By: Express\r\n"
+    #   -> "X-Ratelimit-Limit: 1000\r\n"
+    #   -> "X-Ratelimit-Remaining: 999\r\n"
+    #   -> "X-Ratelimit-Reset: 1670879660\r\n"
+    #   -> "Vary: Origin, Accept-Encoding\r\n"
+    #   -> "Access-Control-Allow-Credentials: true\r\n"
+    #   -> "Cache-Control: max-age=43200\r\n"
+    #   -> "Pragma: no-cache\r\n"
+    #   -> "Expires: -1\r\n"
+    #   -> "X-Content-Type-Options: nosniff\r\n"
+    #   -> "Etag: W/\"2-vyGp6PvFo4RvsFtPoIWeCReyIC8\"\r\n"
+    #   -> "Via: 1.1 vegur\r\n"
+    #   -> "CF-Cache-Status: MISS\r\n"
+    #   -> "Server-Timing: cf-q-config;dur=1.3000000762986e-05\r\n"
+    #   -> "Report-To: {\"endpoints\":[{\"url\":\"https:\\/\\/a.nel.cloudflare.com\\/report\\/v3?s=yOr40jo%2BwS1KHzhTlVpl54beJ5Wx2FcG4gGV0XVrh3X9OlR5q4drUn2dkt5DGO4GDcE%2BVXT7CNgJvGs%2BZleIyMu8CLieFiDIvOviOY3EhHg94m0ZNZgrEdpKD0S85S507l1vsEwEHkoTm%2Ff19SiO\"}],\"group\":\"cf-nel\",\"max_age\":604800}\r\n"
+    #   -> "NEL: {\"success_fraction\":0,\"report_to\":\"cf-nel\",\"max_age\":604800}\r\n"
+    #   -> "Server: cloudflare\r\n"
+    #   -> "CF-RAY: 778977dc484ce591-DFW\r\n"
+    #   -> "alt-svc: h3=\":443\"; ma=86400, h3-29=\":443\"; ma=86400\r\n"
+    #   -> "\r\n"
+    #   reading 2 bytes...
+    #   -> "{}"
+    #   read 2 bytes
+    #   Conn keep-alive
     #
     def set_debug_output(output)
       warn 'Net::HTTP#set_debug_output called after HTTP started', uplevel: 1 if started?
@@ -768,8 +944,24 @@ module Net   #:nodoc:
     # body encoding.
     attr_reader :response_body_encoding
 
-    # Set the encoding to use for the response body.  If given a String, find
-    # the related Encoding.
+    # Sets the encoding to be used for the response body;
+    # returns the encoding.
+    #
+    # The given +value+ may be:
+    #
+    # - An Encoding object.
+    # - The name of an encoding.
+    # - An alias for an encoding name.
+    #
+    # See {Encoding}[https://docs.ruby-lang.org/en/master/Encoding.html].
+    #
+    # Examples:
+    #
+    #   http = Net::HTTP.new(hostname)
+    #   http.response_body_encoding = Encoding::US_ASCII # => #<Encoding:US-ASCII>
+    #   http.response_body_encoding = 'US-ASCII'         # => "US-ASCII"
+    #   http.response_body_encoding = 'ASCII'            # => "ASCII"
+    #
     def response_body_encoding=(value)
       value = Encoding.find(value) if value.is_a?(String)
       @response_body_encoding = value
@@ -781,12 +973,37 @@ module Net   #:nodoc:
     attr_writer :proxy_user
     attr_writer :proxy_pass
 
-    # The IP address to connect to/used to connect to
+    # Returns the IP address for the connection.
+    #
+    # If the session has not been started,
+    # returns the value set by #ipaddr=,
+    # or +nil+ if it has not been set:
+    #
+    #   http = Net::HTTP.new(hostname)
+    #   http.ipaddr # => nil
+    #   http.ipaddr = '172.67.155.76'
+    #   http.ipaddr # => "172.67.155.76"
+    #
+    # If the session has been started,
+    # returns the IP address from the socket:
+    #
+    #   http = Net::HTTP.new(hostname)
+    #   http.start
+    #   http.ipaddr # => "172.67.155.76"
+    #   http.finish
+    #
     def ipaddr
       started? ?  @socket.io.peeraddr[3] : @ipaddr
     end
 
-    # Set the IP address to connect to
+    # Sets the IP address for the connection:
+    #
+    #   http = Net::HTTP.new(hostname)
+    #   http.ipaddr # => nil
+    #   http.ipaddr = '172.67.155.76'
+    #   http.ipaddr # => "172.67.155.76"
+    #
+    # The IP address may not be set if the session has been started.
     def ipaddr=(addr)
       raise IOError, "ipaddr value changed, but session already started" if started?
       @ipaddr = addr
@@ -811,12 +1028,18 @@ module Net   #:nodoc:
     # Net::WriteTimeout is not raised on Windows.
     attr_reader :write_timeout
 
-    # Maximum number of times to retry an idempotent request in case of
+    # Sets the maximum number of times to retry an idempotent request in case of
     # Net::ReadTimeout, IOError, EOFError, Errno::ECONNRESET,
     # Errno::ECONNABORTED, Errno::EPIPE, OpenSSL::SSL::SSLError,
     # Timeout::Error.
-    # Should be a non-negative integer number. Zero means no retries.
-    # The default value is 1.
+    # The initial value is 1.
+    #
+    # Argument +retries+ must be a non-negative numeric value:
+    #
+    #   http = Net::HTTP.new(hostname)
+    #   http.max_retries = 2   # => 2
+    #   http.max_retries       # => 2
+    #
     def max_retries=(retries)
       retries = retries.to_int
       if retries < 0
@@ -827,13 +1050,27 @@ module Net   #:nodoc:
 
     attr_reader :max_retries
 
-    # Setter for the read_timeout attribute.
+    # Sets the read timeout, in seconds, for +self+ to integer +sec+;
+    # the initial value is 60.
+    #
+    # Argument +sec+ must be a non-negative numeric value:
+    #
+    #   http = Net::HTTP.new(hostname)
+    #   http.read_timeout # => 60
+    #   http.get('/todos/1') # => #<Net::HTTPOK 200 OK readbody=true>
+    #   http.read_timeout = 0
+    #   http.get('/todos/1') # Raises Net::ReadTimeout.
+    #
     def read_timeout=(sec)
       @socket.read_timeout = sec if @socket
       @read_timeout = sec
     end
 
-    # Setter for the write_timeout attribute.
+    # 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.
+    #
     def write_timeout=(sec)
       @socket.write_timeout = sec if @socket
       @write_timeout = sec
@@ -1160,7 +1397,7 @@ module Net   #:nodoc:
     #
     # This class is obsolete.  You may pass these same parameters directly to
     # 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)
+    def HTTP.Proxy(p_addr = :ENV, p_port = nil, p_user = nil, p_pass = nil) #:nodoc:
       return self unless p_addr
 
       Class.new(self) {

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: net-http
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.3.2
 platform: ruby
 authors:
 - NARUSE, Yui
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-12-05 00:00:00.000000000 Z
+date: 2022-12-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: uri