@tlockney/cdp-kernel 0.5.0 → 0.7.0

package/dist/traceback.js

@@ -0,0 +1,200 @@
+// Structured tracebacks (#322): an error's stack as frames a frontend can
+// render, link to cells and fold, alongside the classic `traceback` lines.
+// The payload follows nteract's application/vnd.nteract.traceback+json
+// (runtimed/runt, docs/adr/traceback-output-protocol.md): ename, evalue,
+// frames with a source window and a `library` flag, and a plain `text`
+// rendering. Building it must never cost the user their traceback: callers
+// fall back to the classic lines if it throws.
+//
+// Cells run under a //# sourceURL naming them (cellName), so a frame in a
+// cell, including one in a function an earlier cell defined, says which
+// cell. Its line goes through the cell's source map, as for the debugger
+// (src/sourcemap.ts), so it is the line the user wrote, not the line of the
+// stripped JavaScript. Only lines are mapped: a cell frame has no column.
+//
+// Nothing here imports Node; reading other files' source is the caller's.
+import { murmur2 } from "./murmur2.js";
+export const TRACEBACK_MIME = "application/vnd.nteract.traceback+json";
+/** Lines of source shown around a frame's line. */
+const CONTEXT_BEFORE = 2;
+const CONTEXT_AFTER = 2;
+/** Longer stacks keep their first and last frames. */
+const HEAD_FRAMES = 20;
+const TAIL_FRAMES = 10;
+/** The //# sourceURL a cell's script runs under while not debugging. */
+export function cellName(code) {
+    return `$cdpk$cell-${murmur2(code, 0).toString(36)}.ts`;
+}
+// V8: "    at fn (file:1:2)", "    at file:1:2", "    at async fn (file:1:2)",
+// "    at new Promise (<anonymous>)".
+const V8_FRAME = /^\s*at (?:(.*?) \((.*?)(?::(\d+):(\d+))?\)|(.*?)(?::(\d+):(\d+))?)$/;
+// JavaScriptCore and SpiderMonkey: "fn@file:1:2", "@file:1:2", "fn@[native code]".
+const AT_FRAME = /^([^\s@]*)@(.+?)(?::(\d+):(\d+))?$/;
+/** One line of a stack as a frame, or null for a line that isn't one (the message). */
+export function parseFrame(text) {
+    const v8 = /^\s*at /.test(text) ? V8_FRAME.exec(text) : null;
+    if (v8) {
+        const named = v8[2] !== undefined;
+        const line = named ? v8[3] : v8[6];
+        const column = named ? v8[4] : v8[7];
+        return {
+            name: named ? v8[1] : "",
+            file: named ? v8[2] : v8[5],
+            line: line === undefined ? null : Number(line),
+            column: column === undefined ? null : Number(column),
+        };
+    }
+    const at = !/^\s/.test(text) && text.includes("@") ? AT_FRAME.exec(text) : null;
+    if (at) {
+        return {
+            name: at[1],
+            file: at[2],
+            line: at[3] === undefined ? null : Number(at[3]),
+            column: at[4] === undefined ? null : Number(at[4]),
+        };
+    }
+    return null;
+}
+/**
+ * Frames from packages, runtimes and the kernel itself, which a frontend
+ * can dim or fold: a hint, not a boundary.
+ */
+export function isLibraryFile(file, kernelFiles = []) {
+    if (["", "<anonymous>", "native", "[native code]", "unknown"].includes(file))
+        return true;
+    if (/^(?:node|ext|deno|bun|jsr|npm|internal):/.test(file))
+        return true;
+    if (/^https?:\/\/(?:jsr\.io|esm\.sh|cdn\.jsdelivr\.net|unpkg\.com|deno\.land)\//.test(file))
+        return true;
+    const path = file.replaceAll("\\", "/");
+    if (path.includes("/node_modules/") || path.includes("/npm/registry.npmjs.org/"))
+        return true;
+    return kernelFiles.some((prefix) => path.startsWith(prefix));
+}
+function window(source, line) {
+    const all = source.split("\n");
+    if (all.length > 1 && all[all.length - 1] === "")
+        all.pop();
+    const out = [];
+    for (let n = Math.max(1, line - CONTEXT_BEFORE); n <= Math.min(all.length, line + CONTEXT_AFTER); n++) {
+        const entry = { lineno: n, source: all[n - 1].replace(/\r$/, "") };
+        if (n === line)
+            entry.highlight = true;
+        out.push(entry);
+    }
+    return out;
+}
+/** How a cell frame's location reads in the classic traceback. */
+function cellLabel(cell) {
+    return cell.executionCount === null ? "cell" : `In[${cell.executionCount}]`;
+}
+/**
+ * `stack` is the error's stack as the target describes it (src/target.ts's
+ * describeError), message lines included. `callFrames`, from CDP, name the
+ * scripts of frames the stack shows as "<anonymous>": Deno formats stacks
+ * itself and doesn't use a script's //# sourceURL.
+ */
+export function buildTraceback(error, sources, execution) {
+    const raw = error.stack || `${error.ename}: ${error.evalue}`;
+    const lines = [];
+    const frames = [];
+    const callFrames = error.callFrames ?? [];
+    let next = 0;
+    for (const text of raw.split("\n")) {
+        const parsed = parseFrame(text);
+        if (parsed === null) {
+            lines.push(text);
+            continue;
+        }
+        let file = parsed.file;
+        if (parsed.line !== null) {
+            // CDP lists only frames with a position, in the same order.
+            const at = callFrames.findIndex((frame, i) => i >= next && frame.lineNumber + 1 === parsed.line && frame.columnNumber + 1 === parsed.column);
+            if (at !== -1) {
+                next = at + 1;
+                if (file === "<anonymous>" && callFrames[at].url)
+                    file = callFrames[at].url;
+            }
+        }
+        const cell = sources.cell(file);
+        if (cell !== undefined && parsed.line !== null) {
+            // Script lines are 1-based; the map's are 0-based.
+            const lineno = cell.lines ? cell.lines.toOriginal(parsed.line - 1) + 1 : parsed.line;
+            const frame = {
+                filename: cellLabel(cell),
+                lineno,
+                name: parsed.name,
+                library: false,
+                lines: window(cell.code, lineno),
+            };
+            if (cell.executionCount !== null)
+                frame.execution_count = cell.executionCount;
+            if (cell.cellId !== null)
+                frame.cell_id = cell.cellId;
+            frame.source_ref = {
+                kind: "notebook_execution",
+                ...(cell.executionCount !== null ? { execution_count: cell.executionCount } : {}),
+                ...(cell.cellId !== null ? { cell_id: cell.cellId } : {}),
+            };
+            frames.push(frame);
+            const location = `${cellLabel(cell)}:${lineno}`;
+            lines.push(rewriteLocation(text, parsed, location));
+            continue;
+        }
+        lines.push(text);
+        const library = isLibraryFile(file, sources.kernelFiles);
+        const frame = {
+            filename: file,
+            lineno: parsed.line ?? 0,
+            name: parsed.name,
+            library,
+            lines: [],
+        };
+        if (parsed.column !== null)
+            frame.colno = parsed.column;
+        if (!library && parsed.line !== null) {
+            const source = sources.readFile?.(file);
+            if (source !== undefined)
+                frame.lines = window(source, parsed.line);
+        }
+        frames.push(frame);
+    }
+    // What ran the cell (the kernel's evaluator, the runtime's own frames)
+    // comes after the cell's last frame and is never the user's.
+    const lastCell = frames.findLastIndex((frame) => frame.source_ref !== undefined);
+    let end = frames.length;
+    while (end > lastCell + 1 && lastCell !== -1 && frames[end - 1].library)
+        end--;
+    const kept = clip(frames.slice(0, end));
+    const payload = {
+        ename: error.ename,
+        evalue: error.evalue,
+        language: "typescript",
+        frames: kept,
+        syntax: null,
+        text: lines.join("\n"),
+        raw_text: raw,
+    };
+    if (execution.executionCount !== null || execution.cellId !== null) {
+        payload.execution = {
+            ...(execution.executionCount !== null ? { execution_count: execution.executionCount } : {}),
+            ...(execution.cellId !== null ? { cell_id: execution.cellId } : {}),
+        };
+    }
+    return { lines, payload };
+}
+function rewriteLocation(text, frame, location) {
+    const original = `${frame.file}:${frame.line}${frame.column === null ? "" : `:${frame.column}`}`;
+    const at = text.lastIndexOf(original);
+    return at === -1 ? text : text.slice(0, at) + location + text.slice(at + original.length);
+}
+function clip(frames) {
+    if (frames.length <= HEAD_FRAMES + TAIL_FRAMES)
+        return frames;
+    const omitted = frames.length - HEAD_FRAMES - TAIL_FRAMES;
+    return [
+        ...frames.slice(0, HEAD_FRAMES),
+        { filename: "", lineno: 0, name: `… ${omitted} frames omitted …`, library: true, lines: [] },
+        ...frames.slice(-TAIL_FRAMES),
+    ];
+}

package/dist/transform.d.ts

@@ -1,5 +1,6 @@
 import { LineMap } from "./sourcemap.ts";
 export declare const SHIM = "__cdpk";
+export declare const YIELD = "await __cdpk.tick();\n";
 /**
  * Each replMode cell also ends by yielding one macrotask, so the script
  * settles with no other microtasks queued ahead of the inspector's
@@ -29,14 +30,34 @@ export type JsxOptions = {
 export interface CellTransformOptions {
     jsx?: JsxOptions;
     experimentalDecorators?: boolean;
+    /** What removes a cell's types and compiles its JSX; esbuild by default (#238, #234). */
+    typeStrip?: TypeStripperName | TypeStripper;
 }
+/**
+ * Turns a TypeScript/TSX cell into JavaScript with ES module syntax left in
+ * place, and with `mappings` (a source map's field, lines are enough) when
+ * `sourcemap` is set, for the debugger. Throws CellSyntaxError for code it
+ * rejects.
+ */
+export type TypeStripper = (code: string, options: CellTransformOptions, sourcemap: boolean) => {
+    code: string;
+    mappings: string;
+};
+export type TypeStripperName = "esbuild" | "sucrase";
+export declare function isTypeStripperName(value: unknown): value is TypeStripperName;
+/**
+ * Loads a built-in type stripper. Transforms are synchronous, so a kernel
+ * loads the one it uses before its first cell; only that one's module is
+ * imported (#238).
+ */
+export declare function loadTypeStripper(name: TypeStripperName): Promise<TypeStripper>;
 /** Rewrites module-only syntax in plain JavaScript into script syntax. */
 export declare function rewriteModuleSyntax(js: string): string;
 export declare function transformCell(code: string, options?: CellTransformOptions): string;
 /**
  * transformCell, plus the map between the cell's lines and the script's,
  * for the debugger (#18). The rewrite keeps lines (see applyEdits), so the
- * script's lines are esbuild's, after the prelude's one.
+ * script's lines are the stripper's, after the prelude's one.
  */
 export declare function transformCellWithLines(code: string, options?: CellTransformOptions): {
     script: string;

package/dist/transform.js

@@ -2,9 +2,9 @@
 // CDP's Runtime.evaluate can run with replMode: true.
 //
 // Deno does this with deno_ast (swc) and `var_decl_imports: true`
-// (cli/tools/repl/session.rs, evaluate_ts_expression). Here esbuild does the
-// TypeScript/JSX part and acorn finds the module syntax that a script can't
-// contain:
+// (cli/tools/repl/session.rs, evaluate_ts_expression). Here a type stripper
+// (esbuild by default) does the TypeScript/JSX part and acorn finds the
+// module syntax that a script can't contain:
 //   import x, { y as z } from "m"  ->  var __cdpk_m0 = await __cdpk.import("m");
 //                                     var x = __cdpk_m0["default"], z = __cdpk_m0["y"];
 //   import("m")                    ->  __cdpk.import("m")
@@ -14,7 +14,6 @@
 // import() through it matters: code evaluated over the inspector has no
 // module referrer, so Node rejects a bare import() ("A dynamic import
 // callback was not specified").
-import { transformSync } from "esbuild";
 import { parse } from "acorn";
 import { full, recursive } from "acorn-walk";
 import { LineMap } from "./sourcemap.js";
@@ -24,7 +23,14 @@ export const SHIM = "__cdpk";
 // which is what lets a Runtime.terminateExecution from the control session
 // interrupt a busy loop. (Within that dispatch the inspector processes no
 // other messages, so an interrupt would never be seen.)
-const PRELUDE = `'use strict'; await ${SHIM}.tick();\n`;
+//
+// An expression that throws before its first await rejects the replMode
+// result promise at once, inside that dispatch, and a GC before the
+// inspector's then-callback runs fails the evaluate with "Promise was
+// collected" (#329). Yielding first moves the throw into a task, where
+// SETTLE's reasoning applies. The debug console uses YIELD for this.
+export const YIELD = `await ${SHIM}.tick();\n`;
+const PRELUDE = `'use strict'; ${YIELD}`;
 /**
  * Each replMode cell also ends by yielding one macrotask, so the script
  * settles with no other microtasks queued ahead of the inspector's
@@ -37,51 +43,48 @@ export const SETTLE = `\n;let ${SHIM}_settled = await ${SHIM}.tick();`;
 export class CellSyntaxError extends Error {
     name = "SyntaxError";
 }
-function jsxSettings(jsx) {
-    if (jsx?.mode === "automatic") {
-        return { jsx: "automatic", jsxImportSource: jsx.importSource, jsxDev: jsx.development };
+export function isTypeStripperName(value) {
+    return value === "esbuild" || value === "sucrase";
+}
+const strippers = new Map();
+/**
+ * Loads a built-in type stripper. Transforms are synchronous, so a kernel
+ * loads the one it uses before its first cell; only that one's module is
+ * imported (#238).
+ */
+export async function loadTypeStripper(name) {
+    let stripper = strippers.get(name);
+    if (stripper === undefined) {
+        try {
+            stripper = name === "sucrase"
+                ? (await import("./strip-sucrase.js")).stripTypes
+                : (await import("./strip-esbuild.js")).stripTypes;
+        }
+        catch (err) {
+            const reason = err instanceof Error ? err.message : String(err);
+            throw new Error(`cannot load the ${name} type stripper (is the ${name} package installed?): ${reason}`);
+        }
+        strippers.set(name, stripper);
     }
-    return { jsx: "transform", jsxFactory: jsx?.factory, jsxFragment: jsx?.fragment };
+    return stripper;
+}
+function typeStripper(choice = "esbuild") {
+    if (typeof choice === "function")
+        return choice;
+    const stripper = strippers.get(choice);
+    if (stripper === undefined)
+        throw new Error(`the ${choice} type stripper isn't loaded (see loadTypeStripper)`);
+    return stripper;
 }
 // esbuild compiles `import x = require("m")` to a `require` call, which a
 // cell doesn't have (#143); `import type x = require("m")` is erased.
 const IMPORT_REQUIRE = /^\s*(?:export\s+)?import\s+(?!type\s)[\w$]+\s*=\s*require\s*\(/m;
-/** esbuild's output, with its source map's `mappings` when asked for. */
+/** The stripper's output, with its source map's `mappings` when asked for. */
 function stripTypesMapped(code, options, sourcemap) {
     if (IMPORT_REQUIRE.test(code)) {
         throw new CellSyntaxError('import x = require("m") is not supported in a cell; use import x from "m"');
     }
-    const compilerOptions = {
-        verbatimModuleSyntax: true,
-        ...(options.experimentalDecorators ? { experimentalDecorators: true } : {}),
-    };
-    // Like Deno: prefer TSX, fall back to TS for `<T>x` assertions.
-    let firstError;
-    for (const loader of ["tsx", "ts"]) {
-        try {
-            const result = transformSync(code, {
-                loader,
-                target: "esnext",
-                // Neither acorn nor V8 parses standard (TC39) decorators or
-                // `accessor` yet, so esbuild lowers them (#142).
-                supported: { decorators: false },
-                ...jsxSettings(options.jsx),
-                tsconfigRaw: { compilerOptions },
-                logLevel: "silent",
-                ...(sourcemap ? { sourcemap: "external" } : {}),
-            });
-            const map = sourcemap ? JSON.parse(result.map) : null;
-            const mappings = typeof map?.mappings === "string"
-                ? map.mappings
-                : "";
-            return { code: result.code, mappings };
-        }
-        catch (err) {
-            firstError ??= err;
-        }
-    }
-    const message = firstError instanceof Error ? firstError.message : String(firstError);
-    throw new CellSyntaxError(message.replace(/^Transform failed with \d+ errors?:\n/, ""));
+    return typeStripper(options.typeStrip)(code, options, sourcemap);
 }
 function stripTypes(code, options) {
     return stripTypesMapped(code, options, false).code;
@@ -321,11 +324,11 @@ export function transformCell(code, options = {}) {
 /**
  * transformCell, plus the map between the cell's lines and the script's,
  * for the debugger (#18). The rewrite keeps lines (see applyEdits), so the
- * script's lines are esbuild's, after the prelude's one.
+ * script's lines are the stripper's, after the prelude's one.
  */
 export function transformCellWithLines(code, options = {}) {
     const stripped = stripTypesMapped(code, options, true);
-    return { script: PRELUDE + rewriteModuleSyntax(stripped.code) + SETTLE, lines: new LineMap(stripped.mappings, newlines(PRELUDE)) };
+    return { script: PRELUDE + rewriteModuleSyntax(stripped.code) + SETTLE, lines: new LineMap(stripped.mappings, newlines(PRELUDE), stripped.code) };
 }
 /**
  * Like transformCell, for a target that evaluates cells itself, as global

package/dist/wire.d.ts

@@ -1,35 +1,15 @@
+import { type Header, type JsonObject, type KernelMessage } from "./message.ts";
+export { makeHeader, PROTOCOL_VERSION } from "./message.ts";
+export type { Header, JsonObject, ReceivedHeader } from "./message.ts";
 export declare const DELIMITER: Uint8Array<ArrayBuffer>;
-export declare const PROTOCOL_VERSION = "5.3";
-export type JsonObject = {
-    [key: string]: unknown;
-};
-export interface Header extends JsonObject {
-    msg_id: string;
-    session: string;
-    date: string;
-    username: string;
-    msg_type: string;
-    version: string;
-}
-/** A header as received: the fields the kernel relies on, plus whatever else came. */
-export interface ReceivedHeader extends JsonObject {
-    msg_id: string;
-    msg_type: string;
-}
-export interface Message {
+export interface Message extends KernelMessage {
     identities: Uint8Array[];
     sig: string;
     /** Raw bytes of header, parent_header, metadata, content as received. */
     signedParts: Uint8Array[];
-    header: ReceivedHeader;
-    parentHeader: JsonObject;
-    metadata: JsonObject;
-    content: JsonObject;
-    buffers: Uint8Array[];
 }
 export declare function sign(key: string, parts: Uint8Array[]): string;
 export declare function verify(key: string, parts: Uint8Array[], sig: string): boolean;
-export declare function makeHeader(session: string, msgType: string): Header;
 export interface EncodeOptions {
     /** Defaults to a fresh header; pass one to know its msg_id. */
     header?: Header;

package/dist/wire.js

@@ -4,11 +4,12 @@
 // Copyright 2018-2026 the Deno authors, MIT license. The structure is kept;
 // WebCrypto's async HMAC is replaced with node:crypto's synchronous one.
 import { Buffer } from "node:buffer";
-import { createHmac, randomUUID, timingSafeEqual } from "node:crypto";
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { makeHeader } from "./message.js";
+export { makeHeader, PROTOCOL_VERSION } from "./message.js";
 const ENC = new TextEncoder();
 const DEC = new TextDecoder();
 export const DELIMITER = ENC.encode("<IDS|MSG>");
-export const PROTOCOL_VERSION = "5.3";
 export function sign(key, parts) {
     if (key.length === 0)
         return "";
@@ -29,16 +30,6 @@ export function verify(key, parts, sig) {
     const actual = Buffer.from(sig, "hex");
     return expected.length === actual.length && timingSafeEqual(expected, actual);
 }
-export function makeHeader(session, msgType) {
-    return {
-        msg_id: randomUUID(),
-        session,
-        date: new Date().toISOString(),
-        username: "kernel",
-        msg_type: msgType,
-        version: PROTOCOL_VERSION,
-    };
-}
 export function encodeMessage(session, key, msgType, content, options = {}) {
     const parts = [
         options.header ?? makeHeader(session, msgType),

package/dist/workerd-target.js

@@ -263,7 +263,7 @@ export class RawWorkerd {
         killOnExit(child, () => {
             child.kill("SIGKILL");
             rmSync(dir, { recursive: true, force: true });
-        });
+        }, { dir });
         // Cell output is captured inside the Worker; what workerd itself prints
         // (its own warnings, errors from background work) goes to the server log.
         // `early` keeps that output for a startup error only, and stops growing

package/dist/workers-project.js

@@ -9,11 +9,13 @@
 // bundled next to the driver, so its Durable Object classes are exported
 // from the same Worker. Neither wrangler nor Miniflare is a dependency of
 // cdp-kernel: they're loaded from the project, so they match its version.
+import process from "node:process";
 import { builtinModules, createRequire } from "node:module";
 import { randomBytes } from "node:crypto";
 import { existsSync, readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { build } from "esbuild";
+import { childPids, reap } from "./children.js";
 import { runtimeDir } from "./package.js";
 import { cellMeta, WORKER_MODULES } from "./workerd-target.js";
 export const WRANGLER_CONFIGS = ["wrangler.jsonc", "wrangler.json", "wrangler.toml"];
@@ -128,8 +130,12 @@ class MiniflareHost {
     #mf;
     #exitListeners = [];
     #stopped = false;
-    constructor(mf, channel, version, project) {
+    #forget;
+    constructor(mf, channel, version, project, workerd) {
         this.#mf = mf;
+        // Miniflare kills its workerd only on a normal exit; the helper in
+        // src/children.ts kills it if this process is SIGKILLed (#241).
+        this.#forget = workerd.map(reap);
         this.channel = channel;
         this.runtime = `miniflare ${version}`.trim();
         this.project = project;
@@ -140,6 +146,8 @@ class MiniflareHost {
         this.#stopped = true;
         // dispose() ends workerd even mid-cell.
         void this.#mf.dispose().catch(() => { }).finally(() => {
+            for (const forget of this.#forget)
+                forget();
             for (const listener of this.#exitListeners)
                 listener(null);
         });
@@ -178,6 +186,8 @@ export async function startMiniflare(configPath, cwd) {
         // Miniflare 5 renamed Miniflare 4's defaultPersistRoot.
         ...(v5 ? { resourcePersistencePath: state } : { defaultPersistRoot: state }),
     };
+    // Miniflare's workerd is this process's child; it doesn't say which.
+    const before = new Set(childPids(process.pid, "workerd"));
     const mf = new miniflare.Miniflare(v5 && miniflare.convertV4MiniflareOptions ? miniflare.convertV4MiniflareOptions(options) : options);
     try {
         await mf.ready;
@@ -186,7 +196,8 @@ export async function startMiniflare(configPath, cwd) {
         const res = await mf.dispatchFetch("http://cdpk/", { headers: { Upgrade: "websocket", "x-cdpk-token": token } });
         if (res.status !== 101 || res.webSocket === null)
             throw new Error(`the driver answered ${res.status}: ${await res.text()}`);
-        return new MiniflareHost(mf, channelOf(res.webSocket), version, configPath);
+        const workerd = childPids(process.pid, "workerd").filter((pid) => !before.has(pid));
+        return new MiniflareHost(mf, channelOf(res.webSocket), version, configPath, workerd);
     }
     catch (err) {
         await mf.dispose().catch(() => { });

package/dist/zmq-channels.d.ts

@@ -0,0 +1,14 @@
+import type { ConnectionInfo } from "./kernel.ts";
+import type { ChannelName, KernelChannels, Received } from "./kernel-core.ts";
+import type { OutgoingMessage } from "./message.ts";
+export declare class ZmqChannels implements KernelChannels {
+    #private;
+    readonly ready: Promise<unknown>;
+    constructor(conn: ConnectionInfo, log: (text: string) => void);
+    recv(channel: ChannelName): Promise<Received | null>;
+    shellQueued(): number;
+    reply(channel: ChannelName, peer: string, msg: OutgoingMessage): void;
+    publish(msg: OutgoingMessage): void;
+    stdinPeers(): number;
+    sendStdin(msg: OutgoingMessage): void;
+}

package/dist/zmq-channels.js

@@ -0,0 +1,59 @@
+// KernelChannels over ZeroMQ: the connection file's five ports, with
+// messages framed and signed as src/wire.ts does it.
+import { decodeMessage, encodeMessage, verify } from "./wire.js";
+import { listening, PubSocket, RouterSocket, startHeartbeat } from "./zmtp.js";
+export class ZmqChannels {
+    ready;
+    #key;
+    #log;
+    #routers;
+    #iopub;
+    constructor(conn, log) {
+        this.#key = conn.key;
+        this.#log = log;
+        const heartbeat = startHeartbeat(conn.hb_port, conn.ip);
+        this.#routers = {
+            shell: new RouterSocket(conn.shell_port, conn.ip),
+            control: new RouterSocket(conn.control_port, conn.ip),
+            stdin: new RouterSocket(conn.stdin_port, conn.ip),
+        };
+        this.#iopub = new PubSocket(conn.iopub_port, conn.ip);
+        // Settles once all five ports are bound (#257).
+        this.ready = Promise.all([heartbeat, ...Object.values(this.#routers).map((r) => r.server), this.#iopub.server].map(listening));
+    }
+    async recv(channel) {
+        const { peer, frames } = await this.#routers[channel].recv();
+        try {
+            const msg = decodeMessage(frames);
+            // Unsigned or forged messages are dropped, as in Deno.
+            return verify(this.#key, msg.signedParts, msg.sig) ? { peer, msg } : null;
+        }
+        catch (err) {
+            this.#log(`error handling message: ${err instanceof Error ? err.stack : err}`);
+            return null;
+        }
+    }
+    shellQueued() {
+        return this.#routers.shell.incoming.size;
+    }
+    #encode(msg) {
+        return encodeMessage(msg.header.session, this.#key, msg.header.msg_type, msg.content, {
+            header: msg.header,
+            parentHeader: msg.parentHeader,
+            metadata: msg.metadata,
+            buffers: msg.buffers,
+        });
+    }
+    reply(channel, peer, msg) {
+        this.#routers[channel].send(peer, this.#encode(msg));
+    }
+    publish(msg) {
+        this.#iopub.send(this.#encode(msg));
+    }
+    stdinPeers() {
+        return this.#routers.stdin.peers.size;
+    }
+    sendStdin(msg) {
+        this.#routers.stdin.sendAll(this.#encode(msg));
+    }
+}

package/dist/zmtp.d.ts

@@ -25,6 +25,8 @@ export declare class Queue<T> {
     push(item: T): void;
     pop(): Promise<T>;
 }
+/** Resolves once `server` is listening, after any retries. */
+export declare function listening(server: Server): Promise<void>;
 /** REP socket for the heartbeat channel: echo everything. */
 export declare function startHeartbeat(port: number, host: string): Server;
 export interface RoutedMessage {

package/dist/zmtp.js

@@ -8,6 +8,8 @@
 import { Buffer } from "node:buffer";
 import { createServer } from "node:net";
 import { randomBytes } from "node:crypto";
+import process from "node:process";
+import { portHolders } from "./port-holder.js";
 const ENC = new TextEncoder();
 /** Pull-style reader over a socket's 'data' events. */
 export class SocketReader {
@@ -154,6 +156,12 @@ function listen(port, host, onConn) {
     const deadline = Date.now() + LISTEN_RETRY_MS;
     const onError = (err) => {
         if (err.code !== "EADDRINUSE" || Date.now() >= deadline) {
+            // Who kept it, for a port that never came free (#257).
+            if (err.code === "EADDRINUSE") {
+                const holders = portHolders(port).map((line) => `  ${line}\n`).join("") || "  unknown\n";
+                process.stderr.write(`[cdp-kernel] port ${port} still in use after ${LISTEN_RETRY_MS} ms; this kernel is pid ${process.pid} ` +
+                    `(ppid ${process.ppid}, ${process.execPath} ${process.version}); the port's sockets:\n${holders}`);
+            }
             server.off("error", onError);
             server.emit("error", err);
             return;
@@ -187,6 +195,10 @@ export class Queue {
         return new Promise((resolve) => this.#waiters.push(resolve));
     }
 }
+/** Resolves once `server` is listening, after any retries. */
+export function listening(server) {
+    return server.listening ? Promise.resolve() : new Promise((resolve) => server.once("listening", () => resolve()));
+}
 /** REP socket for the heartbeat channel: echo everything. */
 export function startHeartbeat(port, host) {
     return listen(port, host, (socket) => {