@rainbow-robotics/plugin-ui 1.3.8-dev.4 → 1.10.1-dev.0

package/src/ws.ts

@@ -1,256 +1,256 @@
-/**
- * Socket.IO communication client for plugin frontends.
- *
- * Topics are automatically namespaced to prevent cross-plugin collisions:
- *   "sensor/data"  →  "{pluginId}/sensor/data"
- *   "/broadcast/x" →  "broadcast/x"   (leading slash = absolute)
- *
- * Browser ←→ Python backend protocol:
- *   browser emits : sub, unsub, pub, action (with ack), serve_reply
- *   server emits  : msg, serve_call
- */
-import { io, type Socket } from "socket.io-client";
-// Type-only — no runtime coupling to host-ui.ts.
-import type { PluginUIServices } from "./host-ui";
-
-export interface WsHandle {
-  undeclare(): void;
-}
-
-export type WsSubscriber = WsHandle;
-export type WsQueryable = WsHandle;
-
-function resolveTopic(pluginId: string, topic: string): string {
-  return topic.startsWith("/") ? topic.slice(1) : `${pluginId}/${topic}`;
-}
-
-export class RbWs {
-  private readonly _socket: Socket;
-  private readonly _pluginId: string;
-  private readonly _subHandlers = new Map<
-    string,
-    Set<(payload: unknown) => void>
-  >();
-  private readonly _serveHandlers = new Map<
-    string,
-    (payload?: unknown) => unknown | Promise<unknown>
-  >();
-
-  private constructor(socket: Socket, pluginId: string) {
-    this._socket = socket;
-    this._pluginId = pluginId;
-
-    // The gateway keeps subscriptions/serve registrations in memory — re-send them after
-    // a reconnect (e.g. the gateway restarted), or they silently stop working.
-    socket.io.on("reconnect", () => {
-      for (const topic of this._subHandlers.keys()) socket.emit("sub", { topic });
-      for (const topic of this._serveHandlers.keys()) socket.emit("serve_register", { topic });
-    });
-
-    // Deliver incoming pub/sub messages to registered handlers
-    socket.on(
-      "msg",
-      ({ topic, payload }: { topic: string; payload: unknown }) => {
-        this._subHandlers.get(topic)?.forEach((h) => h(payload));
-      },
-    );
-
-    // Python calls a browser-side serve handler
-    socket.on(
-      "serve_call",
-      async ({
-        id,
-        topic,
-        payload,
-      }: {
-        id: string;
-        topic: string;
-        payload: unknown;
-      }) => {
-        const handler = this._serveHandlers.get(topic);
-        const result = handler ? await handler(payload) : undefined;
-        socket.emit("serve_reply", { id, payload: result });
-      },
-    );
-  }
-
-  get pluginId(): string {
-    return this._pluginId;
-  }
-
-  static connect(url: string, pluginId: string): Promise<RbWs> {
-    return new Promise((resolve, reject) => {
-      const socket = io(url, { transports: ["websocket"] });
-      const onConnect = () => {
-        cleanup();
-        resolve(new RbWs(socket, pluginId));
-      };
-      const onError = (err: Error) => {
-        cleanup();
-        reject(err);
-      };
-      const cleanup = () => {
-        socket.off("connect", onConnect);
-        socket.off("connect_error", onError);
-      };
-      socket.once("connect", onConnect);
-      socket.once("connect_error", onError);
-    });
-  }
-
-  private _key(topic: string): string {
-    return resolveTopic(this._pluginId, topic);
-  }
-
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  async pub<P = any>(topic: string, payload: P): Promise<void> {
-    this._socket.emit("pub", { topic: this._key(topic), payload });
-  }
-
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  async sub<P = any>(
-    topic: string,
-    handler: (payload: P) => void,
-  ): Promise<WsSubscriber> {
-    const key = this._key(topic);
-    if (!this._subHandlers.has(key)) {
-      this._subHandlers.set(key, new Set());
-      this._socket.emit("sub", { topic: key });
-    }
-    const h = handler as (payload: unknown) => void;
-    this._subHandlers.get(key)!.add(h);
-    return {
-      undeclare: () => {
-        const set = this._subHandlers.get(key);
-        if (!set) return;
-        set.delete(h);
-        if (set.size === 0) {
-          this._subHandlers.delete(key);
-          this._socket.emit("unsub", { topic: key });
-        }
-      },
-    };
-  }
-
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  async action<R = any, P = any>(topic: string, payload?: P): Promise<R> {
-    const key = this._key(topic);
-    return new Promise((resolve, reject) => {
-      this._socket
-        .timeout(10_000)
-        .emit(
-          "action",
-          { topic: key, payload },
-          (err: Error | null, result: R) => {
-            if (err) {
-              // socket.io ack timeout — the bridge itself never answered.
-              reject(new Error(`action "${key}": no ack from bridge (${err.message})`));
-            } else if (
-              result &&
-              typeof result === "object" &&
-              "error" in result &&
-              typeof result.error === "string"
-            ) {
-              // Backend handler returned an error payload — surface it verbatim.
-              reject(new Error(result.error));
-            } else if (result === undefined || result === null) {
-              // The bridge acked but with no payload: the backend handler is
-              // registered yet didn't reply in time (hung inside the handler,
-              // e.g. a blocked SDK call) or returned nothing. Distinct from a
-              // "No handler registered" error, which comes back as result.error.
-              reject(
-                new Error(
-                  `action "${key}": no reply from plugin backend — the handler was reached but didn't return in time (check the backend's stdout on the robot).`,
-                ),
-              );
-            } else {
-              resolve(result);
-            }
-          },
-        );
-    });
-  }
-
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  async serve<P = any, R = any>(
-    topic: string,
-    handler: (payload?: P) => R | Promise<R>,
-  ): Promise<WsQueryable> {
-    const key = this._key(topic);
-    this._serveHandlers.set(key, handler as (payload?: unknown) => unknown);
-    this._socket.emit("serve_register", { topic: key });
-    return {
-      undeclare: () => {
-        this._serveHandlers.delete(key);
-        this._socket.emit("serve_unregister", { topic: key });
-      },
-    };
-  }
-
-  close(): void {
-    this._socket.disconnect();
-  }
-}
-
-/**
- * Builds an rb-sdk-shaped object (pub/sub/action/serve + the passed-through
- * toast/alert/confirm/prompt) that lazily awaits a not-yet-connected `RbWs` —
- * so callers don't block their first render on the WebSocket handshake (there
- * may be no backend reachable yet). Shared by both host mount paths (see
- * ./host.tsx and muscat-plugin-kit's dev bootstrap), which otherwise
- * duplicate this wiring.
- */
-export function createLazyRbSdk(
-  wsPromise: Promise<RbWs>,
-  services: PluginUIServices,
-  // Per-mount, host-provided (unlike `services`, which is a global singleton):
-  // initial `data` and the `onSave` registration the host reads back. Plain
-  // values/closures, so they cross the dev React-instance boundary safely.
-  mount?: {
-    data?: unknown;
-    onSave?: (getPayload: () => unknown) => () => void;
-  },
-) {
-  return {
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    pub: async (topic: string, payload: any) =>
-      (await wsPromise).pub(topic, payload),
-    sub: async (
-      topic: string,
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      handler: (payload: any) => void,
-    ) => (await wsPromise).sub(topic, handler),
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    action: async (topic: string, payload?: any) =>
-      (await wsPromise).action(topic, payload),
-    serve: async (
-      topic: string,
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      handler: (payload?: any) => any,
-    ) => (await wsPromise).serve(topic, handler),
-    toast: services.toast,
-    alert: services.alert,
-    confirm: services.confirm,
-    prompt: services.prompt,
-    program: services.program,
-    data: mount?.data,
-    onSave: mount?.onSave ?? (() => () => {}),
-    rosPeers: rosPeersApi(async (op, payload) => {
-      const ws = await wsPromise;
-      return ws.action(`/muscat/plugin/${ws.pluginId}/ros_peers/${op}`, payload);
-    }),
-  };
-}
-
-// Answered by Muscat (common) on the robot and by `muscat-pk dev` locally.
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-function rosPeersApi(call: (op: "get" | "set", payload?: any) => Promise<any>) {
-  return {
-    get: async (): Promise<string[]> => (await call("get"))?.peers ?? [],
-    set: async (peers: string[]): Promise<string[]> => {
-      const r = await call("set", { peers });
-      if (!r?.ok) throw new Error(r?.error ?? "rb.rosPeers.set failed");
-      return r.peers;
-    },
-  };
-}
+/**
+ * Socket.IO communication client for plugin frontends.
+ *
+ * Topics are automatically namespaced to prevent cross-plugin collisions:
+ *   "sensor/data"  →  "{pluginId}/sensor/data"
+ *   "/broadcast/x" →  "broadcast/x"   (leading slash = absolute)
+ *
+ * Browser ←→ Python backend protocol:
+ *   browser emits : sub, unsub, pub, action (with ack), serve_reply
+ *   server emits  : msg, serve_call
+ */
+import { io, type Socket } from "socket.io-client";
+// Type-only — no runtime coupling to host-ui.ts.
+import type { PluginUIServices } from "./host-ui";
+
+export interface WsHandle {
+  undeclare(): void;
+}
+
+export type WsSubscriber = WsHandle;
+export type WsQueryable = WsHandle;
+
+function resolveTopic(pluginId: string, topic: string): string {
+  return topic.startsWith("/") ? topic.slice(1) : `${pluginId}/${topic}`;
+}
+
+export class RbWs {
+  private readonly _socket: Socket;
+  private readonly _pluginId: string;
+  private readonly _subHandlers = new Map<
+    string,
+    Set<(payload: unknown) => void>
+  >();
+  private readonly _serveHandlers = new Map<
+    string,
+    (payload?: unknown) => unknown | Promise<unknown>
+  >();
+
+  private constructor(socket: Socket, pluginId: string) {
+    this._socket = socket;
+    this._pluginId = pluginId;
+
+    // The gateway keeps subscriptions/serve registrations in memory — re-send them after
+    // a reconnect (e.g. the gateway restarted), or they silently stop working.
+    socket.io.on("reconnect", () => {
+      for (const topic of this._subHandlers.keys()) socket.emit("sub", { topic });
+      for (const topic of this._serveHandlers.keys()) socket.emit("serve_register", { topic });
+    });
+
+    // Deliver incoming pub/sub messages to registered handlers
+    socket.on(
+      "msg",
+      ({ topic, payload }: { topic: string; payload: unknown }) => {
+        this._subHandlers.get(topic)?.forEach((h) => h(payload));
+      },
+    );
+
+    // Python calls a browser-side serve handler
+    socket.on(
+      "serve_call",
+      async ({
+        id,
+        topic,
+        payload,
+      }: {
+        id: string;
+        topic: string;
+        payload: unknown;
+      }) => {
+        const handler = this._serveHandlers.get(topic);
+        const result = handler ? await handler(payload) : undefined;
+        socket.emit("serve_reply", { id, payload: result });
+      },
+    );
+  }
+
+  get pluginId(): string {
+    return this._pluginId;
+  }
+
+  static connect(url: string, pluginId: string): Promise<RbWs> {
+    return new Promise((resolve, reject) => {
+      const socket = io(url, { transports: ["websocket"] });
+      const onConnect = () => {
+        cleanup();
+        resolve(new RbWs(socket, pluginId));
+      };
+      const onError = (err: Error) => {
+        cleanup();
+        reject(err);
+      };
+      const cleanup = () => {
+        socket.off("connect", onConnect);
+        socket.off("connect_error", onError);
+      };
+      socket.once("connect", onConnect);
+      socket.once("connect_error", onError);
+    });
+  }
+
+  private _key(topic: string): string {
+    return resolveTopic(this._pluginId, topic);
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  async pub<P = any>(topic: string, payload: P): Promise<void> {
+    this._socket.emit("pub", { topic: this._key(topic), payload });
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  async sub<P = any>(
+    topic: string,
+    handler: (payload: P) => void,
+  ): Promise<WsSubscriber> {
+    const key = this._key(topic);
+    if (!this._subHandlers.has(key)) {
+      this._subHandlers.set(key, new Set());
+      this._socket.emit("sub", { topic: key });
+    }
+    const h = handler as (payload: unknown) => void;
+    this._subHandlers.get(key)!.add(h);
+    return {
+      undeclare: () => {
+        const set = this._subHandlers.get(key);
+        if (!set) return;
+        set.delete(h);
+        if (set.size === 0) {
+          this._subHandlers.delete(key);
+          this._socket.emit("unsub", { topic: key });
+        }
+      },
+    };
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  async action<R = any, P = any>(topic: string, payload?: P): Promise<R> {
+    const key = this._key(topic);
+    return new Promise((resolve, reject) => {
+      this._socket
+        .timeout(10_000)
+        .emit(
+          "action",
+          { topic: key, payload },
+          (err: Error | null, result: R) => {
+            if (err) {
+              // socket.io ack timeout — the bridge itself never answered.
+              reject(new Error(`action "${key}": no ack from bridge (${err.message})`));
+            } else if (
+              result &&
+              typeof result === "object" &&
+              "error" in result &&
+              typeof result.error === "string"
+            ) {
+              // Backend handler returned an error payload — surface it verbatim.
+              reject(new Error(result.error));
+            } else if (result === undefined || result === null) {
+              // The bridge acked but with no payload: the backend handler is
+              // registered yet didn't reply in time (hung inside the handler,
+              // e.g. a blocked SDK call) or returned nothing. Distinct from a
+              // "No handler registered" error, which comes back as result.error.
+              reject(
+                new Error(
+                  `action "${key}": no reply from plugin backend — the handler was reached but didn't return in time (check the backend's stdout on the robot).`,
+                ),
+              );
+            } else {
+              resolve(result);
+            }
+          },
+        );
+    });
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  async serve<P = any, R = any>(
+    topic: string,
+    handler: (payload?: P) => R | Promise<R>,
+  ): Promise<WsQueryable> {
+    const key = this._key(topic);
+    this._serveHandlers.set(key, handler as (payload?: unknown) => unknown);
+    this._socket.emit("serve_register", { topic: key });
+    return {
+      undeclare: () => {
+        this._serveHandlers.delete(key);
+        this._socket.emit("serve_unregister", { topic: key });
+      },
+    };
+  }
+
+  close(): void {
+    this._socket.disconnect();
+  }
+}
+
+/**
+ * Builds an rb-sdk-shaped object (pub/sub/action/serve + the passed-through
+ * toast/alert/confirm/prompt) that lazily awaits a not-yet-connected `RbWs` —
+ * so callers don't block their first render on the WebSocket handshake (there
+ * may be no backend reachable yet). Shared by both host mount paths (see
+ * ./host.tsx and muscat-plugin-kit's dev bootstrap), which otherwise
+ * duplicate this wiring.
+ */
+export function createLazyRbSdk(
+  wsPromise: Promise<RbWs>,
+  services: PluginUIServices,
+  // Per-mount, host-provided (unlike `services`, which is a global singleton):
+  // initial `data` and the `onSave` registration the host reads back. Plain
+  // values/closures, so they cross the dev React-instance boundary safely.
+  mount?: {
+    data?: unknown;
+    onSave?: (getPayload: () => unknown) => () => void;
+  },
+) {
+  return {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    pub: async (topic: string, payload: any) =>
+      (await wsPromise).pub(topic, payload),
+    sub: async (
+      topic: string,
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      handler: (payload: any) => void,
+    ) => (await wsPromise).sub(topic, handler),
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    action: async (topic: string, payload?: any) =>
+      (await wsPromise).action(topic, payload),
+    serve: async (
+      topic: string,
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      handler: (payload?: any) => any,
+    ) => (await wsPromise).serve(topic, handler),
+    toast: services.toast,
+    alert: services.alert,
+    confirm: services.confirm,
+    prompt: services.prompt,
+    program: services.program,
+    data: mount?.data,
+    onSave: mount?.onSave ?? (() => () => {}),
+    rosPeers: rosPeersApi(async (op, payload) => {
+      const ws = await wsPromise;
+      return ws.action(`/muscat/plugin/${ws.pluginId}/ros_peers/${op}`, payload);
+    }),
+  };
+}
+
+// Answered by Muscat (common) on the robot and by `muscat-pk dev` locally.
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function rosPeersApi(call: (op: "get" | "set", payload?: any) => Promise<any>) {
+  return {
+    get: async (): Promise<string[]> => (await call("get"))?.peers ?? [],
+    set: async (peers: string[]): Promise<string[]> => {
+      const r = await call("set", { peers });
+      if (!r?.ok) throw new Error(r?.error ?? "rb.rosPeers.set failed");
+      return r.peers;
+    },
+  };
+}