@couch-kit/host 0.5.2 → 1.0.0

package/README.md

@@ -22,7 +22,28 @@ The server-side library for React Native TV applications. This package turns you
 bun add @couch-kit/host
 ```
 
-> **Note:** This library includes native dependencies (`react-native-tcp-socket`, `react-native-fs`, etc.). React Native's autolinking will handle the setup for Android. Ensure your `android/build.gradle` is configured correctly if you encounter build issues.
+Then install the required peer dependencies:
+
+```bash
+npx expo install expo-file-system expo-network
+bun add react-native-tcp-socket
+```
+
+> **Note:** This library requires Expo modules (`expo-file-system`, `expo-network`) and `react-native-tcp-socket` as peer dependencies. These must be installed in your consumer app. React Native's autolinking will handle native setup automatically.
+
+## Compatibility
+
+| Dependency                   | Minimum Version |
+| ---------------------------- | --------------- |
+| `react`                      | `>= 18.2.0`     |
+| `react-native`               | `>= 0.72.0`     |
+| `react-native-nitro-modules` | `>= 0.33.0`     |
+| `expo`                       | `>= 51.0.0`     |
+| `expo-file-system`           | `>= 17.0.0`     |
+| `expo-network`               | `>= 7.0.0`      |
+| `react-native-tcp-socket`    | `>= 6.0.0`      |
+
+> **New Architecture:** This package supports React Native's New Architecture (Fabric/TurboModules) via React Native 0.83+.
 
 ## Usage
 
@@ -36,7 +57,7 @@ Config:
 - `reducer`: `(state, action) => state` (shared reducer)
 - `port?`: HTTP static server port (default `8080`)
 - `wsPort?`: WebSocket game server port (default `8082`)
-- `staticDir?`: absolute path to the directory of static files to serve. On Android, APK assets live inside a zip archive and cannot be served directly — use this to point to a writable filesystem path where you've extracted the `www/` assets at runtime. Defaults to `${RNFS.MainBundlePath}/www`.
+- `staticDir?`: absolute path to the directory of static files to serve. **Required on Android** — APK assets live inside a zip archive and cannot be served directly, so use this to point to a writable filesystem path where you've extracted the `www/` assets at runtime. On iOS, defaults to the bundle directory + `/www`.
 - `devMode?`: if true, do not start the TV static file server; instead point phones at `devServerUrl`
 - `devServerUrl?`: URL of your laptop dev server (e.g. `http://192.168.1.50:5173`)
 - `debug?`: enable verbose logs
@@ -148,6 +169,6 @@ Important: when the controller is served from the laptop, the client-side hook c
 
 ## Bundling / Assets
 
-In production, the host serves static controller assets from `${RNFS.MainBundlePath}/www`.
+In production, the host serves static controller assets from the iOS bundle directory + `/www` by default. On Android, `staticDir` must be provided since bundle assets live inside the APK.
 
 The CLI `couch-kit bundle` copies your web build output into `android/app/src/main/assets/www` (default). Ensure your app packaging makes those assets available under the expected `www` folder.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@couch-kit/host",
-  "version": "0.5.2",
+  "version": "1.0.0",
   "description": "React Native host for local multiplayer party games on Android TV — WebSocket server, state management, and static file serving",
   "license": "MIT",
   "repository": {
@@ -33,43 +33,37 @@
   "files": [
     "src",
     "lib",
-    "android",
-    "ios",
-    "cpp",
-    "*.podspec",
     "!lib/typescript/example",
-    "!android/build",
-    "!ios/build",
     "!**/__tests__",
     "!**/__fixtures__",
     "!**/__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.2",
+    "@couch-kit/core": "0.3.3",
     "buffer": "^6.0.3",
     "js-sha1": "^0.7.0",
-    "react-native-fs": "^2.20.0",
-    "react-native-network-info": "^5.2.1",
-    "react-native-nitro-http-server": "^1.5.4",
-    "react-native-tcp-socket": "^6.0.6"
+    "react-native-nitro-http-server": "^1.5.4"
   },
   "devDependencies": {
-    "@types/react": "^18.2.0",
-    "@types/react-native": "^0.72.0",
-    "react": "18.2.0",
-    "react-native": "0.72.6",
+    "@types/react": "^19.1.1",
+    "react": "19.0.4",
+    "react-native": "0.83.2",
     "del-cli": "^5.1.0",
     "jest": "^29.7.0"
   },
   "peerDependencies": {
-    "react": "*",
-    "react-native": "*",
-    "react-native-nitro-modules": ">=0.33.0"
+    "react": ">=18.2.0",
+    "react-native": ">=0.72.0",
+    "react-native-nitro-modules": ">=0.33.0",
+    "expo": ">=51.0.0",
+    "expo-file-system": ">=17.0.0",
+    "expo-network": ">=7.0.0",
+    "react-native-tcp-socket": ">=6.0.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/network.ts

@@ -1,4 +1,4 @@
-import { NetworkInfo } from "react-native-network-info";
+import * as Network from "expo-network";
 
 /**
  * Smart IP Discovery
@@ -7,16 +7,12 @@ import { NetworkInfo } from "react-native-network-info";
  */
 export async function getBestIpAddress(): Promise<string | null> {
   try {
-    // 1. Try to get the standard IP address (usually WiFi)
-    const ip = await NetworkInfo.getIPV4Address();
+    const ip = await Network.getIpAddressAsync();
 
     if (ip && ip !== "0.0.0.0" && ip !== "127.0.0.1") {
       return ip;
     }
 
-    // Fallback logic could go here (e.g., iterating interfaces if exposed by a native module)
-    // For now, react-native-network-info is the standard abstraction.
-
     return null;
   } catch (error) {
     console.warn("[CouchKit] Failed to get IP address:", error);

package/src/server.ts

@@ -1,6 +1,6 @@
 import { useEffect, useState } from "react";
 import { StaticServer } from "react-native-nitro-http-server";
-import RNFS from "react-native-fs";
+import { Paths } from "expo-file-system";
 import { getBestIpAddress } from "./network";
 import { DEFAULT_HTTP_PORT, toErrorMessage } from "@couch-kit/core";
 
@@ -15,7 +15,8 @@ export interface CouchKitHostConfig {
  * 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).
+ * serving files from `staticDir` (or the iOS bundle directory + `/www` by default).
+ * On Android, `staticDir` must be provided since bundle assets live inside the APK.
  * In dev mode, skips the server and returns `devServerUrl` directly.
  *
  * @param config - Server configuration including port, dev mode, and static directory.
@@ -48,9 +49,11 @@ export const useStaticServer = (config: CouchKitHostConfig) => {
 
       // Production Mode: Serve assets from bundle
       try {
-        // Use staticDir if provided (required on Android where MainBundlePath is undefined),
-        // otherwise fall back to iOS MainBundlePath
-        const path = config.staticDir || `${RNFS.MainBundlePath}/www`;
+        // Use staticDir if provided (required on Android where bundle path is undefined),
+        // otherwise fall back to the iOS bundle directory via expo-file-system
+        const path =
+          config.staticDir ||
+          `${Paths.bundle.uri.replace(/^file:\/\//, "")}www`;
         const port = config.port || DEFAULT_HTTP_PORT;
 
         server = new StaticServer();

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: (.+)/);