@quenty/studio-bridge 0.7.1 → 0.8.0

package/src/bridge/internal/transport-server.test.ts

@@ -0,0 +1,220 @@
+/**
+ * Unit tests for TransportServer — validates port binding, path-based
+ * WebSocket routing, HTTP health endpoint delegation, and cleanup.
+ */
+
+import { describe, it, expect, afterEach } from 'vitest';
+import { WebSocket } from 'ws';
+import http from 'http';
+import { TransportServer } from './transport-server.js';
+
+function connectWs(port: number, path: string): Promise<WebSocket> {
+  return new Promise((resolve, reject) => {
+    const ws = new WebSocket(`ws://localhost:${port}${path}`);
+    ws.on('open', () => resolve(ws));
+    ws.on('error', reject);
+  });
+}
+
+function connectWsExpectReject(port: number, path: string): Promise<string> {
+  return new Promise((resolve) => {
+    const ws = new WebSocket(`ws://localhost:${port}${path}`);
+    ws.on('error', () => resolve('error'));
+    ws.on('unexpected-response', () => {
+      ws.close();
+      resolve('rejected');
+    });
+  });
+}
+
+function httpGet(
+  port: number,
+  path: string
+): Promise<{ status: number; body: string }> {
+  return new Promise((resolve, reject) => {
+    http
+      .get(`http://localhost:${port}${path}`, (res) => {
+        let body = '';
+        res.on('data', (chunk: Buffer | string) => {
+          body += chunk;
+        });
+        res.on('end', () => {
+          resolve({ status: res.statusCode ?? 0, body });
+        });
+        res.on('error', reject);
+      })
+      .on('error', reject);
+  });
+}
+
+describe('TransportServer', () => {
+  let server: TransportServer | undefined;
+  const openClients: WebSocket[] = [];
+
+  afterEach(async () => {
+    for (const ws of openClients) {
+      if (
+        ws.readyState === WebSocket.OPEN ||
+        ws.readyState === WebSocket.CONNECTING
+      ) {
+        ws.close();
+      }
+    }
+    openClients.length = 0;
+
+    if (server) {
+      await server.stopAsync();
+      server = undefined;
+    }
+  });
+
+  describe('startAsync', () => {
+    it('binds to an ephemeral port and returns the actual port', async () => {
+      server = new TransportServer();
+      const port = await server.startAsync({ port: 0 });
+
+      expect(port).toBeGreaterThan(0);
+      expect(server.port).toBe(port);
+      expect(server.isListening).toBe(true);
+    });
+
+    it('throws when trying to start while already listening', async () => {
+      server = new TransportServer();
+      await server.startAsync({ port: 0 });
+
+      await expect(server.startAsync({ port: 0 })).rejects.toThrow(
+        'TransportServer is already listening'
+      );
+    });
+
+    it('reports EADDRINUSE when port is taken', async () => {
+      server = new TransportServer();
+      const port = await server.startAsync({ port: 0 });
+
+      const server2 = new TransportServer();
+      await expect(server2.startAsync({ port })).rejects.toThrow(
+        `Port ${port} is already in use`
+      );
+    });
+  });
+
+  describe('onConnection', () => {
+    it('routes WebSocket connections to registered path handlers', async () => {
+      server = new TransportServer();
+
+      const connections: string[] = [];
+      server.onConnection('/plugin', () => {
+        connections.push('plugin');
+      });
+      server.onConnection('/client', () => {
+        connections.push('client');
+      });
+
+      const port = await server.startAsync({ port: 0 });
+
+      const ws1 = await connectWs(port, '/plugin');
+      openClients.push(ws1);
+      // Allow event loop to process
+      await new Promise((r) => setTimeout(r, 50));
+      expect(connections).toContain('plugin');
+
+      const ws2 = await connectWs(port, '/client');
+      openClients.push(ws2);
+      await new Promise((r) => setTimeout(r, 50));
+      expect(connections).toContain('client');
+    });
+
+    it('rejects WebSocket connections on unregistered paths with 404', async () => {
+      server = new TransportServer();
+      server.onConnection('/plugin', () => {});
+      const port = await server.startAsync({ port: 0 });
+
+      const result = await connectWsExpectReject(port, '/unknown');
+      expect(['error', 'rejected']).toContain(result);
+    });
+
+    it('passes the WebSocket and request to the handler', async () => {
+      server = new TransportServer();
+
+      let receivedWs: WebSocket | undefined;
+      let receivedUrl: string | undefined;
+
+      server.onConnection('/plugin', (ws, req) => {
+        receivedWs = ws;
+        receivedUrl = req.url;
+      });
+
+      const port = await server.startAsync({ port: 0 });
+      const ws = await connectWs(port, '/plugin');
+      openClients.push(ws);
+
+      await new Promise((r) => setTimeout(r, 50));
+
+      expect(receivedWs).toBeDefined();
+      expect(receivedUrl).toBe('/plugin');
+    });
+  });
+
+  describe('onHttpRequest', () => {
+    it('routes HTTP GET requests to registered path handlers', async () => {
+      server = new TransportServer();
+      server.onHttpRequest('/health', (_req, res) => {
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ status: 'ok' }));
+      });
+
+      const port = await server.startAsync({ port: 0 });
+      const result = await httpGet(port, '/health');
+
+      expect(result.status).toBe(200);
+      expect(JSON.parse(result.body)).toEqual({ status: 'ok' });
+    });
+
+    it('returns 404 for unregistered HTTP paths', async () => {
+      server = new TransportServer();
+      const port = await server.startAsync({ port: 0 });
+
+      const result = await httpGet(port, '/nonexistent');
+      expect(result.status).toBe(404);
+    });
+  });
+
+  describe('stopAsync', () => {
+    it('closes the server and resets state', async () => {
+      server = new TransportServer();
+      await server.startAsync({ port: 0 });
+
+      expect(server.isListening).toBe(true);
+
+      await server.stopAsync();
+
+      expect(server.isListening).toBe(false);
+      expect(server.port).toBe(0);
+    });
+
+    it('is idempotent', async () => {
+      server = new TransportServer();
+      await server.startAsync({ port: 0 });
+
+      await server.stopAsync();
+      // Second call should not throw
+      await server.stopAsync();
+    });
+
+    it('terminates connected WebSocket clients', async () => {
+      server = new TransportServer();
+      server.onConnection('/plugin', () => {});
+      const port = await server.startAsync({ port: 0 });
+
+      const ws = await connectWs(port, '/plugin');
+
+      const closedPromise = new Promise<void>((resolve) => {
+        ws.on('close', () => resolve());
+      });
+
+      await server.stopAsync();
+      await closedPromise;
+      // If we get here, the client was terminated
+    });
+  });
+});

package/src/bridge/internal/transport-server.ts

@@ -0,0 +1,242 @@
+/**
+ * Low-level WebSocket server with path-based routing. Handles HTTP server
+ * creation, port binding, WebSocket upgrade for registered paths, and HTTP
+ * GET for the /health endpoint. No business logic — it is a dumb pipe that
+ * routes connections by URL path.
+ */
+
+import {
+  createServer,
+  type IncomingMessage,
+  type ServerResponse,
+  type Server,
+} from 'http';
+import type { Socket } from 'net';
+import { WebSocketServer, WebSocket } from 'ws';
+import { URL } from 'url';
+
+export interface TransportServerOptions {
+  /** Port to bind on. Default: 38741. Use 0 for ephemeral (test-friendly). */
+  port?: number;
+  /** Host to bind on. Default: 'localhost'. */
+  host?: string;
+}
+
+export type ConnectionHandler = (
+  ws: WebSocket,
+  request: IncomingMessage
+) => void;
+export type HttpHandler = (req: IncomingMessage, res: ServerResponse) => void;
+
+const DEFAULT_PORT = 38741;
+const DEFAULT_HOST = 'localhost';
+
+export class TransportServer {
+  private _httpServer: Server | undefined;
+  private _wss: WebSocketServer | undefined;
+  private _port = 0;
+  private _isListening = false;
+  private readonly _sockets = new Set<Socket>();
+
+  private readonly _wsHandlers = new Map<string, ConnectionHandler>();
+  private readonly _httpHandlers = new Map<string, HttpHandler>();
+
+  /**
+   * Start the WebSocket server. Binds to the specified port.
+   * Uses `exclusive: false` for SO_REUSEADDR so the port can be reused
+   * after a crash without waiting for TIME_WAIT.
+   * Returns the actual bound port (important when port: 0 is used).
+   */
+  async startAsync(options?: TransportServerOptions): Promise<number> {
+    if (this._isListening) {
+      throw new Error('TransportServer is already listening');
+    }
+
+    const port = options?.port ?? DEFAULT_PORT;
+    const host = options?.host ?? DEFAULT_HOST;
+
+    this._httpServer = createServer((req, res) => {
+      this._handleHttpRequest(req, res);
+    });
+
+    // Track all raw TCP sockets so forceCloseAsync() can destroy them
+    this._httpServer.on('connection', (socket: Socket) => {
+      this._sockets.add(socket);
+      socket.on('close', () => {
+        this._sockets.delete(socket);
+      });
+    });
+
+    this._wss = new WebSocketServer({ noServer: true });
+
+    this._httpServer.on('upgrade', (request, socket, head) => {
+      const pathname = this._parsePath(request);
+      const handler = this._wsHandlers.get(pathname);
+
+      if (!handler) {
+        socket.write('HTTP/1.1 404 Not Found\r\n\r\n');
+        socket.destroy();
+        return;
+      }
+
+      this._wss!.handleUpgrade(request, socket, head, (ws) => {
+        handler(ws, request);
+      });
+    });
+
+    return new Promise<number>((resolve, reject) => {
+      const server = this._httpServer!;
+
+      const onError = (err: NodeJS.ErrnoException) => {
+        server.off('listening', onListening);
+        if (err.code === 'EADDRINUSE') {
+          reject(new Error(`Port ${port} is already in use`));
+        } else {
+          reject(err);
+        }
+      };
+
+      const onListening = () => {
+        server.off('error', onError);
+        const addr = server.address();
+        if (typeof addr === 'object' && addr !== null) {
+          this._port = addr.port;
+        }
+        this._isListening = true;
+        resolve(this._port);
+      };
+
+      server.once('error', onError);
+      server.once('listening', onListening);
+      // SO_REUSEADDR is enabled by default in Node's net module, allowing
+      // the port to be rebound immediately after a process crash without
+      // waiting for TIME_WAIT to expire. This is essential for host failover.
+      server.listen(port, host, undefined, undefined);
+    });
+  }
+
+  /**
+   * Stop the server and close all connections.
+   */
+  async stopAsync(): Promise<void> {
+    if (!this._isListening) {
+      return;
+    }
+    this._isListening = false;
+
+    // Terminate all WebSocket connections first
+    if (this._wss) {
+      for (const client of this._wss.clients) {
+        client.terminate();
+      }
+    }
+
+    // Close the WebSocket server
+    if (this._wss) {
+      await new Promise<void>((resolve) => {
+        this._wss!.close(() => resolve());
+      });
+      this._wss = undefined;
+    }
+
+    // Close the HTTP server
+    if (this._httpServer) {
+      await new Promise<void>((resolve) => {
+        this._httpServer!.close(() => resolve());
+      });
+      this._httpServer = undefined;
+    }
+
+    this._port = 0;
+  }
+
+  /** The actual port the server is bound to. */
+  get port(): number {
+    return this._port;
+  }
+
+  /** Whether the server is currently listening. */
+  get isListening(): boolean {
+    return this._isListening;
+  }
+
+  /**
+   * Register a handler for WebSocket connections on a specific path.
+   * Paths: '/plugin' for Studio plugins, '/client' for CLI clients.
+   */
+  onConnection(path: string, handler: ConnectionHandler): void {
+    this._wsHandlers.set(path, handler);
+  }
+
+  /**
+   * Register an HTTP request handler for a specific path.
+   * Used for '/health' to handle plain HTTP GET requests.
+   */
+  onHttpRequest(path: string, handler: HttpHandler): void {
+    this._httpHandlers.set(path, handler);
+  }
+
+  /**
+   * Force-close the server by destroying all open TCP sockets immediately.
+   * Unlike stopAsync(), this does not wait for graceful close handshakes.
+   * Used during host shutdown to release the port as fast as possible.
+   */
+  async forceCloseAsync(): Promise<void> {
+    if (!this._isListening) {
+      return;
+    }
+    this._isListening = false;
+
+    // Destroy all raw TCP sockets immediately
+    for (const socket of this._sockets) {
+      socket.destroy();
+    }
+    this._sockets.clear();
+
+    // Terminate all WebSocket connections
+    if (this._wss) {
+      for (const client of this._wss.clients) {
+        client.terminate();
+      }
+      await new Promise<void>((resolve) => {
+        this._wss!.close(() => resolve());
+      });
+      this._wss = undefined;
+    }
+
+    // Close the HTTP server
+    if (this._httpServer) {
+      await new Promise<void>((resolve) => {
+        this._httpServer!.close(() => resolve());
+      });
+      this._httpServer = undefined;
+    }
+
+    this._port = 0;
+  }
+
+  private _parsePath(request: IncomingMessage): string {
+    try {
+      const url = new URL(
+        request.url ?? '/',
+        `http://${request.headers.host ?? 'localhost'}`
+      );
+      return url.pathname;
+    } catch {
+      return '/';
+    }
+  }
+
+  private _handleHttpRequest(req: IncomingMessage, res: ServerResponse): void {
+    const pathname = this._parsePath(req);
+    const handler = this._httpHandlers.get(pathname);
+
+    if (handler) {
+      handler(req, res);
+      return;
+    }
+
+    res.writeHead(404, { 'Content-Type': 'text/plain' });
+    res.end('Not Found');
+  }
+}

package/src/bridge/types.ts

@@ -0,0 +1,161 @@
+/**
+ * Public types for the bridge network layer. Defines session metadata,
+ * instance grouping, action result types, and typed error classes.
+ *
+ * This module has no imports from internal/ -- it is a pure type definition
+ * file that forms the public API surface of the bridge network.
+ */
+
+import type {
+  StudioState,
+  Capability,
+  DataModelInstance,
+  OutputLevel,
+} from '../server/web-socket-protocol.js';
+
+// Re-export protocol types used in the public API
+export type { StudioState, Capability, DataModelInstance, OutputLevel };
+
+export type SessionContext = 'edit' | 'client' | 'server';
+export type SessionOrigin = 'user' | 'managed';
+
+export interface SessionInfo {
+  sessionId: string;
+  placeName: string;
+  placeFile?: string;
+  state: StudioState;
+  pluginVersion: string;
+  capabilities: Capability[];
+  connectedAt: Date;
+  origin: SessionOrigin;
+  context: SessionContext;
+  instanceId: string;
+  placeId: number;
+  gameId: number;
+}
+
+export interface InstanceInfo {
+  instanceId: string;
+  placeName: string;
+  placeId: number;
+  gameId: number;
+  contexts: SessionContext[];
+  origin: SessionOrigin;
+}
+
+export interface ExecResult {
+  success: boolean;
+  output: Array<{ level: OutputLevel; body: string }>;
+  error?: string;
+}
+
+export interface StateResult {
+  state: StudioState;
+  placeId: number;
+  placeName: string;
+  gameId: number;
+}
+
+export interface ScreenshotResult {
+  data: string;
+  format: 'png' | 'rgba';
+  width: number;
+  height: number;
+}
+
+export interface LogEntry {
+  level: OutputLevel;
+  body: string;
+  timestamp: number;
+}
+
+export interface LogsResult {
+  entries: LogEntry[];
+  total: number;
+  bufferCapacity: number;
+}
+
+export interface DataModelResult {
+  instance: DataModelInstance;
+}
+
+export interface LogOptions {
+  count?: number;
+  direction?: 'head' | 'tail';
+  levels?: OutputLevel[];
+  includeInternal?: boolean;
+}
+
+export interface QueryDataModelOptions {
+  path: string;
+  depth?: number;
+  properties?: string[];
+  includeAttributes?: boolean;
+  find?: { name: string; recursive?: boolean };
+  listServices?: boolean;
+}
+
+export interface LogFollowOptions {
+  levels?: OutputLevel[];
+}
+
+export class SessionNotFoundError extends Error {
+  constructor(message: string, public readonly sessionId?: string) {
+    super(message);
+    this.name = 'SessionNotFoundError';
+  }
+}
+
+export class ActionTimeoutError extends Error {
+  constructor(
+    public readonly action: string,
+    public readonly timeoutMs: number,
+    public readonly sessionId: string
+  ) {
+    super(
+      `Action '${action}' timed out after ${timeoutMs}ms on session '${sessionId}'`
+    );
+    this.name = 'ActionTimeoutError';
+  }
+}
+
+export class SessionDisconnectedError extends Error {
+  constructor(public readonly sessionId: string) {
+    super(`Session '${sessionId}' disconnected`);
+    this.name = 'SessionDisconnectedError';
+  }
+}
+
+export class CapabilityNotSupportedError extends Error {
+  constructor(
+    public readonly capability: string,
+    public readonly sessionId: string
+  ) {
+    super(
+      `Plugin does not support capability '${capability}' on session '${sessionId}'`
+    );
+    this.name = 'CapabilityNotSupportedError';
+  }
+}
+
+export class ContextNotFoundError extends Error {
+  constructor(
+    public readonly context: SessionContext,
+    public readonly instanceId: string,
+    public readonly availableContexts: SessionContext[]
+  ) {
+    super(
+      `Context '${context}' not connected on instance '${instanceId}'. Available: ${availableContexts.join(
+        ', '
+      )}`
+    );
+    this.name = 'ContextNotFoundError';
+  }
+}
+
+export class HostUnreachableError extends Error {
+  constructor(public readonly host: string, public readonly port: number) {
+    super(`Bridge host unreachable at ${host}:${port}`);
+    this.name = 'HostUnreachableError';
+  }
+}