doc: caution against removing pseudoheaders

jasnell · gibfahn · commit 51e660ae2a55 · 2017-12-19T22:15:20.000Z
PR-URL: #17329 Fixes: #15312 Reviewed-By: Anna Henningsen <anna@addaleax.net> Reviewed-By: Jon Moss <me@jonathanmoss.me> Reviewed-By: Anatoli Papirovski <apapirovski@mac.com> Reviewed-By: Refael Ackermann <refack@gmail.com> Reviewed-By: Tobias Nießen <tniessen@tnie.de> Reviewed-By: Timothy Gu <timothygu99@gmail.com>
diff --git a/doc/api/http2.md b/doc/api/http2.md
@@ -2127,6 +2127,18 @@ console.log(request.headers);
 
 See [Headers Object][].
 
+*Note*: In HTTP/2, the request path, host name, protocol, and method are
+represented as special headers prefixed with the `:` character (e.g. `':path'`).
+These special headers will be included in the `request.headers` object. Care
+must be taken not to inadvertently modify these special headers or errors may
+occur. For instance, removing all headers from the request will cause errors
+to occur:
+
+```js
+removeAllHeaders(request.headers);
+assert(request.url);   // Fails because the :path header has been removed
+```
+
 #### request.httpVersion
 <!-- YAML
 added: v8.4.0
