http 5.3.1 → 6.0.0

data/lib/http/uri.rb

@@ -1,211 +1,376 @@
 # frozen_string_literal: true
 
-require "addressable/uri"
+require "uri"
 
 module HTTP
+  # HTTP URI with scheme, authority, path, query, and fragment components
+  #
+  # Stores URI components as instance variables. Addressable is only used
+  # when parsing non-ASCII (IRI) strings; ASCII URIs use stdlib's URI.parse.
   class URI
-    extend Forwardable
-
-    def_delegators :@uri, :scheme, :normalized_scheme, :scheme=
-    def_delegators :@uri, :user, :normalized_user, :user=
-    def_delegators :@uri, :password, :normalized_password, :password=
-    def_delegators :@uri, :authority, :normalized_authority, :authority=
-    def_delegators :@uri, :origin, :origin=
-    def_delegators :@uri, :normalized_port, :port=
-    def_delegators :@uri, :path, :normalized_path, :path=
-    def_delegators :@uri, :query, :normalized_query, :query=
-    def_delegators :@uri, :query_values, :query_values=
-    def_delegators :@uri, :request_uri, :request_uri=
-    def_delegators :@uri, :fragment, :normalized_fragment, :fragment=
-    def_delegators :@uri, :omit, :join, :normalize
-
-    # Host, either a domain name or IP address. If the host is an IPv6 address, it will be returned
-    # without brackets surrounding it.
-    #
-    # @return [String] The host of the URI
+    # The URI given was not valid
+    class InvalidError < HTTP::RequestError; end
+
+    # URI scheme (e.g. "http", "https")
+    #
+    # @example
+    #   uri.scheme # => "http"
+    #
+    # @api public
+    # @return [String, nil] The URI scheme
+    attr_reader :scheme
+
+    # User component for authentication
+    #
+    # @example
+    #   uri.user # => "admin"
+    #
+    # @api public
+    # @return [String, nil] The user component
+    attr_reader :user
+
+    # Password component for authentication
+    #
+    # @example
+    #   uri.password # => "secret"
+    #
+    # @api public
+    # @return [String, nil] The password component
+    attr_reader :password
+
+    # Host, either a domain name or IP address
+    #
+    # @example
+    #   uri.host # => "example.com"
+    #
+    # @api public
+    # @return [String, nil] The host of the URI
     attr_reader :host
 
-    # Normalized host, either a domain name or IP address. If the host is an IPv6 address, it will
-    # be returned without brackets surrounding it.
+    # Normalized host
+    #
+    # @example
+    #   uri.normalized_host # => "example.com"
     #
-    # @return [String] The normalized host of the URI
+    # @api public
+    # @return [String, nil] The normalized host of the URI
     attr_reader :normalized_host
 
+    # URI path component
+    #
+    # @example
+    #   uri.path # => "/foo"
+    #
+    # @api public
+    # @return [String] The path component
+    attr_accessor :path
+
+    # URI query string
+    #
+    # @example
+    #   uri.query # => "q=1"
+    #
+    # @api public
+    # @return [String, nil] The query component
+    attr_accessor :query
+
+    # URI fragment
+    #
+    # @example
+    #   uri.fragment # => "section1"
+    #
+    # @api public
+    # @return [String, nil] The fragment component
+    attr_reader :fragment
+
+    # HTTP scheme string
     # @private
     HTTP_SCHEME = "http"
 
+    # HTTPS scheme string
     # @private
     HTTPS_SCHEME = "https"
 
+    # Pattern matching characters requiring percent-encoding
     # @private
-    PERCENT_ENCODE = /[^\x21-\x7E]+/.freeze
+    PERCENT_ENCODE = /[^\x21-\x7E]+/
 
+    # Default ports for supported URI schemes
     # @private
-    NORMALIZER = lambda do |uri|
-      uri = HTTP::URI.parse uri
-
-      HTTP::URI.new(
-        :scheme    => uri.normalized_scheme,
-        :authority => uri.normalized_authority,
-        :path      => uri.path.empty? ? "/" : percent_encode(Addressable::URI.normalize_path(uri.path)),
-        :query     => percent_encode(uri.query),
-        :fragment  => uri.normalized_fragment
-      )
-    end
+    DEFAULT_PORTS = {
+      "http"  => 80,
+      "https" => 443,
+      "ws"    => 80,
+      "wss"   => 443
+    }.freeze
 
-    # Parse the given URI string, returning an HTTP::URI object
+    # Pattern for characters that stdlib's URI.parse silently modifies
+    # @private
+    NEEDS_ADDRESSABLE = /[^\x20-\x7E]/
+
+    # Creates an HTTP::URI instance from the given keyword arguments
+    #
+    # @example
+    #   HTTP::URI.new(scheme: "http", host: "example.com")
     #
-    # @param [HTTP::URI, String, #to_str] uri to parse
+    # @param [String, nil] scheme URI scheme
+    # @param [String, nil] user for basic authentication
+    # @param [String, nil] password for basic authentication
+    # @param [String, nil] host name component (IPv6 addresses must be bracketed)
+    # @param [Integer, nil] port network port to connect to
+    # @param [String, nil] path component to request
+    # @param [String, nil] query component distinct from path
+    # @param [String, nil] fragment component at the end of the URI
     #
+    # @api public
     # @return [HTTP::URI] new URI instance
-    def self.parse(uri)
-      return uri if uri.is_a?(self)
-
-      new(Addressable::URI.parse(uri))
+    def initialize(scheme: nil, user: nil, password: nil, host: nil,
+                   port: nil, path: nil, query: nil, fragment: nil)
+      @scheme   = scheme
+      @user     = user
+      @password = password
+      @raw_host = host
+      @host     = process_ipv6_brackets(host)
+      @normalized_host = normalize_host(@host)
+      @port     = port
+      @path     = path || ""
+      @query    = query
+      @fragment = fragment
     end
 
-    # Encodes key/value pairs as application/x-www-form-urlencoded
+    # Are these URI objects equal after normalization
+    #
+    # @example
+    #   HTTP::URI.parse("http://example.com") == HTTP::URI.parse("http://example.com")
     #
-    # @param [#to_hash, #to_ary] form_values to encode
-    # @param [TrueClass, FalseClass] sort should key/value pairs be sorted first?
+    # @param [Object] other URI to compare this one with
     #
-    # @return [String] encoded value
-    def self.form_encode(form_values, sort = false)
-      Addressable::URI.form_encode(form_values, sort)
+    # @api public
+    # @return [TrueClass, FalseClass] are the URIs equivalent (after normalization)?
+    def ==(other)
+      other.is_a?(URI) && String(normalize).eql?(String(other.normalize))
     end
 
-    # Percent-encode all characters matching a regular expression.
+    # Are these URI objects equal without normalization
     #
-    # @param [String] string raw string
+    # @example
+    #   uri = HTTP::URI.parse("http://example.com")
+    #   uri.eql?(HTTP::URI.parse("http://example.com"))
     #
-    # @return [String] encoded value
+    # @param [Object] other URI to compare this one with
     #
-    # @private
-    def self.percent_encode(string)
-      string&.gsub(PERCENT_ENCODE) do |substr|
-        substr.encode(Encoding::UTF_8).bytes.map { |c| format("%%%02X", c) }.join
-      end
+    # @api public
+    # @return [TrueClass, FalseClass] are the URIs equivalent?
+    def eql?(other)
+      other.is_a?(URI) && String(self).eql?(String(other))
     end
 
-    # Creates an HTTP::URI instance from the given options
+    # Hash value based off the normalized form of a URI
     #
-    # @param [Hash, Addressable::URI] options_or_uri
+    # @example
+    #   HTTP::URI.parse("http://example.com").hash
     #
-    # @option options_or_uri [String, #to_str] :scheme URI scheme
-    # @option options_or_uri [String, #to_str] :user for basic authentication
-    # @option options_or_uri [String, #to_str] :password for basic authentication
-    # @option options_or_uri [String, #to_str] :host name component
-    # @option options_or_uri [String, #to_str] :port network port to connect to
-    # @option options_or_uri [String, #to_str] :path component to request
-    # @option options_or_uri [String, #to_str] :query component distinct from path
-    # @option options_or_uri [String, #to_str] :fragment component at the end of the URI
+    # @api public
+    # @return [Integer] A hash of the URI
+    def hash
+      @hash ||= [self.class, String(self)].hash
+    end
+
+    # Sets the host component for the URI
     #
-    # @return [HTTP::URI] new URI instance
-    def initialize(options_or_uri = {})
-      case options_or_uri
-      when Hash
-        @uri = Addressable::URI.new(options_or_uri)
-      when Addressable::URI
-        @uri = options_or_uri
-      else
-        raise TypeError, "expected Hash for options, got #{options_or_uri.class}"
-      end
+    # @example
+    #   uri = HTTP::URI.parse("http://example.com")
+    #   uri.host = "other.com"
+    #
+    # @param [String, #to_str] new_host The new host component
+    # @api public
+    # @return [void]
+    def host=(new_host)
+      @raw_host = process_ipv6_brackets(new_host, brackets: true)
+      @host = process_ipv6_brackets(@raw_host)
+      @normalized_host = normalize_host(@host)
+    end
 
-      @host = process_ipv6_brackets(@uri.host)
-      @normalized_host = process_ipv6_brackets(@uri.normalized_host)
+    # Port number, either as specified or the default
+    #
+    # @example
+    #   HTTP::URI.parse("http://example.com").port
+    #
+    # @api public
+    # @return [Integer, nil] port number
+    def port
+      @port || default_port
     end
 
-    # Are these URI objects equal? Normalizes both URIs prior to comparison
+    # Default port for the URI scheme
     #
-    # @param [Object] other URI to compare this one with
+    # @example
+    #   HTTP::URI.parse("http://example.com").default_port # => 80
     #
-    # @return [TrueClass, FalseClass] are the URIs equivalent (after normalization)?
-    def ==(other)
-      other.is_a?(URI) && normalize.to_s == other.normalize.to_s
+    # @api public
+    # @return [Integer, nil] default port or nil for unknown schemes
+    def default_port
+      DEFAULT_PORTS[@scheme&.downcase]
     end
 
-    # Are these URI objects equal? Does NOT normalizes both URIs prior to comparison
+    # The origin (scheme + host + port) per RFC 6454
     #
-    # @param [Object] other URI to compare this one with
+    # @example
+    #   HTTP::URI.parse("http://example.com").origin # => "http://example.com"
     #
-    # @return [TrueClass, FalseClass] are the URIs equivalent?
-    def eql?(other)
-      other.is_a?(URI) && to_s == other.to_s
+    # @api public
+    # @return [String] origin of the URI
+    def origin
+      port_suffix = ":#{port}" unless port.eql?(default_port)
+      "#{String(@scheme).downcase}://#{String(@raw_host).downcase}#{port_suffix}"
     end
 
-    # Hash value based off the normalized form of a URI
+    # The path and query for use in an HTTP request line
     #
-    # @return [Integer] A hash of the URI
-    def hash
-      @hash ||= to_s.hash * -1
+    # @example
+    #   HTTP::URI.parse("http://example.com/path?q=1").request_uri # => "/path?q=1"
+    #
+    # @api public
+    # @return [String] request URI string
+    def request_uri
+      "#{'/' if @path.empty?}#{@path}#{"?#{@query}" if @query}"
     end
 
-    # Sets the host component for the URI.
+    # Returns a new URI with the specified components removed
     #
-    # @param [String, #to_str] new_host The new host component.
-    # @return [void]
-    def host=(new_host)
-      @uri.host = process_ipv6_brackets(new_host, :brackets => true)
+    # @example
+    #   HTTP::URI.parse("http://example.com#frag").omit(:fragment)
+    #
+    # @param components [Symbol] URI components to remove
+    # @api public
+    # @return [HTTP::URI] new URI without the specified components
+    def omit(*components)
+      self.class.new(
+        **{ scheme: @scheme, user: @user, password: @password, host: @raw_host,
+            port: @port, path: @path, query: @query, fragment: @fragment }.except(*components)
+      )
+    end
 
-      @host = process_ipv6_brackets(@uri.host)
-      @normalized_host = process_ipv6_brackets(@uri.normalized_host)
+    # Resolves another URI against this one per RFC 3986
+    #
+    # @example
+    #   HTTP::URI.parse("http://example.com/foo/").join("bar")
+    #
+    # @param [String, URI] other the URI to resolve
+    #
+    # @api public
+    # @return [HTTP::URI] resolved URI
+    def join(other)
+      base = self.class.percent_encode(String(self))
+      ref  = self.class.percent_encode(String(other))
+      self.class.parse(::URI.join(base, ref))
     end
 
-    # Port number, either as specified or the default if unspecified
+    # Returns a normalized copy of the URI
     #
-    # @return [Integer] port number
-    def port
-      @uri.port || @uri.default_port
+    # Lowercases scheme and host, strips default port. Used by {#==}
+    # to compare URIs for equivalence.
+    #
+    # @example
+    #   HTTP::URI.parse("HTTP://EXAMPLE.COM:80").normalize
+    #
+    # @api public
+    # @return [HTTP::URI] normalized URI
+    def normalize
+      self.class.new(
+        scheme:   @scheme&.downcase,
+        user:     @user,
+        password: @password,
+        host:     @raw_host&.downcase,
+        port:     (@port unless port.eql?(default_port)),
+        path:     @path.empty? && @raw_host ? "/" : @path,
+        query:    @query,
+        fragment: @fragment
+      )
     end
 
+    # Checks whether the URI scheme is HTTP
+    #
+    # @example
+    #   HTTP::URI.parse("http://example.com").http?
+    #
+    # @api public
     # @return [True] if URI is HTTP
     # @return [False] otherwise
     def http?
-      HTTP_SCHEME == scheme
+      HTTP_SCHEME.eql?(@scheme)
     end
 
+    # Checks whether the URI scheme is HTTPS
+    #
+    # @example
+    #   HTTP::URI.parse("https://example.com").https?
+    #
+    # @api public
     # @return [True] if URI is HTTPS
     # @return [False] otherwise
     def https?
-      HTTPS_SCHEME == scheme
+      HTTPS_SCHEME.eql?(@scheme)
     end
 
-    # @return [Object] duplicated URI
+    # Duplicates the URI object
+    #
+    # @example
+    #   HTTP::URI.parse("http://example.com").dup
+    #
+    # @api public
+    # @return [HTTP::URI] duplicated URI
     def dup
-      self.class.new @uri.dup
+      self.class.new(
+        scheme: @scheme, user: @user, password: @password, host: @raw_host,
+        port: @port, path: @path, query: @query, fragment: @fragment
+      )
     end
 
     # Convert an HTTP::URI to a String
     #
+    # @example
+    #   HTTP::URI.parse("http://example.com").to_s
+    #
+    # @api public
     # @return [String] URI serialized as a String
     def to_s
-      @uri.to_s
+      str = +""
+      str << "#{@scheme}:" if @scheme
+      str << authority_string if @raw_host
+      str << @path
+      str << "?#{@query}" if @query
+      str << "##{@fragment}" if @fragment
+      str
     end
     alias to_str to_s
 
+    # Returns human-readable representation of URI
+    #
+    # @example
+    #   HTTP::URI.parse("http://example.com").inspect
+    #
+    # @api public
     # @return [String] human-readable representation of URI
     def inspect
-      format("#<%s:0x%014x URI:%s>", self.class.name, object_id << 1, to_s)
+      format("#<%s:0x%014x URI:%s>", self.class, object_id << 1, self)
     end
 
-    private
-
-    # Process a URI host, adding or removing surrounding brackets if the host is an IPv6 address.
+    # Pattern matching interface
     #
-    # @param [Boolean] brackets When true, brackets will be added to IPv6 addresses if missing. When
-    #   false, they will be removed if present.
+    # @example
+    #   uri.deconstruct_keys(%i[scheme host])
     #
-    # @return [String] Host with IPv6 address brackets added or removed
-    def process_ipv6_brackets(raw_host, brackets: false)
-      ip = IPAddr.new(raw_host)
-
-      if ip.ipv6?
-        brackets ? "[#{ip}]" : ip.to_s
-      else
-        raw_host
-      end
-    rescue IPAddr::Error
-      raw_host
+    # @param keys [Array<Symbol>, nil] keys to extract, or nil for all
+    # @return [Hash{Symbol => Object}]
+    # @api public
+    def deconstruct_keys(keys)
+      hash = { scheme: @scheme, host: @host, port: port, path: @path,
+               query: @query, fragment: @fragment, user: @user, password: @password }
+      keys ? hash.slice(*keys) : hash
     end
   end
 end
+
+require "http/uri/parsing"
+require "http/uri/normalizer"

data/lib/http/version.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
 module HTTP
-  VERSION = "5.3.1"
+  # Current library version
+  VERSION = "6.0.0"
 end

data/lib/http.rb

@@ -5,8 +5,8 @@ require "http/timeout/null"
 require "http/timeout/per_operation"
 require "http/timeout/global"
 require "http/chainable"
+require "http/session"
 require "http/client"
-require "http/retriable/client"
 require "http/connection"
 require "http/options"
 require "http/feature"
@@ -21,7 +21,16 @@ module HTTP
   extend Chainable
 
   class << self
-    # HTTP[:accept => 'text/html'].get(...)
+    # Set default headers and return a chainable session
+    #
+    # @example
+    #   HTTP[:accept => "text/html"].get("https://example.com")
+    #
+    # @param headers [Hash] headers to set
+    #
+    # @return [HTTP::Session]
+    #
+    # @api public
     alias [] headers
   end
 end

data/sig/deps.rbs

@@ -0,0 +1,122 @@
+# Overrides for stdlib RBS signatures
+
+class ::StringIO
+  # Override: Ruby's StringIO#read accepts nil outbuf
+  def read: (?int? length, ?string? buf) -> String?
+end
+
+class ::File
+  # Override: Ruby's File.new accepts keyword args like binmode:
+  def initialize: (string | _ToPath | int file_name, ?string | int mode, ?int perm, **untyped) -> void
+end
+
+class ::Pathname
+  # Override: Ruby's Pathname#open accepts keyword args like binmode:
+  def open: (?string | int mode, ?int perm, **untyped) -> ::File
+          | [T] (?string | int mode, ?int perm, **untyped) { (::File) -> T } -> T
+end
+
+# Stubs for external dependencies without RBS definitions
+
+module Addressable
+  class URI
+    class InvalidURIError < StandardError
+    end
+
+    def self.parse: (untyped) -> Addressable::URI
+    def self.form_encode: (untyped, ?bool) -> String
+    def self.normalize_path: (untyped) -> String
+
+    def initialize: (?untyped) -> void
+    def scheme: () -> String?
+    def scheme=: (untyped) -> untyped
+    def normalized_scheme: () -> String?
+    def authority: () -> String?
+    def normalized_authority: () -> String?
+    def user: () -> String?
+    def user=: (untyped) -> untyped
+    def password: () -> String?
+    def password=: (untyped) -> untyped
+    def host: () -> String?
+    def host=: (untyped) -> untyped
+    def normalized_host: () -> String?
+    def port: () -> Integer?
+    def port=: (untyped) -> untyped
+    def normalized_port: () -> Integer?
+    def path: () -> String
+    def path=: (untyped) -> untyped
+    def normalized_path: () -> String
+    def query: () -> String?
+    def query=: (untyped) -> untyped
+    def query_values: (?untyped?) -> untyped
+    def query_values=: (untyped) -> untyped
+    def normalized_query: () -> String?
+    def request_uri: () -> String
+    def request_uri=: (untyped) -> untyped
+    def fragment: () -> String?
+    def normalized_fragment: () -> String?
+    def fragment=: (untyped) -> untyped
+    def omit: (*Symbol) -> Addressable::URI
+    def join: (untyped) -> Addressable::URI
+    def normalize: () -> Addressable::URI
+    def origin: () -> String
+    def default_port: () -> Integer?
+    def to_s: () -> String
+    def ==: (untyped) -> bool
+    def eql?: (untyped) -> bool
+    def hash: () -> Integer
+    def dup: () -> Addressable::URI
+  end
+end
+
+# Override: stdlib zlib RBS incorrectly marks level/strategy as required
+module Zlib
+  class GzipWriter
+    private
+
+    def initialize: (untyped io, ?Integer? level, ?Integer? strategy, **untyped opts) -> void
+  end
+end
+
+module LLHttp
+  class Error < StandardError
+  end
+
+  class Parser
+    def initialize: (untyped, ?type: Symbol) -> void
+    def reset: () -> void
+    def <<: (String) -> void
+    def status_code: () -> Integer
+    def http_major: () -> Integer
+    def http_minor: () -> Integer
+  end
+
+  class Delegate
+    def initialize: () -> void
+  end
+end
+
+# Supplement: Numeric#to_i and #to_f are not in the stdlib RBS
+class Numeric
+  def to_i: () -> Integer
+  def to_f: () -> Float
+end
+
+module IO::WaitReadable
+end
+
+module IO::WaitWritable
+end
+
+class IO
+  # Missing from rbs core (available since Ruby 3.2)
+  class TimeoutError < IOError
+  end
+
+  class EAGAINWaitReadable < Errno::EAGAIN
+    include IO::WaitReadable
+  end
+
+  def wait_readable: (?Numeric?) -> (IO | true | nil)
+  def wait_writable: (?Numeric?) -> (IO | true | nil)
+end