@abraca/dabra 1.0.2 → 1.0.4

package/src/webrtc/AbracadabraWebRTC.ts

@@ -0,0 +1,540 @@
+import type * as Y from "yjs";
+import type { Awareness } from "y-protocols/awareness";
+import EventEmitter from "../EventEmitter.ts";
+import type { AbracadabraProvider } from "../AbracadabraProvider.ts";
+import { SignalingSocket } from "./SignalingSocket.ts";
+import { PeerConnection } from "./PeerConnection.ts";
+import { YjsDataChannel } from "./YjsDataChannel.ts";
+import { FileTransferChannel, FileTransferHandle } from "./FileTransferChannel.ts";
+import {
+	DEFAULT_ICE_SERVERS,
+	type AbracadabraWebRTCConfiguration,
+	type PeerInfo,
+	type PeerState,
+} from "./types.ts";
+
+const HAS_RTC = typeof globalThis.RTCPeerConnection !== "undefined";
+
+/**
+ * Optional WebRTC provider for peer-to-peer Y.js sync, awareness, and file transfer.
+ *
+ * Uses the server's signaling endpoint (`/ws/:doc_id/signaling`) for connection
+ * negotiation, then establishes direct data channels between peers. Designed to
+ * work alongside `AbracadabraProvider` — the server remains the persistence layer,
+ * while WebRTC provides low-latency P2P sync.
+ *
+ * Falls back to a no-op when `RTCPeerConnection` is unavailable (e.g. Node.js).
+ */
+export class AbracadabraWebRTC extends EventEmitter {
+	private signaling: SignalingSocket | null = null;
+	private peerConnections = new Map<string, PeerConnection>();
+	private yjsChannels = new Map<string, YjsDataChannel>();
+	private fileChannels = new Map<string, FileTransferChannel>();
+
+	private readonly config: {
+		docId: string;
+		url: string;
+		token: string | (() => string) | (() => Promise<string>);
+		document: Y.Doc | null;
+		awareness: Awareness | null;
+		iceServers: RTCIceServer[];
+		displayName: string | null;
+		color: string | null;
+		enableDocSync: boolean;
+		enableAwarenessSync: boolean;
+		enableFileTransfer: boolean;
+		fileChunkSize: number;
+		WebSocketPolyfill: any;
+	};
+
+	public readonly peers = new Map<string, PeerState>();
+	public localPeerId: string | null = null;
+	public isConnected = false;
+
+	constructor(configuration: AbracadabraWebRTCConfiguration) {
+		super();
+
+		const doc = configuration.document ?? null;
+		const awareness = configuration.awareness ?? null;
+
+		this.config = {
+			docId: configuration.docId,
+			url: configuration.url,
+			token: configuration.token,
+			document: doc,
+			awareness,
+			iceServers: configuration.iceServers ?? DEFAULT_ICE_SERVERS,
+			displayName: configuration.displayName ?? null,
+			color: configuration.color ?? null,
+			enableDocSync: configuration.enableDocSync ?? !!doc,
+			enableAwarenessSync: configuration.enableAwarenessSync ?? !!awareness,
+			enableFileTransfer: configuration.enableFileTransfer ?? false,
+			fileChunkSize: configuration.fileChunkSize ?? 16384,
+			WebSocketPolyfill: configuration.WebSocketPolyfill,
+		};
+
+		if (configuration.autoConnect !== false && HAS_RTC) {
+			this.connect();
+		}
+	}
+
+	/**
+	 * Create an AbracadabraWebRTC instance from an existing provider,
+	 * reusing its document, awareness, URL, and token.
+	 */
+	static fromProvider(
+		provider: AbracadabraProvider,
+		options?: Partial<AbracadabraWebRTCConfiguration>,
+	): AbracadabraWebRTC {
+		// Derive the HTTP URL from the provider's WebSocket URL.
+		const config = provider.configuration;
+		const wsUrl =
+			config.websocketProvider?.url ??
+			(config as { url?: string }).url ??
+			"";
+		const httpUrl = wsUrl
+			.replace(/^wss:/, "https:")
+			.replace(/^ws:/, "http:");
+
+		return new AbracadabraWebRTC({
+			docId: config.name,
+			url: httpUrl,
+			token: config.token as string | (() => string) | (() => Promise<string>),
+			document: provider.document,
+			awareness: provider.awareness,
+			...options,
+		});
+	}
+
+	// ── Connection Lifecycle ────────────────────────────────────────────────
+
+	async connect(): Promise<void> {
+		if (!HAS_RTC) return;
+		if (this.isConnected) return;
+
+		const signalingUrl = this.buildSignalingUrl();
+
+		this.signaling = new SignalingSocket({
+			url: signalingUrl,
+			token: this.config.token,
+			autoConnect: false,
+			WebSocketPolyfill: this.config.WebSocketPolyfill,
+		});
+
+		this.signaling.on(
+			"welcome",
+			(data: { peerId: string; peers: PeerInfo[] }) => {
+				this.localPeerId = data.peerId;
+				this.isConnected = true;
+				this.emit("connected");
+
+				// Send profile if configured.
+				if (this.config.displayName && this.config.color) {
+					this.signaling!.sendProfile(
+						this.config.displayName,
+						this.config.color,
+					);
+				}
+
+				// Initiate connections to existing peers.
+				for (const peer of data.peers) {
+					this.addPeer(peer);
+					// Deterministic initiator: lower peer_id sends offer.
+					if (this.localPeerId! < peer.peer_id) {
+						this.initiateConnection(peer.peer_id);
+					}
+				}
+			},
+		);
+
+		this.signaling.on("joined", (peer: PeerInfo) => {
+			this.addPeer(peer);
+			this.emit("peerJoined", peer);
+
+			// Deterministic initiator.
+			if (this.localPeerId! < peer.peer_id) {
+				this.initiateConnection(peer.peer_id);
+			}
+		});
+
+		this.signaling.on("left", ({ peerId }: { peerId: string }) => {
+			this.removePeer(peerId);
+			this.emit("peerLeft", { peerId });
+		});
+
+		this.signaling.on(
+			"offer",
+			async ({ from, sdp }: { from: string; sdp: string }) => {
+				await this.handleOffer(from, sdp);
+			},
+		);
+
+		this.signaling.on(
+			"answer",
+			async ({ from, sdp }: { from: string; sdp: string }) => {
+				const pc = this.peerConnections.get(from);
+				if (pc) {
+					await pc.setRemoteAnswer(sdp);
+				}
+			},
+		);
+
+		this.signaling.on(
+			"ice",
+			async ({
+				from,
+				candidate,
+			}: { from: string; candidate: string }) => {
+				const pc = this.peerConnections.get(from);
+				if (pc) {
+					await pc.addIceCandidate(candidate);
+				}
+			},
+		);
+
+		this.signaling.on(
+			"mute",
+			({ peerId, muted }: { peerId: string; muted: boolean }) => {
+				const peer = this.peers.get(peerId);
+				if (peer) {
+					peer.muted = muted;
+					this.emit("peerMuted", { peerId, muted });
+				}
+			},
+		);
+
+		this.signaling.on(
+			"media-state",
+			({
+				peerId,
+				video,
+				screen,
+			}: { peerId: string; video: boolean; screen: boolean }) => {
+				const peer = this.peers.get(peerId);
+				if (peer) {
+					peer.video = video;
+					peer.screen = screen;
+					this.emit("peerMediaState", { peerId, video, screen });
+				}
+			},
+		);
+
+		this.signaling.on(
+			"profile",
+			({
+				peerId,
+				name,
+				color,
+			}: { peerId: string; name: string; color: string }) => {
+				const peer = this.peers.get(peerId);
+				if (peer) {
+					peer.name = name;
+					peer.color = color;
+					this.emit("peerProfile", { peerId, name, color });
+				}
+			},
+		);
+
+		this.signaling.on("disconnected", () => {
+			this.isConnected = false;
+			this.localPeerId = null;
+			// Clean up all peer connections — signaling will auto-reconnect.
+			this.removeAllPeers();
+			this.emit("disconnected");
+		});
+
+		this.signaling.on(
+			"error",
+			(err: { code: string; message: string }) => {
+				this.emit("signalingError", err);
+			},
+		);
+
+		await this.signaling.connect();
+	}
+
+	disconnect(): void {
+		if (!HAS_RTC) return;
+
+		this.removeAllPeers();
+
+		if (this.signaling) {
+			this.signaling.disconnect();
+			this.signaling = null;
+		}
+
+		this.isConnected = false;
+		this.localPeerId = null;
+	}
+
+	destroy(): void {
+		this.disconnect();
+
+		if (this.signaling) {
+			this.signaling.destroy();
+			this.signaling = null;
+		}
+
+		this.removeAllListeners();
+	}
+
+	// ── Media State ─────────────────────────────────────────────────────────
+
+	setMuted(muted: boolean): void {
+		this.signaling?.sendMute(muted);
+	}
+
+	setMediaState(video: boolean, screen: boolean): void {
+		this.signaling?.sendMediaState(video, screen);
+	}
+
+	setProfile(name: string, color: string): void {
+		this.signaling?.sendProfile(name, color);
+	}
+
+	// ── File Transfer ───────────────────────────────────────────────────────
+
+	/**
+	 * Send a file to a specific peer. Returns a handle for tracking progress.
+	 */
+	async sendFile(
+		peerId: string,
+		file: File | Blob,
+		filename: string,
+	): Promise<FileTransferHandle | null> {
+		const fc = this.fileChannels.get(peerId);
+		if (!fc) return null;
+		return fc.send(file, filename);
+	}
+
+	/**
+	 * Send a file to all connected peers. Returns an array of handles.
+	 */
+	async broadcastFile(
+		file: File | Blob,
+		filename: string,
+	): Promise<FileTransferHandle[]> {
+		const handles: FileTransferHandle[] = [];
+		for (const [peerId, fc] of this.fileChannels) {
+			const handle = await fc.send(file, filename);
+			handles.push(handle);
+		}
+		return handles;
+	}
+
+	// ── Custom Messages ─────────────────────────────────────────────────────
+
+	/**
+	 * Send a custom string message to a specific peer via a data channel.
+	 */
+	sendCustomMessage(peerId: string, payload: string): void {
+		const pc = this.peerConnections.get(peerId);
+		if (!pc) return;
+
+		let channel = pc.router.getChannel("custom");
+		if (!channel || channel.readyState !== "open") {
+			// Create on-demand.
+			channel = pc.router.createChannel("custom", { ordered: true });
+			// Wait for open before sending.
+			channel.onopen = () => {
+				channel!.send(payload);
+			};
+			return;
+		}
+		channel.send(payload);
+	}
+
+	/**
+	 * Send a custom string message to all connected peers.
+	 */
+	broadcastCustomMessage(payload: string): void {
+		for (const peerId of this.peerConnections.keys()) {
+			this.sendCustomMessage(peerId, payload);
+		}
+	}
+
+	// ── Private: Peer Management ────────────────────────────────────────────
+
+	private addPeer(info: PeerInfo): void {
+		this.peers.set(info.peer_id, {
+			...info,
+			connectionState: "new",
+		});
+	}
+
+	private removePeer(peerId: string): void {
+		this.peers.delete(peerId);
+
+		const yjs = this.yjsChannels.get(peerId);
+		if (yjs) {
+			yjs.destroy();
+			this.yjsChannels.delete(peerId);
+		}
+
+		const fc = this.fileChannels.get(peerId);
+		if (fc) {
+			fc.destroy();
+			this.fileChannels.delete(peerId);
+		}
+
+		const pc = this.peerConnections.get(peerId);
+		if (pc) {
+			pc.destroy();
+			this.peerConnections.delete(peerId);
+		}
+	}
+
+	private removeAllPeers(): void {
+		for (const peerId of [...this.peers.keys()]) {
+			this.removePeer(peerId);
+		}
+	}
+
+	// ── Private: Connection Negotiation ─────────────────────────────────────
+
+	private createPeerConnection(peerId: string): PeerConnection {
+		const pc = new PeerConnection(peerId, this.config.iceServers);
+
+		// Forward ICE candidates to signaling.
+		pc.on(
+			"iceCandidate",
+			({ peerId, candidate }: { peerId: string; candidate: string }) => {
+				this.signaling?.sendIce(peerId, candidate);
+			},
+		);
+
+		// Handle ICE failure with restart.
+		pc.on("iceFailed", async ({ peerId }: { peerId: string }) => {
+			try {
+				const sdp = await pc.createOffer(true);
+				this.signaling?.sendOffer(peerId, sdp);
+			} catch {
+				// If ICE restart fails, remove peer.
+				this.removePeer(peerId);
+			}
+		});
+
+		// Track connection state.
+		pc.on(
+			"connectionStateChange",
+			({ peerId, state }: { peerId: string; state: RTCPeerConnectionState }) => {
+				const peer = this.peers.get(peerId);
+				if (peer) {
+					peer.connectionState = state;
+				}
+
+				if (state === "disconnected" || state === "closed") {
+					// Peer connection dropped. Don't remove yet — ICE may recover.
+					// If "failed", the iceFailed handler will attempt restart.
+				}
+
+				this.emit("peerConnectionState", { peerId, state });
+			},
+		);
+
+		// Listen for custom messages on the router.
+		pc.router.on("channelMessage", ({ name, data }: { name: string; data: any }) => {
+			if (name === "custom") {
+				const payload = typeof data === "string" ? data : new TextDecoder().decode(data);
+				this.emit("customMessage", { peerId, payload });
+			}
+		});
+
+		this.peerConnections.set(peerId, pc);
+		this.attachDataHandlers(peerId, pc);
+
+		return pc;
+	}
+
+	private attachDataHandlers(peerId: string, pc: PeerConnection): void {
+		// Attach Y.js sync.
+		if (this.config.document && this.config.enableDocSync) {
+			const yjs = new YjsDataChannel(
+				this.config.document,
+				this.config.enableAwarenessSync ? this.config.awareness : null,
+				pc.router,
+			);
+			yjs.attach();
+			this.yjsChannels.set(peerId, yjs);
+		}
+
+		// Attach file transfer.
+		if (this.config.enableFileTransfer) {
+			const fc = new FileTransferChannel(pc.router, this.config.fileChunkSize);
+
+			fc.on("receiveStart", (meta: any) => {
+				this.emit("fileReceiveStart", { peerId, ...meta });
+			});
+			fc.on("receiveProgress", (data: any) => {
+				this.emit("fileReceiveProgress", { peerId, ...data });
+			});
+			fc.on("receiveComplete", (data: any) => {
+				this.emit("fileReceiveComplete", { peerId, ...data });
+			});
+			fc.on("receiveError", (data: any) => {
+				this.emit("fileReceiveError", { peerId, ...data });
+			});
+			fc.on("receiveCancelled", (data: any) => {
+				this.emit("fileReceiveCancelled", { peerId, ...data });
+			});
+
+			this.fileChannels.set(peerId, fc);
+		}
+	}
+
+	private async initiateConnection(peerId: string): Promise<void> {
+		const pc = this.createPeerConnection(peerId);
+
+		// Create data channels (initiator creates them).
+		pc.router.createDefaultChannels({
+			enableDocSync: this.config.enableDocSync,
+			enableAwareness: this.config.enableAwarenessSync,
+			enableFileTransfer: this.config.enableFileTransfer,
+		});
+
+		try {
+			const sdp = await pc.createOffer();
+			this.signaling?.sendOffer(peerId, sdp);
+		} catch {
+			this.removePeer(peerId);
+		}
+	}
+
+	private async handleOffer(from: string, sdp: string): Promise<void> {
+		// Clean up any existing connection to this peer.
+		const existing = this.peerConnections.get(from);
+		if (existing) {
+			existing.destroy();
+			this.yjsChannels.get(from)?.destroy();
+			this.yjsChannels.delete(from);
+			this.fileChannels.get(from)?.destroy();
+			this.fileChannels.delete(from);
+			this.peerConnections.delete(from);
+		}
+
+		const pc = this.createPeerConnection(from);
+
+		try {
+			const answerSdp = await pc.setRemoteOffer(sdp);
+			this.signaling?.sendAnswer(from, answerSdp);
+		} catch {
+			this.removePeer(from);
+		}
+	}
+
+	// ── Private: URL Building ───────────────────────────────────────────────
+
+	private buildSignalingUrl(): string {
+		let base = this.config.url;
+
+		// Remove trailing slashes.
+		while (base.endsWith("/")) {
+			base = base.slice(0, -1);
+		}
+
+		// Convert http(s) to ws(s).
+		base = base.replace(/^https:/, "wss:").replace(/^http:/, "ws:");
+
+		return `${base}/ws/${encodeURIComponent(this.config.docId)}/signaling`;
+	}
+}

package/src/webrtc/DataChannelRouter.ts

@@ -0,0 +1,110 @@
+import EventEmitter from "../EventEmitter.ts";
+import { CHANNEL_NAMES } from "./types.ts";
+
+export class DataChannelRouter extends EventEmitter {
+	private channels = new Map<string, RTCDataChannel>();
+
+	constructor(private connection: RTCPeerConnection) {
+		super();
+
+		// Accept incoming data channels from the remote peer.
+		this.connection.ondatachannel = (event) => {
+			this.registerChannel(event.channel);
+		};
+	}
+
+	/** Create a named data channel (initiator side). */
+	createChannel(
+		name: string,
+		options?: RTCDataChannelInit,
+	): RTCDataChannel {
+		const channel = this.connection.createDataChannel(name, options);
+		this.registerChannel(channel);
+		return channel;
+	}
+
+	/** Create the standard set of channels for Abracadabra WebRTC. */
+	createDefaultChannels(opts: {
+		enableDocSync: boolean;
+		enableAwareness: boolean;
+		enableFileTransfer: boolean;
+	}): void {
+		if (opts.enableDocSync) {
+			this.createChannel(CHANNEL_NAMES.YJS_SYNC, {
+				ordered: true,
+			});
+		}
+
+		if (opts.enableAwareness) {
+			this.createChannel(CHANNEL_NAMES.AWARENESS, {
+				ordered: false,
+				maxRetransmits: 0,
+			});
+		}
+
+		if (opts.enableFileTransfer) {
+			this.createChannel(CHANNEL_NAMES.FILE_TRANSFER, {
+				ordered: true,
+			});
+		}
+	}
+
+	getChannel(name: string): RTCDataChannel | null {
+		return this.channels.get(name) ?? null;
+	}
+
+	isOpen(name: string): boolean {
+		return this.channels.get(name)?.readyState === "open";
+	}
+
+	private registerChannel(channel: RTCDataChannel): void {
+		channel.binaryType = "arraybuffer";
+		this.channels.set(channel.label, channel);
+
+		channel.onopen = () => {
+			this.emit("channelOpen", { name: channel.label, channel });
+		};
+
+		channel.onclose = () => {
+			this.emit("channelClose", { name: channel.label });
+			this.channels.delete(channel.label);
+		};
+
+		channel.onmessage = (event) => {
+			this.emit("channelMessage", {
+				name: channel.label,
+				data: event.data,
+			});
+		};
+
+		channel.onerror = (event) => {
+			this.emit("channelError", {
+				name: channel.label,
+				error: event,
+			});
+		};
+
+		// If the channel is already open (can happen with ondatachannel),
+		// emit immediately.
+		if (channel.readyState === "open") {
+			this.emit("channelOpen", { name: channel.label, channel });
+		}
+	}
+
+	close(): void {
+		for (const channel of this.channels.values()) {
+			try {
+				channel.close();
+			} catch {
+				// Ignore
+			}
+		}
+		this.channels.clear();
+	}
+
+	destroy(): void {
+		this.close();
+		this.connection.ondatachannel = null;
+		this.removeAllListeners();
+	}
+}