@roj-ai/transport 0.0.2

package/src/core/router.ts

@@ -0,0 +1,186 @@
+/**
+ * Message Router
+ *
+ * Handles notification dispatching - no request-response, no correlation.
+ * Simplified for notification-only protocols.
+ */
+
+import type { HandlerContext, InferInput, Protocol, ProtocolDef, ProtocolHandlers } from './protocol.js'
+import type { WireMessage } from './types.js'
+
+// ============================================================================
+// Router Types
+// ============================================================================
+
+/**
+ * Message send function type.
+ */
+export type MessageSender = (message: string) => boolean
+
+/**
+ * Router error types for debugging protocol issues.
+ */
+export type RouterErrorType = 'parse' | 'unknown_type' | 'validation' | 'handler'
+
+/**
+ * Router error handler callback.
+ */
+export type RouterErrorHandler = (error: {
+	type: RouterErrorType
+	message: string
+	raw?: string
+	details?: unknown
+}) => void
+
+// ============================================================================
+// Message Router
+// ============================================================================
+
+/**
+ * Message router for handling incoming notifications and sending outbound notifications.
+ *
+ * Simplified notification-only router:
+ * - No request-response correlation
+ * - No pending requests tracking
+ * - Fire-and-forget notifications only
+ */
+/**
+ * Raw message listener — receives every parsed message before handler dispatch.
+ */
+export type RawMessageListener = (type: string, payload: unknown) => void
+
+export class MessageRouter<TReceive extends ProtocolDef, TSend extends ProtocolDef> {
+	private readonly receiveProtocol: Protocol<TReceive> | null
+	private readonly sendProtocol: Protocol<TSend> | null
+
+	private handlers: Partial<ProtocolHandlers<TReceive>> = {}
+	private sender: MessageSender | null = null
+	private errorHandler: RouterErrorHandler | null = null
+	private rawMessageListener: RawMessageListener | null = null
+
+	constructor(
+		receiveProtocol: Protocol<TReceive> | null,
+		sendProtocol: Protocol<TSend> | null,
+	) {
+		this.receiveProtocol = receiveProtocol
+		this.sendProtocol = sendProtocol
+	}
+
+	/**
+	 * Set the message sender function.
+	 */
+	setSender(sender: MessageSender): void {
+		this.sender = sender
+	}
+
+	/**
+	 * Set handlers for incoming notifications.
+	 */
+	setHandlers(handlers: Partial<ProtocolHandlers<TReceive>>): void {
+		this.handlers = handlers
+	}
+
+	/**
+	 * Set error handler for debugging protocol issues.
+	 */
+	setErrorHandler(handler: RouterErrorHandler): void {
+		this.errorHandler = handler
+	}
+
+	/**
+	 * Set a raw message listener that receives every incoming message.
+	 * When set, bypasses per-type handler dispatch — the listener receives (type, payload) directly.
+	 */
+	setRawMessageListener(listener: RawMessageListener): void {
+		this.rawMessageListener = listener
+	}
+
+	/**
+	 * Handle an incoming raw message (notification).
+	 */
+	async handleMessage(raw: string, ctx: HandlerContext): Promise<void> {
+		let parsed: WireMessage
+		try {
+			parsed = JSON.parse(raw)
+		} catch (e) {
+			this.errorHandler?.({ type: 'parse', message: 'Invalid JSON', raw, details: e })
+			return
+		}
+
+		const { type, payload } = parsed
+
+		// Raw listener mode — forward everything without dispatch or validation
+		if (this.rawMessageListener) {
+			this.rawMessageListener(type, payload)
+			return
+		}
+
+		if (this.receiveProtocol) {
+			// Validated path — protocol provided, validate input before dispatching
+			const endpoint = this.receiveProtocol._def[type]
+			if (!endpoint) {
+				this.errorHandler?.({ type: 'unknown_type', message: `Unknown message type: ${type}`, raw })
+				return
+			}
+
+			const inputResult = this.receiveProtocol.validateInput(type, payload)
+			if (!inputResult.success) {
+				this.errorHandler?.({ type: 'validation', message: `Validation failed for ${type}`, raw, details: inputResult.error })
+				return
+			}
+
+			const handler = this.handlers[type]
+			if (!handler) return
+
+			try {
+				await (handler as (input: unknown, ctx: HandlerContext) => Promise<void>)(inputResult.data, ctx)
+			} catch (e) {
+				this.errorHandler?.({ type: 'handler', message: `Handler error for ${type}`, raw, details: e })
+			}
+		} else {
+			// Unvalidated path — no protocol, dispatch directly (trusted source)
+			const handler = this.handlers[type]
+			if (!handler) return
+
+			try {
+				await (handler as (input: unknown, ctx: HandlerContext) => Promise<void>)(payload, ctx)
+			} catch (e) {
+				this.errorHandler?.({ type: 'handler', message: `Handler error for ${type}`, raw, details: e })
+			}
+		}
+	}
+
+	/**
+	 * Send a notification (fire-and-forget).
+	 */
+	notify<K extends keyof TSend>(
+		name: K,
+		input: TSend[K] extends { input: infer I } ? (I extends { _type: string } ? never : InferInput<TSend[K]>) : never,
+	): boolean {
+		if (!this.sender) {
+			return false
+		}
+
+		const message: WireMessage = {
+			type: String(name),
+			payload: input,
+			ts: Date.now(),
+		}
+
+		return this.sender(JSON.stringify(message))
+	}
+}
+
+// ============================================================================
+// Router Builder
+// ============================================================================
+
+/**
+ * Create a message router for the given protocols.
+ */
+export function createRouter<TReceive extends ProtocolDef, TSend extends ProtocolDef>(
+	receiveProtocol: Protocol<TReceive> | null,
+	sendProtocol: Protocol<TSend> | null,
+): MessageRouter<TReceive, TSend> {
+	return new MessageRouter(receiveProtocol, sendProtocol)
+}

package/src/core/types.ts

@@ -0,0 +1,85 @@
+/**
+ * Core Transport Types
+ *
+ * Platform-agnostic types for WebSocket transport infrastructure.
+ */
+
+// ============================================================================
+// Connection States
+// ============================================================================
+
+/**
+ * Connection state machine states.
+ */
+export type ConnectionState =
+	| 'disconnected'
+	| 'connecting'
+	| 'connected'
+	| 'reconnecting'
+
+// ============================================================================
+// Wire Message Format
+// ============================================================================
+
+/**
+ * Wire message envelope for all protocol messages.
+ * Simplified: notification-only, no correlation ID.
+ */
+export interface WireMessage<T = unknown> {
+	/** Notification type name */
+	type: string
+	/** Message payload */
+	payload: T
+	/** Timestamp */
+	ts: number
+}
+
+// ============================================================================
+// Transport Events
+// ============================================================================
+
+/**
+ * Transport event types.
+ */
+export type TransportEvent =
+	| 'connected'
+	| 'disconnected'
+	| 'error'
+	| 'reconnecting'
+	| 'reconnected'
+	| 'state_change'
+	| 'router_error'
+
+/**
+ * Transport event listener.
+ */
+export type TransportEventListener = (event: TransportEvent, data?: unknown) => void
+
+// ============================================================================
+// Configuration
+// ============================================================================
+
+/**
+ * Reconnection strategy options.
+ */
+export interface ReconnectOptions {
+	/** Base delay in ms (default: 1000) */
+	baseDelayMs: number
+	/** Maximum delay in ms (default: 30000) */
+	maxDelayMs: number
+	/** Maximum number of attempts before giving up (default: Infinity) */
+	maxAttempts: number
+	/** Jitter factor (0-1, default: 0.3) */
+	jitterFactor: number
+}
+
+// ============================================================================
+// Default Values
+// ============================================================================
+
+export const DEFAULT_RECONNECT_OPTIONS: ReconnectOptions = {
+	baseDelayMs: 1000,
+	maxDelayMs: 30000,
+	maxAttempts: Infinity,
+	jitterFactor: 0.3,
+}

package/src/index.ts

@@ -0,0 +1,80 @@
+/**
+ * @roj-ai/transport
+ *
+ * Platform-agnostic WebSocket transport infrastructure with RPC-like protocol API.
+ */
+
+// ============================================================================
+// Core Exports
+// ============================================================================
+
+// Protocol Definition API
+export { defineProtocol, method, notification } from './core/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 './core/protocol.js'
+
+// Result Type
+export { Err, flatMapResult, isErr, isOk, mapResult, Ok, unwrapOr, unwrapOrThrow } from './core/result.js'
+export type { Result } from './core/result.js'
+
+// Types
+export type { ConnectionState, ReconnectOptions, TransportEvent, TransportEventListener, WireMessage } from './core/types.js'
+
+export { DEFAULT_RECONNECT_OPTIONS } from './core/types.js'
+
+// Core Components
+export { createRouter, MessageRouter } from './core/router.js'
+export type { MessageSender, RawMessageListener, RouterErrorHandler, RouterErrorType } from './core/router.js'
+
+export { Connection } from './core/connection.js'
+export type { ConnectionConfig } from './core/connection.js'
+
+// ============================================================================
+// Platform Exports
+// ============================================================================
+
+export type { ICloseEvent, IServerWebSocket, IWebSocket, IWebSocketFactory } from './platform/types.js'
+
+export { WebSocketReadyState } from './platform/types.js'
+
+// ============================================================================
+// Client Exports
+// ============================================================================
+
+export { ClientConnection, createClientConnection } from './client/client-connection.js'
+export type { ClientConnectionConfig } from './client/client-connection.js'
+
+// ============================================================================
+// Server Exports
+// ============================================================================
+
+export { createServerConnection, ServerConnection } from './server/server-connection.js'
+export type { ServerConnectionConfig, ServerHandlerContext } from './server/server-connection.js'
+
+export { ConnectionManager } from './server/connection-manager.js'
+export type { ConnectionStats } from './server/connection-manager.js'

package/src/platform/browser.ts

@@ -0,0 +1,79 @@
+/**
+ * Browser WebSocket Adapter
+ *
+ * Wraps the native browser WebSocket to conform to IWebSocket interface.
+ */
+
+import type { ICloseEvent, IWebSocket, IWebSocketFactory } from './types.js'
+import { WebSocketReadyState } from './types.js'
+
+/**
+ * Browser WebSocket adapter that wraps native WebSocket.
+ */
+class BrowserWebSocketAdapter implements IWebSocket {
+	private readonly ws: WebSocket
+
+	onopen: (() => void) | null = null
+	onclose: ((event: ICloseEvent) => void) | null = null
+	onerror: ((error: Error) => void) | null = null
+	onmessage: ((data: string) => void) | null = null
+
+	constructor(url: string) {
+		this.ws = new WebSocket(url)
+
+		this.ws.onopen = () => {
+			this.onopen?.()
+		}
+
+		this.ws.onclose = (event) => {
+			this.onclose?.({
+				code: event.code,
+				reason: event.reason,
+			})
+		}
+
+		this.ws.onerror = () => {
+			// Browser WebSocket doesn't provide error details
+			this.onerror?.(new Error('WebSocket error'))
+		}
+
+		this.ws.onmessage = (event) => {
+			// Handle text data only
+			if (typeof event.data === 'string') {
+				this.onmessage?.(event.data)
+			} else if (event.data instanceof Blob) {
+				// Convert Blob to string for text-only protocol
+				event.data.text().then((text) => {
+					this.onmessage?.(text)
+				})
+			}
+		}
+	}
+
+	get readyState(): WebSocketReadyState {
+		return this.ws.readyState as WebSocketReadyState
+	}
+
+	send(data: string): void {
+		if (this.ws.readyState === WebSocketReadyState.OPEN) {
+			this.ws.send(data)
+		}
+	}
+
+	close(code?: number, reason?: string): void {
+		this.ws.close(code, reason)
+	}
+}
+
+/**
+ * Browser WebSocket factory.
+ */
+export const browserWebSocketFactory: IWebSocketFactory = {
+	create(url: string): IWebSocket {
+		return new BrowserWebSocketAdapter(url)
+	},
+}
+
+// Re-export types for convenience
+export { WebSocketReadyState }
+export type { ICloseEvent, IWebSocket, IWebSocketFactory }

package/src/platform/bun.ts

@@ -0,0 +1,220 @@
+/**
+ * Bun WebSocket Adapters
+ *
+ * Provides both client and server WebSocket adapters for Bun runtime.
+ */
+
+import type { ICloseEvent, IServerWebSocket, IWebSocket, IWebSocketFactory } from './types.js'
+import { WebSocketReadyState } from './types.js'
+
+// Type for Bun's native WebSocket
+type BunWebSocket = WebSocket
+
+/**
+ * Bun WebSocket client adapter.
+ * Wraps Bun's WebSocket client to conform to IWebSocket interface.
+ */
+class BunWebSocketClientAdapter implements IWebSocket {
+	private readonly ws: BunWebSocket
+
+	onopen: (() => void) | null = null
+	onclose: ((event: ICloseEvent) => void) | null = null
+	onerror: ((error: Error) => void) | null = null
+	onmessage: ((data: string) => void) | null = null
+
+	constructor(url: string) {
+		this.ws = new WebSocket(url)
+
+		this.ws.onopen = () => {
+			this.onopen?.()
+		}
+
+		this.ws.onclose = (event) => {
+			this.onclose?.({
+				code: event.code,
+				reason: event.reason,
+			})
+		}
+
+		this.ws.onerror = () => {
+			this.onerror?.(new Error('WebSocket error'))
+		}
+
+		this.ws.onmessage = (event) => {
+			if (typeof event.data === 'string') {
+				this.onmessage?.(event.data)
+			}
+		}
+	}
+
+	get readyState(): WebSocketReadyState {
+		return this.ws.readyState as WebSocketReadyState
+	}
+
+	send(data: string): void {
+		if (this.ws.readyState === WebSocketReadyState.OPEN) {
+			this.ws.send(data)
+		}
+	}
+
+	close(code?: number, reason?: string): void {
+		this.ws.close(code, reason)
+	}
+}
+
+/**
+ * Bun WebSocket client factory.
+ */
+export const bunWebSocketFactory: IWebSocketFactory = {
+	create(url: string): IWebSocket {
+		return new BunWebSocketClientAdapter(url)
+	},
+}
+
+/**
+ * Server WebSocket data interface.
+ */
+export interface ServerWebSocketData<T = unknown> {
+	/** User-attached data */
+	userData: T
+	/** Topics this connection is subscribed to */
+	topics: Set<string>
+}
+
+// Using 'any' here because Bun's ServerWebSocket has complex generics
+// that would require importing Bun types directly
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type BunServerWebSocket = any
+
+/**
+ * Bun server WebSocket adapter.
+ * Wraps Bun's ServerWebSocket to conform to IServerWebSocket interface.
+ */
+export class BunServerWebSocketAdapter<T = unknown> implements IServerWebSocket<T> {
+	private readonly ws: BunServerWebSocket
+	private wsData: ServerWebSocketData<T>
+
+	onopen: (() => void) | null = null
+	onclose: ((event: ICloseEvent) => void) | null = null
+	onerror: ((error: Error) => void) | null = null
+	onmessage: ((data: string) => void) | null = null
+
+	constructor(ws: BunServerWebSocket, data: T) {
+		this.ws = ws
+		this.wsData = {
+			userData: data,
+			topics: new Set(),
+		}
+	}
+
+	get data(): T {
+		return this.wsData.userData
+	}
+
+	set data(value: T) {
+		this.wsData.userData = value
+	}
+
+	get readyState(): WebSocketReadyState {
+		return this.ws.readyState as WebSocketReadyState
+	}
+
+	send(data: string): void {
+		if (this.ws.readyState === WebSocketReadyState.OPEN) {
+			this.ws.send(data)
+		}
+	}
+
+	close(code?: number, reason?: string): void {
+		this.ws.close(code, reason)
+	}
+
+	subscribe(topic: string): void {
+		this.ws.subscribe(topic)
+		this.wsData.topics.add(topic)
+	}
+
+	unsubscribe(topic: string): void {
+		this.ws.unsubscribe(topic)
+		this.wsData.topics.delete(topic)
+	}
+
+	publish(topic: string, message: string): void {
+		this.ws.publish(topic, message)
+	}
+
+	isSubscribed(topic: string): boolean {
+		return this.wsData.topics.has(topic)
+	}
+
+	/**
+	 * Get the underlying Bun WebSocket (for advanced use cases).
+	 */
+	getRawWebSocket(): BunServerWebSocket {
+		return this.ws
+	}
+}
+
+/**
+ * Helper to create Bun WebSocket handlers that integrate with the transport layer.
+ */
+export interface BunWebSocketHandlers<T> {
+	open: (ws: BunServerWebSocket) => void
+	close: (ws: BunServerWebSocket, code: number, reason: string) => void
+	message: (ws: BunServerWebSocket, message: string | Buffer) => void
+	error: (ws: BunServerWebSocket, error: Error) => void
+}
+
+/**
+ * Create Bun WebSocket handlers with adapter integration.
+ */
+export function createBunWebSocketHandlers<T>(callbacks: {
+	onOpen: (ws: IServerWebSocket<T>) => void
+	onClose: (ws: IServerWebSocket<T>, code: number, reason: string) => void
+	onMessage: (ws: IServerWebSocket<T>, message: string) => void
+	onError: (ws: IServerWebSocket<T>, error: Error) => void
+	getData: (ws: BunServerWebSocket) => T
+}): BunWebSocketHandlers<T> {
+	// Map to store adapter instances
+	const adapters = new WeakMap<BunServerWebSocket, BunServerWebSocketAdapter<T>>()
+
+	const getOrCreateAdapter = (ws: BunServerWebSocket): BunServerWebSocketAdapter<T> => {
+		let adapter = adapters.get(ws)
+		if (!adapter) {
+			adapter = new BunServerWebSocketAdapter(ws, callbacks.getData(ws))
+			adapters.set(ws, adapter)
+		}
+		return adapter
+	}
+
+	return {
+		open(ws: BunServerWebSocket) {
+			const adapter = getOrCreateAdapter(ws)
+			callbacks.onOpen(adapter)
+		},
+
+		close(ws: BunServerWebSocket, code: number, reason: string) {
+			const adapter = adapters.get(ws)
+			if (adapter) {
+				callbacks.onClose(adapter, code, reason)
+				adapters.delete(ws)
+			}
+		},
+
+		message(ws: BunServerWebSocket, message: string | Buffer) {
+			const adapter = getOrCreateAdapter(ws)
+			// Convert Buffer to string if needed
+			const data = typeof message === 'string' ? message : message.toString('utf-8')
+			callbacks.onMessage(adapter, data)
+		},
+
+		error(ws: BunServerWebSocket, error: Error) {
+			const adapter = getOrCreateAdapter(ws)
+			callbacks.onError(adapter, error)
+		},
+	}
+}
+
+// Re-export types for convenience
+export { WebSocketReadyState }
+export type { ICloseEvent, IServerWebSocket, IWebSocket, IWebSocketFactory }