@couch-kit/host 0.5.1 → 0.6.0

package/README.md

@@ -50,14 +50,20 @@ Returns:
 - `serverUrl`: HTTP URL phones should open (or `devServerUrl` in dev mode)
 - `serverError`: static server error (if startup fails)
 
-## System Actions (Important)
+## System Actions
 
-The host will dispatch a few **system action types** into your reducer. Treat these as reserved:
+The host automatically dispatches internal system actions (`__PLAYER_JOINED__`, `__PLAYER_LEFT__`, `__HYDRATE__`) into `createGameReducer`, which handles them for you. **You do not need to handle these in your reducer.**
 
-- `PLAYER_JOINED`: payload `{ id: string, name: string, avatar?: string, secret?: string }`
-- `PLAYER_LEFT`: payload `{ playerId: string }`
+Player tracking (`state.players`) is managed automatically:
 
-If you want to track players in `state.players`, handle these action types in your reducer. The `secret` field can be used to identify returning players.
+- When a player joins, they are added to `state.players` with `connected: true`.
+- When a player disconnects, they are marked as `connected: false`.
+
+To react to player events outside of state (e.g., logging, analytics), use the callback config options:
+
+- `onPlayerJoined?: (playerId: string, name: string) => void` -- called when a player successfully joins.
+- `onPlayerLeft?: (playerId: string) => void` -- called when a player disconnects.
+- `onError?: (error: Error) => void` -- called when a server error occurs.
 
 ### 1. Configure the Provider
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@couch-kit/host",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "description": "React Native host for local multiplayer party games on Android TV — WebSocket server, state management, and static file serving",
   "license": "MIT",
   "repository": {
@@ -45,13 +45,13 @@
     "!**/__mocks__"
   ],
   "scripts": {
-    "test": "jest --passWithNoTests",
+    "test": "bun test",
     "typecheck": "tsc --noEmit",
     "lint": "eslint \"**/*.{js,ts,tsx}\"",
     "clean": "del-cli lib"
   },
   "dependencies": {
-    "@couch-kit/core": "0.3.1",
+    "@couch-kit/core": "0.3.3",
     "buffer": "^6.0.3",
     "js-sha1": "^0.7.0",
     "react-native-fs": "^2.20.0",
@@ -60,16 +60,16 @@
     "react-native-tcp-socket": "^6.0.6"
   },
   "devDependencies": {
-    "@types/react": "~17.0.21",
-    "@types/react-native": "0.70.0",
+    "@types/react": "^18.2.0",
+    "@types/react-native": "^0.72.0",
     "react": "18.2.0",
     "react-native": "0.72.6",
     "del-cli": "^5.1.0",
     "jest": "^29.7.0"
   },
   "peerDependencies": {
-    "react": "*",
-    "react-native": "*",
+    "react": ">=18.2.0",
+    "react-native": ">=0.72.0",
     "react-native-nitro-modules": ">=0.33.0"
   }
 }

package/src/buffer-utils.ts

@@ -0,0 +1,53 @@
+/**
+ * Buffer management utilities for WebSocket per-client receive buffers.
+ * Extracted into a standalone module so they can be tested without
+ * react-native dependencies.
+ */
+
+import { Buffer } from "buffer";
+import type { TcpSocketInstance } from "./declarations";
+
+// Internal type for a TCP socket with our added management properties.
+export interface ManagedSocket {
+  socket: TcpSocketInstance;
+  id: string;
+  isHandshakeComplete: boolean;
+  buffer: Buffer;
+  /** Number of valid bytes currently in `buffer` (may be less than buffer.length). */
+  bufferLength: number;
+  lastPong: number;
+}
+
+/**
+ * Append data to a managed socket's buffer, growing capacity geometrically
+ * to avoid re-allocation on every TCP data event.
+ */
+export function appendToBuffer(managed: ManagedSocket, data: Buffer): void {
+  const needed = managed.bufferLength + data.length;
+
+  if (needed > managed.buffer.length) {
+    // Grow by at least 2x or to fit the new data, whichever is larger
+    const newCapacity = Math.max(managed.buffer.length * 2, needed);
+    const grown = Buffer.alloc(newCapacity);
+    managed.buffer.copy(grown, 0, 0, managed.bufferLength);
+    managed.buffer = grown;
+  }
+
+  data.copy(managed.buffer, managed.bufferLength);
+  managed.bufferLength = needed;
+}
+
+/**
+ * Compact the buffer by discarding consumed bytes from the front.
+ * If all data has been consumed, reset the length to 0 without re-allocating.
+ */
+export function compactBuffer(managed: ManagedSocket, consumed: number): void {
+  const remaining = managed.bufferLength - consumed;
+  if (remaining <= 0) {
+    managed.bufferLength = 0;
+    return;
+  }
+  // Shift remaining bytes to the front of the existing buffer
+  managed.buffer.copy(managed.buffer, 0, consumed, managed.bufferLength);
+  managed.bufferLength = remaining;
+}

package/src/declarations.d.ts

@@ -1,3 +1,19 @@
+/**
+ * Minimal type definition for the raw TCP socket provided by react-native-tcp-socket.
+ * Covers only the API surface used by GameWebSocketServer.
+ */
+export interface TcpSocketInstance {
+  write(data: string | Buffer): void;
+  destroy(): void;
+  on(event: "data", callback: (data: Buffer | string) => void): this;
+  on(event: "error", callback: (error: Error) => void): this;
+  on(event: "close", callback: (hadError: boolean) => void): this;
+  address():
+    | { address: string; family: string; port: number }
+    | Record<string, never>;
+  readonly destroyed: boolean;
+}
+
 declare module "react-native-nitro-http-server" {
   export class StaticServer {
     start(port: number, path: string, host?: string): Promise<void>;

package/src/event-emitter.ts

@@ -75,7 +75,10 @@ export class EventEmitter<
       try {
         listener(...args);
       } catch (error) {
-        console.error(`Error in event listener for "${event}":`, error);
+        console.error(
+          `[EventEmitter] Error in listener for "${String(event)}":`,
+          error,
+        );
       }
     }
     return true;

package/src/provider.tsx

@@ -87,6 +87,22 @@ function isValidClientMessage(msg: unknown): msg is ClientMessage {
   }
 }
 
+/**
+ * React context provider that turns a React Native TV app into a local game server.
+ *
+ * Starts a static file server (for the web controller) and a WebSocket game server
+ * (for real-time state sync). Manages the canonical game state using the provided
+ * reducer and broadcasts state updates to all connected clients.
+ *
+ * @param config - Host configuration including reducer, initial state, ports, and callbacks.
+ *
+ * @example
+ * ```tsx
+ * <GameHostProvider config={{ reducer: gameReducer, initialState }}>
+ *   <GameScreen />
+ * </GameHostProvider>
+ * ```
+ */
 export function GameHostProvider<S extends IGameState, A extends IAction>({
   children,
   config,
@@ -318,6 +334,16 @@ export function GameHostProvider<S extends IGameState, A extends IAction>({
   );
 }
 
+/**
+ * React hook to access the game host context.
+ *
+ * Must be used within a `<GameHostProvider>`. Returns the canonical game state,
+ * a dispatch function for actions, the server URL (for QR codes), and any
+ * server startup errors.
+ *
+ * @returns An object with `state`, `dispatch`, `serverUrl`, and `serverError`.
+ * @throws If used outside of a `<GameHostProvider>`.
+ */
 export function useGameHost<S extends IGameState, A extends IAction>() {
   const context = useContext(GameHostContext);
   if (!context) {

package/src/server.ts

@@ -11,6 +11,16 @@ export interface CouchKitHostConfig {
   staticDir?: string; // Override the default www directory path (required on Android)
 }
 
+/**
+ * React hook that manages a static HTTP file server for serving the web controller.
+ *
+ * In production mode, starts a `StaticServer` bound to `0.0.0.0` on the configured port,
+ * serving files from `staticDir` (or `${RNFS.MainBundlePath}/www` by default).
+ * In dev mode, skips the server and returns `devServerUrl` directly.
+ *
+ * @param config - Server configuration including port, dev mode, and static directory.
+ * @returns An object with `url` (the server URL or null), `error`, and `loading`.
+ */
 export const useStaticServer = (config: CouchKitHostConfig) => {
   const [url, setUrl] = useState<string | null>(null);
   const [error, setError] = useState<Error | null>(null);

package/src/websocket.ts

@@ -7,6 +7,7 @@
  */
 
 import TcpSocket from "react-native-tcp-socket";
+import type { TcpSocketInstance } from "./declarations";
 import { EventEmitter } from "./event-emitter";
 import { Buffer } from "buffer";
 import { sha1 } from "js-sha1";
@@ -16,6 +17,8 @@ import {
   KEEPALIVE_INTERVAL,
   KEEPALIVE_TIMEOUT,
 } from "@couch-kit/core";
+import { appendToBuffer, compactBuffer } from "./buffer-utils";
+import type { ManagedSocket } from "./buffer-utils";
 
 export interface WebSocketConfig {
   port: number;
@@ -53,59 +56,12 @@ const GUID = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11";
 /** Initial capacity for per-client receive buffers. */
 const INITIAL_BUFFER_CAPACITY = 4096;
 
-/**
- * Append data to a managed socket's buffer, growing capacity geometrically
- * to avoid re-allocation on every TCP data event.
- */
-function appendToBuffer(managed: ManagedSocket, data: Buffer): void {
-  const needed = managed.bufferLength + data.length;
-
-  if (needed > managed.buffer.length) {
-    // Grow by at least 2x or to fit the new data, whichever is larger
-    const newCapacity = Math.max(managed.buffer.length * 2, needed);
-    const grown = Buffer.alloc(newCapacity);
-    managed.buffer.copy(grown, 0, 0, managed.bufferLength);
-    managed.buffer = grown;
-  }
-
-  data.copy(managed.buffer, managed.bufferLength);
-  managed.bufferLength = needed;
-}
-
-/**
- * Compact the buffer by discarding consumed bytes from the front.
- * If all data has been consumed, reset the length to 0 without re-allocating.
- */
-function compactBuffer(managed: ManagedSocket, consumed: number): void {
-  const remaining = managed.bufferLength - consumed;
-  if (remaining <= 0) {
-    managed.bufferLength = 0;
-    return;
-  }
-  // Shift remaining bytes to the front of the existing buffer
-  managed.buffer.copy(managed.buffer, 0, consumed, managed.bufferLength);
-  managed.bufferLength = remaining;
-}
-
 interface DecodedFrame {
   opcode: number;
   payload: Buffer;
   bytesConsumed: number;
 }
 
-// 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
-  socket: any;
-  id: string;
-  isHandshakeComplete: boolean;
-  buffer: Buffer;
-  /** Number of valid bytes currently in `buffer` (may be less than buffer.length). */
-  bufferLength: number;
-  lastPong: number;
-}
-
 export class GameWebSocketServer extends EventEmitter<WebSocketServerEvents> {
   private server: ReturnType<typeof TcpSocket.createServer> | null = null;
   private clients: Map<string, ManagedSocket> = new Map();
@@ -134,11 +90,11 @@ export class GameWebSocketServer extends EventEmitter<WebSocketServerEvents> {
   public start() {
     this.log(`[WebSocket] Starting server on port ${this.port}...`);
 
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    this.server = TcpSocket.createServer((rawSocket: any) => {
-      this.log(
-        `[WebSocket] New connection from ${rawSocket.address?.()?.address}`,
-      );
+    this.server = TcpSocket.createServer((rawSocket: TcpSocketInstance) => {
+      const addrInfo = rawSocket.address();
+      const remoteAddr =
+        addrInfo && "address" in addrInfo ? addrInfo.address : "unknown";
+      this.log(`[WebSocket] New connection from ${remoteAddr}`);
 
       const managed: ManagedSocket = {
         socket: rawSocket,
@@ -227,8 +183,11 @@ export class GameWebSocketServer extends EventEmitter<WebSocketServerEvents> {
           this.log(`[WebSocket] Keepalive timeout for ${id}, disconnecting`);
           try {
             managed.socket.destroy();
-          } catch {
-            // Already destroyed
+          } catch (error) {
+            this.log(
+              "[WebSocket] Socket already destroyed during keepalive cleanup:",
+              error,
+            );
           }
           this.clients.delete(id);
           this.emit("disconnect", id);
@@ -237,8 +196,8 @@ export class GameWebSocketServer extends EventEmitter<WebSocketServerEvents> {
 
         try {
           managed.socket.write(pingFrame);
-        } catch {
-          // Socket already closing
+        } catch (error) {
+          this.log("[WebSocket] Failed to send keepalive ping:", error);
         }
       }
     }, this.keepaliveInterval);
@@ -258,8 +217,11 @@ export class GameWebSocketServer extends EventEmitter<WebSocketServerEvents> {
         this.log(`[WebSocket] Frame error from ${managed.id}:`, error);
         try {
           managed.socket.destroy();
-        } catch {
-          // Already destroyed
+        } catch (destroyError) {
+          this.log(
+            "[WebSocket] Socket already destroyed after frame error:",
+            destroyError,
+          );
         }
         return;
       }
@@ -278,10 +240,11 @@ export class GameWebSocketServer extends EventEmitter<WebSocketServerEvents> {
           try {
             const message = JSON.parse(frame.payload.toString("utf8"));
             this.emit("message", managed.id, message);
-          } catch {
+          } catch (error) {
             // Corrupt JSON in a complete frame -- discard this frame, continue processing
             this.log(
-              `[WebSocket] Invalid JSON from ${managed.id}, discarding frame`,
+              `[WebSocket] Invalid JSON from ${managed.id}, discarding frame:`,
+              error,
             );
           }
           break;
@@ -295,8 +258,8 @@ export class GameWebSocketServer extends EventEmitter<WebSocketServerEvents> {
           closeFrame[1] = 0x00; // No payload
           try {
             managed.socket.write(closeFrame);
-          } catch {
-            // Socket may already be closing
+          } catch (error) {
+            this.log("[WebSocket] Failed to send close frame:", error);
           }
           managed.socket.destroy();
           break;
@@ -308,8 +271,8 @@ export class GameWebSocketServer extends EventEmitter<WebSocketServerEvents> {
           const pongFrame = this.encodeControlFrame(OPCODE.PONG, frame.payload);
           try {
             managed.socket.write(pongFrame);
-          } catch {
-            // Socket may be closing
+          } catch (error) {
+            this.log("[WebSocket] Failed to send pong:", error);
           }
           break;
         }
@@ -365,13 +328,19 @@ export class GameWebSocketServer extends EventEmitter<WebSocketServerEvents> {
       this.clients.forEach((managed) => {
         try {
           managed.socket.write(closeFrame);
-        } catch {
-          // Socket may already be closing
+        } catch (error) {
+          this.log(
+            "[WebSocket] Failed to send close frame during shutdown:",
+            error,
+          );
         }
         try {
           managed.socket.destroy();
-        } catch {
-          // Already destroyed
+        } catch (error) {
+          this.log(
+            "[WebSocket] Socket already destroyed during shutdown:",
+            error,
+          );
         }
       });
 
@@ -425,7 +394,6 @@ export class GameWebSocketServer extends EventEmitter<WebSocketServerEvents> {
 
   // --- Private Helpers ---
 
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
   private handleHandshake(managed: ManagedSocket, header: string) {
     this.log("[WebSocket] Handshake request header:", JSON.stringify(header));
     const keyMatch = header.match(/Sec-WebSocket-Key: (.+)/);