socket: add conn, client, request getters

Author: rauchg

Diff for: Readme.md

@@ -202,21 +202,65 @@ server.listen(3000);
   Hash of `Socket` objects that are connected to this namespace indexed
   by `id`.
 
+### Namespace#use(fn:Function):Namespace
+
+  Registers a middleware, which is a function that gets executed for
+  every incoming `Socket` and receives as parameter the socket and a
+  function to optionally defer execution to the next registered
+  middleware.
+
+  ```
+  var io = require('socket.io')();
+  io.use(function(socket, next){
+    if (socket.request.headers.cookie) return next();
+    done(new Error('Authentication error'));
+  });
+  ```
+
+  Errors passed to middleware callbacks are sent as special `error`
+  packets to clients.
+
 ### Socket
 
   A `Socket` is the fundamental class for interacting with browser
-  clients.
+  clients. A `Socket` belongs to a certain `Namespace` (by default `/`)
+  and uses an underlying `Client` to communicate.
 
 ### Socket#rooms:Array
 
   A list of strings identifying the rooms this socket is in.
 
+### Socket#client:Client
+
+  A reference to the underlying `Client` object.
+
+### Socket#conn:Socket
+
+  A reference to the underyling `Client` transport connection (engine.io
+  `Socket` object).
+
+### Socket#request:Request
+
+  A getter proxy that returns the reference to the `request` that
+  originated the underlying engine.io `Client`. Useful for accessing
+  request headers such as `Cookie` or `User-Agent`.
+
 ### Client
 
   The `Client` class represents an incoming transport (engine.io)
   connection. A `Client` can be associated with many multiplexed `Socket`
   that belong to different `Namespace`s.
 
+### Client#conn
+
+  A reference to the underlying `engine.io` `Socket` connection.
+
+### Client#request
+
+  A getter proxy that returns the reference to the `request` that
+  originated the engine.io connection. Useful for accessing
+  request headers such as `Cookie` or `User-Agent`.
+
 ### Adapter
 
   The `Adapter` is in charge of keeping track of what rooms each socket

Diff for: lib/socket.js

@@ -59,6 +59,7 @@ function Socket(nsp, client){
   this.id = client.id;
   this.request = client.request;
   this.client = client;
+  this.conn = client.conn;
   this.rooms = [];
   this.acks = {};
   this.connected = true;
@@ -83,6 +84,16 @@ exports.flags.forEach(function(flag){
   });
 });
 
+/**
+ * `request` engine.io shorcut.
+ *
+ * @api public
+ */
+
+Socket.prototype.__defineGetter__('request', function(){
+  return this.conn.request;
+});
+
 /**
  * Emits to this client.
  *

Diff for: test/socket.io.js

@@ -347,6 +347,44 @@ describe('socket.io', function(){
         });
       });
     });
+
+    it('should have access to the client', function(done){
+      var srv = http();
+      var sio = io(srv);
+      srv.listen(function(){
+        var socket = client(srv);
+        sio.on('connection', function(s){
+          expect(s.client).to.be.an('object');
+          done();
+        });
+      });
+    });
+
+    it('should have access to the connection', function(done){
+      var srv = http();
+      var sio = io(srv);
+      srv.listen(function(){
+        var socket = client(srv);
+        sio.on('connection', function(s){
+          expect(s.client.conn).to.be.an('object');
+          expect(s.conn).to.be.an('object');
+          done();
+        });
+      });
+    });
+
+    it('should have access to the request', function(done){
+      var srv = http();
+      var sio = io(srv);
+      srv.listen(function(){
+        var socket = client(srv);
+        sio.on('connection', function(s){
+          expect(s.client.request.headers).to.be.an('object');
+          expect(s.request.headers).to.be.an('object');
+          done();
+        });
+      });
+    });
   });
 
   describe('messaging many', function(){