From 1fad1d44850c066c12ae52420cd535d0cad4316a Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Fri, 3 Feb 2023 21:13:40 +0000 Subject: [PATCH 1/5] Enhanced RDoc for Net::HTTP --- lib/net/http.rb | 95 +++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 76 insertions(+), 19 deletions(-) diff --git a/lib/net/http.rb b/lib/net/http.rb index 0be6db93..af3c4222 100644 --- a/lib/net/http.rb +++ b/lib/net/http.rb @@ -1058,6 +1058,7 @@ def read_timeout=(sec) # EOF # headers = {'content-type': 'application/json'} # http = Net::HTTP.new(hostname) + # http.write_timeout # => 60 # http.post(_uri.path, data, headers) # # => # # http.write_timeout = 0 @@ -1068,12 +1069,21 @@ def write_timeout=(sec) @write_timeout = sec end - # Seconds to wait for 100 Continue response. If the \HTTP object does not - # receive a response in this many seconds it sends the request body. The - # default value is +nil+. + # Returns the continue-timeout value. + # See Net::HTTP.continue_timeout=. + # attr_reader :continue_timeout - # Setter for the continue_timeout attribute. + # Sets the continue-timeout value, + # which is the number of seconds to wait for an expected 100 Continue response. + # If the \HTTP object does not receive a response in this many seconds + # it sends the request body: + # + # http = Net::HTTP.new(hostname) + # http.continue_timeout # => nil + # http.continue_timeout = 2 + # http.continue_timeout # => 2 + # def continue_timeout=(sec) @socket.continue_timeout = sec if @socket @continue_timeout = sec @@ -1089,7 +1099,19 @@ def continue_timeout=(sec) # Content-Length headers. For backwards compatibility, the default is true. attr_accessor :ignore_eof - # Returns true if the \HTTP session has been started. + # Returns +true+ if the \HTTP session has been started: + # + # http = Net::HTTP.new(hostname) + # http.started? # => false + # http.start + # http.started? # => true + # http.finish # => nil + # http.started? # => false + # Net::HTTP.start(hostname) do |http| + # http.started? + # end # => true + # http.started? # => false + # def started? @started end @@ -1098,15 +1120,30 @@ def started? attr_accessor :close_on_empty_response - # Returns true if SSL/TLS is being used with \HTTP. + # Returns +true+ if +self+ uses SSL, +false+ otherwise. + # See use_ssl=. def use_ssl? @use_ssl end - # Turn on/off SSL. - # This flag must be set before starting session. - # If you change use_ssl value after session started, - # IOError is raised. + # Sets whether a new session is to use + # {Secure Socket Layer}[https://en.wikipedia.org/wiki/Transport_Layer_Security]: + # + # port # => 443 # The HTTPS port + # http = Net::HTTP.new(hostname, port) + # http.use_ssl? # => false + # http.use_ssl = true + # http.use_ssl? # => true + # http.start do |http| + # http.use_ssl? + # end # => true + # + # Raises IOError if attempting to change during a session. + # + # Raises OpenSSL::SSL::SSLError if the port is not an HTTPS port. + # + # The setting may not be changed in an active session (raises IOError). + # def use_ssl=(flag) flag = flag ? true : false if started? and @use_ssl != flag @@ -1205,7 +1242,8 @@ def use_ssl=(flag) # See OpenSSL::SSL::SSLContext#verify_hostname= attr_accessor :verify_hostname - # Returns the X.509 certificates the server presented. + # The X509 certificate chain (an array of strings) for the session's socket peer, + # or +nil+ if none. def peer_cert if not use_ssl? or not @socket return nil @@ -1213,14 +1251,26 @@ def peer_cert @socket.io.peer_cert end - # Opens a TCP connection and \HTTP session. + # Starts an \HTTP session. # - # When this method is called with a block, it passes the \Net::HTTP - # object to the block, and closes the TCP connection and \HTTP session - # after the block has been executed. + # Without a block, returns +self+: # - # When called with a block, it returns the return value of the - # block; otherwise, it returns self. + # http = Net::HTTP.new(hostname) + # # => # + # http.start + # # => # + # http.started? # => true + # http.finish + # + # With a block, calls the block with +self+, + # finishes the session when the block exits, + # and returns the block's value: + # + # http.start do |http| + # http + # end + # # => # + # http.started? # => false # def start # :yield: http raise IOError, 'HTTP session already opened' if @started @@ -1356,8 +1406,15 @@ def on_connect end private :on_connect - # Finishes the \HTTP session and closes the TCP connection. - # Raises IOError if the session has not been started. + # Finishes the \HTTP session: + # + # http = Net::HTTP.new(hostname) + # http.start + # http.started? # => true + # http.finish # => nil + # http.started? # => false + # + # Raises IOError if not in a session. def finish raise IOError, 'HTTP session not yet started' unless started? do_finish From b5e25c17c46b905aecc43a6e2f1e0d5510a9a4e1 Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Sat, 4 Feb 2023 16:17:08 +0000 Subject: [PATCH 2/5] Enhanced RDoc forr Net::HTTP --- lib/net/http.rb | 27 +++++---------------------- 1 file changed, 5 insertions(+), 22 deletions(-) diff --git a/lib/net/http.rb b/lib/net/http.rb index af3c4222..8cee48bb 100644 --- a/lib/net/http.rb +++ b/lib/net/http.rb @@ -1074,16 +1074,10 @@ def write_timeout=(sec) # attr_reader :continue_timeout - # Sets the continue-timeout value, + # Sets the continue timeout value, # which is the number of seconds to wait for an expected 100 Continue response. # If the \HTTP object does not receive a response in this many seconds - # it sends the request body: - # - # http = Net::HTTP.new(hostname) - # http.continue_timeout # => nil - # http.continue_timeout = 2 - # http.continue_timeout # => 2 - # + # it sends the request body. def continue_timeout=(sec) @socket.continue_timeout = sec if @socket @continue_timeout = sec @@ -1107,6 +1101,7 @@ def continue_timeout=(sec) # http.started? # => true # http.finish # => nil # http.started? # => false + # # Net::HTTP.start(hostname) do |http| # http.started? # end # => true @@ -1121,29 +1116,17 @@ def started? attr_accessor :close_on_empty_response # Returns +true+ if +self+ uses SSL, +false+ otherwise. - # See use_ssl=. + # See Net::HTTP#use_ssl=. def use_ssl? @use_ssl end # Sets whether a new session is to use - # {Secure Socket Layer}[https://en.wikipedia.org/wiki/Transport_Layer_Security]: - # - # port # => 443 # The HTTPS port - # http = Net::HTTP.new(hostname, port) - # http.use_ssl? # => false - # http.use_ssl = true - # http.use_ssl? # => true - # http.start do |http| - # http.use_ssl? - # end # => true + # {Transport Layer Security}[https://en.wikipedia.org/wiki/Transport_Layer_Security]: # # Raises IOError if attempting to change during a session. # # Raises OpenSSL::SSL::SSLError if the port is not an HTTPS port. - # - # The setting may not be changed in an active session (raises IOError). - # def use_ssl=(flag) flag = flag ? true : false if started? and @use_ssl != flag From e6a93656b9ca3f522a3256d7727d6e1a5f2cc872 Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Sat, 4 Feb 2023 17:22:42 +0000 Subject: [PATCH 3/5] Enhanced RDoc forr Net::HTTP --- lib/net/http.rb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/net/http.rb b/lib/net/http.rb index 8cee48bb..f2dd0ce8 100644 --- a/lib/net/http.rb +++ b/lib/net/http.rb @@ -1069,7 +1069,7 @@ def write_timeout=(sec) @write_timeout = sec end - # Returns the continue-timeout value. + # Returns the continue timeout value. # See Net::HTTP.continue_timeout=. # attr_reader :continue_timeout From 6f06f98d350a408248a1e0102fe61d7674310145 Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Sun, 5 Feb 2023 20:09:02 +0000 Subject: [PATCH 4/5] Enhanced RDoc for Net::HTTP --- lib/net/http.rb | 205 +++++++++++++++++++++++++----------------------- 1 file changed, 107 insertions(+), 98 deletions(-) diff --git a/lib/net/http.rb b/lib/net/http.rb index f2dd0ce8..687b5d84 100644 --- a/lib/net/http.rb +++ b/lib/net/http.rb @@ -332,20 +332,108 @@ class HTTPHeaderSyntaxError < StandardError; end # uri # => # # Net::HTTP.get(uri) # - # == Proxies + # == Proxy Server + # + # An \HTTP object can have + # a {proxy server}[https://en.wikipedia.org/wiki/Proxy_server]. + # + # You can create an \HTTP object with a proxy server + # using method Net::HTTP.new or method net::HTTP.start. + # The two methods differ only in that: + # + # - Net::HTTP.new has +p_no_proxy+ as its last argument + # (see {Filtering Proxies}[rdoc-ref:Net::HTTP@Filtering+Proxies] below), + # and does not take a block (ignored if given). + # - Net::HTTP.start has +opts+ as its last argument (see Net::HTTP.start), + # and may take a block. + # + # The proxy may be defined either by argument +p_addr+ + # or by an environment variable. + # + # === Proxy Using Argument +p_addr+ as a \String + # + # When argument +p_addr+ is a string hostname, + # the returned +http+ has the given host as its proxy: + # + # http = Net::HTTP.new(hostname, nil, 'proxy.example') + # http.proxy? # => true + # http.proxy_from_env? # => false + # 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_from_env? # => false + # 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' + # is set to a \URI string, + # the returned +http+ will have the server at 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 = Net::HTTP.new(hostname) + # http.proxy? # => true + # http.proxy_from_env? # => true + # http.proxy_address # => "example.com" + # # These use default values. + # http.proxy_port # => 80 + # http.proxy_user # => nil + # http.proxy_pass # => nil + # + # The \URI string may include proxy username, password, and port number: + # + # ENV['http_proxy'] = 'http://pname:ppass@example.com:8000' + # http = Net::HTTP.new(hostname) + # http.proxy? # => true + # http.proxy_from_env? # => true + # http.proxy_address # => "example.com" + # http.proxy_port # => 8000 + # http.proxy_user # => "pname" + # http.proxy_pass # => "ppass" + # + # === Filtering Proxies + # + # With method Net::HTTP.new (but not Net::HTTP.start), + # you can use argument +p_no_proxy+ to filter 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: # - # \Net::HTTP will automatically create a proxy from the +http_proxy+ - # environment variable if it is present. To disable use of +http_proxy+, - # pass +nil+ for the proxy address. + # http = Net::HTTP.new('example.com', nil, 'proxy.example', 8000, 'pname', 'ppass', 'proxy.example:1234') + # http.proxy_address # => "proxy.example" # - # You may also create a custom proxy: + # http = Net::HTTP.new('example.com', nil, 'proxy.example', 8000, 'pname', 'ppass', 'proxy.example:8000') + # http.proxy_address # => nil # - # proxy_addr = 'your.proxy.host' - # proxy_port = 8080 + # - Reject a list of the types above delimited using a comma: # - # Net::HTTP.new('example.com', nil, proxy_addr, proxy_port).start { |http| - # # always proxy via your.proxy.addr:8080 - # } + # 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 # # == Compression # @@ -564,14 +652,11 @@ def HTTP.socket_type #:nodoc: obsolete # # 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 arguments +address+ and +port+, see Net::HTTP.new. + # - For proxy-defining arguments +p_addr+ through +p_pass+, + # see {Proxy Server}[rdoc-ref:Net::HTTP@Proxy+Server]. # - 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), @@ -644,6 +729,9 @@ def HTTP.socket_type #:nodoc: obsolete # - #verify_mode # - #write_timeout # + # 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+. + # def HTTP.start(address, *arg, &block) # :yield: +http+ arg.pop if opt = Hash.try_convert(arg[-1]) port, p_addr, p_port, p_user, p_pass = *arg @@ -673,9 +761,7 @@ class << 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 + # With only string argument +address+ given # (and ENV['http_proxy'] undefined or +nil+), # the returned +http+: # @@ -698,85 +784,8 @@ class << HTTP # # => # # 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' - # 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" - # - # Argument +p_no_proxy+ - # - # 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 + # For proxy-defining arguments +p_addr+ through +p_pass+, + # see {Proxy Server}[rdoc-ref:Net::HTTP@Proxy+Server]. # 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 c996aaec5f00946930f212c6540065604b579d66 Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Tue, 7 Feb 2023 12:25:12 +0000 Subject: [PATCH 5/5] Enhanced RDoc for Net::HTTP --- lib/net/http.rb | 13 +++---------- 1 file changed, 3 insertions(+), 10 deletions(-) diff --git a/lib/net/http.rb b/lib/net/http.rb index 687b5d84..8b23f509 100644 --- a/lib/net/http.rb +++ b/lib/net/http.rb @@ -338,17 +338,10 @@ class HTTPHeaderSyntaxError < StandardError; end # a {proxy server}[https://en.wikipedia.org/wiki/Proxy_server]. # # You can create an \HTTP object with a proxy server - # using method Net::HTTP.new or method net::HTTP.start. - # The two methods differ only in that: - # - # - Net::HTTP.new has +p_no_proxy+ as its last argument - # (see {Filtering Proxies}[rdoc-ref:Net::HTTP@Filtering+Proxies] below), - # and does not take a block (ignored if given). - # - Net::HTTP.start has +opts+ as its last argument (see Net::HTTP.start), - # and may take a block. + # using method Net::HTTP.new or method Net::HTTP.start. # # The proxy may be defined either by argument +p_addr+ - # or by an environment variable. + # or by environment variable 'http_proxy'. # # === Proxy Using Argument +p_addr+ as a \String # @@ -784,7 +777,7 @@ class << HTTP # # => # # http.port # => 8000 # - # For proxy-defining arguments +p_addr+ through +p_pass+, + # For proxy-defining arguments +p_addr+ through +p_no_proxy+, # see {Proxy Server}[rdoc-ref:Net::HTTP@Proxy+Server]. # def HTTP.new(address, port = nil, p_addr = :ENV, p_port = nil, p_user = nil, p_pass = nil, p_no_proxy = nil)