feat(singleflight): 并发相同调用去重（进程内合并 + 跨实例表协调）

[Wudarensheng]

feat(singleflight): 并发相同调用去重（进程内合并 + 跨实例表协调）

Summary / 摘要

一个部署会同时存在多个 isolate，进程内 Map 无法跨实例合并重复调用，导致同一目录列表 / 元信息的并发请求各自打一次上游网盘 API —— 这正是限流、封号、CPU 超时的主要来源。本 PR 新增 singleflight，做两级去重。

用户可感知的行为变化

• 同一存储、同一路径的并发读请求（目录列表 / 元信息）只向上游发起一次，其余并发请求等待并复用同一结果。
• 新增 x_singleflight 表：仅当存储后端为 SQL 型（D1 / MySQL / Durable Objects）时，由驱动在初始化时自动创建（CREATE TABLE IF NOT EXISTS，幂等）；非 SQL 后端（KV / Blob / 内存）不建表。
• 新增 5 个环境变量，默认值即可工作，不配置也能跑；SINGLEFLIGHT=off 可完全退回改动前的行为。
• /api/debug/info 响应新增 singleflight 字段，暴露去重统计（executed / coalesced / shared / fallback / active），便于确认跨实例协调是否真的生效。

重要实现变化

两级去重：

• L1 进程内：Map<key, Promise> 合并，所有模式生效，零成本
• L2 跨实例：数据库表 x_singleflight 抢锁 + 结果共享（仅 db 模式）
  • 抢锁靠 INSERT OR IGNORE（MySQL 为 INSERT IGNORE）+ 回读 owner 确认，不依赖事务
  • 执行者按 lockTtl / 3 心跳续租；崩溃后锁到期可被其他实例接管
  • 等待方轮询读取结果；等待超时后自行执行，不会把请求挂死

模式由 SINGLEFLIGHT 控制（auto / db / memory / off），默认 auto：有 SQL 库（d1 / mysql / do）时用表协调，否则退回进程内合并。

关键设计取舍：

• 不做结果缓存。 只有「到达时观察到执行者处于 running」的调用才复用结果；新到达的调用会回收旧记录并重新执行。因此不会出现「删除文件后刷新仍看到被删文件」这类脏读（handoffMs 只是等待方读取结果的交接窗口，不是 TTL 缓存）。
• 业务异常与协调异常分流。 业务函数抛出的异常原样抛出且不重试；协调层异常（表缺失 / DB 超时 / 结果不可序列化 / 执行者崩溃）一律降级为「各自执行一次」，业务不会失败。
• x_singleflight 属运行时数据，刻意不加入 TABLE_NAMES。 否则 sqlFormat.save() 的整表 DELETE 会在每次保存配置时清空在途记录（与 kv 表同样处理，使用独立 DDL 常量）。

接入范围

internal/op/storage.ts 的 listItems / getItem（拆出 listItemsResolved / getItemResolved），去重键为 fs.list|<storage.id>:<storage.modified>:<virtualPath>。

因此一次接入即覆盖：/fs/list、/fs/get、/fs/dir、搜索、WebDAV、MCP。

配置 / 存储 / 兼容性

变量	默认值	说明
SINGLEFLIGHT	auto	auto / db / memory / off
SINGLEFLIGHT_HANDOFF_MS	1000	结果交接窗口（ms），供正在等待的并发实例读取
SINGLEFLIGHT_LOCK_TTL_MS	30000	执行者持锁上限（ms），期间按 1/3 周期续租
SINGLEFLIGHT_POLL_MS	50	等待方轮询间隔（ms）
SINGLEFLIGHT_WAIT_MS	15000	等待方最长等待（ms），超时后自行执行

• 配置文件已同步：.env.example、.dev.vars.example、wrangler.jsonc 的 vars、package.json 的 cloudflare.bindings、README「配置 → 并发去重（singleflight）」。

• 与 Go 后端共享同一物理库时互不影响：Go 无此表，本 PR 也不读写 Go 的任何表。

• 兼容性：纯增量。既有存储格式、迁移行为、公开 API 均未改动。

• This PR has breaking changes.
  / 此 PR 包含破坏性变更。

• This PR changes public API, config, storage format, or migration behavior.
  / 此 PR 修改了公开 API、配置、存储格式或迁移行为。
  （新增 5 个环境变量；SQL 后端会新建 x_singleflight 表。均为增量，无破坏性。）

• This PR requires corresponding changes in related repositories.
  / 此 PR 需要关联仓库同步修改。

Related repository PRs / 关联仓库 PR:

• OpenList: 无（x_singleflight 是 TS 侧「多 isolate」模型专有；Go 单进程只需进程内合并）
• OpenList-Docs:

Related Issues / 关联 Issue

无。

Testing / 测试

平台：Windows + Node 22 / tsx（仓库自带的 npm run 脚本）。

• npx tsc -p tsconfig.json --noEmit —— 无新增报错
• npm run test:pkg（含新增 src/backend/pkg/singleflight.test.ts，17 例）—— 22/22 通过
• npx tsx --test src/backend/internal/model/store/store.test.ts —— 12/12 通过
• npm run test:drivers —— 111/111 通过
• go test ./... —— 不适用（本仓库为 TypeScript / Cloudflare Workers 实现）
• Manual test / 手动测试：未做真机部署验证（需要 D1 / MySQL 实例与并发压测）。建议合入后在真实部署上核对 /api/debug/info 的 singleflight.shared 是否随并发上升。

新增单测覆盖：L1 并发合并、错误传播与在途表清理、off 模式、L2 结果共享、防脏读回归（到达时记录已结束必须重新执行）、handoffMs=0 立即释放、业务异常不触发重试、协调层异常降级、等待超时自行执行、auto 模式探测、SQL 方言分支、环境变量覆盖与非法值回退。

已知且与本次无关的既有问题（在基线 feat/pg-db 上同样存在，可另行处理）：

• tsc 2 个报错：src/backend/internal/model/db_cipher.test.ts:187-188（createFieldCipher 实参 string 与形参 DbCipher 不匹配）
• npm run test:server 125/129：default_credentials.test.ts 3 例、seed.test.ts 1 例
• npm run test:regress 39/40：scripts/_regress.mjs 仍引用已删除的 getStoreConfigError

Checklist / 检查清单

• I have read CONTRIBUTING.
  / 我已阅读 CONTRIBUTING。
• I confirm this contribution follows the repository license, contribution policy, and code of conduct.
  / 我确认此贡献符合仓库许可证、贡献规范和行为准则。
• I have formatted the changed code with gofmt, go fmt, or prettier where applicable.
  / 我已按适用情况使用 gofmt、go fmt 或 prettier 格式化变更代码。
  （两个新增文件已通过 prettier --check；被修改的既有文件保持原状、只做最小增量改动 —— 这些文件在仓库基线上本就不符合 prettier --check，未整体重排以免污染 diff。）
• I have requested review from relevant maintainers or code owners where applicable.
  / 我已在适用情况下请求相关维护者或代码所有者审查。

AI Disclosure / AI 使用声明

• This PR includes AI-assisted content.
  / 此 PR 包含 AI 辅助内容。

Tools used / 使用工具:

• ChatGPT
• Codex
• GitHub Copilot
• Claude
• Gemini
• Other (please specify) / 其他（请注明）: WorkBuddy AI

Usage scope / 使用范围:

• Code generation / 代码生成

• Refactoring / 重构

• Documentation / 文档

• Tests / 测试

• Translation / 翻译

• Review assistance / 审查辅助

• I have reviewed and validated all AI-assisted content included in this PR.
  / 我已审核并验证此 PR 中的所有 AI 辅助内容。

• I have ensured that all AI-assisted commits include Co-Authored-By attribution.
  / 我已确保所有 AI 辅助提交都包含 Co-Authored-By 归属信息。

• I can reproduce all AI-assisted content included in this PR without any AI tools.
  / 我可以在没有任何 AI 工具的情况下重现此 PR 中包含的所有 AI 辅助内容。

[pikachuren]

评审结论：可以合并（附 2 条运行成本建议）

核心并发逻辑我逐段核对过，设计站得住：

• 抢锁 = DELETE(清过期/已结束) → INSERT OR IGNORE → 回读 owner 确认，不依赖事务；
  schema.ts 中 SQLite / MySQL / Durable Object 三方言的 DDL 都把 key 设为 PRIMARY KEY
  （这是 INSERT OR IGNORE 生效的前提，已核对）。
• 执行者按 lockTtl/3 心跳续租；迟到写回受 WHERE key=? AND owner=? 保护，不会覆盖接管者的结果。
• L1（进程内 coalesce）确实包在 L2 外层（singleflight() → coalesce(...) → dbFlight），
  因此「同 isolate 内 owner 都是同一个 INSTANCE_ID」这个隐患被 L1 消掉了，不会出现同实例双 leader。
• 「不把交接记录当结果缓存」（只有到达时观察到 running 才复用）确实避免了「删了文件刷新还在」的脏读。
• 协调层异常一律降级为「各自执行一次」，业务不会因协调失败而失败 —— 失败方向正确。

非阻塞建议

1. 运行成本建议在合并前定个预期：SINGLEFLIGHT_POLL_MS=50 × SINGLEFLIGHT_WAIT_MS=15000 × 最多 3 轮
   ≈ 单个等待请求最多 ~900 次轮询 SELECT，再加每次抢锁的 3 条语句。在 D1 上这会明显消耗 subrequest
   配额与 CPU，可能比它想省的上游调用更贵。建议放宽默认 POLL_MS（如 200~300ms）、下调轮数，或在文档写明成本。
2. 索引名没带表前缀：CREATE INDEX IF NOT EXISTS idx_singleflight_expires 是硬编码名，而表名走
   getTablePrefix(env)。在多部署共用一个物理库（靠前缀隔离）的场景下，第二个部署的建索引会被静默跳过。
   建议索引名也带前缀。
3. 次要：MySQL 侧去重键含完整虚拟路径却是 VARCHAR(512) PRIMARY KEY，深层路径可能超长；另外
   x_singleflight 的行只在「同一 key 有新请求到达」时才回收，不同 key 的残留会长期堆积
   （既然已经为 expires_at 建了索引，补个定期清理更完整）。

说明

作者已如实标注「未做真机部署验证」并列出各仓库基线失败，这点很好。提醒：描述中引用的部分
「基线既有失败」（如 seed.test.ts 的 CAS 字段断言）在今天的 main 上已经修好了，rebase 后建议重跑基线。

---

本评论由 AI 辅助的自动化评审生成，基于对该 PR 当前 head 提交的源码核对。标注「实测复现」的结论已在本地用真实源码（打补丁后）跑脚本验证；其余为代码走查结论。请以人工复核为准。