[feature] Add support for socket middleware (#2306)

Author: Alex

Readme.md

@@ -304,6 +304,25 @@ server.listen(3000);
   It should be noted the `Socket` doesn't relate directly to the actual
   underlying TCP/IP `socket` and it is only the name of the class.
 
+### Socket#use(fn:Function):Socket
+
+  Registers a middleware, which is a function that gets executed for
+  every incoming `Packet` and receives as parameter the packet and a
+  function to optionally defer execution to the next registered
+  middleware.
+
+  ```js
+  var io = require('socket.io')();
+  io.on('connection', function(socket){
+    socket.use(function(packet, next){
+      if (packet.doge === true) return next();
+      next(new Error('Not a doge error'));
+  });
+  ```
+
+  Errors passed to middleware callbacks are sent as special `error`
+  packets to clients.
+
 ### Socket#rooms:Object
 
   A hash of strings identifying the rooms this client is in, indexed by

lib/socket.js

@@ -68,6 +68,7 @@ function Socket(nsp, client, query){
   this.connected = true;
   this.disconnected = false;
   this.handshake = this.buildHandshake(query);
+  this.fns = [];
 }
 
 /**
@@ -345,7 +346,7 @@ Socket.prototype.onevent = function(packet){
     args.push(this.ack(packet.id));
   }
 
-  emit.apply(this, args);
+  this.dispatch(args);
 };
 
 /**
@@ -482,3 +483,63 @@ Socket.prototype.compress = function(compress){
   this.flags.compress = compress;
   return this;
 };
+
+/**
+ * Dispatch incoming event to socket listeners.
+ *
+ * @param {Array} event that will get emitted
+ * @api private
+ */
+
+Socket.prototype.dispatch = function(event){
+  debug('dispatching an event %j', event);
+  var self = this;
+  this.run(event, function(err){
+    process.nextTick(function(){
+      if (err) {
+        return self.emit('error', err.data || err.message);
+      }
+      emit.apply(self, event);
+    });
+  });
+}
+
+/**
+ * Sets up socket middleware.
+ *
+ * @param {Function} middleware function (event, next)
+ * @return {Socket} self
+ * @api public
+ */
+
+Socket.prototype.use = function(fn){
+  this.fns.push(fn);
+  return this;
+};
+
+/**
+ * Executes the middleware for an incoming event.
+ *
+ * @param {Array} event that will get emitted
+ * @param {Function} last fn call in the middleware
+ * @api private
+ */
+Socket.prototype.run = function(event, fn){
+  var fns = this.fns.slice(0);
+  if (!fns.length) return fn(null);
+
+  function run(i){
+    fns[i](event, function(err){
+      // upon error, short-circuit
+      if (err) return fn(err);
+
+      // if no middleware left, summon callback
+      if (!fns[i + 1]) return fn(null);
+
+      // go on to next
+      run(i + 1);
+    });
+  }
+
+  run(0);
+};

test/socket.io.js

@@ -2232,4 +2232,95 @@ describe('socket.io', function(){
       });
     });
   });
+
+  describe('socket middleware', function(done){
+    var Socket = require('../lib/socket');
+
+    it('should call functions', function(done){
+      var srv = http();
+      var sio = io(srv);
+      var run = 0;
+
+      srv.listen(function(){
+        var socket = client(srv, { multiplex: false });
+
+        socket.emit('join', 'woot');
+
+        sio.on('connection', function(socket){
+          socket.use(function(event, next){
+            expect(event).to.eql(['join', 'woot']);
+            event.unshift('wrap');
+            run++;
+            next();
+          });
+          socket.use(function(event, next){
+            expect(event).to.eql(['wrap', 'join', 'woot']);
+            run++;
+            next();
+          });
+          socket.on('wrap', function(data1, data2){
+            expect(data1).to.be('join');
+            expect(data2).to.be('woot');
+            expect(run).to.be(2);
+            done();
+          });
+        });
+      });
+    });
+
+    it('should pass errors', function(done){
+      var srv = http();
+      var sio = io(srv);
+
+      srv.listen(function(){
+        var socket = client(srv, { multiplex: false });
+
+        socket.emit('join', 'woot');
+
+        sio.on('connection', function(socket){
+          socket.use(function(event, next){
+            next(new Error('Authentication error'));
+          });
+          socket.use(function(event, next){
+            done(new Error('nope'));
+          });
+
+          socket.on('join', function(){
+            done(new Error('nope'));
+          });
+          socket.on('error', function(err){
+            expect(err).to.be('Authentication error');
+            done();
+          });
+        });
+      });
+    });
+
+    it('should pass `data` of error object', function(done){
+      var srv = http();
+      var sio = io(srv);
+
+      srv.listen(function(){
+        var socket = client(srv, { multiplex: false });
+
+        socket.emit('join', 'woot');
+
+        sio.on('connection', function(socket){
+          socket.use(function(event, next){
+            var err = new Error('Authentication error');
+            err.data = { a: 'b', c: 3 };
+            next(err);
+          });
+
+          socket.on('join', function(){
+            done(new Error('nope'));
+          });
+          socket.on('error', function(err){
+            expect(err).to.eql({ a: 'b', c: 3 });
+            done();
+          });
+        });
+      });
+    });
+  });
 });