Add options to res.download

closes #3327
closes #3370

lib/response.js

@@ -515,30 +515,56 @@ res.sendfile = deprecate.function(res.sendfile,
  * when the data transfer is complete, or when an error has
  * ocurred. Be sure to check `res.headersSent` if you plan to respond.
  *
- * This method uses `res.sendfile()`.
+ * Optionally providing an `options` object to use with `res.sendFile()`.
+ * This function will set the `Content-Disposition` header, overriding
+ * any `Content-Disposition` header passed as header options in order
+ * to set the attachment and filename.
+ *
+ * This method uses `res.sendFile()`.
  *
  * @public
  */
 
-res.download = function download(path, filename, callback) {
+res.download = function download (path, filename, options, callback) {
   var done = callback;
   var name = filename;
+  var opts = options || null
 
-  // support function as second arg
+  // support function as second or third arg
   if (typeof filename === 'function') {
     done = filename;
     name = null;
+    opts = null
+  } else if (typeof options === 'function') {
+    done = options
+    opts = null
   }
 
   // set Content-Disposition when file is sent
   var headers = {
     'Content-Disposition': contentDisposition(name || path)
   };
 
+  // merge user-provided headers
+  if (opts && opts.headers) {
+    var keys = Object.keys(opts.headers)
+    for (var i = 0; i < keys.length; i++) {
+      var key = keys[i]
+      if (key.toLowerCase() !== 'content-disposition') {
+        headers[key] = opts.headers[key]
+      }
+    }
+  }
+
+  // merge user-provided options
+  opts = Object.create(opts)
+  opts.headers = headers
+
   // Resolve the full path for sendFile
   var fullPath = resolve(path);
 
-  return this.sendFile(fullPath, { headers: headers }, done);
+  // send file
+  return this.sendFile(fullPath, opts, done)
 };
 
 /**

test/res.download.js

@@ -71,6 +71,86 @@ describe('res', function(){
     })
   })
 
+  describe('.download(path, filename, options, fn)', function () {
+    it('should invoke the callback', function (done) {
+      var app = express()
+      var cb = after(2, done)
+      var options = {}
+
+      app.use(function (req, res) {
+        res.download('test/fixtures/user.html', 'document', options, done)
+      })
+
+      request(app)
+      .get('/')
+      .expect(200)
+      .expect('Content-Type', 'text/html; charset=UTF-8')
+      .expect('Content-Disposition', 'attachment; filename="document"')
+      .end(cb)
+    })
+
+    it('should allow options to res.sendFile()', function (done) {
+      var app = express()
+
+      app.use(function (req, res) {
+        res.download('test/fixtures/.name', 'document', {
+          dotfiles: 'allow',
+          maxAge: '4h'
+        })
+      })
+
+      request(app)
+      .get('/')
+      .expect(200)
+      .expect('Content-Disposition', 'attachment; filename="document"')
+      .expect('Cache-Control', 'public, max-age=14400')
+      .expect('tobi')
+      .end(done)
+    })
+
+    describe('when options.headers contains Content-Disposition', function () {
+      it('should should be ignored', function (done) {
+        var app = express()
+
+        app.use(function (req, res) {
+          res.download('test/fixtures/user.html', 'document', {
+            headers: {
+              'Content-Type': 'text/x-custom',
+              'Content-Disposition': 'inline'
+            }
+          })
+        })
+
+        request(app)
+        .get('/')
+        .expect(200)
+        .expect('Content-Type', 'text/x-custom')
+        .expect('Content-Disposition', 'attachment; filename="document"')
+        .end(done)
+      })
+
+      it('should should be ignored case-insensitively', function (done) {
+        var app = express()
+
+        app.use(function (req, res) {
+          res.download('test/fixtures/user.html', 'document', {
+            headers: {
+              'content-type': 'text/x-custom',
+              'content-disposition': 'inline'
+            }
+          })
+        })
+
+        request(app)
+        .get('/')
+        .expect(200)
+        .expect('Content-Type', 'text/x-custom')
+        .expect('Content-Disposition', 'attachment; filename="document"')
+        .end(done)
+      })
+    })
+  })
+
   describe('on failure', function(){
     it('should invoke the callback', function(done){
       var app = express();