http2: add some doc detail for invalid header chars

PR-URL: #14239 Reviewed-By: Anna Henningsen <anna@addaleax.net> Reviewed-By: Colin Ihrig <cjihrig@gmail.com> Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
nodejs · jasnell · Oct 17, 2016 · Nov 4, 2016 · Jul 17, 2017 · Jul 17, 2017
commit ea2a35f6b77291294aea520ae43f069f0f40d4fc
diff --git a/doc/api/http2.md b/doc/api/http2.md
@@ -1707,6 +1707,27 @@ These will be reported using either a synchronous `throw` or via an `'error'`
 event on the `Http2Stream`, `Http2Session` or HTTP/2 Server objects, depending
 on where and when the error occurs.
 
+### Invalid character handling in header names and values
+
+The HTTP/2 implementation applies stricter handling of invalid characters in
+HTTP header names and values than the HTTP/1 implementation.
+
+Header field names are *case-insensitive* and are transmitted over the wire
+strictly as lower-case strings. The API provided by Node.js allows header
+names to be set as mixed-case strings (e.g. `Content-Type`) but will convert
+those to lower-case (e.g. `content-type`) upon transmission.
+
+Header field-names *must only* contain one or more of the following ASCII
+characters: `a`-`z`, `A`-`Z`, `0`-`9`, `!`, `#`, `$`, `%`, `&`, `'`, `*`, `+`,
+`-`, `.`, `^`, `_`, `` (backtick), `|`, and `~`.
+
+Using invalid characters within an HTTP header field name will cause the
+stream to be closed with a protocol error being reported.
+
+Header field values are handled with more leniency but *should* not contain
+new-line or carriage return characters and *should* be limited to US-ASCII
+characters, per the requirements of the HTTP specification.
+
 ### Push streams on the client
 
 To receive pushed streams on the client, set a listener for the `'stream'`