From 69a8af002e6daa53b6b6d7f15101d40cc834cc6e Mon Sep 17 00:00:00 2001 From: Robert Nagy Date: Mon, 13 Apr 2020 11:02:03 +0200 Subject: [PATCH] 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'`