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 <matteo.collina@gmail.com>
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>

3 files changed, 37 insertions, 0 deletions

diff --git a/doc/api/deprecations.md b/doc/api/deprecations.md
index 50303baa782..cc8608c6c22 100644
--- a/doc/api/deprecations.md
+++ b/doc/api/deprecations.md
@@ -2548,6 +2548,27 @@ APIs that do not make sense to use in userland. File streams should always be
 opened through their corresponding factory methods [`fs.createWriteStream()`][]
 and [`fs.createReadStream()`][]) or by passing a file descriptor in options.
 
+<a id="DEP0136"></a>
+### DEP0136: http finished
+<!-- YAML
+changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/28679
+    description: Documentation-only deprecation.
+-->
+
+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`.
+
 [`--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
@@ -2610,6 +2631,10 @@ and [`fs.createReadStream()`][]) or by passing a file descriptor in options.
 [`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 007bbbf5640..f0d02117e6b 100644
--- a/doc/api/http.md
+++ b/doc/api/http.md
@@ -623,8 +623,11 @@ is finished.
 ### request.finished
 <!-- YAML
 added: v0.0.1
+deprecated: REPLACEME
 -->
 
+> Stability: 0 - Deprecated. Use [`request.writableEnded`][].
+
 * {boolean}
 
 The `request.finished` property will be `true` if [`request.end()`][]
@@ -1305,8 +1308,11 @@ is finished.
 ### response.finished
 <!-- YAML
 added: v0.0.2
+deprecated: REPLACEME
 -->
 
+> Stability: 0 - Deprecated. Use [`response.writableEnded`][].
+
 * {boolean}
 
 The `response.finished` property will be `true` if [`response.end()`][]
@@ -2417,12 +2423,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 d783c373cc5..2336547b982 100644
--- a/doc/api/http2.md
+++ b/doc/api/http2.md
@@ -3075,8 +3075,11 @@ is finished.
 #### response.finished
 <!-- YAML
 added: v8.4.0
+deprecated: REPLACEME
 -->
 
+> Stability: 0 - Deprecated. Use [`response.writableEnded`][].
+
 * {boolean}
 
 Boolean value that indicates whether the response has completed. Starts
@@ -3559,6 +3562,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