@abraca/dabra 0.6.0 → 0.7.0

package/src/FileBlobStore.ts

@@ -0,0 +1,300 @@
+/**
+ * IndexedDB-backed file blob cache with an offline-tolerant upload queue.
+ *
+ * Responsibilities:
+ *  - Cache downloaded file blobs locally so they can be served offline via
+ *    object URLs (URL.createObjectURL).
+ *  - Queue file uploads when the network is unavailable. The queue persists
+ *    across page reloads (IndexedDB-backed).
+ *  - Auto-flush the upload queue when the browser reports it is back online,
+ *    and expose flushQueue() for manual flushing.
+ *
+ * Events:
+ *  - "upload:queued"  — entry added to queue
+ *  - "upload:started" — upload attempt started
+ *  - "upload:done"    — upload succeeded
+ *  - "upload:error"   — upload attempt failed
+ *
+ * Falls back to a silent no-op when IndexedDB is unavailable (SSR / Node.js).
+ */
+
+import type { UploadQueueEntry } from "./types.ts";
+import type { AbracadabraClient } from "./AbracadabraClient.ts";
+import EventEmitter from "./EventEmitter.ts";
+
+const DB_VERSION = 1;
+
+function idbAvailable(): boolean {
+	return typeof globalThis !== "undefined" && "indexedDB" in globalThis;
+}
+
+function openDb(origin: string): Promise<IDBDatabase> {
+	return new Promise((resolve, reject) => {
+		const req = globalThis.indexedDB.open(`abracadabra:files:${origin}`, DB_VERSION);
+
+		req.onupgradeneeded = (event) => {
+			const db = (event.target as IDBOpenDBRequest).result;
+			if (!db.objectStoreNames.contains("blobs")) {
+				db.createObjectStore("blobs");
+			}
+			if (!db.objectStoreNames.contains("upload_queue")) {
+				db.createObjectStore("upload_queue", { keyPath: "id" });
+			}
+		};
+
+		req.onsuccess = () => resolve(req.result);
+		req.onerror = () => reject(req.error);
+	});
+}
+
+function txPromise<T>(store: IDBObjectStore, request: IDBRequest<T>): Promise<T> {
+	return new Promise((resolve, reject) => {
+		request.onsuccess = () => resolve(request.result);
+		request.onerror = () => reject(request.error);
+	});
+}
+
+interface BlobCacheEntry {
+	blob: Blob;
+	mime_type: string;
+	filename: string;
+	cachedAt: number;
+}
+
+export class FileBlobStore extends EventEmitter {
+	private readonly origin: string;
+	private readonly client: AbracadabraClient;
+	private dbPromise: Promise<IDBDatabase | null> | null = null;
+	private db: IDBDatabase | null = null;
+
+	/** Tracks active object URLs so we can revoke them on destroy. */
+	private readonly objectUrls = new Map<string, string>();
+
+	/** Prevents concurrent flush runs. */
+	private _flushing = false;
+
+	private readonly _onlineHandler: () => void;
+
+	constructor(serverOrigin: string, client: AbracadabraClient) {
+		super();
+		this.origin = serverOrigin;
+		this.client = client;
+
+		this._onlineHandler = () => { this.flushQueue().catch(() => null); };
+		if (typeof window !== "undefined") {
+			window.addEventListener("online", this._onlineHandler);
+		}
+	}
+
+	private getDb(): Promise<IDBDatabase | null> {
+		if (!idbAvailable()) return Promise.resolve(null);
+		if (!this.dbPromise) {
+			this.dbPromise = openDb(this.origin)
+				.catch(() => null)
+				.then((db) => {
+					this.db = db;
+					return db;
+				});
+		}
+		return this.dbPromise;
+	}
+
+	private blobKey(docId: string, uploadId: string): string {
+		return `${docId}/${uploadId}`;
+	}
+
+	// ── Blob cache ────────────────────────────────────────────────────────────
+
+	/**
+	 * Return a local object URL for a file.
+	 * On first call the blob is downloaded from the server and cached in IDB.
+	 * Returns null when offline and the blob is not yet cached, or when
+	 * URL.createObjectURL is unavailable (e.g. Node.js / SSR).
+	 */
+	async getBlobUrl(docId: string, uploadId: string): Promise<string | null> {
+		// Object URLs are only meaningful in browser environments.
+		if (typeof window === "undefined") return null;
+
+		const key = this.blobKey(docId, uploadId);
+
+		// Reuse existing in-memory object URL if available
+		const existing = this.objectUrls.get(key);
+		if (existing) return existing;
+
+		const db = await this.getDb();
+		if (db) {
+			const tx = db.transaction("blobs", "readonly");
+			const entry = await txPromise<BlobCacheEntry | undefined>(
+				tx.objectStore("blobs"),
+				tx.objectStore("blobs").get(key),
+			);
+			if (entry) {
+				const url = URL.createObjectURL(entry.blob);
+				this.objectUrls.set(key, url);
+				return url;
+			}
+		}
+
+		// Not cached — try downloading
+		let blob: Blob;
+		try {
+			blob = await this.client.getUpload(docId, uploadId);
+		} catch {
+			return null;
+		}
+
+		// Cache the blob
+		if (db) {
+			const entry: BlobCacheEntry = {
+				blob,
+				mime_type: blob.type,
+				filename: uploadId,
+				cachedAt: Date.now(),
+			};
+			const tx = db.transaction("blobs", "readwrite");
+			tx.objectStore("blobs").put(entry, key);
+		}
+
+		const url = URL.createObjectURL(blob);
+		this.objectUrls.set(key, url);
+		return url;
+	}
+
+	/** Revoke the object URL and remove the blob from cache. */
+	async evictBlob(docId: string, uploadId: string): Promise<void> {
+		const key = this.blobKey(docId, uploadId);
+
+		const url = this.objectUrls.get(key);
+		if (url) {
+			URL.revokeObjectURL(url);
+			this.objectUrls.delete(key);
+		}
+
+		const db = await this.getDb();
+		if (!db) return;
+		const tx = db.transaction("blobs", "readwrite");
+		await txPromise(tx.objectStore("blobs"), tx.objectStore("blobs").delete(key));
+	}
+
+	// ── Upload queue ──────────────────────────────────────────────────────────
+
+	/**
+	 * Queue a file for upload. Works offline — the entry is persisted to IDB
+	 * and flushed the next time the queue is flushed.
+	 * Returns the generated queue entry id.
+	 */
+	async queueUpload(
+		docId: string,
+		file: File | Blob,
+		filename?: string,
+	): Promise<string> {
+		const id = crypto.randomUUID();
+		const resolvedFilename =
+			file instanceof File ? file.name : (filename ?? "file");
+
+		const entry: UploadQueueEntry = {
+			id,
+			docId,
+			file,
+			filename: resolvedFilename,
+			status: "pending",
+			createdAt: Date.now(),
+		};
+
+		const db = await this.getDb();
+		if (db) {
+			const tx = db.transaction("upload_queue", "readwrite");
+			await txPromise(
+				tx.objectStore("upload_queue"),
+				tx.objectStore("upload_queue").put(entry),
+			);
+		}
+
+		this.emit("upload:queued", entry);
+		return id;
+	}
+
+	/** Return all upload queue entries. */
+	async getQueue(): Promise<UploadQueueEntry[]> {
+		const db = await this.getDb();
+		if (!db) return [];
+		return new Promise((resolve, reject) => {
+			const tx = db.transaction("upload_queue", "readonly");
+			const req = tx.objectStore("upload_queue").getAll();
+			req.onsuccess = () => resolve(req.result as UploadQueueEntry[]);
+			req.onerror = () => reject(req.error);
+		});
+	}
+
+	/**
+	 * Upload all pending queue entries via AbracadabraClient.
+	 * Safe to call repeatedly — a concurrent call is a no-op.
+	 * Entries that fail are marked with status "error" and left in the queue.
+	 */
+	async flushQueue(): Promise<void> {
+		if (this._flushing) return;
+		this._flushing = true;
+
+		try {
+			const all = await this.getQueue();
+			const pending = all.filter((e) => e.status === "pending");
+
+			for (const entry of pending) {
+				await this._updateQueueEntry(entry.id, { status: "uploading" });
+				this.emit("upload:started", { ...entry, status: "uploading" });
+
+				try {
+					await this.client.upload(entry.docId, entry.file, entry.filename);
+					await this._updateQueueEntry(entry.id, { status: "done" });
+					this.emit("upload:done", { ...entry, status: "done" });
+				} catch (err) {
+					const message = err instanceof Error ? err.message : String(err);
+					await this._updateQueueEntry(entry.id, { status: "error", error: message });
+					this.emit("upload:error", { ...entry, status: "error", error: message });
+				}
+			}
+		} finally {
+			this._flushing = false;
+		}
+	}
+
+	private async _updateQueueEntry(
+		id: string,
+		patch: Partial<UploadQueueEntry>,
+	): Promise<void> {
+		const db = await this.getDb();
+		if (!db) return;
+
+		return new Promise<void>((resolve, reject) => {
+			const tx = db.transaction("upload_queue", "readwrite");
+			const store = tx.objectStore("upload_queue");
+			const req = store.get(id);
+			req.onsuccess = () => {
+				if (!req.result) { resolve(); return; }
+				const updated = { ...req.result, ...patch };
+				store.put(updated);
+				tx.oncomplete = () => resolve();
+				tx.onerror = () => reject(tx.error);
+			};
+			req.onerror = () => reject(req.error);
+		});
+	}
+
+	// ── Lifecycle ─────────────────────────────────────────────────────────────
+
+	destroy(): void {
+		if (typeof window !== "undefined") {
+			window.removeEventListener("online", this._onlineHandler);
+		}
+
+		// Revoke all tracked object URLs
+		for (const url of this.objectUrls.values()) {
+			URL.revokeObjectURL(url);
+		}
+		this.objectUrls.clear();
+
+		this.db?.close();
+		this.db = null;
+		this.removeAllListeners();
+	}
+}

package/src/MessageReceiver.ts

@@ -1,9 +1,9 @@
-import { readAuthMessage } from "@abraca/dabra-common";
+import { readAuthMessage } from "./auth.ts";
 import { readVarInt, readVarString } from "lib0/decoding";
 import type { CloseEvent } from "ws";
 import * as awarenessProtocol from "y-protocols/awareness";
 import { messageYjsSyncStep2, readSyncMessage } from "y-protocols/sync";
-import type { HocuspocusProvider } from "./HocuspocusProvider.ts";
+import type { AbracadabraBaseProvider } from "./AbracadabraBaseProvider.ts";
 import type { IncomingMessage } from "./IncomingMessage.ts";
 import { OutgoingMessage } from "./OutgoingMessage.ts";
 import { MessageType } from "./types.ts";
@@ -15,7 +15,7 @@ export class MessageReceiver {
     this.message = message;
   }
 
-  public apply(provider: HocuspocusProvider, emitSynced: boolean) {
+  public apply(provider: AbracadabraBaseProvider, emitSynced: boolean) {
     const { message } = this;
     const type = message.readVarUint();
 
@@ -72,7 +72,7 @@ export class MessageReceiver {
     }
   }
 
-  private applySyncMessage(provider: HocuspocusProvider, emitSynced: boolean) {
+  private applySyncMessage(provider: AbracadabraBaseProvider, emitSynced: boolean) {
     const { message } = this;
 
     message.writeVarUint(MessageType.Sync);
@@ -91,13 +91,13 @@ export class MessageReceiver {
     }
   }
 
-  applySyncStatusMessage(provider: HocuspocusProvider, applied: boolean) {
+  applySyncStatusMessage(provider: AbracadabraBaseProvider, applied: boolean) {
     if (applied) {
       provider.decrementUnsyncedChanges();
     }
   }
 
-  private applyAwarenessMessage(provider: HocuspocusProvider) {
+  private applyAwarenessMessage(provider: AbracadabraBaseProvider) {
     if (!provider.awareness) return;
 
     const { message } = this;
@@ -109,7 +109,7 @@ export class MessageReceiver {
     );
   }
 
-  private applyAuthMessage(provider: HocuspocusProvider) {
+  private applyAuthMessage(provider: AbracadabraBaseProvider) {
     const { message } = this;
 
     readAuthMessage(
@@ -120,7 +120,7 @@ export class MessageReceiver {
     );
   }
 
-  private applyQueryAwarenessMessage(provider: HocuspocusProvider) {
+  private applyQueryAwarenessMessage(provider: AbracadabraBaseProvider) {
     if (!provider.awareness) return;
 
     const { message } = this;

package/src/OutgoingMessages/AuthenticationMessage.ts

@@ -1,5 +1,5 @@
 import { writeVarString, writeVarUint } from "lib0/encoding";
-import { writeAuthentication } from "@abraca/dabra-common";
+import { writeAuthentication } from "../auth.ts";
 import type { OutgoingMessageArguments } from "../types.ts";
 import { MessageType } from "../types.ts";
 import { OutgoingMessage } from "../OutgoingMessage.ts";

package/src/SearchIndex.ts

@@ -0,0 +1,247 @@
+/**
+ * IndexedDB-backed trigram full-text search index.
+ *
+ * Generic: caller passes (docId, texts[]) — works for Y.Doc text content,
+ * file names, document titles, or any other text. No Y.js coupling.
+ *
+ * Algorithm: trigram inverted index.
+ *   - Each document is decomposed into overlapping 3-character windows.
+ *   - The "postings" store maps trigram → [docId, ...].
+ *   - The "doc_trigrams" store maps docId → [trigram, ...] for efficient removal.
+ *   - search() scores by number of query trigrams that match.
+ *
+ * IDB transactions that touch multiple stores use the callback-only pattern
+ * (not async/await inside a transaction) to avoid the transaction auto-commit
+ * issue across microtask boundaries.
+ */
+
+import type { SearchResult } from "./types.ts";
+
+const DB_VERSION = 1;
+
+function idbAvailable(): boolean {
+	return typeof globalThis !== "undefined" && "indexedDB" in globalThis;
+}
+
+function openDb(origin: string): Promise<IDBDatabase> {
+	return new Promise((resolve, reject) => {
+		const req = globalThis.indexedDB.open(`abracadabra:search:${origin}`, DB_VERSION);
+
+		req.onupgradeneeded = (event) => {
+			const db = (event.target as IDBOpenDBRequest).result;
+			if (!db.objectStoreNames.contains("postings")) {
+				db.createObjectStore("postings");
+			}
+			if (!db.objectStoreNames.contains("doc_trigrams")) {
+				db.createObjectStore("doc_trigrams");
+			}
+		};
+
+		req.onsuccess = () => resolve(req.result);
+		req.onerror = () => reject(req.error);
+	});
+}
+
+/** Extract the set of trigrams for a piece of text. */
+function extractTrigrams(text: string): Set<string> {
+	const trigrams = new Set<string>();
+	const padded = ` ${text.toLowerCase()} `;
+	for (let i = 0; i <= padded.length - 3; i++) {
+		trigrams.add(padded.slice(i, i + 3));
+	}
+	return trigrams;
+}
+
+/** Merge trigrams from multiple texts into a single set. */
+function extractAllTrigrams(texts: string[]): Set<string> {
+	const result = new Set<string>();
+	for (const t of texts) {
+		for (const trigram of extractTrigrams(t)) {
+			result.add(trigram);
+		}
+	}
+	return result;
+}
+
+export class SearchIndex {
+	private readonly origin: string;
+	private dbPromise: Promise<IDBDatabase | null> | null = null;
+	private db: IDBDatabase | null = null;
+
+	constructor(serverOrigin: string) {
+		this.origin = serverOrigin;
+	}
+
+	private getDb(): Promise<IDBDatabase | null> {
+		if (!idbAvailable()) return Promise.resolve(null);
+		if (!this.dbPromise) {
+			this.dbPromise = openDb(this.origin)
+				.catch(() => null)
+				.then((db) => {
+					this.db = db;
+					return db;
+				});
+		}
+		return this.dbPromise;
+	}
+
+	/**
+	 * Replace the index for docId with the given texts.
+	 * Old trigram associations are removed before new ones are added.
+	 */
+	async index(docId: string, texts: string[]): Promise<void> {
+		const db = await this.getDb();
+		if (!db) return;
+
+		const newTrigrams = extractAllTrigrams(texts);
+
+		return new Promise<void>((resolve, reject) => {
+			const tx = db.transaction(["postings", "doc_trigrams"], "readwrite");
+			tx.oncomplete = () => resolve();
+			tx.onerror = () => reject(tx.error);
+
+			const postings = tx.objectStore("postings");
+			const docTrigramsStore = tx.objectStore("doc_trigrams");
+
+			// Step 1: read old trigrams for this doc
+			const oldReq = docTrigramsStore.get(docId);
+			oldReq.onsuccess = () => {
+				const oldTrigrams: string[] = oldReq.result ?? [];
+				let pending = oldTrigrams.length + newTrigrams.size + 1; // +1 for doc_trigrams write
+
+				function done() {
+					pending--;
+					// tx.oncomplete fires naturally once all requests settle
+				}
+
+				// Step 2: remove docId from each old trigram's posting list
+				for (const trigram of oldTrigrams) {
+					const req = postings.get(trigram);
+					req.onsuccess = () => {
+						const list: string[] = req.result ?? [];
+						const updated = list.filter((id) => id !== docId);
+						if (updated.length === 0) {
+							postings.delete(trigram);
+						} else {
+							postings.put(updated, trigram);
+						}
+						done();
+					};
+					req.onerror = done;
+				}
+
+				// Step 3: add docId to each new trigram's posting list
+				for (const trigram of newTrigrams) {
+					const req = postings.get(trigram);
+					req.onsuccess = () => {
+						const list: string[] = req.result ?? [];
+						if (!list.includes(docId)) {
+							list.push(docId);
+						}
+						postings.put(list, trigram);
+						done();
+					};
+					req.onerror = done;
+				}
+
+				// Step 4: save new trigram set for this doc
+				const writeReq = docTrigramsStore.put([...newTrigrams], docId);
+				writeReq.onsuccess = done;
+				writeReq.onerror = done;
+			};
+			oldReq.onerror = () => reject(oldReq.error);
+		});
+	}
+
+	/** Remove all indexed content for a document. */
+	async remove(docId: string): Promise<void> {
+		const db = await this.getDb();
+		if (!db) return;
+
+		return new Promise<void>((resolve, reject) => {
+			const tx = db.transaction(["postings", "doc_trigrams"], "readwrite");
+			tx.oncomplete = () => resolve();
+			tx.onerror = () => reject(tx.error);
+
+			const postings = tx.objectStore("postings");
+			const docTrigramsStore = tx.objectStore("doc_trigrams");
+
+			const oldReq = docTrigramsStore.get(docId);
+			oldReq.onsuccess = () => {
+				const oldTrigrams: string[] = oldReq.result ?? [];
+
+				for (const trigram of oldTrigrams) {
+					const req = postings.get(trigram);
+					req.onsuccess = () => {
+						const list: string[] = req.result ?? [];
+						const updated = list.filter((id) => id !== docId);
+						if (updated.length === 0) {
+							postings.delete(trigram);
+						} else {
+							postings.put(updated, trigram);
+						}
+					};
+				}
+
+				docTrigramsStore.delete(docId);
+			};
+			oldReq.onerror = () => reject(oldReq.error);
+		});
+	}
+
+	/**
+	 * Search for documents matching the query.
+	 * Returns results sorted by score (matching trigram count) descending.
+	 */
+	async search(query: string, limit = 20): Promise<SearchResult[]> {
+		const db = await this.getDb();
+		if (!db) return [];
+
+		const queryTrigrams = [...extractTrigrams(query)];
+		if (queryTrigrams.length === 0) return [];
+
+		return new Promise<SearchResult[]>((resolve, reject) => {
+			const tx = db.transaction("postings", "readonly");
+			const postings = tx.objectStore("postings");
+			const scores = new Map<string, number>();
+			let remaining = queryTrigrams.length;
+
+			for (const trigram of queryTrigrams) {
+				const req = postings.get(trigram);
+				req.onsuccess = () => {
+					const docIds: string[] = req.result ?? [];
+					for (const docId of docIds) {
+						scores.set(docId, (scores.get(docId) ?? 0) + 1);
+					}
+					remaining--;
+					if (remaining === 0) {
+						const results: SearchResult[] = [...scores.entries()]
+							.map(([docId, score]) => ({ docId, score }))
+							.sort((a, b) => b.score - a.score)
+							.slice(0, limit);
+						resolve(results);
+					}
+				};
+				req.onerror = () => {
+					remaining--;
+					if (remaining === 0) {
+						const results: SearchResult[] = [...scores.entries()]
+							.map(([docId, score]) => ({ docId, score }))
+							.sort((a, b) => b.score - a.score)
+							.slice(0, limit);
+						resolve(results);
+					}
+				};
+			}
+
+			tx.onerror = () => reject(tx.error);
+		});
+	}
+
+	// ── Lifecycle ─────────────────────────────────────────────────────────────
+
+	destroy(): void {
+		this.db?.close();
+		this.db = null;
+	}
+}

package/src/auth.ts

@@ -0,0 +1,62 @@
+import * as encoding from "lib0/encoding";
+import * as decoding from "lib0/decoding";
+import type { AuthorizedScope } from "./types.ts";
+
+export enum AuthMessageType {
+	Token = 0,
+	PermissionDenied = 1,
+	Authenticated = 2,
+}
+
+export const writeAuthentication = (
+	encoder: encoding.Encoder,
+	auth: string,
+) => {
+	encoding.writeVarUint(encoder, AuthMessageType.Token);
+	encoding.writeVarString(encoder, auth);
+};
+
+export const writePermissionDenied = (
+	encoder: encoding.Encoder,
+	reason: string,
+) => {
+	encoding.writeVarUint(encoder, AuthMessageType.PermissionDenied);
+	encoding.writeVarString(encoder, reason);
+};
+
+export const writeAuthenticated = (
+	encoder: encoding.Encoder,
+	scope: AuthorizedScope,
+) => {
+	encoding.writeVarUint(encoder, AuthMessageType.Authenticated);
+	encoding.writeVarString(encoder, scope);
+};
+
+export const writeTokenSyncRequest = (
+	encoder: encoding.Encoder,
+) => {
+	encoding.writeVarUint(encoder, AuthMessageType.Token);
+};
+
+export const readAuthMessage = (
+	decoder: decoding.Decoder,
+	sendToken: () => void,
+	permissionDeniedHandler: (reason: string) => void,
+	authenticatedHandler: (scope: string) => void,
+) => {
+	switch (decoding.readVarUint(decoder)) {
+		case AuthMessageType.Token: {
+			sendToken();
+			break;
+		}
+		case AuthMessageType.PermissionDenied: {
+			permissionDeniedHandler(decoding.readVarString(decoder));
+			break;
+		}
+		case AuthMessageType.Authenticated: {
+			authenticatedHandler(decoding.readVarString(decoder));
+			break;
+		}
+		default:
+	}
+};

package/src/awarenessStatesToArray.ts

@@ -0,0 +1,10 @@
+export const awarenessStatesToArray = (
+	states: Map<number, Record<string, any>>,
+) => {
+	return Array.from(states.entries()).map(([key, value]) => {
+		return {
+			clientId: key,
+			...value,
+		};
+	});
+};