@maiyunnet/kebab 2.0.7 → 2.0.9

package/sys/ctr.js

@@ -42,9 +42,15 @@ const crypto = __importStar(require("../lib/crypto"));
 const session = __importStar(require("../lib/session"));
 const text = __importStar(require("../lib/text"));
 const sRoute = __importStar(require("../sys/route"));
+/** --- 已加载的 DATA 数据缓存（不是语言包）-- */
 let loadedData = {};
+/** --- 已加载的语言文件列表 --- */
 let localeFiles = [];
+/** --- 已经加载的语言包（全局） ---  */
 let localeData = {};
+/**
+ * --- 清除已经加载的 data 与语言包文件缓存 ---
+ */
 function clearLocaleData() {
     loadedData = {};
     localeFiles = [];
@@ -52,26 +58,45 @@ function clearLocaleData() {
 }
 class Ctr {
     constructor(config, req, res) {
+        /** --- 路由参数序列数组 --- */
         this._param = [];
+        /** --- 当前的 action 名 --- */
         this._action = '';
+        /** --- 请求的 header 列表，key 均为小写 --- */
         this._headers = {};
+        /** --- 原始 POST 数据 --- */
         this._rawPost = {};
+        /** --- POST 数据 --- */
         this._post = {};
+        /** --- 原始 input 字符串 */
         this._input = '';
+        /** --- 上传的文件列表 --- */
         this._files = {};
+        /** --- Cookie 数组 --- */
         this._cookie = {};
+        /** --- Jwt 数组 --- */
         this._jwt = {};
+        /** --- Session 数组 --- */
         this._session = {};
+        /** --- Session --- 对象 */
         this._sess = null;
+        /** --- XSRF TOKEN 值 --- */
         this._xsrf = '';
+        /** --- 自定义 http code --- */
         this._httpCode = 0;
+        // --- Kebab: true，Mutton: false，全局常量等对象 ---
+        /** --- 当前语言名 --- */
         this._locale = 'en';
+        /** --- 本 ctr 已加载的语言文件列表 --- */
         this._localeFiles = [];
+        /** --- 本 ctr 的 locale data --- */
         this._localeData = {};
+        /** --- 一些需要等待的事项的记录（异步任务、事务） --- */
         this._waitInfo = {
             'asyncTask': {
                 'count': 0,
                 'resolve': () => {
+                    // --- NOTHING ---
                 },
                 'callback': function () {
                     return new Promise((resolve) => {
@@ -81,6 +106,7 @@ class Ctr {
             },
             'transaction': 0
         };
+        /** --- auth 对象，user, pwd --- */
         this._authorization = null;
         this._config = config;
         this._req = req;
@@ -89,12 +115,17 @@ class Ctr {
         }
         this._cacheTTL = config.set.cacheTtl;
     }
+    /** --- 当前用户连接是否还在连接中 --- */
     get isAvail() {
         return this._req.socket.writable;
     }
+    /** --- 获取当前过期时间 --- */
     get timeout() {
         return this._timer?.timeout ?? 30_000;
     }
+    /**
+     * --- 设置当前过期时间 ---
+     */
     set timeout(num) {
         if (!this._timer) {
             return;
@@ -103,6 +134,10 @@ class Ctr {
         clearTimeout(this._timer.timer);
         this._timer.timer = setTimeout(this._timer.callback, num);
     }
+    /**
+     * --- 执行一段跳出堆栈的异步代码，代码执行完成前，热更新不会杀死当面进程 且 ftmp 临时文件不会被清除 ---
+     * @param func 异步代码
+     */
     _asyncTask(func) {
         ++this._waitInfo.asyncTask.count;
         setTimeout(() => {
@@ -125,15 +160,26 @@ class Ctr {
     getPrototype(name) {
         return this[name];
     }
+    /** --- 设置类内部的 prototype --- */
     setPrototype(name, val) {
         this[name] = val;
     }
+    /**
+     * --- 实例化后会执行的方法，可重写此方法 ---
+     */
     onLoad() {
         return true;
     }
+    /**
+     * --- 整个结束前会执行本方法，可重写此方法对输出结果再处理一次（Websocket 模式无效） ---
+     * @param rtn 之前用户的输出结果
+     */
     onUnload(rtn) {
         return rtn;
     }
+    /**
+     * --- WebSocket 下在建立 Server 连接之前可对 WebSocket 的信息进行配置 ---
+     */
     onUpgrade() {
         return {};
     }
@@ -143,19 +189,37 @@ class Ctr {
     onMessage() {
         return;
     }
+    /**
+     * --- WebSocket 下连接恢复可写入状态后会调用此事件，可重写此方法 ---
+     */
     onDrain() {
         return;
     }
+    /**
+     * --- WebSocket 下连接被终止后会自动被调用的事件，可重写此方法 ---
+     */
     onClose() {
         return;
     }
+    /**
+     * --- 获取截止当前时间的总运行时间 ---
+     * @param ms 为 true 为毫秒，否则为秒
+     */
     _getRunTime(ms = false) {
         const t = process.hrtime.bigint() - this._config.const.startTime;
         return ms ? Number(t) / 1000000 : Number(t) / 1000000000;
     }
+    /**
+     * --- 获取截止当前内存的使用情况 ---
+     */
     _getMemoryUsage() {
         return process.memoryUsage().rss - this._config.const.startMemory;
     }
+    /**
+     * --- 加载视图 ---
+     * @param path
+     * @param data
+     */
     async _loadView(path, data = {}) {
         const content = await fs.getContent(this._config.const.viewPath + path + '.ejs', 'utf8');
         if (!content) {
@@ -167,21 +231,34 @@ class Ctr {
         data._staticVer = this._config.set.staticVer;
         data._staticPath = this._config.set.staticPath;
         data._staticPathFull = this._config.set.staticPathFull;
+        // --- 语言包 ---
         data.l = (key, data) => {
             return this._l(key, data);
         };
         return lCore.purify(ejs.render(content, data));
     }
+    /**
+     * --- 检测提交的数据类型 ---
+     * @param input 要校验的输入项
+     * @param rule 规则
+     * @param rtn 返回值
+     */
     _checkInput(input, rule, rtn) {
+        // --- 遍历规则 ---
+        // --- input, {'xx': ['require', '> 6', [0, 'xx 必须大于 6']], 'yy': [], '_xsrf': []], rtn ---
         for (const key in rule) {
             const val = rule[key];
+            // --- key 就是上面的 xx ---
             if (input[key] === undefined) {
+                // --- 原值不存在则设定为 null ---
                 input[key] = null;
             }
+            // --- 判断是否需要遍历 val ---
             const c = val.length;
             if (c === 0) {
                 continue;
             }
+            // --- ['require', '> 6', [0, 'xx 必须大于 6']] ---
             const lastK = c - 1;
             if ((val[lastK][0] === undefined) || (val[lastK][1] === undefined) || !Number.isInteger(val[lastK][0]) || (typeof val[lastK][1] !== 'string')) {
                 rtn[0] = 0;
@@ -199,10 +276,12 @@ class Ctr {
                         }
                         return false;
                     }
+                    // --- 判断提交的数据是否在此 array 之内，若没有提交数据，则自动设置为第一个项 ---
                     if (input[key] === null) {
                         input[key] = v[0];
                     }
                     else if (!v.includes(input[key])) {
+                        // --- 不在 ---
                         rtn[0] = val[lastK][0];
                         rtn[1] = val[lastK][1];
                         if (val[lastK][2]) {
@@ -212,6 +291,7 @@ class Ctr {
                     }
                 }
                 else if (v instanceof RegExp) {
+                    // --- 正则 ---
                     if (input[key] !== null && !v.test(input[key])) {
                         rtn[0] = val[lastK][0];
                         rtn[1] = val[lastK][1];
@@ -222,6 +302,7 @@ class Ctr {
                     }
                 }
                 else if (typeof v === 'object' && v.type !== undefined) {
+                    // --- core.checkType ---
                     if (input[key] !== null) {
                         const r = lCore.checkType(input[key], v.type);
                         if (r) {
@@ -297,6 +378,7 @@ class Ctr {
                         case 'bool':
                         case 'boolean': {
                             if (input[key] !== null && (typeof input[key] !== 'boolean')) {
+                                // --- 如果不是 bool 直接失败，字符串的 true, false 也会失败 ---
                                 rtn[0] = val[lastK][0];
                                 rtn[1] = val[lastK][1];
                                 if (val[lastK][2]) {
@@ -308,6 +390,7 @@ class Ctr {
                         }
                         case 'string': {
                             if (input[key] !== null && (typeof input[key] !== 'string')) {
+                                // --- 如果不是 string 直接失败 ---
                                 rtn[0] = val[lastK][0];
                                 rtn[1] = val[lastK][1];
                                 if (val[lastK][2]) {
@@ -321,6 +404,7 @@ class Ctr {
                             let match;
                             if (input[key] !== null) {
                                 if (v[0] === '/') {
+                                    // --- 正则 ---
                                     if (!(new RegExp(v.slice(1, -1))).test(input[key])) {
                                         rtn[0] = val[lastK][0];
                                         rtn[1] = val[lastK][1];
@@ -331,6 +415,7 @@ class Ctr {
                                     }
                                 }
                                 else if ((match = /^([><=]+) *([0-9]+)$/.exec(v))) {
+                                    // --- 判断表达式 ---
                                     let needReturn = false;
                                     const inputNum = Number(input[key]);
                                     const num = Number(match[2]);
@@ -402,11 +487,22 @@ class Ctr {
         }
         return true;
     }
+    /**
+     * --- 检测提交的数据类型（会检测 XSRF） ---
+     * @param input 要校验的输入项
+     * @param rule 规则
+     * @param rtn 返回值
+     */
     _checkXInput(input, rule, rtn) {
         rule['_xsrf'] ??= ['require', this._cookie['XSRF-TOKEN'], [0, 'Bad request, no permission.']];
         return this._checkInput(input, rule, rtn);
     }
+    /**
+     * --- 当前页面开启 XSRF 支持（主要检测 cookie 是否存在） ---
+     * --- 如果当前页面有 CDN，请不要使用 ---
+     */
     _enabledXsrf() {
+        // --- 设置 XSRF 值 ---
         if (this._cookie['XSRF-TOKEN'] === undefined) {
             const xsrf = lCore.random(16, lCore.RANDOM_LUN);
             this._xsrf = xsrf;
@@ -420,9 +516,17 @@ class Ctr {
             this._xsrf = this._cookie['XSRF-TOKEN'];
         }
     }
+    /**
+     * --- 获取 Auth 字符串，用于客户端提交 ---
+     * @param user 用户名
+     * @param pwd 密码
+     */
     _getBasicAuth(user, pwd) {
         return 'Basic ' + crypto.base64Encode(user + ':' + pwd);
     }
+    /**
+     * --- 根据用户 ua 获取当前用户的设备类型 ---
+     */
     _device() {
         const ua = this._req.headers['user-agent']?.toLowerCase();
         if (!ua) {
@@ -437,6 +541,9 @@ class Ctr {
         }
         return 'unknown';
     }
+    /**
+     * --- 通过 header 或 _auth 获取鉴权信息或 JWT 信息（不解析） ---
+     */
     getAuthorization() {
         if (this._authorization !== null) {
             return this._authorization;
@@ -459,6 +566,7 @@ class Ctr {
             return false;
         }
         if (authArr[1].includes('.')) {
+            // --- 不解析，解析使用 JWT 类解析 ---
             return authArr[1];
         }
         if (!(auth = crypto.base64Decode(authArr[1]))) {
@@ -468,6 +576,10 @@ class Ctr {
         this._authorization = { 'user': authArr[0], 'pwd': authArr[1] ?? '' };
         return this._authorization;
     }
+    /**
+     * --- 获取 data 数据 ---
+     * @param path 文件路径（不含扩展名）
+     */
     async _loadData(path) {
         const realPath = this._config.const.dataPath + path + '.json';
         if (loadedData[realPath]) {
@@ -481,22 +593,41 @@ class Ctr {
         loadedData[realPath] = json;
         return json;
     }
+    /**
+     * --- 跳转（302临时跳转），支持相对本项目根路径的路径或绝对路径 ---
+     * @param location 相对或绝对网址
+     */
     _location(location) {
         if (this._res) {
             this._res.setHeader('location', text.urlResolve(this._config.const.urlBase, location));
+            // this._res.writeHead(302); Kebab 中要在最后设置，否则会报错：ERR_HTTP_HEADERS_SENT
         }
         return false;
     }
+    /**
+     * --- 开启 Session ---
+     * @param link Kv 或 Db 实例
+     * @param auth 设为 true 则从头 Authorization 或 post _auth 值读取 token
+     * @param opt name, ttl, ssl, sqlPre
+     */
     async _startSession(link, auth = false, opt = {}) {
         this._sess = new session.Session();
         await this._sess.init(this, link, auth, opt);
     }
+    // --- 本地化 ---
+    /**
+     * --- 设定语言并加载语言包 ---
+     * @param loc 要加载的目标语言
+     * @param pkg 包名，为空自动填充为 default
+     */
     async _loadLocale(loc, pkg = 'default') {
         const lName = loc + '.' + pkg;
         this._locale = loc;
         if (!this._localeFiles.includes(lName)) {
+            // --- 检测全局缓存是否加载 ---
             const lPath = this._config.const.dataPath + 'locale/' + lName;
             if (!localeFiles.includes(lPath)) {
+                // --- 全局缓存没有，先加载全局缓存 ---
                 const locData = await this._loadData('locale/' + lName);
                 if (locData === null) {
                     return false;
@@ -509,6 +640,7 @@ class Ctr {
             else {
                 this._locale = loc;
             }
+            // --- 缓存中一定有文件 ---
             this._localeData[loc] ??= {};
             for (const key in localeData[lPath]) {
                 this._localeData[loc][key] = localeData[lPath][key];
@@ -531,6 +663,10 @@ class Ctr {
             }
         }
     }
+    /**
+     * --- 根据当前后台语言包设置情况获取 JSON 字符串传输到前台 ---
+     * @return string
+     */
     _getLocaleJsonString() {
         if (this._localeData[this._locale] !== undefined) {
             return text.stringifyJson(this._localeData[this._locale]);
@@ -539,9 +675,16 @@ class Ctr {
             return '{}';
         }
     }
+    /**
+     * --- 获取当前语言名 ---
+     */
     _getLocale() {
         return this._locale;
     }
+    /**
+     * --- 开启跨域请求 ---
+     * 返回 true 接续执行，返回 false 需要中断用户本次访问（options请求）
+     */
     _cross() {
         this._res.setHeader('access-control-allow-origin', '*');
         this._res.setHeader('access-control-allow-headers', '*');
@@ -552,6 +695,13 @@ class Ctr {
         }
         return true;
     }
+    // --- 以下：Mutton: false, Kebab: true ---
+    /**
+     * --- 获取语言包值 ---
+     * @param key
+     * @param data 要替换的数据
+     */
+    // eslint-disable-next-line @typescript-eslint/naming-convention
     _l(key, data) {
         if (!this._localeData[this._locale]) {
             return '[LocaleError]' + key;
@@ -573,24 +723,51 @@ class Ctr {
             return this._localeData[this._locale][key];
         }
     }
+    /**
+     * --- 发送 socket 文本 ---
+     * @param data 要发送的信息
+     */
     _writeText(data) {
         return this._socket.writeText(data);
     }
+    /**
+     * --- 发送结果对象文本 ---
+     * @param data 要发送的结果对象，如 [0, 'Failed.']
+     */
     _writeResult(data) {
         return this._socket.writeResult(data);
     }
+    /**
+     * --- 发送 socket 二进制 ---
+     * @param data 要发送的信息
+     */
     _writeBinary(data) {
         return this._socket.writeBinary(data);
     }
+    /**
+     * --- 发送 socket ping ---
+     * @param data 要发送的信息
+     */
     _ping() {
         return this._socket.ping();
     }
+    /**
+     * --- 发送 socket pong ---
+     * @param data 要发送的信息
+     */
     _pong() {
         return this._socket.pong();
     }
+    /**
+     * --- 主动关闭当前 socket 连接 ---
+     */
     _end() {
         this._socket.end();
     }
+    /**
+     * --- 获取 formdata 的信息 ---
+     * @param events 文件处理情况
+     */
     async _handleFormData(events = {}) {
         const rtn = await sRoute.getFormData(this._req, events);
         if (!rtn) {