@tlockney/cdp-kernel 0.9.0 → 0.10.0

package/dist/browser/target.d.ts

@@ -28,6 +28,13 @@ export interface BrowserTargetOptions {
      * called with `{ host, jupyter }` (#384).
      */
     preload?: string[];
+    /**
+     * The run's parameters, which cells read as `jupyter.params` (#456). The
+     * other targets read them from `GANYMEDE_PARAMS`.
+     */
+    params?: {
+        [name: string]: unknown;
+    };
     /** Answers the Worker's `host.request` calls; without it they reject (#384). */
     host?: HostHandler;
 }

package/dist/browser/target.js

@@ -48,7 +48,8 @@ export class BrowserTarget {
         const target = new BrowserTarget(options.createWorker(), events, options.host);
         const base = options.base ?? globalThis.location?.href ?? "file:///";
         try {
-            const { userAgent } = await target.#request("info", { base, cdn: options.cdn, preload: options.preload ?? [] });
+            const params = options.params === undefined ? undefined : JSON.stringify(options.params);
+            const { userAgent } = await target.#request("info", { base, cdn: options.cdn, preload: options.preload ?? [], params });
             if (typeof userAgent === "string")
                 target.versions.runtime = browserName(userAgent);
             target.versions.engine = engineName(typeof userAgent === "string" ? userAgent : "");

package/dist/browser/worker.js

@@ -86,6 +86,174 @@ function createComms(send, newId = () => crypto.randomUUID()) {
   return { api, dispatch, list: list2 };
 }
 
+// runtime/host.mjs
+var HOST_TARGET = "ganymede.host.v1";
+var CODES = /* @__PURE__ */ new Set(["unavailable", "denied", "cancelled", "timeout", "failed", "disconnected"]);
+var HostError = class _HostError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = "HostError";
+    this.code = code;
+  }
+  /** An abort becomes `cancelled`, a timeout signal's abort `timeout`, anything else `failed`. */
+  static from(err) {
+    if (err instanceof _HostError) return err;
+    const message = typeof err?.message === "string" ? err.message : String(err);
+    if (err?.name === "AbortError") return new _HostError("cancelled", message);
+    if (err?.name === "TimeoutError") return new _HostError("timeout", message);
+    if (typeof err?.code === "string" && CODES.has(err.code)) return new _HostError(err.code, message);
+    return new _HostError("failed", message);
+  }
+};
+function abortError(reason) {
+  const message = typeof reason?.message === "string" ? reason.message : String(reason ?? "aborted");
+  return new HostError(reason?.name === "TimeoutError" ? "timeout" : "cancelled", message);
+}
+function helloOf(data) {
+  if (data === null || typeof data !== "object" || typeof data.protocol !== "number") return null;
+  return {
+    protocol: data.protocol,
+    server: typeof data.server === "string" ? data.server : "",
+    notebook: typeof data.notebook === "string" ? data.notebook : null,
+    methods: Array.isArray(data.methods) ? data.methods.filter((m) => typeof m === "string") : []
+  };
+}
+function createHost(comms, defaultSignal = () => void 0) {
+  let link = null;
+  const waiters = /* @__PURE__ */ new Set();
+  let noServer = false;
+  let nextId = 0;
+  function settle() {
+    const host3 = link?.host ?? null;
+    if (host3 === null && link !== null) return;
+    for (const waiter of [...waiters]) waiter(host3);
+  }
+  function adopt(comm, data, ours = false) {
+    const old = link;
+    const l = { comm, host: null, pending: /* @__PURE__ */ new Map(), ours };
+    if (!ours) noServer = false;
+    link = l;
+    if (old !== null && !old.comm.closed) old.comm.close();
+    const hello = helloOf(data);
+    if (hello !== null) l.host = makeHost(l, hello);
+    comm.onMsg(({ data: data2 }) => {
+      if (data2.hello !== void 0) {
+        const hello2 = helloOf(data2.hello);
+        if (hello2 !== null) {
+          l.host = makeHost(l, hello2);
+          if (link === l) settle();
+        }
+        return;
+      }
+      const call = l.pending.get(data2.id);
+      if (call === void 0) return;
+      if (data2.error !== void 0) {
+        const { code, message } = data2.error ?? {};
+        call.reject(new HostError(CODES.has(code) ? code : "failed", typeof message === "string" ? message : String(code)));
+      } else {
+        call.resolve(data2.result);
+      }
+    });
+    comm.onClose(({ data: data2 }) => {
+      for (const call of l.pending.values()) {
+        call.reject(new HostError("disconnected", typeof data2?.error === "string" ? `host comm closed: ${data2.error}` : "host comm closed"));
+      }
+      l.pending.clear();
+      if (link === l) {
+        link = null;
+        if (l.ours && l.host === null) noServer = true;
+        settle();
+      }
+    });
+    if (l.host !== null) settle();
+  }
+  function makeHost(l, hello) {
+    const methods = Object.freeze([...hello.methods]);
+    function call(method, params = {}, { signal = defaultSignal() } = {}) {
+      if (signal?.aborted) return Promise.reject(abortError(signal.reason));
+      if (l.comm.closed) return Promise.reject(new HostError("disconnected", "host comm closed"));
+      const id = nextId++;
+      return new Promise((resolve, reject) => {
+        const onAbort = () => {
+          l.pending.delete(id);
+          if (!l.comm.closed) l.comm.send({ id, cancel: true });
+          reject(abortError(signal.reason));
+        };
+        const done = () => signal?.removeEventListener("abort", onAbort);
+        const call2 = {
+          resolve: (value) => (l.pending.delete(id), done(), resolve(value)),
+          reject: (error) => (l.pending.delete(id), done(), reject(error))
+        };
+        l.pending.set(id, call2);
+        signal?.addEventListener("abort", onAbort, { once: true });
+        try {
+          l.comm.send({ id, method, params });
+        } catch (err) {
+          call2.reject(new HostError("failed", `cannot send ${method}: ${err instanceof Error ? err.message : err}`));
+        }
+      });
+    }
+    const bind = (method) => (params, options) => call(method, params, options);
+    return Object.freeze({
+      protocol: hello.protocol,
+      server: hello.server,
+      notebook: hello.notebook,
+      methods,
+      has: (method) => methods.includes(method),
+      call,
+      notebooks: Object.freeze({
+        list: bind("notebooks.list"),
+        read: bind("notebooks.read"),
+        search: bind("notebooks.search"),
+        results: bind("notebooks.results"),
+        run: bind("notebooks.run")
+      }),
+      self: Object.freeze({
+        add: bind("self.add"),
+        edit: bind("self.edit"),
+        delete: bind("self.delete")
+      })
+    });
+  }
+  comms.registerTarget(HOST_TARGET, (comm, msg) => adopt(comm, msg.data));
+  async function host2({ timeout = 1e3 } = {}) {
+    if (link?.host) return link.host;
+    const signal = defaultSignal();
+    if (signal?.aborted) throw abortError(signal.reason);
+    if (noServer) return null;
+    if (link === null) adopt(comms.open(HOST_TARGET), null, true);
+    const mine = link;
+    return new Promise((resolve, reject) => {
+      let timer;
+      const onAbort = () => {
+        done();
+        reject(abortError(signal.reason));
+      };
+      const done = () => {
+        waiters.delete(waiter);
+        clearTimeout(timer);
+        signal?.removeEventListener("abort", onAbort);
+      };
+      const waiter = (host3) => {
+        done();
+        resolve(host3);
+      };
+      waiters.add(waiter);
+      signal?.addEventListener("abort", onAbort, { once: true });
+      timer = setTimeout(() => {
+        done();
+        if (waiters.size === 0 && link === mine && mine.host === null && mine.ours) {
+          link = null;
+          noServer = true;
+          mine.comm.close();
+        }
+        resolve(null);
+      }, timeout);
+    });
+  }
+  return { host: host2 };
+}
+
 // runtime/widget.mjs
 var WIDGET_PROTOCOL_VERSION = "2.1.0";
 var WIDGET_TARGET = "jupyter.widget";
@@ -251,7 +419,7 @@ function createWidgetFactory(commApi, $display2) {
 }
 
 // runtime/display.mjs
-var $display = Symbol.for("Jupyter.display");
+var $display = /* @__PURE__ */ Symbol.for("Jupyter.display");
 var rawToEntity = /* @__PURE__ */ new Map([
   ["&", "&"],
   ["<", "&lt;"],
@@ -524,6 +692,14 @@ function hasDisplaySymbol(obj) {
 function isMediaBundle(obj) {
   return obj !== null && typeof obj === "object" && !Array.isArray(obj);
 }
+var RESULT_MIME = "application/vnd.ganymede.result+json";
+function deepFreeze(value) {
+  if (typeof value === "object" && value !== null) {
+    for (const v of Object.values(value)) deepFreeze(v);
+    Object.freeze(value);
+  }
+  return value;
+}
 function createJupyter(host2) {
   async function format2(obj) {
     return await formatNow(obj);
@@ -576,12 +752,12 @@ function createJupyter(host2) {
       transient: options.display_id ? { display_id: options.display_id } : {}
     });
   }
-  async function broadcastResult(executionCount, result) {
-    if (result === void 0) return;
+  async function broadcastResult(executionCount, result2) {
+    if (result2 === void 0) return;
     try {
       broadcast("execute_result", {
         execution_count: executionCount,
-        data: await format2(result),
+        data: await format2(result2),
         metadata: {},
         // nbclient crashes on a null `transient`; Deno learned this too.
         transient: {}
@@ -603,6 +779,38 @@ function createJupyter(host2) {
     const answer2 = host2.input(message, password);
     return answer2 === "" ? defaultValue : answer2;
   }
+  let params;
+  function readParams() {
+    if (params !== void 0) return params;
+    const text = host2.params?.();
+    if (text === void 0 || text === "") return params = Object.freeze({});
+    let value;
+    try {
+      value = JSON.parse(text);
+    } catch (err) {
+      throw new TypeError(`GANYMEDE_PARAMS is not JSON: ${err instanceof Error ? err.message : err}`);
+    }
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+      throw new TypeError('GANYMEDE_PARAMS must be a JSON object, such as {"counter": "Fremont"}');
+    }
+    return params = deepFreeze(value);
+  }
+  function result(name, value) {
+    if (typeof name !== "string" || name === "") throw new TypeError("jupyter.result: name must be a non-empty string");
+    let text;
+    try {
+      text = JSON.stringify(value);
+    } catch (err) {
+      throw new TypeError(`jupyter.result: ${name} is not JSON: ${err instanceof Error ? err.message : err}`);
+    }
+    if (text === void 0) throw new TypeError(`jupyter.result: ${name} is not JSON (${typeof value})`);
+    const json = JSON.parse(text);
+    broadcast("display_data", {
+      data: { [RESULT_MIME]: { name, value: json }, "text/plain": `${name} = ${text}` },
+      metadata: {},
+      transient: {}
+    });
+  }
   const comms = createComms((msgType, content, metadata, buffers) => host2.send(msgType, content, metadata, buffers));
   let cell = new AbortController();
   let current = cell;
@@ -616,6 +824,7 @@ function createJupyter(host2) {
     for (const controller of handlers.keys()) controller.abort(reason);
     handlers.clear();
   }
+  const hostApi = createHost(comms.api, () => current.signal);
   async function commDispatch(msgType, content, metadata, buffers, ownSignal = false) {
     const controller = ownSignal ? new AbortController() : cell;
     if (ownSignal) current = controller;
@@ -635,6 +844,10 @@ function createJupyter(host2) {
       },
       broadcast,
       display,
+      get params() {
+        return readParams();
+      },
+      result,
       format: format2,
       md: taggedTemplate("text/markdown"),
       html: taggedTemplate("text/html"),
@@ -642,6 +855,7 @@ function createJupyter(host2) {
       image,
       $display,
       comm: comms.api,
+      host: hostApi.host,
       widget: createWidgetFactory(comms.api, $display)
     },
     broadcastResult,
@@ -990,8 +1204,11 @@ var jupyter = createJupyter({
   },
   // A synchronous prompt would need SharedArrayBuffer and Atomics.wait, so
   // a cross-origin isolated page; until then, as with no stdin.
-  input: () => null
+  input: () => null,
+  // jupyter.params (#456): the target's `params` option, sent with info.
+  params: () => paramsText
 });
+var paramsText;
 var cdn = DEFAULT_CDN;
 var hostCalls = /* @__PURE__ */ new Map();
 var hostListeners = /* @__PURE__ */ new Set();
@@ -1059,7 +1276,8 @@ async function preload(urls, base) {
   }
 }
 var handle = null;
-function install({ base, cdn: cdnBase }) {
+function install({ base, cdn: cdnBase, params }) {
+  if (typeof params === "string") paramsText = params;
   if (typeof cdnBase === "string") cdn = cdnBase.endsWith("/") ? cdnBase : cdnBase + "/";
   const url = new URL("$cdpk$repl.mjs", base).href;
   globalThis.__cdpk = {