@abraca/dabra 2.0.4 → 2.0.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abraca/dabra",
-  "version": "2.0.4",
+  "version": "2.0.7",
   "description": "abracadabra provider",
   "keywords": [
     "abracadabra",

package/src/AbracadabraBaseProvider.ts

@@ -142,6 +142,16 @@ export class AbracadabraBaseProvider extends EventEmitter {
 
   isAuthenticated = false;
 
+  /**
+   * True once this provider has received at least one Authenticated frame
+   * on the current socket lifetime. Used by `permissionDeniedHandler` to
+   * tell apart "the entry doc is wrong / unreachable" (first frame is a
+   * denial → config error, give up) from "a mid-session write was denied"
+   * (server keeps the read subscription alive → don't kill the socket).
+   * Reset on close.
+   */
+  private _hasEverAuthenticated = false;
+
   /** Current WebSocket connection status. */
   get connectionStatus(): WebSocketStatus {
     return this.configuration.websocketProvider.status;
@@ -504,6 +514,10 @@ export class AbracadabraBaseProvider extends EventEmitter {
   onClose() {
     this.isAuthenticated = false;
     this.synced = false;
+    // Reset per-socket-lifetime auth flag so the next connection's
+    // permissionDeniedHandler can correctly identify a fresh-connection
+    // denial as a config error.
+    this._hasEverAuthenticated = false;
 
     // update awareness (all users except local left)
     if (this.awareness) {
@@ -616,15 +630,26 @@ export class AbracadabraBaseProvider extends EventEmitter {
     // closes after every server-side rejection, AbracadabraWS schedules a
     // retry, the new connection sends the same Subscribe → server denies
     // again, ad infinitum (CPU/log/network spam, page looks "broken" to
-    // the user). The dominant cases:
+    // the user). The dominant cases here:
     //   * "document not found" — entry-doc-id pinned to something that
     //     doesn't exist on this server
-    //   * "permission denied" — operator never granted the user access
-    // Both are config issues; retrying won't fix them. We only stop the
-    // socket when this provider OWNS it (`manageSocket`); shared sockets
-    // (e.g. multiplexed child providers) leave the parent's lifecycle
-    // alone and just give up on this doc.
-    if (this.manageSocket) {
+    //   * initial "permission denied" — operator never granted access
+    // Both are config issues; retrying won't fix them.
+    //
+    // BUT — once we've successfully authenticated at least once on this
+    // socket, a permission_denied frame means a *mid-session* operation
+    // was rejected (e.g. a write attempt on a doc the user only has read
+    // on, or a Forbidden surfaced from defense-in-depth). The server
+    // keeps the read subscription alive in that case (see ws.rs handling
+    // of Error::Forbidden), so killing the socket would be a regression:
+    // it tears down every other doc's sync just because one write was
+    // denied. Skip the disconnect here and let the affected operation
+    // surface its own error.
+    //
+    // We only stop the socket when this provider OWNS it (`manageSocket`);
+    // shared sockets (e.g. multiplexed child providers) leave the parent's
+    // lifecycle alone and just give up on this doc.
+    if (this.manageSocket && !this._hasEverAuthenticated) {
       try {
         this.configuration.websocketProvider.disconnect();
       }
@@ -634,6 +659,7 @@ export class AbracadabraBaseProvider extends EventEmitter {
 
   authenticatedHandler(scope: string) {
     this.isAuthenticated = true;
+    this._hasEverAuthenticated = true;
     this.authorizedScope = scope as AuthorizedScope;
 
     this.emit("authenticated", { scope });

package/src/AbracadabraProvider.ts

@@ -123,8 +123,29 @@ export class AbracadabraProvider extends AbracadabraBaseProvider {
 	private childAccessTimes = new Map<string, number>();
 	/** Pinned children that must not be evicted (e.g. actively viewed docs) */
 	private pinnedChildren = new Set<string>();
-	/** Default cap on simultaneously cached child providers; configurable per-instance via `maxChildren`. */
-	private static readonly DEFAULT_MAX_CHILDREN = 20;
+	/**
+	 * Children explicitly marked as transient (e.g. by a background indexer
+	 * that scans the whole tree). They:
+	 *   - never count toward the LRU `maxChildren` budget
+	 *   - never cause eviction of OTHER children when they're added
+	 *   - are eligible for LRU eviction themselves only after they get
+	 *     unmarked or explicitly unloaded
+	 *
+	 * The motivating case: `useSearchIndex` / `useFileIndex` walk every doc
+	 * in the tree calling `loadChild`. With a default cap of 20 and a tree
+	 * of 76+ subdocs, the LRU silently evicted whichever subdoc the UI was
+	 * actually showing — a CLOSE storm and dead awareness for the user.
+	 * Transient loads sidestep that pool entirely.
+	 */
+	private transientChildren = new Set<string>();
+	/**
+	 * Default cap on simultaneously cached child providers (excluding
+	 * transient ones — see `transientChildren`). Configurable per-instance
+	 * via `maxChildren`. Bumped from 20 → 64 because real apps routinely
+	 * have trees with dozens of subdocs being touched and 20 caused silent
+	 * subdoc eviction (with awareness loss) on perfectly normal load.
+	 */
+	private static readonly DEFAULT_MAX_CHILDREN = 64;
 	private readonly maxChildren: number;
 
 	private abracadabraConfig: AbracadabraProviderConfiguration;
@@ -473,10 +494,22 @@ export class AbracadabraProvider extends AbracadabraBaseProvider {
 
 	/**
 	 * Create (or return cached) a child AbracadabraProvider for a given
-	 * child document id.  Each child opens its own WebSocket connection because
-	 * the server is document-scoped (one WebSocket ↔ one document).
+	 * child document id.  Each child shares the parent's WebSocket via
+	 * multiplexing.
+	 *
+	 * `evictable` (default `true`) controls whether the child enters the
+	 * LRU pool. Pass `evictable: false` for transient loads — typically
+	 * batch indexers (search, file extraction) that touch every doc in
+	 * the tree and would otherwise blow out the cache, silently evicting
+	 * subdocs the UI is actively using. Transient children are excluded
+	 * from the LRU budget AND don't trigger eviction of other children.
+	 * Callers MUST pair `loadChild(id, { evictable: false })` with an
+	 * explicit `unloadChild(id)` once they're done.
 	 */
-	loadChild(childId: string): Promise<AbracadabraProvider> {
+	loadChild(
+		childId: string,
+		options: { evictable?: boolean } = {},
+	): Promise<AbracadabraProvider> {
 		if (!isValidDocId(childId)) {
 			return Promise.reject(
 				new Error(
@@ -486,8 +519,15 @@ export class AbracadabraProvider extends AbracadabraBaseProvider {
 			);
 		}
 
+		const evictable = options.evictable !== false;
+
 		if (this.childProviders.has(childId)) {
 			this.childAccessTimes.set(childId, Date.now());
+			// A second load call promotes a child *out* of transient mode —
+			// once a UI surface wants it, it's no longer "just for indexing"
+			// and should be governed by the normal LRU budget. We never go
+			// the other way (UI-loaded → transient) implicitly.
+			if (evictable) this.transientChildren.delete(childId);
 			return Promise.resolve(this.childProviders.get(childId)!);
 		}
 
@@ -497,13 +537,16 @@ export class AbracadabraProvider extends AbracadabraBaseProvider {
 			return this.pendingLoads.get(childId)!;
 		}
 
-		const load = this._doLoadChild(childId);
+		const load = this._doLoadChild(childId, evictable);
 		this.pendingLoads.set(childId, load);
 		load.finally(() => this.pendingLoads.delete(childId));
 		return load;
 	}
 
-	private async _doLoadChild(childId: string): Promise<AbracadabraProvider> {
+	private async _doLoadChild(
+		childId: string,
+		evictable: boolean,
+	): Promise<AbracadabraProvider> {
 		const childDoc = new Y.Doc({ guid: childId });
 
 		// Fire-and-forget: tell the server this child belongs to the parent.
@@ -535,9 +578,13 @@ export class AbracadabraProvider extends AbracadabraBaseProvider {
 
 		this.childProviders.set(childId, childProvider);
 		this.childAccessTimes.set(childId, Date.now());
+		if (!evictable) this.transientChildren.add(childId);
 
-		// Evict least-recently-used children if over capacity
-		this.evictLRU();
+		// Evict least-recently-used children if over capacity. A transient
+		// load doesn't count toward the budget AND shouldn't kick others
+		// out — it's an indexer scanning the tree, not the UI subscribing
+		// to a new doc.
+		if (evictable) this.evictLRU();
 
 		this.emit("subdocLoaded", { childId, provider: childProvider });
 
@@ -551,6 +598,7 @@ export class AbracadabraProvider extends AbracadabraBaseProvider {
 			this.childProviders.delete(childId);
 			this.childAccessTimes.delete(childId);
 			this.pinnedChildren.delete(childId);
+			this.transientChildren.delete(childId);
 		}
 	}
 
@@ -572,20 +620,31 @@ export class AbracadabraProvider extends AbracadabraBaseProvider {
 	}
 
 	/**
-	 * Evict least-recently-used unpinned child providers until the cache is
-	 * at or below MAX_CHILDREN.
+	 * Evict least-recently-used unpinned, non-transient child providers
+	 * until the cache is at or below MAX_CHILDREN. Transient children
+	 * (loaded with `{ evictable: false }`) are excluded from both the
+	 * budget *and* the eviction list — they're invisible to the LRU and
+	 * only go away when their loader explicitly calls `unloadChild`.
 	 */
 	private evictLRU() {
-		if (this.childProviders.size <= this.maxChildren) return;
+		// Count only non-transient children toward the budget. A search
+		// indexer that pinned 100 transient children must NOT cause the
+		// LRU to evict the 1 doc the user's editor is actively viewing.
+		let nonTransientCount = 0;
+		for (const id of this.childProviders.keys()) {
+			if (!this.transientChildren.has(id)) nonTransientCount++;
+		}
+		if (nonTransientCount <= this.maxChildren) return;
 
 		const evictable: Array<{ id: string; accessTime: number }> = [];
 		for (const [id] of this.childProviders) {
 			if (this.pinnedChildren.has(id)) continue;
+			if (this.transientChildren.has(id)) continue;
 			evictable.push({ id, accessTime: this.childAccessTimes.get(id) ?? 0 });
 		}
 		evictable.sort((a, b) => a.accessTime - b.accessTime);
 
-		let toEvict = this.childProviders.size - this.maxChildren;
+		let toEvict = nonTransientCount - this.maxChildren;
 		for (const entry of evictable) {
 			if (toEvict <= 0) break;
 			this.unloadChild(entry.id);