Add defined behavior for HTTP Upgrade requests

closes #12

HISTORY.md

@@ -2,6 +2,7 @@ unreleased
 ==========
 
   * Add defined behavior for HTTP `CONNECT` requests
+  * Add defined behavior for HTTP `Upgrade` requests
   * deps: [email protected]
 
 2.2.1 / 2015-04-22

README.md

@@ -99,6 +99,26 @@ the request will be considered "finished" even before it has been read.
 There is no such thing as a response object to a `CONNECT` request in
 Node.js, so there is no support for for one.
 
+### HTTP Upgrade request
+
+The meaning of the `Upgrade` header from RFC 7230, section 6.1:
+
+> The "Upgrade" header field is intended to provide a simple mechanism
+> for transitioning from HTTP/1.1 to some other protocol on the same
+> connection.
+
+In Node.js, these request objects come from the `'upgrade'` event on
+the HTTP server.
+
+When this module is used on a HTTP request with an `Upgrade` header, the
+request is considered "finished" immediately, **due to limitations in the
+Node.js interface**. This means if the `Upgrade` request contains a request
+entity, the request will be considered "finished" even before it has been
+read.
+
+There is no such thing as a response object to a `Upgrade` request in
+Node.js, so there is no support for for one.
+
 ## Example
 
 The following code ensures that file descriptors are always closed

test/test.js

@@ -610,6 +610,111 @@ describe('onFinished(req, listener)', function () {
       })
     })
   })
+
+  describe('when Upgrade request', function () {
+    it('should fire when request finishes', function (done) {
+      var client
+      var server = http.createServer(function (req, res) {
+        res.statusCode = 405
+        res.end()
+      })
+      server.on('upgrade', function (req, socket, bodyHead) {
+        var data = [bodyHead]
+
+        onFinished(req, function (err) {
+          assert.ifError(err)
+          assert.equal(Buffer.concat(data).toString(), 'knock, knock')
+
+          socket.on('data', function (chunk) {
+            assert.equal(chunk.toString(), 'ping')
+            socket.end('pong')
+          })
+          socket.write('HTTP/1.1 101 Switching Protocols\r\n')
+          socket.write('Connection: Upgrade\r\n')
+          socket.write('Upgrade: Raw\r\n')
+          socket.write('\r\n')
+        })
+
+        req.on('data', function (chunk) {
+          data.push(chunk)
+        })
+      })
+
+      server.listen(function () {
+        client = http.request({
+          headers: {
+            'Connection': 'Upgrade',
+            'Upgrade': 'Raw'
+          },
+          hostname: '127.0.0.1',
+          port: this.address().port
+        })
+
+        client.on('upgrade', function (res, socket, bodyHead) {
+          socket.write('ping')
+          socket.on('data', function (chunk) {
+            assert.equal(chunk.toString(), 'pong')
+            socket.end()
+            server.close(done)
+          })
+        })
+        client.end('knock, knock')
+      })
+    })
+
+    it('should fire when called after finish', function (done) {
+      var client
+      var server = http.createServer(function (req, res) {
+        res.statusCode = 405
+        res.end()
+      })
+      server.on('upgrade', function (req, socket, bodyHead) {
+        var data = [bodyHead]
+
+        onFinished(req, function (err) {
+          assert.ifError(err)
+          assert.equal(Buffer.concat(data).toString(), 'knock, knock')
+
+          socket.write('HTTP/1.1 101 Switching Protocols\r\n')
+          socket.write('Connection: Upgrade\r\n')
+          socket.write('Upgrade: Raw\r\n')
+          socket.write('\r\n')
+        })
+
+        socket.on('data', function (chunk) {
+          assert.equal(chunk.toString(), 'ping')
+          onFinished(req, function (err) {
+            socket.end('pong')
+          })
+        })
+
+        req.on('data', function (chunk) {
+          data.push(chunk)
+        })
+      })
+
+      server.listen(function () {
+        client = http.request({
+          headers: {
+            'Connection': 'Upgrade',
+            'Upgrade': 'Raw'
+          },
+          hostname: '127.0.0.1',
+          port: this.address().port
+        })
+
+        client.on('upgrade', function (res, socket, bodyHead) {
+          socket.write('ping')
+          socket.on('data', function (chunk) {
+            assert.equal(chunk.toString(), 'pong')
+            socket.end()
+            server.close(done)
+          })
+        })
+        client.end('knock, knock')
+      })
+    })
+  })
 })
 
 describe('isFinished(req)', function () {
@@ -787,6 +892,104 @@ describe('isFinished(req)', function () {
       })
     })
   })
+
+  describe('when Upgrade request', function () {
+    it('should be true immediately', function (done) {
+      var client
+      var server = http.createServer(function (req, res) {
+        res.statusCode = 405
+        res.end()
+      })
+
+      server.on('upgrade', function (req, socket, bodyHead) {
+        assert.ok(onFinished.isFinished(req))
+        assert.equal(bodyHead.length, 0)
+        req.resume()
+
+        socket.on('data', function (chunk) {
+          assert.equal(chunk.toString(), 'ping')
+          socket.end('pong')
+        })
+        socket.write('HTTP/1.1 101 Switching Protocols\r\n')
+        socket.write('Connection: Upgrade\r\n')
+        socket.write('Upgrade: Raw\r\n')
+        socket.write('\r\n')
+      })
+
+      server.listen(function () {
+        client = http.request({
+          headers: {
+            'Connection': 'Upgrade',
+            'Upgrade': 'Raw'
+          },
+          hostname: '127.0.0.1',
+          port: this.address().port
+        })
+
+        client.on('upgrade', function (res, socket, bodyHead) {
+          socket.write('ping')
+          socket.on('data', function (chunk) {
+            assert.equal(chunk.toString(), 'pong')
+            socket.end()
+            server.close(done)
+          })
+        })
+        client.end()
+      })
+    })
+
+    it('should be true after request finishes', function (done) {
+      var client
+      var server = http.createServer(function (req, res) {
+        res.statusCode = 405
+        res.end()
+      })
+      server.on('upgrade', function (req, socket, bodyHead) {
+        var data = [bodyHead]
+
+        onFinished(req, function (err) {
+          assert.ifError(err)
+          assert.ok(onFinished.isFinished(req))
+          assert.equal(Buffer.concat(data).toString(), 'knock, knock')
+
+          socket.write('HTTP/1.1 101 Switching Protocols\r\n')
+          socket.write('Connection: Upgrade\r\n')
+          socket.write('Upgrade: Raw\r\n')
+          socket.write('\r\n')
+        })
+
+        socket.on('data', function (chunk) {
+          assert.equal(chunk.toString(), 'ping')
+          socket.end('pong')
+        })
+
+        req.on('data', function (chunk) {
+          data.push(chunk)
+        })
+      })
+
+      server.listen(function () {
+        client = http.request({
+          headers: {
+            'Connection': 'Upgrade',
+            'Upgrade': 'Raw'
+          },
+          hostname: '127.0.0.1',
+          port: this.address().port
+        })
+
+        client.on('upgrade', function (res, socket, bodyHead) {
+          socket.write('ping')
+          socket.on('data', function (chunk) {
+            assert.equal(chunk.toString(), 'pong')
+            socket.end()
+            server.close(done)
+          })
+        })
+        client.end('knock, knock')
+      })
+    })
+  })
 })
 
 function captureStderr(fn) {