From c86df322fb811895f91700a52dfaeaae1bd7167a Mon Sep 17 00:00:00 2001
From: Gireesh Punathil <gpunathi@in.ibm.com>
Date: Tue, 12 Jun 2018 10:41:07 -0400
Subject: [PATCH] doc: explain HTTP writeHead()'s fast path behavior

calling writeHead() into a Response object that has no headers already
set causes getHeader() to return undefined, even if the header was set
in the writeHead() function call. Explain this behavior as an
optimiation as opposed to a bug.

Fixes: https://github.com/nodejs/node/issues/10354
---
 doc/api/http.md | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/doc/api/http.md b/doc/api/http.md
index 8f2c531713b4f5..ea229ec0b17681 100644
--- a/doc/api/http.md
+++ b/doc/api/http.md
@@ -1277,6 +1277,13 @@ const server = http.createServer((req, res) => {
 });
 ```
 
+If [`response.writeHead()`][] method is called and this method has not been
+called, it will directly write the supplied header values onto the network
+channel without caching internally, and the [`response.getHeader()`][] on the
+header will not yield the expected result. If progressive population of headers
+is desired with potential future retrieval and modification, use
+[`response.setHeader()`][] instead of [`response.writeHead()`][].
+
 ### response.setTimeout(msecs[, callback])
 <!-- YAML
 added: v0.9.12
@@ -1444,6 +1451,13 @@ When headers have been set with [`response.setHeader()`][], they will be merged
 with any headers passed to [`response.writeHead()`][], with the headers passed
 to [`response.writeHead()`][] given precedence.
 
+If this method is called and [`response.setHeader()`][] has not been called,
+it will directly write the supplied header values onto the network channel
+without caching internally, and the [`response.getHeader()`][] on the header
+will not yield the expected result. If progressive population of headers is
+desired with potential future retrieval and modification, use
+[`response.setHeader()`][] instead.
+
 ```js
 // returns content-type = text/plain
 const server = http.createServer((req, res) => {