@filen/sync 0.2.1 → 0.3.2

package/tests/harness/world.ts

@@ -0,0 +1,187 @@
+import SyncWorker from "../../src/index"
+import Sync from "../../src/lib/sync"
+import { type SyncPair, type SyncMode, type SyncMessage } from "../../src/types"
+import { type SyncEnvironment, type SyncWatcher } from "../../src/lib/environment"
+import { createVirtualFS, type VfsSpec, type VirtualFS } from "../fakes/virtual-fs"
+import { createFakeCloud, type CloudSpec, type FakeCloud } from "../fakes/fake-cloud"
+import { v4 as uuidv4 } from "uuid"
+
+/**
+ * A fixed, realistic base time so file mtimes are large ms values (the engine's
+ * `convertTimestampToMs` treats them as already-ms) and the fake clock is deterministic.
+ */
+export const BASE_TIME = new Date("2024-06-01T00:00:00.000Z").getTime()
+
+export const LOCAL_ROOT = "/local"
+export const DB_ROOT = "/db"
+
+export type CreateWorldOptions = {
+	mode: SyncMode
+	initialLocal?: VfsSpec
+	initialRemote?: CloudSpec
+	excludeDotFiles?: boolean
+	localTrashDisabled?: boolean
+	requireConfirmationOnLargeDeletion?: boolean
+	paused?: boolean
+	uuid?: string
+	filenIgnore?: string
+}
+
+export type World = {
+	worker: SyncWorker
+	sync: Sync
+	vfs: VirtualFS
+	cloud: FakeCloud
+	messages: SyncMessage[]
+	syncPair: SyncPair
+	localPath: string
+	/** Simulate the directory watcher firing (a local change was observed). */
+	triggerWatcher: () => void
+}
+
+/**
+ * A manual watcher whose `onChange` callbacks are invoked on demand, so tests deterministically
+ * tell the engine "the local directory changed" instead of relying on a real fs watcher.
+ */
+function createManualWatcher(): { factory: SyncEnvironment["createWatcher"]; trigger: () => void } {
+	const callbacks = new Set<() => void>()
+
+	return {
+		factory: async (_path: string, onChange: () => void): Promise<SyncWatcher> => {
+			callbacks.add(onChange)
+
+			return {
+				close: async (): Promise<void> => {
+					callbacks.delete(onChange)
+				}
+			}
+		},
+		trigger: (): void => {
+			for (const callback of callbacks) {
+				callback()
+			}
+		}
+	}
+}
+
+/**
+ * Build a fully wired, in-memory sync world: a virtual filesystem + a stateful fake cloud injected
+ * into a real {@link SyncWorker}/{@link Sync}, with all engine I/O routed through the fakes and the
+ * scheduling loop bypassed (the runner drives {@link Sync.runCycle} directly).
+ *
+ * Must be called with vitest fake timers already installed and the system time set, so memfs and the
+ * engine share a deterministic clock.
+ */
+export async function createWorld(options: CreateWorldOptions): Promise<World> {
+	const localSpec: VfsSpec = { [LOCAL_ROOT]: null, [DB_ROOT]: null }
+
+	for (const [path, value] of Object.entries(options.initialLocal ?? {})) {
+		localSpec[path] = value
+	}
+
+	if (typeof options.filenIgnore === "string") {
+		localSpec[`${LOCAL_ROOT}/.filenignore`] = options.filenIgnore
+	}
+
+	const vfs = createVirtualFS(localSpec)
+	const cloud = createFakeCloud(options.initialRemote ?? {}, { localFs: vfs.fs })
+	const watcher = createManualWatcher()
+
+	const environment: SyncEnvironment = {
+		fs: vfs.fs,
+		globFs: vfs.globFs,
+		writeFileAtomic: async (filename, data, writeOptions): Promise<void> => {
+			await vfs.fs.writeFile(filename, data, writeOptions)
+		},
+		createWatcher: watcher.factory,
+		// Route the tree fetch back through the fake cloud's SDK so every scenario exercises the real
+		// engine logic without HTTP/msgpack (the production msgpack path is unit-tested separately).
+		fetchDirTree: (_sdk, request) => cloud.sdk.api(3).dir().tree(request)
+	}
+
+	const messages: SyncMessage[] = []
+	const syncPair: SyncPair = {
+		name: "test-pair",
+		uuid: options.uuid ?? uuidv4(),
+		localPath: LOCAL_ROOT,
+		remotePath: "/",
+		remoteParentUUID: cloud.controls.rootUUID,
+		mode: options.mode,
+		excludeDotFiles: options.excludeDotFiles ?? false,
+		paused: options.paused ?? false,
+		localTrashDisabled: options.localTrashDisabled ?? false,
+		requireConfirmationOnLargeDeletion: options.requireConfirmationOnLargeDeletion ?? false
+	}
+
+	const worker = new SyncWorker({
+		syncPairs: [syncPair],
+		dbPath: DB_ROOT,
+		sdk: cloud.sdk,
+		onMessage: message => {
+			messages.push(message)
+		},
+		disableLogging: true,
+		environment
+	})
+
+	const sync = new Sync({ syncPair, worker })
+
+	worker.syncs[syncPair.uuid] = sync
+
+	// The engine's initialize() would also call run() (the self-scheduling loop); we skip it and
+	// load persisted state directly so the runner can drive discrete cycles.
+	await sync.state.initialize()
+	await sync.ignorer.initialize()
+
+	return {
+		worker,
+		sync,
+		vfs,
+		cloud,
+		messages,
+		syncPair,
+		localPath: LOCAL_ROOT,
+		triggerWatcher: watcher.trigger
+	}
+}
+
+/**
+ * Simulate a process restart: rebuild the worker/sync over the SAME virtual filesystem and cloud,
+ * so persisted state (previous trees, deviceId, ignorer) is reloaded from disk. Mutates `world` in
+ * place (new worker/sync/watcher) and keeps appending to the same message stream.
+ */
+export async function restartSync(world: World): Promise<void> {
+	const watcher = createManualWatcher()
+
+	const environment: SyncEnvironment = {
+		fs: world.vfs.fs,
+		globFs: world.vfs.globFs,
+		writeFileAtomic: async (filename, data, writeOptions): Promise<void> => {
+			await world.vfs.fs.writeFile(filename, data, writeOptions)
+		},
+		createWatcher: watcher.factory,
+		fetchDirTree: (_sdk, request) => world.cloud.sdk.api(3).dir().tree(request)
+	}
+
+	const worker = new SyncWorker({
+		syncPairs: [world.syncPair],
+		dbPath: DB_ROOT,
+		sdk: world.cloud.sdk,
+		onMessage: message => {
+			world.messages.push(message)
+		},
+		disableLogging: true,
+		environment
+	})
+
+	const sync = new Sync({ syncPair: world.syncPair, worker })
+
+	worker.syncs[world.syncPair.uuid] = sync
+
+	await sync.state.initialize()
+	await sync.ignorer.initialize()
+
+	world.worker = worker
+	world.sync = sync
+	world.triggerWatcher = watcher.trigger
+}

package/tests/scenarios/a-baseline.test.ts

@@ -0,0 +1,107 @@
+import { describe, it, expect } from "vitest"
+import { runScenario, runCycle, restart } from "../harness/runner"
+import { countMessages, transferKinds, allOps, hadTransfers } from "../harness/snapshot"
+
+/**
+ * Category A — baseline & convergence (behavioral spec §A).
+ *
+ * The exact cycle in which the steady-state `cycleNoChanges` message appears depends on the
+ * deviceId-cache / cache-reset settling mechanics, so these assert the robust invariants: the
+ * expected transfer happens on the first cycle, NO transfers happen afterwards, the worlds converge
+ * to equality, and steady state is eventually reported.
+ */
+describe("Category A — baseline & convergence", () => {
+	it("A1: empty ↔ empty converges with no operations", async () => {
+		const result = await runScenario({
+			name: "A1",
+			mode: "twoWay",
+			steps: [runCycle(), runCycle()]
+		})
+
+		expect(hadTransfers(result.messages)).toBe(false)
+		expect(countMessages(result.messages, "cycleNoChanges")).toBeGreaterThanOrEqual(1)
+		expect(result.finalLocal).toEqual({})
+		expect(result.finalRemote).toEqual({})
+	})
+
+	it("A2: a local-only file uploads on the first cycle, then converges (twoWay)", async () => {
+		const result = await runScenario({
+			name: "A2",
+			mode: "twoWay",
+			initialLocal: { "/local/a.txt": "0123456789" },
+			steps: [runCycle(), runCycle(), runCycle()]
+		})
+
+		expect(result.cycles[0]!.remote["/a.txt"]).toMatchObject({ type: "file", size: 10 })
+		expect(transferKinds(result.cycles[0]!.messages)).toContain("upload")
+		expect(allOps(result.cycles[1]!.messages)).toEqual([])
+		expect(allOps(result.cycles[2]!.messages)).toEqual([])
+		expect(countMessages(result.messages, "cycleNoChanges")).toBeGreaterThanOrEqual(1)
+		expect(result.finalLocal["/a.txt"]).toMatchObject({ type: "file", size: 10 })
+		expect(result.finalLocal).toEqual(result.finalRemote)
+	})
+
+	it("A3: a remote-only file downloads on the first cycle, then converges (twoWay)", async () => {
+		const result = await runScenario({
+			name: "A3",
+			mode: "twoWay",
+			initialRemote: { "/a.txt": "hello" },
+			steps: [runCycle(), runCycle(), runCycle()]
+		})
+
+		expect(result.cycles[0]!.local["/a.txt"]).toMatchObject({ type: "file", size: 5 })
+		expect(transferKinds(result.cycles[0]!.messages)).toContain("download")
+		expect(allOps(result.cycles[1]!.messages)).toEqual([])
+		expect(allOps(result.cycles[2]!.messages)).toEqual([])
+		expect(result.finalLocal["/a.txt"]).toMatchObject({ type: "file", size: 5 })
+		expect(result.finalLocal).toEqual(result.finalRemote)
+	})
+
+	it("A4: identical content on both sides converges without any transfer", async () => {
+		const result = await runScenario({
+			name: "A4",
+			mode: "twoWay",
+			initialLocal: { "/local/same.txt": "identical" },
+			initialRemote: { "/same.txt": "identical" },
+			steps: [runCycle(), runCycle(), runCycle()]
+		})
+
+		expect(hadTransfers(result.messages)).toBe(false)
+		expect(result.finalLocal["/same.txt"]).toMatchObject({ type: "file", size: 9 })
+		expect(result.finalLocal).toEqual(result.finalRemote)
+	})
+
+	it("A5: a converged world reports no operations after a restart (state persistence)", async () => {
+		const result = await runScenario({
+			name: "A5",
+			mode: "twoWay",
+			initialLocal: { "/local/a.txt": "persisted" },
+			steps: [runCycle(), runCycle(), runCycle(), restart(), runCycle(), runCycle()]
+		})
+
+		// The two cycles after the restart (indices 3 and 4) perform no transfers.
+		expect(allOps(result.cycles[3]!.messages)).toEqual([])
+		expect(allOps(result.cycles[4]!.messages)).toEqual([])
+		expect(countMessages(result.messages, "cycleError")).toBe(0)
+		expect(result.finalLocal["/a.txt"]).toMatchObject({ type: "file", size: 9 })
+		expect(result.finalLocal).toEqual(result.finalRemote)
+	})
+
+	it("A6: a deeply nested directory tree converges (twoWay)", async () => {
+		const result = await runScenario({
+			name: "A6",
+			mode: "twoWay",
+			initialLocal: {
+				"/local/a/b/c/d/e/deep.txt": "deep",
+				"/local/a/b/sibling.txt": "sibling",
+				"/local/a/top.txt": "top"
+			},
+			steps: [runCycle(), runCycle(), runCycle(), runCycle()]
+		})
+
+		expect(result.finalRemote["/a/b/c/d/e/deep.txt"]).toMatchObject({ type: "file", size: 4 })
+		expect(result.finalRemote["/a/b/c/d/e"]).toMatchObject({ type: "directory" })
+		expect(result.finalRemote["/a/top.txt"]).toMatchObject({ type: "file", size: 3 })
+		expect(result.finalLocal).toEqual(result.finalRemote)
+	})
+})

package/tests/scenarios/aa-races.test.ts

@@ -0,0 +1,258 @@
+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 { writeLocal, rmLocal } from "../harness/mutations"
+
+/**
+ * Category AA — concurrency / race conditions and the large-deletion confirmation across modes. The
+ * lock cases prove a cycle survives another device holding the remote resource lock (it reports a
+ * cycleError and recovers when released, never corrupting state). The confirmation cases extend the
+ * Category G prompt — which only covered twoWay — to the directional modes: the prompt fires for the
+ * side a mode is allowed to delete (localToCloud→local, cloudToLocal→remote) and NEVER fires for the
+ * additive backup modes (which never delete the target).
+ *
+ * Cycles that block on a confirmation prompt are driven manually (a timer pump delivers the 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()
+	}
+}
+
+async function plainCycle(world: World): Promise<void> {
+	await vi.advanceTimersByTimeAsync(SYNC_INTERVAL + 1)
+
+	await world.sync.runCycle()
+}
+
+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
+	})
+
+	for (let tick = 0; tick < 30 && !settled; tick++) {
+		world.worker.confirmDeletion(world.syncPair.uuid, decision)
+
+		await vi.advanceTimersByTimeAsync(1000)
+	}
+
+	await cyclePromise
+}
+
+/**
+ * Drive one cycle that begins while another device holds the remote lock. With maxTries:Infinity the
+ * acquire BLOCKS (retrying every second) instead of failing, so the cycle does no work and reports no
+ * cycleError until the lock frees. Mirrors cycleWithDecision's timer pump so the blocked acquire and the
+ * rest of the (now unblocked) cycle both drain deterministically. `assertWhileBlocked` runs at the point
+ * the cycle is provably still waiting on the lock, before it is released.
+ */
+async function cycleBlockedByContendedLock(world: World, assertWhileBlocked: () => void): Promise<void> {
+	await vi.advanceTimersByTimeAsync(SYNC_INTERVAL + 1)
+
+	let settled = false
+	const cyclePromise = world.sync.runCycle().finally(() => {
+		settled = true
+	})
+
+	// Spin several retry windows (past the 3s "acquiring lock" notice); the cycle stays blocked.
+	await vi.advanceTimersByTimeAsync(5000)
+
+	expect(settled, "the cycle must block on the contended lock, not fail").toBe(false)
+
+	assertWhileBlocked()
+
+	// Another device releases the lock; the acquire succeeds on its next retry and the cycle finishes.
+	world.cloud.controls.releaseLockContention(lockResource(world))
+
+	for (let tick = 0; tick < 30 && !settled; tick++) {
+		await vi.advanceTimersByTimeAsync(1000)
+	}
+
+	await cyclePromise
+}
+
+function lockResource(world: World): string {
+	return `sync-remoteParentUUID-${world.cloud.controls.rootUUID}`
+}
+
+function confirmDeletionCount(world: World): number {
+	return messagesOfType(world.messages, "confirmDeletion").length
+}
+
+describe("Category AA — races & cross-mode deletion confirmation", () => {
+	it("AA1: a contended remote lock makes the cycle wait, then it recovers when released", async () => {
+		await withWorld({ mode: "twoWay", initialLocal: { "/local/a.txt": "data" } }, async world => {
+			world.cloud.controls.contendLock(lockResource(world))
+
+			await cycleBlockedByContendedLock(world, () => {
+				// Blocked on the lock (the engine acquires with maxTries:Infinity): it announced it is waiting,
+				// reported NO error, and did NO work (no corruption) — the previous fake threw here instead.
+				expect(messagesOfType(world.messages, "cycleAcquiringLockStarted").length).toBeGreaterThan(0)
+				expect(messagesOfType(world.messages, "cycleError").length).toBe(0)
+				expect(snapshotRemote(world)["/a.txt"]).toBeUndefined()
+			})
+
+			// The now-unblocked cycle (plus a follow-up to settle both sides) syncs to convergence.
+			await plainCycle(world)
+
+			expect(snapshotRemote(world)["/a.txt"]).toMatchObject({ type: "file" })
+			expect(snapshotLocal(world)).toEqual(snapshotRemote(world))
+		})
+	})
+
+	it("AA2: a cycle blocked by lock contention applies ALL pending adds and deletes once released", async () => {
+		await withWorld({ mode: "twoWay", initialLocal: { "/local/keep.txt": "k", "/local/remove.txt": "r" } }, async world => {
+			await plainCycle(world)
+			await plainCycle(world)
+
+			// Queue an add and a delete, then block the next cycle on a contended lock.
+			writeLocal(world, "added.txt", "added")
+			rmLocal(world, "remove.txt")
+			world.triggerWatcher()
+			world.cloud.controls.contendLock(lockResource(world))
+
+			await cycleBlockedByContendedLock(world, () => {
+				// Nothing applied while the cycle is blocked on the lock.
+				expect(snapshotRemote(world)["/added.txt"]).toBeUndefined()
+				expect(snapshotRemote(world)["/remove.txt"]).toMatchObject({ type: "file" })
+			})
+
+			// After release the queued work all lands and the worlds converge.
+			await plainCycle(world)
+
+			expect(snapshotRemote(world)["/added.txt"]).toMatchObject({ type: "file" })
+			expect(snapshotRemote(world)["/remove.txt"]).toBeUndefined()
+			expect(snapshotLocal(world)).toEqual(snapshotRemote(world))
+		})
+	})
+
+	it("AA3: localToCloud — emptying the local side prompts a local-deletion confirmation", async () => {
+		await withWorld(
+			{ mode: "localToCloud", 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" confirmed → the remote mirror is emptied.
+				expect(snapshotRemote(world)).toEqual({})
+			}
+		)
+	})
+
+	it("AA4: cloudToLocal — emptying the remote side prompts a remote-deletion confirmation", async () => {
+		await withWorld(
+			{ mode: "cloudToLocal", requireConfirmationOnLargeDeletion: true, initialRemote: { "/a.txt": "a", "/b.txt": "b" } },
+			async world => {
+				await plainCycle(world)
+
+				world.cloud.controls.trashPath("/a.txt")
+				world.cloud.controls.trashPath("/b.txt")
+
+				await cycleWithDecision(world, "delete")
+
+				expect(confirmDeletionCount(world)).toBeGreaterThan(0)
+				expect(messagesOfType(world.messages, "confirmDeletion")[0]!.data.where).toBe("remote")
+				// "delete" confirmed → the local mirror is emptied.
+				expect(snapshotLocal(world)).toEqual({})
+			}
+		)
+	})
+
+	it("AA5: localToCloud — answering 'restart' to the prompt skips the deletions", async () => {
+		await withWorld(
+			{ mode: "localToCloud", 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" → the remote still holds both files (deletions not applied).
+				expect(snapshotRemote(world)["/a.txt"]).toMatchObject({ type: "file" })
+				expect(snapshotRemote(world)["/b.txt"]).toMatchObject({ type: "file" })
+			}
+		)
+	})
+
+	it("AA6: localBackup — emptying the local side NEVER prompts (backups don't delete the target)", async () => {
+		await withWorld(
+			{ mode: "localBackup", 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 plainCycle(world)
+
+				expect(confirmDeletionCount(world)).toBe(0)
+				// The remote backup is untouched.
+				expect(snapshotRemote(world)["/a.txt"]).toMatchObject({ type: "file" })
+				expect(snapshotRemote(world)["/b.txt"]).toMatchObject({ type: "file" })
+			}
+		)
+	})
+
+	it("AA7: cloudBackup — emptying the remote side NEVER prompts (backups don't delete the target)", async () => {
+		await withWorld(
+			{ mode: "cloudBackup", requireConfirmationOnLargeDeletion: true, initialRemote: { "/a.txt": "a", "/b.txt": "b" } },
+			async world => {
+				await plainCycle(world)
+
+				world.cloud.controls.trashPath("/a.txt")
+				world.cloud.controls.trashPath("/b.txt")
+
+				await plainCycle(world)
+
+				expect(confirmDeletionCount(world)).toBe(0)
+				// The local backup is untouched.
+				expect(snapshotLocal(world)["/a.txt"]).toMatchObject({ type: "file" })
+				expect(snapshotLocal(world)["/b.txt"]).toMatchObject({ type: "file" })
+			}
+		)
+	})
+
+	it("AA8: a file replaced (vanished + re-created) mid-flight is handled without error and converges", async () => {
+		await withWorld({ mode: "twoWay", initialLocal: { "/local/a.txt": "v1" } }, async world => {
+			await plainCycle(world)
+
+			// Remote deletes a.txt while local re-creates it with new content in the same beat — the delete
+			// task re-checks existence and the engine still settles on the surviving local content.
+			world.cloud.controls.trashPath("/a.txt")
+			writeLocal(world, "a.txt", "v2-local-recreated")
+			world.triggerWatcher()
+
+			await plainCycle(world)
+			await plainCycle(world)
+			await plainCycle(world)
+
+			expect(messagesOfType(world.messages, "taskErrors").some(message => message.data.errors.length > 0)).toBe(false)
+			expect(snapshotLocal(world)).toEqual(snapshotRemote(world))
+		})
+	})
+})