bundler 2.2.27 → 2.6.1

data/lib/bundler/vendor/uri/lib/uri/common.rb

@@ -3,7 +3,6 @@
 # = uri/common.rb
 #
 # Author:: Akira Yamada <akira@ruby-lang.org>
-# Revision:: $Id$
 # License::
 #   You can redistribute it and/or modify it under the same term as Ruby.
 #
@@ -14,19 +13,46 @@ require_relative "rfc2396_parser"
 require_relative "rfc3986_parser"
 
 module Bundler::URI
-  REGEXP = RFC2396_REGEXP
-  Parser = RFC2396_Parser
+  RFC2396_PARSER = RFC2396_Parser.new
+  Ractor.make_shareable(RFC2396_PARSER) if defined?(Ractor)
+
   RFC3986_PARSER = RFC3986_Parser.new
+  Ractor.make_shareable(RFC3986_PARSER) if defined?(Ractor)
+
+  DEFAULT_PARSER = RFC3986_PARSER
+  Ractor.make_shareable(DEFAULT_PARSER) if defined?(Ractor)
+
+  def self.parser=(parser = RFC3986_PARSER)
+    remove_const(:Parser) if defined?(::Bundler::URI::Parser)
+    const_set("Parser", parser.class)
+
+    remove_const(:REGEXP) if defined?(::Bundler::URI::REGEXP)
+    remove_const(:PATTERN) if defined?(::Bundler::URI::PATTERN)
+    if Parser == RFC2396_Parser
+      const_set("REGEXP", Bundler::URI::RFC2396_REGEXP)
+      const_set("PATTERN", Bundler::URI::RFC2396_REGEXP::PATTERN)
+    end
 
-  # Bundler::URI::Parser.new
-  DEFAULT_PARSER = Parser.new
-  DEFAULT_PARSER.pattern.each_pair do |sym, str|
-    unless REGEXP::PATTERN.const_defined?(sym)
-      REGEXP::PATTERN.const_set(sym, str)
+    Parser.new.regexp.each_pair do |sym, str|
+      remove_const(sym) if const_defined?(sym, false)
+      const_set(sym, str)
     end
   end
-  DEFAULT_PARSER.regexp.each_pair do |sym, str|
-    const_set(sym, str)
+  self.parser = RFC3986_PARSER
+
+  def self.const_missing(const)
+    if const == :REGEXP
+      warn "Bundler::URI::REGEXP is obsolete. Use Bundler::URI::RFC2396_REGEXP explicitly.", uplevel: 1 if $VERBOSE
+      Bundler::URI::RFC2396_REGEXP
+    elsif value = RFC2396_PARSER.regexp[const]
+      warn "Bundler::URI::#{const} is obsolete. Use RFC2396_PARSER.regexp[#{const.inspect}] explicitly.", uplevel: 1 if $VERBOSE
+      value
+    elsif value = RFC2396_Parser.const_get(const)
+      warn "Bundler::URI::#{const} is obsolete. Use RFC2396_Parser::#{const} explicitly.", uplevel: 1 if $VERBOSE
+      value
+    else
+      super
+    end
   end
 
   module Util # :nodoc:
@@ -61,88 +87,72 @@ module Bundler::URI
     module_function :make_components_hash
   end
 
-  # Module for escaping unsafe characters with codes.
-  module Escape
-    #
-    # == Synopsis
-    #
-    #   Bundler::URI.escape(str [, unsafe])
-    #
-    # == Args
-    #
-    # +str+::
-    #   String to replaces in.
-    # +unsafe+::
-    #   Regexp that matches all symbols that must be replaced with codes.
-    #   By default uses <tt>UNSAFE</tt>.
-    #   When this argument is a String, it represents a character set.
-    #
-    # == Description
-    #
-    # Escapes the string, replacing all unsafe characters with codes.
-    #
-    # This method is obsolete and should not be used. Instead, use
-    # CGI.escape, Bundler::URI.encode_www_form or Bundler::URI.encode_www_form_component
-    # depending on your specific use case.
-    #
-    # == Usage
-    #
-    #   require 'bundler/vendor/uri/lib/uri'
-    #
-    #   enc_uri = Bundler::URI.escape("http://example.com/?a=\11\15")
-    #   # => "http://example.com/?a=%09%0D"
-    #
-    #   Bundler::URI.unescape(enc_uri)
-    #   # => "http://example.com/?a=\t\r"
-    #
-    #   Bundler::URI.escape("@?@!", "!?")
-    #   # => "@%3F@%21"
-    #
-    def escape(*arg)
-      warn "Bundler::URI.escape is obsolete", uplevel: 1
-      DEFAULT_PARSER.escape(*arg)
-    end
-    alias encode escape
-    #
-    # == Synopsis
-    #
-    #   Bundler::URI.unescape(str)
-    #
-    # == Args
-    #
-    # +str+::
-    #   String to unescape.
-    #
-    # == Description
-    #
-    # This method is obsolete and should not be used. Instead, use
-    # CGI.unescape, Bundler::URI.decode_www_form or Bundler::URI.decode_www_form_component
-    # depending on your specific use case.
-    #
-    # == Usage
-    #
-    #   require 'bundler/vendor/uri/lib/uri'
-    #
-    #   enc_uri = Bundler::URI.escape("http://example.com/?a=\11\15")
-    #   # => "http://example.com/?a=%09%0D"
-    #
-    #   Bundler::URI.unescape(enc_uri)
-    #   # => "http://example.com/?a=\t\r"
-    #
-    def unescape(*arg)
-      warn "Bundler::URI.unescape is obsolete", uplevel: 1
-      DEFAULT_PARSER.unescape(*arg)
-    end
-    alias decode unescape
-  end # module Escape
+  module Schemes
+  end
+  private_constant :Schemes
 
-  extend Escape
-  include REGEXP
+  # Registers the given +klass+ as the class to be instantiated
+  # when parsing a \Bundler::URI with the given +scheme+:
+  #
+  #   Bundler::URI.register_scheme('MS_SEARCH', Bundler::URI::Generic) # => Bundler::URI::Generic
+  #   Bundler::URI.scheme_list['MS_SEARCH']                   # => Bundler::URI::Generic
+  #
+  # Note that after calling String#upcase on +scheme+, it must be a valid
+  # constant name.
+  def self.register_scheme(scheme, klass)
+    Schemes.const_set(scheme.to_s.upcase, klass)
+  end
 
-  @@schemes = {}
-  # Returns a Hash of the defined schemes.
+  # Returns a hash of the defined schemes:
+  #
+  #   Bundler::URI.scheme_list
+  #   # =>
+  #   {"MAILTO"=>Bundler::URI::MailTo,
+  #    "LDAPS"=>Bundler::URI::LDAPS,
+  #    "WS"=>Bundler::URI::WS,
+  #    "HTTP"=>Bundler::URI::HTTP,
+  #    "HTTPS"=>Bundler::URI::HTTPS,
+  #    "LDAP"=>Bundler::URI::LDAP,
+  #    "FILE"=>Bundler::URI::File,
+  #    "FTP"=>Bundler::URI::FTP}
+  #
+  # Related: Bundler::URI.register_scheme.
   def self.scheme_list
-    @@schemes
+    Schemes.constants.map { |name|
+      [name.to_s.upcase, Schemes.const_get(name)]
+    }.to_h
+  end
+
+  INITIAL_SCHEMES = scheme_list
+  private_constant :INITIAL_SCHEMES
+  Ractor.make_shareable(INITIAL_SCHEMES) if defined?(Ractor)
+
+  # Returns a new object constructed from the given +scheme+, +arguments+,
+  # and +default+:
+  #
+  # - The new object is an instance of <tt>Bundler::URI.scheme_list[scheme.upcase]</tt>.
+  # - The object is initialized by calling the class initializer
+  #   using +scheme+ and +arguments+.
+  #   See Bundler::URI::Generic.new.
+  #
+  # Examples:
+  #
+  #   values = ['john.doe', 'www.example.com', '123', nil, '/forum/questions/', nil, 'tag=networking&order=newest', 'top']
+  #   Bundler::URI.for('https', *values)
+  #   # => #<Bundler::URI::HTTPS https://john.doe@www.example.com:123/forum/questions/?tag=networking&order=newest#top>
+  #   Bundler::URI.for('foo', *values, default: Bundler::URI::HTTP)
+  #   # => #<Bundler::URI::HTTP foo://john.doe@www.example.com:123/forum/questions/?tag=networking&order=newest#top>
+  #
+  def self.for(scheme, *arguments, default: Generic)
+    const_name = scheme.to_s.upcase
+
+    uri_class = INITIAL_SCHEMES[const_name]
+    uri_class ||= if /\A[A-Z]\w*\z/.match?(const_name) && Schemes.const_defined?(const_name, false)
+      Schemes.const_get(const_name, false)
+    end
+    uri_class ||= default
+
+    return uri_class.new(scheme, *arguments)
   end
 
   #
@@ -162,95 +172,49 @@ module Bundler::URI
   #
   class BadURIError < Error; end
 
-  #
-  # == Synopsis
-  #
-  #   Bundler::URI::split(uri)
-  #
-  # == Args
-  #
-  # +uri+::
-  #   String with Bundler::URI.
-  #
-  # == Description
-  #
-  # Splits the string on following parts and returns array with result:
-  #
-  # * Scheme
-  # * Userinfo
-  # * Host
-  # * Port
-  # * Registry
-  # * Path
-  # * Opaque
-  # * Query
-  # * Fragment
-  #
-  # == Usage
-  #
-  #   require 'bundler/vendor/uri/lib/uri'
-  #
-  #   Bundler::URI.split("http://www.ruby-lang.org/")
-  #   # => ["http", nil, "www.ruby-lang.org", nil, nil, "/", nil, nil, nil]
+  # Returns a 9-element array representing the parts of the \Bundler::URI
+  # formed from the string +uri+;
+  # each array element is a string or +nil+:
+  #
+  #   names = %w[scheme userinfo host port registry path opaque query fragment]
+  #   values = Bundler::URI.split('https://john.doe@www.example.com:123/forum/questions/?tag=networking&order=newest#top')
+  #   names.zip(values)
+  #   # =>
+  #   [["scheme", "https"],
+  #    ["userinfo", "john.doe"],
+  #    ["host", "www.example.com"],
+  #    ["port", "123"],
+  #    ["registry", nil],
+  #    ["path", "/forum/questions/"],
+  #    ["opaque", nil],
+  #    ["query", "tag=networking&order=newest"],
+  #    ["fragment", "top"]]
   #
   def self.split(uri)
-    RFC3986_PARSER.split(uri)
+    DEFAULT_PARSER.split(uri)
   end
 
+  # Returns a new \Bundler::URI object constructed from the given string +uri+:
   #
-  # == Synopsis
-  #
-  #   Bundler::URI::parse(uri_str)
+  #   Bundler::URI.parse('https://john.doe@www.example.com:123/forum/questions/?tag=networking&order=newest#top')
+  #   # => #<Bundler::URI::HTTPS https://john.doe@www.example.com:123/forum/questions/?tag=networking&order=newest#top>
+  #   Bundler::URI.parse('http://john.doe@www.example.com:123/forum/questions/?tag=networking&order=newest#top')
+  #   # => #<Bundler::URI::HTTP http://john.doe@www.example.com:123/forum/questions/?tag=networking&order=newest#top>
   #
-  # == Args
-  #
-  # +uri_str+::
-  #   String with Bundler::URI.
-  #
-  # == Description
-  #
-  # Creates one of the Bundler::URI's subclasses instance from the string.
-  #
-  # == Raises
-  #
-  # Bundler::URI::InvalidURIError::
-  #   Raised if Bundler::URI given is not a correct one.
-  #
-  # == Usage
-  #
-  #   require 'bundler/vendor/uri/lib/uri'
-  #
-  #   uri = Bundler::URI.parse("http://www.ruby-lang.org/")
-  #   # => #<Bundler::URI::HTTP http://www.ruby-lang.org/>
-  #   uri.scheme
-  #   # => "http"
-  #   uri.host
-  #   # => "www.ruby-lang.org"
-  #
-  # It's recommended to first ::escape the provided +uri_str+ if there are any
-  # invalid Bundler::URI characters.
+  # It's recommended to first ::escape string +uri+
+  # if it may contain invalid Bundler::URI characters.
   #
   def self.parse(uri)
-    RFC3986_PARSER.parse(uri)
+    DEFAULT_PARSER.parse(uri)
   end
 
+  # Merges the given Bundler::URI strings +str+
+  # per {RFC 2396}[https://www.rfc-editor.org/rfc/rfc2396.html].
   #
-  # == Synopsis
-  #
-  #   Bundler::URI::join(str[, str, ...])
-  #
-  # == Args
-  #
-  # +str+::
-  #   String(s) to work with, will be converted to RFC3986 URIs before merging.
-  #
-  # == Description
-  #
-  # Joins URIs.
-  #
-  # == Usage
+  # Each string in +str+ is converted to an
+  # {RFC3986 Bundler::URI}[https://www.rfc-editor.org/rfc/rfc3986.html] before being merged.
   #
-  #   require 'bundler/vendor/uri/lib/uri'
+  # Examples:
   #
   #   Bundler::URI.join("http://example.com/","main.rbx")
   #   # => #<Bundler::URI::HTTP http://example.com/main.rbx>
@@ -268,7 +232,7 @@ module Bundler::URI
   #   # => #<Bundler::URI::HTTP http://example.com/foo/bar>
   #
   def self.join(*str)
-    RFC3986_PARSER.join(*str)
+    DEFAULT_PARSER.join(*str)
   end
 
   #
@@ -295,7 +259,7 @@ module Bundler::URI
   #   Bundler::URI.extract("text here http://foo.example.org/bla and here mailto:test@example.com and here also.")
   #   # => ["http://foo.example.com/bla", "mailto:test@example.com"]
   #
-  def self.extract(str, schemes = nil, &block)
+  def self.extract(str, schemes = nil, &block) # :nodoc:
     warn "Bundler::URI.extract is obsolete", uplevel: 1 if $VERBOSE
     DEFAULT_PARSER.extract(str, schemes, &block)
   end
@@ -315,7 +279,7 @@ module Bundler::URI
   #
   # Returns a Regexp object which matches to Bundler::URI-like strings.
   # The Regexp object returned by this method includes arbitrary
-  # number of capture group (parentheses).  Never rely on it's number.
+  # number of capture group (parentheses).  Never rely on its number.
   #
   # == Usage
   #
@@ -332,7 +296,7 @@ module Bundler::URI
   #     p $&
   #   end
   #
-  def self.regexp(schemes = nil)
+  def self.regexp(schemes = nil)# :nodoc:
     warn "Bundler::URI.regexp is obsolete", uplevel: 1 if $VERBOSE
     DEFAULT_PARSER.make_regexp(schemes)
   end
@@ -341,6 +305,7 @@ module Bundler::URI
   256.times do |i|
     TBLENCWWWCOMP_[-i.chr] = -('%%%02X' % i)
   end
+  TBLENCURICOMP_ = TBLENCWWWCOMP_.dup.freeze
   TBLENCWWWCOMP_[' '] = '+'
   TBLENCWWWCOMP_.freeze
   TBLDECWWWCOMP_ = {} # :nodoc:
@@ -354,18 +319,91 @@ module Bundler::URI
   TBLDECWWWCOMP_['+'] = ' '
   TBLDECWWWCOMP_.freeze
 
-  # Encodes given +str+ to URL-encoded form data.
+  # Returns a URL-encoded string derived from the given string +str+.
   #
-  # This method doesn't convert *, -, ., 0-9, A-Z, _, a-z, but does convert SP
-  # (ASCII space) to + and converts others to %XX.
+  # The returned string:
   #
-  # If +enc+ is given, convert +str+ to the encoding before percent encoding.
+  # - Preserves:
   #
-  # This is an implementation of
-  # http://www.w3.org/TR/2013/CR-html5-20130806/forms.html#url-encoded-form-data.
+  #   - Characters <tt>'*'</tt>, <tt>'.'</tt>, <tt>'-'</tt>, and <tt>'_'</tt>.
+  #   - Character in ranges <tt>'a'..'z'</tt>, <tt>'A'..'Z'</tt>,
+  #     and <tt>'0'..'9'</tt>.
   #
-  # See Bundler::URI.decode_www_form_component, Bundler::URI.encode_www_form.
+  #   Example:
+  #
+  #     Bundler::URI.encode_www_form_component('*.-_azAZ09')
+  #     # => "*.-_azAZ09"
+  #
+  # - Converts:
+  #
+  #   - Character <tt>' '</tt> to character <tt>'+'</tt>.
+  #   - Any other character to "percent notation";
+  #     the percent notation for character <i>c</i> is <tt>'%%%X' % c.ord</tt>.
+  #
+  #   Example:
+  #
+  #     Bundler::URI.encode_www_form_component('Here are some punctuation characters: ,;?:')
+  #     # => "Here+are+some+punctuation+characters%3A+%2C%3B%3F%3A"
+  #
+  # Encoding:
+  #
+  # - If +str+ has encoding Encoding::ASCII_8BIT, argument +enc+ is ignored.
+  # - Otherwise +str+ is converted first to Encoding::UTF_8
+  #   (with suitable character replacements),
+  #   and then to encoding +enc+.
+  #
+  # In either case, the returned string has forced encoding Encoding::US_ASCII.
+  #
+  # Related: Bundler::URI.encode_uri_component (encodes <tt>' '</tt> as <tt>'%20'</tt>).
   def self.encode_www_form_component(str, enc=nil)
+    _encode_uri_component(/[^*\-.0-9A-Z_a-z]/, TBLENCWWWCOMP_, str, enc)
+  end
+
+  # Returns a string decoded from the given \URL-encoded string +str+.
+  #
+  # The given string is first encoded as Encoding::ASCII-8BIT (using String#b),
+  # then decoded (as below), and finally force-encoded to the given encoding +enc+.
+  #
+  # The returned string:
+  #
+  # - Preserves:
+  #
+  #   - Characters <tt>'*'</tt>, <tt>'.'</tt>, <tt>'-'</tt>, and <tt>'_'</tt>.
+  #   - Character in ranges <tt>'a'..'z'</tt>, <tt>'A'..'Z'</tt>,
+  #     and <tt>'0'..'9'</tt>.
+  #
+  #   Example:
+  #
+  #     Bundler::URI.decode_www_form_component('*.-_azAZ09')
+  #     # => "*.-_azAZ09"
+  #
+  # - Converts:
+  #
+  #   - Character <tt>'+'</tt> to character <tt>' '</tt>.
+  #   - Each "percent notation" to an ASCII character.
+  #
+  #   Example:
+  #
+  #     Bundler::URI.decode_www_form_component('Here+are+some+punctuation+characters%3A+%2C%3B%3F%3A')
+  #     # => "Here are some punctuation characters: ,;?:"
+  #
+  # Related: Bundler::URI.decode_uri_component (preserves <tt>'+'</tt>).
+  def self.decode_www_form_component(str, enc=Encoding::UTF_8)
+    _decode_uri_component(/\+|%\h\h/, str, enc)
+  end
+
+  # Like Bundler::URI.encode_www_form_component, except that <tt>' '</tt> (space)
+  # is encoded as <tt>'%20'</tt> (instead of <tt>'+'</tt>).
+  def self.encode_uri_component(str, enc=nil)
+    _encode_uri_component(/[^*\-.0-9A-Z_a-z]/, TBLENCURICOMP_, str, enc)
+  end
+
+  # Like Bundler::URI.decode_www_form_component, except that <tt>'+'</tt> is preserved.
+  def self.decode_uri_component(str, enc=Encoding::UTF_8)
+    _decode_uri_component(/%\h\h/, str, enc)
+  end
+
+  def self._encode_uri_component(regexp, table, str, enc)
     str = str.to_s.dup
     if str.encoding != Encoding::ASCII_8BIT
       if enc && enc != Encoding::ASCII_8BIT
@@ -374,47 +412,115 @@ module Bundler::URI
       end
       str.force_encoding(Encoding::ASCII_8BIT)
     end
-    str.gsub!(/[^*\-.0-9A-Z_a-z]/, TBLENCWWWCOMP_)
+    str.gsub!(regexp, table)
     str.force_encoding(Encoding::US_ASCII)
   end
+  private_class_method :_encode_uri_component
 
-  # Decodes given +str+ of URL-encoded form data.
-  #
-  # This decodes + to SP.
-  #
-  # See Bundler::URI.encode_www_form_component, Bundler::URI.decode_www_form.
-  def self.decode_www_form_component(str, enc=Encoding::UTF_8)
-    raise ArgumentError, "invalid %-encoding (#{str})" if /%(?!\h\h)/ =~ str
-    str.b.gsub(/\+|%\h\h/, TBLDECWWWCOMP_).force_encoding(enc)
+  def self._decode_uri_component(regexp, str, enc)
+    raise ArgumentError, "invalid %-encoding (#{str})" if /%(?!\h\h)/.match?(str)
+    str.b.gsub(regexp, TBLDECWWWCOMP_).force_encoding(enc)
   end
+  private_class_method :_decode_uri_component
 
-  # Generates URL-encoded form data from given +enum+.
+  # Returns a URL-encoded string derived from the given
+  # {Enumerable}[https://docs.ruby-lang.org/en/master/Enumerable.html#module-Enumerable-label-Enumerable+in+Ruby+Classes]
+  # +enum+.
+  #
+  # The result is suitable for use as form data
+  # for an \HTTP request whose <tt>Content-Type</tt> is
+  # <tt>'application/x-www-form-urlencoded'</tt>.
   #
-  # This generates application/x-www-form-urlencoded data defined in HTML5
-  # from given an Enumerable object.
+  # The returned string consists of the elements of +enum+,
+  # each converted to one or more URL-encoded strings,
+  # and all joined with character <tt>'&'</tt>.
   #
-  # This internally uses Bundler::URI.encode_www_form_component(str).
+  # Simple examples:
   #
-  # This method doesn't convert the encoding of given items, so convert them
-  # before calling this method if you want to send data as other than original
-  # encoding or mixed encoding data. (Strings which are encoded in an HTML5
-  # ASCII incompatible encoding are converted to UTF-8.)
+  #   Bundler::URI.encode_www_form([['foo', 0], ['bar', 1], ['baz', 2]])
+  #   # => "foo=0&bar=1&baz=2"
+  #   Bundler::URI.encode_www_form({foo: 0, bar: 1, baz: 2})
+  #   # => "foo=0&bar=1&baz=2"
   #
-  # This method doesn't handle files.  When you send a file, use
-  # multipart/form-data.
+  # The returned string is formed using method Bundler::URI.encode_www_form_component,
+  # which converts certain characters:
   #
-  # This refers http://url.spec.whatwg.org/#concept-urlencoded-serializer
+  #   Bundler::URI.encode_www_form('f#o': '/', 'b-r': '$', 'b z': '@')
+  #   # => "f%23o=%2F&b-r=%24&b+z=%40"
   #
-  #    Bundler::URI.encode_www_form([["q", "ruby"], ["lang", "en"]])
-  #    #=> "q=ruby&lang=en"
-  #    Bundler::URI.encode_www_form("q" => "ruby", "lang" => "en")
-  #    #=> "q=ruby&lang=en"
-  #    Bundler::URI.encode_www_form("q" => ["ruby", "perl"], "lang" => "en")
-  #    #=> "q=ruby&q=perl&lang=en"
-  #    Bundler::URI.encode_www_form([["q", "ruby"], ["q", "perl"], ["lang", "en"]])
-  #    #=> "q=ruby&q=perl&lang=en"
+  # When +enum+ is Array-like, each element +ele+ is converted to a field:
+  #
+  # - If +ele+ is an array of two or more elements,
+  #   the field is formed from its first two elements
+  #   (and any additional elements are ignored):
+  #
+  #     name = Bundler::URI.encode_www_form_component(ele[0], enc)
+  #     value = Bundler::URI.encode_www_form_component(ele[1], enc)
+  #     "#{name}=#{value}"
+  #
+  #   Examples:
+  #
+  #     Bundler::URI.encode_www_form([%w[foo bar], %w[baz bat bah]])
+  #     # => "foo=bar&baz=bat"
+  #     Bundler::URI.encode_www_form([['foo', 0], ['bar', :baz, 'bat']])
+  #     # => "foo=0&bar=baz"
+  #
+  # - If +ele+ is an array of one element,
+  #   the field is formed from <tt>ele[0]</tt>:
+  #
+  #     Bundler::URI.encode_www_form_component(ele[0])
+  #
+  #   Example:
+  #
+  #     Bundler::URI.encode_www_form([['foo'], [:bar], [0]])
+  #     # => "foo&bar&0"
+  #
+  # - Otherwise the field is formed from +ele+:
+  #
+  #     Bundler::URI.encode_www_form_component(ele)
+  #
+  #   Example:
+  #
+  #     Bundler::URI.encode_www_form(['foo', :bar, 0])
+  #     # => "foo&bar&0"
+  #
+  # The elements of an Array-like +enum+ may be mixture:
+  #
+  #   Bundler::URI.encode_www_form([['foo', 0], ['bar', 1, 2], ['baz'], :bat])
+  #   # => "foo=0&bar=1&baz&bat"
+  #
+  # When +enum+ is Hash-like,
+  # each +key+/+value+ pair is converted to one or more fields:
+  #
+  # - If +value+ is
+  #   {Array-convertible}[https://docs.ruby-lang.org/en/master/implicit_conversion_rdoc.html#label-Array-Convertible+Objects],
+  #   each element +ele+ in +value+ is paired with +key+ to form a field:
+  #
+  #     name = Bundler::URI.encode_www_form_component(key, enc)
+  #     value = Bundler::URI.encode_www_form_component(ele, enc)
+  #     "#{name}=#{value}"
+  #
+  #   Example:
+  #
+  #     Bundler::URI.encode_www_form({foo: [:bar, 1], baz: [:bat, :bam, 2]})
+  #     # => "foo=bar&foo=1&baz=bat&baz=bam&baz=2"
+  #
+  # - Otherwise, +key+ and +value+ are paired to form a field:
+  #
+  #     name = Bundler::URI.encode_www_form_component(key, enc)
+  #     value = Bundler::URI.encode_www_form_component(value, enc)
+  #     "#{name}=#{value}"
+  #
+  #   Example:
+  #
+  #     Bundler::URI.encode_www_form({foo: 0, bar: 1, baz: 2})
+  #     # => "foo=0&bar=1&baz=2"
+  #
+  # The elements of a Hash-like +enum+ may be mixture:
+  #
+  #   Bundler::URI.encode_www_form({foo: [0, 1], bar: 2})
+  #   # => "foo=0&foo=1&bar=2"
   #
-  # See Bundler::URI.encode_www_form_component, Bundler::URI.decode_www_form.
   def self.encode_www_form(enum, enc=nil)
     enum.map do |k,v|
       if v.nil?
@@ -435,22 +541,39 @@ module Bundler::URI
     end.join('&')
   end
 
-  # Decodes URL-encoded form data from given +str+.
+  # Returns name/value pairs derived from the given string +str+,
+  # which must be an ASCII string.
   #
-  # This decodes application/x-www-form-urlencoded data
-  # and returns an array of key-value arrays.
+  # The method may be used to decode the body of Net::HTTPResponse object +res+
+  # for which <tt>res['Content-Type']</tt> is <tt>'application/x-www-form-urlencoded'</tt>.
   #
-  # This refers http://url.spec.whatwg.org/#concept-urlencoded-parser,
-  # so this supports only &-separator, and doesn't support ;-separator.
+  # The returned data is an array of 2-element subarrays;
+  # each subarray is a name/value pair (both are strings).
+  # Each returned string has encoding +enc+,
+  # and has had invalid characters removed via
+  # {String#scrub}[https://docs.ruby-lang.org/en/master/String.html#method-i-scrub].
   #
-  #    ary = Bundler::URI.decode_www_form("a=1&a=2&b=3")
-  #    ary                   #=> [['a', '1'], ['a', '2'], ['b', '3']]
-  #    ary.assoc('a').last   #=> '1'
-  #    ary.assoc('b').last   #=> '3'
-  #    ary.rassoc('a').last  #=> '2'
-  #    Hash[ary]             #=> {"a"=>"2", "b"=>"3"}
+  # A simple example:
+  #
+  #   Bundler::URI.decode_www_form('foo=0&bar=1&baz')
+  #   # => [["foo", "0"], ["bar", "1"], ["baz", ""]]
+  #
+  # The returned strings have certain conversions,
+  # similar to those performed in Bundler::URI.decode_www_form_component:
+  #
+  #   Bundler::URI.decode_www_form('f%23o=%2F&b-r=%24&b+z=%40')
+  #   # => [["f#o", "/"], ["b-r", "$"], ["b z", "@"]]
+  #
+  # The given string may contain consecutive separators:
+  #
+  #   Bundler::URI.decode_www_form('foo=0&&bar=1&&baz=2')
+  #   # => [["foo", "0"], ["", ""], ["bar", "1"], ["", ""], ["baz", "2"]]
+  #
+  # A different separator may be specified:
+  #
+  #   Bundler::URI.decode_www_form('foo=0--bar=1--baz', separator: '--')
+  #   # => [["foo", "0"], ["bar", "1"], ["baz", ""]]
   #
-  # See Bundler::URI.decode_www_form_component, Bundler::URI.encode_www_form.
   def self.decode_www_form(str, enc=Encoding::UTF_8, separator: '&', use__charset_: false, isindex: false)
     raise ArgumentError, "the input of #{self.name}.#{__method__} must be ASCII only string" unless str.ascii_only?
     ary = []
@@ -716,6 +839,7 @@ module Bundler::URI
     "utf-16"=>"utf-16le",
     "utf-16le"=>"utf-16le",
   } # :nodoc:
+  Ractor.make_shareable(WEB_ENCODINGS_) if defined?(Ractor)
 
   # :nodoc:
   # return encoding or nil
@@ -728,7 +852,15 @@ end # module Bundler::URI
 module Bundler
 
   #
-  # Returns +uri+ converted to an Bundler::URI object.
+  # Returns a \Bundler::URI object derived from the given +uri+,
+  # which may be a \Bundler::URI string or an existing \Bundler::URI object:
+  #
+  #   # Returns a new Bundler::URI.
+  #   uri = Bundler::URI('http://github.com/ruby/ruby')
+  #   # => #<Bundler::URI::HTTP http://github.com/ruby/ruby>
+  #   # Returns the given Bundler::URI.
+  #   Bundler::URI(uri)
+  #   # => #<Bundler::URI::HTTP http://github.com/ruby/ruby>
   #
   def URI(uri)
     if uri.is_a?(Bundler::URI::Generic)