@utsp/network-server 0.1.1

package/README.md

@@ -0,0 +1,36 @@
+# @utsp/network-server
+
+> ⚠️ **PROTOTYPE - NOT READY FOR PRODUCTION**
+>
+> This package is currently in early development and should **NOT** be used in production.
+> The API is unstable and subject to breaking changes without notice.
+
+Server-side network communication layer for UTSP (Universal Text Stream Protocol).
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## ⚠️ Development Status
+
+**This is a prototype package under active development.**
+
+- ❌ No stable API
+- ❌ No documentation available yet
+- ❌ Breaking changes expected
+- ❌ Not recommended for production use
+
+**Please check back later for updates or watch the repository for release announcements.**
+
+## Installation
+
+```bash
+npm install @utsp/network-server
+```
+
+## Repository
+
+- [GitHub](https://github.com/thp-software/utsp)
+- [Issues](https://github.com/thp-software/utsp/issues)
+
+## License
+
+MIT © 2025 Thomas Piquet

package/dist/index.cjs

@@ -0,0 +1 @@
+"use strict";var o=Object.defineProperty;var u=Object.getOwnPropertyDescriptor;var m=Object.getOwnPropertyNames;var f=Object.prototype.hasOwnProperty;var S=(r,e,t)=>e in r?o(r,e,{enumerable:!0,configurable:!0,writable:!0,value:t}):r[e]=t;var h=(r,e)=>o(r,"name",{value:e,configurable:!0});var C=(r,e)=>{for(var t in e)o(r,t,{get:e[t],enumerable:!0})},y=(r,e,t,n)=>{if(e&&typeof e=="object"||typeof e=="function")for(let i of m(e))!f.call(r,i)&&i!==t&&o(r,i,{get:()=>e[i],enumerable:!(n=u(e,i))||n.enumerable});return r};var H=r=>y(o({},"__esModule",{value:!0}),r);var s=(r,e,t)=>(S(r,typeof e!="symbol"?e+"":e,t),t);var $={};C($,{SocketIOServer:()=>a});module.exports=H($);var d=require("socket.io"),g=require("http");var c=class c{constructor(e){s(this,"io",null);s(this,"httpServer",null);s(this,"options");s(this,"running",!1);s(this,"clients",new Map);s(this,"clientData",new Map);s(this,"connectionHandlers",[]);s(this,"disconnectionHandlers",[]);s(this,"eventHandlers",new Map);s(this,"stats",{totalConnections:0,startTime:0});if(!Number.isInteger(e.port)||e.port<0||e.port>65535)throw new Error(`SocketIOServer: Invalid port ${e.port} - must be an integer between 0 and 65535`);if(e.maxConnections!==void 0&&(!Number.isInteger(e.maxConnections)||e.maxConnections<=0))throw new Error(`SocketIOServer: Invalid maxConnections ${e.maxConnections} - must be a positive integer`);if(e.pingInterval!==void 0&&(!Number.isFinite(e.pingInterval)||e.pingInterval<=0))throw new Error(`SocketIOServer: Invalid pingInterval ${e.pingInterval} - must be a positive number`);if(e.pingTimeout!==void 0&&(!Number.isFinite(e.pingTimeout)||e.pingTimeout<=0))throw new Error(`SocketIOServer: Invalid pingTimeout ${e.pingTimeout} - must be a positive number`);this.options={port:e.port,host:e.host??"0.0.0.0",cors:e.cors??{origin:"*"},maxConnections:e.maxConnections??1e3,pingInterval:e.pingInterval??25e3,pingTimeout:e.pingTimeout??5e3,debug:e.debug??!1},this.log("Server initialized",{port:this.options.port,host:this.options.host,maxConnections:this.options.maxConnections})}isRunning(){return this.running}async start(){if(this.running){this.log("Server already running");return}return this.log(`Starting server on ${this.options.host}:${this.options.port}...`),new Promise((e,t)=>{try{this.httpServer=(0,g.createServer)(),this.io=new d.Server(this.httpServer,{cors:this.options.cors,pingInterval:this.options.pingInterval,pingTimeout:this.options.pingTimeout,maxHttpBufferSize:1e6}),this.io.on("connection",n=>{this.handleConnection(n)}),this.httpServer.listen(this.options.port,this.options.host,()=>{this.running=!0,this.stats.startTime=Date.now(),this.log(`Server started on ${this.options.host}:${this.options.port}`),e()}),this.httpServer.on("error",n=>{this.log(`Server error: ${n.message}`),t(n)})}catch(n){t(n)}})}async stop(){if(this.running)return this.log("Stopping server..."),new Promise(e=>{this.clients.forEach(t=>{t.disconnect(!0)}),this.clients.clear(),this.clientData.clear(),this.io&&(this.io.close(()=>{this.log("Socket.IO server closed")}),this.io=null),this.httpServer?(this.httpServer.close(()=>{this.log("HTTP server closed"),this.running=!1,e()}),this.httpServer=null):(this.running=!1,e())})}getClients(){return Array.from(this.clients.keys())}getClientInfo(e){let t=this.clients.get(e);return t?{id:e,connectedAt:t.connectedAt||Date.now(),address:t.handshake.address,data:this.clientData.get(e)||{}}:null}sendToClient(e,t,n){let i=this.clients.get(e);if(!i){this.log(`Cannot send to client ${e}: not found`);return}i.emit(t,n)}sendToClientVolatile(e,t,n){let i=this.clients.get(e);if(!i){this.log(`Cannot send volatile to client ${e}: not found`);return}i.compress(!1).emit(t,n)}broadcast(e,t){this.io&&(this.io.emit(e,t),this.log(`Broadcast '${e}' to all clients`))}broadcastVolatile(e,t){this.io&&(this.io.volatile.emit(e,t),this.log(`Broadcast volatile '${e}' to all clients`))}broadcastExcept(e,t,n){let i=this.clients.get(e);i&&(i.broadcast.emit(t,n),this.log(`Broadcast '${t}' except ${e}`))}sendToRoom(e,t,n){this.io&&(this.io.to(e).emit(t,n),this.log(`Sent '${t}' to room '${e}'`))}joinRoom(e,t){let n=this.clients.get(e);n&&(n.join(t),this.log(`Client ${e} joined room '${t}'`))}leaveRoom(e,t){let n=this.clients.get(e);n&&(n.leave(t),this.log(`Client ${e} left room '${t}'`))}getRoomClients(e){if(!this.io)return[];let t=this.io.sockets.adapter.rooms.get(e);return t?Array.from(t):[]}disconnectClient(e,t="Server disconnect"){let n=this.clients.get(e);n&&(n.disconnect(!0),this.log(`Disconnected client ${e}: ${t}`))}on(e,t){let n=this.eventHandlers.get(e)||[];n.push(t),this.eventHandlers.set(e,n),this.log(`Registered handler for '${e}'`)}onConnect(e){this.connectionHandlers.push(e),this.log("Registered connection handler")}onDisconnect(e){this.disconnectionHandlers.push(e),this.log("Registered disconnection handler")}off(e,t){let n=this.eventHandlers.get(e);if(!n)return;let i=n.indexOf(t);i!==-1&&(n.splice(i,1),this.log(`Removed handler for '${e}'`))}setClientData(e,t,n){let i=this.clientData.get(e)||{};i[t]=n,this.clientData.set(e,i)}getClientData(e,t){let n=this.clientData.get(e);return n?n[t]:void 0}getStats(){return{connectedClients:this.clients.size,totalConnections:this.stats.totalConnections,uptime:Date.now()-this.stats.startTime}}async destroy(){await this.stop(),this.connectionHandlers=[],this.disconnectionHandlers=[],this.eventHandlers.clear(),this.log("Server destroyed")}handleConnection(e){let t=e.id;if(this.log(`Client connected: ${t}`),this.clients.size>=this.options.maxConnections){this.log(`Max connections reached, rejecting ${t}`),e.emit("error",{code:"MAX_CONNECTIONS",message:"Server is full"}),e.disconnect(!0);return}this.clients.set(t,e),this.clientData.set(t,{}),e.connectedAt=Date.now(),this.stats.totalConnections++,this.setupClientHandlers(e),this.connectionHandlers.forEach(n=>{try{n(t)}catch(i){this.log(`Error in connection handler: ${i}`)}}),e.on("ping",()=>{e.emit("pong")})}setupClientHandlers(e){let t=e.id;e.on("disconnect",n=>{this.log(`Client disconnected: ${t} (${n})`),this.clients.delete(t),this.clientData.delete(t),this.disconnectionHandlers.forEach(i=>{try{i(t,n)}catch(l){this.log(`Error in disconnection handler: ${l}`)}})}),this.eventHandlers.forEach((n,i)=>{e.on(i,l=>{n.forEach(v=>{try{v(t,l)}catch(p){this.log(`Error in event handler for '${i}': ${p}`)}})})})}log(e,t){this.options.debug&&(t!==void 0?console.warn(`[SocketIOServer] ${e}`,t):console.warn(`[SocketIOServer] ${e}`))}};h(c,"SocketIOServer");var a=c;0&&(module.exports={SocketIOServer});

package/dist/index.d.ts

@@ -0,0 +1,571 @@
+import { INetworkServer, NetworkServerOptions, ClientInfo, ServerEventHandler, ConnectionHandler, DisconnectionHandler } from '@utsp/types';
+export { AnyNetworkMessage, ChatMessage, ClientInfo, ConnectionHandler, DisconnectionHandler, ErrorMessage, INetworkServer, InputMessage, JoinMessage, JoinResponseMessage, LeaveMessage, LoadMessage, MessageType, NetworkMessage, NetworkServerOptions, PingMessage, PongMessage, ServerEventHandler, UpdateMessage } from '@utsp/types';
+
+/**
+ * Socket.IO Server Implementation
+ *
+ * Production-ready Socket.IO server for UTSP real-time networking.
+ * Implements the INetworkServer interface with room management, client tracking,
+ * and comprehensive event handling. Node.js only.
+ *
+ * @example Basic Server
+ * ```typescript
+ * import { SocketIOServer } from '@utsp/network-server';
+ *
+ * const server = new SocketIOServer({
+ *   port: 3000,
+ *   host: '0.0.0.0',
+ *   debug: false
+ * });
+ *
+ * await server.start();
+ * console.log('Server running on port 3000');
+ *
+ * server.onConnect((clientId) => {
+ *   console.log('Client connected:', clientId);
+ *   server.sendToClient(clientId, 'welcome', { message: 'Hello!' });
+ * });
+ *
+ * server.on('input', (clientId, data) => {
+ *   console.log('Input from', clientId, data);
+ *   server.broadcast('update', data);
+ * });
+ * ```
+ *
+ * @example With Rooms
+ * ```typescript
+ * server.onConnect((clientId) => {
+ *   server.joinRoom(clientId, 'lobby');
+ *   server.sendToRoom('lobby', 'playerJoined', { clientId });
+ * });
+ *
+ * server.on('joinGame', (clientId, { gameId }) => {
+ *   server.leaveRoom(clientId, 'lobby');
+ *   server.joinRoom(clientId, `game-${gameId}`);
+ * });
+ * ```
+ *
+ * @example Client Data Storage
+ * ```typescript
+ * server.onConnect((clientId) => {
+ *   server.setClientData(clientId, 'username', 'Player1');
+ *   server.setClientData(clientId, 'score', 0);
+ * });
+ *
+ * server.on('updateScore', (clientId, { points }) => {
+ *   const currentScore = server.getClientData(clientId, 'score') || 0;
+ *   server.setClientData(clientId, 'score', currentScore + points);
+ * });
+ * ```
+ */
+
+/**
+ * Socket.IO server implementation for UTSP network communication
+ *
+ * Features:
+ * - Connection management with max connections limit
+ * - Room-based broadcasting
+ * - Client data storage per connection
+ * - Volatile messaging for high-frequency updates
+ * - Comprehensive event handling system
+ * - Connection/disconnection lifecycle hooks
+ * - Server statistics tracking
+ * - CORS configuration
+ *
+ * @implements {INetworkServer}
+ */
+declare class SocketIOServer implements INetworkServer {
+    private io;
+    private httpServer;
+    private options;
+    private running;
+    private clients;
+    private clientData;
+    private connectionHandlers;
+    private disconnectionHandlers;
+    private eventHandlers;
+    private stats;
+    /**
+     * Create a new Socket.IO server instance
+     *
+     * @param options - Server configuration options
+     * @throws {Error} If port is invalid or options are malformed
+     *
+     * @example
+     * ```typescript
+     * const server = new SocketIOServer({
+     *   port: 3000,
+     *   host: '0.0.0.0',
+     *   cors: { origin: '*' },
+     *   maxConnections: 1000,
+     *   pingInterval: 25000,
+     *   pingTimeout: 5000,
+     *   debug: true
+     * });
+     * ```
+     */
+    constructor(options: NetworkServerOptions);
+    /**
+     * Check if server is currently running
+     *
+     * @returns true if server is running and accepting connections
+     *
+     * @example
+     * ```typescript
+     * if (server.isRunning()) {
+     *   console.log('Server is active');
+     * }
+     * ```
+     */
+    isRunning(): boolean;
+    /**
+     * Start the server and begin accepting connections
+     *
+     * Creates an HTTP server, initializes Socket.IO, and starts listening
+     * on the configured port and host.
+     *
+     * @returns Promise resolving when server is ready to accept connections
+     * @throws {Error} If server fails to start (port in use, permission denied, etc.)
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   await server.start();
+     *   console.log('Server started successfully');
+     * } catch (error) {
+     *   console.error('Failed to start server:', error);
+     * }
+     * ```
+     */
+    start(): Promise<void>;
+    /**
+     * Stop the server and disconnect all clients
+     *
+     * Gracefully shuts down the server by disconnecting all clients,
+     * closing Socket.IO, and stopping the HTTP server.
+     *
+     * @returns Promise resolving when server is fully stopped
+     *
+     * @example
+     * ```typescript
+     * await server.stop();
+     * console.log('Server stopped');
+     * ```
+     */
+    stop(): Promise<void>;
+    /**
+     * Get list of all connected client IDs
+     *
+     * @returns Array of client socket IDs
+     *
+     * @example
+     * ```typescript
+     * const clients = server.getClients();
+     * console.log(`${clients.length} clients connected`);
+     * ```
+     */
+    getClients(): string[];
+    /**
+     * Get information about a specific client
+     *
+     * @param clientId - Client socket ID
+     * @returns Client information object, or null if client not found
+     *
+     * @example
+     * ```typescript
+     * const info = server.getClientInfo(clientId);
+     * if (info) {
+     *   console.log('Client:', info.id);
+     *   console.log('Connected at:', new Date(info.connectedAt));
+     *   console.log('Address:', info.address);
+     *   console.log('Data:', info.data);
+     * }
+     * ```
+     */
+    getClientInfo(clientId: string): ClientInfo | null;
+    /**
+     * Send an event to a specific client
+     *
+     * Sends a message to a single client identified by their socket ID.
+     * Message is silently dropped if client is not connected.
+     *
+     * @param clientId - Client socket ID
+     * @param event - Event name
+     * @param data - Event payload (any serializable data)
+     *
+     * @example
+     * ```typescript
+     * server.sendToClient(clientId, 'notification', {
+     *   type: 'info',
+     *   message: 'You won!'
+     * });
+     * ```
+     */
+    sendToClient(clientId: string, event: string, data: any): void;
+    /**
+     * Send volatile message to a specific client
+     *
+     * Sends a "volatile" message that can be dropped if the network is congested.
+     * Perfect for high-frequency updates (game state, animations, dynamic layers)
+     * where missing a frame is acceptable.
+     *
+     * **Note:** Uses `.compress(false)` instead of `.volatile` due to Socket.IO limitations.
+     * This disables compression for better performance with frequent updates.
+     *
+     * @param clientId - Client socket ID
+     * @param event - Event name
+     * @param data - Event payload
+     *
+     * @example
+     * ```typescript
+     * // Send 60 updates per second - some can be dropped
+     * setInterval(() => {
+     *   server.sendToClientVolatile(clientId, 'gameState', {
+     *     position: player.position,
+     *     velocity: player.velocity
+     *   });
+     * }, 16); // ~60 FPS
+     * ```
+     */
+    sendToClientVolatile(clientId: string, event: string, data: any): void;
+    /**
+     * Broadcast an event to all connected clients
+     *
+     * Sends a message to every connected client simultaneously.
+     *
+     * @param event - Event name
+     * @param data - Event payload
+     *
+     * @example
+     * ```typescript
+     * server.broadcast('serverMessage', {
+     *   type: 'announcement',
+     *   message: 'Server restarting in 5 minutes'
+     * });
+     * ```
+     */
+    broadcast(event: string, data: any): void;
+    /**
+     * Broadcast volatile message to all clients
+     *
+     * Sends a volatile message to all clients. Messages can be dropped
+     * if the network is congested. Useful for high-frequency broadcasts.
+     *
+     * @param event - Event name
+     * @param data - Event payload
+     *
+     * @example
+     * ```typescript
+     * // Broadcast game tick (60 times per second)
+     * setInterval(() => {
+     *   server.broadcastVolatile('tick', {
+     *     timestamp: Date.now(),
+     *     frame: frameCount++
+     *   });
+     * }, 16);
+     * ```
+     */
+    broadcastVolatile(event: string, data: any): void;
+    /**
+     * Broadcast to all clients except one
+     *
+     * Sends a message to all connected clients except the specified one.
+     * Useful for broadcasting player actions to other players.
+     *
+     * @param excludeClientId - Client ID to exclude from broadcast
+     * @param event - Event name
+     * @param data - Event payload
+     *
+     * @example
+     * ```typescript
+     * // When a player moves, tell everyone else
+     * server.on('playerMove', (clientId, position) => {
+     *   server.broadcastExcept(clientId, 'playerMoved', {
+     *     playerId: clientId,
+     *     position
+     *   });
+     * });
+     * ```
+     */
+    broadcastExcept(excludeClientId: string, event: string, data: any): void;
+    /**
+     * Send event to all clients in a room
+     *
+     * Broadcasts a message to all clients that have joined the specified room.
+     *
+     * @param room - Room name
+     * @param event - Event name
+     * @param data - Event payload
+     *
+     * @example
+     * ```typescript
+     * // Send message to all players in a game
+     * server.sendToRoom('game-123', 'gameUpdate', {
+     *   score: { team1: 10, team2: 8 }
+     * });
+     * ```
+     */
+    sendToRoom(room: string, event: string, data: any): void;
+    /**
+     * Add a client to a room
+     *
+     * Rooms allow grouping clients for targeted broadcasts. A client
+     * can be in multiple rooms simultaneously.
+     *
+     * @param clientId - Client socket ID
+     * @param room - Room name
+     *
+     * @example
+     * ```typescript
+     * // When player joins a game
+     * server.on('joinGame', (clientId, { gameId }) => {
+     *   server.joinRoom(clientId, `game-${gameId}`);
+     *   server.sendToRoom(`game-${gameId}`, 'playerJoined', {
+     *     clientId,
+     *     playerCount: server.getRoomClients(`game-${gameId}`).length
+     *   });
+     * });
+     * ```
+     */
+    joinRoom(clientId: string, room: string): void;
+    /**
+     * Remove a client from a room
+     *
+     * @param clientId - Client socket ID
+     * @param room - Room name
+     *
+     * @example
+     * ```typescript
+     * server.on('leaveGame', (clientId) => {
+     *   server.leaveRoom(clientId, 'game-123');
+     *   server.joinRoom(clientId, 'lobby');
+     * });
+     * ```
+     */
+    leaveRoom(clientId: string, room: string): void;
+    /**
+     * Get list of all client IDs in a room
+     *
+     * @param room - Room name
+     * @returns Array of client socket IDs in the room
+     *
+     * @example
+     * ```typescript
+     * const players = server.getRoomClients('game-123');
+     * console.log(`${players.length} players in game`);
+     * ```
+     */
+    getRoomClients(room: string): string[];
+    /**
+     * Forcefully disconnect a client
+     *
+     * Immediately closes the client's connection. Use sparingly as it
+     * does not allow graceful cleanup on the client side.
+     *
+     * @param clientId - Client socket ID
+     * @param reason - Reason for disconnection (default: 'Server disconnect')
+     *
+     * @example
+     * ```typescript
+     * // Kick idle players
+     * if (isIdle(clientId)) {
+     *   server.disconnectClient(clientId, 'Idle timeout');
+     * }
+     * ```
+     */
+    disconnectClient(clientId: string, reason?: string): void;
+    /**
+     * Register an event listener for client messages
+     *
+     * Handles events sent from clients. Multiple handlers can be registered
+     * for the same event. Handlers receive the client ID and event data.
+     *
+     * @param event - Event name to listen for
+     * @param handler - Callback function (clientId, data) => void
+     *
+     * @example
+     * ```typescript
+     * server.on<InputMessage>('input', (clientId, data) => {
+     *   console.log('Input from', clientId, data);
+     *   // Process input and broadcast to others
+     *   server.broadcastExcept(clientId, 'playerAction', data);
+     * });
+     *
+     * server.on('chat', (clientId, message) => {
+     *   const username = server.getClientData(clientId, 'username');
+     *   server.broadcast('chatMessage', { username, message });
+     * });
+     * ```
+     */
+    on<T = any>(event: string, handler: ServerEventHandler<T>): void;
+    /**
+     * Register a connection handler
+     *
+     * Called whenever a new client successfully connects. Use this to
+     * initialize client state, send welcome messages, etc.
+     *
+     * @param handler - Callback function receiving client ID
+     *
+     * @example
+     * ```typescript
+     * server.onConnect((clientId) => {
+     *   console.log('Client connected:', clientId);
+     *   server.setClientData(clientId, 'joinedAt', Date.now());
+     *   server.joinRoom(clientId, 'lobby');
+     *   server.sendToClient(clientId, 'welcome', {
+     *     message: 'Welcome to the server!',
+     *     serverId: 'game-server-1'
+     *   });
+     * });
+     * ```
+     */
+    onConnect(handler: ConnectionHandler): void;
+    /**
+     * Register a disconnection handler
+     *
+     * Called whenever a client disconnects (gracefully or due to error).
+     * Use this for cleanup and notifying other clients.
+     *
+     * @param handler - Callback function receiving client ID and reason
+     *
+     * @example
+     * ```typescript
+     * server.onDisconnect((clientId, reason) => {
+     *   console.log('Client disconnected:', clientId, reason);
+     *   const username = server.getClientData(clientId, 'username');
+     *   server.broadcast('playerLeft', { username, reason });
+     * });
+     * ```
+     */
+    onDisconnect(handler: DisconnectionHandler): void;
+    /**
+     * Unregister a specific event handler
+     *
+     * Removes a previously registered handler for an event. The handler
+     * reference must be the exact same function object that was registered.
+     *
+     * @param event - Event name
+     * @param handler - Handler function to remove (must be same reference)
+     *
+     * @example
+     * ```typescript
+     * const handler = (clientId, data) => { ... };
+     * server.on('input', handler);
+     * // Later...
+     * server.off('input', handler);
+     * ```
+     */
+    off<T = any>(event: string, handler: ServerEventHandler<T>): void;
+    /**
+     * Store arbitrary data for a client
+     *
+     * Associates key-value data with a client connection. Data is
+     * automatically cleared when the client disconnects.
+     *
+     * @param clientId - Client socket ID
+     * @param key - Data key
+     * @param value - Data value (any serializable type)
+     *
+     * @example
+     * ```typescript
+     * server.onConnect((clientId) => {
+     *   server.setClientData(clientId, 'username', 'Player1');
+     *   server.setClientData(clientId, 'score', 0);
+     *   server.setClientData(clientId, 'team', 'red');
+     * });
+     *
+     * server.on('scorePoint', (clientId) => {
+     *   const score = server.getClientData(clientId, 'score') || 0;
+     *   server.setClientData(clientId, 'score', score + 1);
+     * });
+     * ```
+     */
+    setClientData(clientId: string, key: string, value: any): void;
+    /**
+     * Retrieve stored data for a client
+     *
+     * @param clientId - Client socket ID
+     * @param key - Data key
+     * @returns Stored value, or undefined if not found
+     *
+     * @example
+     * ```typescript
+     * const username = server.getClientData(clientId, 'username');
+     * const score = server.getClientData(clientId, 'score') || 0;
+     * ```
+     */
+    getClientData(clientId: string, key: string): any;
+    /**
+     * Get server statistics
+     *
+     * Returns current server metrics including connected clients,
+     * total connections since start, and uptime.
+     *
+     * @returns Object containing server stats
+     *
+     * @example
+     * ```typescript
+     * const stats = server.getStats();
+     * console.log('Connected:', stats.connectedClients);
+     * console.log('Total connections:', stats.totalConnections);
+     * console.log('Uptime:', Math.floor(stats.uptime / 1000), 'seconds');
+     * ```
+     */
+    getStats(): {
+        connectedClients: number;
+        totalConnections: number;
+        uptime: number;
+    };
+    /**
+     * Destroy the server and clean up all resources
+     *
+     * Stops the server, disconnects all clients, and clears all handlers.
+     * Server instance cannot be reused after calling destroy().
+     *
+     * @returns Promise resolving when cleanup is complete
+     *
+     * @example
+     * ```typescript
+     * // Graceful shutdown
+     * process.on('SIGTERM', async () => {
+     *   console.log('Shutting down...');
+     *   await server.destroy();
+     *   process.exit(0);
+     * });
+     * ```
+     */
+    destroy(): Promise<void>;
+    /**
+     * Handle new client connection
+     *
+     * Called when a client successfully connects. Checks max connections limit,
+     * stores client data, sets up event handlers, and calls connection handlers.
+     *
+     * @param socket - Socket.IO socket instance
+     * @private
+     */
+    private handleConnection;
+    /**
+     * Setup event handlers for a client socket
+     *
+     * Registers disconnect handler and all custom event handlers for this client.
+     * Called once when client connects.
+     *
+     * @param socket - Socket.IO socket instance
+     * @private
+     */
+    private setupClientHandlers;
+    /**
+     * Debug logging utility
+     *
+     * Logs messages when debug mode is enabled. Uses console.warn
+     * to ensure visibility in production environments.
+     *
+     * @param message - Log message
+     * @param data - Optional data to log
+     * @private
+     */
+    private log;
+}
+
+export { SocketIOServer, SocketIOServer as SocketIOServerType };

package/dist/index.mjs

@@ -0,0 +1 @@
+var c=Object.defineProperty;var v=(s,e,t)=>e in s?c(s,e,{enumerable:!0,configurable:!0,writable:!0,value:t}):s[e]=t;var h=(s,e)=>c(s,"name",{value:e,configurable:!0});var r=(s,e,t)=>(v(s,typeof e!="symbol"?e+"":e,t),t);import{Server as p}from"socket.io";import{createServer as u}from"http";var l=class l{constructor(e){r(this,"io",null);r(this,"httpServer",null);r(this,"options");r(this,"running",!1);r(this,"clients",new Map);r(this,"clientData",new Map);r(this,"connectionHandlers",[]);r(this,"disconnectionHandlers",[]);r(this,"eventHandlers",new Map);r(this,"stats",{totalConnections:0,startTime:0});if(!Number.isInteger(e.port)||e.port<0||e.port>65535)throw new Error(`SocketIOServer: Invalid port ${e.port} - must be an integer between 0 and 65535`);if(e.maxConnections!==void 0&&(!Number.isInteger(e.maxConnections)||e.maxConnections<=0))throw new Error(`SocketIOServer: Invalid maxConnections ${e.maxConnections} - must be a positive integer`);if(e.pingInterval!==void 0&&(!Number.isFinite(e.pingInterval)||e.pingInterval<=0))throw new Error(`SocketIOServer: Invalid pingInterval ${e.pingInterval} - must be a positive number`);if(e.pingTimeout!==void 0&&(!Number.isFinite(e.pingTimeout)||e.pingTimeout<=0))throw new Error(`SocketIOServer: Invalid pingTimeout ${e.pingTimeout} - must be a positive number`);this.options={port:e.port,host:e.host??"0.0.0.0",cors:e.cors??{origin:"*"},maxConnections:e.maxConnections??1e3,pingInterval:e.pingInterval??25e3,pingTimeout:e.pingTimeout??5e3,debug:e.debug??!1},this.log("Server initialized",{port:this.options.port,host:this.options.host,maxConnections:this.options.maxConnections})}isRunning(){return this.running}async start(){if(this.running){this.log("Server already running");return}return this.log(`Starting server on ${this.options.host}:${this.options.port}...`),new Promise((e,t)=>{try{this.httpServer=u(),this.io=new p(this.httpServer,{cors:this.options.cors,pingInterval:this.options.pingInterval,pingTimeout:this.options.pingTimeout,maxHttpBufferSize:1e6}),this.io.on("connection",n=>{this.handleConnection(n)}),this.httpServer.listen(this.options.port,this.options.host,()=>{this.running=!0,this.stats.startTime=Date.now(),this.log(`Server started on ${this.options.host}:${this.options.port}`),e()}),this.httpServer.on("error",n=>{this.log(`Server error: ${n.message}`),t(n)})}catch(n){t(n)}})}async stop(){if(this.running)return this.log("Stopping server..."),new Promise(e=>{this.clients.forEach(t=>{t.disconnect(!0)}),this.clients.clear(),this.clientData.clear(),this.io&&(this.io.close(()=>{this.log("Socket.IO server closed")}),this.io=null),this.httpServer?(this.httpServer.close(()=>{this.log("HTTP server closed"),this.running=!1,e()}),this.httpServer=null):(this.running=!1,e())})}getClients(){return Array.from(this.clients.keys())}getClientInfo(e){let t=this.clients.get(e);return t?{id:e,connectedAt:t.connectedAt||Date.now(),address:t.handshake.address,data:this.clientData.get(e)||{}}:null}sendToClient(e,t,n){let i=this.clients.get(e);if(!i){this.log(`Cannot send to client ${e}: not found`);return}i.emit(t,n)}sendToClientVolatile(e,t,n){let i=this.clients.get(e);if(!i){this.log(`Cannot send volatile to client ${e}: not found`);return}i.compress(!1).emit(t,n)}broadcast(e,t){this.io&&(this.io.emit(e,t),this.log(`Broadcast '${e}' to all clients`))}broadcastVolatile(e,t){this.io&&(this.io.volatile.emit(e,t),this.log(`Broadcast volatile '${e}' to all clients`))}broadcastExcept(e,t,n){let i=this.clients.get(e);i&&(i.broadcast.emit(t,n),this.log(`Broadcast '${t}' except ${e}`))}sendToRoom(e,t,n){this.io&&(this.io.to(e).emit(t,n),this.log(`Sent '${t}' to room '${e}'`))}joinRoom(e,t){let n=this.clients.get(e);n&&(n.join(t),this.log(`Client ${e} joined room '${t}'`))}leaveRoom(e,t){let n=this.clients.get(e);n&&(n.leave(t),this.log(`Client ${e} left room '${t}'`))}getRoomClients(e){if(!this.io)return[];let t=this.io.sockets.adapter.rooms.get(e);return t?Array.from(t):[]}disconnectClient(e,t="Server disconnect"){let n=this.clients.get(e);n&&(n.disconnect(!0),this.log(`Disconnected client ${e}: ${t}`))}on(e,t){let n=this.eventHandlers.get(e)||[];n.push(t),this.eventHandlers.set(e,n),this.log(`Registered handler for '${e}'`)}onConnect(e){this.connectionHandlers.push(e),this.log("Registered connection handler")}onDisconnect(e){this.disconnectionHandlers.push(e),this.log("Registered disconnection handler")}off(e,t){let n=this.eventHandlers.get(e);if(!n)return;let i=n.indexOf(t);i!==-1&&(n.splice(i,1),this.log(`Removed handler for '${e}'`))}setClientData(e,t,n){let i=this.clientData.get(e)||{};i[t]=n,this.clientData.set(e,i)}getClientData(e,t){let n=this.clientData.get(e);return n?n[t]:void 0}getStats(){return{connectedClients:this.clients.size,totalConnections:this.stats.totalConnections,uptime:Date.now()-this.stats.startTime}}async destroy(){await this.stop(),this.connectionHandlers=[],this.disconnectionHandlers=[],this.eventHandlers.clear(),this.log("Server destroyed")}handleConnection(e){let t=e.id;if(this.log(`Client connected: ${t}`),this.clients.size>=this.options.maxConnections){this.log(`Max connections reached, rejecting ${t}`),e.emit("error",{code:"MAX_CONNECTIONS",message:"Server is full"}),e.disconnect(!0);return}this.clients.set(t,e),this.clientData.set(t,{}),e.connectedAt=Date.now(),this.stats.totalConnections++,this.setupClientHandlers(e),this.connectionHandlers.forEach(n=>{try{n(t)}catch(i){this.log(`Error in connection handler: ${i}`)}}),e.on("ping",()=>{e.emit("pong")})}setupClientHandlers(e){let t=e.id;e.on("disconnect",n=>{this.log(`Client disconnected: ${t} (${n})`),this.clients.delete(t),this.clientData.delete(t),this.disconnectionHandlers.forEach(i=>{try{i(t,n)}catch(o){this.log(`Error in disconnection handler: ${o}`)}})}),this.eventHandlers.forEach((n,i)=>{e.on(i,o=>{n.forEach(d=>{try{d(t,o)}catch(g){this.log(`Error in event handler for '${i}': ${g}`)}})})})}log(e,t){this.options.debug&&(t!==void 0?console.warn(`[SocketIOServer] ${e}`,t):console.warn(`[SocketIOServer] ${e}`))}};h(l,"SocketIOServer");var a=l;export{a as SocketIOServer};

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@utsp/network-server",
+  "version": "0.1.1",
+  "description": "UTSP Network Server - Server-side communication adapters",
+  "author": "Thomas Piquet",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/thp-software/utsp.git",
+    "directory": "packages/network-server"
+  },
+  "bugs": {
+    "url": "https://github.com/thp-software/utsp/issues"
+  },
+  "homepage": "https://github.com/thp-software/utsp/tree/master/packages/network-server#readme",
+  "keywords": [
+    "utsp",
+    "network",
+    "server",
+    "websocket",
+    "socket.io",
+    "communication",
+    "multi-user",
+    "real-time",
+    "terminal",
+    "nodejs"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "socket.io": "^4.7.2",
+    "@utsp/types": "0.1.1"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.6.3"
+  },
+  "scripts": {
+    "build": "node ../../scripts/build-package.mjs packages/network-server",
+    "dev": "tsc --watch",
+    "clean": "rimraf dist",
+    "lint": "eslint \"src/**/*.ts\" --max-warnings 0",
+    "lint:fix": "eslint \"src/**/*.ts\" --fix",
+    "typecheck": "tsc --noEmit"
+  }
+}