koa-files 2.3.7 → 3.0.0

package/esm/utils/http.js

@@ -0,0 +1,216 @@
+/**
+ * @package koa-files
+ * @license MIT
+ * @version 3.0.0
+ * @author nuintun <nuintun@qq.com>
+ * @description A static files serving middleware for koa.
+ * @see https://github.com/nuintun/koa-files#readme
+ */
+
+import { generate } from './hash.js';
+import parseRange from 'range-parser';
+
+/**
+ * @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(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 = `<${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) }];
+}
+
+export { decodeURI, isConditionalGET, isPreconditionFailure, parseRanges };

package/esm/utils/path.js

@@ -0,0 +1,42 @@
+/**
+ * @package koa-files
+ * @license MIT
+ * @version 3.0.0
+ * @author nuintun <nuintun@qq.com>
+ * @description A static files serving middleware for koa.
+ * @see https://github.com/nuintun/koa-files#readme
+ */
+
+import { relative, isAbsolute } from '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, root) {
+  path = relative(root, path);
+  return /\.\.(?:[\\/]|$)/.test(path) || isAbsolute(path);
+}
+
+export { hasTrailingSlash, isOutRoot, unixify };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "koa-files",
-  "version": "2.3.7",
+  "version": "3.0.0",
   "description": "A static files serving middleware for koa.",
   "type": "module",
   "main": "cjs/index.cjs",
@@ -45,10 +45,10 @@
     "test": "node tests",
     "lint": "tsc --noEmit",
     "clean": "node tools/clean.js",
-    "format": "prettier --write .",
     "prepublishOnly": "npm run build",
     "build:cjs": "rollup -c tools/rollup.cjs.js",
     "build:esm": "rollup -c tools/rollup.esm.js",
+    "format": "prettier --write . --ignore-path .prettierignore",
     "build": "npm run clean && npm run build:main && npm run format",
     "build:main": "npm run build:cjs && npm run build:esm && npm run build:types",
     "build:types": "tsc --declaration --emitDeclarationOnly --declarationDir types"
@@ -65,12 +65,12 @@
     "@types/etag": "^1.8.3",
     "@types/koa": "^2.15.0",
     "@types/range-parser": "^1.2.7",
-    "koa": "^2.15.0",
+    "koa": "^2.15.2",
     "magic-string": "^0.30.8",
     "prettier": "^3.2.5",
     "rimraf": "^5.0.5",
-    "rollup": "^4.12.0",
-    "typescript": "^5.3.3"
+    "rollup": "^4.13.0",
+    "typescript": "^5.4.3"
   },
   "peerDependencies": {
     "koa": "^2.0.0"

package/types/Service.d.ts

@@ -0,0 +1,81 @@
+/**
+ * @module Service
+ */
+/// <reference types="node" />
+import { Stats } from 'fs';
+import { Context } from 'koa';
+import { FileSystem } from './utils/fs';
+interface IgnoreFunction {
+  (path: string): boolean;
+}
+interface Headers {
+  [key: string]: string | string[];
+}
+interface HeaderFunction {
+  (path: string, stats: Stats): Headers | void;
+}
+export interface Options {
+  fs: FileSystem;
+  etag?: boolean;
+  acceptRanges?: boolean;
+  lastModified?: boolean;
+  ignore?: IgnoreFunction;
+  headers?: Headers | HeaderFunction;
+}
+/**
+ * @class Service
+ */
+export default class Service {
+  private root;
+  private options;
+  /**
+   * @constructor
+   * @description Create file service.
+   * @param root File service root.
+   * @param options File service options.
+   */
+  constructor(root: string, options: Options);
+  /**
+   * @private
+   * @method isIgnore
+   * @description Check if path is ignore.
+   * @param path File path.
+   */
+  private isIgnore;
+  /**
+   * @private
+   * @method setupHeaders
+   * @description Setup headers
+   * @param context Koa context
+   * @param path File path
+   * @param stats File stats
+   */
+  private setupHeaders;
+  /**
+   * @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.
+   */
+  private write;
+  /**
+   * @private
+   * @method send
+   * @description Send file.
+   * @param context Koa context.
+   * @param path File path.
+   * @param ranges Read ranges.
+   */
+  private send;
+  /**
+   * @public
+   * @method response
+   * @description Response to koa context.
+   * @param context Koa context.
+   */
+  response(context: Context): Promise<boolean>;
+}
+export {};

package/types/index.d.ts

@@ -1,12 +1,12 @@
 /**
  * @module index
- * @license MIT
- * @author nuintun
  */
 import { Middleware } from 'koa';
-import { Options as SendOptions } from './Send';
-export interface Options extends SendOptions {
-    defer?: boolean;
+import { FileSystem } from './utils/fs';
+import { Options as ServiceOptions } from './Service';
+export interface Options extends Omit<ServiceOptions, 'fs'> {
+  fs?: FileSystem;
+  defer?: boolean;
 }
 /**
  * @function server

package/types/utils/fs.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @module fs
+ */
+/// <reference types="node" />
+/// <reference types="node" />
+import { ReadStream, Stats } from 'fs';
+type PathLike = string | Buffer | URL;
+/**
+ * @function stat
+ * @description Get file stats.
+ * @param fs The file system to used.
+ * @param path The file path.
+ */
+export declare function stat(fs: FileSystem, path: string): Promise<Stats | null>;
+export interface FileSystem {
+  stat(path: PathLike, callback: (error: Error | null, stats: Stats) => void): void;
+  createReadStream(
+    path: PathLike,
+    options?: {
+      start?: number;
+      end?: number;
+    }
+  ): ReadStream;
+}
+export {};

package/types/utils/hash.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @module hash
+ */
+/**
+ * @function generate
+ * @description Generate a hash.
+ * @param length The length of hash.
+ */
+export declare function generate(length?: number): string;

package/types/utils/http.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @module http
+ */
+/// <reference types="node" />
+import { Stats } from 'fs';
+import { Context } from 'koa';
+export interface Range {
+  start: number;
+  end?: number;
+  prefix?: string;
+  suffix?: string;
+}
+type Ranges = Range[] | -1 | -2;
+/**
+ * @function decodeURI
+ * @description Decode URI component.
+ * @param URI The URI to decode.
+ */
+export declare function decodeURI(URI: string): string | -1;
+/**
+ * @function isConditionalGET
+ * @description Check if request is conditional GET.
+ * @param context Koa context.
+ */
+export declare function isConditionalGET(context: Context): boolean;
+/**
+ * @function isPreconditionFailure
+ * @description Check if request precondition failure.
+ * @param context Koa context.
+ */
+export declare function isPreconditionFailure({ request, response }: Context): boolean;
+/**
+ * @function parseRanges
+ * @description Parse ranges.
+ * @param context Koa context.
+ * @param stats File stats.
+ */
+export declare function parseRanges(context: Context, stats: Stats): Ranges;
+export {};

package/types/utils/path.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @module path
+ */
+/**
+ * @function unixify
+ * @description Convert path to unix style.
+ * @param path The path to convert.
+ */
+export declare function unixify(path: string): string;
+/**
+ * @function hasTrailingSlash
+ * @description Check if path has trailing slash.
+ * @param path The path to check.
+ */
+export declare function hasTrailingSlash(path: string): boolean;
+/**
+ * @function isOutRoot
+ * @description Check if path is out of root.
+ * @param path The path to check.
+ * @param root The root path.
+ */
+export declare function isOutRoot(path: string, root: string): boolean;