koa-files 2.3.8 → 3.0.1

package/cjs/utils/http.cjs

@@ -0,0 +1,227 @@
+/**
+ * @package koa-files
+ * @license MIT
+ * @version 3.0.1
+ * @author nuintun <nuintun@qq.com>
+ * @description A static files serving middleware for koa.
+ * @see https://github.com/nuintun/koa-files#readme
+ */
+
+'use strict';
+
+const hash = require('./hash.cjs');
+const parseRange = require('range-parser');
+
+function _interopDefault(e) {
+  return e && e.__esModule ? e : { default: e };
+}
+
+const parseRange__default = /*#__PURE__*/ _interopDefault(parseRange);
+
+/**
+ * @module http
+ */
+/**
+ * @function isETag
+ * @description Check if etag is valid.
+ * @param value The value to check.
+ */
+function isETag(value) {
+  return /^(?:W\/)?"[\s\S]+"$/.test(value);
+}
+/**
+ * @function parseTokens
+ * @description Parse HTTP tokens.
+ * @param value The tokens value string.
+ */
+function parseTokens(value) {
+  let end = 0;
+  let start = 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 isRangeFresh
+ * @description Check if request range fresh.
+ * @param context Koa context.
+ */
+function isRangeFresh(context) {
+  const { request, response } = context;
+  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);
+}
+/**
+ * @function isETagFresh
+ * @description Check if etag is fresh.
+ * @param match The match value.
+ * @param etag The etag value.
+ */
+function isETagFresh(match, etag) {
+  return parseTokens(match).some(match => {
+    return match === etag || match === 'W/' + etag || 'W/' + match === etag;
+  });
+}
+/**
+ * @function decodeURI
+ * @description Decode URI component.
+ * @param URI The URI to decode.
+ */
+function decodeURI(URI) {
+  try {
+    return decodeURIComponent(URI);
+  } catch (_a) {
+    return -1;
+  }
+}
+/**
+ * @function isConditionalGET
+ * @description Check if request is conditional GET.
+ * @param context Koa context.
+ */
+function isConditionalGET(context) {
+  const { request } = context;
+  return !!(
+    request.get('If-Match') ||
+    request.get('If-None-Match') ||
+    request.get('If-Modified-Since') ||
+    request.get('If-Unmodified-Since')
+  );
+}
+/**
+ * @function isPreconditionFailure
+ * @description Check if request precondition failure.
+ * @param context Koa context.
+ */
+function isPreconditionFailure({ request, response }) {
+  // If-Match.
+  const match = request.get('If-Match');
+  // Check if request match.
+  if (match) {
+    // Etag.
+    const etag = response.get('ETag');
+    return !etag || match === '*' || !isETagFresh(match, etag);
+  }
+  // If-Unmodified-Since.
+  const unmodifiedSince = Date.parse(request.get('If-Unmodified-Since'));
+  // Check if request unmodified.
+  if (!Number.isNaN(unmodifiedSince)) {
+    // Last-Modified.
+    const lastModified = Date.parse(response.get('Last-Modified'));
+    return Number.isNaN(lastModified) || lastModified > unmodifiedSince;
+  }
+  // Check precondition passed.
+  return false;
+}
+/**
+ * @function parseRanges
+ * @description Parse ranges.
+ * @param context Koa context.
+ * @param stats File stats.
+ */
+function parseRanges(context, stats) {
+  const { size } = stats;
+  // Range support.
+  if (/^bytes$/i.test(context.response.get('Accept-Ranges'))) {
+    const range = context.request.get('Range');
+    // Range fresh.
+    if (range && isRangeFresh(context)) {
+      // Parse range -1 -2 or [].
+      const parsed = parseRange__default.default(size, range, { combine: true });
+      // -1 signals an unsatisfiable range.
+      // -2 signals a malformed header string.
+      if (parsed === -1 || parsed === -2) {
+        return parsed;
+      }
+      // Ranges ok, support multiple ranges.
+      if (parsed.type === 'bytes') {
+        // Set 206 status.
+        context.status = 206;
+        const { length } = parsed;
+        // Multiple ranges.
+        if (length > 1) {
+          // Content-Length.
+          let contentLength = 0;
+          // Ranges.
+          const ranges = [];
+          // Range boundary.
+          const boundary = `<${hash.generate()}>`;
+          // Range suffix.
+          const suffix = `\r\n--${boundary}--\r\n`;
+          // Multipart Content-Type.
+          const contentType = `Content-Type: ${context.type}`;
+          // Override Content-Type.
+          context.type = `multipart/byteranges; boundary=${boundary}`;
+          // Map ranges.
+          for (let index = 0; index < length; index++) {
+            const { start, end } = parsed[index];
+            // The first prefix boundary no \r\n.
+            const head = index > 0 ? '\r\n' : '';
+            const contentRange = `Content-Range: bytes ${start}-${end}/${size}`;
+            const prefix = `${head}--${boundary}\r\n${contentType}\r\n${contentRange}\r\n\r\n`;
+            // Compute Content-Length
+            contentLength += end - start + 1 + Buffer.byteLength(prefix);
+            // Cache range.
+            ranges.push({ start, end, prefix });
+          }
+          // The last add suffix boundary.
+          ranges[length - 1].suffix = suffix;
+          // Compute Content-Length.
+          contentLength += Buffer.byteLength(suffix);
+          // Set Content-Length.
+          context.length = contentLength;
+          // Return ranges.
+          return ranges;
+        } else {
+          const [{ start, end }] = parsed;
+          // Set Content-Length.
+          context.length = end - start + 1;
+          // Set Content-Range.
+          context.set('Content-Range', `bytes ${start}-${end}/${size}`);
+          // Return ranges.
+          return parsed;
+        }
+      }
+    }
+  }
+  // Set Content-Length.
+  context.length = size;
+  // Return ranges.
+  return [{ start: 0, end: Math.max(size - 1) }];
+}
+
+exports.decodeURI = decodeURI;
+exports.isConditionalGET = isConditionalGET;
+exports.isPreconditionFailure = isPreconditionFailure;
+exports.parseRanges = parseRanges;

package/cjs/utils/path.cjs

@@ -0,0 +1,46 @@
+/**
+ * @package koa-files
+ * @license MIT
+ * @version 3.0.1
+ * @author nuintun <nuintun@qq.com>
+ * @description A static files serving middleware for koa.
+ * @see https://github.com/nuintun/koa-files#readme
+ */
+
+'use strict';
+
+const path = require('path');
+
+/**
+ * @module path
+ */
+/**
+ * @function unixify
+ * @description Convert path to unix style.
+ * @param path The path to convert.
+ */
+function unixify(path) {
+  return path.replace(/\\/g, '/');
+}
+/**
+ * @function hasTrailingSlash
+ * @description Check if path has trailing slash.
+ * @param path The path to check.
+ */
+function hasTrailingSlash(path) {
+  return /\/$/.test(path);
+}
+/**
+ * @function isOutRoot
+ * @description Check if path is out of root.
+ * @param path The path to check.
+ * @param root The root path.
+ */
+function isOutRoot(path$1, root) {
+  path$1 = path.relative(root, path$1);
+  return /\.\.(?:[\\/]|$)/.test(path$1) || path.isAbsolute(path$1);
+}
+
+exports.hasTrailingSlash = hasTrailingSlash;
+exports.isOutRoot = isOutRoot;
+exports.unixify = unixify;

package/esm/Service.js

@@ -0,0 +1,271 @@
+/**
+ * @package koa-files
+ * @license MIT
+ * @version 3.0.1
+ * @author nuintun <nuintun@qq.com>
+ * @description A static files serving middleware for koa.
+ * @see https://github.com/nuintun/koa-files#readme
+ */
+
+import createETag from 'etag';
+import destroy from 'destroy';
+import { PassThrough } from 'stream';
+import { stat } from './utils/fs.js';
+import { resolve, extname, join } from 'path';
+import { unixify, isOutRoot, hasTrailingSlash } from './utils/path.js';
+import { decodeURI, isConditionalGET, isPreconditionFailure, parseRanges } from './utils/http.js';
+
+/**
+ * @module Service
+ */
+/**
+ * @function isFunction
+ * @description Check if value is function.
+ * @param value The value to check.
+ */
+function isFunction(value) {
+  return typeof value === 'function';
+}
+/**
+ * @class Service
+ */
+class Service {
+  /**
+   * @constructor
+   * @description Create file service.
+   * @param root File service root.
+   * @param options File service options.
+   */
+  constructor(root, options) {
+    this.options = options;
+    this.root = unixify(resolve(root));
+  }
+  /**
+   * @private
+   * @method isIgnore
+   * @description Check if path is ignore.
+   * @param path File path.
+   */
+  isIgnore(path) {
+    const { ignore } = this.options;
+    return (isFunction(ignore) ? ignore(path) : false) === true;
+  }
+  /**
+   * @private
+   * @method setupHeaders
+   * @description Setup headers
+   * @param context Koa context
+   * @param path File path
+   * @param stats File stats
+   */
+  setupHeaders(context, path, stats) {
+    const { options } = this;
+    const { headers, etag } = options;
+    // Set status.
+    context.status = 200;
+    // Set Content-Type.
+    context.type = extname(path);
+    // Accept-Ranges.
+    if (options.acceptRanges === false) {
+      // Set Accept-Ranges to none tell client not support.
+      context.set('Accept-Ranges', 'none');
+    } else {
+      // Set Accept-Ranges.
+      context.set('Accept-Ranges', 'bytes');
+    }
+    // ETag.
+    if (etag === false) {
+      // Remove ETag.
+      context.remove('ETag');
+    } else {
+      context.set('ETag', createETag(stats));
+    }
+    // Last-Modified.
+    if (options.lastModified === false) {
+      // Remove Last-Modified.
+      context.remove('Last-Modified');
+    } else {
+      // Set mtime utc string.
+      context.set('Last-Modified', stats.mtime.toUTCString());
+    }
+    // Set headers.
+    if (headers) {
+      if (isFunction(headers)) {
+        const fields = headers(path, stats);
+        if (fields) {
+          context.set(fields);
+        }
+      } else {
+        context.set(headers);
+      }
+    }
+  }
+  /**
+   * @private
+   * @method write
+   * @description Write file to stream.
+   * @param stream Destination stream.
+   * @param path The file path to read.
+   * @param range The range to read.
+   * @param end Is destory destination stream after read complete.
+   */
+  write(stream, path, range, end) {
+    const { fs } = this.options;
+    return new Promise(resolve => {
+      // Range prefix and suffix.
+      const { prefix, suffix } = range;
+      // Create file stream reader.
+      const reader = fs.createReadStream(path, range);
+      // File read stream open.
+      if (prefix) {
+        reader.once('open', () => {
+          // Write prefix boundary.
+          stream.write(prefix);
+        });
+      }
+      // File read stream end.
+      if (suffix) {
+        reader.once('end', () => {
+          // Push suffix boundary.
+          stream.write(suffix);
+        });
+      }
+      // File read stream error.
+      reader.once('error', () => {
+        // End stream.
+        stream.end();
+        // Unpipe.
+        reader.unpipe();
+        // Destroy.
+        destroy(reader);
+        // Resolve.
+        resolve(false);
+      });
+      // File read stream close.
+      reader.once('close', () => {
+        // Unpipe.
+        reader.unpipe();
+        // Destroy.
+        destroy(reader);
+        // Resolve.
+        resolve(true);
+      });
+      // Write data to buffer.
+      reader.pipe(stream, { end });
+    });
+  }
+  /**
+   * @private
+   * @method send
+   * @description Send file.
+   * @param context Koa context.
+   * @param path File path.
+   * @param ranges Read ranges.
+   */
+  async send(context, path, ranges) {
+    // Set stream body, highWaterMark 64kb.
+    const stream = new PassThrough({
+      highWaterMark: 65536
+    });
+    // Set response body.
+    context.body = stream;
+    // Ranges length.
+    let { length } = ranges;
+    // Write ranges to stream.
+    for (const range of ranges) {
+      // Write range.
+      const passed = await this.write(stream, path, range, --length === 0);
+      // If not passed, break.
+      if (!passed) {
+        break;
+      }
+    }
+  }
+  /**
+   * @public
+   * @method response
+   * @description Response to koa context.
+   * @param context Koa context.
+   */
+  async response(context) {
+    const { root } = this;
+    // Only support GET and HEAD (405).
+    if (context.method !== 'GET' && context.method !== 'HEAD') {
+      return false;
+    }
+    // Get path of file
+    const pathname = decodeURI(context.path);
+    const path = pathname === -1 ? pathname : unixify(join(root, pathname));
+    // Path -1 or null byte(s)
+    if (path === -1 || path.includes('\0')) {
+      return context.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.
+    const stats = await stat(this.options.fs, path);
+    // Check file stats.
+    if (
+      // File not exist (404 | 500).
+      stats == null ||
+      // Is directory (403).
+      stats.isDirectory() ||
+      // Not a directory but has trailing slash (404).
+      hasTrailingSlash(path)
+    ) {
+      return false;
+    }
+    // Setup headers.
+    this.setupHeaders(context, path, stats);
+    // Conditional get support.
+    if (isConditionalGET(context)) {
+      // Request precondition failure.
+      if (isPreconditionFailure(context)) {
+        return context.throw(412);
+      }
+      // Request fresh (304).
+      if (context.fresh) {
+        // Set status.
+        context.status = 304;
+        // Set body null.
+        context.body = null;
+        // File found.
+        return true;
+      }
+    }
+    // Head request.
+    if (context.method === 'HEAD') {
+      // Set Content-Length.
+      context.length = stats.size;
+      // Set body null
+      context.body = null;
+      // File found.
+      return true;
+    }
+    // Parsed ranges.
+    const ranges = parseRanges(context, stats);
+    // 416
+    if (ranges === -1) {
+      // Set Content-Range.
+      context.set('Content-Range', `bytes */${stats.size}`);
+      // Unsatisfiable 416.
+      return context.throw(416);
+    }
+    // 400.
+    if (ranges === -2) {
+      return context.throw(400);
+    }
+    // Send file.
+    this.send(context, path, ranges);
+    // File found.
+    return true;
+  }
+}
+
+export { Service as default };

package/esm/index.js

@@ -1,18 +1,17 @@
 /**
  * @package koa-files
  * @license MIT
- * @version 2.3.8
+ * @version 3.0.1
  * @author nuintun <nuintun@qq.com>
  * @description A static files serving middleware for koa.
  * @see https://github.com/nuintun/koa-files#readme
  */
 
-import Files from './Files.js';
+import fs from 'fs';
+import Service from './Service.js';
 
 /**
  * @module index
- * @license MIT
- * @author nuintun
  */
 /**
  * @function server
@@ -20,15 +19,16 @@ import Files from './Files.js';
  * @param {Options} options
  */
 function server(root, options) {
-  const files = new Files(root, options);
-  if (options && options.defer) {
+  const config = Object.assign({ fs }, options);
+  const service = new Service(root, config);
+  if (config.defer) {
     return async (context, next) => {
       await next();
-      await files.response(context);
+      await service.response(context);
     };
   }
   return async (context, next) => {
-    if (!(await files.response(context))) {
+    if (!(await service.response(context))) {
       await next();
     }
   };

package/esm/utils/fs.js

@@ -0,0 +1,27 @@
+/**
+ * @package koa-files
+ * @license MIT
+ * @version 3.0.1
+ * @author nuintun <nuintun@qq.com>
+ * @description A static files serving middleware for koa.
+ * @see https://github.com/nuintun/koa-files#readme
+ */
+
+/**
+ * @module fs
+ */
+/**
+ * @function stat
+ * @description Get file stats.
+ * @param fs The file system to used.
+ * @param path The file path.
+ */
+function stat(fs, path) {
+  return new Promise(resolve => {
+    fs.stat(path, (error, stats) => {
+      resolve(error ? null : stats);
+    });
+  });
+}
+
+export { stat };

package/esm/utils/hash.js

@@ -0,0 +1,44 @@
+/**
+ * @package koa-files
+ * @license MIT
+ * @version 3.0.1
+ * @author nuintun <nuintun@qq.com>
+ * @description A static files serving middleware for koa.
+ * @see https://github.com/nuintun/koa-files#readme
+ */
+
+import { getRandomValues } from 'crypto';
+
+/**
+ * @module hash
+ */
+// prettier-ignore
+const CHARS = [
+    // 0-9
+    '0', '1', '2', '3', '4', '5', '6', '7', '8', '9',
+    // A-M
+    'A', 'B', 'C', 'D', 'E', 'F', 'G', 'H', 'I', 'J', 'K', 'L', 'M',
+    // N-Z
+    'N', 'O', 'P', 'Q', 'R', 'S', 'T', 'U', 'V', 'W', 'X', 'Y', 'Z',
+    // a-m
+    'a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i', 'j', 'k', 'l', 'm',
+    // n-z
+    'n', 'o', 'p', 'q', 'r', 's', 't', 'u', 'v', 'w', 'x', 'y', 'z'
+];
+/**
+ * @function generate
+ * @description Generate a hash.
+ * @param length The length of hash.
+ */
+function generate(length = 32) {
+  let hash = '';
+  const randomValues = getRandomValues(new Uint8Array(length));
+  // Create hash.
+  for (const value of randomValues) {
+    hash += CHARS[value % 62];
+  }
+  // Return hash.
+  return hash;
+}
+
+export { generate };