@rynx-ai/server 0.1.0 → 0.1.10-beta.2

package/dist/browser-surface-control-queue.d.ts

@@ -0,0 +1,42 @@
+import { type RuntimeBrowserSurfaceClientFrame, type RuntimeBrowserSurfaceOpenFrame } from "@rynx-ai/protocol/runtime-browser-surface";
+type SurfaceControlFrame = Exclude<RuntimeBrowserSurfaceClientFrame, RuntimeBrowserSurfaceOpenFrame>;
+export interface BrowserSurfaceControlQueueOptions {
+    dispatch(frame: SurfaceControlFrame): void | Promise<void>;
+    onError(error: unknown): void;
+    maxPendingFrames?: number;
+    maxPendingBytes?: number;
+}
+export type BrowserSurfaceControlEnqueueResult = "queued" | "coalesced" | "dropped";
+/**
+ * Bounded semantic queue shared by the local browser bridge and Direct Surface.
+ *
+ * Wire records are parsed before entering this queue. Discrete input remains
+ * ordered and reliable while the connection is live. Pointer movement is
+ * latest-wins, wheel samples are merged only when adjacent, and an explicit
+ * driver intent fences input that has not started executing yet.
+ */
+export declare class BrowserSurfaceControlQueue {
+    private readonly options;
+    private readonly maxPendingFrames;
+    private readonly maxPendingBytes;
+    private readonly items;
+    private queuedBytes;
+    private inFlight;
+    private running;
+    private aborted;
+    private inputAdmission;
+    constructor(options: BrowserSurfaceControlQueueOptions);
+    enqueue(frame: SurfaceControlFrame): BrowserSurfaceControlEnqueueResult;
+    abort(): void;
+    private insert;
+    private replaceTail;
+    private hasCapacity;
+    private removePending;
+    private start;
+    private pump;
+}
+export declare class BrowserSurfaceControlQueueCapacityError extends Error {
+    readonly code: "capacity";
+    constructor();
+}
+export {};

package/dist/browser-surface-control-queue.js

@@ -0,0 +1,187 @@
+import { RUNTIME_BROWSER_SURFACE_MAX_CONTROL_FRAME_BYTES, RUNTIME_BROWSER_SURFACE_MAX_RELIABLE_INPUT_QUEUE, RUNTIME_BROWSER_SURFACE_MAX_WHEEL_DELTA, } from "@rynx-ai/protocol/runtime-browser-surface";
+const DEFAULT_MAX_PENDING_BYTES = RUNTIME_BROWSER_SURFACE_MAX_CONTROL_FRAME_BYTES * 16;
+/**
+ * Bounded semantic queue shared by the local browser bridge and Direct Surface.
+ *
+ * Wire records are parsed before entering this queue. Discrete input remains
+ * ordered and reliable while the connection is live. Pointer movement is
+ * latest-wins, wheel samples are merged only when adjacent, and an explicit
+ * driver intent fences input that has not started executing yet.
+ */
+export class BrowserSurfaceControlQueue {
+    options;
+    maxPendingFrames;
+    maxPendingBytes;
+    items = [];
+    queuedBytes = 0;
+    inFlight;
+    running = false;
+    aborted = false;
+    inputAdmission = true;
+    constructor(options) {
+        this.options = options;
+        this.maxPendingFrames = positiveLimit(options.maxPendingFrames, RUNTIME_BROWSER_SURFACE_MAX_RELIABLE_INPUT_QUEUE, "Browser Surface pending control frame limit");
+        this.maxPendingBytes = positiveLimit(options.maxPendingBytes, DEFAULT_MAX_PENDING_BYTES, "Browser Surface pending control byte limit");
+    }
+    enqueue(frame) {
+        if (this.aborted)
+            return "dropped";
+        if (frame.type === "browser.surface.driver.release") {
+            this.inputAdmission = false;
+            this.removePending((pending) => (pending.frame.type === "browser.surface.input" ||
+                pending.frame.type === "browser.surface.driver.take" ||
+                pending.frame.type === "browser.surface.driver.release"));
+            return this.insert(frame, "before-input");
+        }
+        if (frame.type === "browser.surface.driver.take") {
+            this.inputAdmission = true;
+            // A release is an input-state reset barrier, not a replaceable intent.
+            // Preserve it ahead of this take; only duplicate pending takes coalesce.
+            this.removePending((pending) => pending.frame.type === "browser.surface.driver.take");
+            return this.insert(frame, "tail");
+        }
+        if (frame.type === "browser.surface.frame.ack") {
+            return this.insert(frame, "before-input");
+        }
+        if (!this.inputAdmission)
+            return "dropped";
+        const tail = this.items.at(-1);
+        if (tail && isPointerMove(tail.frame) && isPointerMove(frame)) {
+            return this.replaceTail(frame);
+        }
+        if (tail && isWheel(tail.frame) && isWheel(frame)) {
+            return this.replaceTail(mergeWheel(tail.frame, frame));
+        }
+        return this.insert(frame, "tail", isLossyInput(frame));
+    }
+    abort() {
+        if (this.aborted)
+            return;
+        this.aborted = true;
+        this.inputAdmission = false;
+        this.items.length = 0;
+        this.queuedBytes = 0;
+    }
+    insert(frame, position, lossy = false) {
+        const pending = { frame, bytes: controlBytes(frame) };
+        if (!this.hasCapacity(pending.bytes)) {
+            if (lossy)
+                return "dropped";
+            const error = new BrowserSurfaceControlQueueCapacityError();
+            this.abort();
+            throw error;
+        }
+        if (position === "before-input") {
+            const firstInput = this.items.findIndex((item) => (item.frame.type === "browser.surface.input"));
+            if (firstInput === -1)
+                this.items.push(pending);
+            else
+                this.items.splice(firstInput, 0, pending);
+        }
+        else {
+            this.items.push(pending);
+        }
+        this.queuedBytes += pending.bytes;
+        this.start();
+        return "queued";
+    }
+    replaceTail(frame) {
+        const tail = this.items.at(-1);
+        if (!tail)
+            return this.insert(frame, "tail", true);
+        const bytes = controlBytes(frame);
+        const nextBytes = this.queuedBytes - tail.bytes + bytes;
+        if (nextBytes + (this.inFlight?.bytes ?? 0) > this.maxPendingBytes) {
+            return "dropped";
+        }
+        tail.frame = frame;
+        tail.bytes = bytes;
+        this.queuedBytes = nextBytes;
+        return "coalesced";
+    }
+    hasCapacity(bytes) {
+        const count = this.items.length + (this.inFlight ? 1 : 0);
+        const totalBytes = this.queuedBytes + (this.inFlight?.bytes ?? 0);
+        return count < this.maxPendingFrames && totalBytes + bytes <= this.maxPendingBytes;
+    }
+    removePending(predicate) {
+        for (let index = this.items.length - 1; index >= 0; index -= 1) {
+            const pending = this.items[index];
+            if (!predicate(pending))
+                continue;
+            this.items.splice(index, 1);
+            this.queuedBytes -= pending.bytes;
+        }
+    }
+    start() {
+        if (this.running || this.aborted)
+            return;
+        this.running = true;
+        void this.pump();
+    }
+    async pump() {
+        try {
+            while (!this.aborted) {
+                const pending = this.items.shift();
+                if (!pending)
+                    return;
+                this.queuedBytes -= pending.bytes;
+                this.inFlight = pending;
+                await this.options.dispatch(pending.frame);
+                this.inFlight = undefined;
+            }
+        }
+        catch (error) {
+            this.inFlight = undefined;
+            if (this.aborted)
+                return;
+            this.abort();
+            this.options.onError(error);
+        }
+        finally {
+            this.inFlight = undefined;
+            this.running = false;
+            if (!this.aborted && this.items.length > 0)
+                this.start();
+        }
+    }
+}
+export class BrowserSurfaceControlQueueCapacityError extends Error {
+    code = "capacity";
+    constructor() {
+        super("Browser Surface input queue is full");
+        this.name = "BackpressureError";
+    }
+}
+function controlBytes(frame) {
+    return Buffer.byteLength(JSON.stringify(frame), "utf8");
+}
+function isLossyInput(frame) {
+    return isPointerMove(frame) || isWheel(frame);
+}
+function isPointerMove(frame) {
+    return frame.type === "browser.surface.input" && frame.event.type === "pointer.move";
+}
+function isWheel(frame) {
+    return frame.type === "browser.surface.input" && frame.event.type === "wheel";
+}
+function mergeWheel(previous, next) {
+    return {
+        ...next,
+        event: {
+            ...next.event,
+            deltaX: clampWheel(previous.event.deltaX + next.event.deltaX),
+            deltaY: clampWheel(previous.event.deltaY + next.event.deltaY),
+        },
+    };
+}
+function clampWheel(value) {
+    return Math.max(-RUNTIME_BROWSER_SURFACE_MAX_WHEEL_DELTA, Math.min(RUNTIME_BROWSER_SURFACE_MAX_WHEEL_DELTA, value));
+}
+function positiveLimit(value, fallback, field) {
+    const resolved = value ?? fallback;
+    if (!Number.isSafeInteger(resolved) || resolved < 1) {
+        throw new Error(`${field} must be a positive safe integer`);
+    }
+    return resolved;
+}

package/dist/browser-surface-ws.d.ts

@@ -0,0 +1,16 @@
+import type { Server } from "node:http";
+import { WebSocketServer } from "ws";
+import { type RuntimeWebAccessPolicy } from "./runtime-web-auth.js";
+import type { RuntimeConnectionResolverHost } from "./server.js";
+export interface BrowserSurfaceWsDeps {
+    runtimeConnectionResolver?: RuntimeConnectionResolverHost;
+    runtimeWebAccess?: RuntimeWebAccessPolicy;
+    keepAliveMs?: number;
+    peerLivenessTimeoutMs?: number;
+}
+/**
+ * Attach the browser-facing, same-origin Surface bridge. The browser receives
+ * only bounded presentation frames; Runtime credentials and native CDP remain
+ * behind RuntimeConnectionResolverHost.
+ */
+export declare function attachBrowserSurfaceWs(server: Server, deps: BrowserSurfaceWsDeps): WebSocketServer;

package/dist/browser-surface-ws.js

@@ -0,0 +1,356 @@
+import { randomUUID } from "node:crypto";
+import { encodeRuntimeBrowserSurfaceImageFrame, parseRuntimeBrowserSurfaceClientFrame, RUNTIME_BROWSER_SURFACE_HEARTBEAT_INTERVAL_MS, RUNTIME_BROWSER_SURFACE_MAX_CONTROL_FRAME_BYTES, RUNTIME_BROWSER_SURFACE_MAX_ENCODED_FRAME_BYTES, RUNTIME_BROWSER_SURFACE_PEER_LIVENESS_TIMEOUT_MS, } from "@rynx-ai/protocol/runtime-browser-surface";
+import { WebSocket, WebSocketServer } from "ws";
+import { authorizeRuntimeWebRequest, RUNTIME_WEB_CAPABILITY_QUERY, } from "./runtime-web-auth.js";
+import { BrowserSurfaceControlQueue } from "./browser-surface-control-queue.js";
+const SURFACE_PATH = /^\/api\/runtimes\/([^/]+)\/sessions\/([^/]+)\/browser\/pages\/([^/]+)\/surface$/;
+const SELECTOR_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._~-]{0,255}$/;
+const MAX_ROUTE_ID_BYTES = 512;
+const MAX_BROWSER_BUFFERED_BYTES = 8 * 1024 * 1024;
+const OPEN_TIMEOUT_MS = 10_000;
+const CLOSE_BAD_REQUEST = 4400;
+const CLOSE_UNAUTHORIZED = 4403;
+const CLOSE_RUNTIME_UNAVAILABLE = 4406;
+const CLOSE_BACKPRESSURE = 4408;
+const CLOSE_INTERNAL = 4500;
+/**
+ * Attach the browser-facing, same-origin Surface bridge. The browser receives
+ * only bounded presentation frames; Runtime credentials and native CDP remain
+ * behind RuntimeConnectionResolverHost.
+ */
+export function attachBrowserSurfaceWs(server, deps) {
+    const wss = new WebSocketServer({
+        noServer: true,
+        perMessageDeflate: false,
+        maxPayload: RUNTIME_BROWSER_SURFACE_MAX_CONTROL_FRAME_BYTES,
+    });
+    server.on("upgrade", (request, socket, head) => {
+        const parsed = parseSurfaceUpgrade(request);
+        if (!parsed)
+            return;
+        if ("failure" in parsed) {
+            rejectUpgrade(socket, 400, parsed.failure);
+            return;
+        }
+        const authorization = authorizeRuntimeWebRequest(request, {
+            mutation: true,
+            capability: parsed.url.searchParams.get(RUNTIME_WEB_CAPABILITY_QUERY) ?? "",
+            access: deps.runtimeWebAccess,
+        });
+        if (authorization) {
+            rejectUpgrade(socket, authorization.status, authorization.error);
+            return;
+        }
+        try {
+            wss.handleUpgrade(request, socket, head, (ws) => {
+                void handleConnection(ws, parsed.url, parsed.route, deps);
+            });
+        }
+        catch {
+            rejectUpgrade(socket, 400, "invalid Browser Surface WebSocket upgrade");
+        }
+    });
+    return wss;
+}
+async function handleConnection(ws, url, route, deps) {
+    let open;
+    try {
+        open = parseOpenOptions(url, route);
+    }
+    catch (error) {
+        closeBrowser(ws, CLOSE_BAD_REQUEST, "invalid Browser Surface options", errorMessage(error));
+        return;
+    }
+    if (!deps.runtimeConnectionResolver) {
+        closeBrowser(ws, CLOSE_RUNTIME_UNAVAILABLE, "Browser Surface is unavailable");
+        return;
+    }
+    const controller = new AbortController();
+    let lease;
+    let surface;
+    let controlQueue;
+    let keepalive;
+    let lastPeerActivityAt = Date.now();
+    let cleaned = false;
+    const cleanup = async () => {
+        if (cleaned)
+            return;
+        cleaned = true;
+        if (keepalive)
+            clearInterval(keepalive);
+        controlQueue?.abort();
+        controller.abort(new Error("Browser Surface client disconnected"));
+        try {
+            await surface?.close();
+        }
+        finally {
+            lease?.release();
+        }
+    };
+    const keepAliveMs = deps.keepAliveMs ?? RUNTIME_BROWSER_SURFACE_HEARTBEAT_INTERVAL_MS;
+    const peerLivenessTimeoutMs = deps.peerLivenessTimeoutMs ??
+        RUNTIME_BROWSER_SURFACE_PEER_LIVENESS_TIMEOUT_MS;
+    keepalive = setInterval(() => {
+        if (ws.readyState !== WebSocket.OPEN)
+            return;
+        if (Date.now() - lastPeerActivityAt >= peerLivenessTimeoutMs) {
+            ws.terminate();
+            void cleanup();
+            return;
+        }
+        ws.ping();
+    }, keepAliveMs);
+    keepalive.unref?.();
+    ws.on("pong", () => {
+        lastPeerActivityAt = Date.now();
+    });
+    ws.on("message", (data, isBinary) => {
+        lastPeerActivityAt = Date.now();
+        if (!surface) {
+            closeBrowser(ws, CLOSE_BAD_REQUEST, "Browser Surface is not ready");
+            void cleanup();
+            return;
+        }
+        let frame;
+        try {
+            frame = parseControlFrame(data, isBinary, open);
+        }
+        catch (error) {
+            closeBrowser(ws, CLOSE_BAD_REQUEST, "invalid Browser Surface control", errorMessage(error));
+            void cleanup();
+            return;
+        }
+        if (!controlQueue) {
+            closeBrowser(ws, CLOSE_BAD_REQUEST, "Browser Surface is not ready");
+            void cleanup();
+            return;
+        }
+        try {
+            controlQueue.enqueue(frame);
+        }
+        catch (error) {
+            closeForError(ws, error);
+            void cleanup();
+        }
+    });
+    ws.on("close", () => void cleanup());
+    ws.on("error", () => void cleanup());
+    try {
+        lease = await deps.runtimeConnectionResolver.acquire(route.selector, {
+            signal: controller.signal,
+        });
+        if (cleaned)
+            return;
+        if (lease.target.selector !== route.selector) {
+            throw new Error("Runtime resolver returned a mismatched target");
+        }
+        surface = await lease.openBrowserSurface(open, {
+            signal: controller.signal,
+            timeoutMs: OPEN_TIMEOUT_MS,
+        });
+        if (cleaned)
+            return;
+        controlQueue = new BrowserSurfaceControlQueue({
+            dispatch: (frame) => surface.send(frame),
+            onError: (error) => {
+                if (cleaned)
+                    return;
+                closeForError(ws, error);
+                void cleanup();
+            },
+        });
+        await sendText(ws, surface.ready);
+        for await (const event of surface) {
+            if (cleaned)
+                return;
+            if ("encodedBytes" in event)
+                await sendImage(ws, event);
+            else
+                await sendText(ws, event);
+        }
+        if (!cleaned)
+            closeBrowser(ws, 1000, "Browser Surface ended");
+    }
+    catch (error) {
+        if (!cleaned)
+            closeForError(ws, error);
+    }
+    finally {
+        if (keepalive)
+            clearInterval(keepalive);
+        await cleanup().catch(() => undefined);
+    }
+}
+function parseSurfaceUpgrade(request) {
+    let url;
+    try {
+        url = new URL(request.url ?? "", "http://localhost");
+    }
+    catch {
+        return undefined;
+    }
+    const match = SURFACE_PATH.exec(url.pathname);
+    if (!match)
+        return undefined;
+    try {
+        const selector = decodeURIComponent(match[1]);
+        const sessionId = decodeURIComponent(match[2]);
+        const pageId = decodeURIComponent(match[3]);
+        if (!SELECTOR_PATTERN.test(selector) ||
+            !validRouteId(sessionId) ||
+            !validRouteId(pageId)) {
+            return { failure: "invalid Browser Surface route" };
+        }
+        return { url, route: { selector, sessionId, pageId } };
+    }
+    catch {
+        return { failure: "invalid Browser Surface route encoding" };
+    }
+}
+function parseOpenOptions(url, route) {
+    return parseRuntimeBrowserSurfaceClientFrame({
+        type: "browser.surface.open",
+        subscriptionId: randomUUID(),
+        sessionId: route.sessionId,
+        pageId: route.pageId,
+        browserGeneration: requiredInteger(url, "generation"),
+        requestedRole: url.searchParams.get("role") ?? "control",
+        format: url.searchParams.get("format") ?? "jpeg",
+        quality: optionalInteger(url, "quality", 75),
+        maximumFrameRate: optionalInteger(url, "maximumFrameRate", 15),
+    });
+}
+function parseControlFrame(data, isBinary, open) {
+    if (isBinary)
+        throw new Error("Browser Surface client frames must be text");
+    const bytes = rawDataBytes(data);
+    if (bytes.byteLength === 0 || bytes.byteLength > RUNTIME_BROWSER_SURFACE_MAX_CONTROL_FRAME_BYTES) {
+        throw new Error("Browser Surface control frame size is invalid");
+    }
+    const parsed = parseRuntimeBrowserSurfaceClientFrame(JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes)));
+    if (parsed.type === "browser.surface.open") {
+        throw new Error("Browser Surface is already open");
+    }
+    if (parsed.subscriptionId !== open.subscriptionId) {
+        throw new Error("Browser Surface control targets another subscription");
+    }
+    if ("browserGeneration" in parsed &&
+        parsed.browserGeneration !== open.browserGeneration) {
+        throw new Error("Browser Surface control targets another Browser generation");
+    }
+    return parsed;
+}
+async function sendText(ws, value) {
+    await send(ws, Buffer.from(JSON.stringify(value), "utf8"), false);
+}
+async function sendImage(ws, image) {
+    const encoded = encodeRuntimeBrowserSurfaceImageFrame(image);
+    if (encoded.byteLength > RUNTIME_BROWSER_SURFACE_MAX_ENCODED_FRAME_BYTES + 1024) {
+        throw backpressureError("Browser Surface image exceeded its wire bound");
+    }
+    await send(ws, encoded, true);
+}
+async function send(ws, data, binary) {
+    if (ws.readyState !== WebSocket.OPEN)
+        throw transportError("Browser Surface is closed");
+    if (ws.bufferedAmount + data.byteLength > MAX_BROWSER_BUFFERED_BYTES) {
+        throw backpressureError("Browser Surface output exceeded its bounded buffer");
+    }
+    await new Promise((resolve, reject) => {
+        ws.send(data, { binary, compress: false }, (error) => {
+            if (error)
+                reject(transportError(error.message));
+            else
+                resolve();
+        });
+    });
+}
+function closeForError(ws, error) {
+    const code = errorCode(error);
+    if (code === "unauthorized" || code === "authentication_failed") {
+        closeBrowser(ws, CLOSE_UNAUTHORIZED, "Browser Surface authorization failed");
+    }
+    else if (code === "capacity" || errorName(error) === "BackpressureError") {
+        closeBrowser(ws, CLOSE_BACKPRESSURE, "Browser Surface backpressure");
+    }
+    else if (code === "not_found" ||
+        code === "incompatible" ||
+        code === "unsupported" ||
+        code === "method_not_found") {
+        closeBrowser(ws, CLOSE_RUNTIME_UNAVAILABLE, "Browser Surface Runtime unavailable");
+    }
+    else if (code === "unreachable" ||
+        code === "closed" ||
+        code === "deadline_exceeded" ||
+        errorName(error) === "AbortError" ||
+        errorName(error) === "TransportError") {
+        closeBrowser(ws, 1012, "Browser Surface transport unavailable");
+    }
+    else {
+        closeBrowser(ws, CLOSE_INTERNAL, "Browser Surface bridge error", errorMessage(error));
+    }
+}
+function closeBrowser(ws, code, reason, message) {
+    if (message && ws.readyState === WebSocket.OPEN) {
+        ws.send(JSON.stringify({ type: "error", message }), { binary: false, compress: false });
+    }
+    if (ws.readyState === WebSocket.OPEN)
+        ws.close(code, boundedCloseReason(reason));
+}
+function rejectUpgrade(socket, status, message) {
+    if (socket.destroyed)
+        return;
+    const body = `${message}\n`;
+    socket.end(`HTTP/1.1 ${status} ${status === 401 ? "Unauthorized" : "Bad Request"}\r\n` +
+        "Connection: close\r\n" +
+        "Content-Type: text/plain; charset=utf-8\r\n" +
+        `Content-Length: ${Buffer.byteLength(body)}\r\n\r\n${body}`);
+}
+function rawDataBytes(data) {
+    if (data instanceof ArrayBuffer)
+        return new Uint8Array(data);
+    if (Array.isArray(data))
+        return Uint8Array.from(Buffer.concat(data));
+    return new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+}
+function requiredInteger(url, field) {
+    const value = url.searchParams.get(field);
+    if (value === null || !/^\d+$/.test(value))
+        throw new Error(`${field} is required`);
+    return Number(value);
+}
+function optionalInteger(url, field, fallback) {
+    const value = url.searchParams.get(field);
+    if (value === null)
+        return fallback;
+    if (!/^\d+$/.test(value))
+        throw new Error(`${field} must be an integer`);
+    return Number(value);
+}
+function validRouteId(value) {
+    return value.length > 0 &&
+        Buffer.byteLength(value, "utf8") <= MAX_ROUTE_ID_BYTES &&
+        !/[\u0000-\u001f\u007f]/.test(value);
+}
+function boundedCloseReason(reason) {
+    return Buffer.byteLength(reason, "utf8") <= 123 ? reason : "Browser Surface closed";
+}
+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 errorMessage(error) {
+    return error instanceof Error ? error.message : "Browser Surface bridge failed";
+}
+function transportError(message) {
+    const error = new Error(message);
+    error.name = "TransportError";
+    return error;
+}
+function backpressureError(message) {
+    const error = new Error(message);
+    error.name = "BackpressureError";
+    return error;
+}