@abraca/dabra 0.6.0 → 0.8.0

package/src/DocumentCache.ts

@@ -0,0 +1,210 @@
+/**
+ * IndexedDB-backed cache for REST API metadata (documents, children, profiles,
+ * permissions, uploads). Provides offline-first read access to data fetched
+ * from the server.
+ *
+ * Each entry carries a `cachedAt` timestamp; reads return null once the TTL
+ * has elapsed. The cache is scoped by server origin so the same app can work
+ * against multiple backends without cross-contamination.
+ *
+ * Designed to be passed to AbracadabraClientConfig.cache so the client
+ * automatically checks the cache before hitting the network.
+ */
+
+import type {
+	DocumentMeta,
+	UserProfile,
+	PermissionEntry,
+	UploadInfo,
+} from "./types.ts";
+
+const DB_VERSION = 1;
+const DEFAULT_TTL_MS = 5 * 60 * 1000; // 5 minutes
+
+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:meta-cache:${origin}`,
+			DB_VERSION,
+		);
+
+		req.onupgradeneeded = (event) => {
+			const db = (event.target as IDBOpenDBRequest).result;
+			for (const name of ["doc_meta", "children", "user_profile", "permissions", "uploads"]) {
+				if (!db.objectStoreNames.contains(name)) {
+					db.createObjectStore(name);
+				}
+			}
+		};
+
+		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);
+	});
+}
+
+export interface DocumentCacheOptions {
+	/** How long cached entries remain valid. Default: 5 minutes. */
+	ttlMs?: number;
+}
+
+export class DocumentCache {
+	private readonly origin: string;
+	private readonly ttlMs: number;
+	private dbPromise: Promise<IDBDatabase | null> | null = null;
+	private db: IDBDatabase | null = null;
+
+	constructor(serverOrigin: string, opts?: DocumentCacheOptions) {
+		this.origin = serverOrigin;
+		this.ttlMs = opts?.ttlMs ?? DEFAULT_TTL_MS;
+	}
+
+	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 isExpired(cachedAt: number): boolean {
+		return Date.now() - cachedAt > this.ttlMs;
+	}
+
+	// ── Generic TTL helpers ───────────────────────────────────────────────────
+
+	private async getWithTtl<T>(
+		storeName: string,
+		key: string,
+	): Promise<T | null> {
+		const db = await this.getDb();
+		if (!db) return null;
+		const tx = db.transaction(storeName, "readonly");
+		const result = await txPromise<{ value: T; cachedAt: number } | undefined>(
+			tx.objectStore(storeName),
+			tx.objectStore(storeName).get(key),
+		);
+		if (!result) return null;
+		if (this.isExpired(result.cachedAt)) {
+			// Stale — evict asynchronously and signal miss
+			this.deleteKey(storeName, key).catch(() => null);
+			return null;
+		}
+		return result.value;
+	}
+
+	private async setWithTtl<T>(storeName: string, key: string, value: T): Promise<void> {
+		const db = await this.getDb();
+		if (!db) return;
+		const entry = { value, cachedAt: Date.now() };
+		const tx = db.transaction(storeName, "readwrite");
+		await txPromise(
+			tx.objectStore(storeName),
+			tx.objectStore(storeName).put(entry, key),
+		);
+	}
+
+	private async deleteKey(storeName: string, key: string): Promise<void> {
+		const db = await this.getDb();
+		if (!db) return;
+		const tx = db.transaction(storeName, "readwrite");
+		await txPromise(tx.objectStore(storeName), tx.objectStore(storeName).delete(key));
+	}
+
+	// ── Document metadata ─────────────────────────────────────────────────────
+
+	async getDoc(docId: string): Promise<DocumentMeta | null> {
+		return this.getWithTtl<DocumentMeta>("doc_meta", docId);
+	}
+
+	async setDoc(meta: DocumentMeta): Promise<void> {
+		return this.setWithTtl("doc_meta", meta.id, meta);
+	}
+
+	async invalidateDoc(docId: string): Promise<void> {
+		await this.deleteKey("doc_meta", docId).catch(() => null);
+	}
+
+	// ── Children list ─────────────────────────────────────────────────────────
+
+	async getChildren(parentId: string): Promise<string[] | null> {
+		return this.getWithTtl<string[]>("children", parentId);
+	}
+
+	async setChildren(parentId: string, items: string[]): Promise<void> {
+		return this.setWithTtl("children", parentId, items);
+	}
+
+	async invalidateChildren(parentId: string): Promise<void> {
+		await this.deleteKey("children", parentId).catch(() => null);
+	}
+
+	// ── User profile ──────────────────────────────────────────────────────────
+
+	async getProfile(userId: string): Promise<UserProfile | null> {
+		return this.getWithTtl<UserProfile>("user_profile", userId);
+	}
+
+	async setProfile(profile: UserProfile): Promise<void> {
+		return this.setWithTtl("user_profile", profile.id, profile);
+	}
+
+	/** Get the cached profile for the currently authenticated user. */
+	async getCurrentProfile(): Promise<UserProfile | null> {
+		return this.getWithTtl<UserProfile>("user_profile", "__current__");
+	}
+
+	/** Cache a profile both by its ID and as the current user. */
+	async setCurrentProfile(profile: UserProfile): Promise<void> {
+		await Promise.all([
+			this.setWithTtl("user_profile", profile.id, profile),
+			this.setWithTtl("user_profile", "__current__", profile),
+		]);
+	}
+
+	// ── Permissions ───────────────────────────────────────────────────────────
+
+	async getPermissions(docId: string): Promise<PermissionEntry[] | null> {
+		return this.getWithTtl<PermissionEntry[]>("permissions", docId);
+	}
+
+	async setPermissions(docId: string, items: PermissionEntry[]): Promise<void> {
+		return this.setWithTtl("permissions", docId, items);
+	}
+
+	// ── Uploads list ──────────────────────────────────────────────────────────
+
+	async getUploads(docId: string): Promise<UploadInfo[] | null> {
+		return this.getWithTtl<UploadInfo[]>("uploads", docId);
+	}
+
+	async setUploads(docId: string, items: UploadInfo[]): Promise<void> {
+		return this.setWithTtl("uploads", docId, items);
+	}
+
+	async invalidateUploads(docId: string): Promise<void> {
+		await this.deleteKey("uploads", docId).catch(() => null);
+	}
+
+	// ── Lifecycle ─────────────────────────────────────────────────────────────
+
+	destroy(): void {
+		this.db?.close();
+		this.db = null;
+	}
+}

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";