quak/test/library/library.test.ts

/**
 * Tests for `Library.open()` and its transparent background refresh loop.
 *
 * The library keeps the account's server state in a `MetadataStore` (issue
 * #41) and pulls changes with the resumable, tombstone-aware enumerators on
 * `Client` (issue #38: `collectionsSince` / `filesSince`). `open()` loads the
 * cache, does one refresh, then refreshes again every `refreshIntervalSeconds`
 * on a background timer. The design (#36) forbids an exposed `sync()`, a
 * `serverReachable` flag, a `lib.refresh()` method, and a "before each read"
 * mode. The contracts exercised here:
 *
 * 1. Reads are answered from RAM. A read never calls the client.
 * 2. `open()` does an initial refresh, then the interval keeps refreshing;
 *    each refresh resumes from the stored cursor and applies diffs + tombstones.
 * 3. The cache is rewritten only when a refresh actually changes something.
 * 4. A failed refresh is invisible to reads: the last good data stays, the
 *    failure surfaces via `onProgress` ("failed") and `status()`, and a later
 *    success clears the error. `open()` itself resolves even when the first
 *    refresh fails (offline start from cache).
 * 5. `close()` stops the timer and is idempotent.
 * 6. `cacheDirectory` defaults to the env-paths cache dir plus the user id.
 *
 * The client is a mock: no crypto, no network. It serves scripted pages and
 * records the `sinceTime` each call carried so cursor threading is provable.
 *
 * `open()` awaits the initial refresh (including its cache write), so state
 * right after `open()` is deterministic. The interval tests then use real
 * timers with a short interval and `vi.waitFor`: a fake clock cannot settle
 * the real fsync-and-rename cache write, and empty diffs never write, so the
 * eventual state is stable to poll for.
 */

import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
import { mkdtempSync, rmSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import envPaths from "env-paths";

import { Library, type RefreshEvent } from "../../src/library/index.js";
import { MetadataStore } from "../../src/library/store.js";
import type { CollectionsPage, FilesPage } from "../../src/client.js";
import type { Collection, EnteFile } from "../../src/model/types.js";

const USER_ID = 42;

// Short enough that a couple of ticks pass within a test, long enough not to
// spin; interval tests poll for the eventual state rather than counting ticks.
const FAST_INTERVAL = 0.02;

const collection = (
    id: number,
    updationTime: number,
    name = `album-${id}`,
): Collection => ({
    id,
    ownerID: USER_ID,
    key: new Uint8Array([id & 0xff]),
    name,
    type: "album",
    updationTime,
    isShared: false,
});

const file = (
    id: number,
    collectionID: number,
    updationTime: number,
): EnteFile => ({
    id,
    collectionID,
    ownerID: USER_ID,
    key: new Uint8Array([id & 0xff]),
    metadata: {
        title: `file-${id}.jpg`,
        fileType: "image",
        creationTime: updationTime,
        modificationTime: updationTime,
    },
    file: { decryptionHeader: "aGVhZGVy" },
    thumbnail: { decryptionHeader: "dGh1bWI=" },
    updationTime,
});

/**
 * A mock `Client`. `collectionsSince` shifts one page off `collectionsQueue`
 * per call (an empty diff that advances nothing when the queue runs dry);
 * `filesSince` shifts from a per-collection queue. `failCollections` makes the
 * next and all further collection fetches throw, to simulate an offline server.
 */
class MockClient {
    userID = USER_ID;
    failCollections = false;
    collectionsQueue: CollectionsPage[] = [];
    filesByCollection = new Map<number, FilesPage[]>();

    collectionsSinceTimes: number[] = [];
    filesCalls: { collectionID: number; sinceTime: number }[] = [];

    whoami(): { email: string; userID: number } {
        return { email: "user@example.com", userID: this.userID };
    }

    async collectionsSince(args: {
        sinceTime: number;
    }): Promise<CollectionsPage> {
        this.collectionsSinceTimes.push(args.sinceTime);
        if (this.failCollections) throw new Error("network down");
        return (
            this.collectionsQueue.shift() ?? {
                collections: [],
                deleted: [],
                cursor: args.sinceTime,
            }
        );
    }

    async filesSince(args: {
        collectionID: number;
        collectionKey: Uint8Array;
        sinceTime: number;
    }): Promise<FilesPage> {
        this.filesCalls.push({
            collectionID: args.collectionID,
            sinceTime: args.sinceTime,
        });
        const queue = this.filesByCollection.get(args.collectionID);
        return (
            queue?.shift() ?? {
                files: [],
                deleted: [],
                cursor: args.sinceTime,
            }
        );
    }

    filesFor(collectionID: number, ...pages: FilesPage[]): void {
        this.filesByCollection.set(collectionID, pages);
    }
}

describe("Library.open and background refresh", () => {
    let dir: string;
    let cacheDirectory: string;

    beforeEach(() => {
        dir = mkdtempSync(join(tmpdir(), "quak-library-"));
        cacheDirectory = join(dir, "cache");
    });

    afterEach(() => {
        rmSync(dir, { recursive: true, force: true });
    });

    it("does an initial refresh and answers reads from the cache", async () => {
        const client = new MockClient();
        client.collectionsQueue.push({
            collections: [collection(1, 100)],
            deleted: [],
            cursor: 100,
        });
        client.filesFor(1, {
            files: [file(1001, 1, 90), file(1002, 1, 95)],
            deleted: [],
            cursor: 95,
        });

        const lib = await Library.open({ client, cacheDirectory });
        try {
            expect(lib.listCollections().map((c) => c.id)).toEqual([1]);
            expect(lib.listFiles(1).map((f) => f.id)).toEqual([1001, 1002]);
            expect(lib.getFile(1, 1001)?.metadata.title).toBe("file-1001.jpg");

            const status = lib.status();
            expect(status.userID).toBe(USER_ID);
            expect(status.collections).toBe(1);
            expect(status.files).toBe(2);
            expect(status.lastRefreshAt).toBeGreaterThan(0);
            expect(status.lastError).toBeUndefined();

            // The initial refresh persisted the cache to disk.
            const reloaded = await MetadataStore.load(
                join(cacheDirectory, "metadata.json"),
            );
            expect(reloaded.getFile(1, 1001)?.id).toBe(1001);
            expect(reloaded.collectionsSinceTime).toBe(100);
        } finally {
            lib.close();
        }
    });

    it("reads never call the client", async () => {
        const client = new MockClient();
        client.collectionsQueue.push({
            collections: [collection(1, 100)],
            deleted: [],
            cursor: 100,
        });
        client.filesFor(1, {
            files: [file(1001, 1, 90)],
            deleted: [],
            cursor: 90,
        });

        const lib = await Library.open({ client, cacheDirectory });
        try {
            const collectionCalls = client.collectionsSinceTimes.length;
            const fileCalls = client.filesCalls.length;

            lib.listCollections();
            lib.getCollection(1);
            lib.listFiles(1);
            lib.getFile(1, 1001);
            lib.status();

            expect(client.collectionsSinceTimes.length).toBe(collectionCalls);
            expect(client.filesCalls.length).toBe(fileCalls);
        } finally {
            lib.close();
        }
    });

    it("resumes each refresh from the stored cursor", async () => {
        // Seed a cache with a cursor and a collection, as a prior run left it.
        const path = join(cacheDirectory, "metadata.json");
        const seed = await MetadataStore.load(path);
        seed.userID = USER_ID;
        seed.collectionsSinceTime = 500;
        seed.putCollection(collection(1, 400));
        seed.putFile(file(1001, 1, 400));
        await seed.save();

        const client = new MockClient();
        // The collection's updationTime advances (400 -> 600), so its files are
        // re-enumerated from the collection's stored updationTime (400).
        client.collectionsQueue.push({
            collections: [collection(1, 600)],
            deleted: [],
            cursor: 600,
        });
        client.filesFor(1, {
            files: [file(1002, 1, 550)],
            deleted: [],
            cursor: 550,
        });

        const lib = await Library.open({ client, cacheDirectory });
        try {
            // The initial refresh resumed collections from the stored cursor.
            expect(client.collectionsSinceTimes[0]).toBe(500);
            // Files were re-enumerated from the stored collection updationTime.
            expect(client.filesCalls).toEqual([
                { collectionID: 1, sinceTime: 400 },
            ]);
            expect(lib.listFiles(1).map((f) => f.id)).toEqual([1001, 1002]);
        } finally {
            lib.close();
        }
    });

    it("does not re-enumerate a collection whose updationTime did not advance", async () => {
        const path = join(cacheDirectory, "metadata.json");
        const seed = await MetadataStore.load(path);
        seed.userID = USER_ID;
        seed.collectionsSinceTime = 100;
        seed.putCollection(collection(1, 400));
        await seed.save();

        const client = new MockClient();
        // The collection comes back in the diff (its metadata changed) but at
        // the same updationTime, so its files must not be re-fetched.
        client.collectionsQueue.push({
            collections: [collection(1, 400, "renamed")],
            deleted: [],
            cursor: 400,
        });

        const lib = await Library.open({ client, cacheDirectory });
        try {
            expect(client.filesCalls).toEqual([]);
            expect(lib.getCollection(1)?.name).toBe("renamed");
        } finally {
            lib.close();
        }
    });

    it("applies diffs and tombstones on the interval", async () => {
        const client = new MockClient();
        client.collectionsQueue.push({
            collections: [collection(1, 100), collection(2, 100)],
            deleted: [],
            cursor: 100,
        });
        client.filesFor(1, {
            files: [file(1001, 1, 90)],
            deleted: [],
            cursor: 90,
        });
        client.filesFor(2, {
            files: [file(2001, 2, 90)],
            deleted: [],
            cursor: 90,
        });

        const lib = await Library.open({
            client,
            cacheDirectory,
            refreshIntervalSeconds: FAST_INTERVAL,
        });
        try {
            expect(lib.listCollections().map((c) => c.id)).toEqual([1, 2]);
            expect(lib.listFiles(2).map((f) => f.id)).toEqual([2001]);

            // Next refresh: collection 2 is tombstoned; collection 1 gains a
            // file and loses its old one.
            client.filesFor(1, {
                files: [file(1002, 1, 190)],
                deleted: [1001],
                cursor: 190,
            });
            client.collectionsQueue.push({
                collections: [collection(1, 200)],
                deleted: [2],
                cursor: 200,
            });

            await vi.waitFor(
                () => {
                    expect(lib.listCollections().map((c) => c.id)).toEqual([1]);
                    expect(lib.listFiles(1).map((f) => f.id)).toEqual([1002]);
                    // Collection 2's files went with it.
                    expect(lib.listFiles(2)).toEqual([]);
                },
                { timeout: 2000, interval: 5 },
            );
        } finally {
            lib.close();
        }
    });

    it("rewrites the cache only when a refresh changes something", async () => {
        const saveSpy = vi.spyOn(MetadataStore.prototype, "save");
        const client = new MockClient();
        client.collectionsQueue.push({
            collections: [collection(1, 100)],
            deleted: [],
            cursor: 100,
        });
        client.filesFor(1, {
            files: [file(1001, 1, 90)],
            deleted: [],
            cursor: 90,
        });

        const lib = await Library.open({
            client,
            cacheDirectory,
            refreshIntervalSeconds: FAST_INTERVAL,
        });
        try {
            // The initial refresh changed everything, so it saved once.
            expect(saveSpy).toHaveBeenCalledTimes(1);

            // Several empty-diff ticks pass; none of them may rewrite the file.
            await new Promise((r) => setTimeout(r, FAST_INTERVAL * 1000 * 4));
            expect(saveSpy).toHaveBeenCalledTimes(1);

            // A real change triggers exactly one more rewrite; later empty ticks
            // still do not, so the count settles at two.
            client.collectionsQueue.push({
                collections: [collection(2, 200)],
                deleted: [],
                cursor: 200,
            });
            await vi.waitFor(() => expect(saveSpy).toHaveBeenCalledTimes(2), {
                timeout: 2000,
                interval: 5,
            });
            await new Promise((r) => setTimeout(r, FAST_INTERVAL * 1000 * 4));
            expect(saveSpy).toHaveBeenCalledTimes(2);
        } finally {
            lib.close();
            saveSpy.mockRestore();
        }
    });

    it("keeps a failed refresh invisible to reads and recovers later", async () => {
        const events: RefreshEvent[] = [];
        const client = new MockClient();
        client.collectionsQueue.push({
            collections: [collection(1, 100)],
            deleted: [],
            cursor: 100,
        });
        client.filesFor(1, {
            files: [file(1001, 1, 90)],
            deleted: [],
            cursor: 90,
        });

        const lib = await Library.open({
            client,
            cacheDirectory,
            refreshIntervalSeconds: FAST_INTERVAL,
            onProgress: (e) => events.push(e),
        });
        try {
            expect(lib.listFiles(1).map((f) => f.id)).toEqual([1001]);

            // The server goes away; refreshes now fail.
            client.failCollections = true;
            await vi.waitFor(
                () => expect(lib.status().lastError).toMatch(/network down/),
                { timeout: 2000, interval: 5 },
            );

            // Reads still see the last good data; the failure was reported.
            expect(lib.listFiles(1).map((f) => f.id)).toEqual([1001]);
            expect(
                events.some(
                    (e) => e.operation === "refresh" && e.status === "failed",
                ),
            ).toBe(true);

            // Recovery: a later refresh succeeds and clears the error.
            client.failCollections = false;
            client.collectionsQueue.push({
                collections: [collection(2, 300)],
                deleted: [],
                cursor: 300,
            });
            await vi.waitFor(
                () => {
                    expect(lib.status().lastError).toBeUndefined();
                    expect(lib.listCollections().map((c) => c.id)).toEqual([
                        1, 2,
                    ]);
                },
                { timeout: 2000, interval: 5 },
            );
        } finally {
            lib.close();
        }
    });

    it("resolves open() even when the first refresh fails", async () => {
        const client = new MockClient();
        client.failCollections = true;
        const events: RefreshEvent[] = [];

        const lib = await Library.open({
            client,
            cacheDirectory,
            onProgress: (e) => events.push(e),
        });
        try {
            // Nothing was cached and the server is unreachable: reads are empty,
            // but the library opened and the failure is on record.
            expect(lib.listCollections()).toEqual([]);
            expect(lib.status().lastError).toMatch(/network down/);
            expect(lib.status().lastRefreshAt).toBeUndefined();
            expect(
                events.some(
                    (e) => e.operation === "refresh" && e.status === "failed",
                ),
            ).toBe(true);
        } finally {
            lib.close();
        }
    });

    it("close() stops the timer and is idempotent", async () => {
        const client = new MockClient();

        const lib = await Library.open({
            client,
            cacheDirectory,
            refreshIntervalSeconds: FAST_INTERVAL,
        });
        const callsAfterOpen = client.collectionsSinceTimes.length;

        lib.close();
        lib.close(); // second close must not throw
        expect(lib.status().closed).toBe(true);

        // No further refreshes fire once closed.
        await new Promise((r) => setTimeout(r, FAST_INTERVAL * 1000 * 5));
        expect(client.collectionsSinceTimes.length).toBe(callsAfterOpen);
    });

    it("defaults cacheDirectory to the env-paths cache dir plus user id", async () => {
        const xdg = join(dir, "xdg-cache");
        const prev = process.env.XDG_CACHE_HOME;
        process.env.XDG_CACHE_HOME = xdg;
        try {
            const client = new MockClient();
            const lib = await Library.open({ client });
            try {
                const expected = join(
                    envPaths("quak", { suffix: "" }).cache,
                    String(USER_ID),
                );
                expect(lib.cacheDirectory).toBe(expected);
                expect(lib.cacheDirectory.startsWith(xdg)).toBe(true);
                expect(lib.cacheDirectory.endsWith(String(USER_ID))).toBe(true);
            } finally {
                lib.close();
            }
        } finally {
            if (prev === undefined) delete process.env.XDG_CACHE_HOME;
            else process.env.XDG_CACHE_HOME = prev;
        }
    });
});