bare-url 2.5.1 → 2.5.3

package/index.js

@@ -7,6 +7,67 @@ const kind = Symbol.for('bare.url.kind')
 
 const isWindows = Bare.platform === 'win32'
 
+// Scratch buffer that the binding writes the parsed component offsets into. A
+// single shared buffer is reused across every parse.
+//
+// The offsets are copied out into fields on the URL immediately after a
+// successful parse, so nothing observes the buffer across calls.
+const components = new Uint32Array(8)
+
+// The value used for a component that is not present in the URL.
+const unset = 0xffffffff
+
+// The schemes the parser treats specially. A URL cannot be switched between a
+// special and a non-special scheme, and a backslash only terminates a host for
+// the former.
+const special = new Set(['ftp', 'file', 'http', 'https', 'ws', 'wss'])
+
+// https://url.spec.whatwg.org/#scheme-start-state
+const scheme = /^[a-z][a-z0-9+\-.]*$/
+
+// ASCII tab and newline are removed from input before it is parsed rather than
+// percent-encoded like the other C0 controls.
+const whitespaceAll = /[\t\n\r]/g
+
+// The characters that terminate a host, and so bound the value the host and
+// hostname setters accept.
+const hostEnd = /[/\\?#]/
+const hostEndOpaque = /[/?#]/
+
+// The delimiters that would let a setter's value escape the component it is
+// spliced into. Everything else is left to the reparse, which applies the full
+// percent-encode set for the component. As elsewhere in this package, each set
+// needs two patterns because test() advances a global pattern's lastIndex.
+//
+// Credentials are not run through the parser and so keep their tabs and
+// newlines, percent-encoded, rather than having them stripped.
+const userinfoDelimiter = /[\t\n\r/\\?#@:]/
+const userinfoDelimiterAll = /[\t\n\r/\\?#@:]/g
+
+const pathDelimiter = /[?#]/
+const pathDelimiterAll = /[?#]/g
+
+// A leading or trailing run of C0 control or space in a value that ends up at
+// either end of the href. The parser strips those, but only when parsing a URL
+// as a whole, so a setter has to encode its own.
+const edges = /^[\u0000-\u0020]+|[\u0000-\u0020]+$/g
+
+const escapes = {
+  '\t': '%09',
+  '\n': '%0A',
+  '\r': '%0D',
+  '/': '%2F',
+  '\\': '%5C',
+  ':': '%3A',
+  '?': '%3F',
+  '@': '%40',
+  '#': '%23'
+}
+
+// The characters that pathToFileURL() has to percent-encode itself. A backslash
+// is a path separator on Windows and so is left alone there.
+const reserved = isWindows ? /[%#?\n\r\t]/ : /[%#?\n\r\t\\]/
+
 class URL {
   static get [kind]() {
     return 0 // Compatibility version
@@ -19,11 +80,17 @@ class URL {
 
     if (base !== undefined) base = String(base)
 
-    this._components = new Uint32Array(8)
+    this._href = undefined
+    this._schemeEnd = 0
+    this._usernameEnd = 0
+    this._hostStart = 0
+    this._hostEnd = 0
+    this._pathStart = 0
+    this._queryStart = 0
+    this._fragmentStart = 0
+    this._params = null
 
     this._parse(input, base, opts.throw !== false)
-
-    if (this._href) this._params = new URLSearchParams(this.search, this)
   }
 
   get [kind]() {
@@ -37,25 +104,47 @@ class URL {
   }
 
   set href(value) {
-    this._update(value)
+    // Unlike every other setter, the href setter reports a parse failure rather
+    // than leaving the URL untouched.
+    this._parse(String(value), null, true)
 
-    this._params._parse(this.search)
+    if (this._params) this._params._parse(this.search)
   }
 
   // https://url.spec.whatwg.org/#dom-url-protocol
 
   get protocol() {
-    return this._slice(0, this._components[0]) + ':'
+    return this._slice(0, this._schemeEnd) + ':'
   }
 
   set protocol(value) {
-    this._update(this._replace(value.replace(/:+$/, ''), 0, this._components[0]))
+    value = strip(String(value))
+
+    const end = value.indexOf(':')
+
+    if (end !== -1) value = value.slice(0, end)
+
+    value = value.toLowerCase()
+
+    if (!scheme.test(value)) return
+
+    const current = this._slice(0, this._schemeEnd)
+
+    if (special.has(current) !== special.has(value)) return
+
+    if (value === 'file' && (this.username || this.password || this.port)) {
+      return
+    }
+
+    if (current === 'file' && this._hostStart === this._hostEnd) return
+
+    this._update(this._replace(value, 0, this._schemeEnd))
   }
 
   // https://url.spec.whatwg.org/#dom-url-username
 
   get username() {
-    return this._slice(this._components[0] + 3 /* :// */, this._components[1])
+    return this._slice(this._schemeEnd + 3 /* :// */, this._usernameEnd)
   }
 
   set username(value) {
@@ -63,15 +152,17 @@ class URL {
       return
     }
 
-    if (this.username === '') value += '@'
+    value = encodeUserinfo(String(value))
 
-    this._update(this._replace(value, this._components[0] + 3 /* :// */, this._components[1]))
+    if (!hasCredentials(this)) value += '@'
+
+    this._update(this._replace(value, this._schemeEnd + 3 /* :// */, this._usernameEnd))
   }
 
   // https://url.spec.whatwg.org/#dom-url-password
 
   get password() {
-    return this._href.slice(this._components[1] + 1 /* : */, this._components[2] - 1 /* @ */)
+    return this._href.slice(this._usernameEnd + 1 /* : */, this._hostStart - 1 /* @ */)
   }
 
   set password(value) {
@@ -79,26 +170,22 @@ class URL {
       return
     }
 
-    let start = this._components[1] + 1 /* : */
-    let end = this._components[2] - 1 /* @ */
+    value = ':' + encodeUserinfo(String(value))
 
-    if (this.password === '') {
-      value = ':' + value
-      start--
-    }
+    let end = this._hostStart - 1 /* @ */
 
-    if (this.username === '') {
+    if (!hasCredentials(this)) {
       value += '@'
-      end++
+      end = this._usernameEnd
     }
 
-    this._update(this._replace(value, start, end))
+    this._update(this._replace(value, this._usernameEnd, end))
   }
 
   // https://url.spec.whatwg.org/#dom-url-host
 
   get host() {
-    return this._slice(this._components[2], this._components[5])
+    return this._slice(this._hostStart, this._pathStart)
   }
 
   set host(value) {
@@ -106,15 +193,44 @@ class URL {
       return
     }
 
-    this._update(
-      this._replace(value, this._components[2], this._components[value.includes(':') ? 5 : 3])
-    )
+    const protocol = this._slice(0, this._schemeEnd)
+
+    value = truncateHost(protocol, String(value))
+
+    // An `@` would make the reparse read the value as credentials rather than
+    // as a host, so it is rejected outright.
+    if (value.includes('@')) return
+
+    const separator = portSeparator(value)
+
+    let end = this._hostEnd
+
+    // A port in the value is parsed separately so that an invalid one leaves
+    // the existing port in place rather than rejecting the host along with it.
+    if (separator !== -1) {
+      // A file URL cannot have a port, so a value carrying one is rejected
+      // rather than split.
+      if (protocol === 'file') return
+
+      const port = parsePort(value.slice(separator + 1))
+
+      value = value.slice(0, separator)
+
+      if (port !== null) {
+        value += port
+        end = this._pathStart
+      }
+    }
+
+    if (value === '' && cannotHaveEmptyHost(protocol)) return
+
+    this._update(this._replace(value, this._hostStart, end))
   }
 
   // https://url.spec.whatwg.org/#dom-url-hostname
 
   get hostname() {
-    return this._slice(this._components[2], this._components[3])
+    return this._slice(this._hostStart, this._hostEnd)
   }
 
   set hostname(value) {
@@ -122,13 +238,24 @@ class URL {
       return
     }
 
-    this._update(this._replace(value, this._components[2], this._components[3]))
+    const protocol = this._slice(0, this._schemeEnd)
+
+    value = truncateHost(protocol, String(value))
+
+    // A port cannot be set through this setter, and a value that carries one is
+    // rejected outright rather than truncated. An `@` would make the reparse
+    // read the value as credentials rather than as a host.
+    if (value.includes('@') || portSeparator(value) !== -1) return
+
+    if (value === '' && cannotHaveEmptyHost(protocol)) return
+
+    this._update(this._replace(value, this._hostStart, this._hostEnd))
   }
 
   // https://url.spec.whatwg.org/#dom-url-port
 
   get port() {
-    return this._slice(this._components[3] + 1 /* : */, this._components[5])
+    return this._slice(this._hostEnd + 1 /* : */, this._pathStart)
   }
 
   set port(value) {
@@ -136,20 +263,21 @@ class URL {
       return
     }
 
-    let start = this._components[3] + 1 /* : */
+    value = strip(String(value))
+
+    if (value !== '') {
+      value = parsePort(value)
 
-    if (this.port === '') {
-      value = ':' + value
-      start--
+      if (value === null) return
     }
 
-    this._update(this._replace(value, start, this._components[5]))
+    this._update(this._replace(value, this._hostEnd, this._pathStart))
   }
 
   // https://url.spec.whatwg.org/#dom-url-pathname
 
   get pathname() {
-    return this._slice(this._components[5], this._components[6] - 1 /* ? */)
+    return this._slice(this._pathStart, this._queryStart - 1 /* ? */)
   }
 
   set pathname(value) {
@@ -157,45 +285,65 @@ class URL {
       return
     }
 
-    if (value[0] !== '/' && value[0] !== '\\') {
+    value = encodePath(encodeEdges(String(value)))
+
+    // An empty path is left alone, as only a special scheme is required to have
+    // one and the reparse inserts it there.
+    if (value !== '' && value[0] !== '/' && value[0] !== '\\') {
       value = '/' + value
     }
 
-    this._update(this._replace(value, this._components[5], this._components[6] - 1 /* ? */))
+    this._update(this._replace(value, this._pathStart, this._queryStart - 1 /* ? */))
   }
 
   // https://url.spec.whatwg.org/#dom-url-search
 
   get search() {
-    return this._slice(this._components[6] - 1 /* ? */, this._components[7] - 1 /* # */)
+    return this._slice(this._queryStart - 1 /* ? */, this._fragmentStart - 1 /* # */)
   }
 
   set search(value) {
-    if (value && value[0] !== '?') value = '?' + value
+    value = String(value)
+
+    if (value !== '') {
+      if (value[0] === '?') value = value.slice(1)
+
+      value = '?' + encodeQuery(encodeEdges(value))
+    }
 
     this._update(
-      this._replace(value, this._components[6] - 1 /* ? */, this._components[7] - 1 /* # */)
+      this._replace(value, this._queryStart - 1 /* ? */, this._fragmentStart - 1 /* # */)
     )
-
-    this._params._parse(this.search)
   }
 
   // https://url.spec.whatwg.org/#dom-url-searchparams
 
   get searchParams() {
+    if (this._params === null) {
+      this._params = new URLSearchParams(this.search, this)
+    }
+
     return this._params
   }
 
   // https://url.spec.whatwg.org/#dom-url-hash
 
   get hash() {
-    return this._slice(this._components[7] - 1 /* # */)
+    return this._slice(this._fragmentStart - 1 /* # */)
   }
 
   set hash(value) {
-    if (value && value[0] !== '#') value = '#' + value
+    value = String(value)
+
+    // The fragment runs to the end of the URL, so nothing in it can escape into
+    // another component and no delimiter needs encoding here.
+    if (value !== '') {
+      if (value[0] === '#') value = value.slice(1)
+
+      value = '#' + encodeEdges(value)
+    }
 
-    this._update(this._replace(value, this._components[7] - 1 /* # */))
+    this._update(this._replace(value, this._fragmentStart - 1 /* # */))
   }
 
   toString() {
@@ -233,18 +381,32 @@ class URL {
   }
 
   _parse(input, base, shouldThrow) {
+    let href
+
     try {
-      this._href = binding.parse(
-        String(input),
-        base ? String(base) : null,
-        this._components,
-        shouldThrow
-      )
+      href = binding.parse(input, base || null, components, shouldThrow)
     } catch (err) {
-      if (err instanceof TypeError) throw err
+      if (err instanceof TypeError || err.code !== undefined) throw err
 
       throw errors.INVALID_URL(`Invalid URL '${input}'`, input)
     }
+
+    if (href === undefined) return
+
+    this._href = href
+    this._schemeEnd = components[0]
+    this._usernameEnd = components[1]
+    this._hostStart = components[2]
+    this._hostEnd = components[3]
+    this._pathStart = components[5]
+
+    const queryStart = components[6]
+    const fragmentStart = components[7]
+
+    const end = href.length + 1
+
+    this._queryStart = queryStart === unset ? end : queryStart
+    this._fragmentStart = fragmentStart === unset ? end : fragmentStart
   }
 
   _update(input) {
@@ -252,7 +414,11 @@ class URL {
       this._parse(input, null, true)
     } catch (err) {
       if (err instanceof TypeError) throw err
+
+      return
     }
+
+    if (this._params) this._params._parse(this.search)
   }
 }
 
@@ -268,6 +434,93 @@ function cannotHaveCredentialsOrPort(url) {
   return url.hostname === '' || url.protocol === 'file:'
 }
 
+// Whether the URL carries a userinfo section, and so an `@` before its host.
+function hasCredentials(url) {
+  return url._hostStart !== url._usernameEnd
+}
+
+// Almost no input contains any of these, so it is worth ruling all three out
+// before rewriting anything.
+function strip(value) {
+  if (value.indexOf('\t') === -1 && value.indexOf('\n') === -1 && value.indexOf('\r') === -1) {
+    return value
+  }
+
+  return value.replace(whitespaceAll, '')
+}
+
+// https://url.spec.whatwg.org/#host-state
+//
+// Host parsing stops at the first character that starts another component, so
+// anything from there on is dropped rather than spliced into the host.
+function truncateHost(protocol, value) {
+  const end = value.search(special.has(protocol) ? hostEnd : hostEndOpaque)
+
+  return end === -1 ? value : value.slice(0, end)
+}
+
+// Only a special scheme other than file has to have a host.
+function cannotHaveEmptyHost(protocol) {
+  return protocol !== 'file' && special.has(protocol)
+}
+
+// The index of the colon that separates a host from its port, disregarding the
+// colons of an IPv6 address, or -1 if the host carries no port.
+function portSeparator(host) {
+  return host.indexOf(':', host[0] === '[' ? host.indexOf(']') : 0)
+}
+
+// https://url.spec.whatwg.org/#port-state
+//
+// Parsing stops at the first character that is not a digit, so a value with no
+// leading digits, or one that overflows, leaves the port as it was.
+function parsePort(value) {
+  value = /^\d*/.exec(value)[0]
+
+  if (value === '' || Number(value) > 65535) return null
+
+  return ':' + value
+}
+
+function encodeUserinfo(value) {
+  if (!userinfoDelimiter.test(value)) return value
+
+  return value.replace(userinfoDelimiterAll, (match) => escapes[match])
+}
+
+function encodePath(value) {
+  if (!pathDelimiter.test(value)) return value
+
+  return value.replace(pathDelimiterAll, (match) => escapes[match])
+}
+
+function encodeQuery(value) {
+  if (value.indexOf('#') === -1) return value
+
+  return value.replaceAll('#', '%23')
+}
+
+// Percent-encodes a leading or trailing run of C0 control or space, which the
+// parser would otherwise strip from a value that lands at either end of the
+// href. Every component that can end a URL encodes them anyway, so this only
+// brings the encoding forward.
+function encodeEdges(value) {
+  const len = value.length
+
+  if (len === 0) return value
+  if (value.charCodeAt(0) > 0x20 && value.charCodeAt(len - 1) > 0x20) return value
+
+  return value.replace(edges, (match) => {
+    let encoded = ''
+
+    for (let i = 0, n = match.length; i < n; i++) {
+      encoded += '%' + match.charCodeAt(i).toString(16).padStart(2, '0').toUpperCase()
+    }
+
+    return encoded
+  })
+}
+
 exports.URL = URL
 exports.URLSearchParams = URLSearchParams
 
@@ -301,27 +554,35 @@ exports.fileURLToPath = function fileURLToPath(url) {
     throw errors.INVALID_URL_SCHEME('The URL must use the file: protocol')
   }
 
-  if (isWindows) {
-    if (/%2f|%5c/i.test(url.pathname)) {
-      throw errors.INVALID_FILE_URL_PATH(
-        'The file: URL path must not include encoded \\ or / characters'
-      )
-    }
-  } else {
-    if (url.hostname) {
-      throw errors.INVALID_FILE_URL_HOST("The file: URL host must be 'localhost' or empty")
-    }
+  if (!isWindows && url.hostname) {
+    throw errors.INVALID_FILE_URL_HOST("The file: URL host must be 'localhost' or empty")
+  }
+
+  const encoded = url.pathname
 
-    if (/%2f/i.test(url.pathname)) {
+  // Every check below looks for a percent encoded sequence, as does the decoding
+  // that follows, so a path without any can skip all of them.
+  const hasEncoded = encoded.includes('%')
+
+  if (hasEncoded) {
+    if (isWindows) {
+      if (/%2f|%5c/i.test(encoded)) {
+        throw errors.INVALID_FILE_URL_PATH(
+          'The file: URL path must not include encoded \\ or / characters'
+        )
+      }
+    } else if (/%2f/i.test(encoded)) {
       throw errors.INVALID_FILE_URL_PATH('The file: URL path must not include encoded / characters')
     }
-  }
 
-  if (/%00/i.test(url.pathname)) {
-    throw errors.INVALID_FILE_URL_PATH('The file: URL path must not include encoded NUL characters')
+    if (/%00/i.test(encoded)) {
+      throw errors.INVALID_FILE_URL_PATH(
+        'The file: URL path must not include encoded NUL characters'
+      )
+    }
   }
 
-  const pathname = path.normalize(decodeURIComponent(url.pathname))
+  const pathname = path.normalize(hasEncoded ? decodeURIComponent(encoded) : encoded)
 
   if (isWindows) {
     if (url.hostname) return '\\\\' + url.hostname + pathname
@@ -347,16 +608,20 @@ exports.pathToFileURL = function pathToFileURL(pathname) {
     resolved += '\\'
   }
 
-  resolved = resolved
-    .replaceAll('%', '%25') // Must be first
-    .replaceAll('#', '%23')
-    .replaceAll('?', '%3f')
-    .replaceAll('\n', '%0a')
-    .replaceAll('\r', '%0d')
-    .replaceAll('\t', '%09')
+  // Paths hardly ever contain any of these, so one pass to rule them out is
+  // cheaper than the six or seven replacements it stands in for.
+  if (reserved.test(resolved)) {
+    resolved = resolved
+      .replaceAll('%', '%25') // Must be first
+      .replaceAll('#', '%23')
+      .replaceAll('?', '%3f')
+      .replaceAll('\n', '%0a')
+      .replaceAll('\r', '%0d')
+      .replaceAll('\t', '%09')
 
-  if (!isWindows) {
-    resolved = resolved.replaceAll('\\', '%5c')
+    if (!isWindows) {
+      resolved = resolved.replaceAll('\\', '%5c')
+    }
   }
 
   return new URL('file:' + resolved)

package/lib/url-search-params.d.ts

@@ -1,22 +1,65 @@
 interface URLSearchParams extends Iterable<[name: string, value: string]> {
+  /** The total number of search parameters. */
   readonly size: number
 
+  /**
+   * Append a new `name`/`value` pair.
+   * @param name - The parameter name.
+   * @param value - The parameter value.
+   */
   append(name: string, value: string): void
+  /**
+   * Remove all pairs with `name`. If `value` is provided, only pairs with both the matching `name`
+   * and `value` are removed.
+   * @param name - The parameter name to remove.
+   * @param value - If provided, only pairs also matching this value are removed.
+   */
   delete(name: string, value?: string): void
+  /**
+   * Return the first value for `name`, or `null` if not present.
+   * @param name - The parameter name to look up.
+   */
   get(name: string): string | undefined
+  /**
+   * Return all values for `name` as an array.
+   * @param name - The parameter name to look up.
+   */
   getAll(name: string): string[]
+  /**
+   * Return `true` if a pair with `name` exists. If `value` is provided, the pair must also match
+   * `value`.
+   * @param name - The parameter name to check.
+   * @param value - If provided, the pair must also match this value.
+   */
   has(name: string, value?: string): boolean
+  /**
+   * Set the value for `name`, replacing any existing pairs with that name.
+   * @param name - The parameter name.
+   * @param value - The value to set.
+   */
   set(name: string, value: string): void
 
+  /** Returns the serialized string form. */
   toString(): string
+  /** Returns the serialized string form. Suitable for JSON serialization. */
   toJSON(): string
 }
 
 declare class URLSearchParams {
+  /**
+   * Create a new `URLSearchParams` instance. `init` may be a query string, an iterable of `[name,
+   * value]` pairs, or an object of key-value pairs.
+   * @param init - A query string, an iterable of `[name, value]` pairs, or an object of key-value
+   * pairs to initialize the params from.
+   */
   constructor(init: string | Record<string, string> | Iterable<[string, string]>)
 }
 
 declare namespace URLSearchParams {
+  /**
+   * Return `true` if `value` is a `URLSearchParams` instance.
+   * @param value - The value to test.
+   */
   export function isURLSearchParams(value: unknown): value is URLSearchParams
 }