@louloulinx/metagpt 0.1.3

package/src/websocket/browser-client.ts

@@ -0,0 +1,187 @@
+import type { Message } from '../types/message';
+import {
+  WebSocketMessageSchema,
+  WebSocketMessageType,
+} from './types';
+import type {
+  WebSocketClient,
+  WebSocketClientOptions,
+  WebSocketMessage,
+  WebSocketStreamOptions,
+} from './types';
+
+/**
+ * Browser-compatible WebSocket client implementation
+ * 
+ * Features:
+ * - Uses native browser WebSocket API
+ * - Automatic reconnection with configurable attempts and intervals
+ * - Message validation using Zod schema
+ * - Support for streaming large messages in chunks
+ * - Progress tracking for streaming operations
+ * - Error handling and event callbacks
+ */
+export class BrowserWebSocketClient implements WebSocketClient {
+  private ws: WebSocket | null = null;
+  private reconnectAttempts = 0;
+  private reconnectTimeout: number | null = null;
+
+  /**
+   * Create a new browser WebSocket client instance
+   * @param options - Configuration options for the client
+   */
+  constructor(private options: WebSocketClientOptions) {
+    this.options = {
+      reconnect: true,
+      reconnectInterval: 1000,
+      maxReconnectAttempts: 5,
+      ...options,
+    };
+  }
+
+  /**
+   * Connect to WebSocket server with automatic reconnection support
+   * @throws Error if connection fails and max reconnection attempts are reached
+   */
+  public async connect(): Promise<void> {
+    return new Promise((resolve, reject) => {
+      try {
+        this.ws = new WebSocket(this.options.url, this.options.protocols);
+
+        // Handle successful connection
+        this.ws.onopen = () => {
+          this.reconnectAttempts = 0;
+          this.options.onConnect?.();
+          resolve();
+        };
+
+        // Handle incoming messages with validation
+        this.ws.onmessage = (event: MessageEvent) => {
+          try {
+            const message = WebSocketMessageSchema.parse(JSON.parse(event.data));
+            this.options.onMessage?.(message);
+          } catch (error: unknown) {
+            const message = error instanceof Error ? error.message : String(error);
+            this.options.onError?.(new Error(`Invalid message format: ${message}`));
+          }
+        };
+
+        // Handle connection errors
+        this.ws.onerror = (event: Event) => {
+          const error = new Error('WebSocket connection error');
+          this.options.onError?.(error);
+          reject(error);
+        };
+
+        // Handle disconnection and reconnection
+        this.ws.onclose = () => {
+          this.options.onDisconnect?.();
+          if (this.options.reconnect && this.reconnectAttempts < this.options.maxReconnectAttempts!) {
+            this.reconnectTimeout = window.setTimeout(() => {
+              this.reconnectAttempts++;
+              this.connect().catch(error => {
+                if (error instanceof Error) {
+                  this.options.onError?.(error);
+                } else {
+                  this.options.onError?.(new Error(String(error)));
+                }
+              });
+            }, this.options.reconnectInterval);
+          }
+        };
+      } catch (error: unknown) {
+        if (error instanceof Error) {
+          reject(error);
+        } else {
+          reject(new Error(String(error)));
+        }
+      }
+    });
+  }
+
+  /**
+   * Disconnect from WebSocket server and cleanup resources
+   */
+  public async disconnect(): Promise<void> {
+    if (this.reconnectTimeout !== null) {
+      window.clearTimeout(this.reconnectTimeout);
+      this.reconnectTimeout = null;
+    }
+
+    if (this.ws) {
+      this.ws.close();
+      this.ws = null;
+    }
+  }
+
+  /**
+   * Send a message to the WebSocket server
+   * @param message - Message to send (either Message or WebSocketMessage format)
+   * @throws Error if client is not connected
+   */
+  public async send(message: Message | WebSocketMessage): Promise<void> {
+    if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+      throw new Error('WebSocket is not connected');
+    }
+
+    const wsMessage = 'type' in message ? message : {
+      type: WebSocketMessageType.MESSAGE,
+      payload: message,
+      timestamp: Date.now(),
+      id: crypto.randomUUID(),
+    };
+
+    this.ws.send(JSON.stringify(wsMessage));
+  }
+
+  /**
+   * Stream a large message in chunks with progress tracking
+   * @param message - Message to stream
+   * @param options - Streaming options (chunk size, delay, progress callback)
+   * @yields Each chunk of the message
+   */
+  public async *stream(
+    message: Message,
+    options: WebSocketStreamOptions = {}
+  ): AsyncIterableIterator<string> {
+    const {
+      chunkSize = 1024,
+      delay = 0,
+      onProgress,
+    } = options;
+
+    const content = message.content;
+    const totalChunks = Math.ceil(content.length / chunkSize);
+
+    for (let i = 0; i < totalChunks; i++) {
+      const chunk = content.slice(i * chunkSize, (i + 1) * chunkSize);
+      const progress = Math.round(((i + 1) / totalChunks) * 100);
+
+      await this.send({
+        type: i === totalChunks - 1 ? WebSocketMessageType.STREAM_END : WebSocketMessageType.STREAM,
+        payload: {
+          ...message,
+          content: chunk,
+          progress,
+        },
+        timestamp: Date.now(),
+        id: crypto.randomUUID(),
+      });
+
+      onProgress?.(progress);
+      yield chunk;
+
+      if (delay > 0) {
+        await new Promise(resolve => setTimeout(resolve, delay));
+      }
+    }
+  }
+
+  /**
+   * Check if client is currently connected to the server
+   * @returns true if connected, false otherwise
+   */
+  public isConnected(): boolean {
+    return this.ws?.readyState === WebSocket.OPEN;
+  }
+} 

package/src/websocket/client.ts

@@ -0,0 +1,186 @@
+import WebSocket from 'ws';
+import type { Message } from '../types/message';
+import {
+  WebSocketMessageSchema,
+  WebSocketMessageType,
+} from './types';
+import type {
+  WebSocketClient,
+  WebSocketClientOptions,
+  WebSocketMessage,
+  WebSocketStreamOptions,
+} from './types';
+
+/**
+ * WebSocket client implementation with reconnection and streaming support
+ * 
+ * Features:
+ * - Automatic reconnection with configurable attempts and intervals
+ * - Message validation using Zod schema
+ * - Support for streaming large messages in chunks
+ * - Progress tracking for streaming operations
+ * - Error handling and event callbacks
+ */
+export class WebSocketClientImpl implements WebSocketClient {
+  private ws: WebSocket | null = null;
+  private reconnectAttempts = 0;
+  private reconnectTimeout: ReturnType<typeof setTimeout> | null = null;
+
+  /**
+   * Create a new WebSocket client instance
+   * @param options - Configuration options for the client
+   */
+  constructor(private options: WebSocketClientOptions) {
+    this.options = {
+      reconnect: true,
+      reconnectInterval: 1000,
+      maxReconnectAttempts: 5,
+      ...options,
+    };
+  }
+
+  /**
+   * Connect to WebSocket server with automatic reconnection support
+   * @throws Error if connection fails and max reconnection attempts are reached
+   */
+  public async connect(): Promise<void> {
+    return new Promise((resolve, reject) => {
+      try {
+        this.ws = new WebSocket(this.options.url, this.options.protocols);
+
+        // Handle successful connection
+        this.ws.on('open', () => {
+          this.reconnectAttempts = 0;
+          this.options.onConnect?.();
+          resolve();
+        });
+
+        // Handle incoming messages with validation
+        this.ws.on('message', (data: string) => {
+          try {
+            const message = WebSocketMessageSchema.parse(JSON.parse(data));
+            this.options.onMessage?.(message);
+          } catch (error: unknown) {
+            const message = error instanceof Error ? error.message : String(error);
+            this.options.onError?.(new Error(`Invalid message format: ${message}`));
+          }
+        });
+
+        // Handle connection errors
+        this.ws.on('error', (error: Error) => {
+          this.options.onError?.(error);
+          reject(error);
+        });
+
+        // Handle disconnection and reconnection
+        this.ws.on('close', () => {
+          this.options.onDisconnect?.();
+          if (this.options.reconnect && this.reconnectAttempts < this.options.maxReconnectAttempts!) {
+            this.reconnectTimeout = setTimeout(() => {
+              this.reconnectAttempts++;
+              this.connect().catch(error => {
+                if (error instanceof Error) {
+                  this.options.onError?.(error);
+                } else {
+                  this.options.onError?.(new Error(String(error)));
+                }
+              });
+            }, this.options.reconnectInterval);
+          }
+        });
+      } catch (error: unknown) {
+        if (error instanceof Error) {
+          reject(error);
+        } else {
+          reject(new Error(String(error)));
+        }
+      }
+    });
+  }
+
+  /**
+   * Disconnect from WebSocket server and cleanup resources
+   */
+  public async disconnect(): Promise<void> {
+    if (this.reconnectTimeout) {
+      clearTimeout(this.reconnectTimeout);
+      this.reconnectTimeout = null;
+    }
+
+    if (this.ws) {
+      this.ws.close();
+      this.ws = null;
+    }
+  }
+
+  /**
+   * Send a message to the WebSocket server
+   * @param message - Message to send (either Message or WebSocketMessage format)
+   * @throws Error if client is not connected
+   */
+  public async send(message: Message | WebSocketMessage): Promise<void> {
+    if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+      throw new Error('WebSocket is not connected');
+    }
+
+    const wsMessage = 'type' in message ? message : {
+      type: WebSocketMessageType.MESSAGE,
+      payload: message,
+      timestamp: Date.now(),
+      id: crypto.randomUUID(),
+    };
+
+    this.ws.send(JSON.stringify(wsMessage));
+  }
+
+  /**
+   * Stream a large message in chunks with progress tracking
+   * @param message - Message to stream
+   * @param options - Streaming options (chunk size, delay, progress callback)
+   * @yields Each chunk of the message
+   */
+  public async *stream(
+    message: Message,
+    options: WebSocketStreamOptions = {}
+  ): AsyncIterableIterator<string> {
+    const {
+      chunkSize = 1024,
+      delay = 0,
+      onProgress,
+    } = options;
+
+    const content = message.content;
+    const totalChunks = Math.ceil(content.length / chunkSize);
+
+    for (let i = 0; i < totalChunks; i++) {
+      const chunk = content.slice(i * chunkSize, (i + 1) * chunkSize);
+      const progress = Math.round(((i + 1) / totalChunks) * 100);
+
+      await this.send({
+        type: i === totalChunks - 1 ? WebSocketMessageType.STREAM_END : WebSocketMessageType.STREAM,
+        payload: {
+          ...message,
+          content: chunk,
+          progress,
+        },
+        timestamp: Date.now(),
+        id: crypto.randomUUID(),
+      });
+
+      onProgress?.(progress);
+      yield chunk;
+
+      if (delay > 0) {
+        await new Promise(resolve => setTimeout(resolve, delay));
+      }
+    }
+  }
+
+  /**
+   * Check if client is currently connected to the server
+   * @returns true if connected, false otherwise
+   */
+  public isConnected(): boolean {
+    return this.ws?.readyState === WebSocket.OPEN;
+  }
+} 

package/src/websocket/server.ts

@@ -0,0 +1,169 @@
+import { WebSocketServer as WSServer } from 'ws';
+import type { Message } from '../types/message';
+import {
+  WebSocketMessageSchema,
+  WebSocketMessageType,
+} from './types';
+import type {
+  WebSocketMessage,
+  WebSocketServer,
+  WebSocketServerOptions,
+} from './types';
+
+/**
+ * WebSocket server implementation with client management and broadcasting support
+ * 
+ * Features:
+ * - Client connection management
+ * - Message validation using Zod schema
+ * - Broadcasting to all connected clients
+ * - Automatic cleanup of disconnected clients
+ * - Error handling and event callbacks
+ */
+export class WebSocketServerImpl implements WebSocketServer {
+  private wss: WSServer | null = null;
+  private clients: Set<WebSocket> = new Set();
+
+  /**
+   * Create a new WebSocket server instance
+   * @param options - Configuration options for the server
+   */
+  constructor(private options: WebSocketServerOptions) {}
+
+  /**
+   * Start the WebSocket server and begin accepting connections
+   * @throws Error if server fails to start
+   */
+  public async start(): Promise<void> {
+    return new Promise((resolve, reject) => {
+      try {
+        this.wss = new WSServer({
+          port: this.options.port,
+          host: this.options.host,
+          path: this.options.path,
+        });
+
+        // Handle new client connections
+        this.wss.on('connection', (client: WebSocket) => {
+          this.clients.add(client);
+          this.options.onConnection?.(client);
+
+          // Handle incoming messages with validation
+          client.on('message', async (data: string) => {
+            try {
+              const message = WebSocketMessageSchema.parse(JSON.parse(data));
+              this.options.onMessage?.(message, client);
+            } catch (error: unknown) {
+              const message = error instanceof Error ? error.message : String(error);
+              this.options.onError?.(new Error(`Invalid message format: ${message}`));
+            }
+          });
+
+          // Remove client on disconnection
+          client.on('close', () => {
+            this.clients.delete(client);
+          });
+
+          // Handle client errors and cleanup
+          client.on('error', (error: Error) => {
+            this.options.onError?.(error);
+            this.clients.delete(client);
+          });
+        });
+
+        // Handle server errors
+        this.wss.on('error', (error: Error) => {
+          this.options.onError?.(error);
+          reject(error);
+        });
+
+        // Server is ready to accept connections
+        this.wss.on('listening', () => {
+          resolve();
+        });
+      } catch (error: unknown) {
+        if (error instanceof Error) {
+          reject(error);
+        } else {
+          reject(new Error(String(error)));
+        }
+      }
+    });
+  }
+
+  /**
+   * Stop the WebSocket server and close all client connections
+   * @throws Error if server fails to stop cleanly
+   */
+  public async stop(): Promise<void> {
+    return new Promise((resolve, reject) => {
+      if (!this.wss) {
+        resolve();
+        return;
+      }
+
+      this.wss.close((error) => {
+        if (error) {
+          reject(error);
+        } else {
+          this.wss = null;
+          this.clients.clear();
+          resolve();
+        }
+      });
+    });
+  }
+
+  /**
+   * Broadcast a message to all connected clients
+   * @param message - Message to broadcast (either Message or WebSocketMessage format)
+   * Automatically removes disconnected clients during broadcast
+   */
+  public async broadcast(message: Message | WebSocketMessage): Promise<void> {
+    const wsMessage = 'type' in message ? message : {
+      type: WebSocketMessageType.MESSAGE,
+      payload: message,
+      timestamp: Date.now(),
+      id: crypto.randomUUID(),
+    };
+
+    const data = JSON.stringify(wsMessage);
+    const deadClients = new Set<WebSocket>();
+
+    // Send message to all connected clients
+    for (const client of this.clients) {
+      try {
+        if (client.readyState === WebSocket.OPEN) {
+          client.send(data);
+        } else {
+          deadClients.add(client);
+        }
+      } catch (error: unknown) {
+        const message = error instanceof Error ? error.message : String(error);
+        this.options.onError?.(new Error(`Failed to send message to client: ${message}`));
+        deadClients.add(client);
+      }
+    }
+
+    // Clean up dead clients
+    for (const client of deadClients) {
+      this.clients.delete(client);
+    }
+  }
+
+  /**
+   * Get array of all currently connected clients
+   * @returns Array of WebSocket client instances
+   */
+  public getClients(): WebSocket[] {
+    return Array.from(this.clients);
+  }
+
+  /**
+   * Check if server is currently running
+   * @returns true if server is running, false otherwise
+   */
+  public isRunning(): boolean {
+    return this.wss !== null;
+  }
+} 

package/src/websocket/types.ts

@@ -0,0 +1,125 @@
+import { z } from 'zod';
+import type { Message } from '../types/message';
+
+/**
+ * WebSocket message types for different communication scenarios
+ */
+export enum WebSocketMessageType {
+  /** Connection established */
+  CONNECT = 'connect',
+  /** Connection terminated */
+  DISCONNECT = 'disconnect',
+  /** Regular message */
+  MESSAGE = 'message',
+  /** Error occurred */
+  ERROR = 'error',
+  /** Streaming chunk */
+  STREAM = 'stream',
+  /** End of stream */
+  STREAM_END = 'stream_end',
+}
+
+/**
+ * Schema for WebSocket messages with validation
+ */
+export const WebSocketMessageSchema = z.object({
+  /** Message type from WebSocketMessageType enum */
+  type: z.nativeEnum(WebSocketMessageType),
+  /** Message payload - can be any valid JSON data */
+  payload: z.any(),
+  /** Timestamp of message creation */
+  timestamp: z.number().default(() => Date.now()),
+  /** Unique message identifier */
+  id: z.string().uuid().default(() => crypto.randomUUID()),
+});
+
+/**
+ * WebSocket message type
+ */
+export type WebSocketMessage = z.infer<typeof WebSocketMessageSchema>;
+
+/**
+ * Configuration options for WebSocket client
+ */
+export interface WebSocketClientOptions {
+  /** WebSocket server URL */
+  url: string;
+  /** WebSocket protocols */
+  protocols?: string | string[];
+  /** Whether to attempt reconnection on disconnect */
+  reconnect?: boolean;
+  /** Interval between reconnection attempts in ms */
+  reconnectInterval?: number;
+  /** Maximum number of reconnection attempts */
+  maxReconnectAttempts?: number;
+  /** Callback for received messages */
+  onMessage?: (message: WebSocketMessage) => void;
+  /** Callback for errors */
+  onError?: (error: Error) => void;
+  /** Callback for successful connection */
+  onConnect?: () => void;
+  /** Callback for disconnection */
+  onDisconnect?: () => void;
+}
+
+/**
+ * Configuration options for WebSocket server
+ */
+export interface WebSocketServerOptions {
+  /** Port to listen on */
+  port: number;
+  /** Host to bind to */
+  host?: string;
+  /** URL path for WebSocket endpoint */
+  path?: string;
+  /** Callback for new client connections */
+  onConnection?: (client: WebSocket) => void;
+  /** Callback for received messages */
+  onMessage?: (message: WebSocketMessage, client: WebSocket) => void;
+  /** Callback for errors */
+  onError?: (error: Error) => void;
+}
+
+/**
+ * Options for streaming messages over WebSocket
+ */
+export interface WebSocketStreamOptions {
+  /** Size of each chunk in bytes */
+  chunkSize?: number;
+  /** Delay between chunks in ms */
+  delay?: number;
+  /** Callback for streaming progress */
+  onProgress?: (progress: number) => void;
+}
+
+/**
+ * Interface for WebSocket client implementation
+ */
+export interface WebSocketClient {
+  /** Connect to WebSocket server */
+  connect(): Promise<void>;
+  /** Disconnect from WebSocket server */
+  disconnect(): Promise<void>;
+  /** Send a message */
+  send(message: Message | WebSocketMessage): Promise<void>;
+  /** Stream a message in chunks */
+  stream(message: Message, options?: WebSocketStreamOptions): AsyncIterableIterator<string>;
+  /** Check connection status */
+  isConnected(): boolean;
+}
+
+/**
+ * Interface for WebSocket server implementation
+ */
+export interface WebSocketServer {
+  /** Start the WebSocket server */
+  start(): Promise<void>;
+  /** Stop the WebSocket server */
+  stop(): Promise<void>;
+  /** Broadcast a message to all clients */
+  broadcast(message: Message | WebSocketMessage): Promise<void>;
+  /** Get list of connected clients */
+  getClients(): WebSocket[];
+  /** Check server status */
+  isRunning(): boolean;
+}