dgram: add maxSendQueueSize socket option

This commit adds the maxSendQueueSize option to dgram sockets.
When used, this option prevents the socket's send queue from
growing without an upper bound.

Author: cjihrig

doc/api/dgram.md

@@ -431,8 +431,8 @@ added: v0.11.13
 * Returns: {dgram.Socket}
 
 Creates a `dgram.Socket` object. The `options` argument is an object that
-should contain a `type` field of either `udp4` or `udp6` and an optional
-boolean `reuseAddr` field.
+should contain a `type` field of either `udp4` or `udp6`. `options` may also
+contain optional `reuseAddr` and `maxSendQueueSize` fields.
 
 When `reuseAddr` is `true` [`socket.bind()`][] will reuse the address, even if
 another process has already bound a socket on it. `reuseAddr` defaults to
@@ -446,6 +446,13 @@ interfaces" address on a random port (it does the right thing for both `udp4`
 and `udp6` sockets). The bound address and port can be retrieved using
 [`socket.address().address`][] and [`socket.address().port`][].
 
+It is possible to begin sending data from a socket that has not been bound. In
+this situation, the socket will be bound automatically before sending the data.
+Send operations are stored in a queue until the socket binds. `maxSendQueueSize`
+is a number that places an upper bound on the number of send operations that can
+be queued. If the queue size is exceeded, an error is emitted.
+`maxSendQueueSize` defaults to `Infinity`.
+
 ### dgram.createSocket(type[, callback])
 <!-- YAML
 added: v0.1.99

lib/dgram.js

@@ -13,6 +13,8 @@ const BIND_STATE_UNBOUND = 0;
 const BIND_STATE_BINDING = 1;
 const BIND_STATE_BOUND = 2;
 
+const maxSendQueueSize = Symbol('maxSendQueueSize');
+
 // lazily loaded
 var cluster = null;
 var dns = null;
@@ -76,11 +78,15 @@ exports._createSocketHandle = function(address, port, addressType, fd, flags) {
 
 
 function Socket(type, listener) {
+  var options;
+
   EventEmitter.call(this);
 
   if (type !== null && typeof type === 'object') {
-    var options = type;
+    options = type;
     type = options.type;
+  } else {
+    options = {};
   }
 
   var handle = newHandle(type);
@@ -89,11 +95,15 @@ function Socket(type, listener) {
   this._handle = handle;
   this._receiving = false;
   this._bindState = BIND_STATE_UNBOUND;
+  this._queue = undefined;
   this.type = type;
   this.fd = null; // compatibility hack
 
   // If true - UV_UDP_REUSEADDR flag will be set
-  this._reuseAddr = options && options.reuseAddr;
+  this._reuseAddr = !!options.reuseAddr;
+
+  this[maxSendQueueSize] = typeof options.maxSendQueueSize === 'number' ?
+                           options.maxSendQueueSize : Infinity;
 
   if (typeof listener === 'function')
     this.on('message', listener);
@@ -284,6 +294,12 @@ function enqueue(self, toEnqueue) {
     self._queue = [];
     self.once('listening', clearQueue);
   }
+
+  if (self._queue.length >= self[maxSendQueueSize]) {
+    self.emit('error', new Error('Maximum send queue size exceeded'));
+    return;
+  }
+
   self._queue.push(toEnqueue);
   return;
 }

test/parallel/test-dgram-max-send-queue.js

@@ -0,0 +1,58 @@
+'use strict';
+const common = require('../common');
+const assert = require('assert');
+const dgram = require('dgram');
+const dns = require('dns');
+const maxSendQueueSize = 10;
+
+// Monkey patch dns.lookup() so that it always fails.
+dns.lookup = function(address, family, callback) {
+  callback(new Error('fake DNS'));
+};
+
+// Verify that maxSendQueueSize is respected.
+{
+  const socket = dgram.createSocket({ type: 'udp4', maxSendQueueSize });
+  let queueErrors = 0;
+
+  process.on('exit', () => {
+    assert.strictEqual(queueErrors, 1);
+  });
+
+  socket.on('error', (err) => {
+    // Ignore DNS errors.
+    if (/^Error: fake DNS$/.test(err))
+      return;
+
+    if (/^Error: Maximum send queue size exceeded$/.test(err)) {
+      queueErrors++;
+      return;
+    }
+
+    common.fail(`Unexpected error: ${err}`);
+  });
+
+  // Fill the send queue.
+  for (let i = 0; i < maxSendQueueSize; ++i)
+    socket.send('foobar', common.PORT, 'localhost');
+
+  // Pause to make sure nothing leaves the queue.
+  setImmediate(() => {
+    assert.strictEqual(socket._queue.length, maxSendQueueSize);
+    socket.send('foobar', common.PORT, 'localhost');
+    assert.strictEqual(socket._queue.length, maxSendQueueSize);
+  });
+}
+
+// Verify the default behavior when no maxSendQueueSize is specified.
+{
+  const socket = dgram.createSocket({ type: 'udp4' });
+
+  // Only fake DNS errors should be seen.
+  socket.on('error', (err) => { assert(/^Error: fake DNS$/.test(err)); });
+
+  for (let i = 0; i < maxSendQueueSize * 2; ++i)
+    socket.send('foobar', common.PORT, 'localhost');
+
+  assert.strictEqual(socket._queue.length, maxSendQueueSize * 2);
+}