From d1d9f2de308af640cec27669776462170499d4be Mon Sep 17 00:00:00 2001 From: dr-js Date: Tue, 19 Jan 2021 07:55:57 +0800 Subject: [PATCH] doc: deprecate (doc-only) http abort related MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 Co-authored-by: Rich Trott Co-authored-by: Robert Nagy Co-authored-by: Antoine du Hamel PR-URL: https://github.com/nodejs/node/pull/36670 Reviewed-By: Robert Nagy Reviewed-By: James M Snell Reviewed-By: Matteo Collina --- doc/api/deprecations.md | 26 ++++++++++++++++++++++++++ doc/api/http.md | 15 ++++++++++++++- 2 files changed, 40 insertions(+), 1 deletion(-) diff --git a/doc/api/deprecations.md b/doc/api/deprecations.md index 13ad661725bfcf..c9e0d2ba3ab452 100644 --- a/doc/api/deprecations.md +++ b/doc/api/deprecations.md @@ -2827,6 +2827,28 @@ Type: Documentation-only (supports [`--pending-deprecation`][]) 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` + + +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 @@ -2884,6 +2906,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 @@ -2896,6 +2921,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 4133f0d1cb1988..7abaa9bfed660f 100644 --- a/doc/api/http.md +++ b/doc/api/http.md @@ -405,8 +405,11 @@ body which has been transmitted are equal or not. ### Event: `'abort'` +> 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()`. @@ -562,7 +565,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()`][]. @@ -643,12 +646,15 @@ in the response to be dropped and the socket to be destroyed. ### `request.aborted` +> Stability: 0 - Deprecated. Check [`request.destroyed`][] instead. + * {boolean} The `request.aborted` property will be `true` if the request has @@ -1984,8 +1990,11 @@ may be reused multiple times in case of keep-alive. ### Event: `'aborted'` +> Stability: 0 - Deprecated. Listen for `'close'` event instead. + Emitted when the request has been aborted. ### Event: `'close'` @@ -1998,8 +2007,11 @@ Indicates that the underlying connection was closed. ### `message.aborted` +> Stability: 0 - Deprecated. Check `message.destroyed` from {stream.Readable}. + * {boolean} The `message.aborted` property will be `true` if the request has @@ -3231,6 +3243,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