Add test for agent upgrade and example in docs

doc/api/http.markdown

@@ -476,13 +476,59 @@ agent. The `http.getAgent()` function allows you to access the agents.
 
 ### Event: 'upgrade'
 
-`function (request, socket, head)`
+`function (response, socket, head)`
 
-Emitted each time a server responds to a request with an upgrade. If this event
-isn't being listened for, clients receiving an upgrade header will have their
-connections closed.
+Emitted each time a server responds to a request with an upgrade. If this
+event isn't being listened for, clients receiving an upgrade header will have
+their connections closed.
+
+A client server pair that show you how to listen for the `upgrade` event using `http.getAgent`:
+
+    var http = require('http');
+    var net = require('net');
+
+    // Create an HTTP server
+    var srv = http.createServer(function (req, res) {
+      res.writeHead(200, {'Content-Type': 'text/plain'});
+      res.end('okay');
+    });
+    srv.on('upgrade', function(req, socket, upgradeHead) {
+      socket.write('HTTP/1.1 101 Web Socket Protocol Handshake\r\n' +
+                   'Upgrade: WebSocket\r\n' +
+                   'Connection: Upgrade\r\n' +
+                   '\r\n\r\n');
+
+      socket.ondata = function(data, start, end) {
+        socket.write(data.toString('utf8', start, end), 'utf8'); // echo back
+      };
+    });
+
+    // now that server is running
+    srv.listen(1337, '127.0.0.1', function() {
+
+      // make a request
+      var agent = http.getAgent('127.0.0.1', 1337);
+
+      var options = {
+        agent: agent,
+        port: 1337,
+        host: '127.0.0.1',
+        headers: {
+          'Connection': 'Upgrade',
+          'Upgrade': 'websocket'
+        }
+      };
+
+      var req = http.request(options);
+      req.end();
+
+      agent.on('upgrade', function(res, socket, upgradeHead) {
+        console.log('got upgraded!');
+        socket.end();
+        process.exit(0);
+      });
+    });
 
-See the description of the [upgrade event](http.html#event_upgrade_) for `http.Server` for further details.
 
 ### Event: 'continue'
 

test/simple/test-http-upgrade-agent.js

@@ -0,0 +1,90 @@
+// 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.
+
+// Verify that the 'upgrade' header causes an 'upgrade' event to be emitted to
+// the HTTP client. This test uses a raw TCP server to better control server
+// behavior.
+
+var common = require('../common');
+var assert = require('assert');
+
+var http = require('http');
+var net = require('net');
+
+// Create a TCP server
+var srv = net.createServer(function(c) {
+  var data = '';
+  c.addListener('data', function(d) {
+    data += d.toString('utf8');
+
+    c.write('HTTP/1.1 101\r\n');
+    c.write('hello: world\r\n');
+    c.write('connection: upgrade\r\n');
+    c.write('upgrade: websocket\r\n');
+    c.write('\r\n');
+    c.write('nurtzo');
+  });
+
+  c.addListener('end', function() {
+    c.end();
+  });
+});
+
+var gotUpgrade = false;
+
+srv.listen(common.PORT, '127.0.0.1', function() {
+
+  var agent = http.getAgent('127.0.0.1', common.PORT);
+  assert.ok(agent);
+
+  var options = {
+    port: common.PORT,
+    host: '127.0.0.1',
+    headers: {
+      'upgrade': 'websocket'
+    }
+  };
+
+  var req = http.request(options);
+  req.end();
+
+  agent.on('upgrade', function(res, socket, upgradeHead) {
+    // XXX: This test isn't fantastic, as it assumes that the entire response
+    //      from the server will arrive in a single data callback
+    assert.equal(upgradeHead, 'nurtzo');
+
+    console.log(res.headers);
+    var expectedHeaders = { 'hello': 'world',
+                            'connection': 'upgrade',
+                            'upgrade': 'websocket' };
+    assert.deepEqual(expectedHeaders, res.headers);
+
+    socket.end();
+    srv.close();
+
+    gotUpgrade = true;
+  });
+
+});
+
+process.addListener('exit', function() {
+  assert.ok(gotUpgrade);
+});