From 444cf91d4cbf88b3f11bc6ec5b71c128e75aa303 Mon Sep 17 00:00:00 2001 From: BurdetteLamar Date: Mon, 30 Jan 2023 18:35:22 +0000 Subject: [PATCH 1/2] Enhanced RDoc for Net::HTTP --- doc/net-http/examples.rdoc | 3 +- lib/net/http.rb | 166 +++++++++++++++++-------------------- 2 files changed, 78 insertions(+), 91 deletions(-) diff --git a/doc/net-http/examples.rdoc b/doc/net-http/examples.rdoc index dd4acecd..c1366e7a 100644 --- a/doc/net-http/examples.rdoc +++ b/doc/net-http/examples.rdoc @@ -10,9 +10,10 @@ Many code examples here use these example websites: Some examples also assume these variables: - uri = URI('https://jsonplaceholder.typicode.com') + uri = URI('https://jsonplaceholder.typicode.com/') uri.freeze # Examples may not modify. hostname = uri.hostname # => "jsonplaceholder.typicode.com" + path = uri.path # => "/" port = uri.port # => 443 So that example requests may be written as: diff --git a/lib/net/http.rb b/lib/net/http.rb index 270743e5..75aa4681 100644 --- a/lib/net/http.rb +++ b/lib/net/http.rb @@ -39,6 +39,10 @@ class HTTPHeaderSyntaxError < StandardError; end # - {Hypertext Transfer Protocol}[https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol]. # - {Technical overview}[https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Technical_overview]. # + # == About the Examples + # + # :include: doc/net-http/examples.rdoc + # # == Strategies # # - If you will make only a few GET requests, @@ -49,17 +53,19 @@ class HTTPHeaderSyntaxError < StandardError; end # a {session}[rdoc-ref:Net::HTTP@Sessions] that sends a single request: # # # Return string response body. - # Net::HTTP.get(hostname, path, port = 80) - # Net::HTTP.get(uri, headers = {}, port = 80) + # Net::HTTP.get(hostname, path) + # Net::HTTP.get(uri) # # # Write string response body to $stdout. - # Net::HTTP.get_print(hostname, path_or_uri, port = 80) - # Net::HTTP.get_print(uri, headers = {}, port = 80) + # Net::HTTP.get_print(hostname, path) + # Net::HTTP.get_print(uri) # # # Return response as Net::HTTPResponse object. - # Net::HTTP.get_response(hostname, path_or_uri, port = 80) - # Net::HTTP.get_response(uri, headers = {}, port = 80) - # Net::HTTP.post(uri, data, headers = {}) + # Net::HTTP.get_response(hostname, path) + # Net::HTTP.get_response(uri) + # data = '{"title": "foo", "body": "bar", "userId": 1}' + # Net::HTTP.post(uri, data) + # params = {title: 'foo', body: 'bar', userId: 1} # Net::HTTP.post_form(uri, params) # # - If performance is important, consider using sessions, which lower request overhead. @@ -69,21 +75,22 @@ class HTTPHeaderSyntaxError < StandardError; end # # Net::HTTP.start(hostname) do |http| # # Session started automatically before block execution. - # http.get(path_or_uri, headers = {}) - # http.head(path_or_uri, headers = {}) - # http.post(path_or_uri, body, headers = {}) # Can also have a block. - # http.put(path_or_uri, body, headers = {}) - # http.delete(path_or_uri, headers = {Depth: 'Infinity'}) - # http.options(path_or_uri, headers = {}) - # http.trace(path_or_uri, headers = {}) - # http.patch(path_or_uri, body, headers = {}) # Can also have a block. - # http.copy(path_or_uri, headers = {}) - # http.lock(path_or_uri, body, headers = {}) - # http.mkcol(path_or_uri, body = nil, headers = {}) - # http.move(path_or_uri, headers = {}) - # http.propfind(path_or_uri, body = nil, headers = {'Depth' => '0'}) - # http.proppatch(path_or_uri, body, headers = {}) - # http.unlock(path_or_uri, body, headers = {}) + # http.get(path) + # http.head(path) + # body = 'Some text' + # http.post(path, body) # Can also have a block. + # http.put(path, body) + # http.delete(path) + # http.options(path) + # http.trace(path) + # http.patch(path, body) # Can also have a block. + # http.copy(path) + # http.lock(path, body) + # http.mkcol(path, body) + # http.move(path) + # http.propfind(path, body) + # http.proppatch(path, body) + # http.unlock(path, body) # # Session finished automatically at block exit. # end # @@ -91,10 +98,6 @@ class HTTPHeaderSyntaxError < StandardError; end # allow minimal control over the requests. # For greater control, consider using {request objects}[rdoc-ref:Net::HTTPRequest]. # - # == About the Examples - # - # :include: doc/net-http/examples.rdoc - # # == URIs # # On the internet, a URI @@ -263,62 +266,53 @@ class HTTPHeaderSyntaxError < StandardError; end # # For example, all 2XX responses are instances of a Net::HTTPSuccess # subclass, a 3XX response is an instance of a Net::HTTPRedirection - # subclass and a 200 response is an instance of the Net::HTTPOK class. For - # details of response classes, see the section "HTTP Response Classes" - # below. + # subclass and a 200 response is an instance of the Net::HTTPOK class. + # For details, see HTTPResponse. # # Using a case statement you can handle various types of responses properly: # - # def fetch(uri_str, limit = 10) + # def fetch(uri, limit = 10) # # You should choose a better exception. # raise ArgumentError, 'too many HTTP redirects' if limit == 0 # - # response = Net::HTTP.get_response(URI(uri_str)) - # - # case response + # res = Net::HTTP.get_response(URI(uri)) + # case res # when Net::HTTPSuccess then - # response + # res # when Net::HTTPRedirection then - # location = response['location'] + # location = res['location'] # warn "redirected to #{location}" # fetch(location, limit - 1) # else - # response.value + # res.value # end # end # - # print fetch('http://www.ruby-lang.org') + # fetch(uri) # # == Basic Authentication # # Basic authentication is performed according to - # [RFC2617](http://www.ietf.org/rfc/rfc2617.txt). - # - # uri = URI('http://example.com/index.html?key=value') + # {RFC2617}[http://www.ietf.org/rfc/rfc2617.txt]: # # req = Net::HTTP::Get.new(uri) - # req.basic_auth 'user', 'pass' - # - # res = Net::HTTP.start(uri.hostname, uri.port) {|http| + # req.basic_auth('user', 'pass') + # res = Net::HTTP.start(hostname) do |http| # http.request(req) - # } - # puts res.body + # end # # == Streaming Response Bodies # - # By default Net::HTTP reads an entire response into memory. If you are + # By default \Net::HTTP reads an entire response into memory. If you are # handling large files or wish to implement a progress bar you can instead # stream the body directly to an IO. # - # uri = URI('http://example.com/large_file') - # - # Net::HTTP.start(uri.host, uri.port) do |http| - # request = Net::HTTP::Get.new uri - # - # http.request request do |response| - # open 'large_file', 'w' do |io| - # response.read_body do |chunk| - # io.write chunk + # Net::HTTP.start(hostname) do |http| + # req = Net::HTTP::Get.new(uri) + # http.request(req) do |res| + # open('t.tmp', 'w') do |f| + # res.read_body do |chunk| + # f.write chunk # end # end # end @@ -326,28 +320,23 @@ class HTTPHeaderSyntaxError < StandardError; end # # == HTTPS # - # HTTPS is enabled for an HTTP connection by Net::HTTP#use_ssl=. - # - # uri = URI('https://secure.example.com/some_path?query=string') + # HTTPS is enabled for an HTTP connection by Net::HTTP#use_ssl=: # - # Net::HTTP.start(uri.host, uri.port, :use_ssl => true) do |http| - # request = Net::HTTP::Get.new uri - # response = http.request request # Net::HTTPResponse object + # Net::HTTP.start(hostname, :use_ssl => true) do |http| + # req = Net::HTTP::Get.new(uri) + # res = http.request(req) # end # - # Or if you simply want to make a GET request, you may pass in an URI - # object that has an HTTPS URL. Net::HTTP automatically turns on TLS - # verification if the URI object has a 'https' URI scheme. + # Or if you simply want to make a GET request, you may pass in a URI + # object that has an HTTPS URL. \Net::HTTP automatically turns on TLS + # verification if the URI object has a 'https' URI scheme: # - # uri = URI('https://example.com/') - # Net::HTTP.get(uri) # => String - # - # In previous versions of Ruby you would need to require 'net/https' to use - # HTTPS. This is no longer true. + # uri # => # + # Net::HTTP.get(uri) # # == Proxies # - # Net::HTTP will automatically create a proxy from the +http_proxy+ + # \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. # @@ -360,12 +349,9 @@ class HTTPHeaderSyntaxError < StandardError; end # # always proxy via your.proxy.addr:8080 # } # - # See Net::HTTP.new for further details and examples such as proxies that - # require a username and password. - # # == Compression # - # Net::HTTP automatically adds Accept-Encoding for compression of response + # \Net::HTTP automatically adds Accept-Encoding for compression of response # bodies and automatically decompresses gzip and deflate responses unless a # Range header was sent. # @@ -686,7 +672,7 @@ class << HTTP alias newobj new # :nodoc: end - # Returns a new Net::HTTP object +http+ + # Returns a new \Net::HTTP object +http+ # (but does not open a TCP connection or HTTP session). # # No Proxy @@ -819,7 +805,7 @@ def HTTP.new(address, port = nil, p_addr = :ENV, p_port = nil, p_user = nil, p_p http end - # Creates a new Net::HTTP object for the specified server address, + # Creates a new \Net::HTTP object for the specified server address, # without opening the TCP connection or initializing the HTTP session. # The +address+ should be a DNS hostname or IP address. def initialize(address, port = nil) @@ -1007,7 +993,7 @@ def ipaddr=(addr) # Number of seconds to wait for the connection to open. Any number # may be used, including Floats for fractional seconds. If the HTTP # object cannot open a connection in this many seconds, it raises a - # Net::OpenTimeout exception. The default value is 60 seconds. + # \Net::OpenTimeout exception. The default value is 60 seconds. attr_accessor :open_timeout # Number of seconds to wait for one block to be read (via one read(2) @@ -1019,12 +1005,12 @@ def ipaddr=(addr) # Number of seconds to wait for one block to be written (via one write(2) # call). Any number may be used, including Floats for fractional # seconds. If the HTTP object cannot write data in this many seconds, - # it raises a Net::WriteTimeout exception. The default value is 60 seconds. - # Net::WriteTimeout is not raised on Windows. + # it raises a \Net::WriteTimeout exception. The default value is 60 seconds. + # \Net::WriteTimeout is not raised on Windows. attr_reader :write_timeout # Sets the maximum number of times to retry an idempotent request in case of - # Net::ReadTimeout, IOError, EOFError, Errno::ECONNRESET, + # \Net::ReadTimeout, IOError, EOFError, Errno::ECONNRESET, # Errno::ECONNABORTED, Errno::EPIPE, OpenSSL::SSL::SSLError, # Timeout::Error. # The initial value is 1. @@ -1084,7 +1070,7 @@ def continue_timeout=(sec) # Seconds to reuse the connection of the previous request. # If the idle time is less than this Keep-Alive Timeout, - # Net::HTTP reuses the TCP/IP socket used by the previous communication. + # \Net::HTTP reuses the TCP/IP socket used by the previous communication. # The default value is 2 seconds. attr_accessor :keep_alive_timeout @@ -1109,7 +1095,7 @@ def use_ssl? # Turn on/off SSL. # This flag must be set before starting session. # If you change use_ssl value after session started, - # a Net::HTTP object raises IOError. + # IOError is raised. def use_ssl=(flag) flag = flag ? true : false if started? and @use_ssl != flag @@ -1218,7 +1204,7 @@ def peer_cert # Opens a TCP connection and HTTP session. # - # When this method is called with a block, it passes the Net::HTTP + # 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. # @@ -1387,11 +1373,11 @@ def do_finish @proxy_user = nil @proxy_pass = nil - # Creates an HTTP proxy class which behaves like Net::HTTP, but + # Creates an HTTP proxy class which behaves like \Net::HTTP, but # performs all access via the specified proxy. # # This class is obsolete. You may pass these same parameters directly to - # Net::HTTP.new. See Net::HTTP.new for details of the arguments. + # \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) #:nodoc: return self unless p_addr @@ -1419,16 +1405,16 @@ def proxy_class? defined?(@is_proxy_class) ? @is_proxy_class : false end - # Address of proxy host. If Net::HTTP does not use a proxy, nil. + # Address of proxy host. If \Net::HTTP does not use a proxy, nil. attr_reader :proxy_address - # Port number of proxy host. If Net::HTTP does not use a proxy, nil. + # Port number of proxy host. If \Net::HTTP does not use a proxy, nil. attr_reader :proxy_port - # User name for accessing proxy. If Net::HTTP does not use a proxy, nil. + # User name for accessing proxy. If \Net::HTTP does not use a proxy, nil. attr_reader :proxy_user - # User password for accessing proxy. If Net::HTTP does not use a proxy, + # User password for accessing proxy. \If Net::HTTP does not use a proxy, # nil. attr_reader :proxy_pass end @@ -1796,7 +1782,7 @@ def send_request(name, path, data = nil, header = nil) # # If +req+ is a Net::HTTP::Post or Net::HTTP::Put request containing # data, the data is also sent. Providing data for a Net::HTTP::Head or - # Net::HTTP::Get request results in an ArgumentError. + # \Net::HTTP::Get request results in an ArgumentError. # # Returns an HTTPResponse object. # From 7ffbebaa90671c10dcfebee8490d95c12b89129f Mon Sep 17 00:00:00 2001 From: Burdette Lamar Date: Mon, 30 Jan 2023 14:31:48 -0600 Subject: [PATCH 2/2] Update lib/net/http.rb Co-authored-by: Peter Zhu --- 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 75aa4681..fb0030c5 100644 --- a/lib/net/http.rb +++ b/lib/net/http.rb @@ -267,7 +267,7 @@ class HTTPHeaderSyntaxError < StandardError; end # For example, all 2XX responses are instances of a Net::HTTPSuccess # subclass, a 3XX response is an instance of a Net::HTTPRedirection # subclass and a 200 response is an instance of the Net::HTTPOK class. - # For details, see HTTPResponse. + # For details, see HTTPResponse. # # Using a case statement you can handle various types of responses properly: #