@tequila99/githuman 0.4.2 → 0.5.0

package/dist/server/services/terminal/escape-tail.js

@@ -0,0 +1,93 @@
+// Drop an unfinished control string that is too long to keep for a snapshot.
+const MAX_ESCAPE_TAIL = 8192;
+export class EscapeTail {
+    // text: no sequence is open. escape: after ESC. csi: control sequence, ends with a final byte.
+    // string: OSC, DCS, PM or APC data, ends with BEL or ST. string-escape: after ESC inside a string.
+    state = 'text';
+    value = '';
+    get tail() {
+        return this.value;
+    }
+    push(data) {
+        for (const char of data) {
+            // 8-bit CSI (U+009B) starts a control sequence in any state.
+            if (char === '\u009b') {
+                this.state = 'csi';
+                this.value = char;
+                continue;
+            }
+            // 8-bit OSC, DCS, SOS, PM and APC start a control string in any state.
+            if (['\u009d', '\u0090', '\u0098', '\u009e', '\u009f'].includes(char)) {
+                this.state = 'string';
+                this.value = char;
+                continue;
+            }
+            if (this.state === 'text') {
+                // ESC opens a new sequence. Other text is not part of the tail.
+                if (char === '\x1b') {
+                    this.state = 'escape';
+                    this.value = char;
+                }
+                continue;
+            }
+            this.value += char;
+            // A long OSC, DCS or APC string must not close the shell.
+            if (this.value.length > MAX_ESCAPE_TAIL) {
+                this.reset();
+                continue;
+            }
+            // CAN and SUB cancel the open sequence.
+            if (char === '\x18' || char === '\x1a') {
+                this.reset();
+                continue;
+            }
+            if (this.state === 'escape') {
+                if (char === '[') {
+                    // ESC [ starts a control sequence.
+                    this.state = 'csi';
+                }
+                else if (']PX^_'.includes(char)) {
+                    // ESC ] P X ^ _ start OSC, DCS, SOS, PM and APC strings.
+                    this.state = 'string';
+                }
+                else if (char >= '0' && char <= '~') {
+                    // A final byte ends a short escape sequence, for example ESC 7.
+                    this.reset();
+                }
+            }
+            else if (this.state === 'csi') {
+                if (char >= '@' && char <= '~') {
+                    // A final byte ends the control sequence.
+                    this.reset();
+                }
+                else if (char === '\x1b') {
+                    // ESC aborts the control sequence and opens a new one.
+                    this.state = 'escape';
+                    this.value = char;
+                }
+            }
+            else if (this.state === 'string') {
+                if (char === '\x07' || char === '\u009c') {
+                    // BEL or 8-bit ST ends the string.
+                    this.reset();
+                }
+                else if (char === '\x1b') {
+                    // ESC can start the two-character ST (ESC \).
+                    this.state = 'string-escape';
+                }
+            }
+            else if (char === '\\') {
+                // ESC \ is ST: it ends the string.
+                this.reset();
+            }
+            else {
+                // ESC with any other character is part of the string data.
+                this.state = 'string';
+            }
+        }
+    }
+    reset() {
+        this.state = 'text';
+        this.value = '';
+    }
+}

package/dist/server/services/terminal/processes.js

@@ -0,0 +1,115 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+// Give processes time to react to SIGHUP before SIGKILL.
+const TERMINATE_GRACE_MS = 200;
+// A slow `ps` must not block the caller. The caller treats a timeout as unknown.
+const PS_TIMEOUT_MS = 2000;
+// Bound the memory for the `ps` output on a host with many processes.
+const PS_MAX_BUFFER_BYTES = 4 * 1024 * 1024;
+// PID 1 is init. PID 0 and -1 make kill() reach many processes. Never signal them.
+const INIT_PID = 1;
+// Share the Node callback adapter without starting a shell.
+const execute = promisify(execFile);
+export async function processes() {
+    const { stdout } = await execute('ps', ['-axo', 'pid=,ppid=,pgid='], {
+        timeout: PS_TIMEOUT_MS,
+        maxBuffer: PS_MAX_BUFFER_BYTES
+    });
+    return stdout
+        .trim()
+        .split('\n')
+        .map(line => {
+        const [pid, parent, group] = line.trim().split(/\s+/).map(Number);
+        return { pid, parent, group };
+    })
+        .filter(row => Number.isInteger(row.pid) &&
+        Number.isInteger(row.parent) &&
+        Number.isInteger(row.group) &&
+        row.pid > 0);
+}
+// Returns the process and its descendants, each parent before its children.
+// One pass over a parent-to-children map keeps the cost linear.
+export function descendants(rows, pid) {
+    const byPid = new Map();
+    const children = new Map();
+    for (const row of rows) {
+        byPid.set(row.pid, row);
+        const siblings = children.get(row.parent);
+        if (siblings) {
+            siblings.push(row.pid);
+        }
+        else {
+            children.set(row.parent, [row.pid]);
+        }
+    }
+    // The queue grows while the loop reads it: this is a breadth-first walk.
+    const order = [pid];
+    const seen = new Set(order);
+    for (const id of order) {
+        for (const child of children.get(id) ?? []) {
+            if (seen.has(child))
+                continue;
+            seen.add(child);
+            order.push(child);
+        }
+    }
+    return order.flatMap(id => byPid.get(id) ?? []);
+}
+export function classifyProcessActivity(rows, pid) {
+    if (!rows.some(row => row.pid === pid))
+        return 'unknown';
+    return descendants(rows, pid).some(row => row.pid !== pid)
+        ? 'running'
+        : 'idle';
+}
+export async function processActivity(pid) {
+    try {
+        return classifyProcessActivity(await processes(), pid);
+    }
+    catch {
+        return 'unknown';
+    }
+}
+export function signalProcess(pid, signal) {
+    // PID 0 and -1 would reach the server's own group or every process of the user.
+    if (!Number.isInteger(pid) || Math.abs(pid) <= INIT_PID)
+        return;
+    try {
+        process.kill(pid, signal);
+    }
+    catch {
+        /* The process may have exited before the signal. */
+    }
+}
+export async function terminateProcesses(pid) {
+    if (!Number.isInteger(pid) || pid <= INIT_PID)
+        return;
+    // One snapshot keeps the targets and the group owners consistent.
+    let all = [];
+    try {
+        all = await processes();
+    }
+    catch {
+        /* The backend still terminates its shell. */
+    }
+    const targets = descendants(all, pid);
+    const ids = new Set(targets.map(row => row.pid));
+    // Only signal groups that are wholly owned by this shell tree.
+    const groups = [
+        ...new Set(targets.map(row => row.group).filter(group => group > INIT_PID))
+    ].filter(group => all.filter(row => row.group === group).every(row => ids.has(row.pid)));
+    // oxlint-disable-next-line unicorn/no-array-reverse -- the type-aware checker lacks toReversed in this module
+    const childrenFirst = targets.slice().reverse();
+    const signalAll = (signal) => {
+        // A group also reaches a child that started after the snapshot.
+        for (const group of groups)
+            signalProcess(-group, signal);
+        for (const row of childrenFirst)
+            signalProcess(row.pid, signal);
+        signalProcess(pid, signal);
+    };
+    signalAll('SIGHUP');
+    await new Promise(resolve => setTimeout(resolve, TERMINATE_GRACE_MS));
+    // A PID can be reused in the grace time. The risk is accepted: PIDs wrap slowly.
+    signalAll('SIGKILL');
+}

package/dist/server/services/terminal/prompt-tracker.js

@@ -0,0 +1,15 @@
+// OSC 133 marks a prompt without adding visible characters.
+export const TERMINAL_PROMPT_MARKER = '\x1b]133;A\x07';
+export class PromptTracker {
+    idle = false;
+    tail = '';
+    input() {
+        this.idle = false;
+    }
+    output(data) {
+        const combined = this.tail + data;
+        if (combined.includes(TERMINAL_PROMPT_MARKER))
+            this.idle = true;
+        this.tail = combined.slice(-(TERMINAL_PROMPT_MARKER.length - 1));
+    }
+}

package/dist/server/services/terminal/registry.js

@@ -0,0 +1,167 @@
+import { randomUUID } from 'node:crypto';
+import { MAX_TERMINAL_SESSIONS, TERMINAL_IDLE_MS, TERMINAL_ORPHAN_MS } from "../../../shared/terminal/constants.js";
+import { TerminalLimitError, TerminalNotFoundError } from "../../errors/terminal.js";
+import { createBackend } from "./backend.js";
+import { processes } from "./processes.js";
+import { TerminalSession } from "./session.js";
+// Check the activity of every session this often.
+const POLL_MS = 5000;
+export class TerminalRegistry {
+    entries = new Map();
+    listeners = new Set();
+    closing = new Set();
+    poll;
+    creating = 0;
+    nextNumber = 1;
+    stopped = false;
+    checking = false;
+    options;
+    constructor(options) {
+        this.options = options;
+        this.poll = setInterval(() => {
+            void this.checkActivity();
+        }, options.pollMs ?? POLL_MS);
+        this.poll.unref();
+    }
+    get list() {
+        return [...this.entries.values()].map(entry => entry.session.info);
+    }
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    publish(message) {
+        for (const listener of this.listeners)
+            listener(message);
+    }
+    publishList() {
+        this.publish({ type: 'list', sessions: this.list });
+    }
+    now() {
+        return (this.options.now ?? Date.now)();
+    }
+    get(id) {
+        const entry = this.entries.get(id);
+        if (!entry)
+            throw new TerminalNotFoundError('Terminal session no longer exists.');
+        return entry.session;
+    }
+    async create(cols, rows) {
+        if (this.stopped)
+            throw new TerminalNotFoundError('Terminal server is stopping.');
+        if (this.entries.size + this.creating >= MAX_TERMINAL_SESSIONS)
+            throw new TerminalLimitError('The terminal limit has been reached.');
+        this.creating++;
+        try {
+            const backend = await (this.options.backend ?? createBackend)(this.options.repositoryPath, cols, rows);
+            if (this.stopped) {
+                await backend.kill();
+                throw new TerminalNotFoundError('Terminal server is stopping.');
+            }
+            const id = randomUUID();
+            const session = new TerminalSession(id, `Terminal ${this.nextNumber++}`, backend, cols, rows, message => this.publish(message), () => {
+                void this.close(id);
+            });
+            this.entries.set(id, {
+                session,
+                subscribers: new Set(),
+                orphanedSince: this.now(),
+                idleSince: null
+            });
+            this.options.onLifecycle?.({ type: 'created', id, mode: backend.mode });
+            this.publishList();
+            return session;
+        }
+        finally {
+            this.creating--;
+        }
+    }
+    attach(id, subscriber) {
+        const entry = this.entries.get(id);
+        if (!entry)
+            throw new TerminalNotFoundError('Terminal session no longer exists.');
+        entry.subscribers.add(subscriber);
+        entry.orphanedSince = null;
+        entry.idleSince = null;
+    }
+    detach(subscriber) {
+        for (const entry of this.entries.values()) {
+            if (!entry.subscribers.delete(subscriber) || entry.subscribers.size)
+                continue;
+            entry.orphanedSince = this.now();
+            entry.idleSince = entry.session.running === 'idle' ? this.now() : null;
+        }
+    }
+    async checkActivity() {
+        if (this.checking || this.stopped)
+            return;
+        this.checking = true;
+        try {
+            // One process list serves every session. A failed read leaves them unknown.
+            let rows;
+            if (this.entries.size > 0) {
+                try {
+                    rows = await (this.options.listProcesses ?? processes)();
+                }
+                catch {
+                    rows = undefined;
+                }
+            }
+            for (const [id, entry] of this.entries) {
+                const previous = entry.session.running;
+                entry.session.running =
+                    rows === undefined
+                        ? 'unknown'
+                        : await entry.session.backend.activity(rows);
+                if (previous !== entry.session.running)
+                    this.publishList();
+                if (entry.orphanedSince === null)
+                    continue;
+                const now = this.now();
+                if (entry.session.running === 'idle') {
+                    entry.idleSince ??= now;
+                }
+                else {
+                    entry.idleSince = null;
+                }
+                if (now - entry.orphanedSince >= TERMINAL_ORPHAN_MS ||
+                    (entry.idleSince !== null &&
+                        now - entry.idleSince >= TERMINAL_IDLE_MS)) {
+                    this.options.onLifecycle?.({ type: 'timeout', id });
+                    await this.close(id);
+                }
+            }
+        }
+        finally {
+            this.checking = false;
+        }
+    }
+    async resize(id, cols, rows) {
+        await this.get(id).resize(cols, rows);
+        this.publishList();
+    }
+    async close(id) {
+        const entry = this.entries.get(id);
+        if (!entry)
+            return;
+        this.entries.delete(id);
+        this.options.onLifecycle?.({ type: 'closed', id });
+        this.publish({ type: 'exit', terminalId: id });
+        this.publishList();
+        const closing = entry.session.dispose();
+        this.closing.add(closing);
+        try {
+            await closing;
+        }
+        finally {
+            this.closing.delete(closing);
+        }
+    }
+    async dispose() {
+        this.stopped = true;
+        clearInterval(this.poll);
+        await Promise.all([...this.entries.keys()].map(id => this.close(id)));
+        await Promise.all(this.closing);
+        this.listeners.clear();
+    }
+}

package/dist/server/services/terminal/session.js

@@ -0,0 +1,238 @@
+import headless from '@xterm/headless';
+import { SerializeAddon } from '@xterm/addon-serialize';
+import { TERMINAL_SCROLLBACK, TERMINAL_QUEUE_BYTES, TERMINAL_SNAPSHOT_BYTES, TERMINAL_FRAME_BYTES, TERMINAL_TITLE_LENGTH } from "../../../shared/terminal/constants.js";
+import { EscapeTail } from "./escape-tail.js";
+import { TerminalError } from "../../errors/terminal.js";
+// Join output that arrives within one display frame (about 60 Hz) into one write.
+const FLUSH_DELAY_MS = 16;
+// One UTF-16 unit takes up to 3 UTF-8 bytes. A divisor of 4 keeps a part below the frame limit.
+const FRAME_PART_UNITS = TERMINAL_FRAME_BYTES / 4;
+// Close the session when the parser queue grows to twice the pause limit.
+const QUEUE_CLOSE_BYTES = TERMINAL_QUEUE_BYTES * 2;
+// Resume the backend only after the parser queue falls well below the pause limit.
+const QUEUE_RESUME_BYTES = TERMINAL_QUEUE_BYTES / 4;
+// A high surrogate starts a pair. A part must not end after it.
+const HIGH_SURROGATE_FIRST = 0xd800;
+const HIGH_SURROGATE_LAST = 0xdbff;
+export class TerminalSession {
+    terminal;
+    serializer;
+    tail = new EscapeTail();
+    queue = Promise.resolve();
+    pendingBytes = 0;
+    staged = '';
+    flushTimer;
+    blocked = new Set();
+    sequence = 0;
+    stopped = false;
+    disposers = [];
+    title;
+    cols;
+    rows;
+    running = 'unknown';
+    id;
+    backend;
+    publish;
+    onExit;
+    constructor(id, title, backend, cols, rows, publish, onExit) {
+        this.id = id;
+        this.backend = backend;
+        this.publish = publish;
+        this.onExit = onExit;
+        this.title = title;
+        this.cols = cols;
+        this.rows = rows;
+        this.terminal = new headless.Terminal({
+            cols,
+            rows,
+            scrollback: TERMINAL_SCROLLBACK,
+            allowProposedApi: true
+        });
+        this.serializer = new SerializeAddon();
+        this.terminal.loadAddon(this.serializer);
+        this.disposers.push(backend.onData(data => this.output(data)), backend.onExit(onExit));
+        // Only the server answers terminal queries, even with multiple browsers.
+        this.disposers.push(() => this.terminal.dispose());
+        this.terminal.onData(data => {
+            if (!this.stopped && backend.mode === 'pty')
+                backend.write(data);
+        });
+        this.terminal.onTitleChange(shellTitle => {
+            this.title = shellTitle.slice(0, TERMINAL_TITLE_LENGTH);
+            publish({ type: 'title', terminalId: id, title: this.title });
+        });
+    }
+    get info() {
+        return {
+            id: this.id,
+            title: this.title,
+            cols: this.cols,
+            rows: this.rows,
+            mode: this.backend.mode,
+            running: this.running
+        };
+    }
+    output(data) {
+        if (this.stopped)
+            return;
+        this.staged += data;
+        if (Buffer.byteLength(this.staged) >= TERMINAL_FRAME_BYTES) {
+            this.flush();
+        }
+        else {
+            this.flushTimer ??= setTimeout(() => this.flush(), FLUSH_DELAY_MS);
+        }
+    }
+    flush() {
+        clearTimeout(this.flushTimer);
+        this.flushTimer = undefined;
+        const data = this.staged;
+        this.staged = '';
+        if (data)
+            this.enqueue(data);
+    }
+    enqueue(data) {
+        if (this.stopped)
+            return undefined;
+        // Bound each frame by UTF-8 bytes without splitting a surrogate pair.
+        for (let offset = 0; offset < data.length;) {
+            let end = Math.min(data.length, offset + FRAME_PART_UNITS);
+            if (end < data.length &&
+                data.charCodeAt(end - 1) >= HIGH_SURROGATE_FIRST &&
+                data.charCodeAt(end - 1) <= HIGH_SURROGATE_LAST)
+                end--;
+            const part = data.slice(offset, end);
+            offset = end;
+            const bytes = Buffer.byteLength(part);
+            this.pendingBytes += bytes;
+            if (this.pendingBytes > TERMINAL_QUEUE_BYTES)
+                this.updateFlow();
+            if (this.pendingBytes > QUEUE_CLOSE_BYTES) {
+                this.onExit();
+                return;
+            }
+            this.queue = this.queue
+                .then(async () => {
+                if (this.stopped)
+                    return undefined;
+                this.tail.push(part);
+                await new Promise(resolve => this.terminal.write(part, resolve));
+                this.sequence++;
+                this.publish({
+                    type: 'output',
+                    terminalId: this.id,
+                    data: part,
+                    cols: this.cols,
+                    rows: this.rows,
+                    sequence: this.sequence
+                });
+                return undefined;
+            })
+                .catch(() => this.onExit())
+                .finally(() => {
+                this.pendingBytes -= bytes;
+                if (!this.stopped && this.pendingBytes < QUEUE_RESUME_BYTES)
+                    this.updateFlow();
+            });
+        }
+    }
+    block(owner, blocked) {
+        if (blocked) {
+            this.blocked.add(owner);
+        }
+        else {
+            this.blocked.delete(owner);
+        }
+        this.updateFlow();
+    }
+    updateFlow() {
+        if (this.stopped)
+            return;
+        if (this.blocked.size || this.pendingBytes > TERMINAL_QUEUE_BYTES) {
+            this.backend.pause();
+        }
+        else {
+            this.backend.resume();
+        }
+    }
+    snapshot(send) {
+        this.flush();
+        this.queue = this.queue.then(() => {
+            if (this.stopped)
+                return undefined;
+            let scrollback = TERMINAL_SCROLLBACK;
+            let data = this.serializer.serialize({ scrollback }) + this.tail.tail;
+            while (Buffer.byteLength(data) > TERMINAL_SNAPSHOT_BYTES &&
+                scrollback > 0) {
+                scrollback = Math.floor(scrollback / 2);
+                data = this.serializer.serialize({ scrollback }) + this.tail.tail;
+            }
+            if (Buffer.byteLength(data) > TERMINAL_SNAPSHOT_BYTES)
+                throw new TerminalError('Terminal snapshot exceeds its limit.');
+            send({
+                type: 'snapshot',
+                terminalId: this.id,
+                data,
+                cols: this.cols,
+                rows: this.rows,
+                sequence: this.sequence
+            });
+            return undefined;
+        });
+        return this.queue;
+    }
+    write(data) {
+        if (!this.stopped)
+            this.backend.write(data);
+    }
+    line(data) {
+        if (this.backend.mode !== 'pipe')
+            throw new TerminalError('Line input requires limited mode.');
+        this.output(data.replace(/\n/g, '\r\n') + '\r\n');
+        this.backend.write(data + '\n');
+    }
+    signal(signal) {
+        if (signal === 'interrupt') {
+            this.backend.interrupt();
+        }
+        else {
+            this.onExit();
+        }
+    }
+    resize(cols, rows) {
+        this.flush();
+        this.queue = this.queue
+            .then(() => {
+            if (this.stopped || (cols === this.cols && rows === this.rows))
+                return undefined;
+            this.backend.resize(cols, rows);
+            this.terminal.resize(cols, rows);
+            this.cols = cols;
+            this.rows = rows;
+            // Order geometry changes with output so every viewer parses the same screen.
+            this.sequence++;
+            this.publish({
+                type: 'output',
+                terminalId: this.id,
+                data: '',
+                cols,
+                rows,
+                sequence: this.sequence
+            });
+            return undefined;
+        })
+            .catch(() => this.onExit());
+        return this.queue;
+    }
+    async dispose() {
+        if (this.stopped)
+            return undefined;
+        this.stopped = true;
+        clearTimeout(this.flushTimer);
+        this.staged = '';
+        await this.backend.kill();
+        await this.queue.catch(() => { });
+        for (const dispose of this.disposers)
+            dispose();
+    }
+}