@abraca/dabra 0.1.0

package/src/MessageReceiver.ts

@@ -0,0 +1,139 @@
+import { readAuthMessage } from "@hocuspocus/common";
+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 { IncomingMessage } from "./IncomingMessage.ts";
+import { OutgoingMessage } from "./OutgoingMessage.ts";
+import { MessageType } from "./types.ts";
+
+export class MessageReceiver {
+	message: IncomingMessage;
+
+	constructor(message: IncomingMessage) {
+		this.message = message;
+	}
+
+	public apply(provider: HocuspocusProvider, emitSynced: boolean) {
+		const { message } = this;
+		const type = message.readVarUint();
+
+		const emptyMessageLength = message.length();
+
+		switch (type) {
+			case MessageType.Sync:
+				this.applySyncMessage(provider, emitSynced);
+				break;
+
+			case MessageType.Awareness:
+				this.applyAwarenessMessage(provider);
+				break;
+
+			case MessageType.Auth:
+				this.applyAuthMessage(provider);
+				break;
+
+			case MessageType.QueryAwareness:
+				this.applyQueryAwarenessMessage(provider);
+				break;
+
+			case MessageType.Stateless:
+				provider.receiveStateless(readVarString(message.decoder));
+				break;
+
+			case MessageType.SyncStatus:
+				this.applySyncStatusMessage(
+					provider,
+					readVarInt(message.decoder) === 1,
+				);
+				break;
+
+			case MessageType.CLOSE:
+				// eslint-disable-next-line no-case-declarations
+				const event: CloseEvent = {
+					code: 1000,
+					reason: readVarString(message.decoder),
+					// @ts-ignore
+					target: provider.configuration.websocketProvider.webSocket!,
+					type: "close",
+				};
+				provider.onClose();
+				provider.configuration.onClose({ event });
+				provider.forwardClose({ event });
+				break;
+
+			default:
+				throw new Error(`Can’t apply message of unknown type: ${type}`);
+		}
+
+		// Reply
+		if (message.length() > emptyMessageLength + 1) {
+			// length of documentName (considered in emptyMessageLength plus length of yjs sync type, set in applySyncMessage)
+			// @ts-ignore
+			provider.send(OutgoingMessage, { encoder: message.encoder });
+		}
+	}
+
+	private applySyncMessage(provider: HocuspocusProvider, emitSynced: boolean) {
+		const { message } = this;
+
+		message.writeVarUint(MessageType.Sync);
+
+		// Apply update
+		const syncMessageType = readSyncMessage(
+			message.decoder,
+			message.encoder,
+			provider.document,
+			provider,
+		);
+
+		// Synced once we receive Step2
+		if (emitSynced && syncMessageType === messageYjsSyncStep2) {
+			provider.synced = true;
+		}
+	}
+
+	applySyncStatusMessage(provider: HocuspocusProvider, applied: boolean) {
+		if (applied) {
+			provider.decrementUnsyncedChanges();
+		}
+	}
+
+	private applyAwarenessMessage(provider: HocuspocusProvider) {
+		if (!provider.awareness) return;
+
+		const { message } = this;
+
+		awarenessProtocol.applyAwarenessUpdate(
+			provider.awareness,
+			message.readVarUint8Array(),
+			provider,
+		);
+	}
+
+	private applyAuthMessage(provider: HocuspocusProvider) {
+		const { message } = this;
+
+		readAuthMessage(
+			message.decoder,
+			provider.sendToken.bind(provider),
+			provider.permissionDeniedHandler.bind(provider),
+			provider.authenticatedHandler.bind(provider),
+		);
+	}
+
+	private applyQueryAwarenessMessage(provider: HocuspocusProvider) {
+		if (!provider.awareness) return;
+
+		const { message } = this;
+
+		message.writeVarUint(MessageType.Awareness);
+		message.writeVarUint8Array(
+			awarenessProtocol.encodeAwarenessUpdate(
+				provider.awareness,
+				Array.from(provider.awareness.getStates().keys()),
+			),
+		);
+	}
+}

package/src/MessageSender.ts

@@ -0,0 +1,22 @@
+import type { Encoder } from "lib0/encoding";
+import { toUint8Array } from "lib0/encoding";
+import type { ConstructableOutgoingMessage } from "./types.ts";
+
+export class MessageSender {
+	encoder: Encoder;
+
+	message: any;
+
+	constructor(Message: ConstructableOutgoingMessage, args: any = {}) {
+		this.message = new Message();
+		this.encoder = this.message.get(args);
+	}
+
+	create() {
+		return toUint8Array(this.encoder);
+	}
+
+	send(webSocket: any) {
+		webSocket?.send(this.create());
+	}
+}

package/src/OfflineStore.ts

@@ -0,0 +1,185 @@
+/**
+ * IndexedDB-backed offline store for a single Abracadabra document.
+ *
+ * Responsibilities:
+ *  - Persist CRDT updates locally so they survive page refreshes / network loss.
+ *  - Store the last-known state vector for fast reconnect diffs.
+ *  - Store a permission snapshot so the UI can gate writes without a network round-trip.
+ *  - Queue subdoc registration events created while offline.
+ *
+ * Falls back to a silent no-op when IndexedDB is unavailable (e.g. SSR / Node.js).
+ */
+
+export interface PendingSubdoc {
+	childId: string;
+	parentId: string;
+	createdAt: number;
+}
+
+const DB_VERSION = 1;
+
+function idbAvailable(): boolean {
+	return typeof globalThis !== "undefined" && "indexedDB" in globalThis;
+}
+
+function openDb(docId: string): Promise<IDBDatabase> {
+	return new Promise((resolve, reject) => {
+		const req = globalThis.indexedDB.open(`abracadabra:${docId}`, DB_VERSION);
+
+		req.onupgradeneeded = (event) => {
+			const db = (event.target as IDBOpenDBRequest).result;
+
+			if (!db.objectStoreNames.contains("updates")) {
+				db.createObjectStore("updates", { autoIncrement: true });
+			}
+			if (!db.objectStoreNames.contains("meta")) {
+				db.createObjectStore("meta");
+			}
+			if (!db.objectStoreNames.contains("subdoc_queue")) {
+				db.createObjectStore("subdoc_queue", { keyPath: "childId" });
+			}
+		};
+
+		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 class OfflineStore {
+	private docId: string;
+	private db: IDBDatabase | null = null;
+
+	constructor(docId: string) {
+		this.docId = docId;
+	}
+
+	private async getDb(): Promise<IDBDatabase | null> {
+		if (!idbAvailable()) return null;
+		if (!this.db) {
+			this.db = await openDb(this.docId).catch(() => null);
+		}
+		return this.db;
+	}
+
+	// ── Updates ─────────────────────────────────────────────────────────────
+
+	async persistUpdate(update: Uint8Array): Promise<void> {
+		const db = await this.getDb();
+		if (!db) return;
+		const tx = db.transaction("updates", "readwrite");
+		const store = tx.objectStore("updates");
+		await txPromise(store, store.add(update));
+	}
+
+	async getPendingUpdates(): Promise<Uint8Array[]> {
+		const db = await this.getDb();
+		if (!db) return [];
+		return new Promise((resolve, reject) => {
+			const tx = db.transaction("updates", "readonly");
+			const store = tx.objectStore("updates");
+			const req = store.getAll();
+			req.onsuccess = () => resolve(req.result as Uint8Array[]);
+			req.onerror = () => reject(req.error);
+		});
+	}
+
+	async clearPendingUpdates(): Promise<void> {
+		const db = await this.getDb();
+		if (!db) return;
+		const tx = db.transaction("updates", "readwrite");
+		await txPromise(tx.objectStore("updates"), tx.objectStore("updates").clear());
+	}
+
+	// ── State vector ─────────────────────────────────────────────────────────
+
+	async getStateVector(): Promise<Uint8Array | null> {
+		const db = await this.getDb();
+		if (!db) return null;
+		const tx = db.transaction("meta", "readonly");
+		const result = await txPromise<Uint8Array | undefined>(
+			tx.objectStore("meta"),
+			tx.objectStore("meta").get("sv"),
+		);
+		return result ?? null;
+	}
+
+	async saveStateVector(sv: Uint8Array): Promise<void> {
+		const db = await this.getDb();
+		if (!db) return;
+		const tx = db.transaction("meta", "readwrite");
+		await txPromise(tx.objectStore("meta"), tx.objectStore("meta").put(sv, "sv"));
+	}
+
+	// ── Permission snapshot ──────────────────────────────────────────────────
+
+	async getPermissionSnapshot(): Promise<string | null> {
+		const db = await this.getDb();
+		if (!db) return null;
+		const tx = db.transaction("meta", "readonly");
+		const result = await txPromise<string | undefined>(
+			tx.objectStore("meta"),
+			tx.objectStore("meta").get("role"),
+		);
+		return result ?? null;
+	}
+
+	async savePermissionSnapshot(role: string): Promise<void> {
+		const db = await this.getDb();
+		if (!db) return;
+		const tx = db.transaction("meta", "readwrite");
+		await txPromise(
+			tx.objectStore("meta"),
+			tx.objectStore("meta").put(role, "role"),
+		);
+	}
+
+	// ── Subdoc registration queue ─────────────────────────────────────────────
+
+	async queueSubdoc(entry: PendingSubdoc): Promise<void> {
+		const db = await this.getDb();
+		if (!db) return;
+		const tx = db.transaction("subdoc_queue", "readwrite");
+		await txPromise(
+			tx.objectStore("subdoc_queue"),
+			tx.objectStore("subdoc_queue").put(entry),
+		);
+	}
+
+	async getPendingSubdocs(): Promise<PendingSubdoc[]> {
+		const db = await this.getDb();
+		if (!db) return [];
+		return new Promise((resolve, reject) => {
+			const tx = db.transaction("subdoc_queue", "readonly");
+			const req = tx.objectStore("subdoc_queue").getAll();
+			req.onsuccess = () => resolve(req.result as PendingSubdoc[]);
+			req.onerror = () => reject(req.error);
+		});
+	}
+
+	async removeSubdocFromQueue(childId: string): Promise<void> {
+		const db = await this.getDb();
+		if (!db) return;
+		const tx = db.transaction("subdoc_queue", "readwrite");
+		await txPromise(
+			tx.objectStore("subdoc_queue"),
+			tx.objectStore("subdoc_queue").delete(childId),
+		);
+	}
+
+	// ── Lifecycle ─────────────────────────────────────────────────────────────
+
+	destroy() {
+		this.db?.close();
+		this.db = null;
+	}
+}

package/src/OutgoingMessage.ts

@@ -0,0 +1,25 @@
+import type { Encoder } from "lib0/encoding";
+import { createEncoder, toUint8Array } from "lib0/encoding";
+import type {
+	MessageType,
+	OutgoingMessageArguments,
+	OutgoingMessageInterface,
+} from "./types.ts";
+
+export class OutgoingMessage implements OutgoingMessageInterface {
+	encoder: Encoder;
+
+	type?: MessageType;
+
+	constructor() {
+		this.encoder = createEncoder();
+	}
+
+	get(args: Partial<OutgoingMessageArguments>) {
+		return args.encoder;
+	}
+
+	toUint8Array() {
+		return toUint8Array(this.encoder);
+	}
+}

package/src/OutgoingMessages/AuthenticationMessage.ts

@@ -0,0 +1,25 @@
+import { writeVarString, writeVarUint } from "lib0/encoding";
+import { writeAuthentication } from "@hocuspocus/common";
+import type { OutgoingMessageArguments } from "../types.ts";
+import { MessageType } from "../types.ts";
+import { OutgoingMessage } from "../OutgoingMessage.ts";
+
+export class AuthenticationMessage extends OutgoingMessage {
+	type = MessageType.Auth;
+
+	description = "Authentication";
+
+	get(args: Partial<OutgoingMessageArguments>) {
+		if (typeof args.token === "undefined") {
+			throw new Error(
+				"The authentication message requires `token` as an argument.",
+			);
+		}
+
+		writeVarString(this.encoder, args.documentName!);
+		writeVarUint(this.encoder, this.type);
+		writeAuthentication(this.encoder, args.token);
+
+		return this.encoder;
+	}
+}

package/src/OutgoingMessages/AwarenessMessage.ts

@@ -0,0 +1,41 @@
+import * as encoding from "lib0/encoding";
+import { encodeAwarenessUpdate } from "y-protocols/awareness";
+import type { OutgoingMessageArguments } from "../types.ts";
+import { MessageType } from "../types.ts";
+import { OutgoingMessage } from "../OutgoingMessage.ts";
+
+export class AwarenessMessage extends OutgoingMessage {
+	type = MessageType.Awareness;
+
+	description = "Awareness states update";
+
+	get(args: Partial<OutgoingMessageArguments>) {
+		if (typeof args.awareness === "undefined") {
+			throw new Error(
+				"The awareness message requires awareness as an argument",
+			);
+		}
+
+		if (typeof args.clients === "undefined") {
+			throw new Error("The awareness message requires clients as an argument");
+		}
+
+		encoding.writeVarString(this.encoder, args.documentName!);
+		encoding.writeVarUint(this.encoder, this.type);
+
+		let awarenessUpdate;
+		if (args.states === undefined) {
+			awarenessUpdate = encodeAwarenessUpdate(args.awareness, args.clients);
+		} else {
+			awarenessUpdate = encodeAwarenessUpdate(
+				args.awareness,
+				args.clients,
+				args.states,
+			);
+		}
+
+		encoding.writeVarUint8Array(this.encoder, awarenessUpdate);
+
+		return this.encoder;
+	}
+}

package/src/OutgoingMessages/CloseMessage.ts

@@ -0,0 +1,17 @@
+import * as encoding from "lib0/encoding";
+import type { OutgoingMessageArguments } from "../types.ts";
+import { MessageType } from "../types.ts";
+import { OutgoingMessage } from "../OutgoingMessage.ts";
+
+export class CloseMessage extends OutgoingMessage {
+	type = MessageType.CLOSE;
+
+	description = "Ask the server to close the connection";
+
+	get(args: Partial<OutgoingMessageArguments>) {
+		encoding.writeVarString(this.encoder, args.documentName!);
+		encoding.writeVarUint(this.encoder, this.type);
+
+		return this.encoder;
+	}
+}

package/src/OutgoingMessages/QueryAwarenessMessage.ts

@@ -0,0 +1,17 @@
+import * as encoding from "lib0/encoding";
+import type { OutgoingMessageArguments } from "../types.ts";
+import { MessageType } from "../types.ts";
+import { OutgoingMessage } from "../OutgoingMessage.ts";
+
+export class QueryAwarenessMessage extends OutgoingMessage {
+	type = MessageType.QueryAwareness;
+
+	description = "Queries awareness states";
+
+	get(args: Partial<OutgoingMessageArguments>) {
+		encoding.writeVarString(this.encoder, args.documentName!);
+		encoding.writeVarUint(this.encoder, this.type);
+
+		return this.encoder;
+	}
+}

package/src/OutgoingMessages/StatelessMessage.ts

@@ -0,0 +1,18 @@
+import { writeVarString, writeVarUint } from "lib0/encoding";
+import type { OutgoingMessageArguments } from "../types.ts";
+import { MessageType } from "../types.ts";
+import { OutgoingMessage } from "../OutgoingMessage.ts";
+
+export class StatelessMessage extends OutgoingMessage {
+	type = MessageType.Stateless;
+
+	description = "A stateless message";
+
+	get(args: Partial<OutgoingMessageArguments>) {
+		writeVarString(this.encoder, args.documentName!);
+		writeVarUint(this.encoder, this.type);
+		writeVarString(this.encoder, args.payload ?? "");
+
+		return this.encoder;
+	}
+}

package/src/OutgoingMessages/SubdocMessage.ts

@@ -0,0 +1,35 @@
+import { writeVarString, writeVarUint } from "lib0/encoding";
+import type { OutgoingMessageArguments } from "../types.ts";
+import { MessageType } from "../types.ts";
+import { OutgoingMessage } from "../OutgoingMessage.ts";
+
+/**
+ * Registers a new subdocument with the Abracadabra server.
+ *
+ * Wire format (consumed by handle_subdoc in sync.rs):
+ *   [ParentDocName: VarString] [MSG_SUBDOC(4): VarUint] [childDocumentName: VarString]
+ *
+ * The server responds with a MSG_STATELESS JSON frame:
+ *   { type: "subdoc_registered", child_id, parent_id }
+ * which AbracadabraProvider intercepts in receiveStateless().
+ */
+export class SubdocMessage extends OutgoingMessage {
+	type = MessageType.Subdoc;
+
+	description = "SubdocRegistration";
+
+	get(args: Partial<OutgoingMessageArguments>) {
+		if (!args.documentName) {
+			throw new Error("SubdocMessage requires `documentName` (parent id).");
+		}
+		if (!args.childDocumentName) {
+			throw new Error("SubdocMessage requires `childDocumentName`.");
+		}
+
+		writeVarString(this.encoder, args.documentName);
+		writeVarUint(this.encoder, this.type);
+		writeVarString(this.encoder, args.childDocumentName);
+
+		return this.encoder;
+	}
+}

package/src/OutgoingMessages/SyncStepOneMessage.ts

@@ -0,0 +1,25 @@
+import * as encoding from "lib0/encoding";
+import * as syncProtocol from "y-protocols/sync";
+import type { OutgoingMessageArguments } from "../types.ts";
+import { MessageType } from "../types.ts";
+import { OutgoingMessage } from "../OutgoingMessage.ts";
+
+export class SyncStepOneMessage extends OutgoingMessage {
+	type = MessageType.Sync;
+
+	description = "First sync step";
+
+	get(args: Partial<OutgoingMessageArguments>) {
+		if (typeof args.document === "undefined") {
+			throw new Error(
+				"The sync step one message requires document as an argument",
+			);
+		}
+
+		encoding.writeVarString(this.encoder, args.documentName!);
+		encoding.writeVarUint(this.encoder, this.type);
+		syncProtocol.writeSyncStep1(this.encoder, args.document);
+
+		return this.encoder;
+	}
+}

package/src/OutgoingMessages/SyncStepTwoMessage.ts

@@ -0,0 +1,25 @@
+import * as encoding from "lib0/encoding";
+import * as syncProtocol from "y-protocols/sync";
+import type { OutgoingMessageArguments } from "../types.ts";
+import { MessageType } from "../types.ts";
+import { OutgoingMessage } from "../OutgoingMessage.ts";
+
+export class SyncStepTwoMessage extends OutgoingMessage {
+	type = MessageType.Sync;
+
+	description = "Second sync step";
+
+	get(args: Partial<OutgoingMessageArguments>) {
+		if (typeof args.document === "undefined") {
+			throw new Error(
+				"The sync step two message requires document as an argument",
+			);
+		}
+
+		encoding.writeVarString(this.encoder, args.documentName!);
+		encoding.writeVarUint(this.encoder, this.type);
+		syncProtocol.writeSyncStep2(this.encoder, args.document);
+
+		return this.encoder;
+	}
+}

package/src/OutgoingMessages/UpdateMessage.ts

@@ -0,0 +1,20 @@
+import { writeVarString, writeVarUint } from "lib0/encoding";
+import { writeUpdate } from "y-protocols/sync";
+import type { OutgoingMessageArguments } from "../types.ts";
+import { MessageType } from "../types.ts";
+import { OutgoingMessage } from "../OutgoingMessage.ts";
+
+export class UpdateMessage extends OutgoingMessage {
+	type = MessageType.Sync;
+
+	description = "A document update";
+
+	get(args: Partial<OutgoingMessageArguments>) {
+		writeVarString(this.encoder, args.documentName!);
+		writeVarUint(this.encoder, this.type);
+
+		writeUpdate(this.encoder, args.update);
+
+		return this.encoder;
+	}
+}

package/src/index.ts

@@ -0,0 +1,7 @@
+export * from "./HocuspocusProvider.ts";
+export * from "./HocuspocusProviderWebsocket.ts";
+export * from "./types.ts";
+export * from "./AbracadabraProvider.ts";
+export * from "./OfflineStore.ts";
+export { SubdocMessage } from "./OutgoingMessages/SubdocMessage.ts";
+export { CryptoIdentityKeystore } from "./CryptoIdentityKeystore.ts";