@tlockney/cdp-kernel 0.7.2 → 0.9.0

package/dist/crash-reports.d.ts

@@ -0,0 +1,47 @@
+/** The cdp-kernel project's DSN. It only lets a client send events. */
+export declare const DSN = "https://91c2265acb5b0b0115914a43375be9ba@o4512380800598016.ingest.us.sentry.io/4512380976168960";
+export interface Frame {
+    filename: string;
+    function?: string;
+    lineno?: number;
+    colno?: number;
+    in_app: boolean;
+}
+/** `text` with home directories as `~`, URLs cut to their path, and at most MAX_MESSAGE characters. */
+export declare function scrubText(text: string): string;
+/**
+ * A frame's file as cdp-kernel's own, `app:///src/kernel-core.ts`, or null
+ * when it isn't: its path from the package root (`src/`, `dist/` or
+ * `runtime/` and below), wherever the package is installed.
+ */
+export declare function packageFile(file: string): string | null;
+/** V8's stack lines as Sentry frames, oldest first. Files outside the package are dropped to `<other>`. */
+export declare function parseStack(stack: string | undefined): Frame[];
+export interface ReportContext {
+    /** Where it was caught, e.g. `shell handler`. */
+    where: string;
+    /** The target runtime: node, deno, bun, workerd or celld. */
+    target?: string;
+}
+/** The Sentry event for `err`. Pure but for the clock and the ids. */
+export declare function buildEvent(err: unknown, context: ReportContext): Record<string, unknown>;
+export interface Reporter {
+    /** Sends a report; resolves once sent or given up on. Never throws. */
+    report(err: unknown, where: string): Promise<void>;
+}
+/**
+ * The reporter for this process: a real one when CDP_KERNEL_CRASH_REPORTS
+ * is `1`, otherwise one that does nothing. `send` is for tests.
+ */
+export declare function crashReporter(options?: {
+    env?: Record<string, string | undefined>;
+    target?: string;
+    send?: typeof fetch;
+}): Reporter | null;
+/**
+ * Reports an exception that would end the process, then ends it as Node
+ * would have: the stack on stderr and exit code 1. Only installed when
+ * reporting is on, so with it off a crash is exactly as before. An
+ * unhandled rejection arrives here too (Node's default `throw` mode).
+ */
+export declare function reportUncaught(reporter: Reporter): void;

package/dist/crash-reports.js

@@ -0,0 +1,155 @@
+// Opt-in reports of faults in cdp-kernel's own code (#422,
+// tlockney/ganymede#384), sent to Sentry's cdp-kernel project.
+//
+// Off unless the host sets CDP_KERNEL_CRASH_REPORTS=1, which Ganymede does
+// when its user opted in. While off nothing here runs: no handler, no
+// request. Errors from user cells never come through here: the target
+// reports those to KernelCore as exception details, and KernelCore answers
+// them as cell errors. What does: an exception that escapes a message
+// handler, the target-message handler, or the process.
+//
+// No Sentry SDK: an event is a small JSON envelope, posted with fetch.
+// That keeps the npm and JSR packages free of a dependency and its
+// install-time cost for everyone who never opts in.
+//
+// Sent: the error's type, message (home directories as `~`, URLs cut to
+// their path, 300 characters at most) and stack (frames in cdp-kernel's
+// own files by their path in the package; others by name only), the
+// version, host and target runtime, OS and architecture. Not sent: cell
+// source, outputs, variables, file paths outside the package, env vars,
+// host name.
+import process from "node:process";
+import { arch, platform, release } from "node:os";
+import { hostRuntime, VERSION } from "./package.js";
+/** The cdp-kernel project's DSN. It only lets a client send events. */
+export const DSN = "https://91c2265acb5b0b0115914a43375be9ba@o4512380800598016.ingest.us.sentry.io/4512380976168960";
+/** At most this many reports per process: a fault in a loop sends a few, not thousands. */
+const MAX_REPORTS = 10;
+const MAX_MESSAGE = 300;
+const SEND_TIMEOUT_MS = 5000;
+/** `text` with home directories as `~`, URLs cut to their path, and at most MAX_MESSAGE characters. */
+export function scrubText(text) {
+    const out = text
+        .replace(/\b(?:https?|wss?|file):\/\/[^\s/'"`)]*([^\s?#'"`)]*)(?:[?#][^\s'"`)]*)?/g, "$1")
+        .replace(/(?:\/Users|\/home)\/[^/\s'"`)]+/g, "~")
+        .replace(/[A-Za-z]:\\Users\\[^\\\s'"`)]+/g, "~");
+    return out.length > MAX_MESSAGE ? `${out.slice(0, MAX_MESSAGE)}…` : out;
+}
+/**
+ * A frame's file as cdp-kernel's own, `app:///src/kernel-core.ts`, or null
+ * when it isn't: its path from the package root (`src/`, `dist/` or
+ * `runtime/` and below), wherever the package is installed.
+ */
+export function packageFile(file) {
+    const path = file.replace(/^file:\/\//, "").replaceAll("\\", "/");
+    // From npm, from JSR (jsr.io/@tlockney/cdp-kernel/<version>/src/…), or a checkout.
+    const match = /(?:^|\/)(?:@tlockney\/cdp-kernel(?:\/[^/]+)?|cdp-kernel)\/((?:src|dist|runtime)\/[^?#]+)$/.exec(path);
+    return match ? `app:///${match[1]}` : null;
+}
+const V8_FRAME = /^\s*at (?:(.+?) \()?(.+?):(\d+):(\d+)\)?$/;
+/** V8's stack lines as Sentry frames, oldest first. Files outside the package are dropped to `<other>`. */
+export function parseStack(stack) {
+    const frames = [];
+    for (const line of (stack ?? "").split("\n")) {
+        const m = V8_FRAME.exec(line);
+        if (!m)
+            continue;
+        const [, fn, file, lineno, colno] = m;
+        const own = packageFile(file);
+        const internal = file.startsWith("node:") || file.startsWith("ext:");
+        frames.push({
+            filename: own ?? (internal ? file : "<other>"),
+            function: fn,
+            lineno: own || internal ? Number(lineno) : undefined,
+            colno: own || internal ? Number(colno) : undefined,
+            in_app: own !== null,
+        });
+    }
+    return frames.reverse();
+}
+/** The Sentry event for `err`. Pure but for the clock and the ids. */
+export function buildEvent(err, context) {
+    const error = err instanceof Error ? err : new Error(String(err));
+    return {
+        event_id: crypto.randomUUID().replaceAll("-", ""),
+        timestamp: Date.now() / 1000,
+        platform: "node",
+        level: "error",
+        release: `cdp-kernel@${VERSION}`,
+        environment: "production",
+        tags: { where: context.where, host: hostRuntime(), ...(context.target ? { target: context.target } : {}) },
+        contexts: {
+            os: { name: platform(), kernel_version: release() },
+            device: { arch: arch() },
+            runtime: { name: hostRuntime(), version: process.versions.deno ?? process.versions.node },
+        },
+        exception: {
+            values: [{
+                    type: error.name,
+                    value: scrubText(error.message),
+                    stacktrace: { frames: parseStack(error.stack) },
+                    mechanism: { type: context.where, handled: context.where !== "uncaught" },
+                }],
+        },
+    };
+}
+function parseDsn(dsn) {
+    const url = new URL(dsn);
+    const project = url.pathname.replace(/^\//, "");
+    return { key: url.username, envelope: `${url.protocol}//${url.host}/api/${project}/envelope/` };
+}
+/**
+ * The reporter for this process: a real one when CDP_KERNEL_CRASH_REPORTS
+ * is `1`, otherwise one that does nothing. `send` is for tests.
+ */
+export function crashReporter(options = {}) {
+    const env = options.env ?? process.env;
+    if (env.CDP_KERNEL_CRASH_REPORTS !== "1")
+        return null;
+    const dsn = parseDsn(env.CDP_KERNEL_SENTRY_DSN || DSN);
+    const send = options.send ?? fetch;
+    let sent = 0;
+    return {
+        async report(err, where) {
+            if (sent >= MAX_REPORTS)
+                return;
+            sent++;
+            try {
+                const event = buildEvent(err, { where, target: options.target });
+                const body = [
+                    JSON.stringify({ event_id: event.event_id, sent_at: new Date().toISOString() }),
+                    JSON.stringify({ type: "event" }),
+                    JSON.stringify(event),
+                ].join("\n");
+                await send(dsn.envelope, {
+                    method: "POST",
+                    headers: {
+                        "content-type": "application/x-sentry-envelope",
+                        "x-sentry-auth": `Sentry sentry_version=7, sentry_key=${dsn.key}, sentry_client=cdp-kernel/${VERSION}`,
+                    },
+                    body,
+                    signal: AbortSignal.timeout(SEND_TIMEOUT_MS),
+                });
+            }
+            catch {
+                // Reporting must never take the kernel down.
+            }
+        },
+    };
+}
+/**
+ * Reports an exception that would end the process, then ends it as Node
+ * would have: the stack on stderr and exit code 1. Only installed when
+ * reporting is on, so with it off a crash is exactly as before. An
+ * unhandled rejection arrives here too (Node's default `throw` mode).
+ */
+export function reportUncaught(reporter) {
+    let ending = false;
+    process.on("uncaughtException", (err) => {
+        if (ending)
+            return;
+        ending = true;
+        console.error(err instanceof Error ? err.stack ?? String(err) : err);
+        void reporter.report(err, "uncaught").finally(() => process.exit(1));
+    });
+}

package/dist/globals.d.ts

@@ -16,7 +16,7 @@ import type { Displayable, DisplayOptions, JupyterNamespace, MediaBundle } from
 export type { Displayable, DisplayOptions, JupyterNamespace, MediaBundle };
 /** Options for the notebook's `prompt()`. */
 export interface PromptOptions {
-    /** Ask the frontend to hide what is typed. */
+    /** Ask the frontend to hide what is typed, for secrets. Default `false`. */
     password?: boolean;
 }
 declare global {
@@ -27,10 +27,41 @@ declare global {
      */
     var jupyter: JupyterNamespace;
     /**
-     * Ask the frontend for a line of input over the Jupyter stdin channel.
-     * Returns `null` when the frontend didn't allow input for this cell.
+     * Ask for a line of input in the notebook: the frontend shows an input
+     * box under the cell, and the cell waits for the answer.
+     *
+     * @param message The question. Default `"Prompt"`. A non-empty
+     *   `defaultValue` is shown after it, as `message [default]`.
+     * @param defaultValue Returned when the answer is empty. Default `""`.
+     * @param options `password: true` hides what is typed.
+     * @returns The typed text, `defaultValue` for an empty answer, or `null`
+     *   when nothing can answer (the frontend allows no input, as in
+     *   `nbconvert --execute`).
+     * @availability On workerd and celld it always returns `null`.
+     * @example
+     * ```ts
+     * const name = prompt("What's your name?", "world");
+     * `Hello, ${name}!`;
+     * ```
+     * @example
+     * ```ts
+     * const apiKey = prompt("API key", "", { password: true });
+     * ```
+     * @see jupyter-api.md#asking-for-input-prompt-and-confirm
      */
     function prompt(message?: string, defaultValue?: string, options?: PromptOptions): string | null;
-    /** Ask a yes/no question over the Jupyter stdin channel. */
+    /**
+     * Ask a yes/no question in the notebook. `[y/N]` is added to the message.
+     *
+     * @param message The question. Default `"Confirm"`.
+     * @returns `true` only for `y` or `Y`; `false` otherwise, and when
+     *   nothing can answer.
+     * @availability On workerd and celld it always returns `false`.
+     * @example
+     * ```ts
+     * if (confirm("Delete the cache?")) console.log("deleting");
+     * ```
+     * @see jupyter-api.md#asking-for-input-prompt-and-confirm
+     */
     function confirm(message?: string): boolean;
 }

package/dist/kernel-core.d.ts

@@ -52,11 +52,18 @@ export interface KernelHost {
     readonly capabilities?: JsonObject;
     /** JupyterLab's visual debugger, for targets driven over CDP (#18). */
     createDebugger?(publish: (event: JsonObject) => void, transformOptions: () => CellTransformOptions): Debugger;
+    /** usage_reply's content: the host's and the running target's (null while none runs) memory and CPU (#409). */
+    usage?(target: KernelTarget | null): Promise<JsonObject>;
     /** A file's source, for the lines around a traceback frame (#322). */
     readSource?(file: string): string | undefined;
     /** Path or URL prefixes of the kernel's own runtime files, whose frames a traceback marks as library code. */
     readonly kernelFiles?: readonly string[];
     log(text: string): void;
+    /**
+     * A fault in the kernel's own code, caught where it would otherwise only
+     * be logged: for opt-in crash reports (#422). Never a cell's error.
+     */
+    fault?(err: unknown, where: string): void;
     /** After shutdown_reply has gone out. */
     exit(): void;
 }