http: makes response.writeHead return the response

Fixes: https://github.com/nodejs/node/issues/25935

PR-URL: https://github.com/nodejs/node/pull/25974
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>

3 files changed, 37 insertions, 3 deletions

diff --git a/doc/api/http.md b/doc/api/http.md
index 8803078569..87de5a9bba 100644
--- a/doc/api/http.md
+++ b/doc/api/http.md
@@ -1450,6 +1450,10 @@ the request body should be sent. See the [`'checkContinue'`][] event on
 <!-- YAML
 added: v0.1.30
 changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/25974
+    description: Return `this` from `writeHead()` to allow chaining with
+                 `end()`.
   - version: v5.11.0, v4.4.5
     pr-url: https://github.com/nodejs/node/pull/6291
     description: A `RangeError` is thrown if `statusCode` is not a number in
@@ -1459,17 +1463,23 @@ changes:
 * `statusCode` {number}
 * `statusMessage` {string}
 * `headers` {Object}
+* Returns: {http.ServerResponse}
 
 Sends a response header to the request. The status code is a 3-digit HTTP
 status code, like `404`. The last argument, `headers`, are the response headers.
 Optionally one can give a human-readable `statusMessage` as the second
 argument.
 
+Returns a reference to the `ServerResponse`, so that calls can be chained.
+
 ```js
 const body = 'hello world';
-response.writeHead(200, {
-  'Content-Length': Buffer.byteLength(body),
-  'Content-Type': 'text/plain' });
+response
+  .writeHead(200, {
+    'Content-Length': Buffer.byteLength(body),
+    'Content-Type': 'text/plain'
+  })
+  .end(body);
 ```
 
 This method must only be called once on a message and it must
diff --git a/lib/_http_server.js b/lib/_http_server.js
index 8d39d46896..a899f651be 100644
--- a/lib/_http_server.js
+++ b/lib/_http_server.js
@@ -270,6 +270,8 @@ function writeHead(statusCode, reason, obj) {
   }
 
   this._storeHeader(statusLine, headers);
+
+  return this;
 }
 
 // Docs-only deprecated: DEP0063
diff --git a/test/parallel/test-http-response-writehead-returns-this.js b/test/parallel/test-http-response-writehead-returns-this.js
new file mode 100644
index 0000000000..a62c2eca03
--- /dev/null
+++ b/test/parallel/test-http-response-writehead-returns-this.js
@@ -0,0 +1,22 @@
+'use strict';
+require('../common');
+const http = require('http');
+const assert = require('assert');
+
+const server = http.createServer((req, res) => {
+  res.writeHead(200, { 'a-header': 'a-header-value' }).end('abc');
+});
+
+server.listen(0, () => {
+  http.get({ port: server.address().port }, (res) => {
+    assert.strictEqual(res.headers['a-header'], 'a-header-value');
+
+    const chunks = [];
+
+    res.on('data', (chunk) => chunks.push(chunk));
+    res.on('end', () => {
+      assert.strictEqual(Buffer.concat(chunks).toString(), 'abc');
+      server.close();
+    });
+  });
+});