@maiyunnet/kebab 9.14.0 → 9.14.1

package/index.d.ts

@@ -5,7 +5,7 @@
  * --- 本文件用来定义每个目录实体地址的常量 ---
  */
 /** --- 当前系统版本号 --- */
-export declare const VER = "9.14.0";
+export declare const VER = "9.14.1";
 /** --- 框架根目录，以 / 结尾  --- */
 export declare const ROOT_PATH: string;
 /** --- 框架的 LIB，以 / 结尾 --- */

package/index.js

@@ -6,7 +6,7 @@
  * --- 本文件用来定义每个目录实体地址的常量 ---
  */
 /** --- 当前系统版本号 --- */
-export const VER = '9.14.0';
+export const VER = '9.14.1';
 // --- 服务端用的路径 ---
 const imu = decodeURIComponent(import.meta.url).replace('file://', '').replace(/^\/(\w:)/, '$1');
 /** --- /xxx/xxx --- */

package/lib/core.js

@@ -307,10 +307,11 @@ export function muid(ctr, opt = {}) {
 export function ip(ctr, req) {
     const headers = ctr instanceof sCtr.Ctr ? ctr.getPrototype('_headers') : ctr;
     if (typeof headers['cf-connecting-ip'] === 'string') {
-        return headers['cf-connecting-ip'];
+        return normalizeIP(headers['cf-connecting-ip']);
     }
     else if (typeof headers['x-forwarded-for'] === 'string') {
-        return headers['x-forwarded-for'];
+        // --- X-Forwarded-For 可能为逗号分隔的多个 IP，取第一个即客户端 IP ---
+        return normalizeIP(headers['x-forwarded-for'].split(',')[0].trim());
     }
     else {
         if (!req) {
@@ -321,21 +322,37 @@ export function ip(ctr, req) {
                 return '';
             }
         }
-        return req.socket.remoteAddress ?? '';
+        return normalizeIP(req.socket.remoteAddress ?? '');
     }
 }
 /** --- 获取 CF 和 X 的 IP --- */
 export function ips(ctr) {
     const headers = ctr instanceof sCtr.Ctr ? ctr.getPrototype('_headers') : ctr;
     return {
-        'cf': typeof headers['cf-connecting-ip'] === 'string' ? headers['cf-connecting-ip'] : '',
-        'x': typeof headers['x-forwarded-for'] === 'string' ? headers['x-forwarded-for'] : ''
+        'cf': typeof headers['cf-connecting-ip'] === 'string' ? normalizeIP(headers['cf-connecting-ip']) : '',
+        'x': typeof headers['x-forwarded-for'] === 'string' ? normalizeIP(headers['x-forwarded-for'].split(',')[0].trim()) : ''
     };
 }
 /** --- 使用 X-Forwarded-For 的 CDN 厂商 --- */
 export const REAL_IP_X = 'x-forwarded-for';
 /** --- 使用的是 Cloudflare --- */
 export const REAL_IP_CF = 'cf-connecting-ip';
+/**
+ * --- 规范化 IP 地址 ---
+ * --- 将 IPv4-mapped IPv6（如 ::ffff:127.0.0.1）转换为纯 IPv4，原生 IPv6 保持不变 ---
+ * @param ip 原始 IP 地址
+ */
+function normalizeIP(ip) {
+    if (!ip) {
+        return '';
+    }
+    const value = ip.trim();
+    const mapped = /^::ffff:(\d{1,3}(?:\.\d{1,3}){3})$/i.exec(value);
+    if (mapped) {
+        return mapped[1];
+    }
+    return value;
+}
 /**
  * --- 获取直连 IP（安全 IP） ---
  * @param ctr
@@ -346,11 +363,11 @@ export function realIP(ctr, name = '') {
     if (name !== '') {
         const value = headers[name];
         if (typeof value === 'string') {
-            return value;
+            return normalizeIP(value);
         }
     }
     const req = ctr.getPrototype('_req');
-    return req.socket.remoteAddress ?? '';
+    return normalizeIP(req.socket.remoteAddress ?? '');
 }
 /**
  * --- 间隔一段时间 ---

package/lib/sql.d.ts

@@ -42,6 +42,8 @@ export declare class Sql {
     private _placeholderCounter;
     /** --- 是否忽略错误 --- */
     private _ignore;
+    /** --- MySQL 优化器 Hint，如 INDEX(table idx) --- */
+    private _hint;
     constructor(opt: {
         'service': ESERVICE;
         'ctr'?: ctr.Ctr;
@@ -51,6 +53,30 @@ export declare class Sql {
         'sql'?: string[];
         'alias'?: string[];
     });
+    /**
+     * --- 设置 MySQL 优化器 Hint ---
+     * --- 会以 Optimizer Hint 注释语法注入到 SELECT 关键字后 ---
+     * --- 传入 hint 内容即可，无需包裹注释符号 ---
+     * @param h Hint 内容
+     * @example
+     * // --- 强制走指定索引（最常用） ---
+     * INDEX(`supply_date_0_0` `idx_supply_date_query`)
+     *
+     * // --- 指定某表不用某索引 ---
+     * NO_INDEX(`supply_date_0_0` `idx_old`)
+     *
+     * // --- 指定 JOIN 顺序和索引 ---
+     * JOIN_ORDER(`a` `b`) INDEX(`a` `idx_a`) INDEX(`b` `idx_b`)
+     *
+     * // --- 指定 JOIN 中某表使用的索引 ---
+     * JOIN_INDEX(`supply_date_0_0` `idx_supply_date_query`)
+     *
+     * // --- 多表多索引组合 ---
+     * 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 table 表名

package/lib/sql.js

@@ -45,6 +45,8 @@ export class Sql {
     _placeholderCounter = 1;
     /** --- 是否忽略错误 --- */
     _ignore = false;
+    /** --- MySQL 优化器 Hint，如 INDEX(table idx) --- */
+    _hint = '';
     // --- 实例化 ---
     constructor(opt) {
         this._ctr = opt.ctr;
@@ -60,6 +62,33 @@ export class Sql {
             this._alias = opt.alias;
         }
     }
+    /**
+     * --- 设置 MySQL 优化器 Hint ---
+     * --- 会以 Optimizer Hint 注释语法注入到 SELECT 关键字后 ---
+     * --- 传入 hint 内容即可，无需包裹注释符号 ---
+     * @param h Hint 内容
+     * @example
+     * // --- 强制走指定索引（最常用） ---
+     * INDEX(`supply_date_0_0` `idx_supply_date_query`)
+     *
+     * // --- 指定某表不用某索引 ---
+     * NO_INDEX(`supply_date_0_0` `idx_old`)
+     *
+     * // --- 指定 JOIN 顺序和索引 ---
+     * JOIN_ORDER(`a` `b`) INDEX(`a` `idx_a`) INDEX(`b` `idx_b`)
+     *
+     * // --- 指定 JOIN 中某表使用的索引 ---
+     * JOIN_INDEX(`supply_date_0_0` `idx_supply_date_query`)
+     *
+     * // --- 多表多索引组合 ---
+     * INDEX(`t1` `idx_a`) JOIN_INDEX(`t2` `idx_b`)
+     *
+     * // --- 官方文档: https://dev.mysql.com/doc/refman/8.0/en/optimizer-hints.html ---
+     */
+    hint(h) {
+        this._hint = h;
+        return this;
+    }
     // --- 前导 ---
     /**
      * --- 插入数据前导 ---
@@ -880,7 +909,7 @@ export class Sql {
             'data': data,
             'sql': sql,
             'alias': lCore.clone(this._alias),
-        });
+        }).hint(this._hint);
     }
     // --- 操作 ---
     /**
@@ -888,6 +917,10 @@ export class Sql {
      */
     getSql() {
         let sql = this._sql.join('');
+        // --- 注入优化器 Hint 到 SELECT 关键字后 ---
+        if (this._hint && !sql.includes('/*+')) {
+            sql = sql.replace(/^SELECT /i, `SELECT /*+ ${this._hint} */ `);
+        }
         if (this._pre) {
             return this._alias.reduce((result, item) => {
                 if (this._service === ESERVICE.MYSQL) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maiyunnet/kebab",
-  "version": "9.14.0",
+  "version": "9.14.1",
   "description": "Simple, easy-to-use, and fully-featured Node.js framework that is ready-to-use out of the box.",
   "type": "module",
   "keywords": [

package/sys/ctr.d.ts

@@ -342,5 +342,9 @@ export declare class Ctr {
         'maxFileSize'?: number;
         /** --- 允许的文件扩展名（含点号），如 ['.jpg', '.png', '.pdf'] --- */
         'allowedExts'?: string[];
+        /** --- 单个字段（非文件）最大字节数，默认 1 MB --- */
+        'maxFieldSize'?: number;
+        /** --- 整体请求超时时间（毫秒），默认 5 分钟，设为 0 禁用超时 --- */
+        'timeout'?: number;
     }): Promise<boolean>;
 }

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;
     });
@@ -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();
     }