doc: add note about header values encoding

PR-URL: #42624 Fixes: #42579 Co-authored-by: Antoine du Hamel <[email protected]> Reviewed-By: Matteo Collina <[email protected]> Reviewed-By: Antoine du Hamel <[email protected]>
nodejs · May 31, 2022 · 77d6bfd · 77d6bfd
1 parent 93c9402
commit 77d6bfd
Showing 1 changed file with 12 additions and 0 deletions.
diff --git a/doc/api/http.md b/doc/api/http.md
@@ -979,6 +979,17 @@ or
 request.setHeader('Cookie', ['type=ninja', 'language=javascript']);
 ```
 
+When the value is a string an exception will be thrown if it contains
+characters outside the `latin1` encoding.
+
+If you need to pass UTF-8 characters in the value please encode the value
+using the [RFC 8187][] standard.
+
+```js
+const filename = 'Rock 🎵.txt';
+request.setHeader('Content-Disposition', `attachment; filename*=utf-8''${encodeURIComponent(filename)}`);
+```
+
 ### `request.setNoDelay([noDelay])`
 
 <!-- YAML
@@ -3387,6 +3398,7 @@ try {
 }
 ```
 
+[RFC 8187]: https://www.rfc-editor.org/rfc/rfc8187.txt
 [`'checkContinue'`]: #event-checkcontinue
 [`'finish'`]: #event-finish
 [`'request'`]: #event-request