From 69a8af002e6daa53b6b6d7f15101d40cc834cc6e Mon Sep 17 00:00:00 2001 From: Robert Nagy Date: Mon, 13 Apr 2020 11:02:03 +0200 Subject: [PATCH 1/8] 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 --- doc/api/deprecations.md | 16 +++++++++++++++ doc/api/http.md | 45 +++++++++++++++++++++++++++++++++++++---- 2 files changed, 57 insertions(+), 4 deletions(-) diff --git a/doc/api/deprecations.md b/doc/api/deprecations.md index 4b2c7da0474a70..2ace83abb406bf 100644 --- a/doc/api/deprecations.md +++ b/doc/api/deprecations.md @@ -2651,6 +2651,20 @@ written twice. This introduces a race condition between threads, and is a potential security vulnerability. There is no safe, cross-platform alternative API. + + +### DEPXXX: Use `request.destroy()` in favor of `request.abort()` + + +Type: Documentation-only + +Use [`request.destroy()`][] in favor 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 @@ -2712,8 +2726,10 @@ API. [`punycode`]: punycode.html [`require.extensions`]: modules.html#modules_require_extensions [`require.main`]: modules.html#modules_accessing_the_main_module +[`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_err_callback [`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 fb2f2b32399121..6e9918c6ee4ce7 100644 --- a/doc/api/http.md +++ b/doc/api/http.md @@ -568,6 +568,7 @@ server.listen(1337, '127.0.0.1', () => { ### `request.abort()` Marks the request as aborting. Calling this will cause remaining data @@ -2356,8 +2357,44 @@ 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) @@ -2366,8 +2403,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'` From 00f23eeb0e68afcb9f719e770c64458f1297389c Mon Sep 17 00:00:00 2001 From: Robert Nagy Date: Mon, 13 Apr 2020 11:25:17 +0200 Subject: [PATCH 2/8] fixup: lint --- doc/api/deprecations.md | 1 - doc/api/http.md | 1 - 2 files changed, 2 deletions(-) diff --git a/doc/api/deprecations.md b/doc/api/deprecations.md index 2ace83abb406bf..2aa0bda7c24014 100644 --- a/doc/api/deprecations.md +++ b/doc/api/deprecations.md @@ -2651,7 +2651,6 @@ written twice. This introduces a race condition between threads, and is a potential security vulnerability. There is no safe, cross-platform alternative API. - ### DEPXXX: Use `request.destroy()` in favor of `request.abort()` + +* `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. + +##### `request.destroyed` + + +* {boolean} + +Is `true` after [`request.destroy()`][] has been called. + ### `request.finished` * `error` {Error} Optional, an error to emit with `'error'` event. @@ -638,7 +638,7 @@ in the response to be dropped and the socket to be destroyed. ##### `request.destroyed` * {boolean} From 72b26946d829b8569f7ebd9299fe05365b65d06f Mon Sep 17 00:00:00 2001 From: Robert Nagy Date: Mon, 13 Apr 2020 15:17:56 +0200 Subject: [PATCH 5/8] fixup: further details --- doc/api/http.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/doc/api/http.md b/doc/api/http.md index aca36bd48a5a22..0129c4ade24ecd 100644 --- a/doc/api/http.md +++ b/doc/api/http.md @@ -636,6 +636,8 @@ 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.destroyed`][] for further details. + ##### `request.destroyed` @@ -647,6 +647,8 @@ added: REPLACEME Is `true` after [`request.destroy()`][] has been called. +See [`writable.destroyed`][] for further details. + ### `request.finished` * `error` {Error} Optional, an error to emit with `'error'` event.