bunite-core 0.2.1 → 0.3.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "bunite-core",
   "description": "Uniting UI and Bun",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "type": "module",
   "scripts": {
     "setup:cef": "bun ../tools/bunite-dev/scripts/setup-cef.ts",

package/src/bun/index.ts

@@ -13,7 +13,7 @@ import {
   type RPCSchema,
   type RPCWithTransport
 } from "../shared/rpc";
-import { createTransportDemuxer, type TransportDemuxer } from "../shared/rpcDemux";
+import { createTransportDemuxer, type ChannelHandle, type TransportDemuxer, type TransportDemuxerOptions } from "../shared/rpcDemux";
 import { createWebSocketTransport, type WebSocketLike, type WebSocketTransportPipe } from "../shared/webSocketTransport";
 import { createWebRPCHandler, type WebRPCClient } from "../shared/webRpcHandler";
 import type { MessageBoxOptions, MessageBoxResponse } from "./core/Utils";
@@ -40,11 +40,13 @@ export type {
   BuniteRPCConfig,
   BuniteRPCSchema,
   BrowserViewOptions,
+  ChannelHandle,
   MessageBoxOptions,
   MessageBoxResponse,
   RPCSchema,
   RPCWithTransport,
   TransportDemuxer,
+  TransportDemuxerOptions,
   WebRPCClient,
   WebSocketLike,
   WebSocketTransportPipe,

package/src/shared/rpcDemux.ts

@@ -1,64 +1,173 @@
-import type { RPCPacket, RPCTransport } from "./rpc";
+import type { RPCPacket, RPCTransport, RPCWithTransport } from "./rpc";
 
-type DemuxEnvelope = { channel: string; packet: RPCPacket };
+type DemuxPacketEnvelope = { channel: string; packet: RPCPacket };
+type DemuxHelloFrame = { channel: string; hello: true };
+type DemuxFrame = DemuxPacketEnvelope | DemuxHelloFrame;
 
-function isDemuxEnvelope(value: unknown): value is DemuxEnvelope {
+function isDemuxFrame(value: unknown): value is DemuxFrame {
   if (typeof value !== "object" || value === null) return false;
-  const v = value as Partial<DemuxEnvelope>;
-  return typeof v.channel === "string" && typeof v.packet === "object" && v.packet !== null;
+  return typeof (value as DemuxFrame).channel === "string";
 }
 
+function isPacketEnvelope(frame: DemuxFrame): frame is DemuxPacketEnvelope {
+  const v = frame as DemuxPacketEnvelope;
+  return typeof v.packet === "object" && v.packet !== null;
+}
+
+function isHelloFrame(frame: DemuxFrame): frame is DemuxHelloFrame {
+  return (frame as DemuxHelloFrame).hello === true;
+}
+
+export type ChannelHandle = {
+  /**
+   * Connect an RPC instance to this channel. Returns a promise that resolves
+   * once both sides have registered a handler (HELLO handshake). Awaiting
+   * guarantees the first subsequent request reaches the peer.
+   */
+  bindTo(rpc: RPCWithTransport): Promise<void>;
+};
+
 export type TransportDemuxer = {
-  channel(name: string): RPCTransport;
+  channel(name: string): ChannelHandle;
   dispose(): void;
 };
 
-export function createTransportDemuxer(base: RPCTransport): TransportDemuxer {
+export type TransportDemuxerOptions = {
+  /** ms to wait for peer before `bindTo` rejects. Default 10_000. */
+  readyTimeout?: number;
+};
+
+type ChannelState = {
+  handler?: (packet: RPCPacket) => void;
+  peerSawUs: boolean;
+  ready: Promise<void>;
+  resolveReady: () => void;
+  rejectReady: (error: Error) => void;
+  readySettled: boolean;
+  readyTimer?: ReturnType<typeof setTimeout>;
+};
+
+const DEFAULT_READY_TIMEOUT = 10_000;
+
+export function createTransportDemuxer(
+  base: RPCTransport,
+  options: TransportDemuxerOptions = {}
+): TransportDemuxer {
   if (!base.send || !base.registerHandler) {
     throw new Error("createTransportDemuxer requires a base transport with both send and registerHandler");
   }
 
-  const handlers = new Map<string, (packet: RPCPacket) => void>();
+  const readyTimeout = options.readyTimeout ?? DEFAULT_READY_TIMEOUT;
+  const channels = new Map<string, ChannelState>();
   let disposed = false;
 
+  function getOrCreateState(name: string): ChannelState {
+    let state = channels.get(name);
+    if (state) return state;
+
+    let resolveReady!: () => void;
+    let rejectReady!: (error: Error) => void;
+    const ready = new Promise<void>((resolve, reject) => {
+      resolveReady = resolve;
+      rejectReady = reject;
+    });
+    ready.catch(() => {}); // prevent unhandled rejection if consumer doesn't await
+
+    state = {
+      peerSawUs: false,
+      ready,
+      resolveReady,
+      rejectReady,
+      readySettled: false
+    };
+    channels.set(name, state);
+    return state;
+  }
+
+  function settleReady(state: ChannelState, action: () => void) {
+    if (state.readySettled) return;
+    state.readySettled = true;
+    if (state.readyTimer) clearTimeout(state.readyTimer);
+    action();
+  }
+
+  function sendHello(name: string) {
+    const frame: DemuxHelloFrame = { channel: name, hello: true };
+    base.send!(frame as unknown as RPCPacket);
+  }
+
   base.registerHandler((data) => {
-    // Envelopes missing or malformed are dropped. A future fallthrough hook
-    // would land here if we ever multiplex legacy RPC on the same transport.
-    if (!isDemuxEnvelope(data)) return;
-    handlers.get(data.channel)?.(data.packet);
+    if (!isDemuxFrame(data)) return;
+    const state = getOrCreateState(data.channel);
+
+    if (isHelloFrame(data)) {
+      if (state.handler) {
+        const wasReady = state.readySettled;
+        settleReady(state, state.resolveReady);
+        if (!wasReady && !disposed) sendHello(data.channel); // echo so peer wakes up
+      } else {
+        state.peerSawUs = true;
+      }
+      return;
+    }
+
+    if (isPacketEnvelope(data)) {
+      state.handler?.(data.packet);
+    }
   });
 
   return {
     channel(name) {
-      let ownHandler: ((packet: RPCPacket) => void) | undefined;
+      const state = getOrCreateState(name);
 
-      return {
+      const transport: RPCTransport = {
         send(packet) {
           if (disposed) throw new Error(`Demuxer disposed; cannot send on channel "${name}"`);
-          const envelope: DemuxEnvelope = { channel: name, packet };
-          // The wire layer (msgpackr) serializes the envelope opaquely, so
-          // routing the wider type through RPCTransport.send is safe in practice.
+          const envelope: DemuxPacketEnvelope = { channel: name, packet };
           base.send!(envelope as unknown as RPCPacket);
         },
         registerHandler(handler) {
           if (disposed) throw new Error(`Demuxer disposed; cannot register on channel "${name}"`);
-          if (handlers.has(name)) {
+          if (state.handler) {
             throw new Error(`Channel "${name}" already has a handler on this demuxer`);
           }
-          ownHandler = handler;
-          handlers.set(name, handler);
+          state.handler = handler;
+
+          sendHello(name);
+
+          if (state.peerSawUs) {
+            settleReady(state, state.resolveReady);
+          } else if (!state.readySettled && !state.readyTimer) {
+            state.readyTimer = setTimeout(() => {
+              settleReady(state, () =>
+                state.rejectReady(new Error(`Channel "${name}" ready timed out after ${readyTimeout}ms`))
+              );
+            }, readyTimeout);
+          }
         },
         unregisterHandler() {
-          if (ownHandler && handlers.get(name) === ownHandler) {
-            handlers.delete(name);
-            ownHandler = undefined;
-          }
+          state.handler = undefined;
+        }
+      };
+
+      return {
+        bindTo(rpc) {
+          rpc.setTransport(transport);
+          return state.ready;
         }
       };
     },
     dispose() {
+      if (disposed) return;
       disposed = true;
-      handlers.clear();
+      for (const state of channels.values()) {
+        if (state.readyTimer) clearTimeout(state.readyTimer);
+        if (!state.readySettled) {
+          state.readySettled = true;
+          state.rejectReady(new Error("Demuxer disposed"));
+        }
+      }
+      channels.clear();
       base.unregisterHandler?.();
     }
   };

package/src/view/index.ts

@@ -8,7 +8,7 @@ import {
   type RPCTransport,
   type RPCWithTransport
 } from "../shared/rpc";
-import { createTransportDemuxer, type TransportDemuxer } from "../shared/rpcDemux";
+import { createTransportDemuxer, type ChannelHandle, type TransportDemuxer, type TransportDemuxerOptions } from "../shared/rpcDemux";
 import { createWebSocketTransport, type WebSocketLike, type WebSocketTransportPipe } from "../shared/webSocketTransport";
 import { decodeRPCPacket, encodeRPCPacket } from "../shared/rpcWire";
 import { log } from "../shared/log";
@@ -176,8 +176,10 @@ export { createTransportDemuxer, createWebSocketTransport, defineWebviewRPC };
 export type {
   BuniteRPCConfig,
   BuniteRPCSchema,
+  ChannelHandle,
   RPCSchema,
   TransportDemuxer,
+  TransportDemuxerOptions,
   WebSocketLike,
   WebSocketTransportPipe
 };