tt-uploader 1.6.2 → 2.0.0-beta

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md ADDED
@@ -0,0 +1,30 @@
1
+ # Changelog
2
+
3
+ ## 2.0.0 — 2026-11-19
4
+
5
+ ### 新增
6
+
7
+ - VOD 预签名上传:`addPresignedFile({file, type?, uploadInfo})`,业务服务端负责 Apply/Commit,SDK 负责直传或分片上传;同文件所有分片共用 Auth。
8
+ - `presignedConfig.onUploadSuccess` 与 `callbackError`:分离字节上传完成和业务提交结果,支持业务单独重试 Commit。
9
+ - STS `onRefreshStsToken` 与预签名 `onRefreshUploadInfo` 续签回调,提前检查有效期,并发共享续签。
10
+ - 预签名跨页面分片恢复:全文件 SHA-256 校验、原分片布局恢复、云端分片列表核对,缓存不持久化 Auth。
11
+
12
+ ### 默认行为变化与迁移
13
+
14
+ - 默认单文件分片并发由 5 提升到 8;需要原并发行为的业务请显式设置 `uploadSliceCount: 5`。实际并发受分片数、浏览器及云控影响。
15
+ - 尾片恰好等于基础分片大小时不再合并:默认 20 MiB 从 5/5/10 变为 5/5/5/5;不足基础片大小的尾片仍合并。
16
+ - 预签名 `complete` 仅表示传输完成,`committed=false`;请等待业务服务端 Commit 成功再展示最终成功。原 STS 正常流程仍包含 Commit。
17
+ - 预签名续签必须保持原上传目标和 Commit 会话;不可用新 Apply 会话接用旧分片。跨页面恢复需重新选择原文件,并从业务服务端找回原会话。
18
+
19
+ ### 兼容性与修复
20
+
21
+ - 原公开添加文件/启动/暂停/恢复/取消/手动更新 STS 接口保持同步返回契约;内部网络阶段支持等待续签,不应依赖内部类方法的返回值或请求发起的微任务时序。
22
+ - Init/Merge 重试重新校验凭证并构造请求,暂停/取消期间不使用旧 Auth 发起请求。
23
+ - 预签名上传尊重云端返回的上传头,不再强制 gateway;隔离 STS 与预签名缓存。
24
+ - 文件内容身份与存储目标鉴权不同:Auth/StoreUri 不保证内容相同;FileSize、FileName、CRC 不替代可信内容摘要或服务端验收。
25
+
26
+ ### 构建与发布
27
+
28
+ - 根目录 `npm run build` / `npm run build-sdk` 编译 SDK 与插件;Demo 使用独立的 `npm run build-presigned`。
29
+ - 包目录 `npm publish` 或根目录 `npm publish --workspace=tt-uploader` 执行 `prepublishOnly → build`,随后发布 dist、types、README 与本 CHANGELOG;不要使用 `--ignore-scripts` 跳过编译。
30
+ - Node 测试服务位于独立 generate_token 目录,不包含在 npm 包中。开发设计/诊断 docs 不纳入本 MR 或 npm 包。
package/README.md CHANGED
@@ -15,10 +15,42 @@
15
15
  ## 安装
16
16
 
17
17
  ```bash
18
- npm i tt-uploader
18
+ npm i tt-uploader@^2.0.0
19
19
  ```
20
20
 
21
- ## 使用示例
21
+ ## 编译与 npm 发布
22
+
23
+ 从仓库根目录操作:
24
+
25
+ ```sh
26
+ npm ci
27
+ npm run build # 等价于 build-sdk,编译 SDK 并复制插件到 dist/plugins
28
+ npm publish --workspace=tt-uploader --access=public
29
+ ```
30
+
31
+ 也可在 `packages/tt-uploader` 中执行 `npm publish`。包的 `prepublishOnly` 会自动执行 `npm run build`,再返回仓库根目录编译 SDK/插件;**不要加 `--ignore-scripts`**。根 package 为 private,不应直接在根目录执行不带 workspace 的 publish。
32
+
33
+ 本地打包检查可先 `npm run build-sdk`,再执行 `npm pack --workspace=tt-uploader --dry-run`;`npm pack` 本身不会执行 `prepublishOnly`。`build-presigned` 只编译 Demo,不是 npm SDK 编译入口;`presigned-server` 只用于启动同级测试服务,不进入 npm 包。
34
+
35
+ 发布文件包含 dist、types、README、CHANGELOG 和 package.json,不包含 Node 服务、Demo、测试或开发 docs。2.0.0 的默认行为变化与迁移说明见 [CHANGELOG](CHANGELOG.md)。
36
+
37
+ ## 两种鉴权模式
38
+
39
+ **VOD 支持 STS 和预签名两种鉴权模式。** 预签名自 2.0.0 新增;ImageX 不在本次预签名支持范围内。
40
+
41
+ | 对比项 | 1. STS 模式 | 2. 预签名模式 |
42
+ | --- | --- | --- |
43
+ | 添加任务 | `addFile({file, stsToken})` | `addPresignedFile({file, uploadInfo})` |
44
+ | 服务端下发 | 临时 STS 凭证 | 本次上传的 Auth、StoreUri、SessionKey、uploadHost 等 |
45
+ | ApplyUploadInfo | SDK 使用 STS 签名并调用 | 业务服务端调用 |
46
+ | 文件传输 | SDK 直传或分片上传 | SDK 直传或分片上传,所有分片共用同一 Auth |
47
+ | CommitUploadInfo | SDK 调用 | **业务服务端调用,SDK 不代为提交** |
48
+ | 完成状态 | SDK 正常流程包含 Commit | **`complete` 仅代表字节上传完成,`committed=false`** |
49
+ | 本地跨页面断点缓存 | 按原配置支持 | **支持:启用缓存、提供有效期,并重新选择原文件及提供原会话信息** |
50
+
51
+ STS 接入见下方示例;预签名接入见 [VOD 预签名上传接入](#vod-预签名上传接入)。分片/直传是传输方式,与这两种鉴权模式分别配置。
52
+
53
+ ## STS 模式接入示例
22
54
 
23
55
  ```javascript
24
56
  import TTUploader from 'tt-uploader'
@@ -59,6 +91,183 @@ uploader.start(key)
59
91
  - veVod: https://www.volcengine.com/docs/4/66560
60
92
  - veImageX: https://www.volcengine.com/docs/508/66132
61
93
 
94
+ ## VOD 预签名上传接入
95
+
96
+ 以下 API 自 2.0.0 提供,仅支持 VOD;原 STS `addFile` 链路继续保留。
97
+
98
+ ### 预签名模式重点关注
99
+
100
+ > **接入前必须确认以下事项,尤其不要将“上传完成”直接展示成“云端提交成功”。**
101
+
102
+ 1. **Apply 和 Commit 均由业务服务端负责。** SDK 只上传字节;通过 `presignedConfig.onUploadSuccess` 通知业务提交,确认服务端 Commit 成功后再展示最终成功。
103
+ 2. **`complete` 不等待成功回调。** 回调异常通过 `callbackError` 单独通知,保留 `params.sessionKey` 重试提交;不要因此重复上传,也不要把任意回调返回值当成云端提交结果。
104
+ 3. **Auth 绑定上传目标,不绑定文件内容。** 保留合法 Auth/StoreUri 时,换内容仍可能成功;`FileName` 和 CRC 不等于可信内容摘要。**实测 `FileSize` 不强制等于实际上传大小,不能用它限制配额或证明文件身份。**
105
+ 4. **自动续签需要业务回调。** 配置 `onRefreshUploadInfo` 并提供 `expiresAt`,SDK 在请求前检查有效期。续签必须保持原上传目标和会话;重新 Apply 属于新会话,不能接用旧分片。跨页面恢复需启用 `useLocalStorage`、重新选择原文件并提供原会话信息。
106
+ 5. **上传信息必须成套使用。** `uploadHost`、`storeUri`、`auth`、`sessionKey` 使用同次 Apply 的返回值,所有分片共用该 Auth;上传头按服务端响应传入,禁止覆盖 Authorization。
107
+ 6. **长期凭证只留在服务端。** 服务端需要校验业务用户与上传会话归属、控制配额并处理提交幂等;浏览器参数和 SessionKey 不能代替业务授权。不要公开或记录 Auth、SessionKey。
108
+
109
+ ### 职责与流程
110
+
111
+ 业务服务端持有云端凭证,调用 ApplyUploadInfo,向浏览器返回上传信息。浏览器 SDK 只执行直传或 InitUpload → UploadPart → MergePart,不签名、不调用 TOP Apply/Commit。字节上传完成后,业务通过成功回调请求服务端 CommitUploadInfo。
112
+
113
+ 所有分片使用同一份服务端返回的 Auth。不要向浏览器发送 AK/SK 或服务端长期凭证;Auth、SessionKey 也不应写入日志或公开分享。
114
+
115
+ ### 客户端示例
116
+
117
+ ```js
118
+ import TTUploader from 'tt-uploader'
119
+
120
+ // 请求业务服务端的上传接口:统一发送 JSON,并将 HTTP 或业务错误转换为异常。
121
+ // Apply、Commit 和续签均通过业务服务端完成,浏览器无需持有长期密钥。
122
+ async function requestUploadApi(path, body) {
123
+ const response = await fetch(path, {
124
+ method: 'POST',
125
+ headers: { 'Content-Type': 'application/json' },
126
+ body: JSON.stringify(body),
127
+ })
128
+ const data = await response.json()
129
+ if (!response.ok || data.error) throw new Error(data.error?.message || '请求失败')
130
+ return data
131
+ }
132
+
133
+ const uploader = new TTUploader({
134
+ userId: 'your-user-id',
135
+ appId: 1, // 使用业务实际 appId
136
+ uploadSliceCount: 8,
137
+ presignedConfig: {
138
+ onUploadSuccess: async params => {
139
+ const result = await requestUploadApi('/api/uploads/presigned/commit', {
140
+ sessionKey: params.sessionKey,
141
+ })
142
+ // 业务在这里展示云端提交成功;complete 不等待此回调。
143
+ console.log(result)
144
+ },
145
+ },
146
+ })
147
+ uploader.on('error', error => console.error('上传失败', error))
148
+ uploader.on('callbackError', ({ error, params }) => {
149
+ // 字节已上传成功。保留 params,允许用户单独重试提交,无需重传文件。
150
+ showCommitRetry(error, params)
151
+ })
152
+ uploader.on('complete', info => {
153
+ // 仅字节上传完成,info.committed === false,不代表云端 Commit 成功。
154
+ })
155
+
156
+ // 1. file 是用户从 <input type="file"> 选择的 File 对象。
157
+ // 向业务服务端申请本次上传凭证;服务端完成业务权限校验并调用 ApplyUploadInfo。
158
+ const { uploadInfo } = await requestUploadApi('/api/uploads/presigned/apply', {
159
+ fileName: file.name, // 本地文件名;是否转发为云端 FileName 由业务服务端决定
160
+ fileSize: file.size, // 文件字节数;不能将此声明作为云端强制大小校验
161
+ fileType: 'video', // 业务上传类型:video / image / object / media
162
+ })
163
+ // uploadInfo 包含 uploadHost、storeUri、auth、sessionKey,以及可选上传头和有效期。
164
+ // 申请接口不上传文件字节,也不将 Auth 与文件内容绑定。
165
+
166
+ // 2. 创建预签名任务,再开始直传或分片传输。
167
+ // 字节上传完成后,上面的 onUploadSuccess 回调请求业务服务端进行 Commit。
168
+ const key = uploader.addPresignedFile({ file, type: 'video', uploadInfo })
169
+ uploader.start(key)
170
+ // 暂停、恢复、取消方式与普通任务相同,见主 API。
171
+ ```
172
+
173
+ `showCommitRetry` 为业务自行实现的 UI。示例 HTTP 路径是配套测试服务约定,不是 SDK 强制要求。
174
+
175
+ ### uploadInfo 与回调契约
176
+
177
+ | 字段 | 要求 |
178
+ | --- | --- |
179
+ | uploadHost | 必填,完整 HTTP(S) origin,无路径;生产使用 HTTPS |
180
+ | storeUri | 必填,Apply 返回的存储路径,保持原值 |
181
+ | auth | 必填,Apply 返回的上传 Authorization |
182
+ | sessionKey | 必填,供业务服务端 Commit 使用 |
183
+ | uploadHeaders | 可选,字符串键值对象,按云端响应传入;不得覆盖 Authorization |
184
+ | expiresAt | 可选,ISO 日期时间;启用跨页面缓存必须提供。配置续签回调后可在请求前刷新,未配置则过期拒绝 |
185
+
186
+ `file` 必须为非空 File/Blob;`type` 可选,支持 video/image/object/media。参数不合法时同步抛错。
187
+
188
+ `onUploadSuccess` 参数:`{key, sessionKey, storeUri, uploadHost, fileName, fileSize, fileType}`,不包含 Auth、STS、文件字节。每个成功预签名任务调用一次,支持同步函数或 Promise。同步异常和 Promise 拒绝触发 `callbackError({error, params})`;不改变上传成功状态,不自动重试回调。回调返回值不会自动合并成 SDK 的提交结果。
189
+
190
+ 预签名分片任务在 `useLocalStorage: true` 且提供 `expiresAt` 时启用跨页面缓存;恢复规则与续签见下节。服务端须校验登录用户、会话归属和业务权限,并保证提交幂等;不能只信任客户端给出的 SessionKey 或文件元数据。
191
+
192
+ ### 自动续签与跨页面断点恢复
193
+
194
+ ```js
195
+ // file 是用户选择的 File;多任务分别保存 Apply 响应并关联到各自任务。
196
+ const appliedSession = await requestUploadApi('/api/uploads/presigned/apply', {
197
+ fileName: file.name, fileSize: file.size, fileType: 'video',
198
+ })
199
+ const { uploadSessionId } = appliedSession
200
+ const uploader = new TTUploader({
201
+ userId: 'your-user-id', appId: 1,
202
+ useLocalStorage: true,
203
+ credentialRefreshWindowMs: 60_000, // 默认提前 60 秒
204
+ onRefreshStsToken: async ({ key, reason, expiresAt }) => {
205
+ const { stsToken } = await requestUploadApi('/your-api/renew-sts', { key })
206
+ return stsToken // 含新的 ExpiredTime 和临时凭证
207
+ },
208
+ presignedConfig: {
209
+ onRefreshUploadInfo: async ({ sessionKey, storeUri, uploadHost, reason }) => {
210
+ const { uploadInfo } = await requestUploadApi('/api/uploads/presigned/renew', { uploadSessionId })
211
+ return uploadInfo // 同一 uploadHost/storeUri/sessionKey,更新 auth/expiresAt/合法上传头
212
+ },
213
+ onUploadSuccess: async ({ sessionKey }) => {
214
+ await requestUploadApi('/api/uploads/presigned/commit', { sessionKey })
215
+ },
216
+ },
217
+ })
218
+ ```
219
+
220
+ `renew-sts` 是业务接口示意。配套 Node 已实现 `POST /api/uploads/presigned/renew`,接收 Apply/批量成功项返回的 `uploadSessionId`;多任务应分别关联自己的 ID。`appliedSession` 表示此前 Apply 的完整响应。
221
+
222
+ **续签不是无条件重新 Apply。** 服务端首次分配唯一云端 FileName,保存原 Apply 参数;续签带原 SessionKey 再次 Apply,仅在 StoreUri 相同且云端 Auth 有效期确实延长时更新凭证。虽然 TOP 可能返回不同域名和 SessionKey,适配层保持原上传域名、原 Commit SessionKey,使用同目标的新 Auth。已在 `nzx-test` 验证新 Auth 上传旧 uploadID 的后续分片、Merge 及原 SessionKey Commit 成功。目标变化返回 `409 / UPLOAD_SESSION_NOT_RENEWABLE`,无可信的新有效期返回 `502 / UPLOAD_AUTH_NOT_EXTENDED`,不伪造 expiresAt。此结果不保证已失效的云端上传会话总能恢复。
223
+
224
+ - 在请求前检查(含分片发送/重试、Apply/Commit 等对应凭证边界),不运行后台续签定时器,不中断已发送请求。reason 为 `expiring` 或 `expired`。STS 依据 `ExpiredTime`,预签名依据 `expiresAt`;未知有效期不猜测、不主动续签。
225
+ - 同一实例、相同 STS 凭证或预签名会话的并发检查共享一次回调。回调失败或返回无效凭证通过上传 `error` 报告;不无限续签。返回有效期必须超过当前时间加提前窗口。
226
+ - **不将通用 401/4001 当作过期信号**,因为它也可能表示 Auth/StoreUri 不匹配。`refreshStsToken` 手动更新接口继续保留。
227
+
228
+ 页面重开后的恢复步骤(Demo 已提供“恢复上次上传”入口):
229
+
230
+ 1. 使用相同 `userId/appId`、同源 localStorage,并启用 `useLocalStorage`。
231
+ 2. 重新选择原始 File;从业务服务端取回**原会话** uploadInfo(含有效期)。配套服务支持 `POST /api/uploads/presigned/resume`,请求 `{uploadSessionId}`。SDK 不持久化 Auth,也不缓存文件字节;刷新后不会自动找回文件,需要用户重新选择。
232
+ 3. 再调用 `addPresignedFile({file, uploadInfo})` 和 `start(key)`。若已到期且配置回调,先完成续签再发上传请求。
233
+ 4. SDK 对文件名、大小、类型及**全文件 SHA-256**做一致性校验,恢复原分片边界,再查询云端已完成分片并核对 CRC,只有确认匹配的分片才跳过。校验失败保留旧缓存并报错,禁止误接另一文件;分片列表失败也不会静默重建旧会话。
234
+
235
+ **新 SessionKey/StoreUri 属于新任务,将从头上传。** 损坏缓存丢弃;存储不可用时正常上传但无跨页面保障。完成或取消清理该任务缓存;凭证更新不落盘。需额外读取整个文件计算摘要,内存按块控制,但会增加上传前的本地处理耗时。预签名缓存使用独立版本/命名空间,不改变 STS 旧缓存格式。
236
+
237
+ 业务服务端必须能找回旧会话并完成 Commit;示例 Node 服务使用内存会话,进程重启后不具备这个条件。对于云端已合并但页面未获知的情况,SDK 不会仅凭本地 merged 标记宣布成功;需业务查询实际状态处理。
238
+
239
+ ### 分片与并发
240
+
241
+ 默认分片并发上限为 8,非 HTTP/2 专属开关;实际并发还受分片数、浏览器和云控影响。默认小文件分片大小 5 MiB,文件小于两倍分片大小时走直传。剩余尾片不足 5 MiB 时仍合并到前片,因此 20 MiB 是 5/5/5/5,21 MiB 是 5/5/5/6。更大文件会选择 8 或 10 MiB 基础分片。
242
+
243
+ 预签名模式仅使用服务端提供的上传头,不强制添加 `x-storage-mode: gateway`。
244
+
245
+ ### 鉴权边界:对象授权不等于内容绑定
246
+
247
+ Auth 约束可写入的 StoreUri,并不证明上传的是申请时预期的本地文件。Apply 的 FileName 可影响云端对象名;它不是内容摘要。配套服务现会生成唯一云端 FileName 以保证续签目标稳定;该名称不是本地文件内容的身份。本节内容替换反例来自独立调用云端的诊断测试。
248
+
249
+ 2026-11-18 在 nzx-test 的真实接口实测(声明 20 MiB、传入 FileName,每片 5 MiB):
250
+
251
+ | 反例 | 结果 |
252
+ | --- | --- |
253
+ | 实际上传 20 MiB | 分片、Merge、Commit 成功 |
254
+ | 实际上传 15 / 25 MiB | 均成功,Commit 返回实际大小 |
255
+ | 使用其他对象的 Auth 上传分片 | HTTP 401,error_code 4001 |
256
+ | 分片 CRC32 错误 | HTTP 400,error_code 4007 MismatchChecksum |
257
+ | Merge 清单包含未上传分片 | HTTP 400,error_code 4019 InvalidMergeParts |
258
+ | 伪造 uploadID 上传单片 | HTTP 200、success=0;未验证该 ID 的 Merge/Commit |
259
+
260
+ 直传也验证:保留 Auth/StoreUri、替换文件内容或大小仍能成功;修改 StoreUri 中对象名则返回 401/4001。不能将这些单次环境结果推广为所有云端版本的协议保证。CRC 校验的是本次传输数据,不是与可信预期文件做比对。
261
+
262
+ 若业务要求指定文件内容,需建立可信预期摘要并在服务端校验,校验通过才接纳资源。客户端自报摘要或 SDK 检查不足以形成可信约束。不要将 FileSize 当成服务端强制的等值约束或配额保护。
263
+
264
+ ### 自测与服务端参考
265
+
266
+ [真实云端 Demo 与启动步骤](../../examples/presigned/README.md)。配套 Node 服务迁移至同级 `generate_token` 项目,SDK 包本身不依赖该项目。Demo 的生成文件为测试字节,验证视频 Commit 时应选择有效媒体文件。
267
+
268
+ 本页是仓库内对外接入文档;官网文档尚未随本次分支发布。
269
+
270
+
62
271
  ## 更新日志
63
272
 
64
273
  ### 1.5.5
@@ -79,4 +288,3 @@ uploader.start(key)
79
288
  - 优化错误处理逻辑
80
289
  - 当遇到错误码 4024(InMergedError)和 4025(AlreadyExistedError)时,自动清空本地缓存,避免使用过期缓存导致一直失败
81
290
  - 优化重试和错误日志打印逻辑
82
-