diff options
author | dr-js <dr@dr.run> | 2021-01-19 02:55:57 +0300 |
---|---|---|
committer | Matteo Collina <hello@matteocollina.com> | 2021-09-27 13:43:58 +0300 |
commit | 4b030d057375e58d2e99182f6ef7aa70f6ebcf99 (patch) | |
tree | 4408a747f88ae55cf15a86e639f098e4db15e239 | |
parent | 44b173e01346c679f8b8c0ec26fd041b02c46bca (diff) |
doc: deprecate (doc-only) http abort related
Refs: https://github.com/nodejs/node/pull/36641
Refs: https://github.com/nodejs/node/issues/36617#issuecomment-751443964
Documentation-only deprecate `.aborted` property and `'abort'`,
`'aborted'` event in `http`, and suggest using the corresponding
Stream API instead.
Co-authored-by: Michaƫl Zasso <targos@protonmail.com>
Co-authored-by: Rich Trott <rtrott@gmail.com>
Co-authored-by: Robert Nagy <ronagy@icloud.com>
Co-authored-by: Antoine du Hamel <duhamelantoine1995@gmail.com>
PR-URL: https://github.com/nodejs/node/pull/36670
Reviewed-By: Robert Nagy <ronagy@icloud.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
-rw-r--r-- | doc/api/deprecations.md | 26 | ||||
-rw-r--r-- | doc/api/http.md | 15 |
2 files changed, 40 insertions, 1 deletions
diff --git a/doc/api/deprecations.md b/doc/api/deprecations.md index ce2d2918d42..7d610d04bae 100644 --- a/doc/api/deprecations.md +++ b/doc/api/deprecations.md @@ -2838,6 +2838,28 @@ Type: Runtime The remapping of specifiers ending in `"/"` like `import 'pkg/x/'` is deprecated for package `"exports"` and `"imports"` pattern resolutions. +### DEP0XXX: `.aborted` property and `'abort'`, `'aborted'` event in `http` +<!-- YAML +changes: + - version: REPLACEME + pr-url: https://github.com/nodejs/node/pull/36670 + description: Documentation-only deprecation. +--> + +Type: Documentation-only + +Move to {Stream} API instead, as the [`http.ClientRequest`][], +[`http.ServerResponse`][], and [`http.IncomingMessage`][] are all stream-based. +Check `stream.destroyed` instead of the `.aborted` property, and listen for +`'close'` instead of `'abort'`, `'aborted'` event. + +The `.aborted` property and `'abort'` event are only useful for detecting +`.abort()` calls. For closing a request early, use the Stream +`.destroy([error])` then check the `.destroyed` property and `'close'` event +should have the same effect. The receiving end should also check the +[`readable.readableEnded`][] value on [`http.IncomingMessage`][] to get whether +it was an aborted or graceful destroy. + [Legacy URL API]: url.md#legacy-url-api [NIST SP 800-38D]: https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-38d.pdf [RFC 6066]: https://tools.ietf.org/html/rfc6066#section-3 @@ -2895,6 +2917,9 @@ for package `"exports"` and `"imports"` pattern resolutions. [`fs.read()`]: fs.md#fsreadfd-buffer-offset-length-position-callback [`fs.readSync()`]: fs.md#fsreadsyncfd-buffer-offset-length-position [`fs.stat()`]: fs.md#fsstatpath-options-callback +[`http.ClientRequest`]: http.md#class-httpclientrequest +[`http.IncomingMessage`]: http.md#class-httpincomingmessage +[`http.ServerResponse`]: http.md#class-httpserverresponse [`http.get()`]: http.md#httpgetoptions-callback [`http.request()`]: http.md#httprequestoptions-callback [`https.get()`]: https.md#httpsgetoptions-callback @@ -2907,6 +2932,7 @@ for package `"exports"` and `"imports"` pattern resolutions. [`process.env`]: process.md#processenv [`process.mainModule`]: process.md#processmainmodule [`punycode`]: punycode.md +[`readable.readableEnded`]: stream.md#readablereadableended [`request.abort()`]: http.md#requestabort [`request.connection`]: http.md#requestconnection [`request.destroy()`]: http.md#requestdestroyerror diff --git a/doc/api/http.md b/doc/api/http.md index af68e710037..3fb6d398330 100644 --- a/doc/api/http.md +++ b/doc/api/http.md @@ -407,8 +407,11 @@ body which has been transmitted are equal or not. ### Event: `'abort'` <!-- YAML added: v1.4.1 +deprecated: REPLACEME --> +> Stability: 0 - Deprecated. Listen for the `'close'` event instead. + Emitted when the request has been aborted by the client. This event is only emitted on the first call to `abort()`. @@ -564,7 +567,7 @@ added: v0.7.8 --> Emitted when the underlying socket times out from inactivity. This only notifies -that the socket has been idle. The request must be aborted manually. +that the socket has been idle. The request must be destroyed manually. See also: [`request.setTimeout()`][]. @@ -645,12 +648,15 @@ in the response to be dropped and the socket to be destroyed. ### `request.aborted` <!-- YAML added: v0.11.14 +deprecated: REPLACEME changes: - version: v11.0.0 pr-url: https://github.com/nodejs/node/pull/20230 description: The `aborted` property is no longer a timestamp number. --> +> Stability: 0 - Deprecated. Check [`request.destroyed`][] instead. + * {boolean} The `request.aborted` property will be `true` if the request has @@ -1988,8 +1994,11 @@ may be reused multiple times in case of keep-alive. ### Event: `'aborted'` <!-- YAML added: v0.3.8 +deprecated: REPLACEME --> +> Stability: 0 - Deprecated. Listen for `'close'` event instead. + Emitted when the request has been aborted. ### Event: `'close'` @@ -2002,8 +2011,11 @@ Indicates that the underlying connection was closed. ### `message.aborted` <!-- YAML added: v10.1.0 +deprecated: REPLACEME --> +> Stability: 0 - Deprecated. Check `message.destroyed` from {stream.Readable}. + * {boolean} The `message.aborted` property will be `true` if the request has @@ -3237,6 +3249,7 @@ try { [`outgoingMessage.socket`]: #outgoingmessagesocket [`removeHeader(name)`]: #requestremoveheadername [`request.destroy()`]: #requestdestroyerror +[`request.destroyed`]: #requestdestroyed [`request.end()`]: #requestenddata-encoding-callback [`request.flushHeaders()`]: #requestflushheaders [`request.getHeader()`]: #requestgetheadername |