@carlonicora/nextjs-jsonapi 6.12.2 → 6.13.1

package/src/offline/store/DeviceStore.ts

@@ -0,0 +1,112 @@
+import type { OfflineChangeResolution } from "../sync/models/OfflineChangeSetInterface";
+import type { OfflineMethod } from "../types";
+
+export type StoredRecord = {
+  type: string;
+  id: string;
+  rootId: string;
+  resource: any;
+  updatedAt: Date | null;
+  base: any | null;
+  localOnly: boolean;
+};
+
+export type StoredLink = {
+  fromType: string;
+  fromId: string;
+  toType: string;
+  toId: string;
+  kind: string;
+  props: Record<string, unknown>;
+};
+
+export type QueueStatus = "pending" | "sending" | "conflict" | "failed";
+
+/** The `resolution` of a server-side `OfflineChange` (C1b): kind, per-field choices, merged body. */
+export type QueueResolution = OfflineChangeResolution;
+
+export type QueueEntry = {
+  seq: number;
+  rootId: string;
+  method: OfflineMethod;
+  path: string;
+  body?: any;
+  recordType?: string;
+  recordId?: string;
+  base: any | null;
+  resolution?: QueueResolution;
+  createdAt: Date;
+  status: QueueStatus;
+  /**
+   * The id of the package (`offline-change-sets`) the entry was last sent in, kept until the
+   * server answers for it: a package that never got its answer is sent again with the same id,
+   * so the server applies it once.
+   */
+  packageId?: string;
+};
+
+export type ConflictKind = "fields" | "deleted-on-server" | "changed-on-server" | "could-not-apply";
+
+export type Conflict = {
+  id: string;
+  queueSeq: number;
+  kind: ConflictKind;
+  recordType?: string;
+  recordId?: string;
+  mine: any;
+  theirs: any;
+  base: any;
+  /** The merge the server settled, as a resource: its current resource with the merged attributes. */
+  merged?: any;
+  fields: string[];
+  blocks?: Record<string, string[]>;
+  reason?: string;
+};
+
+export type SyncState = { serverTime: Date | null; locked: boolean; lockedFrom: Date | null };
+
+/** A record a sync could not read (403/404, or absent from the answer), with its `updatedAt` then. */
+export type SkippedRecord = { type: string; id: string; updatedAt: Date };
+
+export interface DeviceStore {
+  getRecord(type: string, id: string): Promise<StoredRecord | undefined>;
+  /** With `rootId`: every record that root record uses, shared records included. */
+  listRecords(filter: { type: string; rootId?: string; ids?: string[] }): Promise<StoredRecord[]>;
+  putRecord(
+    record: Omit<StoredRecord, "base" | "localOnly"> & { base?: any | null; localOnly?: boolean },
+  ): Promise<void>;
+  /** Removes the record (every root record's copy) and every link from or to it. */
+  deleteRecord(type: string, id: string): Promise<void>;
+  /**
+   * The record leaves `rootId`. A shared record (an artwork, a template) that another
+   * root record still uses is kept for that root record; it is deleted only when no root record keeps it.
+   */
+  removeRecordFromRoot(type: string, id: string, rootId: string): Promise<void>;
+  linksFrom(fromId: string, kind?: string): Promise<StoredLink[]>;
+  linksTo(toId: string, kind?: string): Promise<StoredLink[]>;
+  replaceRootLinks(rootId: string, links: StoredLink[]): Promise<void>;
+  putLink(link: StoredLink): Promise<void>;
+  deleteLink(link: Pick<StoredLink, "fromId" | "toId" | "kind">): Promise<void>;
+  enqueue(entry: Omit<QueueEntry, "seq" | "createdAt" | "status">): Promise<number>;
+  queue(filter?: { status?: QueueStatus }): Promise<QueueEntry[]>;
+  setQueueStatus(seq: number, status: QueueStatus): Promise<void>;
+  /** Stores (or with `null` clears) the package id of the given entries. */
+  setQueuePackage(seqs: number[], packageId: string | null): Promise<void>;
+  removeQueueEntry(seq: number): Promise<void>;
+  addConflict(c: Omit<Conflict, "id">): Promise<string>;
+  conflicts(): Promise<Conflict[]>;
+  removeConflict(id: string): Promise<void>;
+  getSyncState(rootId: string): Promise<SyncState>;
+  /** The store writes ISO strings and parses them back with `new Date`. */
+  setSyncState(rootId: string, s: SyncState): Promise<void>;
+  /** The records the last sync of `rootId` skipped: asked for again only once they change. */
+  skippedRecords(rootId: string): Promise<SkippedRecord[]>;
+  /** Replaces the skipped records of `rootId`. */
+  setSkippedRecords(rootId: string, records: SkippedRecord[]): Promise<void>;
+  /**
+   * Records, links, queue, conflicts, sync_state, skipped records — kept only when its queue is empty. A shared
+   * record another root record still uses is kept for that root record.
+   */
+  removeRoot(rootId: string): Promise<void>;
+  transaction<T>(fn: (store: DeviceStore) => Promise<T>): Promise<T>;
+}

package/src/offline/store/__tests__/device-store-lifecycle.spec.ts

@@ -0,0 +1,343 @@
+import { afterEach, beforeEach, describe, expect, it, vi, type MockInstance } from "vitest";
+import {
+  blockOfflineStore,
+  configureOffline,
+  DeviceStoreUnavailableError,
+  getOfflineStore,
+  isOfflineConfigured,
+  OfflineUnavailableError,
+  resetOfflineConfig,
+  setDeviceStoreOpener,
+} from "../../config";
+import { getOfflineState, resetOfflineState } from "../../state";
+import { NeedsConnectionError, type OfflineConfig } from "../../types";
+import {
+  deleteDeviceStore,
+  hasUnsentChanges,
+  onUserSignedIn,
+  openDeviceStore,
+  openMemoryDatabase,
+  setDeviceStoreBackend,
+  type OfflineDirectory,
+} from "../lifecycle";
+import { fakeCacheStorage } from "../../sync/__tests__/sync-fixtures";
+
+/** An in-memory stand-in for the OPFS root directory. */
+const fakeDirectory = () => {
+  const entries = new Set<string>();
+  const directory: OfflineDirectory = {
+    async *keys() {
+      for (const name of [...entries]) yield name;
+    },
+    async getFileHandle(name, options) {
+      if (!entries.has(name)) {
+        if (!options?.create) throw Object.assign(new Error(name), { name: "NotFoundError" });
+        entries.add(name);
+      }
+      return {};
+    },
+    async removeEntry(name) {
+      if (!entries.delete(name)) throw Object.assign(new Error(name), { name: "NotFoundError" });
+    },
+  };
+  return { entries, directory };
+};
+
+describe("device store lifecycle", () => {
+  let entries: Set<string>;
+  let opened: string[];
+  let persisted: number;
+
+  beforeEach(() => {
+    const fake = fakeDirectory();
+    entries = fake.entries;
+    opened = [];
+    persisted = 0;
+    setDeviceStoreBackend({
+      getDirectory: async () => fake.directory,
+      openDatabase: async (_userId, fileName) => {
+        opened.push(fileName);
+        const created = !entries.has(fileName);
+        entries.add(fileName);
+        const database = await openMemoryDatabase();
+        return { ...database, created };
+      },
+      requestPersistence: vi.fn(async () => {
+        persisted += 1;
+      }),
+    });
+  });
+
+  afterEach(() => {
+    setDeviceStoreBackend(null);
+  });
+
+  it("keeps another user's database that has unsent changes", async () => {
+    const storeA = await openDeviceStore("user-a");
+    await storeA.enqueue({ rootId: "C", method: "PATCH", path: "npcs/n1", base: { type: "npcs", id: "n1" } });
+    // User A's sign-in expired without a logout; user B signs in on the same browser.
+
+    await onUserSignedIn("user-b");
+    await openDeviceStore("user-b");
+
+    expect(entries.has("nja-offline-user-a.sqlite3")).toBe(true);
+    expect(await hasUnsentChanges("user-a")).toBe(true);
+    expect(opened).toEqual(["nja-offline-user-a.sqlite3", "nja-offline-user-b.sqlite3"]);
+  });
+
+  it("deletes another user's database with an empty queue", async () => {
+    const storeA = await openDeviceStore("user-a");
+    const seq = await storeA.enqueue({ rootId: "C", method: "DELETE", path: "npcs/n1", base: null });
+    await storeA.putRecord({ type: "npcs", id: "n2", rootId: "C", resource: {}, updatedAt: null });
+    await storeA.removeQueueEntry(seq);
+    expect(await hasUnsentChanges("user-a")).toBe(false);
+
+    await onUserSignedIn("user-b");
+
+    expect([...entries].filter((name) => name.includes("user-a"))).toEqual([]);
+  });
+
+  describe("the artwork images cache", () => {
+    afterEach(() => vi.unstubAllGlobals());
+
+    it("is deleted when a different user signs in, and kept when the same user signs in again", async () => {
+      const cache = fakeCacheStorage(["wyrdli-offline-1", "wyrdli-images"]);
+      vi.stubGlobal("caches", cache.storage);
+
+      await onUserSignedIn("user-a");
+      // user-a's sync downloads their artwork.
+      await (await cache.storage.open("wyrdli-images")).put("http://api.test/artworks/a1/image", {});
+      await onUserSignedIn("user-a");
+      expect(cache.caches.get("wyrdli-images")?.has("http://api.test/artworks/a1/image")).toBe(true);
+
+      await onUserSignedIn("user-b");
+      expect(cache.caches.has("wyrdli-images")).toBe(false);
+      expect(cache.caches.has("wyrdli-offline-1")).toBe(true);
+    });
+
+    it("is deleted when a different user signs in while the first user's database has unsent changes", async () => {
+      const cache = fakeCacheStorage(["wyrdli-offline-1", "wyrdli-images"]);
+      vi.stubGlobal("caches", cache.storage);
+      await onUserSignedIn("user-a");
+      const storeA = await openDeviceStore("user-a");
+      await storeA.enqueue({ rootId: "C", method: "PATCH", path: "npcs/n1", base: null });
+
+      await onUserSignedIn("user-b");
+
+      expect(cache.caches.has("wyrdli-images")).toBe(false);
+      expect(entries.has("nja-offline-user-a.sqlite3")).toBe(true);
+    });
+  });
+
+  it("never opens a file for a user other than the one asked", async () => {
+    entries.add("nja-offline-user-a.sqlite3");
+    entries.add("nja-offline-user-a.pending");
+    entries.add(".nja-offline-user-c");
+
+    const store = await openDeviceStore("user-b");
+    expect(await openDeviceStore("user-b")).toBe(store);
+    expect(await hasUnsentChanges("user-a")).toBe(true);
+    await onUserSignedIn("user-b");
+
+    expect(opened).toEqual(["nja-offline-user-b.sqlite3"]);
+    expect(entries.has("nja-offline-user-a.sqlite3")).toBe(true);
+    expect(entries.has(".nja-offline-user-c")).toBe(false);
+  });
+
+  it("requests persistent storage only when the file is first created", async () => {
+    await openDeviceStore("user-a");
+    await deleteDeviceStore("user-a");
+    expect(persisted).toBe(1);
+    expect(entries.size).toBe(0);
+
+    entries.add("nja-offline-user-a.sqlite3");
+    await openDeviceStore("user-a");
+    expect(persisted).toBe(1);
+  });
+
+  it("keeps the unsent-changes mark when a transaction that emptied the queue rolls back", async () => {
+    const store = await openDeviceStore("user-a");
+    const seq = await store.enqueue({ rootId: "C", method: "PATCH", path: "npcs/n1", base: null });
+
+    await expect(
+      store.transaction(async (tx) => {
+        await tx.removeQueueEntry(seq);
+        throw new Error("boom");
+      }),
+    ).rejects.toThrow("boom");
+
+    expect(entries.has("nja-offline-user-a.pending")).toBe(true);
+    expect(await hasUnsentChanges("user-a")).toBe(true);
+  });
+
+  describe("getOfflineStore", () => {
+    const config = (userId: string): OfflineConfig => ({
+      getUserId: () => userId,
+      rootModule: { name: "roots" } as any,
+      types: [],
+      routes: [],
+      listSyncRoots: async () => [],
+      shellPath: () => "/offline-shell",
+      syncIntervalMs: 300000,
+    });
+
+    afterEach(() => resetOfflineConfig());
+
+    it("a store that cannot be opened (a second tab holds the SQLite file) is a needs-connection error", async () => {
+      configureOffline(config("user-a"));
+      setDeviceStoreOpener(async () => {
+        throw new Error("NoModificationAllowedError: Access Handles cannot be created");
+      });
+
+      const error = await getOfflineStore().catch((caught) => caught);
+
+      expect(error).toBeInstanceOf(DeviceStoreUnavailableError);
+      expect(error).toBeInstanceOf(NeedsConnectionError);
+      expect(error.status).toBe(503);
+      // A real failure on a browser that can keep the copy never switches offline mode off.
+      expect(error).not.toBeInstanceOf(OfflineUnavailableError);
+      expect(getOfflineState().available).toBe(true);
+      expect(isOfflineConfigured()).toBe(true);
+    });
+
+    it("a blocked user's store (logged out) is never opened again until that user signs in", async () => {
+      configureOffline(config("user-a"));
+      const opener = vi.fn(async () => openDeviceStore("user-a"));
+      setDeviceStoreOpener(opener);
+
+      blockOfflineStore("user-a");
+      await expect(getOfflineStore()).rejects.toBeInstanceOf(DeviceStoreUnavailableError);
+      await expect(openDeviceStore("user-a")).rejects.toBeInstanceOf(DeviceStoreUnavailableError);
+      expect(opener).not.toHaveBeenCalled();
+      expect(opened).toEqual([]);
+
+      await onUserSignedIn("user-a");
+      await getOfflineStore();
+      expect(opener).toHaveBeenCalledTimes(1);
+      expect(opened).toEqual(["nja-offline-user-a.sqlite3"]);
+    });
+  });
+
+  describe("a browser that cannot keep the device copy", () => {
+    const config: OfflineConfig = {
+      getUserId: () => "user-a",
+      rootModule: { name: "roots", model: class {} },
+      types: [],
+      routes: [],
+      listSyncRoots: async () => [],
+      shellPath: () => "/offline-shell",
+      syncIntervalMs: 300000,
+    };
+
+    /** A device worker whose "open" fails the way SQLite does without the OPFS sync-access handles. */
+    const workers: string[] = [];
+    class OpfsMissingWorker {
+      onmessage: ((event: { data: unknown }) => void) | null = null;
+      onerror: ((event: unknown) => void) | null = null;
+      constructor(url: string) {
+        workers.push(url);
+      }
+      postMessage(message: { id: number }) {
+        queueMicrotask(() =>
+          this.onmessage?.({ data: { id: message.id, ok: false, error: "Missing required OPFS APIs." } }),
+        );
+      }
+      terminate() {}
+    }
+
+    let warn: MockInstance<typeof console.warn>;
+
+    beforeEach(() => {
+      workers.length = 0;
+      resetOfflineState();
+      configureOffline(config);
+      setDeviceStoreOpener((userId) => openDeviceStore(userId));
+      warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+      vi.stubGlobal("Worker", OpfsMissingWorker);
+    });
+
+    afterEach(() => {
+      warn.mockRestore();
+      vi.unstubAllGlobals();
+      resetOfflineConfig();
+      resetOfflineState();
+    });
+
+    it("not a secure context (a custom http dev host): the sign-in switches offline mode off, once, without starting a worker", async () => {
+      setDeviceStoreBackend(null);
+      vi.stubGlobal("isSecureContext", false);
+
+      await expect(onUserSignedIn("user-a")).resolves.toBeUndefined();
+
+      expect(getOfflineState().available).toBe(false);
+      expect(isOfflineConfigured()).toBe(false);
+      expect(warn).toHaveBeenCalledTimes(1);
+
+      // Later uses never try again and never warn again.
+      await expect(getOfflineStore()).rejects.toBeInstanceOf(OfflineUnavailableError);
+      await expect(openDeviceStore("user-a")).rejects.toBeInstanceOf(OfflineUnavailableError);
+      await expect(hasUnsentChanges("user-a")).resolves.toBe(false);
+      await expect(deleteDeviceStore("user-a")).resolves.toBeUndefined();
+      await onUserSignedIn("user-a");
+      expect(workers).toEqual([]);
+      expect(warn).toHaveBeenCalledTimes(1);
+    });
+
+    it("no private file storage (navigator.storage.getDirectory missing): offline mode is off", async () => {
+      setDeviceStoreBackend(null);
+      vi.stubGlobal("isSecureContext", true);
+      vi.stubGlobal("navigator", { onLine: true });
+
+      await onUserSignedIn("user-a");
+
+      expect(getOfflineState().available).toBe(false);
+      expect(workers).toEqual([]);
+      expect(warn).toHaveBeenCalledTimes(1);
+    });
+
+    it("the worker reports the OPFS APIs missing: the open is an unavailable browser, warned once, and no worker starts again", async () => {
+      const fake = fakeDirectory();
+      vi.stubGlobal("isSecureContext", true);
+      vi.stubGlobal("navigator", { onLine: true, storage: { getDirectory: async () => fake.directory } });
+      // The browser's database opener (the worker), over a fake directory.
+      setDeviceStoreBackend({ getDirectory: async () => fake.directory });
+
+      await onUserSignedIn("user-a");
+      expect(getOfflineState().available).toBe(true);
+
+      const [first, second] = await Promise.all([
+        getOfflineStore().catch((caught) => caught),
+        getOfflineStore().catch((caught) => caught),
+      ]);
+
+      expect(first).toBeInstanceOf(OfflineUnavailableError);
+      expect(second).toBe(first);
+      expect(workers).toHaveLength(1);
+      expect(getOfflineState().available).toBe(false);
+      expect(isOfflineConfigured()).toBe(false);
+      expect(warn).toHaveBeenCalledTimes(1);
+
+      await expect(getOfflineStore()).rejects.toBeInstanceOf(OfflineUnavailableError);
+      expect(workers).toHaveLength(1);
+      expect(warn).toHaveBeenCalledTimes(1);
+    });
+
+    it("a storage SecurityError (some private windows) is an unavailable browser", async () => {
+      setDeviceStoreBackend(null);
+      vi.stubGlobal("isSecureContext", true);
+      vi.stubGlobal("navigator", {
+        onLine: true,
+        storage: {
+          getDirectory: async () => {
+            throw Object.assign(new Error("Security error when calling GetDirectory"), { name: "SecurityError" });
+          },
+        },
+      });
+
+      await onUserSignedIn("user-a");
+
+      expect(getOfflineState().available).toBe(false);
+      expect(warn).toHaveBeenCalledTimes(1);
+    });
+  });
+});

package/src/offline/store/__tests__/shared-database.spec.ts

@@ -0,0 +1,151 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { openSharedDatabase, withDatabaseReleased } from "../shared-database";
+import type { OpenedDatabase } from "../worker-client";
+
+/** A minimal Web Locks manager shared by every simulated page (exclusive locks, a FIFO queue). */
+function fakeLocks() {
+  const held = new Set<string>();
+  const queues = new Map<string, (() => void)[]>();
+  const next = (name: string) => {
+    const waiting = queues.get(name);
+    const run = waiting?.shift();
+    if (run) run();
+    else held.delete(name);
+  };
+  return {
+    request(name: string, ...args: any[]): Promise<unknown> {
+      const callback = args[args.length - 1] as (lock: unknown) => Promise<unknown>;
+      const options = (args.length > 1 ? args[0] : {}) as { ifAvailable?: boolean; signal?: AbortSignal };
+      return new Promise((resolve, reject) => {
+        const grant = () => {
+          Promise.resolve(callback({ name }))
+            .then(resolve, reject)
+            .finally(() => next(name));
+        };
+        if (!held.has(name)) {
+          held.add(name);
+          grant();
+          return;
+        }
+        if (options.ifAvailable) {
+          Promise.resolve(callback(null)).then(resolve, reject);
+          return;
+        }
+        const queue = queues.get(name) ?? [];
+        queue.push(grant);
+        queues.set(name, queue);
+        options.signal?.addEventListener("abort", () => {
+          const index = queue.indexOf(grant);
+          if (index >= 0) queue.splice(index, 1);
+          reject(Object.assign(new Error("aborted"), { name: "AbortError" }));
+        });
+      });
+    },
+    query: async () => ({ held: [...held].map((name) => ({ name })) }),
+  };
+}
+
+/** A fake database recording every statement, in order, with the page that sent it. */
+function fakeDatabase(log: string[], label: string): OpenedDatabase {
+  return {
+    created: true,
+    exec: async (sql) => {
+      log.push(`${label}:${sql}`);
+      await new Promise((resolve) => setTimeout(resolve, 1));
+      return [{ sql }];
+    },
+    close: vi.fn(async () => undefined),
+  };
+}
+
+const settle = () => new Promise((resolve) => setTimeout(resolve, 20));
+
+describe("shared device database", () => {
+  beforeEach(() => {
+    vi.stubGlobal("navigator", { ...navigator, locks: fakeLocks() });
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it("the first page holds the database; a second page sends its statements to it and gets the answers", async () => {
+    const log: string[] = [];
+    const openA = vi.fn(async () => fakeDatabase(log, "files"));
+    const openB = vi.fn(async () => fakeDatabase(log, "never"));
+
+    const a = await openSharedDatabase("u1", openA);
+    const b = await openSharedDatabase("u1", openB);
+
+    expect(openA).toHaveBeenCalledTimes(1);
+    expect(openB).not.toHaveBeenCalled();
+    expect(await b.exclusive(() => b.exec("SELECT 1"))).toEqual([{ sql: "SELECT 1" }]);
+    expect(log).toEqual(["files:SELECT 1"]);
+
+    await b.close();
+    await a.close();
+  });
+
+  it("a transaction of one page never interleaves with another page's statements", async () => {
+    const log: string[] = [];
+    const a = await openSharedDatabase("u2", async () => fakeDatabase(log, "db"));
+    const b = await openSharedDatabase("u2", async () => fakeDatabase(log, "never"));
+
+    await Promise.all([
+      b.exclusive(async () => {
+        await b.exec("BEGIN");
+        await b.exec("B1");
+        await b.exec("COMMIT");
+      }),
+      a.exclusive(async () => {
+        await a.exec("BEGIN");
+        await a.exec("A1");
+        await a.exec("COMMIT");
+      }),
+    ]);
+
+    const statements = log.map((line) => line.split(":")[1]);
+    const firstCommit = statements.indexOf("COMMIT");
+    expect(statements.slice(0, firstCommit + 1)).toHaveLength(3);
+    expect(statements.slice(firstCommit + 1)).toHaveLength(3);
+    expect(new Set(statements.slice(0, 3))).not.toEqual(new Set(["BEGIN", "A1", "B1"]));
+
+    await b.close();
+    await a.close();
+  });
+
+  it("when the holder closes, the waiting page takes over, opening the files itself (retrying while they are released)", async () => {
+    const log: string[] = [];
+    const a = await openSharedDatabase("u3", async () => fakeDatabase(log, "a"));
+    let attempts = 0;
+    const openB = vi.fn(async () => {
+      attempts++;
+      if (attempts === 1) throw new Error("NoModificationAllowedError: Access Handles cannot be created");
+      return fakeDatabase(log, "b");
+    });
+    const b = await openSharedDatabase("u3", openB);
+
+    await a.close();
+    await new Promise((resolve) => setTimeout(resolve, 300));
+
+    expect(openB).toHaveBeenCalledTimes(2);
+    expect(await b.exclusive(() => b.exec("SELECT 2"))).toEqual([{ sql: "SELECT 2" }]);
+    expect(log).toEqual(["b:SELECT 2"]);
+    await b.close();
+  });
+
+  it("withDatabaseReleased closes the copy in every page before running the removal", async () => {
+    const log: string[] = [];
+    const database = fakeDatabase(log, "a");
+    const onShutdown = vi.fn();
+    await openSharedDatabase("u4", async () => database, onShutdown);
+
+    const removal = vi.fn(async () => "removed");
+    expect(await withDatabaseReleased("u4", removal)).toBe("removed");
+    await settle();
+
+    expect(database.close).toHaveBeenCalled();
+    expect(onShutdown).toHaveBeenCalled();
+    expect(removal).toHaveBeenCalledTimes(1);
+  });
+});