@maiyunnet/kebab 9.13.8 → 9.14.1

package/sys/mod.d.ts

@@ -80,6 +80,8 @@ export default class Mod {
             'key': string;
             'list': string[];
         };
+        /** --- MySQL 优化器 Hint，如 `INDEX(\`t\` \`idx_xx\`)`，注入到 SELECT 后 --- */
+        'hint'?: string;
         /** --- MySQL 表前缀或 PostgreSQL Schema 名，优先级：选项 > 类属性 > 配置 --- */
         'pre'?: string;
     });
@@ -96,7 +98,7 @@ export default class Mod {
         'value': kebab.DbValue;
     };
     /** --- 创建 JSON 字符串对象，用于 PGSQL 的 jsonb 字段 --- */
-    static json(obj: kebab.Json): any;
+    static json<T>(obj: T): T;
     /**
      * --- 添加一个序列（允许超过 65536 的占位符会被拆分多次执行） ---
      * @param db 数据库对象
@@ -208,6 +210,7 @@ export default class Mod {
             'key': string;
             'list': string[];
         };
+        'hint'?: string;
     }): T & Record<string, any>;
     /**
      * --- 通过 where 条件获取模型 ---
@@ -224,6 +227,7 @@ export default class Mod {
             'key': string;
             'list': string[];
         };
+        'hint'?: string;
     }): T & Record<string, any>;
     /**
      * --- 获取创建对象，通常用于新建数据库条目 ---
@@ -248,6 +252,7 @@ export default class Mod {
         'index'?: string | string[];
         /** --- 通过 key 字段获取，默认为 false，即从主键获取 --- */
         'key'?: boolean;
+        'hint'?: string;
     }): Promise<false | null | (T & Record<string, any>)>;
     static one(db: lDb.Pool | lDb.Transaction, s: string | kebab.Json, opt: {
         'ctr'?: sCtr.Ctr;
@@ -256,6 +261,7 @@ export default class Mod {
         'index'?: string | string[];
         'select'?: string | string[];
         'by'?: [string | string[], 'DESC' | 'ASC'];
+        'hint'?: string;
         'array': true;
     }): Promise<false | null | Record<string, any>>;
     static one<T extends Mod>(db: lDb.Pool | lDb.Transaction, s: string | kebab.Json, opt?: {
@@ -265,6 +271,7 @@ export default class Mod {
         'index'?: string | string[];
         'select'?: string | string[];
         'by'?: [string | string[], 'DESC' | 'ASC'];
+        'hint'?: string;
         'array'?: false;
     }): Promise<false | null | (T & Record<string, any>)>;
     /**
@@ -279,6 +286,7 @@ export default class Mod {
         'pre'?: string;
         'index'?: string | string[];
         'select'?: string | string[];
+        'hint'?: string;
     }): Promise<false | null | Record<string, any>>;
     /**
      * --- 根据 where 条件获取主键值列表 ---
@@ -414,6 +422,30 @@ export default class Mod {
      * @param pre 前缀，仅与主表的 pre 不同时传入
      */
     crossJoin(f: string, s: kebab.Json, index?: string, pre?: string): this;
+    /**
+     * --- 设置 MySQL 优化器 Hint ---
+     * --- 内容会以 Optimizer Hint 注释语法注入到 SELECT 关键字后 ---
+     * --- 必须在查询入口调用之后、执行方法之前链式调用 ---
+     * @param h Hint 内容
+     * @example
+     * // 强制走指定索引（最常用）
+     * .hint("INDEX(`supply_date_0_0` `idx_supply_date_query`)")
+     *
+     * // 指定某表不用某索引
+     * .hint("NO_INDEX(`supply_date_0_0` `idx_old`)")
+     *
+     * // 指定 JOIN 顺序和索引
+     * .hint("JOIN_ORDER(`a` `b`) INDEX(`a` `idx_a`) INDEX(`b` `idx_b`)")
+     *
+     * // 指定 JOIN 中某表使用的索引
+     * .hint("JOIN_INDEX(`supply_date_0_0` `idx_supply_date_query`)")
+     *
+     * // 多表多索引组合
+     * .hint("INDEX(`t1` `idx_a`) JOIN_INDEX(`t2` `idx_b`)")
+     *
+     * // 官方文档: https://dev.mysql.com/doc/refman/8.0/en/optimizer-hints.html
+     */
+    hint(h: string): this;
     /**
      * --- 筛选器 ---
      * @param s 筛选条件数组或字符串

package/sys/mod.js

@@ -89,6 +89,10 @@ export default class Mod {
             'ctr': opt.ctr,
             'pre': opt.pre ?? this.constructor._$pre,
         });
+        /** --- 设置优化器 Hint --- */
+        if (opt.hint) {
+            this._sql.hint(opt.hint);
+        }
         if (opt.index) {
             this._index = typeof opt.index === 'string' ? [opt.index] : [...new Set(opt.index)];
         }
@@ -375,7 +379,8 @@ export default class Mod {
             'select': c,
             'index': opt.index,
             'alias': opt.alias,
-            'contain': opt.contain
+            'contain': opt.contain,
+            'hint': opt.hint,
         });
     }
     /**
@@ -393,6 +398,7 @@ export default class Mod {
             'index': opt.index,
             'contain': opt.contain,
             'alias': opt.alias,
+            'hint': opt.hint,
         });
     }
     /**
@@ -427,6 +433,7 @@ export default class Mod {
                     [opt.key ? this._$key : this._$primary]: val,
                 }],
             'index': opt.index,
+            'hint': opt.hint,
         }).first(opt.lock);
     }
     /**
@@ -444,6 +451,7 @@ export default class Mod {
                 'ctr': opt.ctr,
                 'pre': opt.pre,
                 'where': s,
+                'hint': opt.hint,
             });
             if (opt.by) {
                 o.by(opt.by[0], opt.by[1]);
@@ -459,6 +467,7 @@ export default class Mod {
                 'pre': opt.pre,
                 'where': s,
                 'index': item,
+                'hint': opt.hint,
             });
             if (opt.by) {
                 row.by(opt.by[0], opt.by[1]);
@@ -1307,6 +1316,33 @@ export default class Mod {
         this._sql.crossJoin(f, s, index ? '_' + index : '', pre);
         return this;
     }
+    /**
+     * --- 设置 MySQL 优化器 Hint ---
+     * --- 内容会以 Optimizer Hint 注释语法注入到 SELECT 关键字后 ---
+     * --- 必须在查询入口调用之后、执行方法之前链式调用 ---
+     * @param h Hint 内容
+     * @example
+     * // 强制走指定索引（最常用）
+     * .hint("INDEX(`supply_date_0_0` `idx_supply_date_query`)")
+     *
+     * // 指定某表不用某索引
+     * .hint("NO_INDEX(`supply_date_0_0` `idx_old`)")
+     *
+     * // 指定 JOIN 顺序和索引
+     * .hint("JOIN_ORDER(`a` `b`) INDEX(`a` `idx_a`) INDEX(`b` `idx_b`)")
+     *
+     * // 指定 JOIN 中某表使用的索引
+     * .hint("JOIN_INDEX(`supply_date_0_0` `idx_supply_date_query`)")
+     *
+     * // 多表多索引组合
+     * .hint("INDEX(`t1` `idx_a`) JOIN_INDEX(`t2` `idx_b`)")
+     *
+     * // 官方文档: https://dev.mysql.com/doc/refman/8.0/en/optimizer-hints.html
+     */
+    hint(h) {
+        this._sql.hint(h);
+        return this;
+    }
     /**
      * --- 筛选器 ---
      * @param s 筛选条件数组或字符串

package/sys/route.d.ts

@@ -77,6 +77,10 @@ export declare function getFormData(req: http2.Http2ServerRequest | http.Incomin
     'maxFileSize'?: number;
     /** --- 允许的文件扩展名（含点号），如 ['.jpg', '.png', '.pdf'] --- */
     'allowedExts'?: string[];
+    /** --- 单个字段（非文件）最大字节数，默认 1 MB --- */
+    'maxFieldSize'?: number;
+    /** --- 整体请求超时时间（毫秒），默认 5 分钟，设为 0 禁用超时 --- */
+    'timeout'?: number;
 }): Promise<{
     'post': Record<string, kebab.Json>;
     'files': Record<string, kebab.IPostFile | kebab.IPostFile[]>;

package/sys/route.js

@@ -935,6 +935,18 @@ export function getFormData(req, events = {}, limits = {}) {
         };
         /** --- 获取的 boundary 文本 --- */
         const boundary = ct.slice(clio + 9);
+        // --- 超时护盾：防止网络静默断开时 Promise 永不 resolve ---
+        /** --- 超时定时器 --- */
+        let timer;
+        /** --- 是否已经结束（防止重复 resolve） --- */
+        let finished = false;
+        /** --- 清理定时器 --- */
+        function clearTimer() {
+            if (timer) {
+                clearTimeout(timer);
+                timer = undefined;
+            }
+        }
         // 一下变量是相对于 data 事件的全局变量 ---
         /** --- 当前临时读入的还未处理的 buffer --- */
         let buffer = Buffer.from('');
@@ -978,6 +990,23 @@ export function getFormData(req, events = {}, limits = {}) {
                 }
             }
         }
+        // --- 启动超时定时器（在所有变量声明之后，确保回调闭包可引用） ---
+        const timeoutMs = limits.timeout ?? 300_000;
+        if (timeoutMs > 0) {
+            timer = setTimeout(() => {
+                if (finished) {
+                    return;
+                }
+                finished = true;
+                if ((state === EState.FILE) && ftmpName && ftmpStream) {
+                    ftmpStream.destroy();
+                }
+                lCore.debug('[ROUTE][GETFORMDATA] formdata request timeout');
+                lCore.log({}, '[ROUTE][GETFORMDATA] formdata request timeout after ' + timeoutMs + 'ms', '-error');
+                cleanupFiles();
+                resolve(false);
+            }, timeoutMs);
+        }
         /** --- 拒绝当前文件：销毁流、删临时文件、标记 rejected --- */
         function rejectFile() {
             rejected = true;
@@ -988,6 +1017,11 @@ export function getFormData(req, events = {}, limits = {}) {
         }
         /** --- 最终输出 --- */
         function finalize() {
+            if (finished) {
+                return;
+            }
+            finished = true;
+            clearTimer();
             if (rejected) {
                 cleanupFiles();
                 resolve(false);
@@ -1064,6 +1098,12 @@ export function getFormData(req, events = {}, limits = {}) {
                         // --- POST 模式 ---
                         const io = buffer.indexOf('\r\n--' + boundary);
                         if (io === -1) {
+                            // --- 检查字段大小限制，防止畸形数据导致 buffer 无限增长 ---
+                            const maxField = limits.maxFieldSize ?? 1_048_576;
+                            if (buffer.length > maxField + boundary.length + 4) {
+                                rejected = true;
+                                return;
+                            }
                             return;
                         }
                         // --- 找到结束标语，写入 POST ---
@@ -1178,6 +1218,11 @@ export function getFormData(req, events = {}, limits = {}) {
             }
         });
         req.on('error', function (e) {
+            if (finished) {
+                return;
+            }
+            finished = true;
+            clearTimer();
             if ((state === EState.FILE) && ftmpName) {
                 ftmpStream.destroy();
             }
@@ -1186,8 +1231,26 @@ export function getFormData(req, events = {}, limits = {}) {
             cleanupFiles();
             resolve(false);
         });
+        // --- 监听连接关闭（HTTP/2 RST_STREAM、代理断连、或用户主动中断上传等场景） ---
+        req.on('close', function () {
+            if (finished) {
+                return;
+            }
+            // --- 若数据未读完且连接已关闭，视为传输中断（多数是用户主动取消，无需记录错误） ---
+            if (!readEnd && writeFileLength > 0) {
+                finished = true;
+                clearTimer();
+                if ((state === EState.FILE) && ftmpName && ftmpStream) {
+                    ftmpStream.destroy();
+                }
+                lCore.debug('[ROUTE][GETFORMDATA] connection closed before formdata complete');
+                cleanupFiles();
+                resolve(false);
+            }
+        });
         req.on('end', function () {
             readEnd = true;
+            clearTimer();
             // --- 被拒绝则清理文件并 resolve(false) ---
             if (rejected) {
                 finalize();

package/www/example/ctr/test.js

@@ -213,6 +213,7 @@ export default class extends sCtr.Ctr {
             `<br><a href="${this._config.const.urlBase}test/sql?type=having">View "test/sql?type=having"</a> <a href="${this._config.const.urlBase}test/sql?type=having&s=pgsql">pgsql</a>`,
             `<br><a href="${this._config.const.urlBase}test/sql?type=by">View "test/sql?type=by"</a> <a href="${this._config.const.urlBase}test/sql?type=by&s=pgsql">pgsql</a>`,
             `<br><a href="${this._config.const.urlBase}test/sql?type=field">View "test/sql?type=field"</a> <a href="${this._config.const.urlBase}test/sql?type=field&s=pgsql">pgsql</a>`,
+            `<br><a href="${this._config.const.urlBase}test/sql?type=hint">View "test/sql?type=hint"</a>`,
             '<br><br><b>Consistent:</b>',
             `<br><br><a href="${this._config.const.urlBase}test/consistent-hash">View "test/consistent-hash"</a>`,
             `<br><a href="${this._config.const.urlBase}test/consistent-distributed">View "test/consistent-distributed"</a>`,
@@ -3064,6 +3065,21 @@ Result:<pre id="result">Nothing.</pre>`);
                 echo.push(`<pre>sql.field('*');</pre>` + sql.field('*'));
                 break;
             }
+            case 'hint': {
+                let s = sql.hint('INDEX(`supply_date_0_0` `idx_supply_date_query`)').select('*', 'supply_date_0_0').getSql();
+                let sd = sql.getData();
+                echo.push(`<pre>sql.hint('INDEX(\`supply_date_0_0\` \`idx_supply_date_query\`)').select('*', 'supply_date_0_0');</pre>
+<b>getSql() :</b> ${s}<br>
+<b>getData():</b> <pre>${JSON.stringify(sd, undefined, 4)}</pre>
+<b>format() :</b> ${sql.format(s, sd)}<hr>`);
+                s = sql.hint('INDEX(`supply_date_0_0` `idx_supply_date_query`) NO_INDEX(`supply_date_0_0` `idx_old`)').select('*', 'supply_date_0_0').getSql();
+                sd = sql.getData();
+                echo.push(`<pre>sql.hint('INDEX(\`supply_date_0_0\` \`idx_supply_date_query\`) NO_INDEX(\`supply_date_0_0\` \`idx_old\`)').select('*', 'supply_date_0_0');</pre>
+<b>getSql() :</b> ${s}<br>
+<b>getData():</b> <pre>${JSON.stringify(sd, undefined, 4)}</pre>
+<b>format() :</b> ${sql.format(s, sd)}`);
+                break;
+            }
         }
         return echo.join('') + '<br><br>' + this._getEnd();
     }