Skip to content

Commit

Permalink
http: doc deprecate abort and improve docs
Browse files Browse the repository at this point in the history
Doc deprecates ClientRequest.abort in favor of
ClientRequest.destroy. Also improves event order
documentation for abort and destroy.

Refs: #32225

PR-URL: #32807
Reviewed-By: Matteo Collina <[email protected]>
Reviewed-By: Zeyu Yang <[email protected]>
Reviewed-By: Anna Henningsen <[email protected]>
Reviewed-By: James M Snell <[email protected]>
Reviewed-By: Trivikram Kamat <[email protected]>
Reviewed-By: Rich Trott <[email protected]>
  • Loading branch information
ronag authored and BridgeAR committed Apr 28, 2020
1 parent 48a72bf commit 4d9e69d
Show file tree
Hide file tree
Showing 2 changed files with 83 additions and 4 deletions.
15 changes: 15 additions & 0 deletions doc/api/deprecations.md
Original file line number Diff line number Diff line change
Expand Up @@ -2569,6 +2569,19 @@ accordingly instead to avoid the ambigiuty.
To maintain existing behaviour `response.finished` should be replaced with
`response.writableEnded`.
<a id="DEP0XXX"></a>
### DEP0XXX: Use `request.destroy()` instead of `request.abort()`
<!-- YAML
changes:
- version: REPLACEME
pr-url: https://github.com/nodejs/node/pull/32807
description: Documentation-only deprecation.
-->
Type: Documentation-only
Use [`request.destroy()`][] instead of [`request.abort()`][].
[`--pending-deprecation`]: cli.html#cli_pending_deprecation
[`--throw-deprecation`]: cli.html#cli_throw_deprecation
[`Buffer.allocUnsafeSlow(size)`]: buffer.html#buffer_class_method_buffer_allocunsafeslow_size
Expand Down Expand Up @@ -2627,8 +2640,10 @@ To maintain existing behaviour `response.finished` should be replaced with
[`process.env`]: process.html#process_process_env
[`punycode`]: punycode.html
[`require.extensions`]: modules.html#modules_require_extensions
[`request.abort()`]: http.html#http_request_abort
[`request.socket`]: http.html#http_request_socket
[`request.connection`]: http.html#http_request_connection
[`request.destroy()`]: http.html#http_request_destroy_error
[`response.socket`]: http.html#http_response_socket
[`response.connection`]: http.html#http_response_connection
[`response.end()`]: http.html#http_response_end_data_encoding_callback
Expand Down
72 changes: 68 additions & 4 deletions doc/api/http.md
Original file line number Diff line number Diff line change
Expand Up @@ -568,6 +568,7 @@ server.listen(1337, '127.0.0.1', () => {
### `request.abort()`
<!-- YAML
added: v0.3.8
deprecated: REPLACEME
-->

Marks the request as aborting. Calling this will cause remaining data
Expand Down Expand Up @@ -623,6 +624,31 @@ If `data` is specified, it is equivalent to calling
If `callback` is specified, it will be called when the request stream
is finished.

### `request.destroy([error])`
<!-- YAML
added: v0.3.0
-->

* `error` {Error} Optional, an error to emit with `'error'` event.
* Returns: {this}

Destroy the request. Optionally emit an `'error'` event,
and emit a `'close'` event. Calling this will cause remaining data
in the response to be dropped and the socket to be destroyed.

See [`writable.destroy()`][] for further details.

#### `request.destroyed`
<!-- YAML
added: REPLACEME
-->

* {boolean}

Is `true` after [`request.destroy()`][] has been called.

See [`writable.destroyed`][] for further details.

### `request.finished`
<!-- YAML
added: v0.0.1
Expand Down Expand Up @@ -2354,8 +2380,43 @@ the following events will be emitted in the following order:
* `'close'`
* `'close'` on the `res` object

If `req.abort()` is called before the connection succeeds, the following events
will be emitted in the following order:
If `req.destroy()` is called before a socket is assigned, the following
events will be emitted in the following order:

* (`req.destroy()` called here)
* `'error'` with an error with message `'Error: socket hang up'` and code
`'ECONNRESET'`
* `'close'`

If `req.destroy()` is called before the connection succeeds, the following
events will be emitted in the following order:

* `'socket'`
* (`req.destroy()` called here)
* `'error'` with an error with message `'Error: socket hang up'` and code
`'ECONNRESET'`
* `'close'`

If `req.destroy()` is called after the response is received, the following
events will be emitted in the following order:

* `'socket'`
* `'response'`
* `'data'` any number of times, on the `res` object
* (`req.destroy()` called here)
* `'aborted'` on the `res` object
* `'close'`
* `'close'` on the `res` object

If `req.abort()` is called before a socket is assigned, the following
events will be emitted in the following order:

* (`req.abort()` called here)
* `'abort'`
* `'close'`

If `req.abort()` is called before the connection succeeds, the following
events will be emitted in the following order:

* `'socket'`
* (`req.abort()` called here)
Expand All @@ -2364,8 +2425,8 @@ will be emitted in the following order:
`'ECONNRESET'`
* `'close'`

If `req.abort()` is called after the response is received, the following events
will be emitted in the following order:
If `req.abort()` is called after the response is received, the following
events will be emitted in the following order:

* `'socket'`
* `'response'`
Expand Down Expand Up @@ -2411,6 +2472,7 @@ not abort the request or do anything besides add a `'timeout'` event.
[`new URL()`]: url.html#url_constructor_new_url_input_base
[`removeHeader(name)`]: #http_request_removeheader_name
[`request.end()`]: #http_request_end_data_encoding_callback
[`request.destroy()`]: #http_request_destroy_error
[`request.flushHeaders()`]: #http_request_flushheaders
[`request.getHeader()`]: #http_request_getheader_name
[`request.setHeader()`]: #http_request_setheader_name_value
Expand Down Expand Up @@ -2440,5 +2502,7 @@ not abort the request or do anything besides add a `'timeout'` event.
[`socket.unref()`]: net.html#net_socket_unref
[`url.parse()`]: url.html#url_url_parse_urlstring_parsequerystring_slashesdenotehost
[`HPE_HEADER_OVERFLOW`]: errors.html#errors_hpe_header_overflow
[`writable.destroy()`]: stream.html#stream_writable_destroy_error
[`writable.destroyed`]: stream.html#stream_writable_destroyed
[`writable.cork()`]: stream.html#stream_writable_cork
[`writable.uncork()`]: stream.html#stream_writable_uncork

0 comments on commit 4d9e69d

Please sign in to comment.