@eggjs/koa 2.17.0 → 2.18.0

package/dist/esm/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoidHlwZXMuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvdHlwZXMudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IiJ9

package/package.json

@@ -1,22 +1,19 @@
 {
   "name": "@eggjs/koa",
-  "version": "2.17.0",
-  "description": "Koa web app framework",
-  "main": "lib/application.js",
-  "types": "lib/application.d.ts",
-  "files": [
-    "lib/*.d.ts",
-    "lib/*.js"
-  ],
+  "version": "2.18.0",
+  "engines": {
+    "node": ">= 18.7.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "Koa web app framework for https://eggjs.org",
   "scripts": {
-    "test": "egg-bin test",
-    "ci": "egg-bin cov && npm run tsd",
+    "test": "npm run lint -- --fix && egg-bin test",
+    "ci": "npm run lint && egg-bin cov && npm run prepublishOnly",
     "lint": "eslint src test",
-    "tsd": "npm run tsc && tsd",
     "authors": "git log --format='%aN <%aE>' | sort -u > AUTHORS",
-    "clean": "tsc -b --clean",
-    "tsc": "tsc",
-    "prepublishOnly": "npm run tsc"
+    "prepublishOnly": "tshy && tshy-after"
   },
   "repository": {
     "type": "git",
@@ -34,9 +31,9 @@
   "license": "MIT",
   "dependencies": {
     "accepts": "^1.3.5",
-    "cache-content-type": "^1.0.0",
-    "content-disposition": "~0.5.2",
-    "content-type": "^1.0.4",
+    "cache-content-type": "^2.0.0",
+    "content-disposition": "~0.5.4",
+    "content-type": "^1.0.5",
     "cookies": "~0.8.0",
     "delegates": "^1.0.0",
     "destroy": "^1.0.4",
@@ -45,32 +42,69 @@
     "fresh": "~0.5.2",
     "gals": "^1.0.1",
     "http-assert": "^1.3.0",
-    "http-errors": "^1.6.3",
-    "is-generator-function": "^1.0.7",
+    "http-errors": "^2.0.0",
+    "is-type-of": "^2.1.0",
     "koa-compose": "^4.1.0",
-    "on-finished": "^2.3.0",
-    "only": "~0.0.2",
-    "parseurl": "^1.3.2",
-    "statuses": "^1.5.0",
-    "type-is": "^1.6.16",
+    "on-finished": "^2.4.1",
+    "parseurl": "^1.3.3",
+    "statuses": "^2.0.1",
+    "type-is": "^1.6.18",
     "vary": "^1.1.2"
   },
   "devDependencies": {
     "@eggjs/tsconfig": "^1.3.3",
+    "@types/content-type": "^1.1.8",
+    "@types/delegates": "^1.0.3",
+    "@types/destroy": "^1.0.3",
+    "@types/encodeurl": "^1.0.2",
+    "@types/escape-html": "^1.0.4",
+    "@types/fresh": "^0.5.2",
+    "@types/http-errors": "^2.0.4",
+    "@types/koa-compose": "^3.2.8",
     "@types/mocha": "^10.0.1",
     "@types/node": "^20.2.5",
+    "@types/on-finished": "^2.3.4",
+    "@types/parseurl": "^1.3.3",
+    "@types/statuses": "^2.0.5",
+    "@types/supertest": "^6.0.2",
+    "@types/type-is": "^1.6.6",
+    "@types/vary": "^1.1.3",
     "egg-bin": "^6.4.0",
     "eslint": "^8.41.0",
     "eslint-config-egg": "^13.1.0",
     "mm": "^3.3.0",
     "supertest": "^3.1.0",
-    "tsd": "^0.28.1",
-    "typescript": "^5.0.4"
+    "tsd": "^0.31.0",
+    "tshy": "^1.15.1",
+    "tshy-after": "^1.0.0",
+    "typescript": "^5.4.5"
   },
-  "engines": {
-    "node": ">= 16.13.0"
+  "type": "module",
+  "tshy": {
+    "exports": {
+      "./package.json": "./package.json",
+      ".": "./src/index.ts"
+    }
   },
-  "publishConfig": {
-    "access": "public"
-  }
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "import": {
+        "source": "./src/index.ts",
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "source": "./src/index.ts",
+        "types": "./dist/commonjs/index.d.ts",
+        "default": "./dist/commonjs/index.js"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "main": "./dist/commonjs/index.js",
+  "types": "./dist/commonjs/index.d.ts"
 }

package/src/application.ts

@@ -0,0 +1,276 @@
+import { debuglog } from 'node:util';
+import Emitter from 'node:events';
+import util from 'node:util';
+import Stream from 'node:stream';
+import http from 'node:http';
+import type { AsyncLocalStorage } from 'node:async_hooks';
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { getAsyncLocalStorage } from 'gals';
+import { isGeneratorFunction } from 'is-type-of';
+import onFinished from 'on-finished';
+import statuses from 'statuses';
+import compose from 'koa-compose';
+import { HttpError } from 'http-errors';
+import Context from './context.js';
+import Request from './request.js';
+import Response from './response.js';
+import type { ContextDelegation } from './context.js';
+import type { CustomError, AnyProto } from './types.js';
+
+const debug = debuglog('koa:application');
+
+export type ProtoImplClass<T = object> = new(...args: any[]) => T;
+export type Next = () => Promise<void>;
+export type MiddlewareFunc = (ctx: ContextDelegation, next: Next) => Promise<void> | void;
+export type { ContextDelegation as Context } from './context.js';
+
+/**
+ * Expose `Application` class.
+ * Inherits from `Emitter.prototype`.
+ */
+export default class Application extends Emitter {
+  /**
+   * Make HttpError available to consumers of the library so that consumers don't
+   * have a direct dependency upon `http-errors`
+   */
+  static HttpError = HttpError;
+
+  proxy: boolean;
+  subdomainOffset: number;
+  proxyIpHeader: string;
+  maxIpsCount: number;
+  env: string;
+  keys?: string[];
+  middleware: MiddlewareFunc[];
+  ctxStorage: AsyncLocalStorage<ContextDelegation>;
+  silent: boolean;
+  ContextClass: ProtoImplClass<Context>;
+  context: AnyProto;
+  RequestClass: ProtoImplClass<Request>;
+  request: AnyProto;
+  ResponseClass: ProtoImplClass<Response>;
+  response: AnyProto;
+
+  /**
+   * Initialize a new `Application`.
+    *
+    * @param {object} [options] Application options
+    * @param {string} [options.env='development'] Environment
+    * @param {string[]} [options.keys] Signed cookie keys
+    * @param {boolean} [options.proxy] Trust proxy headers
+    * @param {number} [options.subdomainOffset] Subdomain offset
+    * @param {string} [options.proxyIpHeader] Proxy IP header, defaults to X-Forwarded-For
+    * @param {number} [options.maxIpsCount] Max IPs read from proxy IP header, default to 0 (means infinity)
+    */
+
+  constructor(options?: {
+    proxy?: boolean;
+    subdomainOffset?: number;
+    proxyIpHeader?: string;
+    maxIpsCount?: number;
+    env?: string;
+    keys?: string[];
+  }) {
+    super();
+    options = options || {};
+    this.proxy = options.proxy || false;
+    this.subdomainOffset = options.subdomainOffset || 2;
+    this.proxyIpHeader = options.proxyIpHeader || 'X-Forwarded-For';
+    this.maxIpsCount = options.maxIpsCount || 0;
+    this.env = options.env || process.env.NODE_ENV || 'development';
+    if (options.keys) this.keys = options.keys;
+    this.middleware = [];
+    this.ctxStorage = getAsyncLocalStorage();
+    this.silent = false;
+    this.ContextClass = class ApplicationContext extends Context {};
+    this.context = this.ContextClass.prototype;
+    this.RequestClass = class ApplicationRequest extends Request {};
+    this.request = this.RequestClass.prototype;
+    this.ResponseClass = class ApplicationResponse extends Response {};
+    this.response = this.ResponseClass.prototype;
+  }
+
+  /**
+   * Shorthand for:
+   *
+   *    http.createServer(app.callback()).listen(...)
+   */
+  listen(...args: any[]) {
+    debug('listen');
+    const server = http.createServer(this.callback());
+    return server.listen(...args);
+  }
+
+  /**
+   * Return JSON representation.
+   * We only bother showing settings.
+   */
+  toJSON() {
+    return {
+      subdomainOffset: this.subdomainOffset,
+      proxy: this.proxy,
+      env: this.env,
+    };
+  }
+
+  /**
+   * Inspect implementation.
+   */
+  inspect() {
+    return this.toJSON();
+  }
+
+  [util.inspect.custom]() {
+    return this.inspect();
+  }
+
+  /**
+   * Use the given middleware `fn`.
+   *
+   * Old-style middleware will be converted.
+   */
+  use(fn: MiddlewareFunc) {
+    if (typeof fn !== 'function') throw new TypeError('middleware must be a function!');
+    if (isGeneratorFunction(fn)) {
+      throw new TypeError('Support for generators was removed. ' +
+        'See the documentation for examples of how to convert old middleware ' +
+        'https://github.com/koajs/koa/blob/master/docs/migration.md');
+    }
+    debug('use %s #%d', (fn as any)._name || fn.name || '-', this.middleware.length);
+    this.middleware.push(fn);
+    return this;
+  }
+
+  /**
+   * Return a request handler callback
+   * for node's native http server.
+   */
+  callback() {
+    const fn = compose(this.middleware);
+
+    if (!this.listenerCount('error')) {
+      this.on('error', this.onerror.bind(this));
+    }
+
+    const handleRequest = (req: IncomingMessage, res: ServerResponse) => {
+      const ctx = this.createContext(req, res);
+      return this.ctxStorage.run(ctx, async () => {
+        return await this.#handleRequest(ctx, fn);
+      });
+    };
+
+    return handleRequest;
+  }
+
+  /**
+   * return current context from async local storage
+   */
+  get currentContext() {
+    return this.ctxStorage.getStore();
+  }
+
+  /**
+   * Handle request in callback.
+   * @private
+   */
+  async #handleRequest(ctx: ContextDelegation, fnMiddleware: (ctx: ContextDelegation) => Promise<void>) {
+    const res = ctx.res;
+    res.statusCode = 404;
+    const onerror = (err: any) => ctx.onerror(err);
+    onFinished(res, onerror);
+    try {
+      await fnMiddleware(ctx);
+      return this._respond(ctx);
+    } catch (err) {
+      return onerror(err);
+    }
+  }
+
+  /**
+   * Initialize a new context.
+   * @private
+   */
+  protected createContext(req: IncomingMessage, res: ServerResponse) {
+    const context = new this.ContextClass(this, req, res);
+    return context as ContextDelegation;
+  }
+
+  /**
+   * Default error handler.
+   * @private
+   */
+  protected onerror(err: CustomError) {
+    // When dealing with cross-globals a normal `instanceof` check doesn't work properly.
+    // See https://github.com/koajs/koa/issues/1466
+    // We can probably remove it once jest fixes https://github.com/facebook/jest/issues/2549.
+    const isNativeError = err instanceof Error ||
+      Object.prototype.toString.call(err) === '[object Error]';
+    if (!isNativeError) throw new TypeError(util.format('non-error thrown: %j', err));
+
+    if (err.status === 404 || err.expose) return;
+    if (this.silent) return;
+
+    const msg = err.stack || err.toString();
+    console.error(`\n${msg.replace(/^/gm, '  ')}\n`);
+  }
+
+  /**
+   * Response helper.
+   */
+  protected _respond(ctx: ContextDelegation) {
+    // allow bypassing koa
+    if (ctx.respond === false) return;
+
+    if (!ctx.writable) return;
+
+    const res = ctx.res;
+    let body = ctx.body;
+    const code = ctx.status;
+
+    // ignore body
+    if (statuses.empty[code]) {
+      // strip headers
+      ctx.body = null;
+      return res.end();
+    }
+
+    if (ctx.method === 'HEAD') {
+      if (!res.headersSent && !ctx.response.has('Content-Length')) {
+        const { length } = ctx.response;
+        if (Number.isInteger(length)) ctx.length = length;
+      }
+      return res.end();
+    }
+
+    // status body
+    if (body == null) {
+      if (ctx.response._explicitNullBody) {
+        ctx.response.remove('Content-Type');
+        ctx.response.remove('Transfer-Encoding');
+        return res.end();
+      }
+      if (ctx.req.httpVersionMajor >= 2) {
+        body = String(code);
+      } else {
+        body = ctx.message || String(code);
+      }
+      if (!res.headersSent) {
+        ctx.type = 'text';
+        ctx.length = Buffer.byteLength(body);
+      }
+      return res.end(body);
+    }
+
+    // responses
+    if (Buffer.isBuffer(body)) return res.end(body);
+    if (typeof body === 'string') return res.end(body);
+    if (body instanceof Stream) return body.pipe(res);
+
+    // body: json
+    body = JSON.stringify(body);
+    if (!res.headersSent) {
+      ctx.length = Buffer.byteLength(body);
+    }
+    res.end(body);
+  }
+}

package/src/context.ts

@@ -0,0 +1,284 @@
+import util from 'node:util';
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import createError from 'http-errors';
+import httpAssert from 'http-assert';
+import delegate from 'delegates';
+import statuses from 'statuses';
+import Cookies from 'cookies';
+import type Application from './application.js';
+import type Request from './request.js';
+import type Response from './response.js';
+import type { CustomError, AnyProto } from './types.js';
+
+export default class Context {
+  app: Application;
+  req: IncomingMessage;
+  res: ServerResponse;
+  request: Request & AnyProto;
+  response: Response & AnyProto;
+  state: Record<string, any>;
+  originalUrl: string;
+  respond?: boolean;
+
+  constructor(app: Application, req: IncomingMessage, res: ServerResponse) {
+    this.app = app;
+    this.req = req;
+    this.res = res;
+    this.state = {};
+    this.request = new app.RequestClass(app, this, req, res);
+    this.response = new app.ResponseClass(app, this as any, req, res);
+    this.request.response = this.response;
+    this.response.request = this.request;
+    this.originalUrl = req.url!;
+  }
+
+  /**
+   * util.inspect() implementation, which
+   * just returns the JSON output.
+   */
+  inspect() {
+    return this.toJSON();
+  }
+
+  /**
+   * Custom inspection implementation for newer Node.js versions.
+   */
+  [util.inspect.custom]() {
+    return this.inspect();
+  }
+
+  /**
+   * Return JSON representation.
+   *
+   * Here we explicitly invoke .toJSON() on each
+   * object, as iteration will otherwise fail due
+   * to the getters and cause utilities such as
+   * clone() to fail.
+   */
+
+  toJSON() {
+    return {
+      request: this.request.toJSON(),
+      response: this.response.toJSON(),
+      app: this.app.toJSON(),
+      originalUrl: this.originalUrl,
+      req: '<original node req>',
+      res: '<original node res>',
+      socket: '<original node socket>',
+    };
+  }
+
+  /**
+   * Similar to .throw(), adds assertion.
+   *
+   *    this.assert(this.user, 401, 'Please login!');
+   *
+   * See: https://github.com/jshttp/http-assert
+   * @param {Mixed} value
+   * @param {Number} status
+   * @param {String} opts
+   */
+  assert(value: any, status?: number, opts?: Record<string, any>): void;
+  assert(value: any, status?: number, msg?: string, opts?: Record<string, any>): void;
+  assert(value: any, status?: number, msgOrOptions?: string | Record<string, any>, opts?: Record<string, any>) {
+    if (typeof msgOrOptions === 'string') {
+      return httpAssert(value, status, msgOrOptions, opts);
+    }
+    return httpAssert(value, status, msgOrOptions);
+  }
+
+  /**
+   * Throw an error with `status` (default 500) and
+   * `msg`. Note that these are user-level
+   * errors, and the message may be exposed to the client.
+   *
+   *    this.throw(403)
+   *    this.throw(400, 'name required')
+   *    this.throw('something exploded')
+   *    this.throw(new Error('invalid'))
+   *    this.throw(400, new Error('invalid'))
+   *    this.throw(400, new Error('invalid'), { foo: 'bar' })
+   *    this.throw(new Error('invalid'), { foo: 'bar' })
+   *
+   * See: https://github.com/jshttp/http-errors
+   *
+   * Note: `status` should only be passed as the first parameter.
+   *
+   * @param {String|Number|Error} status error, msg or status
+   * @param {String|Number|Error|Object} [error] error, msg, status or errorProps
+   * @param {Object} [errorProps] error object properties
+   */
+
+  throw(status: number): void;
+  throw(status: number, errorProps: object): void;
+  throw(status: number, errorMessage: string): void;
+  throw(status: number, errorMessage: string, errorProps: object): void;
+  throw(status: number, error: Error): void;
+  throw(status: number, error: Error, errorProps: object): void;
+  throw(errorMessage: string): void;
+  throw(errorMessage: string, errorProps: object): void;
+  throw(errorMessage: string, status: number): void;
+  throw(errorMessage: string, status: number, errorProps: object): void;
+  throw(error: Error): void;
+  throw(error: Error, errorProps: object): void;
+  throw(error: Error, status: number): void;
+  throw(error: Error, status: number, errorProps: object): void;
+  throw(arg1: number | string | Error, arg2?: number | string | Error | object, errorProps?: object) {
+    const args: any[] = [];
+    if (typeof arg2 === 'number') {
+      // throw(error, status)
+      args.push(arg2);
+      args.push(arg1);
+    } else {
+      // throw(status, error?)
+      args.push(arg1);
+      if (arg2) {
+        args.push(arg2);
+      }
+    }
+    if (errorProps) {
+      args.push(errorProps);
+    }
+    throw createError(...args);
+  }
+
+  /**
+   * Default error handling.
+   * @private
+   */
+  onerror(err: CustomError) {
+    // don't do anything if there is no error.
+    // this allows you to pass `this.onerror`
+    // to node-style callbacks.
+    if (err === null || err === undefined) return;
+
+    // When dealing with cross-globals a normal `instanceof` check doesn't work properly.
+    // See https://github.com/koajs/koa/issues/1466
+    // We can probably remove it once jest fixes https://github.com/facebook/jest/issues/2549.
+    const isNativeError = err instanceof Error ||
+      Object.prototype.toString.call(err) === '[object Error]';
+    if (!isNativeError) err = new Error(util.format('non-error thrown: %j', err));
+
+    let headerSent = false;
+    if (this.response.headerSent || !this.response.writable) {
+      headerSent = (err as any).headerSent = true;
+    }
+
+    // delegate
+    this.app.emit('error', err, this);
+
+    // nothing we can do here other
+    // than delegate to the app-level
+    // handler and log.
+    if (headerSent) {
+      return;
+    }
+
+    const { res } = this;
+
+    // first unset all headers
+    res.getHeaderNames().forEach(name => res.removeHeader(name));
+
+    // then set those specified
+    if (err.headers) this.response.set(err.headers);
+
+    // force text/plain
+    this.response.type = 'text';
+
+    let statusCode = err.status || err.statusCode;
+
+    // ENOENT support
+    if (err.code === 'ENOENT') statusCode = 404;
+
+    // default to 500
+    if (typeof statusCode !== 'number' || !statuses.message[statusCode]) statusCode = 500;
+
+    // respond
+    const statusMessage = statuses.message[statusCode] as string;
+    const msg = err.expose ? err.message : statusMessage;
+    this.response.status = err.status = statusCode;
+    this.response.length = Buffer.byteLength(msg);
+    res.end(msg);
+  }
+
+  #cookies: Cookies;
+  get cookies() {
+    if (!this.#cookies) {
+      this.#cookies = new Cookies(this.req, this.res, {
+        keys: this.app.keys,
+        secure: this.request.secure,
+      });
+    }
+    return this.#cookies;
+  }
+
+  set cookies(cookies: Cookies) {
+    this.#cookies = cookies;
+  }
+}
+
+/**
+ * Request delegation.
+ */
+
+delegate(Context.prototype, 'request')
+  .method('acceptsLanguages')
+  .method('acceptsEncodings')
+  .method('acceptsCharsets')
+  .method('accepts')
+  .method('get')
+  .method('is')
+  .access('querystring')
+  .access('idempotent')
+  .access('socket')
+  .access('search')
+  .access('method')
+  .access('query')
+  .access('path')
+  .access('url')
+  .access('accept')
+  .getter('origin')
+  .getter('href')
+  .getter('subdomains')
+  .getter('protocol')
+  .getter('host')
+  .getter('hostname')
+  .getter('URL')
+  .getter('header')
+  .getter('headers')
+  .getter('secure')
+  .getter('stale')
+  .getter('fresh')
+  .getter('ips')
+  .getter('ip');
+
+/**
+ * Response delegation.
+ */
+
+delegate(Context.prototype, 'response')
+  .method('attachment')
+  .method('redirect')
+  .method('remove')
+  .method('vary')
+  .method('has')
+  .method('set')
+  .method('append')
+  .method('flushHeaders')
+  .access('status')
+  .access('message')
+  .access('body')
+  .access('length')
+  .access('type')
+  .access('lastModified')
+  .access('etag')
+  .getter('headerSent')
+  .getter('writable');
+
+export type ContextDelegation = Context & Pick<Request, 'acceptsLanguages' | 'acceptsEncodings' | 'acceptsCharsets'
+| 'accepts' | 'get' | 'is' | 'querystring' | 'idempotent' | 'socket' | 'search' | 'method' | 'query'
+| 'path' | 'url' | 'accept' | 'origin' | 'href' | 'subdomains' | 'protocol' | 'host' | 'hostname'
+| 'URL' | 'header' | 'headers' | 'secure' | 'stale' | 'fresh' | 'ips' | 'ip'>
+& Pick<Response, 'attachment' | 'redirect' | 'remove' | 'vary' | 'has' | 'set' | 'append' | 'flushHeaders'
+| 'status' | 'message' | 'body' | 'length' | 'type' | 'lastModified' | 'etag' | 'headerSent' | 'writable'>
+& AnyProto;