Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 4 additions & 1 deletion docs/design.md
Original file line number Diff line number Diff line change
Expand Up @@ -151,7 +151,10 @@ negotiate 返回三种传输;连接最终落到单个 `SyncClipboardHub` DO。
- 唯一索引解决并发插入;
- `UPDATE ... WHERE ID=? AND Version=?` 把乐观并发下推到 D1;
- 批量写可合并 DO 子请求,但客户端仍收到逐条、保序的广播;
- 软删保留数据,硬删才清 R2;孤儿扫描必须把仍可恢复的回收站数据视为“有引用”。
- 软删保留数据,硬删才清 R2;孤儿扫描必须把仍可恢复的回收站数据视为“有引用”;
- 删除的**成功语义**:D1 完成永久删除 = 业务删除成功;随后 R2 清理失败只留下孤儿对象
(由清理任务的孤儿阶段回收)并打日志,不把已生效的删除改判成 500。顺序恒为“先 D1、后 R2”,
绝不反过来(反转一旦失败就是整库悬空)。

## 7. 资源边界

Expand Down
25 changes: 18 additions & 7 deletions src/historyOps.ts
Original file line number Diff line number Diff line change
Expand Up @@ -42,19 +42,30 @@ export async function purgeTrash(env: Bindings): Promise<number> {

// 按记录集合清扫 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<void> {
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 =
Expand Down
13 changes: 11 additions & 2 deletions src/ui/routes.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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';
Expand Down Expand Up @@ -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;
Expand Down
87 changes: 85 additions & 2 deletions test/fixes.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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';
Expand All @@ -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) =>
Expand Down Expand Up @@ -855,6 +855,8 @@ class FakeBucket {
// 存**字节**(不是只存 size):`GET /file/{name}` 这类用例要断言回退后拿到的内容,
// 而 `get()` 必须能交出可读的 body(`new Response(obj.body)` 需要真正的流)。
objects = new Map<string, Uint8Array>();
/** 置为 true 时 `delete()` 抛错:注入 R2 清理失败,验证"已生效的删除不改判业务结果"。 */
failDelete = false;

async put(key: string, body: unknown): Promise<void> {
const bytes =
Expand All @@ -871,6 +873,7 @@ class FakeBucket {
return { size: bytes.length, body: new Blob([bytes]).stream() };
}
async delete(keyOrKeys: string | string[]): Promise<void> {
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 } = {}) {
Expand Down Expand Up @@ -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> = {}): 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);
Expand Down
Loading