@abraca/dabra 2.0.5 → 2.0.8

package/dist/index.d.ts

@@ -1089,7 +1089,28 @@ declare class AbracadabraProvider extends AbracadabraBaseProvider {
   private childAccessTimes;
   /** Pinned children that must not be evicted (e.g. actively viewed docs) */
   private pinnedChildren;
-  /** Default cap on simultaneously cached child providers; configurable per-instance via `maxChildren`. */
+  /**
+   * 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;
+  /**
+   * 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;
   private readonly maxChildren;
   private abracadabraConfig;
@@ -1166,10 +1187,21 @@ declare class AbracadabraProvider extends AbracadabraBaseProvider {
   hasChild(childId: string): boolean;
   /**
    * 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).
-   */
-  loadChild(childId: string): Promise<AbracadabraProvider>;
+   * 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, options?: {
+    evictable?: boolean;
+  }): Promise<AbracadabraProvider>;
   private _doLoadChild;
   unloadChild(childId: string): void;
   /**
@@ -1182,8 +1214,11 @@ declare class AbracadabraProvider extends AbracadabraBaseProvider {
    */
   unpinChild(childId: string): void;
   /**
-   * 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;
   /** Return all currently-loaded child providers. */
@@ -2280,6 +2315,15 @@ declare class AbracadabraBaseProvider extends EventEmitter {
   isSynced: boolean;
   unsyncedChanges: number;
   isAuthenticated: boolean;
+  /**
+   * 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;
   /** Current WebSocket connection status. */
   get connectionStatus(): WebSocketStatus;
   authorizedScope: AuthorizedScope | undefined;

package/package.json

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

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,32 @@ export class AbracadabraProvider extends AbracadabraBaseProvider {
 			);
 		}
 
+		// Self-load: caller asked for the doc this provider already owns.
+		// Return `this` directly. Without this guard we'd build a sibling
+		// AbracadabraProvider with the same `name` and call attach() on the
+		// shared AbracadabraWS. The wsp's providerMap is keyed by name, so
+		// the sibling silently REPLACES the root in the routing table — its
+		// outgoing messages still reach the wire (send doesn't read the
+		// map), but inbound frames addressed to that doc go to the sibling.
+		// When the borrow ends and the sibling detaches, providerMap is
+		// wiped of that name and the root is left orphaned: the UI still
+		// reports `connected` + `synced`, but no awareness/sync messages
+		// are received. Returning `this` is intentionally not added to
+		// `childProviders` so LRU eviction never destroys the root, and
+		// `unloadChild(self)` becomes a safe no-op (see below).
+		if (childId === this.configuration.name) {
+			return Promise.resolve(this);
+		}
+
+		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 +554,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 +595,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 +615,7 @@ export class AbracadabraProvider extends AbracadabraBaseProvider {
 			this.childProviders.delete(childId);
 			this.childAccessTimes.delete(childId);
 			this.pinnedChildren.delete(childId);
+			this.transientChildren.delete(childId);
 		}
 	}
 
@@ -572,20 +637,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);