http: add request.flush() method

Forcibly flushes the request headers.  You need this with long-lived
HTTP connections where the first data isn't written until the connection
has been established (think: tunneling requests over HTTP CONNECT.)

Fixes #7296.

Signed-off-by: Fedor Indutny <fedor@indutny.com>

doc/api/http.markdown

@@ -845,6 +845,18 @@ Emitted when the server sends a '100 Continue' HTTP response, usually because
 the request contained 'Expect: 100-continue'. This is an instruction that
 the client should send the request body.
 
+### request.flush()
+
+Flush the request headers.
+
+For effiency reasons, node.js normally buffers the request headers until you
+call `request.end()` or write the first chunk of request data.  It then tries
+hard to pack the request headers and data into a single TCP packet.
+
+That's usually what you want (it saves a TCP round-trip) but not when the first
+data isn't sent until possibly much later.  `request.flush()` lets you bypass
+the optimization and kickstart the request.
+
 ### request.write(chunk, [encoding])
 
 Sends a chunk of the body.  By calling this method

lib/_http_outgoing.js

@@ -595,3 +595,12 @@ OutgoingMessage.prototype._flush = function() {
     }
   }
 };
+
+
+OutgoingMessage.prototype.flush = function() {
+  if (!this._header) {
+    // Force-flush the headers.
+    this._implicitHeader();
+    this._send('');
+  }
+};

test/simple/test-http-flush.js

@@ -0,0 +1,37 @@
+// Copyright Joyent, Inc. and other Node contributors.
+//
+// Permission is hereby granted, free of charge, to any person obtaining a
+// copy of this software and associated documentation files (the
+// "Software"), to deal in the Software without restriction, including
+// without limitation the rights to use, copy, modify, merge, publish,
+// distribute, sublicense, and/or sell copies of the Software, and to permit
+// persons to whom the Software is furnished to do so, subject to the
+// following conditions:
+//
+// The above copyright notice and this permission notice shall be included
+// in all copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+// OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+// MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN
+// NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+// DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+// OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
+// USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+var common = require('../common');
+var assert = require('assert');
+var http = require('http');
+
+http.createServer(function(req, res) {
+  res.end('ok');
+  this.close();
+}).listen(function() {
+  var req = http.request({
+    method: 'POST',
+    host: this.address().address,
+    port: this.address().port,
+  });
+  req.flush();  // Flush the request headers.
+  req.flush();  // Should be idempotent.
+});