@rynx-ai/server 0.1.0 → 0.1.9

package/dist/terminal-ws.js

@@ -1,123 +1,446 @@
-import { WebSocketServer } from "ws";
-const TERMINAL_PATH = /^\/api\/sessions\/([^/]+)\/terminal$/;
-const MAX_DIM = 1000;
-// PTY-output → WS coalescing, ported from omnigent's `_forward_pty_to_ws`
-// (ws_bridge.py): merge PTY chunks that arrive in the same tick into bounded
-// frames so a screen redraw is a few frames, not dozens. Cap each frame at
-// 64 KiB normally; drop to 2 KiB within 750 ms of user input so a post-keystroke
-// redraw stays in the browser terminal's synchronous-echo fast path (xterm falls
-// back to a laggy async write for frames over ~2 KiB). Oversize accumulations are
-// split across frames. Constants match omnigent's exactly.
-const WS_COALESCE_MAX_BYTES = 64 * 1024;
-const INTERACTIVE_WS_COALESCE_MAX_BYTES = 2048;
+import { WebSocket, WebSocketServer } from "ws";
+import { authorizeRuntimeWebRequest, RUNTIME_WEB_CAPABILITY_QUERY, } from "./runtime-web-auth.js";
+import { SessionTerminalOpenError, } from "./session-terminal-host.js";
+const RUNTIME_TERMINAL_PATH = /^\/api\/runtimes\/([^/]+)\/sessions\/([^/]+)\/terminal$/;
+const LEGACY_TERMINAL_PATH = /^\/api\/sessions\/([^/]+)\/terminal$/;
+const SELECTOR_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._~-]{0,255}$/;
+const MAX_DIMENSION = 1_000;
+const MAX_BROWSER_MESSAGE_BYTES = 64 * 1024;
+const MAX_PENDING_BROWSER_MESSAGES = 32;
+const MAX_PENDING_BROWSER_BYTES = 128 * 1024;
+const MAX_BROWSER_BUFFERED_BYTES = 1024 * 1024;
+const INTERACTIVE_OUTPUT_CHUNK_BYTES = 2 * 1024;
+const NORMAL_OUTPUT_CHUNK_BYTES = 16 * 1024;
 const INTERACTIVE_ECHO_WINDOW_MS = 750;
-// Application WebSocket close codes, matching omnigent (ws_bridge.py). 4404 = the
-// pane's inner process exited / session gone; 4500 = bridge could not open the
-// terminal. The frontend's isUnexpectedTerminalClose auto-reconnects only on
-// transport codes (1006 etc.), so these 4xxx codes correctly land on the
-// dead-pane overlay instead of a reconnect loop. rynx's server-initiated close is
-// always "gone" (a client *detach* is client-initiated and never reaches here),
-// so omnigent's 4405 "detached" has no rynx counterpart.
-const WS_CLOSE_TERMINAL_GONE = 4404;
+const WS_CLOSE_BAD_REQUEST = 4400;
+const WS_CLOSE_UNAUTHORIZED = 4403;
+/** Reserved exclusively for an attachment that was not live at open time. */
+const WS_CLOSE_TERMINAL_NOT_LIVE = 4404;
+const WS_CLOSE_TERMINAL_EXITED = 4405;
+const WS_CLOSE_RUNTIME_UNAVAILABLE = 4406;
+const WS_CLOSE_BACKPRESSURE = 4408;
 const WS_CLOSE_INTERNAL_ERROR = 4500;
-/** Attach the terminal WS upgrade handler to a running http.Server. */
+/** Attach the authenticated Runtime-scoped terminal bridge to an HTTP server. */
 export function attachTerminalWs(server, deps) {
-    const wss = new WebSocketServer({ noServer: true });
-    server.on("upgrade", (req, socket, head) => {
-        let url;
+    const wss = new WebSocketServer({
+        noServer: true,
+        perMessageDeflate: false,
+        maxPayload: MAX_BROWSER_MESSAGE_BYTES,
+    });
+    server.on("upgrade", (request, socket, head) => {
+        const parsed = parseTerminalUpgrade(request);
+        if (!parsed)
+            return;
+        if ("failure" in parsed) {
+            rejectUpgrade(socket, 400, parsed.failure);
+            return;
+        }
+        const { url, route } = parsed;
+        const authorization = authorizeRuntimeWebRequest(request, {
+            mutation: true,
+            capability: url.searchParams.get(RUNTIME_WEB_CAPABILITY_QUERY) ?? "",
+        });
+        if (authorization) {
+            rejectUpgrade(socket, authorization.status, authorization.error);
+            return;
+        }
         try {
-            url = new URL(req.url ?? "", "http://localhost");
+            wss.handleUpgrade(request, socket, head, (ws) => {
+                void handleConnection(ws, url, route, deps);
+            });
         }
         catch {
-            return;
+            rejectUpgrade(socket, 400, "invalid terminal WebSocket upgrade");
         }
-        const match = TERMINAL_PATH.exec(url.pathname);
-        if (!match)
-            return; // Not our route — leave it for any other upgrade handler.
-        wss.handleUpgrade(req, socket, head, (ws) => {
-            handleConnection(ws, url, decodeURIComponent(match[1]), deps);
-        });
     });
     return wss;
 }
-function clampDim(raw, fallback) {
-    const n = raw ? Number.parseInt(raw, 10) : Number.NaN;
-    return Number.isFinite(n) && n > 0 && n <= MAX_DIM ? n : fallback;
-}
-function handleConnection(ws, url, sessionId, deps) {
-    const role = url.searchParams.get("role") === "read-only" ? "read-only" : "owner";
-    const cols = clampDim(url.searchParams.get("cols"), 80);
-    const rows = clampDim(url.searchParams.get("rows"), 24);
-    const cwd = deps.resolveCwd?.(sessionId) ?? process.cwd();
-    const term = deps.runnerManager.openTerminal(sessionId, {
-        role,
-        cwd,
-        cols,
-        rows,
-        ...(deps.command ? { command: deps.command } : {}),
-        ...(deps.args ? { args: deps.args } : {}),
-    });
-    const sendText = (obj) => {
-        if (ws.readyState === ws.OPEN)
-            ws.send(JSON.stringify(obj));
-    };
-    // Monotonic-ish stamp of the last client keystroke, so a redraw right after
-    // input takes the smaller interactive frame cap (omnigent `last_client_input_at`).
+async function handleConnection(ws, url, route, deps) {
+    let role;
+    let cols;
+    let rows;
+    try {
+        role = queryRole(url.searchParams.get("role"));
+        cols = queryDimension(url.searchParams.get("cols"), 80, "cols");
+        rows = queryDimension(url.searchParams.get("rows"), 24, "rows");
+    }
+    catch (error) {
+        closeBrowser(ws, WS_CLOSE_BAD_REQUEST, "invalid terminal options", error instanceof Error ? error.message : "invalid terminal options");
+        return;
+    }
+    const controller = new AbortController();
+    const pendingInputs = [];
+    let pendingInputBytes = 0;
+    let lease;
+    let terminal;
+    let browserClosed = false;
+    let cleanupPromise;
     let lastClientInputAt = 0;
-    // Chunks buffered within the current tick, flushed coalesced on the next.
-    let pending = [];
-    let flushScheduled = false;
-    const flushOutput = () => {
-        flushScheduled = false;
-        if (ws.readyState !== ws.OPEN || pending.length === 0) {
-            pending = [];
+    let liveInputTail = Promise.resolve();
+    let liveInputFrames = 0;
+    let liveInputBytes = 0;
+    let inputReady = false;
+    const cleanup = () => {
+        if (cleanupPromise)
+            return cleanupPromise;
+        browserClosed = true;
+        controller.abort(new Error("Browser terminal disconnected"));
+        pendingInputs.length = 0;
+        pendingInputBytes = 0;
+        const opened = terminal;
+        terminal = undefined;
+        const acquired = lease;
+        lease = undefined;
+        cleanupPromise = (async () => {
+            try {
+                await opened?.close();
+            }
+            finally {
+                acquired?.release();
+            }
+        })();
+        return cleanupPromise;
+    };
+    const keepAliveMs = deps.keepAliveMs ?? 25_000;
+    const keepalive = keepAliveMs > 0
+        ? setInterval(() => {
+            if (ws.readyState === WebSocket.OPEN)
+                ws.ping();
+        }, keepAliveMs)
+        : undefined;
+    keepalive?.unref?.();
+    ws.on("message", (data, isBinary) => {
+        if (browserClosed)
             return;
+        let input;
+        try {
+            input = parseBrowserInput(data, isBinary);
         }
-        const merged = pending.length === 1 ? pending[0] : Buffer.concat(pending);
-        pending = [];
-        const limit = Date.now() - lastClientInputAt < INTERACTIVE_ECHO_WINDOW_MS
-            ? INTERACTIVE_WS_COALESCE_MAX_BYTES
-            : WS_COALESCE_MAX_BYTES;
-        for (let off = 0; off < merged.length; off += limit) {
-            ws.send(merged.subarray(off, Math.min(off + limit, merged.length)));
+        catch (error) {
+            closeBrowser(ws, WS_CLOSE_BAD_REQUEST, "invalid terminal input", error instanceof Error ? error.message : "invalid terminal input");
+            void cleanup();
+            return;
         }
-    };
-    term.onData((chunk) => {
-        pending.push(Buffer.from(chunk, "utf8"));
-        if (!flushScheduled) {
-            flushScheduled = true;
-            setImmediate(flushOutput);
+        if (input.type === "input")
+            lastClientInputAt = Date.now();
+        const bytes = input.type === "input" ? input.data.byteLength : 16;
+        const opened = terminal;
+        if (opened && inputReady) {
+            if (liveInputFrames >= MAX_PENDING_BROWSER_MESSAGES ||
+                liveInputBytes + bytes > MAX_PENDING_BROWSER_BYTES) {
+                closeBrowser(ws, WS_CLOSE_BACKPRESSURE, "terminal input queue full", "Terminal input exceeded its bounded live queue");
+                void cleanup();
+                return;
+            }
+            liveInputFrames += 1;
+            liveInputBytes += bytes;
+            const operation = liveInputTail.then(() => applyBrowserInput(opened, input));
+            liveInputTail = operation
+                .catch((error) => {
+                closeForError(ws, error);
+                void cleanup();
+            })
+                .finally(() => {
+                liveInputFrames -= 1;
+                liveInputBytes -= bytes;
+            });
+            return;
         }
+        if (pendingInputs.length >= MAX_PENDING_BROWSER_MESSAGES ||
+            pendingInputBytes + bytes > MAX_PENDING_BROWSER_BYTES) {
+            closeBrowser(ws, WS_CLOSE_BACKPRESSURE, "terminal input queue full", "Terminal input exceeded its bounded pre-open queue");
+            void cleanup();
+            return;
+        }
+        pendingInputs.push({ input, bytes });
+        pendingInputBytes += bytes;
     });
-    term.onExit(() => {
-        flushOutput(); // drain the pane's final bytes before the close frame
-        sendText({ t: "exit" });
-        ws.close(WS_CLOSE_TERMINAL_GONE, "terminal session ended");
+    ws.on("close", () => {
+        if (keepalive)
+            clearInterval(keepalive);
+        void cleanup();
     });
-    term.ready.then((opened) => sendText({ t: "opened", role: opened.role }), (error) => {
-        sendText({ t: "error", message: error instanceof Error ? error.message : String(error) });
-        ws.close(WS_CLOSE_INTERNAL_ERROR, "terminal bridge error");
+    ws.on("error", () => {
+        if (keepalive)
+            clearInterval(keepalive);
+        void cleanup();
     });
-    ws.on("message", (data, isBinary) => {
-        if (isBinary) {
-            lastClientInputAt = Date.now();
-            term.write(data.toString("utf8"));
+    try {
+        let opening;
+        if (route.legacy) {
+            if (!deps.legacyLocalTerminalHost) {
+                throw new SessionTerminalOpenError("method_not_found", "Legacy local Session terminals are unavailable");
+            }
+            opening = deps.legacyLocalTerminalHost.open(route.sessionId, {
+                role,
+                cols,
+                rows,
+                signal: controller.signal,
+            });
+        }
+        else {
+            if (!deps.runtimeConnectionResolver) {
+                throw new SessionTerminalOpenError("method_not_found", "Runtime-scoped Session terminals are unavailable");
+            }
+            const acquired = await deps.runtimeConnectionResolver.acquire(route.selector, {
+                signal: controller.signal,
+            });
+            if (browserClosed || controller.signal.aborted) {
+                acquired.release();
+                return;
+            }
+            lease = acquired;
+            opening = acquired.openSessionTerminal(route.sessionId, {
+                role,
+                cols,
+                rows,
+                signal: controller.signal,
+                timeoutMs: 10_000,
+            });
+        }
+        const opened = await opening;
+        if (browserClosed) {
+            await opened.close().catch(() => undefined);
             return;
         }
-        try {
-            const msg = JSON.parse(data.toString("utf8"));
-            if (msg.t === "resize" && typeof msg.cols === "number" && typeof msg.rows === "number") {
-                term.resize(msg.cols, msg.rows);
+        terminal = opened;
+        sendText(ws, { t: "opened", role: opened.role });
+        while (pendingInputs.length > 0) {
+            const batch = pendingInputs.splice(0);
+            for (const queued of batch) {
+                pendingInputBytes -= queued.bytes;
+                await applyBrowserInput(opened, queued.input);
             }
-            else if (msg.t === "input" && typeof msg.data === "string") {
-                lastClientInputAt = Date.now();
-                term.write(msg.data);
+        }
+        pendingInputBytes = 0;
+        inputReady = true;
+        for await (const output of opened) {
+            if (browserClosed)
+                return;
+            const chunkSize = Date.now() - lastClientInputAt < INTERACTIVE_ECHO_WINDOW_MS
+                ? INTERACTIVE_OUTPUT_CHUNK_BYTES
+                : NORMAL_OUTPUT_CHUNK_BYTES;
+            for (let offset = 0; offset < output.byteLength; offset += chunkSize) {
+                await sendBinary(ws, output.subarray(offset, Math.min(offset + chunkSize, output.byteLength)));
             }
         }
-        catch {
-            // Ignore malformed control frames.
+        if (browserClosed)
+            return;
+        const closed = await opened.closed;
+        closeForTerminalEnd(ws, closed.reason);
+    }
+    catch (error) {
+        if (!browserClosed)
+            closeForError(ws, error);
+    }
+    finally {
+        if (keepalive)
+            clearInterval(keepalive);
+        await cleanup().catch(() => undefined);
+    }
+}
+function parseTerminalUpgrade(request) {
+    let url;
+    try {
+        url = new URL(request.url ?? "", "http://localhost");
+    }
+    catch {
+        return undefined;
+    }
+    const runtimeMatch = RUNTIME_TERMINAL_PATH.exec(url.pathname);
+    const legacyMatch = LEGACY_TERMINAL_PATH.exec(url.pathname);
+    if (!runtimeMatch && !legacyMatch)
+        return undefined;
+    try {
+        if (runtimeMatch) {
+            const selector = decodeURIComponent(runtimeMatch[1]);
+            const sessionId = decodeURIComponent(runtimeMatch[2]);
+            if (!SELECTOR_PATTERN.test(selector) || !validSessionId(sessionId)) {
+                return { failure: "invalid terminal route" };
+            }
+            return { url, route: { selector, sessionId, legacy: false } };
         }
+        const sessionId = decodeURIComponent(legacyMatch[1]);
+        if (!validSessionId(sessionId))
+            return { failure: "invalid terminal route" };
+        return { url, route: { selector: "local", sessionId, legacy: true } };
+    }
+    catch {
+        return { failure: "invalid terminal route encoding" };
+    }
+}
+function parseBrowserInput(data, isBinary) {
+    const bytes = rawDataBytes(data);
+    if (bytes.byteLength === 0 || bytes.byteLength > MAX_BROWSER_MESSAGE_BYTES) {
+        throw new Error("Terminal input frame size is invalid");
+    }
+    if (isBinary)
+        return { type: "input", data: bytes };
+    const value = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error("Terminal control frame must be an object");
+    }
+    const frame = value;
+    if (frame.t === "resize" &&
+        Object.keys(frame).every((key) => key === "t" || key === "cols" || key === "rows") &&
+        validDimension(frame.cols) &&
+        validDimension(frame.rows)) {
+        return { type: "resize", cols: frame.cols, rows: frame.rows };
+    }
+    if (frame.t === "input" &&
+        Object.keys(frame).every((key) => key === "t" || key === "data") &&
+        typeof frame.data === "string" &&
+        frame.data.length > 0 &&
+        Buffer.byteLength(frame.data, "utf8") <= MAX_BROWSER_MESSAGE_BYTES) {
+        return { type: "input", data: Uint8Array.from(Buffer.from(frame.data, "utf8")) };
+    }
+    throw new Error("Unknown or invalid terminal control frame");
+}
+async function applyBrowserInput(terminal, input) {
+    if (input.type === "input") {
+        // Defense in depth: tmux -r also blocks writes, but bytes never reach it.
+        if (terminal.role === "owner")
+            await terminal.write(input.data);
+        return;
+    }
+    await terminal.resize(input.cols, input.rows);
+}
+async function sendBinary(ws, data) {
+    if (ws.readyState !== WebSocket.OPEN)
+        throw transportError("Browser terminal is closed");
+    if (ws.bufferedAmount + data.byteLength > MAX_BROWSER_BUFFERED_BYTES) {
+        const error = new Error("Browser terminal output exceeded its bounded buffer");
+        error.name = "BackpressureError";
+        throw error;
+    }
+    await new Promise((resolve, reject) => {
+        ws.send(data, { binary: true, compress: false }, (error) => {
+            if (error)
+                reject(transportError(error.message));
+            else
+                resolve();
+        });
     });
-    ws.on("close", () => term.close());
-    ws.on("error", () => term.close());
+}
+function sendText(ws, value) {
+    if (ws.readyState === WebSocket.OPEN) {
+        ws.send(JSON.stringify(value), { binary: false, compress: false });
+    }
+}
+function closeForTerminalEnd(ws, reason) {
+    if (reason === "client_closed")
+        return;
+    if (reason === "terminal_exited") {
+        closeBrowser(ws, WS_CLOSE_TERMINAL_EXITED, "terminal exited");
+        return;
+    }
+    if (reason === "backpressure" || reason === "capacity") {
+        closeBrowser(ws, WS_CLOSE_BACKPRESSURE, "terminal backpressure");
+        return;
+    }
+    if (reason === "unauthorized") {
+        closeBrowser(ws, WS_CLOSE_UNAUTHORIZED, "terminal authorization revoked");
+        return;
+    }
+    closeBrowser(ws, WS_CLOSE_INTERNAL_ERROR, "terminal bridge error");
+}
+function closeForError(ws, error) {
+    const code = errorCode(error);
+    const message = error instanceof Error ? error.message : "Terminal bridge failed";
+    if (code === "not_live") {
+        closeBrowser(ws, WS_CLOSE_TERMINAL_NOT_LIVE, "terminal not live");
+    }
+    else if (code === "unauthorized" || code === "authentication_failed") {
+        closeBrowser(ws, WS_CLOSE_UNAUTHORIZED, "terminal authorization failed");
+    }
+    else if (code === "method_not_found" || code === "incompatible" || code === "not_found") {
+        closeBrowser(ws, WS_CLOSE_RUNTIME_UNAVAILABLE, "terminal runtime unavailable");
+    }
+    else if (code === "capacity" || errorName(error) === "BackpressureError") {
+        closeBrowser(ws, WS_CLOSE_BACKPRESSURE, "terminal backpressure");
+    }
+    else if (code === "unreachable" ||
+        code === "closed" ||
+        code === "deadline_exceeded" ||
+        errorName(error) === "AbortError" ||
+        errorName(error) === "TransportError") {
+        closeBrowser(ws, 1012, "terminal transport unavailable");
+    }
+    else {
+        sendText(ws, { t: "error", message });
+        closeBrowser(ws, WS_CLOSE_INTERNAL_ERROR, "terminal bridge error");
+    }
+}
+function closeBrowser(ws, code, reason, message) {
+    if (message)
+        sendText(ws, { t: "error", message });
+    if (ws.readyState === WebSocket.OPEN)
+        ws.close(code, boundedCloseReason(reason));
+}
+function errorCode(error) {
+    return error && typeof error === "object" && "code" in error ? error.code : undefined;
+}
+function errorName(error) {
+    return error && typeof error === "object" && "name" in error ? error.name : undefined;
+}
+function transportError(message) {
+    const error = new Error(message);
+    error.name = "TransportError";
+    return error;
+}
+function queryDimension(raw, fallback, field) {
+    if (raw === null)
+        return fallback;
+    const value = Number(raw);
+    if (!validDimension(value)) {
+        throw new Error(`Terminal ${field} must be an integer within 1..${MAX_DIMENSION}`);
+    }
+    return value;
+}
+function queryRole(raw) {
+    if (raw === null || raw === "owner")
+        return "owner";
+    if (raw === "read-only")
+        return "read-only";
+    throw new Error("Terminal role must be owner or read-only");
+}
+function validDimension(value) {
+    return Number.isSafeInteger(value) && value >= 1 && value <= MAX_DIMENSION;
+}
+function validSessionId(value) {
+    return value.length > 0 && value.length <= 256 && !/[\u0000-\u001f\u007f]/.test(value);
+}
+function rawDataBytes(data) {
+    if (Buffer.isBuffer(data))
+        return Uint8Array.from(data);
+    if (data instanceof ArrayBuffer)
+        return new Uint8Array(data.slice(0));
+    if (Array.isArray(data))
+        return Uint8Array.from(Buffer.concat(data));
+    return Uint8Array.from(Buffer.from(data));
+}
+function rejectUpgrade(socket, status, message) {
+    if (socket.destroyed)
+        return;
+    const body = `${message}\n`;
+    socket.end(`HTTP/1.1 ${status} ${status === 401 ? "Unauthorized" : status === 403 ? "Forbidden" : "Bad Request"}\r\n` +
+        "Connection: close\r\n" +
+        "Content-Type: text/plain; charset=utf-8\r\n" +
+        `Content-Length: ${Buffer.byteLength(body, "utf8")}\r\n` +
+        "Cache-Control: no-store\r\n\r\n" +
+        body);
+}
+function boundedCloseReason(reason) {
+    if (Buffer.byteLength(reason, "utf8") <= 123)
+        return reason;
+    let bounded = "";
+    let bytes = 0;
+    for (const character of reason) {
+        const characterBytes = Buffer.byteLength(character, "utf8");
+        if (bytes + characterBytes > 123)
+            break;
+        bounded += character;
+        bytes += characterBytes;
+    }
+    return bounded;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rynx-ai/server",
-  "version": "0.1.0",
+  "version": "0.1.9",
   "description": "Composition root: wires the @rynx-ai/runtime host to channel plugins (injected by the daemon) and exposes a liveness HTTP probe.",
   "type": "module",
   "publishConfig": {
@@ -22,16 +22,18 @@
     "@koa/router": "^15.4.0",
     "koa": "^3.2.0",
     "ws": "^8.21.0",
-    "@rynx-ai/control-web": "0.1.0",
-    "@rynx-ai/runtime": "0.1.0",
-    "@rynx-ai/core": "0.1.0",
-    "@rynx-ai/protocol": "0.1.0"
+    "@rynx-ai/core": "0.1.9",
+    "@rynx-ai/plugin-sdk": "0.1.9",
+    "@rynx-ai/remote-runtime-e2ee": "0.1.9",
+    "@rynx-ai/runtime": "0.1.9",
+    "@rynx-ai/protocol": "0.1.9"
   },
   "devDependencies": {
-    "@types/ws": "^8.18.1"
+    "@types/ws": "^8.18.1",
+    "@rynx-ai/control-web": "0.1.9"
   },
   "scripts": {
-    "build": "rm -rf dist && tsc -p tsconfig.json",
+    "build": "rm -rf dist && tsc -p tsconfig.json && mkdir -p dist/control-web && cp -R ../control-web/dist/. dist/control-web/",
     "start": "node dist/server.js",
     "dev": "tsx watch --tsconfig ../../tsconfig.json src/server.ts"
   }