Rclnodejs web capability runtime over WebSocket (#1509)

Opt-in **Web Runtime** that lets browser code talk to ROS 2 via an explicit, allow-listed set of capabilities exposed by a host Node.js process. JSON over WebSocket; transport-agnostic dispatcher so HTTP/etc. can plug in later. Reachable only through the new `rclnodejs/web/server` subpath export — no existing behavior changes.

```js
const { createRuntime, WebSocketTransport } = require('rclnodejs/web/server');
const runtime = createRuntime({
  node, transports: [new WebSocketTransport({ port: 9000 })],
});
runtime.expose({ call: ['/add_two_ints'], publish: ['/chatter'], subscribe: ['/chatter'] });
await runtime.start();
```

## Files

| Area | Path |
|---|---|
| Registry / Dispatcher / Transport / WS / Façade / Types | `lib/runtime/{registry,dispatcher,transport,index}.js`, `lib/runtime/transports/ws.js`, `lib/runtime/index.d.ts` |
| Subpath exports (`./web/server`, `./rosocket`, `./lib/*`) | `package.json` |
| Shared `reviveBigInts` (null-proto, prototype-pollution safe) | `lib/message_serialization.js`, `rosocket/index.js` |
| Tests (+19 cases) | `test/test-runtime.js`, `test/test-serialization-modes.js` |

## CI workaround

`test/electron/run_test.js` skips the Electron smoke test on Node ≥ 26. Upstream `extract-zip@2.0.1` (unmaintained, used by `electron`'s postinstall) silently aborts on Node ≥ 26.1. Native addon coverage is already provided by the mocha suite that runs first; drop the gate when upstream is fixed.


Fix: #1510

Author: minggangw

lib/message_serialization.js

@@ -168,6 +168,40 @@ function isValidSerializationMode(mode) {
   return ['default', 'plain', 'json'].includes(mode);
 }
 
+/**
+ * Inverse of {@link toJSONSafe} for 64-bit integer fields.
+ *
+ * `toJSONSafe` encodes `bigint` as the string `"<n>n"` so values survive
+ * `JSON.stringify`. `reviveBigInts` walks an arbitrary JSON value and
+ * converts any such string back into a real `bigint`. Everything else
+ * passes through unchanged. Used by the rosocket bridge and the Web
+ * Runtime dispatcher to rehydrate inbound JSON before handing it to
+ * rclnodejs.
+ *
+ * Returned objects use a null prototype and skip the well-known
+ * prototype-pollution keys (`__proto__`, `constructor`, `prototype`)
+ * because the input is attacker-controllable JSON arriving from a
+ * remote peer.
+ *
+ * @param {*} value
+ * @returns {*}
+ */
+function reviveBigInts(value) {
+  if (value === null || typeof value !== 'object') {
+    if (typeof value === 'string' && /^-?\d+n$/.test(value)) {
+      return BigInt(value.slice(0, -1));
+    }
+    return value;
+  }
+  if (Array.isArray(value)) return value.map(reviveBigInts);
+  const out = Object.create(null);
+  for (const k of Object.keys(value)) {
+    if (k === '__proto__' || k === 'constructor' || k === 'prototype') continue;
+    out[k] = reviveBigInts(value[k]);
+  }
+  return out;
+}
+
 module.exports = {
   isTypedArray,
   needsJSONConversion,
@@ -176,4 +210,5 @@ module.exports = {
   toJSONString,
   applySerializationMode,
   isValidSerializationMode,
+  reviveBigInts,
 };

lib/runtime/capability_registry.js

@@ -0,0 +1,136 @@
+// Copyright (c) 2026 RobotWebTools Contributors. All rights reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+
+'use strict';
+
+/**
+ * Declarative allow-list of ROS 2 capabilities exposed to the Web Runtime.
+ *
+ * The registry is the single source of truth for "what may a connected client
+ * do?" — every dispatched frame is checked against it. Capabilities not listed
+ * here are rejected at the runtime layer before any rclnodejs Node API is
+ * touched.
+ *
+ * Each capability is a tuple `(kind, name, type)` where:
+ *   - `kind` is one of `'call' | 'publish' | 'subscribe'`
+ *   - `name` is the ROS 2 service or topic name (e.g. `'/cmd_vel'`)
+ *   - `type` is the ROS 2 interface name (e.g. `'std_msgs/msg/String'`)
+ */
+class CapabilityRegistry {
+  constructor() {
+    // Per-kind allow-lists. Each map is keyed by ROS name and stores the
+    // resolved interface type, e.g. `_call.get('/add_two_ints')` returns
+    // `'example_interfaces/srv/AddTwoInts'`. Looked up at dispatch time
+    // by Dispatcher.resolve(kind, name).
+    this._call = new Map(); //      ROS service name -> srv type
+    this._publish = new Map(); //   ROS topic name   -> msg type
+    this._subscribe = new Map(); // ROS topic name   -> msg type
+  }
+
+  /**
+   * Register one or more capabilities.
+   *
+   * @example Shorthand (string value = type name)
+   *   registry.expose({
+   *     call:      { '/add':    'example_interfaces/srv/AddTwoInts' },
+   *     publish:   { '/chatter':'std_msgs/msg/String' },
+   *     subscribe: { '/scan':   'sensor_msgs/msg/LaserScan' },
+   *   });
+   *
+   * @example Rich form (object value with metadata)
+   *   registry.expose({
+   *     subscribe: {
+   *       '/scan': { type: 'sensor_msgs/msg/LaserScan' /* future: qos, keep_last, ... *\/ },
+   *     },
+   *   });
+   *
+   * The rich form is accepted today but the runtime only consumes
+   * `type`; additional fields are reserved for forward-compatibility
+   * (e.g. future QoS metadata). Snapshots via {@link list} always
+   * return the canonical `{ name: typeName }` form regardless of
+   * which form was used here.
+   *
+   * @param {{
+   *   call?:      Object<string, string | {type:string}>,
+   *   publish?:   Object<string, string | {type:string}>,
+   *   subscribe?: Object<string, string | {type:string}>,
+   * }} spec
+   * @returns {CapabilityRegistry} this (chainable)
+   */
+  expose(spec = {}) {
+    for (const [name, value] of Object.entries(spec.call || {})) {
+      this._call.set(name, _typeOf(value, 'call', name));
+    }
+    for (const [name, value] of Object.entries(spec.publish || {})) {
+      this._publish.set(name, _typeOf(value, 'publish', name));
+    }
+    for (const [name, value] of Object.entries(spec.subscribe || {})) {
+      this._subscribe.set(name, _typeOf(value, 'subscribe', name));
+    }
+    return this;
+  }
+
+  /**
+   * Resolve a capability lookup.
+   * @param {'call'|'publish'|'subscribe'} kind
+   * @param {string} name
+   * @returns {{kind:string, name:string, type:string}|null}
+   */
+  resolve(kind, name) {
+    const map = this._mapFor(kind);
+    if (!map) return null;
+    const type = map.get(name);
+    return type ? { kind, name, type } : null;
+  }
+
+  /**
+   * Snapshot the registered capabilities as a plain object.
+   *
+   * Always returns the canonical shorthand form
+   * (`{ [name]: typeName }`) regardless of how `expose()` was called.
+   * Useful for introspection and future OpenAPI export.
+   */
+  list() {
+    return {
+      call: Object.fromEntries(this._call),
+      publish: Object.fromEntries(this._publish),
+      subscribe: Object.fromEntries(this._subscribe),
+    };
+  }
+
+  _mapFor(kind) {
+    if (kind === 'call') return this._call;
+    if (kind === 'publish') return this._publish;
+    if (kind === 'subscribe') return this._subscribe;
+    return null;
+  }
+}
+
+function _typeOf(value, kind, name) {
+  if (typeof value === 'string') {
+    if (!value) {
+      throw new TypeError(
+        `expose.${kind}["${name}"] is an empty string; expected a ROS type name`
+      );
+    }
+    return value;
+  }
+  if (value && typeof value === 'object' && typeof value.type === 'string') {
+    if (!value.type) {
+      throw new TypeError(
+        `expose.${kind}["${name}"].type is empty; expected a ROS type name`
+      );
+    }
+    return value.type;
+  }
+  throw new TypeError(
+    `expose.${kind}["${name}"]: expected a string or { type: string }`
+  );
+}
+
+module.exports = { CapabilityRegistry };

lib/runtime/connection.js

@@ -0,0 +1,68 @@
+// Copyright (c) 2026 RobotWebTools Contributors. All rights reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+
+'use strict';
+
+const EventEmitter = require('events');
+
+/**
+ * @typedef {Object} CapabilityFrame
+ * @property {string|number} [id]      - Caller-assigned request id (echoed in reply).
+ * @property {'call'|'publish'|'subscribe'|'unsubscribe'|'action'} [kind] - Request kind (C→S only). `'action'` is reserved and currently returns `code: 'not_implemented'`.
+ * @property {string} [capability]     - Capability name, e.g. `/cmd_vel`.
+ * @property {*}     [payload]         - Message payload (call request, publish msg, sub event).
+ * @property {string|number} [subId]   - For unsubscribe: id of the original subscribe.
+ * @property {boolean} [ok]            - Reply success flag (S→C only).
+ * @property {string} [event]          - `'message'` for streamed subscription deliveries.
+ * @property {string} [error]          - Human-readable error message on failure.
+ * @property {string} [code]           - Stable machine-readable error code.
+ */
+
+/**
+ * Per-connection abstraction handed to the runtime by a transport adapter.
+ *
+ * The transport owns the wire (WebSocket today; other adapters may follow)
+ * and exposes each connection as a `Connection` so the runtime can stay
+ * transport-agnostic. Concrete adapters subclass `Connection` and call
+ * `this.emit('message', frame)` / `this.emit('close')` as frames arrive on
+ * the wire, and implement `send(frame)` / `close(code, reason)` to push
+ * frames back out.
+ *
+ * @experimental — the base class shape may grow (e.g. backpressure hooks)
+ * and is not part of the SemVer-stable surface for third-party adapter
+ * authors. The first-party `WebSocketTransport` is stable and recommended
+ * for production use.
+ *
+ * @event Connection#message
+ * @type {CapabilityFrame}
+ *
+ * @event Connection#close
+ */
+class Connection extends EventEmitter {
+  /**
+   * Push a frame to the remote peer. Implementations should silently drop
+   * sends on a closed connection rather than throwing.
+   * @param {CapabilityFrame} frame
+   */
+  // eslint-disable-next-line no-unused-vars
+  send(frame) {
+    throw new Error('Connection.send() must be implemented by the transport');
+  }
+
+  /**
+   * Close the connection.
+   * @param {number} [code]
+   * @param {string} [reason]
+   */
+  // eslint-disable-next-line no-unused-vars
+  close(code, reason) {
+    throw new Error('Connection.close() must be implemented by the transport');
+  }
+}
+
+module.exports = { Connection };