@statewalker/webrun-rpc 0.4.0

package/src/duplex-over-port.ts

@@ -0,0 +1,471 @@
+import {
+  type ChunkReceiver,
+  type Duplex,
+  deserializeError,
+  recieveIterator,
+  type SerializedError,
+  sendIterator,
+  serializeError,
+  toChunks,
+} from "@statewalker/webrun-streams";
+import { callPort, NO_TIMEOUT } from "./call-port.js";
+import { listenPort } from "./listen-port.js";
+import type { MessageTarget } from "./message-target.js";
+import { throughAbort } from "./through-abort.js";
+
+/**
+ * The `type` of the out-of-band notice a side posts when it abandons a stream.
+ *
+ * Layer 1's `close` is not observable to layer 2 — a closed virtual port drops
+ * its listeners silently and is indistinguishable from a working port nobody
+ * is answering — so the peer would otherwise wait forever. Exported because
+ * tests and adapters assert on it.
+ */
+export const STREAM_ABORT = "webrun-rpc:stream-abort";
+
+/** Caller's input travels on this channel; the handler listens on it. */
+const CHANNEL_IN = "in";
+/** The handler's output travels on this channel; the caller listens on it. */
+const CHANNEL_OUT = "out";
+
+/** One chunk on the wire: `IteratorChunk<Uint8Array>` with the error serialised. */
+interface WireChunk {
+  done: boolean;
+  value?: Uint8Array;
+  error?: SerializedError;
+}
+
+export interface DuplexOverPortOptions {
+  /**
+   * Largest payload one chunk may carry, from `PortMux.maxMessageSize` (spec
+   * D10). Bodies are split to fit with `toChunks`. Unset means no limit and no
+   * splitting.
+   */
+  maxMessageSize?: number;
+  /**
+   * Inactivity timeout for the whole stream, in ms: the clock is reset by any
+   * chunk in either direction, and elapsing aborts the stream. Unset — the
+   * default — means no timeout at all (spec D8): a slow consumer is throttled,
+   * never failed. Any finite default would reintroduce F5 at a different
+   * threshold.
+   */
+  timeout?: number;
+  /** Logging function; defaults to a no-op. */
+  log?: (...args: unknown[]) => void;
+}
+
+/**
+ * One port in, one `Duplex` out (spec D9).
+ *
+ * The returned `Duplex` runs a single stream on `port`: the caller's `input`
+ * is sent chunk by chunk with `callPort`, and the handler's output arrives the
+ * same way on the other channel. Within each direction the next chunk is never
+ * sent until the previous one has been delivered *and* pulled past by the
+ * consumer (spec D11) — the reply to a chunk call *is* the confirmation, and
+ * `listenPort` withholds it until then.
+ *
+ * A stream port carries exactly one invocation. To make several calls, open
+ * several ports: `mux.openPort({ kind: "stream" })` per call.
+ */
+export function duplexOverPort(port: MessageTarget, options: DuplexOverPortOptions = {}): Duplex {
+  return (input) => runCallerSide(port, input, options);
+}
+
+/**
+ * Installs `handler` as the serving side of one stream on `port`. Returns an
+ * idempotent teardown that abandons the stream and notifies the peer.
+ */
+export function serveDuplexOverPort(
+  port: MessageTarget,
+  handler: Duplex,
+  options: DuplexOverPortOptions = {},
+): () => void {
+  const controller = new AbortController();
+  const notice = installAbortNotice(port, controller);
+  const clock = installStreamTimeout(controller, options.timeout);
+  const inbound = receiveChunks(port, CHANNEL_IN, controller, clock.touch);
+  let output: AsyncGenerator<Uint8Array>;
+  try {
+    output = handler(inbound.stream);
+  } catch (err) {
+    // A handler that throws before returning a generator still owes the peer
+    // an end-of-stream, or its `callPort` never settles.
+    const pump = sendChunks(
+      port,
+      CHANNEL_OUT,
+      failing(err),
+      options,
+      controller.signal,
+      clock.touch,
+    );
+    void pump.catch(() => {});
+    disarmClockWhenBothSidesSettle(clock, pump, inbound.ended);
+    return teardownOnce(controller, notice, clock, inbound, undefined);
+  }
+  const pump = sendChunks(port, CHANNEL_OUT, output, options, controller.signal, clock.touch);
+  void pump.catch(() => {
+    // Reported to the peer inside sendChunks; nothing to surface locally.
+  });
+  disarmClockWhenBothSidesSettle(clock, pump, inbound.ended);
+  return teardownOnce(controller, notice, clock, inbound, output);
+}
+
+/**
+ * A stream that completes normally has nobody left to call the returned
+ * teardown — the caller only knows the stream ended, not that it must also
+ * dispose the serve-side handle. Without this, the last `touch()`'s timer
+ * stays armed for up to `timeout` ms after real completion, doing nothing
+ * but holding the event loop open.
+ *
+ * Only disarms once BOTH `pump` (our output) and `inboundEnded` (the peer's
+ * declared end of input, or an abort) have settled. Disarming on `pump`
+ * alone is not safe: under half-close the handler can finish producing
+ * output while the caller is still sending input, and a clock stopped then
+ * would leave that still-open half with no deadline at all — worse than the
+ * leak this fixes.
+ */
+function disarmClockWhenBothSidesSettle(
+  clock: { stop(): void },
+  pump: Promise<void>,
+  inboundEnded: Promise<void>,
+): void {
+  void Promise.allSettled([pump, inboundEnded]).then(() => {
+    clock.stop();
+  });
+}
+
+async function* failing(err: unknown): AsyncGenerator<Uint8Array> {
+  if ((0 as number) === 0) throw err;
+  yield new Uint8Array(0);
+}
+
+function teardownOnce(
+  controller: AbortController,
+  notice: { post(): void; stop(): void },
+  clock: { touch(): void; stop(): void },
+  inbound: { stop(): void },
+  output: AsyncGenerator<Uint8Array> | undefined,
+): () => void {
+  let torn = false;
+  return () => {
+    if (torn) return;
+    torn = true;
+    if (!controller.signal.aborted) controller.abort(new Error("webrun-rpc: stream torn down"));
+    notice.post();
+    notice.stop();
+    clock.stop();
+    inbound.stop();
+    void output?.return(undefined as never).catch(() => {});
+  };
+}
+
+function runCallerSide(
+  port: MessageTarget,
+  input: AsyncIterable<Uint8Array> | Iterable<Uint8Array>,
+  options: DuplexOverPortOptions,
+): AsyncGenerator<Uint8Array> {
+  const controller = new AbortController();
+  const notice = installAbortNotice(port, controller);
+  const clock = installStreamTimeout(controller, options.timeout);
+  const inbound = receiveChunks(port, CHANNEL_OUT, controller, clock.touch);
+  const pump = sendChunks(port, CHANNEL_IN, input, options, controller.signal, clock.touch);
+  void pump.catch(() => {
+    // The outbound half's failure surfaces to the peer, not to this consumer:
+    // the consumer's contract is the inbound half.
+  });
+
+  return (async function* () {
+    try {
+      yield* inbound.stream;
+    } finally {
+      // Abort BEFORE awaiting the pump. `callPort` runs with NO_TIMEOUT here,
+      // so an un-aborted in-flight chunk call would never settle and this
+      // `finally` would deadlock — which is exactly the defect found in the
+      // -webrtc adapter, where the outbound half was awaited unconditionally.
+      if (!controller.signal.aborted) {
+        controller.abort(new Error("webrun-rpc: the caller abandoned the stream"));
+      }
+      notice.post();
+      notice.stop();
+      clock.stop();
+      inbound.stop();
+      await pump.catch(() => {});
+      try {
+        await port.close?.();
+      } catch {
+        /* the port may already be gone; nothing to unwind */
+      }
+    }
+  })();
+}
+
+/**
+ * Listens for the peer's abort notice, and can post our own. The notice is a
+ * plain message with no `channelName` and a `type` that is not `"request"`,
+ * so neither `callPort` nor `listenPort` reacts to it, and it carries no
+ * numeric `id`, so `structuredCodec` never mistakes it for a layer 1 envelope.
+ */
+function installAbortNotice(
+  port: MessageTarget,
+  controller: AbortController,
+): { post(): void; stop(): void } {
+  const onMessage = (event: MessageEvent) => {
+    const data = event.data as { type?: unknown } | undefined;
+    if (!data || data.type !== STREAM_ABORT) return;
+    if (!controller.signal.aborted) {
+      controller.abort(new Error("webrun-rpc: the peer abandoned the stream"));
+    }
+  };
+  port.addEventListener("message", onMessage);
+  let posted = false;
+  return {
+    post() {
+      if (posted) return;
+      posted = true;
+      try {
+        port.postMessage({ type: STREAM_ABORT });
+      } catch {
+        /* the port is already gone — the peer needs no notice */
+      }
+    },
+    stop() {
+      port.removeEventListener("message", onMessage);
+    },
+  };
+}
+
+/**
+ * The per-stream inactivity timeout (spec D8). Reset by any chunk in either
+ * direction; elapsing aborts the stream. Unset, zero or non-finite installs no
+ * timer at all, which is the default: a slow consumer is throttled, not failed.
+ */
+function installStreamTimeout(
+  controller: AbortController,
+  timeout: number | undefined,
+): { touch(): void; stop(): void } {
+  if (timeout === undefined || !Number.isFinite(timeout) || timeout <= 0) {
+    return { touch() {}, stop() {} };
+  }
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  // Once `stop()` runs, it must stay stopped. Without this, a chunk that
+  // arrives after disarming (e.g. `touch()` called from a pump that hadn't
+  // yet noticed the stream ended) would silently re-arm a timer nobody is
+  // ever going to stop again — the same leak this task exists to close, just
+  // reachable from a different angle now that `stop()` can run mid-life
+  // (fix round 2), not only at final teardown.
+  let stopped = false;
+  const arm = () => {
+    timer = setTimeout(() => {
+      if (!controller.signal.aborted) {
+        controller.abort(new Error(`webrun-rpc: stream idle for ${timeout} ms`));
+      }
+    }, timeout);
+  };
+  arm();
+  return {
+    touch() {
+      if (stopped) return;
+      if (timer !== undefined) clearTimeout(timer);
+      arm();
+    },
+    stop() {
+      stopped = true;
+      if (timer !== undefined) clearTimeout(timer);
+      timer = undefined;
+    },
+  };
+}
+
+/**
+ * The receiving half of one direction.
+ *
+ * The `listenPort` listener is installed **eagerly**, not lazily inside
+ * `recieveIterator`'s installer, because a handler that never drains its input
+ * would otherwise leave the peer's chunk calls with nobody to answer them. If
+ * the local consumer has not started iterating, an inbound chunk waits for it —
+ * which is the correct backpressure, and different from having no listener.
+ */
+function receiveChunks(
+  port: MessageTarget,
+  channelName: string,
+  controller: AbortController,
+  touch: () => void,
+): { stream: AsyncGenerator<Uint8Array>; stop(): void; ended: Promise<void> } {
+  let deliver: ChunkReceiver<Uint8Array> | undefined;
+  const waiting: Array<() => void> = [];
+  let finished = false;
+  let outstanding = false;
+  let poison: Error | undefined;
+  // Resolves once no more chunks are coming on this channel — either the
+  // wire declared `done` (with or without an error) or the signal aborted.
+  // Used by `serveDuplexOverPort` to know when it is safe to disarm the
+  // inactivity clock on a stream nobody explicitly tears down.
+  let resolveEnded: () => void = () => {};
+  const ended = new Promise<void>((resolve) => {
+    resolveEnded = resolve;
+  });
+  // Set by `onAbort` the instant the signal fires, independent of whether a
+  // consumer has started iterating yet. `recieveIterator`'s installer below
+  // runs lazily, on the consumer's first `.next()` — if abort fires first,
+  // `deliver` is still undefined when `onAbort` runs, so its delivery below
+  // is a no-op. Recording the reason here lets the installer catch up and
+  // settle the generator immediately instead of leaving it to wait forever
+  // for a `deliver` call that already happened before it existed.
+  let aborted = false;
+  let abortReason: unknown;
+
+  const ready = (): Promise<void> =>
+    deliver || finished ? Promise.resolve() : new Promise<void>((r) => waiting.push(r));
+
+  const wake = () => {
+    for (const r of waiting.splice(0)) r();
+  };
+
+  const off = listenPort<WireChunk, void>(
+    port,
+    async ({ done, value, error }) => {
+      touch();
+      if (poison) throw poison;
+      if (outstanding) {
+        // Spec D15: a second chunk before the first was confirmed is a
+        // protocol violation, not a resource question. A count of one needs
+        // no threshold and no byte accounting, and it bounds memory by
+        // construction: maxPorts x one chunk.
+        poison = new Error(
+          "webrun-rpc: peer sent a second unconfirmed chunk; the stream port is closed",
+        );
+        // Route through the existing abort machinery instead of duplicating
+        // it by hand. `onAbort` below (a) sets `aborted`/`abortReason`, so
+        // `recieveIterator`'s installer replays the error even if poison
+        // fires before the consumer's first `.next()` — otherwise `deliver`
+        // is still undefined here and the local stream hangs forever; and
+        // (b) since `controller.signal` is the very signal `sendChunks`
+        // passes into `callPort` for *both* directions of this stream,
+        // aborting it rejects any outbound call parked at `NO_TIMEOUT` —
+        // otherwise `port.close()` below makes that call unsettleable, the
+        // pump never returns, the handler's `finally` never runs, and
+        // `disarmClockWhenBothSidesSettle` never fires. `onAbort` also
+        // resolves `ended`, making a separate call here redundant.
+        controller.abort(poison);
+        // Close on the next macrotask, so listenPort still gets to post the
+        // refusal on this one — a virtual port goes inert the instant it
+        // closes, and a silent drop would leave the offender hanging rather
+        // than telling it what it did wrong.
+        setTimeout(() => {
+          try {
+            void port.close?.();
+          } catch {
+            /* already gone */
+          }
+        }, 0);
+        throw poison;
+      }
+      outstanding = true;
+      try {
+        await ready();
+        if (finished) throw poison ?? new Error("webrun-rpc: the stream is closed");
+        await deliver?.({
+          done,
+          value,
+          error: error ? deserializeError(error) : undefined,
+        });
+      } finally {
+        outstanding = false;
+      }
+      if (done) resolveEnded();
+    },
+    { channelName },
+  );
+
+  // Every path that stops listening to this channel — the consumer walking
+  // away early (`break`/`return`/`throw` on the `for await`), an external
+  // `stop()`, or the abort branch below — means no more chunks are coming
+  // *as far as this side is concerned*, regardless of what the wire still
+  // has in flight. `off()` unregisters the port listener right here, so
+  // nothing is left to notice a later wire `done` even if one arrives.
+  // `ended` must resolve at the same moment, or `serveDuplexOverPort`'s
+  // `Promise.allSettled([pump, inbound.ended])` waits forever for a signal
+  // that can no longer come (round-2 fix — this was the dead path: the
+  // round-1 version only resolved `ended` from the wire's own `done` chunk
+  // or from `onAbort`, missing exactly the "consumer stopped pulling before
+  // the wire said done" case, e.g. a handler that reads one chunk and
+  // returns).
+  const detach = () => {
+    finished = true;
+    wake();
+    off();
+    controller.signal.removeEventListener("abort", onAbort);
+    resolveEnded();
+  };
+
+  const onAbort = () => {
+    aborted = true;
+    abortReason = controller.signal.reason;
+    finished = true;
+    wake();
+    // No-op if the consumer hasn't started iterating yet — `deliver` is only
+    // assigned inside the installer below. That ordering is exactly what the
+    // `aborted` check in the installer exists to catch.
+    void deliver?.({ done: true, error: abortReason });
+    resolveEnded();
+  };
+  controller.signal.addEventListener("abort", onAbort, { once: true });
+
+  const stream = recieveIterator<Uint8Array>((d) => {
+    if (aborted) {
+      // The signal already fired before this installer ran. `onAbort`'s
+      // delivery above was a no-op because `deliver` didn't exist yet — settle
+      // the generator immediately instead of registering `deliver` and
+      // waiting for a chunk that will never arrive.
+      void d({ done: true, error: abortReason });
+      return detach;
+    }
+    deliver = d;
+    wake();
+    return detach;
+  });
+
+  return {
+    stream,
+    stop: detach,
+    ended,
+  };
+}
+
+/**
+ * The sending half of one direction: one `callPort` per chunk, one call
+ * outstanding at a time (spec D11/D12), with no per-chunk deadline (spec D8).
+ */
+async function sendChunks(
+  port: MessageTarget,
+  channelName: string,
+  output: AsyncIterable<Uint8Array> | Iterable<Uint8Array>,
+  { maxMessageSize, log }: DuplexOverPortOptions,
+  signal: AbortSignal,
+  touch: () => void,
+): Promise<void> {
+  const framed = maxMessageSize ? toChunks(maxMessageSize)(output) : output;
+  const stream = throughAbort(framed, signal);
+  try {
+    await sendIterator<Uint8Array>(async ({ done, value, error }) => {
+      if (signal.aborted) return;
+      const chunk: WireChunk = {
+        done,
+        value,
+        error: error === undefined ? undefined : serializeError(error),
+      };
+      log?.("[duplexOverPort] send", { channelName, done, size: value?.byteLength });
+      await callPort<void, WireChunk>(port, chunk, {
+        channelName,
+        timeout: NO_TIMEOUT,
+        signal,
+      });
+      touch();
+    }, stream);
+  } catch (err) {
+    // An abort is the expected way this ends when the local side walks away;
+    // anything else is a genuine transport failure worth surfacing.
+    if (signal.aborted) return;
+    throw err;
+  }
+}

package/src/index.ts

@@ -0,0 +1,29 @@
+// Typed-JSON RPC tier (callPort/callBidi/ioSend/ioHandle) over any
+// MessageTarget — moved here from the deleted `webrun-streams-port` package.
+export { byteChannelFromMessagePort } from "./byte-channel.js";
+export * from "./call-bidi.js";
+export * from "./call-port.js";
+export * from "./cancel-channel.js";
+export { getPortCloseSignal, setPortCloseSignal } from "./close-signal.js";
+export {
+  connect,
+  type OnPort,
+  type OverPipeOptions,
+  overPipe,
+  overPorts,
+  type PortMuxFactory,
+  type PortParams,
+  serve,
+} from "./connect-serve.js";
+export * from "./duplex-over-port.js";
+export * from "./io-handle.js";
+export * from "./io-send.js";
+export * from "./listen-bidi.js";
+export * from "./listen-port.js";
+export * from "./message-target.js";
+export { DEFAULT_MAX_PORTS, multiplexPort } from "./multiplex-port.js";
+export type { PortCodec, PortEnvelope, PortMux, PortMuxOptions } from "./port-types.js";
+export * from "./recieve.js";
+export * from "./send.js";
+export { structuredCodec } from "./structured-codec.js";
+export * from "./transfer-port-mux.js";

package/src/io-handle.ts

@@ -0,0 +1,40 @@
+import { listenCancelChannel } from "./cancel-channel.js";
+import type { ListenPortOptions } from "./listen-port.js";
+import type { MessageTarget } from "./message-target.js";
+import { recieve } from "./recieve.js";
+import { send } from "./send.js";
+
+/**
+ * Server half of a full-duplex exchange over any `MessageTarget`.
+ *
+ * For each inbound stream, invokes `handler` with the stream, sends the
+ * handler's output back, and yields a counter. The generator never ends
+ * on its own — consumers break when they want to stop. Pairs with
+ * {@link ioSend}.
+ *
+ * If the peer (the consumer of our outbound send) posts a `cancel-channel`
+ * message on the same sub-channel, we abort `send` immediately. This makes
+ * `ioSend`'s `iter.return()` propagate cleanly without waiting for
+ * `callPort` timeouts.
+ */
+export async function* ioHandle<T, U = T>(
+  port: MessageTarget,
+  handler: (input: AsyncIterable<T>) => AsyncIterable<U> | Promise<AsyncIterable<U>>,
+  options: ListenPortOptions = {},
+): AsyncGenerator<number> {
+  let counter = 0;
+  const channelName = options.channelName ?? "";
+  for await (const input of recieve<T>(port, options)) {
+    const sendAbort = new AbortController();
+    const unsubscribeCancel = channelName
+      ? listenCancelChannel(port, channelName, () => sendAbort.abort())
+      : () => {};
+    try {
+      const output = await handler(input);
+      await send<U>(port, output, { ...options, signal: sendAbort.signal });
+    } finally {
+      unsubscribeCancel();
+    }
+    yield counter++;
+  }
+}

package/src/io-send.ts

@@ -0,0 +1,70 @@
+import { postCancelChannel } from "./cancel-channel.js";
+import type { ListenPortOptions } from "./listen-port.js";
+import type { MessageTarget } from "./message-target.js";
+import { type RecieveOptions, recieve } from "./recieve.js";
+import { send } from "./send.js";
+
+export interface IoSendOptions extends ListenPortOptions {
+  /**
+   * Optional cancel signal threaded into `recieve` so the consumer can force
+   * an in-flight `input.next()` to resolve immediately (otherwise an
+   * AsyncGenerator's `.return()` queues behind the pending `.next()` and
+   * never preempts a hanging await). Used by `callBidi` to abort the inner
+   * stream when the outer call rejects.
+   */
+  cancelSignal?: AbortSignal;
+}
+
+/**
+ * Client half of a full-duplex exchange over any `MessageTarget`.
+ *
+ * Concurrently reads one inbound stream from the peer and writes `output`
+ * to it. Yields each value received from the peer. Completes once both
+ * directions finish. Pairs with {@link ioHandle}.
+ *
+ * If the consumer breaks out of the `for await` (via `iter.return()` or
+ * loop `break`), `ioSend` posts a `cancel-channel` message on the same
+ * sub-channel so the peer can abort its `send` immediately rather than
+ * waiting for `callPort` timeouts to fire.
+ */
+export async function* ioSend<T, U = T>(
+  port: MessageTarget,
+  output: AsyncIterable<U> | Iterable<U>,
+  options: IoSendOptions = {},
+): AsyncGenerator<T> {
+  const { cancelSignal, ...recieveOptions } = options;
+  const channelName = recieveOptions.channelName ?? "";
+  let inputEndedNormally = false;
+  const sendAbort = new AbortController();
+
+  // When the outer cancel fires, also abort the outbound `send` so any
+  // in-flight `callPort` (e.g., the trailing `{done:true}` whose ack the
+  // peer will never produce after closing its listener) short-circuits
+  // instead of hanging on its own timeout.
+  if (cancelSignal) {
+    if (cancelSignal.aborted) sendAbort.abort();
+    else cancelSignal.addEventListener("abort", () => sendAbort.abort(), { once: true });
+  }
+
+  // Combine outer cancel signal with recieve's force-close mechanism.
+  const recieveOpts: RecieveOptions = { ...recieveOptions, signal: cancelSignal };
+
+  for await (const input of recieve<T>(port, recieveOpts)) {
+    const sendPromise = send<U>(port, output, { ...recieveOptions, signal: sendAbort.signal });
+    try {
+      yield* input;
+      inputEndedNormally = true;
+    } finally {
+      if (!inputEndedNormally) {
+        postCancelChannel(port, channelName);
+        sendAbort.abort();
+      }
+      try {
+        await sendPromise;
+      } catch {
+        /* swallow — consumer is done either way */
+      }
+    }
+    break;
+  }
+}

package/src/listen-bidi.ts

@@ -0,0 +1,31 @@
+import { ioHandle } from "./io-handle.js";
+import { listenPort } from "./listen-port.js";
+import type { MessageTarget } from "./message-target.js";
+
+export type BidiHandler<TIn, TOut> = (
+  input: AsyncIterable<TIn>,
+  params: Record<string, unknown>,
+) => AsyncIterable<TOut> | Promise<AsyncIterable<TOut>>;
+
+/**
+ * Server half of {@link callBidi}: listens for stream-call requests on `port`
+ * and dispatches each accepted one to `action`.
+ *
+ * The optional `accept` predicate can inspect the incoming params and reject
+ * unwanted calls. Returns a cleanup function that removes the listener.
+ */
+export function listenBidi<TIn, TOut>(
+  port: MessageTarget,
+  action: BidiHandler<TIn, TOut>,
+  accept: (params: Record<string, unknown>) => boolean = () => true,
+): () => void {
+  return listenPort(port, async (params: Record<string, unknown>) => {
+    if (!params || typeof params.channelName !== "string") return;
+    if (!accept(params)) return;
+    const handler = async (input: AsyncIterable<TIn>) => action(input, params);
+    for await (const _idx of ioHandle<TIn, TOut>(port, handler, params)) {
+      void _idx;
+      break;
+    }
+  });
+}

package/src/listen-port.ts

@@ -0,0 +1,47 @@
+import { serializeError } from "@statewalker/webrun-streams";
+import type { MessageTarget } from "./message-target.js";
+
+export interface ListenPortOptions {
+  /** Channel name filter — ignore messages whose `channelName` doesn't match. */
+  channelName?: string;
+  /** Logging function; defaults to a no-op. */
+  log?: (...args: unknown[]) => void;
+}
+
+export type PortHandler<TParams = unknown, TResult = unknown> = (
+  params: TParams,
+) => TResult | Promise<TResult>;
+
+/**
+ * Installs `handler` as the server side of a `callPort` / `listenPort`
+ * request/response pair on `port`.
+ *
+ * Returns a cleanup function that removes the listener.
+ */
+export function listenPort<TParams = unknown, TResult = unknown>(
+  port: MessageTarget,
+  handler: PortHandler<TParams, TResult>,
+  { channelName = "", log = () => {} }: ListenPortOptions = {},
+): () => void {
+  const onMessage = async (event: MessageEvent) => {
+    const data = event.data as
+      | { type: string; channelName: string; callId: string; params: TParams }
+      | undefined;
+    if (!data || data.channelName !== channelName || data.type !== "request") return;
+    const { callId, params } = data;
+    log("[listenPort]", { channelName, callId, params });
+    let result: TResult | undefined;
+    let error: ReturnType<typeof serializeError> | undefined;
+    let type: "response:result" | "response:error";
+    try {
+      result = await handler(params);
+      type = "response:result";
+    } catch (e) {
+      error = serializeError(e);
+      type = "response:error";
+    }
+    port.postMessage({ callId, channelName, type, result, error });
+  };
+  port.addEventListener("message", onMessage);
+  return () => port.removeEventListener("message", onMessage);
+}