tassello 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -28,6 +28,44 @@ change the plugin API (`tassello/sdk`, `tassello/server`, `tassello/vite`), as n
   *_server`). The server follows the log for every page and keeps its latest 10,000 messages.
 - Plugins: `connection.subscribeRosout`, and the `LogsIcon`, `NodesIcon`, `SearchIcon`,
   `BanIcon`, `FilterIcon`, `DownloadIcon` and `ArrowDownToLineIcon` icons.
+- Diagnostics widget: the robot's diagnostics (`diagnostic_msgs/msg/DiagnosticArray`), from every
+  node's `diagnostic_updater` (`/diagnostics`, by node) or the aggregator's tree
+  (`/diagnostics_agg`): each status's level, message, hardware ID and values, the groups with the
+  worst under them, as a tree, as a list or as the latest changes of level, filtered by level and
+  text. A widget can be for some statuses only (`Sensors, motor_*`). The server follows the
+  diagnostics for every page, marks stale the statuses no longer received, and keeps their changes
+  of level.
+- Plugins: `connection.subscribeDiagnostics`, and the `DiagnosticsIcon` and `UnfoldIcon` icons.
+- File Manager widget: the robot's files, in the behavior tree editor's look. Folders listed with
+  their entries' sizes and times, unfolded in place, sorted and filtered; places (home, the ROS
+  workspaces sourced, bookmarks) and the disks with their free space; an entry's details, its
+  permissions changed there; an overview of the disks and of what takes a folder's space (its
+  largest entries, its files by type, the largest and latest files). Entries made, renamed in
+  place, cut, copied and pasted, moved or copied by dragging them onto folders, deleted,
+  downloaded (folders as `.tar.gz`), uploaded by dropping files and folders onto the widget, with
+  their progress; names taken are asked about. Text files are edited in tabs, as gedit does: line
+  numbers, syntax highlighting (YAML, XML, Python, C++, CMake, JSON, shell, INI, Markdown, ROS
+  interfaces), search and replace, indentation, line ends kept, undo and redo, never saved over
+  changes made on the robot since they were read. Images are shown, PGM maps too. A widget can
+  stay in its folder, or be read-only. The server polls the folders and files shown.
+- Plugins: `fsApi` and `ApiError`, the `Fs*` types, and the `FolderIcon`, `FolderPlusIcon`,
+  `FileIcon`, `FileTextIcon`, `FilePlusIcon`, `UploadIcon`, `ArrowUpIcon`, `ArrowLeftIcon`,
+  `HomeIcon`, `HardDriveIcon`, `BookmarkIcon`, `SidebarIcon`, `PieChartIcon`, `InfoIcon`,
+  `WrapIcon`, `LinkIcon`, `LockIcon` and `ArchiveIcon` icons.
+- REST errors of the API reject with an `ApiError`, which has the HTTP status.
+- Terminal widget: a shell on the robot (the login shell of the server's user), or a command, in
+  a full terminal (xterm.js): colours, full screen programs and their mouse, copy and paste. It
+  outlives the page: reloaded, reconnected or shown again, it is as it was, full screen programs
+  included; hung up an hour after no page shows it. On touch screens, Termux's extra keys (Esc,
+  Tab, Ctrl, Alt, Home, End, the arrows, Page Up and Down): sticky modifiers that also apply to the
+  on-screen keyboard, keys swiped up for another character, a layout of one's own; the terminal
+  fills the screen above the on-screen keyboard while typing; one finger scrolls, two pinch the
+  text's size. Needs Python 3 (ROS 2's), no native module. Terminals open from the dashboard's own
+  pages only.
+- Plugins: `connection.subscribeTerminal`, `terminalInput`, `resizeTerminal`, `ackTerminal`,
+  `restartTerminal`, the `TerminalOutput` and `TerminalExit` types, and the `ShellIcon`,
+  `KeyboardIcon`, `MaximizeIcon`, `MinimizeIcon`, `ClipboardIcon`, `TextSmallerIcon` and
+  `TextLargerIcon` icons.
 
 ## 0.1.0
 

package/README.md

@@ -1,8 +1,8 @@
 # Tassello
 
 **A web dashboard for ROS 2 robots.** Drive the robot, send it navigation goals, see it move in 3D,
-watch its cameras, run commands on it and manage its services from any browser on the network,
-phones included. Arrange it all in the browser, as panels of widgets, and extend it with plugins.
+watch its cameras, run commands on it, open a terminal on it and manage its services from any
+browser on the network, phones included. Arrange it all in the browser, as panels of widgets, and extend it with plugins.
 
 *Tassello* is Italian for a mosaic tile, and for a wall plug: the dashboard is a mosaic of widgets,
 and plugins add more.
@@ -11,7 +11,7 @@ and plugins add more.
 - **Every device**: a desktop canvas, and layouts of their own for tablets and phones.
 - **Built in**: teleop pads, a Nav2 map with goals, the robot's URDF in 3D, an arm jogger, cameras,
   images, command buttons, a systemd application manager, a behavior tree inspector and
-  editor, and the ROS log of every node.
+  editor, the ROS log of every node, the robot's diagnostics, a file manager and a terminal.
 - **Plugins**: widgets of your own, with server-side code if they need it, as npm or ROS packages.
 - **One process**: a ROS 2 node in Node.js. Nothing to install on the robot but Node.js.
 
@@ -21,7 +21,8 @@ Tassello runs on the robot (or any machine on its ROS network) and needs:
 
 - ROS 2: Humble, Jazzy, Kilted or Lyrical, on x64 or arm64 (e.g. a Raspberry Pi), for which
   [rclnodejs](https://github.com/RobotWebTools/rclnodejs) ships prebuilt binaries;
-- Node.js 22 or newer, and npm.
+- Node.js 22 or newer, and npm;
+- Python 3, which ROS 2 comes with: the Terminal widget's pseudo-terminals.
 
 ```bash
 npm install -g tassello
@@ -117,6 +118,9 @@ after the others on the devices already arranged.
 | **Behavior Tree Inspector** | What a BT.CPP behavior tree is doing, from its log (Nav2's `/behavior_tree_log`): the tree of its XML file with the running branch lit, each node's status, last result, counts and ports, and the latest transitions. As a graph (pan, zoom, follow the running nodes) or a list. Records the log into rosbags, and plays rosbags back at any speed |
 | **Behavior Tree Editor** | Edits a BT.CPP behavior tree's XML file of the robot as a graph: nodes from a palette (BT.CPP's, Nav2's, your libraries'), dragged where they go, moved with their children, their names and ports edited in a side panel. Subtrees, undo and redo, copy and paste, an XML view. Saves only what changed, never over changes made meanwhile |
 | **Logs** | The ROS log (`/rosout`), as rqt_console and swri_console show it: every node's messages coloured by level, the nodes running and those that logged with their counts, filtered by node, by level and by text (terms or a regular expression, to show or to hide). Pause, follow the newest, clear, download, and a message's details: where it was logged |
+| **Diagnostics** | The robot's diagnostics (`/diagnostics`, or the aggregator's `/diagnostics_agg`), as rqt_robot_monitor shows them: each status's level, the groups with the worst under them, those with problems unfolded. As a tree, as a list (the worst first) or as the latest changes of level, filtered by level and by text; a widget can be for some statuses only. A status's details: its message, hardware ID, values and latest changes. Pause, download, and forget the statuses no longer published |
+| **File Manager** | The robot's files: folders unfolded in place, places (home, the ROS workspaces, bookmarks) and the disks' free space, an entry's details and permissions, what takes a folder's space. Make, rename, cut, copy, paste, drag onto folders, delete, download (folders as `.tar.gz`) and upload (drop files and folders onto it). Text files edited in tabs as gedit does: highlighting, search and replace, undo; images and PGM maps shown |
+| **Terminal** | A shell on the robot, or a command (`htop`, `tmux attach`), in a full terminal: colours, full screen programs, the mouse. It outlives the page: reloaded, reconnected or shown again, it is as it was. On touch screens, the keys phones lack, as Termux has them: Esc, Tab, Ctrl, Alt, Home, End, the arrows, Page Up and Down, and while typing the terminal fills the screen above the on-screen keyboard |
 
 Their properties (topics, frames, speeds, colours, ...) are edited in the side panel of edit mode.
 
@@ -209,6 +213,89 @@ Notes on some of them:
   log for every page, keeping its latest 10,000 messages, and for 10 minutes after the last page
   closes: a page opened later sees what was logged meanwhile, and when first opened, what each
   node logged in its last 10 seconds (rosout's own history).
+- **Diagnostics** follows a `diagnostic_msgs/msg/DiagnosticArray` topic: `/diagnostics`, on which
+  every node's `diagnostic_updater` publishes its statuses (named `node: task`, grouped by node),
+  or `/diagnostics_agg`, the aggregator's tree of them (`/Robot/Sensors/Lidar`). A group shows the
+  worst level under it; one the aggregator puts in error only because some statuses under it are
+  stale shows as stale. A status not received for 5 s, or for 3 of its periods if it is slower, is
+  stale: what published it stopped. The level buttons show and hide each level (Shift+click: that
+  level only), counting the statuses, not the groups that sum them up; *Filter* keeps the statuses
+  whose name, message or hardware ID contain any of its terms, separated by `;`, or match a
+  regular expression, and a group's with all those under it. The groups with problems unfold, and
+  stay unfolded once these are gone, until folded; the arrow keys go through the tree and fold
+  and unfold it. A status clicked shows its message, hardware ID, values and latest changes of
+  level. Pausing holds the statuses as they are; *Forget* hides those no longer published, until
+  they are again; *Download* saves the statuses shown, the worst first, with their values (or the
+  changes shown). The widget's properties set its statuses (names, paths or globs, e.g.
+  `Sensors, motor_*`: from the root if they start with `/`, else at any depth), and the levels,
+  filter and view it opens with. The server follows the diagnostics for every page, and for 10
+  minutes after the last page closes, keeping the latest status of each name and their latest
+  1,000 changes of level.
+- **File Manager** opens its *folder* (`~` by default; `/…`, `~/…`, `package://…`) and lists it
+  with its entries' sizes and times, sorted by name (naturally: `run_2` before `run_10`), size or
+  time, folders first; the chevrons unfold folders in place. Its places are home, the root, the
+  ROS installations and workspaces sourced (`AMENT_PREFIX_PATH`), its *bookmarks* (the widget's,
+  and those made in the page, kept by the browser) and the disks, with their free space. Click to
+  select (Ctrl, Shift: several), double click (on touch screens tap) to open: folders, text files
+  into the editor, images (PNG, JPEG, SVG…, and PGM maps, converted on the robot) into a viewer.
+  Right click, or the ⋯ of a row, for the rest: download (a folder, or several entries, as one
+  `.tar.gz`), cut, copy and paste (between file managers too), duplicate, move or copy to a folder
+  picked, rename (F2, in place), copy the path, details, delete (there is no trash: it asks
+  first). Drag entries onto a folder, a place or the address bar's folders to move them (Ctrl:
+  copy them); drop files or folders from the computer to upload them, with their progress. Where
+  names are taken, it asks: replace, keep both (`map (2).yaml`) or skip. *Details* show an entry's
+  kind, size (a folder's computed on demand), times, owner, mode, link and disk, an image's
+  preview, and change its permissions; *what takes the space* shows the disks (size, use, free
+  space, inodes when short) and analyzes the folder: its largest entries, its files by type, the
+  largest and the latest files under it, on its disk only, for 15 s at most. Keys: the arrows
+  (Left and Right fold), Enter, Backspace, Alt+arrows (up, back, forward), Delete, F2, Ctrl+A,
+  Ctrl+C, Ctrl+X, Ctrl+V, Ctrl+F (filter), Ctrl+L (type a path), Ctrl+H (hidden files), and typing
+  a name's first letters.
+
+  Text files (UTF-8, 5 MB at most) open in tabs, edited as with gedit: line numbers, the line of
+  the cursor lit, syntax highlighting (YAML, XML for URDF, xacro, launch and SDF, Python, C and
+  C++, CMake, JSON, shell, INI, TOML and systemd units, Markdown, ROS interfaces), search and
+  replace (case, whole words, regular expressions with `$1`), Tab and Shift+Tab indenting the lines
+  selected, new lines indented as the one before, Ctrl+/ commenting lines out, go to line (Ctrl+I),
+  undo and redo a word at a time, long lines wrapped on demand (then not highlighted). The status
+  line shows the cursor's line and column, and switches the highlighting, the indentation and the
+  line ends (kept as the file has them, LF or CRLF). As the behavior tree editor, it saves only
+  over the version read: a file changed on the robot is shown at once without changes in the
+  editor, with changes the editor asks which to keep, and a save over a file changed since it was
+  read is refused. *Save as* writes elsewhere, e.g. a file the server's user cannot write. Changes
+  are kept while the page is open, and the page asks before closing with changes not saved.
+
+  The folders shown and the files open are read again every 3 s. A widget can *stay in its
+  folder* (e.g. one for the maps, or the rosbags) or be *read-only*: these are the page's choices,
+  not a protection (see Security).
+- **Terminal** runs the login shell of the server's user (`$SHELL -l`, as SSH does: its
+  `~/.bashrc` and the ROS setup Tassello was started with), or the widget's *command* through it,
+  in its *folder* (`~` by default; `/…`, `~/…`, `package://…`), on a pseudo-terminal of its own:
+  `TERM=xterm-256color`, true colour, full screen programs (vim, htop, less) and their mouse. A
+  terminal belongs to the browser's tab: reloading the page, losing the connection or showing
+  another panel and coming back finds it as it was, what it printed meanwhile included, screens of
+  full screen programs too. A terminal no page shows is hung up after an hour (its programs get
+  SIGHUP, as when a terminal window is closed), as is the one unseen the longest when 16 are open:
+  for jobs that should outlive it, `tmux` or `nohup`. A *command* such as `tmux new -A -s robot` gives every page, and every
+  device, the same session. When the program ends, Enter or *Restart* starts it again; *Restart*
+  also hangs up a program that hangs. Changing the widget's command or folder starts it anew.
+
+  Copy with Ctrl+C while text is selected (it interrupts otherwise) or Ctrl+Shift+C, paste with
+  Ctrl+Shift+V or the toolbar's button (pages served over http cannot read the clipboard: it opens
+  a box to paste into, on phones too). The toolbar changes the size of the text for this device, as
+  pinching does, and fills the window with the terminal.
+
+  On touch screens (or always, or never: *Extra keys*) the keys phones lack are under the
+  terminal, as Termux has them: Esc, `/`, `-`, Home, ↑, End, Page Up, then Tab, Ctrl, Alt, ←, ↓,
+  →, Page Down. Tapped, they type without closing the on-screen keyboard. Ctrl, Alt and Shift
+  apply to the next key, of the row or of the keyboard (Ctrl, then `c`: interrupt); tapped twice,
+  or held, they stay until tapped again. Swiping up on a key, or holding it, types what its corner
+  shows (`\`, `|`, `~`); the arrows repeat while held. Their *layout* is a property: a line per
+  row, keys by name (`ESC TAB CTRL ALT SHIFT HOME END PGUP PGDN UP DOWN LEFT RIGHT INS DEL BKSP
+  ENTER SPACE F1`…`F12 KEYBOARD PASTE`) or what they type (`~`, `|`, `ros2`), what swiping up
+  types after a colon (`-:|`). While the on-screen keyboard is open, the terminal fills the screen
+  above it, the keys right above the keyboard (*Full screen while typing*). One finger scrolls (the
+  scrollback, or the program: less, htop), flung or not; two pinch the text's size.
 
 ## Plugins
 
@@ -236,10 +323,14 @@ and ship example panels. See **[docs/plugins.md](docs/plugins.md)**.
 ## Security
 
 Tassello has no login. **Anyone who can open the page can drive the robot, run any command as
-the server's user, read its images, behavior trees and the behavior tree logs of its rosbags,
-record rosbags into new folders, and write behavior tree files (XML files whose root is
-`<root>`, over others of the same kind only)**: keep it on a network you trust, or behind a reverse proxy
-with authentication (it serves everything under `/`, its WebSocket at `/ws`).
+the server's user (the Terminal, a shell), and read, write, upload, move and delete any of the
+files that user can (the File Manager)**: keep it on a network you trust, or behind a reverse proxy
+with authentication (it serves everything under `/`, its WebSocket at `/ws`). Changes to the files
+are accepted from the dashboard's own pages only (they send a header that another site's page
+cannot), and the root, the home folder and the system's top folders (`/usr`, `/etc`…) are never
+deleted nor moved. Terminals open from the dashboard's own pages only too: those whose origin is
+the host they reached (the `Host` header, or the `X-Forwarded-Host` a reverse proxy sets), which
+another site's page cannot pretend.
 
 ## How it works
 
@@ -250,6 +341,7 @@ with authentication (it serves everything under `/`, its WebSocket at `/ws`).
                                                                         ├─ rclnodejs: ROS
                                                                         ├─ sharp: raw images to JPEG, maps to PNG
                                                                         ├─ bash: the buttons' commands
+                                                                        ├─ python3: the terminals' pseudo-terminals
                                                                         └─ the plugins' server sides
 ```
 
@@ -270,7 +362,19 @@ Safety and bandwidth are the server's concern:
 - The ROS log is followed once for every page: each gets the new messages at most 10 times a
   second, at most 500 at a time (a node logging faster has some skipped, which the page shows).
   Only the rows in sight are drawn.
+- Diagnostics are followed once for every page: each gets the statuses that changed, at most 4
+  times a second, not those received the same again. Subscribed best effort, they come from
+  every publisher, whatever its QoS.
 - A button runs the command saved in its panel, never one sent by the page.
+- A terminal's pseudo-terminal is opened by a few lines of Python (ROS 2's own), no native module
+  to build. Its output is also played on a terminal of the server's own (xterm.js, headless), which
+  paces the program, never the pages: a page gets at most 256 KB ahead of what it has drawn, and a
+  page further behind (a slow phone, a hidden tab, a flood of output) gets the screen as it is
+  instead of all that led to it. A page that reconnects gets what it missed, from the last 1 MB.
+- The File Manager's folders are read again every 3 s, and answered "unchanged" while they are;
+  the largest are listed in part (5,000 entries), and only the rows in sight are drawn. Uploads
+  and downloads are streamed, folders archived by `tar` as they are sent; saves replace files at
+  once (a temporary file renamed over them).
 
 ## Developing
 

package/dist/server/behavior_tree_files.d.ts

@@ -6,7 +6,6 @@ export interface BehaviorTreeFileWatcher {
     onFile: (file: FileState) => void;
     onModels: (models: ModelsState) => void;
 }
-export declare function contentVersion(text: string): string;
 export declare class BehaviorTreeFiles {
     private readonly uploadsDir;
     private readonly logger;

package/dist/server/behavior_tree_files.js

@@ -3,14 +3,13 @@
 // 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 { createHash, randomBytes } from 'node:crypto';
 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 { errorMessage, packageShareDirectory } from './util.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;
@@ -18,10 +17,6 @@ const MAX_FILE_BYTES = 5 * 1024 * 1024;
 const MAX_INCLUDES = 50;
 // A file of models kept parsed while unchanged; this many
 const MODEL_CACHE = 64;
-// Of a file's content
-export function contentVersion(text) {
-    return createHash('sha256').update(text).digest('hex').slice(0, 16);
-}
 // Size, time and inode of a file, '' if gone
 async function stamp(file) {
     const stat = await fs.stat(file).catch(() => null);
@@ -297,24 +292,6 @@ class ModelsWatch {
         }
     }
 }
-// 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)
-async function writeFile(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);
-}
 export class BehaviorTreeFiles {
     uploadsDir;
     logger;
@@ -390,7 +367,7 @@ export class BehaviorTreeFiles {
             if (base !== null && contentVersion(current) !== base) {
                 return { version: contentVersion(current), conflict: true };
             }
-            await writeFile(real, text);
+            await replaceFile(real, text);
         }
         this.logger.info(`Behavior tree saved: ${file}`);
         await this.watched.get(file)?.refresh();

package/dist/server/diagnostics.d.ts

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

package/dist/server/diagnostics.js

@@ -0,0 +1,200 @@
+// The robot's diagnostics for the diagnostics widgets: the
+// diagnostic_msgs/msg/DiagnosticArray of /diagnostics, which every node's
+// diagnostic_updater publishes, or of /diagnostics_agg, the aggregator's tree.
+//
+// A topic is followed once for every page, like the ROS log (rosout.ts). The
+// server keeps the latest status of each name, marks stale those no longer
+// received, and logs their changes of level (diagnostics_state.ts); its pages
+// get the statuses that changed at most DIAGNOSTICS_RATE times a second.
+// Diagnostics are followed for LINGER_MS after the last page: a page opened
+// later sees what changed meanwhile.
+import rclnodejs from 'rclnodejs';
+import { DIAGNOSTICS_CHANGES, DIAGNOSTICS_RATE } from '../shared/protocol.js';
+import { DiagnosticsState, STALE_AFTER_MS } from './diagnostics_state.js';
+import { absoluteTopic, errorMessage } from './util.js';
+const { HistoryPolicy, ReliabilityPolicy, DurabilityPolicy } = rclnodejs.QoS;
+const ARRAY_TYPE = 'diagnostic_msgs/msg/DiagnosticArray';
+// Arrays queued while the server is busy: every node publishes its own
+const QUEUE_DEPTH = 100;
+// How often the statuses are checked for staleness, and the topic for
+// publishers until it has messages
+const CHECK_PERIOD_MS = 1000;
+const LINGER_MS = 10 * 60_000;
+// A diagnostics topic: its subscription, its statuses, its pages
+class DiagnosticsTopic {
+    watchers = new Set();
+    lingerTimer = null;
+    node;
+    logger;
+    topic;
+    started = Date.now();
+    statuses = new DiagnosticsState(DIAGNOSTICS_CHANGES);
+    subscription = null;
+    checkTimer;
+    state = 'waiting';
+    message = '';
+    // When the latest array came, 0 before the first
+    lastMessage = 0;
+    flushTimer = null;
+    lastFlush = 0;
+    constructor(node, logger, topic) {
+        this.node = node;
+        this.logger = logger;
+        this.topic = topic;
+        this.check();
+        this.checkTimer = setInterval(() => this.check(), CHECK_PERIOD_MS);
+    }
+    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.state, this.message);
+        watcher.onUpdate({ reset: true, started: this.started, ...this.statuses.snapshot() });
+    }
+    remove(watcher) {
+        this.watchers.delete(watcher);
+    }
+    destroy() {
+        clearInterval(this.checkTimer);
+        for (const timer of [this.flushTimer, this.lingerTimer]) {
+            if (timer) {
+                clearTimeout(timer);
+            }
+        }
+        if (this.subscription) {
+            this.node.destroySubscription(this.subscription);
+        }
+    }
+    // Best effort and volatile, which every publisher matches, reliable or not,
+    // latched or not: unlike most topics, /diagnostics has many publishers, and
+    // those that come later may not have the first ones' QoS. A lost array is
+    // followed by another a second later. Whether it could.
+    subscribe() {
+        const qos = new rclnodejs.QoS(HistoryPolicy.RMW_QOS_POLICY_HISTORY_KEEP_LAST, QUEUE_DEPTH, ReliabilityPolicy.RMW_QOS_POLICY_RELIABILITY_BEST_EFFORT, DurabilityPolicy.RMW_QOS_POLICY_DURABILITY_VOLATILE);
+        try {
+            this.subscription = this.node.createSubscription(ARRAY_TYPE, this.topic, { qos }, (raw) => this.onMessage(raw));
+            return true;
+        }
+        catch (e) {
+            this.setState('error', `Cannot subscribe to ${this.topic}: ${errorMessage(e)}`);
+            return false;
+        }
+    }
+    onMessage(raw) {
+        this.lastMessage = Date.now();
+        this.statuses.add(raw, this.lastMessage);
+        this.setState('streaming', this.topic);
+        this.scheduleFlush();
+    }
+    // Marks the stale statuses, and until diagnostics come, subscribes when the
+    // topic is not of another type (which the middleware would refuse), and
+    // says what they wait for
+    check() {
+        const now = Date.now();
+        this.statuses.checkStale(now);
+        this.scheduleFlush();
+        if (this.lastMessage > 0 && now - this.lastMessage <= STALE_AFTER_MS) {
+            return;
+        }
+        let types;
+        try {
+            // Which says what is wrong with it, unlike the lookup
+            rclnodejs.validator.validateFullTopicName(this.topic);
+            const publishers = this.node.getPublishersInfoByTopic(this.topic, false);
+            types = [...new Set(publishers.map((p) => p.topic_type))];
+        }
+        catch (e) {
+            this.setState('error', errorMessage(e));
+            return;
+        }
+        if (types.length > 0 && !types.includes(ARRAY_TYPE)) {
+            this.setState('error', `${this.topic} is a ${types.join(', ')}, not a ${ARRAY_TYPE}`);
+            return;
+        }
+        if (!this.subscription && !this.subscribe()) {
+            return;
+        }
+        if (this.lastMessage > 0) {
+            this.setState('waiting', `No diagnostics on ${this.topic} lately: their statuses went stale`);
+        }
+        else if (types.length === 0) {
+            this.setState('waiting', `Waiting for ${this.topic} to be published`);
+        }
+        else {
+            this.setState('waiting', `Waiting for diagnostics on ${this.topic}`);
+        }
+    }
+    scheduleFlush() {
+        if (this.flushTimer || this.watchers.size === 0) {
+            return;
+        }
+        const wait = Math.max(0, this.lastFlush + 1000 / DIAGNOSTICS_RATE - Date.now());
+        this.flushTimer = setTimeout(() => this.flush(), wait);
+    }
+    flush() {
+        if (this.flushTimer) {
+            clearTimeout(this.flushTimer);
+            this.flushTimer = null;
+        }
+        this.lastFlush = Date.now();
+        // With no page left, what changed waits for the next one, which gets it
+        // with the rest
+        const batch = this.statuses.takeBatch();
+        if (!batch) {
+            return;
+        }
+        const update = { reset: false, started: this.started, ...batch };
+        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 Diagnostics {
+    node;
+    logger;
+    topics = 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 diagnostics = this.topics.get(name);
+        if (!diagnostics) {
+            diagnostics = new DiagnosticsTopic(this.node, this.logger, name);
+            this.topics.set(name, diagnostics);
+        }
+        const shared = diagnostics;
+        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, diagnostics) {
+        diagnostics.destroy();
+        if (this.topics.get(topic) === diagnostics) {
+            this.topics.delete(topic);
+        }
+    }
+}

package/dist/server/diagnostics_state.d.ts

@@ -0,0 +1,23 @@
+import type { DiagnosticChange, DiagnosticEntry } from '../shared/protocol.ts';
+export declare const STALE_AFTER_MS = 5000;
+export declare function levelOf(entry: Pick<DiagnosticEntry, 'level' | 'stale'>): number;
+export interface DiagnosticsBatch {
+    statuses: DiagnosticEntry[];
+    changes: DiagnosticChange[];
+}
+export declare class DiagnosticsState {
+    private readonly capacity;
+    private readonly statuses;
+    private changes;
+    private lastId;
+    private lastSeq;
+    private taken;
+    private readonly dirty;
+    constructor(capacity: number);
+    add(raw: unknown, now: number): void;
+    checkStale(now: number): void;
+    snapshot(): DiagnosticsBatch;
+    takeBatch(): DiagnosticsBatch | null;
+    private addStatus;
+    private change;
+}