ros-mobile-bridge 0.1.2 → 0.1.3

package/CHANGELOG.md

@@ -4,6 +4,18 @@ All notable changes to `ros-mobile-bridge` will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.1.3] - 2026-06-02
+
+### Added
+
+- **`SubscribeOptions.dispatchMode`** controls how throttle-surviving messages reach the callback. `'immediate'` (the default, and the only prior behavior) parses and delivers every surviving message synchronously on the message-handler tick. `'latest-only'` delivers only the newest message under back-pressure: superseded messages are dropped *before* being parsed and delivery is deferred off the message-handler tick, so a high-bandwidth topic like a raw camera stream decodes only the frame you will actually render. The conflation happens upstream of the CDR/JSON decode, which an external wrapper cannot do because it only ever receives already-parsed messages. Available on both Foxglove WS and rosbridge. On a binary (CDR) topic the surviving payload is copied to outlive the deferral, so `'latest-only'` is parse-cheap but not allocation-free; on rosbridge the stashed frame is an immutable string and the stash is copy-free. It composes below the throttle (`maxFrequency` and the adaptive cap decide eligibility, then `'latest-only'` keeps the newest of those). A callback that throws is logged and never wedges the subscription; on unsubscribe, disconnect, or a circuit-breaker trip any pending message is dropped rather than delivered.
+- **`materializeBytes(view: Uint8Array): Uint8Array`** returns an owned, offset-0 copy of a `Uint8Array`. `RosMessage.data`, when it is a `Uint8Array`, is a zero-copy view into the inbound WebSocket frame (v0.1.2); call this before retaining the bytes past the callback or handing them to a native binding that ignores `byteOffset` (some Skia paths, `node-canvas`, `sharp`, FFI). It always copies and never returns the input view, so the result is always safe to retain. This supersedes the v0.1.2 note that anticipated a conditional (skip-when-already-owned) copy: a full-span view can still alias the shared frame buffer, so the conditional form would have skipped the copy in exactly the unsafe case.
+- **`matchesSchema(a: string, b: string): boolean`** compares two ROS schema names tolerant of the ROS 1 / ROS 2 `msg/` (and `srv/`, `action/`) asymmetry, so `sensor_msgs/msg/Image` matches `sensor_msgs/Image`. It is kind-agnostic: it strips the interface-kind segment and compares `pkg` + `Type`. A `normalizeSchema` counterpart is deliberately not exported, because a 2-part name cannot be safely expanded to canonical 3-part form (the interface kind cannot be inferred from the string).
+
+### Changed
+
+- **Bundled service-schema lookup now tolerates the 2-part / 3-part name asymmetry.** A bridge advertising a well-known system service as `rcl_interfaces/ListParameters` (without the `srv/` segment) now resolves to the bundled schema, so parameter operations and goal cancellation work regardless of which form the bridge reports. Bridge-advertised schemas remain authoritative.
+
 ## [0.1.2] - 2026-06-01
 
 ### Performance
@@ -58,5 +70,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 - `ZenohClient` ships as an unimplemented skeleton (every method throws). `ProtocolManager.connect` throws a clear "Zenoh support is planned for v0.2.0" error for `protocol: 'zenoh'`. The class is not exported from `index.ts` in v0.1.0.
 
+[0.1.3]: https://github.com/AuriLabsTech/ros-mobile-bridge/releases/tag/v0.1.3
+[0.1.2]: https://github.com/AuriLabsTech/ros-mobile-bridge/releases/tag/v0.1.2
 [0.1.1]: https://github.com/AuriLabsTech/ros-mobile-bridge/releases/tag/v0.1.1
 [0.1.0]: https://github.com/AuriLabsTech/ros-mobile-bridge/releases/tag/v0.1.0

package/README.md

@@ -98,6 +98,27 @@ const unwatch = client.onBreakerStateChange('/camera/compressed', (state) => {
 
 Manual breaker controls (`breakerRetry`, `breakerDisable`) let consumers expose user-driven recovery in their UI.
 
+### High-throughput subscriptions: `dispatchMode`
+
+`SubscribeOptions.dispatchMode` controls how messages reach your callback when they arrive faster than you can use them. The default, `'immediate'`, parses and delivers every message that survives the throttle, synchronously on the message-handler tick. For a high-bandwidth topic where only the freshest message matters (a raw camera stream feeding a viewport), `'latest-only'` delivers just the newest message and drops the rest *before* they are parsed, so you decode only the frame you actually render:
+
+```typescript
+import { materializeBytes } from 'ros-mobile-bridge';
+
+client.subscribe(
+  '/camera/raw',
+  (msg) => {
+    if (msg.data instanceof Uint8Array) {
+      // msg.data is a zero-copy view; copy it before retaining past the callback.
+      render(materializeBytes(msg.data));
+    }
+  },
+  { dispatchMode: 'latest-only' },
+);
+```
+
+Delivery is deferred off the message-handler tick, and the conflation happens upstream of the decode, which a wrapper around `subscribe` cannot do because it only ever sees already-parsed messages. `'latest-only'` composes below the throttle: `maxFrequency` and the adaptive cap still decide which messages are eligible, then the newest of those is delivered. For lossless-but-deferred delivery, keep your own bounded queue in the callback (the `dispatchMode` TSDoc shows the pattern); the bound and drop policy are yours to set because they depend on the device.
+
 ### Host-app injection
 
 Construct clients with `ProtocolClientOptions` to receive latency callbacks, route logs, and tell the throttle which mode the user picked:

package/dist/index.cjs

@@ -478,6 +478,16 @@ function jsonSchemaToTemplate(schema) {
   return null;
 }
 
+// src/schemaName.ts
+var INTERFACE_KIND = /^([^/]+)\/(?:msg|srv|action)\/([^/]+)$/;
+function stripInterfaceKind(name) {
+  const m = INTERFACE_KIND.exec(name);
+  return m ? `${m[1]}/${m[2]}` : name;
+}
+function matchesSchema(a, b) {
+  return stripInterfaceKind(a) === stripInterfaceKind(b);
+}
+
 // src/builtinSchemas.ts
 var SEP = "\n================================================================================\n";
 var MSG_PARAMETER_VALUE = `MSG: rcl_interfaces/ParameterValue
@@ -581,7 +591,13 @@ var BUNDLED = {
   }
 };
 function getBundledServiceSchema(serviceType) {
-  return BUNDLED[serviceType] ?? null;
+  const exact = BUNDLED[serviceType];
+  if (exact) return exact;
+  const target = stripInterfaceKind(serviceType);
+  for (const key of Object.keys(BUNDLED)) {
+    if (stripInterfaceKind(key) === target) return BUNDLED[key] ?? null;
+  }
+  return null;
 }
 
 // src/FoxgloveClient.ts
@@ -789,6 +805,7 @@ var _FoxgloveClient = class _FoxgloveClient {
   subscribe(topic, onMessage, options) {
     const userMinIntervalMs = options?.maxFrequency && options.maxFrequency > 0 ? 1e3 / options.maxFrequency : void 0;
     const disableAdaptive = options?.disableAdaptive ?? false;
+    const dispatchMode = options?.dispatchMode ?? "immediate";
     const existingSubId = this.topicToSubscriptionId.get(topic);
     if (existingSubId !== void 0) {
       const sub = this.subscriptions.get(existingSubId);
@@ -796,9 +813,14 @@ var _FoxgloveClient = class _FoxgloveClient {
         sub.callbacks.set(onMessage, {
           userMinIntervalMs,
           disableAdaptive,
-          lastDeliveredAt: 0
+          lastDeliveredAt: 0,
+          dispatchMode,
+          pending: null,
+          drainTimer: null
         });
         return () => {
+          const entry = sub.callbacks.get(onMessage);
+          if (entry) this.cancelDrain(entry);
           sub.callbacks.delete(onMessage);
           if (sub.callbacks.size === 0) {
             this.unsubscribeTopic(topic, existingSubId);
@@ -819,7 +841,10 @@ var _FoxgloveClient = class _FoxgloveClient {
     callbacks.set(onMessage, {
       userMinIntervalMs,
       disableAdaptive,
-      lastDeliveredAt: 0
+      lastDeliveredAt: 0,
+      dispatchMode,
+      pending: null,
+      drainTimer: null
     });
     const breaker = new CircuitBreaker({
       ...DEFAULT_BREAKER_CONFIG,
@@ -827,6 +852,7 @@ var _FoxgloveClient = class _FoxgloveClient {
         const sub = this.subscriptions.get(subscriptionId);
         if (!sub) return;
         sub.isPaused = newState === "tripped_auto" || newState === "tripped_manual";
+        if (sub.isPaused) this.cancelAllDrains(sub);
         if (newState === "tripped_auto") {
           if (this.ws && this.status === "connected") {
             this.sendJson({ op: "unsubscribe", subscriptionIds: [subscriptionId] });
@@ -892,6 +918,8 @@ var _FoxgloveClient = class _FoxgloveClient {
       subscriptions: [{ id: subscriptionId, channelId }]
     });
     return () => {
+      const entry = callbacks.get(onMessage);
+      if (entry) this.cancelDrain(entry);
       callbacks.delete(onMessage);
       if (callbacks.size === 0) {
         this.unsubscribeTopic(topic, subscriptionId);
@@ -1306,46 +1334,103 @@ var _FoxgloveClient = class _FoxgloveClient {
       }
     }
     if (deliverTo.length === 0) return;
-    const channelInfo = this.channels.get(sub.channelId);
-    const schemaName = channelInfo?.schemaName ?? "";
-    const encoding = channelInfo?.encoding ?? "json";
-    let data;
+    let parsed = null;
+    for (const [cb, entry] of deliverTo) {
+      entry.lastDeliveredAt = now;
+      if (entry.dispatchMode === "latest-only") {
+        entry.pending = { payload: new Uint8Array(payload), sec, nsec };
+        if (entry.drainTimer === null) {
+          entry.drainTimer = setTimeout(
+            () => this.drainLatestOnly(subscriptionId, cb, entry),
+            0
+          );
+        }
+        continue;
+      }
+      if (parsed === null) {
+        const channelInfo = this.channels.get(sub.channelId);
+        const encoding = channelInfo?.encoding ?? "json";
+        parsed = {
+          topic: sub.topic,
+          schemaName: channelInfo?.schemaName ?? "",
+          encoding: encoding === "json" ? "json" : "cdr",
+          data: this.decodePayload(payload, subscriptionId, encoding),
+          receiveTime: { sec, nsec },
+          byteSize: payload.byteLength
+        };
+      }
+      try {
+        cb(parsed);
+      } catch (err) {
+        this.logger.error("[FoxgloveClient] Subscriber callback error:", err);
+      }
+    }
+  }
+  /**
+   * Decode a `messageData` payload to its delivered shape: a parsed object when
+   * a CDR reader or JSON decode succeeds, the raw bytes otherwise. Shared by
+   * the synchronous `immediate` path and the deferred `latest-only` drain.
+   */
+  decodePayload(payload, subscriptionId, encoding) {
     if (encoding === "json") {
       try {
-        const text = TEXT_DECODER.decode(payload);
-        data = JSON.parse(text);
+        return JSON.parse(TEXT_DECODER.decode(payload));
       } catch {
-        data = payload;
+        return payload;
       }
-    } else {
-      const reader = this.messageReaders.get(subscriptionId);
-      if (reader) {
-        try {
-          data = reader.readMessage(payload);
-        } catch {
-          data = payload;
-        }
-      } else {
-        data = payload;
+    }
+    const reader = this.messageReaders.get(subscriptionId);
+    if (reader) {
+      try {
+        return reader.readMessage(payload);
+      } catch {
+        return payload;
       }
     }
+    return payload;
+  }
+  /**
+   * Drain one `latest-only` callback's pending payload: parse the survivor and
+   * deliver it. Cleared state (`pending`, `drainTimer`) is reset *before* the
+   * callback runs, so a throwing callback never wedges future delivery — the
+   * next arrival re-arms normally. Bails if the subscription was torn down or
+   * paused while the drain was armed (no post-teardown delivery).
+   */
+  drainLatestOnly(subscriptionId, cb, entry) {
+    entry.drainTimer = null;
+    const pending = entry.pending;
+    entry.pending = null;
+    if (!pending) return;
+    const sub = this.subscriptions.get(subscriptionId);
+    if (!sub || sub.isPaused) return;
+    const channelInfo = this.channels.get(sub.channelId);
+    const encoding = channelInfo?.encoding ?? "json";
     const rosMsg = {
       topic: sub.topic,
-      schemaName,
+      schemaName: channelInfo?.schemaName ?? "",
       encoding: encoding === "json" ? "json" : "cdr",
-      data,
-      receiveTime: { sec, nsec },
-      byteSize: payload.byteLength
+      data: this.decodePayload(pending.payload, subscriptionId, encoding),
+      receiveTime: { sec: pending.sec, nsec: pending.nsec },
+      byteSize: pending.payload.byteLength
     };
-    for (const [cb, entry] of deliverTo) {
-      entry.lastDeliveredAt = now;
-      try {
-        cb(rosMsg);
-      } catch (err) {
-        this.logger.error("[FoxgloveClient] Subscriber callback error:", err);
-      }
+    try {
+      cb(rosMsg);
+    } catch (err) {
+      this.logger.error("[FoxgloveClient] Subscriber callback error:", err);
     }
   }
+  /** Cancel one callback's armed drain and drop its pending payload. */
+  cancelDrain(entry) {
+    if (entry.drainTimer !== null) {
+      clearTimeout(entry.drainTimer);
+      entry.drainTimer = null;
+    }
+    entry.pending = null;
+  }
+  /** Cancel every armed drain on a subscription (teardown / pause). */
+  cancelAllDrains(sub) {
+    for (const entry of sub.callbacks.values()) this.cancelDrain(entry);
+  }
   handleServerInfo(info) {
     this.log(`Received serverInfo: ${info.name} (sessionId: ${info.sessionId ?? "none"})`);
     this.serverInfoReceived = true;
@@ -1553,6 +1638,7 @@ var _FoxgloveClient = class _FoxgloveClient {
   // ── Private: unsubscribe ─────────────────────────────────────────────────
   unsubscribeTopic(topic, subscriptionId) {
     const sub = this.subscriptions.get(subscriptionId);
+    if (sub) this.cancelAllDrains(sub);
     sub?.breaker.destroy();
     this.subscriptions.delete(subscriptionId);
     this.topicToSubscriptionId.delete(topic);
@@ -1649,6 +1735,7 @@ var _FoxgloveClient = class _FoxgloveClient {
       }
       this.ws = null;
     }
+    for (const sub of this.subscriptions.values()) this.cancelAllDrains(sub);
     this.channels.clear();
     this.topicToChannelId.clear();
     this.subscriptions.clear();
@@ -1839,14 +1926,20 @@ var _RosbridgeClient = class _RosbridgeClient {
     }
     const userMinIntervalMs = options?.maxFrequency && options.maxFrequency > 0 ? 1e3 / options.maxFrequency : void 0;
     const disableAdaptive = options?.disableAdaptive ?? false;
+    const dispatchMode = options?.dispatchMode ?? "immediate";
     const existing = this.activeSubscriptions.get(topic);
     if (existing) {
       existing.callbacks.set(onMessage, {
         userMinIntervalMs,
         disableAdaptive,
-        lastDeliveredAt: 0
+        lastDeliveredAt: 0,
+        dispatchMode,
+        pending: null,
+        drainTimer: null
       });
       return () => {
+        const entry = existing.callbacks.get(onMessage);
+        if (entry) this.cancelDrain(entry);
         existing.callbacks.delete(onMessage);
         if (existing.callbacks.size === 0) {
           this.unsubscribeTopic(topic);
@@ -1862,7 +1955,10 @@ var _RosbridgeClient = class _RosbridgeClient {
     callbacks.set(onMessage, {
       userMinIntervalMs,
       disableAdaptive,
-      lastDeliveredAt: 0
+      lastDeliveredAt: 0,
+      dispatchMode,
+      pending: null,
+      drainTimer: null
     });
     const breaker = new CircuitBreaker({
       ...DEFAULT_BREAKER_CONFIG,
@@ -1870,6 +1966,7 @@ var _RosbridgeClient = class _RosbridgeClient {
         const sub = this.activeSubscriptions.get(topic);
         if (!sub) return;
         sub.isPaused = newState === "tripped_auto" || newState === "tripped_manual";
+        if (sub.isPaused) this.cancelAllDrains(sub);
         if (newState === "tripped_auto") {
           if (this.ws && this.status === "connected") {
             this.send({ op: "unsubscribe", topic });
@@ -1919,6 +2016,8 @@ var _RosbridgeClient = class _RosbridgeClient {
       queue_length: 1
     });
     return () => {
+      const entry = callbacks.get(onMessage);
+      if (entry) this.cancelDrain(entry);
       callbacks.delete(onMessage);
       if (callbacks.size === 0) {
         this.unsubscribeTopic(topic);
@@ -2218,19 +2317,26 @@ var _RosbridgeClient = class _RosbridgeClient {
       recordBytes(sub.bandwidth, now, byteSize, mode);
       return true;
     }
-    let anyCallbackWantsThis = false;
-    for (const entry of sub.callbacks.values()) {
+    let anyImmediateWantsThis = false;
+    for (const [cb, entry] of sub.callbacks) {
       const interval = effectiveMinInterval(
         entry.userMinIntervalMs,
         entry.disableAdaptive,
         sub.bandwidth
       );
-      if (interval <= 0 || now - entry.lastDeliveredAt >= interval) {
-        anyCallbackWantsThis = true;
-        break;
+      const eligible = interval <= 0 || now - entry.lastDeliveredAt >= interval;
+      if (!eligible) continue;
+      if (entry.dispatchMode === "latest-only") {
+        entry.lastDeliveredAt = now;
+        entry.pending = { raw: data, receivedAt: now };
+        if (entry.drainTimer === null) {
+          entry.drainTimer = setTimeout(() => this.drainLatestOnly(topic, cb, entry), 0);
+        }
+      } else {
+        anyImmediateWantsThis = true;
       }
     }
-    if (anyCallbackWantsThis) return false;
+    if (anyImmediateWantsThis) return false;
     recordBytes(sub.bandwidth, now, byteSize, mode);
     sub.breaker.recordObservation(now, sub.bandwidth.bytesPerSec, getMaxLagMs());
     return true;
@@ -2246,6 +2352,7 @@ var _RosbridgeClient = class _RosbridgeClient {
     sub.breaker.recordObservation(now, sub.bandwidth.bytesPerSec, getMaxLagMs());
     const deliverTo = [];
     for (const [cb, entry] of sub.callbacks) {
+      if (entry.dispatchMode === "latest-only") continue;
       const interval = effectiveMinInterval(
         entry.userMinIntervalMs,
         entry.disableAdaptive,
@@ -2276,6 +2383,55 @@ var _RosbridgeClient = class _RosbridgeClient {
       }
     }
   }
+  /**
+   * Drain one `latest-only` callback's pending frame: parse the survivor and
+   * deliver it. State (`pending`, `drainTimer`) is cleared *before* the
+   * callback runs, so a throwing callback never wedges future delivery. Bails
+   * if the subscription was torn down or paused while the drain was armed (no
+   * post-teardown delivery).
+   */
+  drainLatestOnly(topic, cb, entry) {
+    entry.drainTimer = null;
+    const pending = entry.pending;
+    entry.pending = null;
+    if (!pending) return;
+    const sub = this.activeSubscriptions.get(topic);
+    if (!sub || sub.isPaused) return;
+    let parsed;
+    try {
+      parsed = JSON.parse(pending.raw);
+    } catch {
+      return;
+    }
+    const rosMsg = {
+      topic,
+      schemaName: sub.schemaName,
+      encoding: "json",
+      data: parsed.msg ?? {},
+      receiveTime: {
+        sec: Math.floor(pending.receivedAt / 1e3),
+        nsec: pending.receivedAt % 1e3 * 1e6
+      },
+      byteSize: pending.raw.length
+    };
+    try {
+      cb(rosMsg);
+    } catch (err) {
+      this.logger.error("[RosbridgeClient] Subscriber callback error:", err);
+    }
+  }
+  /** Cancel one callback's armed drain and drop its pending frame. */
+  cancelDrain(entry) {
+    if (entry.drainTimer !== null) {
+      clearTimeout(entry.drainTimer);
+      entry.drainTimer = null;
+    }
+    entry.pending = null;
+  }
+  /** Cancel every armed drain on a subscription (teardown / pause). */
+  cancelAllDrains(sub) {
+    for (const entry of sub.callbacks.values()) this.cancelDrain(entry);
+  }
   handleServiceResponse(msg) {
     const id = msg.id;
     const pending = this.pendingServiceCalls.get(id);
@@ -2294,6 +2450,7 @@ var _RosbridgeClient = class _RosbridgeClient {
   // ── Private: topic management ──────────────────────────────────────────
   unsubscribeTopic(topic) {
     const sub = this.activeSubscriptions.get(topic);
+    if (sub) this.cancelAllDrains(sub);
     sub?.breaker.destroy();
     this.activeSubscriptions.delete(topic);
     if (this.ws && this.status === "connected" && !sub?.isPaused) {
@@ -2416,6 +2573,7 @@ var _RosbridgeClient = class _RosbridgeClient {
   cleanupConnection() {
     this.clearConnectionTimeout();
     this.stopServicesPoll();
+    for (const sub of this.activeSubscriptions.values()) this.cancelAllDrains(sub);
     this.activeSubscriptions.clear();
     for (const [, pending] of this.pendingServiceCalls) {
       clearTimeout(pending.timer);
@@ -2599,6 +2757,11 @@ var ProtocolManager = class {
   }
 };
 
+// src/materializeBytes.ts
+function materializeBytes(view) {
+  return new Uint8Array(view);
+}
+
 exports.DEFAULT_PORTS = DEFAULT_PORTS;
 exports.DEFAULT_PRESETS = DEFAULT_PRESETS;
 exports.FoxgloveClient = FoxgloveClient;
@@ -2610,6 +2773,8 @@ exports.getLagHistoryCsv = getLagHistoryCsv;
 exports.getLagStats = getLagStats;
 exports.getMaxLagMs = getMaxLagMs;
 exports.jsonSchemaToTemplate = jsonSchemaToTemplate;
+exports.matchesSchema = matchesSchema;
+exports.materializeBytes = materializeBytes;
 exports.schemaToTemplate = schemaToTemplate;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map