http2: add some doc detail for invalid header chars

Backport-PR-URL: #14813 Backport-Reviewed-By: Anna Henningsen <[email protected]> Backport-Reviewed-By: Timothy Gu <[email protected]> PR-URL: #14239 Reviewed-By: Anna Henningsen <[email protected]> Reviewed-By: Colin Ihrig <[email protected]> Reviewed-By: Matteo Collina <[email protected]>
nodejs · Aug 14, 2017 · f46c50b · f46c50b
1 parent b43caf9
commit f46c50b
Showing 1 changed file with 21 additions and 0 deletions.
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'`