@abraca/dabra 1.0.2 → 1.0.4

package/src/webrtc/SignalingSocket.ts

@@ -0,0 +1,366 @@
+import { retry } from "@lifeomic/attempt";
+import EventEmitter from "../EventEmitter.ts";
+import type {
+	PeerInfo,
+	SignalingIncoming,
+	SignalingOutgoing,
+} from "./types.ts";
+
+export interface SignalingSocketConfiguration {
+	/** WebSocket URL for the signaling endpoint. */
+	url: string;
+
+	/** JWT token or async token factory for auth. */
+	token: string | (() => string) | (() => Promise<string>);
+
+	/** Auto-connect on construction. Default: true. */
+	autoConnect?: boolean;
+
+	/** WebSocket polyfill (e.g. for Node.js). */
+	WebSocketPolyfill?: any;
+
+	/** Retry delay in ms. Default: 1000. */
+	delay?: number;
+	/** Retry factor. Default: 2. */
+	factor?: number;
+	/** Min retry delay. Default: 1000. */
+	minDelay?: number;
+	/** Max retry delay. Default: 30000. */
+	maxDelay?: number;
+	/** Randomize delay. Default: true. */
+	jitter?: boolean;
+	/** Max retry attempts (0 = unlimited). Default: 0. */
+	maxAttempts?: number;
+}
+
+export class SignalingSocket extends EventEmitter {
+	private ws: WebSocket | null = null;
+	private wsHandlers: Record<string, (e: any) => void> = {};
+	private shouldConnect = true;
+	private cancelRetry?: () => void;
+	private connectionAttempt: {
+		resolve: (v?: any) => void;
+		reject: (r?: any) => void;
+	} | null = null;
+
+	private readonly config: Required<
+		Pick<
+			SignalingSocketConfiguration,
+			| "url"
+			| "token"
+			| "delay"
+			| "factor"
+			| "minDelay"
+			| "maxDelay"
+			| "jitter"
+			| "maxAttempts"
+		>
+	> & { WebSocketPolyfill: any };
+
+	public localPeerId: string | null = null;
+	public isConnected = false;
+
+	constructor(configuration: SignalingSocketConfiguration) {
+		super();
+
+		this.config = {
+			url: configuration.url,
+			token: configuration.token,
+			delay: configuration.delay ?? 1000,
+			factor: configuration.factor ?? 2,
+			minDelay: configuration.minDelay ?? 1000,
+			maxDelay: configuration.maxDelay ?? 30000,
+			jitter: configuration.jitter ?? true,
+			maxAttempts: configuration.maxAttempts ?? 0,
+			WebSocketPolyfill: configuration.WebSocketPolyfill ?? WebSocket,
+		};
+
+		if (configuration.autoConnect !== false) {
+			this.connect();
+		}
+	}
+
+	private async getToken(): Promise<string> {
+		if (typeof this.config.token === "function") {
+			return await this.config.token();
+		}
+		return this.config.token;
+	}
+
+	async connect(): Promise<void> {
+		if (this.isConnected) return;
+
+		if (this.cancelRetry) {
+			this.cancelRetry();
+			this.cancelRetry = undefined;
+		}
+
+		this.shouldConnect = true;
+
+		let cancelAttempt = false;
+
+		const retryPromise = retry(
+			() => this.createConnection(),
+			{
+				delay: this.config.delay,
+				initialDelay: 0,
+				factor: this.config.factor,
+				maxAttempts: this.config.maxAttempts,
+				minDelay: this.config.minDelay,
+				maxDelay: this.config.maxDelay,
+				jitter: this.config.jitter,
+				timeout: 0,
+				beforeAttempt: (context) => {
+					if (!this.shouldConnect || cancelAttempt) {
+						context.abort();
+					}
+				},
+			},
+		).catch((error: any) => {
+			if (error && error.code !== "ATTEMPT_ABORTED") {
+				throw error;
+			}
+		});
+
+		this.cancelRetry = () => {
+			cancelAttempt = true;
+		};
+
+		return retryPromise;
+	}
+
+	private async createConnection(): Promise<void> {
+		this.cleanup();
+
+		const token = await this.getToken();
+		const separator = this.config.url.includes("?") ? "&" : "?";
+		const url = `${this.config.url}${separator}token=${encodeURIComponent(token)}`;
+
+		const ws = new this.config.WebSocketPolyfill(url);
+
+		return new Promise((resolve, reject) => {
+			const onOpen = () => {
+				this.isConnected = true;
+				// Server auto-sends Welcome on join; we send Join to register
+				this.sendRaw({ type: "join" });
+			};
+
+			// eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
+			const onMessage = (event: MessageEvent | { data: string }) => {
+				const data =
+					typeof event === "string"
+						? event
+						: typeof (event as MessageEvent).data === "string"
+							? (event as MessageEvent).data
+							: null;
+				if (!data) return;
+
+				let msg: SignalingOutgoing;
+				try {
+					msg = JSON.parse(data);
+				} catch {
+					return;
+				}
+
+				this.handleMessage(msg, resolve);
+			};
+
+			const onClose = (event: CloseEvent | { code?: number }) => {
+				const wasConnected = this.isConnected;
+				this.isConnected = false;
+				this.localPeerId = null;
+
+				if (this.connectionAttempt) {
+					this.connectionAttempt = null;
+					reject(
+						new Error(`Signaling WebSocket closed: ${(event as CloseEvent)?.code}`),
+					);
+				}
+
+				this.emit("disconnected");
+
+				if (!wasConnected) return;
+
+				// Auto-reconnect if desired
+				if (this.shouldConnect && !this.cancelRetry) {
+					setTimeout(() => this.connect(), this.config.delay);
+				}
+			};
+
+			const onError = (err: Event) => {
+				if (this.connectionAttempt) {
+					this.connectionAttempt = null;
+					reject(err);
+				}
+			};
+
+			this.wsHandlers = {
+				open: onOpen,
+				message: onMessage,
+				close: onClose,
+				error: onError,
+			};
+
+			for (const [name, handler] of Object.entries(this.wsHandlers)) {
+				ws.addEventListener(name, handler);
+			}
+
+			this.ws = ws;
+			this.connectionAttempt = { resolve, reject };
+		});
+	}
+
+	private handleMessage(msg: SignalingOutgoing, resolveConnection?: (v?: any) => void): void {
+		switch (msg.type) {
+			case "welcome":
+				this.localPeerId = msg.peer_id;
+				if (this.connectionAttempt) {
+					this.connectionAttempt = null;
+					resolveConnection?.();
+				}
+				this.emit("welcome", {
+					peerId: msg.peer_id,
+					peers: msg.peers,
+				});
+				break;
+
+			case "joined":
+				this.emit("joined", {
+					peerId: msg.peer_id,
+					userId: msg.user_id,
+					muted: msg.muted,
+					video: msg.video,
+					screen: msg.screen,
+					name: msg.name,
+					color: msg.color,
+				} satisfies PeerInfo);
+				break;
+
+			case "left":
+				this.emit("left", { peerId: msg.peer_id });
+				break;
+
+			case "offer":
+				this.emit("offer", { from: msg.from, sdp: msg.sdp });
+				break;
+
+			case "answer":
+				this.emit("answer", { from: msg.from, sdp: msg.sdp });
+				break;
+
+			case "ice":
+				this.emit("ice", { from: msg.from, candidate: msg.candidate });
+				break;
+
+			case "mute":
+				this.emit("mute", {
+					peerId: msg.peer_id,
+					muted: msg.muted,
+				});
+				break;
+
+			case "media-state":
+				this.emit("media-state", {
+					peerId: msg.peer_id,
+					video: msg.video,
+					screen: msg.screen,
+				});
+				break;
+
+			case "profile":
+				this.emit("profile", {
+					peerId: msg.peer_id,
+					name: msg.name,
+					color: msg.color,
+				});
+				break;
+
+			case "ping":
+				this.sendRaw({ type: "pong" });
+				break;
+
+			case "error":
+				this.emit("error", {
+					code: msg.code,
+					message: msg.message,
+				});
+				break;
+		}
+	}
+
+	private sendRaw(msg: SignalingIncoming): void {
+		if (this.ws?.readyState === 1 /* OPEN */) {
+			this.ws.send(JSON.stringify(msg));
+		}
+	}
+
+	// ── Public send methods ─────────────────────────────────────────────────
+
+	sendOffer(to: string, sdp: string): void {
+		this.sendRaw({ type: "offer", to, sdp });
+	}
+
+	sendAnswer(to: string, sdp: string): void {
+		this.sendRaw({ type: "answer", to, sdp });
+	}
+
+	sendIce(to: string, candidate: string): void {
+		this.sendRaw({ type: "ice", to, candidate });
+	}
+
+	sendMute(muted: boolean): void {
+		this.sendRaw({ type: "mute", muted });
+	}
+
+	sendMediaState(video: boolean, screen: boolean): void {
+		this.sendRaw({ type: "media-state", video, screen });
+	}
+
+	sendProfile(name: string, color: string): void {
+		this.sendRaw({ type: "profile", name, color });
+	}
+
+	sendLeave(): void {
+		this.sendRaw({ type: "leave" });
+	}
+
+	// ── Lifecycle ───────────────────────────────────────────────────────────
+
+	disconnect(): void {
+		this.shouldConnect = false;
+		this.sendLeave();
+
+		if (this.cancelRetry) {
+			this.cancelRetry();
+			this.cancelRetry = undefined;
+		}
+
+		this.cleanup();
+	}
+
+	destroy(): void {
+		this.disconnect();
+		this.removeAllListeners();
+	}
+
+	private cleanup(): void {
+		if (!this.ws) return;
+
+		for (const [name, handler] of Object.entries(this.wsHandlers)) {
+			this.ws.removeEventListener(name, handler);
+		}
+		this.wsHandlers = {};
+
+		try {
+			if (this.ws.readyState !== 3 /* CLOSED */) {
+				this.ws.close();
+			}
+		} catch {
+			// Ignore close errors
+		}
+
+		this.ws = null;
+		this.isConnected = false;
+		this.localPeerId = null;
+	}
+}

package/src/webrtc/YjsDataChannel.ts

@@ -0,0 +1,195 @@
+import * as Y from "yjs";
+import * as syncProtocol from "y-protocols/sync";
+import {
+	encodeAwarenessUpdate,
+	applyAwarenessUpdate,
+	type Awareness,
+} from "y-protocols/awareness";
+import * as encoding from "lib0/encoding";
+import * as decoding from "lib0/decoding";
+import type { DataChannelRouter } from "./DataChannelRouter.ts";
+import { CHANNEL_NAMES, YJS_MSG } from "./types.ts";
+
+/**
+ * Handles Y.js document sync and awareness over WebRTC data channels.
+ *
+ * Uses the same y-protocols/sync encoding as the WebSocket provider but
+ * transported over RTCDataChannel instead. A unique origin is used to
+ * prevent echo loops with the server-based provider.
+ */
+export class YjsDataChannel {
+	private docUpdateHandler: ((update: Uint8Array, origin: any) => void) | null = null;
+	private awarenessUpdateHandler: ((changes: { added: number[]; updated: number[]; removed: number[] }, origin: any) => void) | null = null;
+	private channelOpenHandler: ((data: { name: string; channel: RTCDataChannel }) => void) | null = null;
+	private channelMessageHandler: ((data: { name: string; data: any }) => void) | null = null;
+
+	constructor(
+		private readonly document: Y.Doc,
+		private readonly awareness: Awareness | null,
+		private readonly router: DataChannelRouter,
+	) {}
+
+	/** Start listening for Y.js updates and data channel messages. */
+	attach(): void {
+		// Listen for local doc updates and send to peer.
+		this.docUpdateHandler = (update: Uint8Array, origin: any) => {
+			// Don't echo updates we received from this data channel.
+			if (origin === this) return;
+
+			const channel = this.router.getChannel(CHANNEL_NAMES.YJS_SYNC);
+			if (!channel || channel.readyState !== "open") return;
+
+			const encoder = encoding.createEncoder();
+			encoding.writeVarUint(encoder, YJS_MSG.UPDATE);
+			encoding.writeVarUint8Array(encoder, update);
+			channel.send(encoding.toUint8Array(encoder));
+		};
+		this.document.on("update", this.docUpdateHandler);
+
+		// Listen for local awareness updates and send to peer.
+		if (this.awareness) {
+			this.awarenessUpdateHandler = (
+				{ added, updated, removed }: { added: number[]; updated: number[]; removed: number[] },
+				_origin: any,
+			) => {
+				const channel = this.router.getChannel(CHANNEL_NAMES.AWARENESS);
+				if (!channel || channel.readyState !== "open") return;
+
+				const changedClients = added.concat(updated).concat(removed);
+				const update = encodeAwarenessUpdate(this.awareness!, changedClients);
+				channel.send(update);
+			};
+			this.awareness.on("update", this.awarenessUpdateHandler);
+		}
+
+		// Handle incoming data channel messages.
+		this.channelMessageHandler = ({ name, data }: { name: string; data: any }) => {
+			if (name === CHANNEL_NAMES.YJS_SYNC) {
+				this.handleSyncMessage(data);
+			} else if (name === CHANNEL_NAMES.AWARENESS) {
+				this.handleAwarenessMessage(data);
+			}
+		};
+		this.router.on("channelMessage", this.channelMessageHandler);
+
+		// When sync channel opens, initiate sync handshake.
+		this.channelOpenHandler = ({ name }: { name: string; channel: RTCDataChannel }) => {
+			if (name === CHANNEL_NAMES.YJS_SYNC) {
+				this.sendSyncStep1();
+			} else if (name === CHANNEL_NAMES.AWARENESS && this.awareness) {
+				// Send full awareness state on channel open.
+				const channel = this.router.getChannel(CHANNEL_NAMES.AWARENESS);
+				if (channel?.readyState === "open") {
+					const update = encodeAwarenessUpdate(
+						this.awareness,
+						Array.from(this.awareness.getStates().keys()),
+					);
+					channel.send(update);
+				}
+			}
+		};
+		this.router.on("channelOpen", this.channelOpenHandler);
+
+		// If sync channel is already open, start sync immediately.
+		if (this.router.isOpen(CHANNEL_NAMES.YJS_SYNC)) {
+			this.sendSyncStep1();
+		}
+
+		// If awareness channel is already open, send state immediately.
+		if (this.awareness && this.router.isOpen(CHANNEL_NAMES.AWARENESS)) {
+			const channel = this.router.getChannel(CHANNEL_NAMES.AWARENESS);
+			if (channel?.readyState === "open") {
+				const update = encodeAwarenessUpdate(
+					this.awareness,
+					Array.from(this.awareness.getStates().keys()),
+				);
+				channel.send(update);
+			}
+		}
+	}
+
+	/** Stop listening and clean up handlers. */
+	detach(): void {
+		if (this.docUpdateHandler) {
+			this.document.off("update", this.docUpdateHandler);
+			this.docUpdateHandler = null;
+		}
+
+		if (this.awarenessUpdateHandler && this.awareness) {
+			this.awareness.off("update", this.awarenessUpdateHandler);
+			this.awarenessUpdateHandler = null;
+		}
+
+		if (this.channelMessageHandler) {
+			this.router.off("channelMessage", this.channelMessageHandler);
+			this.channelMessageHandler = null;
+		}
+
+		if (this.channelOpenHandler) {
+			this.router.off("channelOpen", this.channelOpenHandler);
+			this.channelOpenHandler = null;
+		}
+
+		this.isSynced = false;
+	}
+
+	destroy(): void {
+		this.detach();
+	}
+
+	private sendSyncStep1(): void {
+		const channel = this.router.getChannel(CHANNEL_NAMES.YJS_SYNC);
+		if (!channel || channel.readyState !== "open") return;
+
+		const encoder = encoding.createEncoder();
+		encoding.writeVarUint(encoder, YJS_MSG.SYNC);
+		syncProtocol.writeSyncStep1(encoder, this.document);
+		channel.send(encoding.toUint8Array(encoder));
+	}
+
+	private handleSyncMessage(data: ArrayBuffer | Uint8Array): void {
+		const buf = data instanceof ArrayBuffer ? new Uint8Array(data) : data;
+		const decoder = decoding.createDecoder(buf);
+		const msgType = decoding.readVarUint(decoder);
+
+		if (msgType === YJS_MSG.SYNC) {
+			// Standard y-protocols/sync message (SyncStep1, SyncStep2, or Update).
+			const encoder = encoding.createEncoder();
+			const syncMessageType = syncProtocol.readSyncMessage(
+				decoder,
+				encoder,
+				this.document,
+				this,
+			);
+
+			// If the sync protocol generated a response (SyncStep2), send it.
+			if (encoding.length(encoder) > 0) {
+				const responseEncoder = encoding.createEncoder();
+				encoding.writeVarUint(responseEncoder, YJS_MSG.SYNC);
+				encoding.writeUint8Array(
+					responseEncoder,
+					encoding.toUint8Array(encoder),
+				);
+				const channel = this.router.getChannel(CHANNEL_NAMES.YJS_SYNC);
+				if (channel?.readyState === "open") {
+					channel.send(encoding.toUint8Array(responseEncoder));
+				}
+			}
+
+			// SyncStep2 means initial sync is complete.
+			if (syncMessageType === syncProtocol.messageYjsSyncStep2) {
+				this.isSynced = true;
+			}
+		} else if (msgType === YJS_MSG.UPDATE) {
+			// Raw incremental update.
+			const update = decoding.readVarUint8Array(decoder);
+			Y.applyUpdate(this.document, update, this);
+		}
+	}
+
+	private handleAwarenessMessage(data: ArrayBuffer | Uint8Array): void {
+		if (!this.awareness) return;
+		const buf = data instanceof ArrayBuffer ? new Uint8Array(data) : data;
+		applyAwarenessUpdate(this.awareness, buf, this);
+	}
+}

package/src/webrtc/index.ts

@@ -0,0 +1,20 @@
+export { AbracadabraWebRTC } from "./AbracadabraWebRTC.ts";
+export { SignalingSocket } from "./SignalingSocket.ts";
+export { PeerConnection } from "./PeerConnection.ts";
+export { DataChannelRouter } from "./DataChannelRouter.ts";
+export { YjsDataChannel } from "./YjsDataChannel.ts";
+export { FileTransferChannel, FileTransferHandle } from "./FileTransferChannel.ts";
+export type {
+	AbracadabraWebRTCConfiguration,
+	PeerInfo,
+	PeerState,
+	FileTransferMeta,
+	FileTransferStatus,
+	SignalingIncoming,
+	SignalingOutgoing,
+} from "./types.ts";
+export {
+	CHANNEL_NAMES,
+	DEFAULT_ICE_SERVERS,
+	DEFAULT_FILE_CHUNK_SIZE,
+} from "./types.ts";