koa-files 2.3.8 → 3.0.1

package/README.md

@@ -16,48 +16,93 @@ $ npm install koa-files
 
 ## API
 
-```js
-import Koa from 'koa';
-import files from 'koa-files';
+```ts
+import { Middleware } from 'koa';
+import { createReadStream, stat, Stats } from 'fs';
 
-const app = new Koa();
+interface IgnoreFunction {
+  (path: string): boolean;
+}
 
-// Static files server
-app.use(files(root, options));
+interface Headers {
+  [key: string]: string | string[];
+}
+
+interface HeaderFunction {
+  (path: string, stats: Stats): Headers | void;
+}
+
+interface FileSystem {
+  readonly stat: typeof stat;
+  readonly createReadStream: typeof createReadStream;
+}
+
+export interface Options {
+  etag?: boolean;
+  fs?: FileSystem;
+  defer?: boolean;
+  acceptRanges?: boolean;
+  lastModified?: boolean;
+  ignore?: IgnoreFunction;
+  headers?: Headers | HeaderFunction;
+}
+
+export default function server(root: string, options?: Options): Middleware;
 ```
 
-- `root` root directory string. nothing above this root directory can be served.
-- `options` options object.
+### root
+
+- Root directory string.
+- Nothing above this root directory can be served.
 
 ### Options
 
-#### acceptRanges?: `boolean`
+##### `fs`
+
+- Defaults to `node:fs`.
+- The file system to used.
 
-- 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`.
+##### `headers`
 
-#### cacheControl?: `string`
+- Defaults to `undefined`.
+- Set headers to be sent.
+- See docs: [Headers in MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers).
 
-- 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).
+##### `acceptRanges`
 
-#### etag?: `boolean`
+- 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.
+- Can be overridden by the `headers`.
 
-- Enable or disable etag generation, defaults to `true`.
+##### `etag`
 
-#### lastModified?: `boolean`
+- Defaults to `true`.
+- Enable or disable etag generation.
+- Use weak etag internally.
+- Can be overridden by the `headers`.
 
-- Enable or disable Last-Modified header, defaults to true. Uses the file system's last modified value. defaults to `true`.
+##### `lastModified`
 
-#### ignore?: `(path: string) => boolean`
+- Defaults to `true`.
+- Enable or disable Last-Modified header.
+- Use the file system's last modified value.
+- Can be overridden by the `headers`.
 
-- Set ignore rules. defaults to `undefined`.
+##### `ignore`
 
-#### defer?: `boolean`
+- Defaults to `undefined`.
+- Function that determines if a file should be ignored.
 
-- If true, serves after `await next()`, allowing any downstream middleware to respond first. defaults to `false`.
+##### `defer`
+
+- Defaults to `false`.
+- If true, serves after `await next()`.
+- Allowing any downstream middleware to respond first.
 
 ## Example
 
-```js
+```ts
 /**
  * @module server
  * @license MIT
@@ -70,6 +115,15 @@ import files from 'koa-files';
 const app = new Koa();
 const port = process.env.PORT || 80;
 
+// Static files server
+app.use(
+  files('tests', {
+    headers: {
+      'Cache-Control': 'public, max-age=31557600'
+    }
+  })
+);
+
 /**
  * @function httpError
  * @param {NodeJS.ErrnoException} error
@@ -79,14 +133,15 @@ function httpError(error) {
   return /^(EOF|EPIPE|ECANCELED|ECONNRESET|ECONNABORTED)$/i.test(error.code);
 }
 
-// Static files server
-app.use(files('tests', { cacheControl: 'public, max-age=31557600' }));
-
 // Listen error event
-app.on('error', error => !httpError(error) && console.error(error));
+app.on('error', error => {
+  !httpError(error) && console.error(error);
+});
 
 // Start server
-app.listen(port, () => console.log(`> server running at: 127.0.0.1:${port}`));
+app.listen(port, () => {
+  console.log(`> server running at: 127.0.0.1:${port}`);
+});
 ```
 
 ## Features

package/cjs/Service.cjs

@@ -0,0 +1,280 @@
+/**
+ * @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 createETag = require('etag');
+const destroy = require('destroy');
+const stream = require('stream');
+const fs = require('./utils/fs.cjs');
+const path$1 = require('path');
+const path = require('./utils/path.cjs');
+const http = require('./utils/http.cjs');
+
+function _interopDefault(e) {
+  return e && e.__esModule ? e : { default: e };
+}
+
+const createETag__default = /*#__PURE__*/ _interopDefault(createETag);
+const destroy__default = /*#__PURE__*/ _interopDefault(destroy);
+
+/**
+ * @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 = path.unixify(path$1.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 = path$1.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__default.default(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__default.default(reader);
+        // Resolve.
+        resolve(false);
+      });
+      // File read stream close.
+      reader.once('close', () => {
+        // Unpipe.
+        reader.unpipe();
+        // Destroy.
+        destroy__default.default(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$1 = new stream.PassThrough({
+      highWaterMark: 65536
+    });
+    // Set response body.
+    context.body = stream$1;
+    // Ranges length.
+    let { length } = ranges;
+    // Write ranges to stream.
+    for (const range of ranges) {
+      // Write range.
+      const passed = await this.write(stream$1, 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 = http.decodeURI(context.path);
+    const path$2 = pathname === -1 ? pathname : path.unixify(path$1.join(root, pathname));
+    // Path -1 or null byte(s)
+    if (path$2 === -1 || path$2.includes('\0')) {
+      return context.throw(400);
+    }
+    // Malicious path (403).
+    if (path.isOutRoot(path$2, root)) {
+      return false;
+    }
+    // Is ignore path or file (403).
+    if (this.isIgnore(path$2)) {
+      return false;
+    }
+    // File stats.
+    const stats = await fs.stat(this.options.fs, path$2);
+    // Check file stats.
+    if (
+      // File not exist (404 | 500).
+      stats == null ||
+      // Is directory (403).
+      stats.isDirectory() ||
+      // Not a directory but has trailing slash (404).
+      path.hasTrailingSlash(path$2)
+    ) {
+      return false;
+    }
+    // Setup headers.
+    this.setupHeaders(context, path$2, stats);
+    // Conditional get support.
+    if (http.isConditionalGET(context)) {
+      // Request precondition failure.
+      if (http.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 = http.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$2, ranges);
+    // File found.
+    return true;
+  }
+}
+
+module.exports = Service;

package/cjs/index.cjs

@@ -1,7 +1,7 @@
 /**
  * @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
@@ -9,12 +9,17 @@
 
 'use strict';
 
-const Files = require('./Files.cjs');
+const fs = require('fs');
+const Service = require('./Service.cjs');
+
+function _interopDefault(e) {
+  return e && e.__esModule ? e : { default: e };
+}
+
+const fs__default = /*#__PURE__*/ _interopDefault(fs);
 
 /**
  * @module index
- * @license MIT
- * @author nuintun
  */
 /**
  * @function server
@@ -22,15 +27,16 @@ const Files = require('./Files.cjs');
  * @param {Options} options
  */
 function server(root, options) {
-  const files = new Files(root, options);
-  if (options && options.defer) {
+  const config = Object.assign({ fs: fs__default.default }, 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/cjs/utils/fs.cjs

@@ -0,0 +1,29 @@
+/**
+ * @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';
+
+/**
+ * @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);
+    });
+  });
+}
+
+exports.stat = stat;

package/cjs/utils/hash.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 crypto = require('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 = crypto.getRandomValues(new Uint8Array(length));
+  // Create hash.
+  for (const value of randomValues) {
+    hash += CHARS[value % 62];
+  }
+  // Return hash.
+  return hash;
+}
+
+exports.generate = generate;