FazBrowse GitHub Viewer | Trending |
URL:
| Home
Tools: [Download Repo ZIP]   [Original HTTPS Page]

doc: deprecate (doc-only) http abort related · nodejs/node@d1d9f2d · GitHub

/ node Public

Commit d1d9f2d

Browse files
dr-js
authored and
danielleadams
committed
doc: deprecate (doc-only) http abort related
Refs: #36641 Refs: #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 <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: #36670 Reviewed-By: Robert Nagy <ronagy@icloud.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
1 parent a8926d1 commit d1d9f2d

2 files changed

Lines changed: 40 additions & 1 deletion

File tree

‎doc/api/deprecations.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2827,6 +2827,28 @@ Type: Documentation-only (supports [`--pending-deprecation`][])
28272827
The remapping of specifiers ending in `"/"` like `import 'pkg/x/'` is deprecated
28282828
for package `"exports"` and `"imports"` pattern resolutions.
28292829

2830+
### DEP0XXX: `.aborted` property and `'abort'`, `'aborted'` event in `http`
2831+
<!-- YAML
2832+
changes:
2833+
- version: REPLACEME
2834+
pr-url: https://github.com/nodejs/node/pull/36670
2835+
description: Documentation-only deprecation.
2836+
-->
2837+
2838+
Type: Documentation-only
2839+
2840+
Move to {Stream} API instead, as the [`http.ClientRequest`][],
2841+
[`http.ServerResponse`][], and [`http.IncomingMessage`][] are all stream-based.
2842+
Check `stream.destroyed` instead of the `.aborted` property, and listen for
2843+
`'close'` instead of `'abort'`, `'aborted'` event.
2844+
2845+
The `.aborted` property and `'abort'` event are only useful for detecting
2846+
`.abort()` calls. For closing a request early, use the Stream
2847+
`.destroy([error])` then check the `.destroyed` property and `'close'` event
2848+
should have the same effect. The receiving end should also check the
2849+
[`readable.readableEnded`][] value on [`http.IncomingMessage`][] to get whether
2850+
it was an aborted or graceful destroy.
2851+
28302852
[Legacy URL API]: url.md#legacy-url-api
28312853
[NIST SP 800-38D]: https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-38d.pdf
28322854
[RFC 6066]: https://tools.ietf.org/html/rfc6066#section-3
@@ -2884,6 +2906,9 @@ for package `"exports"` and `"imports"` pattern resolutions.
28842906
[`fs.read()`]: fs.md#fsreadfd-buffer-offset-length-position-callback
28852907
[`fs.readSync()`]: fs.md#fsreadsyncfd-buffer-offset-length-position
28862908
[`fs.stat()`]: fs.md#fsstatpath-options-callback
2909+
[`http.ClientRequest`]: http.md#class-httpclientrequest
2910+
[`http.IncomingMessage`]: http.md#class-httpincomingmessage
2911+
[`http.ServerResponse`]: http.md#class-httpserverresponse
28872912
[`http.get()`]: http.md#httpgetoptions-callback
28882913
[`http.request()`]: http.md#httprequestoptions-callback
28892914
[`https.get()`]: https.md#httpsgetoptions-callback
@@ -2896,6 +2921,7 @@ for package `"exports"` and `"imports"` pattern resolutions.
28962921
[`process.env`]: process.md#processenv
28972922
[`process.mainModule`]: process.md#processmainmodule
28982923
[`punycode`]: punycode.md
2924+
[`readable.readableEnded`]: stream.md#readablereadableended
28992925
[`request.abort()`]: http.md#requestabort
29002926
[`request.connection`]: http.md#requestconnection
29012927
[`request.destroy()`]: http.md#requestdestroyerror

‎doc/api/http.md‎

Lines changed: 14 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -405,8 +405,11 @@ body which has been transmitted are equal or not.
405405
### Event: `'abort'`
406406
<!-- YAML
407407
added: v1.4.1
408+
deprecated: REPLACEME
408409
-->
409410

411+
> Stability: 0 - Deprecated. Listen for the `'close'` event instead.
412+
410413
Emitted when the request has been aborted by the client. This event is only
411414
emitted on the first call to `abort()`.
412415

@@ -562,7 +565,7 @@ added: v0.7.8
562565
-->
563566

564567
Emitted when the underlying socket times out from inactivity. This only notifies
565-
that the socket has been idle. The request must be aborted manually.
568+
that the socket has been idle. The request must be destroyed manually.
566569

567570
See also: [`request.setTimeout()`][].
568571

@@ -643,12 +646,15 @@ in the response to be dropped and the socket to be destroyed.
643646
### `request.aborted`
644647
<!-- YAML
645648
added: v0.11.14
649+
deprecated: REPLACEME
646650
changes:
647651
- version: v11.0.0
648652
pr-url: https://github.com/nodejs/node/pull/20230
649653
description: The `aborted` property is no longer a timestamp number.
650654
-->
651655

656+
> Stability: 0 - Deprecated. Check [`request.destroyed`][] instead.
657+
652658
* {boolean}
653659

654660
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.
19841990
### Event: `'aborted'`
19851991
<!-- YAML
19861992
added: v0.3.8
1993+
deprecated: REPLACEME
19871994
-->
19881995

1996+
> Stability: 0 - Deprecated. Listen for `'close'` event instead.
1997+
19891998
Emitted when the request has been aborted.
19901999

19912000
### Event: `'close'`
@@ -1998,8 +2007,11 @@ Indicates that the underlying connection was closed.
19982007
### `message.aborted`
19992008
<!-- YAML
20002009
added: v10.1.0
2010+
deprecated: REPLACEME
20012011
-->
20022012

2013+
> Stability: 0 - Deprecated. Check `message.destroyed` from {stream.Readable}.
2014+
20032015
* {boolean}
20042016

20052017
The `message.aborted` property will be `true` if the request has
@@ -3231,6 +3243,7 @@ try {
32313243
[`outgoingMessage.socket`]: #outgoingmessagesocket
32323244
[`removeHeader(name)`]: #requestremoveheadername
32333245
[`request.destroy()`]: #requestdestroyerror
3246+
[`request.destroyed`]: #requestdestroyed
32343247
[`request.end()`]: #requestenddata-encoding-callback
32353248
[`request.flushHeaders()`]: #requestflushheaders
32363249
[`request.getHeader()`]: #requestgetheadername

0 commit comments

Comments
 (0)
Back | FazBrowse Home | New Git URL