@davideasden/pi-undo 0.4.0 → 0.4.1
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/README.md +3 -1
- package/docs/native-performance.md +19 -0
- package/native/bin/pi-undo-fs-win32-arm64.exe +0 -0
- package/native/bin/pi-undo-fs-win32-x64.exe +0 -0
- package/package.json +1 -1
- package/src/native-capabilities.ts +14 -0
- package/src/native-directory-scan.ts +3 -2
- package/src/restore-engine.ts +20 -9
- package/src/root-discovery.ts +7 -5
package/README.md
CHANGED
|
@@ -167,6 +167,8 @@ recovery_required
|
|
|
167
167
|
|
|
168
168
|
### Performance Notes
|
|
169
169
|
|
|
170
|
+
**Linux 共享盘:** 可以直接在 Parallels 的 `/media/psf` 下使用默认配置,不需要搬动项目或设置 `PI_UNDO_DISABLE_NATIVE=1`。工作区根位于 FUSE 时,每次完整枚举目录,不依赖宿主机是否投递 inotify 事件。覆盖已有普通文件时,若其父目录位于 FUSE,整批在写入前选择现有的 TypeScript 事务日志路径;元数据检查仍可使用原生 helper。见[共享盘实测](docs/native-performance.md#linux-共享盘)。
|
|
171
|
+
|
|
170
172
|
普通文件恢复在持有 workspace 独占锁时,先逐项核验 changedPaths 中的叶子文件;若与 checkpoint source 一致,就直接复用 manifest,避免额外 scoped capture 和全目录扫描。目录 scope、内容不匹配或 source 无法证明时仍走 scoped safety capture。成功路径保留 `restore-pre` 与 `restore-post` 两次 topology 检查,并继续执行 scope 内可见路径校验;锁内省略其后的重复 topology 扫描。native helper 仍不跟随符号链接地扫描 ignored 目录中的嵌套仓库;没有默认跳过 `node_modules`,也没有使用 TTL 缓存。
|
|
171
173
|
|
|
172
174
|
原生恢复可处理已有父目录中的普通文件删除、覆盖、创建及混合计划。`restore-files-v2` 覆盖子目录删除和混合 mutation;`restore-files-v3` 会把分散在大量父目录中的文件拆成多个批次,每批最多打开 128 个非根父目录句柄。旧 helper、缺少二进制、目录操作、类型替换及单条路径深度超过句柄预算时继续走 TypeScript 路径。durable pack、逐项内容校验、no-clobber 与恢复依据均保留。
|
|
@@ -218,7 +220,7 @@ Performance gains come from:
|
|
|
218
220
|
- **Indexed mutation path checks** — `MutationPathIndex` replaces the per-target-path `[...deletePaths, ...writePaths].some(...)` scan (10k × 10k ≈ 962 ms → < 1 ms).
|
|
219
221
|
- **Deduped batch blob reads** — object IDs are deduplicated with a `Set` instead of `Array.includes` (10k unique blobs ≈ 101 ms → 2.2 ms).
|
|
220
222
|
- **Shared, parallel parent validation** — native metadata inspect validates the deduplicated parent set once per request with 32-way concurrency (10k deep paths 111.7 ms → 71.0 ms).
|
|
221
|
-
-
|
|
223
|
+
- **常驻目录缓存**:使用 `--serve` 时可从磁盘 v2 缓存启动,当前服务空闲约 10 秒后退出。Linux FUSE 工作区不使用此缓存。
|
|
222
224
|
- **Racy-window baseline skip** — settled capture skips the guaranteed-failing `isBaselineFresh` probe within 2 s after a restore, removing ~227–240 ms from the settlement path.
|
|
223
225
|
- **Transferred pack payloads** — the restore path hands pack ownership of its freshly read blobs instead of copying them (64 MiB benchmark: +64.0 MiB → +0.01 MiB extra ArrayBuffers, +2.3 MiB RSS), and the pack checksum is computed during the write pass.
|
|
224
226
|
|
|
@@ -1,5 +1,24 @@
|
|
|
1
1
|
# 原生目录扫描与普通文件恢复性能验证
|
|
2
2
|
|
|
3
|
+
## Linux 共享盘
|
|
4
|
+
|
|
5
|
+
Linux arm64、Node 23.11.1、Pi 1.4.0 SDK。工作区和会话目录均放在同一 Parallels `fuse.prl_fsd` 挂载上。3,000 个 ignored 依赖包(6,002 个目录),每次只覆盖一个根目录文件。表中为每组连续三次操作的中位数;成功的用例同时断言文件内容与 undo/redo 栈。
|
|
6
|
+
|
|
7
|
+
| 同一挂载上的配置 | 撤销 | 重做 |
|
|
8
|
+
| --- | ---: | ---: |
|
|
9
|
+
| `c73bd40f` 默认 | `recovery_required`,无有效耗时 | 未执行 |
|
|
10
|
+
| `c73bd40f` 全局禁用 native | 5.54 s | 3.75 s |
|
|
11
|
+
| 仅将 FUSE 覆盖切换到事务日志 | 5.58 s | 5.35 s |
|
|
12
|
+
| 同时按目录项扫描,首次 / 复测 | 3.27 / 3.90 s | 3.25 / 3.88 s |
|
|
13
|
+
|
|
14
|
+
失败的单文件用例在 `renameat2(RENAME_NOREPLACE)` 处返回 `EINVAL`。现在在预制 pack 和真正应用计划前,分别用 `statfs` 检查待覆盖普通文件的父目录(去重、有界并发);Linux FUSE 或无法判断时,整批走原有 WAL。它是保守的挂载类型判断,不是在用户目录创建文件做能力探测;纯新增、纯删除不依赖这次 rename,保留原选择。已进入 mutation 的事务仍使用原恢复流程,不在失败后换实现。
|
|
15
|
+
|
|
16
|
+
工作区根位于 Linux FUSE 时不启动 `--serve`,TypeScript 每次完整枚举目录,从枚举结果挑选可能含 `.git` 的目录再检查,不对每个普通目录单独查询 `.git`。仍遍历 ignored 目录,并在枚举前后复核目录路径。两次实测每轮撤销均执行两次拓扑发现。完整快照仍须通过 Git 枚举 ignored 叶子。未在 Windows 或其他 FUSE 驱动上实测,不把本机数据当作性能保证。
|
|
17
|
+
|
|
18
|
+
复现:将 `TMPDIR` 指向共享盘上工作区外的临时目录,运行 `PI_UNDO_LARGE_WORKSPACE=1 npx vitest run test/large-workspace.test.ts -t '3000 个依赖包,修改 1 个文件'`。不指定 `TMPDIR` 时夹具通常在 `/tmp` 建工作区,测不到共享盘。
|
|
19
|
+
|
|
20
|
+
## 历史基准
|
|
21
|
+
|
|
3
22
|
本轮实现目录项缓存与 scoped restore 的可见路径检查;普通一次性扫描仍会逐个打开、核验工作区内的目录,宽目录最多使用 16 个有界 worker 并行处理。常驻 `--serve` 在 macOS 上使用 FSEvents 收集变更父目录,只重新枚举受影响祖先并合并局部 cache;无变化请求复用驻留 cache,事件丢失、监听停止或扫描竞争时回退完整校验。
|
|
4
23
|
|
|
5
24
|
## Durable pack 准备与批量写入
|
|
Binary file
|
|
Binary file
|
package/package.json
CHANGED
|
@@ -1,6 +1,20 @@
|
|
|
1
|
+
import { statfs } from "node:fs/promises";
|
|
2
|
+
|
|
1
3
|
import { GitRunError, runSupervisedProcess } from "./git-runner.ts";
|
|
2
4
|
import { checkOperation, OperationError, operationProcessOptions, rethrowOperationFailure } from "./operation-context.ts";
|
|
3
5
|
|
|
6
|
+
const LINUX_FUSE_SUPER_MAGIC = 0x65735546;
|
|
7
|
+
|
|
8
|
+
/** Linux FUSE 不保证支持防覆盖 rename,也不保证宿主机变更会产生客户机 inotify 事件。 */
|
|
9
|
+
export async function allowsNativeMountFastPaths(directory: string): Promise<boolean> {
|
|
10
|
+
if (process.platform !== "linux") return true;
|
|
11
|
+
try {
|
|
12
|
+
return (await statfs(directory)).type !== LINUX_FUSE_SUPER_MAGIC;
|
|
13
|
+
} catch {
|
|
14
|
+
return false;
|
|
15
|
+
}
|
|
16
|
+
}
|
|
17
|
+
|
|
4
18
|
/** 在私有目录探测,防止旧 helper 把 --capabilities 当成工作区里的请求文件。 */
|
|
5
19
|
export async function probeNativeCapabilities(
|
|
6
20
|
executable: string,
|
|
@@ -4,7 +4,7 @@ import { tmpdir } from "node:os";
|
|
|
4
4
|
import { isAbsolute, join, relative, resolve, sep } from "node:path";
|
|
5
5
|
|
|
6
6
|
import { GitRunError, runSupervisedProcess } from "./git-runner.ts";
|
|
7
|
-
import { probeNativeCapabilities } from "./native-capabilities.ts";
|
|
7
|
+
import { allowsNativeMountFastPaths, probeNativeCapabilities } from "./native-capabilities.ts";
|
|
8
8
|
import { nativeExecutable } from "./native-restore.ts";
|
|
9
9
|
import { checkOperation, configuredTimeout, OperationError, operationProcessOptions } from "./operation-context.ts";
|
|
10
10
|
import { ResidentScanClient } from "./resident-scan-client.ts";
|
|
@@ -84,6 +84,7 @@ export class NativeDirectoryScanner implements NativeDirectoryScanPort {
|
|
|
84
84
|
}
|
|
85
85
|
|
|
86
86
|
private async prewarmResident(workspaceRoot: string): Promise<void> {
|
|
87
|
+
if (!await allowsNativeMountFastPaths(workspaceRoot)) return;
|
|
87
88
|
const temporaryRoot = await realpath(tmpdir()).catch(() => undefined);
|
|
88
89
|
if (temporaryRoot === undefined || isPathInside(workspaceRoot, temporaryRoot)) return;
|
|
89
90
|
const requestDirectory = await mkdtemp(join(temporaryRoot, "pi-undo-native-serve-probe-"));
|
|
@@ -118,7 +119,7 @@ export class NativeDirectoryScanner implements NativeDirectoryScanPort {
|
|
|
118
119
|
|
|
119
120
|
async scan(workspaceRoot: string): Promise<NativeDirectoryScan | undefined> {
|
|
120
121
|
checkOperation();
|
|
121
|
-
if (this.executable === undefined) return undefined;
|
|
122
|
+
if (this.executable === undefined || !await allowsNativeMountFastPaths(workspaceRoot)) return undefined;
|
|
122
123
|
const pendingPrewarm = this.prewarmInFlight;
|
|
123
124
|
if (pendingPrewarm?.workspaceRoot === workspaceRoot) await pendingPrewarm.promise;
|
|
124
125
|
checkOperation();
|
package/src/restore-engine.ts
CHANGED
|
@@ -22,6 +22,7 @@ import {
|
|
|
22
22
|
import { assertManifest, assertOperationId, canonicalJson, checksum } from "./encoding.ts";
|
|
23
23
|
import { MutationJournal } from "./mutation-journal.ts";
|
|
24
24
|
import { allCompleted, checkOperation, rethrowOperationFailure, isUnconfirmedExit, operationFailure, withRecoveryBudget } from "./operation-context.ts";
|
|
25
|
+
import { allowsNativeMountFastPaths } from "./native-capabilities.ts";
|
|
25
26
|
import { createNativeFileBatch, nativeRestoreCapability } from "./native-restore.ts";
|
|
26
27
|
import { recoverPackedMutations } from "./packed-recovery.ts";
|
|
27
28
|
import type { ManifestId, RestorePath, SnapshotManifest, SnapshotRoot } from "./model.ts";
|
|
@@ -515,7 +516,7 @@ export class RestoreEngine {
|
|
|
515
516
|
// durable pack 的 blob 读取和编码可能持续一段时间;保留已完成的 plan/path 表,
|
|
516
517
|
// 让用户在此窗口触发 undo 时复用前序准备结果,而不是重新 listTree。
|
|
517
518
|
this.rememberPreparedPlan(plan, prepared.currentPaths, prepared.targetPaths);
|
|
518
|
-
if (!this.canUseNativeFilePlan(plan, prepared.currentPaths, prepared.targetPaths)) return;
|
|
519
|
+
if (!await this.canUseNativeFilePlan(plan, prepared.currentPaths, prepared.targetPaths)) return;
|
|
519
520
|
const cacheRoot = await this.store.durableCacheDirectory();
|
|
520
521
|
const cacheOpId = `cache-${plan.planDigest}`;
|
|
521
522
|
const cacheJournal = new MutationJournal(
|
|
@@ -1103,7 +1104,7 @@ export class RestoreEngine {
|
|
|
1103
1104
|
!compatibilityMode &&
|
|
1104
1105
|
options.deferDurability === true &&
|
|
1105
1106
|
options.forceTargetArtifactSync !== true &&
|
|
1106
|
-
this.canUseNativeFilePlan(plan, currentPaths, targetPaths)
|
|
1107
|
+
await this.canUseNativeFilePlan(plan, currentPaths, targetPaths)
|
|
1107
1108
|
) {
|
|
1108
1109
|
try {
|
|
1109
1110
|
const cached = this.durablePackCache.get(plan.planDigest);
|
|
@@ -1169,10 +1170,7 @@ export class RestoreEngine {
|
|
|
1169
1170
|
);
|
|
1170
1171
|
}
|
|
1171
1172
|
const durablePackEnabled = durablePack !== undefined;
|
|
1172
|
-
if (
|
|
1173
|
-
nativeFileBatch !== undefined && durablePack !== undefined &&
|
|
1174
|
-
this.canUseNativeFilePlan(plan, currentPaths, targetPaths)
|
|
1175
|
-
) {
|
|
1173
|
+
if (nativeFileBatch !== undefined && durablePack !== undefined) {
|
|
1176
1174
|
if (!await visiblePreflight) {
|
|
1177
1175
|
return { code: "restore_failed_safe", verifiedPaths: 0, totalPaths: 0 };
|
|
1178
1176
|
}
|
|
@@ -1275,11 +1273,11 @@ export class RestoreEngine {
|
|
|
1275
1273
|
}
|
|
1276
1274
|
}
|
|
1277
1275
|
|
|
1278
|
-
private canUseNativeFilePlan(
|
|
1276
|
+
private async canUseNativeFilePlan(
|
|
1279
1277
|
plan: RestorePlan,
|
|
1280
1278
|
currentPaths: ReadonlyMap<string, OwnedPath>,
|
|
1281
1279
|
targetPaths: ReadonlyMap<string, OwnedPath>,
|
|
1282
|
-
): boolean {
|
|
1280
|
+
): Promise<boolean> {
|
|
1283
1281
|
if (plan.deletePaths.length + plan.writePaths.length === 0) return false;
|
|
1284
1282
|
if (process.platform === "win32" && plan.deletePaths.length > 0) return false;
|
|
1285
1283
|
if (!plan.deletePaths.every((path) =>
|
|
@@ -1288,7 +1286,20 @@ export class RestoreEngine {
|
|
|
1288
1286
|
targetPaths.get(path)?.entry.kind === "file" &&
|
|
1289
1287
|
(currentPaths.get(path) === undefined || currentPaths.get(path)?.entry.kind === "file"))) return false;
|
|
1290
1288
|
const paths = [...plan.deletePaths, ...plan.writePaths];
|
|
1291
|
-
|
|
1289
|
+
if (process.platform === "win32") return true;
|
|
1290
|
+
if (paths.some((path) => strictPathAncestors(path).length > 128)) return false;
|
|
1291
|
+
if (process.platform !== "linux") return true;
|
|
1292
|
+
// 只有覆盖已有文件才用 renameat2。按实际父目录判断,以覆盖工作区内的嵌套挂载;
|
|
1293
|
+
// 不跨操作缓存结果,预制 pack 之后挂载也可能变化。
|
|
1294
|
+
const parents = [...new Set(plan.writePaths.filter((path) => currentPaths.has(path))
|
|
1295
|
+
.map((path) => dirname(path)))];
|
|
1296
|
+
for (let start = 0; start < parents.length; start += RESTORE_FILE_PREPARE_CONCURRENCY) {
|
|
1297
|
+
checkOperation();
|
|
1298
|
+
const supported = await allCompleted(parents.slice(start, start + RESTORE_FILE_PREPARE_CONCURRENCY)
|
|
1299
|
+
.map((parent) => allowsNativeMountFastPaths(this.absolutePath(parent))));
|
|
1300
|
+
if (supported.includes(false)) return false;
|
|
1301
|
+
}
|
|
1302
|
+
return true;
|
|
1292
1303
|
}
|
|
1293
1304
|
|
|
1294
1305
|
private async applyNativeFilePlan(
|
package/src/root-discovery.ts
CHANGED
|
@@ -176,14 +176,16 @@ export class RootDiscovery {
|
|
|
176
176
|
): Promise<Array<{ readonly path: string; readonly inspect: true }>> {
|
|
177
177
|
checkOperation();
|
|
178
178
|
if (!await isSafeDirectory(candidate.path, workspaceIdentity)) return [];
|
|
179
|
-
if (candidate.inspect) {
|
|
180
|
-
const inspection = await this.inspectRepository(candidate.path, workspaceIdentity);
|
|
181
|
-
this.recordInspection(workspaceIdentity, inspection, activeRoots);
|
|
182
|
-
if (!await isSafeDirectory(candidate.path, workspaceIdentity)) return [];
|
|
183
|
-
}
|
|
184
179
|
checkOperation();
|
|
185
180
|
const entries = await readdir(candidate.path, { withFileTypes: true });
|
|
186
181
|
if (!await isSafeDirectory(candidate.path, workspaceIdentity)) return [];
|
|
182
|
+
// 使用这次枚举识别候选;遇到大小写变体仍由文件系统对 .git 的实际查找决定。
|
|
183
|
+
if (candidate.inspect && entries.some((entry) => entry.name.toLowerCase() === ".git")) {
|
|
184
|
+
checkOperation();
|
|
185
|
+
const inspection = await this.inspectRepository(candidate.path, workspaceIdentity);
|
|
186
|
+
if (!await isSafeDirectory(candidate.path, workspaceIdentity)) return [];
|
|
187
|
+
this.recordInspection(workspaceIdentity, inspection, activeRoots);
|
|
188
|
+
}
|
|
187
189
|
return entries
|
|
188
190
|
.filter((entry) => entry.name !== ".git" && !entry.isSymbolicLink() && entry.isDirectory())
|
|
189
191
|
.map((entry) => ({ path: join(candidate.path, entry.name), inspect: true as const }));
|