dommy 0.13.0 → 0.14.0

data/lib/dommy/internal/url_parser.rb

@@ -28,12 +28,17 @@ module Dommy
         def default_port = SPECIAL[scheme]
       end
 
-      def parse(input, base_input = nil)
+      # `encoding` is the Encoding Standard name HTML's "encoding-parse a URL"
+      # hands the parser (the document's character encoding); nil means UTF-8,
+      # which is what the URL API and every other caller uses. It only changes
+      # the query, and only for a special URL that is not ws/wss (see
+      # BasicParser#query_encoding).
+      def parse(input, base_input = nil, encoding: nil)
         base = nil
         if base_input && base_input != ""
           base = base_input.is_a?(Record) ? base_input : run(base_input.to_s, nil)
         end
-        run(input.to_s, base)
+        run(input.to_s, base, encoding: encoding)
       end
 
       # The basic URL parser with a state override: `input` is read from
@@ -45,684 +50,832 @@ module Dommy
         run(input.to_s, nil, url: url, state_override: state)
       end
 
-      # ===== percent-encode sets =====
+      # The URL Standard vocabulary the parser is written in: the percent-encode
+      # sets, the host and IPv6 parsers, the serializers, and the path helpers.
+      # Every one is a function of its arguments alone.
+      #
+      # It is a separate module because it has two users with nothing else in
+      # common: UrlParser extends it, so callers outside this file keep writing
+      # `UrlParser.serialize(record)`, and BasicParser includes it, because a
+      # state machine is written in this vocabulary. Including UrlParser itself
+      # would also hand BasicParser `parse` / `run` — the entry points that build
+      # a BasicParser — which is not a vocabulary a parser state should reach for.
+      module Syntax
+        # ===== percent-encode sets =====
+
+        def c0?(cp) = cp <= 0x1F || cp > 0x7E
+        def fragment_set?(cp) = c0?(cp) || [0x20, 0x22, 0x3C, 0x3E, 0x60].include?(cp)
+        def query_set?(cp) = c0?(cp) || [0x20, 0x22, 0x23, 0x3C, 0x3E].include?(cp)
+        def special_query_set?(cp) = query_set?(cp) || cp == 0x27
+        def path_set?(cp) = query_set?(cp) || [0x3F, 0x5E, 0x60, 0x7B, 0x7D].include?(cp)
+        def userinfo_set?(cp) = path_set?(cp) || [0x2F, 0x3A, 0x3B, 0x3D, 0x40, 0x5B, 0x5C, 0x5D, 0x7C].include?(cp)
+
+        # UTF-8 percent-encode a single code point against `set` (a predicate).
+        def pe(char, set)
+          return char unless set.call(char.ord)
+
+          char.b.bytes.map { |b| format("%%%02X", b) }.join
+        end
 
-      def c0?(cp) = cp <= 0x1F || cp > 0x7E
-      def fragment_set?(cp) = c0?(cp) || [0x20, 0x22, 0x3C, 0x3E, 0x60].include?(cp)
-      def query_set?(cp) = c0?(cp) || [0x20, 0x22, 0x23, 0x3C, 0x3E].include?(cp)
-      def special_query_set?(cp) = query_set?(cp) || cp == 0x27
-      def path_set?(cp) = query_set?(cp) || [0x3F, 0x5E, 0x60, 0x7B, 0x7D].include?(cp)
-      def userinfo_set?(cp) = path_set?(cp) || [0x2F, 0x3A, 0x3B, 0x3D, 0x40, 0x5B, 0x5C, 0x5D, 0x7C].include?(cp)
+        # Spec: "percent-encode after encoding" (URL §1.3), the query state's
+        # flush. The whole buffer is encoded at once — ISO-2022-JP is stateful,
+        # so encoding code point by code point would emit a fresh escape per
+        # character — then each byte is percent-encoded if it falls in `set`. A
+        # code point the encoding cannot represent becomes the spec's numeric
+        # character reference escape ("%26%23" + decimal + "%3B").
+        def percent_encode_after_encoding(encoding_name, input, set)
+          out = +"".b
+          encode_bytes(encoding_name, input).each do |byte|
+            out << (set.call(byte) ? format("%%%02X", byte) : byte.chr)
+          end
+          out.force_encoding(::Encoding::UTF_8)
+        end
 
-      # UTF-8 percent-encode a single code point against `set` (a predicate).
-      def pe(char, set)
-        return char unless set.call(char.ord)
+        # The bytes `input` encodes to under `encoding_name` (an Encoding
+        # Standard name), or its UTF-8 bytes when the name is nil or Ruby has no
+        # matching encoding. Only a handful of the standard's names lack one
+        # (x-user-defined, replacement), and those are never a document's.
+        def encode_bytes(encoding_name, input)
+          ruby = begin
+            ::Encoding.find(encoding_name.to_s)
+          rescue ArgumentError
+            nil
+          end
+          return input.b.bytes if ruby.nil? || ruby == ::Encoding::UTF_8
 
-        char.b.bytes.map { |b| format("%%%02X", b) }.join
-      end
+          begin
+            input.encode(ruby).b.bytes
+          rescue ::Encoding::UndefinedConversionError, ::Encoding::InvalidByteSequenceError
+            per_code_point_bytes(ruby, input)
+          end
+        end
 
-      def percent_decode(str)
-        out = +"".b
-        bytes = str.b
-        i = 0
-        while i < bytes.bytesize
-          b = bytes.getbyte(i)
-          if b == 0x25 && i + 2 < bytes.bytesize &&
-              bytes.byteslice(i + 1, 2) =~ /\A[0-9A-Fa-f]{2}\z/
-            out << bytes.byteslice(i + 1, 2).to_i(16)
-            i += 3
-          else
-            out << b
-            i += 1
+        # A code point the encoding cannot represent yields the numeric-reference
+        # escape, already percent-encoded so the caller's per-byte pass leaves it
+        # alone.
+        def per_code_point_bytes(ruby, input)
+          out = +"".b
+          input.each_char do |char|
+            out << char.encode(ruby)
+          rescue ::Encoding::UndefinedConversionError, ::Encoding::InvalidByteSequenceError
+            out << "%26%23#{char.ord}%3B"
           end
+          out.bytes
         end
-        out
-      end
 
-      # ===== host parsing =====
+        def percent_decode(str)
+          out = +"".b
+          bytes = str.b
+          i = 0
+          while i < bytes.bytesize
+            b = bytes.getbyte(i)
+            if b == 0x25 && i + 2 < bytes.bytesize &&
+                bytes.byteslice(i + 1, 2) =~ /\A[0-9A-Fa-f]{2}\z/
+              out << bytes.byteslice(i + 1, 2).to_i(16)
+              i += 3
+            else
+              out << b
+              i += 1
+            end
+          end
+          out
+        end
 
-      FORBIDDEN_HOST = [0x00, 0x09, 0x0A, 0x0D, 0x20, 0x23, 0x2F, 0x3A, 0x3C, 0x3E,
-                        0x3F, 0x40, 0x5B, 0x5C, 0x5D, 0x5E, 0x7C].freeze
+        # ===== host parsing =====
 
-      def forbidden_host?(cp) = FORBIDDEN_HOST.include?(cp)
-      def forbidden_domain?(cp) = forbidden_host?(cp) || cp <= 0x1F || cp == 0x25 || cp == 0x7F
+        FORBIDDEN_HOST = [0x00, 0x09, 0x0A, 0x0D, 0x20, 0x23, 0x2F, 0x3A, 0x3C, 0x3E,
+                          0x3F, 0x40, 0x5B, 0x5C, 0x5D, 0x5E, 0x7C].freeze
 
-      def parse_host(input, special)
-        if input.start_with?("[")
-          raise Failure, "unclosed IPv6 address" unless input.end_with?("]")
+        def forbidden_host?(cp) = FORBIDDEN_HOST.include?(cp)
+        def forbidden_domain?(cp) = forbidden_host?(cp) || cp <= 0x1F || cp == 0x25 || cp == 0x7F
 
-          return "[#{parse_ipv6(input[1...-1])}]"
-        end
-        return parse_opaque_host(input) unless special
-        raise Failure, "empty host" if input.empty?
+        def parse_host(input, special)
+          if input.start_with?("[")
+            raise Failure, "unclosed IPv6 address" unless input.end_with?("]")
 
-        # UTF-8-decode-without-BOM the percent-decoded bytes: malformed
-        # sequences become U+FFFD (which domain-to-ASCII then rejects),
-        # matching the spec rather than crashing on invalid encoding.
-        domain = percent_decode(input).force_encoding("UTF-8").scrub("\uFFFD")
-        # The domain parser (beStrict false): an ASCII domain is only
-        # lowercased, whatever UTS #46 would make of it, for web
-        # compatibility; a non-ASCII one goes through ToASCII.
-        ascii =
-          if domain.ascii_only?
-            domain.downcase
-          else
-            begin
-              IDNA.to_ascii(domain, check_hyphens: false, verify_dns_length: false)
-            rescue IDNA::Error, Punycode::Error => e
-              raise Failure, "domain to ASCII: #{e.message}"
-            end
+            return "[#{parse_ipv6(input[1...-1])}]"
           end
-        raise Failure, "empty domain" if ascii.empty?
-        raise Failure, "forbidden domain code point" if ascii.each_char.any? { |ch| forbidden_domain?(ch.ord) }
+          return parse_opaque_host(input) unless special
+          raise Failure, "empty host" if input.empty?
+
+          # UTF-8-decode-without-BOM the percent-decoded bytes: malformed
+          # sequences become U+FFFD (which domain-to-ASCII then rejects),
+          # matching the spec rather than crashing on invalid encoding.
+          domain = percent_decode(input).force_encoding("UTF-8").scrub("\uFFFD")
+          # The domain parser (beStrict false): an ASCII domain is only
+          # lowercased, whatever UTS #46 would make of it, for web
+          # compatibility; a non-ASCII one goes through ToASCII.
+          ascii =
+            if domain.ascii_only?
+              domain.downcase
+            else
+              begin
+                IDNA.to_ascii(domain, check_hyphens: false, verify_dns_length: false)
+              rescue IDNA::Error, Punycode::Error => e
+                raise Failure, "domain to ASCII: #{e.message}"
+              end
+            end
+          raise Failure, "empty domain" if ascii.empty?
+          raise Failure, "forbidden domain code point" if ascii.each_char.any? { |ch| forbidden_domain?(ch.ord) }
 
-        if ends_in_number?(ascii)
-          ip = Ipv4Parser.parse(ascii)
-          raise Failure, "invalid IPv4 address" if ip.nil?
+          if ends_in_number?(ascii)
+            ip = Ipv4Parser.parse(ascii)
+            raise Failure, "invalid IPv4 address" if ip.nil?
 
-          return ip
+            return ip
+          end
+          ascii
         end
-        ascii
-      end
-
-      def parse_opaque_host(input)
-        raise Failure, "forbidden host code point" if input.each_char.any? { |ch| forbidden_host?(ch.ord) }
-
-        input.each_char.map { |ch| pe(ch, method(:c0?)) }.join
-      end
 
-      def ends_in_number?(input)
-        parts = input.split(".", -1)
-        parts.pop if parts.length > 1 && parts.last == ""
-        return false if parts.empty?
+        def parse_opaque_host(input)
+          raise Failure, "forbidden host code point" if input.each_char.any? { |ch| forbidden_host?(ch.ord) }
 
-        last = parts.last
-        return false if last.empty?
-        return true if last.match?(/\A[0-9]+\z/)
-
-        last.match?(/\A0[xX][0-9A-Fa-f]*\z/)
-      end
+          input.each_char.map { |ch| pe(ch, method(:c0?)) }.join
+        end
 
-      # WHATWG IPv6 parser -> compressed serialized string (no brackets).
-      def parse_ipv6(input)
-        address = [0, 0, 0, 0, 0, 0, 0, 0]
-        piece_index = 0
-        compress = nil
-        chars = input.chars
-        ptr = 0
-        c = ->(i) { i < chars.length ? chars[i] : nil }
+        def ends_in_number?(input)
+          parts = input.split(".", -1)
+          parts.pop if parts.length > 1 && parts.last == ""
+          return false if parts.empty?
 
-        if c.call(ptr) == ":"
-          raise Failure, "IPv6 starts with single colon" unless c.call(ptr + 1) == ":"
+          last = parts.last
+          return false if last.empty?
+          return true if last.match?(/\A[0-9]+\z/)
 
-          ptr += 2
-          piece_index += 1
-          compress = piece_index
+          last.match?(/\A0[xX][0-9A-Fa-f]*\z/)
         end
 
-        while c.call(ptr)
-          raise Failure, "too many IPv6 pieces" if piece_index == 8
+        # WHATWG IPv6 parser -> compressed serialized string (no brackets).
+        def parse_ipv6(input)
+          address = [0, 0, 0, 0, 0, 0, 0, 0]
+          piece_index = 0
+          compress = nil
+          chars = input.chars
+          ptr = 0
+          c = ->(i) { i < chars.length ? chars[i] : nil }
 
           if c.call(ptr) == ":"
-            raise Failure, "multiple IPv6 compressions" unless compress.nil?
+            raise Failure, "IPv6 starts with single colon" unless c.call(ptr + 1) == ":"
 
-            ptr += 1
+            ptr += 2
             piece_index += 1
             compress = piece_index
-            next
           end
 
-          value = 0
-          length = 0
-          while length < 4 && c.call(ptr)&.match?(/[0-9A-Fa-f]/)
-            value = value * 16 + c.call(ptr).to_i(16)
-            ptr += 1
-            length += 1
-          end
+          while c.call(ptr)
+            raise Failure, "too many IPv6 pieces" if piece_index == 8
 
-          if c.call(ptr) == "."
-            raise Failure, "IPv4-in-IPv6 with no digits" if length.zero?
+            if c.call(ptr) == ":"
+              raise Failure, "multiple IPv6 compressions" unless compress.nil?
 
-            ptr -= length
-            raise Failure, "too few pieces for embedded IPv4" if piece_index > 6
+              ptr += 1
+              piece_index += 1
+              compress = piece_index
+              next
+            end
+
+            value = 0
+            length = 0
+            while length < 4 && c.call(ptr)&.match?(/[0-9A-Fa-f]/)
+              value = value * 16 + c.call(ptr).to_i(16)
+              ptr += 1
+              length += 1
+            end
+
+            if c.call(ptr) == "."
+              raise Failure, "IPv4-in-IPv6 with no digits" if length.zero?
+
+              ptr -= length
+              raise Failure, "too few pieces for embedded IPv4" if piece_index > 6
+
+              numbers_seen = 0
+              while c.call(ptr)
+                ipv4_piece = nil
+                if numbers_seen.positive?
+                  if c.call(ptr) == "." && numbers_seen < 4
+                    ptr += 1
+                  else
+                    raise Failure, "invalid embedded IPv4"
+                  end
+                end
+                raise Failure, "invalid embedded IPv4 digit" unless c.call(ptr)&.match?(/[0-9]/)
+
+                while c.call(ptr)&.match?(/[0-9]/)
+                  number = c.call(ptr).to_i
+                  if ipv4_piece.nil?
+                    ipv4_piece = number
+                  elsif ipv4_piece.zero?
+                    raise Failure, "leading zero in embedded IPv4"
+                  else
+                    ipv4_piece = ipv4_piece * 10 + number
+                  end
+                  raise Failure, "embedded IPv4 piece > 255" if ipv4_piece > 255
 
-            numbers_seen = 0
-            while c.call(ptr)
-              ipv4_piece = nil
-              if numbers_seen.positive?
-                if c.call(ptr) == "." && numbers_seen < 4
                   ptr += 1
-                else
-                  raise Failure, "invalid embedded IPv4"
                 end
+                address[piece_index] = address[piece_index] * 0x100 + ipv4_piece
+                numbers_seen += 1
+                piece_index += 1 if numbers_seen == 2 || numbers_seen == 4
               end
-              raise Failure, "invalid embedded IPv4 digit" unless c.call(ptr)&.match?(/[0-9]/)
-
-              while c.call(ptr)&.match?(/[0-9]/)
-                number = c.call(ptr).to_i
-                if ipv4_piece.nil?
-                  ipv4_piece = number
-                elsif ipv4_piece.zero?
-                  raise Failure, "leading zero in embedded IPv4"
-                else
-                  ipv4_piece = ipv4_piece * 10 + number
-                end
-                raise Failure, "embedded IPv4 piece > 255" if ipv4_piece > 255
+              raise Failure, "incomplete embedded IPv4" unless numbers_seen == 4
 
-                ptr += 1
-              end
-              address[piece_index] = address[piece_index] * 0x100 + ipv4_piece
-              numbers_seen += 1
-              piece_index += 1 if numbers_seen == 2 || numbers_seen == 4
+              break
+            elsif c.call(ptr) == ":"
+              ptr += 1
+              raise Failure, "trailing colon in IPv6" if c.call(ptr).nil?
+            elsif c.call(ptr)
+              raise Failure, "invalid IPv6 code point"
             end
-            raise Failure, "incomplete embedded IPv4" unless numbers_seen == 4
 
-            break
-          elsif c.call(ptr) == ":"
-            ptr += 1
-            raise Failure, "trailing colon in IPv6" if c.call(ptr).nil?
-          elsif c.call(ptr)
-            raise Failure, "invalid IPv6 code point"
+            address[piece_index] = value
+            piece_index += 1
           end
 
-          address[piece_index] = value
-          piece_index += 1
-        end
-
-        if compress
-          swaps = piece_index - compress
-          piece_index = 7
-          while piece_index != 0 && swaps.positive?
-            address[piece_index], address[compress + swaps - 1] = address[compress + swaps - 1], address[piece_index]
-            piece_index -= 1
-            swaps -= 1
+          if compress
+            swaps = piece_index - compress
+            piece_index = 7
+            while piece_index != 0 && swaps.positive?
+              address[piece_index], address[compress + swaps - 1] = address[compress + swaps - 1], address[piece_index]
+              piece_index -= 1
+              swaps -= 1
+            end
+          elsif piece_index != 8
+            raise Failure, "too few IPv6 pieces"
           end
-        elsif piece_index != 8
-          raise Failure, "too few IPv6 pieces"
-        end
 
-        serialize_ipv6(address)
-      end
+          serialize_ipv6(address)
+        end
 
-      def serialize_ipv6(pieces)
-        # Find the longest run (length > 1) of zero pieces to compress.
-        best_start = nil
-        best_len = 0
-        i = 0
-        while i < 8
-          if pieces[i].zero?
-            j = i
-            j += 1 while j < 8 && pieces[j].zero?
-            if (j - i) > best_len
-              best_len = j - i
-              best_start = i
+        def serialize_ipv6(pieces)
+          # Find the longest run (length > 1) of zero pieces to compress.
+          best_start = nil
+          best_len = 0
+          i = 0
+          while i < 8
+            if pieces[i].zero?
+              j = i
+              j += 1 while j < 8 && pieces[j].zero?
+              if (j - i) > best_len
+                best_len = j - i
+                best_start = i
+              end
+              i = j
+            else
+              i += 1
             end
-            i = j
-          else
+          end
+          best_start = nil if best_len < 2
+
+          out = +""
+          i = 0
+          while i < 8
+            if best_start == i
+              out << (i.zero? ? "::" : ":")
+              i += best_len
+              next
+            end
+            out << pieces[i].to_s(16)
+            out << ":" if i < 7
             i += 1
           end
+          out
+        end
+
+        # ===== serialization =====
+
+        def serialize_path(record)
+          return record.path if record.opaque_path?
+
+          record.path.map { |seg| "/#{seg}" }.join
         end
-        best_start = nil if best_len < 2
 
-        out = +""
-        i = 0
-        while i < 8
-          if best_start == i
-            out << (i.zero? ? "::" : ":")
-            i += best_len
-            next
+        def serialize(record, exclude_fragment: false)
+          out = +"#{record.scheme}:"
+          if record.host
+            out << "//"
+            if record.includes_credentials?
+              out << record.username
+              out << ":#{record.password}" unless record.password.empty?
+              out << "@"
+            end
+            out << record.host
+            out << ":#{record.port}" if record.port
+          elsif !record.opaque_path? && record.path.is_a?(Array) &&
+              record.path.length > 1 && record.path[0] == ""
+            out << "/."
           end
-          out << pieces[i].to_s(16)
-          out << ":" if i < 7
-          i += 1
+          out << serialize_path(record)
+          out << "?#{record.query}" if record.query
+          out << "##{record.fragment}" if record.fragment && !exclude_fragment
+          out
         end
-        out
-      end
 
-      # ===== serialization =====
+        # ===== helpers for path normalization =====
 
-      def serialize_path(record)
-        return record.path if record.opaque_path?
+        def windows_drive_letter?(seg) = seg.length == 2 && seg[0].match?(/[A-Za-z]/) && [":", "|"].include?(seg[1])
+        def normalized_windows_drive_letter?(seg) = seg.length == 2 && seg[0].match?(/[A-Za-z]/) && seg[1] == ":"
+        def starts_with_windows_drive_letter?(s)
+          s.length >= 2 && s[0].match?(/[A-Za-z]/) && [":", "|"].include?(s[1]) &&
+            (s.length == 2 || ["/", "\\", "?", "#"].include?(s[2]))
+        end
 
-        record.path.map { |seg| "/#{seg}" }.join
-      end
+        def single_dot?(seg) = [".", "%2e"].include?(seg.downcase)
 
-      def serialize(record, exclude_fragment: false)
-        out = +"#{record.scheme}:"
-        if record.host
-          out << "//"
-          if record.includes_credentials?
-            out << record.username
-            out << ":#{record.password}" unless record.password.empty?
-            out << "@"
-          end
-          out << record.host
-          out << ":#{record.port}" if record.port
-        elsif !record.opaque_path? && record.path.is_a?(Array) &&
-            record.path.length > 1 && record.path[0] == ""
-          out << "/."
-        end
-        out << serialize_path(record)
-        out << "?#{record.query}" if record.query
-        out << "##{record.fragment}" if record.fragment && !exclude_fragment
-        out
-      end
+        def double_dot?(seg)
+          ["..", ".%2e", "%2e.", "%2e%2e"].include?(seg.downcase)
+        end
 
-      # ===== helpers for path normalization =====
+        def shorten_path(record)
+          path = record.path
+          return if path.empty?
+          return if record.scheme == "file" && path.length == 1 && normalized_windows_drive_letter?(path[0])
 
-      def windows_drive_letter?(seg) = seg.length == 2 && seg[0].match?(/[A-Za-z]/) && [":", "|"].include?(seg[1])
-      def normalized_windows_drive_letter?(seg) = seg.length == 2 && seg[0].match?(/[A-Za-z]/) && seg[1] == ":"
-      def starts_with_windows_drive_letter?(s)
-        s.length >= 2 && s[0].match?(/[A-Za-z]/) && [":", "|"].include?(s[1]) &&
-          (s.length == 2 || ["/", "\\", "?", "#"].include?(s[2]))
+          path.pop
+        end
       end
 
-      def single_dot?(seg) = [".", "%2e"].include?(seg.downcase)
-
-      def double_dot?(seg)
-        ["..", ".%2e", "%2e.", "%2e%2e"].include?(seg.downcase)
-      end
+      # So `UrlParser.percent_decode` and friends keep answering.
+      extend Syntax
 
-      def shorten_path(record)
-        path = record.path
-        return if path.empty?
-        return if record.scheme == "file" && path.length == 1 && normalized_windows_drive_letter?(path[0])
+      # ===== the basic URL parser state machine =====
 
-        path.pop
+      def run(input, base, url: nil, state_override: nil, encoding: nil)
+        BasicParser.new(input, base, url: url, state_override: state_override, encoding: encoding).run
       end
 
-      # ===== the basic URL parser state machine =====
-
-      def run(input, base, url: nil, state_override: nil)
-        input = input.dup
-        # Strip leading/trailing C0 controls and spaces (only for a fresh
-        # parse; a setter's input keeps them), then remove all ASCII
-        # tab/newline.
-        input = input.sub(/\A[\x00-\x20]+/, "").sub(/[\x00-\x20]+\z/, "") if url.nil?
-        input = input.gsub(/[\t\n\r]/, "")
-
-        chars = input.chars
-        len = chars.length
-        state = state_override || :scheme_start
-        url ||= Record.new("", "", "", nil, nil, [], nil, nil)
-        buffer = +""
-        at_sign_seen = false
-        inside_brackets = false
-        password_token_seen = false
-        ptr = 0
-
-        cp = lambda { ptr < len ? chars[ptr] : nil }
-
-        loop do
-          c = cp.call
-
-          case state
-          when :scheme_start
-            if c&.match?(/[A-Za-z]/)
-              buffer << c.downcase
-              state = :scheme
-            elsif state_override
-              raise Failure, "scheme must start with a letter"
-            else
-              state = :no_scheme
-              next # reprocess (do not advance)
-            end
+      # The basic URL parser's state machine (url.spec.whatwg.org §4.4), one
+      # method per state.
+      #
+      # It was one 390-line method, which is faithful to the spec's shape but
+      # leaves eight mutable locals whose writers are scattered over twenty
+      # states. As a class the locals are the parser's own state, and each spec
+      # state is a method carrying the spec's name for it, so a state can be
+      # read without reading the other nineteen.
+      #
+      # The two non-linear moves the spec makes are throws the loop catches:
+      # "do not advance, re-run this position in the new state" is
+      # `throw :reprocess`, and a setter that stops early (state_override) is
+      # `throw :done`. A `next` inside a nested block still means the next
+      # element of that block — see the authority state, which walks the
+      # buffer's characters.
+      class BasicParser
+        include Syntax
+        # Syntax is the parser's vocabulary, not part of its interface: a state
+        # calls `pe` or `shorten_path` on itself, nobody calls them on a parser.
+        private(*Syntax.public_instance_methods)
+
+        STATES = {
+          scheme_start: :state_scheme_start,
+          scheme: :state_scheme,
+          no_scheme: :state_no_scheme,
+          special_relative_or_authority: :state_special_relative_or_authority,
+          path_or_authority: :state_path_or_authority,
+          relative: :state_relative,
+          relative_slash: :state_relative_slash,
+          special_authority_slashes: :state_special_authority_slashes,
+          special_authority_ignore_slashes: :state_special_authority_ignore_slashes,
+          authority: :state_authority,
+          host: :state_host,
+          hostname: :state_host,
+          port: :state_port,
+          file: :state_file,
+          file_slash: :state_file_slash,
+          file_host: :state_file_host,
+          path_start: :state_path_start,
+          path: :state_path,
+          opaque_path: :state_opaque_path,
+          query: :state_query,
+          fragment: :state_fragment,
+        }.freeze
+
+        def initialize(input, base, url: nil, state_override: nil, encoding: nil)
+          input = input.dup
+          # Strip leading/trailing C0 controls and spaces (only for a fresh
+          # parse; a setter's input keeps them), then remove all ASCII
+          # tab/newline.
+          input = input.sub(/\A[\x00-\x20]+/, "").sub(/[\x00-\x20]+\z/, "") if url.nil?
+          @input = input.gsub(/[\t\n\r]/, "")
+          @chars = @input.chars
+          @len = @chars.length
+          @base = base
+          @state_override = state_override
+          @encoding = encoding
+          @state = state_override || :scheme_start
+          @url = url || Record.new("", "", "", nil, nil, [], nil, nil)
+          @buffer = +""
+          @at_sign_seen = false
+          @inside_brackets = false
+          @password_token_seen = false
+          @ptr = 0
+        end
 
-          when :scheme
-            if c&.match?(/[A-Za-z0-9+\-.]/)
-              buffer << c.downcase
-            elsif c == ":"
-              if state_override
-                # A setter may not move a URL between special and
-                # non-special, onto file with credentials or a port, or off
-                # file with an empty host.
-                return url if SPECIAL.key?(url.scheme) != SPECIAL.key?(buffer)
-                return url if (url.includes_credentials? || !url.port.nil?) && buffer == "file"
-                return url if url.scheme == "file" && url.host == ""
-
-                url.scheme = buffer
-                url.port = nil if url.port == url.default_port
-                return url
+        def run
+          catch(:done) do
+            loop do
+              advanced = catch(:reprocess) do
+                send(STATES.fetch(@state), current_char)
+                true
               end
+              next unless advanced
+              break if @ptr >= @len
 
-              url.scheme = buffer
-              buffer = +""
-              if url.scheme == "file"
-                state = :file
-              elsif url.special? && base && base.scheme == url.scheme
-                state = :special_relative_or_authority
-              elsif url.special?
-                state = :special_authority_slashes
-              elsif input[(ptr + 1)..].to_s.start_with?("/")
-                state = :path_or_authority
-                ptr += 1
-              else
-                url.path = ""
-                state = :opaque_path
-              end
-            elsif state_override
-              raise Failure, "invalid scheme"
-            else
-              buffer = +""
-              state = :no_scheme
-              ptr = -1 # restart from 0 (advance makes it 0)
+              @ptr += 1
             end
+            @url
+          end
+        end
 
-          when :no_scheme
-            raise Failure, "missing scheme" if base.nil? || (base.opaque_path? && c != "#")
-
-            if base.opaque_path? && c == "#"
-              url.scheme = base.scheme
-              url.path = base.path
-              url.query = base.query
-              url.fragment = +""
-              state = :fragment
-            elsif base.scheme != "file"
-              state = :relative
-              next
-            else
-              state = :file
-              next
-            end
+        private
 
-          when :special_relative_or_authority
-            if c == "/" && input[(ptr + 1)..].to_s.start_with?("/")
-              state = :special_authority_ignore_slashes
-              ptr += 1
-            else
-              state = :relative
-              next
-            end
+        def current_char = @ptr < @len ? @chars[@ptr] : nil
 
-          when :path_or_authority
-            if c == "/"
-              state = :authority
-            else
-              state = :path
-              next
-            end
+        def state_scheme_start(c)
+          if c&.match?(/[A-Za-z]/)
+            @buffer << c.downcase
+            @state = :scheme
+          elsif @state_override
+            raise Failure, "scheme must start with a letter"
+          else
+            @state = :no_scheme
+            throw :reprocess
+          end
+        end
 
-          when :relative
-            url.scheme = base.scheme
-            if c == "/"
-              state = :relative_slash
-            elsif url.special? && c == "\\"
-              state = :relative_slash
-            else
-              url.username = base.username
-              url.password = base.password
-              url.host = base.host
-              url.port = base.port
-              url.path = base.path.dup
-              url.query = base.query
-              if c == "?"
-                url.query = +""
-                state = :query
-              elsif c == "#"
-                url.fragment = +""
-                state = :fragment
-              elsif c
-                url.query = nil
-                shorten_path(url)
-                state = :path
-                next
-              end
+        def state_scheme(c)
+          if c&.match?(/[A-Za-z0-9+\-.]/)
+            @buffer << c.downcase
+          elsif c == ":"
+            if @state_override
+              # A setter may not move a URL between special and
+              # non-special, onto file with credentials or a port, or off
+              # file with an empty host.
+              throw :done, @url if SPECIAL.key?(@url.scheme) != SPECIAL.key?(@buffer)
+              throw :done, @url if (@url.includes_credentials? || !@url.port.nil?) && @buffer == "file"
+              throw :done, @url if @url.scheme == "file" && @url.host == ""
+
+              @url.scheme = @buffer
+              @url.port = nil if @url.port == @url.default_port
+              throw :done, @url
             end
 
-          when :relative_slash
-            if url.special? && (c == "/" || c == "\\")
-              state = :special_authority_ignore_slashes
-            elsif c == "/"
-              state = :authority
+            @url.scheme = @buffer
+            @buffer = +""
+            if @url.scheme == "file"
+              @state = :file
+            elsif @url.special? && @base && @base.scheme == @url.scheme
+              @state = :special_relative_or_authority
+            elsif @url.special?
+              @state = :special_authority_slashes
+            elsif @input[(@ptr + 1)..].to_s.start_with?("/")
+              @state = :path_or_authority
+              @ptr += 1
             else
-              url.username = base.username
-              url.password = base.password
-              url.host = base.host
-              url.port = base.port
-              state = :path
-              next
+              @url.path = ""
+              @state = :opaque_path
             end
+          elsif @state_override
+            raise Failure, "invalid scheme"
+          else
+            @buffer = +""
+            @state = :no_scheme
+            @ptr = -1 # restart from 0 (advance makes it 0)
+          end
+        end
 
-          when :special_authority_slashes
-            if c == "/" && input[(ptr + 1)..].to_s.start_with?("/")
-              state = :special_authority_ignore_slashes
-              ptr += 1
-            else
-              state = :special_authority_ignore_slashes
-              next
-            end
+        def state_no_scheme(c)
+          raise Failure, "missing scheme" if @base.nil? || (@base.opaque_path? && c != "#")
+
+          if @base.opaque_path? && c == "#"
+            @url.scheme = @base.scheme
+            @url.path = @base.path
+            @url.query = @base.query
+            @url.fragment = +""
+            @state = :fragment
+          elsif @base.scheme != "file"
+            @state = :relative
+            throw :reprocess
+          else
+            @state = :file
+            throw :reprocess
+          end
+        end
 
-          when :special_authority_ignore_slashes
-            if c != "/" && c != "\\"
-              state = :authority
-              next
-            end
+        def state_special_relative_or_authority(c)
+          if c == "/" && @input[(@ptr + 1)..].to_s.start_with?("/")
+            @state = :special_authority_ignore_slashes
+            @ptr += 1
+          else
+            @state = :relative
+            throw :reprocess
+          end
+        end
 
-          when :authority
-            if c == "@"
-              buffer = "%40#{buffer}" if at_sign_seen
-              at_sign_seen = true
-              buffer.each_char do |ch|
-                if ch == ":" && !password_token_seen
-                  password_token_seen = true
-                  next
-                end
-                encoded = pe(ch, method(:userinfo_set?))
-                if password_token_seen
-                  url.password += encoded
-                else
-                  url.username += encoded
-                end
-              end
-              buffer = +""
-            elsif c.nil? || ["/", "?", "#"].include?(c) || (url.special? && c == "\\")
-              raise Failure, "empty host with credentials" if at_sign_seen && buffer.empty?
+        def state_path_or_authority(c)
+          if c == "/"
+            @state = :authority
+          else
+            @state = :path
+            throw :reprocess
+          end
+        end
 
-              ptr -= (buffer.length + 1)
-              buffer = +""
-              state = :host
-            else
-              buffer << c
+        def state_relative(c)
+          @url.scheme = @base.scheme
+          if c == "/"
+            @state = :relative_slash
+          elsif @url.special? && c == "\\"
+            @state = :relative_slash
+          else
+            @url.username = @base.username
+            @url.password = @base.password
+            @url.host = @base.host
+            @url.port = @base.port
+            @url.path = @base.path.dup
+            @url.query = @base.query
+            if c == "?"
+              @url.query = +""
+              @state = :query
+            elsif c == "#"
+              @url.fragment = +""
+              @state = :fragment
+            elsif c
+              @url.query = nil
+              shorten_path(@url)
+              @state = :path
+              throw :reprocess
             end
+          end
+        end
 
-          when :host, :hostname
-            if state_override && url.scheme == "file"
-              ptr -= 1
-              state = :file_host
-            elsif c == ":" && !inside_brackets
-              raise Failure, "empty host" if buffer.empty?
-              raise Failure, "a hostname cannot carry a port" if state_override == :hostname
-
-              url.host = parse_host(buffer, url.special?)
-              buffer = +""
-              state = :port
-            elsif c.nil? || ["/", "?", "#"].include?(c) || (url.special? && c == "\\")
-              ptr -= 1
-              raise Failure, "empty special host" if url.special? && buffer.empty?
-              if state_override && buffer.empty? && (url.includes_credentials? || !url.port.nil?)
-                raise Failure, "a URL with credentials or a port needs a host"
-              end
-
-              url.host = parse_host(buffer, url.special?)
-              return url if state_override
-
-              buffer = +""
-              state = :path_start
-            else
-              inside_brackets = true if c == "["
-              inside_brackets = false if c == "]"
-              buffer << c
-            end
+        def state_relative_slash(c)
+          if @url.special? && (c == "/" || c == "\\")
+            @state = :special_authority_ignore_slashes
+          elsif c == "/"
+            @state = :authority
+          else
+            @url.username = @base.username
+            @url.password = @base.password
+            @url.host = @base.host
+            @url.port = @base.port
+            @state = :path
+            throw :reprocess
+          end
+        end
 
-          when :port
-            if c&.match?(/[0-9]/)
-              buffer << c
-            elsif c.nil? || ["/", "?", "#"].include?(c) || (url.special? && c == "\\") || state_override
-              unless buffer.empty?
-                port = buffer.to_i
-                raise Failure, "port out of range" if port > 65_535
-
-                url.port = (port == url.default_port ? nil : port)
-                buffer = +""
-                return url if state_override
-              end
-              raise Failure, "empty port" if state_override
+        def state_special_authority_slashes(c)
+          if c == "/" && @input[(@ptr + 1)..].to_s.start_with?("/")
+            @state = :special_authority_ignore_slashes
+            @ptr += 1
+          else
+            @state = :special_authority_ignore_slashes
+            throw :reprocess
+          end
+        end
 
-              state = :path_start
-              next
-            else
-              raise Failure, "invalid port"
-            end
+        def state_special_authority_ignore_slashes(c)
+          if c != "/" && c != "\\"
+            @state = :authority
+            throw :reprocess
+          end
+        end
 
-          when :file
-            url.scheme = "file"
-            url.host = ""
-            if c == "/" || c == "\\"
-              state = :file_slash
-            elsif base && base.scheme == "file"
-              url.host = base.host
-              url.path = base.path.dup
-              url.query = base.query
-              if c == "?"
-                url.query = +""
-                state = :query
-              elsif c == "#"
-                url.fragment = +""
-                state = :fragment
-              elsif c
-                url.query = nil
-                shorten_path(url) unless starts_with_windows_drive_letter?(input[ptr..].to_s)
-                url.path = [] if starts_with_windows_drive_letter?(input[ptr..].to_s)
-                state = :path
+        def state_authority(c)
+          if c == "@"
+            @buffer = "%40#{@buffer}" if @at_sign_seen
+            @at_sign_seen = true
+            @buffer.each_char do |ch|
+              if ch == ":" && !@password_token_seen
+                @password_token_seen = true
                 next
               end
-            else
-              state = :path
-              next
+              encoded = pe(ch, method(:userinfo_set?))
+              if @password_token_seen
+                @url.password += encoded
+              else
+                @url.username += encoded
+              end
             end
+            @buffer = +""
+          elsif c.nil? || ["/", "?", "#"].include?(c) || (@url.special? && c == "\\")
+            raise Failure, "empty host with credentials" if @at_sign_seen && @buffer.empty?
 
-          when :file_slash
-            if c == "/" || c == "\\"
-              state = :file_host
-            else
-              if base && base.scheme == "file"
-                url.host = base.host
-                if !starts_with_windows_drive_letter?(input[ptr..].to_s) &&
-                    base.path[0] && normalized_windows_drive_letter?(base.path[0])
-                  url.path << base.path[0]
-                end
-              end
-              state = :path
-              next
+            @ptr -= (@buffer.length + 1)
+            @buffer = +""
+            @state = :host
+          else
+            @buffer << c
+          end
+        end
+
+        def state_host(c)
+          if @state_override && @url.scheme == "file"
+            @ptr -= 1
+            @state = :file_host
+          elsif c == ":" && !@inside_brackets
+            raise Failure, "empty host" if @buffer.empty?
+            raise Failure, "a hostname cannot carry a port" if @state_override == :hostname
+
+            @url.host = parse_host(@buffer, @url.special?)
+            @buffer = +""
+            @state = :port
+          elsif c.nil? || ["/", "?", "#"].include?(c) || (@url.special? && c == "\\")
+            @ptr -= 1
+            raise Failure, "empty special host" if @url.special? && @buffer.empty?
+            if @state_override && @buffer.empty? && (@url.includes_credentials? || !@url.port.nil?)
+              raise Failure, "a URL with credentials or a port needs a host"
             end
 
-          when :file_host
-            if c.nil? || ["/", "\\", "?", "#"].include?(c)
-              ptr -= 1
-              if state_override.nil? && buffer.match?(/\A[A-Za-z][:|]\z/)
-                state = :path
-              elsif buffer.empty?
-                url.host = ""
-                return url if state_override
+            @url.host = parse_host(@buffer, @url.special?)
+            throw :done, @url if @state_override
 
-                state = :path_start
-              else
-                host = parse_host(buffer, true)
-                host = "" if host == "localhost"
-                url.host = host
-                return url if state_override
+            @buffer = +""
+            @state = :path_start
+          else
+            @inside_brackets = true if c == "["
+            @inside_brackets = false if c == "]"
+            @buffer << c
+          end
+        end
 
-                buffer = +""
-                state = :path_start
-              end
-            else
-              buffer << c
+        def state_port(c)
+          if c&.match?(/[0-9]/)
+            @buffer << c
+          elsif c.nil? || ["/", "?", "#"].include?(c) || (@url.special? && c == "\\") || @state_override
+            unless @buffer.empty?
+              port = @buffer.to_i
+              raise Failure, "port out of range" if port > 65_535
+
+              @url.port = (port == @url.default_port ? nil : port)
+              @buffer = +""
+              throw :done, @url if @state_override
             end
+            raise Failure, "empty port" if @state_override
+
+            @state = :path_start
+            throw :reprocess
+          else
+            raise Failure, "invalid port"
+          end
+        end
 
-          when :path_start
-            if url.special?
-              state = :path
-              next unless c == "/" || c == "\\"
-            elsif state_override.nil? && c == "?"
-              url.query = +""
-              state = :query
-            elsif state_override.nil? && c == "#"
-              url.fragment = +""
-              state = :fragment
+        def state_file(c)
+          @url.scheme = "file"
+          @url.host = ""
+          if c == "/" || c == "\\"
+            @state = :file_slash
+          elsif @base && @base.scheme == "file"
+            @url.host = @base.host
+            @url.path = @base.path.dup
+            @url.query = @base.query
+            if c == "?"
+              @url.query = +""
+              @state = :query
+            elsif c == "#"
+              @url.fragment = +""
+              @state = :fragment
             elsif c
-              state = :path
-              next unless c == "/"
-            elsif state_override && url.host.nil?
-              url.path << ""
+              @url.query = nil
+              shorten_path(@url) unless starts_with_windows_drive_letter?(@input[@ptr..].to_s)
+              @url.path = [] if starts_with_windows_drive_letter?(@input[@ptr..].to_s)
+              @state = :path
+              throw :reprocess
             end
+          else
+            @state = :path
+            throw :reprocess
+          end
+        end
 
-          when :path
-            if c.nil? || c == "/" || (url.special? && c == "\\") ||
-                (state_override.nil? && (c == "?" || c == "#"))
-              if double_dot?(buffer)
-                shorten_path(url)
-                url.path << "" unless c == "/" || (url.special? && c == "\\")
-              elsif single_dot?(buffer)
-                url.path << "" unless c == "/" || (url.special? && c == "\\")
-              else
-                if url.scheme == "file" && url.path.empty? && windows_drive_letter?(buffer)
-                  buffer[1] = ":"
-                end
-                url.path << buffer
-              end
-              buffer = +""
-              if c == "?"
-                url.query = +""
-                state = :query
-              elsif c == "#"
-                url.fragment = +""
-                state = :fragment
+        def state_file_slash(c)
+          if c == "/" || c == "\\"
+            @state = :file_host
+          else
+            if @base && @base.scheme == "file"
+              @url.host = @base.host
+              if !starts_with_windows_drive_letter?(@input[@ptr..].to_s) &&
+                  @base.path[0] && normalized_windows_drive_letter?(@base.path[0])
+                @url.path << @base.path[0]
               end
+            end
+            @state = :path
+            throw :reprocess
+          end
+        end
+
+        def state_file_host(c)
+          if c.nil? || ["/", "\\", "?", "#"].include?(c)
+            @ptr -= 1
+            if @state_override.nil? && @buffer.match?(/\A[A-Za-z][:|]\z/)
+              @state = :path
+            elsif @buffer.empty?
+              @url.host = ""
+              throw :done, @url if @state_override
+
+              @state = :path_start
             else
-              buffer << pe(c, method(:path_set?))
+              host = parse_host(@buffer, true)
+              host = "" if host == "localhost"
+              @url.host = host
+              throw :done, @url if @state_override
+
+              @buffer = +""
+              @state = :path_start
             end
+          else
+            @buffer << c
+          end
+        end
+
+        def state_path_start(c)
+          if @url.special?
+            @state = :path
+            throw :reprocess unless c == "/" || c == "\\"
+          elsif @state_override.nil? && c == "?"
+            @url.query = +""
+            @state = :query
+          elsif @state_override.nil? && c == "#"
+            @url.fragment = +""
+            @state = :fragment
+          elsif c
+            @state = :path
+            throw :reprocess unless c == "/"
+          elsif @state_override && @url.host.nil?
+            @url.path << ""
+          end
+        end
 
-          when :opaque_path
+        def state_path(c)
+          if c.nil? || c == "/" || (@url.special? && c == "\\") ||
+              (@state_override.nil? && (c == "?" || c == "#"))
+            if double_dot?(@buffer)
+              shorten_path(@url)
+              @url.path << "" unless c == "/" || (@url.special? && c == "\\")
+            elsif single_dot?(@buffer)
+              @url.path << "" unless c == "/" || (@url.special? && c == "\\")
+            else
+              if @url.scheme == "file" && @url.path.empty? && windows_drive_letter?(@buffer)
+                @buffer[1] = ":"
+              end
+              @url.path << @buffer
+            end
+            @buffer = +""
             if c == "?"
-              url.query = +""
-              state = :query
+              @url.query = +""
+              @state = :query
             elsif c == "#"
-              url.fragment = +""
-              state = :fragment
-            elsif c == " "
-              # A space is only percent-encoded when it abuts the end of
-              # the opaque path (a following `?`/`#`); an interior space
-              # stays literal. (Trailing-at-EOF spaces are already gone
-              # via the leading/trailing strip.)
-              nxt = chars[ptr + 1]
-              url.path += (nxt == "?" || nxt == "#") ? "%20" : " "
-            elsif c
-              url.path += pe(c, method(:c0?))
+              @url.fragment = +""
+              @state = :fragment
             end
+          else
+            @buffer << pe(c, method(:path_set?))
+          end
+        end
 
-          when :query
-            if c.nil? || (state_override.nil? && c == "#")
-              set = url.special? ? method(:special_query_set?) : method(:query_set?)
-              url.query += buffer.each_char.map { |ch| pe(ch, set) }.join
-              buffer = +""
-              if c == "#"
-                url.fragment = +""
-                state = :fragment
-              end
-            else
-              buffer << c
-            end
+        def state_opaque_path(c)
+          if c == "?"
+            @url.query = +""
+            @state = :query
+          elsif c == "#"
+            @url.fragment = +""
+            @state = :fragment
+          elsif c == " "
+            # A space is only percent-encoded when it abuts the end of
+            # the opaque path (a following `?`/`#`); an interior space
+            # stays literal. (Trailing-at-EOF spaces are already gone
+            # via the leading/trailing strip.)
+            nxt = @chars[@ptr + 1]
+            @url.path += (nxt == "?" || nxt == "#") ? "%20" : " "
+          elsif c
+            @url.path += pe(c, method(:c0?))
+          end
+        end
 
-          when :fragment
-            url.fragment += pe(c, method(:fragment_set?)) if c
+        def state_query(c)
+          if c.nil? || (@state_override.nil? && c == "#")
+            set = @url.special? ? method(:special_query_set?) : method(:query_set?)
+            @url.query += percent_encode_after_encoding(query_encoding, @buffer, set)
+            @buffer = +""
+            if c == "#"
+              @url.fragment = +""
+              @state = :fragment
+            end
+          else
+            @buffer << c
           end
+        end
 
-          break if ptr >= len
+        # Spec query state step 1: the encoding override is ignored (forced to
+        # UTF-8) when the URL is not special, or is ws/wss.
+        def query_encoding
+          return "UTF-8" if @encoding.nil? || !@url.special?
+          return "UTF-8" if @url.scheme == "ws" || @url.scheme == "wss"
 
-          ptr += 1
+          @encoding
         end
 
-        url
+        def state_fragment(c)
+          @url.fragment += pe(c, method(:fragment_set?)) if c
+        end
       end
     end
   end