koa-files 1.0.2 → 2.1.0

package/README.md

@@ -31,35 +31,27 @@ app.use(server(root, options));
 
 ### Options
 
-#### acceptRanges: `boolean`
+#### acceptRanges?: `boolean`
 
-- Enable or disable accepting ranged requests, defaults to true. Disabling this will not send Accept-Ranges and ignore the contents of the Range request header. defaults to `true`.
+- Enable or disable accepting ranged requests. Disabling this will not send Accept-Ranges and ignore the contents of the Range request header. defaults to `true`.
 
-#### cacheControl: `boolean`
+#### cacheControl?: `string`
 
-- Enable or disable setting Cache-Control response header, defaults to true. Disabling this will ignore the immutable and maxAge options. defaults to `true`.
+- Set Cache-Control response header, defaults to `undefined`, see docs: [Cache-Control in MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control).
 
-#### etag: `boolean`
+#### etag?: `boolean`
 
 - Enable or disable etag generation, defaults to `true`.
 
-#### ignore: `false | (path: string) => boolean`
-
-- Set ignore rules. defaults to `false`.
-
-#### immutable: `boolean`
-
-- Enable or diable the immutable directive in the Cache-Control response header, defaults to false. If set to true, the maxAge option should also be specified to enable caching. The immutable directive will prevent supported clients from making conditional requests during the life of the maxAge option to check if the file has changed. defaults to `false`.
-
-#### lastModified: `boolean`
+#### lastModified?: `boolean`
 
 - Enable or disable Last-Modified header, defaults to true. Uses the file system's last modified value. defaults to `true`.
 
-#### maxAge: `number`
+#### ignore?: `(path: string) => boolean`
 
-- Browser cache max-age in seconds. defaults to `31557600`.
+- Set ignore rules. defaults to `undefined`.
 
-#### defer: `boolean`
+#### defer?: `boolean`
 
 - If true, serves after `await next()`, allowing any downstream middleware to respond first. defaults to `false`.
 
@@ -90,7 +82,7 @@ function httpError(error) {
 }
 
 // Static files server
-app.use(server('tests'));
+app.use(server('tests', { cacheControl: 'public, max-age=31557600' }));
 
 // Listen error event
 app.on('error', error => !httpError(error) && console.error(error));

package/cjs/Send.js

@@ -0,0 +1,354 @@
+'use strict';
+
+var etag = require('etag');
+var destroy = require('destroy');
+var stream = require('stream');
+var fs = require('fs');
+var path = require('path');
+var parseRange = require('range-parser');
+var utils = require('./utils.js');
+
+/**
+ * @module Send
+ * @license MIT
+ * @author nuintun
+ */
+/**
+ * @class Send
+ */
+class Send {
+  /**
+   * @constructor
+   * @param {Context} ctx
+   * @param {string} root
+   * @param {Options} options
+   */
+  constructor(ctx, root = '.', options) {
+    let { cacheControl } = options;
+    const path$1 = utils.decodeURI(ctx.path);
+    this.ctx = ctx;
+    this.root = utils.unixify(path.resolve(root));
+    this.options = Object.assign(Object.assign({}, options), { cacheControl });
+    this.path = path$1 === -1 ? -1 : utils.unixify(path.join(this.root, path$1));
+  }
+  /**
+   * @method isConditionalGET
+   * @returns {boolean}
+   */
+  isConditionalGET() {
+    const { request } = this.ctx;
+    return !!(
+      request.get('If-Match') ||
+      request.get('If-None-Match') ||
+      request.get('If-Modified-Since') ||
+      request.get('if-Unmodified-Since')
+    );
+  }
+  /**
+   * @method isPreconditionFailure
+   * @returns {boolean}
+   */
+  isPreconditionFailure() {
+    const { request, response } = this.ctx;
+    // If-Match
+    const match = request.get('If-Match');
+    if (match) {
+      const etag = response.get('ETag');
+      return !etag || (match !== '*' && !utils.isETagFresh(match, etag));
+    }
+    // If-Unmodified-Since
+    const unmodifiedSince = Date.parse(request.get('If-Unmodified-Since'));
+    if (!isNaN(unmodifiedSince)) {
+      const lastModified = Date.parse(response.get('Last-Modified'));
+      return isNaN(lastModified) || lastModified > unmodifiedSince;
+    }
+    return false;
+  }
+  /**
+   * @method isRangeFresh
+   * @returns {boolean}
+   */
+  isRangeFresh() {
+    const { request, response } = this.ctx;
+    const ifRange = request.get('If-Range');
+    // No If-Range
+    if (!ifRange) {
+      return true;
+    }
+    // If-Range as etag
+    if (utils.isETag(ifRange)) {
+      const etag = response.get('ETag');
+      return !!(etag && utils.isETagFresh(ifRange, etag));
+    }
+    // If-Range as modified date
+    const lastModified = response.get('Last-Modified');
+    return Date.parse(lastModified) <= Date.parse(ifRange);
+  }
+  /**
+   * @method isIgnore
+   * @param {string} path
+   * @returns {boolean}
+   */
+  isIgnore(path) {
+    const { ignore } = this.options;
+    return (typeof ignore === 'function' ? ignore(path) : false) === true;
+  }
+  /**
+   * @method parseRange
+   * @param {Stats} stats
+   * @returns {Ranges}
+   */
+  parseRange(stats) {
+    const { ctx } = this;
+    const result = [];
+    const { size } = stats;
+    const { request } = ctx;
+    // Content-Length
+    let contentLength = size;
+    // Range support
+    if (this.options.acceptRanges !== false) {
+      const range = request.get('Range');
+      // Range fresh
+      if (range && this.isRangeFresh()) {
+        // Parse range -1 -2 or []
+        const ranges = parseRange(size, range, { combine: true });
+        // -1 signals an unsatisfiable range
+        // -2 signals a malformed header string
+        if (ranges === -1 || ranges === -2) {
+          return ranges;
+        }
+        // Ranges ok, support multiple ranges
+        if (ranges.type === 'bytes') {
+          // Set 206 status
+          ctx.status = 206;
+          // Multiple ranges
+          if (ranges.length > 1) {
+            // Reset content-length
+            contentLength = 0;
+            // Range boundary
+            const boundary = `<${utils.boundaryGenerator()}>`;
+            const suffix = `\r\n--${boundary}--\r\n`;
+            const contentType = `Content-Type: ${ctx.type}`;
+            ctx.type = `multipart/byteranges; boundary=${boundary}`;
+            // Map ranges
+            ranges.forEach(({ start, end }, index) => {
+              // The first prefix boundary no \r\n
+              const prefixHead = index > 0 ? '\r\n' : '';
+              const contentRange = `Content-Range: bytes ${start}-${end}/${size}`;
+              const prefix = `${prefixHead}--${boundary}\r\n${contentType}\r\n${contentRange}\r\n\r\n`;
+              // Compute content-length
+              contentLength += end - start + 1 + Buffer.byteLength(prefix);
+              // Cache range
+              result.push({ start, end, prefix });
+            });
+            // The last add suffix boundary
+            result[result.length - 1].suffix = suffix;
+            // Compute content-length
+            contentLength += Buffer.byteLength(suffix);
+          } else {
+            const { start, end } = ranges[0];
+            ctx.set('Content-Range', `bytes ${start}-${end}/${size}`);
+            // Compute content-length
+            contentLength = end - start + 1;
+            // Cache range
+            result.push({ start, end });
+          }
+        }
+      }
+    }
+    // Set Content-Length
+    ctx.length = contentLength;
+    return result.length ? result : [{ start: 0 }];
+  }
+  /**
+   * @method setupHeaders
+   * @param {string} path
+   * @param {Stats} stats
+   */
+  setupHeaders(path$1, stats) {
+    const { ctx, options } = this;
+    const { toString } = Object.prototype;
+    const { acceptRanges, cacheControl, lastModified } = options;
+    // Set status
+    ctx.status = 200;
+    // Set Content-Type
+    ctx.type = path.extname(path$1);
+    // ETag
+    if (options.etag !== false) {
+      // Set ETag
+      ctx.set('ETag', etag(stats));
+    }
+    // Accept-Ranges
+    if (acceptRanges !== false) {
+      // Set Accept-Ranges
+      ctx.set('Accept-Ranges', 'bytes');
+    }
+    // Last-Modified
+    if (lastModified !== false) {
+      // Set mtime utc string
+      ctx.set('Last-Modified', stats.mtime.toUTCString());
+    }
+    // Cache-Control
+    if (cacheControl && toString.call(cacheControl) === '[object String]') {
+      // Set Cache-Control
+      ctx.set('Cache-Control', cacheControl);
+    }
+  }
+  /**
+   * @method read
+   * @param {string} path
+   * @param {Range} range
+   * @param {PassThrough} buffer
+   * @param {boolean} end
+   * @returns {Promise<true>}
+   */
+  read(path, range, buffer, end) {
+    return new Promise((resolve, reject) => {
+      // Create file stream
+      const file = fs.createReadStream(path, range);
+      // File read stream open
+      if (range.prefix) {
+        file.once('open', () => {
+          // Write prefix boundary
+          buffer.write(range.prefix);
+        });
+      }
+      // File read stream error
+      file.once('error', error => {
+        // Unpipe
+        file.unpipe(buffer);
+        // Destroy file stream
+        destroy(file);
+        // Reject
+        reject(error);
+      });
+      // File read stream end
+      if (range.suffix) {
+        file.once('end', () => {
+          // Push suffix boundary
+          buffer.write(range.suffix);
+        });
+      }
+      // File read stream close
+      file.once('close', () => {
+        // Unpipe
+        file.unpipe(buffer);
+        // Destroy file stream
+        destroy(file);
+        // Resolve
+        resolve(true);
+      });
+      // Write data to buffer
+      file.pipe(buffer, { end });
+    });
+  }
+  /**
+   * @method send
+   * @param {string} path
+   * @param {Range[]} ranges
+   */
+  async send(path, ranges) {
+    // Ranges count
+    let count = ranges.length;
+    // Set stream body, highWaterMark 64kb
+    const stream$1 = new stream.PassThrough({ highWaterMark: 65536 });
+    // Set response body
+    this.ctx.body = stream$1;
+    // Read file ranges
+    try {
+      for (const range of ranges) {
+        await this.read(path, range, stream$1, --count === 0);
+      }
+    } catch (error) {
+      // End stream when read exception
+      stream$1.end();
+    }
+  }
+  /**
+   * @method response
+   * @returns {Promise<boolean>}
+   */
+  async response() {
+    const { ctx, root, path } = this;
+    // Only support GET and HEAD (405)
+    if (ctx.method !== 'GET' && ctx.method !== 'HEAD') {
+      return false;
+    }
+    // Path -1 or null byte(s)
+    if (path === -1 || path.includes('\0')) {
+      return ctx.throw(400);
+    }
+    // Malicious path (403)
+    if (utils.isOutRoot(path, root)) {
+      return false;
+    }
+    // Is ignore path or file (403)
+    if (this.isIgnore(path)) {
+      return false;
+    }
+    // File stats
+    let stats;
+    // Get file stats
+    try {
+      stats = await utils.fstat(path);
+    } catch (error) {
+      // 404 | 500
+      return false;
+    }
+    // File not exist (404 | 500)
+    if (!stats) {
+      return false;
+    }
+    // Is directory (403)
+    if (stats.isDirectory()) {
+      return false;
+    }
+    // Not a directory but has trailing slash (404)
+    if (utils.hasTrailingSlash(path)) {
+      return false;
+    }
+    // Setup headers
+    this.setupHeaders(path, stats);
+    // Conditional get support
+    if (this.isConditionalGET()) {
+      // Request precondition failure
+      if (this.isPreconditionFailure()) {
+        return ctx.throw(412);
+      }
+      // Request fresh (304)
+      if (ctx.fresh) {
+        // Set status
+        ctx.status = 304;
+        // Set body null
+        ctx.body = null;
+        return true;
+      }
+    }
+    // Head request
+    if (ctx.method === 'HEAD') {
+      // Set content-length
+      ctx.length = stats.size;
+      // Set body null
+      ctx.body = null;
+      return true;
+    }
+    // Parse ranges
+    const ranges = this.parseRange(stats);
+    // 416
+    if (ranges === -1) {
+      // Set content-range
+      ctx.set('Content-Range', `bytes */${stats.size}`);
+      // Unsatisfiable 416
+      return ctx.throw(416);
+    }
+    // 400
+    if (ranges === -2) {
+      return ctx.throw(400);
+    }
+    // Send file
+    this.send(path, ranges);
+    return true;
+  }
+}
+
+module.exports = Send;

package/cjs/index.js

@@ -0,0 +1,28 @@
+'use strict';
+
+var Send = require('./Send.js');
+
+/**
+ * @module index
+ * @license MIT
+ * @author nuintun
+ */
+/**
+ * @function server
+ * @param {string} root
+ * @param {Options} options
+ */
+function server(root, options = {}) {
+  if (options.defer) {
+    return async (ctx, next) => {
+      await next();
+      await new Send(ctx, root, options).response();
+    };
+  }
+  return async (ctx, next) => {
+    const respond = await new Send(ctx, root, options).response();
+    !respond && (await next());
+  };
+}
+
+module.exports = server;

package/cjs/utils.js

@@ -0,0 +1,138 @@
+'use strict';
+
+var fs = require('fs');
+var path = require('path');
+
+/**
+ * @module utils
+ * @license MIT
+ * @author nuintun
+ */
+const CHARS = Array.from('0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz');
+/**
+ * @function isOutRoot
+ * @description Test path is out of bound of root
+ * @param {string} path
+ * @param {string} root
+ * @returns {boolean}
+ */
+function isOutRoot(path$1, root) {
+  path$1 = path.relative(root, path$1);
+  return /\.\.(?:[\\/]|$)/.test(path$1) || path.isAbsolute(path$1);
+}
+/**
+ * @function unixify
+ * @description Convert path separators to posix/unix-style forward slashes
+ * @param {string} path
+ * @returns {string}
+ */
+function unixify(path) {
+  return path.replace(/\\/g, '/');
+}
+/**
+ * @function decodeURI
+ * @description Decode URI component.
+ * @param {string} URI
+ * @returns {string|-1}
+ */
+function decodeURI(URI) {
+  try {
+    return decodeURIComponent(URI);
+  } catch (error) {
+    return -1;
+  }
+}
+/**
+ * @function boundaryGenerator
+ * @description Create boundary
+ * @returns {string}
+ */
+function boundaryGenerator() {
+  let boundary = '';
+  // Create boundary
+  for (let i = 0; i < 38; i++) {
+    boundary += CHARS[Math.floor(Math.random() * 62)];
+  }
+  // Return boundary
+  return boundary;
+}
+/**
+ * @function fstat
+ * @param {string} path
+ * @returns {Promise<Stats>}
+ */
+function fstat(path) {
+  return new Promise((resolve, reject) => {
+    fs.stat(path, (error, stats) => {
+      error ? reject(error) : resolve(stats);
+    });
+  });
+}
+/**
+ * @function hasTrailingSlash
+ * @param {string} path
+ * @returns {boolean}
+ */
+function hasTrailingSlash(path) {
+  return /\/$/.test(path);
+}
+/**
+ * @function parseTokens
+ * @description Parse a HTTP tokens.
+ * @param {string[]} value
+ */
+function parseTokens(value) {
+  let start = 0;
+  let end = 0;
+  let tokens = [];
+  // gather tokens
+  for (let i = 0, length = value.length; i < length; i++) {
+    switch (value.charCodeAt(i)) {
+      case 0x20:
+        // ' '
+        if (start === end) {
+          start = end = i + 1;
+        }
+        break;
+      case 0x2c:
+        // ','
+        tokens.push(value.substring(start, end));
+        start = end = i + 1;
+        break;
+      default:
+        end = i + 1;
+        break;
+    }
+  }
+  // final token
+  tokens.push(value.substring(start, end));
+  return tokens;
+}
+/**
+ * @function isETagFresh
+ * @param {string} match
+ * @param {string} etag
+ * @returns {boolean}
+ */
+function isETagFresh(match, etag) {
+  return parseTokens(match).some(match => {
+    return match === etag || match === 'W/' + etag || 'W/' + match === etag;
+  });
+}
+/**
+ * @function isETag
+ * @param {string} etag
+ * @returns {boolean}
+ */
+function isETag(etag) {
+  return /(?:W\/)?"(?:[ !#-\x7E\x80-\xFF]*|\r\n[\t ]|\\.)*"/.test(etag);
+}
+
+exports.boundaryGenerator = boundaryGenerator;
+exports.decodeURI = decodeURI;
+exports.fstat = fstat;
+exports.hasTrailingSlash = hasTrailingSlash;
+exports.isETag = isETag;
+exports.isETagFresh = isETagFresh;
+exports.isOutRoot = isOutRoot;
+exports.unixify = unixify;