@igoforth/ws-rpc 1.0.0

package/src/adapters/multi-peer.ts

@@ -0,0 +1,404 @@
+/**
+ * Multi-Peer Base Class
+ *
+ * Abstract base class for adapters managing multiple RPC peers.
+ * Extended by RpcServer and Cloudflare DO adapter.
+ */
+
+import { RpcPeer } from "../peers/default.js";
+import type {
+	EventDef,
+	InferEventData,
+	Provider,
+	RpcSchema,
+	StringKeys,
+} from "../schema.js";
+import type { IMinWebSocket } from "../types.js";
+import type {
+	IMultiAdapterHooks,
+	IMultiConnectionAdapter,
+	MultiCallOptions,
+	MultiCallResult,
+	MultiDriver,
+} from "./types.js";
+
+/**
+ * Options for creating a MultiPeerBase subclass
+ */
+export interface MultiPeerOptions<
+	TLocalSchema extends RpcSchema,
+	TRemoteSchema extends RpcSchema,
+> {
+	/** Schema defining local methods we implement */
+	localSchema: TLocalSchema;
+	/** Schema defining remote methods we can call */
+	remoteSchema: TRemoteSchema;
+	/** Implementation of local methods */
+	provider: Provider<TLocalSchema>;
+	/** Default timeout for RPC calls in ms */
+	timeout?: number;
+	/** Lifecycle hooks */
+	hooks?: IMultiAdapterHooks<TLocalSchema, TRemoteSchema>;
+}
+
+/**
+ * Abstract base class for multi-peer adapters
+ *
+ * Provides shared functionality for managing multiple RPC peers:
+ * - Driver for calling methods on multiple peers
+ * - Broadcast emit to all peers
+ * - Peer lookup by ID
+ * - Connection count/IDs
+ *
+ * @typeParam TLocalSchema - Schema for methods/events this side provides
+ * @typeParam TRemoteSchema - Schema for methods/events the remote side provides
+ * @typeParam TConnection - Connection type (IWebSocket, WebSocket, etc.)
+ */
+export abstract class MultiPeerBase<
+	TLocalSchema extends RpcSchema,
+	TRemoteSchema extends RpcSchema,
+	TConnection,
+> implements IMultiConnectionAdapter<TLocalSchema, TRemoteSchema>
+{
+	protected readonly peers = new Map<
+		TConnection,
+		RpcPeer<TLocalSchema, TRemoteSchema>
+	>();
+
+	/** Local schema */
+	public readonly localSchema: TLocalSchema;
+
+	/** Remote schema */
+	public readonly remoteSchema: TRemoteSchema;
+
+	/** Implementation of local methods */
+	public readonly provider: Provider<TLocalSchema>;
+
+	/** Default timeout for RPC calls */
+	public readonly timeout: number;
+
+	/** Lifecycle hooks */
+	public readonly hooks: IMultiAdapterHooks<TLocalSchema, TRemoteSchema>;
+
+	constructor(options: MultiPeerOptions<TLocalSchema, TRemoteSchema>) {
+		this.localSchema = options.localSchema;
+		this.remoteSchema = options.remoteSchema;
+		this.provider = options.provider;
+		this.timeout = options.timeout ?? 30000;
+		this.hooks = options.hooks ?? {};
+	}
+
+	// =========================================================================
+	// Peer Creation
+	// =========================================================================
+
+	/**
+	 * Create an RPC peer for a WebSocket connection.
+	 * Subclasses can override to customize peer creation.
+	 */
+	protected createPeer(
+		ws: IMinWebSocket,
+	): RpcPeer<TLocalSchema, TRemoteSchema> {
+		return new RpcPeer<TLocalSchema, TRemoteSchema>({
+			ws,
+			localSchema: this.localSchema,
+			remoteSchema: this.remoteSchema,
+			provider: this.provider,
+			onEvent: this.hooks.onEvent
+				? (event, data) => {
+						const peer = this.findPeerByWs(ws);
+						if (peer) {
+							(
+								this.hooks.onEvent as (
+									peer: RpcPeer<TLocalSchema, TRemoteSchema>,
+									event: string,
+									data: unknown,
+								) => void
+							)(peer, event, data);
+						}
+					}
+				: undefined,
+			timeout: this.timeout,
+		});
+	}
+
+	/**
+	 * Find peer by WebSocket (internal helper for event routing)
+	 */
+	private findPeerByWs(
+		ws: IMinWebSocket,
+	): RpcPeer<TLocalSchema, TRemoteSchema> | null {
+		for (const peer of this.peers.values()) {
+			if (peer.getWebSocket() === ws) {
+				return peer;
+			}
+		}
+		return null;
+	}
+
+	// =========================================================================
+	// Peer Management
+	// =========================================================================
+
+	/**
+	 * Add a peer (called by subclass when connection established)
+	 */
+	protected addPeer(
+		connection: TConnection,
+		peer: RpcPeer<TLocalSchema, TRemoteSchema>,
+	): void {
+		this.peers.set(connection, peer);
+		this.hooks.onConnect?.(peer);
+	}
+
+	/**
+	 * Remove a peer (called by subclass when connection closes)
+	 */
+	protected removePeer(
+		connection: TConnection,
+	): RpcPeer<TLocalSchema, TRemoteSchema> | null {
+		const peer = this.peers.get(connection);
+		if (peer) {
+			peer.close();
+			this.peers.delete(connection);
+			this.hooks.onDisconnect?.(peer);
+			return peer;
+		}
+		return null;
+	}
+
+	/**
+	 * Get peer by connection object
+	 */
+	public getPeerFor(
+		connection: TConnection,
+	): RpcPeer<TLocalSchema, TRemoteSchema> | null {
+		return this.peers.get(connection) ?? null;
+	}
+
+	/**
+	 * Get peer by ID
+	 */
+	public getPeer(id: string): RpcPeer<TLocalSchema, TRemoteSchema> | null {
+		for (const peer of this.peers.values()) {
+			if (peer.id === id) {
+				return peer;
+			}
+		}
+		return null;
+	}
+
+	/**
+	 * Find peer entry by ID (internal - includes connection)
+	 */
+	protected findPeerEntry(id: string): {
+		peer: RpcPeer<TLocalSchema, TRemoteSchema>;
+		connection: TConnection;
+	} | null {
+		for (const [connection, peer] of this.peers) {
+			if (peer.id === id) {
+				return { peer, connection };
+			}
+		}
+		return null;
+	}
+
+	/**
+	 * Get all peers
+	 */
+	public getPeers(): IterableIterator<RpcPeer<TLocalSchema, TRemoteSchema>> {
+		return this.peers.values();
+	}
+
+	/**
+	 * Get all open peer entries (internal)
+	 */
+	protected getOpenEntries(): Array<{
+		peer: RpcPeer<TLocalSchema, TRemoteSchema>;
+		connection: TConnection;
+	}> {
+		const result: Array<{
+			peer: RpcPeer<TLocalSchema, TRemoteSchema>;
+			connection: TConnection;
+		}> = [];
+		for (const [connection, peer] of this.peers) {
+			if (peer.isOpen) result.push({ peer, connection });
+		}
+		return result;
+	}
+
+	// =========================================================================
+	// IMultiConnectionAdapter Implementation
+	// =========================================================================
+
+	/**
+	 * Get count of open connections
+	 */
+	public getConnectionCount(): number {
+		let count = 0;
+		for (const peer of this.peers.values()) {
+			if (peer.isOpen) count++;
+		}
+		return count;
+	}
+
+	/**
+	 * Get all open peer IDs
+	 */
+	public getConnectionIds(): string[] {
+		const ids: string[] = [];
+		for (const peer of this.peers.values()) {
+			if (peer.isOpen) ids.push(peer.id);
+		}
+		return ids;
+	}
+
+	/**
+	 * Driver for calling remote methods on connected peers
+	 *
+	 * @returns MultiDriver proxy for calling methods on all or specific peers
+	 */
+	public get driver(): MultiDriver<TRemoteSchema> {
+		return this.createMultiDriver();
+	}
+
+	/**
+	 * Emit an event to connected peers
+	 *
+	 * @param event - Event name from local schema
+	 * @param data - Event data matching the schema
+	 * @param ids - Optional array of peer IDs to emit to (broadcasts to all if omitted)
+	 */
+	public emit<K extends StringKeys<TLocalSchema["events"]>>(
+		event: K,
+		data: TLocalSchema["events"] extends Record<string, EventDef>
+			? InferEventData<TLocalSchema["events"][K]>
+			: never,
+		ids?: string[],
+	): void {
+		const validPeers = ids
+			? this.peers.values().filter((p) => ids.includes(p.id) && p.isOpen)
+			: this.peers.values().filter((p) => p.isOpen);
+		for (const peer of validPeers) peer.emit(event, data);
+	}
+
+	/**
+	 * Close a specific peer by ID
+	 *
+	 * @param id - Peer ID to close
+	 * @returns true if peer was found and closed, false otherwise
+	 */
+	public closePeer(id: string): boolean {
+		const entry = this.findPeerEntry(id);
+		if (entry) {
+			entry.peer.close();
+			this.peers.delete(entry.connection);
+			this.hooks.onDisconnect?.(entry.peer);
+			return true;
+		}
+		return false;
+	}
+
+	/**
+	 * Close all peers
+	 */
+	protected closeAll(): void {
+		for (const peer of this.peers.values()) {
+			peer.close();
+			this.hooks.onDisconnect?.(peer);
+		}
+		this.peers.clear();
+		this.hooks.onClose?.();
+	}
+
+	// =========================================================================
+	// Driver Implementation
+	// =========================================================================
+
+	/**
+	 * Create a driver proxy for calling remote methods on multiple peers
+	 */
+	private createMultiDriver(): MultiDriver<TRemoteSchema> {
+		const methods = this.remoteSchema.methods ?? {};
+		const driver: Record<
+			string,
+			(input: unknown, options?: MultiCallOptions) => Promise<unknown>
+		> = {};
+
+		for (const methodName of Object.keys(methods)) {
+			driver[methodName] = async (
+				input: unknown,
+				options?: MultiCallOptions,
+			) => {
+				return this.callMethod(methodName, input, options);
+			};
+		}
+
+		return driver as MultiDriver<TRemoteSchema>;
+	}
+
+	/**
+	 * Call a method on multiple peers with timeout handling
+	 *
+	 * @param method - Method name to call
+	 * @param input - Method input parameters
+	 * @param options - Call options including target peer IDs and timeout
+	 * @returns Array of results from each peer (success or error)
+	 */
+	private async callMethod(
+		method: string,
+		input: unknown,
+		options?: MultiCallOptions,
+	): Promise<Array<MultiCallResult<unknown>>> {
+		const ids = options?.ids;
+		const timeout = options?.timeout ?? this.timeout;
+
+		// Determine which peers to call
+		let targetPeers: Array<RpcPeer<TLocalSchema, TRemoteSchema>>;
+
+		if (ids === undefined) {
+			targetPeers = Array.from(this.peers.values()).filter((p) => p.isOpen);
+		} else if (typeof ids === "string") {
+			const peer = this.getPeer(ids);
+			targetPeers = peer?.isOpen ? [peer] : [];
+		} else {
+			targetPeers = ids
+				.map((id) => this.getPeer(id))
+				.filter(
+					(p): p is RpcPeer<TLocalSchema, TRemoteSchema> => p?.isOpen === true,
+				);
+		}
+
+		const promises = targetPeers.map(async (peer) => {
+			try {
+				const peerDriver = peer.driver as Record<
+					string,
+					(input: unknown) => Promise<unknown>
+				>;
+				const callPromise = peerDriver[method]!(input);
+
+				const value = await Promise.race([
+					callPromise,
+					new Promise<never>((_, reject) =>
+						setTimeout(
+							() => reject(new Error(`Timeout after ${timeout}ms`)),
+							timeout,
+						),
+					),
+				]);
+
+				return { id: peer.id, result: { success: true as const, value } };
+			} catch (error) {
+				return {
+					id: peer.id,
+					result: {
+						success: false as const,
+						error: error instanceof Error ? error : new Error(String(error)),
+					},
+				};
+			}
+		});
+
+		return Promise.all(promises);
+	}
+}

package/src/adapters/server.ts

@@ -0,0 +1,192 @@
+/**
+ * RPC Server Adapter
+ *
+ * Manages RpcPeer instances for incoming WebSocket connections.
+ * Works with Node.js `ws`, Bun's native WebSocket, or any compatible server.
+ */
+
+import { RpcPeer } from "../peers/default.js";
+import type { Provider, RpcSchema } from "../schema.js";
+import {
+	type IRpcOptions,
+	type IWebSocket,
+	type IWebSocketServer,
+	WebSocketReadyState,
+	type WebSocketServerOptions,
+} from "../types.js";
+import { MultiPeerBase } from "./multi-peer.js";
+import type { IMultiAdapterHooks } from "./types.js";
+
+/**
+ * Options for creating an RpcServer
+ */
+export interface RpcServerOptions<
+	TLocalSchema extends RpcSchema,
+	TRemoteSchema extends RpcSchema,
+> extends IRpcOptions<TLocalSchema, TRemoteSchema> {
+	/** Implementation of local methods */
+	provider: Provider<TLocalSchema>;
+	/** WebSocket server instance or options to create one */
+	wss: IWebSocketServer | WebSocketServerOptions;
+	/** WebSocket server constructor (defaults to require('ws').WebSocketServer) */
+	WebSocketServer?: new (
+		options: WebSocketServerOptions,
+	) => IWebSocketServer;
+	/** Lifecycle hooks */
+	hooks?: IMultiAdapterHooks<TLocalSchema, TRemoteSchema>;
+}
+
+/**
+ * RPC Server
+ *
+ * Manages WebSocket server and client connections with RPC capabilities.
+ *
+ * @example
+ * ```typescript
+ * import { WebSocketServer } from "ws";
+ * import { RpcServer } from "@igoforth/ws-rpc/adapters/server";
+ *
+ * const server = new RpcServer({
+ *   wss: { port: 8080 },
+ *   WebSocketServer,
+ *   localSchema: ServerSchema,
+ *   remoteSchema: ClientSchema,
+ *   provider: {
+ *     getUser: async ({ id }) => ({ name: "John", email: "john@example.com" }),
+ *   },
+ *   hooks: {
+ *     onConnect: (peer) => {
+ *       console.log(`Client ${peer.id} connected`);
+ *       peer.driver.ping({}).then(console.log);
+ *     },
+ *     onDisconnect: (peer) => console.log(`Client ${peer.id} disconnected`),
+ *   },
+ * });
+ *
+ * // Emit to all clients
+ * server.emit("orderUpdated", { orderId: "123", status: "shipped" });
+ *
+ * // Graceful shutdown
+ * process.on("SIGTERM", () => server.close());
+ * ```
+ */
+export class RpcServer<
+	TLocalSchema extends RpcSchema,
+	TRemoteSchema extends RpcSchema,
+> extends MultiPeerBase<TLocalSchema, TRemoteSchema, IWebSocket> {
+	private readonly wss: IWebSocketServer;
+
+	constructor(options: RpcServerOptions<TLocalSchema, TRemoteSchema>) {
+		super({
+			localSchema: options.localSchema,
+			remoteSchema: options.remoteSchema,
+			provider: options.provider,
+			...(options.timeout !== undefined && { timeout: options.timeout }),
+			...(options.hooks !== undefined && { hooks: options.hooks }),
+		});
+
+		// Create or use existing WebSocket server
+		if ("on" in options.wss && typeof options.wss.on === "function") {
+			this.wss = options.wss as IWebSocketServer;
+		} else {
+			if (!options.WebSocketServer) {
+				throw new Error(
+					"WebSocketServer constructor required when passing options",
+				);
+			}
+			this.wss = new options.WebSocketServer(
+				options.wss as WebSocketServerOptions,
+			);
+		}
+
+		// Set up server event handlers
+		this.wss.on("connection", (ws) => this.handleConnection(ws));
+		this.wss.on("error", (error) => this.hooks.onError?.(null, error));
+		this.wss.on("close", () => this.hooks.onClose?.());
+	}
+
+	// =========================================================================
+	// Connection Handling
+	// =========================================================================
+
+	private handleConnection(ws: IWebSocket): void {
+		const peer = new RpcPeer({
+			ws,
+			localSchema: this.localSchema,
+			remoteSchema: this.remoteSchema,
+			provider: this.provider,
+			timeout: this.timeout,
+			onEvent: (event, data) => {
+				this.hooks.onEvent?.(peer, event, data);
+			},
+		});
+
+		this.addPeer(ws, peer);
+
+		ws.onmessage = (event) => {
+			if (
+				typeof event === "object" &&
+				event != null &&
+				"data" in event &&
+				(typeof event.data === "string" || event.data instanceof ArrayBuffer)
+			) {
+				peer.handleMessage(event.data as string | ArrayBuffer);
+			}
+		};
+
+		ws.onclose = () => {
+			this.removePeer(ws);
+		};
+
+		ws.onerror = (event) => {
+			const error =
+				event instanceof Error
+					? event
+					: new Error(`WebSocket error for peer ${peer.id}`);
+			this.hooks.onError?.(peer, error);
+		};
+	}
+
+	// =========================================================================
+	// Server-Specific Methods
+	// =========================================================================
+
+	/**
+	 * Close a peer connection with WebSocket close code/reason
+	 *
+	 * @param id - Peer ID to close
+	 * @param code - WebSocket close code (default: 1000)
+	 * @param reason - Close reason message (default: "Server disconnect")
+	 * @returns true if peer was found and closed, false otherwise
+	 */
+	override closePeer(
+		id: string,
+		code = 1000,
+		reason = "Server disconnect",
+	): boolean {
+		const entry = this.findPeerEntry(id);
+		if (entry) {
+			if (entry.connection.readyState !== WebSocketReadyState.CLOSED) {
+				entry.connection.close(code, reason);
+			}
+			return super.closePeer(id);
+		}
+		return false;
+	}
+
+	/**
+	 * Close the server and all client connections
+	 *
+	 * @param callback - Optional callback invoked when server is closed
+	 */
+	close(callback?: (err?: Error) => void): void {
+		for (const entry of this.getOpenEntries()) {
+			if (entry.connection.readyState !== WebSocketReadyState.CLOSED) {
+				entry.connection.close(1001, "Server shutdown");
+			}
+		}
+
+		this.closeAll();
+		this.wss.close(callback);
+	}
+}