doc: deprecate (doc-only) http abort related

Refs: nodejs#36641
Refs: nodejs#36617 (comment)

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 <[email protected]>
Co-authored-by: Rich Trott <[email protected]>
Co-authored-by: Robert Nagy <[email protected]>
Co-authored-by: Antoine du Hamel <[email protected]>

Author: 5 people

doc/api/deprecations.md

@@ -2743,6 +2743,28 @@ Previously, `index.js` and extension searching lookups would apply to
 With this deprecation, all ES module main entry point resolutions require
 an explicit [`"exports"` or `"main"` entry][] with the exact file extension.
 
+### 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#url_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
@@ -2798,6 +2820,9 @@ an explicit [`"exports"` or `"main"` entry][] with the exact file extension.
 [`fs.read()`]: fs.md#fs_fs_read_fd_buffer_offset_length_position_callback
 [`fs.readSync()`]: fs.md#fs_fs_readsync_fd_buffer_offset_length_position
 [`fs.stat()`]: fs.md#fs_fs_stat_path_options_callback
+[`http.ClientRequest`]: #http_class_http_clientrequest
+[`http.IncomingMessage`]: #http_class_http_incomingmessage
+[`http.ServerResponse`]: #http_class_http_serverresponse
 [`http.get()`]: http.md#http_http_get_options_callback
 [`http.request()`]: http.md#http_http_request_options_callback
 [`https.get()`]: https.md#https_https_get_options_callback
@@ -2810,6 +2835,7 @@ an explicit [`"exports"` or `"main"` entry][] with the exact file extension.
 [`process.env`]: process.md#process_process_env
 [`process.mainModule`]: process.md#process_process_mainmodule
 [`punycode`]: punycode.md
+[`readable.readableEnded`]: stream.md#stream_readable_readableended
 [`request.abort()`]: http.md#http_request_abort
 [`request.connection`]: http.md#http_request_connection
 [`request.destroy()`]: http.md#http_request_destroy_error

doc/api/http.md

@@ -405,8 +405,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()`.
 
@@ -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`
 <!-- 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
@@ -1950,8 +1956,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'`
@@ -1964,8 +1973,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
@@ -2771,6 +2783,7 @@ try {
 [`removeHeader(name)`]: #http_request_removeheader_name
 [`request.end()`]: #http_request_end_data_encoding_callback
 [`request.destroy()`]: #http_request_destroy_error
+[`request.destroyed`]: #http_request_destroyed
 [`request.flushHeaders()`]: #http_request_flushheaders
 [`request.getHeader()`]: #http_request_getheader_name
 [`request.setHeader()`]: #http_request_setheader_name_value