@ifc-lite/viewer 1.23.0 → 1.25.0

package/src/services/extensions/idb-flavor-storage.ts

@@ -0,0 +1,241 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
+
+/**
+ * IndexedDB-backed implementation of the `FlavorStorage` interface
+ * from `@ifc-lite/extensions`.
+ *
+ * Three object stores:
+ *   - `flavors`       keyed by flavor id        → Flavor
+ *   - `flavor-active` single-row key 'active'   → { id }
+ *   - `flavor-snaps`  keyed by `<flavorId>@<seq>` → FlavorSnapshot
+ *
+ * The schema mirrors the in-memory storage in `@ifc-lite/extensions/flavor/storage.ts`
+ * but persists across reloads. Snapshot cap of 10 per flavor is enforced
+ * client-side (same as the in-memory impl).
+ */
+
+import type { Flavor, FlavorSnapshot, FlavorStorage } from '@ifc-lite/extensions';
+import { ExtensionStorageQuotaError } from './idb-storage.js';
+
+const DB_NAME = 'ifc-lite-flavors';
+/** See idb-storage.ts for the migration policy. */
+const DB_VERSION = 1;
+const STORE_FLAVORS = 'flavors';
+const STORE_ACTIVE = 'flavor-active';
+const STORE_SNAPS = 'flavor-snaps';
+const SNAPSHOT_CAP = 10;
+const ACTIVE_KEY = 'active';
+
+let dbPromise: Promise<IDBDatabase> | null = null;
+
+interface SnapshotRow extends FlavorSnapshot {
+  /** Compound key `<flavorId>@<seq>` so IDB can index without composite keys. */
+  key: string;
+  flavorId: string;
+}
+
+/**
+ * Resolve once a readwrite transaction commits. Rejects on both
+ * `error` AND `abort` — an aborted transaction fires neither
+ * `oncomplete` nor `onerror`, so without the `onabort` branch the
+ * returned promise would hang forever.
+ */
+function txDone(tx: IDBTransaction): Promise<void> {
+  return new Promise<void>((resolve, reject) => {
+    tx.oncomplete = () => resolve();
+    tx.onerror = () => reject(tx.error ?? new Error('Flavor IDB transaction failed.'));
+    tx.onabort = () => reject(tx.error ?? new Error('Flavor IDB transaction aborted.'));
+  });
+}
+
+function isQuotaError(err: unknown): boolean {
+  if (!err || typeof err !== 'object') return false;
+  const name = (err as { name?: unknown }).name;
+  return name === 'QuotaExceededError' || name === 'NS_ERROR_DOM_QUOTA_REACHED';
+}
+
+async function withQuotaGuard<T>(operation: string, fn: () => Promise<T>): Promise<T> {
+  try {
+    return await fn();
+  } catch (err) {
+    if (isQuotaError(err)) {
+      throw new ExtensionStorageQuotaError(operation, err);
+    }
+    throw err;
+  }
+}
+
+export class IdbFlavorStorage implements FlavorStorage {
+  async putFlavor(flavor: Flavor, reason?: string): Promise<void> {
+    const db = await openDatabase();
+    const previous = await this.getFlavor(flavor.id);
+    if (previous) {
+      await this.recordSnapshot(db, previous, reason);
+    }
+    await withQuotaGuard(`saving flavor "${flavor.id}"`, async () => {
+      const tx = db.transaction(STORE_FLAVORS, 'readwrite');
+      tx.objectStore(STORE_FLAVORS).put(flavor);
+      await txDone(tx);
+    });
+  }
+
+  async getFlavor(id: string): Promise<Flavor | undefined> {
+    const db = await openDatabase();
+    return new Promise((resolve, reject) => {
+      const tx = db.transaction(STORE_FLAVORS, 'readonly');
+      const req = tx.objectStore(STORE_FLAVORS).get(id);
+      req.onsuccess = () => resolve((req.result as Flavor | undefined) ?? undefined);
+      req.onerror = () => reject(req.error);
+    });
+  }
+
+  async listFlavors(): Promise<Flavor[]> {
+    const db = await openDatabase();
+    return new Promise((resolve, reject) => {
+      const tx = db.transaction(STORE_FLAVORS, 'readonly');
+      const req = tx.objectStore(STORE_FLAVORS).getAll();
+      req.onsuccess = () => resolve((req.result as Flavor[] | undefined) ?? []);
+      req.onerror = () => reject(req.error);
+    });
+  }
+
+  async deleteFlavor(id: string): Promise<void> {
+    const db = await openDatabase();
+    // Drop the flavor itself + cascade its snapshots.
+    const tx = db.transaction([STORE_FLAVORS, STORE_SNAPS], 'readwrite');
+    tx.objectStore(STORE_FLAVORS).delete(id);
+    const snaps = tx.objectStore(STORE_SNAPS);
+    const cursorReq = snaps.openCursor();
+    cursorReq.onsuccess = () => {
+      const cursor = cursorReq.result;
+      if (!cursor) return;
+      const row = cursor.value as SnapshotRow;
+      if (row.flavorId === id) cursor.delete();
+      cursor.continue();
+    };
+    await txDone(tx);
+    // If we deleted the active flavor, clear the pointer.
+    const activeId = await this.getActiveId();
+    if (activeId === id) await this.setActiveId(undefined);
+  }
+
+  async getActiveId(): Promise<string | undefined> {
+    const db = await openDatabase();
+    return new Promise((resolve, reject) => {
+      const tx = db.transaction(STORE_ACTIVE, 'readonly');
+      const req = tx.objectStore(STORE_ACTIVE).get(ACTIVE_KEY);
+      req.onsuccess = () => resolve((req.result as { id?: string } | undefined)?.id);
+      req.onerror = () => reject(req.error);
+    });
+  }
+
+  async setActiveId(id: string | undefined): Promise<void> {
+    const db = await openDatabase();
+    const tx = db.transaction(STORE_ACTIVE, 'readwrite');
+    const store = tx.objectStore(STORE_ACTIVE);
+    if (id === undefined) {
+      store.delete(ACTIVE_KEY);
+    } else {
+      store.put({ key: ACTIVE_KEY, id });
+    }
+    await txDone(tx);
+  }
+
+  async listSnapshots(flavorId: string): Promise<FlavorSnapshot[]> {
+    return (await this.listSnapshotRows(flavorId))
+      .map(({ key, flavorId: _id, ...rest }) => rest as FlavorSnapshot);
+  }
+
+  async restoreSnapshot(flavorId: string, seq: number, reason?: string): Promise<Flavor | undefined> {
+    const db = await openDatabase();
+    const snap = await new Promise<SnapshotRow | undefined>((resolve, reject) => {
+      const tx = db.transaction(STORE_SNAPS, 'readonly');
+      const req = tx.objectStore(STORE_SNAPS).get(`${flavorId}@${seq}`);
+      req.onsuccess = () => resolve(req.result as SnapshotRow | undefined);
+      req.onerror = () => reject(req.error);
+    });
+    if (!snap) return undefined;
+    await this.putFlavor(snap.flavor, reason ?? 'restored from snapshot');
+    return snap.flavor;
+  }
+
+  async clear(): Promise<void> {
+    const db = await openDatabase();
+    const tx = db.transaction([STORE_FLAVORS, STORE_ACTIVE, STORE_SNAPS], 'readwrite');
+    tx.objectStore(STORE_FLAVORS).clear();
+    tx.objectStore(STORE_ACTIVE).clear();
+    tx.objectStore(STORE_SNAPS).clear();
+    await txDone(tx);
+  }
+
+  /** Raw snapshot rows for a flavor, newest seq first. */
+  private async listSnapshotRows(flavorId: string): Promise<SnapshotRow[]> {
+    const db = await openDatabase();
+    const all = await new Promise<SnapshotRow[]>((resolve, reject) => {
+      const tx = db.transaction(STORE_SNAPS, 'readonly');
+      const req = tx.objectStore(STORE_SNAPS).getAll();
+      req.onsuccess = () => resolve((req.result as SnapshotRow[] | undefined) ?? []);
+      req.onerror = () => reject(req.error);
+    });
+    return all
+      .filter((s) => s.flavorId === flavorId)
+      .sort((a, b) => b.seq - a.seq);
+  }
+
+  private async recordSnapshot(
+    db: IDBDatabase,
+    flavor: Flavor,
+    reason: string | undefined,
+  ): Promise<void> {
+    // Derive the next seq from the snapshots already persisted for
+    // this flavor. A reload-resettable in-memory counter would restart
+    // at 1 and overwrite existing `<flavorId>@1`, `@2`, … rows.
+    const existing = await this.listSnapshotRows(flavor.id);
+    const seq = existing.reduce((max, s) => Math.max(max, s.seq), 0) + 1;
+    const row: SnapshotRow = {
+      key: `${flavor.id}@${seq}`,
+      flavorId: flavor.id,
+      seq,
+      capturedAt: new Date().toISOString(),
+      flavor,
+      reason,
+    };
+    const putTx = db.transaction(STORE_SNAPS, 'readwrite');
+    putTx.objectStore(STORE_SNAPS).put(row);
+    await txDone(putTx);
+    // Enforce cap: keep newest SNAPSHOT_CAP rows per flavor.
+    const all = [row, ...existing];
+    if (all.length > SNAPSHOT_CAP) {
+      const toDrop = all.slice(SNAPSHOT_CAP);
+      const dropTx = db.transaction(STORE_SNAPS, 'readwrite');
+      const store = dropTx.objectStore(STORE_SNAPS);
+      for (const s of toDrop) store.delete(`${flavor.id}@${s.seq}`);
+      await txDone(dropTx);
+    }
+  }
+}
+
+function openDatabase(): Promise<IDBDatabase> {
+  if (dbPromise) return dbPromise;
+  dbPromise = new Promise<IDBDatabase>((resolve, reject) => {
+    const req = indexedDB.open(DB_NAME, DB_VERSION);
+    req.onupgradeneeded = () => {
+      const db = req.result;
+      if (!db.objectStoreNames.contains(STORE_FLAVORS)) {
+        db.createObjectStore(STORE_FLAVORS, { keyPath: 'id' });
+      }
+      if (!db.objectStoreNames.contains(STORE_ACTIVE)) {
+        db.createObjectStore(STORE_ACTIVE, { keyPath: 'key' });
+      }
+      if (!db.objectStoreNames.contains(STORE_SNAPS)) {
+        db.createObjectStore(STORE_SNAPS, { keyPath: 'key' });
+      }
+    };
+    req.onsuccess = () => resolve(req.result);
+    req.onerror = () => reject(req.error);
+    req.onblocked = () => reject(new Error('Flavor IDB open blocked by another tab.'));
+  });
+  return dbPromise;
+}

package/src/services/extensions/idb-log-storage.test.ts

@@ -0,0 +1,110 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
+
+import 'fake-indexeddb/auto';
+
+import assert from 'node:assert/strict';
+import { beforeEach, describe, it } from 'node:test';
+import type { ActionEvent, AuditEvent } from '@ifc-lite/extensions';
+import { IdbLogStorage } from './idb-log-storage.js';
+
+function actionEvent(seq: number, intent: ActionEvent['intent'] = 'model.unload'): ActionEvent {
+  return {
+    seq,
+    ts: new Date(2026, 0, 1, 0, 0, seq).toISOString(),
+    intent,
+    params: {} as ActionEvent['params'],
+    success: true,
+  } as ActionEvent;
+}
+
+function auditEvent(seq: number, id: string = 'com.example.ext'): AuditEvent {
+  return {
+    seq,
+    ts: new Date(2026, 0, 1, 0, 0, seq).toISOString(),
+    kind: 'install',
+    extensionId: id,
+    version: '1.0.0',
+    grantedCapabilities: [],
+  } as AuditEvent;
+}
+
+const FLUSH_WAIT_MS = 400; // debounce is 250 ms; wait a bit longer.
+
+async function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+describe('IdbLogStorage', () => {
+  beforeEach(async () => {
+    const store = new IdbLogStorage();
+    await store.clearActions();
+    await store.clearAudit();
+  });
+
+  it('round-trips action events through debounced writes', async () => {
+    const store = new IdbLogStorage();
+    store.appendAction(actionEvent(1));
+    store.appendAction(actionEvent(2));
+    store.appendAction(actionEvent(3));
+    await sleep(FLUSH_WAIT_MS);
+    const loaded = await store.loadActions();
+    assert.strictEqual(loaded.length, 3);
+    assert.deepStrictEqual(loaded.map((e) => e.seq).sort((a, b) => a - b), [1, 2, 3]);
+  });
+
+  it('round-trips audit events', async () => {
+    const store = new IdbLogStorage();
+    store.appendAudit(auditEvent(1));
+    store.appendAudit(auditEvent(2));
+    await sleep(FLUSH_WAIT_MS);
+    const loaded = await store.loadAudit();
+    assert.strictEqual(loaded.length, 2);
+  });
+
+  it('clearActions wipes the action store but leaves audit alone', async () => {
+    const store = new IdbLogStorage();
+    store.appendAction(actionEvent(1));
+    store.appendAudit(auditEvent(1));
+    await sleep(FLUSH_WAIT_MS);
+    await store.clearActions();
+    assert.strictEqual((await store.loadActions()).length, 0);
+    assert.strictEqual((await store.loadAudit()).length, 1);
+  });
+
+  it('clearAudit wipes the audit store but leaves actions alone', async () => {
+    const store = new IdbLogStorage();
+    store.appendAction(actionEvent(1));
+    store.appendAudit(auditEvent(1));
+    await sleep(FLUSH_WAIT_MS);
+    await store.clearAudit();
+    assert.strictEqual((await store.loadAudit()).length, 0);
+    assert.strictEqual((await store.loadActions()).length, 1);
+  });
+
+  it('debounces a burst into one flush', async () => {
+    const store = new IdbLogStorage();
+    // Append 20 events in a tight loop — all should land after one
+    // debounce window expires.
+    for (let i = 1; i <= 20; i++) {
+      store.appendAction(actionEvent(i));
+    }
+    // Before the debounce fires nothing is in storage yet.
+    assert.strictEqual((await store.loadActions()).length, 0);
+    await sleep(FLUSH_WAIT_MS);
+    assert.strictEqual((await store.loadActions()).length, 20);
+  });
+
+  it('preserves the seq-based key uniqueness', async () => {
+    const store = new IdbLogStorage();
+    // Re-appending the same seq overwrites (keyPath: 'seq').
+    store.appendAction({ ...actionEvent(1), params: { type: 'foo' } } as ActionEvent);
+    await sleep(FLUSH_WAIT_MS);
+    store.appendAction({ ...actionEvent(1), params: { type: 'bar' } } as ActionEvent);
+    await sleep(FLUSH_WAIT_MS);
+    const loaded = await store.loadActions();
+    assert.strictEqual(loaded.length, 1);
+    assert.strictEqual((loaded[0].params as { type?: string }).type, 'bar');
+  });
+});

package/src/services/extensions/idb-log-storage.ts

@@ -0,0 +1,171 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
+
+/**
+ * IndexedDB-backed persistence for the action log and audit log.
+ *
+ * Both logs are append-only ring buffers in memory. This module mirrors
+ * each appended event into IDB so the history survives reloads, and
+ * loads the prior snapshot on app boot via the logs' `hydrate()`
+ * methods.
+ *
+ * Two object stores:
+ *   - `action-events`  keyed by `seq` → ActionEvent
+ *   - `audit-events`   keyed by `seq` → AuditEvent
+ *
+ * Writes are debounced (250 ms) to keep the IDB hit rate down during
+ * fast bursts; the in-memory log is the source of truth between
+ * debounce flushes.
+ */
+
+import type { ActionEvent, AuditEvent } from '@ifc-lite/extensions';
+
+const DB_NAME = 'ifc-lite-extension-logs';
+const DB_VERSION = 1;
+const STORE_ACTION = 'action-events';
+const STORE_AUDIT = 'audit-events';
+const DEBOUNCE_MS = 250;
+
+let dbPromise: Promise<IDBDatabase> | null = null;
+
+export class IdbLogStorage {
+  private actionPending: ActionEvent[] = [];
+  private auditPending: AuditEvent[] = [];
+  private actionTimer: ReturnType<typeof setTimeout> | null = null;
+  private auditTimer: ReturnType<typeof setTimeout> | null = null;
+
+  async loadActions(): Promise<ActionEvent[]> {
+    return loadAll<ActionEvent>(STORE_ACTION);
+  }
+
+  async loadAudit(): Promise<AuditEvent[]> {
+    return loadAll<AuditEvent>(STORE_AUDIT);
+  }
+
+  /** Queue an action event for persistence; flushes after DEBOUNCE_MS. */
+  appendAction(event: ActionEvent): void {
+    this.actionPending.push(event);
+    if (this.actionTimer) clearTimeout(this.actionTimer);
+    this.actionTimer = setTimeout(() => {
+      void this.flushActions();
+    }, DEBOUNCE_MS);
+  }
+
+  /** Queue an audit event for persistence; flushes after DEBOUNCE_MS. */
+  appendAudit(event: AuditEvent): void {
+    this.auditPending.push(event);
+    if (this.auditTimer) clearTimeout(this.auditTimer);
+    this.auditTimer = setTimeout(() => {
+      void this.flushAudit();
+    }, DEBOUNCE_MS);
+  }
+
+  /** Wipe the action store (called when the user clears the log). */
+  async clearActions(): Promise<void> {
+    const db = await openDatabase();
+    await new Promise<void>((resolve, reject) => {
+      const tx = db.transaction(STORE_ACTION, 'readwrite');
+      tx.objectStore(STORE_ACTION).clear();
+      bindTx(tx, resolve, reject);
+    });
+    this.actionPending = [];
+  }
+
+  async clearAudit(): Promise<void> {
+    const db = await openDatabase();
+    await new Promise<void>((resolve, reject) => {
+      const tx = db.transaction(STORE_AUDIT, 'readwrite');
+      tx.objectStore(STORE_AUDIT).clear();
+      bindTx(tx, resolve, reject);
+    });
+    this.auditPending = [];
+  }
+
+  /**
+   * Flush both pending batches immediately and cancel the debounce
+   * timers. Call on host teardown / before reload so events appended
+   * within the last DEBOUNCE_MS window aren't lost and the timers
+   * don't leak.
+   */
+  async flush(): Promise<void> {
+    if (this.actionTimer) { clearTimeout(this.actionTimer); this.actionTimer = null; }
+    if (this.auditTimer) { clearTimeout(this.auditTimer); this.auditTimer = null; }
+    await Promise.all([this.flushActions(), this.flushAudit()]);
+  }
+
+  private async flushActions(): Promise<void> {
+    if (this.actionPending.length === 0) return;
+    const batch = this.actionPending;
+    this.actionPending = [];
+    try {
+      const db = await openDatabase();
+      await new Promise<void>((resolve, reject) => {
+        const tx = db.transaction(STORE_ACTION, 'readwrite');
+        const store = tx.objectStore(STORE_ACTION);
+        for (const event of batch) store.put(event);
+        bindTx(tx, resolve, reject);
+      });
+    } catch (err) {
+      console.warn('[IdbLogStorage] action flush failed:', err);
+    }
+  }
+
+  private async flushAudit(): Promise<void> {
+    if (this.auditPending.length === 0) return;
+    const batch = this.auditPending;
+    this.auditPending = [];
+    try {
+      const db = await openDatabase();
+      await new Promise<void>((resolve, reject) => {
+        const tx = db.transaction(STORE_AUDIT, 'readwrite');
+        const store = tx.objectStore(STORE_AUDIT);
+        for (const event of batch) store.put(event);
+        bindTx(tx, resolve, reject);
+      });
+    } catch (err) {
+      console.warn('[IdbLogStorage] audit flush failed:', err);
+    }
+  }
+}
+
+/**
+ * Settle a readwrite transaction. The `abort` branch matters: an
+ * aborted transaction fires neither `complete` nor `error`, so the
+ * promise would otherwise hang forever.
+ */
+function bindTx(tx: IDBTransaction, resolve: () => void, reject: (e: unknown) => void): void {
+  tx.oncomplete = () => resolve();
+  tx.onerror = () => reject(tx.error ?? new Error('Log IDB transaction failed.'));
+  tx.onabort = () => reject(tx.error ?? new Error('Log IDB transaction aborted.'));
+}
+
+async function loadAll<T>(store: string): Promise<T[]> {
+  const db = await openDatabase();
+  return new Promise((resolve, reject) => {
+    const tx = db.transaction(store, 'readonly');
+    const req = tx.objectStore(store).getAll();
+    req.onsuccess = () => resolve(((req.result as T[] | undefined) ?? []));
+    req.onerror = () => reject(req.error);
+  });
+}
+
+function openDatabase(): Promise<IDBDatabase> {
+  if (dbPromise) return dbPromise;
+  dbPromise = new Promise<IDBDatabase>((resolve, reject) => {
+    const req = indexedDB.open(DB_NAME, DB_VERSION);
+    req.onupgradeneeded = () => {
+      const db = req.result;
+      if (!db.objectStoreNames.contains(STORE_ACTION)) {
+        db.createObjectStore(STORE_ACTION, { keyPath: 'seq' });
+      }
+      if (!db.objectStoreNames.contains(STORE_AUDIT)) {
+        db.createObjectStore(STORE_AUDIT, { keyPath: 'seq' });
+      }
+    };
+    req.onsuccess = () => resolve(req.result);
+    req.onerror = () => reject(req.error);
+    req.onblocked = () => reject(new Error('Log IDB open blocked by another tab.'));
+  });
+  return dbPromise;
+}