@maiyunnet/kebab 9.20.0 → 9.21.0

package/doc/kebab-rag.md

@@ -1589,7 +1589,7 @@ index/variables/VER.md
 
 # Variable: VER
 
-> `const` **VER**: `"9.20.0"` = `'9.20.0'`
+> `const` **VER**: `"9.21.0"` = `'9.21.0'`
 
 Defined in: [index.ts:10](https://github.com/maiyunnet/kebab/blob/master/index.ts#L10)
 
@@ -118073,7 +118073,7 @@ lib/fs/functions/chmod.md
 
 > **chmod**(`path`, `mod`): `Promise`\<`boolean`\>
 
-Defined in: [lib/fs.ts:277](https://github.com/maiyunnet/kebab/blob/master/lib/fs.ts#L277)
+Defined in: [lib/fs.ts:224](https://github.com/maiyunnet/kebab/blob/master/lib/fs.ts#L224)
 
 修改权限
 
@@ -118108,7 +118108,7 @@ lib/fs/functions/copyFile.md
 
 > **copyFile**(`src`, `dest`): `Promise`\<`boolean`\>
 
-Defined in: [lib/fs.ts:385](https://github.com/maiyunnet/kebab/blob/master/lib/fs.ts#L385)
+Defined in: [lib/fs.ts:316](https://github.com/maiyunnet/kebab/blob/master/lib/fs.ts#L316)
 
 复制文件
 
@@ -118143,7 +118143,7 @@ lib/fs/functions/copyFolder.md
 
 > **copyFolder**(`from`, `to`, `ignore?`): `Promise`\<`number`\>
 
-Defined in: [lib/fs.ts:340](https://github.com/maiyunnet/kebab/blob/master/lib/fs.ts#L340)
+Defined in: [lib/fs.ts:273](https://github.com/maiyunnet/kebab/blob/master/lib/fs.ts#L273)
 
 复制文件夹里的内容到另一个地方，失败不会回滚
 
@@ -118184,7 +118184,7 @@ lib/fs/functions/createReadStream.md
 
 > **createReadStream**(`path`, `options?`): `ReadStream`
 
-Defined in: [lib/fs.ts:400](https://github.com/maiyunnet/kebab/blob/master/lib/fs.ts#L400)
+Defined in: [lib/fs.ts:331](https://github.com/maiyunnet/kebab/blob/master/lib/fs.ts#L331)
 
 创建读取文件的流
 
@@ -118219,7 +118219,7 @@ lib/fs/functions/createWriteStream.md
 
 > **createWriteStream**(`path`, `options?`): `WriteStream`
 
-Defined in: [lib/fs.ts:447](https://github.com/maiyunnet/kebab/blob/master/lib/fs.ts#L447)
+Defined in: [lib/fs.ts:364](https://github.com/maiyunnet/kebab/blob/master/lib/fs.ts#L364)
 
 创建写入文件的流
 
@@ -118252,7 +118252,7 @@ lib/fs/functions/getContent.md
 
 # Function: getContent()
 
-读取完整文件或一段
+读取完整文件或一段，区间包含首尾字节
 
 ## Param
 
@@ -118270,7 +118270,7 @@ lib/fs/functions/getContent.md
 
 > **getContent**(`path`, `options?`): `Promise`\<`Buffer`\<`ArrayBufferLike`\> \| `null`\>
 
-Defined in: [lib/fs.ts:14](https://github.com/maiyunnet/kebab/blob/master/lib/fs.ts#L14)
+Defined in: [lib/fs.ts:16](https://github.com/maiyunnet/kebab/blob/master/lib/fs.ts#L16)
 
 ### Parameters
 
@@ -118296,7 +118296,7 @@ Defined in: [lib/fs.ts:14](https://github.com/maiyunnet/kebab/blob/master/lib/fs
 
 > **getContent**(`path`, `options`): `Promise`\<`string` \| `null`\>
 
-Defined in: [lib/fs.ts:18](https://github.com/maiyunnet/kebab/blob/master/lib/fs.ts#L18)
+Defined in: [lib/fs.ts:20](https://github.com/maiyunnet/kebab/blob/master/lib/fs.ts#L20)
 
 ### Parameters
 
@@ -118325,7 +118325,7 @@ lib/fs/functions/isDir.md
 
 > **isDir**(`path`): `Promise`\<`false` \| `Stats`\>
 
-Defined in: [lib/fs.ts:181](https://github.com/maiyunnet/kebab/blob/master/lib/fs.ts#L181)
+Defined in: [lib/fs.ts:144](https://github.com/maiyunnet/kebab/blob/master/lib/fs.ts#L144)
 
 判断是否是目录或目录是否存在，是的话返回 stats
 
@@ -118354,7 +118354,7 @@ lib/fs/functions/isFile.md
 
 > **isFile**(`path`): `Promise`\<`false` \| `Stats`\>
 
-Defined in: [lib/fs.ts:193](https://github.com/maiyunnet/kebab/blob/master/lib/fs.ts#L193)
+Defined in: [lib/fs.ts:153](https://github.com/maiyunnet/kebab/blob/master/lib/fs.ts#L153)
 
 判断是否是文件或文件是否存在，是的话返回 stats
 
@@ -118383,7 +118383,7 @@ lib/fs/functions/mkdir.md
 
 > **mkdir**(`path`, `mode?`): `Promise`\<`boolean`\>
 
-Defined in: [lib/fs.ts:206](https://github.com/maiyunnet/kebab/blob/master/lib/fs.ts#L206)
+Defined in: [lib/fs.ts:163](https://github.com/maiyunnet/kebab/blob/master/lib/fs.ts#L163)
 
 深度创建目录，如果最末目录存在，则自动创建成功
 
@@ -118418,7 +118418,7 @@ lib/fs/functions/pipe.md
 
 > **pipe**(`path`, `destination`, `options?`): `Promise`\<`boolean`\>
 
-Defined in: [lib/fs.ts:430](https://github.com/maiyunnet/kebab/blob/master/lib/fs.ts#L430)
+Defined in: [lib/fs.ts:347](https://github.com/maiyunnet/kebab/blob/master/lib/fs.ts#L347)
 
 读取文件写入到流，并等待写入完成
 
@@ -118461,7 +118461,7 @@ lib/fs/functions/putContent.md
 
 > **putContent**(`path`, `data`, `options?`): `Promise`\<`boolean`\>
 
-Defined in: [lib/fs.ts:92](https://github.com/maiyunnet/kebab/blob/master/lib/fs.ts#L92)
+Defined in: [lib/fs.ts:59](https://github.com/maiyunnet/kebab/blob/master/lib/fs.ts#L59)
 
 写入文件内容
 
@@ -118512,7 +118512,7 @@ lib/fs/functions/readDir.md
 
 > **readDir**(`path`, `encoding?`): `Promise`\<`Dirent`\<`string`\>[]\>
 
-Defined in: [lib/fs.ts:306](https://github.com/maiyunnet/kebab/blob/master/lib/fs.ts#L306)
+Defined in: [lib/fs.ts:253](https://github.com/maiyunnet/kebab/blob/master/lib/fs.ts#L253)
 
 获取文件夹下文件列表
 
@@ -118545,7 +118545,7 @@ lib/fs/functions/readLink.md
 
 > **readLink**(`path`, `encoding?`): `Promise`\<`string` \| `null`\>
 
-Defined in: [lib/fs.ts:114](https://github.com/maiyunnet/kebab/blob/master/lib/fs.ts#L114)
+Defined in: [lib/fs.ts:81](https://github.com/maiyunnet/kebab/blob/master/lib/fs.ts#L81)
 
 读取链接的 target
 
@@ -118580,9 +118580,16 @@ lib/fs/functions/readToResponse.md
 
 > **readToResponse**(`path`, `req`, `res`, `stat?`): `Promise`\<`void`\>
 
-Defined in: [lib/fs.ts:478](https://github.com/maiyunnet/kebab/blob/master/lib/fs.ts#L478)
+Defined in: [lib/fs.ts:480](https://github.com/maiyunnet/kebab/blob/master/lib/fs.ts#L480)
+
+读取文件并输出到 http 的 response，支持 GET 字节范围与条件请求
 
-读取文件并输出到 http 的 response
+Range 支持 start-end、start-、-length 及最多 16 段，请求头上限 8 KiB；相邻和重叠区间合并。
+有效区间返回 206，全部越界或区间过多返回 416；无效语法、未知单位和空文件忽略 Range。
+部分响应按原始文件字节流式输出，不进行动态压缩。If-Range 日期须匹配 Last-Modified，
+且文件不启用动态压缩、修改时间早于当前响应所在秒，否则退回完整响应；
+文件元数据生成的 ETag 为弱校验值，不接受其作为 If-Range 的强校验值。
+HEAD 忽略 Range 且不输出响应体。
 
 ## Parameters
 
@@ -118614,6 +118621,8 @@ http 响应对象
 
 `Promise`\<`void`\>
 
+输出完成或连接终止后无返回值
+
 lib/fs/functions/rename.md
 ---
 
@@ -118627,7 +118636,7 @@ lib/fs/functions/rename.md
 
 > **rename**(`oldPath`, `newPath`): `Promise`\<`boolean`\>
 
-Defined in: [lib/fs.ts:292](https://github.com/maiyunnet/kebab/blob/master/lib/fs.ts#L292)
+Defined in: [lib/fs.ts:239](https://github.com/maiyunnet/kebab/blob/master/lib/fs.ts#L239)
 
 重命名/移动文件文件夹
 
@@ -118662,7 +118671,7 @@ lib/fs/functions/rmdirDeep.md
 
 > **rmdirDeep**(`path`): `Promise`\<`boolean`\>
 
-Defined in: [lib/fs.ts:245](https://github.com/maiyunnet/kebab/blob/master/lib/fs.ts#L245)
+Defined in: [lib/fs.ts:200](https://github.com/maiyunnet/kebab/blob/master/lib/fs.ts#L200)
 
 Danger 危险：危险函数，尽量不要使用
 This is a danger function, please don't use it
@@ -118674,10 +118683,14 @@ This is a danger function, please don't use it
 
 `string`
 
+目录路径，不递归读取符号链接指向的目录
+
 ## Returns
 
 `Promise`\<`boolean`\>
 
+删除成功或根路径不是目录返回 true，删除失败返回 false
+
 lib/fs/functions/rmdir.md
 ---
 
@@ -118691,7 +118704,7 @@ lib/fs/functions/rmdir.md
 
 > **rmdir**(`path`): `Promise`\<`boolean`\>
 
-Defined in: [lib/fs.ts:227](https://github.com/maiyunnet/kebab/blob/master/lib/fs.ts#L227)
+Defined in: [lib/fs.ts:180](https://github.com/maiyunnet/kebab/blob/master/lib/fs.ts#L180)
 
 删除空目录
 
@@ -118720,7 +118733,7 @@ lib/fs/functions/stats.md
 
 > **stats**(`path`): `Promise`\<`Stats` \| `null`\>
 
-Defined in: [lib/fs.ts:168](https://github.com/maiyunnet/kebab/blob/master/lib/fs.ts#L168)
+Defined in: [lib/fs.ts:131](https://github.com/maiyunnet/kebab/blob/master/lib/fs.ts#L131)
 
 获取对象是否存在，存在则返回 stats 对象，否则返回 null
 
@@ -118749,7 +118762,7 @@ lib/fs/functions/symlink.md
 
 > **symlink**(`filePath`, `linkPath`, `type?`): `Promise`\<`boolean`\>
 
-Defined in: [lib/fs.ts:131](https://github.com/maiyunnet/kebab/blob/master/lib/fs.ts#L131)
+Defined in: [lib/fs.ts:98](https://github.com/maiyunnet/kebab/blob/master/lib/fs.ts#L98)
 
 把源文件创建一个 link
 
@@ -118790,7 +118803,7 @@ lib/fs/functions/unlink.md
 
 > **unlink**(`path`): `Promise`\<`boolean`\>
 
-Defined in: [lib/fs.ts:145](https://github.com/maiyunnet/kebab/blob/master/lib/fs.ts#L145)
+Defined in: [lib/fs.ts:112](https://github.com/maiyunnet/kebab/blob/master/lib/fs.ts#L112)
 
 删除一个文件
 
@@ -122018,7 +122031,7 @@ Defined in: [lib/s3.ts:88](https://github.com/maiyunnet/kebab/blob/master/lib/s3
 
 > **deleteObject**(`key`, `bucket?`): `Promise`\<`boolean`\>
 
-Defined in: [lib/s3.ts:279](https://github.com/maiyunnet/kebab/blob/master/lib/s3.ts#L279)
+Defined in: [lib/s3.ts:367](https://github.com/maiyunnet/kebab/blob/master/lib/s3.ts#L367)
 
 删除对象
 
@@ -122046,7 +122059,7 @@ bucket 名
 
 > **deleteObjects**(`keys`, `bucket?`): `Promise`\<`boolean`\>
 
-Defined in: [lib/s3.ts:299](https://github.com/maiyunnet/kebab/blob/master/lib/s3.ts#L299)
+Defined in: [lib/s3.ts:387](https://github.com/maiyunnet/kebab/blob/master/lib/s3.ts#L387)
 
 批量删除对象
 
@@ -122074,7 +122087,7 @@ bucket 名
 
 > **destroy**(): `void`
 
-Defined in: [lib/s3.ts:341](https://github.com/maiyunnet/kebab/blob/master/lib/s3.ts#L341)
+Defined in: [lib/s3.ts:429](https://github.com/maiyunnet/kebab/blob/master/lib/s3.ts#L429)
 
 销毁连接，释放资源
 一般会自动垃圾回收，但高频接口也可主动调用
@@ -122089,7 +122102,7 @@ Defined in: [lib/s3.ts:341](https://github.com/maiyunnet/kebab/blob/master/lib/s
 
 > **getObject**(`key`, `bucket?`): `Promise`\<`false` \| `Readable` & `SdkStreamMixin` \| `Blob` & `SdkStreamMixin` \| `ReadableStream`\<`any`\> & `SdkStreamMixin` \| `undefined`\>
 
-Defined in: [lib/s3.ts:235](https://github.com/maiyunnet/kebab/blob/master/lib/s3.ts#L235)
+Defined in: [lib/s3.ts:323](https://github.com/maiyunnet/kebab/blob/master/lib/s3.ts#L323)
 
 获取对象流，可通过流获取 buffer 或 text
 
@@ -122117,7 +122130,7 @@ bucket 名
 
 > **getObjectBuffer**(`key`, `bucket?`): `Promise`\<`false` \| `Buffer`\<`ArrayBufferLike`\>\>
 
-Defined in: [lib/s3.ts:256](https://github.com/maiyunnet/kebab/blob/master/lib/s3.ts#L256)
+Defined in: [lib/s3.ts:344](https://github.com/maiyunnet/kebab/blob/master/lib/s3.ts#L344)
 
 获取对象 Buffer
 
@@ -122147,7 +122160,7 @@ bucket 名
 
 > **headObject**(`key`, `bucket?`): `Promise`\<`false` \| `HeadObjectCommandOutput`\>
 
-Defined in: [lib/s3.ts:321](https://github.com/maiyunnet/kebab/blob/master/lib/s3.ts#L321)
+Defined in: [lib/s3.ts:409](https://github.com/maiyunnet/kebab/blob/master/lib/s3.ts#L409)
 
 检测对象是否存在
 
@@ -122175,9 +122188,9 @@ bucket 名
 
 > **putObject**(`key`, `content`, `length?`, `bucket?`): `Promise`\<`false` \| `CompleteMultipartUploadCommandOutput`\>
 
-Defined in: [lib/s3.ts:139](https://github.com/maiyunnet/kebab/blob/master/lib/s3.ts#L139)
+Defined in: [lib/s3.ts:140](https://github.com/maiyunnet/kebab/blob/master/lib/s3.ts#L140)
 
-上传对象（可传流且也可无需设置 length） --
+上传对象，流内容可省略 length
 
 #### Parameters
 
@@ -122195,9 +122208,9 @@ Defined in: [lib/s3.ts:139](https://github.com/maiyunnet/kebab/blob/master/lib/s
 
 ##### length?
 
-`number` \| \{ `bucket?`: `string`; `disposition?`: `string`; `length?`: `number`; `type?`: `string`; \}
+`number` \| \{ `bucket?`: `string`; `disposition?`: `string`; `length?`: `number`; `signal?`: `AbortSignal`; `type?`: `string`; \}
 
-设置 contentLength，如果是流模式则需要设置此项，也可以设置为对象参数
+contentLength 或上传选项
 
 `number`
 
@@ -122205,22 +122218,36 @@ Defined in: [lib/s3.ts:139](https://github.com/maiyunnet/kebab/blob/master/lib/s
 
 ###### Type Literal
 
-\{ `bucket?`: `string`; `disposition?`: `string`; `length?`: `number`; `type?`: `string`; \}
+\{ `bucket?`: `string`; `disposition?`: `string`; `length?`: `number`; `signal?`: `AbortSignal`; `type?`: `string`; \}
 
-设置 contentLength，如果是流模式则需要设置此项，也可以设置为对象参数
+contentLength 或上传选项
 
 ###### bucket?
 
 `string`
 
+bucket 名，省略时使用预定义 bucket
+
 ###### disposition?
 
 `string`
 
+content-disposition，如 attachment
+
 ###### length?
 
 `number`
 
+contentLength，流内容可省略
+
+###### signal?
+
+`AbortSignal`
+
+取消上传请求并销毁输入流，等待已知的未完成分片清理后返回 false
+清理使用独立的 30 秒超时信号，失败时记录错误；不传则沿用原上传流程
+不删除同名对象，上传完成与取消同时发生时，由调用方清理独立任务文件
+
 ###### type?
 
 `string`
@@ -122237,13 +122264,15 @@ bucket 名
 
 `Promise`\<`false` \| `CompleteMultipartUploadCommandOutput`\>
 
+上传结果，失败或取消返回 false；传入 signal 时，返回前会尝试清理已知的未完成分片
+
 ***
 
 ### putObjects()
 
 > **putObjects**(`items`, `options?`): `Promise`\<[`IPutObjectsItemResult`](../interfaces/IPutObjectsItemResult.md)[]\>
 
-Defined in: [lib/s3.ts:184](https://github.com/maiyunnet/kebab/blob/master/lib/s3.ts#L184)
+Defined in: [lib/s3.ts:272](https://github.com/maiyunnet/kebab/blob/master/lib/s3.ts#L272)
 
 批量上传对象，并发控制，单次失败不影响其他项
 
@@ -122347,7 +122376,7 @@ lib/s3/functions/get.md
 
 > **get**(`ctr`, `opt`): [`S3`](../classes/S3.md)
 
-Defined in: [lib/s3.ts:351](https://github.com/maiyunnet/kebab/blob/master/lib/s3.ts#L351)
+Defined in: [lib/s3.ts:439](https://github.com/maiyunnet/kebab/blob/master/lib/s3.ts#L439)
 
 创建一个对象存储对象
 

package/index.d.ts

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

package/index.js

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

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>;

package/lib/fs.js

@@ -4,67 +4,34 @@
  * Last: 2020-3-11 22:21:51, 2022-12-29 01:18:25, 2023-12-13 20:50:09
  */
 import * as fs from 'fs';
+import * as crypto from 'crypto';
 import * as http2 from 'http2';
+import * as stream from 'stream';
 import * as mime from '@litert/mime';
 import * as lText from './text.js';
 import * as lCore from './core.js';
 import * as lZlib from './zlib.js';
 /**
- * --- 读取完整文件或一段 ---
+ * --- 读取完整文件或一段，区间包含首尾字节 ---
  * @param path 文件路径
  * @param options 编码或选项
+ * @returns 文件内容，读取失败返回 null
  */
 export async function getContent(path, options) {
-    if (typeof options === 'string') {
-        options = {
-            'encoding': options
-        };
-    }
-    else {
-        options ??= {};
-    }
-    const encoding = options.encoding;
-    const start = options.start;
-    const end = options.end;
-    if ((start !== undefined) || (end !== undefined)) {
-        return new Promise(function (resolve) {
-            const rs = createReadStream(path, {
-                'start': start,
-                'end': end
-            });
-            const data = [];
-            rs.on('data', (chunk) => {
-                if (!(chunk instanceof Buffer)) {
-                    return;
-                }
-                data.push(chunk);
-            }).on('end', function () {
-                const buf = Buffer.concat(data);
-                if (encoding) {
-                    resolve(buf.toString());
-                }
-                else {
-                    resolve(buf);
-                }
-            }).on('error', function () {
-                resolve(null);
-            });
-        });
-    }
-    else {
-        try {
-            if (encoding) {
-                return await fs.promises.readFile(path, {
-                    'encoding': encoding
-                });
-            }
-            else {
-                return await fs.promises.readFile(path);
-            }
+    const { encoding, start, end } = typeof options === 'string' ? { 'encoding': options } : options ?? {};
+    try {
+        if (start === undefined && end === undefined) {
+            return await fs.promises.readFile(path, { encoding });
         }
-        catch {
-            return null;
+        const data = [];
+        for await (const chunk of createReadStream(path, { start, end })) {
+            data.push(chunk);
         }
+        const content = Buffer.concat(data);
+        return encoding ? content.toString(encoding) : content;
+    }
+    catch {
+        return null;
     }
 }
 /**
@@ -117,22 +84,18 @@ export async function symlink(filePath, linkPath, type) {
  * @param path 要删除的文件路径
  */
 export async function unlink(path) {
-    for (let i = 0; i <= 2; ++i) {
+    for (let i = 0; i < 4; ++i) {
         try {
             await fs.promises.unlink(path);
             return true;
         }
         catch {
-            await lCore.sleep(250);
+            if (i < 3) {
+                await lCore.sleep(250);
+            }
         }
     }
-    try {
-        await fs.promises.unlink(path);
-        return true;
-    }
-    catch {
-        return false;
-    }
+    return false;
 }
 /**
  * --- 获取对象是否存在，存在则返回 stats 对象，否则返回 null ---
@@ -152,10 +115,7 @@ export async function stats(path) {
  */
 export async function isDir(path) {
     const pstats = await stats(path);
-    if (!pstats?.isDirectory()) {
-        return false;
-    }
-    return pstats;
+    return pstats?.isDirectory() ? pstats : false;
 }
 /**
  * --- 判断是否是文件或文件是否存在，是的话返回 stats ---
@@ -163,10 +123,7 @@ export async function isDir(path) {
  */
 export async function isFile(path) {
     const pstats = await stats(path);
-    if (!pstats?.isFile()) {
-        return false;
-    }
-    return pstats;
+    return pstats?.isFile() ? pstats : false;
 }
 /**
  * --- 深度创建目录，如果最末目录存在，则自动创建成功 ---
@@ -174,10 +131,6 @@ export async function isFile(path) {
  * @param mode 权限
  */
 export async function mkdir(path, mode = 0o755) {
-    if (await isDir(path)) {
-        return true;
-    }
-    // --- 深度创建目录 ---
     try {
         await fs.promises.mkdir(path, {
             'recursive': true,
@@ -209,30 +162,24 @@ export async function rmdir(path) {
  * --- Danger 危险：危险函数，尽量不要使用 ---
  * --- This is a danger function, please don't use it ---
  * --- 删除一个非空目录 ---
+ * @param path 目录路径，不递归读取符号链接指向的目录
+ * @returns 删除成功或根路径不是目录返回 true，删除失败返回 false
  */
 export async function rmdirDeep(path) {
+    // --- 去掉末尾斜线再用 lstat 检查，避免目录链接被跟随 ---
+    if (await isDir(path.replace(/\/+$/, '') || path) === false) {
+        return true;
+    }
     if (!path.endsWith('/')) {
         path += '/';
     }
     const list = await readDir(path);
     for (const item of list) {
-        const stat = await stats(item.name);
-        if (!stat) {
+        const target = path + item.name;
+        const result = item.isDirectory() ? await rmdirDeep(target) : await unlink(target);
+        if (!result) {
             return false;
         }
-        if (stat.isDirectory()) {
-            // --- 目录 ---
-            const rtn = await rmdirDeep(path + item.name);
-            if (!rtn) {
-                return false;
-            }
-        }
-        else {
-            const rtn = await unlink(path + item.name);
-            if (!rtn) {
-                return false;
-            }
-        }
     }
     return rmdir(path);
 }
@@ -270,28 +217,12 @@ export async function rename(oldPath, newPath) {
  */
 export async function readDir(path, encoding) {
     try {
-        const list = [];
-        const dlist = await fs.promises.readdir(path, {
+        const list = await fs.promises.readdir(path, {
             'encoding': encoding,
             'withFileTypes': true
         });
-        for (const item of dlist) {
-            if (item.name === '.' || item.name === '..') {
-                continue;
-            }
-            list.push(item);
-        }
-        // --- 将 list 根据先目录后文件排序，如果是同是目录或文件，则以名称排序 ---
-        list.sort((a, b) => {
-            // --- 目录排在文件前面 ---
-            if (a.isDirectory() && !b.isDirectory())
-                return -1;
-            if (!a.isDirectory() && b.isDirectory())
-                return 1;
-            // --- 同类型按名称排序 ---
-            return a.name.localeCompare(b.name);
-        });
-        return list;
+        // --- 目录优先，同类型按名称排序；readdir 本身不返回 . 和 .. ---
+        return list.sort((a, b) => Number(b.isDirectory()) - Number(a.isDirectory()) || a.name.localeCompare(b.name));
     }
     catch {
         return [];
@@ -319,13 +250,11 @@ export async function copyFolder(from, to, ignore = []) {
             if (r === -1) {
                 return r;
             }
-            else {
-                num += r;
-            }
+            num += r;
         }
         else if (item.isFile()) {
             // --- 先判断本文件是否被排除 ---
-            if (ignore.length > 0 && lText.match(item.name, ignore)) {
+            if (lText.match(item.name, ignore)) {
                 continue;
             }
             if (!checkTo) {
@@ -362,21 +291,7 @@ export async function copyFile(src, dest) {
  * @param options 编码或配置
  */
 export function createReadStream(path, options) {
-    if (typeof options === 'string') {
-        options = {
-            'encoding': options
-        };
-    }
-    else {
-        options ??= {};
-    }
-    return fs.createReadStream(path, {
-        'flags': options.flags,
-        'encoding': options.encoding,
-        'autoClose': options.autoClose,
-        'start': options.start,
-        'end': options.end
-    });
+    return fs.createReadStream(path, typeof options === 'string' ? { 'encoding': options } : options);
 }
 /**
  * --- 读取文件写入到流，并等待写入完成 ---
@@ -399,28 +314,102 @@ export function pipe(path, destination, options) {
  * @param options 编码或配置
  */
 export function createWriteStream(path, options) {
-    if (typeof options === 'string') {
-        options = {
-            'encoding': options
-        };
+    return fs.createWriteStream(path, typeof options === 'string' ? { 'encoding': options } : options);
+}
+/**
+ * --- 解析并合并字节区间，限制多段请求的读取开销 ---
+ * @param value Range 请求头
+ * @param size 文件字节数
+ * @returns 区间列表；false 表示全部越界或区间过多；null 表示忽略请求头
+ */
+function parseFileRanges(value, size) {
+    if (!/^bytes=/i.test(value) || size === 0 || !Number.isSafeInteger(size)) {
+        return null;
     }
-    else {
-        options ??= {};
-    }
-    return fs.createWriteStream(path, {
-        'flags': options.flags,
-        'encoding': options.encoding,
-        'mode': options.mode,
-        'autoClose': options.autoClose,
-        'start': options.start
-    });
+    const values = value.slice(6).split(',');
+    // --- 防止客户端利用大量小区间放大文件读取与响应开销 ---
+    if (value.length > 8192 || values.length > 16) {
+        return false;
+    }
+    const total = BigInt(size);
+    const ranges = [];
+    let count = 0;
+    for (const item of values) {
+        const part = item.trim();
+        if (part === '') {
+            continue;
+        }
+        const match = /^(\d*)-(\d*)$/.exec(part);
+        if (!match || match[1] === '' && match[2] === '') {
+            return null;
+        }
+        ++count;
+        // --- 先以 BigInt 解析，避免超大偏移被浮点取整后读错字节 ---
+        const start = match[1] !== '' ? BigInt(match[1]) : total - BigInt(match[2]);
+        const end = match[1] !== '' && match[2] !== '' ? BigInt(match[2]) : total - 1n;
+        if (match[1] !== '' && match[2] !== '' && end < start) {
+            return null;
+        }
+        if (start >= total) {
+            continue;
+        }
+        ranges.push({
+            'start': Number(start < 0n ? 0n : start),
+            'end': Number(end >= total ? total - 1n : end),
+            'order': count
+        });
+    }
+    if (count === 0) {
+        return null;
+    }
+    if (ranges.length === 0) {
+        return false;
+    }
+    ranges.sort((a, b) => a.start - b.start);
+    const merged = [];
+    for (const range of ranges) {
+        const previous = merged[merged.length - 1];
+        if (previous && range.start <= previous.end + 1) {
+            previous.end = Math.max(previous.end, range.end);
+            previous.order = Math.min(previous.order, range.order);
+        }
+        else {
+            merged.push(range);
+        }
+    }
+    return merged.sort((a, b) => a.order - b.order);
 }
 /**
- * --- 读取文件并输出到 http 的 response ---
+ * --- 逐段读取 multipart 响应，保持背压且在取消时关闭当前文件流 ---
+ * @param path 文件路径
+ * @param ranges 文件区间
+ * @param headers 每段的 MIME 头
+ * @param footer 结束边界
+ * @returns multipart 数据流
+ */
+async function* readFileRanges(path, ranges, headers, footer) {
+    for (let i = 0; i < ranges.length; ++i) {
+        yield headers[i];
+        yield* createReadStream(path, ranges[i]);
+        yield Buffer.from('\r\n');
+    }
+    yield footer;
+}
+/**
+ * --- 读取文件并输出到 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 async function readToResponse(path, req, res, stat) {
     stat ??= await stats(path);
@@ -428,7 +417,7 @@ export async function readToResponse(path, req, res, stat) {
         const content = '<h1>404 Not found</h1><hr>Kebab';
         res.setHeader('content-length', Buffer.byteLength(content));
         lCore.writeHead(res, 404);
-        res.end(content);
+        res.end(req.method === 'HEAD' ? '' : content);
         return;
     }
     // --- 判断缓存以及 MIME 和编码 ---
@@ -438,44 +427,110 @@ export async function readToResponse(path, req, res, stat) {
     if (mimeData.mime.startsWith('text/') || ['json', 'xml', 'svg', 'js', 'mjs', 'map', 'webmanifest'].includes(mimeData.extension)) {
         charset = '; charset=utf-8';
     }
+    const hash = `W/"${stat.size.toString(16)}-${stat.mtime.getTime().toString(16)}"`;
+    const lastModified = stat.mtime.toUTCString();
+    const modifiedTime = Date.parse(lastModified);
+    const canCompress = mimeData.compressible && stat.size >= 1024;
+    res.setHeader('etag', hash);
+    res.setHeader('last-modified', lastModified);
+    res.setHeader('accept-ranges', 'bytes');
+    if (canCompress) {
+        const vary = res.getHeader('vary');
+        const values = (Array.isArray(vary) ? vary.join(',') : String(vary ?? '')).split(',').map((item) => item.trim()).filter(Boolean);
+        if (!values.some((item) => item === '*' || item.toLowerCase() === 'accept-encoding')) {
+            values.push('Accept-Encoding');
+            res.setHeader('vary', values.join(', '));
+        }
+    }
     // --- 这些文件可能需要缓存 ---
     if (['htm', 'html', 'css', 'js', 'mjs', 'xml', 'jpg', 'jpeg', 'svg', 'gif', 'png', 'json'].includes(mimeData.extension)) {
         /** --- 静态文件默认缓存秒数 --- */
         const cacheTTL = 600;
-        const hash = `W/"${stat.size.toString(16)}-${stat.mtime.getTime().toString(16)}"`;
-        const lastModified = stat.mtime.toUTCString();
-        res.setHeader('etag', hash);
         res.setHeader('expires', new Date(Date.now() + cacheTTL * 1_000).toUTCString());
         res.setHeader('cache-control', 'public, max-age=' + cacheTTL.toString());
-        // --- 判断返回 304 吗 ---
-        const noneMatch = req.headers['if-none-match'];
-        const modifiedSince = req.headers['if-modified-since'];
-        if ((hash === noneMatch) && (lastModified === modifiedSince)) {
-            lCore.writeHead(res, 304);
-            res.end();
-            return;
-        }
-        res.setHeader('last-modified', lastModified);
     }
     else {
         res.setHeader('cache-control', 'no-cache, must-revalidate');
     }
-    // --- 设置 type ---
-    res.setHeader('content-type', mimeData.mime + charset);
+    // --- 条件请求优先于 Range；弱 ETag 只能用于缓存验证，不能用于 If-Match ---
+    const match = req.headers['if-match'];
+    const unmodifiedSince = req.headers['if-unmodified-since'];
+    if (match !== undefined ? match.trim() !== '*' : unmodifiedSince !== undefined && modifiedTime > Date.parse(unmodifiedSince)) {
+        res.setHeader('content-length', 0);
+        lCore.writeHead(res, 412);
+        res.end();
+        return;
+    }
+    const noneMatch = req.headers['if-none-match'];
+    const modifiedSince = req.headers['if-modified-since'];
+    const isRead = req.method === 'GET' || req.method === 'HEAD';
+    const unchanged = noneMatch !== undefined ? noneMatch.trim() === '*' || noneMatch.split(',').some((item) => item.trim().replace(/^W\//, '') === hash.slice(2)) :
+        isRead && modifiedSince !== undefined && modifiedTime <= Date.parse(modifiedSince);
+    if (unchanged) {
+        if (!isRead) {
+            res.setHeader('content-length', 0);
+        }
+        lCore.writeHead(res, isRead ? 304 : 412);
+        res.end();
+        return;
+    }
+    const contentType = mimeData.mime + charset;
+    res.setHeader('content-type', contentType);
+    const rangeHeader = req.headers['range'];
+    const ifRange = req.headers['if-range'];
+    // --- 日期必须精确匹配且至少早一秒；压缩与原始字节共享的日期不能作强校验，避免跨编码续传 ---
+    const rangeMatches = ifRange === undefined || typeof ifRange === 'string' && !ifRange.includes('"') &&
+        Date.parse(ifRange) === modifiedTime && modifiedTime <= Date.now() - 1_000 && !canCompress;
+    const ranges = req.method === 'GET' && rangeHeader !== undefined &&
+        rangeMatches ? parseFileRanges(rangeHeader, stat.size) : null;
+    if (ranges === false) {
+        res.setHeader('content-range', `bytes */${stat.size}`);
+        res.setHeader('content-length', 0);
+        lCore.writeHead(res, 416);
+        res.end();
+        return;
+    }
     // --- 判断客户端支持的压缩模式 ---
     const encoding = req.headers['accept-encoding'] ?? '';
-    if (mimeData.compressible && (stat.size >= 1024)) {
+    if (ranges === null && canCompress && encoding !== '') {
         // --- 压缩 ---
         const compress = await lZlib.compress(encoding, await getContent(path));
         if (compress) {
             res.setHeader('content-encoding', compress.type);
             res.setHeader('content-length', Buffer.byteLength(compress.buffer));
-            res.end(compress.buffer);
+            lCore.writeHead(res, 200);
+            res.end(req.method === 'HEAD' ? '' : compress.buffer);
             return;
         }
     }
-    // --- 不压缩 ---
-    res.setHeader('content-length', stat.size);
-    lCore.writeHead(res, 200);
-    await pipe(path, res instanceof http2.Http2ServerResponse ? (res.stream ?? res) : res);
+    let headers = [];
+    let footer = Buffer.alloc(0);
+    if (ranges !== null && ranges.length > 1) {
+        const boundary = `kebab-${crypto.randomBytes(16).toString('hex')}`;
+        headers = ranges.map((range) => Buffer.from(`--${boundary}\r\nContent-Type: ${contentType}\r\nContent-Range: bytes ${range.start}-${range.end}/${stat.size}\r\n\r\n`));
+        footer = Buffer.from(`--${boundary}--\r\n`);
+        res.setHeader('content-type', `multipart/byteranges; boundary=${boundary}`);
+        res.setHeader('content-length', ranges.reduce((length, range, i) => length + headers[i].length + (range.end - range.start + 1) + 2, footer.length));
+    }
+    else if (ranges !== null) {
+        res.setHeader('content-range', `bytes ${ranges[0].start}-${ranges[0].end}/${stat.size}`);
+        res.setHeader('content-length', ranges[0].end - ranges[0].start + 1);
+    }
+    else {
+        res.setHeader('content-length', stat.size);
+    }
+    lCore.writeHead(res, ranges === null ? 200 : 206);
+    if (req.method === 'HEAD') {
+        res.end();
+        return;
+    }
+    const source = ranges !== null && ranges.length > 1 ?
+        stream.Readable.from(readFileRanges(path, ranges, headers, footer)) : createReadStream(path, ranges?.[0]);
+    try {
+        await stream.promises.pipeline(source, res instanceof http2.Http2ServerResponse ? (res.stream ?? res) : res);
+    }
+    catch {
+        // --- 已提交响应头后不能再发送错误页；管道会关闭文件流及断开的响应 ---
+        res.destroy();
+    }
 }

package/lib/s3.d.ts

@@ -3,8 +3,8 @@
  * Date: 2024-2-18 18:32:45
  * Last: 2024-2-18 18:32:47, 2024-3-16 16:42:27, 2024-5-31 21:36:26, 2024-7-8 00:28:42, 2024-7-19 11:32:43, 2025-6-10 21:45:34, 2025-12-5 23:42:59
  */
-import * as s3 from '@aws-sdk/client-s3';
 import * as stream from 'stream';
+import * as s3 from '@aws-sdk/client-s3';
 import * as sCtr from '#kebab/sys/ctr.js';
 /**
  * --- s3 文档：https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/s3/ ---
@@ -76,18 +76,28 @@ export declare class S3 {
      */
     setBucket(bucket: string): void;
     /**
-     * --- 上传对象（可传流且也可无需设置 length） --
+     * --- 上传对象，流内容可省略 length ---
      * @param key 对象路径
      * @param content 内容
-     * @param length 设置 contentLength，如果是流模式则需要设置此项，也可以设置为对象参数
+     * @param length contentLength 或上传选项
      * @param bucket bucket 名
+     * @returns 上传结果，失败或取消返回 false；传入 signal 时，返回前会尝试清理已知的未完成分片
      */
     putObject(key: string, content: string | Buffer | stream.Readable, length?: number | {
+        /** --- contentLength，流内容可省略 --- */
         'length'?: number;
         /** --- content-type，如 application/javascript --- */
         'type'?: string;
+        /** --- content-disposition，如 attachment --- */
         'disposition'?: string;
+        /** --- bucket 名，省略时使用预定义 bucket --- */
         'bucket'?: string;
+        /**
+         * --- 取消上传请求并销毁输入流，等待已知的未完成分片清理后返回 false ---
+         * --- 清理使用独立的 30 秒超时信号，失败时记录错误；不传则沿用原上传流程 ---
+         * --- 不删除同名对象，上传完成与取消同时发生时，由调用方清理独立任务文件 ---
+         */
+        'signal'?: AbortSignal;
     }, bucket?: string): Promise<s3.CompleteMultipartUploadCommandOutput | false>;
     /**
      * --- 批量上传对象，并发控制，单次失败不影响其他项 ---

package/lib/s3.js

@@ -4,6 +4,7 @@
  * Last: 2024-2-18 18:32:47, 2024-3-16 16:42:27, 2024-5-31 21:36:26, 2024-7-8 00:28:42, 2024-7-19 11:32:43, 2025-6-10 21:45:34, 2025-12-5 23:42:59
  */
 // --- 库和定义 ---
+import * as stream from 'stream';
 import * as s3 from '@aws-sdk/client-s3';
 import * as ls from '@aws-sdk/lib-storage';
 import * as lCore from '#kebab/lib/core.js';
@@ -67,28 +68,79 @@ export class S3 {
         this._bucket = bucket;
     }
     /**
-     * --- 上传对象（可传流且也可无需设置 length） --
+     * --- 上传对象，流内容可省略 length ---
      * @param key 对象路径
      * @param content 内容
-     * @param length 设置 contentLength，如果是流模式则需要设置此项，也可以设置为对象参数
+     * @param length contentLength 或上传选项
      * @param bucket bucket 名
+     * @returns 上传结果，失败或取消返回 false；传入 signal 时，返回前会尝试清理已知的未完成分片
      */
     async putObject(key, content, length, bucket) {
+        /** --- 对象内容类型 --- */
+        let type;
+        /** --- 对象下载方式 --- */
+        let disposition;
+        /** --- 调用方传入的取消信号，仅作用于本次上传 --- */
+        let signal;
+        if (typeof length !== 'number') {
+            type = length?.type;
+            disposition = length?.disposition;
+            bucket = length?.bucket;
+            signal = length?.signal;
+            length = length?.length;
+        }
+        bucket ??= this._bucket;
+        /** --- 输入流，传入 signal 时在取消或失败后停止读取；字符串与 Buffer 无需释放 --- */
+        const source = content instanceof stream.Readable ? content : undefined;
+        /**
+         * --- 停止流读取，避免取消时仍阻塞在等待下一块数据的阶段 ---
+         * @returns 无返回值
+         */
+        const onAbort = () => {
+            source?.destroy();
+        };
+        /** --- 尚未确认合并或清理完成的分片上传 ID，用于失败后的兜底清理 --- */
+        let uploadId;
+        /** --- 是否取得有效上传结果，失败时需要释放输入流 --- */
+        let success = false;
+        /** --- 分片清理请求的超时毫秒数，避免清理阶段无限等待 --- */
+        const cleanupTimeout = 30000;
         try {
-            /** --- content type --- */
-            let type = undefined;
-            /** --- content disposition --- */
-            let disposition = undefined;
-            if (typeof length !== 'number') {
-                type = length?.type;
-                disposition = length?.disposition;
-                bucket = length?.bucket;
-                length = length?.length;
+            if (signal?.aborted) {
+                return false;
             }
+            signal?.addEventListener('abort', onAbort, { 'once': true });
+            /** --- 本次上传的客户端入口，共享连接配置但不修改共享客户端的 send --- */
+            const client = signal ? Object.create(this._link) : this._link;
+            if (signal) {
+                /**
+                 * --- 为上传命令传递取消信号，并跟踪未完成的分片上传 ---
+                 * --- Upload.abort() 会提前结束 done()，且不会取消正在发送的请求 ---
+                 * --- 逐条命令传入信号，让 done() 等待分片任务和清理结束 ---
+                 * @param command SDK 上传或分片清理命令；Upload 仅使用 send 的 Promise 调用形式
+                 * @returns SDK 命令结果
+                 */
+                client.send = (async (command) => {
+                    /** --- 清理请求必须使用独立信号，避免随上传请求一起取消 --- */
+                    const isCleanup = command instanceof s3.AbortMultipartUploadCommand;
+                    /** --- 命令成功后再更新分片 ID，失败时保留 ID 供 finally 重试清理 --- */
+                    const res = await this._link.send(command, {
+                        'abortSignal': isCleanup ? AbortSignal.timeout(cleanupTimeout) : signal,
+                    });
+                    if (command instanceof s3.CreateMultipartUploadCommand) {
+                        uploadId = res.UploadId;
+                    }
+                    else if (isCleanup || (command instanceof s3.CompleteMultipartUploadCommand)) {
+                        uploadId = undefined;
+                    }
+                    return res;
+                });
+            }
+            /** --- SDK 上传任务，继续由 SDK 管理分片和并发 --- */
             const upload = new ls.Upload({
-                'client': this._link,
+                'client': client,
                 'params': {
-                    'Bucket': bucket ?? this._bucket,
+                    'Bucket': bucket,
                     'Key': key,
                     'Body': content,
                     'ContentLength': length,
@@ -96,13 +148,40 @@ export class S3 {
                     'ContentDisposition': disposition,
                 }
             });
+            /** --- 上传结果；取消与上传完成同时发生时仍向调用方返回 false --- */
             const res = await upload.done();
-            return (res.Location && res.Bucket && res.Key) ? res : false;
+            if (signal?.aborted || !res.Location || !res.Bucket || !res.Key) {
+                return false;
+            }
+            success = true;
+            return res;
         }
         catch (e) {
-            lCore.log(this._ctr, '[LIB][S3][putObject] ' + lText.stringifyJson(e.message ?? '').slice(1, -1).replace(/"/g, '""'), '-error');
+            if (!signal?.aborted) {
+                lCore.log(this._ctr, `[LIB][S3][putObject] ${lText.stringifyError(e)}`, '-error');
+            }
             return false;
         }
+        finally {
+            signal?.removeEventListener('abort', onAbort);
+            if (signal && !success) {
+                source?.destroy();
+            }
+            // --- SDK 的合并失败分支不会清理分片；SDK 清理失败时也保留 ID，在这里兜底 ---
+            // --- 只清理本次未完成的分片，不删除可能已存在的同名对象 ---
+            if (uploadId) {
+                try {
+                    await this._link.send(new s3.AbortMultipartUploadCommand({
+                        'Bucket': bucket,
+                        'Key': key,
+                        'UploadId': uploadId,
+                    }), { 'abortSignal': AbortSignal.timeout(cleanupTimeout) });
+                }
+                catch (e) {
+                    lCore.log(this._ctr, `[LIB][S3][putObject][cleanup] ${lText.stringifyError(e)}`, '-error');
+                }
+            }
+        }
     }
     /**
      * --- 批量上传对象，并发控制，单次失败不影响其他项 ---

package/package.json

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