@filen/sync 0.2.1 → 0.3.1

package/tests/conformance/virtual-fs.test.ts

@@ -0,0 +1,213 @@
+import { describe, it, expect, beforeAll, afterAll } from "vitest"
+import fsExtra from "fs-extra"
+import os from "os"
+import pathModule from "path"
+import FastGlob from "fast-glob"
+import { createVirtualFS, type VfsSpec } from "../fakes/virtual-fs"
+import { type SyncFS } from "../../src/lib/environment"
+
+/**
+ * These tests are the backstop for the in-memory virtual filesystem: they assert
+ * that it behaves like a real OS filesystem for exactly the semantics the sync
+ * engine relies on (inode identity, timestamps, recursive ensureDir, symlink
+ * detection, fast-glob enumeration). They run with REAL timers on purpose.
+ */
+
+const UTIMES_TARGET = new Date("2020-06-15T12:00:00.000Z")
+const UTIMES_TARGET_SEC = Math.floor(UTIMES_TARGET.getTime() / 1000)
+
+type FsProbe = {
+	inoStable: boolean
+	inoAfterRename: number
+	inoBeforeRename: number
+	inoAfterMove: number
+	inoBeforeMove: number
+	inoRecreateBefore: number
+	inoRecreateAfter: number
+	mtimeMsAfterWrite: number
+	birthtimeMsAfterWrite: number
+	mtimeSecAfterUtimes: number
+	nestedDirsAreDirectories: boolean
+}
+
+/**
+ * Exercise the engine-relevant subset of an fs surface under `root` and report
+ * what was observed, so the real and virtual implementations can be compared.
+ */
+async function probe(fs: SyncFS, root: string): Promise<FsProbe> {
+	// Stable inode across two stats of the same file.
+	const a = pathModule.join(root, "a.txt")
+	await fs.writeFile(a, "alpha", { encoding: "utf-8" })
+	const aStat1 = await fs.stat(a)
+	const aStat2 = await fs.stat(a)
+
+	// Inode preserved across rename within the same directory.
+	const b = pathModule.join(root, "b.txt")
+	const b2 = pathModule.join(root, "b-renamed.txt")
+	await fs.writeFile(b, "bravo", { encoding: "utf-8" })
+	const inoBeforeRename = (await fs.stat(b)).ino
+	await fs.rename(b, b2)
+	const inoAfterRename = (await fs.stat(b2)).ino
+
+	// Inode preserved across a move into another directory.
+	const sub = pathModule.join(root, "sub")
+	await fs.ensureDir(sub)
+	const c = pathModule.join(root, "c.txt")
+	const c2 = pathModule.join(sub, "c.txt")
+	await fs.writeFile(c, "charlie", { encoding: "utf-8" })
+	const inoBeforeMove = (await fs.stat(c)).ino
+	await fs.move(c, c2, { overwrite: true })
+	const inoAfterMove = (await fs.stat(c2)).ino
+
+	// Fresh inode after delete + recreate at the same path.
+	const d = pathModule.join(root, "d.txt")
+	await fs.writeFile(d, "delta", { encoding: "utf-8" })
+	const inoRecreateBefore = (await fs.stat(d)).ino
+	await fs.rm(d, { force: true, recursive: true })
+	await fs.writeFile(d, "delta-2", { encoding: "utf-8" })
+	const inoRecreateAfter = (await fs.stat(d)).ino
+
+	// Timestamps populated on write; utimes updates mtime.
+	const e = pathModule.join(root, "e.txt")
+	await fs.writeFile(e, "echo", { encoding: "utf-8" })
+	const eStat = await fs.stat(e)
+	await fs.utimes(e, UTIMES_TARGET, UTIMES_TARGET)
+	const eStatAfter = await fs.stat(e)
+
+	// Recursive ensureDir.
+	const deep = pathModule.join(root, "x", "y", "z")
+	await fs.ensureDir(deep)
+	const deepStat = await fs.stat(deep)
+	const midStat = await fs.stat(pathModule.join(root, "x", "y"))
+
+	return {
+		inoStable: aStat1.ino === aStat2.ino,
+		inoBeforeRename,
+		inoAfterRename,
+		inoBeforeMove,
+		inoAfterMove,
+		inoRecreateBefore,
+		inoRecreateAfter,
+		mtimeMsAfterWrite: eStat.mtimeMs,
+		birthtimeMsAfterWrite: eStat.birthtimeMs,
+		mtimeSecAfterUtimes: Math.floor(eStatAfter.mtimeMs / 1000),
+		nestedDirsAreDirectories: deepStat.isDirectory() && midStat.isDirectory()
+	}
+}
+
+describe("virtual filesystem conformance", () => {
+	let realRoot: string
+	let realProbe: FsProbe
+	let virtualProbe: FsProbe
+
+	beforeAll(async () => {
+		realRoot = await fsExtra.mkdtemp(pathModule.join(os.tmpdir(), "filen-sync-conformance-"))
+
+		realProbe = await probe(fsExtra as unknown as SyncFS, realRoot)
+
+		const virtual = createVirtualFS()
+		await virtual.fs.ensureDir("/root")
+		virtualProbe = await probe(virtual.fs, "/root")
+	})
+
+	afterAll(async () => {
+		if (!realRoot) {
+			return
+		}
+
+		// Best-effort removal of the OS temp directory; never let a cleanup
+		// failure mask a real test result.
+		try {
+			await fsExtra.rm(realRoot, { force: true, recursive: true, maxRetries: 5, retryDelay: 50 })
+		} catch {
+			// ignore
+		}
+	})
+
+	it("reports a stable inode across repeated stats (real + virtual)", () => {
+		expect(realProbe.inoStable).toBe(true)
+		expect(virtualProbe.inoStable).toBe(true)
+	})
+
+	it("preserves the inode across a rename (real + virtual)", () => {
+		expect(realProbe.inoAfterRename).toBe(realProbe.inoBeforeRename)
+		expect(virtualProbe.inoAfterRename).toBe(virtualProbe.inoBeforeRename)
+	})
+
+	it("preserves the inode across a cross-directory move (real + virtual)", () => {
+		expect(realProbe.inoAfterMove).toBe(realProbe.inoBeforeMove)
+		expect(virtualProbe.inoAfterMove).toBe(virtualProbe.inoBeforeMove)
+	})
+
+	it("assigns a fresh inode after delete + recreate (virtual is deterministic)", () => {
+		// The engine relies on a recreated path looking like a new item (delete + add,
+		// not a no-op). memfs never reuses inodes, so this is deterministic.
+		expect(virtualProbe.inoRecreateAfter).not.toBe(virtualProbe.inoRecreateBefore)
+	})
+
+	it("populates mtime and birthtime on write (real + virtual)", () => {
+		expect(realProbe.mtimeMsAfterWrite).toBeGreaterThan(0)
+		expect(virtualProbe.mtimeMsAfterWrite).toBeGreaterThan(0)
+		expect(virtualProbe.birthtimeMsAfterWrite).toBeGreaterThan(0)
+	})
+
+	it("updates mtime via utimes to whole-second precision (real + virtual)", () => {
+		expect(realProbe.mtimeSecAfterUtimes).toBe(UTIMES_TARGET_SEC)
+		expect(virtualProbe.mtimeSecAfterUtimes).toBe(UTIMES_TARGET_SEC)
+	})
+
+	it("creates intermediate directories with ensureDir (real + virtual)", () => {
+		expect(realProbe.nestedDirsAreDirectories).toBe(true)
+		expect(virtualProbe.nestedDirsAreDirectories).toBe(true)
+	})
+
+	it("detects symlinks via lstat while stat follows them (virtual)", () => {
+		const virtual = createVirtualFS({ "/root/target.txt": "payload" })
+
+		virtual.ifs.symlinkSync("/root/target.txt", "/root/link.txt")
+
+		expect(virtual.ifs.lstatSync("/root/link.txt").isSymbolicLink()).toBe(true)
+		expect(virtual.ifs.statSync("/root/link.txt").isSymbolicLink()).toBe(false)
+		expect(virtual.ifs.statSync("/root/link.txt").isFile()).toBe(true)
+	})
+
+	it("enumerates a tree with fast-glob identically to a real directory", async () => {
+		const spec: VfsSpec = {
+			"/tree/a.txt": "a",
+			"/tree/sub/b.txt": "b",
+			"/tree/sub/c/d.txt": "d"
+		}
+
+		const virtual = createVirtualFS(spec)
+
+		// Mirror the same tree on the real filesystem.
+		const realTree = pathModule.join(realRoot, "tree")
+		await fsExtra.ensureDir(pathModule.join(realTree, "sub", "c"))
+		await fsExtra.writeFile(pathModule.join(realTree, "a.txt"), "a")
+		await fsExtra.writeFile(pathModule.join(realTree, "sub", "b.txt"), "b")
+		await fsExtra.writeFile(pathModule.join(realTree, "sub", "c", "d.txt"), "d")
+
+		const globOptions = {
+			dot: true,
+			onlyDirectories: false,
+			onlyFiles: false,
+			followSymbolicLinks: false,
+			deep: Infinity,
+			unique: false,
+			objectMode: false,
+			stats: false
+		} as const
+
+		const realEntries = (await FastGlob.async("**/*", { ...globOptions, cwd: realTree })).sort()
+		const virtualEntries = (
+			await FastGlob.async("**/*", {
+				...globOptions,
+				cwd: "/tree",
+				fs: virtual.globFs as FastGlob.FileSystemAdapter
+			})
+		).sort()
+
+		expect(virtualEntries).toEqual(["a.txt", "sub", "sub/b.txt", "sub/c", "sub/c/d.txt"])
+		expect(virtualEntries).toEqual(realEntries)
+	})
+})

package/tests/e2e/backup.e2e.test.ts

@@ -0,0 +1,130 @@
+import { describe, it, expect, beforeAll, afterAll } from "vitest"
+import type FilenSDK from "@filen/sdk"
+import { E2E_ENABLED, loginTestSDK, teardownTestSDK } from "./harness/account"
+import { withE2EWorld } from "./harness/world"
+import { settle } from "./harness/drive"
+import { snapshotRemoteReal } from "./harness/assert"
+import { writeLocal, modifyLocal, rmLocal, renameLocal, readLocal, existsLocal, uploadRemote, deleteRemote } from "./harness/mutations"
+
+/**
+ * Phase 3 e2e — the ADDITIVE backup modes against the live backend (previously untested live).
+ * localBackup pushes local up but NEVER deletes the remote and tolerates foreign remote edits;
+ * cloudBackup pulls remote down but NEVER deletes the local copy and tolerates foreign local edits.
+ */
+describe.skipIf(!E2E_ENABLED)("E2E — backup modes (additive)", () => {
+	let sdk: FilenSDK
+
+	beforeAll(async () => {
+		sdk = await loginTestSDK()
+	}, 300_000)
+
+	afterAll(async () => {
+		await teardownTestSDK()
+	})
+
+	// ---- localBackup ------------------------------------------------------------------------------
+
+	it("localBackup: a new local file is uploaded", async () => {
+		await withE2EWorld({ sdk, mode: "localBackup" }, async world => {
+			await writeLocal(world, "a.txt", "data")
+			await settle(world)
+
+			expect((await snapshotRemoteReal(world))["/a.txt"]).toMatchObject({ type: "file", size: 4 })
+		})
+	})
+
+	it("localBackup: a local deletion does NOT propagate — the remote keeps the backup", async () => {
+		await withE2EWorld({ sdk, mode: "localBackup" }, async world => {
+			await writeLocal(world, "keep.txt", "keep")
+			await settle(world)
+
+			await rmLocal(world, "keep.txt")
+			await settle(world)
+
+			// The remote copy survives the local deletion.
+			expect((await snapshotRemoteReal(world))["/keep.txt"]).toMatchObject({ type: "file" })
+		})
+	})
+
+	it("localBackup: a local rename propagates (the move follows; no data lost)", async () => {
+		await withE2EWorld({ sdk, mode: "localBackup" }, async world => {
+			await writeLocal(world, "before.txt", "data")
+			await settle(world)
+
+			await renameLocal(world, "before.txt", "after.txt")
+			await settle(world)
+
+			const remote = await snapshotRemoteReal(world)
+
+			expect(remote["/after.txt"]).toMatchObject({ type: "file" })
+			expect(remote["/before.txt"]).toBeUndefined()
+		})
+	})
+
+	it("localBackup: a foreign remote edit is tolerated (not reverted)", async () => {
+		await withE2EWorld({ sdk, mode: "localBackup" }, async world => {
+			await writeLocal(world, "a.txt", "local-content")
+			await settle(world)
+
+			// Another device overwrites the remote copy.
+			await uploadRemote(world, "a.txt", "FOREIGN-EDIT")
+			await settle(world)
+
+			// The remote keeps the foreign edit; the local copy is untouched (additive — never reverts).
+			expect((await snapshotRemoteReal(world, { withContent: true }))["/a.txt"]!.size).toBe("FOREIGN-EDIT".length)
+			expect(await readLocal(world, "a.txt")).toBe("local-content")
+		})
+	})
+
+	// ---- cloudBackup ------------------------------------------------------------------------------
+
+	it("cloudBackup: a new remote file is downloaded", async () => {
+		await withE2EWorld({ sdk, mode: "cloudBackup" }, async world => {
+			await uploadRemote(world, "a.txt", "data")
+			await settle(world)
+
+			expect(await existsLocal(world, "a.txt")).toBe(true)
+			expect(await readLocal(world, "a.txt")).toBe("data")
+		})
+	})
+
+	it("cloudBackup: a remote deletion does NOT propagate — the local copy is kept", async () => {
+		await withE2EWorld({ sdk, mode: "cloudBackup" }, async world => {
+			await uploadRemote(world, "keep.txt", "keep")
+			await settle(world)
+
+			expect(await existsLocal(world, "keep.txt")).toBe(true)
+
+			await deleteRemote(world, "keep.txt")
+			await settle(world)
+
+			// The local copy survives the remote deletion.
+			expect(await existsLocal(world, "keep.txt")).toBe(true)
+		})
+	})
+
+	it("cloudBackup: a remote modification is pulled down (remote authoritative)", async () => {
+		await withE2EWorld({ sdk, mode: "cloudBackup" }, async world => {
+			await uploadRemote(world, "a.txt", "v1")
+			await settle(world)
+
+			await uploadRemote(world, "a.txt", "v2-modified-longer")
+			await settle(world)
+
+			expect(await readLocal(world, "a.txt")).toBe("v2-modified-longer")
+		})
+	})
+
+	it("cloudBackup: a foreign local edit is tolerated (not reverted)", async () => {
+		await withE2EWorld({ sdk, mode: "cloudBackup" }, async world => {
+			await uploadRemote(world, "a.txt", "remote-content")
+			await settle(world)
+
+			// Edit the pulled-down copy locally; cloudBackup must NOT re-download over it.
+			await modifyLocal(world, "a.txt", "LOCAL-EDIT")
+			await settle(world)
+
+			expect(await readLocal(world, "a.txt")).toBe("LOCAL-EDIT")
+		})
+	})
+})

package/tests/e2e/confirm.e2e.test.ts

@@ -0,0 +1,191 @@
+import { describe, it, expect, beforeAll, afterAll } from "vitest"
+import type FilenSDK from "@filen/sdk"
+import { E2E_ENABLED, loginTestSDK, teardownTestSDK } from "./harness/account"
+import { withE2EWorld, type E2EWorld } from "./harness/world"
+import { settle, messagesOfType } from "./harness/drive"
+import { snapshotRemoteReal, snapshotLocalReal } from "./harness/assert"
+import { writeLocal, rmLocal, uploadRemote, deleteRemote } from "./harness/mutations"
+
+/**
+ * Phase 3 e2e — large-deletion confirmation against the live backend. When
+ * `requireConfirmationOnLargeDeletion` is set and an entire side is emptied, the engine raises a
+ * `confirmDeletion` prompt every second and BLOCKS the cycle until `confirmDeletion(uuid, decision)`
+ * arrives: "delete" proceeds, "restart" skips the cycle's deletions. This is the live counterpart of
+ * mocked Category G — the gate's threshold is computed from the real tree sizes the real walk reports,
+ * and the confirmed deletion is carried out against the real backend.
+ *
+ * Because the cycle blocks mid-run, these are driven by hand (real timers): start the cycle, deliver the
+ * decision repeatedly (the prompt resets it to "waiting" each tick) until the cycle resolves.
+ */
+async function runCycleWithDecision(world: E2EWorld, decision: "delete" | "restart"): Promise<void> {
+	world.worker.resetCache(world.syncPair.uuid)
+
+	let settled = false
+	const cyclePromise = world.sync.runCycle().finally(() => {
+		settled = true
+	})
+
+	// Deliver the decision until the 1s prompt interval observes it and the cycle moves on. 250ms poll vs
+	// the 1s prompt interval is a comfortable margin; the 80-iteration cap (20s) is only a safety net.
+	for (let tick = 0; tick < 80 && !settled; tick++) {
+		world.worker.confirmDeletion(world.syncPair.uuid, decision)
+
+		await new Promise<void>(resolve => setTimeout(resolve, 250))
+	}
+
+	await cyclePromise
+}
+
+describe.skipIf(!E2E_ENABLED)("E2E — large-deletion confirmation", () => {
+	let sdk: FilenSDK
+
+	beforeAll(async () => {
+		sdk = await loginTestSDK()
+	}, 300_000)
+
+	afterAll(async () => {
+		await teardownTestSDK()
+	})
+
+	it("a confirmed full-emptying deletion (decision: delete) propagates to the real backend", async () => {
+		await withE2EWorld({ sdk, mode: "twoWay", requireConfirmationOnLargeDeletion: true }, async world => {
+			await writeLocal(world, "a.txt", "a")
+			await writeLocal(world, "b.txt", "b")
+			await settle(world)
+
+			expect((await snapshotRemoteReal(world))["/a.txt"]).toMatchObject({ type: "file" })
+
+			// Empty the entire local side — this trips the large-deletion gate on the next cycle.
+			await rmLocal(world, "a.txt")
+			await rmLocal(world, "b.txt")
+
+			await runCycleWithDecision(world, "delete")
+
+			// A prompt WAS raised, and the confirmed deletion really emptied the remote.
+			expect(messagesOfType(world.messages, "confirmDeletion").length).toBeGreaterThan(0)
+
+			const remote = await snapshotRemoteReal(world)
+
+			expect(remote["/a.txt"]).toBeUndefined()
+			expect(remote["/b.txt"]).toBeUndefined()
+		})
+	})
+
+	it("declining the prompt (decision: restart) skips the deletion — the remote copies survive", async () => {
+		await withE2EWorld({ sdk, mode: "twoWay", requireConfirmationOnLargeDeletion: true }, async world => {
+			await writeLocal(world, "x.txt", "x")
+			await writeLocal(world, "y.txt", "y")
+			await settle(world)
+
+			await rmLocal(world, "x.txt")
+			await rmLocal(world, "y.txt")
+
+			await runCycleWithDecision(world, "restart")
+
+			// The deletion was declined: the remote still holds both files (the gate protected them).
+			const remote = await snapshotRemoteReal(world)
+
+			expect(remote["/x.txt"]).toMatchObject({ type: "file" })
+			expect(remote["/y.txt"]).toMatchObject({ type: "file" })
+		})
+	})
+
+	it("localToCloud — emptying the local side prompts (where: local) and 'delete' mirrors the emptying (AA3)", async () => {
+		await withE2EWorld({ sdk, mode: "localToCloud", requireConfirmationOnLargeDeletion: true }, async world => {
+			await writeLocal(world, "a.txt", "a")
+			await writeLocal(world, "b.txt", "b")
+			await settle(world)
+
+			await rmLocal(world, "a.txt")
+			await rmLocal(world, "b.txt")
+
+			await runCycleWithDecision(world, "delete")
+
+			const prompts = messagesOfType(world.messages, "confirmDeletion")
+
+			expect(prompts.length).toBeGreaterThan(0)
+			expect(prompts[0]!.data.where).toBe("local")
+			// "delete" confirmed → the remote mirror is emptied.
+			expect(await snapshotRemoteReal(world)).toEqual({})
+		})
+	})
+
+	it("localToCloud — answering 'restart' to the prompt skips the deletions (AA5)", async () => {
+		await withE2EWorld({ sdk, mode: "localToCloud", requireConfirmationOnLargeDeletion: true }, async world => {
+			await writeLocal(world, "a.txt", "a")
+			await writeLocal(world, "b.txt", "b")
+			await settle(world)
+
+			await rmLocal(world, "a.txt")
+			await rmLocal(world, "b.txt")
+
+			await runCycleWithDecision(world, "restart")
+
+			expect(messagesOfType(world.messages, "confirmDeletion").length).toBeGreaterThan(0)
+			// "restart" → the remote still holds both files (deletions not applied).
+			const remote = await snapshotRemoteReal(world)
+
+			expect(remote["/a.txt"]).toMatchObject({ type: "file" })
+			expect(remote["/b.txt"]).toMatchObject({ type: "file" })
+		})
+	})
+
+	it("cloudToLocal — emptying the remote side prompts (where: remote) and 'delete' empties local (AA4)", async () => {
+		await withE2EWorld({ sdk, mode: "cloudToLocal", requireConfirmationOnLargeDeletion: true }, async world => {
+			await uploadRemote(world, "a.txt", "a")
+			await uploadRemote(world, "b.txt", "b")
+			await settle(world)
+
+			await deleteRemote(world, "a.txt")
+			await deleteRemote(world, "b.txt")
+
+			await runCycleWithDecision(world, "delete")
+
+			const prompts = messagesOfType(world.messages, "confirmDeletion")
+
+			expect(prompts.length).toBeGreaterThan(0)
+			expect(prompts[0]!.data.where).toBe("remote")
+			// "delete" confirmed → the local mirror is emptied.
+			expect(await snapshotLocalReal(world)).toEqual({})
+		})
+	})
+
+	it("localBackup — emptying the local side NEVER prompts; the remote backup is untouched (AA6)", async () => {
+		await withE2EWorld({ sdk, mode: "localBackup", requireConfirmationOnLargeDeletion: true }, async world => {
+			await writeLocal(world, "a.txt", "a")
+			await writeLocal(world, "b.txt", "b")
+			await settle(world)
+
+			await rmLocal(world, "a.txt")
+			await rmLocal(world, "b.txt")
+			await settle(world)
+
+			// Additive backup: the source emptying is never mirrored, so no prompt and the backup survives.
+			expect(messagesOfType(world.messages, "confirmDeletion").length).toBe(0)
+
+			const remote = await snapshotRemoteReal(world)
+
+			expect(remote["/a.txt"]).toMatchObject({ type: "file" })
+			expect(remote["/b.txt"]).toMatchObject({ type: "file" })
+		})
+	})
+
+	it("cloudBackup — emptying the remote side NEVER prompts; the local backup is untouched (AA7)", async () => {
+		await withE2EWorld({ sdk, mode: "cloudBackup", requireConfirmationOnLargeDeletion: true }, async world => {
+			await uploadRemote(world, "a.txt", "a")
+			await uploadRemote(world, "b.txt", "b")
+			await settle(world)
+
+			await deleteRemote(world, "a.txt")
+			await deleteRemote(world, "b.txt")
+			await settle(world)
+
+			expect(messagesOfType(world.messages, "confirmDeletion").length).toBe(0)
+
+			const local = await snapshotLocalReal(world)
+
+			expect(local["/a.txt"]).toMatchObject({ type: "file" })
+			expect(local["/b.txt"]).toMatchObject({ type: "file" })
+		})
+	})
+})