@roj-ai/transport 0.0.2

package/src/__tests__/integration.test.ts

@@ -0,0 +1,443 @@
+/**
+ * Integration Tests for Transport Package
+ *
+ * These tests run actual WebSocket server and client to verify
+ * real-world communication scenarios with notification-only protocol.
+ */
+
+import type { Server } from 'bun'
+import { afterAll, afterEach, beforeAll, describe, expect, it } from 'bun:test'
+import { z } from 'zod'
+
+import { ClientConnection } from '../client/client-connection.js'
+import { defineProtocol, notification } from '../core/protocol.js'
+import { BunServerWebSocketAdapter, bunWebSocketFactory, createBunWebSocketHandlers } from '../platform/bun.js'
+import type { IServerWebSocket } from '../platform/types.js'
+import { ServerConnection } from '../server/server-connection.js'
+
+// ============================================================================
+// Test Protocols (notification-only)
+// ============================================================================
+
+// Client -> Server (notifications)
+const clientProtocol = defineProtocol({
+	userMessage: notification({
+		input: z.object({ sessionId: z.string(), content: z.string() }),
+	}),
+	userStatus: notification({
+		input: z.object({ status: z.enum(['online', 'away', 'offline']) }),
+	}),
+})
+
+// Server -> Client (notifications)
+const serverProtocol = defineProtocol({
+	serverEvent: notification({
+		input: z.object({ eventType: z.string(), data: z.unknown() }),
+	}),
+	agentMessage: notification({
+		input: z.object({ sessionId: z.string(), content: z.string() }),
+	}),
+})
+
+// ============================================================================
+// Test Server Setup
+// ============================================================================
+
+interface TestServerState {
+	server: Server
+	port: number
+	connections: Map<string, ServerConnection<typeof clientProtocol._def, typeof serverProtocol._def>>
+	receivedNotifications: Array<{ type: string; input: unknown }>
+}
+
+function createTestServer(): Promise<TestServerState> {
+	return new Promise((resolve) => {
+		const connections = new Map<string, ServerConnection<typeof clientProtocol._def, typeof serverProtocol._def>>()
+		const receivedNotifications: Array<{ type: string; input: unknown }> = []
+
+		const wsHandlers = createBunWebSocketHandlers({
+			onOpen: (ws: IServerWebSocket) => {
+				const serverConn = new ServerConnection({
+					receiveProtocol: clientProtocol,
+					sendProtocol: serverProtocol,
+				})
+
+				// Set up handlers for incoming notifications
+				serverConn.setHandlers({
+					userMessage: async (input) => {
+						receivedNotifications.push({ type: 'userMessage', input })
+					},
+					userStatus: async (input) => {
+						receivedNotifications.push({ type: 'userStatus', input })
+					},
+				})
+
+				serverConn.attach(ws)
+				connections.set(serverConn.getConnectionId(), serverConn)
+				;(ws as unknown as { __serverConn: ServerConnection<typeof clientProtocol._def, typeof serverProtocol._def> }).__serverConn = serverConn
+			},
+			onClose: (ws: IServerWebSocket) => {
+				const serverConn = (ws as unknown as { __serverConn: ServerConnection<typeof clientProtocol._def, typeof serverProtocol._def> }).__serverConn
+				if (serverConn) {
+					connections.delete(serverConn.getConnectionId())
+				}
+			},
+			onMessage: (ws: IServerWebSocket, message: string) => {
+				// Forward message to the WebSocket's onmessage handler
+				ws.onmessage?.(message)
+			},
+			onError: () => {},
+			getData: () => ({}),
+		})
+
+		const server = Bun.serve({
+			port: 0, // Random available port
+			fetch(req, server) {
+				if (server.upgrade(req)) {
+					return
+				}
+				return new Response('WebSocket server', { status: 200 })
+			},
+			websocket: {
+				open: wsHandlers.open,
+				close: wsHandlers.close,
+				message: wsHandlers.message,
+			},
+		})
+
+		resolve({
+			server,
+			port: server.port,
+			connections,
+			receivedNotifications,
+		})
+	})
+}
+
+// ============================================================================
+// Integration Tests
+// ============================================================================
+
+describe('Transport Integration Tests', () => {
+	let testServer: TestServerState
+
+	beforeAll(async () => {
+		testServer = await createTestServer()
+	})
+
+	afterAll(() => {
+		testServer.server.stop()
+	})
+
+	afterEach(() => {
+		testServer.receivedNotifications.length = 0
+	})
+
+	describe('Connection', () => {
+		it('should connect successfully', async () => {
+			const client = new ClientConnection({
+				url: `ws://localhost:${testServer.port}`,
+				wsFactory: bunWebSocketFactory,
+				receiveProtocol: serverProtocol,
+				sendProtocol: clientProtocol,
+			})
+
+			await client.connect()
+
+			expect(client.isConnected()).toBe(true)
+			expect(client.getState()).toBe('connected')
+
+			await client.disconnect()
+			expect(client.isConnected()).toBe(false)
+		})
+
+		it('should emit state change events', async () => {
+			const stateChanges: Array<{ from: string; to: string }> = []
+
+			const client = new ClientConnection({
+				url: `ws://localhost:${testServer.port}`,
+				wsFactory: bunWebSocketFactory,
+				receiveProtocol: serverProtocol,
+				sendProtocol: clientProtocol,
+			})
+
+			client.on((event, data) => {
+				if (event === 'state_change') {
+					stateChanges.push(data as { from: string; to: string })
+				}
+			})
+
+			await client.connect()
+			await client.disconnect()
+
+			// Should have state changes: disconnected -> connecting -> connected -> disconnected
+			expect(stateChanges.length).toBeGreaterThan(2)
+			expect(stateChanges.some((s) => s.to === 'connected')).toBe(true)
+		})
+	})
+
+	describe('Client-to-Server Notifications', () => {
+		it('should send notification to server', async () => {
+			const client = new ClientConnection({
+				url: `ws://localhost:${testServer.port}`,
+				wsFactory: bunWebSocketFactory,
+				receiveProtocol: serverProtocol,
+				sendProtocol: clientProtocol,
+			})
+
+			await client.connect()
+
+			// Send notification
+			client.notify.userMessage({ sessionId: 'sess-1', content: 'Hello World' })
+
+			// Wait for notification to arrive
+			await new Promise((resolve) => setTimeout(resolve, 50))
+
+			// Verify server received the notification
+			expect(testServer.receivedNotifications).toContainEqual({
+				type: 'userMessage',
+				input: { sessionId: 'sess-1', content: 'Hello World' },
+			})
+
+			await client.disconnect()
+		})
+
+		it('should send multiple notifications', async () => {
+			const client = new ClientConnection({
+				url: `ws://localhost:${testServer.port}`,
+				wsFactory: bunWebSocketFactory,
+				receiveProtocol: serverProtocol,
+				sendProtocol: clientProtocol,
+			})
+
+			await client.connect()
+
+			// Send multiple notifications
+			client.notify.userMessage({ sessionId: 'sess-1', content: 'First message' })
+			client.notify.userStatus({ status: 'online' })
+			client.notify.userMessage({ sessionId: 'sess-1', content: 'Second message' })
+
+			// Wait for notifications to arrive
+			await new Promise((resolve) => setTimeout(resolve, 50))
+
+			expect(testServer.receivedNotifications.length).toBe(3)
+			expect(testServer.receivedNotifications[0]).toEqual({
+				type: 'userMessage',
+				input: { sessionId: 'sess-1', content: 'First message' },
+			})
+			expect(testServer.receivedNotifications[1]).toEqual({
+				type: 'userStatus',
+				input: { status: 'online' },
+			})
+			expect(testServer.receivedNotifications[2]).toEqual({
+				type: 'userMessage',
+				input: { sessionId: 'sess-1', content: 'Second message' },
+			})
+
+			await client.disconnect()
+		})
+	})
+
+	describe('Server-to-Client Notifications', () => {
+		it('should receive notifications from server', async () => {
+			const receivedNotifications: Array<{ eventType: string; data: unknown }> = []
+
+			const client = new ClientConnection({
+				url: `ws://localhost:${testServer.port}`,
+				wsFactory: bunWebSocketFactory,
+				receiveProtocol: serverProtocol,
+				sendProtocol: clientProtocol,
+			})
+
+			// Set up notification handler
+			client.setHandlers({
+				serverEvent: async (input) => {
+					receivedNotifications.push(input)
+				},
+			})
+
+			await client.connect()
+
+			// Get the server connection and send notification
+			await new Promise((resolve) => setTimeout(resolve, 50)) // Wait for server to register connection
+
+			const serverConnections = Array.from(testServer.connections.values())
+			expect(serverConnections.length).toBeGreaterThan(0)
+
+			const serverConn = serverConnections[0]
+			serverConn.notify.serverEvent({ eventType: 'test_event', data: { foo: 'bar' } })
+
+			// Wait for notification to arrive
+			await new Promise((resolve) => setTimeout(resolve, 50))
+
+			expect(receivedNotifications.length).toBe(1)
+			expect(receivedNotifications[0].eventType).toBe('test_event')
+			expect(receivedNotifications[0].data).toEqual({ foo: 'bar' })
+
+			await client.disconnect()
+		})
+
+		it('should receive agent messages from server', async () => {
+			const receivedMessages: Array<{ sessionId: string; content: string }> = []
+
+			const client = new ClientConnection({
+				url: `ws://localhost:${testServer.port}`,
+				wsFactory: bunWebSocketFactory,
+				receiveProtocol: serverProtocol,
+				sendProtocol: clientProtocol,
+			})
+
+			client.setHandlers({
+				agentMessage: async (input) => {
+					receivedMessages.push(input)
+				},
+			})
+
+			await client.connect()
+			await new Promise((resolve) => setTimeout(resolve, 50))
+
+			const serverConnections = Array.from(testServer.connections.values())
+			const serverConn = serverConnections[0]
+
+			serverConn.notify.agentMessage({ sessionId: 'sess-1', content: 'Hello from agent!' })
+
+			await new Promise((resolve) => setTimeout(resolve, 50))
+
+			expect(receivedMessages.length).toBe(1)
+			expect(receivedMessages[0]).toEqual({ sessionId: 'sess-1', content: 'Hello from agent!' })
+
+			await client.disconnect()
+		})
+	})
+
+	describe('Reconnection', () => {
+		it('should attempt reconnection when connection is lost', async () => {
+			const reconnectAttempts: number[] = []
+			const stateChanges: string[] = []
+
+			// Create a server that immediately closes connections
+			const tempServer = Bun.serve({
+				port: 0,
+				fetch(req, server) {
+					if (server.upgrade(req)) return
+					return new Response('ok')
+				},
+				websocket: {
+					open(ws) {
+						// Close connection after a brief delay to trigger reconnect
+						setTimeout(() => ws.close(1000, 'Server initiated close'), 50)
+					},
+					message() {},
+					close() {},
+				},
+			})
+
+			const client = new ClientConnection({
+				url: `ws://localhost:${tempServer.port}`,
+				wsFactory: bunWebSocketFactory,
+				receiveProtocol: serverProtocol,
+				sendProtocol: clientProtocol,
+				reconnect: {
+					baseDelayMs: 20,
+					maxDelayMs: 100,
+					maxAttempts: 2,
+					jitterFactor: 0,
+				},
+			})
+
+			client.on((event, data) => {
+				if (event === 'reconnecting') {
+					reconnectAttempts.push((data as { attempt: number }).attempt)
+				}
+				if (event === 'state_change') {
+					stateChanges.push((data as { to: string }).to)
+				}
+			})
+
+			await client.connect()
+
+			// Wait for server to close connection and client to attempt reconnect
+			await new Promise((resolve) => setTimeout(resolve, 200))
+
+			// Should have attempted reconnection
+			expect(reconnectAttempts.length).toBeGreaterThan(0)
+			expect(stateChanges).toContain('reconnecting')
+
+			await client.disconnect()
+			tempServer.stop()
+		})
+	})
+
+	describe('Multiple Clients', () => {
+		it('should handle multiple simultaneous clients', async () => {
+			const numClients = 5
+			const clients: ClientConnection<typeof serverProtocol._def, typeof clientProtocol._def>[] = []
+
+			// Connect multiple clients
+			for (let i = 0; i < numClients; i++) {
+				const client = new ClientConnection({
+					url: `ws://localhost:${testServer.port}`,
+					wsFactory: bunWebSocketFactory,
+					receiveProtocol: serverProtocol,
+					sendProtocol: clientProtocol,
+				})
+				await client.connect()
+				clients.push(client)
+			}
+
+			// All clients should be connected
+			expect(clients.every((c) => c.isConnected())).toBe(true)
+
+			// Each client sends a notification
+			clients.forEach((client, i) => {
+				client.notify.userMessage({ sessionId: `sess-${i}`, content: `Message from client ${i}` })
+			})
+
+			// Wait for notifications to arrive
+			await new Promise((resolve) => setTimeout(resolve, 100))
+
+			// All notifications should be received
+			expect(testServer.receivedNotifications.length).toBe(numClients)
+
+			// Disconnect all
+			await Promise.all(clients.map((c) => c.disconnect()))
+		})
+	})
+
+	describe('Bidirectional Communication', () => {
+		it('should handle simultaneous send and receive', async () => {
+			const clientReceivedMessages: unknown[] = []
+
+			const client = new ClientConnection({
+				url: `ws://localhost:${testServer.port}`,
+				wsFactory: bunWebSocketFactory,
+				receiveProtocol: serverProtocol,
+				sendProtocol: clientProtocol,
+			})
+
+			client.setHandlers({
+				agentMessage: async (input) => {
+					clientReceivedMessages.push(input)
+				},
+			})
+
+			await client.connect()
+			await new Promise((resolve) => setTimeout(resolve, 50))
+
+			// Client sends notification
+			client.notify.userMessage({ sessionId: 'sess-1', content: 'Client message' })
+
+			// Server sends notification simultaneously
+			const serverConnections = Array.from(testServer.connections.values())
+			serverConnections[0].notify.agentMessage({ sessionId: 'sess-1', content: 'Server message' })
+
+			await new Promise((resolve) => setTimeout(resolve, 100))
+
+			// Both sides should have received notifications
+			expect(testServer.receivedNotifications.some((n) => n.type === 'userMessage')).toBe(true)
+			expect(clientReceivedMessages.length).toBe(1)
+
+			await client.disconnect()
+		})
+	})
+})

package/src/client/client-connection.ts

@@ -0,0 +1,207 @@
+/**
+ * Client Connection
+ *
+ * WebSocket client with automatic reconnection.
+ * Simplified: no handshake - connected immediately when WebSocket opens.
+ */
+
+import { Connection } from '../core/connection.js'
+import type { ConnectionConfig } from '../core/connection.js'
+import type { ProtocolDef } from '../core/protocol.js'
+import type { ReconnectOptions } from '../core/types.js'
+import { DEFAULT_RECONNECT_OPTIONS } from '../core/types.js'
+import type { IWebSocketFactory } from '../platform/types.js'
+import { WebSocketReadyState } from '../platform/types.js'
+
+/**
+ * Client connection configuration.
+ */
+export interface ClientConnectionConfig<TReceive extends ProtocolDef, TSend extends ProtocolDef> extends ConnectionConfig<TReceive, TSend> {
+	url: string
+	wsFactory: IWebSocketFactory
+	reconnect?: Partial<ReconnectOptions>
+}
+
+/**
+ * WebSocket client with automatic reconnection and exponential backoff.
+ */
+export class ClientConnection<TReceive extends ProtocolDef, TSend extends ProtocolDef> extends Connection<TReceive, TSend> {
+	private readonly url: string
+	private readonly wsFactory: IWebSocketFactory
+
+	// Reconnection
+	private readonly reconnectOptions: ReconnectOptions | null
+	private reconnectAttempts = 0
+	private reconnectTimer: ReturnType<typeof setTimeout> | null = null
+	private reconnectStopped = false
+
+	// Connect promise
+	private connectPromise: Promise<void> | null = null
+	private connectResolve: (() => void) | null = null
+	private connectReject: ((error: Error) => void) | null = null
+	private intentionalDisconnect = false
+
+	constructor(config: ClientConnectionConfig<TReceive, TSend>) {
+		super(config)
+		this.url = config.url
+		this.wsFactory = config.wsFactory
+		this.reconnectOptions = config.reconnect
+			? { ...DEFAULT_RECONNECT_OPTIONS, ...config.reconnect }
+			: null
+	}
+
+	async connect(): Promise<void> {
+		if (this.isConnected()) return
+		if (this.connectPromise) return this.connectPromise
+
+		this.intentionalDisconnect = false
+		this.reconnectStopped = false
+
+		this.connectPromise = new Promise<void>((resolve, reject) => {
+			this.connectResolve = resolve
+			this.connectReject = reject
+			this.doConnect()
+		})
+
+		return this.connectPromise
+	}
+
+	async disconnect(): Promise<void> {
+		this.intentionalDisconnect = true
+		this.stopReconnect()
+		this.cleanup()
+
+		if (this.ws && this.ws.readyState !== WebSocketReadyState.CLOSED) {
+			this.ws.close(1000, 'Client disconnect')
+		}
+
+		this.ws = null
+		this.setState('disconnected')
+
+		if (this.connectReject) {
+			this.connectReject(new Error('Disconnected'))
+			this.clearConnectPromise()
+		}
+	}
+
+	getReconnectAttempts(): number {
+		return this.reconnectAttempts
+	}
+
+	hasReconnect(): boolean {
+		return this.reconnectOptions !== null
+	}
+
+	// Override to resolve connect promise and reset reconnect
+	protected override handleOpen(): void {
+		const wasReconnecting = this.reconnectAttempts > 0
+		super.handleOpen()
+		this.reconnectAttempts = 0
+
+		// Flush any messages buffered during disconnect
+		this.flushSendBuffer()
+
+		if (this.connectResolve) {
+			this.connectResolve()
+			this.clearConnectPromise()
+		}
+
+		// Emit reconnected event so application can restore subscriptions
+		if (wasReconnecting) {
+			this.emit('reconnected')
+		}
+	}
+
+	protected override handleClose(code: number, reason: string): void {
+		this.cleanup()
+
+		if (this.intentionalDisconnect) {
+			this.setState('disconnected')
+			return
+		}
+
+		if (this.connectReject) {
+			this.connectReject(new Error(`Connection closed: ${code} ${reason}`))
+			this.clearConnectPromise()
+		}
+
+		this.handleConnectionLost()
+	}
+
+	protected override handleConnectionLost(): void {
+		this.cleanup()
+
+		if (this.intentionalDisconnect) {
+			this.setState('disconnected')
+			return
+		}
+
+		if (!this.reconnectOptions || this.reconnectStopped) {
+			this.setState('disconnected')
+			return
+		}
+
+		if (this.reconnectAttempts >= this.reconnectOptions.maxAttempts) {
+			this.emit('error', new Error('Max reconnection attempts reached'))
+			this.setState('disconnected')
+			return
+		}
+
+		this.setState('reconnecting')
+		const delay = this.calculateReconnectDelay()
+		this.reconnectAttempts++
+
+		this.emit('reconnecting', { delay, attempt: this.reconnectAttempts })
+
+		this.reconnectTimer = setTimeout(() => {
+			this.reconnectTimer = null
+			this.setState('connecting')
+			this.doConnect()
+		}, delay)
+	}
+
+	private doConnect(): void {
+		this.setState('connecting')
+
+		try {
+			const ws = this.wsFactory.create(this.url)
+			this.setupWebSocket(ws)
+			ws.onopen = () => this.handleOpen()
+		} catch (error) {
+			if (this.connectReject) {
+				this.connectReject(error instanceof Error ? error : new Error('Connection failed'))
+				this.clearConnectPromise()
+			}
+			this.handleConnectionLost()
+		}
+	}
+
+	private calculateReconnectDelay(): number {
+		if (!this.reconnectOptions) return 0
+		const { baseDelayMs, maxDelayMs, jitterFactor } = this.reconnectOptions
+		const exponential = baseDelayMs * Math.pow(2, this.reconnectAttempts)
+		const capped = Math.min(exponential, maxDelayMs)
+		const jitter = capped * jitterFactor * Math.random()
+		return Math.floor(capped + jitter)
+	}
+
+	private stopReconnect(): void {
+		this.reconnectStopped = true
+		if (this.reconnectTimer) {
+			clearTimeout(this.reconnectTimer)
+			this.reconnectTimer = null
+		}
+	}
+
+	private clearConnectPromise(): void {
+		this.connectPromise = null
+		this.connectResolve = null
+		this.connectReject = null
+	}
+}
+
+export function createClientConnection<TReceive extends ProtocolDef, TSend extends ProtocolDef>(
+	config: ClientConnectionConfig<TReceive, TSend>,
+): ClientConnection<TReceive, TSend> {
+	return new ClientConnection(config)
+}

package/src/client/index.ts

@@ -0,0 +1,24 @@
+/**
+ * Client Connection Module
+ *
+ * WebSocket client for connecting to server endpoints.
+ */
+
+export { ClientConnection, createClientConnection } from './client-connection.js'
+export type { ClientConnectionConfig } from './client-connection.js'
+
+// Re-export core types commonly used with client
+export type {
+	ConnectionState,
+	HandlerContext,
+	Protocol,
+	ProtocolCaller,
+	ProtocolDef,
+	ProtocolHandlers,
+	ProtocolNotifier,
+	ReconnectOptions,
+	TransportEvent,
+	TransportEventListener,
+} from '../core/index.js'
+
+export { defineProtocol, method, notification } from '../core/index.js'