@kbve/droid 0.0.6 → 0.1.2

package/src/lib/droid.ts

@@ -1,7 +1,51 @@
-export async function droid(opts?: { workerURLs?: Record<string, string> }): Promise<{ initialized: boolean }> {
+export {
+	downscale,
+	upscale,
+	getScaleLevel,
+	type DroidScaleLevel,
+} from './workers/main.js';
+
+export async function droid(opts?: {
+	workerURLs?: Record<string, string>;
+	workerRefs?: {
+		canvasWorker?: Worker;
+		dbWorker?: SharedWorker;
+		wsWorker?: SharedWorker;
+	};
+	i18nPath?: string;
+	dataPath?: string;
+	/** Maximum time (ms) to wait for worker initialization before rejecting. Default: no timeout. */
+	initTimeout?: number;
+}): Promise<{ initialized: boolean }> {
 	console.log('[DROID]: droid<T>');
+
 	const { main } = await import('./workers/main.js');
-	await main({ workerURLs: opts?.workerURLs });
-	console.log('[DROID]: droid<T> => await WorkerURLs');
+
+	const initPromise = main({
+		workerURLs: opts?.workerURLs,
+		workerRefs: opts?.workerRefs,
+		i18nPath: opts?.i18nPath,
+		dataPath: opts?.dataPath,
+	});
+
+	if (opts?.initTimeout && opts.initTimeout > 0) {
+		const timeout = new Promise<never>((_, reject) =>
+			setTimeout(
+				() =>
+					reject(
+						new Error(
+							`[DROID] Worker init timed out after ${opts.initTimeout}ms`,
+						),
+					),
+				opts.initTimeout,
+			),
+		);
+		await Promise.race([initPromise, timeout]);
+	} else {
+		await initPromise;
+	}
+
+	console.log('[DROID]: droid<T> => await WorkerRefs + URLs');
+
 	return { initialized: true };
-}
+}

package/src/lib/gateway/SupabaseGateway.ts

@@ -0,0 +1,236 @@
+// Unified gateway for Supabase operations with automatic strategy selection
+
+import type {
+	ISupabaseStrategy,
+	SelectOptions,
+	SessionResponse,
+	WebSocketStatus,
+	StrategyType,
+	GatewayConfig,
+} from './types';
+import {
+	detectCapabilities,
+	selectStrategy,
+	logCapabilities,
+	getStrategyDescription,
+} from './capabilities';
+import { SharedWorkerStrategy } from './strategies/SharedWorkerStrategy';
+import { WebWorkerStrategy } from './strategies/WebWorkerStrategy';
+import { DirectStrategy } from './strategies/DirectStrategy';
+import { getWorkerCommunication } from './WorkerCommunication';
+import { DroidEvents } from '../workers/events';
+
+// Vite ?worker&url imports — bundles workers as JS and returns their URL
+import defaultSharedWorkerUrl from '../workers/supabase-shared-worker?worker&url';
+import defaultDbWorkerUrl from '../workers/supabase-db-worker?worker&url';
+
+/**
+ * SupabaseGateway: Unified interface for all Supabase operations
+ *
+ * Automatically selects the best strategy based on browser capabilities:
+ * 1. SharedWorker + DB Worker Pool (desktop: Chrome, Firefox, Edge)
+ * 2. WebSocket Worker + DB Worker Pool (Android, Safari)
+ * 3. Direct/Main thread (fallback)
+ *
+ * All strategies implement the same interface, so application code is unchanged.
+ */
+export class SupabaseGateway implements ISupabaseStrategy {
+	private strategy: ISupabaseStrategy;
+	private strategyType: StrategyType;
+
+	constructor(config: GatewayConfig = {}) {
+		const capabilities = detectCapabilities();
+		logCapabilities(capabilities);
+
+		this.strategyType =
+			config.forceStrategy || selectStrategy(capabilities);
+		console.log(
+			`[SupabaseGateway] Selected strategy: ${getStrategyDescription(this.strategyType)}`,
+		);
+
+		const poolSize = config.poolSize ?? 3;
+		const workerUrls = config.workerUrls ?? {};
+
+		switch (this.strategyType) {
+			case 'shared-worker': {
+				const sharedUrl =
+					workerUrls.sharedWorker ?? defaultSharedWorkerUrl;
+				const dbUrl = workerUrls.dbWorker ?? defaultDbWorkerUrl;
+				this.strategy = new SharedWorkerStrategy(
+					sharedUrl,
+					dbUrl,
+					poolSize,
+				);
+				break;
+			}
+			case 'web-worker': {
+				const wsUrl =
+					workerUrls.webSocketWorker ?? defaultSharedWorkerUrl;
+				const dbUrl = workerUrls.dbWorker ?? defaultDbWorkerUrl;
+				this.strategy = new WebWorkerStrategy(wsUrl, dbUrl, poolSize);
+				break;
+			}
+			case 'direct':
+				this.strategy = new DirectStrategy();
+				break;
+		}
+
+		// Forward worker-error events from BroadcastChannel to DroidEvents
+		if (typeof window !== 'undefined') {
+			const comm = getWorkerCommunication();
+			comm.on('worker-error', (payload) => {
+				DroidEvents.emit(
+					'worker-error',
+					payload as {
+						timestamp: number;
+						worker: 'shared' | 'db' | 'ws';
+						operation: string;
+						message: string;
+					},
+				);
+			});
+		}
+	}
+
+	getStrategyType(): StrategyType {
+		return this.strategyType;
+	}
+
+	getStrategyDescription(): string {
+		return getStrategyDescription(this.strategyType);
+	}
+
+	// Delegate all methods to the selected strategy
+
+	async init(
+		url: string,
+		anonKey: string,
+		options?: Record<string, unknown>,
+	): Promise<SessionResponse> {
+		if (this.strategyType === 'direct') {
+			return this.strategy.init(url, anonKey, options);
+		}
+
+		const WORKER_INIT_FALLBACK_MS = 3500;
+		const primary = this.strategy.init(url, anonKey, options);
+
+		let timer: ReturnType<typeof setTimeout> | null = null;
+		const fallback = new Promise<never>((_, reject) => {
+			timer = setTimeout(
+				() => reject(new Error('worker init stalled')),
+				WORKER_INIT_FALLBACK_MS,
+			);
+		});
+
+		try {
+			const result = await Promise.race([primary, fallback]);
+			if (timer) clearTimeout(timer);
+			return result;
+		} catch (err) {
+			if (timer) clearTimeout(timer);
+			const previousType = this.strategyType;
+			console.warn(
+				`[SupabaseGateway] ${previousType} init did not respond in ${WORKER_INIT_FALLBACK_MS}ms — switching to direct strategy.`,
+				err,
+			);
+			this.strategy = new DirectStrategy();
+			this.strategyType = 'direct';
+			DroidEvents.emit('gateway-strategy-fallback', {
+				timestamp: Date.now(),
+				from: previousType,
+				to: 'direct',
+				reason: err instanceof Error ? err.message : String(err),
+			});
+			return this.strategy.init(url, anonKey, options);
+		}
+	}
+
+	on(event: string, callback: (payload: unknown) => void): () => void {
+		return this.strategy.on(event, callback);
+	}
+
+	getSession(): Promise<SessionResponse> {
+		return this.strategy.getSession();
+	}
+
+	signInWithPassword(
+		email: string,
+		password: string,
+	): Promise<SessionResponse> {
+		return this.strategy.signInWithPassword(email, password);
+	}
+
+	signOut(): Promise<void> {
+		return this.strategy.signOut();
+	}
+
+	select(table: string, opts?: SelectOptions): Promise<unknown[]> {
+		return this.strategy.select(table, opts);
+	}
+
+	insert(
+		table: string,
+		data: Record<string, unknown> | Record<string, unknown>[],
+	): Promise<unknown[]> {
+		return this.strategy.insert(table, data);
+	}
+
+	update(
+		table: string,
+		data: Record<string, unknown>,
+		match: Record<string, unknown>,
+	): Promise<unknown[]> {
+		return this.strategy.update(table, data, match);
+	}
+
+	upsert(
+		table: string,
+		data: Record<string, unknown> | Record<string, unknown>[],
+	): Promise<unknown[]> {
+		return this.strategy.upsert(table, data);
+	}
+
+	delete(table: string, match: Record<string, unknown>): Promise<unknown[]> {
+		return this.strategy.delete(table, match);
+	}
+
+	rpc(fn: string, args?: Record<string, unknown>): Promise<unknown> {
+		return this.strategy.rpc(fn, args);
+	}
+
+	subscribePostgres(
+		key: string,
+		params: Record<string, unknown>,
+		callback: (payload: unknown) => void,
+	): () => void {
+		return this.strategy.subscribePostgres(key, params, callback);
+	}
+
+	connectWebSocket(wsUrl?: string): Promise<WebSocketStatus> {
+		return this.strategy.connectWebSocket(wsUrl);
+	}
+
+	disconnectWebSocket(): Promise<void> {
+		return this.strategy.disconnectWebSocket();
+	}
+
+	sendWebSocketMessage(data: unknown): Promise<void> {
+		return this.strategy.sendWebSocketMessage(data);
+	}
+
+	getWebSocketStatus(): Promise<WebSocketStatus> {
+		return this.strategy.getWebSocketStatus();
+	}
+
+	onWebSocketMessage(callback: (message: unknown) => void): () => void {
+		return this.strategy.onWebSocketMessage(callback);
+	}
+
+	onWebSocketStatus(callback: (status: WebSocketStatus) => void): () => void {
+		return this.strategy.onWebSocketStatus(callback);
+	}
+
+	terminate() {
+		this.strategy.terminate();
+	}
+}

package/src/lib/gateway/WorkerCommunication.ts

@@ -0,0 +1,132 @@
+// Unified communication layer for all workers (SharedWorker, WebWorker, main thread)
+// Uses BroadcastChannel for real-time events
+
+import type { BroadcastEvent } from './types';
+
+/**
+ * WorkerCommunication: Unified communication layer for workers
+ *
+ * Features:
+ * - BroadcastChannel for real-time events
+ * - Works in SharedWorker, WebWorker, and main thread
+ *
+ * Note: This layer does NOT open IndexedDB. The SharedWorker is the single
+ * writer to the auth database (sb-auth-v2). All other contexts receive
+ * auth state via BroadcastChannel or postMessage.
+ */
+export class WorkerCommunication {
+	private bc: BroadcastChannel | null = null;
+	private listeners = new Map<string, Set<(payload: unknown) => void>>();
+	private channelName: string;
+
+	constructor(channelName = 'supabase_events') {
+		this.channelName = channelName;
+		this.initBroadcastChannel();
+	}
+
+	private initBroadcastChannel() {
+		try {
+			if (typeof BroadcastChannel !== 'undefined') {
+				this.bc = new BroadcastChannel(this.channelName);
+				this.bc.onmessage = (e: MessageEvent) =>
+					this.handleBroadcast(e.data);
+			}
+		} catch (err) {
+			console.error(
+				'[WorkerCommunication] Failed to initialize BroadcastChannel:',
+				err,
+			);
+		}
+	}
+
+	/**
+	 * Broadcast an event to all workers and tabs
+	 */
+	broadcast(event: BroadcastEvent) {
+		if (this.bc) {
+			try {
+				this.bc.postMessage(event);
+			} catch (err) {
+				console.error('[WorkerCommunication] Broadcast failed:', err);
+			}
+		}
+	}
+
+	private handleBroadcast(event: BroadcastEvent) {
+		const { type, key } = event;
+
+		if (type === 'realtime' && key) {
+			this.emit(`realtime:${key}`, event.payload);
+		} else {
+			this.emit(type, event.data ?? event);
+		}
+	}
+
+	/**
+	 * Subscribe to events (local and broadcast)
+	 */
+	on(event: string, callback: (payload: unknown) => void): () => void {
+		if (!this.listeners.has(event)) {
+			this.listeners.set(event, new Set());
+		}
+		this.listeners.get(event)?.add(callback);
+
+		return () => {
+			const set = this.listeners.get(event);
+			if (set) {
+				set.delete(callback);
+				if (set.size === 0) {
+					this.listeners.delete(event);
+				}
+			}
+		};
+	}
+
+	private emit(event: string, payload: unknown) {
+		const listeners = this.listeners.get(event);
+		if (listeners) {
+			listeners.forEach((cb) => {
+				try {
+					cb(payload);
+				} catch (err) {
+					console.error(
+						`[WorkerCommunication] Listener error for ${event}:`,
+						err,
+					);
+				}
+			});
+		}
+	}
+
+	/**
+	 * Check if BroadcastChannel is available
+	 */
+	hasBroadcastChannel(): boolean {
+		return this.bc !== null;
+	}
+
+	/**
+	 * Close connections
+	 */
+	close() {
+		if (this.bc) {
+			this.bc.close();
+			this.bc = null;
+		}
+		this.listeners.clear();
+	}
+}
+
+/**
+ * Create a singleton instance for use across workers
+ */
+let _instance: WorkerCommunication | null = null;
+
+export function getWorkerCommunication(
+	channelName?: string,
+): WorkerCommunication {
+	if (!_instance) {
+		_instance = new WorkerCommunication(channelName);
+	}
+	return _instance;
+}

package/src/lib/gateway/WorkerPool.ts

@@ -0,0 +1,304 @@
+// Worker pool manager with round-robin routing for DB operations
+
+import type { WorkerMessage, WorkerResponse } from './types';
+
+export interface WorkerPoolConfig {
+	size: number;
+	workerUrl: string | URL;
+}
+
+/**
+ * WorkerPool: Manages a pool of workers with round-robin load balancing
+ *
+ * Features:
+ * - Fixed-size pool (default: 3 workers)
+ * - Round-robin routing for database operations
+ * - Request/response tracking with UUIDs
+ * - Automatic error handling with exponential backoff retries
+ */
+export class WorkerPool {
+	private workers: Worker[] = [];
+	private poolSize: number;
+	private roundRobinIndex = 0;
+	private pending = new Map<
+		string,
+		{
+			resolve: (value: unknown) => void;
+			reject: (reason?: unknown) => void;
+			workerId: number;
+		}
+	>();
+	private workerUrl: string | URL;
+	private workerRetryCount = new Map<number, number>();
+	private workerRetryTimers = new Map<
+		number,
+		ReturnType<typeof setTimeout>
+	>();
+
+	private readonly MAX_RETRY_ATTEMPTS = 3;
+	private readonly BASE_RETRY_DELAY_MS = 1000;
+	private readonly MAX_RETRY_DELAY_MS = 8000;
+	private readonly REQUEST_TIMEOUT_MS = 30000;
+
+	constructor(config: WorkerPoolConfig) {
+		this.poolSize = config.size;
+		this.workerUrl = config.workerUrl;
+	}
+
+	/**
+	 * Initialize the worker pool
+	 */
+	async init(): Promise<void> {
+		console.log(
+			`[WorkerPool] Initializing pool with ${this.poolSize} workers`,
+		);
+
+		for (let i = 0; i < this.poolSize; i++) {
+			try {
+				const worker = new Worker(this.workerUrl, {
+					type: 'module',
+					name: `db-worker-${i}`,
+				});
+
+				worker.onmessage = (e: MessageEvent) =>
+					this.handleMessage(e.data, i);
+				worker.onerror = (err) => this.handleError(err, i);
+
+				this.workers.push(worker);
+				console.log(`[WorkerPool] Worker ${i} initialized`);
+			} catch (err) {
+				console.error(
+					`[WorkerPool] Failed to create worker ${i}:`,
+					err,
+				);
+				throw err;
+			}
+		}
+
+		// Wait for all workers to be ready
+		await Promise.all(
+			this.workers.map((_worker, i) =>
+				this.sendToWorker(i, {
+					id: crypto.randomUUID(),
+					type: 'ping',
+					payload: {},
+				}),
+			),
+		);
+
+		console.log('[WorkerPool] All workers ready');
+	}
+
+	private getNextWorker(): number {
+		const workerId = this.roundRobinIndex;
+		this.roundRobinIndex = (this.roundRobinIndex + 1) % this.poolSize;
+		return workerId;
+	}
+
+	private sendToWorker<T>(
+		workerId: number,
+		message: WorkerMessage,
+	): Promise<T> {
+		return new Promise<T>((resolve, reject) => {
+			const worker = this.workers[workerId];
+			if (!worker) {
+				return reject(new Error(`Worker ${workerId} not available`));
+			}
+
+			const timer = setTimeout(() => {
+				if (this.pending.has(message.id)) {
+					this.pending.delete(message.id);
+					reject(
+						new Error(
+							`Worker ${workerId} request ${message.type} timed out after ${this.REQUEST_TIMEOUT_MS}ms`,
+						),
+					);
+				}
+			}, this.REQUEST_TIMEOUT_MS);
+
+			this.pending.set(message.id, {
+				resolve: (value: unknown) => {
+					clearTimeout(timer);
+					resolve(value as T);
+				},
+				reject: (err: unknown) => {
+					clearTimeout(timer);
+					reject(err);
+				},
+				workerId,
+			});
+
+			try {
+				worker.postMessage(message);
+			} catch (err) {
+				clearTimeout(timer);
+				this.pending.delete(message.id);
+				reject(err);
+			}
+		});
+	}
+
+	/**
+	 * Send message to next available worker (round-robin)
+	 */
+	send<T>(type: string, payload?: unknown): Promise<T> {
+		const workerId = this.getNextWorker();
+		const id = crypto.randomUUID();
+		const message: WorkerMessage = { id, type, payload };
+
+		return this.sendToWorker<T>(workerId, message);
+	}
+
+	private handleMessage(response: WorkerResponse, workerId: number) {
+		const { id, ok, data, error } = response;
+
+		if (!id) {
+			console.warn(
+				`[WorkerPool] Worker ${workerId} sent message without ID:`,
+				response,
+			);
+			return;
+		}
+
+		const pending = this.pending.get(id);
+		if (!pending) {
+			console.warn(
+				`[WorkerPool] Received response for unknown request ${id}`,
+			);
+			return;
+		}
+
+		this.pending.delete(id);
+
+		if (ok) {
+			pending.resolve(data);
+		} else {
+			pending.reject(new Error(error || 'Worker request failed'));
+		}
+	}
+
+	private handleError(error: ErrorEvent, workerId: number) {
+		console.error(`[WorkerPool] Worker ${workerId} error:`, error);
+
+		const failedRequests: string[] = [];
+		for (const [id, pending] of this.pending.entries()) {
+			if (pending.workerId === workerId) {
+				pending.reject(
+					new Error(`Worker ${workerId} crashed: ${error.message}`),
+				);
+				failedRequests.push(id);
+			}
+		}
+
+		failedRequests.forEach((id) => this.pending.delete(id));
+
+		this.scheduleWorkerRecreation(workerId);
+	}
+
+	private scheduleWorkerRecreation(workerId: number) {
+		const retryCount = this.workerRetryCount.get(workerId) || 0;
+
+		if (retryCount >= this.MAX_RETRY_ATTEMPTS) {
+			console.error(
+				`[WorkerPool] Worker ${workerId} has failed ${retryCount} times. Giving up.`,
+			);
+			this.workerRetryCount.delete(workerId);
+			return;
+		}
+
+		const delay = Math.min(
+			this.BASE_RETRY_DELAY_MS * Math.pow(2, retryCount),
+			this.MAX_RETRY_DELAY_MS,
+		);
+
+		console.log(
+			`[WorkerPool] Scheduling worker ${workerId} recreation in ${delay}ms (attempt ${retryCount + 1}/${this.MAX_RETRY_ATTEMPTS})`,
+		);
+
+		const existingTimer = this.workerRetryTimers.get(workerId);
+		if (existingTimer) {
+			clearTimeout(existingTimer);
+		}
+
+		const timer = setTimeout(() => {
+			this.workerRetryTimers.delete(workerId);
+			this.recreateWorker(workerId);
+		}, delay);
+
+		this.workerRetryTimers.set(workerId, timer);
+		this.workerRetryCount.set(workerId, retryCount + 1);
+	}
+
+	private async recreateWorker(workerId: number) {
+		const retryCount = this.workerRetryCount.get(workerId) || 0;
+		console.log(
+			`[WorkerPool] Attempting to recreate worker ${workerId} (attempt ${retryCount}/${this.MAX_RETRY_ATTEMPTS})`,
+		);
+
+		try {
+			const worker = new Worker(this.workerUrl, {
+				type: 'module',
+				name: `db-worker-${workerId}`,
+			});
+
+			worker.onmessage = (e: MessageEvent) =>
+				this.handleMessage(e.data, workerId);
+			worker.onerror = (err) => this.handleError(err, workerId);
+
+			this.workers[workerId] = worker;
+
+			await this.sendToWorker(workerId, {
+				id: crypto.randomUUID(),
+				type: 'ping',
+				payload: {},
+			});
+
+			console.log(
+				`[WorkerPool] Worker ${workerId} recreated successfully`,
+			);
+			this.workerRetryCount.delete(workerId);
+		} catch (err) {
+			console.error(
+				`[WorkerPool] Failed to recreate worker ${workerId}:`,
+				err,
+			);
+		}
+	}
+
+	/**
+	 * Terminate all workers
+	 */
+	terminate() {
+		console.log('[WorkerPool] Terminating all workers');
+
+		this.workerRetryTimers.forEach((timer) => clearTimeout(timer));
+		this.workerRetryTimers.clear();
+		this.workerRetryCount.clear();
+
+		this.workers.forEach((worker, i) => {
+			try {
+				worker.terminate();
+			} catch (err) {
+				console.error(
+					`[WorkerPool] Error terminating worker ${i}:`,
+					err,
+				);
+			}
+		});
+
+		this.workers = [];
+		this.pending.clear();
+	}
+
+	/**
+	 * Get pool statistics
+	 */
+	getStats() {
+		return {
+			size: this.poolSize,
+			activeWorkers: this.workers.length,
+			pendingRequests: this.pending.size,
+			nextWorker: this.roundRobinIndex,
+		};
+	}
+}