From ec514a6a985bb12ebfb9779aa10333534ff31db3 Mon Sep 17 00:00:00 2001 From: Robert Nagy Date: Sun, 14 Jul 2019 16:59:25 +0200 Subject: [PATCH] doc: deprecate http finished PR-URL: https://github.com/nodejs/node/pull/28679 Refs: https://github.com/nodejs/node/issues/28651 Reviewed-By: Matteo Collina Reviewed-By: Rich Trott Reviewed-By: Ruben Bridgewater --- doc/api/deprecations.md | 25 +++++++++++++++++++++++++ doc/api/http.md | 8 ++++++++ doc/api/http2.md | 4 ++++ 3 files changed, 37 insertions(+) diff --git a/doc/api/deprecations.md b/doc/api/deprecations.md index 35a98fcb55e8a6..6a7c209f4a13fc 100644 --- a/doc/api/deprecations.md +++ b/doc/api/deprecations.md @@ -2521,6 +2521,27 @@ Type: Documentation-only (supports [`--pending-deprecation`][]) The `process._tickCallback` property was never documented as an officially supported API. + +### DEP0136: `http` `finished` + + +Type: Documentation-only + +[`response.finished`][] indicates whether [`response.end()`][] has been +called, not whether `'finish'` has been emitted and the underlying data +is flushed. + +Use [`response.writableFinished`][] or [`response.writableEnded`][] +accordingly instead to avoid the ambigiuty. + +To maintain existing behaviour `response.finished` should be replaced with +`response.writableEnded`. + [`--http-parser=legacy`]: cli.html#cli_http_parser_library [`--pending-deprecation`]: cli.html#cli_pending_deprecation [`--throw-deprecation`]: cli.html#cli_throw_deprecation @@ -2580,6 +2601,10 @@ an officially supported API. [`request.connection`]: http.html#http_request_connection [`response.socket`]: http.html#http_response_socket [`response.connection`]: http.html#http_response_connection +[`response.end()`]: http.html#http_response_end_data_encoding_callback +[`response.finished`]: #http_response_finished +[`response.writableFinished`]: #http_response_writablefinished +[`response.writableEnded`]: #http_response_writableended [`script.createCachedData()`]: vm.html#vm_script_createcacheddata [`setInterval()`]: timers.html#timers_setinterval_callback_delay_args [`setTimeout()`]: timers.html#timers_settimeout_callback_delay_args diff --git a/doc/api/http.md b/doc/api/http.md index c36ea0b98cb231..237119a9680ccc 100644 --- a/doc/api/http.md +++ b/doc/api/http.md @@ -620,8 +620,11 @@ is finished. ### `request.finished` +> Stability: 0 - Deprecated. Use [`request.writableEnded`][]. + * {boolean} The `request.finished` property will be `true` if [`request.end()`][] @@ -1297,8 +1300,11 @@ is finished. ### `response.finished` +> Stability: 0 - Deprecated. Use [`response.writableEnded`][]. + * {boolean} The `response.finished` property will be `true` if [`response.end()`][] @@ -2353,12 +2359,14 @@ not abort the request or do anything besides add a `'timeout'` event. [`request.socket.getPeerCertificate()`]: tls.html#tls_tlssocket_getpeercertificate_detailed [`request.socket`]: #http_request_socket [`request.writableFinished`]: #http_request_writablefinished +[`request.writableEnded`]: #http_request_writableended [`request.write(data, encoding)`]: #http_request_write_chunk_encoding_callback [`response.end()`]: #http_response_end_data_encoding_callback [`response.getHeader()`]: #http_response_getheader_name [`response.setHeader()`]: #http_response_setheader_name_value [`response.socket`]: #http_response_socket [`response.writableFinished`]: #http_response_writablefinished +[`response.writableEnded`]: #http_response_writableended [`response.write()`]: #http_response_write_chunk_encoding_callback [`response.write(data, encoding)`]: #http_response_write_chunk_encoding_callback [`response.writeContinue()`]: #http_response_writecontinue diff --git a/doc/api/http2.md b/doc/api/http2.md index 2c4a91dda080d4..32333d0feb4d5d 100644 --- a/doc/api/http2.md +++ b/doc/api/http2.md @@ -3091,8 +3091,11 @@ is finished. #### `response.finished` +> Stability: 0 - Deprecated. Use [`response.writableEnded`][]. + * {boolean} Boolean value that indicates whether the response has completed. Starts @@ -3576,6 +3579,7 @@ following additional properties: [`response.end()`]: #http2_response_end_data_encoding_callback [`response.setHeader()`]: #http2_response_setheader_name_value [`response.socket`]: #http2_response_socket +[`response.writableEnded`]: #http2_response_writableended [`response.write()`]: #http2_response_write_chunk_encoding_callback [`response.write(data, encoding)`]: http.html#http_response_write_chunk_encoding_callback [`response.writeContinue()`]: #http2_response_writecontinue