tassello 0.1.0 → 0.2.0

package/dist/server/rosbag.js

@@ -0,0 +1,418 @@
+// Rosbags (rosbag2), for the behavior tree inspectors' record and playback:
+// the messages of some of their topics, read from either storage (MCAP,
+// Jazzy's default, or SQLite, Humble's), serialized as recorded; and topics
+// recorded into a new one by ros2 bag record, the robot's own tool.
+import { spawn } from 'node:child_process';
+import { promises as fs } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import zlib from 'node:zlib';
+import { errorMessage, stripAnsi } from './util.js';
+const BAG_FILE = /\.(mcap|db3)$/i;
+function absolute(input, home) {
+    const trimmed = input.trim();
+    const expanded = trimmed === '~' || trimmed.startsWith('~/') ? path.join(home, trimmed.slice(1)) : trimmed;
+    if (!path.isAbsolute(expanded)) {
+        throw new Error(`Not a path: "${input}" (/…, ~/…)`);
+    }
+    return path.resolve(expanded);
+}
+const nsToMs = (ns) => Number(ns / 1000n) / 1000;
+// The files of a bag: its folder's (split bags' in order), or one of them
+export async function bagFiles(input, home = os.homedir()) {
+    const location = absolute(input, home);
+    const stat = await fs.stat(location).catch(() => null);
+    if (!stat) {
+        throw new Error(`No rosbag at ${location}`);
+    }
+    if (stat.isDirectory()) {
+        const names = await fs.readdir(location);
+        const files = names.filter((name) => BAG_FILE.test(name)).sort((a, b) => a.localeCompare(b, undefined, { numeric: true }));
+        if (files.length === 0) {
+            const compressed = names.some((name) => /\.(mcap|db3)\.\w+$/i.test(name));
+            throw new Error(`No rosbag in ${location}: no .mcap nor .db3 file${compressed ? ' (compressed files are not read)' : ''}`);
+        }
+        return files.map((name) => path.join(location, name));
+    }
+    if (!BAG_FILE.test(location)) {
+        throw new Error(`Not a rosbag: ${location} (a bag's folder, an .mcap or .db3 file)`);
+    }
+    return [location];
+}
+// The messages of the topics accepted, by topic, in the order recorded
+export async function readBag(files, accept) {
+    const topics = new Map();
+    for (const file of files) {
+        const read = /\.mcap$/i.test(file) ? await readMcap(file, accept) : await readSqlite(file, accept);
+        for (const [name, found] of read) {
+            const known = topics.get(name);
+            if (known) {
+                known.messages = known.messages.concat(found.messages);
+            }
+            else {
+                topics.set(name, found);
+            }
+        }
+    }
+    for (const { messages } of topics.values()) {
+        messages.sort((a, b) => a.time - b.time);
+    }
+    return topics;
+}
+// ── MCAP ─────────────────────────────────────────────────────────────────────
+// Records: opcode (u8), length (u64), content; little endian, strings and
+// maps prefixed with their u32 byte length (https://mcap.dev/spec)
+const MCAP_MAGIC = [0x89, 0x4d, 0x43, 0x41, 0x50, 0x30, 0x0d, 0x0a];
+const FOOTER = 0x02;
+const SCHEMA = 0x03;
+const CHANNEL = 0x04;
+const MESSAGE = 0x05;
+const CHUNK = 0x06;
+const CHUNK_INDEX = 0x08;
+const DATA_END = 0x0f;
+// Opcode, length, summary start, summary offset start, summary CRC
+const FOOTER_BYTES = 1 + 8 + 8 + 8 + 4;
+// Reads a buffer; past its end throws (RangeError)
+class Cursor {
+    offset = 0;
+    data;
+    constructor(data) {
+        this.data = data;
+    }
+    u8() {
+        return this.data.readUInt8(this.offset++);
+    }
+    u16() {
+        const value = this.data.readUInt16LE(this.offset);
+        this.offset += 2;
+        return value;
+    }
+    u32() {
+        const value = this.data.readUInt32LE(this.offset);
+        this.offset += 4;
+        return value;
+    }
+    u64() {
+        const value = this.data.readBigUInt64LE(this.offset);
+        this.offset += 8;
+        return value;
+    }
+    // Offsets and lengths: well within a number
+    size() {
+        return Number(this.u64());
+    }
+    bytes(length) {
+        if (this.offset + length > this.data.length) {
+            throw new RangeError('Truncated record');
+        }
+        const bytes = this.data.subarray(this.offset, this.offset + length);
+        this.offset += length;
+        return bytes;
+    }
+    string() {
+        return this.bytes(this.u32()).toString('utf8');
+    }
+}
+function decompress(compression, data) {
+    if (!compression) {
+        return data;
+    }
+    if (compression === 'zstd') {
+        if (typeof zlib.zstdDecompressSync !== 'function') {
+            throw new Error('Reading zstd compressed MCAP needs Node.js 22.15 or newer');
+        }
+        return zlib.zstdDecompressSync(data);
+    }
+    throw new Error(`MCAP compressed with ${compression} is not read: record with zstd, or without compression`);
+}
+// What the records of a file say: its schemas and channels, and the messages
+// of those accepted
+class McapRecords {
+    topics = new Map();
+    channels = new Map();
+    schemas = new Map();
+    accept;
+    constructor(accept) {
+        this.accept = accept;
+    }
+    // The channels whose messages are read
+    wanted() {
+        return new Set([...this.channels].flatMap(([id, topic]) => (topic ? [id] : [])));
+    }
+    record(opcode, content) {
+        const cursor = new Cursor(content);
+        switch (opcode) {
+            case SCHEMA:
+                this.schemas.set(cursor.u16(), cursor.string());
+                break;
+            case CHANNEL: {
+                const id = cursor.u16();
+                const schema = cursor.u16();
+                const topic = { name: cursor.string(), type: this.schemas.get(schema) ?? '' };
+                if (!this.channels.has(id)) {
+                    this.channels.set(id, this.accept(topic) ? topic : null);
+                }
+                break;
+            }
+            case MESSAGE: {
+                const topic = this.channels.get(cursor.u16());
+                if (!topic) {
+                    break;
+                }
+                cursor.u32();
+                const time = nsToMs(cursor.u64());
+                cursor.u64();
+                // A copy: not to keep the whole chunk
+                const data = Uint8Array.prototype.slice.call(content, cursor.offset);
+                const known = this.topics.get(topic.name);
+                if (known) {
+                    known.messages.push({ time, data });
+                }
+                else {
+                    this.topics.set(topic.name, { topic, messages: [{ time, data }] });
+                }
+                break;
+            }
+            case CHUNK: {
+                cursor.offset += 8 + 8 + 8 + 4;
+                const compression = cursor.string();
+                this.records(decompress(compression, cursor.bytes(cursor.size())));
+                break;
+            }
+        }
+    }
+    // A sequence of records, e.g. a chunk's
+    records(data) {
+        const cursor = new Cursor(data);
+        while (cursor.offset + 9 <= data.length) {
+            const opcode = cursor.u8();
+            this.record(opcode, cursor.bytes(cursor.size()));
+        }
+    }
+}
+async function readMcap(file, accept) {
+    const handle = await fs.open(file, 'r').catch((e) => {
+        throw new Error(`Cannot read ${file}: ${e.code ?? errorMessage(e)}`);
+    });
+    try {
+        const { size } = await handle.stat();
+        const read = async (position, length) => {
+            const buffer = Buffer.alloc(Math.max(0, length));
+            const { bytesRead } = await handle.read(buffer, 0, buffer.length, position);
+            return buffer.subarray(0, bytesRead);
+        };
+        const head = await read(0, 8);
+        if (!MCAP_MAGIC.every((byte, i) => head[i] === byte)) {
+            throw new Error(`${file} is not an MCAP file`);
+        }
+        const records = new McapRecords(accept);
+        if (!(await readIndexed(records, read, size))) {
+            await readSequentially(records, read, size);
+        }
+        return records.topics;
+    }
+    finally {
+        await handle.close();
+    }
+}
+// From the summary at the end of the file: the channels, and where the
+// chunks with messages of those accepted are, which alone are read. false if
+// the file has no summary (unfinished, or written without chunks).
+async function readIndexed(records, read, size) {
+    const footerAt = size - 8 - FOOTER_BYTES;
+    if (footerAt < 8) {
+        return false;
+    }
+    const footer = new Cursor(await read(footerAt, FOOTER_BYTES));
+    if (footer.u8() !== FOOTER) {
+        return false;
+    }
+    footer.size();
+    const summaryAt = footer.size();
+    if (summaryAt === 0 || summaryAt >= footerAt) {
+        return false;
+    }
+    const chunks = [];
+    const summary = new Cursor(await read(summaryAt, footerAt - summaryAt));
+    while (summary.offset + 9 <= summary.data.length) {
+        const opcode = summary.u8();
+        const content = summary.bytes(summary.size());
+        if (opcode !== CHUNK_INDEX) {
+            records.record(opcode, content);
+            continue;
+        }
+        const index = new Cursor(content);
+        const start = index.u64();
+        index.u64();
+        const at = index.size();
+        const length = index.size();
+        const map = new Cursor(index.bytes(index.u32()));
+        const channels = [];
+        while (map.offset < map.data.length) {
+            channels.push(map.u16());
+            map.u64();
+        }
+        chunks.push({ at, length, start, channels });
+    }
+    if (chunks.length === 0) {
+        return false;
+    }
+    const wanted = records.wanted();
+    chunks.sort((a, b) => (a.start < b.start ? -1 : a.start > b.start ? 1 : 0));
+    for (const chunk of chunks.filter((c) => c.channels.some((id) => wanted.has(id)))) {
+        const record = new Cursor(await read(chunk.at, chunk.length));
+        const opcode = record.u8();
+        records.record(opcode, record.bytes(record.size()));
+    }
+    return true;
+}
+// Record after record from the start, as far as the file goes
+async function readSequentially(records, read, size) {
+    let position = 8;
+    while (position + 9 <= size) {
+        const header = new Cursor(await read(position, 9));
+        const opcode = header.u8();
+        const length = header.size();
+        if (opcode === FOOTER || opcode === DATA_END) {
+            break;
+        }
+        if ([SCHEMA, CHANNEL, MESSAGE, CHUNK].includes(opcode)) {
+            const content = await read(position + 9, length);
+            if (content.length < length) {
+                // Cut short: a recording that did not end
+                break;
+            }
+            records.record(opcode, content);
+        }
+        position += 9 + length;
+    }
+}
+// ── SQLite ───────────────────────────────────────────────────────────────────
+async function readSqlite(file, accept) {
+    let sqlite;
+    try {
+        sqlite = await import('node:sqlite');
+    }
+    catch {
+        throw new Error('Reading SQLite rosbags (.db3) needs Node.js 22.13 or newer');
+    }
+    let db;
+    try {
+        db = new sqlite.DatabaseSync(file, { readOnly: true });
+    }
+    catch (e) {
+        throw new Error(`Cannot read ${file}: ${errorMessage(e)}`);
+    }
+    try {
+        const topics = new Map();
+        const rows = db.prepare('SELECT id, name, type FROM topics').all();
+        const select = db.prepare('SELECT timestamp, data FROM messages WHERE topic_id = ? ORDER BY timestamp');
+        // Nanoseconds since the epoch: beyond a number's integers
+        select.setReadBigInts(true);
+        for (const row of rows) {
+            const topic = { name: row.name, type: row.type };
+            if (accept(topic)) {
+                const messages = select.all(row.id).map((m) => ({
+                    time: nsToMs(m.timestamp),
+                    data: m.data,
+                }));
+                topics.set(topic.name, { topic, messages });
+            }
+        }
+        return topics;
+    }
+    catch (e) {
+        throw new Error(`Cannot read ${file}: ${errorMessage(e)}`);
+    }
+    finally {
+        db.close();
+    }
+}
+// ── Recording ────────────────────────────────────────────────────────────────
+// Waited for ros2 bag record to say it records; quiet, it is taken as doing so
+const START_TIMEOUT_MS = 8000;
+// Then it is killed: the bag may lack its metadata
+const STOP_TIMEOUT_MS = 10_000;
+const READY = /Subscribed to topic|Listening for topics|Recording\.\.\./;
+const OUTPUT_LIMIT = 4000;
+// The folder a recording makes: a new one, absolute or ~/…, its parent made
+export async function newBagFolder(input, home = os.homedir()) {
+    const folder = absolute(input.trim().replace(/(.)\/+$/, '$1'), home);
+    if (await fs.stat(folder).catch(() => null)) {
+        throw new Error(`${folder} exists already: a recording makes a new folder`);
+    }
+    await fs.mkdir(path.dirname(folder), { recursive: true });
+    return folder;
+}
+// ros2 bag record of topics into a new folder, until stopped
+export class BagRecorder {
+    folder;
+    // Called if it stops by itself, with why
+    onExit = null;
+    child;
+    output = '';
+    stopping = false;
+    constructor(child, folder) {
+        this.child = child;
+        this.folder = folder;
+    }
+    // Resolves once it records, rejects with why it could not
+    static start(folder, topics) {
+        return new Promise((resolve, reject) => {
+            const child = spawn('ros2', ['bag', 'record', '-o', folder, ...topics], {
+                cwd: os.homedir(),
+                stdio: ['ignore', 'pipe', 'pipe'],
+            });
+            const recorder = new BagRecorder(child, folder);
+            let settled = false;
+            const ready = () => {
+                if (!settled) {
+                    settled = true;
+                    clearTimeout(timer);
+                    resolve(recorder);
+                }
+            };
+            const timer = setTimeout(ready, START_TIMEOUT_MS);
+            const onOutput = (chunk) => {
+                recorder.output = (recorder.output + stripAnsi(chunk.toString())).slice(-OUTPUT_LIMIT);
+                if (READY.test(recorder.output)) {
+                    ready();
+                }
+            };
+            child.stdout?.on('data', onOutput);
+            child.stderr?.on('data', onOutput);
+            child.on('error', (e) => {
+                recorder.output = e.code === 'ENOENT' ? 'ros2 not found: is ROS sourced?' : errorMessage(e);
+                if (!settled) {
+                    settled = true;
+                    clearTimeout(timer);
+                    reject(new Error(recorder.output));
+                }
+            });
+            child.on('close', (code, signal) => {
+                clearTimeout(timer);
+                const lines = recorder.output.trim().split('\n').slice(-2).join(' ').trim();
+                const reason = lines || `ros2 bag record exited (${signal ?? code})`;
+                if (!settled) {
+                    settled = true;
+                    reject(new Error(reason));
+                }
+                else if (!recorder.stopping) {
+                    recorder.onExit?.(reason);
+                }
+            });
+        });
+    }
+    // As Ctrl+C does, which completes the bag
+    async stop() {
+        this.stopping = true;
+        if (this.child.exitCode !== null || this.child.signalCode !== null) {
+            return;
+        }
+        const closed = new Promise((resolve) => this.child.once('close', resolve));
+        this.child.kill('SIGINT');
+        const timer = setTimeout(() => this.child.kill('SIGKILL'), STOP_TIMEOUT_MS);
+        await closed;
+        clearTimeout(timer);
+    }
+}

package/dist/server/rosout.d.ts

@@ -0,0 +1,16 @@
+import type rclnodejs from 'rclnodejs';
+import { type RosoutUpdate } from '../shared/protocol.ts';
+import type { StreamState } from './frame_stream.ts';
+import { type Logger } from './util.ts';
+export interface RosoutWatcher {
+    onStatus: (state: StreamState, message: string) => void;
+    onUpdate: (update: Omit<RosoutUpdate, 'type' | 'id'>) => void;
+}
+export declare class Rosout {
+    private readonly node;
+    private readonly logger;
+    private readonly logs;
+    constructor(node: rclnodejs.Node, logger: Logger);
+    watch(topic: string, watcher: RosoutWatcher): () => void;
+    private forget;
+}

package/dist/server/rosout.js

@@ -0,0 +1,203 @@
+// The ROS log for the logs widgets: the rcl_interfaces/msg/Log every node's
+// logger publishes on /rosout, and the nodes of the ROS graph.
+//
+// A log is followed whole, like the behavior trees' (behavior_trees.ts): each
+// topic is subscribed once, with its publishers' QoS (rcl's: reliable and
+// transient local, so that each node's latest messages arrive first) and a
+// deep queue. The server keeps its latest ROSOUT_HISTORY messages, and sends
+// its pages the new ones at most ROSOUT_RATE times a second, at most
+// MAX_BATCH at a time: a node logging faster than that has the oldest of each
+// batch skipped, which the page is told. The log outlives its last page for
+// LINGER_MS: a page reloaded, or a panel shown again, finds what was logged
+// meanwhile.
+import { ROSOUT_HISTORY, ROSOUT_RATE } from '../shared/protocol.js';
+import { publishersQos } from './qos.js';
+import { LogHistory, nodeNames } from './rosout_log.js';
+import { absoluteTopic, errorMessage } from './util.js';
+const LOG_TYPE = 'rcl_interfaces/msg/Log';
+// How often the graph is checked for the topic's publishers, until it has one
+const RETRY_PERIOD_MS = 1000;
+// Messages queued while the server is busy: nodes log bursts as they start.
+// The depth of rcl's own rosout publishers.
+const QUEUE_DEPTH = 1000;
+// ROSOUT_RATE times this a second, at most, to a page
+const MAX_BATCH = 500;
+const LINGER_MS = 10 * 60_000;
+// How often the graph is checked for its nodes, while a page watches
+const NODES_CHECK_MS = 2000;
+// A log topic: its subscription, its messages, its pages
+class RosoutLog {
+    watchers = new Set();
+    lingerTimer = null;
+    node;
+    logger;
+    topic;
+    started = Date.now();
+    history = new LogHistory(ROSOUT_HISTORY);
+    subscription = null;
+    retryTimer = null;
+    state = 'waiting';
+    message = '';
+    nodes = [];
+    // Since the last update
+    nodesChanged = false;
+    nodesTimer = null;
+    flushTimer = null;
+    lastFlush = 0;
+    constructor(node, logger, topic) {
+        this.node = node;
+        this.logger = logger;
+        this.topic = topic;
+        this.subscribe();
+    }
+    add(watcher) {
+        if (this.lingerTimer) {
+            clearTimeout(this.lingerTimer);
+            this.lingerTimer = null;
+        }
+        this.checkNodes();
+        // What the others have not had yet, which the new one gets with the rest
+        this.flush();
+        this.watchers.add(watcher);
+        watcher.onStatus(this.state, this.message);
+        watcher.onUpdate({
+            reset: true,
+            started: this.started,
+            entries: this.history.snapshot(),
+            skipped: 0,
+            nodes: this.nodes,
+        });
+        this.nodesTimer ??= setInterval(() => this.checkNodes(), NODES_CHECK_MS);
+    }
+    remove(watcher) {
+        this.watchers.delete(watcher);
+        if (this.watchers.size === 0 && this.nodesTimer) {
+            clearInterval(this.nodesTimer);
+            this.nodesTimer = null;
+        }
+    }
+    destroy() {
+        for (const timer of [this.retryTimer, this.flushTimer, this.lingerTimer]) {
+            if (timer) {
+                clearTimeout(timer);
+            }
+        }
+        if (this.nodesTimer) {
+            clearInterval(this.nodesTimer);
+        }
+        if (this.subscription) {
+            this.node.destroySubscription(this.subscription);
+        }
+    }
+    subscribe() {
+        this.retryTimer = null;
+        const match = publishersQos(this.node, this.topic, LOG_TYPE, QUEUE_DEPTH);
+        if (!('qos' in match)) {
+            this.setState(match.state, match.message);
+            this.retryTimer = setTimeout(() => this.subscribe(), RETRY_PERIOD_MS);
+            return;
+        }
+        try {
+            this.subscription = this.node.createSubscription(LOG_TYPE, this.topic, { qos: match.qos }, (raw) => this.onMessage(raw));
+        }
+        catch (e) {
+            this.setState('error', `Cannot subscribe to ${this.topic}: ${errorMessage(e)}`);
+            return;
+        }
+        this.setState('waiting', `Waiting for messages on ${this.topic}`);
+    }
+    onMessage(raw) {
+        this.history.add(raw);
+        this.setState('streaming', LOG_TYPE);
+        this.scheduleFlush();
+    }
+    checkNodes() {
+        let nodes;
+        try {
+            nodes = nodeNames(this.node.getNodeNamesAndNamespaces());
+        }
+        catch {
+            return;
+        }
+        if (nodes.join('\n') !== this.nodes.join('\n')) {
+            this.nodes = nodes;
+            this.nodesChanged = true;
+            this.scheduleFlush();
+        }
+    }
+    scheduleFlush() {
+        if (this.flushTimer || this.watchers.size === 0) {
+            return;
+        }
+        const wait = Math.max(0, this.lastFlush + 1000 / ROSOUT_RATE - Date.now());
+        this.flushTimer = setTimeout(() => this.flush(), wait);
+    }
+    flush() {
+        if (this.flushTimer) {
+            clearTimeout(this.flushTimer);
+            this.flushTimer = null;
+        }
+        this.lastFlush = Date.now();
+        const batch = this.history.takeBatch(MAX_BATCH);
+        const nodes = this.nodesChanged ? this.nodes : null;
+        this.nodesChanged = false;
+        if (!batch && !nodes) {
+            return;
+        }
+        const update = {
+            reset: false,
+            started: this.started,
+            entries: batch?.entries ?? [],
+            skipped: batch?.skipped ?? 0,
+            nodes,
+        };
+        for (const watcher of this.watchers) {
+            watcher.onUpdate(update);
+        }
+    }
+    setState(state, message) {
+        if (state === this.state && message === this.message) {
+            return;
+        }
+        if (state === 'error') {
+            this.logger.warn(message);
+        }
+        this.state = state;
+        this.message = message;
+        for (const watcher of this.watchers) {
+            watcher.onStatus(state, message);
+        }
+    }
+}
+export class Rosout {
+    node;
+    logger;
+    logs = new Map();
+    constructor(node, logger) {
+        this.node = node;
+        this.logger = logger;
+    }
+    // Until the returned function is called
+    watch(topic, watcher) {
+        const name = absoluteTopic(topic);
+        let log = this.logs.get(name);
+        if (!log) {
+            log = new RosoutLog(this.node, this.logger, name);
+            this.logs.set(name, log);
+        }
+        const shared = log;
+        shared.add(watcher);
+        return () => {
+            shared.remove(watcher);
+            if (shared.watchers.size === 0 && !shared.lingerTimer) {
+                shared.lingerTimer = setTimeout(() => this.forget(name, shared), LINGER_MS);
+            }
+        };
+    }
+    forget(topic, log) {
+        log.destroy();
+        if (this.logs.get(topic) === log) {
+            this.logs.delete(topic);
+        }
+    }
+}

package/dist/server/rosout_log.d.ts

@@ -0,0 +1,20 @@
+import type { LogEntry } from '../shared/protocol.ts';
+export declare function logEntry(raw: unknown, seq: number): LogEntry;
+export interface LogBatch {
+    entries: LogEntry[];
+    skipped: number;
+}
+export declare class LogHistory {
+    private readonly capacity;
+    private entries;
+    private last;
+    private taken;
+    constructor(capacity: number);
+    add(raw: unknown): void;
+    snapshot(): LogEntry[];
+    takeBatch(max: number): LogBatch | null;
+}
+export declare function nodeNames(nodes: {
+    name: string;
+    namespace: string;
+}[]): string[];