@abraca/dabra 2.19.0 → 2.21.0

package/dist/index.d.ts

@@ -158,9 +158,12 @@ declare class OfflineStore {
   private db;
   /**
    * @param docId       The document UUID.
-   * @param serverOrigin  Hostname of the server (e.g. "abra.cou.sh").
-   *                    When provided the IndexedDB database is namespaced
-   *                    per-server, preventing cross-server data contamination.
+   * @param serverOrigin  Host of the server, including a non-default port
+   *                    (e.g. "abra.cou.sh", "localhost:3001"). When provided
+   *                    the IndexedDB database is namespaced per-server,
+   *                    preventing cross-server data contamination — the port
+   *                    matters because two same-host servers sharing the
+   *                    default root_doc_id would otherwise collide.
    */
   constructor(docId: string, serverOrigin?: string);
   private dbPromise;
@@ -1257,6 +1260,7 @@ interface AbracadabraProviderConfiguration extends Omit<AbracadabraBaseProviderC
  */
 declare class AbracadabraProvider extends AbracadabraBaseProvider {
   effectiveRole: EffectiveRole;
+  private _writeDropWarned;
   private _client;
   private offlineStore;
   private childProviders;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abraca/dabra",
-  "version": "2.19.0",
+  "version": "2.21.0",
   "description": "abracadabra provider",
   "keywords": [
     "abracadabra",
@@ -41,7 +41,7 @@
     "yjs": "^13.6.8"
   },
   "devDependencies": {
-    "@abraca/schema": "2.19.0"
+    "@abraca/schema": "2.21.0"
   },
   "scripts": {
     "test": "node --no-warnings --conditions=source --experimental-transform-types --test 'tests/*.test.ts'"

package/src/AbracadabraBaseProvider.ts

@@ -717,9 +717,18 @@ export class AbracadabraBaseProvider extends EventEmitter {
 
     this.configuration.websocketProvider.on("rateLimited", this.forwardRateLimited);
 
-    this.configuration.websocketProvider.attach(this);
-
+    // Mark attached BEFORE registering with the socket: when the shared
+    // socket is already connected (the loadChild case), wsp.attach()
+    // synchronously invokes onOpen() → sendToken(), and send() drops frames
+    // while _isAttached is false. With a crypto identity OBJECT sendToken()
+    // hits no await before send(), so the AUTH frame was silently swallowed
+    // and the doc never authenticated on the connection — the server then
+    // (correctly) ignored every subsequent frame for it: child providers
+    // never synced and their writes were dropped. (JWT auth only survived
+    // by accident: `await getToken()` defers send() past attach().)
     this._isAttached = true;
+
+    this.configuration.websocketProvider.attach(this);
   }
 
   permissionDeniedHandler(reason: string) {

package/src/AbracadabraProvider.ts

@@ -113,6 +113,10 @@ function isValidDocId(id: string): boolean {
 export class AbracadabraProvider extends AbracadabraBaseProvider {
 	public effectiveRole: EffectiveRole = null;
 
+	// Throttle the "write-drop" warning/event to once per (role) transition so a
+	// read-only editor session doesn't flood the console on every keystroke.
+	private _writeDropWarned = false;
+
 	private _client: AbracadabraClient | null;
 	private offlineStore: OfflineStore | null;
 	private childProviders = new Map<string, AbracadabraProvider>();
@@ -240,7 +244,13 @@ export class AbracadabraProvider extends AbracadabraBaseProvider {
 				config.url ??
 				(config.websocketProvider as AbracadabraWS | undefined)?.url ??
 				client?.wsUrl;
-			if (url) return new URL(url).hostname;
+			// `host` (NOT `hostname`): the port is part of a server's identity.
+			// Two servers on the same host but different ports would otherwise
+			// share one IDB namespace — and since default-config servers also
+			// share the same root_doc_id, one server's cached doc state silently
+			// hydrated into the other's Y.Doc (cross-server contamination that
+			// can then sync back upstream).
+			if (url) return new URL(url).host;
 		} catch {
 			// Malformed URL — fall back to no scoping
 		}
@@ -281,6 +291,10 @@ export class AbracadabraProvider extends AbracadabraBaseProvider {
 	// ── Auth / permission snapshot ────────────────────────────────────────────
 
 	override authenticatedHandler(scope: string) {
+		// NB: super.authenticatedHandler emits "authenticated" BEFORE we set
+		// effectiveRole below, so listeners of "authenticated" must not read the
+		// role from this provider — use the "roleChanged" event emitted at the end
+		// of this method instead, which fires once effectiveRole reflects `scope`.
 		super.authenticatedHandler(scope);
 
 		const roleMap: Record<string, import("./types.ts").EffectiveRole> = {
@@ -293,9 +307,28 @@ export class AbracadabraProvider extends AbracadabraBaseProvider {
 			"read-write": "editor",
 			readonly: "viewer",
 		};
+		const couldWrite = this.canWrite;
 		this.effectiveRole = roleMap[scope] ?? "observer";
 
 		this.offlineStore?.savePermissionSnapshot(this.effectiveRole);
+
+		// Regaining write access re-arms the one-shot write-drop warning so a later
+		// downgrade to a read-only role surfaces again.
+		if (this.canWrite) this._writeDropWarned = false;
+
+		// Reactive role signal for consumers (e.g. the editor edit-gate). Fired
+		// AFTER effectiveRole is set so `canWrite` reflects the new role.
+		this.emit("roleChanged", { role: this.effectiveRole, canWrite: this.canWrite });
+
+		// Self-heal: if the server's authentication frame arrived AFTER the initial
+		// sync (so the "synced" flush ran while the role was still null/stale and
+		// skipped, see flushPendingUpdates' canWrite guard), and we now have write
+		// access, push any updates that were queued to IndexedDB while we couldn't
+		// send. Without this, edits made before auth completed stay stuck in IDB
+		// (visible locally, never on the server) until the next reconnect.
+		if (!couldWrite && this.canWrite && this.isSynced) {
+			this.flushPendingUpdates().catch(() => null);
+		}
 	}
 
 	/**
@@ -363,6 +396,10 @@ export class AbracadabraProvider extends AbracadabraBaseProvider {
 		const role = await this.offlineStore.getPermissionSnapshot();
 		if (role && !this.effectiveRole) {
 			this.effectiveRole = role as EffectiveRole;
+			// Surface the cached role reactively so the offline edit-gate can open
+			// before any server round-trip. The server's authenticatedHandler will
+			// later override this with ground truth (and re-emit).
+			this.emit("roleChanged", { role: this.effectiveRole, canWrite: this.canWrite });
 		}
 	}
 
@@ -696,7 +733,32 @@ export class AbracadabraProvider extends AbracadabraBaseProvider {
 		this.offlineStore?.persistUpdate(update).catch(() => null);
 
 		// Don't send writes over the wire if we lack write permission.
-		if (!this.canWrite) return;
+		if (!this.canWrite) {
+			// Make the otherwise-silent write-drop observable. A local edit was just
+			// persisted to IndexedDB but will NOT be sent to the server because this
+			// provider's effective role can't write. If the editor UI let the user
+			// type here, the UI's write-gate diverged from this provider's — the edit
+			// lives only in local IDB (looks fine locally, empty on the server). We
+			// emit a "writeDropped" event so consumers can surface a read-only /
+			// "unsynced changes" banner, and warn once per role-transition so a
+			// read-only session doesn't flood the console on every keystroke.
+			if (!this._writeDropWarned) {
+				this._writeDropWarned = true;
+				try {
+					console.warn(
+						`[abra:write-drop] dropping wire-send for doc "${this.configuration?.name}" ` +
+							`— effectiveRole=${this.effectiveRole ?? "null"} (canWrite=false). ` +
+							`Edits are persisted to IndexedDB only; the server will NOT receive them ` +
+							`until this doc regains write access.`,
+					);
+				} catch { /* noop */ }
+			}
+			this.emit("writeDropped", {
+				name: this.configuration?.name,
+				role: this.effectiveRole ?? null,
+			});
+			return;
+		}
 
 		super.documentUpdateHandler(update, origin);
 	}

package/src/BackgroundSyncManager.ts

@@ -165,10 +165,12 @@ export class BackgroundSyncManager extends EventEmitter {
 			maxRetries: opts?.maxRetries ?? 2,
 		};
 
-		// Derive server origin from client URL for IDB namespacing
+		// Derive server origin from client URL for IDB namespacing.
+		// `host` (not `hostname`): port-scoped so same-host servers on
+		// different ports don't share a namespace.
 		let serverOrigin = "default";
 		try {
-			serverOrigin = new URL((client as any).baseUrl ?? "").hostname;
+			serverOrigin = new URL((client as any).baseUrl ?? "").host;
 		} catch {}
 
 		this.persistence = new BackgroundSyncPersistence(serverOrigin);
@@ -377,10 +379,10 @@ export class BackgroundSyncManager extends EventEmitter {
 			docIds.add(docId);
 		}
 
-		// Derive server origin the same way the provider does
+		// Derive server origin the same way the provider does (`host`, port-scoped)
 		let serverOrigin: string | undefined;
 		try {
-			serverOrigin = new URL((this.client as any).baseUrl ?? "").hostname;
+			serverOrigin = new URL((this.client as any).baseUrl ?? "").host;
 		} catch {}
 
 		// Clear each document's offline store contents

package/src/OfflineStore.ts

@@ -69,9 +69,12 @@ export class OfflineStore {
 
 	/**
 	 * @param docId       The document UUID.
-	 * @param serverOrigin  Hostname of the server (e.g. "abra.cou.sh").
-	 *                    When provided the IndexedDB database is namespaced
-	 *                    per-server, preventing cross-server data contamination.
+	 * @param serverOrigin  Host of the server, including a non-default port
+	 *                    (e.g. "abra.cou.sh", "localhost:3001"). When provided
+	 *                    the IndexedDB database is namespaced per-server,
+	 *                    preventing cross-server data contamination — the port
+	 *                    matters because two same-host servers sharing the
+	 *                    default root_doc_id would otherwise collide.
 	 */
 	constructor(docId: string, serverOrigin?: string) {
 		this.storeKey = serverOrigin ? `${serverOrigin}/${docId}` : docId;