Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

doc: deprecate (doc-only) .aborted property and 'abort', 'aborted' event in http #36670

Closed
wants to merge 1 commit into from
Closed

doc: deprecate (doc-only) .aborted property and 'abort', 'aborted' event in http #36670

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 26 additions & 0 deletions doc/api/deprecations.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2831,6 +2831,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`
<!-- 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
dr-js marked this conversation as resolved.
Show resolved Hide resolved
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
Expand Down Expand Up @@ -2888,6 +2910,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
Expand All @@ -2900,6 +2925,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
Expand Down
15 changes: 14 additions & 1 deletion doc/api/http.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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()`.

Expand Down Expand Up @@ -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()`][].

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -1972,8 +1978,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'`
Expand All @@ -1986,8 +1995,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
Expand Down Expand Up @@ -3221,6 +3233,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
Expand Down