@roj-ai/transport 0.0.2

package/src/core/connection.ts

@@ -0,0 +1,203 @@
+/**
+ * Connection Base Class
+ *
+ * Provides symmetric API for WebSocket client and server connections.
+ * Simplified: no handshake, no heartbeat - just WebSocket open/close → connected/disconnected.
+ * Notification-only: no request-response, no correlation.
+ */
+
+import type { IWebSocket } from '../platform/types.js'
+import { WebSocketReadyState } from '../platform/types.js'
+import type { Protocol, ProtocolDef, ProtocolHandlers, ProtocolNotifier } from './protocol.js'
+import { MessageRouter } from './router.js'
+import type { RawMessageListener } from './router.js'
+import type { ConnectionState, TransportEvent, TransportEventListener } from './types.js'
+
+/**
+ * Connection configuration.
+ */
+export interface ConnectionConfig<TReceive extends ProtocolDef, TSend extends ProtocolDef> {
+	receiveProtocol?: Protocol<TReceive>
+	sendProtocol?: Protocol<TSend>
+}
+
+/**
+ * Abstract base class for WebSocket connections.
+ * State transitions: disconnected ↔ connecting ↔ connected ↔ reconnecting
+ */
+export abstract class Connection<TReceive extends ProtocolDef, TSend extends ProtocolDef> {
+	protected readonly config: ConnectionConfig<TReceive, TSend>
+	protected readonly router: MessageRouter<TReceive, TSend>
+
+	// State
+	protected state: ConnectionState = 'disconnected'
+	protected ws: IWebSocket | null = null
+	protected connectionId: string
+	protected eventListeners = new Set<TransportEventListener>()
+
+	constructor(config: ConnectionConfig<TReceive, TSend>) {
+		this.config = config
+		this.connectionId = `conn-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`
+
+		this.router = new MessageRouter(
+			config.receiveProtocol ?? null,
+			config.sendProtocol ?? null,
+		)
+		this.router.setErrorHandler((error) => this.emit('router_error', error))
+	}
+
+	// ============================================================================
+	// Public API
+	// ============================================================================
+
+	getState(): ConnectionState {
+		return this.state
+	}
+
+	isConnected(): boolean {
+		return this.state === 'connected'
+	}
+
+	getConnectionId(): string {
+		return this.connectionId
+	}
+
+	setHandlers(handlers: Partial<ProtocolHandlers<TReceive>>): void {
+		this.router.setHandlers(handlers)
+	}
+
+	/**
+	 * Set a raw message listener that receives every incoming message as (type, payload).
+	 * When set, bypasses per-type handler dispatch.
+	 */
+	setRawMessageListener(listener: RawMessageListener): void {
+		this.router.setRawMessageListener(listener)
+	}
+
+	get notify(): ProtocolNotifier<TSend> {
+		const protocol = this.config.sendProtocol
+		if (!protocol) {
+			throw new Error('Cannot send notifications without a send protocol')
+		}
+		const notifier: Record<string, unknown> = {}
+		for (const name of protocol.getNotificationNames()) {
+			notifier[name as string] = (input: unknown) => this.router.notify(name, input as never)
+		}
+		return notifier as ProtocolNotifier<TSend>
+	}
+
+	// ============================================================================
+	// Send Buffer (bridges short disconnects)
+	// ============================================================================
+
+	private sendBuffer: string[] = []
+	private readonly maxBufferSize: number = 500
+
+	send(data: string): boolean {
+		if (!this.ws || this.ws.readyState !== WebSocketReadyState.OPEN) {
+			if (this.sendBuffer.length < this.maxBufferSize) {
+				this.sendBuffer.push(data)
+			}
+			return false
+		}
+		this.flushSendBuffer()
+		try {
+			this.ws.send(data)
+			return true
+		} catch {
+			if (this.sendBuffer.length < this.maxBufferSize) {
+				this.sendBuffer.push(data)
+			}
+			return false
+		}
+	}
+
+	flushSendBuffer(): void {
+		while (this.sendBuffer.length > 0) {
+			if (!this.ws || this.ws.readyState !== WebSocketReadyState.OPEN) break
+			const msg = this.sendBuffer.shift()!
+			try {
+				this.ws.send(msg)
+			} catch {
+				this.sendBuffer.unshift(msg)
+				break
+			}
+		}
+	}
+
+	clearSendBuffer(): void {
+		this.sendBuffer.length = 0
+	}
+
+	get bufferedMessageCount(): number {
+		return this.sendBuffer.length
+	}
+
+	on(listener: TransportEventListener): () => void {
+		this.eventListeners.add(listener)
+		return () => this.eventListeners.delete(listener)
+	}
+
+	abstract connect(): Promise<void>
+	abstract disconnect(): Promise<void>
+
+	// ============================================================================
+	// State Management
+	// ============================================================================
+
+	protected setState(newState: ConnectionState): void {
+		if (newState === this.state) return
+		const from = this.state
+		this.state = newState
+		this.emit('state_change', { from, to: newState })
+		if (newState === 'connected') this.emit('connected')
+		else if (newState === 'disconnected') this.emit('disconnected')
+		else if (newState === 'reconnecting') this.emit('reconnecting')
+	}
+
+	// ============================================================================
+	// WebSocket Setup
+	// ============================================================================
+
+	protected setupWebSocket(ws: IWebSocket): void {
+		this.ws = ws
+		this.router.setSender((message) => this.send(message))
+		ws.onmessage = (data) => this.router.handleMessage(data, { connectionId: this.connectionId })
+		ws.onerror = (error) => this.emit('error', error)
+		ws.onclose = (event) => this.handleClose(event.code, event.reason)
+	}
+
+	protected handleOpen(): void {
+		// Immediately connected - no handshake needed
+		this.setState('connected')
+	}
+
+	protected handleClose(_code: number, _reason: string): void {
+		this.cleanup()
+		this.setState('disconnected')
+	}
+
+	protected handleConnectionLost(): void {
+		this.cleanup()
+		this.setState('disconnected')
+	}
+
+	protected cleanup(): void {
+		if (this.ws) {
+			this.ws.onopen = null
+			this.ws.onclose = null
+			this.ws.onerror = null
+			this.ws.onmessage = null
+		}
+	}
+
+	protected emit(event: TransportEvent, data?: unknown): void {
+		for (const listener of this.eventListeners) {
+			try {
+				listener(event, data)
+			} catch {
+				// Ignore listener errors
+			}
+		}
+	}
+}

package/src/core/index.ts

@@ -0,0 +1,52 @@
+/**
+ * Core Transport Module
+ *
+ * Platform-agnostic WebSocket infrastructure.
+ */
+
+// Types
+export type { ConnectionState, ReconnectOptions, TransportEvent, TransportEventListener, WireMessage } from './types.js'
+
+export { DEFAULT_RECONNECT_OPTIONS } from './types.js'
+
+// Result
+export type { Result } from './result.js'
+export { Err, flatMapResult, isErr, isOk, mapResult, Ok, unwrapOr, unwrapOrThrow } from './result.js'
+
+// Protocol Definition
+export { defineProtocol, method, notification } from './protocol.js'
+export type {
+	CallerFor,
+	EndpointDef,
+	EndpointHandler,
+	ExtractProtocolDef,
+	HandlerContext,
+	HandlersFor,
+	InferError,
+	InferInput,
+	InferOutput,
+	IsMethod,
+	IsNotification,
+	MethodCaller,
+	MethodDef,
+	MethodHandler,
+	MethodOptions,
+	NotificationDef,
+	NotificationHandler,
+	NotificationNotifier,
+	NotificationOptions,
+	NotifierFor,
+	Protocol,
+	ProtocolCaller,
+	ProtocolDef,
+	ProtocolHandlers,
+	ProtocolNotifier,
+} from './protocol.js'
+
+// Message Router
+export { createRouter, MessageRouter } from './router.js'
+export type { MessageSender } from './router.js'
+
+// Connection Base
+export { Connection } from './connection.js'
+export type { ConnectionConfig } from './connection.js'

package/src/core/protocol.test.ts

@@ -0,0 +1,235 @@
+/**
+ * Protocol Definition Tests
+ */
+
+import { describe, expect, it } from 'bun:test'
+import { z } from 'zod'
+import { defineProtocol, method, notification } from './protocol.js'
+
+describe('Protocol Definition', () => {
+	describe('method()', () => {
+		it('should create a method definition', () => {
+			const def = method({
+				input: z.object({ id: z.string() }),
+				output: z.object({ success: z.boolean() }),
+				error: z.object({ code: z.string() }),
+			})
+
+			expect(def._type).toBe('method')
+			expect(def.input).toBeDefined()
+			expect(def.output).toBeDefined()
+			expect(def.error).toBeDefined()
+		})
+	})
+
+	describe('notification()', () => {
+		it('should create a notification definition', () => {
+			const def = notification({
+				input: z.object({ message: z.string() }),
+			})
+
+			expect(def._type).toBe('notification')
+			expect(def.input).toBeDefined()
+		})
+	})
+
+	describe('defineProtocol()', () => {
+		const testProtocol = defineProtocol({
+			subscribe: method({
+				input: z.object({ sessionId: z.string() }),
+				output: z.void(),
+				error: z.object({ code: z.enum(['SESSION_NOT_FOUND']), message: z.string() }),
+			}),
+			unsubscribe: method({
+				input: z.object({ sessionId: z.string() }),
+				output: z.void(),
+				error: z.never(),
+			}),
+			agentMessage: notification({
+				input: z.object({
+					sessionId: z.string(),
+					content: z.string(),
+					format: z.enum(['text', 'markdown']),
+				}),
+			}),
+		})
+
+		it('should expose the definition', () => {
+			expect(testProtocol._def).toBeDefined()
+			expect(testProtocol._def.subscribe).toBeDefined()
+			expect(testProtocol._def.unsubscribe).toBeDefined()
+			expect(testProtocol._def.agentMessage).toBeDefined()
+		})
+
+		describe('getEndpoint()', () => {
+			it('should return endpoint definition by name', () => {
+				const endpoint = testProtocol.getEndpoint('subscribe')
+				expect(endpoint._type).toBe('method')
+			})
+		})
+
+		describe('isMethod()', () => {
+			it('should return true for methods', () => {
+				expect(testProtocol.isMethod('subscribe')).toBe(true)
+				expect(testProtocol.isMethod('unsubscribe')).toBe(true)
+			})
+
+			it('should return false for notifications', () => {
+				expect(testProtocol.isMethod('agentMessage')).toBe(false)
+			})
+		})
+
+		describe('isNotification()', () => {
+			it('should return true for notifications', () => {
+				expect(testProtocol.isNotification('agentMessage')).toBe(true)
+			})
+
+			it('should return false for methods', () => {
+				expect(testProtocol.isNotification('subscribe')).toBe(false)
+			})
+		})
+
+		describe('getMethodNames()', () => {
+			it('should return all method names', () => {
+				const names = testProtocol.getMethodNames()
+				expect(names).toContain('subscribe')
+				expect(names).toContain('unsubscribe')
+				expect(names).not.toContain('agentMessage')
+			})
+		})
+
+		describe('getNotificationNames()', () => {
+			it('should return all notification names', () => {
+				const names = testProtocol.getNotificationNames()
+				expect(names).toContain('agentMessage')
+				expect(names).not.toContain('subscribe')
+			})
+		})
+
+		describe('validateInput()', () => {
+			it('should validate correct input', () => {
+				const result = testProtocol.validateInput('subscribe', { sessionId: 'test-123' })
+				expect(result.success).toBe(true)
+				if (result.success) {
+					expect(result.data.sessionId).toBe('test-123')
+				}
+			})
+
+			it('should reject invalid input', () => {
+				const result = testProtocol.validateInput('subscribe', { sessionId: 123 })
+				expect(result.success).toBe(false)
+				if (!result.success) {
+					expect(result.error.message).toBeDefined()
+				}
+			})
+
+			it('should reject missing required fields', () => {
+				const result = testProtocol.validateInput('subscribe', {})
+				expect(result.success).toBe(false)
+			})
+
+			it('should validate notification input', () => {
+				const result = testProtocol.validateInput('agentMessage', {
+					sessionId: 'test',
+					content: 'Hello',
+					format: 'text',
+				})
+				expect(result.success).toBe(true)
+			})
+
+			it('should reject invalid notification input', () => {
+				const result = testProtocol.validateInput('agentMessage', {
+					sessionId: 'test',
+					content: 'Hello',
+					format: 'invalid',
+				})
+				expect(result.success).toBe(false)
+			})
+		})
+
+		describe('validateOutput()', () => {
+			it('should validate method output', () => {
+				const result = testProtocol.validateOutput('subscribe', undefined)
+				expect(result.success).toBe(true)
+			})
+
+			it('should throw for notification output validation', () => {
+				expect(() => testProtocol.validateOutput('agentMessage', {})).toThrow(
+					'Endpoint agentMessage is not a method',
+				)
+			})
+		})
+	})
+
+	describe('complex schemas', () => {
+		it('should handle nested objects', () => {
+			const protocol = defineProtocol({
+				createUser: method({
+					input: z.object({
+						name: z.string(),
+						address: z.object({
+							street: z.string(),
+							city: z.string(),
+						}),
+					}),
+					output: z.object({ id: z.string() }),
+					error: z.object({ code: z.string() }),
+				}),
+			})
+
+			const valid = protocol.validateInput('createUser', {
+				name: 'John',
+				address: { street: '123 Main St', city: 'NYC' },
+			})
+			expect(valid.success).toBe(true)
+
+			const invalid = protocol.validateInput('createUser', {
+				name: 'John',
+				address: { street: '123 Main St' }, // Missing city
+			})
+			expect(invalid.success).toBe(false)
+		})
+
+		it('should handle arrays', () => {
+			const protocol = defineProtocol({
+				sendBatch: method({
+					input: z.object({
+						messages: z.array(z.object({
+							id: z.string(),
+							content: z.string(),
+						})),
+					}),
+					output: z.object({ processed: z.number() }),
+					error: z.object({ code: z.string() }),
+				}),
+			})
+
+			const valid = protocol.validateInput('sendBatch', {
+				messages: [
+					{ id: '1', content: 'Hello' },
+					{ id: '2', content: 'World' },
+				],
+			})
+			expect(valid.success).toBe(true)
+		})
+
+		it('should handle optional fields', () => {
+			const protocol = defineProtocol({
+				search: method({
+					input: z.object({
+						query: z.string(),
+						limit: z.number().optional(),
+					}),
+					output: z.array(z.string()),
+					error: z.object({ code: z.string() }),
+				}),
+			})
+
+			const withOptional = protocol.validateInput('search', { query: 'test', limit: 10 })
+			expect(withOptional.success).toBe(true)
+
+			const withoutOptional = protocol.validateInput('search', { query: 'test' })
+			expect(withoutOptional.success).toBe(true)
+		})
+	})
+})