@tlockney/cdp-kernel 0.4.0 → 0.6.0

package/dist/ws-client.js

@@ -2,13 +2,14 @@
 // target's session with its driver Worker (#26). The WebSocket that Node
 // and Deno provide can't connect to a Unix socket, and a TCP listener would
 // be reachable by every local process. Text messages only: that's all the
-// session carries.
+// session carries, so binary messages are dropped.
 import { Buffer } from "node:buffer";
 import { createHash, randomBytes } from "node:crypto";
 import { connect } from "node:net";
 const GUID = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11";
 export const OP_CONTINUATION = 0x0;
 export const OP_TEXT = 0x1;
+export const OP_BINARY = 0x2;
 export const OP_CLOSE = 0x8;
 export const OP_PING = 0x9;
 export const OP_PONG = 0xa;
@@ -40,14 +41,24 @@ export function encodeFrame(opcode, payload, mask = randomBytes(4)) {
     }
     return out;
 }
-/** Splits a byte stream into frames, holding back a partial one. */
+/**
+ * Splits a byte stream into frames, holding back a partial one. Chunks of a
+ * large frame are only joined once the whole frame has arrived.
+ */
 export class FrameDecoder {
-    #buffer = Buffer.alloc(0);
+    #chunks = [];
+    #length = 0;
+    /** Bytes the frame at the front needs, once its header is known. */
+    #needed = 0;
     push(chunk) {
-        this.#buffer = Buffer.concat([this.#buffer, chunk]);
+        this.#chunks.push(chunk);
+        this.#length += chunk.length;
+        if (this.#length < this.#needed)
+            return [];
+        let b = this.#chunks.length === 1 ? this.#chunks[0] : Buffer.concat(this.#chunks, this.#length);
+        this.#needed = 0;
         const frames = [];
         for (;;) {
-            const b = this.#buffer;
             if (b.length < 2)
                 break;
             const masked = (b[1] & 0x80) !== 0;
@@ -68,15 +79,19 @@ export class FrameDecoder {
             const maskAt = offset;
             if (masked)
                 offset += 4;
-            if (b.length < offset + len)
+            if (b.length < offset + len) {
+                this.#needed = offset + len;
                 break;
+            }
             const payload = Buffer.from(b.subarray(offset, offset + len));
             if (masked)
                 for (let i = 0; i < len; i++)
                     payload[i] ^= b[maskAt + (i & 3)];
             frames.push({ fin: (b[0] & 0x80) !== 0, opcode: b[0] & 0x0f, payload });
-            this.#buffer = b.subarray(offset + len);
+            b = b.subarray(offset + len);
         }
+        this.#chunks = b.length ? [b] : [];
+        this.#length = b.length;
         return frames;
     }
 }
@@ -95,6 +110,9 @@ export function connectUnixWebSocket(socketPath, { path = "/", headers = {} } =
         let head = Buffer.alloc(0);
         const decoder = new FrameDecoder();
         let parts = [];
+        // The opcode of the message whose fragments are arriving.
+        let messageOpcode = null;
+        let closeSent = false;
         const finish = () => {
             if (closed)
                 return;
@@ -108,30 +126,45 @@ export function connectUnixWebSocket(socketPath, { path = "/", headers = {} } =
             if (!closed)
                 socket.write(encodeFrame(opcode, payload));
         };
+        const sendClose = (payload) => {
+            if (closeSent)
+                return;
+            closeSent = true;
+            write(OP_CLOSE, payload);
+        };
         const channel = {
             send: (text) => write(OP_TEXT, Buffer.from(text)),
             onMessage: (listener) => void messageListeners.push(listener),
             onClose: (listener) => void closeListeners.push(listener),
             close() {
-                write(OP_CLOSE, Buffer.alloc(0));
+                sendClose(Buffer.alloc(0));
                 socket.end();
             },
         };
         const onFrames = (frames) => {
             for (const frame of frames) {
-                if (frame.opcode === OP_TEXT || frame.opcode === OP_CONTINUATION) {
-                    parts.push(frame.payload);
+                if (frame.opcode === OP_TEXT || frame.opcode === OP_BINARY || frame.opcode === OP_CONTINUATION) {
+                    if (frame.opcode !== OP_CONTINUATION) {
+                        messageOpcode = frame.opcode;
+                        parts = [];
+                    }
+                    if (messageOpcode === OP_TEXT)
+                        parts.push(frame.payload);
                     if (frame.fin) {
-                        const text = Buffer.concat(parts).toString("utf8");
+                        const text = messageOpcode === OP_TEXT ? Buffer.concat(parts).toString("utf8") : null;
                         parts = [];
-                        for (const listener of messageListeners)
-                            listener(text);
+                        messageOpcode = null;
+                        if (text !== null)
+                            for (const listener of messageListeners)
+                                listener(text);
                     }
                 }
                 else if (frame.opcode === OP_PING) {
                     write(OP_PONG, frame.payload);
                 }
                 else if (frame.opcode === OP_CLOSE) {
+                    // Echo the status code, as RFC 6455 section 5.5.1 asks.
+                    sendClose(frame.payload.subarray(0, 2));
                     socket.end();
                 }
             }

package/dist/zmtp.d.ts

@@ -20,16 +20,24 @@ export declare function recvMultipart(reader: SocketReader): Promise<Uint8Array[
 /** Async FIFO with blocking pop. */
 export declare class Queue<T> {
     #private;
+    /** Items waiting to be popped. */
+    get size(): number;
     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 {
     peer: string;
     frames: Uint8Array[];
 }
-/** ROUTER socket: each TCP connection is one peer with a generated identity. */
+/**
+ * ROUTER socket: each TCP connection is one peer with a generated identity.
+ * Writes ignore socket.write's backpressure signal: node:net buffers the
+ * rest, which is fine for loopback peers that read promptly.
+ */
 export declare class RouterSocket {
     #private;
     readonly incoming: Queue<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 {
@@ -36,6 +38,10 @@ export class SocketReader {
         this.#waiter = null;
         waiter?.();
     }
+    // Each call joins every buffered chunk, so a reader that keeps a large
+    // backlog while small chunks trickle in recopies it per call (quadratic).
+    // Jupyter traffic over loopback arrives in few, large chunks; a chunk
+    // list with an offset would avoid the copies if that ever changes.
     async readExact(n) {
         while (this.#buffered < n) {
             if (this.#error)
@@ -136,11 +142,34 @@ export async function recvMultipart(reader) {
             return frames;
     }
 }
+/** How long a port from the connection file may stay taken before the kernel gives up. */
+const LISTEN_RETRY_MS = 5000;
+const LISTEN_RETRY_INTERVAL_MS = 100;
 function listen(port, host, onConn) {
     const server = createServer((socket) => {
         socket.setNoDelay(true);
         onConn(socket);
     });
+    // The frontend picks these ports by binding and releasing them, so another
+    // socket can take one before the kernel binds it. Wait for it to be freed
+    // rather than die before kernel_info.
+    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;
+        }
+        setTimeout(() => server.listen(port, host), LISTEN_RETRY_INTERVAL_MS);
+    };
+    server.on("error", onError);
+    server.once("listening", () => server.off("error", onError));
     server.listen(port, host);
     return server;
 }
@@ -148,6 +177,10 @@ function listen(port, host, onConn) {
 export class Queue {
     #items = [];
     #waiters = [];
+    /** Items waiting to be popped. */
+    get size() {
+        return this.#items.length;
+    }
     push(item) {
         const waiter = this.#waiters.shift();
         if (waiter)
@@ -162,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) => {
@@ -173,7 +210,11 @@ export function startHeartbeat(port, host) {
         })().catch(() => socket.destroy());
     });
 }
-/** ROUTER socket: each TCP connection is one peer with a generated identity. */
+/**
+ * ROUTER socket: each TCP connection is one peer with a generated identity.
+ * Writes ignore socket.write's backpressure signal: node:net buffers the
+ * rest, which is fine for loopback peers that read promptly.
+ */
 export class RouterSocket {
     incoming = new Queue();
     peers = new Map();

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tlockney/cdp-kernel",
-  "version": "0.4.0",
-  "description": "Deno's Jupyter kernel, extracted to run notebooks on any V8 runtime over the Chrome DevTools Protocol",
+  "version": "0.6.0",
+  "description": "Deno's Jupyter kernel, extracted to run notebooks on Node, Deno, Bun, workerd and celld",
   "license": "MIT",
   "author": "Thomas Lockney <thomas@lockney.net>",
   "repository": {
@@ -20,7 +20,7 @@
   ],
   "type": "module",
   "engines": {
-    "node": ">=24"
+    "node": ">=22.18"
   },
   "bin": {
     "cdp-kernel": "dist/main.js"
@@ -42,7 +42,8 @@
   "files": [
     "dist/",
     "runtime/*.mjs",
-    "runtime/*.d.mts"
+    "runtime/*.d.mts",
+    "THIRD-PARTY-NOTICES"
   ],
   "publishConfig": {
     "access": "public"
@@ -50,6 +51,10 @@
   "scripts": {
     "build": "rm -rf dist && tsc -p tsconfig.build.json",
     "check": "tsc -p tsconfig.json",
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs",
+    "docs:notebooks": "node docs/.vitepress/run-notebooks.ts",
+    "docs:widgets": "uv run --with jupyterlab --with anywidget --with playwright --with nbformat python test/widget_screenshots.py",
     "install:node": "node src/main.ts install --runtime node",
     "install:deno": "node src/main.ts install --runtime deno",
     "install:node-deno": "node src/main.ts install --runtime node --deno-compat",
@@ -59,17 +64,23 @@
     "prepack": "npm run build",
     "test": "node --test --test-timeout=300000 test/*.test.ts",
     "e2e": "uv run --with nbclient --with nbformat --with jupyter_client python test/e2e.py",
+    "bench": "uv run --with jupyter_client python test/bench.py",
+    "soak": "uv run --with jupyter_client python test/soak.py",
     "test:lab": "uv run --with jupyterlab --with anywidget --with playwright --with nbformat python test/lab_widgets.py"
   },
   "dependencies": {
     "acorn": "^8.15.0",
     "acorn-walk": "^8.3.4",
-    "esbuild": "^0.25.10"
+    "esbuild": "^0.25.10",
+    "typescript": "^6.0.3"
   },
   "devDependencies": {
     "@types/node": "^24.19.2",
-    "typescript": "^5.9.3",
+    "vitepress": "^1.6.4",
     "workerd": "1.20261015.1",
     "wrangler": "4.151.0"
+  },
+  "optionalDependencies": {
+    "sucrase": "^3.35.1"
   }
 }