koa-files 1.0.2 → 2.1.0

package/esm/Send.js

@@ -0,0 +1,352 @@
+import etag from 'etag';
+import destroy from 'destroy';
+import { PassThrough } from 'stream';
+import fs from 'fs';
+import { resolve, join, extname } from 'path';
+import parseRange from 'range-parser';
+import { decodeURI, unixify, isETagFresh, isETag, boundaryGenerator, isOutRoot, fstat, hasTrailingSlash } from './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 = decodeURI(ctx.path);
+    this.ctx = ctx;
+    this.root = unixify(resolve(root));
+    this.options = Object.assign(Object.assign({}, options), { cacheControl });
+    this.path = path === -1 ? -1 : unixify(join(this.root, path));
+  }
+  /**
+   * @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 !== '*' && !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 (isETag(ifRange)) {
+      const etag = response.get('ETag');
+      return !!(etag && 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 = `<${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, stats) {
+    const { ctx, options } = this;
+    const { toString } = Object.prototype;
+    const { acceptRanges, cacheControl, lastModified } = options;
+    // Set status
+    ctx.status = 200;
+    // Set Content-Type
+    ctx.type = extname(path);
+    // 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 = new PassThrough({ highWaterMark: 65536 });
+    // Set response body
+    this.ctx.body = stream;
+    // Read file ranges
+    try {
+      for (const range of ranges) {
+        await this.read(path, range, stream, --count === 0);
+      }
+    } catch (error) {
+      // End stream when read exception
+      stream.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 (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 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 (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;
+  }
+}
+
+export { Send as default };

package/esm/index.js

@@ -0,0 +1,26 @@
+import Send from './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());
+  };
+}
+
+export { server as default };

package/esm/utils.js

@@ -0,0 +1,129 @@
+import fs from 'fs';
+import { isAbsolute, relative } from '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, root) {
+  path = relative(root, path);
+  return /\.\.(?:[\\/]|$)/.test(path) || isAbsolute(path);
+}
+/**
+ * @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);
+}
+
+export { boundaryGenerator, decodeURI, fstat, hasTrailingSlash, isETag, isETagFresh, isOutRoot, unixify };

package/package.json

@@ -1,13 +1,21 @@
 {
   "name": "koa-files",
-  "version": "1.0.2",
+  "version": "2.1.0",
   "description": "A static files serving middleware for koa.",
-  "main": "index.js",
+  "main": "cjs/index.js",
+  "module": "esm/index.js",
   "typings": "typings/index.d.ts",
   "scripts": {
+    "tests": "node tests",
+    "lint": "tsc --noEmit",
+    "clean": "node tools/clean.js",
     "prepublishOnly": "npm run build",
-    "build": "rollup -c rollup.config.js",
-    "tests": "npm run build & node tests/server.js"
+    "build:cjs": "rollup -c tools/rollup.cjs.js",
+    "build:esm": "rollup -c tools/rollup.esm.js",
+    "format": "prettier --write tools src cjs esm tests typings",
+    "build": "npm run clean && npm run build:main && npm run format",
+    "build:main": "npm run build:cjs && npm run build:esm && npm run build:typings",
+    "build:typings": "tsc --declaration --emitDeclarationOnly --declarationDir typings"
   },
   "repository": {
     "type": "git",
@@ -38,19 +46,22 @@
     "koa": "^2.0.0"
   },
   "dependencies": {
-    "destroy": "^1.0.4",
+    "destroy": "^1.2.0",
     "etag": "^1.8.1",
-    "range-parser": "^1.2.1"
+    "range-parser": "^1.2.1",
+    "tslib": "^2.3.1"
   },
   "devDependencies": {
+    "@rollup/plugin-typescript": "^8.3.1",
     "@types/destroy": "^1.0.0",
-    "@types/etag": "^1.8.0",
-    "@types/koa": "^2.11.3",
-    "@types/range-parser": "^1.2.3",
-    "koa": "^2.11.0",
+    "@types/etag": "^1.8.1",
+    "@types/koa": "^2.13.4",
+    "@types/range-parser": "^1.2.4",
+    "koa": "^2.13.4",
+    "magic-string": "^0.26.1",
+    "prettier": "^2.6.0",
     "rimraf": "^3.0.2",
-    "rollup": "^2.8.2",
-    "rollup-plugin-typescript2": "^0.27.0",
-    "typescript": "^3.8.3"
+    "rollup": "^2.70.1",
+    "typescript": "^4.6.2"
   }
-}
+}