tassello 0.1.1 → 0.3.0

package/dist/server/behavior_tree_files.js

@@ -0,0 +1,382 @@
+// The behavior trees' XML files, for the behavior tree editors: read for
+// their pages, and again whenever they change (saved by a page, or edited on
+// the robot), with the nodes they can use: Nav2's, those of their includes
+// and of the libraries the pages name (TreeNodesModel). And saved, only over
+// behavior trees, and only if unchanged since the page read them.
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { readModels } from '../shared/bt_nodes.js';
+import { parseXmlSource, sourceText } from '../shared/xml.js';
+import { resolveTreeFile } from './behavior_tree_file.js';
+import { isBehaviorTreeXml } from './files.js';
+import { contentVersion, errorMessage, packageShareDirectory, replaceFile } from './util.js';
+// How often the files are checked for changes
+const POLL_MS = 2000;
+const MAX_FILE_BYTES = 5 * 1024 * 1024;
+// Includes of includes, at most
+const MAX_INCLUDES = 50;
+// A file of models kept parsed while unchanged; this many
+const MODEL_CACHE = 64;
+// Size, time and inode of a file, '' if gone
+async function stamp(file) {
+    const stat = await fs.stat(file).catch(() => null);
+    return stat ? `${stat.size}-${stat.mtimeMs}-${stat.ino}` : '';
+}
+async function readText(file) {
+    const stat = await fs.stat(file);
+    if (!stat.isFile()) {
+        throw new Error(`${file} is not a file`);
+    }
+    if (stat.size > MAX_FILE_BYTES) {
+        throw new Error(`${file} is larger than ${MAX_FILE_BYTES / 1024 / 1024} MB`);
+    }
+    return fs.readFile(file, 'utf8');
+}
+function modelElement(text, element) {
+    return {
+        name: element.name,
+        attributes: element.attributes,
+        children: element.children.flatMap((child) => (child.type === 'element' ? [modelElement(text, child)] : [])),
+        text: sourceText(text, element),
+    };
+}
+// The includes of a tree's root, resolved: relative to its file, or to their
+// ros_pkg's share directory
+function includes(root, file, warnings) {
+    return root.children.flatMap((child) => {
+        if (child.type !== 'element' || child.name !== 'include') {
+            return [];
+        }
+        const { ros_pkg: rosPackage, path: relative = '' } = child.attributes;
+        const share = rosPackage ? packageShareDirectory(rosPackage) : path.dirname(file);
+        if (!share) {
+            warnings.push(`Not included: ${relative}, of the package ${rosPackage}, not found`);
+            return [];
+        }
+        return [path.resolve(share, relative)];
+    });
+}
+const modelCache = new Map();
+// A file's models and BehaviorTrees, parsed again only when it changes
+async function readModelFile(file) {
+    const current = await stamp(file);
+    const cached = modelCache.get(file);
+    if (cached && cached.stamp === current) {
+        return cached.parsed;
+    }
+    const text = await readText(file).catch((e) => {
+        throw new Error(`Cannot read ${file}: ${e.code ?? errorMessage(e)}`);
+    });
+    const root = parseXmlSource(text);
+    if (root.name !== 'root') {
+        throw new Error(`${file} is not of BT.CPP: its root element is <${root.name}>, not <root>`);
+    }
+    const parsed = {
+        models: readModels(modelElement(text, root)),
+        trees: root.children.flatMap((child) => (child.type === 'element' && child.name === 'BehaviorTree' && child.attributes.ID ? [child.attributes.ID] : [])),
+        root,
+    };
+    modelCache.delete(file);
+    modelCache.set(file, { stamp: current, parsed });
+    if (modelCache.size > MODEL_CACHE) {
+        modelCache.delete(modelCache.keys().next().value);
+    }
+    return parsed;
+}
+// The models of Nav2's nodes, if installed
+function nav2Models() {
+    const share = packageShareDirectory('nav2_behavior_tree');
+    return share && path.join(share, 'nav2_tree_nodes.xml');
+}
+// What a page edits: the file, read again when it changes, for all its pages
+class WatchedFile {
+    file;
+    readOnly;
+    watchers = new Set();
+    state = null;
+    stamp = null;
+    timer = null;
+    checking = null;
+    constructor(file, readOnly) {
+        this.file = file;
+        this.readOnly = readOnly;
+    }
+    get text() {
+        return this.state?.text ?? null;
+    }
+    add(watcher) {
+        this.watchers.add(watcher);
+        if (this.state) {
+            watcher.onFile(this.state);
+        }
+        this.timer ??= setInterval(() => void this.check(), POLL_MS);
+        void this.check();
+    }
+    // false once it has no watcher left
+    remove(watcher) {
+        this.watchers.delete(watcher);
+        if (this.watchers.size > 0) {
+            return true;
+        }
+        this.stop();
+        return false;
+    }
+    stop() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+    }
+    // Reads it again if it changed: once at a time
+    check() {
+        this.checking ??= this.read().finally(() => (this.checking = null));
+        return this.checking;
+    }
+    // After a check started before it changed
+    async refresh() {
+        await this.checking;
+        await this.check();
+    }
+    async read() {
+        const current = await stamp(this.file);
+        if (current === this.stamp) {
+            return;
+        }
+        this.stamp = current;
+        let state;
+        try {
+            const text = await readText(this.file);
+            let readOnly = this.readOnly;
+            if (!readOnly) {
+                readOnly = await fs.access(await fs.realpath(this.file), fs.constants.W_OK).then(() => null, () => 'The server’s user cannot write it: save it elsewhere');
+            }
+            state = { file: this.file, text, version: contentVersion(text), readOnly, error: null };
+        }
+        catch (e) {
+            const code = e.code;
+            const error = code === 'ENOENT' ? `No file ${this.file}` : `Cannot read ${this.file}: ${code ?? errorMessage(e)}`;
+            state = { file: this.file, text: null, version: null, readOnly: this.readOnly, error };
+        }
+        if (state.version !== this.state?.version || state.error !== this.state?.error || state.readOnly !== this.state?.readOnly) {
+            this.state = state;
+            for (const watcher of this.watchers) {
+                watcher.onFile(state);
+            }
+        }
+    }
+}
+// The models a page can use with its file and libraries: again whenever the
+// file's includes, or any file read for them, change
+class ModelsWatch {
+    watched;
+    libraries;
+    uploadsDir;
+    onModels;
+    // The files read, and their stamps then
+    stamps = new Map();
+    text = undefined;
+    sent = '';
+    timer;
+    running = false;
+    // Asked again while checking
+    again = false;
+    closed = false;
+    constructor(watched, libraries, uploadsDir, onModels) {
+        this.watched = watched;
+        this.libraries = libraries;
+        this.uploadsDir = uploadsDir;
+        this.onModels = onModels;
+        this.timer = setInterval(() => void this.check(), POLL_MS);
+    }
+    close() {
+        this.closed = true;
+        clearInterval(this.timer);
+    }
+    async check() {
+        if (this.running) {
+            this.again = true;
+            return;
+        }
+        this.running = true;
+        try {
+            do {
+                this.again = false;
+                let changed = this.watched.text !== this.text;
+                for (const [file, known] of this.stamps) {
+                    changed ||= (await stamp(file)) !== known;
+                }
+                if (changed && !this.closed) {
+                    await this.read();
+                }
+            } while (this.again && !this.closed);
+        }
+        finally {
+            this.running = false;
+        }
+    }
+    async read() {
+        this.text = this.watched.text;
+        const stamps = new Map();
+        const libraries = [];
+        // The first of each ID
+        const trees = new Map();
+        const warnings = [];
+        const load = async (file) => {
+            stamps.set(file, await stamp(file));
+            return readModelFile(file);
+        };
+        const nav2 = nav2Models();
+        if (nav2) {
+            try {
+                libraries.push({ name: 'Nav2', file: nav2, models: (await load(nav2)).models });
+            }
+            catch {
+                // Not readable: Nav2's nodes are known by name anyway
+            }
+        }
+        if (this.text !== null) {
+            // The includes, and theirs
+            const queue = [];
+            try {
+                queue.push(...includes(parseXmlSource(this.text), this.watched.file, warnings));
+            }
+            catch {
+                // Not XML, as the page will say
+            }
+            const seen = new Set([this.watched.file]);
+            while (queue.length > 0 && seen.size <= MAX_INCLUDES) {
+                const file = queue.shift();
+                if (seen.has(file)) {
+                    continue;
+                }
+                seen.add(file);
+                try {
+                    const included = await load(file);
+                    for (const id of included.trees) {
+                        if (!trees.has(id)) {
+                            trees.set(id, file);
+                        }
+                    }
+                    if (included.models.length > 0) {
+                        libraries.push({ name: path.basename(file), file, models: included.models });
+                    }
+                    queue.push(...includes(included.root, file, warnings));
+                }
+                catch (e) {
+                    warnings.push(`Not included: ${errorMessage(e)}`);
+                }
+            }
+        }
+        for (const source of this.libraries) {
+            try {
+                const file = resolveTreeFile(source, this.uploadsDir);
+                const library = await load(file);
+                if (library.models.length === 0) {
+                    warnings.push(`No node models (TreeNodesModel) in the library ${source}`);
+                }
+                libraries.push({ name: source.startsWith('uploads/') ? source : path.basename(file), file, models: library.models });
+            }
+            catch (e) {
+                warnings.push(`Library ${source}: ${errorMessage(e)}`);
+            }
+        }
+        if (this.closed) {
+            return;
+        }
+        this.stamps = stamps;
+        const models = { libraries, trees: [...trees].map(([id, file]) => ({ id, file })), warnings };
+        const text = JSON.stringify(models);
+        if (text !== this.sent) {
+            this.sent = text;
+            this.onModels(models);
+        }
+    }
+}
+export class BehaviorTreeFiles {
+    uploadsDir;
+    logger;
+    // By file
+    watched = new Map();
+    constructor(uploadsDir, logger) {
+        this.uploadsDir = uploadsDir;
+        this.logger = logger;
+    }
+    // The file the page names, and the models it can use: returns what ends it
+    watch(source, libraries, watcher) {
+        let file;
+        try {
+            file = resolveTreeFile(source, this.uploadsDir);
+        }
+        catch (e) {
+            watcher.onFile({ file: '', text: null, version: null, readOnly: null, error: errorMessage(e) });
+            watcher.onModels({ libraries: [], trees: [], warnings: [] });
+            return () => { };
+        }
+        let watched = this.watched.get(file);
+        if (!watched) {
+            watched = new WatchedFile(file, source.trim().startsWith('uploads/') ? 'An upload: save it on the robot' : null);
+            this.watched.set(file, watched);
+        }
+        const shared = watched;
+        const models = new ModelsWatch(shared, libraries, this.uploadsDir, watcher.onModels);
+        // Its includes may have changed with it
+        const own = {
+            onFile: (state) => {
+                watcher.onFile(state);
+                void models.check();
+            },
+            onModels: watcher.onModels,
+        };
+        shared.add(own);
+        void models.check();
+        return () => {
+            models.close();
+            if (!shared.remove(own)) {
+                this.watched.delete(file);
+            }
+        };
+    }
+    // Saves the file: over a behavior tree, unless it changed since base (null:
+    // whatever it is), or a new one (create)
+    async save(source, text, base, create) {
+        if (source.trim().startsWith('uploads/')) {
+            throw new Error('Uploads are not saved: save it on the robot');
+        }
+        const file = resolveTreeFile(source, this.uploadsDir);
+        if (Buffer.byteLength(text) > MAX_FILE_BYTES) {
+            throw new Error(`Larger than ${MAX_FILE_BYTES / 1024 / 1024} MB`);
+        }
+        const root = parseXmlSource(text);
+        if (root.name !== 'root') {
+            throw new Error(`Not a behavior tree: its root element is <${root.name}>, not <root>`);
+        }
+        if (create) {
+            await fs.mkdir(path.dirname(file), { recursive: true });
+            await fs.writeFile(file, text, { flag: 'wx' }).catch((e) => {
+                throw new Error(e.code === 'EEXIST' ? `${file} exists already` : errorMessage(e));
+            });
+        }
+        else {
+            const real = await fs.realpath(file).catch(() => {
+                throw new Error(`No file ${file}`);
+            });
+            const current = await readText(real);
+            if (!isBehaviorTreeXml(current)) {
+                throw new Error(`${file} is not a behavior tree (its root element is not <root>): not overwritten`);
+            }
+            if (base !== null && contentVersion(current) !== base) {
+                return { version: contentVersion(current), conflict: true };
+            }
+            await replaceFile(real, text);
+        }
+        this.logger.info(`Behavior tree saved: ${file}`);
+        await this.watched.get(file)?.refresh();
+        return { version: contentVersion(text), conflict: false };
+    }
+    stopAll() {
+        for (const watched of this.watched.values()) {
+            watched.stop();
+        }
+        this.watched.clear();
+    }
+}

package/dist/server/behavior_tree_log.d.ts

@@ -0,0 +1,10 @@
+export interface LogTransition {
+    uid: number | null;
+    name: string;
+    from: string;
+    to: string;
+    time: number;
+}
+export declare function logTransitions(raw: unknown): LogTransition[];
+export declare function decodeLog(data: Uint8Array, uids: boolean): LogTransition[];
+export declare function logLayout(messages: Iterable<Uint8Array>): boolean | null;

package/dist/server/behavior_tree_log.js

@@ -0,0 +1,132 @@
+// The messages of a behavior tree's log (nav2_msgs/msg/BehaviorTreeLog): as
+// rclnodejs gives them, live, and as rosbags keep them, CDR serialized. Their
+// transitions in either case.
+//
+//   builtin_interfaces/Time timestamp
+//   BehaviorTreeStatusChange[] event_log
+//     builtin_interfaces/Time timestamp
+//     string node_name
+//     uint16 uid               (since Jazzy)
+//     string previous_status
+//     string current_status
+const STATUSES = new Set(['IDLE', 'RUNNING', 'SUCCESS', 'FAILURE', 'SKIPPED']);
+const toMs = (time) => (time?.sec ? time.sec * 1000 + (time.nanosec ?? 0) / 1e6 : 0);
+// A message's transitions, as rclnodejs gives it; throws if it is not a log
+export function logTransitions(raw) {
+    const log = raw;
+    if (!Array.isArray(log?.event_log)) {
+        throw new Error('not a log of transitions (nav2_msgs/msg/BehaviorTreeLog)');
+    }
+    const sent = toMs(log.timestamp) || Date.now();
+    return log.event_log.map((event) => ({
+        uid: typeof event.uid === 'number' && event.uid > 0 ? event.uid : null,
+        name: String(event.node_name ?? ''),
+        from: String(event.previous_status ?? '').toUpperCase(),
+        to: String(event.current_status ?? '').toUpperCase(),
+        time: toMs(event.timestamp) || sent,
+    }));
+}
+const utf8 = new TextDecoder();
+// Reads CDR (XCDR 1 or 2, of final types: the same here) after its 4 byte
+// encapsulation header, which says its endianness; aligned from after it
+class CdrReader {
+    offset = 4;
+    view;
+    little;
+    constructor(data) {
+        if (data.length < 4) {
+            throw new Error('Truncated message');
+        }
+        this.view = new DataView(data.buffer, data.byteOffset, data.byteLength);
+        this.little = (data[1] & 1) === 1;
+    }
+    take(size) {
+        this.offset += (size - ((this.offset - 4) % size)) % size;
+        const at = this.offset;
+        if (at + size > this.view.byteLength) {
+            throw new Error('Truncated message');
+        }
+        this.offset += size;
+        return at;
+    }
+    int32() {
+        return this.view.getInt32(this.take(4), this.little);
+    }
+    uint32() {
+        return this.view.getUint32(this.take(4), this.little);
+    }
+    uint16() {
+        return this.view.getUint16(this.take(2), this.little);
+    }
+    // Its length counts the terminating null
+    string() {
+        const length = this.uint32();
+        if (length === 0) {
+            return '';
+        }
+        if (this.offset + length > this.view.byteLength) {
+            throw new Error('Truncated message');
+        }
+        const text = utf8.decode(new Uint8Array(this.view.buffer, this.view.byteOffset + this.offset, length - 1));
+        this.offset += length;
+        return text;
+    }
+    time() {
+        const sec = this.int32();
+        return sec * 1000 + this.uint32() / 1e6;
+    }
+}
+// A serialized log's transitions, with UIDs (Jazzy's) or without; throws if
+// it is not a log of that layout
+export function decodeLog(data, uids) {
+    const reader = new CdrReader(data);
+    const sent = reader.time();
+    const count = reader.uint32();
+    const transitions = [];
+    for (let i = 0; i < count; i++) {
+        const time = reader.time();
+        const name = reader.string();
+        const uid = uids ? reader.uint16() : 0;
+        const from = reader.string();
+        const to = reader.string();
+        if (!STATUSES.has(from) || !STATUSES.has(to)) {
+            throw new Error(`not a log of transitions: statuses “${from}”, “${to}”`);
+        }
+        transitions.push({ uid: uid > 0 ? uid : null, name, from, to, time: time || sent });
+    }
+    return transitions;
+}
+// How many messages tell the layout
+const LAYOUT_SAMPLES = 200;
+// Whether the serialized logs have UIDs, from their first transitions; null
+// if neither layout reads them. Either may read the other's, the UIDs in the
+// strings' padding: with UIDs, those of a log without them read 0, which
+// BT.CPP never numbers.
+export function logLayout(messages) {
+    const samples = [];
+    for (const data of messages) {
+        if (samples.length === LAYOUT_SAMPLES) {
+            break;
+        }
+        // Not empty: an empty log reads either way
+        if (data.length > 16) {
+            samples.push(data);
+        }
+    }
+    const read = (uids) => {
+        const transitions = [];
+        try {
+            for (const data of samples) {
+                transitions.push(...decodeLog(data, uids));
+            }
+        }
+        catch {
+            return null;
+        }
+        return transitions;
+    };
+    if (read(true)?.some((transition) => transition.uid !== null)) {
+        return true;
+    }
+    return read(false)?.length ? false : null;
+}

package/dist/server/behavior_tree_playback.d.ts

@@ -0,0 +1,57 @@
+import { type BehaviorTreePlaybackState } from '../shared/protocol.ts';
+import { type LogTransition } from './behavior_tree_log.ts';
+import type { BehaviorTreeWatcher } from './behavior_trees.ts';
+import { type Logger } from './util.ts';
+export type PlaybackState = Omit<BehaviorTreePlaybackState, 'type' | 'id'>;
+export type PlaybackWatcher = Omit<BehaviorTreeWatcher, 'onRecording'> & {
+    onPlayback: (state: PlaybackState) => void;
+};
+export interface PlaybackOptions {
+    bag: string;
+    topic: string;
+    tree: string;
+    uploadsDir: string;
+    logger: Logger;
+}
+interface Timed {
+    time: number;
+    transitions: LogTransition[];
+}
+export declare function readLog(bag: string, topic: string): Promise<{
+    topic: string;
+    messages: Timed[];
+}>;
+export declare class BehaviorTreePlayback {
+    private readonly watcher;
+    private nodes;
+    private messages;
+    private state;
+    private next;
+    private topic;
+    private start;
+    private end;
+    private time;
+    private playing;
+    private speed;
+    private error;
+    private timer;
+    private lastTick;
+    private lastFlush;
+    private lastState;
+    private closed;
+    constructor(options: PlaybackOptions, watcher: PlaybackWatcher);
+    control({ playing, speed, time }: {
+        playing?: boolean;
+        speed?: number;
+        time?: number;
+    }): void;
+    close(): void;
+    private open;
+    private tick;
+    private advance;
+    private seek;
+    private flush;
+    private sendState;
+    private stopTimer;
+}
+export {};