net: add pauseOnConnect option to createServer()

Currently when a server receives a new connection the underlying socket
handle begins reading data immediately. This causes problems when
sockets are passed between processes, as data can be read by the first
process and thus never read by the second process.

This commit allows sockets that are constructed with a handle to be
paused initially.

PR-URL: https://github.com/joyent/node/pull/8576
Fixes: https://github.com/joyent/node/issues/7905
Fixes: https://github.com/joyent/node/issues/7784
Reviewed-by: Trevor Norris <trev.norris@gmail.com>

doc/api/net.markdown

@@ -13,7 +13,9 @@ automatically set as a listener for the ['connection'][] event.
 
 `options` is an object with the following defaults:
 
-    { allowHalfOpen: false
+    {
+      allowHalfOpen: false,
+      pauseOnConnect: false
     }
 
 If `allowHalfOpen` is `true`, then the socket won't automatically send a FIN
@@ -21,6 +23,11 @@ packet when the other end of the socket sends a FIN packet. The socket becomes
 non-readable, but still writable. You should call the `end()` method explicitly.
 See ['end'][] event for more information.
 
+If `pauseOnConnect` is `true`, then the socket associated with each incoming
+connection will be paused, and no data will be read from its handle. This allows
+connections to be passed between processes without any data being read by the
+original process. To begin reading data from a paused socket, call `resume()`.
+
 Here is an example of an echo server which listens for connections
 on port 8124:
 

lib/net.js

@@ -180,8 +180,16 @@ function Socket(options) {
 
   // if we have a handle, then start the flow of data into the
   // buffer.  if not, then this will happen when we connect
-  if (this._handle && options.readable !== false)
+  if (this._handle && options.readable !== false) {
+    if (options.pauseOnCreate) {
+      // stop the handle from reading and pause the stream
+      this._handle.reading = false;
+      this._handle.readStop();
+      this._readableState.flowing = false;
+    } else {
       this.read(0);
+    }
+  }
 }
 util.inherits(Socket, stream.Duplex);
 
@@ -1024,6 +1032,7 @@ function Server(/* [ options, ] listener */) {
   this._slaves = [];
 
   this.allowHalfOpen = options.allowHalfOpen || false;
+  this.pauseOnConnect = !!options.pauseOnConnect;
 }
 util.inherits(Server, events.EventEmitter);
 exports.Server = Server;
@@ -1287,7 +1296,8 @@ function onconnection(err, clientHandle) {
 
   var socket = new Socket({
     handle: clientHandle,
-    allowHalfOpen: self.allowHalfOpen
+    allowHalfOpen: self.allowHalfOpen,
+    pauseOnCreate: self.pauseOnConnect
   });
   socket.readable = socket.writable = true;
 

test/simple/test-net-server-pause-on-connect.js

@@ -0,0 +1,59 @@
+// 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 net = require('net');
+var msg = 'test';
+var stopped = true;
+var server1 = net.createServer({pauseOnConnect: true}, function(socket) {
+  socket.on('data', function(data) {
+    if (stopped) {
+      assert(false, 'data event should not have happened yet');
+    }
+
+    assert.equal(data.toString(), msg, 'invalid data received');
+    socket.end();
+    server1.close();
+  });
+
+  setTimeout(function() {
+    assert.equal(socket.bytesRead, 0, 'no data should have been read yet');
+    socket.resume();
+    stopped = false;
+  }, 3000);
+});
+
+var server2 = net.createServer({pauseOnConnect: false}, function(socket) {
+  socket.on('data', function(data) {
+    assert.equal(data.toString(), msg, 'invalid data received');
+    socket.end();
+    server2.close();
+  });
+});
+
+server1.listen(common.PORT, function() {
+  net.createConnection({port: common.PORT}).write(msg);
+});
+
+server2.listen(common.PORT + 1, function() {
+  net.createConnection({port: common.PORT + 1}).write(msg);
+});