From add5aa36c910ddf2225ffb29156cf93ca07f3597 Mon Sep 17 00:00:00 2001 From: Leexunhuan743 Date: Tue, 6 Oct 2026 19:42:54 +0800 Subject: [PATCH] =?UTF-8?q?fix(delete):=20=E7=BB=9F=E4=B8=80=E3=80=8CD1=20?= =?UTF-8?q?=E5=88=A0=E6=88=90=E5=8A=9F=20=3D=20=E4=B8=9A=E5=8A=A1=E6=88=90?= =?UTF-8?q?=E5=8A=9F=E3=80=8D=EF=BC=8CR2=20=E6=B8=85=E7=90=86=E5=A4=B1?= =?UTF-8?q?=E8=B4=A5=E7=95=99=E5=AD=A4=E5=84=BF?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 删除顺序仍是先 D1 后 R2(反转一旦失败就是整库悬空),改的是后半段的错误处理: 此前 R2 清理抛错会让已经删掉行的请求变成 500 —— 用户看到失败、数据其实没了, 重试也删不掉(行已不在),只会误导。 - src/historyOps.ts:deleteRecordsWorkingDirs 改 best-effort,内部 catch 后 打 '[cleanup] deferred R2 cleanup' 日志;clearAllHistory/purgeTrash 照常返回条数。 - src/ui/routes.ts:batch-purge 单条 R2 删失败不再把整批变 500(D1 删成功计入 purged, 目录失败只留日志,由孤儿阶段兜底)。 - test/fixes.test.ts:注入 Bucket.delete 抛错,验证 purgeTrash/clearAllHistory 仍返回 删除条数且行确实已删;阳性对照证明无故障时字节确实被清。 - docs/design.md §6:登记删除的成功语义。 --- docs/design.md | 5 ++- src/historyOps.ts | 25 +++++++++---- src/ui/routes.ts | 13 +++++-- test/fixes.test.ts | 87 ++++++++++++++++++++++++++++++++++++++++++++-- 4 files changed, 118 insertions(+), 12 deletions(-) diff --git a/docs/design.md b/docs/design.md index c6ad833..03152f6 100644 --- a/docs/design.md +++ b/docs/design.md @@ -151,7 +151,10 @@ negotiate 返回三种传输;连接最终落到单个 `SyncClipboardHub` DO。 - 唯一索引解决并发插入; - `UPDATE ... WHERE ID=? AND Version=?` 把乐观并发下推到 D1; - 批量写可合并 DO 子请求,但客户端仍收到逐条、保序的广播; -- 软删保留数据,硬删才清 R2;孤儿扫描必须把仍可恢复的回收站数据视为“有引用”。 +- 软删保留数据,硬删才清 R2;孤儿扫描必须把仍可恢复的回收站数据视为“有引用”; +- 删除的**成功语义**:D1 完成永久删除 = 业务删除成功;随后 R2 清理失败只留下孤儿对象 + (由清理任务的孤儿阶段回收)并打日志,不把已生效的删除改判成 500。顺序恒为“先 D1、后 R2”, + 绝不反过来(反转一旦失败就是整库悬空)。 ## 7. 资源边界 diff --git a/src/historyOps.ts b/src/historyOps.ts index 0166f02..5f3b2fe 100644 --- a/src/historyOps.ts +++ b/src/historyOps.ts @@ -42,19 +42,30 @@ export async function purgeTrash(env: Bindings): Promise { // 按记录集合清扫 R2 数据目录。 // +// **成功后语义统一:D1 完成永久删除 = 业务删除成功。** 本函数是删除之后的后半段,R2 清理失败 +// 只能留下孤儿目录(由清理任务的孤儿阶段回收,最长一轮),**不能**把一次已经生效的删除变成 500 —— +// 否则用户看到失败、数据其实没了,重试也删不掉(行已不在),只会误导。 +// 因此这里整体 best-effort:内部 catch 后打一条可观测日志,调用方照常返回删除条数。 +// // **跳过 hash 非法的行**:`workingDirPrefix` → `workingDirName` 对含路径分隔符的 hash 直接抛 -// (storage.ts 的 `assertHashForPath`,那是 key 构造的最后防线),而本函数在**删行之后**才被调用 -// ⇒ 不跳过就会「行已删掉、接口却报 500」,用户看到失败而数据其实没了、R2 残留还要等孤儿阶段。 -// 坏行只可能来自带外写入(三条写路径都拒这种 hash),它们的目录名也构造不出来 —— 漏掉不可惜, -// 孤儿阶段照样回收。 +// (storage.ts 的 `assertHashForPath`,那是 key 构造的最后防线)。坏行只可能来自带外写入 +// (三条写路径都拒这种 hash),它们的目录名也构造不出来 —— 漏掉不可惜,孤儿阶段照样回收。 async function deleteRecordsWorkingDirs( env: Bindings, entries: { type: ProfileType; hash: string }[], ): Promise { + const dirs = entries.filter((e) => isValidProfileHash(e.hash)).map((e) => workingDirPrefix(e.type, e.hash)); + if (dirs.length === 0) return; const { storage } = stores({ env }); - await storage.deleteHistoryDirs( - entries.filter((e) => isValidProfileHash(e.hash)).map((e) => workingDirPrefix(e.type, e.hash)), - ); + try { + await storage.deleteHistoryDirs(dirs); + } catch (err) { + // 行已经删掉了,这次失败只意味着数据目录要等孤儿阶段回收 ⇒ 记日志、不改判业务结果。 + console.warn('[cleanup] deferred R2 cleanup', { + dirs: dirs.length, + error: err instanceof Error ? err.message : String(err), + }); + } } export type HistoryUpdateResult = diff --git a/src/ui/routes.ts b/src/ui/routes.ts index c4b5397..e71fccb 100644 --- a/src/ui/routes.ts +++ b/src/ui/routes.ts @@ -15,6 +15,7 @@ import { issueSession, clearSession } from './session'; import { uiAuthMiddleware, authenticateUi } from './guard'; import { parseProfileType, parseHistoryRecordUpdateDto, historySizeMB } from '../serialization'; import { applyHistoryUpdate, clearAllHistory, purgeTrash } from '../historyOps'; +import { workingDirPrefix } from '../storage'; import { broadcastMany } from '../hub'; import { entityToDtoWire } from '../serialization'; import { addRecordDto } from '../profile'; @@ -725,8 +726,16 @@ export function createUiRoutes(): Hono<{ Bindings: Bindings }> { } // 行删掉了 ⇒ 顺手把它的数据目录清掉。**2026-09-22(ADR D29)起必需**:真回收站保留数据, // 不扫就等于把字节留给孤儿阶段(最长 20 分钟),而"彻底删除"的语义就是立刻没了。 - // 成本:每条 +1 次 R2 列举(目录不存在/为空时只有这一次),仍是本端点最便宜的那一段。 - await storage.deleteHistoryWorkingDir(ids.type!, ids.hash); + // **但 R2 清理失败不得把已生效的删除变成失败**:D1 删成功 = 业务成功,目录失败只留日志, + // 由孤儿阶段兜底。成本:每条 +1 次 R2 列举(目录不存在/为空时只有这一次)。 + try { + await storage.deleteHistoryWorkingDir(ids.type!, ids.hash); + } catch (err) { + console.warn('[cleanup] deferred R2 cleanup', { + dir: workingDirPrefix(ids.type!, ids.hash), + error: err instanceof Error ? err.message : String(err), + }); + } return null; }); let purged = 0; diff --git a/test/fixes.test.ts b/test/fixes.test.ts index 4759c0b..380c3ce 100644 --- a/test/fixes.test.ts +++ b/test/fixes.test.ts @@ -2,7 +2,7 @@ // - 纯逻辑:multipart / serialization / hash // - 服务层:profile.ts(用内存 stub 驱动 R2/D1 接口) // - 数据层:db.ts(用 node:sqlite + schema.sql 建真实 SQLite,验证 SQL 语义) -import { describe, expect, it } from 'vitest'; +import { describe, expect, it, vi } from 'vitest'; import { createHash } from 'node:crypto'; import { zipSync, strToU8, Zip, ZipPassThrough } from 'fflate'; import { createSqliteD1, readSchemaSql, type SqliteD1 } from './support/d1-sqlite'; @@ -19,7 +19,7 @@ import { R2Storage as RealR2Storage } from '../src/storage'; import { runCleanup } from '../src/cleanup'; import { createWebdavRoutes } from '../src/routes/webdav'; import { createHistoryRoutes } from '../src/routes/history'; -import { purgeTrash } from '../src/historyOps'; +import { purgeTrash, clearAllHistory } from '../src/historyOps'; import type { Bindings } from '../src/env'; const sha256 = (data: Uint8Array | string) => @@ -855,6 +855,8 @@ class FakeBucket { // 存**字节**(不是只存 size):`GET /file/{name}` 这类用例要断言回退后拿到的内容, // 而 `get()` 必须能交出可读的 body(`new Response(obj.body)` 需要真正的流)。 objects = new Map(); + /** 置为 true 时 `delete()` 抛错:注入 R2 清理失败,验证"已生效的删除不改判业务结果"。 */ + failDelete = false; async put(key: string, body: unknown): Promise { const bytes = @@ -871,6 +873,7 @@ class FakeBucket { return { size: bytes.length, body: new Blob([bytes]).stream() }; } async delete(keyOrKeys: string | string[]): Promise { + if (this.failDelete) throw new Error('injected R2 delete failure'); for (const k of Array.isArray(keyOrKeys) ? keyOrKeys : [keyOrKeys]) this.objects.delete(k); } async list(opts: { prefix?: string; cursor?: string } = {}) { @@ -1247,6 +1250,86 @@ describe('D29 · purgeTrash:只删已删除的行,并按同一集合清扫 R }); }); +describe('D29 · 删除成功后语义:R2 清理失败不改判业务结果(留孤儿给清理任务)', () => { + function fixture() { + const d1 = createSqliteD1(schemaSql); + const db = new HistoryDb(d1 as unknown as D1Database); + const bucket = new FakeBucket(); + const env = { DB: d1, R2: bucket, HUB: hubStub() } as unknown as Bindings; + return { d1, db, bucket, env }; + } + const rec = (hash: string, over: Partial = {}): HistoryRecordEntity => { + const now = Date.now(); + return { + userId: 'default_user', + type: ProfileType.File, + text: `${hash}.bin`, + size: 3, + transferDataFile: `${hash}.bin`, + filePaths: [`${hash}.bin`], + hash, + createTime: now, + lastAccessed: now, + lastModified: now, + stared: false, + pinned: false, + version: 0, + isDeleted: false, + ...over, + }; + }; + + it('purgeTrash:R2 删除抛错时仍返回删除条数,且行确实已删(不被 500 掩盖)', async () => { + const { db, bucket, env } = fixture(); + await db.insert(rec('T1', { isDeleted: true })); + await new RealR2Storage(bucket as unknown as R2Bucket).putHistory( + ProfileType.File, + 'T1', + 'T1.bin', + new Uint8Array([1]), + ); + bucket.failDelete = true; + + const warn = vi.spyOn(console, 'warn').mockImplementation(() => {}); + const deleted = await purgeTrash(env); + expect(deleted, 'D1 删成功即业务成功,R2 失败不得改判').toBe(1); + expect(await db.getByTypeAndHash(ProfileType.File, 'T1'), '行确实已删').toBeNull(); + expect(warn.mock.calls.some((c) => String(c[0]).includes('deferred R2 cleanup')), '打了可观测日志').toBe(true); + // 数据仍在(残留孤儿)⇒ 由清理任务的孤儿阶段回收 + expect(bucket.objects.has('history/File_T1/T1.bin'), '字节留给孤儿阶段').toBe(true); + }); + + it('clearAllHistory:R2 删除抛错时仍返回删除条数(顺序仍是先 D1 后 R2)', async () => { + const { db, bucket, env } = fixture(); + await db.insert(rec('A')); + await new RealR2Storage(bucket as unknown as R2Bucket).putHistory( + ProfileType.File, + 'A', + 'A.bin', + new Uint8Array([1]), + ); + bucket.failDelete = true; + + vi.spyOn(console, 'warn').mockImplementation(() => {}); + const deleted = await clearAllHistory(env); + expect(deleted).toBe(1); + expect(await db.getByTypeAndHash(ProfileType.File, 'A')).toBeNull(); + }); + + it('阳性对照:R2 正常时目录确实被清(证明上两条的"残留"是注入故障造成的)', async () => { + const { db, bucket, env } = fixture(); + await db.insert(rec('B', { isDeleted: true })); + await new RealR2Storage(bucket as unknown as R2Bucket).putHistory( + ProfileType.File, + 'B', + 'B.bin', + new Uint8Array([1]), + ); + expect(await purgeTrash(env)).toBe(1); + expect(bucket.objects.has('history/File_B/B.bin'), '无故障时字节应被清掉').toBe(false); + }); +}); + describe('D29 · POST /api/history 的软删同样保留数据(三条写路径同一语义)', () => { it('带 isDeleted=true 的 POST 只标记删除,**不**清 R2 目录', async () => { const d1 = createSqliteD1(schemaSql);