From 77685d5ab06015cd3473ed24b78f6ac48548be72 Mon Sep 17 00:00:00 2001
From: Rafael Silva <rafael.nunu@hotmail.com>
Date: Sun, 6 Feb 2022 06:28:55 -0300
Subject: [PATCH] doc: add stream pipelining note on Http usage

PR-URL: https://github.com/nodejs/node/pull/41796
Reviewed-By: Robert Nagy <ronagy@icloud.com>
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
Reviewed-By: Mary Marchini <oss@mmarchini.me>
Reviewed-By: James M Snell <jasnell@gmail.com>
---
 doc/api/stream.md | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/doc/api/stream.md b/doc/api/stream.md
index 60faf7d2058b02..764ba3c763bf8b 100644
--- a/doc/api/stream.md
+++ b/doc/api/stream.md
@@ -2107,6 +2107,28 @@ run().catch(console.error);
 after the `callback` has been invoked. In the case of reuse of streams after
 failure, this can cause event listener leaks and swallowed errors.
 
+`stream.pipeline()` closes all the streams when an error is raised.
+The `IncomingRequest` usage with `pipeline` could lead to an unexpected behavior
+once it would destroy the socket without sending the expected response.
+See the example below:
+
+```js
+const fs = require('fs');
+const http = require('http');
+const { pipeline } = require('stream');
+
+const server = http.createServer((req, res) => {
+  const fileStream = fs.createReadStream('./fileNotExist.txt');
+  pipeline(fileStream, res, (err) => {
+    if (err) {
+      console.log(err); // No such file
+      // this message can't be sent once `pipeline` already destroyed the socket
+      return res.end('error!!!');
+    }
+  });
+});
+```
+
 ### `stream.compose(...streams)`
 
 <!-- YAML