@couch-kit/host 0.3.0 → 0.4.0

package/package.json

@@ -1,6 +1,24 @@
 {
   "name": "@couch-kit/host",
-  "version": "0.3.0",
+  "version": "0.4.0",
+  "description": "React Native host for local multiplayer party games on Android TV — WebSocket server, state management, and static file serving",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/faluciano/react-native-couch-kit.git",
+    "directory": "packages/host"
+  },
+  "homepage": "https://github.com/faluciano/react-native-couch-kit#readme",
+  "keywords": [
+    "react-native",
+    "android-tv",
+    "fire-tv",
+    "party-game",
+    "websocket",
+    "couch-kit",
+    "local-multiplayer",
+    "game-host"
+  ],
   "main": "src/index.tsx",
   "react-native": "src/index.tsx",
   "source": "src/index.tsx",
@@ -25,7 +43,7 @@
     "clean": "del-cli lib"
   },
   "dependencies": {
-    "@couch-kit/core": "0.2.0",
+    "@couch-kit/core": "0.3.0",
     "js-sha1": "^0.7.0",
     "react-native-fs": "^2.20.0",
     "react-native-network-info": "^5.2.1",

package/src/event-emitter.ts

@@ -1,15 +1,32 @@
 /**
- * Lightweight EventEmitter implementation for cross-platform compatibility.
+ * Lightweight, type-safe EventEmitter implementation for cross-platform compatibility.
  * Works in browser, React Native, and Node.js environments.
+ *
+ * @typeParam EventMap - A record mapping event names to their listener argument tuples.
+ *
+ * @example
+ * ```ts
+ * type MyEvents = {
+ *   data: [payload: string];
+ *   error: [err: Error];
+ *   close: [];
+ * };
+ * const emitter = new EventEmitter<MyEvents>();
+ * emitter.on("data", (payload) => { ... }); // payload is typed as string
+ * ```
  */
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
-type Listener = (...args: any[]) => void;
+export class EventEmitter<
+  EventMap extends Record<string, any[]> = Record<string, any[]>,
+> {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  private listeners: Map<string, Array<(...args: any[]) => void>> = new Map();
 
-export class EventEmitter {
-  private listeners: Map<string, Listener[]> = new Map();
-
-  on(event: string, listener: Listener): this {
+  on<K extends string & keyof EventMap>(
+    event: K,
+    listener: (...args: EventMap[K]) => void,
+  ): this {
     if (!this.listeners.has(event)) {
       this.listeners.set(event, []);
     }
@@ -17,15 +34,22 @@ export class EventEmitter {
     return this;
   }
 
-  once(event: string, listener: Listener): this {
-    const onceWrapper: Listener = (...args: any[]) => {
-      this.off(event, onceWrapper);
-      listener(...args);
+  once<K extends string & keyof EventMap>(
+    event: K,
+    listener: (...args: EventMap[K]) => void,
+  ): this {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const onceWrapper = (...args: any[]) => {
+      this.off(event, onceWrapper as (...a: EventMap[K]) => void);
+      listener(...(args as EventMap[K]));
     };
-    return this.on(event, onceWrapper);
+    return this.on(event, onceWrapper as (...a: EventMap[K]) => void);
   }
 
-  off(event: string, listener: Listener): this {
+  off<K extends string & keyof EventMap>(
+    event: K,
+    listener: (...args: EventMap[K]) => void,
+  ): this {
     const listeners = this.listeners.get(event);
     if (listeners) {
       const index = listeners.indexOf(listener);
@@ -36,7 +60,10 @@ export class EventEmitter {
     return this;
   }
 
-  emit(event: string, ...args: any[]): boolean {
+  emit<K extends string & keyof EventMap>(
+    event: K,
+    ...args: EventMap[K]
+  ): boolean {
     const listeners = this.listeners.get(event);
     if (!listeners || listeners.length === 0) {
       return false;
@@ -54,7 +81,7 @@ export class EventEmitter {
     return true;
   }
 
-  removeAllListeners(event?: string): this {
+  removeAllListeners<K extends string & keyof EventMap>(event?: K): this {
     if (event) {
       this.listeners.delete(event);
     } else {
@@ -63,7 +90,7 @@ export class EventEmitter {
     return this;
   }
 
-  listenerCount(event: string): number {
+  listenerCount<K extends string & keyof EventMap>(event: K): number {
     return this.listeners.get(event)?.length ?? 0;
   }
 }

package/src/provider.tsx

@@ -2,6 +2,7 @@ import React, {
   createContext,
   useContext,
   useEffect,
+  useMemo,
   useReducer,
   useRef,
 } from "react";
@@ -9,25 +10,35 @@ import { GameWebSocketServer } from "./websocket";
 import { useStaticServer } from "./server";
 import {
   MessageTypes,
+  InternalActionTypes,
+  DEFAULT_HTTP_PORT,
+  DEFAULT_WS_PORT_OFFSET,
   type IGameState,
   type IAction,
+  type InternalAction,
   type ClientMessage,
 } from "@couch-kit/core";
 
-interface GameHostConfig<S extends IGameState, A extends IAction> {
+export interface GameHostConfig<S extends IGameState, A extends IAction> {
   initialState: S;
-  reducer: (state: S, action: A) => S;
+  reducer: (state: S, action: A | InternalAction<S>) => S;
   port?: number; // Static server port (default 8080)
   wsPort?: number; // WebSocket port (default: HTTP port + 2, i.e. 8082)
   devMode?: boolean;
   devServerUrl?: string;
   staticDir?: string; // Override the default www directory path (required on Android)
   debug?: boolean;
+  /** Called when a player successfully joins. */
+  onPlayerJoined?: (playerId: string, name: string) => void;
+  /** Called when a player disconnects. */
+  onPlayerLeft?: (playerId: string) => void;
+  /** Called when a server error occurs. */
+  onError?: (error: Error) => void;
 }
 
 interface GameHostContextValue<S extends IGameState, A extends IAction> {
   state: S;
-  dispatch: (action: A) => void;
+  dispatch: (action: A | InternalAction<S>) => void;
   serverUrl: string | null;
   serverError: Error | null;
 }
@@ -38,6 +49,42 @@ const GameHostContext = createContext<GameHostContextValue<any, any> | null>(
   null,
 );
 
+/**
+ * Validates that an incoming message has the expected shape.
+ * Returns true if the message is a valid ClientMessage, false otherwise.
+ */
+function isValidClientMessage(msg: unknown): msg is ClientMessage {
+  if (typeof msg !== "object" || msg === null) return false;
+  const m = msg as Record<string, unknown>;
+  if (typeof m.type !== "string") return false;
+
+  switch (m.type) {
+    case MessageTypes.JOIN:
+      return (
+        typeof m.payload === "object" &&
+        m.payload !== null &&
+        typeof (m.payload as Record<string, unknown>).name === "string"
+      );
+    case MessageTypes.ACTION:
+      return (
+        typeof m.payload === "object" &&
+        m.payload !== null &&
+        typeof (m.payload as Record<string, unknown>).type === "string"
+      );
+    case MessageTypes.PING:
+      return (
+        typeof m.payload === "object" &&
+        m.payload !== null &&
+        typeof (m.payload as Record<string, unknown>).id === "string" &&
+        typeof (m.payload as Record<string, unknown>).timestamp === "number"
+      );
+    case MessageTypes.ASSETS_LOADED:
+      return m.payload === true;
+    default:
+      return false;
+  }
+}
+
 export function GameHostProvider<S extends IGameState, A extends IAction>({
   children,
   config,
@@ -53,9 +100,16 @@ export function GameHostProvider<S extends IGameState, A extends IAction>({
     stateRef.current = state;
   }, [state]);
 
-  // 1. Start Static File Server (Port 8080)
+  // Keep refs for callback props to avoid stale closures
+  const configRef = useRef(config);
+  useEffect(() => {
+    configRef.current = config;
+  });
+
+  // 1. Start Static File Server
+  const httpPort = config.port || DEFAULT_HTTP_PORT;
   const { url: serverUrl, error: serverError } = useStaticServer({
-    port: config.port || 8080,
+    port: httpPort,
     devMode: config.devMode,
     devServerUrl: config.devServerUrl,
     staticDir: config.staticDir,
@@ -67,30 +121,48 @@ export function GameHostProvider<S extends IGameState, A extends IAction>({
   // Track active sessions: secret -> playerId
   const sessions = useRef<Map<string, string>>(new Map());
 
+  // Track socket IDs that have received their WELCOME message
+  const welcomedClients = useRef<Set<string>>(new Set());
+
   useEffect(() => {
-    const httpPort = config.port || 8080;
-    const port = config.wsPort || httpPort + 2;
+    const port = config.wsPort || httpPort + DEFAULT_WS_PORT_OFFSET;
     const server = new GameWebSocketServer({ port, debug: config.debug });
 
     server.start();
     wsServer.current = server;
 
     server.on("listening", (p) => {
-      if (config.debug)
+      if (configRef.current.debug)
         console.log(`[GameHost] WebSocket listening on port ${p}`);
     });
 
     server.on("connection", (socketId) => {
-      if (config.debug) console.log(`[GameHost] Client connected: ${socketId}`);
+      if (configRef.current.debug)
+        console.log(`[GameHost] Client connected: ${socketId}`);
     });
 
-    server.on("message", (socketId, message: ClientMessage) => {
-      if (config.debug)
+    server.on("message", (socketId, rawMessage) => {
+      // Validate message structure before processing
+      if (!isValidClientMessage(rawMessage)) {
+        if (configRef.current.debug)
+          console.warn(
+            `[GameHost] Invalid message from ${socketId}:`,
+            rawMessage,
+          );
+        server.send(socketId, {
+          type: MessageTypes.ERROR,
+          payload: { code: "INVALID_MESSAGE", message: "Malformed message" },
+        });
+        return;
+      }
+
+      const message = rawMessage;
+
+      if (configRef.current.debug)
         console.log(`[GameHost] Msg from ${socketId}:`, message);
 
       switch (message.type) {
         case MessageTypes.JOIN: {
-          // Check for existing session
           const { secret, ...payload } = message.payload;
 
           if (secret) {
@@ -98,25 +170,58 @@ export function GameHostProvider<S extends IGameState, A extends IAction>({
             sessions.current.set(secret, socketId);
           }
 
+          // Dispatch the internal PLAYER_JOINED action
           dispatch({
-            type: "PLAYER_JOINED",
-            payload: { id: socketId, secret, ...payload },
-          } as unknown as A);
+            type: InternalActionTypes.PLAYER_JOINED,
+            payload: { id: socketId, ...payload },
+          } as InternalAction<S>);
 
-          server.send(socketId, {
-            type: MessageTypes.WELCOME,
-            payload: {
-              playerId: socketId,
-              state: stateRef.current,
-              serverTime: Date.now(),
-            },
+          // Use queueMicrotask to send WELCOME after the reducer has processed
+          // the PLAYER_JOINED action, so the client receives state that includes
+          // themselves in the players list.
+          queueMicrotask(() => {
+            welcomedClients.current.add(socketId);
+            server.send(socketId, {
+              type: MessageTypes.WELCOME,
+              payload: {
+                playerId: socketId,
+                state: stateRef.current,
+                serverTime: Date.now(),
+              },
+            });
           });
+
+          configRef.current.onPlayerJoined?.(socketId, payload.name);
           break;
         }
 
-        case MessageTypes.ACTION:
-          dispatch(message.payload as A);
+        case MessageTypes.ACTION: {
+          // Only accept actions with a user-defined type string,
+          // reject internal action types to prevent injection.
+          const actionPayload = message.payload as A;
+          if (
+            actionPayload.type === InternalActionTypes.HYDRATE ||
+            actionPayload.type === InternalActionTypes.PLAYER_JOINED ||
+            actionPayload.type === InternalActionTypes.PLAYER_LEFT
+          ) {
+            if (configRef.current.debug)
+              console.warn(
+                `[GameHost] Rejected internal action from ${socketId}:`,
+                actionPayload.type,
+              );
+            server.send(socketId, {
+              type: MessageTypes.ERROR,
+              payload: {
+                code: "FORBIDDEN_ACTION",
+                message:
+                  "Internal action types cannot be dispatched by clients",
+              },
+            });
+            return;
+          }
+          dispatch(actionPayload);
           break;
+        }
 
         case MessageTypes.PING:
           server.send(socketId, {
@@ -132,28 +237,38 @@ export function GameHostProvider<S extends IGameState, A extends IAction>({
     });
 
     server.on("disconnect", (socketId) => {
-      if (config.debug)
+      if (configRef.current.debug)
         console.log(`[GameHost] Client disconnected: ${socketId}`);
 
+      welcomedClients.current.delete(socketId);
+
       // We do NOT remove the session from the map here,
       // allowing them to reconnect later with the same secret.
 
       dispatch({
-        type: "PLAYER_LEFT",
+        type: InternalActionTypes.PLAYER_LEFT,
         payload: { playerId: socketId },
-      } as unknown as A);
+      } as InternalAction<S>);
+
+      configRef.current.onPlayerLeft?.(socketId);
+    });
+
+    server.on("error", (error) => {
+      if (configRef.current.debug)
+        console.error(`[GameHost] Server error:`, error);
+      configRef.current.onError?.(error);
     });
 
     return () => {
       server.stop();
     };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
   }, []); // Run once on mount
 
   // 3. Broadcast State Updates
-  // Whenever React state changes, send it to all clients
+  // Whenever React state changes, send it to all clients that have been welcomed
   useEffect(() => {
     if (wsServer.current) {
-      // Optimization: In the future, send deltas or only send if changed significantly
       wsServer.current.broadcast({
         type: MessageTypes.STATE_UPDATE,
         payload: {
@@ -164,15 +279,15 @@ export function GameHostProvider<S extends IGameState, A extends IAction>({
     }
   }, [state]);
 
-  // Keep stateRef in sync inside this effect too just in case (redundant but safe)
-  useEffect(() => {
-    stateRef.current = state;
-  }, [state]);
+  // Memoize context value to prevent unnecessary re-renders of consumers
+  // that only use stable references like dispatch
+  const contextValue = useMemo(
+    () => ({ state, dispatch, serverUrl, serverError }),
+    [state, serverUrl, serverError],
+  );
 
   return (
-    <GameHostContext.Provider
-      value={{ state, dispatch, serverUrl, serverError }}
-    >
+    <GameHostContext.Provider value={contextValue}>
       {children}
     </GameHostContext.Provider>
   );

package/src/server.ts

@@ -2,8 +2,9 @@ import { useEffect, useState } from "react";
 import { StaticServer } from "react-native-nitro-http-server";
 import RNFS from "react-native-fs";
 import { getBestIpAddress } from "./network";
+import { DEFAULT_HTTP_PORT, toErrorMessage } from "@couch-kit/core";
 
-interface CouchKitHostConfig {
+export interface CouchKitHostConfig {
   port?: number;
   devMode?: boolean;
   devServerUrl?: string; // e.g. "http://localhost:5173"
@@ -13,9 +14,11 @@ interface CouchKitHostConfig {
 export const useStaticServer = (config: CouchKitHostConfig) => {
   const [url, setUrl] = useState<string | null>(null);
   const [error, setError] = useState<Error | null>(null);
+  const [loading, setLoading] = useState(true);
 
   useEffect(() => {
     let server: StaticServer | null = null;
+    setLoading(true);
 
     const startServer = async () => {
       // In Dev Mode, we don't start the static server.
@@ -29,6 +32,7 @@ export const useStaticServer = (config: CouchKitHostConfig) => {
         } else {
           setError(new Error("Could not detect TV IP address"));
         }
+        setLoading(false);
         return;
       }
 
@@ -37,7 +41,7 @@ export const useStaticServer = (config: CouchKitHostConfig) => {
         // Use staticDir if provided (required on Android where MainBundlePath is undefined),
         // otherwise fall back to iOS MainBundlePath
         const path = config.staticDir || `${RNFS.MainBundlePath}/www`;
-        const port = config.port || 8080;
+        const port = config.port || DEFAULT_HTTP_PORT;
 
         server = new StaticServer();
 
@@ -49,11 +53,13 @@ export const useStaticServer = (config: CouchKitHostConfig) => {
         if (ip) {
           setUrl(`http://${ip}:${port}`);
         } else {
-          // Fallback if we can't detect IP (though HttpServer doesn't return the URL directly like the old lib)
+          // Fallback if we can't detect IP
           setUrl(`http://localhost:${port}`);
         }
       } catch (e) {
-        setError(e as Error);
+        setError(new Error(toErrorMessage(e)));
+      } finally {
+        setLoading(false);
       }
     };
 
@@ -66,5 +72,5 @@ export const useStaticServer = (config: CouchKitHostConfig) => {
     };
   }, [config.port, config.devMode, config.devServerUrl, config.staticDir]);
 
-  return { url, error };
+  return { url, error, loading };
 };

package/src/websocket.ts

@@ -3,19 +3,40 @@
  * Built on top of react-native-tcp-socket
  *
  * Supports: text frames, close frames, ping/pong, multi-frame TCP packets,
- * and robust buffer management per RFC 6455.
+ * server-side keepalive, frame size limits, and robust buffer management per RFC 6455.
  */
 
 import TcpSocket from "react-native-tcp-socket";
 import { EventEmitter } from "./event-emitter";
 import { Buffer } from "buffer";
 import { sha1 } from "js-sha1";
-
-interface WebSocketConfig {
+import {
+  generateId,
+  MAX_FRAME_SIZE,
+  KEEPALIVE_INTERVAL,
+  KEEPALIVE_TIMEOUT,
+} from "@couch-kit/core";
+
+export interface WebSocketConfig {
   port: number;
   debug?: boolean;
+  /** Maximum allowed frame payload size in bytes (default: 1 MB). */
+  maxFrameSize?: number;
+  /** Interval (ms) between server-side keepalive pings (default: 30s). 0 disables. */
+  keepaliveInterval?: number;
+  /** Timeout (ms) to wait for a pong after a keepalive ping (default: 10s). */
+  keepaliveTimeout?: number;
 }
 
+/** Event map for type-safe event emission. */
+export type WebSocketServerEvents = {
+  connection: [socketId: string];
+  message: [socketId: string, message: unknown];
+  disconnect: [socketId: string];
+  listening: [port: number];
+  error: [error: Error];
+};
+
 // WebSocket opcodes (RFC 6455 Section 5.2)
 const OPCODE = {
   CONTINUATION: 0x0,
@@ -35,19 +56,34 @@ interface DecodedFrame {
   bytesConsumed: number;
 }
 
-export class GameWebSocketServer extends EventEmitter {
+// Internal type for a TCP socket with our added management properties.
+// We use `any` for the raw socket since react-native-tcp-socket doesn't export a clean type.
+interface ManagedSocket {
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  private server: any;
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  private clients: Map<string, any>;
+  socket: any;
+  id: string;
+  isHandshakeComplete: boolean;
+  buffer: Buffer;
+  lastPong: number;
+}
+
+export class GameWebSocketServer extends EventEmitter<WebSocketServerEvents> {
+  private server: ReturnType<typeof TcpSocket.createServer> | null = null;
+  private clients: Map<string, ManagedSocket> = new Map();
   private port: number;
   private debug: boolean;
+  private maxFrameSize: number;
+  private keepaliveInterval: number;
+  private keepaliveTimeout: number;
+  private keepaliveTimer: ReturnType<typeof setInterval> | null = null;
 
   constructor(config: WebSocketConfig) {
     super();
     this.port = config.port;
     this.debug = !!config.debug;
-    this.clients = new Map();
+    this.maxFrameSize = config.maxFrameSize ?? MAX_FRAME_SIZE;
+    this.keepaliveInterval = config.keepaliveInterval ?? KEEPALIVE_INTERVAL;
+    this.keepaliveTimeout = config.keepaliveTimeout ?? KEEPALIVE_TIMEOUT;
   }
 
   private log(...args: unknown[]) {
@@ -56,46 +92,46 @@ export class GameWebSocketServer extends EventEmitter {
     }
   }
 
-  private generateSocketId(): string {
-    // Generate a 21-character base36 ID for negligible collision probability
-    const a = Math.random().toString(36).substring(2, 15); // 13 chars
-    const b = Math.random().toString(36).substring(2, 10); // 8 chars
-    return a + b;
-  }
-
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
   public start() {
     this.log(`[WebSocket] Starting server on port ${this.port}...`);
+
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    this.server = TcpSocket.createServer((socket: any) => {
+    this.server = TcpSocket.createServer((rawSocket: any) => {
       this.log(
-        `[WebSocket] New connection from ${socket.address?.()?.address}`,
+        `[WebSocket] New connection from ${rawSocket.address?.()?.address}`,
       );
-      let buffer: Buffer = Buffer.alloc(0);
 
-      socket.on("data", (data: Buffer | string) => {
+      const managed: ManagedSocket = {
+        socket: rawSocket,
+        id: "",
+        isHandshakeComplete: false,
+        buffer: Buffer.alloc(0),
+        lastPong: Date.now(),
+      };
+
+      rawSocket.on("data", (data: Buffer | string) => {
         this.log(
           `[WebSocket] Received data chunk: ${typeof data === "string" ? data.length : data.length} bytes`,
         );
         // Concatenate new data
-        buffer = Buffer.concat([
-          buffer,
+        managed.buffer = Buffer.concat([
+          managed.buffer,
           typeof data === "string" ? Buffer.from(data) : data,
         ]);
 
         // Handshake not yet performed?
-        if (!socket.isHandshakeComplete) {
-          const header = buffer.toString("utf8");
+        if (!managed.isHandshakeComplete) {
+          const header = managed.buffer.toString("utf8");
           const endOfHeader = header.indexOf("\r\n\r\n");
           if (endOfHeader !== -1) {
-            this.handleHandshake(socket, header);
+            this.handleHandshake(managed, header);
             // Retain any bytes after the handshake (could be the first WS frame)
             const headerByteLength = Buffer.byteLength(
               header.substring(0, endOfHeader + 4),
               "utf8",
             );
-            buffer = buffer.slice(headerByteLength);
-            socket.isHandshakeComplete = true;
+            managed.buffer = managed.buffer.slice(headerByteLength);
+            managed.isHandshakeComplete = true;
             // Fall through to process any remaining frames below
           } else {
             return;
@@ -103,37 +139,92 @@ export class GameWebSocketServer extends EventEmitter {
         }
 
         // Process all complete frames in the buffer
-        this.processFrames(socket, buffer, (remaining) => {
-          buffer = remaining;
+        this.processFrames(managed, (remaining) => {
+          managed.buffer = remaining;
         });
       });
 
-      socket.on("error", (error: Error) => {
+      rawSocket.on("error", (error: Error) => {
         this.emit("error", error);
       });
 
-      socket.on("close", () => {
-        if (socket.id) {
-          this.clients.delete(socket.id);
-          this.emit("disconnect", socket.id);
+      rawSocket.on("close", () => {
+        if (managed.id) {
+          this.clients.delete(managed.id);
+          this.emit("disconnect", managed.id);
         }
       });
     });
 
+    // Handle server-level errors (e.g., port already in use)
+    this.server.on("error", (error: Error) => {
+      this.log("[WebSocket] Server error:", error);
+      this.emit("error", error);
+    });
+
     this.server.listen({ port: this.port, host: "0.0.0.0" }, () => {
       this.log(`[WebSocket] Server listening on 0.0.0.0:${this.port}`);
       this.emit("listening", this.port);
     });
+
+    // Start keepalive pings if enabled
+    if (this.keepaliveInterval > 0) {
+      this.startKeepalive();
+    }
+  }
+
+  private startKeepalive() {
+    this.keepaliveTimer = setInterval(() => {
+      const now = Date.now();
+      const pingFrame = this.encodeControlFrame(OPCODE.PING, Buffer.alloc(0));
+
+      for (const [id, managed] of this.clients) {
+        // Check if previous keepalive timed out
+        if (
+          now - managed.lastPong >
+          this.keepaliveInterval + this.keepaliveTimeout
+        ) {
+          this.log(`[WebSocket] Keepalive timeout for ${id}, disconnecting`);
+          try {
+            managed.socket.destroy();
+          } catch {
+            // Already destroyed
+          }
+          this.clients.delete(id);
+          this.emit("disconnect", id);
+          continue;
+        }
+
+        try {
+          managed.socket.write(pingFrame);
+        } catch {
+          // Socket already closing
+        }
+      }
+    }, this.keepaliveInterval);
   }
 
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
   private processFrames(
-    socket: any,
-    buffer: Buffer,
+    managed: ManagedSocket,
     setBuffer: (b: Buffer) => void,
   ) {
+    let { buffer } = managed;
+
     while (buffer.length > 0) {
-      const frame = this.decodeFrame(buffer);
+      let frame: DecodedFrame | null;
+      try {
+        frame = this.decodeFrame(buffer);
+      } catch (error) {
+        // Frame too large or malformed -- disconnect the client
+        this.log(`[WebSocket] Frame error from ${managed.id}:`, error);
+        try {
+          managed.socket.destroy();
+        } catch {
+          // Already destroyed
+        }
+        return;
+      }
+
       if (!frame) {
         // Incomplete frame -- keep buffer, wait for more data
         break;
@@ -147,37 +238,37 @@ export class GameWebSocketServer extends EventEmitter {
         case OPCODE.TEXT: {
           try {
             const message = JSON.parse(frame.payload.toString("utf8"));
-            this.emit("message", socket.id, message);
-          } catch (e) {
+            this.emit("message", managed.id, message);
+          } catch {
             // Corrupt JSON in a complete frame -- discard this frame, continue processing
             this.log(
-              `[WebSocket] Invalid JSON from ${socket.id}, discarding frame`,
+              `[WebSocket] Invalid JSON from ${managed.id}, discarding frame`,
             );
           }
           break;
         }
 
         case OPCODE.CLOSE: {
-          this.log(`[WebSocket] Close frame from ${socket.id}`);
+          this.log(`[WebSocket] Close frame from ${managed.id}`);
           // Send close frame back (RFC 6455 Section 5.5.1)
           const closeFrame = Buffer.alloc(2);
           closeFrame[0] = 0x88; // FIN + Close opcode
           closeFrame[1] = 0x00; // No payload
           try {
-            socket.write(closeFrame);
+            managed.socket.write(closeFrame);
           } catch {
             // Socket may already be closing
           }
-          socket.destroy();
+          managed.socket.destroy();
           break;
         }
 
         case OPCODE.PING: {
-          this.log(`[WebSocket] Ping from ${socket.id}`);
+          this.log(`[WebSocket] Ping from ${managed.id}`);
           // Respond with pong containing the same payload (RFC 6455 Section 5.5.3)
           const pongFrame = this.encodeControlFrame(OPCODE.PONG, frame.payload);
           try {
-            socket.write(pongFrame);
+            managed.socket.write(pongFrame);
           } catch {
             // Socket may be closing
           }
@@ -185,68 +276,132 @@ export class GameWebSocketServer extends EventEmitter {
         }
 
         case OPCODE.PONG: {
-          // Unsolicited pong -- safe to ignore (RFC 6455 Section 5.5.3)
-          this.log(`[WebSocket] Pong from ${socket.id}`);
+          // Update last-seen pong time for keepalive tracking
+          managed.lastPong = Date.now();
+          this.log(`[WebSocket] Pong from ${managed.id}`);
           break;
         }
 
         case OPCODE.BINARY: {
           // Binary frames not supported -- log and discard
           this.log(
-            `[WebSocket] Binary frame from ${socket.id}, not supported -- discarding`,
+            `[WebSocket] Binary frame from ${managed.id}, not supported -- discarding`,
           );
           break;
         }
 
         default: {
           this.log(
-            `[WebSocket] Unknown opcode 0x${frame.opcode.toString(16)} from ${socket.id}, discarding`,
+            `[WebSocket] Unknown opcode 0x${frame.opcode.toString(16)} from ${managed.id}, discarding`,
           );
           break;
         }
       }
 
       // If socket was destroyed (e.g., close frame), stop processing
-      if (socket.destroyed) break;
+      if (managed.socket.destroyed) break;
     }
 
     setBuffer(buffer);
   }
 
+  /**
+   * Gracefully stop the server.
+   * Sends close frames to all clients before destroying connections.
+   */
   public stop() {
+    // Stop keepalive timer
+    if (this.keepaliveTimer) {
+      clearInterval(this.keepaliveTimer);
+      this.keepaliveTimer = null;
+    }
+
     if (this.server) {
-      this.server.close();
-      this.clients.forEach((socket) => socket.destroy());
+      // Send close frames to all clients before destroying
+      const closeFrame = Buffer.alloc(2);
+      closeFrame[0] = 0x88; // FIN + Close opcode
+      closeFrame[1] = 0x00; // No payload
+
+      this.clients.forEach((managed) => {
+        try {
+          managed.socket.write(closeFrame);
+        } catch {
+          // Socket may already be closing
+        }
+        try {
+          managed.socket.destroy();
+        } catch {
+          // Already destroyed
+        }
+      });
+
       this.clients.clear();
+      this.server.close();
     }
   }
 
+  /**
+   * Send data to a specific client by socket ID.
+   * Silently ignores unknown socket IDs and write errors.
+   */
   public send(socketId: string, data: unknown) {
-    const socket = this.clients.get(socketId);
-    if (socket) {
-      const frame = this.encodeFrame(JSON.stringify(data));
-      socket.write(frame);
+    const managed = this.clients.get(socketId);
+    if (managed) {
+      try {
+        const frame = this.encodeFrame(JSON.stringify(data));
+        managed.socket.write(frame);
+      } catch (error) {
+        this.log(`[WebSocket] Failed to send to ${socketId}:`, error);
+        this.emit(
+          "error",
+          error instanceof Error ? error : new Error(String(error)),
+        );
+      }
     }
   }
 
+  /**
+   * Broadcast data to all connected clients.
+   * Wraps each write in try/catch so a single dead socket doesn't skip remaining clients.
+   */
   public broadcast(data: unknown, excludeId?: string) {
     const frame = this.encodeFrame(JSON.stringify(data));
-    this.clients.forEach((socket, id) => {
+    this.clients.forEach((managed, id) => {
       if (id !== excludeId) {
-        socket.write(frame);
+        try {
+          managed.socket.write(frame);
+        } catch (error) {
+          this.log(`[WebSocket] Failed to broadcast to ${id}:`, error);
+          // Don't abort -- continue sending to remaining clients
+        }
       }
     });
   }
 
+  /** Returns the number of currently connected clients. */
+  public get clientCount(): number {
+    return this.clients.size;
+  }
+
   // --- Private Helpers ---
 
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  private handleHandshake(socket: any, header: string) {
+  private handleHandshake(managed: ManagedSocket, header: string) {
     this.log("[WebSocket] Handshake request header:", JSON.stringify(header));
     const keyMatch = header.match(/Sec-WebSocket-Key: (.+)/);
     if (!keyMatch) {
       console.error("[WebSocket] Handshake failed: No Sec-WebSocket-Key found");
-      socket.destroy();
+      managed.socket.destroy();
+      return;
+    }
+
+    // Validate Sec-WebSocket-Version (RFC 6455 Section 4.2.1)
+    const versionMatch = header.match(/Sec-WebSocket-Version: (\d+)/);
+    if (versionMatch && versionMatch[1] !== "13") {
+      console.error(
+        `[WebSocket] Unsupported WebSocket version: ${versionMatch[1]}`,
+      );
+      managed.socket.destroy();
       return;
     }
 
@@ -269,15 +424,15 @@ export class GameWebSocketServer extends EventEmitter {
         "[WebSocket] Sending Handshake Response:",
         JSON.stringify(response),
       );
-      socket.write(response);
+      managed.socket.write(response);
 
-      // Assign ID and store
-      socket.id = this.generateSocketId();
-      this.clients.set(socket.id, socket);
-      this.emit("connection", socket.id);
+      // Assign cryptographically random ID and store
+      managed.id = generateId();
+      this.clients.set(managed.id, managed);
+      this.emit("connection", managed.id);
     } catch (error) {
       console.error("[WebSocket] Handshake error:", error);
-      socket.destroy();
+      managed.socket.destroy();
     }
   }
 
@@ -310,13 +465,19 @@ export class GameWebSocketServer extends EventEmitter {
       // Read 64-bit length. For safety, only use the lower 32 bits.
       const highBits = buffer.readUInt32BE(2);
       if (highBits > 0) {
-        // Payload > 4GB -- reject
-        throw new Error("Frame payload too large");
+        throw new Error("Frame payload too large (exceeds 4 GB)");
       }
       payloadLength = buffer.readUInt32BE(6);
       headerLength = 10;
     }
 
+    // Enforce max frame size to prevent memory exhaustion attacks
+    if (payloadLength > this.maxFrameSize) {
+      throw new Error(
+        `Frame payload (${payloadLength} bytes) exceeds maximum allowed size (${this.maxFrameSize} bytes)`,
+      );
+    }
+
     const maskLength = isMasked ? 4 : 0;
     const totalFrameLength = headerLength + maskLength + payloadLength;
 

package/src/events.d.ts

@@ -1,20 +0,0 @@
-import { EventEmitter } from "./event-emitter";
-
-// Since the EventEmitter type definition might not perfectly match the Node.js one in RN environment,
-// we'll declare the interface we expect.
-export interface GameWebSocketServer extends EventEmitter {
-  on(event: "connection", listener: (socketId: string) => void): this;
-  on(
-    event: "message",
-    listener: (socketId: string, message: unknown) => void,
-  ): this;
-  on(event: "disconnect", listener: (socketId: string) => void): this;
-  on(event: "listening", listener: (port: number) => void): this;
-  on(event: "error", listener: (error: Error) => void): this;
-
-  emit(event: "connection", socketId: string): boolean;
-  emit(event: "message", socketId: string, message: unknown): boolean;
-  emit(event: "disconnect", socketId: string): boolean;
-  emit(event: "listening", port: number): boolean;
-  emit(event: "error", error: Error): boolean;
-}