From 90b988aba85018268efa1d567d31c7d921fe235c Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Wed, 7 Dec 2022 21:56:18 +0000 Subject: [PATCH 1/6] Enhanced RDoc for Net::HTTP --- lib/net/http.rb | 245 ++++++++++++++++++++++++++++++++++++------------ 1 file changed, 184 insertions(+), 61 deletions(-) diff --git a/lib/net/http.rb b/lib/net/http.rb index 985a72f2..63f725b2 100644 --- a/lib/net/http.rb +++ b/lib/net/http.rb @@ -452,6 +452,11 @@ def HTTP.get_print(uri_or_host, path_or_headers = nil, port = nil) # 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 @@ def HTTP.get(uri_or_host, path_or_headers = nil, port = nil) # 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,34 @@ def HTTP.get_response(uri_or_host, path_or_headers = nil, port = nil, &block) end end - # Posts data to the specified URI object. + # :call-seq: + # post(uri, data, headers = {}) # - # Example: + # Posts data to a host; returns a Net::HTTPResponse object. + # + # Argument +uri+ must be a URI; + # argument +data+ must be a string: + # + # _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) # => # + # puts res.body + # + # Output: + # + # { + # "title": "foo", + # "body": "bar", + # "userId": 1, + # "id": 101 + # } # - # require 'net/http' - # require 'uri' + # Related: # - # Net::HTTP.post URI('http://www.example.com/api/search'), - # { "q" => "ruby", "max" => "50" }.to_json, - # "Content-Type" => "application/json" + # - 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 +520,28 @@ def HTTP.post(url, data, header = nil) } 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: + # :call-seq: + # Net::HTTP.post_form(uri, data) -> response # - # { "cmd" => "search", "q" => "ruby", "max" => "50" } + # Posts data to a host; returns a Net::HTTPResponse object. # - # 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. + # Argument +uri+ must be a URI; + # argument +data+ must be a hash: # - # Example: + # _uri = uri.dup + # _uri.path = '/posts' + # data = {title: 'foo', body: 'bar', userId: 1} + # res = Net::HTTP.post_form(_uri, data) # => # + # puts res.body # - # 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 +557,26 @@ def HTTP.post_form(url, params) # 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.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.default_port # => 443 + # def HTTP.https_default_port 443 end @@ -548,20 +586,42 @@ def HTTP.socket_type #:nodoc: obsolete 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| ... } + # 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 # - # Creates a new \Net::HTTP object, - # opens a TCP connection and \HTTP session. + # Creates a new \Net::HTTP object, +http+, via \Net::HTTP.new: # - # Argument +address+ is the hostname or IP address of the server. + # 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 opts[:use_ssl] is a truthy value, + # the value passed to +new+ is Net::HTTP.https_default_port, not +port+. + # + # With no block given: + # + # - Calls http.start 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 http.start 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: # @@ -586,19 +646,7 @@ def HTTP.socket_type #:nodoc: obsolete # "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. # @@ -649,25 +697,100 @@ class << HTTP alias newobj new # :nodoc: end - # Creates a new Net::HTTP object without opening a TCP connection or - # HTTP session. + # :call-seq: + # HTTP.new(address, port = nil, p_addr = :ENV, p_port = nil, p_user = nil, p_pass = nil, p_no_proxy) → http + # + # Returns a new Net::HTTP object +http+ + # (but does not open a TCP connection or HTTP session). + # + # No Proxy + # + # With only string argument +hostname+ given + # (and ENV['http_proxy'] undefined or +nil+), + # the returned +http+: + # + # - Has the given address. + # - Has the default port number + # (Net::HTTP.http_default_port or Net::HTTP.https_default_port, + # depending on host's protocol). + # - Has no proxy. + # + # Example: + # + # http = Net::HTTP.new(hostname) + # # => # + # 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) + # # => # + # http.port # => 8000 + # + # Proxy Using Argument +p_addr+ as a \String + # + # When argument +p_addr+ is a string hostname, + # the returned +http+ has a proxy: + # + # http = Net::HTTP.new(hostname, nil, 'proxy.example') + # # => # + # 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') + # # => # + # http.proxy? # => true + # http.proxy_address # => "proxy.example" + # http.proxy_port # => 8000 + # http.proxy_user # => "pname" + # http.proxy_pass # => "ppass" + # + # Proxy Using ENV['http_proxy'] + # + # When environment variable 'http_proxy' + # (or uppercase 'HTTP_PROXY') + # 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 'http' or 'https': + # + # ENV['http_proxy'] = 'http://example.com' + # # => "http://example.com" + # http = Net::HTTP.new(hostname) + # # => # + # 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) + # # => # + # http.proxy_port # => 8000 + # http.proxy_user # => "pname" + # http.proxy_pass # => "ppass" # - # 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. + # Proxy Using Argument +p_addr+ as \Symbol :ENV # - # 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. + # When argument +p_addr+ is given as +:ENV+, + # the returned +http+ has a proxy: # - # 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. + # ENV['http_proxy'] = 'http://example.com' + # # => "http://example.com" + # http = Net::HTTP.new(hostname, 8000, :ENV) + # # => # + # http.proxy_address # => "example.com" # 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 @@ -1161,7 +1284,7 @@ def do_finish # # 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) { From 32d23eed7b452e2bd7e22ab8a0d0213778969d91 Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Sat, 10 Dec 2022 20:59:13 +0000 Subject: [PATCH 2/6] Enhanced RDoc for Net::HTTP --- lib/net/http.rb | 51 +++++++++++++++++++++++++++++++++---------------- 1 file changed, 35 insertions(+), 16 deletions(-) diff --git a/lib/net/http.rb b/lib/net/http.rb index 63f725b2..9d5cb08b 100644 --- a/lib/net/http.rb +++ b/lib/net/http.rb @@ -484,12 +484,9 @@ def HTTP.get_response(uri_or_host, path_or_headers = nil, port = nil, &block) end end - # :call-seq: - # post(uri, data, headers = {}) - # # Posts data to a host; returns a Net::HTTPResponse object. # - # Argument +uri+ must be a URI; + # Argument +url+ must be a URL; # argument +data+ must be a string: # # _uri = uri.dup @@ -567,15 +564,15 @@ def HTTP.default_port # Returns integer +80+, the default port to use for HTTP requests: # - # Net::HTTP.default_port # => 80 + # Net::HTTP.http_default_port # => 80 # def HTTP.http_default_port 80 end - # Returns integer +443+, the default port to use for HTTPs requests: + # Returns integer +443+, the default port to use for HTTPS requests: # - # Net::HTTP.default_port # => 443 + # Net::HTTP.https_default_port # => 443 # def HTTP.https_default_port 443 @@ -586,7 +583,7 @@ def HTTP.socket_type #:nodoc: obsolete end # :call-seq: - # 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 # HTTP.start(address, port = nil, p_addr = :ENV, p_port = nil, p_user = nil, p_pass = nil, opts) {|http| ... } -> object # # Creates a new \Net::HTTP object, +http+, via \Net::HTTP.new: @@ -697,9 +694,6 @@ class << HTTP alias newobj new # :nodoc: end - # :call-seq: - # HTTP.new(address, port = nil, p_addr = :ENV, p_port = nil, p_user = nil, p_pass = nil, p_no_proxy) → http - # # Returns a new Net::HTTP object +http+ # (but does not open a TCP connection or HTTP session). # @@ -710,9 +704,7 @@ class << HTTP # the returned +http+: # # - Has the given address. - # - Has the default port number - # (Net::HTTP.http_default_port or Net::HTTP.https_default_port, - # depending on host's protocol). + # - Has the default port number, Net::HTTP.default_port (80). # - Has no proxy. # # Example: @@ -757,7 +749,6 @@ class << HTTP # Proxy Using ENV['http_proxy'] # # When environment variable 'http_proxy' - # (or uppercase 'HTTP_PROXY') # 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 @@ -783,7 +774,7 @@ class << HTTP # # Proxy Using Argument +p_addr+ as \Symbol :ENV # - # When argument +p_addr+ is given as +:ENV+, + # When argument +p_addr+ is given as +:ENV+ (the default), # the returned +http+ has a proxy: # # ENV['http_proxy'] = 'http://example.com' @@ -792,6 +783,34 @@ class << HTTP # # => # # http.proxy_address # => "example.com" # + # 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: + # + # http = Net::HTTP.new('example.com', nil, 'my.proxy.example', 8000, 'pname', 'ppass', 'proxy.example') + # http.proxy_address # => nil + # + # Reject certain addresses and port combinations: + # + # 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 From 1b6ff704e6d6f1b971d2111d5768ab03944ed852 Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Sun, 11 Dec 2022 15:17:01 +0000 Subject: [PATCH 3/6] Enhanced RDoc for Net::HTTPHeader --- lib/net/http.rb | 16 +--------------- 1 file changed, 1 insertion(+), 15 deletions(-) diff --git a/lib/net/http.rb b/lib/net/http.rb index 9d5cb08b..494f4002 100644 --- a/lib/net/http.rb +++ b/lib/net/http.rb @@ -517,9 +517,6 @@ def HTTP.post(url, data, header = nil) } end - # :call-seq: - # Net::HTTP.post_form(uri, data) -> response - # # Posts data to a host; returns a Net::HTTPResponse object. # # Argument +uri+ must be a URI; @@ -772,17 +769,6 @@ class << HTTP # http.proxy_user # => "pname" # http.proxy_pass # => "ppass" # - # Proxy Using Argument +p_addr+ as \Symbol :ENV - # - # When argument +p_addr+ is given as +:ENV+ (the default), - # the returned +http+ has a proxy: - # - # ENV['http_proxy'] = 'http://example.com' - # # => "http://example.com" - # http = Net::HTTP.new(hostname, 8000, :ENV) - # # => # - # http.proxy_address # => "example.com" - # # You can use argument +p_no_proxy+ to reject certain proxies: # # - Reject a certain address: @@ -795,7 +781,7 @@ class << HTTP # http = Net::HTTP.new('example.com', nil, 'my.proxy.example', 8000, 'pname', 'ppass', 'proxy.example') # http.proxy_address # => nil # - # Reject certain addresses and port combinations: + # - Reject certain addresses and port combinations: # # http = Net::HTTP.new('example.com', nil, 'proxy.example', 8000, 'pname', 'ppass', 'proxy.example:1234') # http.proxy_address # => "proxy.example" From 34461ed949660adaa7b39906657c94602e5ac900 Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Sun, 11 Dec 2022 18:53:25 +0000 Subject: [PATCH 4/6] Enhanced RDoc for Net::HTTPHeader --- lib/net/http.rb | 2 ++ 1 file changed, 2 insertions(+) diff --git a/lib/net/http.rb b/lib/net/http.rb index 494f4002..44b57dca 100644 --- a/lib/net/http.rb +++ b/lib/net/http.rb @@ -769,6 +769,8 @@ class << HTTP # http.proxy_user # => "pname" # http.proxy_pass # => "ppass" # + # Argument +p_no_proxy+ + # # You can use argument +p_no_proxy+ to reject certain proxies: # # - Reject a certain address: From 157e1a1670b0373b7c6e17508ff0da986dbc1566 Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Sun, 11 Dec 2022 19:41:27 +0000 Subject: [PATCH 5/6] Enhanced RDoc for Net::HTTPHeader --- lib/net/http.rb | 3 +++ 1 file changed, 3 insertions(+) diff --git a/lib/net/http.rb b/lib/net/http.rb index 44b57dca..2de1cee8 100644 --- a/lib/net/http.rb +++ b/lib/net/http.rb @@ -517,6 +517,9 @@ def HTTP.post(url, data, header = nil) } end + # :call-seq: + # post_form(uri, params) + # # Posts data to a host; returns a Net::HTTPResponse object. # # Argument +uri+ must be a URI; From 81d32f64459f95674859c4cfabf55d33b2f73d4f Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Sun, 11 Dec 2022 21:31:04 +0000 Subject: [PATCH 6/6] Enhanced RDoc for Net::HTTPHeader --- lib/net/http.rb | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/lib/net/http.rb b/lib/net/http.rb index 2de1cee8..9fc50ab0 100644 --- a/lib/net/http.rb +++ b/lib/net/http.rb @@ -517,12 +517,9 @@ def HTTP.post(url, data, header = nil) } end - # :call-seq: - # post_form(uri, params) - # # Posts data to a host; returns a Net::HTTPResponse object. # - # Argument +uri+ must be a URI; + # Argument +url+ must be a URI; # argument +data+ must be a hash: # # _uri = uri.dup