tassello 0.2.0 → 0.3.0

package/dist/server/session.js

@@ -37,6 +37,8 @@ function strings(value, field) {
     }
     return value.map((v) => v.trim()).filter(Boolean);
 }
+// A terminal's name, chosen by the page
+const TERMINAL_NAME = /^[\w-]{1,64}$/;
 function subscriptionId(value) {
     if (typeof value !== 'number' || !Number.isInteger(value) || value < 0 || value > 0xffffffff) {
         throw new Error('Invalid subscription id');
@@ -55,10 +57,16 @@ export class Session {
     arms = new Map();
     // The behavior tree playbacks, for their controls
     playbacks = new Map();
+    // The terminals, for what is typed in them
+    terminals = new Map();
+    // The page is one of the dashboard's own (see ownPage): only those open
+    // terminals
+    ownPage;
     lastError = { message: '', at: 0 };
-    constructor(ws, services) {
+    constructor(ws, services, ownPage) {
         this.ws = ws;
         this.services = services;
+        this.ownPage = ownPage;
         ws.on('message', (data, isBinary) => {
             if (!isBinary) {
                 this.onMessage(data.toString());
@@ -98,6 +106,7 @@ export class Session {
         this.consumers.clear();
         this.arms.clear();
         this.playbacks.clear();
+        this.terminals.clear();
     }
     reportError(message) {
         const now = Date.now();
@@ -237,6 +246,62 @@ export class Session {
                 }));
                 return;
             }
+            case 'diagnostics.subscribe': {
+                const id = subscriptionId(message.id);
+                this.unsubscribe(id);
+                this.subscriptions.set(id, services.diagnostics.watch(string(message.topic, 'topic'), {
+                    onStatus: (state, text) => this.sendStreamStatus(id, state, text),
+                    onUpdate: (update) => this.send({ type: 'diagnostics', id, ...update }),
+                }));
+                return;
+            }
+            case 'terminal.open': {
+                const id = subscriptionId(message.id);
+                this.unsubscribe(id);
+                if (!this.ownPage) {
+                    // e.g. another site's page, which a browser lets reach the robot
+                    this.sendStreamStatus(id, 'error', 'Terminals open in the dashboard’s own pages only');
+                    return;
+                }
+                if (typeof message.terminal !== 'string' || !TERMINAL_NAME.test(message.terminal)) {
+                    throw new Error('Invalid terminal name');
+                }
+                const point = (value) => (typeof value === 'number' && Number.isFinite(value) ? value : null);
+                const view = services.terminals.open({
+                    terminal: message.terminal,
+                    command: optionalString(message.command),
+                    folder: optionalString(message.folder) || '~',
+                    cols: number(message.cols, 2, 1000, 80),
+                    rows: number(message.rows, 1, 500, 24),
+                    started: point(message.started),
+                    offset: point(message.offset),
+                }, {
+                    onOutput: (output) => this.send({ type: 'terminal.output', id, ...output }),
+                    onExit: (exit) => this.send({ type: 'terminal.exit', id, ...exit }),
+                    onStatus: (state, text) => this.sendStreamStatus(id, state, text),
+                });
+                this.terminals.set(id, view);
+                this.subscriptions.set(id, () => view.close());
+                return;
+            }
+            case 'terminal.input':
+                if (typeof message.data === 'string') {
+                    this.terminals.get(subscriptionId(message.id))?.input(message.data);
+                }
+                return;
+            case 'terminal.resize':
+                this.terminals
+                    .get(subscriptionId(message.id))
+                    ?.resize(number(message.cols, 2, 1000, 80), number(message.rows, 1, 500, 24));
+                return;
+            case 'terminal.ack':
+                if (typeof message.started === 'number' && typeof message.offset === 'number') {
+                    this.terminals.get(subscriptionId(message.id))?.ack(message.started, message.offset);
+                }
+                return;
+            case 'terminal.restart':
+                this.terminals.get(subscriptionId(message.id))?.restart();
+                return;
             case 'arm.subscribe': {
                 const id = subscriptionId(message.id);
                 this.unsubscribe(id);
@@ -375,5 +440,6 @@ export class Session {
         this.consumers.delete(id);
         this.arms.delete(id);
         this.playbacks.delete(id);
+        this.terminals.delete(id);
     }
 }

package/dist/server/terminal_output.d.ts

@@ -0,0 +1,25 @@
+export declare class OutputLog {
+    private readonly limit;
+    private readonly chunks;
+    private first;
+    private length;
+    constructor(limit: number);
+    get start(): number;
+    get end(): number;
+    append(text: string): void;
+    since(offset: number): string | null;
+}
+export type NextOutput = {
+    data: string;
+    offset: number;
+} | 'snapshot' | null;
+export declare class Delivery {
+    offset: number;
+    private readonly sent;
+    private size;
+    constructor(offset: number);
+    get pending(): number;
+    next(log: OutputLog, window: number): NextOutput;
+    record(offset: number, size: number): void;
+    ack(offset: number): void;
+}

package/dist/server/terminal_output.js

@@ -0,0 +1,108 @@
+// A terminal's output as its pages get it (see terminals.ts): numbered by
+// offset, in characters (UTF-16 code units) since its program started, the
+// latest kept for the pages that missed some; and for each page, what it was
+// sent and has not written yet.
+// Small chunks (echoes of what is typed) are joined into the last one, up to
+// this many characters
+const JOIN_BELOW = 16 * 1024;
+export class OutputLog {
+    // At least `limit` characters, the latest, in whole chunks
+    limit;
+    chunks = [];
+    // Of the first chunk
+    first = 0;
+    length = 0;
+    constructor(limit) {
+        this.limit = limit;
+    }
+    // The oldest output kept
+    get start() {
+        return this.first;
+    }
+    get end() {
+        return this.first + this.length;
+    }
+    append(text) {
+        if (!text) {
+            return;
+        }
+        const last = this.chunks.length - 1;
+        if (last >= 0 && this.chunks[last].length < JOIN_BELOW) {
+            this.chunks[last] += text;
+        }
+        else {
+            this.chunks.push(text);
+        }
+        this.length += text.length;
+        while (this.chunks.length > 1 && this.length - this.chunks[0].length >= this.limit) {
+            const dropped = this.chunks.shift();
+            this.first += dropped.length;
+            this.length -= dropped.length;
+        }
+    }
+    // The output from offset on; null if it is no longer kept, or not yet
+    since(offset) {
+        if (offset < this.first || offset > this.end) {
+            return null;
+        }
+        let skip = offset - this.first;
+        let index = 0;
+        while (index < this.chunks.length && skip >= this.chunks[index].length) {
+            skip -= this.chunks[index].length;
+            index++;
+        }
+        return index === this.chunks.length ? '' : this.chunks[index].slice(skip) + this.chunks.slice(index + 1).join('');
+    }
+}
+function isHighSurrogate(code) {
+    return code >= 0xd800 && code <= 0xdbff;
+}
+// What a page was sent of the output, and has not written yet: at most a
+// window of characters, so that a slow page (or one hidden, which writes
+// nothing) does not pile output up on the way, and gets the screen instead
+// once it lacks too much
+export class Delivery {
+    // Where the page's output goes once it wrote what it was sent
+    offset;
+    // What it was sent: the offset after each message, and its size
+    sent = [];
+    size = 0;
+    constructor(offset) {
+        this.offset = offset;
+    }
+    // Characters sent and not written yet
+    get pending() {
+        return this.size;
+    }
+    // What the page should get next: the output it lacks, as much as the window
+    // leaves; the screen instead if it lacks more than a window of it, or what
+    // it lacks is no longer kept; null if up to date, or its window is full
+    next(log, window) {
+        const room = window - this.size;
+        if (this.offset === log.end || room <= 0) {
+            return null;
+        }
+        const data = log.end - this.offset > window ? null : log.since(this.offset);
+        if (data === null) {
+            return 'snapshot';
+        }
+        let part = data.length > room ? data.slice(0, room) : data;
+        if (part.length < data.length && isHighSurrogate(part.charCodeAt(part.length - 1))) {
+            part = part.slice(0, -1);
+        }
+        return part ? { data: part, offset: this.offset + part.length } : null;
+    }
+    // Sent: the output up to offset, in a message of size characters
+    record(offset, size) {
+        this.offset = offset;
+        this.sent.push({ offset, size });
+        this.size += size;
+    }
+    // The page wrote the output up to offset: its messages are acknowledged in
+    // the order they were sent, whose offsets never go back
+    ack(offset) {
+        while (this.sent.length > 0 && this.sent[0].offset <= offset) {
+            this.size -= this.sent.shift().size;
+        }
+    }
+}

package/dist/server/terminals.d.ts

@@ -0,0 +1,32 @@
+import { type TerminalExit, type TerminalOutput } from '../shared/protocol.ts';
+import type { StreamState } from './frame_stream.ts';
+import { type Logger } from './util.ts';
+export interface TerminalRequest {
+    terminal: string;
+    command: string;
+    folder: string;
+    cols: number;
+    rows: number;
+    started: number | null;
+    offset: number | null;
+}
+export interface TerminalWatcher {
+    onOutput: (output: Omit<TerminalOutput, 'type' | 'id'>) => void;
+    onExit: (exit: Omit<TerminalExit, 'type' | 'id'>) => void;
+    onStatus: (state: StreamState, message: string) => void;
+}
+export interface TerminalView {
+    input(data: string): void;
+    resize(cols: number, rows: number): void;
+    ack(started: number, offset: number): void;
+    restart(): void;
+    close(): void;
+}
+export declare class Terminals {
+    private readonly logger;
+    private readonly terminals;
+    constructor(logger: Logger);
+    open(request: TerminalRequest, watcher: TerminalWatcher): TerminalView;
+    stopAll(): void;
+    private hangUpUnseen;
+}

package/dist/server/terminals.js

@@ -0,0 +1,366 @@
+// The terminal widgets' terminals: the user's login shell, or a command it
+// runs, on a pseudo-terminal (pty.ts), as the server's user.
+//
+// A terminal outlives its pages: a page that reloads or reconnects opens it
+// again by its name and gets the output it missed. That output is also
+// written to a terminal of the server's own (xterm.js, headless), whose
+// screen and scrollback a page gets instead when it shows none of it yet, or
+// lacks more than a window of it (TERMINAL_WINDOW). The server's terminal
+// paces the program, which waits while it is behind; the pages do not: a slow
+// page, or a hidden one, gets the screen later, never holding the program up.
+//
+// A terminal that no page shows is hung up after LINGER_MS, as is the one
+// unseen the longest when MAX_TERMINALS are open and another is opened.
+import { statSync } from 'node:fs';
+import os from 'node:os';
+import serializeModule from '@xterm/addon-serialize';
+import headlessModule from '@xterm/headless';
+import { TERMINAL_SCROLLBACK, TERMINAL_WINDOW, } from '../shared/protocol.js';
+import { resolvePath } from './file_manager.js';
+import { Pty } from './pty.js';
+import { Delivery, OutputLog } from './terminal_output.js';
+import { errorMessage } from './util.js';
+// CommonJS modules, without named exports for Node
+const { SerializeAddon } = serializeModule;
+const { Terminal: Screen } = headlessModule;
+const LINGER_MS = 60 * 60_000;
+const MAX_TERMINALS = 16;
+// Output kept for the pages that missed some
+const LOG_LIMIT = 1024 * 1024;
+// The program waits while the server's terminal has more than this to write,
+// until it has less than RESUME_BELOW
+const PAUSE_ABOVE = 128 * 1024;
+const RESUME_BELOW = 32 * 1024;
+// Output goes out at most this often, gathered
+const FLUSH_MS = 5;
+const MAX_COLS = 1000;
+const MAX_ROWS = 500;
+function isFile(file) {
+    try {
+        return statSync(file).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+// The user's, unless it lets no one in (a service's user)
+function loginShell() {
+    for (const shell of [process.env.SHELL, os.userInfo().shell]) {
+        if (shell && !/\/(nologin|false)$/.test(shell) && isFile(shell)) {
+            return shell;
+        }
+    }
+    return '/bin/bash';
+}
+// The folder to start in: the home folder if it cannot be, and why
+function workingFolder(folder) {
+    const home = os.homedir();
+    try {
+        const cwd = resolvePath(folder || '~');
+        return statSync(cwd).isDirectory() ? { cwd, problem: null } : { cwd: home, problem: 'not a folder' };
+    }
+    catch (e) {
+        return { cwd: home, problem: e.code === 'ENOENT' ? 'not found' : errorMessage(e) };
+    }
+}
+function programEnvironment() {
+    const env = {
+        ...process.env,
+        TERM: 'xterm-256color',
+        COLORTERM: 'truecolor',
+        TERM_PROGRAM: 'tassello',
+    };
+    // The server's own, as a systemd service: not the terminal's
+    for (const name of ['NOTIFY_SOCKET', 'JOURNAL_STREAM', 'INVOCATION_ID', 'COLUMNS', 'LINES']) {
+        delete env[name];
+    }
+    return env;
+}
+// One run of a terminal's program: the program, its output and its screen
+class Run {
+    started;
+    pty;
+    screen;
+    serializer = new SerializeAddon();
+    log = new OutputLog(LOG_LIMIT);
+    // Of the output: received, and written to the screen
+    written = 0;
+    parsed = 0;
+    paused = false;
+    title = '';
+    // undefined while it runs
+    exitCode = undefined;
+    // Why it could not start
+    error = null;
+    constructor(started, pty, cols, rows) {
+        this.started = started;
+        this.pty = pty;
+        this.screen = new Screen({ cols, rows, scrollback: TERMINAL_SCROLLBACK, allowProposedApi: true });
+        // The addon is typed for the page's terminal, which the headless one is
+        // made of
+        this.screen.loadAddon(this.serializer);
+        this.screen.onTitleChange((title) => {
+            this.title = title;
+        });
+    }
+    // The screen and its scrollback, as of the output parsed
+    snapshot() {
+        return this.serializer.serialize({ scrollback: TERMINAL_SCROLLBACK });
+    }
+    dispose() {
+        this.pty.hangUp();
+        this.screen.dispose();
+    }
+}
+class Terminal {
+    name;
+    command;
+    folder;
+    // While no page shows it: since when
+    hiddenSince = null;
+    // The pages showing it, and what each was sent
+    watchers = new Map();
+    logger;
+    onEnd;
+    run;
+    cols;
+    rows;
+    flushTimer = null;
+    lingerTimer = null;
+    constructor(request, logger, onEnd) {
+        this.name = request.terminal;
+        this.command = request.command;
+        this.folder = request.folder;
+        this.cols = request.cols;
+        this.rows = request.rows;
+        this.logger = logger;
+        this.onEnd = onEnd;
+        this.start();
+    }
+    attach(watcher, started, offset, cols, rows) {
+        if (this.lingerTimer) {
+            clearTimeout(this.lingerTimer);
+            this.lingerTimer = null;
+        }
+        this.hiddenSince = null;
+        this.resize(cols, rows);
+        const { run } = this;
+        const delivery = new Delivery(0);
+        this.watchers.set(watcher, delivery);
+        watcher.onStatus(run.error ? 'error' : 'streaming', run.error ?? '');
+        if (started === run.started && offset !== null && run.log.since(offset) !== null) {
+            // The page missed some: what follows
+            delivery.offset = offset;
+        }
+        else if (run.written === 0) {
+            // A new program: the page keeps what it shows of another
+            watcher.onOutput({ started: run.started, offset: 0, reset: false, data: '', title: null });
+        }
+        else {
+            this.sendSnapshot(watcher, delivery);
+        }
+        this.deliver(watcher, delivery);
+        if (run.exitCode !== undefined) {
+            watcher.onExit({ started: run.started, exitCode: run.exitCode });
+        }
+    }
+    detach(watcher) {
+        if (!this.watchers.delete(watcher) || this.watchers.size > 0) {
+            return;
+        }
+        this.hiddenSince = Date.now();
+        this.lingerTimer = setTimeout(() => {
+            this.logger.info(`Terminal ${this.name}: not shown for ${LINGER_MS / 60_000} minutes, hung up`);
+            this.end();
+        }, LINGER_MS);
+    }
+    input(data) {
+        if (this.run.exitCode === undefined) {
+            this.run.pty.write(data);
+        }
+    }
+    resize(cols, rows) {
+        cols = Math.min(MAX_COLS, Math.max(2, Math.round(cols)));
+        rows = Math.min(MAX_ROWS, Math.max(1, Math.round(rows)));
+        if (cols === this.cols && rows === this.rows) {
+            return;
+        }
+        this.cols = cols;
+        this.rows = rows;
+        this.run.pty.resize(cols, rows);
+        this.run.screen.resize(cols, rows);
+    }
+    ack(watcher, started, offset) {
+        const delivery = this.watchers.get(watcher);
+        if (delivery && started === this.run.started) {
+            delivery.ack(offset);
+            this.deliver(watcher, delivery);
+        }
+    }
+    // Its program anew, from a clean screen; with another command or folder
+    restart(command = this.command, folder = this.folder) {
+        this.command = command;
+        this.folder = folder;
+        this.run.dispose();
+        this.start();
+        for (const watcher of this.watchers.keys()) {
+            this.watchers.set(watcher, new Delivery(0));
+            watcher.onStatus(this.run.error ? 'error' : 'streaming', this.run.error ?? '');
+            watcher.onOutput({ started: this.run.started, offset: 0, reset: false, data: '', title: null });
+        }
+    }
+    end() {
+        if (this.flushTimer) {
+            clearTimeout(this.flushTimer);
+        }
+        if (this.lingerTimer) {
+            clearTimeout(this.lingerTimer);
+        }
+        this.run.dispose();
+        this.onEnd();
+    }
+    start() {
+        const { cwd, problem } = workingFolder(this.folder);
+        const shell = loginShell();
+        const args = this.command ? ['-l', '-c', this.command] : ['-l'];
+        const pty = new Pty({ file: shell, args, cwd, env: programEnvironment(), cols: this.cols, rows: this.rows });
+        // Unique to this terminal: what tells the pages it is another program
+        const started = Math.max(Date.now(), (this.run?.started ?? 0) + 1);
+        const run = new Run(started, pty, this.cols, this.rows);
+        this.run = run;
+        const what = this.command ? `\`${this.command}\`` : shell;
+        this.logger.info(`Terminal ${this.name}: ${what} in ${cwd} (pid ${pty.pid ?? '-'})`);
+        if (problem) {
+            this.output(run, `\x1b[33mtassello: cannot start in ${this.folder} (${problem}): starting in ${cwd}\x1b[0m\r\n`);
+        }
+        pty.on('data', (data) => this.output(run, data));
+        pty.on('exit', (exitCode) => {
+            if (run !== this.run) {
+                return;
+            }
+            run.exitCode = exitCode;
+            this.logger.info(`Terminal ${this.name}: ${what} ${exitCode === null ? 'hung up' : `exited with ${exitCode}`}`);
+            this.flush();
+            for (const watcher of this.watchers.keys()) {
+                watcher.onExit({ started: run.started, exitCode });
+            }
+        });
+        pty.on('error', (e) => {
+            if (run !== this.run) {
+                return;
+            }
+            run.exitCode = null;
+            run.error =
+                e.code === 'ENOENT'
+                    ? 'Cannot open a terminal: python3 is not installed (ROS 2 comes with it)'
+                    : `Cannot open a terminal: ${errorMessage(e)}`;
+            this.logger.error(`Terminal ${this.name}: ${run.error}`);
+            for (const watcher of this.watchers.keys()) {
+                watcher.onStatus('error', run.error);
+                watcher.onExit({ started: run.started, exitCode: null });
+            }
+        });
+    }
+    output(run, data) {
+        if (run !== this.run) {
+            return;
+        }
+        run.log.append(data);
+        run.written += data.length;
+        run.screen.write(data, () => {
+            run.parsed += data.length;
+            if (run.paused && run.written - run.parsed < RESUME_BELOW) {
+                run.paused = false;
+                run.pty.resume();
+            }
+        });
+        if (!run.paused && run.written - run.parsed > PAUSE_ABOVE) {
+            run.paused = true;
+            run.pty.pause();
+        }
+        this.flushTimer ??= setTimeout(() => {
+            this.flushTimer = null;
+            this.flush();
+        }, FLUSH_MS);
+    }
+    flush() {
+        for (const [watcher, delivery] of this.watchers) {
+            this.deliver(watcher, delivery);
+        }
+    }
+    deliver(watcher, delivery) {
+        const { run } = this;
+        const next = delivery.next(run.log, TERMINAL_WINDOW);
+        if (next === 'snapshot') {
+            this.sendSnapshot(watcher, delivery);
+        }
+        else if (next) {
+            delivery.record(next.offset, next.data.length);
+            watcher.onOutput({ started: run.started, offset: next.offset, reset: false, data: next.data, title: null });
+        }
+    }
+    // The screen as of the output it has written: the page gets the rest after
+    sendSnapshot(watcher, delivery) {
+        const { run } = this;
+        const data = run.snapshot();
+        delivery.record(run.parsed, data.length);
+        watcher.onOutput({ started: run.started, offset: run.parsed, reset: true, data, title: run.title });
+    }
+}
+const IDLE_VIEW = { input() { }, resize() { }, ack() { }, restart() { }, close() { } };
+export class Terminals {
+    logger;
+    terminals = new Map();
+    constructor(logger) {
+        this.logger = logger;
+    }
+    open(request, watcher) {
+        let terminal = this.terminals.get(request.terminal);
+        if (terminal && (terminal.command !== request.command || terminal.folder !== request.folder)) {
+            // Its widget's properties changed
+            terminal.restart(request.command, request.folder);
+        }
+        if (!terminal) {
+            if (this.terminals.size >= MAX_TERMINALS && !this.hangUpUnseen()) {
+                watcher.onStatus('error', `${MAX_TERMINALS} terminals are open on the robot already: close one`);
+                return IDLE_VIEW;
+            }
+            const opened = new Terminal(request, this.logger, () => {
+                if (this.terminals.get(request.terminal) === opened) {
+                    this.terminals.delete(request.terminal);
+                }
+            });
+            this.terminals.set(request.terminal, opened);
+            terminal = opened;
+        }
+        const shown = terminal;
+        shown.attach(watcher, request.started, request.offset, request.cols, request.rows);
+        return {
+            input: (data) => shown.input(data),
+            resize: (cols, rows) => shown.resize(cols, rows),
+            ack: (started, offset) => shown.ack(watcher, started, offset),
+            restart: () => shown.restart(),
+            close: () => shown.detach(watcher),
+        };
+    }
+    // The server is shutting down
+    stopAll() {
+        for (const terminal of [...this.terminals.values()]) {
+            terminal.end();
+        }
+    }
+    // The terminal unseen the longest, if any is: hung up to open another
+    hangUpUnseen() {
+        let oldest = null;
+        for (const terminal of this.terminals.values()) {
+            if (terminal.hiddenSince !== null && (oldest === null || terminal.hiddenSince < oldest.hiddenSince)) {
+                oldest = terminal;
+            }
+        }
+        if (oldest) {
+            this.logger.info(`Terminal ${oldest.name}: hung up, to open another`);
+            oldest.end();
+        }
+        return oldest !== null;
+    }
+}

package/dist/server/util.d.ts

@@ -1,3 +1,4 @@
+import type { IncomingHttpHeaders } from 'node:http';
 export interface Logger {
     debug(message: string): unknown;
     info(message: string): unknown;
@@ -8,6 +9,9 @@ export declare function packageShareDirectory(name: string): string | null;
 export declare function defaultPanelsDirectory(): string;
 export declare function tasselloRoot(): string;
 export declare function absoluteTopic(topic: string): string;
+export declare function ownPage(headers: IncomingHttpHeaders): boolean;
 export declare function errorMessage(e: unknown): string;
 export declare function stripAnsi(text: string): string;
 export declare function toJson(value: unknown): unknown;
+export declare function contentVersion(text: string): string;
+export declare function replaceFile(file: string, text: string): Promise<void>;