Add support for Cache-Control: immutable with a new "immutable" option

More browsers are starting to support Cache-Control: immutable (see: https://hacks.mozilla.org/2017/01/using-immutable-caching-to-speed-up-the-web/). This commit adds support for an "immutable" option to add this directive to the Cache-Control header.

Test Plan: Added unit tests to verify that the "immutable" directive is added only when the option is specified and when the response is successful.

closes #75

Author: ide

Readme.md

@@ -19,6 +19,7 @@ $ npm install koa-send
 ## Options
 
  - `maxage` Browser cache max-age in milliseconds. (defaults to `0`)
+ - `immutable` Tell the browser the resource is immutable and can be cached indefinitely (defaults to `false`)
  - `hidden` Allow transfer of hidden files. (defaults to `false`)
  - [`root`](#root-path) Root directory to restrict file access
  - `gzip` Try to serve the gzipped version of a file automatically when `gzip` is supported by a client and if the requested file with `.gz` extension exists. defaults to true.

index.js

@@ -45,6 +45,7 @@ async function send(ctx, path, opts = {}) {
   path = path.substr(parse(path).root.length);
   const index = opts.index;
   const maxage = opts.maxage || opts.maxAge || 0;
+  const immutable = opts.immutable || false;
   const hidden = opts.hidden || false;
   const format = opts.format === false ? false : true;
   const extensions = Array.isArray(opts.extensions) ? opts.extensions : false;
@@ -125,7 +126,13 @@ async function send(ctx, path, opts = {}) {
   // stream
   ctx.set('Content-Length', stats.size);
   if (!ctx.response.get('Last-Modified')) ctx.set('Last-Modified', stats.mtime.toUTCString());
-  if (!ctx.response.get('Cache-Control')) ctx.set('Cache-Control', 'max-age=' + (maxage / 1000 | 0));
+  if (!ctx.response.get('Cache-Control')) {
+    const directives = ['max-age=' + (maxage / 1000 | 0)];
+    if (opts.immutable) {
+      directives.push('immutable');
+    }
+    ctx.set('Cache-Control', directives.join(','));
+  }
   ctx.type = type(path);
   ctx.body = fs.createReadStream(path);
 

test/index.js

@@ -493,7 +493,44 @@ describe('send(ctx, file)', function(){
         .expect(200, done);
       })
     })
+
+    describe('and immutable is specified', function(){
+      it('should set the immutable directive', function(done){
+        const app = new Koa();
+
+        app.use(async (ctx) => {
+          const p = '/test/fixtures/user.json';
+          const sent = await send(ctx, p, { immutable: true, maxage: 31536000000 });
+          assert.equal(sent, path.resolve(__dirname + '/fixtures/user.json'));
+        });
+
+        request(app.listen())
+        .get('/')
+        .expect('Cache-Control', 'max-age=31536000,immutable')
+        .expect(200, done);
+      })
+    })
   })
+
+  describe('.immutable option', function(){
+    describe('when trying to get a non-existent file', function(){
+      it('should not set the Cache-Control header', function(done){
+        const app = new Koa();
+
+        app.use(async (ctx) => {
+          await send(ctx, 'test/fixtures/does-not-exist.json', { immutable: true });
+        });
+
+        request(app.listen())
+        .get('/')
+        .expect((res) => {
+          assert.equal(res.header['cache-control'], undefined)
+        })
+        .expect(404, done);
+      })
+    })
+  })
+
   describe('.hidden option', function(){
     describe('when trying to get a hidden file', function(){
       it('should 404', function(done){