fix: use @eggjs/security and @eggjs/session (#5384)

export Singleton

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

- **Dependencies**
	- Replaced `egg-security` with `@eggjs/security` package
	- Replaced `egg-session` with `@eggjs/session` package
	- Updated security and session plugin references across documentation

- **Documentation**
- Updated plugin, security, and core documentation to reflect new
package naming
	- Corrected GitHub repository links for security and session plugins

- **Configuration**
- Modified plugin configuration to use new `@eggjs/security` and
`@eggjs/session` packages
	- Removed legacy security configuration from type definitions

- **Core Functionality**
	- Added singleton instance management method
	- Enhanced type definitions for core framework components
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: fengmk2

index-old.d.ts

@@ -33,11 +33,8 @@
 // } from 'egg-core';
 // import EggCookies = require('egg-cookies');
 // import 'egg-onerror';
-// import 'egg-session';
 // import 'egg-multipart';
-// import 'egg-security';
 // import 'egg-logrotator';
-// import '@eggjs/schedule';
 // import 'egg-view';
 
 // declare module 'egg' {

package.json

@@ -26,6 +26,8 @@
     "@eggjs/i18n": "^3.0.1",
     "@eggjs/jsonp": "^3.0.0",
     "@eggjs/schedule": "^5.0.2",
+    "@eggjs/security": "^4.0.0",
+    "@eggjs/session": "^4.0.0",
     "@eggjs/static": "^3.0.0",
     "@eggjs/utils": "^4.2.4",
     "@eggjs/watcher": "^4.0.3",
@@ -36,8 +38,6 @@
     "egg-logrotator": "^3.1.0",
     "egg-multipart": "^3.1.0",
     "egg-onerror": "^2.1.1",
-    "egg-security": "^3.0.0",
-    "egg-session": "^3.3.0",
     "egg-view": "^2.1.3",
     "extend2": "^4.0.0",
     "graceful": "^2.0.0",

site/docs/advanced/view-plugin.md

@@ -121,7 +121,7 @@ module.exports = {
 
 The framework provides `ctx.helper` for developer use, but in some cases we want to override the helper method and only take effect when the template is rendered.
 
-In template rendering, we often need to output a user-supplied html fragment, in which case, we often use the `helper.shtml` provided by the `egg-security` plugin.
+In template rendering, we often need to output a user-supplied html fragment, in which case, we often use the `helper.shtml` provided by the `@eggjs/security` plugin.
 
 ```html
 <div>{{ helper.shtml(data.content) | safe }}</div>
@@ -163,9 +163,9 @@ You can [view](https://github.com/eggjs/egg-view-nunjucks/blob/2ee5ee992cfd95bc0
 
 ### Security Related
 
-Templates and security are related and [egg-security] also provides some methods for the template. The template engine can be used according to requirements.
+Templates and security are related and [@eggjs/security] also provides some methods for the template. The template engine can be used according to requirements.
 
-First declare a dependency on [egg-security]:
+First declare a dependency on [@eggjs/security]:
 
 ```json
 {
@@ -183,6 +183,6 @@ Besides, the framework provides [app.injectCsrf](../core/security.md#appinjectcs
 
 As a high-quality plugin, perfect unit testing is indispensable, and we also provide lots of auxiliary tools to make it painless for plugin developers to write tests with, see [unit testing](../core/unittest.md) and [plugin](./plugin.md) docs.
 
-[egg-security]: https://github.com/eggjs/egg-security
+[@eggjs/security]: https://github.com/eggjs/security
 [egg-view-nunjucks]: https://github.com/eggjs/egg-view-nunjucks
 [egg-view-ejs]: https://github.com/eggjs/egg-view-ejs

site/docs/advanced/view-plugin.zh-CN.md

@@ -116,7 +116,7 @@ module.exports = {
 
 框架本身提供了 `ctx.helper` 供开发者使用。但在某些情况下，我们希望覆盖 helper 方法，使其仅在模板渲染时生效。
 
-在模板渲染中，我们经常需要输出用户提供的 HTML 片段，这通常需要使用 `egg-security` 插件提供的 `helper.shtml` 方法进行清洗：
+在模板渲染中，我们经常需要输出用户提供的 HTML 片段，这通常需要使用 `@eggjs/security` 插件提供的 `helper.shtml` 方法进行清洗：
 
 ```html
 <div>{{ helper.shtml(data.content) | safe }}</div>
@@ -160,9 +160,9 @@ module.exports = class MyCustomView {
 
 ### 安全相关
 
-模板与安全密不可分。[egg-security] 也为模板提供了一些方法。模板引擎可以根据需求使用这些方法。
+模板与安全密不可分。[@eggjs/security] 也为模板提供了一些方法。模板引擎可以根据需求使用这些方法。
 
-首先声明对 [egg-security] 的依赖：
+首先声明对 [@eggjs/security] 的依赖：
 
 ```json
 {
@@ -180,6 +180,6 @@ module.exports = class MyCustomView {
 
 为了确保插件的高质量，完善的单元测试是不可或缺的。我们也提供了很多辅助工具，以帮助插件开发者毫无障碍地编写测试。具体内容请参见[单元测试](../core/unittest.md)与[插件](./plugin.md)相关章节。
 
-[egg-security]: https://github.com/eggjs/egg-security
+[@eggjs/security]: https://github.com/eggjs/security
 [egg-view-nunjucks]: https://github.com/eggjs/egg-view-nunjucks
 [egg-view-ejs]: https://github.com/eggjs/egg-view-ejs

site/docs/basics/controller.md

@@ -684,7 +684,7 @@ module.exports = {
 
 By using Cookie, we can create an individual Session specific to every user to store user identity information, which will be encrypted then stored in Cookie to perform session persistence across requests.
 
-The framework builds in [Session](https://github.com/eggjs/egg-session) plugin, which provides `ctx.session` for us to get or set current user's Session.
+The framework builds in [Session](https://github.com/eggjs/session) plugin, which provides `ctx.session` for us to get or set current user's Session.
 
 ```js
 class PostController extends Controller {

site/docs/basics/controller.zh-CN.md

@@ -671,7 +671,7 @@ module.exports = {
 
 Cookie 可以存储每个用户的 Session 来保持跨请求的用户身份。这些信息加密后存储在 Cookie 中。
 
-框架内置了 [Session](https://github.com/eggjs/egg-session) 插件，通过 `ctx.session` 访问或修改用户 Session：
+框架内置了 [Session](https://github.com/eggjs/session) 插件，通过 `ctx.session` 访问或修改用户 Session：
 
 ```js
 class PostController extends Controller {
@@ -1077,4 +1077,4 @@ exports.security = {
 };
 ```
 
-如果没有配置 `domainWhiteList` 或 `domainWhiteList` 数组为空，则默认允许所有跳转请求，等同于使用 `ctx.unsafeRedirect(url)`。
+如果没有配置 `domainWhiteList` 或 `domainWhiteList` 数组为空，则默认允许所有跳转请求，等同于使用 `ctx.unsafeRedirect(url)`。

site/docs/basics/plugin.md

@@ -161,11 +161,11 @@ Specific consolidation rules can be found in [Configuration](./config.md).
 
 - Framework has default built-in plugins for enterprise applications [Common plugins](https://eggjs.org/zh-cn/plugins/):
     - [onerror](https://github.com/eggjs/egg-onerror) Uniform Exception Handling
-    - [Session](https://github.com/eggjs/egg-session) Session implementation
+    - [session](https://github.com/eggjs/session) Session implementation
     - [i18n](https://github.com/eggjs/i18n) Multilingual
     - [watcher](https://github.com/eggjs/watcher) File and folder monitoring
     - [multipart](https://github.com/eggjs/egg-multipart) File Streaming Upload
-    - [security](https://github.com/eggjs/egg-security) Security
+    - [security](https://github.com/eggjs/security) Security
     - [development](https://github.com/eggjs/development) Development Environment Configuration
     - [logrotator](https://github.com/eggjs/egg-logrotator) Log segmentation
     - [schedule](https://github.com/eggjs/schedule) Timing tasks

site/docs/basics/plugin.zh-CN.md

@@ -161,11 +161,11 @@ exports.mysql = {
 
 - 框架默认内置了企业级应用[常用的插件](https://eggjs.org/zh-cn/plugins/)：
   - [onerror](https://github.com/eggjs/egg-onerror) 统一异常处理
-  - [Session](https://github.com/eggjs/egg-session) Session 实现
+  - [session](https://github.com/eggjs/session) Session 实现
   - [i18n](https://github.com/eggjs/i18n) 多语言
   - [watcher](https://github.com/eggjs/watcher) 文件和文件夹监控
   - [multipart](https://github.com/eggjs/egg-multipart) 文件流式上传
-  - [security](https://github.com/eggjs/egg-security) 安全
+  - [security](https://github.com/eggjs/security) 安全
   - [development](https://github.com/eggjs/development) 开发环境配置
   - [logrotator](https://github.com/eggjs/egg-logrotator) 日志切分
   - [schedule](https://github.com/eggjs/schedule) 定时任务

site/docs/basics/router.md

@@ -214,7 +214,7 @@ exports.post = async (ctx) => {
 
 > **Reason**: the framework verifies the CSRF value specially for form POST requests, so please submit the CSRF key as well when you submit a form. Refer to [Keep Away from CSRF Threat](https://eggjs.org/zh-cn/core/security.html#安全威胁csrf的防范) for more detail.
 
-> **Note**: the verification is performed because the framework builds in a security plugin [egg-security](https://github.com/eggjs/egg-security) that provides some default security practices and this plugin is enabled by default. In case you want to disable some security protections, just set the enable attribute to false.
+> **Note**: the verification is performed because the framework builds in a security plugin [@eggjs/security](https://github.com/eggjs/security) that provides some default security practices and this plugin is enabled by default. In case you want to disable some security protections, just set the enable attribute to false.
 
 > "Unless you clearly confirm the consequence, it's not recommended to disable functions provided by the security plugin"
 

site/docs/basics/router.zh-CN.md

@@ -211,7 +211,7 @@ exports.post = async (ctx) => {
 
 > **原因**：框架内部针对表单 POST 请求均会验证 CSRF 的值，因此我们在表单提交时，需要带上 CSRF key 进行提交。具体可参考[安全威胁 CSRF 的防范](https://eggjs.org/zh-cn/core/security.html#安全威胁csrf的防范)。
 
-> **注意**：上述校验是因为框架中内置了安全插件 [egg-security](https://github.com/eggjs/egg-security)，提供了一些默认的安全实践，并且框架的安全插件默认是开启的。如果需要关闭一些安全防范，直接设置相应选项的 `enable` 属性为 `false` 即可。
+> **注意**：上述校验是因为框架中内置了安全插件 [@eggjs/security](https://github.com/eggjs/security)，提供了一些默认的安全实践，并且框架的安全插件默认是开启的。如果需要关闭一些安全防范，直接设置相应选项的 `enable` 属性为 `false` 即可。
 
 > 虽然不推荐，但如果确实需要关闭某些安全功能，可以在 `config/config.default.js` 中设置以下代码：
 

site/docs/community/faq.md

@@ -77,7 +77,7 @@ There are two kinds of common csrf errors:
 - `missing csrf token`
 - `invalid csrf token`
 
-By default [egg-security](https://github.com/eggjs/egg-security/) plugin built in Egg requires CSRF validation against all 'unsafe' request such as `POST`, `PUT`, `DELETE` requests.
+By default [@eggjs/security](https://github.com/eggjs/security/) plugin built in Egg requires CSRF validation against all 'unsafe' request such as `POST`, `PUT`, `DELETE` requests.
 
 The error will disappear in the presence of the correct csrf token in the request. For more implementation details, see [../core/security.md#csrf].
 

site/docs/community/faq.zh-CN.md

@@ -79,7 +79,7 @@ pm2 start server.js
 - `missing csrf token`
 - `invalid csrf token`
 
-Egg 内置的 [egg-security](https://github.com/eggjs/egg-security/) 插件默认对所有“非安全”的方法，例如 `POST`、`PUT`、`DELETE`，都进行 CSRF 校验。
+Egg 内置的 [@eggjs/security](https://github.com/eggjs/security/) 插件默认对所有“非安全”的方法，例如 `POST`、`PUT`、`DELETE`，都进行 CSRF 校验。
 
 遇到 csrf 报错通常是因为没有加正确的 csrf token 导致的，具体实现方式，请阅读[安全威胁 CSRF 的防范](../core/security.md#安全威胁csrf的防范)。
 

site/docs/core/cookie-and-session.md

@@ -127,7 +127,7 @@ In web applications, Cookie is usually used to identify users.
 So the concept of Session, which is built on top of Cookie,
 was created to specifically handle user identification.
 
-Egg.js built-in supports Session through [egg-session](https://github.com/eggjs/egg-session) plugin.
+Egg.js built-in supports Session through [@eggjs/session](https://github.com/eggjs/session) plugin.
 We can use `ctx.session` to read or modify current user session.
 
 ```js

site/docs/core/cookie-and-session.zh-CN.md

@@ -108,7 +108,7 @@ keys 配置成一个字符串，可以按照逗号分隔配置多个 key。Cooki
 
 Cookie 通常用作 Web 应用中标识请求方身份的功能，基于此，Web 应用封装了 Session 概念，专用于用户身份识别。
 
-框架内置了 [Session](https://github.com/eggjs/egg-session) 插件，提供了 `ctx.session` 用于访问或修改当前用户的 Session。
+框架内置了 [Session](https://github.com/eggjs/session) 插件，提供了 `ctx.session` 用于访问或修改当前用户的 Session。
 
 ```js
 class HomeController extends Controller {

site/docs/core/security.md

@@ -22,7 +22,7 @@ The framework itself has a rich solution for common security risks on the Web si
 - customizable white list for safe redirect and url filtering.
 - all kinds of template related tools for preprocessing.
 
-Security plugins [egg-security](https://github.com/eggjs/egg-security) are built into the framework, provides default security practices.
+Security plugins [@eggjs/security](https://github.com/eggjs/security) are built into the framework, provides default security practices.
 
 ### Open or Close the Configuration
 

site/docs/core/security.zh-CN.md

@@ -22,7 +22,7 @@ Web 应用中存在很多安全风险，这些风险可能会被黑客利用。
 - 可定制的白名单，用于安全跳转和 url 过滤。
 - 各种模板相关的工具函数做预处理。
 
-框架内置了安全插件 [egg-security](https://github.com/eggjs/egg-security)，提供了默认的安全实践。
+框架内置了安全插件 [@eggjs/security](https://github.com/eggjs/security)，提供了默认的安全实践。
 
 ### 开启与关闭配置
 

site/docs/core/view.md

@@ -218,8 +218,8 @@ await ctx.renderString('{{ helper.lowercaseFirst(name) }}', data);
 
 ## Security
 
-The built-in plugin [egg-security] provides common security helper functions, including `helper.shtml / surl / sjs` and so on. It's strongly recommended to read [Security](./security.md).
+The built-in plugin [@eggjs/security] provides common security helper functions, including `helper.shtml / surl / sjs` and so on. It's strongly recommended to read [Security](./security.md).
 
-[egg-security]: https://github.com/eggjs/egg-security
+[@eggjs/security]: https://github.com/eggjs/security
 [egg-view-nunjucks]: https://github.com/eggjs/egg-view-nunjucks
 [egg-view]: https://github.com/eggjs/egg-view

site/docs/core/view.zh-CN.md

@@ -197,8 +197,8 @@ await ctx.renderString('{{ helper.lowercaseFirst(name) }}', data);
 
 ## 安全性（Security）
 
-框架内置的 [egg-security] 插件，提供了常见的安全辅助函数，包括 `helper.shtml`、`surl`、`sjs` 等，强烈建议阅读安全性相关的[文档内容](./security.md)。
+框架内置的 [@eggjs/security] 插件，提供了常见的安全辅助函数，包括 `helper.shtml`、`surl`、`sjs` 等，强烈建议阅读安全性相关的[文档内容](./security.md)。
 
-[egg-security]: https://github.com/eggjs/egg-security
+[@eggjs/security]: https://github.com/eggjs/security
 [egg-view-nunjucks]: https://github.com/eggjs/egg-view-nunjucks
 [egg-view]: https://github.com/eggjs/egg-view

site/docs/intro/egg-and-koa.md

@@ -124,7 +124,7 @@ One plugin can include:
 
 A stand-alone module plugin can provide rich features with high maintainability. You can almost forget the configuration as the plugin supports configuring the default value in different environments.
 
-[egg-security](https://github.com/eggjs/egg-security) is a typical example.
+[@eggjs/security](https://github.com/eggjs/security) is a typical example.
 
 More about plugin, please check [Plugin](../basics/plugin.md) section.
 

site/docs/intro/egg-and-koa.zh-CN.md

@@ -125,7 +125,7 @@ exports.handler = (ctx) => {
 
 在一个独立领域下实现的插件，可以在维护性非常高的情况下提供完善的功能。插件还支持配置各个环境下的默认（最佳）配置，使得使用插件时几乎无需修改配置项。
 
-[egg-security](https://github.com/eggjs/egg-security) 插件是一个典型的例子。
+[@eggjs/security](https://github.com/eggjs/security) 插件是一个典型的例子。
 
 更多关于插件的内容，请查看[插件](../basics/plugin.md)章节。
 

src/config/plugin.ts

@@ -17,7 +17,7 @@ export default {
    */
   session: {
     enable: true,
-    package: 'egg-session',
+    package: '@eggjs/session',
   },
 
   /**
@@ -61,7 +61,7 @@ export default {
    */
   security: {
     enable: true,
-    package: 'egg-security',
+    package: '@eggjs/security',
   },
 
   /**

src/index.ts

@@ -23,6 +23,7 @@ export type {
 export * from './lib/egg.js';
 export * from './lib/types.js';
 export * from './lib/start.js';
+export * from './lib/core/singleton.js';
 
 // export errors
 export * from './lib/error/index.js';

src/lib/core/singleton.ts

@@ -1,19 +1,19 @@
 import assert from 'node:assert';
 import { isAsyncFunction } from 'is-type-of';
-import type { EggApplicationCore } from '../egg.js';
+import type { EggCore } from '@eggjs/core';
 
 export type SingletonCreateMethod =
-  (config: Record<string, any>, app: EggApplicationCore, clientName: string) => unknown | Promise<unknown>;
+  (config: Record<string, any>, app: EggCore, clientName: string) => unknown | Promise<unknown>;
 
 export interface SingletonOptions {
   name: string;
-  app: EggApplicationCore;
+  app: EggCore;
   create: SingletonCreateMethod;
 }
 
-export class Singleton {
-  readonly clients = new Map<string, any>();
-  readonly app: EggApplicationCore;
+export class Singleton<T = any> {
+  readonly clients = new Map<string, T>();
+  readonly app: EggCore;
   readonly create: SingletonCreateMethod;
   readonly name: string;
   readonly options: Record<string, any>;
@@ -46,7 +46,7 @@ export class Singleton {
       return;
     }
 
-    // multi client, use app[name].getInstance(id)
+    // multi client, use app[name].getSingletonInstance(id)
     if (options.clients) {
       Object.keys(options.clients).forEach(id => {
         const client = this.createInstance(options.clients[id], id);
@@ -91,13 +91,18 @@ export class Singleton {
     Reflect.set(this.app, this.name, client);
   }
 
+  /**
+   * @deprecated please use `getSingletonInstance(id)` instead
+   */
   get(id: string) {
-    return this.clients.get(id);
+    return this.clients.get(id)!;
   }
 
-  // alias to `get(id)`
+  /**
+   * Get singleton instance by id
+   */
   getSingletonInstance(id: string) {
-    return this.clients.get(id);
+    return this.clients.get(id)!;
   }
 
   createInstance(config: Record<string, any>, clientName: string) {
@@ -109,7 +114,7 @@ export class Singleton {
       ...this.options.default,
       ...config,
     };
-    return (this.create as SingletonCreateMethod)(config, this.app, clientName);
+    return (this.create as SingletonCreateMethod)(config, this.app, clientName) as T;
   }
 
   async createInstanceAsync(config: Record<string, any>, clientName: string) {
@@ -118,7 +123,7 @@ export class Singleton {
       ...this.options.default,
       ...config,
     };
-    return await this.create(config, this.app, clientName);
+    return await this.create(config, this.app, clientName) as T;
   }
 
   #extendDynamicMethods(client: any) {

src/lib/egg.ts

@@ -702,5 +702,6 @@ declare module '@eggjs/core' {
     HttpClient: typeof HttpClient;
     get httpClient(): HttpClient;
     curl<T = any>(url: HttpClientRequestURL, options?: HttpClientRequestOptions): Promise<HttpClientResponse<T>>;
+    addSingleton(name: string, create: SingletonCreateMethod): void;
   }
 }