@tlockney/cdp-kernel 0.5.0 → 0.7.0

package/README.md

@@ -10,9 +10,19 @@ inspector speaks CDP works too.
 **Website:** <https://cdp-kernel.org/> ·
 **Docs:** [cdp-kernel.org/docs](https://cdp-kernel.org/docs/)
 
+[![Try it on Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/tlockney/cdp-kernel/main?urlpath=lab/tree/getting-started.ipynb)
+[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/tlockney/cdp-kernel?quickstart=1)
+
+Binder opens JupyterLab with every runtime and the example notebooks,
+nothing installed. A Codespace does the same in VS Code, with the
+repository checked out ([Install › In a container](https://cdp-kernel.org/docs/install#in-a-container)).
+
 This is early software. It passes a conformance suite derived from Deno's
 own Jupyter integration tests on every target, and it's packaged for npm and
 JSR as `@tlockney/cdp-kernel`, but it hasn't seen much real use yet.
+The [support policy](https://cdp-kernel.org/docs/support) says which
+runtime versions and frontends are supported, and what may change before
+1.0.
 
 ## Features
 
@@ -29,7 +39,7 @@ JSR as `@tlockney/cdp-kernel`, but it hasn't seen much real use yet.
 
 ## Install
 
-Node 24+ host, from npm:
+Node 22.18+ host, from npm:
 
 ```sh
 npm install -g @tlockney/cdp-kernel
@@ -43,11 +53,19 @@ deno run -A jsr:@tlockney/cdp-kernel/cli install --runtime deno
 ```
 
 Each install writes a Jupyter kernelspec (`cdp-node`, `cdp-deno`, …). Pick
-it in JupyterLab or VS Code. Linux and macOS are supported; Windows isn't
-yet. See [Install](https://cdp-kernel.org/docs/install)
-for `--deno-compat`, release-day installs on Deno, target runtime
+it in JupyterLab or VS Code. To run notebooks with no Python installed,
+serve JupyterLab with
+[Ganymede](https://ganymede-server.com/docs/install). Linux and macOS
+are supported; Windows isn't yet. See
+[Install](https://cdp-kernel.org/docs/install) for `--deno-compat`, release-day installs on Deno, target runtime
 requirements, and installing from a checkout.
 
+JupyterLab with every runtime and the examples, in a container:
+
+```sh
+docker run --rm -p 8888:8888 ghcr.io/tlockney/cdp-kernel
+```
+
 ## Quick start
 
 ```ts
@@ -68,10 +86,13 @@ New to Jupyter? Start with
   [Widgets and comms](https://cdp-kernel.org/docs/widgets),
   [Debugger](https://cdp-kernel.org/docs/debugger)
 - Reference: [Editor types](https://cdp-kernel.org/docs/editor-types),
-  [Known gaps](https://cdp-kernel.org/docs/known-gaps)
+  [Known gaps](https://cdp-kernel.org/docs/known-gaps),
+  [Support policy](https://cdp-kernel.org/docs/support)
 - Internals: [Architecture](https://cdp-kernel.org/docs/architecture),
   [Runtime integrations](https://cdp-kernel.org/docs/integrations)
-- Contributing: [Development](https://cdp-kernel.org/docs/development)
+- Contributing: [CONTRIBUTING.md](CONTRIBUTING.md),
+  [Development](https://cdp-kernel.org/docs/development),
+  [Security policy](SECURITY.md)
 
 The [feasibility study](https://cdp-kernel.org/docs/feasibility-study)
 behind the project covers the design, the alternatives considered (workerd,

package/dist/browser/channels.d.ts

@@ -0,0 +1,27 @@
+import type { ChannelName, KernelChannels, Received } from "../kernel-core.ts";
+import type { JsonObject, OutgoingMessage } from "../message.ts";
+/** Every channel a message travels on, iopub included. */
+export type Channel = ChannelName | "iopub";
+/** A Jupyter message as JSON, the shape a frontend sends and receives. */
+export interface JupyterMessage {
+    header: JsonObject;
+    parent_header: JsonObject;
+    metadata: JsonObject;
+    content: JsonObject;
+    buffers?: (ArrayBuffer | ArrayBufferView)[];
+    channel?: string;
+}
+export type MessageListener = (channel: Channel, msg: JupyterMessage) => void;
+export declare class PageChannels implements KernelChannels {
+    #private;
+    readonly ready: Promise<unknown>;
+    /** A message from the frontend. One without a msg_id and msg_type is dropped. */
+    deliver(channel: ChannelName, msg: JupyterMessage): void;
+    onMessage(listener: MessageListener): () => 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/browser/channels.js

@@ -0,0 +1,90 @@
+// KernelChannels inside a page: the frontend hands the kernel messages in
+// Jupyter's JSON shape (as the websocket's JSON protocol and
+// @jupyterlab/services carry them) and gets messages back the same way.
+// There is one frontend, so one peer, and no signing.
+const PEER = "page";
+class Queue {
+    #items = [];
+    #waiters = [];
+    get size() {
+        return this.#items.length;
+    }
+    push(item) {
+        const waiter = this.#waiters.shift();
+        if (waiter)
+            waiter(item);
+        else
+            this.#items.push(item);
+    }
+    pop() {
+        const item = this.#items.shift();
+        if (item !== undefined)
+            return Promise.resolve(item);
+        return new Promise((resolve) => this.#waiters.push(resolve));
+    }
+}
+function bytes(buffer) {
+    return buffer instanceof ArrayBuffer ? new Uint8Array(buffer) : new Uint8Array(buffer.buffer, buffer.byteOffset, buffer.byteLength);
+}
+function isHeader(value) {
+    return typeof value.msg_id === "string" && typeof value.msg_type === "string";
+}
+function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export class PageChannels {
+    ready = Promise.resolve();
+    #queues = { shell: new Queue(), control: new Queue(), stdin: new Queue() };
+    #listeners = new Set();
+    /** A message from the frontend. One without a msg_id and msg_type is dropped. */
+    deliver(channel, msg) {
+        const { header, parent_header: parentHeader, metadata, content } = msg;
+        const valid = isObject(header) && isHeader(header) && isObject(content);
+        this.#queues[channel].push(valid
+            ? {
+                peer: PEER,
+                msg: {
+                    header,
+                    parentHeader: isObject(parentHeader) ? parentHeader : {},
+                    metadata: isObject(metadata) ? metadata : {},
+                    content,
+                    buffers: (msg.buffers ?? []).map(bytes),
+                },
+            }
+            : null);
+    }
+    onMessage(listener) {
+        this.#listeners.add(listener);
+        return () => this.#listeners.delete(listener);
+    }
+    #emit(channel, msg) {
+        const out = {
+            channel,
+            header: msg.header,
+            parent_header: msg.parentHeader,
+            metadata: msg.metadata,
+            content: msg.content,
+            buffers: msg.buffers,
+        };
+        for (const listener of this.#listeners)
+            listener(channel, out);
+    }
+    recv(channel) {
+        return this.#queues[channel].pop();
+    }
+    shellQueued() {
+        return this.#queues.shell.size;
+    }
+    reply(channel, _peer, msg) {
+        this.#emit(channel, msg);
+    }
+    publish(msg) {
+        this.#emit("iopub", msg);
+    }
+    stdinPeers() {
+        return 1;
+    }
+    sendStdin(msg) {
+        this.#emit("stdin", msg);
+    }
+}