@tequila99/githuman 0.4.1 → 0.5.0

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

@@ -0,0 +1,200 @@
+import { Value } from '@sinclair/typebox/value';
+import { TerminalClientMessageSchema } from "../../../shared/terminal/schemas.js";
+import { TERMINAL_CLIENT_BYTES } from "../../../shared/terminal/constants.js";
+import { errorMessage } from "../../../shared/utils/error-message.js";
+// Close the connection when a client queues more commands than it can need.
+const MAX_PENDING_COMMANDS = 128;
+// Disconnect a client that stays blocked for this long.
+const SLOW_CLIENT_MS = 5000;
+// Block the output of a session when a client holds this much unacknowledged data.
+const CREDIT_PAUSE_BYTES = TERMINAL_CLIENT_BYTES / 16;
+export class TerminalChannel {
+    subscribed = new Set();
+    subscribing = new Set();
+    credit = new Map();
+    unsubscribe;
+    stopped = false;
+    commands = Promise.resolve();
+    pendingCommands = 0;
+    registry;
+    send;
+    disconnect;
+    slowClientMs;
+    constructor(registry, send, disconnect, slowClientMs = SLOW_CLIENT_MS) {
+        this.registry = registry;
+        this.send = send;
+        this.disconnect = disconnect;
+        this.slowClientMs = slowClientMs;
+        this.unsubscribe = registry.subscribe(message => this.event(message));
+        send({ type: 'list', sessions: registry.list });
+    }
+    receive(value) {
+        if (!Value.Check(TerminalClientMessageSchema, value)) {
+            this.disconnect();
+            return;
+        }
+        if (++this.pendingCommands > MAX_PENDING_COMMANDS) {
+            this.disconnect();
+            return;
+        }
+        this.commands = this.commands
+            .then(async () => {
+            if (this.stopped)
+                return undefined;
+            try {
+                switch (value.type) {
+                    case 'create': {
+                        const session = await this.registry.create(value.cols, value.rows);
+                        if (!this.stopped)
+                            this.send({
+                                type: 'created',
+                                requestId: value.requestId,
+                                terminalId: session.id
+                            });
+                        break;
+                    }
+                    case 'subscribe':
+                        await this.attach(value.terminalId);
+                        break;
+                    case 'snapshot':
+                        await this.snapshot(value.terminalId);
+                        break;
+                    case 'input':
+                        this.registry.get(value.terminalId).write(value.data);
+                        break;
+                    case 'line':
+                        this.registry.get(value.terminalId).line(value.data);
+                        break;
+                    case 'signal':
+                        this.registry.get(value.terminalId).signal(value.signal);
+                        break;
+                    case 'resize':
+                        await this.registry.resize(value.terminalId, value.cols, value.rows);
+                        break;
+                    case 'close':
+                        await this.registry.close(value.terminalId);
+                        break;
+                    case 'ack':
+                        this.ack(value.terminalId, value.sequence);
+                        break;
+                    case 'ping':
+                        this.send({ type: 'pong' });
+                        break;
+                }
+            }
+            catch (error) {
+                if (!this.stopped)
+                    this.send({
+                        type: 'error',
+                        ...('requestId' in value ? { requestId: value.requestId } : {}),
+                        code: 'GHT_TERMINAL',
+                        message: errorMessage(error)
+                    });
+            }
+            return undefined;
+        })
+            .finally(() => {
+            this.pendingCommands--;
+        });
+    }
+    async attach(id) {
+        if (this.subscribed.has(id) || this.subscribing.has(id))
+            return;
+        this.subscribing.add(id);
+        try {
+            this.registry.attach(id, this);
+            await this.snapshot(id);
+        }
+        finally {
+            this.subscribing.delete(id);
+        }
+    }
+    async snapshot(id) {
+        const session = this.registry.get(id);
+        await session.snapshot(message => {
+            if (this.stopped)
+                return undefined;
+            clearTimeout(this.credit.get(id)?.timeout);
+            session.block(this, false);
+            this.credit.set(id, {
+                bytes: 0,
+                frames: new Map(),
+                lastSequence: message.type === 'snapshot' ? message.sequence : 0
+            });
+            this.subscribed.add(id);
+            this.send(message);
+            return undefined;
+        });
+    }
+    ack(id, sequence) {
+        const credit = this.credit.get(id);
+        if (!credit)
+            return;
+        if (sequence > credit.lastSequence) {
+            this.disconnect();
+            return;
+        }
+        for (const [key, bytes] of credit.frames)
+            if (key <= sequence) {
+                credit.bytes -= bytes;
+                credit.frames.delete(key);
+            }
+        this.flow(id, credit);
+    }
+    flow(id, credit) {
+        if (credit.bytes > CREDIT_PAUSE_BYTES) {
+            this.registry.get(id).block(this, true);
+            credit.timeout ??= setTimeout(() => this.disconnect(), this.slowClientMs);
+        }
+        else {
+            clearTimeout(credit.timeout);
+            credit.timeout = undefined;
+            this.registry.get(id).block(this, false);
+        }
+    }
+    event(message) {
+        if (this.stopped)
+            return undefined;
+        if (message.type === 'output') {
+            if (!this.subscribed.has(message.terminalId))
+                return;
+            const credit = this.credit.get(message.terminalId);
+            if (!credit)
+                return;
+            const bytes = Buffer.byteLength(message.data);
+            credit.bytes += bytes;
+            credit.frames.set(message.sequence, bytes);
+            credit.lastSequence = message.sequence;
+            this.flow(message.terminalId, credit);
+            if (credit.bytes > TERMINAL_CLIENT_BYTES) {
+                this.disconnect();
+                return;
+            }
+        }
+        else if (message.type === 'exit') {
+            clearTimeout(this.credit.get(message.terminalId)?.timeout);
+            this.subscribed.delete(message.terminalId);
+            this.credit.delete(message.terminalId);
+        }
+        this.send(message);
+    }
+    dispose() {
+        if (this.stopped)
+            return undefined;
+        this.stopped = true;
+        for (const [id, credit] of this.credit) {
+            clearTimeout(credit.timeout);
+            try {
+                this.registry.get(id).block(this, false);
+            }
+            catch {
+                /* The session already exited. */
+            }
+        }
+        this.unsubscribe();
+        this.registry.detach(this);
+        this.subscribed.clear();
+        this.subscribing.clear();
+        this.credit.clear();
+    }
+}

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();
+    }
+}