✨ 为 GM_xmlhttpRequest / GM.xmlHttpRequest 支持上传进度事件 (GM/TM/VM)

[cyfung1031]

Checklist / 检查清单

• Fixes API Compatibility Issue (GM/TM/VM)
• Code reviewed by human / 代码通过人工检查
• Changes tested / 已完成测试

背景

当前 GM_xmlhttpRequest / GM.xmlHttpRequest 只能接收主请求下载阶段的事件，无法通过 details.upload 获取上传阶段的开始、进度、完成或异常信息。

这会影响文件上传、表单上传等需要显示上传进度、处理超时或响应用户中止操作的用户脚本，也使 ScriptCat 与原生 XMLHttpRequestUpload 以及常见用户脚本管理器的接口存在差异。

本次改动

• 为 details.upload 增加以下回调支持：

  • onloadstart
  • onprogress
  • onload
  • onloadend
  • onerror
  • onabort
  • ontimeout

• 后台原生 XMLHttpRequest 路径监听 xhr.upload，通过现有消息通道转发为 onupload* 事件。

• 内容脚本侧将 onupload* 消息分发到 details.upload.on*，并统一提供：

  • loaded
  • total
  • lengthComputable
  • done
  • totalSize

• 请求体编码完成后计算 hasUpload，只在请求确实可能产生上传生命周期时通知后台绑定上传监听器。

• 对齐原生 XHR 的主动中止行为，处理上传回调与主请求回调的顺序、去重和同步竞态。

• 更新 GMSend.XHRDetails、GMTypes.XHRDetails，新增 GMTypes.XHRUpload，并同步模板、英文及简体中文声明文件。

• 新增后台、内容脚本、运行时及浏览器集成测试，覆盖正常上传、异常、超时、主动中止、事件顺序和竞态。

• 调整 GM API E2E fixture：每个 Playwright worker 只执行一次 user scripts 权限初始化，各测试从预配置 profile 创建独立副本，减少并行 CI 中重复启动 Chrome 导致的 Service Worker 超时，同时保持测试状态隔离。

实现考虑

1. 只在确实需要时绑定 xhr.upload

为 XMLHttpRequestUpload 注册监听器会改变跨域请求行为，并可能触发额外的 CORS 预检请求。

因此不能无条件为所有 XHR 请求绑定上传监听器。

内容侧会在请求体完成编码后计算 canHaveUploadLifecycle，仅在同时满足以下条件时向后台发送 hasUpload: true：

1. 请求不会切换到 fetch 传输；
2. 方法不是 GET 或 HEAD；
3. 存在实际请求体；
4. details.upload 中至少有一个回调值确实是函数。

后台仅在原生 XHR 路径且 details.hasUpload === true 时绑定七类 xhr.upload 事件。

这样不会让未使用上传回调的既有脚本承担额外预检、性能开销和跨域兼容风险。

2. 区分“注册了回调”和“真实存在上传生命周期”

仅传入 details.upload 并不代表浏览器一定会产生上传事件：

• GET / HEAD 的请求体会被忽略；
• 没有实际请求体时，上传阶段在发送前就视为完成；
• fetch 传输路径没有 XMLHttpRequestUpload；
• details.upload 中 truthy 但非函数的值不是有效回调。

因此后台监听开关、本地完成状态以及 abort() 的上传事件补发都统一依赖 canHaveUploadLifecycle。

这可以避免在根本不存在上传阶段的请求中错误触发 upload.onabort 或 upload.onloadend。

3. 对齐原生 XHR 的中止语义和事件顺序

当上传尚未完成时主动调用返回对象的 abort()：

1. 先触发 upload.onabort；
2. 再触发 upload.onloadend；
3. 然后触发主请求 onabort；
4. 最后触发主请求 onloadend。

实现使用 uploadDone 和 uploadLoadEndCalled 维护上传完成状态并保证 upload.onloadend 只执行一次。

同时处理以下竞态：

• 在 upload.onload 回调中同步调用 abort() 时，上传已被视为完成，不应误触发 upload.onabort；
• 消息通道断开可能导致后台已发出或即将发出的真实 upload.onloadend 丢失，因此需要本地兜底；
• 真实 upload.onloadend 和本地兜底只能执行一次；
• 上传正常完成后再中止主请求时，兜底 upload.onloadend 会保留最后一次真实上传进度；
• 上传以 error、abort 或 timeout 结束后，返回对象的 abort() 会成为空操作，让真实的主请求终止事件继续到达，避免被本地合成的 AbortError 覆盖。

4. 上传事件统一使用进度响应结构

主请求 onprogress 与全部上传事件共用同一套进度参数构造逻辑。

上传事件会尽量保留现有 XHR 响应字段，并统一补充：

• lengthComputable
• loaded
• total
• done
• totalSize

其中 done 与 loaded 一致，totalSize 与 total 一致，用于兼容现有 ScriptCat 进度回调结构。

5. 只接受函数类型的上传回调

details.upload 中 truthy 但非函数的值不会：

• 启用后台上传监听器；
• 触发额外的 CORS 预检；
• 在事件到达时被尝试调用。

这样既避免无效配置改变请求行为，也避免运行时出现非函数调用异常。

6. 降低 E2E 并行执行的启动开销

GM API 浏览器测试需要先通过 chrome://extensions 和 developerPrivate 启用 user scripts 权限，再重新启动持久化浏览器上下文。

此前每个测试都会重复执行完整初始化；并行 worker 较多时，大量 Chrome 实例会同时争用 CPU，使扩展 Service Worker 启动时间超过测试超时。

现在权限初始化改为 worker 级 fixture：

1. 每个 worker 创建并初始化一次基础 profile；
2. 每个测试复制该 profile 到独立临时目录；
3. 测试结束后删除副本；
4. worker 结束后删除基础 profile。

这样可以减少重复启动成本，同时避免脚本、存储和扩展状态在不同测试之间泄漏。

已知限制

1. 强制走 fetch 的配置不支持上传回调

当前以下配置会让 ScriptCat 使用 fetch 传输，因此不会产生 details.upload 事件：

• fetch: true
• 设置 redirect
• anonymous: true 或 mozAnon: true
• responseType: "stream"

其中 anonymous / mozAnon 切换到 fetch 是现有架构通过 credentials: "omit" 实现不携带 Cookie 的方式。

要让匿名请求继续使用原生 XHR，需要重新设计跨域 Cookie 处理机制，影响范围超出本 PR，因此本次只明确记录限制，不调整现有传输架构。

2. 兼容目标

本实现以原生 XMLHttpRequestUpload 的事件模型和顺序为准，并提供与常见用户脚本管理器相近的 details.upload 接口。

类型声明和说明不承诺与某个特定版本的 Tampermonkey、Greasemonkey 或 Violentmonkey 在所有边缘行为上完全一致。

3. 进度总量由浏览器决定

所有上传回调都会提供 loaded、total 和 lengthComputable，但浏览器不保证每次都能计算上传总大小。

用户脚本仍应在 lengthComputable === false 时使用不确定进度展示，而不能假设 total 始终有效。

建议审查重点

• hasUpload / canHaveUploadLifecycle 是否完整覆盖所有传输选择条件；
• 是否只有函数类型的上传回调会改变后台监听和跨域预检行为；
• 主请求与上传事件之间的完成状态、去重和竞态处理；
• upload.onload 内同步调用 abort() 时的事件顺序；
• 上传异常后再次调用 abort() 是否会保留真实的主请求错误类型；
• 强制 fetch 配置下的限制说明是否足够清晰；
• 新增公开类型是否符合项目现有 API 命名和兼容策略；
• worker 级 E2E profile 是否同时保证 CI 稳定性和测试状态隔离。

参考

https://wiki.greasespot.net/GM.xmlHttpRequest

Tampermonkey/tampermonkey#1429

violentmonkey/violentmonkey#2302

[cyfung1031]

按 PickInvariant 的 DELTA_AUDIT，对 base 3fc6ced2a16ca6abfbc7bfefaa66d1cc97343e34 → head ce39a4cb870cf457673f0e1318c3681e76209d3c 审查了上传生命周期启用条件、content→background 参数序列化、native XHR/fetch 分流、事件分发/abort、类型声明与测试。

结论：正常 native XHR 上传事件、字段映射、声明和去重逻辑基本覆盖，但以下跨层接缝仍有缺口：

• [P1，确认] mozAnon 参与了 content 侧 fetch 判定，却没有传到 background。 src/app/service/content/gm_api/gm_xhr.ts:150 用 details.anonymous ?? details.mozAnon 禁用上传生命周期，但 :234-247 序列化参数没有 mozAnon。因此 mozAnon: true 且未设置 anonymous 时，background src/pkg/utils/xhr/bg_gm_xhr.ts:254-264 看不到该值，可能选择 native XHR，并在 :449 设置 withCredentials = true；content 与 background 对匿名传输的判断相反，匿名请求可能继续带凭据。建议传递该字段，或统一由一个已序列化的 transport decision 驱动两侧。

• [P2，确认] truthy 非函数的 upload handler 会在事件到达时抛错。 src/app/service/content/gm_api/gm_xhr.ts:136-146 的启用判断只接受函数，但 :579 和 :805 使用 optional-call；例如 upload: { onprogress: true } 会启用其他函数 handler 后，在进度/收尾分发中尝试调用布尔值。结果是上传事件被丢弃，且异常可能打断 abort/loadend 收尾。建议分发时也用 typeof handler === "function" 保护，并补非函数值测试。

• [P2，确认/既有 body 接缝被本 PR 的 gate 暴露] hasUpload 可能与实际发送的 body 不一致。 src/app/service/content/gm_api/gm_xhr.ts:268-275 对 POST 的 object 编码结果判定存在请求体并设置 hasUpload: true；但无 Content-Type 时，background src/pkg/utils/xhr/bg_gm_xhr.ts:497-516 会把该 object 路径清成 null 后发送。此时 :401 仍绑定 xhr.upload，可能承担不必要的 CORS 预检，却没有真实上传生命周期。建议让 hasUpload 基于最终发送 body，或统一 body 编码与判定。

已检查：函数回调启用谓词、native XHR 监听绑定、事件名/进度字段、upload/main abort 顺序、loadend 去重、模板/英文/中文声明。未验证：真实浏览器的 CORS 预检、native upload error/timeout/loadend 时序及 E2E；PR 中的 worker profile 初始化调整不在本上传语义结论内。