Add the "loopback" flag. (#1)

The "loopback" flag is used to emit messages on the local endpoint of
a socket; e.g., allowing the server to send a message to the server's
handler directly.

This is especially useful in conjunction with rooms, as it allows the
server to proactively trigger behavior for each socket in a room without
having to maintain a separate list of said sockets or relying on the
client endpoint to trigger the behavior.

lib/client.js

@@ -163,6 +163,11 @@ Client.prototype.packet = function(packet, opts){
   opts = opts || {};
   var self = this;
 
+  if ('open' != this.conn.readyState) {
+    debug('ignoring packet write %j', packet);
+    return;
+  }
+
   // this writes to the actual connection
   function writeToEngine(encodedPackets) {
     if (opts.volatile && !self.conn.transport.writable) return;
@@ -171,15 +176,23 @@ Client.prototype.packet = function(packet, opts){
     }
   }
 
-  if ('open' == this.conn.readyState) {
+  if (opts.loopback) {
+    debug('writing loopback packet %j', packet);
+    // handle loopback packets as though they came in off the wire.
+    if (opts.preEncoded) { // a broadcast pre-encodes a packet
+      for (var i = 0; i < packet.length; i++) {
+        this.decoder.add(packet[i]);
+      }
+    } else { // no broadcasting, no need to decode
+      this.ondecoded(packet);
+    }
+  } else {
     debug('writing packet %j', packet);
     if (!opts.preEncoded) { // not broadcasting, need to encode
       this.encoder.encode(packet, writeToEngine); // encode, then write results to engine
     } else { // a broadcast pre-encodes a packet
       writeToEngine(packet);
     }
-  } else {
-    debug('ignoring packet write %j', packet);
   }
 };
 

lib/namespace.js

@@ -30,6 +30,7 @@ exports.events = [
  */
 
 exports.flags = [
+  'loopback',
   'json',
   'volatile',
   'local'

lib/socket.js

@@ -37,6 +37,7 @@ exports.events = [
  */
 
 var flags = [
+  'loopback',
   'json',
   'volatile',
   'broadcast',
@@ -155,6 +156,10 @@ Socket.prototype.emit = function(ev){
       throw new Error('Callbacks are not supported when broadcasting');
     }
 
+    if (this.flags.loopback) {
+      throw new Error('Callbacks are not supported when emitting loopback messages');
+    }
+
     debug('emitting packet with ack id %d', this.nsp.ids);
     this.acks[this.nsp.ids] = args.pop();
     packet.id = this.nsp.ids++;

test/socket.io.js

@@ -677,7 +677,7 @@ describe('socket.io', function(){
         });
       });
     });
-    
+
     it('should not reuse same-namespace connections', function(done){
       var srv = http();
       var sio = io(srv);
@@ -837,6 +837,47 @@ describe('socket.io', function(){
       }, 500);
     });
 
+    it('should emit loopback messages locally', function(done) {
+      var srv = http();
+      var sio = io(srv);
+
+      var local_counter = 0;
+      var remote_counter = 0;
+      srv.listen(function(){
+        sio.of('/chat').on('connection', function(s){
+          setTimeout(function() {
+            // test broadcast and local.
+            sio.of('/chat').loopback.emit('ev1', 'data1');
+            s.loopback.emit('ev2', 'data2');
+          }, 50);
+          s.on('ev1', function(data) {
+            if (data === 'data1') {
+              local_counter++;
+            }
+          });
+          s.on('ev2', function(data) {
+            if (data === 'data2') {
+              local_counter++;
+            }
+          });
+        });
+
+        var socket = client(srv, '/chat');
+        socket.on('ev1', function() {
+          remote_counter++;
+        });
+        socket.on('ev2', function() {
+          remote_counter++;
+        });
+      });
+
+      setTimeout(function() {
+        expect(local_counter).to.be(2);
+        expect(remote_counter).to.be(0);
+        done();
+      }, 500);
+    });
+
     it('should emit volatile event', function(done) {
       var srv = http();
       var sio = io(srv);
@@ -1608,7 +1649,7 @@ describe('socket.io', function(){
         });
       });
     });
-    
+
     it('should see query parameters sent from secondary namespace connections in handshake object', function(done){
       var srv = http();
       var sio = io(srv);