tassello 0.1.0 → 0.2.0

package/dist/server/behavior_trees.js

@@ -0,0 +1,362 @@
+// The logs of behavior trees (nav2_msgs/msg/BehaviorTreeLog), for the
+// behavior tree inspector widgets: the tree a widget names (its XML file, see
+// behavior_tree_file.ts) and what its nodes are doing (behavior_tree_state.ts).
+//
+// A log is a stream of transitions, not of states: none of them may be lost,
+// unlike the latest-only messages of topics.ts. Each topic is subscribed once,
+// with its publishers' QoS and a deep queue; each tree of it keeps its nodes'
+// state, sent to its pages as it changes, at most BT_RATE a second. The state
+// outlives its last page for LINGER_MS: a page reloaded, or a panel shown
+// again, finds the nodes as they are, which the log only says when they change.
+//
+// A topic is recorded into a rosbag (ros2 bag record) when a page asks, until
+// one asks to stop: every page following it is told. A bag is played back for
+// the page that opens it (behavior_tree_playback.ts).
+import { promises as fs } from 'node:fs';
+import { BT_RATE } from '../shared/protocol.js';
+import { readTree } from './behavior_tree_file.js';
+import { logTransitions } from './behavior_tree_log.js';
+import { BehaviorTreePlayback } from './behavior_tree_playback.js';
+import { BehaviorTreeState } from './behavior_tree_state.js';
+import { publishersQos } from './qos.js';
+import { BagRecorder, newBagFolder } from './rosbag.js';
+import { absoluteTopic, errorMessage } from './util.js';
+// 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: a tree logs bursts of them
+const QUEUE_DEPTH = 100;
+const LINGER_MS = 10 * 60_000;
+// How often the tree's files are checked for changes, while watched
+const FILE_CHECK_MS = 3000;
+// The subscription to a topic, shared by its trees
+class LogTopic {
+    listeners = new Set();
+    node;
+    logger;
+    topic;
+    subscription = null;
+    retryTimer = null;
+    state = 'waiting';
+    message = '';
+    constructor(node, logger, topic) {
+        this.node = node;
+        this.logger = logger;
+        this.topic = topic;
+        this.subscribe();
+    }
+    add(listener) {
+        this.listeners.add(listener);
+        listener.onStatus(this.state, this.message);
+    }
+    destroy() {
+        if (this.retryTimer) {
+            clearTimeout(this.retryTimer);
+        }
+        if (this.subscription) {
+            this.node.destroySubscription(this.subscription);
+        }
+    }
+    subscribe() {
+        this.retryTimer = null;
+        const match = publishersQos(this.node, this.topic, null, 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(
+            // @ts-expect-error: the type is a runtime string, not one of the literal types
+            match.type, this.topic, { qos: match.qos }, (raw) => this.onMessage(raw, match.type));
+        }
+        catch (e) {
+            this.setState('error', `Cannot subscribe to ${this.topic}: ${errorMessage(e)}`);
+            return;
+        }
+        this.setState('waiting', `Waiting for transitions on ${this.topic}`);
+    }
+    onMessage(raw, type) {
+        let transitions;
+        try {
+            transitions = logTransitions(raw);
+        }
+        catch (e) {
+            this.setState('error', `${this.topic} is a ${type}, ${errorMessage(e)}`);
+            return;
+        }
+        this.setState('streaming', type);
+        for (const listener of this.listeners) {
+            listener.onTransitions(transitions);
+        }
+    }
+    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 listener of this.listeners) {
+            listener.onStatus(state, message);
+        }
+    }
+}
+// A tree of a topic: its file, its nodes' state, its pages
+class TreeMonitor {
+    watchers = new Set();
+    lingerTimer = null;
+    source;
+    uploadsDir;
+    logger;
+    tree = null;
+    recording;
+    state = new BehaviorTreeState([]);
+    // Transitions that came while the tree was read, applied after
+    queued = [];
+    // The files read, and their versions then
+    versions = new Map();
+    status = { state: 'waiting', message: '' };
+    flushTimer = null;
+    lastFlush = 0;
+    fileTimer = null;
+    destroyed = false;
+    constructor(source, uploadsDir, logger, recording) {
+        this.source = source;
+        this.uploadsDir = uploadsDir;
+        this.logger = logger;
+        this.recording = recording;
+        void this.load();
+    }
+    add(watcher) {
+        if (this.lingerTimer) {
+            clearTimeout(this.lingerTimer);
+            this.lingerTimer = null;
+        }
+        // What the others have not had yet, which the new one gets with the rest
+        this.flush();
+        this.watchers.add(watcher);
+        watcher.onStatus(this.status.state, this.status.message);
+        watcher.onRecording(this.recording);
+        if (this.tree) {
+            watcher.onTree(this.tree);
+            watcher.onUpdate({ reset: true, ...this.state.snapshot() });
+        }
+        this.fileTimer ??= setInterval(() => void this.checkFiles(), FILE_CHECK_MS);
+    }
+    remove(watcher) {
+        this.watchers.delete(watcher);
+        if (this.watchers.size === 0 && this.fileTimer) {
+            clearInterval(this.fileTimer);
+            this.fileTimer = null;
+        }
+    }
+    destroy() {
+        this.destroyed = true;
+        for (const timer of [this.flushTimer, this.lingerTimer]) {
+            if (timer) {
+                clearTimeout(timer);
+            }
+        }
+        if (this.fileTimer) {
+            clearInterval(this.fileTimer);
+        }
+    }
+    setRecording(recording) {
+        this.recording = recording;
+        for (const watcher of this.watchers) {
+            watcher.onRecording(recording);
+        }
+    }
+    onStatus(state, message) {
+        this.status = { state, message };
+        for (const watcher of this.watchers) {
+            watcher.onStatus(state, message);
+        }
+    }
+    onTransitions(transitions) {
+        const now = Date.now();
+        if (this.queued) {
+            this.queued.push({ transitions, at: now });
+            return;
+        }
+        for (const transition of transitions) {
+            this.state.apply(transition, now);
+        }
+        this.scheduleFlush();
+    }
+    async load() {
+        const { tree, files } = await readTree(this.source, this.uploadsDir, this.logger);
+        if (this.destroyed) {
+            return;
+        }
+        this.versions = new Map(await Promise.all(files.map(async (file) => [file, await version(file)])));
+        this.tree = tree;
+        this.state = new BehaviorTreeState(tree.nodes);
+        for (const { transitions, at } of this.queued ?? []) {
+            for (const transition of transitions) {
+                this.state.apply(transition, at);
+            }
+        }
+        this.queued = null;
+        for (const watcher of this.watchers) {
+            watcher.onTree(tree);
+            watcher.onUpdate({ reset: true, ...this.state.snapshot() });
+        }
+    }
+    // The tree is read again when one of its files changed: its pages start over
+    async checkFiles() {
+        if (this.queued || this.versions.size === 0) {
+            return;
+        }
+        for (const [file, known] of this.versions) {
+            if ((await version(file)) !== known) {
+                this.queued = [];
+                await this.load();
+                return;
+            }
+        }
+    }
+    scheduleFlush() {
+        if (this.flushTimer || this.watchers.size === 0) {
+            return;
+        }
+        const wait = Math.max(0, this.lastFlush + 1000 / BT_RATE - Date.now());
+        this.flushTimer = setTimeout(() => this.flush(), wait);
+    }
+    flush() {
+        if (this.flushTimer) {
+            clearTimeout(this.flushTimer);
+            this.flushTimer = null;
+        }
+        this.lastFlush = Date.now();
+        const changes = this.state.takeChanges();
+        if (!changes) {
+            return;
+        }
+        for (const watcher of this.watchers) {
+            watcher.onUpdate({ reset: false, ...changes });
+        }
+    }
+}
+// Size and time of a file, '' if gone
+async function version(file) {
+    const stat = await fs.stat(file).catch(() => null);
+    return stat ? `${stat.size}-${stat.mtimeMs}` : '';
+}
+export class BehaviorTrees {
+    node;
+    logger;
+    uploadsDir;
+    topics = new Map();
+    // By topic, then tree source
+    monitors = new Map();
+    // By topic
+    recordings = new Map();
+    constructor(node, logger, uploadsDir) {
+        this.node = node;
+        this.logger = logger;
+        this.uploadsDir = uploadsDir;
+    }
+    // Until the returned function is called
+    watch(topic, tree, watcher) {
+        const name = absoluteTopic(topic);
+        const source = tree.trim();
+        let trees = this.monitors.get(name);
+        if (!trees) {
+            trees = new Map();
+            this.monitors.set(name, trees);
+        }
+        let monitor = trees.get(source);
+        if (!monitor) {
+            monitor = new TreeMonitor(source, this.uploadsDir, this.logger, this.recordingOf(name));
+            trees.set(source, monitor);
+            let log = this.topics.get(name);
+            if (!log) {
+                log = new LogTopic(this.node, this.logger, name);
+                this.topics.set(name, log);
+            }
+            log.add(monitor);
+        }
+        const shared = monitor;
+        shared.add(watcher);
+        return () => {
+            shared.remove(watcher);
+            if (shared.watchers.size === 0 && !shared.lingerTimer) {
+                shared.lingerTimer = setTimeout(() => this.forget(name, source, shared), LINGER_MS);
+            }
+        };
+    }
+    // Records the topic into a new folder, or stops (path null): resolves with
+    // the bag's folder, null if it was not recording
+    async record(topic, path) {
+        const name = absoluteTopic(topic);
+        const current = this.recordings.get(name);
+        if (path === null) {
+            if (!current?.recorder) {
+                return null;
+            }
+            this.recordings.delete(name);
+            this.announce(name);
+            await current.recorder.stop();
+            this.logger.info(`Recorded ${name} into ${current.path}`);
+            return current.path;
+        }
+        if (current) {
+            throw new Error(`${name} is being recorded already, into ${current.path}`);
+        }
+        const recording = { path: '', since: 0, recorder: null };
+        this.recordings.set(name, recording);
+        try {
+            recording.path = await newBagFolder(path);
+            recording.recorder = await BagRecorder.start(recording.path, [name]);
+        }
+        catch (e) {
+            this.recordings.delete(name);
+            throw new Error(`Cannot record ${name}: ${errorMessage(e)}`);
+        }
+        recording.since = Date.now();
+        recording.recorder.onExit = (reason) => {
+            if (this.recordings.get(name) === recording) {
+                this.recordings.delete(name);
+                this.announce(name);
+                this.logger.warn(`Recording ${name} stopped: ${reason}`);
+            }
+        };
+        this.logger.info(`Recording ${name} into ${recording.path}`);
+        this.announce(name);
+        return recording.path;
+    }
+    // A bag played back for a page, until closed
+    play(bag, topic, tree, watcher) {
+        return new BehaviorTreePlayback({ bag, topic, tree: tree.trim(), uploadsDir: this.uploadsDir, logger: this.logger }, watcher);
+    }
+    // The recordings completed, as the server stops
+    async stopAll() {
+        const recorders = [...this.recordings.values()].flatMap((recording) => recording.recorder ?? []);
+        this.recordings.clear();
+        await Promise.all(recorders.map((recorder) => recorder.stop()));
+    }
+    recordingOf(topic) {
+        const recording = this.recordings.get(topic);
+        return recording?.recorder ? { path: recording.path, since: recording.since } : null;
+    }
+    announce(topic) {
+        for (const monitor of this.monitors.get(topic)?.values() ?? []) {
+            monitor.setRecording(this.recordingOf(topic));
+        }
+    }
+    forget(topic, source, monitor) {
+        monitor.destroy();
+        const trees = this.monitors.get(topic);
+        trees?.delete(source);
+        const log = this.topics.get(topic);
+        log?.listeners.delete(monitor);
+        if (trees?.size === 0) {
+            this.monitors.delete(topic);
+            log?.destroy();
+            this.topics.delete(topic);
+        }
+    }
+}

package/dist/server/files.d.ts

@@ -1,5 +1,7 @@
 export declare const IMAGE_EXTENSIONS: Set<string>;
+export type FileKind = 'image' | 'behavior-tree' | 'bag' | 'folder';
 export declare const MAX_UPLOAD_BYTES: number;
+export declare function fileKind(value: string | null): FileKind;
 export declare function resolveImagePath(input: string, home?: string): string;
 export declare function imageType(data: Buffer): string | null;
 export interface DirectoryListing {
@@ -7,9 +9,10 @@ export interface DirectoryListing {
     parent: string | null;
     entries: {
         name: string;
-        kind: 'dir' | 'image';
+        kind: 'dir' | FileKind;
     }[];
 }
-export declare function listDirectory(input: string, home?: string): Promise<DirectoryListing>;
+export declare function listDirectory(input: string, kind?: FileKind, home?: string): Promise<DirectoryListing>;
 export declare function saveUpload(uploadsDir: string, data: Buffer): Promise<string>;
+export declare function isBehaviorTreeXml(text: string): boolean;
 export declare function isUploadName(name: string): boolean;

package/dist/server/files.js

@@ -1,16 +1,29 @@
-// Images for the image viewer widgets: files of the robot, which a page picks
-// by browsing its directories, and images uploaded from a page, kept by the
-// server next to the panels. Only images: the dashboard does not hand out any
-// file of the robot.
+// Images for the image viewer widgets, and behavior trees (XML) for the
+// behavior tree inspectors: files of the robot, which a page picks by
+// browsing its directories, and files uploaded from a page, kept by the
+// server next to the panels. Only those: the dashboard does not hand out any
+// file of the robot. A page also browses for rosbags, and for folders.
 import { createHash } from 'node:crypto';
 import { promises as fs } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { HttpError } from './panels.js';
 export const IMAGE_EXTENSIONS = new Set(['.png', '.jpg', '.jpeg', '.gif', '.webp', '.bmp', '.svg']);
+const EXTENSIONS = {
+    image: IMAGE_EXTENSIONS,
+    'behavior-tree': new Set(['.xml']),
+    bag: new Set(['.mcap', '.db3']),
+    folder: new Set(),
+};
+const FILE_KINDS = new Set(Object.keys(EXTENSIONS));
 export const MAX_UPLOAD_BYTES = 20 * 1024 * 1024;
 // Uploaded files are named after their content: no clash, no duplicate
-const UPLOAD_NAME = /^[0-9a-f]{16}\.(png|jpg|gif|webp|bmp|svg)$/;
+const UPLOAD_NAME = /^[0-9a-f]{16}\.(png|jpg|gif|webp|bmp|svg|xml)$/;
+// BT.CPP's XML, whose root element is <root>
+const BEHAVIOR_TREE = /^(<\?xml[^>]*>\s*)?(<!--[\s\S]*?-->\s*)*<root[\s>]/;
+export function fileKind(value) {
+    return value && FILE_KINDS.has(value) ? value : 'image';
+}
 // A robot path (absolute or ~/...) to an image file; throws for anything else
 export function resolveImagePath(input, home = os.homedir()) {
     const trimmed = input.trim();
@@ -48,8 +61,8 @@ export function imageType(data) {
     }
     return null;
 }
-// Of the directory (~ by default)
-export async function listDirectory(input, home = os.homedir()) {
+// Of the directory (~ by default): its directories and files of that kind
+export async function listDirectory(input, kind = 'image', home = os.homedir()) {
     const trimmed = input.trim() || '~';
     const expanded = trimmed === '~' || trimmed.startsWith('~/') ? path.join(home, trimmed.slice(1)) : trimmed;
     if (!path.isAbsolute(expanded)) {
@@ -74,26 +87,32 @@ export async function listDirectory(input, home = os.homedir()) {
             ? await fs.stat(path.join(dir, entry.name)).catch(() => null)
             : entry;
         if (target?.isDirectory()) {
-            entries.push({ name: entry.name, kind: 'dir' });
+            const bag = kind === 'bag' && (await fs.stat(path.join(dir, entry.name, 'metadata.yaml')).catch(() => null));
+            entries.push({ name: entry.name, kind: bag ? 'bag' : 'dir' });
         }
-        else if (target?.isFile() && IMAGE_EXTENSIONS.has(path.extname(entry.name).toLowerCase())) {
-            entries.push({ name: entry.name, kind: 'image' });
+        else if (target?.isFile() && EXTENSIONS[kind].has(path.extname(entry.name).toLowerCase())) {
+            entries.push({ name: entry.name, kind });
         }
     }
     entries.sort((a, b) => (a.kind === b.kind ? a.name.localeCompare(b.name) : a.kind === 'dir' ? -1 : 1));
     return { dir, parent: dir === path.parse(dir).root ? null : path.dirname(dir), entries };
 }
-// Saves an uploaded image; returns its name in the uploads directory
+// Saves an uploaded image or behavior tree; returns its name in the uploads
+// directory
 export async function saveUpload(uploadsDir, data) {
-    const type = imageType(data);
+    const type = imageType(data) ?? (isBehaviorTreeXml(data.subarray(0, 64 * 1024).toString('utf8')) ? 'xml' : null);
     if (!type) {
-        throw new HttpError(415, 'Not an image: PNG, JPEG, GIF, WebP, BMP or SVG');
+        throw new HttpError(415, 'Not an image (PNG, JPEG, GIF, WebP, BMP, SVG) nor a behavior tree (XML)');
     }
     const name = `${createHash('sha256').update(data).digest('hex').slice(0, 16)}.${type}`;
     await fs.mkdir(uploadsDir, { recursive: true });
     await fs.writeFile(path.join(uploadsDir, name), data);
     return name;
 }
+// Whether the text is BT.CPP's XML, by its first element: <root>
+export function isBehaviorTreeXml(text) {
+    return BEHAVIOR_TREE.test(text.slice(0, 64 * 1024).trimStart());
+}
 export function isUploadName(name) {
     return UPLOAD_NAME.test(name);
 }

package/dist/server/http.js

@@ -12,9 +12,10 @@
 //          directory, as package://<package>/<path> names it: the meshes of
 //          the robot description
 //   GET    /api/files?path=<path>       an image of the robot (absolute or ~/ path)
-//   GET    /api/files/list?dir=<dir>    its subdirectories and images
-//   POST   /api/uploads                 an image (the body) -> {name}
-//   GET    /api/uploads/<name>          an uploaded image
+//   GET    /api/files/list?dir=<dir>[&kind=behavior-tree]
+//                                       its subdirectories and images (or XML files)
+//   POST   /api/uploads                 an image or a behavior tree (the body) -> {name}
+//   GET    /api/uploads/<name>          an uploaded file
 //   GET    /api/plugins                 [PluginInfo] of the plugins loaded
 //   GET    /plugins/<name>/<path>       a file of the plugin's client folder
 import { createReadStream, promises as fs } from 'node:fs';
@@ -22,7 +23,7 @@ import path from 'node:path';
 import { promisify } from 'node:util';
 import { gzip } from 'node:zlib';
 import { DASHBOARD_CLIENT_HEADER } from '../shared/protocol.js';
-import { isUploadName, listDirectory, MAX_UPLOAD_BYTES, resolveImagePath, saveUpload } from './files.js';
+import { fileKind, isUploadName, listDirectory, MAX_UPLOAD_BYTES, resolveImagePath, saveUpload } from './files.js';
 import { HttpError } from './panels.js';
 import { errorMessage, packageShareDirectory } from './util.js';
 // By lowercase extension: meshes come as .STL as often as .stl
@@ -38,6 +39,7 @@ const CONTENT_TYPES = {
     '.jpeg': 'image/jpeg',
     '.gif': 'image/gif',
     '.webp': 'image/webp',
+    '.xml': 'application/xml; charset=utf-8',
     '.bmp': 'image/bmp',
     '.ico': 'image/x-icon',
     '.woff2': 'font/woff2',
@@ -143,7 +145,7 @@ async function api({ store, topics, uploadsDir, plugins }, req, res, route) {
             return serveFile(path.dirname(file), path.basename(file), req, res, SANDBOXED);
         }
         if (id === 'list' && rest.length === 0) {
-            return sendJson(res, 200, await listDirectory(query.get('dir') ?? ''));
+            return sendJson(res, 200, await listDirectory(query.get('dir') ?? '', fileKind(query.get('kind'))));
         }
         throw new HttpError(404, `No API at ${req.url}`);
     }

package/dist/server/rosbag.d.ts

@@ -0,0 +1,25 @@
+export interface BagTopic {
+    name: string;
+    type: string;
+}
+export interface BagMessage {
+    time: number;
+    data: Uint8Array;
+}
+export type BagTopics = Map<string, {
+    topic: BagTopic;
+    messages: BagMessage[];
+}>;
+export declare function bagFiles(input: string, home?: string): Promise<string[]>;
+export declare function readBag(files: string[], accept: (topic: BagTopic) => boolean): Promise<BagTopics>;
+export declare function newBagFolder(input: string, home?: string): Promise<string>;
+export declare class BagRecorder {
+    readonly folder: string;
+    onExit: ((reason: string) => void) | null;
+    private readonly child;
+    private output;
+    private stopping;
+    private constructor();
+    static start(folder: string, topics: string[]): Promise<BagRecorder>;
+    stop(): Promise<void>;
+}