@roj-ai/transport 0.0.2

package/src/platform/types.ts

@@ -0,0 +1,102 @@
+/**
+ * Platform Abstraction Types
+ *
+ * Common interfaces for WebSocket implementations across platforms (browser + Bun).
+ */
+
+/**
+ * WebSocket ready state values.
+ */
+export const WebSocketReadyState = {
+	CONNECTING: 0,
+	OPEN: 1,
+	CLOSING: 2,
+	CLOSED: 3,
+} as const
+
+export type WebSocketReadyState = (typeof WebSocketReadyState)[keyof typeof WebSocketReadyState]
+
+/**
+ * Close event structure.
+ */
+export interface ICloseEvent {
+	code: number
+	reason: string
+}
+
+/**
+ * Platform-agnostic WebSocket interface.
+ */
+export interface IWebSocket {
+	/** Current ready state */
+	readonly readyState: WebSocketReadyState
+
+	/** Send a text message */
+	send(data: string): void
+
+	/** Close the connection */
+	close(code?: number, reason?: string): void
+
+	/** Called when connection opens */
+	onopen: (() => void) | null
+
+	/** Called when connection closes */
+	onclose: ((event: ICloseEvent) => void) | null
+
+	/** Called on error */
+	onerror: ((error: Error) => void) | null
+
+	/** Called when a message is received */
+	onmessage: ((data: string) => void) | null
+}
+
+/**
+ * Factory for creating WebSocket client connections.
+ */
+export interface IWebSocketFactory {
+	/** Create a new WebSocket connection to the given URL */
+	create(url: string): IWebSocket
+}
+
+/**
+ * Server-side WebSocket interface (for handling incoming connections).
+ * Extended from IWebSocket with server-specific capabilities.
+ */
+export interface IServerWebSocket<T = unknown> extends IWebSocket {
+	/** Attached data for this connection */
+	data: T
+
+	/** Subscribe to a topic for pub/sub messaging */
+	subscribe(topic: string): void
+
+	/** Unsubscribe from a topic */
+	unsubscribe(topic: string): void
+
+	/** Publish to a topic (message sent to all subscribers except sender) */
+	publish(topic: string, message: string): void
+
+	/** Check if subscribed to a topic */
+	isSubscribed(topic: string): boolean
+}
+
+/**
+ * WebSocket server upgrade request data.
+ */
+export interface IUpgradeData<T = unknown> {
+	/** Data to attach to the WebSocket connection */
+	data: T
+}
+
+/**
+ * WebSocket server interface for handling multiple connections.
+ */
+export interface IWebSocketServer<T = unknown> {
+	/** Handle WebSocket upgrade from HTTP request */
+	upgrade(request: Request, data: T): boolean
+
+	/** Publish to all connections subscribed to a topic */
+	publish(topic: string, message: string): void
+
+	/** Get all active connections */
+	getConnections(): Iterable<IServerWebSocket<T>>
+}

package/src/server/connection-manager.ts

@@ -0,0 +1,298 @@
+/**
+ * Connection Manager
+ *
+ * Manages multiple WebSocket connections and session subscriptions.
+ */
+
+import type { ProtocolDef } from '../core/protocol.js'
+import type { ServerConnection } from './server-connection.js'
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/**
+ * Connection statistics.
+ */
+export interface ConnectionStats {
+	/** Total number of connections */
+	totalConnections: number
+	/** Number of active (connected) connections */
+	activeConnections: number
+	/** Number of unique sessions with subscribers */
+	activeSessions: number
+	/** Connections by client type */
+	byClientType: Record<string, number>
+}
+
+// ============================================================================
+// Connection Manager
+// ============================================================================
+
+/**
+ * Manages multiple server connections and session subscriptions.
+ *
+ * Features:
+ * - Track all active connections
+ * - Manage session subscriptions
+ * - Broadcast to subscribed connections
+ * - Connection statistics
+ */
+export class ConnectionManager<
+	TReceive extends ProtocolDef = ProtocolDef,
+	TSend extends ProtocolDef = ProtocolDef,
+> {
+	private connections = new Map<string, ServerConnection<TReceive, TSend>>()
+	private sessionSubscriptions = new Map<string, Set<string>>() // sessionId -> connectionIds
+
+	// ============================================================================
+	// Connection Management
+	// ============================================================================
+
+	/**
+	 * Add a connection.
+	 */
+	add(connection: ServerConnection<TReceive, TSend>): void {
+		this.connections.set(connection.getConnectionId(), connection)
+	}
+
+	/**
+	 * Remove a connection.
+	 */
+	remove(connectionId: string): void {
+		const connection = this.connections.get(connectionId)
+		if (!connection) return
+
+		// Clean up subscriptions
+		for (const sessionId of connection.getSubscribedSessions()) {
+			this.unsubscribeInternal(connectionId, sessionId)
+		}
+
+		this.connections.delete(connectionId)
+	}
+
+	/**
+	 * Get a connection by ID.
+	 */
+	get(connectionId: string): ServerConnection<TReceive, TSend> | undefined {
+		return this.connections.get(connectionId)
+	}
+
+	/**
+	 * Check if a connection exists.
+	 */
+	has(connectionId: string): boolean {
+		return this.connections.has(connectionId)
+	}
+
+	/**
+	 * Get all connections.
+	 */
+	getAll(): Iterable<ServerConnection<TReceive, TSend>> {
+		return this.connections.values()
+	}
+
+	/**
+	 * Get all connection IDs.
+	 */
+	getAllIds(): Iterable<string> {
+		return this.connections.keys()
+	}
+
+	/**
+	 * Get connection count.
+	 */
+	get size(): number {
+		return this.connections.size
+	}
+
+	// ============================================================================
+	// Session Subscriptions
+	// ============================================================================
+
+	/**
+	 * Subscribe a connection to a session.
+	 */
+	subscribe(connectionId: string, sessionId: string): boolean {
+		const connection = this.connections.get(connectionId)
+		if (!connection) return false
+
+		connection.subscribe(sessionId)
+
+		let subscribers = this.sessionSubscriptions.get(sessionId)
+		if (!subscribers) {
+			subscribers = new Set()
+			this.sessionSubscriptions.set(sessionId, subscribers)
+		}
+		subscribers.add(connectionId)
+
+		return true
+	}
+
+	/**
+	 * Unsubscribe a connection from a session.
+	 */
+	unsubscribe(connectionId: string, sessionId: string): boolean {
+		const connection = this.connections.get(connectionId)
+		if (!connection) return false
+
+		connection.unsubscribe(sessionId)
+		this.unsubscribeInternal(connectionId, sessionId)
+
+		return true
+	}
+
+	/**
+	 * Get all subscribers for a session.
+	 */
+	getSubscribers(sessionId: string): ServerConnection<TReceive, TSend>[] {
+		const subscriberIds = this.sessionSubscriptions.get(sessionId)
+		if (!subscriberIds) return []
+
+		const subscribers: ServerConnection<TReceive, TSend>[] = []
+		const deadIds: string[] = []
+		for (const connectionId of subscriberIds) {
+			const connection = this.connections.get(connectionId)
+			if (connection?.isConnected()) {
+				subscribers.push(connection)
+			} else {
+				deadIds.push(connectionId)
+			}
+		}
+
+		// Clean up dead subscriptions
+		for (const id of deadIds) {
+			subscriberIds.delete(id)
+		}
+		if (subscriberIds.size === 0) {
+			this.sessionSubscriptions.delete(sessionId)
+		}
+
+		return subscribers
+	}
+
+	/**
+	 * Get subscriber count for a session.
+	 */
+	getSubscriberCount(sessionId: string): number {
+		return this.sessionSubscriptions.get(sessionId)?.size ?? 0
+	}
+
+	/**
+	 * Check if a session has any subscribers.
+	 */
+	hasSubscribers(sessionId: string): boolean {
+		return this.getSubscriberCount(sessionId) > 0
+	}
+
+	// ============================================================================
+	// Broadcasting
+	// ============================================================================
+
+	/**
+	 * Broadcast a raw message to all subscribers of a session.
+	 */
+	broadcast(sessionId: string, message: string): number {
+		const subscribers = this.getSubscribers(sessionId)
+		let sent = 0
+
+		for (const connection of subscribers) {
+			if (connection.send(message)) {
+				sent++
+			}
+		}
+
+		return sent
+	}
+
+	/**
+	 * Broadcast to all connections.
+	 */
+	broadcastToAll(message: string): number {
+		let sent = 0
+
+		for (const connection of this.connections.values()) {
+			if (connection.isConnected() && connection.send(message)) {
+				sent++
+			}
+		}
+
+		return sent
+	}
+
+	// ============================================================================
+	// Statistics
+	// ============================================================================
+
+	/**
+	 * Get connection statistics.
+	 */
+	getStats(): ConnectionStats {
+		const byClientType: Record<string, number> = {}
+		let activeConnections = 0
+
+		for (const connection of this.connections.values()) {
+			const clientType = connection.getClientType()
+			byClientType[clientType] = (byClientType[clientType] ?? 0) + 1
+
+			if (connection.isConnected()) {
+				activeConnections++
+			}
+		}
+
+		return {
+			totalConnections: this.connections.size,
+			activeConnections,
+			activeSessions: this.sessionSubscriptions.size,
+			byClientType,
+		}
+	}
+
+	// ============================================================================
+	// Cleanup
+	// ============================================================================
+
+	/**
+	 * Clear all connections.
+	 */
+	clear(): void {
+		for (const connection of this.connections.values()) {
+			connection.disconnect()
+		}
+		this.connections.clear()
+		this.sessionSubscriptions.clear()
+	}
+
+	/**
+	 * Remove disconnected connections.
+	 */
+	cleanup(): number {
+		let removed = 0
+
+		for (const [connectionId, connection] of this.connections) {
+			if (!connection.isConnected()) {
+				this.remove(connectionId)
+				removed++
+			}
+		}
+
+		return removed
+	}
+
+	// ============================================================================
+	// Private Methods
+	// ============================================================================
+
+	/**
+	 * Internal unsubscribe (updates subscription map only).
+	 */
+	private unsubscribeInternal(connectionId: string, sessionId: string): void {
+		const subscribers = this.sessionSubscriptions.get(sessionId)
+		if (subscribers) {
+			subscribers.delete(connectionId)
+			if (subscribers.size === 0) {
+				this.sessionSubscriptions.delete(sessionId)
+			}
+		}
+	}
+}

package/src/server/index.ts

@@ -0,0 +1,26 @@
+/**
+ * Server Connection Module
+ *
+ * WebSocket server for handling incoming client connections.
+ */
+
+export { createServerConnection, ServerConnection } from './server-connection.js'
+export type { ServerConnectionConfig, ServerHandlerContext } from './server-connection.js'
+
+export { ConnectionManager } from './connection-manager.js'
+export type { ConnectionStats } from './connection-manager.js'
+
+// Re-export core types commonly used with server
+export type {
+	ConnectionState,
+	HandlerContext,
+	Protocol,
+	ProtocolCaller,
+	ProtocolDef,
+	ProtocolHandlers,
+	ProtocolNotifier,
+	TransportEvent,
+	TransportEventListener,
+} from '../core/index.js'
+
+export { defineProtocol, method, notification } from '../core/index.js'

package/src/server/server-connection.ts

@@ -0,0 +1,122 @@
+/**
+ * Server Connection
+ *
+ * Represents a single client connection on the server side.
+ * Simplified: no handshake - connection is ready immediately when attached.
+ */
+
+import { Connection } from '../core/connection.js'
+import type { ConnectionConfig } from '../core/connection.js'
+import type { HandlerContext, ProtocolDef } from '../core/protocol.js'
+import type { IServerWebSocket } from '../platform/types.js'
+import { WebSocketReadyState } from '../platform/types.js'
+
+/**
+ * Server connection configuration.
+ */
+export interface ServerConnectionConfig<TReceive extends ProtocolDef, TSend extends ProtocolDef> extends ConnectionConfig<TReceive, TSend> {
+	connectionId?: string
+}
+
+/**
+ * Extended handler context for server connections.
+ */
+export interface ServerHandlerContext extends HandlerContext {
+	clientType?: string
+	subscribedSessions: Set<string>
+}
+
+/**
+ * Server-side WebSocket connection representing a single client.
+ */
+export class ServerConnection<TReceive extends ProtocolDef, TSend extends ProtocolDef> extends Connection<TReceive, TSend> {
+	private serverWs: IServerWebSocket | null = null
+	private clientType: string = 'unknown'
+	private subscribedSessions = new Set<string>()
+
+	constructor(config: ServerConnectionConfig<TReceive, TSend>) {
+		super(config)
+		if (config.connectionId) {
+			this.connectionId = config.connectionId
+		}
+	}
+
+	/**
+	 * Attach an already-accepted WebSocket connection.
+	 * Connection is immediately ready - no handshake needed.
+	 */
+	attach(ws: IServerWebSocket): void {
+		this.serverWs = ws
+		this.setupServerWebSocket(ws)
+		this.setState('connected')
+	}
+
+	async connect(): Promise<void> {
+		throw new Error('Server connections use attach() instead of connect()')
+	}
+
+	async disconnect(): Promise<void> {
+		this.cleanup()
+
+		if (this.serverWs && this.serverWs.readyState !== WebSocketReadyState.CLOSED) {
+			this.serverWs.close(1000, 'Server disconnect')
+		}
+
+		this.serverWs = null
+		this.ws = null
+		this.setState('disconnected')
+	}
+
+	getClientType(): string {
+		return this.clientType
+	}
+
+	setClientType(clientType: string): void {
+		this.clientType = clientType
+	}
+
+	getSubscribedSessions(): ReadonlySet<string> {
+		return this.subscribedSessions
+	}
+
+	subscribe(sessionId: string): void {
+		this.subscribedSessions.add(sessionId)
+		this.serverWs?.subscribe(`session:${sessionId}`)
+	}
+
+	unsubscribe(sessionId: string): void {
+		this.subscribedSessions.delete(sessionId)
+		this.serverWs?.unsubscribe(`session:${sessionId}`)
+	}
+
+	isSubscribedTo(sessionId: string): boolean {
+		return this.subscribedSessions.has(sessionId)
+	}
+
+	publishToSession(sessionId: string, message: string): void {
+		this.serverWs?.publish(`session:${sessionId}`, message)
+	}
+
+	getHandlerContext(): ServerHandlerContext {
+		return {
+			connectionId: this.connectionId,
+			clientType: this.clientType,
+			subscribedSessions: this.subscribedSessions,
+		}
+	}
+
+	// Use server context for handlers
+	private setupServerWebSocket(ws: IServerWebSocket): void {
+		this.ws = ws
+		this.router.setSender((message) => this.send(message))
+		ws.onmessage = (data) => this.router.handleMessage(data, this.getHandlerContext())
+		ws.onerror = (error) => this.emit('error', error)
+		ws.onclose = (event) => this.handleClose(event.code, event.reason)
+	}
+}
+
+export function createServerConnection<TReceive extends ProtocolDef, TSend extends ProtocolDef>(
+	config: ServerConnectionConfig<TReceive, TSend>,
+): ServerConnection<TReceive, TSend> {
+	return new ServerConnection(config)
+}