http 5.3.1 → 6.0.0

data/lib/http/request/writer.rb

@@ -4,19 +4,24 @@ require "http/headers"
 
 module HTTP
   class Request
+    # Streams HTTP requests to a socket
     class Writer
       # CRLF is the universal HTTP delimiter
       CRLF = "\r\n"
 
-      # Chunked data termintaor.
+      # Chunked data terminator
       ZERO = "0"
 
-      # Chunked transfer encoding
-      CHUNKED = "chunked"
-
       # End of a chunked transfer
-      CHUNKED_END = "#{ZERO}#{CRLF}#{CRLF}"
+      CHUNKED_END = "#{ZERO}#{CRLF}#{CRLF}".freeze
 
+      # Initialize a new request writer
+      #
+      # @example
+      #   Writer.new(socket, body, headers, "GET / HTTP/1.1")
+      #
+      # @return [HTTP::Request::Writer]
+      # @api public
       def initialize(socket, body, headers, headline)
         @body           = body
         @socket         = socket
@@ -24,7 +29,13 @@ module HTTP
         @request_header = [headline]
       end
 
-      # Adds headers to the request header from the headers array
+      # Adds headers to the request header array
+      #
+      # @example
+      #   writer.add_headers
+      #
+      # @return [void]
+      # @api public
       def add_headers
         @headers.each do |field, value|
           @request_header << "#{field}: #{value}"
@@ -32,6 +43,12 @@ module HTTP
       end
 
       # Stream the request to a socket
+      #
+      # @example
+      #   writer.stream
+      #
+      # @return [void]
+      # @api public
       def stream
         add_headers
         add_body_type_headers
@@ -39,32 +56,54 @@ module HTTP
       end
 
       # Send headers needed to connect through proxy
+      #
+      # @example
+      #   writer.connect_through_proxy
+      #
+      # @return [void]
+      # @api public
       def connect_through_proxy
         add_headers
         write(join_headers)
       end
 
-      # Adds the headers to the header array for the given request body we are working
-      # with
+      # Adds content length or transfer encoding headers
+      #
+      # @example
+      #   writer.add_body_type_headers
+      #
+      # @return [void]
+      # @api public
       def add_body_type_headers
         return if @headers[Headers::CONTENT_LENGTH] || chunked? || (
           @body.source.nil? && %w[GET HEAD DELETE CONNECT].any? do |method|
-            @request_header[0].start_with?("#{method} ")
+            @request_header.fetch(0).start_with?("#{method} ")
           end
         )
 
         @request_header << "#{Headers::CONTENT_LENGTH}: #{@body.size}"
       end
 
-      # Joins the headers specified in the request into a correctly formatted
-      # http request header string
+      # Joins headers into an HTTP request header string
+      #
+      # @example
+      #   writer.join_headers
+      #
+      # @return [String]
+      # @api public
       def join_headers
         # join the headers array with crlfs, stick two on the end because
         # that ends the request header
         @request_header.join(CRLF) + (CRLF * 2)
       end
 
-      # Writes HTTP request data into the socket.
+      # Writes HTTP request data into the socket
+      #
+      # @example
+      #   writer.send_request
+      #
+      # @return [void]
+      # @api public
       def send_request
         each_chunk { |chunk| write chunk }
       rescue Errno::EPIPE
@@ -72,12 +111,18 @@ module HTTP
         nil
       end
 
-      # Yields chunks of request data that should be sent to the socket.
+      # Yields chunks of request data for the socket
       #
       # It's important to send the request in a single write call when possible
       # in order to play nicely with Nagle's algorithm. Making two writes in a
       # row triggers a pathological case where Nagle is expecting a third write
       # that never happens.
+      #
+      # @example
+      #   writer.each_chunk { |chunk| socket.write(chunk) }
+      #
+      # @return [void]
+      # @api public
       def each_chunk
         data = join_headers
 
@@ -92,7 +137,13 @@ module HTTP
         yield CHUNKED_END if chunked?
       end
 
-      # Returns the chunk encoded for to the specified "Transfer-Encoding" header.
+      # Returns chunk encoded per Transfer-Encoding header
+      #
+      # @example
+      #   writer.encode_chunk("hello")
+      #
+      # @return [String]
+      # @api public
       def encode_chunk(chunk)
         if chunked?
           chunk.bytesize.to_s(16) << CRLF << chunk << CRLF
@@ -101,14 +152,23 @@ module HTTP
         end
       end
 
-      # Returns true if the request should be sent in chunked encoding.
+      # Returns true if using chunked transfer encoding
+      #
+      # @example
+      #   writer.chunked?
+      #
+      # @return [Boolean]
+      # @api public
       def chunked?
-        @headers[Headers::TRANSFER_ENCODING] == CHUNKED
+        @headers[Headers::TRANSFER_ENCODING].eql?(Headers::CHUNKED)
       end
 
       private
 
+      # Write data to the underlying socket
+      # @return [void]
       # @raise [SocketWriteError] when unable to write to socket
+      # @api private
       def write(data)
         until data.empty?
           length = @socket.write(data)

data/lib/http/request.rb

@@ -7,16 +7,18 @@ require "http/base64"
 require "http/errors"
 require "http/headers"
 require "http/request/body"
+require "http/request/proxy"
 require "http/request/writer"
 require "http/version"
 require "http/uri"
 
 module HTTP
+  # Represents an HTTP request with verb, URI, headers, and body
   class Request
     extend Forwardable
 
     include HTTP::Base64
-    include HTTP::Headers::Mixin
+    include Proxy
 
     # The method given was not understood
     class UnsupportedMethodError < RequestError; end
@@ -25,8 +27,9 @@ module HTTP
     class UnsupportedSchemeError < RequestError; end
 
     # Default User-Agent header value
-    USER_AGENT = "http.rb/#{HTTP::VERSION}"
+    USER_AGENT = "http.rb/#{HTTP::VERSION}".freeze
 
+    # Supported HTTP methods
     METHODS = [
       # RFC 2616: Hypertext Transfer Protocol -- HTTP/1.1
       :options, :get, :head, :post, :put, :delete, :trace, :connect,
@@ -61,115 +64,176 @@ module HTTP
 
     # Default ports of supported schemes
     PORTS = {
-      :http  => 80,
-      :https => 443,
-      :ws    => 80,
-      :wss   => 443
+      http:  80,
+      https: 443,
+      ws:    80,
+      wss:   443
     }.freeze
 
-    # Method is given as a lowercase symbol e.g. :get, :post
+    # HTTP method as a lowercase symbol
+    #
+    # @example
+    #   request.verb # => :get
+    #
+    # @return [Symbol]
+    # @api public
     attr_reader :verb
 
-    # Scheme is normalized to be a lowercase symbol e.g. :http, :https
+    # URI scheme as a lowercase symbol
+    #
+    # @example
+    #   request.scheme # => :https
+    #
+    # @return [Symbol]
+    # @api public
     attr_reader :scheme
 
+    # URI normalizer callable
+    #
+    # @example
+    #   request.uri_normalizer
+    #
+    # @return [#call]
+    # @api public
     attr_reader :uri_normalizer
 
-    # "Request URI" as per RFC 2616
-    # http://www.w3.org/Protocols/rfc2616/rfc2616-sec5.html
+    # Request URI
+    #
+    # @example
+    #   request.uri # => #<HTTP::URI ...>
+    #
+    # @return [HTTP::URI]
+    # @api public
     attr_reader :uri
-    attr_reader :proxy, :body, :version
-
-    # @option opts [String] :version
-    # @option opts [#to_s] :verb HTTP request method
-    # @option opts [#call] :uri_normalizer (HTTP::URI::NORMALIZER)
-    # @option opts [HTTP::URI, #to_s] :uri
-    # @option opts [Hash] :headers
-    # @option opts [Hash] :proxy
-    # @option opts [String, Enumerable, IO, nil] :body
-    def initialize(opts)
-      @verb           = opts.fetch(:verb).to_s.downcase.to_sym
-      @uri_normalizer = opts[:uri_normalizer] || HTTP::URI::NORMALIZER
-
-      @uri    = @uri_normalizer.call(opts.fetch(:uri))
-      @scheme = @uri.scheme.to_s.downcase.to_sym if @uri.scheme
 
-      raise(UnsupportedMethodError, "unknown method: #{verb}") unless METHODS.include?(@verb)
-      raise(UnsupportedSchemeError, "unknown scheme: #{scheme}") unless SCHEMES.include?(@scheme)
+    # Proxy configuration hash
+    #
+    # @example
+    #   request.proxy
+    #
+    # @return [Hash]
+    # @api public
+    attr_reader :proxy
+
+    # Request body object
+    #
+    # @example
+    #   request.body
+    #
+    # @return [HTTP::Request::Body]
+    # @api public
+    attr_reader :body
 
-      @proxy   = opts[:proxy] || {}
-      @version = opts[:version] || "1.1"
-      @headers = prepare_headers(opts[:headers])
-      @body    = prepare_body(opts[:body])
+    # The HTTP headers collection
+    #
+    # @example
+    #   request.headers
+    #
+    # @return [HTTP::Headers]
+    # @api public
+    attr_reader :headers
+
+    # HTTP version string
+    #
+    # @example
+    #   request.version # => "1.1"
+    #
+    # @return [String]
+    # @api public
+    attr_reader :version
+
+    # Create a new HTTP request
+    #
+    # @param [#to_s] verb HTTP request method
+    # @param [HTTP::URI, #to_s] uri
+    # @param [Hash] headers
+    # @param [Hash] proxy
+    # @param [String, Enumerable, IO, nil] body
+    # @param [String] version
+    # @param [#call] uri_normalizer
+    #
+    # @example
+    #   Request.new(verb: :get, uri: "https://example.com")
+    #
+    # @return [HTTP::Request]
+    # @api public
+    def initialize(verb:, uri:, headers: nil, proxy: {}, body: nil, version: "1.1",
+                   uri_normalizer: nil)
+      @uri_normalizer = uri_normalizer || HTTP::URI::NORMALIZER
+      @verb = verb.to_s.downcase.to_sym
+      parse_uri!(uri)
+      validate_method_and_scheme!
+
+      @proxy   = proxy
+      @version = version
+      @headers = prepare_headers(headers)
+      @body    = prepare_body(body)
     end
 
     # Returns new Request with updated uri
+    #
+    # @example
+    #   request.redirect("https://example.com/new")
+    #
+    # @return [HTTP::Request]
+    # @api public
     def redirect(uri, verb = @verb)
-      headers = self.headers.dup
-      headers.delete(Headers::HOST)
-
-      new_body = body.source
-      if verb == :get
-        # request bodies should not always be resubmitted when following a redirect
-        # some servers will close the connection after receiving the request headers
-        # which may cause Errno::ECONNRESET: Connection reset by peer
-        # see https://github.com/httprb/http/issues/649
-        # new_body = Request::Body.new(nil)
-        new_body = nil
-        # the CONTENT_TYPE header causes problems if set on a get request w/ an empty body
-        # the server might assume that there should be content if it is set to multipart
-        # rack raises EmptyContentError if this happens
-        headers.delete(Headers::CONTENT_TYPE)
-      end
+      redirect_uri = @uri.join(uri)
+      headers = redirect_headers(redirect_uri, verb)
+      new_body = verb == :get ? nil : body.source
 
       self.class.new(
-        :verb           => verb,
-        :uri            => @uri.join(uri),
-        :headers        => headers,
-        :proxy          => proxy,
-        :body           => new_body,
-        :version        => version,
-        :uri_normalizer => uri_normalizer
+        verb:           verb,
+        uri:            redirect_uri,
+        headers:        headers,
+        proxy:          proxy,
+        body:           new_body,
+        version:        version,
+        uri_normalizer: uri_normalizer
       )
     end
 
     # Stream the request to a socket
+    #
+    # @example
+    #   request.stream(socket)
+    #
+    # @return [void]
+    # @api public
     def stream(socket)
       include_proxy_headers if using_proxy? && !@uri.https?
       Request::Writer.new(socket, body, headers, headline).stream
     end
 
     # Is this request using a proxy?
+    #
+    # @example
+    #   request.using_proxy?
+    #
+    # @return [Boolean]
+    # @api public
     def using_proxy?
       proxy && proxy.keys.size >= 2
     end
 
     # Is this request using an authenticated proxy?
+    #
+    # @example
+    #   request.using_authenticated_proxy?
+    #
+    # @return [Boolean]
+    # @api public
     def using_authenticated_proxy?
       proxy && proxy.keys.size >= 4
     end
 
-    def include_proxy_headers
-      headers.merge!(proxy[:proxy_headers]) if proxy.key?(:proxy_headers)
-      include_proxy_authorization_header if using_authenticated_proxy?
-    end
-
-    # Compute and add the Proxy-Authorization header
-    def include_proxy_authorization_header
-      headers[Headers::PROXY_AUTHORIZATION] = proxy_authorization_header
-    end
-
-    def proxy_authorization_header
-      digest = encode64("#{proxy[:proxy_username]}:#{proxy[:proxy_password]}")
-      "Basic #{digest}"
-    end
-
-    # Setup tunnel through proxy for SSL request
-    def connect_using_proxy(socket)
-      Request::Writer.new(socket, nil, proxy_connect_headers, proxy_connect_header).connect_through_proxy
-    end
-
     # Compute HTTP request header for direct or proxy request
+    #
+    # @example
+    #   request.headline
+    #
+    # @return [String]
+    # @api public
     def headline
       request_uri =
         if using_proxy? && !uri.https?
@@ -183,34 +247,29 @@ module HTTP
       "#{verb.to_s.upcase} #{request_uri} HTTP/#{version}"
     end
 
-    # Compute HTTP request header SSL proxy connection
-    def proxy_connect_header
-      "CONNECT #{host}:#{port} HTTP/#{version}"
-    end
-
-    # Headers to send with proxy connect request
-    def proxy_connect_headers
-      connect_headers = HTTP::Headers.coerce(
-        Headers::HOST       => headers[Headers::HOST],
-        Headers::USER_AGENT => headers[Headers::USER_AGENT]
-      )
-
-      connect_headers[Headers::PROXY_AUTHORIZATION] = proxy_authorization_header if using_authenticated_proxy?
-      connect_headers.merge!(proxy[:proxy_headers]) if proxy.key?(:proxy_headers)
-      connect_headers
-    end
-
     # Host for tcp socket
+    #
+    # @example
+    #   request.socket_host
+    #
+    # @return [String]
+    # @api public
     def socket_host
       using_proxy? ? proxy[:proxy_address] : host
     end
 
     # Port for tcp socket
+    #
+    # @example
+    #   request.socket_port
+    #
+    # @return [Integer]
+    # @api public
     def socket_port
       using_proxy? ? proxy[:proxy_port] : port
     end
 
-    # Human-readable representation of base request info.
+    # Human-readable representation of base request info
     #
     # @example
     #
@@ -218,23 +277,54 @@ module HTTP
     #     # => #<HTTP::Request/1.1 GET https://example.com>
     #
     # @return [String]
+    # @api public
     def inspect
-      "#<#{self.class}/#{@version} #{verb.to_s.upcase} #{uri}>"
+      format("#<%s/%s %s %s>", self.class, @version, String(verb).upcase, uri)
     end
 
     private
 
+    # Build headers for a redirect request
+    #
+    # Strips the Host header (it will be regenerated), sensitive credentials
+    # on cross-origin redirects, and Content-Type on GET verb changes.
+    #
+    # @param [HTTP::URI] redirect_uri the target URI
+    # @param [Symbol] verb the HTTP verb for the redirected request
+    # @return [HTTP::Headers] headers for the redirect
+    # @api private
+    def redirect_headers(redirect_uri, verb)
+      headers = self.headers.dup
+      headers.delete(Headers::HOST)
+
+      # Strip sensitive headers when redirecting to a different origin
+      # (scheme + host + port) to prevent credential leakage.
+      unless @uri.origin == redirect_uri.origin
+        headers.delete(Headers::AUTHORIZATION)
+        headers.delete(Headers::COOKIE)
+      end
+
+      headers.delete(Headers::CONTENT_TYPE) if verb == :get
+
+      headers
+    end
+
     # @!attribute [r] host
+    #   Host from the URI
     #   @return [String]
+    #   @api private
     def_delegator :@uri, :host
 
-    # @!attribute [r] port
-    #   @return [Fixnum]
+    # Return the port for the request URI
+    # @return [Fixnum]
+    # @api private
     def port
       @uri.port || @uri.default_port
     end
 
-    # @return [String] Default host (with port if needed) header value.
+    # Build default Host header value
+    # @return [String]
+    # @api private
     def default_host_header_value
       value = PORTS[@scheme] == port ? host : "#{host}:#{port}"
 
@@ -243,12 +333,38 @@ module HTTP
       value
     end
 
+    # Parse and normalize the URI, setting scheme
+    # @return [void]
+    # @api private
+    def parse_uri!(uri)
+      raise ArgumentError, "uri is nil" if uri.nil?
+      raise ArgumentError, "uri is empty" if uri.is_a?(String) && uri.empty?
+
+      @uri = @uri_normalizer.call(uri)
+      @scheme = String(@uri.scheme).downcase.to_sym if @uri.scheme
+    end
+
+    # Validate HTTP method and URI scheme
+    # @return [void]
+    # @api private
+    def validate_method_and_scheme!
+      raise(UnsupportedMethodError, "unknown method: #{verb}") unless METHODS.include?(@verb)
+      raise(HTTP::URI::InvalidError, "invalid URI: #{@uri}") unless @scheme
+      raise(UnsupportedSchemeError, "unknown scheme: #{scheme}") unless SCHEMES.include?(@scheme)
+    end
+
+    # Coerce input into a Body object
+    # @return [HTTP::Request::Body]
+    # @api private
     def prepare_body(body)
-      body.is_a?(Request::Body) ? body : Request::Body.new(body)
+      body.is_a?(Body) ? body : Body.new(body)
     end
 
+    # Build headers with default values
+    # @return [HTTP::Headers]
+    # @api private
     def prepare_headers(headers)
-      headers = HTTP::Headers.coerce(headers || {})
+      headers = Headers.coerce(headers || {})
 
       headers[Headers::HOST]       ||= default_host_header_value
       headers[Headers::USER_AGENT] ||= USER_AGENT