@geolonia/geonicdb-sdk 0.12.0 → 0.14.0

package/geonicdb.mjs

@@ -51,6 +51,9 @@ var SDK_POLL_INTERVAL_MS_DEFAULT = 5e3;
 var DPOP_IDB_NAME = "geonicdb-sdk";
 var DPOP_IDB_STORE = "dpop-sessions";
 var DPOP_IDB_VERSION = 1;
+var SDK_CACHE_IDB_NAME = "geonicdb-sdk-cache";
+var SDK_CACHE_IDB_STORE = "responses";
+var SDK_CACHE_IDB_VERSION = 1;
 
 // src/sdk/dpop.ts
 var dpopSupported = typeof crypto !== "undefined" && !!crypto.subtle && !!crypto.subtle.generateKey;
@@ -330,11 +333,97 @@ var SdkCache = class {
   constructor(maxEntries = SDK_CACHE_MAX_ENTRIES_DEFAULT) {
     __publicField(this, "_store", /* @__PURE__ */ new Map());
     __publicField(this, "_maxEntries");
+    /**
+     * Optional persistent backing store (IndexedDB) so cached validators survive
+     * a page reload (#1262). `null` in non-browser runtimes — the cache then
+     * behaves as a pure in-memory LRU.
+     */
+    __publicField(this, "_persistence", null);
+    /**
+     * Auth-scope namespace for persisted entries. The auth layer sets this to a
+     * tenant + authenticated-principal identifier so that entries written by one
+     * principal are never read back by another sharing the same origin/tenant
+     * (different tabs / SDK instances each scope to their own principal).
+     */
+    __publicField(this, "_scope", "");
+    /**
+     * Whether write-through persistence is currently active. Driven by the auth
+     * layer: enabled only for remembered sessions, so persisted entries belong to
+     * exactly one principal and are dropped on every credential change.
+     */
+    __publicField(this, "_persistEnabled", false);
+    /**
+     * Serialises persistence writes so they complete in call order (#1262
+     * review). `set`/`delete`/`clearPersisted` are otherwise independent
+     * fire-and-forget ops; if a late `put()` resolved after a `remove()` /
+     * `clearScope()`, an evicted/deleted/logged-out entry could reappear in
+     * IndexedDB. Chaining them keeps the persisted store consistent with the
+     * in-memory state and with the auth-boundary flush.
+     */
+    __publicField(this, "_persistQueue", Promise.resolve());
     if (!Number.isInteger(maxEntries) || maxEntries <= 0) {
       throw new Error(`SdkCache maxEntries must be a positive integer, got ${String(maxEntries)}`);
     }
     this._maxEntries = maxEntries;
   }
+  /** Wire a persistence backend (called once at construction when available). */
+  attachPersistence(persistence) {
+    this._persistence = persistence;
+  }
+  /** Whether a persistence backend is attached. */
+  hasPersistence() {
+    return this._persistence !== null;
+  }
+  /** Set the auth-scope namespace used for persisted reads/writes. */
+  setScope(scope) {
+    this._scope = scope;
+  }
+  /** Enable or disable write-through persistence (driven by `rememberSession`). */
+  setPersistEnabled(enabled) {
+    this._persistEnabled = enabled && this._persistence !== null;
+  }
+  /** True when set/delete should propagate to the persistent store. */
+  get _persisting() {
+    return this._persistEnabled && this._persistence !== null;
+  }
+  /**
+   * Append a persistence operation to the serialised queue. The backend and
+   * scope are captured at enqueue time so a later scope change cannot retarget
+   * an already-queued op. A failing op is swallowed (persistence is
+   * best-effort) and does not stall the chain. Returns the tail so callers that
+   * need ordering (`clearPersisted`) can await it.
+   */
+  _enqueuePersist(op) {
+    const persistence = this._persistence;
+    if (!persistence) return this._persistQueue;
+    const scope = this._scope;
+    this._persistQueue = this._persistQueue.catch(() => void 0).then(() => op(persistence, scope)).catch(() => void 0);
+    return this._persistQueue;
+  }
+  /**
+   * Load persisted entries for the current scope into memory, oldest first so
+   * the in-memory LRU recency order is preserved. Best-effort and idempotent —
+   * a no-op when no backend is attached. Called after a remembered session is
+   * restored so the very first request after a reload can send `If-None-Match`.
+   */
+  async hydrate() {
+    if (!this._persistence) return;
+    const entries = await this._persistence.loadScope(this._scope, this._maxEntries);
+    for (const { key, entry } of entries) {
+      if (this._store.has(key)) this._store.delete(key);
+      this._store.set(key, entry);
+    }
+    while (this._store.size > this._maxEntries) {
+      const oldest = this._store.keys().next().value;
+      if (oldest === void 0) break;
+      this._store.delete(oldest);
+    }
+  }
+  /** Drop every persisted entry for the current scope (auth change / flush). */
+  async clearPersisted() {
+    if (!this._persistence) return;
+    await this._enqueuePersist((persistence, scope) => persistence.clearScope(scope));
+  }
   /** Build a stable cache key. Method is upper-cased so casing differences do not produce duplicate entries. */
   static keyFor(method, path) {
     return `${method.toUpperCase()}:${path}`;
@@ -353,15 +442,27 @@ var SdkCache = class {
       this._store.delete(key);
     }
     this._store.set(key, entry);
+    const evicted = [];
     while (this._store.size > this._maxEntries) {
       const oldest = this._store.keys().next().value;
       if (oldest === void 0) break;
       this._store.delete(oldest);
+      evicted.push(oldest);
+    }
+    if (this._persisting) {
+      void this._enqueuePersist(async (persistence, scope) => {
+        await persistence.put(scope, key, entry);
+        if (evicted.length > 0) await persistence.remove(scope, evicted);
+      });
     }
   }
   /** Delete a specific entry. Returns whether anything was removed. */
   delete(key) {
-    return this._store.delete(key);
+    const removed = this._store.delete(key);
+    if (removed && this._persisting) {
+      void this._enqueuePersist((persistence, scope) => persistence.remove(scope, [key]));
+    }
+    return removed;
   }
   /**
    * Delete every entry whose key matches a predicate. Returns the array of
@@ -499,6 +600,49 @@ var _AuthManager = class _AuthManager {
   /** Wire an SdkCache instance (called by GeonicDB constructor when caching is enabled). */
   setCache(cache) {
     this._cache = cache;
+    cache?.setScope(this._cacheScope());
+  }
+  /**
+   * #1262: persistence scope for the SDK cache — tenant + authenticated
+   * principal (email when available). Keying on the principal, not just the
+   * tenant, prevents a different subject sharing the same origin/tenant (another
+   * tab, another SDK instance, a later login) from reading entries written by a
+   * previous principal. The principal segment is empty for sessions without a
+   * known email; such sessions never persist (persistence is gated on a
+   * remembered DPoP session that always carries an email), so the empty segment
+   * is not reachable as a write scope in practice.
+   */
+  _cacheScope() {
+    return `${this._tenant}
${this._email ?? ""}`;
+  }
+  /**
+   * #1262: enable write-through persistence for the SDK cache so it survives a
+   * reload. Always re-scopes to the current tenant + principal first.
+   *
+   * `clearFirst` drops any persisted entries left by a previous session of the
+   * same principal — used on a fresh `login()`. It is `false` on
+   * `restoreSession()`, where the persisted entries belong to the very session
+   * being restored and are about to be rehydrated.
+   */
+  async _enablePersistentCache(clearFirst) {
+    if (!this._cache) return;
+    this._cache.setScope(this._cacheScope());
+    if (clearFirst) await this._cache.clearPersisted();
+    this._cache.setPersistEnabled(true);
+  }
+  /**
+   * #1262: disable write-through persistence and drop the persisted cache for
+   * the current principal. Called on credential changes that do not persist a
+   * session (`setCredentials()`, non-remembered `login()`, `logout()`),
+   * mirroring the in-memory invalidation so a stale body can never outlive its
+   * principal. Callers that null out `_email` must invoke this **before** doing
+   * so, otherwise the scope no longer resolves to the principal being dropped.
+   */
+  _disablePersistentCache() {
+    if (!this._cache) return;
+    this._cache.setScope(this._cacheScope());
+    this._cache.setPersistEnabled(false);
+    void this._cache.clearPersisted();
   }
   /** Provide the cache event emitter (forwarded to the GeonicDB EventEmitter). */
   setCacheEventEmitter(emitter) {
@@ -553,6 +697,7 @@ var _AuthManager = class _AuthManager {
     this._email = email;
     this._rememberSession = wantsRemember;
     this._invalidateAuthScopedState();
+    this._cache?.setPersistEnabled(false);
     if (!wantsRemember && this._tenant) {
       void clearDPoPSession(this._tenant);
     }
@@ -562,6 +707,9 @@ var _AuthManager = class _AuthManager {
         const bound = await this._bindDpopSession();
         if (this._rememberSession) {
           await this._persistDpopSession();
+          await this._enablePersistentCache(true);
+        } else {
+          this._disablePersistentCache();
         }
         return bound;
       } catch (err) {
@@ -570,12 +718,18 @@ var _AuthManager = class _AuthManager {
         this._tokenType = "Bearer";
         this._refreshToken = null;
         this._tokenPromise = null;
+        this._invalidateAuthScopedState();
+        this._disablePersistentCache();
         this._rememberSession = false;
         this._email = null;
-        this._invalidateAuthScopedState();
         throw err;
       }
     }
+    this._rememberSession = false;
+    if (this._tenant) {
+      void clearDPoPSession(this._tenant);
+    }
+    this._disablePersistentCache();
     return data;
   }
   /**
@@ -660,6 +814,12 @@ var _AuthManager = class _AuthManager {
     this._refreshToken = opts.refreshToken || null;
     this._tokenPromise = null;
     this._invalidateAuthScopedState();
+    this._disablePersistentCache();
+    this._rememberSession = false;
+    this._email = null;
+    if (this._tenant) {
+      void clearDPoPSession(this._tenant);
+    }
   }
   /** Clear all credentials. */
   logout() {
@@ -667,6 +827,7 @@ var _AuthManager = class _AuthManager {
     this._tokenExpiry = 0;
     this._refreshToken = null;
     this._tokenPromise = null;
+    this._disablePersistentCache();
     this._email = null;
     if (this._tenant) {
       void clearDPoPSession(this._tenant);
@@ -712,6 +873,8 @@ var _AuthManager = class _AuthManager {
     this._email = persisted.email ?? null;
     this._tokenPromise = null;
     this._invalidateAuthScopedState();
+    await this._enablePersistentCache(false);
+    await this._cache?.hydrate();
     return true;
   }
   /**
@@ -1334,6 +1497,140 @@ var WebSocketManager = class {
   }
 };
 
+// src/sdk/cache-persistence.ts
+var cachePersistenceSupported = typeof globalThis.indexedDB !== "undefined" && typeof structuredClone !== "undefined";
+var SCOPE_SEP = "\0";
+var SCOPE_RANGE_END = "\uFFFF";
+function openCacheDB() {
+  return new Promise((resolve, reject) => {
+    const req = globalThis.indexedDB.open(
+      SDK_CACHE_IDB_NAME,
+      SDK_CACHE_IDB_VERSION
+    );
+    req.onupgradeneeded = () => {
+      const db = req.result;
+      if (!db.objectStoreNames.contains(SDK_CACHE_IDB_STORE)) {
+        db.createObjectStore(SDK_CACHE_IDB_STORE, { keyPath: "id" });
+      }
+    };
+    req.onsuccess = () => {
+      resolve(req.result);
+    };
+    req.onerror = () => {
+      reject(req.error ?? new Error("IndexedDB open failed"));
+    };
+    req.onblocked = () => {
+      reject(req.error ?? new Error("IndexedDB open blocked"));
+    };
+  });
+}
+function recordId(scope, key) {
+  return scope + SCOPE_SEP + key;
+}
+var IdbCachePersistence = class {
+  async loadScope(scope, limit) {
+    let db = null;
+    try {
+      db = await openCacheDB();
+      const records = await new Promise((resolve, reject) => {
+        const tx = db.transaction(SDK_CACHE_IDB_STORE, "readonly");
+        const range = globalThis.IDBKeyRange.bound(
+          scope + SCOPE_SEP,
+          scope + SCOPE_SEP + SCOPE_RANGE_END
+        );
+        const req = tx.objectStore(SDK_CACHE_IDB_STORE).getAll(range);
+        req.onsuccess = () => {
+          resolve(req.result ?? []);
+        };
+        req.onerror = () => {
+          reject(req.error ?? new Error("IndexedDB getAll failed"));
+        };
+      });
+      return records.filter((r) => r && r.scope === scope && typeof r.key === "string" && r.entry).sort((a, b) => (a.entry.cachedAt ?? 0) - (b.entry.cachedAt ?? 0)).slice(-limit).map((r) => ({ key: r.key, entry: r.entry }));
+    } catch {
+      return [];
+    } finally {
+      db?.close();
+    }
+  }
+  async put(scope, key, entry) {
+    let db = null;
+    try {
+      db = await openCacheDB();
+      await new Promise((resolve, reject) => {
+        const tx = db.transaction(SDK_CACHE_IDB_STORE, "readwrite");
+        const record = { id: recordId(scope, key), scope, key, entry };
+        tx.objectStore(SDK_CACHE_IDB_STORE).put(record);
+        tx.oncomplete = () => {
+          resolve();
+        };
+        tx.onerror = () => {
+          reject(tx.error ?? new Error("IndexedDB put failed"));
+        };
+        tx.onabort = () => {
+          reject(tx.error ?? new Error("IndexedDB transaction aborted"));
+        };
+      });
+    } catch {
+    } finally {
+      db?.close();
+    }
+  }
+  async remove(scope, keys) {
+    if (keys.length === 0) return;
+    let db = null;
+    try {
+      db = await openCacheDB();
+      await new Promise((resolve, reject) => {
+        const tx = db.transaction(SDK_CACHE_IDB_STORE, "readwrite");
+        const store = tx.objectStore(SDK_CACHE_IDB_STORE);
+        for (const key of keys) store.delete(recordId(scope, key));
+        tx.oncomplete = () => {
+          resolve();
+        };
+        tx.onerror = () => {
+          reject(tx.error ?? new Error("IndexedDB delete failed"));
+        };
+        tx.onabort = () => {
+          reject(tx.error ?? new Error("IndexedDB transaction aborted"));
+        };
+      });
+    } catch {
+    } finally {
+      db?.close();
+    }
+  }
+  async clearScope(scope) {
+    let db = null;
+    try {
+      db = await openCacheDB();
+      await new Promise((resolve, reject) => {
+        const tx = db.transaction(SDK_CACHE_IDB_STORE, "readwrite");
+        const range = globalThis.IDBKeyRange.bound(
+          scope + SCOPE_SEP,
+          scope + SCOPE_SEP + SCOPE_RANGE_END
+        );
+        tx.objectStore(SDK_CACHE_IDB_STORE).delete(range);
+        tx.oncomplete = () => {
+          resolve();
+        };
+        tx.onerror = () => {
+          reject(tx.error ?? new Error("IndexedDB clear failed"));
+        };
+        tx.onabort = () => {
+          reject(tx.error ?? new Error("IndexedDB transaction aborted"));
+        };
+      });
+    } catch {
+    } finally {
+      db?.close();
+    }
+  }
+};
+function createCachePersistence() {
+  return cachePersistenceSupported ? new IdbCachePersistence() : null;
+}
+
 // src/sdk/index.ts
 var GeonicDB = class extends EventEmitter {
   constructor(options) {
@@ -1363,6 +1660,8 @@ var GeonicDB = class extends EventEmitter {
     };
     if (opts.cache !== false) {
       const cache = new SdkCache(opts.cacheMaxEntries ?? SDK_CACHE_MAX_ENTRIES_DEFAULT);
+      const persistence = createCachePersistence();
+      if (persistence) cache.attachPersistence(persistence);
       this._auth.setCache(cache);
       this._auth.setCacheEventEmitter((name, payload) => this.emit(name, payload));
     }
@@ -1391,6 +1690,7 @@ var GeonicDB = class extends EventEmitter {
     for (const key of removed) {
       this._auth.emitCacheEvent("cacheInvalidated", { key, path: key.split(":").slice(1).join(":") });
     }
+    void cache.clearPersisted();
   }
   // --- Authentication ---
   /**