1berry/nodejs
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

doc: deprecate url.parse()

Browse Source 
This is a documentation-deprecation only and it is possible that it will
not proceed to a runtime-deprecation any time in the foreseeable future.
But url.parse() is not standardized and prone to errors that have
security implications.

Refs: https://github.com/nodejs/node/issues/44911#issuecomment-1271631345
PR-URL: https://github.com/nodejs/node/pull/44919
Reviewed-By: Geoffrey Booth <webadmin@geoffreybooth.com>
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Rafael Gonzaga <rafael.nunu@hotmail.com>
Reviewed-By: Juan José Arboleda <soyjuanarbol@gmail.com>
Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>
Reviewed-By: Michael Dawson <midawson@redhat.com>
Reviewed-By: Danielle Adams <adamzdanielle@gmail.com>
This commit is contained in:
Rich Trott 2022-10-11 15:35:52 -07:00 committed by GitHub
parent 6686d9000b
commit 19a909902a
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 31 additions and 16 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

25
doc/api/deprecations.md
View File

@ -2288,6 +2288,9 @@ future release.
<!-- YAML
changes:
- version: REPLACEME
pr-url: https://github.com/nodejs/node/pull/44919
description: \`url.parse()` is deprecated again in DEP0169.
- version:
- v15.13.0
- v14.17.0
@ -2300,7 +2303,7 @@ changes:
Type: Deprecation revoked
The [Legacy URL API][] is deprecated. This includes [`url.format()`][],
The [legacy URL API][] is deprecated. This includes [`url.format()`][],
[`url.parse()`][], [`url.resolve()`][], and the [legacy `urlObject`][]. Please
use the [WHATWG URL API][] instead.
@ -3258,7 +3261,7 @@ changes:
description: Runtime deprecation.
-->
Type: Runtime.
Type: Runtime
The implicit suppression of uncaught exceptions in Node-API callbacks is now
deprecated.
@ -3267,7 +3270,22 @@ Set the flag [`--force-node-api-uncaught-exceptions-policy`][] to force Node.js
to emit an [`'uncaughtException'`][] event if the exception is not handled in
Node-API callbacks.
[Legacy URL API]: url.md#legacy-url-api
### DEP0169: Insecure url.parse()
<!-- YAML
changes:
- version:
- REPLACEME
pr-url: https://github.com/nodejs/node/pull/44919
description: Documentation-only deprecation.
-->
Type: Documentation-only
[`url.parse()`][] behavior is not standardized and prone to errors that
have security implications. Use the [WHATWG URL API][] instead. CVEs are not
issued for `url.parse()` vulnerabilities.
[NIST SP 800-38D]: https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-38d.pdf
[RFC 6066]: https://tools.ietf.org/html/rfc6066#section-3
[RFC 8247 Section 2.4]: https://www.rfc-editor.org/rfc/rfc8247#section-2.4
@ -3413,6 +3431,7 @@ Node-API callbacks.
[alloc_unsafe_size]: buffer.md#static-method-bufferallocunsafesize
[from_arraybuffer]: buffer.md#static-method-bufferfromarraybuffer-byteoffset-length
[from_string_encoding]: buffer.md#static-method-bufferfromstring-encoding
[legacy URL API]: url.md#legacy-url-api
[legacy `urlObject`]: url.md#legacy-urlobject
[static methods of `crypto.Certificate()`]: crypto.md#class-certificate
[subpath exports]: packages.md#subpath-exports

22
doc/api/url.md
View File

@ -27,7 +27,7 @@ The `node:url` module provides two APIs for working with URLs: a legacy API that
is Node.js specific, and a newer API that implements the same
[WHATWG URL Standard][] used by web browsers.
A comparison between the WHATWG and Legacy APIs is provided below. Above the URL
A comparison between the WHATWG and legacy APIs is provided below. Above the URL
`'https://user:pass@sub.example.com:8080/p/a/t/h?query=string#hash'`, properties
of an object returned by the legacy `url.parse()` are shown. Below it are
properties of a WHATWG `URL` object.
@ -63,7 +63,7 @@ const myURL =
new URL('https://user:pass@sub.example.com:8080/p/a/t/h?query=string#hash');
```
Parsing the URL string using the Legacy API:
Parsing the URL string using the legacy API:
```mjs
import url from 'node:url';
@ -1521,6 +1521,9 @@ The formatting process operates as follows:
<!-- YAML
added: v0.1.25
changes:
- version: REPLACEME
pr-url: https://github.com/nodejs/node/pull/44919
description: Documentation-only deprecation.
- version:
- v15.13.0
- v14.17.0
@ -1540,7 +1543,7 @@ changes:
when no query string is present.
-->
> Stability: 3 - Legacy: Use the WHATWG URL API instead.
> Stability: 0 - Deprecated: Use the WHATWG URL API instead.
* `urlString` {string} The URL string to parse.
* `parseQueryString` {boolean} If `true`, the `query` property will always
@ -1562,16 +1565,9 @@ A `URIError` is thrown if the `auth` property is present but cannot be decoded.
`url.parse()` uses a lenient, non-standard algorithm for parsing URL
strings. It is prone to security issues such as [host name spoofing][]
and incorrect handling of usernames and passwords.
`url.parse()` is an exception to most of the legacy APIs. Despite its security
concerns, it is legacy and not deprecated because it is:
* Faster than the alternative WHATWG `URL` parser.
* Easier to use with regards to relative URLs than the alternative WHATWG `URL` API.
* Widely relied upon within the npm ecosystem.
Use with caution.
and incorrect handling of usernames and passwords. Do not use with untrusted
input. CVEs are not issued for `url.parse()` vulnerabilities. Use the
[WHATWG URL][] API instead.
### `url.resolve(from, to)`