doc,test: clarify that Http2Stream is destroyed after data is read

Correct docs to clarify that behaviour,
and fix a race condition in test-http2-large-write-destroy.js.

Fixes: #27863

Backport-PR-URL: #28904
PR-URL: #27891
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>

doc/api/http2.md

@@ -902,8 +902,9 @@ the value is `undefined`, the stream is not yet ready for use.
 
 All [`Http2Stream`][] instances are destroyed either when:
 
-* An `RST_STREAM` frame for the stream is received by the connected peer.
-* The `http2stream.close()` method is called.
+* An `RST_STREAM` frame for the stream is received by the connected peer,
+  and pending data has been read.
+* The `http2stream.close()` method is called, and pending data has been read.
 * The `http2stream.destroy()` or `http2session.destroy()` methods are called.
 
 When an `Http2Stream` instance is destroyed, an attempt will be made to send an

test/parallel/test-http2-large-write-destroy.js

@@ -32,6 +32,7 @@ server.listen(0, common.mustCall(() => {
 
   const req = client.request({ ':path': '/' });
   req.end();
+  req.resume(); // Otherwise close won't be emitted if there's pending data.
 
   req.on('close', common.mustCall(() => {
     client.close();