@jhebe/web-terminal 0.2.0

package/dist-server/server/session-manager.js

@@ -0,0 +1,274 @@
+import { randomUUID } from 'node:crypto';
+import { platform } from 'node:os';
+import * as pty from 'node-pty';
+import { HistoryBuffer } from './history-buffer.js';
+export function createTerminalSessionManager(options = {}) {
+    return new InMemoryTerminalSessionManager(options);
+}
+class InMemoryTerminalSessionManager {
+    options;
+    records = new Map();
+    listeners = new Set();
+    historyLimitBytes;
+    idleTimeoutMs;
+    maxSessions;
+    maxObserversPerSession;
+    maxWriteBytes;
+    maxInputBytes;
+    constructor(options) {
+        this.options = options;
+        this.historyLimitBytes = options.historyLimitBytes ?? 256 * 1024;
+        this.idleTimeoutMs = options.idleTimeoutMs ?? 5 * 60 * 1000;
+        this.maxSessions = options.maxSessions ?? 100;
+        this.maxObserversPerSession = options.maxObserversPerSession ?? 32;
+        this.maxWriteBytes = options.maxWriteBytes ?? 64 * 1024;
+        this.maxInputBytes = options.maxInputBytes ?? 64 * 1024;
+    }
+    get sessions() {
+        return [...this.records.values()]
+            .map((session) => this.summarize(session))
+            .sort((left, right) => left.createdAt.localeCompare(right.createdAt));
+    }
+    open(options = {}) {
+        if (this.records.size >= this.maxSessions) {
+            throw new Error(`Session limit reached (${this.maxSessions}). Close or expire sessions before opening more.`);
+        }
+        const id = randomUUID();
+        const createdAt = new Date();
+        const terminal = pty.spawn(options.shell ?? this.options.shell ?? defaultShell(), options.shellArgs ?? this.options.shellArgs ?? [], {
+            name: 'xterm-256color',
+            cols: 80,
+            rows: 24,
+            cwd: options.cwd ?? this.options.cwd ?? process.cwd(),
+            env: {
+                ...process.env,
+                ...this.options.env,
+                ...options.env,
+                TERM: 'xterm-256color',
+            },
+        });
+        const history = new HistoryBuffer(this.historyLimitBytes);
+        const outputSubscription = terminal.onData((data) => {
+            const current = this.records.get(id);
+            if (!current) {
+                return;
+            }
+            current.lastActiveAt = new Date();
+            current.history.append(data);
+            current.attachment?.sink.output(data);
+            for (const observer of current.observers.values()) {
+                observer.output(data);
+            }
+            if (!current.attachment) {
+                this.scheduleExpiration(current);
+            }
+        });
+        const exitSubscription = terminal.onExit(({ exitCode, signal }) => {
+            const current = this.records.get(id);
+            if (!current) {
+                return;
+            }
+            current.state = 'exited';
+            current.exitCode = exitCode;
+            current.lastActiveAt = new Date();
+            current.attachment?.sink.exit(exitCode, signal);
+            for (const observer of current.observers.values()) {
+                observer.exit(exitCode, signal);
+            }
+            if (!current.attachment) {
+                this.scheduleExpiration(current);
+            }
+            this.emit('exited', current);
+        });
+        const record = {
+            id,
+            name: options.name?.trim() || `Terminal ${this.records.size + 1}`,
+            createdAt,
+            lastActiveAt: createdAt,
+            state: 'running',
+            terminal,
+            history,
+            outputSubscription,
+            exitSubscription,
+            attachment: undefined,
+            observers: new Map(),
+            idleTimer: undefined,
+        };
+        this.records.set(id, record);
+        this.scheduleExpiration(record);
+        this.emit('opened', record);
+        return this.summarize(record);
+    }
+    close(sessionId) {
+        const session = this.requireSession(sessionId);
+        const summary = this.summarize(session);
+        this.remove(session);
+        this.emitSummary('closed', summary);
+    }
+    write(sessionId, data) {
+        const session = this.requireSession(sessionId);
+        if (session.state !== 'running') {
+            throw new Error('This session process has exited.');
+        }
+        assertPayloadWithinLimit(data, this.maxWriteBytes, 'write');
+        session.lastActiveAt = new Date();
+        session.terminal.write(data);
+        if (!session.attachment && session.observers.size === 0) {
+            this.scheduleExpiration(session);
+        }
+    }
+    observe(sessionId, observerId, sink) {
+        const session = this.requireSession(sessionId);
+        if (!session.observers.has(observerId) &&
+            session.observers.size >= this.maxObserversPerSession) {
+            throw new Error(`Observer limit reached (${this.maxObserversPerSession}) for this session.`);
+        }
+        this.clearExpiration(session);
+        session.observers.set(observerId, sink);
+        session.lastActiveAt = new Date();
+        this.emit('attached', session);
+        return {
+            session: this.summarize(session),
+            history: session.history.read(),
+        };
+    }
+    unobserve(sessionId, observerId) {
+        const session = this.records.get(sessionId);
+        if (!session || !session.observers.delete(observerId)) {
+            return;
+        }
+        session.lastActiveAt = new Date();
+        this.scheduleExpiration(session);
+        this.emit('detached', session);
+    }
+    attach(sessionId, attachmentId, sink) {
+        const session = this.requireSession(sessionId);
+        if (session.attachment && session.attachment.id !== attachmentId) {
+            throw new Error('This session already has a writable view.');
+        }
+        this.clearExpiration(session);
+        session.attachment = { id: attachmentId, sink };
+        session.lastActiveAt = new Date();
+        this.emit('attached', session);
+        return {
+            session: this.summarize(session),
+            history: session.history.read(),
+        };
+    }
+    detach(sessionId, attachmentId) {
+        const session = this.records.get(sessionId);
+        if (!session || session.attachment?.id !== attachmentId) {
+            return;
+        }
+        session.attachment = undefined;
+        session.lastActiveAt = new Date();
+        this.scheduleExpiration(session);
+        this.emit('detached', session);
+    }
+    input(sessionId, attachmentId, data) {
+        const session = this.requireAttached(sessionId, attachmentId);
+        if (session.state !== 'running') {
+            throw new Error('This session process has exited.');
+        }
+        assertPayloadWithinLimit(data, this.maxInputBytes, 'input');
+        session.lastActiveAt = new Date();
+        session.terminal.write(data);
+    }
+    resize(sessionId, attachmentId, cols, rows) {
+        const session = this.requireAttached(sessionId, attachmentId);
+        if (session.state === 'running') {
+            session.terminal.resize(cols, rows);
+        }
+    }
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    shutdown() {
+        for (const session of [...this.records.values()]) {
+            this.remove(session);
+        }
+        this.listeners.clear();
+    }
+    requireSession(sessionId) {
+        const session = this.records.get(sessionId);
+        if (!session) {
+            throw new Error(`Unknown terminal session: ${sessionId}`);
+        }
+        return session;
+    }
+    requireAttached(sessionId, attachmentId) {
+        const session = this.requireSession(sessionId);
+        if (session.attachment?.id !== attachmentId) {
+            throw new Error('This connection is not attached to the session.');
+        }
+        return session;
+    }
+    scheduleExpiration(session) {
+        this.clearExpiration(session);
+        if (this.idleTimeoutMs <= 0 ||
+            session.attachment ||
+            session.observers.size > 0) {
+            return;
+        }
+        session.idleTimer = setTimeout(() => {
+            if (this.records.get(session.id) !== session ||
+                session.attachment ||
+                session.observers.size > 0) {
+                return;
+            }
+            const summary = this.summarize(session);
+            this.remove(session);
+            this.emitSummary('expired', summary);
+        }, this.idleTimeoutMs);
+        session.idleTimer.unref?.();
+    }
+    clearExpiration(session) {
+        if (session.idleTimer) {
+            clearTimeout(session.idleTimer);
+            session.idleTimer = undefined;
+        }
+    }
+    remove(session) {
+        this.records.delete(session.id);
+        this.clearExpiration(session);
+        session.outputSubscription.dispose();
+        session.exitSubscription.dispose();
+        if (session.state === 'running') {
+            session.terminal.kill();
+        }
+    }
+    summarize(session) {
+        return {
+            id: session.id,
+            name: session.name,
+            state: session.state,
+            attached: Boolean(session.attachment),
+            observers: session.observers.size,
+            createdAt: session.createdAt.toISOString(),
+            lastActiveAt: session.lastActiveAt.toISOString(),
+            ...(session.exitCode === undefined ? {} : { exitCode: session.exitCode }),
+        };
+    }
+    emit(type, session) {
+        this.emitSummary(type, this.summarize(session));
+    }
+    emitSummary(type, session) {
+        const event = { type, session };
+        for (const listener of this.listeners) {
+            listener(event);
+        }
+    }
+}
+function defaultShell() {
+    if (platform() === 'win32') {
+        return process.env.COMSPEC ?? 'powershell.exe';
+    }
+    return process.env.SHELL ?? '/bin/sh';
+}
+function assertPayloadWithinLimit(value, limitBytes, operation) {
+    const bytes = Buffer.byteLength(value);
+    if (bytes > limitBytes) {
+        throw new Error(`Terminal ${operation} exceeds ${limitBytes} bytes (received ${bytes}).`);
+    }
+}

package/dist-server/server/terminal-server.d.ts

@@ -0,0 +1,16 @@
+import type { IncomingMessage, Server as HttpServer } from 'node:http';
+import type { OpenSessionOptions, TerminalSessionManager } from './session-manager.js';
+export type TerminalAction = 'open' | 'list' | 'attach' | 'detach' | 'close' | 'write' | 'observe';
+export interface TerminalServerOptions {
+    server: HttpServer;
+    manager: TerminalSessionManager;
+    path?: string;
+    maxPayloadBytes?: number;
+    authorize?: (request: IncomingMessage, action: TerminalAction, sessionId?: string) => boolean | Promise<boolean>;
+    resolveOpenOptions?: (request: IncomingMessage, requestedName?: string) => OpenSessionOptions | Promise<OpenSessionOptions>;
+    onError?: (error: Error, request: IncomingMessage) => void;
+}
+export interface TerminalServer {
+    close(): Promise<void>;
+}
+export declare function attachTerminalServer(options: TerminalServerOptions): TerminalServer;

package/dist-server/server/terminal-server.js

@@ -0,0 +1,250 @@
+import { randomUUID } from 'node:crypto';
+import { WebSocket, WebSocketServer } from 'ws';
+import { parseClientMessage, } from '../src/protocol.js';
+export function attachTerminalServer(options) {
+    const webSocketServer = new WebSocketServer({
+        server: options.server,
+        path: options.path ?? '/terminal',
+        maxPayload: options.maxPayloadBytes ?? 64 * 1024,
+    });
+    webSocketServer.on('connection', (socket, request) => {
+        const state = {
+            id: randomUUID(),
+            attachedSessionId: undefined,
+            closed: false,
+            snapshotQueue: Promise.resolve(),
+            observedSessionIds: new Set(),
+        };
+        let queue = Promise.resolve();
+        const unsubscribe = options.manager.subscribe(() => {
+            queueSessions(socket, request, state, options);
+        });
+        queueSessions(socket, request, state, options);
+        socket.on('message', (raw) => {
+            queue = queue
+                .then(() => handleMessage(raw.toString(), socket, request, state, options))
+                .catch((error) => {
+                reportError(socket, request, options, toError(error));
+            });
+        });
+        socket.on('error', (error) => {
+            options.onError?.(toError(error), request);
+            socket.terminate();
+        });
+        socket.on('close', () => {
+            state.closed = true;
+            unsubscribe();
+            if (state.attachedSessionId) {
+                options.manager.detach(state.attachedSessionId, state.id);
+                state.attachedSessionId = undefined;
+            }
+            for (const sessionId of state.observedSessionIds) {
+                options.manager.unobserve(sessionId, state.id);
+            }
+            state.observedSessionIds.clear();
+        });
+    });
+    return {
+        close: () => new Promise((resolve, reject) => {
+            for (const client of webSocketServer.clients) {
+                client.close(1001, 'Server shutting down');
+            }
+            webSocketServer.close((error) => {
+                if (error) {
+                    reject(error);
+                }
+                else {
+                    resolve();
+                }
+            });
+        }),
+    };
+}
+async function handleMessage(raw, socket, request, state, options) {
+    const message = parseClientMessage(raw);
+    if (!message) {
+        send(socket, { type: 'error', message: 'Invalid client message.' });
+        return;
+    }
+    try {
+        await executeMessage(message, socket, request, state, options);
+    }
+    catch (error) {
+        reportError(socket, request, options, toError(error), 'requestId' in message ? message.requestId : undefined);
+    }
+}
+async function executeMessage(message, socket, request, state, options) {
+    switch (message.type) {
+        case 'open': {
+            await requireAuthorization(options, request, 'open');
+            const openOptions = options.resolveOpenOptions
+                ? await options.resolveOpenOptions(request, message.name)
+                : { ...(message.name === undefined ? {} : { name: message.name }) };
+            requireOpenConnection(socket, state);
+            const session = options.manager.open(openOptions);
+            send(socket, { type: 'opened', requestId: message.requestId, session });
+            return;
+        }
+        case 'attach': {
+            await requireAuthorization(options, request, 'attach', message.sessionId);
+            requireOpenConnection(socket, state);
+            const attachment = options.manager.attach(message.sessionId, state.id, {
+                output: (data) => send(socket, {
+                    type: 'output',
+                    sessionId: message.sessionId,
+                    data,
+                }),
+                exit: (exitCode, signal) => send(socket, {
+                    type: 'exit',
+                    sessionId: message.sessionId,
+                    exitCode,
+                    ...(signal === undefined ? {} : { signal }),
+                }),
+            });
+            const previousSessionId = state.attachedSessionId;
+            state.attachedSessionId = message.sessionId;
+            if (previousSessionId && previousSessionId !== message.sessionId) {
+                options.manager.detach(previousSessionId, state.id);
+            }
+            send(socket, {
+                type: 'attached',
+                requestId: message.requestId,
+                session: attachment.session,
+                history: attachment.history,
+            });
+            return;
+        }
+        case 'detach': {
+            const sessionId = message.sessionId;
+            await requireAuthorization(options, request, 'detach', sessionId);
+            requireOpenConnection(socket, state);
+            if (state.attachedSessionId === sessionId) {
+                options.manager.detach(sessionId, state.id);
+                state.attachedSessionId = undefined;
+            }
+            send(socket, {
+                type: 'detached',
+                requestId: message.requestId,
+                sessionId,
+            });
+            return;
+        }
+        case 'close': {
+            await requireAuthorization(options, request, 'close', message.sessionId);
+            requireOpenConnection(socket, state);
+            options.manager.close(message.sessionId);
+            if (state.attachedSessionId === message.sessionId) {
+                state.attachedSessionId = undefined;
+            }
+            send(socket, {
+                type: 'closed',
+                requestId: message.requestId,
+                sessionId: message.sessionId,
+            });
+            return;
+        }
+        case 'write': {
+            await requireAuthorization(options, request, 'write', message.sessionId);
+            requireOpenConnection(socket, state);
+            options.manager.write(message.sessionId, message.data);
+            send(socket, {
+                type: 'written',
+                requestId: message.requestId,
+                sessionId: message.sessionId,
+            });
+            return;
+        }
+        case 'observe': {
+            await requireAuthorization(options, request, 'observe', message.sessionId);
+            requireOpenConnection(socket, state);
+            const observation = options.manager.observe(message.sessionId, state.id, {
+                output: (data) => send(socket, {
+                    type: 'output',
+                    sessionId: message.sessionId,
+                    data,
+                }),
+                exit: (exitCode, signal) => send(socket, {
+                    type: 'exit',
+                    sessionId: message.sessionId,
+                    exitCode,
+                    ...(signal === undefined ? {} : { signal }),
+                }),
+            });
+            state.observedSessionIds.add(message.sessionId);
+            send(socket, {
+                type: 'observing',
+                requestId: message.requestId,
+                session: observation.session,
+                history: observation.history,
+            });
+            return;
+        }
+        case 'unobserve': {
+            await requireAuthorization(options, request, 'observe', message.sessionId);
+            requireOpenConnection(socket, state);
+            options.manager.unobserve(message.sessionId, state.id);
+            state.observedSessionIds.delete(message.sessionId);
+            send(socket, {
+                type: 'unobserved',
+                requestId: message.requestId,
+                sessionId: message.sessionId,
+            });
+            return;
+        }
+        case 'input':
+            options.manager.input(message.sessionId, state.id, message.data);
+            return;
+        case 'resize':
+            options.manager.resize(message.sessionId, state.id, message.cols, message.rows);
+    }
+}
+async function sendSessions(socket, request, options) {
+    const visible = [];
+    for (const session of options.manager.sessions) {
+        if (!options.authorize ||
+            (await options.authorize(request, 'list', session.id))) {
+            visible.push(session);
+        }
+    }
+    send(socket, { type: 'sessions', sessions: visible });
+}
+function queueSessions(socket, request, state, options) {
+    state.snapshotQueue = state.snapshotQueue
+        .then(async () => {
+        if (!state.closed) {
+            await sendSessions(socket, request, options);
+        }
+    })
+        .catch((error) => {
+        if (!state.closed) {
+            reportError(socket, request, options, toError(error));
+        }
+    });
+}
+async function requireAuthorization(options, request, action, sessionId) {
+    if (options.authorize &&
+        !(await options.authorize(request, action, sessionId))) {
+        throw new Error(`Not authorized to ${action} this terminal session.`);
+    }
+}
+function reportError(socket, request, options, error, requestId) {
+    options.onError?.(error, request);
+    send(socket, {
+        type: 'error',
+        message: error.message,
+        ...(requestId === undefined ? {} : { requestId }),
+    });
+}
+function send(socket, message) {
+    if (socket.readyState === WebSocket.OPEN) {
+        socket.send(JSON.stringify(message));
+    }
+}
+function requireOpenConnection(socket, state) {
+    if (state.closed || socket.readyState !== WebSocket.OPEN) {
+        throw new Error('Terminal connection closed before the operation completed.');
+    }
+}
+function toError(error) {
+    return error instanceof Error ? error : new Error(String(error));
+}

package/dist-server/src/protocol.d.ts

@@ -0,0 +1,98 @@
+export interface SessionSummary {
+    readonly id: string;
+    readonly name: string;
+    readonly state: 'running' | 'exited';
+    readonly attached: boolean;
+    readonly observers: number;
+    readonly createdAt: string;
+    readonly lastActiveAt: string;
+    readonly exitCode?: number;
+}
+export type ClientMessage = {
+    type: 'open';
+    requestId: string;
+    name?: string;
+} | {
+    type: 'close';
+    requestId: string;
+    sessionId: string;
+} | {
+    type: 'attach';
+    requestId: string;
+    sessionId: string;
+} | {
+    type: 'detach';
+    requestId: string;
+    sessionId: string;
+} | {
+    type: 'write';
+    requestId: string;
+    sessionId: string;
+    data: string;
+} | {
+    type: 'observe';
+    requestId: string;
+    sessionId: string;
+} | {
+    type: 'unobserve';
+    requestId: string;
+    sessionId: string;
+} | {
+    type: 'input';
+    sessionId: string;
+    data: string;
+} | {
+    type: 'resize';
+    sessionId: string;
+    cols: number;
+    rows: number;
+};
+export type ServerMessage = {
+    type: 'sessions';
+    sessions: SessionSummary[];
+} | {
+    type: 'opened';
+    requestId: string;
+    session: SessionSummary;
+} | {
+    type: 'closed';
+    requestId: string;
+    sessionId: string;
+} | {
+    type: 'attached';
+    requestId: string;
+    session: SessionSummary;
+    history: string;
+} | {
+    type: 'detached';
+    requestId: string;
+    sessionId: string;
+} | {
+    type: 'written';
+    requestId: string;
+    sessionId: string;
+} | {
+    type: 'observing';
+    requestId: string;
+    session: SessionSummary;
+    history: string;
+} | {
+    type: 'unobserved';
+    requestId: string;
+    sessionId: string;
+} | {
+    type: 'output';
+    sessionId: string;
+    data: string;
+} | {
+    type: 'exit';
+    sessionId: string;
+    exitCode: number;
+    signal?: number;
+} | {
+    type: 'error';
+    message: string;
+    requestId?: string;
+};
+export declare function parseClientMessage(value: unknown): ClientMessage | undefined;
+export declare function parseServerMessage(value: unknown): ServerMessage | undefined;