URL

To percent-encode a byte byte, return a string consisting of U+0025 (%), followed by two ASCII upper hex digits representing byte.

To percent-decode a byte sequence input, run these steps:

Using anything but UTF-8 decode without BOM when input contains bytes that are not ASCII bytes might be insecure and is not recommended.

1. Let output be an empty byte sequence.

2. For each byte byte in input:

   1. If byte is not 0x25 (%), then append byte to output.

   2. Otherwise, if byte is 0x25 (%) and the next two bytes after byte in input are not in the ranges 0x30 (0) to 0x39 (9), 0x41 (A) to 0x46 (F), and 0x61 (a) to 0x66 (f), all inclusive, append byte to output.

   3. Otherwise:

      1. Let bytePoint be the two bytes after byte in input, decoded, and then interpreted as hexadecimal number.

      2. Append a byte whose value is bytePoint to output.

      3. Skip the next two bytes in input.

3. Return output.

To percent-decode a scalar value string input:

1. Let bytes be the UTF-8 encoding of input.

2. Return the percent-decoding of bytes.

In general, percent-encoding results in a string with more U+0025 (%) code points than the input, and percent-decoding results in a byte sequence with less 0x25 (%) bytes than the input.

To percent-encode after encoding, given an encoding encoding, scalar value string input, a percentEncodeSet, and an optional boolean spaceAsPlus (default false):

1. Let encoder be the result of getting an encoder from encoding.

2. Let inputQueue be input converted to an I/O queue.

3. Let output be the empty string.

4. Let potentialError be 0.

   This needs to be a non-null value to initiate the subsequent while loop.

5. While potentialError is non-null:

   1. Let encodeOutput be an empty I/O queue.

   2. Set potentialError to the result of running encode or fail with inputQueue, encoder, and encodeOutput.

   3. For each byte of encodeOutput converted to a byte sequence:

      1. If spaceAsPlus is true and byte is 0x20 (SP), then append U+002B (+) to output and continue.

      2. Let isomorph be a code point whose value is byte’s value.

      3. Assert: percentEncodeSet includes all non-ASCII code points.

      4. If isomorph is not in percentEncodeSet, then append isomorph to output.

      5. Otherwise, percent-encode byte and append the result to output.

   4. If potentialError is non-null, then append "%26%23", followed by the shortest sequence of ASCII digits representing potentialError in base ten, followed by "%3B", to output.

      This can happen when encoding is not UTF-8.

6. Return output.

Of the possible values for the percentEncodeSet argument only two end up encoding U+0025 (%) and thus give “roundtripable data”: component percent-encode set and application/x-www-form-urlencoded percent-encode set. The other values for the percentEncodeSet argument — which happen to be used by the URL parser — leave U+0025 (%) untouched and as such it needs to be percent-encoded first in order to be properly represented.

To UTF-8 percent-encode a scalar value scalarValue using a percentEncodeSet, return the result of running percent-encode after encoding with UTF-8, scalarValue as a string, and percentEncodeSet.

To UTF-8 percent-encode a scalar value string input using a percentEncodeSet, return the result of running percent-encode after encoding with UTF-8, input, and percentEncodeSet.

To obtain the public suffix of a host host, run these steps. They return null or a domain representing a portion of host that is included on the Public Suffix List. [PSL]

1. If host is not a domain, then return null.

2. Let trailingDot be "." if host ends with "."; otherwise the empty string.

3. Let publicSuffix be the public suffix determined by running the Public Suffix List algorithm with host as domain. [PSL]

4. Assert: publicSuffix is an ASCII string that does not end with ".".

5. Return publicSuffix and trailingDot concatenated.

To obtain the registrable domain of a host host, run these steps. They return null or a domain formed by host’s public suffix and the domain label preceding it, if any.

1. If host’s public suffix is null or host’s public suffix equals host, then return null.

2. Let trailingDot be "." if host ends with "."; otherwise the empty string.

3. Let registrableDomain be the registrable domain determined by running the Public Suffix List algorithm with host as domain. [PSL]

4. Assert: registrableDomain is an ASCII string that does not end with ".".

5. Return registrableDomain and trailingDot concatenated.

The domain to ASCII algorithm, given a string domain and a boolean beStrict, runs these steps:

1. Let result be the result of running Unicode ToASCII with domain_name set to domain, CheckHyphens set to beStrict, CheckBidi set to true, CheckJoiners set to true, UseSTD3ASCIIRules set to beStrict, Transitional_Processing set to false, VerifyDnsLength set to beStrict, and IgnoreInvalidPunycode set to false. [UTS46]

   If beStrict is false, domain is an ASCII string, and strictly splitting domain on U+002E (.) does not produce any item that starts with an ASCII case-insensitive match for "xn--", this step is equivalent to ASCII lowercasing domain.

2. If result is a failure value, domain-to-ASCII validation error, return failure.

3. If beStrict is false:

   1. If result is the empty string, domain-to-ASCII validation error, return failure.

   2. If result contains a forbidden domain code point, domain-invalid-code-point validation error, return failure.

      Due to web compatibility and compatibility with non-DNS-based systems the forbidden domain code points are a subset of those disallowed when UseSTD3ASCIIRules is true. See also issue #397.

4. Assert: result is not the empty string and does not contain a forbidden domain code point.

   Unicode IDNA Compatibility Processing guarantees this holds when beStrict is true. [UTS46]

5. Return result.

This document and the web platform at large use Unicode IDNA Compatibility Processing and not IDNA2008. For instance, ☕.example becomes xn--53h.example and not failure. [UTS46] [RFC5890]

The domain to Unicode algorithm, given a domain domain and a boolean beStrict, runs these steps:

1. Let result be the result of running Unicode ToUnicode with domain_name set to domain, CheckHyphens set to beStrict, CheckBidi set to true, CheckJoiners set to true, UseSTD3ASCIIRules set to beStrict, Transitional_Processing set to false, and IgnoreInvalidPunycode set to false. [UTS46]

2. Signify domain-to-Unicode validation errors for any returned errors, and then, return result.

The host parser takes a scalar value string input with an optional boolean isOpaque (default false), and then runs these steps. They return failure or a host.

1. If input starts with U+005B ([), then:

   1. If input does not end with U+005D (]), IPv6-unclosed validation error, return failure.

   2. Return the result of IPv6 parsing input with its leading U+005B ([) and trailing U+005D (]) removed.

2. If isOpaque is true, then return the result of opaque-host parsing input.

3. Assert: input is not the empty string.

4. Let domain be the result of running UTF-8 decode without BOM on the percent-decoding of input.

   Alternatively UTF-8 decode without BOM or fail can be used, coupled with an early return for failure, as domain to ASCII fails on U+FFFD (�).

5. Let asciiDomain be the result of running domain to ASCII with domain and false.

6. If asciiDomain is failure, then return failure.

7. If asciiDomain ends in a number, then return the result of IPv4 parsing asciiDomain.

8. Return asciiDomain.

The ends in a number checker takes an ASCII string input and then runs these steps. They return a boolean.

1. Let parts be the result of strictly splitting input on U+002E (.).

2. If the last item in parts is the empty string, then:

   1. If parts’s size is 1, then return false.

   2. Remove the last item from parts.

3. Let last be the last item in parts.

4. If last is non-empty and contains only ASCII digits, then return true.

   The erroneous input "09" will be caught by the IPv4 parser at a later stage.

5. If parsing last as an IPv4 number does not return failure, then return true.

   This is equivalent to checking that last is "0X" or "0x", followed by zero or more ASCII hex digits.

6. Return false.

The IPv4 parser takes an ASCII string input and then runs these steps. They return failure or an IPv4 address.

The IPv4 parser is not to be invoked directly. Instead check that the return value of the host parser is an IPv4 address.

1. Let parts be the result of strictly splitting input on U+002E (.).

2. If the last item in parts is the empty string, then:

   1. IPv4-empty-part validation error.

   2. If parts’s size is greater than 1, then remove the last item from parts.

3. If parts’s size is greater than 4, IPv4-too-many-parts validation error, return failure.

4. Let numbers be an empty list.

5. For each part of parts:

   1. Let result be the result of parsing part.

   2. If result is failure, IPv4-non-numeric-part validation error, return failure.

   3. If result[1] is true, IPv4-non-decimal-part validation error.

   4. Append result[0] to numbers.

6. If any item in numbers is greater than 255, IPv4-out-of-range-part validation error.

7. If any but the last item in numbers is greater than 255, then return failure.

8. If the last item in numbers is greater than or equal to 256^{(5 − numbers’s size)}, then return failure.

9. Let ipv4 be the last item in numbers.

10. Remove the last item from numbers.

11. Let counter be 0.

12. For each n of numbers:

    1. Increment ipv4 by n × 256^{(3 − counter)}.

    2. Increment counter by 1.

13. Return ipv4.

The IPv4 number parser takes an ASCII string input and then runs these steps. They return failure or a tuple of a number and a boolean.

1. If input is the empty string, then return failure.

2. Let validationError be false.

3. Let R be 10.

4. If input contains at least two code points and the first two code points are either "0X" or "0x", then:

   1. Set validationError to true.

   2. Remove the first two code points from input.

   3. Set R to 16.

5. Otherwise, if input contains at least two code points and the first code point is U+0030 (0), then:

   1. Set validationError to true.

   2. Remove the first code point from input.

   3. Set R to 8.

6. If input is the empty string, then return (0, true).

7. If input contains a code point that is not a radix-R digit, then return failure.

8. Let output be the mathematical integer value that is represented by input in radix-R notation, using ASCII hex digits for digits with values 0 through 15.

9. Return (output, validationError).

The IPv6 parser takes a scalar value string input and then runs these steps. They return failure or an IPv6 address.

The IPv6 parser could in theory be invoked directly, but please discuss actually doing that with the editors of this document first.

1. Let address be a new IPv6 address whose pieces are all 0.

2. Let pieceIndex be 0.

3. Let compress be null.

4. Let pointer be a pointer for input.

5. If c is U+003A (:), then:

   1. If remaining does not start with U+003A (:), IPv6-invalid-compression validation error, return failure.

   2. Increase pointer by 2.

   3. Increase pieceIndex by 1 and then set compress to pieceIndex.

6. While c is not the EOF code point:

   1. If pieceIndex is 8, IPv6-too-many-pieces validation error, return failure.

   2. If c is U+003A (:), then:

      1. If compress is non-null, IPv6-multiple-compression validation error, return failure.

      2. Increase pointer and pieceIndex by 1, set compress to pieceIndex, and then continue.

   3. Let value and length be 0.

   4. While length is less than 4 and c is an ASCII hex digit, set value to value × 0x10 + c interpreted as hexadecimal number, and increase pointer and length by 1.

   5. If c is U+002E (.), then:

      1. If length is 0, IPv4-in-IPv6-invalid-code-point validation error, return failure.

      2. Decrease pointer by length.

      3. If pieceIndex is greater than 6, IPv4-in-IPv6-too-many-pieces validation error, return failure.

      4. Let numbersSeen be 0.

      5. While c is not the EOF code point:

         1. Let ipv4Piece be null.

         2. If numbersSeen is greater than 0, then:

            1. If c is a U+002E (.) and numbersSeen is less than 4, then increase pointer by 1.

            2. Otherwise, IPv4-in-IPv6-invalid-code-point validation error, return failure.

         3. If c is not an ASCII digit, IPv4-in-IPv6-invalid-code-point validation error, return failure.

         4. While c is an ASCII digit:

            1. Let number be c interpreted as decimal number.

            2. If ipv4Piece is null, then set ipv4Piece to number.

               Otherwise, if ipv4Piece is 0, IPv4-in-IPv6-invalid-code-point validation error, return failure.

               Otherwise, set ipv4Piece to ipv4Piece × 10 + number.

            3. If ipv4Piece is greater than 255, IPv4-in-IPv6-out-of-range-part validation error, return failure.

            4. Increase pointer by 1.

         5. Set address[pieceIndex] to address[pieceIndex] × 0x100 + ipv4Piece.

         6. Increase numbersSeen by 1.

         7. If numbersSeen is 2 or 4, then increase pieceIndex by 1.

      6. If numbersSeen is not 4, IPv4-in-IPv6-too-few-parts validation error, return failure.

      7. Break.

   6. Otherwise, if c is U+003A (:):

      1. Increase pointer by 1.

      2. If c is the EOF code point, IPv6-invalid-code-point validation error, return failure.

   7. Otherwise, if c is not the EOF code point, IPv6-invalid-code-point validation error, return failure.

   8. Set address[pieceIndex] to value.

   9. Increase pieceIndex by 1.

7. If compress is non-null, then:

   1. Let swaps be pieceIndex − compress.

   2. Set pieceIndex to 7.

   3. While pieceIndex is not 0 and swaps is greater than 0, swap address[pieceIndex] with address[compress + swaps − 1], and then decrease both pieceIndex and swaps by 1.

8. Otherwise, if compress is null and pieceIndex is not 8, IPv6-too-few-pieces validation error, return failure.

9. Return address.

The opaque-host parser takes a scalar value string input, and then runs these steps. They return failure or an opaque host.

1. If input contains a forbidden host code point, host-invalid-code-point validation error, return failure.

2. If input contains a code point that is not a URL code point and not U+0025 (%), invalid-URL-unit validation error.

3. If input contains a U+0025 (%) and the two code points following it are not ASCII hex digits, invalid-URL-unit validation error.

4. Return the result of running UTF-8 percent-encode on input using the C0 control percent-encode set.

The host serializer takes a host host and then runs these steps. They return an ASCII string.

1. If host is an IPv4 address, return the result of running the IPv4 serializer on host.

2. Otherwise, if host is an IPv6 address, return U+005B ([), followed by the result of running the IPv6 serializer on host, followed by U+005D (]).

3. Otherwise, host is a domain, opaque host, or empty host, return host.

The IPv4 serializer takes an IPv4 address address and then runs these steps. They return an ASCII string.

1. Let output be the empty string.

2. Let n be the value of address.

3. For each i in the range 1 to 4, inclusive:

   1. Prepend n % 256, serialized, to output.

   2. If i is not 4, then prepend U+002E (.) to output.

   3. Set n to floor(n / 256).

4. Return output.

The IPv6 serializer takes an IPv6 address address and then runs these steps. They return an ASCII string.

1. Let output be the empty string.

2. Let compress be the result of finding the IPv6 address compressed piece index given address.

3. Let ignore0 be false.

4. For each pieceIndex of address’s pieces’s indices:

   1. If ignore0 is true and address[pieceIndex] is 0, then continue.

   2. Otherwise, if ignore0 is true, set ignore0 to false.

   3. If compress is pieceIndex, then:

      1. Let separator be "::" if pieceIndex is 0; otherwise U+003A (:).

      2. Append separator to output.

      3. Set ignore0 to true and continue.

   4. Append address[pieceIndex], represented as the shortest possible lowercase hexadecimal number, to output.

   5. If pieceIndex is not 7, then append U+003A (:) to output.

5. Return output.

This algorithm requires the recommendation from A Recommendation for IPv6 Address Text Representation. [RFC5952]

To find the IPv6 address compressed piece index given an IPv6 address address:

1. Let longestIndex be null.

2. Let longestSize be 1.

3. Let foundIndex be null.

4. Let foundSize be 0.

5. For each pieceIndex of address’s pieces’s indices:

   1. If address’s pieces[pieceIndex] is not 0:

      1. If foundSize is greater than longestSize, then set longestIndex to foundIndex and longestSize to foundSize.

      2. Set foundIndex to null.
      3. Set foundSize to 0.

   2. Otherwise:

      1. If foundIndex is null, then set foundIndex to pieceIndex.

      2. Increment foundSize by 1.

6. If foundSize is greater than longestSize, then return foundIndex.

7. Return longestIndex.

In 0:f:0:0:f:f:0:0 it would point to the second 0.

To determine whether a host A equals host B, return true if A is B, and false otherwise.

To shorten a url’s path:

1. Assert: url does not have an opaque path.

2. Let path be url’s path.

3. If url’s scheme is "file", path’s size is 1, and path[0] is a normalized Windows drive letter, then return.

4. Remove path’s last item, if any.

The URL parser takes a scalar value string input, with an optional null or base URL base (default null) and an optional encoding encoding (default UTF-8), and then runs these steps:

Non-web-browser implementations only need to implement the basic URL parser.

How user input in the web browser’s address bar is converted to a URL record is out-of-scope of this standard. This standard does include URL rendering requirements as they pertain trust decisions.

1. Let url be the result of running the basic URL parser on input with base and encoding.

2. If url is failure, return failure.

3. If url’s scheme is not "blob", return url.

4. Set url’s blob URL entry to the result of resolving the blob URL url, if that did not return failure, and null otherwise.

5. Return url.

The basic URL parser takes a scalar value string input, with an optional null or base URL base (default null), an optional encoding encoding (default UTF-8), an optional URL url, and an optional state override state override, and then runs these steps:

1. If url is not given:

   1. Set url to a new URL.

   2. If input contains any leading or trailing C0 control or space, invalid-URL-unit validation error.

   3. Remove any leading and trailing C0 control or space from input.

2. If input contains any ASCII tab or newline, invalid-URL-unit validation error.

3. Remove all ASCII tab or newline from input.

4. Let state be state override if given, or scheme start state otherwise.

5. Set encoding to the result of getting an output encoding from encoding.

6. Let buffer be the empty string.

7. Let atSignSeen, insideBrackets, and passwordTokenSeen be false.

8. Let pointer be a pointer for input.

9. Keep running the following state machine by switching on state. If after a run pointer points to the EOF code point, go to the next step. Otherwise, increase pointer by 1 and continue with the state machine.

   scheme start state

   1. If c is an ASCII alpha, append c, lowercased, to buffer, and set state to scheme state.

   2. Otherwise, if state override is not given, set state to no scheme state and decrease pointer by 1.

   3. Otherwise, return failure.

      This indication of failure is used exclusively by the Location object’s protocol setter.

   scheme state

   1. If c is an ASCII alphanumeric, U+002B (+), U+002D (-), or U+002E (.), append c, lowercased, to buffer.

   2. Otherwise, if c is U+003A (:), then:

      1. If state override is given, then:

         1. If url’s scheme is a special scheme and buffer is not a special scheme, then return.

         2. If url’s scheme is not a special scheme and buffer is a special scheme, then return.

         3. If url includes credentials or has a non-null port, and buffer is "file", then return.

         4. If url’s scheme is "file" and its host is an empty host, then return.

      2. Set url’s scheme to buffer.

      3. If state override is given, then:

         1. If url’s port is url’s scheme’s default port, then set url’s port to null.

         2. Return.

      4. Set buffer to the empty string.

      5. If url’s scheme is "file", then:

         1. If remaining does not start with "//", special-scheme-missing-following-solidus validation error.

         2. Set state to file state.

      6. Otherwise, if url is special, base is non-null, and base’s scheme is url’s scheme:

         1. Assert: base is special (and therefore does not have an opaque path).

         2. Set state to special relative or authority state.

      7. Otherwise, if url is special, set state to special authority slashes state.

      8. Otherwise, if remaining starts with an U+002F (/), set state to path or authority state and increase pointer by 1.

      9. Otherwise, set url’s path to the empty string and set state to opaque path state.

   3. Otherwise, if state override is not given, set buffer to the empty string, state to no scheme state, and start over (from the first code point in input).

   4. Otherwise, return failure.

      This indication of failure is used exclusively by the Location object’s protocol setter. Furthermore, the non-failure termination earlier in this state is an intentional difference for defining that setter.

   no scheme state

   1. If base is null, or base has an opaque path and c is not U+0023 (#), missing-scheme-non-relative-URL validation error, return failure.

   2. Otherwise, if base has an opaque path and c is U+0023 (#), set url’s scheme to base’s scheme, url’s path to base’s path, url’s query to base’s query, url’s fragment to the empty string, and set state to fragment state.

   3. Otherwise, if base’s scheme is not "file", set state to relative state and decrease pointer by 1.

   4. Otherwise, set state to file state and decrease pointer by 1.

   special relative or authority state

   1. If c is U+002F (/) and remaining starts with U+002F (/), then set state to special authority ignore slashes state and increase pointer by 1.

   2. Otherwise, special-scheme-missing-following-solidus validation error, set state to relative state and decrease pointer by 1.

   path or authority state

   1. If c is U+002F (/), then set state to authority state.

   2. Otherwise, set state to path state, and decrease pointer by 1.

   relative state

   1. Assert: base’s scheme is not "file".

   2. Set url’s scheme to base’s scheme.

   3. If c is U+002F (/), then set state to relative slash state.

   4. Otherwise, if url is special and c is U+005C (\), invalid-reverse-solidus validation error, set state to relative slash state.

   5. Otherwise:

      1. Set url’s username to base’s username, url’s password to base’s password, url’s host to base’s host, url’s port to base’s port, url’s path to a clone of base’s path, and url’s query to base’s query.

      2. If c is U+003F (?), then set url’s query to the empty string, and state to query state.

      3. Otherwise, if c is U+0023 (#), set url’s fragment to the empty string and state to fragment state.

      4. Otherwise, if c is not the EOF code point:

         1. Set url’s query to null.

         2. Shorten url’s path.

         3. Set state to path state and decrease pointer by 1.

   relative slash state

   1. If url is special and c is U+002F (/) or U+005C (\), then:

      1. If c is U+005C (\), invalid-reverse-solidus validation error.

      2. Set state to special authority ignore slashes state.

   2. Otherwise, if c is U+002F (/), then set state to authority state.

   3. Otherwise, set url’s username to base’s username, url’s password to base’s password, url’s host to base’s host, url’s port to base’s port, state to path state, and then, decrease pointer by 1.

   special authority slashes state

   1. If c is U+002F (/) and remaining starts with U+002F (/), then set state to special authority ignore slashes state and increase pointer by 1.

   2. Otherwise, special-scheme-missing-following-solidus validation error, set state to special authority ignore slashes state and decrease pointer by 1.

   special authority ignore slashes state

   1. If c is neither U+002F (/) nor U+005C (\), then set state to authority state and decrease pointer by 1.

   2. Otherwise, special-scheme-missing-following-solidus validation error.

   authority state

   1. If c is U+0040 (@), then:

      1. Invalid-credentials validation error.

      2. If atSignSeen is true, then prepend "%40" to buffer.

      3. Set atSignSeen to true.

      4. For each codePoint in buffer:

         1. If codePoint is U+003A (:) and passwordTokenSeen is false, then set passwordTokenSeen to true and continue.

         2. Let encodedCodePoints be the result of running UTF-8 percent-encode codePoint using the userinfo percent-encode set.

         3. If passwordTokenSeen is true, then append encodedCodePoints to url’s password.

         4. Otherwise, append encodedCodePoints to url’s username.

      5. Set buffer to the empty string.

   2. Otherwise, if one of the following is true:

      • c is the EOF code point, U+002F (/), U+003F (?), or U+0023 (#)

      • url is special and c is U+005C (\)

      then:

      1. If atSignSeen is true and buffer is the empty string, host-missing validation error, return failure.

      2. Decrease pointer by buffer’s code point length + 1, set buffer to the empty string, and set state to host state.

   3. Otherwise, append c to buffer.

   host state

   hostname state

   1. If state override is given and url’s scheme is "file", then decrease pointer by 1 and set state to file host state.

   2. Otherwise, if c is U+003A (:) and insideBrackets is false, then:

      1. If buffer is the empty string, host-missing validation error, return failure.

      2. If state override is given and state override is hostname state, then return.

      3. Let host be the result of host parsing buffer with url is not special.

      4. If host is failure, then return failure.

      5. Set url’s host to host, buffer to the empty string, and state to port state.

   3. Otherwise, if one of the following is true:

      • c is the EOF code point, U+002F (/), U+003F (?), or U+0023 (#)

      • url is special and c is U+005C (\)

      then decrease pointer by 1, and then:

      1. If url is special and buffer is the empty string, host-missing validation error, return failure.

      2. Otherwise, if state override is given, buffer is the empty string, and either url includes credentials or url’s port is non-null, return.

      3. Let host be the result of host parsing buffer with url is not special.

      4. If host is failure, then return failure.

      5. Set url’s host to host, buffer to the empty string, and state to path start state.

      6. If state override is given, then return.

   4. Otherwise:

      1. If c is U+005B ([), then set insideBrackets to true.

      2. If c is U+005D (]), then set insideBrackets to false.

      3. Append c to buffer.

   port state

   1. If c is an ASCII digit, append c to buffer.

   2. Otherwise, if one of the following is true:

      • c is the EOF code point, U+002F (/), U+003F (?), or U+0023 (#)

      • url is special and c is U+005C (\)

      • state override is given

      then:

      1. If buffer is not the empty string, then:

         1. Let port be the mathematical integer value that is represented by buffer in radix-10 using ASCII digits for digits with values 0 through 9.

         2. If port is not a 16-bit unsigned integer, port-out-of-range validation error, return failure.

         3. Set url’s port to null, if port is url’s scheme’s default port; otherwise to port.

         4. Set buffer to the empty string.

      2. If state override is given, then return.

      3. Set state to path start state and decrease pointer by 1.

   3. Otherwise, port-invalid validation error, return failure.

   file state

   1. Set url’s scheme to "file".

   2. Set url’s host to the empty string.

   3. If c is U+002F (/) or U+005C (\), then:

      1. If c is U+005C (\), invalid-reverse-solidus validation error.

      2. Set state to file slash state.

   4. Otherwise, if base is non-null and base’s scheme is "file":

      1. Set url’s host to base’s host, url’s path to a clone of base’s path, and url’s query to base’s query.

      2. If c is U+003F (?), then set url’s query to the empty string and state to query state.

      3. Otherwise, if c is U+0023 (#), set url’s fragment to the empty string and state to fragment state.

      4. Otherwise, if c is not the EOF code point:

         1. Set url’s query to null.

         2. If the code point substring from pointer to the end of input does not start with a Windows drive letter, then shorten url’s path.

         3. Otherwise:

            1. File-invalid-Windows-drive-letter validation error.

            2. Set url’s path to « ».

            This is a (platform-independent) Windows drive letter quirk.

         4. Set state to path state and decrease pointer by 1.

   5. Otherwise, set state to path state, and decrease pointer by 1.

   file slash state

   1. If c is U+002F (/) or U+005C (\), then:

      1. If c is U+005C (\), invalid-reverse-solidus validation error.

      2. Set state to file host state.

   2. Otherwise:

      1. If base is non-null and base’s scheme is "file", then:

         1. Set url’s host to base’s host.

         2. If the code point substring from pointer to the end of input does not start with a Windows drive letter and base’s path[0] is a normalized Windows drive letter, then append base’s path[0] to url’s path.

            This is a (platform-independent) Windows drive letter quirk.

      2. Set state to path state, and decrease pointer by 1.

   file host state

   1. If c is the EOF code point, U+002F (/), U+005C (\), U+003F (?), or U+0023 (#), then decrease pointer by 1 and then:

      1. If state override is not given and buffer is a Windows drive letter, file-invalid-Windows-drive-letter-host validation error, set state to path state.

         This is a (platform-independent) Windows drive letter quirk. buffer is not reset here and instead used in the path state.

      2. Otherwise, if buffer is the empty string, then:

         1. Set url’s host to the empty string.

         2. If state override is given, then return.

         3. Set state to path start state.

      3. Otherwise, run these steps:

         1. Let host be the result of host parsing buffer with url is not special.

         2. If host is failure, then return failure.

         3. If host is "localhost", then set host to the empty string.

         4. Set url’s host to host.

         5. If state override is given, then return.

         6. Set buffer to the empty string and state to path start state.

   2. Otherwise, append c to buffer.

   path start state

   1. If url is special, then:

      1. If c is U+005C (\), invalid-reverse-solidus validation error.

      2. Set state to path state.

      3. If c is neither U+002F (/) nor U+005C (\), then decrease pointer by 1.

   2. Otherwise, if state override is not given and c is U+003F (?), set url’s query to the empty string and state to query state.

   3. Otherwise, if state override is not given and c is U+0023 (#), set url’s fragment to the empty string and state to fragment state.

   4. Otherwise, if c is not the EOF code point:

      1. Set state to path state.

      2. If c is not U+002F (/), then decrease pointer by 1.

   5. Otherwise, if state override is given and url’s host is null, append the empty string to url’s path.

   path state

   1. If one of the following is true:

      • c is the EOF code point or U+002F (/)

      • url is special and c is U+005C (\)

      • state override is not given and c is U+003F (?) or U+0023 (#)

      then:

      1. If url is special and c is U+005C (\), invalid-reverse-solidus validation error.

      2. If buffer is a double-dot URL path segment, then:

         1. Shorten url’s path.

         2. If neither c is U+002F (/), nor url is special and c is U+005C (\), append the empty string to url’s path.

            This means that for input /usr/.. the result is / and not a lack of a path.

      3. Otherwise, if buffer is a single-dot URL path segment and if neither c is U+002F (/), nor url is special and c is U+005C (\), append the empty string to url’s path.

      4. Otherwise, if buffer is not a single-dot URL path segment, then:

         1. If url’s scheme is "file", url’s path is empty, and buffer is a Windows drive letter, then replace the second code point in buffer with U+003A (:).

            This is a (platform-independent) Windows drive letter quirk.

         2. Append buffer to url’s path.

      5. Set buffer to the empty string.

      6. If c is U+003F (?), then set url’s query to the empty string and state to query state.

      7. If c is U+0023 (#), then set url’s fragment to the empty string and state to fragment state.

   2. Otherwise, run these steps:

      1. If c is not a URL code point and not U+0025 (%), invalid-URL-unit validation error.

      2. If c is U+0025 (%) and remaining does not start with two ASCII hex digits, invalid-URL-unit validation error.

      3. UTF-8 percent-encode c using the path percent-encode set and append the result to buffer.

   opaque path state

   1. If c is U+003F (?), then set url’s query to the empty string and state to query state.

   2. Otherwise, if c is U+0023 (#), then set url’s fragment to the empty string and state to fragment state.

   3. Otherwise:

      1. If c is not the EOF code point, not a URL code point, and not U+0025 (%), invalid-URL-unit validation error.

      2. If c is U+0025 (%) and remaining does not start with two ASCII hex digits, invalid-URL-unit validation error.

      3. If c is not the EOF code point, UTF-8 percent-encode c using the C0 control percent-encode set and append the result to url’s path.

   query state

   1. If encoding is not UTF-8 and one of the following is true:

      • url is not special

      • url’s scheme is "ws" or "wss"

      then set encoding to UTF-8.

   2. If one of the following is true:

      • state override is not given and c is U+0023 (#)

      • c is the EOF code point

      then:

      1. Let queryPercentEncodeSet be the special-query percent-encode set if url is special; otherwise the query percent-encode set.

      2. Percent-encode after encoding, with encoding, buffer, and queryPercentEncodeSet, and append the result to url’s query.

         This operation cannot be invoked code-point-for-code-point due to the stateful ISO-2022-JP encoder.

      3. Set buffer to the empty string.

      4. If c is U+0023 (#), then set url’s fragment to the empty string and state to fragment state.

   3. Otherwise, if c is not the EOF code point:

      1. If c is not a URL code point and not U+0025 (%), invalid-URL-unit validation error.

      2. If c is U+0025 (%) and remaining does not start with two ASCII hex digits, invalid-URL-unit validation error.

      3. Append c to buffer.

   fragment state

   1. If c is not the EOF code point, then:

      1. If c is not a URL code point and not U+0025 (%), invalid-URL-unit validation error.

      2. If c is U+0025 (%) and remaining does not start with two ASCII hex digits, invalid-URL-unit validation error.

      3. UTF-8 percent-encode c using the fragment percent-encode set and append the result to url’s fragment.

10. Return url.

To set the username given a url and username, set url’s username to the result of running UTF-8 percent-encode on username using the userinfo percent-encode set.

To set the password given a url and password, set url’s password to the result of running UTF-8 percent-encode on password using the userinfo percent-encode set.

The URL serializer takes a URL url, with an optional boolean exclude fragment (default false), and then runs these steps. They return an ASCII string.

1. Let output be url’s scheme and U+003A (:) concatenated.

2. If url’s host is non-null:

   1. Append "//" to output.

   2. If url includes credentials, then:

      1. Append url’s username to output.

      2. If url’s password is not the empty string, then append U+003A (:), followed by url’s password, to output.

      3. Append U+0040 (@) to output.

   3. Append url’s host, serialized, to output.

   4. If url’s port is non-null, append U+003A (:) followed by url’s port, serialized, to output.

3. If url’s host is null, url does not have an opaque path, url’s path’s size is greater than 1, and url’s path[0] is the empty string, then append U+002F (/) followed by U+002E (.) to output.

   This prevents web+demo:/.//not-a-host/ or web+demo:/path/..//not-a-host/, when parsed and then serialized, from ending up as web+demo://not-a-host/ (they end up as web+demo:/.//not-a-host/).

4. Append the result of URL path serializing url to output.

5. If url’s query is non-null, append U+003F (?), followed by url’s query, to output.

6. If exclude fragment is false and url’s fragment is non-null, then append U+0023 (#), followed by url’s fragment, to output.

7. Return output.

The URL path serializer takes a URL url and then runs these steps. They return an ASCII string.

1. If url has an opaque path, then return url’s path.

2. Let output be the empty string.

3. For each segment of url’s path: append U+002F (/) followed by segment to output.

4. Return output.

To determine whether a URL A equals URL B, with an optional boolean exclude fragments (default false), run these steps:

1. Let serializedA be the result of serializing A, with exclude fragment set to exclude fragments.

2. Let serializedB be the result of serializing B, with exclude fragment set to exclude fragments.

3. Return true if serializedA is serializedB; otherwise false.

The origin of a URL url is the origin returned by running these steps, switching on url’s scheme:

"blob"

1. If url’s blob URL entry is non-null, then return url’s blob URL entry’s environment’s origin.

2. Let pathURL be the result of parsing the result of URL path serializing url.

3. If pathURL is failure, then return a new opaque origin.

4. If pathURL’s scheme is "http", "https", or "file", then return pathURL’s origin.

5. Return a new opaque origin.

The origin of blob:https://whatwg.org/d0360e2f-caee-469f-9a2f-87d5b0456f6f is the tuple origin ("https", "whatwg.org", null, null).

"ftp"

"http"

"https"

"ws"

"wss"

Return the tuple origin (url’s scheme, url’s host, url’s port, null).

"file"

Unfortunate as it is, this is left as an exercise to the reader. When in doubt, return a new opaque origin.

Otherwise

Return a new opaque origin.

This does indeed mean that these URLs cannot be same origin with themselves.

The application/x-www-form-urlencoded parser takes a byte sequence input, and then runs these steps:

1. Let sequences be the result of splitting input on 0x26 (&).

2. Let output be an initially empty list of name-value tuples where both name and value hold a string.

3. For each byte sequence bytes in sequences:

   1. If bytes is the empty byte sequence, then continue.

   2. If bytes contains a 0x3D (=), then let name be the bytes from the start of bytes up to but excluding its first 0x3D (=), and let value be the bytes, if any, after the first 0x3D (=) up to the end of bytes. If 0x3D (=) is the first byte, then name will be the empty byte sequence. If it is the last, then value will be the empty byte sequence.

   3. Otherwise, let name have the value of bytes and let value be the empty byte sequence.

   4. Replace any 0x2B (+) in name and value with 0x20 (SP).

   5. Let nameString and valueString be the result of running UTF-8 decode without BOM on the percent-decoding of name and value, respectively.

   6. Append (nameString, valueString) to output.

4. Return output.

The application/x-www-form-urlencoded serializer takes a list of name-value tuples tuples, with an optional encoding encoding (default UTF-8), and then runs these steps. They return an ASCII string.

1. Set encoding to the result of getting an output encoding from encoding.

2. Let output be the empty string.

3. For each tuple of tuples:

   1. Assert: tuple’s name and tuple’s value are scalar value strings.

   2. Let name be the result of running percent-encode after encoding with encoding, tuple’s name, the application/x-www-form-urlencoded percent-encode set, and true.

   3. Let value be the result of running percent-encode after encoding with encoding, tuple’s value, the application/x-www-form-urlencoded percent-encode set, and true.

   4. If output is not the empty string, then append U+0026 (&) to output.

   5. Append name, followed by U+003D (=), followed by value, to output.
4. Return output.

To potentially strip trailing spaces from an opaque path given a URL object url:

1. If url’s URL does not have an opaque path, then return.

2. If url’s URL’s fragment is non-null, then return.

3. If url’s URL’s query is non-null, then return.

4. Remove all trailing U+0020 SPACE code points from url’s URL’s path.

The API URL parser takes a scalar value string url and an optional null-or-scalar value string base (default null), and then runs these steps:

1. Let parsedBase be null.

2. If base is non-null:

   1. Set parsedBase to the result of running the basic URL parser on base.

   2. If parsedBase is failure, then return failure.

3. Return the result of running the basic URL parser on url with parsedBase.

To initialize a URL object url with a URL urlRecord:

1. Let query be urlRecord’s query, if that is non-null; otherwise the empty string.

2. Set url’s URL to urlRecord.

3. Set url’s query object to a new URLSearchParams object.

4. Initialize url’s query object with query.

5. Set url’s query object’s URL object to url.

The new URL(url, base) constructor steps are:

1. Let parsedURL be the result of running the API URL parser on url with base, if given.

2. If parsedURL is failure, then throw a TypeError.

3. Initialize this with parsedURL.

The static parse(url, base) method steps are:

1. Let parsedURL be the result of running the API URL parser on url with base, if given.

2. If parsedURL is failure, then return null.

3. Let url be a new URL object.

4. Initialize url with parsedURL.

5. Return url.

The static canParse(url, base) method steps are:

1. Let parsedURL be the result of running the API URL parser on url with base, if given.

2. If parsedURL is failure, then return false.

3. Return true.

The href getter steps and the toJSON() method steps are to return the serialization of this’s URL.

The href setter steps are:

1. Let parsedURL be the result of running the basic URL parser on the given value.

2. If parsedURL is failure, then throw a TypeError.

3. Set this’s URL to parsedURL.

4. Empty this’s query object’s list.

5. Let query be this’s URL’s query.

6. If query is non-null, then set this’s query object’s list to the result of parsing query.

The origin getter steps are to return the serialization of this’s URL’s origin. [HTML]

The protocol getter steps are to return this’s URL’s scheme, followed by U+003A (:).

The protocol setter steps are to basic URL parse the given value, followed by U+003A (:), with this’s URL as url and scheme start state as state override.

The username getter steps are to return this’s URL’s username.

The username setter steps are:

1. If this’s URL cannot have a username/password/port, then return.

2. Set the username given this’s URL and the given value.

The password getter steps are to return this’s URL’s password.

The password setter steps are:

1. If this’s URL cannot have a username/password/port, then return.

2. Set the password given this’s URL and the given value.

The host getter steps are:

1. Let url be this’s URL.

2. If url’s host is null, then return the empty string.

3. If url’s port is null, return url’s host, serialized.

4. Return url’s host, serialized, followed by U+003A (:) and url’s port, serialized.

The host setter steps are:

1. If this’s URL has an opaque path, then return.

2. Basic URL parse the given value with this’s URL as url and host state as state override.

If the given value for the host setter lacks a port, this’s URL’s port will not change. This can be unexpected as host getter does return a URL-port string so one might have assumed the setter to always "reset" both.

The hostname getter steps are:

1. If this’s URL’s host is null, then return the empty string.

2. Return this’s URL’s host, serialized.

The hostname setter steps are:

1. If this’s URL has an opaque path, then return.

2. Basic URL parse the given value with this’s URL as url and hostname state as state override.

The port getter steps are:

1. If this’s URL’s port is null, then return the empty string.

2. Return this’s URL’s port, serialized.

The port setter steps are:

1. If this’s URL cannot have a username/password/port, then return.

2. If the given value is the empty string, then set this’s URL’s port to null.

3. Otherwise, basic URL parse the given value with this’s URL as url and port state as state override.

The pathname getter steps are to return the result of URL path serializing this’s URL.

The pathname setter steps are:

1. If this’s URL has an opaque path, then return.

2. Empty this’s URL’s path.

3. Basic URL parse the given value with this’s URL as url and path start state as state override.

The search getter steps are:

1. If this’s URL’s query is either null or the empty string, then return the empty string.

2. Return U+003F (?), followed by this’s URL’s query.

The search setter steps are:

1. Let url be this’s URL.

2. If the given value is the empty string:

   1. Set url’s query to null.

   2. Empty this’s query object’s list.

   3. Potentially strip trailing spaces from an opaque path with this.

   4. Return.

3. Let input be the given value with a single leading U+003F (?) removed, if any.

4. Set url’s query to the empty string.

5. Basic URL parse input with url as url and query state as state override.

6. Set this’s query object’s list to the result of parsing input.

The search setter has the potential to remove trailing U+0020 SPACE code points from this’s URL’s path. It does this so that running the URL parser on the output of running the URL serializer on this’s URL does not yield a URL that is not equal.

The searchParams getter steps are to return this’s query object.

The hash getter steps are:

1. If this’s URL’s fragment is either null or the empty string, then return the empty string.

2. Return U+0023 (#), followed by this’s URL’s fragment.

The hash setter steps are:

1. If the given value is the empty string:

   1. Set this’s URL’s fragment to null.

   2. Potentially strip trailing spaces from an opaque path with this.

   3. Return.

2. Let input be the given value with a single leading U+0023 (#) removed, if any.

3. Set this’s URL’s fragment to the empty string.

4. Basic URL parse input with this’s URL as url and fragment state as state override.

The hash setter has the potential to change this’s URL’s path in a manner equivalent to the search setter.

To initialize a URLSearchParams object query with init:

1. If init is a sequence, then for each innerSequence of init:

   1. If innerSequence’s size is not 2, then throw a TypeError.

   2. Append (innerSequence[0], innerSequence[1]) to query’s list.

2. Otherwise, if init is a record, then for each name → value of init, append (name, value) to query’s list.

3. Otherwise:

   1. Assert: init is a string.

   2. Set query’s list to the result of parsing init.

To update a URLSearchParams object query:

1. If query’s URL object is null, then return.

2. Let serializedQuery be the serialization of query’s list.

3. If serializedQuery is the empty string, then set serializedQuery to null.

4. Set query’s URL object’s URL’s query to serializedQuery.

5. If serializedQuery is null, then potentially strip trailing spaces from an opaque path with query’s URL object.

The new URLSearchParams(init) constructor steps are:

1. If init is a string and starts with U+003F (?), then remove the first code point from init.

2. Initialize this with init.

The size getter steps are to return this’s list’s size.

The append(name, value) method steps are:

1. Append (name, value) to this’s list.

2. Update this.

The delete(name, value) method steps are:

1. If value is given, then remove all tuples whose name is name and value is value from this’s list.

2. Otherwise, remove all tuples whose name is name from this’s list.

3. Update this.

The get(name) method steps are to return the value of the first tuple whose name is name in this’s list, if there is such a tuple; otherwise null.

The getAll(name) method steps are to return the values of all tuples whose name is name in this’s list, in list order; otherwise the empty sequence.

The has(name, value) method steps are:

1. If value is given and there is a tuple whose name is name and value is value in this’s list, then return true.

2. If value is not given and there is a tuple whose name is name in this’s list, then return true.

3. Return false.

The set(name, value) method steps are:

1. If this’s list contains any tuples whose name is name, then set the value of the first such tuple to value and remove the others.

2. Otherwise, append (name, value) to this’s list.

3. Update this.

The sort() method steps are:

1. Sort all tuples in this’s list, if any, by their names. Sorting must be done by comparison of code units. The relative order between tuples with equal names must be preserved.

2. Update this.