These changes are in preparation for enabling a JSDoc lint rule.
PR-URL: https://github.com/nodejs/node/pull/41109
Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>
Reviewed-By: Michaël Zasso <targos@protonmail.com>
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
PR-URL: https://github.com/nodejs/node/pull/40403
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
Reviewed-By: Zijian Liu <lxxyxzj@gmail.com>
Reviewed-By: Michaël Zasso <targos@protonmail.com>
Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>
Main changes:
- Replace current HTML anchor generation to match
header anchor generation in Github markdown.
- Remove unnecessary double namespacing on generated anchors/links (E.G.
`esm.md#loaders` instead of `esm.md#esm_loaders`).
- Anchors/links are automatically prefixed with their respective modules
when concatenated for usage in `all.html`.
Benefits:
- All anchor links within and between markdown API docs actually work.
- Adding new anchor links no longer requires contributors to generate
the HTML docs first to look up the correct anchors.
- Anchors are much shorter.
- All previous anchor links are preserved by generating hidden legacy
anchors.
PR-URL: https://github.com/nodejs/node/pull/39304
Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>
Signed-off-by: James M Snell <jasnell@gmail.com>
PR-URL: https://github.com/nodejs/node/pull/39693
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
Reviewed-By: Bradley Farias <bradley.meck@gmail.com>
Reviewed-By: Stephen Belanger <admin@stephenbelanger.com>
PR-URL: https://github.com/nodejs/node/pull/39666
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Tobias Nießen <tniessen@tnie.de>
There are many things called `url` in this page including `url` module,
`URL` instances, etc.
The original example was not clear where these methods come from.
PR-URL: https://github.com/nodejs/node/pull/38645
Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
The legacy url.parse() function attempts to convert Unicode domains
(IDNs) into their ASCII/Punycode form through the use of the toASCII
function. However, toASCII can introduce or remove various characters
that at best invalidate the parsed URL, and at worst cause hostname
spoofing:
url.parse('http://bad.c℀.good.com/').href === 'http://bad.ca/c.good.com/'
(from [1])
url.parse('http://\u00AD/bad.com').href === 'http:///bad.com/'
While changes to the legacy URL parser are discouraged in general, the
security implications here outweigh the desire for strict compatibility.
This is since this commit only changes behavior when non-ASCII
characters appear in the hostname, an unusual situation for most use
cases. Additionally, despite the availability of the WHATWG URL API,
url.parse remain widely deployed in the Node.js ecosystem, as
exemplified by the recent un-deprecation of the legacy API.
This change is similar in spirit to CPython 3.8's change [2] fixing
bpo-36216 [3] aka CVE-2019-9636, which also occurred despite potential
compatibility concerns.
[1]: https://hackerone.com/reports/678487
[2]: 16e6f7dee7
[3]: https://bugs.python.org/issue36216
PR-URL: https://github.com/nodejs/node/pull/38631
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
Reviewed-By: Joyee Cheung <joyeec9h3@gmail.com>
Notable Changes:
Diagnostics channel (experimental module):
`diagnostics_channel` is a new experimental module that provides an API
to create named channels to report arbitrary message data for
diagnostics purposes.
The module was initially introduced in Node.js v15.1.0 and is
backported to v14.17.0 to enable testing it at a larger scale.
With `diagnostics_channel`, Node.js core and module authors can publish
contextual data about what they are doing at a given time. This could
be the hostname and query string of a mysql query, for example. Just
create a named channel with `dc.channel(name)` and call
`channel.publish(data)` to send the data to any listeners to that
channel.
```js
const dc = require('diagnostics_channel');
const channel = dc.channel('mysql.query');
MySQL.prototype.query = function query(queryString, values, callback) {
// Broadcast query information whenever a query is made
channel.publish({
query: queryString,
host: this.hostname,
});
this.doQuery(queryString, values, callback);
};
```
Channels are like one big global event emitter but are split into
separate objects to ensure they get the best performance. If nothing is
listening to the channel, the publishing overhead should be as close to
zero as possible. Consuming channel data is as easy as using
`channel.subscribe(listener)` to run a function whenever a message is
published to that channel.
```js
const dc = require('diagnostics_channel');
const channel = dc.channel('mysql.query');
channel.subscribe(({ query, host }) => {
console.log(`mysql query to ${host}: ${query}`);
});
```
The data captured can be used to provide context for what an app is
doing at a given time. This can be used for things like augmenting
tracing data, tracking network and filesystem activity, logging
queries, and many other things. It's also a very useful data source
for diagnostics tools to provide a clearer picture of exactly what the
application is doing at a given point in the data they are presenting.
Contributed by Stephen Belanger (https://github.com/nodejs/node/pull/34895).
UUID support in the crypto module:
The new `crypto.randomUUID()` method now allows to generate random
[RFC 4122](https://www.rfc-editor.org/rfc/rfc4122.txt) Version 4
UUID strings:
```js
const { randomUUID } = require('crypto');
console.log(randomUUID());
// 'aa7c91a1-f8fc-4339-b9db-f93fc7233429'
```
Contributed by James M Snell (https://github.com/nodejs/node/pull/36729).
Experimental support for `AbortController` and `AbortSignal`:
Node.js 14.17.0 adds experimental partial support for `AbortController`
and `AbortSignal`.
Both constructors can be enabled globally using the
`--experimental-abortcontroller` flag.
Additionally, several Node.js APIs have been updated to support
`AbortSignal` for cancellation.
It is not mandatory to use the built-in constructors with them. Any
spec-compliant third-party alternatives should be compatible.
`AbortSignal` support was added to the following methods:
* `child_process.exec`
* `child_process.execFile`
* `child_process.fork`
* `child_process.spawn`
* `dgram.createSocket`
* `events.on`
* `events.once`
* `fs.readFile`
* `fs.watch`
* `fs.writeFile`
* `http.request`
* `https.request`
* `http2Session.request`
* The promisified variants of `setImmediate` and `setTimeout`
Other notable changes:
* doc:
* revoke deprecation of legacy url, change status to legacy (James M Snell) (https://github.com/nodejs/node/pull/37784)
* add legacy status to stability index (James M Snell) (https://github.com/nodejs/node/pull/37784)
* upgrade stability status of report API (Gireesh Punathil) (https://github.com/nodejs/node/pull/35654)
* deps:
* V8: Backport various patches for Apple Silicon support (BoHong Li) (https://github.com/nodejs/node/pull/38051)
* update ICU to 68.1 (Michaël Zasso) (https://github.com/nodejs/node/pull/36187)
* upgrade to libuv 1.41.0 (Colin Ihrig) (https://github.com/nodejs/node/pull/37360)
* http:
* add http.ClientRequest.getRawHeaderNames() (simov) (https://github.com/nodejs/node/pull/37660)
* report request start and end with diagnostics\_channel (Stephen Belanger) (https://github.com/nodejs/node/pull/34895)
* util:
* add getSystemErrorMap() impl (eladkeyshawn) (https://github.com/nodejs/node/pull/38101)
PR-URL: https://github.com/nodejs/node/pull/38507
Signed-off-by: James M Snell <jasnell@gmail.com>
PR-URL: https://github.com/nodejs/node/pull/37822
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Myles Borins <myles.borins@gmail.com>
Reviewed-By: Darshan Sen <raisinten@gmail.com>
We're about to turn on a requirement for dangling commas.
PR-URL: https://github.com/nodejs/node/pull/37088
Reviewed-By: Michaël Zasso <targos@protonmail.com>
Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>
Add missing 's' to example URL.
PR-URL: https://github.com/nodejs/node/pull/36147
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Harshitha K P <harshitha014@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
PR-URL: https://github.com/nodejs/node/pull/36175
Reviewed-By: Richard Lau <rlau@redhat.com>
Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>
This helps catch broken links as part of the test suite. This also
improves the user experience when browsing the markdown files.
PR-URL: https://github.com/nodejs/node/pull/35191
Fixes: https://github.com/nodejs/node/issues/35189
Reviewed-By: Derek Lewis <DerekNonGeneric@inf.is>
Reviewed-By: Jiawen Geng <technicalcute@gmail.com>
Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>
Reviewed-By: Richard Lau <riclau@uk.ibm.com>
Reviewed-By: Rich Trott <rtrott@gmail.com>
We use "falsy" in multiple places in our docs, but only use "false-y" in
one place in url.md. Replace it with "falsy".
PR-URL: https://github.com/nodejs/node/pull/34545
Reviewed-By: Anto Aravinth <anto.aravinth.cse@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Pranshu Srivastava <rexagod@gmail.com>
Reviewed-By: Ron Korving <ron@ronkorving.nl>
Reviewed-By: Yuta Hiroto <hello@hiroppy.me>
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>
Our docs use a mixture of _Constructor: `new Fhqwhgads()`_ in some
headers and only _`new Fhqwhgads()`_ in other headers. The latter is
about three times as common, so let's standardize on that.
PR-URL: https://github.com/nodejs/node/pull/33781
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Evan Lucas <evanlucas@me.com>
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
These are changed to either ```text or ```console.
PR-URL: https://github.com/nodejs/node/pull/33028
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
The WHATWG URL spec is not going to change this behavior so
let's document it
Signed-off-by: James M Snell <jasnell@gmail.com>
Fixes: https://github.com/nodejs/node/issues/33037
PR-URL: https://github.com/nodejs/node/pull/33236
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Joyee Cheung <joyeec9h3@gmail.com>
Reviewed-By: Zeyu Yang <himself65@outlook.com>
Currently, the URL docs for the WHATWG URL spec support are
somewhat lacking in their code example of how to access the
new URL constructor that lives inside the core url package.
PR-URL: https://github.com/nodejs/node/pull/32782
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Our documentation uses em dashes inconsistently. They are treated
inconsistently typographically too. (For example, they are sometimes
surrounded by spaces and sometimes not.) They are also often confused
with ordinary hyphens such as in the CHANGELOG, where they are
inadvertently mixed together in a single list. The difference is
not obvious in the raw markdown but is very noticeable when rendered,
appearing to be a typographical error (which it in fact is).
The em dash is never needed. There are always alternatives. Remove em
dashes entirely.
PR-URL: https://github.com/nodejs/node/pull/32080
Reviewed-By: Richard Lau <riclau@uk.ibm.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Our docs have a mix of "hostname" and "host name" in prose.
Let's follow the usage of Unix man pages, RFCs, and most
professionally-edited sources, and use "host name" in prose and
"hostname" to refer to the command and in code.
Lint rule forthcoming.
PR-URL: https://github.com/nodejs/node/pull/31326
Refs: https://github.com/nodejs/node/pull/31073
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Richard Lau <riclau@uk.ibm.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>
Document that returned `pathname` is now `/` when the URL to parse has
no path and the protocol scheme is`ws:` or `wss:`.
PR-URL: https://github.com/nodejs/node/pull/30348
Fixes: https://github.com/nodejs/node/issues/30154
Refs: https://github.com/nodejs/node/pull/26941
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Yongsheng Zhang <zyszys98@gmail.com>
Reviewed-By: Masashi Hirano <shisama07@gmail.com>
Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>
Reviewed-By: Tobias Nießen <tniessen@tnie.de>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
This is obsolete. Also, in our case it doesn't seem to have
any effect since the table cells have their natural width,
i.e. as much as they need.
PR-URL: https://github.com/nodejs/node/pull/29668
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: David Carlier <devnexen@gmail.com>
Address Markdownlint MD007 rule.
Default suggestion is 2 space indenting for unordered list items.
PR-URL: https://github.com/nodejs/node/pull/29390
Reviewed-By: David Carlier <devnexen@gmail.com>
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
PR-URL: https://github.com/nodejs/node/pull/24847
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Sam Roberts <vieuxtech@gmail.com>
Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>
