egg 4.0.0-beta.0 → 4.0.0-beta.11

package/src/app/extend/context.ts

@@ -0,0 +1,303 @@
+import delegate from 'delegates';
+import { assign } from 'utility';
+import { now, diff } from 'performance-ms';
+import {
+  utils, Context as EggCoreContext, Router,
+  type ContextDelegation as EggCoreContextDelegation,
+} from '@eggjs/core';
+import type { Cookies as ContextCookies } from '@eggjs/cookies';
+import { EggLogger } from 'egg-logger';
+import type { Application } from '../../lib/application.js';
+import type {
+  HttpClientRequestURL, HttpClientRequestOptions, HttpClient,
+} from '../../lib/core/httpclient.js';
+import type { ContextHttpClient } from '../../lib/core/context_httpclient.js';
+import type { BaseContextClass } from '../../lib//core/base_context_class.js';
+import Request from './request.js';
+import Response from './response.js';
+import type Helper from './helper.js';
+
+import './context.types.js';
+
+const HELPER = Symbol('ctx helper');
+const LOCALS = Symbol('ctx locals');
+const LOCALS_LIST = Symbol('ctx localsList');
+const COOKIES = Symbol('ctx cookies');
+const CONTEXT_HTTPCLIENT = Symbol('ctx httpclient');
+const CONTEXT_ROUTER = Symbol('ctx router');
+
+interface Cookies extends ContextCookies {
+  request: any;
+  response: any;
+}
+
+export default class Context extends EggCoreContext {
+  declare app: Application;
+  declare request: Request;
+  declare service: BaseContextClass;
+
+  /**
+   * Request start time
+   * @member {Number} Context#starttime
+   */
+  starttime: number;
+  /**
+   * Request start timer using `performance.now()`
+   * @member {Number} Context#performanceStarttime
+   */
+  performanceStarttime: number;
+
+  /**
+   * Get the current visitor's cookies.
+   */
+  get cookies() {
+    let cookies = this[COOKIES];
+    if (!cookies) {
+      this[COOKIES] = cookies = new this.app.ContextCookies(this, this.app.keys, this.app.config.cookies);
+    }
+    return cookies as Cookies;
+  }
+
+  /**
+   * Get a wrapper httpclient instance contain ctx in the hold request process
+   *
+   * @return {ContextHttpClient} the wrapper httpclient instance
+   */
+  get httpclient(): ContextHttpClient {
+    if (!this[CONTEXT_HTTPCLIENT]) {
+      this[CONTEXT_HTTPCLIENT] = new this.app.ContextHttpClient(this as any);
+    }
+    return this[CONTEXT_HTTPCLIENT] as ContextHttpClient;
+  }
+
+  /**
+   * Alias to {@link Context#httpclient}
+   */
+  get httpClient(): ContextHttpClient {
+    return this.httpclient;
+  }
+
+  /**
+   * Shortcut for httpclient.curl
+   *
+   * @function Context#curl
+   * @param {String|Object} url - request url address.
+   * @param {Object} [options] - options for request.
+   * @return {Object} see {@link ContextHttpClient#curl}
+   */
+  async curl(url: HttpClientRequestURL, options?: HttpClientRequestOptions): ReturnType<HttpClient['request']> {
+    return await this.httpclient.curl(url, options);
+  }
+
+  /**
+   * Alias to {@link Application#router}
+   *
+   * @member {Router} Context#router
+   * @since 1.0.0
+   * @example
+   * ```js
+   * this.router.pathFor('post', { id: 12 });
+   * ```
+   */
+  get router(): Router {
+    if (this[CONTEXT_ROUTER]) {
+      return this[CONTEXT_ROUTER] as Router;
+    }
+    return this.app.router;
+  }
+
+  /**
+   * Set router to Context, only use on EggRouter
+   * @param {Router} val router instance
+   */
+  set router(val: Router) {
+    this[CONTEXT_ROUTER] = val;
+  }
+
+  /**
+   * Get helper instance from {@link Application#Helper}
+   *
+   * @member {Helper} Context#helper
+   * @since 1.0.0
+   */
+  get helper(): Helper {
+    if (!this[HELPER]) {
+      this[HELPER] = new this.app.Helper(this as any);
+    }
+    return this[HELPER] as Helper;
+  }
+
+  /**
+   * Wrap app.loggers with context information,
+   * if a custom logger is defined by naming aLogger, then you can `ctx.getLogger('aLogger')`
+   *
+   * @param {String} name - logger name
+   */
+  getLogger(name: string): EggLogger {
+    return this.app.getLogger(name);
+  }
+
+  /**
+   * Logger for Application
+   *
+   * @member {Logger} Context#logger
+   * @since 1.0.0
+   * @example
+   * ```js
+   * this.logger.info('some request data: %j', this.request.body);
+   * this.logger.warn('WARNING!!!!');
+   * ```
+   */
+  get logger(): EggLogger {
+    return this.getLogger('logger');
+  }
+
+  /**
+   * Logger for frameworks and plugins
+   *
+   * @member {Logger} Context#coreLogger
+   * @since 1.0.0
+   */
+  get coreLogger(): EggLogger {
+    return this.getLogger('coreLogger');
+  }
+
+  /**
+   * locals is an object for view, you can use `app.locals` and `ctx.locals` to set variables,
+   * which will be used as data when view is rendering.
+   * The difference between `app.locals` and `ctx.locals` is the context level, `app.locals` is global level, and `ctx.locals` is request level. when you get `ctx.locals`, it will merge `app.locals`.
+   *
+   * when you set locals, only object is available
+   *
+   * ```js
+   * this.locals = {
+   *   a: 1
+   * };
+   * this.locals = {
+   *   b: 1
+   * };
+   * this.locals.c = 1;
+   * console.log(this.locals);
+   * {
+   *   a: 1,
+   *   b: 1,
+   *   c: 1,
+   * };
+   * ```
+   *
+   * `ctx.locals` has cache, it only merges `app.locals` once in one request.
+   *
+   * @member {Object} Context#locals
+   */
+  get locals() {
+    if (!this[LOCALS]) {
+      this[LOCALS] = assign({}, this.app.locals);
+    }
+    if (Array.isArray(this[LOCALS_LIST]) && this[LOCALS_LIST].length > 0) {
+      assign(this[LOCALS], this[LOCALS_LIST]);
+      this[LOCALS_LIST] = null;
+    }
+    return this[LOCALS] as Record<string, any>;
+  }
+
+  set locals(val) {
+    const localsList = this[LOCALS_LIST] as Record<string, any>[] ?? [];
+    localsList.push(val);
+    this[LOCALS_LIST] = localsList;
+  }
+
+  /**
+   * alias to {@link Context#locals}, compatible with koa that use this variable
+   * @member {Object} state
+   * @see Context#locals
+   */
+  get state() {
+    return this.locals;
+  }
+
+  set state(val) {
+    this.locals = val;
+  }
+
+  /**
+   * Run async function in the background
+   * @param {Function} scope - the first args is ctx
+   * ```js
+   * this.body = 'hi';
+   *
+   * this.runInBackground(async ctx => {
+   *   await ctx.mysql.query(sql);
+   *   await ctx.curl(url);
+   * });
+   * ```
+   */
+  runInBackground(scope: (ctx: ContextDelegation) => Promise<void>, taskName?: string): void {
+    // try to use custom function name first
+    if (!taskName) {
+      taskName = Reflect.get(scope, '_name') || scope.name || utils.getCalleeFromStack(true);
+    }
+    // use setImmediate to ensure all sync logic will run async
+    setImmediate(() => {
+      this._runInBackground(scope, taskName!);
+    });
+  }
+
+  // let plugins or frameworks to reuse _runInBackground in some cases.
+  // e.g.: https://github.com/eggjs/egg-mock/pull/78
+  async _runInBackground(scope: (ctx: ContextDelegation) => Promise<void>, taskName: string) {
+    const startTime = now();
+    try {
+      await scope(this as any);
+      this.coreLogger.info('[egg:background] task:%s success (%dms)', taskName, diff(startTime));
+    } catch (err: any) {
+      // background task process log
+      this.coreLogger.info('[egg:background] task:%s fail (%dms)', taskName, diff(startTime));
+
+      // emit error when promise catch, and set err.runInBackground flag
+      err.runInBackground = true;
+      this.app.emit('error', err, this);
+    }
+  }
+}
+
+/**
+ * Context delegation.
+ */
+
+delegate(Context.prototype, 'request')
+  /**
+   * @member {Boolean} Context#acceptJSON
+   * @see Request#acceptJSON
+   * @since 1.0.0
+   */
+  .getter('acceptJSON')
+  /**
+   * @member {Array} Context#queries
+   * @see Request#queries
+   * @since 1.0.0
+   */
+  .getter('queries')
+  /**
+   * @member {Boolean} Context#accept
+   * @see Request#accept
+   * @since 1.0.0
+   */
+  .getter('accept')
+  /**
+   * @member {string} Context#ip
+   * @see Request#ip
+   * @since 1.0.0
+   */
+  .access('ip');
+
+delegate(Context.prototype, 'response')
+  /**
+   * @member {Number} Context#realStatus
+   * @see Response#realStatus
+   * @since 1.0.0
+   */
+  .access('realStatus');
+
+export type ContextDelegation = EggCoreContextDelegation & Context
+& Pick<Request, 'acceptJSON' | 'queries' | 'accept' | 'ip'>
+& Pick<Response, 'realStatus'>;

package/src/app/extend/context.types.ts

@@ -0,0 +1,24 @@
+import type {
+  Router,
+} from '@eggjs/core';
+import type {
+  HttpClientRequestURL, HttpClientRequestOptions, HttpClient,
+} from '../../lib/core/httpclient.js';
+import type {
+  ContextHttpClient,
+} from '../../lib/core/context_httpclient.js';
+import type Helper from './helper.js';
+import type { EggLogger } from 'egg-logger';
+
+declare module '@eggjs/core' {
+  // add Context overrides types
+  interface Context {
+    curl(url: HttpClientRequestURL, options?: HttpClientRequestOptions): ReturnType<HttpClient['request']>;
+    get router(): Router;
+    set router(val: Router);
+    get helper(): Helper;
+    get httpclient(): ContextHttpClient;
+    get httpClient(): ContextHttpClient;
+    getLogger(name: string): EggLogger;
+  }
+}

package/src/app/extend/{helper.js → helper.ts}

@@ -1,10 +1,12 @@
-'use strict';
-
-const url = require('url');
-
-
-module.exports = {
+import url from 'node:url';
+import { BaseContextClass } from '../../lib/core/base_context_class.js';
 
+/**
+ * The Helper class which can be used as utility function.
+ * We support developers to extend Helper through ${baseDir}/app/extend/helper.js ,
+ * then you can use all method on `ctx.helper` that is a instance of Helper.
+ */
+export default class Helper extends BaseContextClass {
   /**
    * Generate URL path(without host) for route. Takes the route name and a map of named params.
    * @function Helper#pathFor
@@ -19,9 +21,9 @@ module.exports = {
    * ```
    * @return {String} url path(without host)
    */
-  pathFor(name, params) {
+  pathFor(name: string, params: Record<string, any>): string {
     return this.app.router.url(name, params);
-  },
+  }
 
   /**
    * Generate full URL(with host) for route. Takes the route name and a map of named params.
@@ -36,8 +38,7 @@ module.exports = {
    * ```
    * @return {String} full url(with host)
    */
-  urlFor(name, params) {
-    return this.ctx.protocol + '://' + this.ctx.host + url.resolve('/', this.app.router.url(name, params));
-  },
-
-};
+  urlFor(name: string, params: Record<string, any>): string {
+    return this.ctx.protocol + '://' + this.ctx.host + url.resolve('/', this.pathFor(name, params));
+  }
+}

package/src/app/extend/{request.js → request.ts}

@@ -1,17 +1,21 @@
-'use strict';
+import querystring from 'node:querystring';
+import { Request as EggCoreRequest } from '@eggjs/core';
+import type { Application } from '../../lib/application.js';
+import type { ContextDelegation } from './context.js';
+import Response from './response.js';
 
-const querystring = require('querystring');
-const accepts = require('accepts');
-
-const _querycache = Symbol('_querycache');
-const _queriesCache = Symbol('_queriesCache');
-const PROTOCOL = Symbol('PROTOCOL');
-const HOST = Symbol('HOST');
-const ACCEPTS = Symbol('ACCEPTS');
-const IPS = Symbol('IPS');
+const QUERY_CACHE = Symbol('request query cache');
+const QUERIES_CACHE = Symbol('request queries cache');
+const PROTOCOL = Symbol('request protocol');
+const HOST = Symbol('request host');
+const IPS = Symbol('request ips');
 const RE_ARRAY_KEY = /[^\[\]]+\[\]$/;
 
-module.exports = {
+export default class Request extends EggCoreRequest {
+  declare app: Application;
+  declare ctx: ContextDelegation;
+  declare response: Response;
+
   /**
    * Parse the "Host" header field host
    * and support X-Forwarded-Host when a
@@ -29,17 +33,19 @@ module.exports = {
    * => 'demo.eggjs.org'
    * ```
    */
-  get host() {
-    if (this[HOST]) return this[HOST];
+  get host(): string {
+    let host = this[HOST] as string | undefined;
+    if (host) {
+      return host;
+    }
 
-    let host;
     if (this.app.config.proxy) {
       host = getFromHeaders(this, this.app.config.hostHeaders);
     }
     host = host || this.get('host') || '';
-    this[HOST] = host.split(/\s*,\s*/)[0];
-    return this[HOST];
-  },
+    this[HOST] = host = host.split(',')[0].trim();
+    return host;
+  }
 
   /**
    * @member {String} Request#protocol
@@ -49,25 +55,28 @@ module.exports = {
    * => 'https'
    * ```
    */
-  get protocol() {
-    if (this[PROTOCOL]) return this[PROTOCOL];
+  get protocol(): string {
+    let protocol = this[PROTOCOL] as string;
+    if (protocol) {
+      return protocol;
+    }
     // detect encrypted socket
-    if (this.socket && this.socket.encrypted) {
-      this[PROTOCOL] = 'https';
-      return this[PROTOCOL];
+    if (this.socket?.encrypted) {
+      this[PROTOCOL] = protocol = 'https';
+      return protocol;
     }
     // get from headers specified in `app.config.protocolHeaders`
     if (this.app.config.proxy) {
       const proto = getFromHeaders(this, this.app.config.protocolHeaders);
       if (proto) {
-        this[PROTOCOL] = proto.split(/\s*,\s*/)[0];
-        return this[PROTOCOL];
+        this[PROTOCOL] = protocol = proto.split(/\s*,\s*/)[0];
+        return protocol;
       }
     }
-    // use protocol specified in `app.conig.protocol`
-    this[PROTOCOL] = this.app.config.protocol || 'http';
-    return this[PROTOCOL];
-  },
+    // use protocol specified in `app.config.protocol`
+    this[PROTOCOL] = protocol = this.app.config.protocol || 'http';
+    return protocol;
+  }
 
   /**
    * Get all pass through ip addresses from the request.
@@ -80,29 +89,34 @@ module.exports = {
    * => ['100.23.1.2', '201.10.10.2']
    * ```
    */
-  get ips() {
-    if (this[IPS]) return this[IPS];
+  get ips(): string[] {
+    let ips = this[IPS] as string[] | undefined;
+    if (ips) {
+      return ips;
+    }
 
     // return empty array when proxy=false
     if (!this.app.config.proxy) {
-      this[IPS] = [];
-      return this[IPS];
+      this[IPS] = ips = [];
+      return ips;
     }
 
-    const val = getFromHeaders(this, this.app.config.ipHeaders) || '';
-    this[IPS] = val ? val.split(/\s*,\s*/) : [];
+    const val = getFromHeaders(this, this.app.config.ipHeaders);
+    this[IPS] = ips = val ? val.split(/\s*,\s*/) : [];
 
     let maxIpsCount = this.app.config.maxIpsCount;
     // Compatible with maxProxyCount logic (previous logic is wrong, only for compatibility with legacy logic)
-    if (!maxIpsCount && this.app.config.maxProxyCount) maxIpsCount = this.app.config.maxProxyCount + 1;
+    if (!maxIpsCount && this.app.config.maxProxyCount) {
+      maxIpsCount = this.app.config.maxProxyCount + 1;
+    }
 
     if (maxIpsCount > 0) {
       // if maxIpsCount present, only keep `maxIpsCount` ips
       // [ illegalIp, clientRealIp, proxyIp1, proxyIp2 ...]
-      this[IPS] = this[IPS].slice(-maxIpsCount);
+      this[IPS] = ips = ips.slice(-maxIpsCount);
     }
-    return this[IPS];
-  },
+    return ips;
+  }
 
   /**
    * Get the request remote IPv4 address
@@ -115,16 +129,16 @@ module.exports = {
    * => '111.10.2.1'
    * ```
    */
-  get ip() {
+  get ip(): string {
     if (this._ip) {
       return this._ip;
     }
-    const ip = this.ips[0] || this.socket.remoteAddress;
+    const ip = this.ips[0] ?? this.socket.remoteAddress;
     // will be '::ffff:x.x.x.x', should convert to standard IPv4 format
     // https://zh.wikipedia.org/wiki/IPv6
-    this._ip = ip && ip.indexOf('::ffff:') > -1 ? ip.substring(7) : ip;
+    this._ip = ip && ip.startsWith('::ffff:') ? ip.substring(7) : ip;
     return this._ip;
-  },
+  }
 
   /**
    * Set the request remote IPv4 address
@@ -137,9 +151,9 @@ module.exports = {
    * => '111.10.2.1'
    * ```
    */
-  set ip(ip) {
+  set ip(ip: string) {
     this._ip = ip;
-  },
+  }
 
   /**
    * detect if response should be json
@@ -150,25 +164,25 @@ module.exports = {
    * @member {Boolean} Request#acceptJSON
    * @since 1.0.0
    */
-  get acceptJSON() {
+  get acceptJSON(): boolean {
     if (this.path.endsWith('.json')) return true;
     if (this.response.type && this.response.type.indexOf('json') >= 0) return true;
     if (this.accepts('html', 'text', 'json') === 'json') return true;
     return false;
-  },
+  }
 
   // How to read query safely
   // https://github.com/koajs/qs/issues/5
-  _customQuery(cacheName, filter) {
+  _customQuery(cacheName: symbol, filter: (value: string | string[]) => string | string[]) {
     const str = this.querystring || '';
-    let c = this[cacheName];
+    let c = this[cacheName] as Record<string, Record<string, string | string[]>>;
     if (!c) {
       c = this[cacheName] = {};
     }
     let cacheQuery = c[str];
     if (!cacheQuery) {
       cacheQuery = c[str] = {};
-      const isQueries = cacheName === _queriesCache;
+      const isQueries = cacheName === QUERIES_CACHE;
       // `querystring.parse` CANNOT parse something like `a[foo]=1&a[bar]=2`
       const query = str ? querystring.parse(str) : {};
       for (const key in query) {
@@ -176,20 +190,19 @@ module.exports = {
           // key is '', like `a=b&`
           continue;
         }
-        const value = filter(query[key]);
+        const value = filter(query[key]!);
         cacheQuery[key] = value;
         if (isQueries && RE_ARRAY_KEY.test(key)) {
           // `this.queries['key'] => this.queries['key[]']` is compatibly supported
-          const subkey = key.substring(0, key.length - 2);
-
-          if (!cacheQuery[subkey]) {
-            cacheQuery[subkey] = value;
+          const subKey = key.substring(0, key.length - 2);
+          if (!cacheQuery[subKey]) {
+            cacheQuery[subKey] = value;
           }
         }
       }
     }
     return cacheQuery;
-  },
+  }
 
   /**
    * get params pass by querystring, all values are of string type.
@@ -212,8 +225,8 @@ module.exports = {
    * ```
    */
   get query() {
-    return this._customQuery(_querycache, firstValue);
-  },
+    return this._customQuery(QUERY_CACHE, firstValue) as Record<string, string>;
+  }
 
   /**
    * get params pass by querystring, all value are Array type. {@link Request#query}
@@ -232,50 +245,39 @@ module.exports = {
    * ```
    */
   get queries() {
-    return this._customQuery(_queriesCache, arrayValue);
-  },
-
-  get accept() {
-    let accept = this[ACCEPTS];
-    if (accept) {
-      return accept;
-    }
-    accept = this[ACCEPTS] = accepts(this.req);
-    return accept;
-  },
+    return this._customQuery(QUERIES_CACHE, arrayValue) as Record<string, string[]>;
+  }
 
   /**
    * Set query-string as an object.
    *
    * @function Request#query
    * @param {Object} obj set querystring and query object for request.
-   * @return {void}
    */
-  set query(obj) {
+  set query(obj: Record<string, string>) {
     this.querystring = querystring.stringify(obj);
-  },
-};
-
+  }
+}
 
-function firstValue(value) {
+function firstValue(value: string | string[]) {
   if (Array.isArray(value)) {
     value = value[0];
   }
   return value;
 }
 
-function arrayValue(value) {
+function arrayValue(value: string | string[]) {
   if (!Array.isArray(value)) {
     value = [ value ];
   }
   return value;
 }
 
-function getFromHeaders(ctx, names) {
+function getFromHeaders(request: Request, names: string) {
   if (!names) return '';
-  names = names.split(/\s*,\s*/);
-  for (const name of names) {
-    const value = ctx.get(name);
+  const fields = names.split(/\s*,\s*/);
+  for (const name of fields) {
+    const value = request.get<string>(name);
     if (value) return value;
   }
   return '';