@filen/sync 0.2.1 → 0.3.2

package/tests/scenarios/g-large-deletion.test.ts

@@ -0,0 +1,277 @@
+import { describe, it, expect, vi } from "vitest"
+import { SYNC_INTERVAL } from "../../src/constants"
+import { createWorld, BASE_TIME, type CreateWorldOptions, type World } from "../harness/world"
+import { snapshotLocal, snapshotRemote, messagesOfType } from "../harness/snapshot"
+import { rmLocal } from "../harness/mutations"
+
+/**
+ * Category G — large-deletion confirmation (behavioral spec §G, §6). When
+ * requireConfirmationOnLargeDeletion is set and an entire side is emptied, the engine emits a
+ * `confirmDeletion` prompt every second and blocks the cycle until `confirmDeletion(uuid, decision)`
+ * arrives. "delete" proceeds; "restart" (or timeout) skips the cycle's deletions.
+ *
+ * These cycles block mid-run on the prompt, so they are driven manually (not via runScenario): the
+ * timer pump below both fires the 1s prompt interval and delivers the user's decision.
+ */
+const FAKE_TIMERS = ["setTimeout", "clearTimeout", "setInterval", "clearInterval", "Date"] as const
+
+async function withWorld(options: CreateWorldOptions, body: (world: World) => Promise<void>): Promise<void> {
+	vi.useFakeTimers({ toFake: [...FAKE_TIMERS] })
+	vi.setSystemTime(BASE_TIME)
+
+	try {
+		const world = await createWorld(options)
+
+		await body(world)
+	} finally {
+		vi.useRealTimers()
+	}
+}
+
+/** Drive one cycle that is NOT expected to block on a confirmation prompt. */
+async function plainCycle(world: World): Promise<void> {
+	await vi.advanceTimersByTimeAsync(SYNC_INTERVAL + 1)
+
+	await world.sync.runCycle()
+}
+
+/** Drive one cycle, delivering `decision` to any confirmation prompt so the cycle can complete. */
+async function cycleWithDecision(world: World, decision: "delete" | "restart"): Promise<void> {
+	await vi.advanceTimersByTimeAsync(SYNC_INTERVAL + 1)
+
+	let settled = false
+	const cyclePromise = world.sync.runCycle().finally(() => {
+		settled = true
+	})
+
+	// The prompt resets the decision to "waiting" when it opens, so re-deliver each tick until the
+	// 1s interval observes it and the cycle moves on.
+	for (let tick = 0; tick < 30 && !settled; tick++) {
+		world.worker.confirmDeletion(world.syncPair.uuid, decision)
+
+		await vi.advanceTimersByTimeAsync(1000)
+	}
+
+	await cyclePromise
+}
+
+function confirmDeletionCount(world: World): number {
+	return messagesOfType(world.messages, "confirmDeletion").length
+}
+
+describe("Category G — large-deletion confirmation", () => {
+	it("G1: emptying the local side and confirming the deletion proceeds", async () => {
+		await withWorld(
+			{
+				mode: "twoWay",
+				requireConfirmationOnLargeDeletion: true,
+				initialLocal: { "/local/a.txt": "a", "/local/b.txt": "b" }
+			},
+			async world => {
+				await plainCycle(world)
+
+				rmLocal(world, "a.txt")
+				rmLocal(world, "b.txt")
+				world.triggerWatcher()
+
+				await cycleWithDecision(world, "delete")
+
+				expect(confirmDeletionCount(world)).toBeGreaterThan(0)
+				expect(messagesOfType(world.messages, "confirmDeletion")[0]!.data.where).toBe("local")
+				// "delete" was given, so the remote is emptied to match.
+				expect(snapshotRemote(world)).toEqual({})
+			}
+		)
+	})
+
+	it("G2: emptying the local side and answering restart skips the cycle (no deletions)", async () => {
+		await withWorld(
+			{
+				mode: "twoWay",
+				requireConfirmationOnLargeDeletion: true,
+				initialLocal: { "/local/a.txt": "a", "/local/b.txt": "b" }
+			},
+			async world => {
+				await plainCycle(world)
+
+				rmLocal(world, "a.txt")
+				rmLocal(world, "b.txt")
+				world.triggerWatcher()
+
+				await cycleWithDecision(world, "restart")
+
+				expect(confirmDeletionCount(world)).toBeGreaterThan(0)
+				// "restart" was given, so the deletions are NOT applied — the remote still has both files.
+				expect(snapshotRemote(world)["/a.txt"]).toMatchObject({ type: "file" })
+				expect(snapshotRemote(world)["/b.txt"]).toMatchObject({ type: "file" })
+			}
+		)
+	})
+
+	// G3: confirmRemoteDeletion is gated by BOTH the mode and the `previousRemote.size <= deleteCount`
+	// threshold (symmetric to confirmLocalDeletion). Here the remote is emptied but only part of it is
+	// attributable to remote-side deletions (the rest was deleted locally), so the threshold is NOT met
+	// and there is NO prompt. (BUG-001 fix: the missing `&&` that dropped the threshold + mode gate is
+	// restored, so confirmRemoteDeletion is now symmetric with confirmLocalDeletion.)
+	it("G3: a sub-threshold remote emptying does not trigger a confirmation prompt", async () => {
+		await withWorld(
+			{
+				mode: "twoWay",
+				requireConfirmationOnLargeDeletion: true,
+				// Start from the remote so the previous remote tree is observed non-empty (size 3) — an
+				// upload-only cycle would leave previousRemote.size at 0 and the prompt could never fire.
+				initialRemote: { "/a.txt": "a", "/b.txt": "b", "/c.txt": "c" }
+			},
+			async world => {
+				await plainCycle(world)
+
+				// Remote loses everything, but one of those removals is also a LOCAL deletion — so it is
+				// attributed to a remote-delete, leaving deleteLocalCount (2) < previousRemote.size (3). The
+				// correct (threshold-gated) confirmRemoteDeletion is therefore false.
+				world.cloud.controls.trashPath("/a.txt")
+				world.cloud.controls.trashPath("/b.txt")
+				world.cloud.controls.trashPath("/c.txt")
+				rmLocal(world, "a.txt")
+				world.triggerWatcher()
+
+				await cycleWithDecision(world, "delete")
+
+				// TARGET: the threshold is not met, so the engine proceeds without prompting.
+				expect(confirmDeletionCount(world)).toBe(0)
+			}
+		)
+	})
+
+	it("G4: with confirmation disabled, a full emptying deletes without prompting", async () => {
+		await withWorld(
+			{
+				mode: "twoWay",
+				requireConfirmationOnLargeDeletion: false,
+				initialLocal: { "/local/a.txt": "a", "/local/b.txt": "b" }
+			},
+			async world => {
+				await plainCycle(world)
+
+				rmLocal(world, "a.txt")
+				rmLocal(world, "b.txt")
+				world.triggerWatcher()
+
+				await plainCycle(world)
+
+				expect(confirmDeletionCount(world)).toBe(0)
+				expect(snapshotRemote(world)).toEqual({})
+			}
+		)
+	})
+
+	it("G5: a partial deletion (side not emptied) does not trigger a prompt", async () => {
+		await withWorld(
+			{
+				mode: "twoWay",
+				requireConfirmationOnLargeDeletion: true,
+				initialLocal: { "/local/a.txt": "a", "/local/b.txt": "b", "/local/c.txt": "c" }
+			},
+			async world => {
+				await plainCycle(world)
+
+				rmLocal(world, "a.txt")
+				world.triggerWatcher()
+
+				await plainCycle(world)
+
+				expect(confirmDeletionCount(world)).toBe(0)
+				// Only the deleted file is gone; the rest remain.
+				expect(snapshotRemote(world)["/a.txt"]).toBeUndefined()
+				expect(snapshotRemote(world)["/b.txt"]).toMatchObject({ type: "file" })
+				expect(snapshotRemote(world)["/c.txt"]).toMatchObject({ type: "file" })
+				expect(snapshotLocal(world)["/a.txt"]).toBeUndefined()
+			}
+		)
+	})
+
+	// Drive a cycle that opens the confirmation prompt, then STOP the pair (pause/remove) mid-wait instead
+	// of answering. Returns whether the cycle settled — with the bail-out fix it does (the cycle skips and
+	// the finally releases the lock); without it the wait spins forever holding the lock. The tick loop is
+	// capped so a regression fails fast (settled === false) instead of hanging the suite.
+	async function runCycleThenStopMidConfirmation(world: World, stop: (world: World) => void): Promise<boolean> {
+		await vi.advanceTimersByTimeAsync(SYNC_INTERVAL + 1)
+
+		let settled = false
+		const cyclePromise = world.sync.runCycle().finally(() => {
+			settled = true
+		})
+
+		// Let the prompt open, then stop the pair while the wait loop is still polling.
+		await vi.advanceTimersByTimeAsync(1000)
+
+		stop(world)
+
+		for (let tick = 0; tick < 5 && !settled; tick++) {
+			await vi.advanceTimersByTimeAsync(1000)
+		}
+
+		if (settled) {
+			await cyclePromise
+		}
+
+		return settled
+	}
+
+	it("G6: pausing the pair while awaiting confirmation bails out — no wedge, lock released, no deletion", async () => {
+		await withWorld(
+			{
+				mode: "twoWay",
+				requireConfirmationOnLargeDeletion: true,
+				initialLocal: { "/local/a.txt": "a", "/local/b.txt": "b" }
+			},
+			async world => {
+				await plainCycle(world)
+
+				rmLocal(world, "a.txt")
+				rmLocal(world, "b.txt")
+				world.triggerWatcher()
+
+				const settled = await runCycleThenStopMidConfirmation(world, w => {
+					w.sync.paused = true
+				})
+
+				// The cycle stopped waiting (it did not hold the lock forever) and applied NO deletion.
+				expect(settled, "the cycle must stop waiting once the pair is paused").toBe(true)
+				expect(confirmDeletionCount(world)).toBeGreaterThan(0)
+				expect(snapshotRemote(world)["/a.txt"]).toMatchObject({ type: "file" })
+				expect(snapshotRemote(world)["/b.txt"]).toMatchObject({ type: "file" })
+
+				// The lock was released (the finally ran), so once un-paused a normal cycle proceeds to
+				// completion — it would block forever on lock.acquire() if the previous cycle still held it.
+				world.sync.paused = false
+
+				await cycleWithDecision(world, "restart")
+			}
+		)
+	})
+
+	it("G7: removing the pair while awaiting confirmation bails out — no wedge", async () => {
+		await withWorld(
+			{
+				mode: "twoWay",
+				requireConfirmationOnLargeDeletion: true,
+				initialLocal: { "/local/a.txt": "a", "/local/b.txt": "b" }
+			},
+			async world => {
+				await plainCycle(world)
+
+				rmLocal(world, "a.txt")
+				rmLocal(world, "b.txt")
+				world.triggerWatcher()
+
+				const settled = await runCycleThenStopMidConfirmation(world, w => {
+					w.sync.removed = true
+				})
+
+				expect(settled, "the cycle must stop waiting once the pair is removed").toBe(true)
+				// No deletion was applied — the wait was abandoned, not confirmed.
+				expect(snapshotRemote(world)["/a.txt"]).toMatchObject({ type: "file" })
+			}
+		)
+	})
+})

package/tests/scenarios/h-resilience.test.ts

@@ -0,0 +1,167 @@
+import { describe, it, expect } from "vitest"
+import { APIError } from "@filen/sdk"
+import { runScenario, runCycle, localMutate, control } from "../harness/runner"
+import { BASE_TIME } from "../harness/world"
+import { messagesOfType, transferKinds } from "../harness/snapshot"
+import { writeLocalAt, rmLocal, mkdirLocal, writeLocal } from "../harness/mutations"
+import { type SyncMessage } from "../../src/types"
+
+/**
+ * Category H — resilience / races (behavioral spec §H, §7). A task whose source vanished before it
+ * runs is skipped without error; an `APIError{file_not_found|folder_not_found}` on a remote unlink is
+ * treated as already-deleted; a real task failure is recorded and the cycle restarts WITHOUT
+ * persisting new state, so a retry recovers. Several true mid-I/O races (modify-during-upload, a
+ * vanish strictly between delta-computation and the task) are only fully reproducible against real
+ * I/O — those are deferred to the Phase 3 live e2e suite; here we pin the deterministic guarantees.
+ */
+const SECOND = 1000
+
+/** Total number of individual task errors reported across the message stream. */
+function taskErrorCount(messages: SyncMessage[]): number {
+	return messagesOfType(messages, "taskErrors").reduce((sum, message) => sum + message.data.errors.length, 0)
+}
+
+describe("Category H — resilience / races", () => {
+	it("H1: a delete whose remote target already vanished is a silent no-op (no task error)", async () => {
+		const result = await runScenario({
+			name: "H1",
+			mode: "twoWay",
+			initialLocal: { "/local/a.txt": "content" },
+			steps: [
+				runCycle(),
+				// The local delete produces a deleteRemote delta, but the remote copy is ALSO already gone
+				// (trashed externally in the same beat) — the unlink must find nothing and skip cleanly.
+				localMutate(world => rmLocal(world, "a.txt")),
+				control(world => world.cloud.controls.trashPath("/a.txt")),
+				runCycle(),
+				runCycle()
+			]
+		})
+
+		expect(taskErrorCount(result.messages)).toBe(0)
+		expect(result.finalRemote["/a.txt"]).toBeUndefined()
+		expect(result.finalLocal["/a.txt"]).toBeUndefined()
+		expect(result.finalLocal).toEqual(result.finalRemote)
+	})
+
+	it("H2: successive edits to a file always converge to the latest content (no lost update)", async () => {
+		const result = await runScenario({
+			name: "H2",
+			mode: "twoWay",
+			initialLocal: { "/local/a.txt": "v1" },
+			steps: [
+				runCycle(),
+				localMutate(world => writeLocalAt(world, "a.txt", "v2", BASE_TIME + 2 * SECOND)),
+				runCycle(),
+				localMutate(world => writeLocalAt(world, "a.txt", "v3-final", BASE_TIME + 4 * SECOND)),
+				runCycle(),
+				runCycle()
+			]
+		})
+
+		expect(taskErrorCount(result.messages)).toBe(0)
+		// The remote reflects the LAST write, not an earlier one — no edit was lost across the overlap.
+		expect(result.finalRemote["/a.txt"]).toMatchObject({ type: "file", size: "v3-final".length })
+		expect(result.finalLocal).toEqual(result.finalRemote)
+	})
+
+	it("H3: an APIError file_not_found on the remote unlink is treated as already-deleted (no error)", async () => {
+		// The file lives in a subdirectory: the delete task's existence re-check resolves a parent, and
+		// the two settle cycles seed both previous trees + the engine's remote uuid cache before the delete.
+		const result = await runScenario({
+			name: "H3",
+			mode: "twoWay",
+			initialRemote: { "/dir/a.txt": "content" },
+			steps: [
+				runCycle(),
+				runCycle(),
+				localMutate(world => rmLocal(world, "dir/a.txt")),
+				// The backend reports the file as already gone when we try to trash it.
+				control(world =>
+					world.cloud.controls.setError("trashFile", new APIError({ code: "file_not_found", message: "File not found." }))
+				),
+				runCycle(),
+				runCycle()
+			]
+		})
+
+		// file_not_found is swallowed and the unlink is reported as a SUCCESSFUL delete — never an error.
+		// (We assert the success signal rather than final convergence: injecting not_found leaves the node
+		// live in the fake — the backend would actually have removed it — so the two would otherwise
+		// re-diverge. The guarantee under test is purely that not_found does not surface as a failure.)
+		const deleteMessages = messagesOfType(result.cycles[2]!.messages, "transfer").filter(message => message.data.of === "deleteRemoteFile")
+
+		expect(deleteMessages.some(message => message.data.type === "success")).toBe(true)
+		expect(deleteMessages.some(message => message.data.type === "error")).toBe(false)
+		expect(taskErrorCount(result.messages)).toBe(0)
+	})
+
+	it("H4: a real (non-not_found) error on a delete is recorded, the cycle restarts, and a retry recovers", async () => {
+		const result = await runScenario({
+			name: "H4",
+			mode: "twoWay",
+			initialRemote: { "/dir/a.txt": "content" },
+			steps: [
+				runCycle(),
+				runCycle(),
+				localMutate(world => rmLocal(world, "dir/a.txt")),
+				control(world => world.cloud.controls.setError("trashFile", new Error("backend unavailable"))),
+				runCycle(),
+				// Recover: clear the fault and the gating task error, then re-run.
+				control(world => {
+					world.cloud.controls.clearError("trashFile")
+					world.worker.resetTaskErrors(world.syncPair.uuid)
+					world.triggerWatcher()
+				}),
+				runCycle(),
+				runCycle()
+			]
+		})
+
+		// The failed cycle surfaced the error (a deleteRemoteFile that errored) and recorded a task error.
+		expect(taskErrorCount(result.cycles[2]!.messages)).toBeGreaterThan(0)
+		expect(transferKinds(result.cycles[2]!.messages)).toContain("deleteRemoteFile")
+		// After recovery the delete completes and the worlds converge.
+		expect(result.finalRemote["/dir/a.txt"]).toBeUndefined()
+		expect(result.finalLocal["/dir/a.txt"]).toBeUndefined()
+	})
+
+	it("H5: when one upload fails, an independent op still proceeds and the failure is retried to convergence", async () => {
+		const result = await runScenario({
+			name: "H5",
+			mode: "twoWay",
+			steps: [
+				runCycle(),
+				localMutate(world => {
+					// A new empty directory (createRemoteDirectory — succeeds) alongside a file whose upload
+					// is forced to fail. The independent directory op must not be blocked by the failure.
+					mkdirLocal(world, "survives")
+					writeLocal(world, "bad.txt", "payload")
+				}),
+				control(world => world.cloud.controls.setError("uploadLocalFile", new Error("upload boom"))),
+				runCycle(),
+				control(world => {
+					world.cloud.controls.clearError("uploadLocalFile")
+					world.worker.resetTaskErrors(world.syncPair.uuid)
+					world.triggerWatcher()
+				}),
+				runCycle(),
+				runCycle()
+			]
+		})
+
+		// The upload failed and was recorded…
+		expect(taskErrorCount(result.cycles[1]!.messages)).toBeGreaterThan(0)
+		const failedKinds = transferKinds(result.cycles[1]!.messages)
+
+		expect(failedKinds).toContain("uploadFile")
+		// …but the independent directory creation still went through in that same cycle.
+		expect(result.cycles[1]!.remote["/survives"]).toMatchObject({ type: "directory" })
+		expect(result.cycles[1]!.remote["/bad.txt"]).toBeUndefined()
+
+		// After recovery the previously-failed upload completes and everything converges.
+		expect(result.finalRemote["/bad.txt"]).toMatchObject({ type: "file", size: "payload".length })
+		expect(result.finalRemote["/survives"]).toMatchObject({ type: "directory" })
+		expect(result.finalLocal).toEqual(result.finalRemote)
+	})
+})