diff options
author | Robert Nagy <ronagy@icloud.com> | 2020-04-13 12:02:03 +0300 |
---|---|---|
committer | Ruben Bridgewater <ruben@bridgewater.de> | 2020-04-28 14:58:31 +0300 |
commit | 9d18408b49a4fcaec8e89612c984e76e280caa95 (patch) | |
tree | ebebbb4129f5b0f1636ec1cba9220487f41f6253 | |
parent | 4fc7877ea3b693cdd2775a22572e4ef15388a473 (diff) |
http: doc deprecate abort and improve docs
Doc deprecates ClientRequest.abort in favor of
ClientRequest.destroy. Also improves event order
documentation for abort and destroy.
Refs: https://github.com/nodejs/node/issues/32225
PR-URL: https://github.com/nodejs/node/pull/32807
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
Reviewed-By: Zeyu Yang <himself65@outlook.com>
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>
Reviewed-By: Rich Trott <rtrott@gmail.com>
-rw-r--r-- | doc/api/deprecations.md | 15 | ||||
-rw-r--r-- | doc/api/http.md | 72 |
2 files changed, 83 insertions, 4 deletions
diff --git a/doc/api/deprecations.md b/doc/api/deprecations.md index 07e76f041ea..acd95125962 100644 --- a/doc/api/deprecations.md +++ b/doc/api/deprecations.md @@ -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 @@ -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 diff --git a/doc/api/http.md b/doc/api/http.md index a683eebdab5..7f097b0bc3a 100644 --- a/doc/api/http.md +++ b/doc/api/http.md @@ -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 @@ -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 @@ -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) @@ -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'` @@ -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 @@ -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 |