@maiyunnet/kebab 9.20.1 → 9.21.1

package/index.d.ts

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

package/index.js

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

package/lib/core.d.ts

@@ -331,6 +331,65 @@ export declare function getLog(opt: {
     'list': string[][] | kebab.Json[];
     'total': number;
 } | false>;
+/** --- 已保存监控事件的简短摘要，path 相对于 log/monitor/ --- */
+export interface IMonitorEventSummary {
+    'path': string;
+    'pid': number;
+    'time': number;
+    'source': 'main' | 'watchdog';
+    'status': string;
+    'reasons': string[];
+}
+/** --- 监控文件元数据；复杂格式或超过 1 MiB 的文件不提供预览 --- */
+export interface IMonitorFile {
+    'path': string;
+    'name': string;
+    'size': number;
+    /** --- 最后修改时间，单位 ms --- */
+    'mtime': number;
+    'preview': 'json' | 'text' | null;
+}
+/** --- 事件原始数据与可读取的文件；data 为 null 时可下载原始记录复盘 --- */
+export interface IMonitorEvent {
+    'summary': IMonitorEventSummary;
+    'data': Record<string, unknown> | null;
+    'recordStatus': 'loaded' | 'missing' | 'too-large' | 'invalid' | 'unreadable';
+    'files': IMonitorFile[];
+}
+/**
+ * --- 获取某天已保存的监控事件，按目录时间倒序分页 ---
+ * @param opt path 为 YYYY/MM/DD，默认目标服务器的当天；offset 默认 0，limit 默认 20、最多 100
+ * @returns 事件列表和总数；无事件时返回空列表，参数、配置或读取错误时返回 false
+ */
+export declare function getMonitorEvents(opt?: {
+    'path'?: string;
+    'offset'?: number;
+    'limit'?: number;
+    /** --- 与 getLog 相同，使用目标服务器的 RPC 端口和密钥 --- */
+    'host'?: string;
+}): Promise<{
+    'list': IMonitorEventSummary[];
+    'total': number;
+} | false>;
+/**
+ * --- 读取事件详情和文件清单；只解析事件记录，不解析 Profile 或堆快照 ---
+ * @param opt path 使用 getMonitorEvents 返回的事件路径；host 默认本机
+ * @returns 事件详情；不存在时返回 null，参数、配置或读取错误时返回 false
+ */
+export declare function getMonitorEvent(opt: {
+    'path': string;
+    'host'?: string;
+}): Promise<IMonitorEvent | null | false>;
+/**
+ * --- 获取监控原始文件的响应，可使用 getStream() 下载；小文件可用 getText()/getJson() 预览 ---
+ * @param opt path 使用事件 files 中的文件路径；preview=true 只允许 1 MiB 内的 JSON/调用栈文本；host 默认本机
+ * @returns 文件响应；不存在时返回 null，参数、预览限制、配置或读取错误时返回 false；流消费或销毁由调用方负责
+ */
+export declare function getMonitorFile(opt: {
+    'path': string;
+    'preview'?: boolean;
+    'host'?: string;
+}): Promise<lUndiciResponse.Response | null | false>;
 /**
  * --- 获取目录内文件/文件夹列表 ---
  * @param opt 参数

package/lib/core.js

@@ -1182,6 +1182,87 @@ export async function getLog(opt) {
         'total': res.total,
     };
 }
+/**
+ * --- 通过 master RPC 读取已保存的监控数据，不依赖目标 HTTP 子进程 ---
+ * @param action 要读取的监控资源
+ * @param opt 读取参数，host 默认本机
+ * @returns 响应对象；配置或网络错误时返回 false
+ */
+async function requestMonitor(action, opt) {
+    if (!Number.isInteger(globalConfig.rpcPort) || typeof globalConfig.rpcSecret !== 'string') {
+        return false;
+    }
+    const command = lCrypto.aesEncrypt(lText.stringifyJson({
+        action, 'time': lTime.stamp(), 'path': opt.path, 'offset': opt.offset,
+        'limit': opt.limit, 'preview': opt.preview,
+    }), globalConfig.rpcSecret);
+    const res = await lUndici.get(`http://${opt.host ?? '127.0.0.1'}:${globalConfig.rpcPort}/${command}`, {
+        'timeout': action === 'monitor-file' ? 300 : 5,
+        'follow': 0,
+    });
+    if (res.error || !res.headers) {
+        await res.getRawStream()?.dump({ 'limit': 4096 });
+        return false;
+    }
+    return res;
+}
+/**
+ * --- 获取某天已保存的监控事件，按目录时间倒序分页 ---
+ * @param opt path 为 YYYY/MM/DD，默认目标服务器的当天；offset 默认 0，limit 默认 20、最多 100
+ * @returns 事件列表和总数；无事件时返回空列表，参数、配置或读取错误时返回 false
+ */
+export async function getMonitorEvents(opt = {}) {
+    const res = await requestMonitor('monitor-events', opt);
+    if (res === false) {
+        return false;
+    }
+    const text = await res.getText();
+    if (text === null) {
+        return false;
+    }
+    const result = lText.parseJson(text);
+    if (!result || result.result !== 1 || !Array.isArray(result.list) || !Number.isSafeInteger(result.total)) {
+        return false;
+    }
+    return { 'list': result.list, 'total': result.total };
+}
+/**
+ * --- 读取事件详情和文件清单；只解析事件记录，不解析 Profile 或堆快照 ---
+ * @param opt path 使用 getMonitorEvents 返回的事件路径；host 默认本机
+ * @returns 事件详情；不存在时返回 null，参数、配置或读取错误时返回 false
+ */
+export async function getMonitorEvent(opt) {
+    const res = await requestMonitor('monitor-event', opt);
+    if (res === false) {
+        return false;
+    }
+    const text = await res.getText();
+    if (text === null) {
+        return false;
+    }
+    const result = lText.parseJson(text);
+    if (!result || result.result !== 1 || result.data === undefined) {
+        return false;
+    }
+    return result.data;
+}
+/**
+ * --- 获取监控原始文件的响应，可使用 getStream() 下载；小文件可用 getText()/getJson() 预览 ---
+ * @param opt path 使用事件 files 中的文件路径；preview=true 只允许 1 MiB 内的 JSON/调用栈文本；host 默认本机
+ * @returns 文件响应；不存在时返回 null，参数、预览限制、配置或读取错误时返回 false；流消费或销毁由调用方负责
+ */
+export async function getMonitorFile(opt) {
+    const res = await requestMonitor('monitor-file', opt);
+    if (res === false) {
+        return false;
+    }
+    if (res.headers?.['http-code'] === 200 && res.headers['x-kebab-monitor-file'] === '1') {
+        return res;
+    }
+    // --- 有界丢弃错误响应；直接 destroy 未消费的 Undici 流会产生未处理的 AbortError ---
+    await res.getRawStream()?.dump({ 'limit': 4096 });
+    return res.headers?.['http-code'] === 404 ? null : false;
+}
 /**
  * --- 获取目录内文件/文件夹列表 ---
  * @param opt 参数

package/lib/fs.d.ts

@@ -74,6 +74,8 @@ export declare function rmdir(path: string): Promise<boolean>;
  * --- Danger 危险：危险函数，尽量不要使用 ---
  * --- This is a danger function, please don't use it ---
  * --- 删除一个非空目录 ---
+ * @param path 目录路径，不递归读取符号链接指向的目录
+ * @returns 删除成功或根路径不是目录返回 true，删除失败返回 false
  */
 export declare function rmdirDeep(path: string): Promise<boolean>;
 /**
@@ -140,10 +142,19 @@ export declare function createWriteStream(path: string, options?: BufferEncoding
     'start'?: number;
 }): fs.WriteStream;
 /**
- * --- 读取文件并输出到 http 的 response ---
+ * --- 读取文件并输出到 http 的 response，支持 GET 字节范围与条件请求 ---
+ *
+ * Range 支持 start-end、start-、-length 及最多 16 段，请求头上限 8 KiB；相邻和重叠区间合并。
+ * 有效区间返回 206，全部越界或区间过多返回 416；无效语法、未知单位和空文件忽略 Range。
+ * 部分响应按原始文件字节流式输出，不进行动态压缩。If-Range 日期须匹配 Last-Modified，
+ * 且文件不启用动态压缩、修改时间早于当前响应所在秒，否则退回完整响应；
+ * 文件元数据生成的 ETag 为弱校验值，不接受其作为 If-Range 的强校验值。
+ * HEAD 忽略 Range 且不输出响应体。
+ *
  * @param path 文件绝对路径
  * @param req http 请求对象
  * @param res http 响应对象
  * @param stat 文件的 stat（如果有）
+ * @returns 输出完成或连接终止后无返回值
  */
 export declare function readToResponse(path: string, req: http2.Http2ServerRequest | http.IncomingMessage, res: http2.Http2ServerResponse | http.ServerResponse, stat?: fs.Stats | null): Promise<void>;