tassello 0.2.0 → 0.4.0

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>;

package/dist/server/util.js

@@ -1,4 +1,5 @@
-import { existsSync } from 'node:fs';
+import { createHash, randomBytes } from 'node:crypto';
+import { existsSync, promises as fs } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 // The share directory of a ROS package, from the ament index of the sourced
@@ -26,6 +27,27 @@ export function absoluteTopic(topic) {
     const trimmed = topic.trim().replace(/\/+$/, '');
     return trimmed.startsWith('/') ? trimmed : `/${trimmed}`;
 }
+// Whether the page that opened a WebSocket is one of the dashboard's own.
+// Browsers say which site a page is from (Origin), and another site's page
+// cannot change it; the dashboard's is the host the page reached: the Host
+// header, or the X-Forwarded-Host of a reverse proxy. Programs other than
+// browsers send no Origin.
+export function ownPage(headers) {
+    if (headers.origin === undefined) {
+        return true;
+    }
+    let host;
+    try {
+        host = new URL(headers.origin).host.toLowerCase();
+    }
+    catch {
+        // "null": a sandboxed frame, a file
+        return false;
+    }
+    const forwarded = headers['x-forwarded-host'];
+    const proxied = (Array.isArray(forwarded) ? forwarded[0] : forwarded)?.split(',')[0].trim();
+    return [headers.host, proxied].some((reached) => reached?.toLowerCase() === host);
+}
 export function errorMessage(e) {
     return e instanceof Error ? e.message : String(e);
 }
@@ -52,3 +74,25 @@ export function toJson(value) {
     }
     return value;
 }
+// Of a file's content
+export function contentVersion(text) {
+    return createHash('sha256').update(text).digest('hex').slice(0, 16);
+}
+// Writes the file anew, at once: a temporary file renamed over it, keeping
+// its mode; in place if that cannot be (a folder the server cannot write in,
+// a file of another user's)
+export async function replaceFile(file, text) {
+    const stat = await fs.stat(file);
+    if (stat.uid === process.getuid?.()) {
+        const temporary = path.join(path.dirname(file), `.${path.basename(file)}.${randomBytes(4).toString('hex')}.tmp`);
+        try {
+            await fs.writeFile(temporary, text, { mode: stat.mode & 0o7777, flag: 'wx' });
+            await fs.rename(temporary, file);
+            return;
+        }
+        catch {
+            await fs.rm(temporary, { force: true });
+        }
+    }
+    await fs.writeFile(file, text);
+}

package/dist/shared/file_manager.d.ts

@@ -0,0 +1,130 @@
+export interface FsEntry {
+    name: string;
+    kind: 'dir' | 'file' | 'other';
+    link: string | null;
+    size: number;
+    modified: number;
+    mode: number;
+    owner: string;
+    group: string;
+    readable: boolean;
+    writable: boolean;
+    bag: boolean;
+}
+export interface FsSpace {
+    mount: string;
+    total: number;
+    free: number;
+}
+export interface FsListing {
+    path: string;
+    parent: string | null;
+    entries: FsEntry[];
+    truncated: number;
+    writable: boolean;
+    version: string;
+    space: FsSpace | null;
+}
+export interface FsPlaces {
+    home: string;
+    user: string;
+    ros: {
+        name: string;
+        path: string;
+    }[];
+}
+export interface FsDetails extends FsEntry {
+    path: string;
+    realPath: string | null;
+    created: number | null;
+    accessed: number;
+    changed: number;
+    inode: number;
+    links: number;
+    items: number | null;
+    hidden: number | null;
+    space: FsSpace | null;
+}
+export interface FsDisk extends FsSpace {
+    device: string;
+    type: string;
+    readOnly: boolean;
+    used: number;
+    inodes: {
+        total: number;
+        free: number;
+    } | null;
+}
+export interface FsAnalysis {
+    path: string;
+    size: number;
+    disk: number;
+    files: number;
+    folders: number;
+    links: number;
+    children: {
+        name: string;
+        kind: FsEntry['kind'];
+        size: number;
+        files: number;
+    }[];
+    types: {
+        type: string;
+        files: number;
+        size: number;
+    }[];
+    largest: {
+        path: string;
+        size: number;
+    }[];
+    recent: {
+        path: string;
+        modified: number;
+    }[];
+    partial: string | null;
+    unreadable: number;
+    mounts: number;
+    elapsedMs: number;
+}
+export interface FsText {
+    path: string;
+    text: string;
+    version: string;
+    stamp: string;
+    readOnly: string | null;
+}
+export interface FsSaved {
+    version: string;
+    stamp: string;
+    conflict: boolean;
+}
+export type FsConflict = 'ask' | 'skip' | 'keep-both' | 'replace';
+export type FsOperation = {
+    op: 'mkdir';
+    path: string;
+} | {
+    op: 'create';
+    path: string;
+} | {
+    op: 'rename';
+    path: string;
+    name: string;
+} | {
+    op: 'move' | 'copy';
+    paths: string[];
+    to: string;
+    conflict: FsConflict;
+} | {
+    op: 'delete';
+    paths: string[];
+} | {
+    op: 'chmod';
+    path: string;
+    mode: number;
+};
+export interface FsResult {
+    paths: string[];
+    conflicts: string[];
+}
+export declare const FS_MAX_ENTRIES = 5000;
+export declare const FS_MAX_TEXT_BYTES: number;

package/dist/shared/file_manager.js

@@ -0,0 +1,7 @@
+// The robot's files, as the file manager widgets see them: the REST API of
+// /api/fs (see src/server/http.ts). The server acts as its user, anywhere that
+// user can: see the README's Security.
+// Of a folder's entries, at most, listed
+export const FS_MAX_ENTRIES = 5000;
+// Of the files edited as text
+export const FS_MAX_TEXT_BYTES = 5 * 1024 * 1024;