From 6073b6c57a67082094aaaf0b09f541ea3bcab11d Mon Sep 17 00:00:00 2001
From: Paolo Insogna <paolo@cowtech.it>
Date: Thu, 3 Aug 2023 12:59:37 +0200
Subject: [PATCH] http: updated docs

---
 doc/api/cli.md  | 20 ++++++++++++++++----
 doc/api/http.md | 12 ++++++------
 2 files changed, 22 insertions(+), 10 deletions(-)

diff --git a/doc/api/cli.md b/doc/api/cli.md
index cf509503dc838a..c139de8efbde5e 100644
--- a/doc/api/cli.md
+++ b/doc/api/cli.md
@@ -957,10 +957,22 @@ added:
  - v10.19.0
 -->
 
-Use an insecure HTTP parser that accepts invalid HTTP headers. This may allow
-interoperability with non-conformant HTTP implementations. It may also allow
-request smuggling and other HTTP attacks that rely on invalid headers being
-accepted. Avoid using this option.
+Enable leniency flags on the HTTP parser. This may allow
+interoperability with non-conformant HTTP implementations.
+
+When enabled, the parser will accept the following:
+
+* Invalid HTTP headers values.
+* Invalid HTTP versions.
+* Allow message containing both `Transfer-Encoding`
+  and `Content-Length` headers.
+* Allow extra data after message when `Connection: close` is present.
+* Allow extra trasfer encodings after `chunked` has been provided.
+* Allow `\n` to be used as token separator instead of `\r\n`.
+* Allow `\r\n` not to be provided after a chunk.
+
+All the above will expose your application to request smuggling
+or poisoning attack. Avoid using this option.
 
 ### `--jitless`
 
diff --git a/doc/api/http.md b/doc/api/http.md
index bb69094a5079c0..6d5d8d2e787e7b 100644
--- a/doc/api/http.md
+++ b/doc/api/http.md
@@ -3250,9 +3250,9 @@ changes:
     `readableHighWaterMark` and `writableHighWaterMark`. This affects
     `highWaterMark` property of both `IncomingMessage` and `ServerResponse`.
     **Default:** See [`stream.getDefaultHighWaterMark()`][].
-  * `insecureHTTPParser` {boolean} Use an insecure HTTP parser that accepts
-    invalid HTTP headers when `true`. Using the insecure parser should be
-    avoided. See [`--insecure-http-parser`][] for more information.
+  * `insecureHTTPParser` {boolean} If set to `true`, it will use a HTTP parser
+    with leniency flags enabled. Using the insecure parser should be avoided.
+    See [`--insecure-http-parser`][] for more information.
     **Default:** `false`.
   * `IncomingMessage` {http.IncomingMessage} Specifies the `IncomingMessage`
     class to be used. Useful for extending the original `IncomingMessage`.
@@ -3512,9 +3512,9 @@ changes:
     request to. **Default:** `'localhost'`.
   * `hostname` {string} Alias for `host`. To support [`url.parse()`][],
     `hostname` will be used if both `host` and `hostname` are specified.
-  * `insecureHTTPParser` {boolean} Use an insecure HTTP parser that accepts
-    invalid HTTP headers when `true`. Using the insecure parser should be
-    avoided. See [`--insecure-http-parser`][] for more information.
+  * `insecureHTTPParser` {boolean} If set to `true`, it will use a HTTP parser
+    with leniency flags enabled. Using the insecure parser should be avoided.
+    See [`--insecure-http-parser`][] for more information.
     **Default:** `false`
   * `joinDuplicateHeaders` {boolean} It joins the field line values of
     multiple headers in a request with `, ` instead of discarding