koa-files 4.1.7 → 5.0.1

package/README.md

@@ -9,17 +9,38 @@
 > ![Node Version][node-image]
 > [![License][license-image]][license-url]
 
-## Installation
+## Install
 
 ```bash
 $ npm install koa-files
 ```
 
+## Quick start
+
+```ts
+import Koa from 'koa';
+import { server } from 'koa-files';
+
+const app = new Koa();
+
+app.use(
+  server('public', {
+    headers: {
+      'Cache-Control': 'public, max-age=31536000, immutable'
+    }
+  })
+);
+
+app.listen(3000);
+```
+
+Then visit `http://127.0.0.1:3000/app.js` to serve `public/app.js`.
+
 ## API
 
 ```ts
 import { Middleware } from 'koa';
-import fs, { Stats } from 'node:fs';
+import { PathLike, Stats } from 'node:fs';
 
 interface Headers {
   [key: string]: string | string[];
@@ -38,10 +59,21 @@ interface HeadersFunction {
 }
 
 export interface FileSystem {
-  stat: typeof fs.stat;
-  open: typeof fs.open;
-  read: typeof fs.read;
-  close: typeof fs.close;
+  close(fd: number, callback?: (error?: Error | null) => void): void;
+  read<T extends ArrayBufferView>(
+    fd: number,
+    buffer: T,
+    offset: number,
+    length: number,
+    position: number | bigint | null,
+    callback: (error: Error | null | undefined, bytesRead: number, buffer: T) => void
+  ): void;
+  stat(path: PathLike, callback: (error: Error | null | undefined, stats: Stats) => void): void;
+  open(
+    path: PathLike,
+    flags: string | number | undefined,
+    callback: (error: Error | null | undefined, fd: number) => void
+  ): void;
 }
 
 export interface Options {
@@ -62,6 +94,7 @@ export function server(root: string, options?: Options): Middleware;
 
 - Root directory string.
 - Nothing above this root directory can be served.
+- `root` is resolved with `path.resolve`, so relative paths are based on the process working directory.
 
 ### Options
 
@@ -75,6 +108,7 @@ export function server(root: string, options?: Options): Middleware;
 - Defaults to `false`.
 - If true, serves after `await next()`.
 - Allowing any downstream middleware to respond first.
+- Useful when you want route handlers to take priority over static files.
 
 ##### `etag`
 
@@ -101,17 +135,28 @@ export function server(root: string, options?: Options): Middleware;
 
 - Defaults to `65536` (64 KiB).
 - Set the high water mark for the read stream.
+- Supports function form to customize by file path and stats.
 
 ##### `ignore`
 
 - Defaults to `undefined`.
 - Function that determines if a file should be ignored.
+- Return `true` to skip static serving for the current file.
 
 ##### `headers`
 
 - Defaults to `undefined`.
 - Set headers to be sent.
 - See docs: [Headers in MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers).
+- Supports function form to compute headers dynamically.
+
+### Behavior notes
+
+- Only `GET` and `HEAD` requests are handled.
+- `Range` requests are supported (including multipart range responses).
+- Conditional requests are supported via `ETag` and `Last-Modified`.
+- Requests containing invalid paths (e.g. null bytes) respond with `400`.
+- Files outside `root` are never served.
 
 ## Example
 
@@ -157,9 +202,48 @@ app.listen(port, () => {
 });
 ```
 
+## More examples
+
+### Prefer application routes first (`defer: true`)
+
+```ts
+app.use(async (ctx, next) => {
+  if (ctx.path === '/healthz') {
+    ctx.body = 'ok';
+    return;
+  }
+
+  await next();
+});
+
+app.use(server('public', { defer: true }));
+```
+
+### Dynamic ignore rule
+
+```ts
+app.use(
+  server('public', {
+    ignore: path => path.endsWith('.map')
+  })
+);
+```
+
+### Dynamic stream buffer
+
+```ts
+app.use(
+  server('public', {
+    highWaterMark: (path, stats) => (stats.size > 10 * 1024 * 1024 ? 256 * 1024 : 64 * 1024)
+  })
+);
+```
+
 ## Features
 
-Support multipart range and download resumption.
+- Static file middleware for Koa.
+- Supports multipart range and download resumption.
+- Supports conditional requests (`ETag`, `Last-Modified`).
 
 ## License
 

package/cjs/ReadStream.cjs

@@ -1,7 +1,8 @@
 /**
+ * @module koa-files
  * @package koa-files
  * @license MIT
- * @version 4.1.7
+ * @version 5.0.1
  * @author nuintun <nuintun@qq.com>
  * @description A static files serving middleware for koa.
  * @see https://github.com/nuintun/koa-files#readme
@@ -9,14 +10,22 @@
 
 'use strict';
 
-const buffer = require('buffer');
-const stream = require('stream');
+const node_buffer = require('node:buffer');
+const node_stream = require('node:stream');
 
 /**
  * @module ReadStream
  */
 const DISPOSE_EVENT = Symbol('dispose');
-class ReadStream extends stream.Readable {
+class ReadStream extends node_stream.Readable {
+  #path;
+  #fs;
+  #ranges;
+  #bytesRead = 0;
+  #fd = null;
+  #reading = false;
+  #currentRangeIndex = 0;
+  #readState = 0 /* ReadState.PREFIX */;
   /**
    * @constructor
    * @param path The file path.
@@ -26,14 +35,9 @@ class ReadStream extends stream.Readable {
   constructor(path, ranges, options) {
     const { fs, highWaterMark } = options;
     super({ highWaterMark });
-    this.bytesRead = 0;
-    this.fd = null;
-    this.reading = false;
-    this.currentRangeIndex = 0;
-    this.readState = 0 /* ReadState.PREFIX */;
-    this.fs = fs;
-    this.path = path;
-    this.ranges = ranges;
+    this.#fs = fs;
+    this.#path = path;
+    this.#ranges = ranges;
   }
   /**
    * @override
@@ -41,27 +45,27 @@ class ReadStream extends stream.Readable {
    * @param callback The callback.
    */
   _construct(callback) {
-    this.fs.open(this.path, 'r', (openError, fd) => {
+    this.#fs.open(this.#path, 'r', (openError, fd) => {
       if (openError == null) {
-        this.fd = fd;
+        this.#fd = fd;
       }
       callback(openError);
     });
   }
   /**
    * @private
-   * @method getRange
+   * @method #getRange
    */
-  getRange() {
-    return this.ranges[this.currentRangeIndex];
+  #getRange() {
+    return this.#ranges[this.#currentRangeIndex];
   }
   /**
    * @private
-   * @method getPadding
+   * @method #getPadding
    * @param range The current range.
    */
-  getPadding(range) {
-    switch (this.readState) {
+  #getPadding(range) {
+    switch (this.#readState) {
       case 0 /* ReadState.PREFIX */:
         return range.prefix;
       case 2 /* ReadState.SUFFIX */:
@@ -70,42 +74,42 @@ class ReadStream extends stream.Readable {
   }
   /**
    * @private
-   * @method readPadding
+   * @method #readPadding
    * @param fd The file descriptor.
    * @param range The current range.
    * @param size The number of bytes to read.
    */
-  readPadding(fd, range, size) {
+  #readPadding(fd, range, size) {
     let bytesRead = 0;
-    const padding = this.getPadding(range);
+    const padding = this.#getPadding(range);
     // If padding exists.
     if (padding != null) {
       const { length } = padding;
-      const begin = this.bytesRead;
+      const begin = this.#bytesRead;
       if (begin < length) {
         bytesRead = Math.min(size, length - begin);
         const end = begin + bytesRead;
         this.push(padding.subarray(begin, end));
-        this.bytesRead = end;
+        this.#bytesRead = end;
       }
     }
     // If no padding or read completed.
     if (bytesRead < size) {
-      this.bytesRead = 0;
+      this.#bytesRead = 0;
       // Change read state.
-      switch (this.readState) {
+      switch (this.#readState) {
         case 0 /* ReadState.PREFIX */:
-          this.readState = 1 /* ReadState.RANGE */;
-          this.readFileRange(fd, range, size - bytesRead);
+          this.#readState = 1 /* ReadState.RANGE */;
+          this.#readFileRange(fd, range, size - bytesRead);
           break;
         case 2 /* ReadState.SUFFIX */:
-          this.currentRangeIndex++;
-          this.readState = 0 /* ReadState.PREFIX */;
-          const nextRange = this.getRange();
+          this.#currentRangeIndex++;
+          this.#readState = 0 /* ReadState.PREFIX */;
+          const nextRange = this.#getRange();
           if (nextRange == null) {
             this.push(null);
           } else {
-            this.readPadding(fd, nextRange, size - bytesRead);
+            this.#readPadding(fd, nextRange, size - bytesRead);
           }
           break;
       }
@@ -113,23 +117,23 @@ class ReadStream extends stream.Readable {
   }
   /**
    * @private
-   * @method readFileRange
+   * @method #readFileRange
    * @param fd The file descriptor.
    * @param range The current range.
    * @param size The number of bytes to read.
    */
-  readFileRange(fd, range, size) {
+  #readFileRange(fd, range, size) {
     const { length } = range;
-    const { bytesRead } = this;
+    const bytesRead = this.#bytesRead;
     // File range not finished.
     if (bytesRead < length) {
-      this.reading = true;
+      this.#reading = true;
       const bytesToRead = Math.min(size, length - bytesRead);
-      const buffer$1 = buffer.Buffer.allocUnsafeSlow(bytesToRead);
+      const buffer = node_buffer.Buffer.allocUnsafeSlow(bytesToRead);
       const position = range.offset + bytesRead;
       // Read file range.
-      this.fs.read(fd, buffer$1, 0, bytesToRead, position, (readError, bytesRead, buffer) => {
-        this.reading = false;
+      this.#fs.read(fd, buffer, 0, bytesToRead, position, (readError, bytesRead, buffer) => {
+        this.#reading = false;
         // Tell ._destroy() that it's safe to close the fd now.
         if (this.destroyed) {
           this.emit(DISPOSE_EVENT, readError);
@@ -139,19 +143,19 @@ class ReadStream extends stream.Readable {
           this.destroy(new RangeError('invalid read operation'));
         } else {
           this.push(buffer);
-          this.bytesRead += bytesRead;
+          this.#bytesRead += bytesRead;
           // file range read completed.
           if (bytesRead < size) {
-            this.bytesRead = 0;
-            this.readState = 2 /* ReadState.SUFFIX */;
-            this.readPadding(fd, range, size - bytesRead);
+            this.#bytesRead = 0;
+            this.#readState = 2 /* ReadState.SUFFIX */;
+            this.#readPadding(fd, range, size - bytesRead);
           }
         }
       });
     } else {
-      this.bytesRead = 0;
-      this.readState = 2 /* ReadState.SUFFIX */;
-      this.readPadding(fd, range, size);
+      this.#bytesRead = 0;
+      this.#readState = 2 /* ReadState.SUFFIX */;
+      this.#readPadding(fd, range, size);
     }
   }
   /**
@@ -160,21 +164,21 @@ class ReadStream extends stream.Readable {
    * @param size The number of bytes to read.
    */
   _read(size) {
-    if (!this.reading) {
-      const { fd } = this;
-      const range = this.getRange();
+    if (!this.#reading) {
+      const fd = this.#fd;
+      const range = this.#getRange();
       // If fd or range is null, finish stream.
       if (fd == null || range == null) {
         this.push(null);
       } else {
         // Read bytes from range.
-        switch (this.readState) {
+        switch (this.#readState) {
           case 0 /* ReadState.PREFIX */:
           case 2 /* ReadState.SUFFIX */:
-            this.readPadding(fd, range, size);
+            this.#readPadding(fd, range, size);
             break;
           case 1 /* ReadState.RANGE */:
-            this.readFileRange(fd, range, size);
+            this.#readFileRange(fd, range, size);
             break;
         }
       }
@@ -182,17 +186,17 @@ class ReadStream extends stream.Readable {
   }
   /**
    * @private
-   * @method dispose
+   * @method #dispose
    * @param error The error.
    * @param callback The callback.
    */
-  dispose(error, callback) {
-    const { fd } = this;
+  #dispose(error, callback) {
+    const fd = this.#fd;
     if (fd != null) {
-      this.fd = null;
+      this.#fd = null;
       // Close the fd.
-      this.fs.close(fd, closeError => {
-        callback(error !== null && error !== void 0 ? error : closeError);
+      this.#fs.close(fd, closeError => {
+        callback(error ?? closeError);
       });
     } else {
       callback(error);
@@ -206,12 +210,12 @@ class ReadStream extends stream.Readable {
    */
   _destroy(error, callback) {
     // Wait I/O completion.
-    if (this.reading) {
+    if (this.#reading) {
       this.once(DISPOSE_EVENT, disposeError => {
-        this.dispose(error !== null && error !== void 0 ? error : disposeError, callback);
+        this.#dispose(error ?? disposeError, callback);
       });
     } else {
-      this.dispose(error, callback);
+      this.#dispose(error, callback);
     }
   }
 }

package/cjs/ReadStream.d.cts

@@ -1,9 +1,8 @@
 /**
  * @module ReadStream
  */
-import { PathLike } from 'fs';
-import { Readable } from 'stream';
 import { Range } from './utils/http.cjs';
+import { Readable } from 'node:stream';
 import { FileSystem } from './utils/fs.cjs';
 export interface Options {
   fs: FileSystem;
@@ -13,67 +12,26 @@ interface Callback {
   (error?: Error | null): void;
 }
 export declare class ReadStream extends Readable {
-  private readonly fs;
-  private readonly path;
-  private readonly ranges;
-  private bytesRead;
-  private fd;
-  private reading;
-  private currentRangeIndex;
-  private readState;
+  #private;
   /**
    * @constructor
    * @param path The file path.
    * @param ranges The ranges to read.
    * @param options The stream options.
    */
-  constructor(path: PathLike, ranges: Range[], options: Options);
+  constructor(path: string, ranges: Range[], options: Options);
   /**
    * @override
    * @method _construct
    * @param callback The callback.
    */
   _construct(callback: Callback): void;
-  /**
-   * @private
-   * @method getRange
-   */
-  private getRange;
-  /**
-   * @private
-   * @method getPadding
-   * @param range The current range.
-   */
-  private getPadding;
-  /**
-   * @private
-   * @method readPadding
-   * @param fd The file descriptor.
-   * @param range The current range.
-   * @param size The number of bytes to read.
-   */
-  private readPadding;
-  /**
-   * @private
-   * @method readFileRange
-   * @param fd The file descriptor.
-   * @param range The current range.
-   * @param size The number of bytes to read.
-   */
-  private readFileRange;
   /**
    * @override
    * @method _read
    * @param size The number of bytes to read.
    */
   _read(size: number): void;
-  /**
-   * @private
-   * @method dispose
-   * @param error The error.
-   * @param callback The callback.
-   */
-  private dispose;
   /**
    * @override
    * @method _destroy

package/cjs/Service.cjs

@@ -1,7 +1,8 @@
 /**
+ * @module koa-files
  * @package koa-files
  * @license MIT
- * @version 4.1.7
+ * @version 5.0.1
  * @author nuintun <nuintun@qq.com>
  * @description A static files serving middleware for koa.
  * @see https://github.com/nuintun/koa-files#readme
@@ -10,11 +11,11 @@
 'use strict';
 
 const createETag = require('etag');
-const fs = require('fs');
+const fs = require('node:fs');
 const ReadStream = require('./ReadStream.cjs');
 const type = require('./utils/type.cjs');
 const fs$1 = require('./utils/fs.cjs');
-const path$1 = require('path');
+const node_path = require('node:path');
 const path = require('./utils/path.cjs');
 const http = require('./utils/http.cjs');
 
@@ -32,6 +33,8 @@ const fs__default = /*#__PURE__*/ _interopDefault(fs);
  * @class Service
  */
 class Service {
+  #root;
+  #options;
   /**
    * @constructor
    * @description Create file service.
@@ -39,30 +42,30 @@ class Service {
    * @param options The file service options.
    */
   constructor(root, options = {}) {
-    var _a;
-    this.root = path.unixify(path$1.resolve(root));
+    this.#root = path.unixify(node_path.resolve(root));
     const { ignore, headers, highWaterMark = 65536 } = options;
-    this.options = Object.assign(Object.assign({}, options), {
-      fs: (_a = options.fs) !== null && _a !== void 0 ? _a : fs__default.default,
+    this.#options = {
+      ...options,
+      fs: options.fs ?? fs__default.default,
       ignore: type.isFunction(ignore) ? ignore : () => false,
       headers: type.isFunction(headers) ? headers : () => headers,
       highWaterMark: type.isFunction(highWaterMark) ? highWaterMark : () => highWaterMark
-    });
+    };
   }
   /**
    * @private
-   * @method setupHeaders
+   * @method #setupHeaders
    * @description Setup headers.
    * @param context The koa context.
    * @param path The file path.
    * @param stats The file stats.
    */
-  async setupHeaders({ response }, path, stats) {
-    const { options } = this;
+  async #setupHeaders({ response }, path, stats) {
+    const options = this.#options;
     // Set status.
     response.status = 200;
     // Set Content-Type.
-    response.type = path$1.extname(path);
+    response.type = node_path.extname(path);
     // Get headers.
     const headers = await options.headers(path, stats);
     // If headers not empty, set headers.
@@ -114,21 +117,21 @@ class Service {
       return context.throw(400);
     }
     // Get service root.
-    const { root } = this;
+    const root = this.#root;
     // Get file path.
-    const path$2 = path.unixify(path$1.join(root, pathname));
+    const path$1 = path.unixify(node_path.join(root, pathname));
     // Malicious path (403).
-    if (path.isOutRoot(path$2, root)) {
+    if (path.isOutRoot(path$1, root)) {
       return false;
     }
     // Get options.
-    const { options } = this;
+    const options = this.#options;
     // Is ignore path or file (403).
-    if (await options.ignore(path$2)) {
+    if (await options.ignore(path$1)) {
       return false;
     }
     // File stats.
-    const stats = await fs$1.stat(options.fs, path$2);
+    const stats = await fs$1.stat(options.fs, path$1);
     // Check file stats.
     if (
       // File not exist (404 | 500).
@@ -136,14 +139,14 @@ class Service {
       // Is directory (403).
       stats.isDirectory() ||
       // Not a directory but has trailing slash (404).
-      path.hasTrailingSlash(path$2)
+      path.hasTrailingSlash(path$1)
     ) {
       return false;
     }
     // Koa response.
     const { response } = context;
     // Setup headers.
-    await this.setupHeaders(context, path$2, stats);
+    await this.#setupHeaders(context, path$1, stats);
     // Conditional get support.
     if (http.isConditionalGET(context)) {
       // Request precondition failed.
@@ -183,9 +186,9 @@ class Service {
       return context.throw(400);
     }
     // Set response body.
-    response.body = new ReadStream.ReadStream(path$2, ranges, {
+    response.body = new ReadStream.ReadStream(path$1, ranges, {
       fs: options.fs,
-      highWaterMark: await options.highWaterMark(path$2, stats)
+      highWaterMark: await options.highWaterMark(path$1, stats)
     });
     // File found.
     return true;

package/cjs/Service.d.cts

@@ -2,7 +2,7 @@
  * @module Service
  */
 import { Context } from 'koa';
-import { Stats } from 'fs';
+import { Stats } from 'node:fs';
 import { FileSystem } from './utils/fs.cjs';
 interface Headers {
   [key: string]: string | string[];
@@ -29,8 +29,7 @@ export interface Options {
  * @class Service
  */
 export declare class Service {
-  private readonly root;
-  private readonly options;
+  #private;
   /**
    * @constructor
    * @description Create file service.
@@ -38,15 +37,6 @@ export declare class Service {
    * @param options The file service options.
    */
   constructor(root: string, options?: Options);
-  /**
-   * @private
-   * @method setupHeaders
-   * @description Setup headers.
-   * @param context The koa context.
-   * @param path The file path.
-   * @param stats The file stats.
-   */
-  private setupHeaders;
   /**
    * @public
    * @method respond

package/cjs/index.cjs

@@ -1,7 +1,8 @@
 /**
+ * @module koa-files
  * @package koa-files
  * @license MIT
- * @version 4.1.7
+ * @version 5.0.1
  * @author nuintun <nuintun@qq.com>
  * @description A static files serving middleware for koa.
  * @see https://github.com/nuintun/koa-files#readme
@@ -22,7 +23,7 @@ const Service = require('./Service.cjs');
  */
 function server(root, options) {
   const service = new Service.Service(root, options);
-  if (options === null || options === void 0 ? void 0 : options.defer) {
+  if (options?.defer) {
     return async (context, next) => {
       await next();
       await service.respond(context);