@kupcad/wasm 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,74 @@
-# Temporary Holding Version
+# @kupcad/wasm
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The KupCAD core compiled to WebAssembly: preview, build, check, format and read the parameters of
+a script, in a page or in Node, with no server. The shapes it gives back are
+[@kupcad/protocol](../kupcad-protocol)'s.
+
+```js
+import { createKupcadWorker } from '@kupcad/wasm';
+
+const kupcad = createKupcadWorker(); // the core in a Web Worker: a long build doesn't freeze the page
+
+const { header, model } = await kupcad.preview(source, { params: { width: 40 } });
+// model: { kind: '3d', glb, parts } | { kind: '2d', svg } | { kind: 'none' }
+// header.error: why the run failed, where, and the parameter whose value was refused
+
+const stl = await kupcad.build(source, { format: 'stl' }); // Uint8Array
+const findings = await kupcad.check(source);
+const formatted = await kupcad.format(source);
+const schema = await kupcad.params(source); // the parameter panel's controls, without a run
+// The files the script reads, by the paths it names: a module it imports, data (an STL, a JSON)
+await kupcad.build(source, { files: { 'lib.kup': libSource, 'plate.dxf': bytes } });
+```
+
+## In a worker, or in this thread
+
+* `createKupcadWorker(options)` runs the core in a module Web Worker. Calls run one at a time,
+  the next waiting its turn. A call's `signal` (an `AbortSignal`) drops it while it waits, and
+  stops the worker while it runs: a script can't be stopped inside the module, so the worker is
+  ended and a new one starts with the next call. A worker whose core stopped (a trap) is replaced
+  the same way. A
+  call that can't be sent (the worker doesn't start, or its arguments can't be posted to one) is
+  refused with why, and the next goes. `terminate()` ends it for good.
+* `createKupcad(options)` instantiates the core in this thread: the same calls, for Node, tests
+  and a worker of the host's own. `Kupcad.fromExports(exports)` takes a module the host
+  instantiated itself.
+
+Both take `wasm` (the module: a URL, its bytes or a compiled `WebAssembly.Module`, and for
+`createKupcad` a fetch `Response` too, which can't be posted to a worker; by default the
+`kupcad.wasm` this package ships) and `log` (where the module's log goes, a line at a time; by
+default `console.debug`). A worker is given a relative URL resolved against the page, as the
+page means it.
+
+## What a call can fail with
+
+* `KupcadError`: the core refused, with its message: a script that doesn't parse
+  (`1:6: Expected 'r_paren' ...`) or run (`RuntimeError: boom`), values it refused
+  (`parameters: ...`), a format it doesn't write. A preview doesn't throw for these: its frame
+  says why.
+* `KupcadCrashError`: the module stopped (a trap, or an exit), or the worker failed (its script
+  didn't load, or it sent what couldn't be read). A worker is replaced on the next call; a module
+  of `createKupcad` is made again.
+* `ProtocolError` (@kupcad/protocol's): the module speaks a protocol version this package doesn't
+  read.
+
+## Inside
+
+The module asks its host for WASI. A browser has none and Node's would give it a file system, so
+the package answers it itself (`src/wasi.js`): the host's clocks and randomness, the log, and no
+files. A script reads the files its call brings (`files`, by the paths the script names them):
+they are packed into one buffer (`src/files.js`, as `core/src/vfs/packed.zig` reads it) and
+kept in an in-memory file system of that call alone, so no script sees another's files and a
+script's exports go nowhere. A build runs under the core's interactive limits (instructions,
+memory), as a preview does: a runaway script stops with an error instead of hanging the worker. Every string and buffer is copied in and freed after the call;
+every result is copied out and freed. `pnpm build` copies the module from the core's
+build (`pnpm build:core:wasm` at the root) into `dist/`, which the package ships; its version is
+the core's, which the tests hold it to.
+
+The threaded build of the core (`-Dwasm_threads`) isn't shipped yet: it needs a host that runs
+its threads in workers and pages served cross-origin isolated.
+
+`@kupcad/wasm/types` has the API's types (`KupcadApi`, the options, the worker's messages).
+`@kupcad/wasm/testing` is for the tests of a package that shows what the core makes: the real
+module, made once a test process (`testCore`), and `modelOf` and `schemaOf` of a script, a
+script that fails failing the test.

package/package.json

@@ -1,6 +1,46 @@
 {
   "name": "@kupcad/wasm",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "description": "The KupCAD core compiled to WebAssembly: preview, build, check, format and read the parameters of a script in the browser or Node, directly or in a Web Worker.",
+  "license": "AGPL-3.0-only",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kupcad/kupcad.git",
+    "directory": "packages/kupcad-wasm"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.js",
+    "dist/kupcad.wasm"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "imports": {
+    "#read-file": {
+      "node": "./src/read-file.node.js",
+      "default": "./src/read-file.browser.js"
+    }
+  },
+  "exports": {
+    ".": "./src/index.js",
+    "./types": {
+      "types": "./src/types.d.ts"
+    },
+    "./testing": "./src/testing.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@kupcad/protocol": "0.1.1"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.5",
+    "vitest": "^5.0.5"
+  },
+  "scripts": {
+    "build": "node scripts/copy-wasm.js",
+    "check": "tsc -p jsconfig.json",
+    "test": "vitest run"
+  }
 }

package/src/client.js

@@ -0,0 +1,291 @@
+// The core in a Web Worker, with createKupcad's API: a long build runs there and the page goes
+// on. Calls run one at a time, the next waiting its turn. A call's AbortSignal drops it while
+// it waits, and stops the worker while it runs: the worker is replaced on the next call, as
+// one that crashed is.
+
+import { ProtocolError } from '@kupcad/protocol';
+import { KupcadCrashError, KupcadError } from './errors.js';
+
+/** @import { Finding, Preview, UiSchema, VersionInfo } from '@kupcad/protocol/types' */
+/** @import { BuildOptions, CallOptions, FromWorker, KupcadApi, Method, PreviewOptions, SentError, ToWorker, WorkerLike, WorkerOptions, WorkerWasmSource } from './types.js' */
+
+/**
+ * @typedef {object} Call
+ * @property {number} id
+ * @property {Method} method
+ * @property {unknown[]} args
+ * @property {(value: any) => void} resolve
+ * @property {(reason: unknown) => void} reject
+ * @property {AbortSignal | undefined} signal
+ * @property {() => void} onAbort
+ */
+
+/** @type {() => WorkerLike} */
+const moduleWorker = () => new Worker(new URL('./worker.js', import.meta.url), { type: 'module' });
+/** Why a worker failed when its error says nothing: its script didn't load, most often. */
+const SILENT_FAILURE = 'it failed without a message (its script may not have loaded)';
+
+/**
+ * The core in a Web Worker.
+ * @param {WorkerOptions} [options]
+ * @returns {KupcadWorker}
+ */
+export function createKupcadWorker(options = {}) {
+  return new KupcadWorker(options);
+}
+
+/** @implements {KupcadApi} */
+export class KupcadWorker {
+  /** @type {() => WorkerLike} */
+  #spawn;
+  /** The module, as it can be posted (a URL as its href). */
+  #wasm;
+  /** @type {(line: string) => void} */
+  #log;
+  /** @type {WorkerLike | null} */
+  #worker = null;
+  /** @type {Call[]} */
+  #queue = [];
+  /** @type {Call | null} */
+  #running = null;
+  #nextId = 1;
+  /** @type {Error | null} */
+  #terminated = null;
+
+  /** @param {WorkerOptions} options */
+  constructor(options) {
+    this.#spawn = options.worker ?? moduleWorker;
+    this.#wasm = postable(options.wasm);
+    this.#log = options.log ?? ((line) => console.debug(line));
+  }
+
+  /**
+   * @param {string} source
+   * @param {PreviewOptions} [options]
+   * @returns {Promise<Preview>}
+   */
+  preview(source, { signal, ...options } = {}) {
+    return this.#call('preview', [source, options], signal);
+  }
+
+  /**
+   * @param {string} source
+   * @param {BuildOptions} [options]
+   * @returns {Promise<Uint8Array>}
+   */
+  build(source, { signal, ...options } = {}) {
+    return this.#call('build', [source, options], signal);
+  }
+
+  /**
+   * @param {string} source
+   * @param {CallOptions} [options]
+   * @returns {Promise<Finding[]>}
+   */
+  check(source, { signal } = {}) {
+    return this.#call('check', [source], signal);
+  }
+
+  /**
+   * @param {string} source
+   * @param {CallOptions} [options]
+   * @returns {Promise<string>}
+   */
+  format(source, { signal } = {}) {
+    return this.#call('format', [source], signal);
+  }
+
+  /**
+   * @param {string} source
+   * @param {CallOptions} [options]
+   * @returns {Promise<UiSchema>}
+   */
+  params(source, { signal } = {}) {
+    return this.#call('params', [source], signal);
+  }
+
+  /** @returns {Promise<VersionInfo>} */
+  version() {
+    return this.#call('version', []);
+  }
+
+  /** Stops the worker for good: the calls waiting, and any made after, are refused. */
+  terminate() {
+    this.#terminated = new Error('the kupcad worker was terminated');
+    this.#stopWorker();
+    for (const call of [...(this.#running ? [this.#running] : []), ...this.#queue]) {
+      this.#settle(call, () => call.reject(this.#terminated));
+    }
+    this.#running = null;
+    this.#queue = [];
+  }
+
+  /**
+   * @param {Method} method
+   * @param {unknown[]} args
+   * @param {AbortSignal} [signal]
+   * @returns {Promise<any>}
+   */
+  #call(method, args, signal) {
+    if (this.#terminated) return Promise.reject(this.#terminated);
+    if (signal?.aborted) return Promise.reject(signal.reason);
+    return new Promise((resolve, reject) => {
+      /** @type {Call} */
+      const call = {
+        id: this.#nextId++,
+        method,
+        args,
+        resolve,
+        reject,
+        signal,
+        onAbort: () => this.#abort(call),
+      };
+      signal?.addEventListener('abort', call.onAbort, { once: true });
+      this.#queue.push(call);
+      this.#pump();
+    });
+  }
+
+  /**
+   * Sends the next call when none runs, starting a worker if none does. One that can't be
+   * sent (no worker starts, or its arguments can't be posted) is refused, and the next goes:
+   * it was taken for running, and every call after waited for good.
+   */
+  #pump() {
+    while (!this.#running) {
+      const next = this.#queue.shift();
+      if (!next) return;
+      try {
+        this.#ensureWorker().postMessage({
+          type: 'call',
+          id: next.id,
+          method: next.method,
+          args: next.args,
+        });
+        this.#running = next;
+      } catch (error) {
+        this.#settle(next, () => next.reject(error));
+      }
+    }
+  }
+
+  /** @returns {WorkerLike} */
+  #ensureWorker() {
+    if (this.#worker) return this.#worker;
+    const worker = this.#spawn();
+    // A worker stopped may still have sent: only the running one's messages count
+    worker.addEventListener('message', ({ data }) => {
+      if (worker === this.#worker) this.#receive(data);
+    });
+    worker.addEventListener('error', (event) => {
+      event.preventDefault();
+      if (worker === this.#worker) {
+        this.#fail(
+          new KupcadCrashError(`the kupcad worker failed: ${event.message || SILENT_FAILURE}`),
+        );
+      }
+    });
+    // A reply that couldn't be read would leave its call waiting for good
+    worker.addEventListener('messageerror', () => {
+      if (worker === this.#worker) {
+        this.#fail(new KupcadCrashError("the kupcad worker sent a message that couldn't be read"));
+      }
+    });
+    try {
+      worker.postMessage({ type: 'init', wasm: this.#wasm });
+    } catch (error) {
+      worker.terminate();
+      throw error;
+    }
+    this.#worker = worker;
+    return worker;
+  }
+
+  /** @param {FromWorker} message */
+  #receive(message) {
+    if (message.type === 'log') {
+      this.#log(message.line);
+      return;
+    }
+    const call = this.#running;
+    if (!call || call.id !== message.id) return;
+    this.#running = null;
+    if (message.ok) {
+      this.#settle(call, () => call.resolve(message.value));
+    } else {
+      // A core that can't go on is replaced on the next call
+      if (message.error.fatal) this.#stopWorker();
+      this.#settle(call, () => call.reject(revive(message.error)));
+    }
+    this.#pump();
+  }
+
+  /**
+   * Refuses the running call with `error`, the worker gone with it.
+   * @param {Error} error
+   */
+  #fail(error) {
+    this.#stopWorker();
+    const call = this.#running;
+    this.#running = null;
+    if (call) this.#settle(call, () => call.reject(error));
+    this.#pump();
+  }
+
+  /** @param {Call} call */
+  #abort(call) {
+    const reason = call.signal?.reason;
+    if (call === this.#running) {
+      // A call can't be stopped inside the module: the worker running it is
+      this.#stopWorker();
+      this.#running = null;
+      this.#settle(call, () => call.reject(reason));
+      this.#pump();
+      return;
+    }
+    this.#queue = this.#queue.filter((queued) => queued !== call);
+    this.#settle(call, () => call.reject(reason));
+  }
+
+  /**
+   * @param {Call} call
+   * @param {() => void} done
+   */
+  #settle(call, done) {
+    call.signal?.removeEventListener('abort', call.onAbort);
+    done();
+  }
+
+  #stopWorker() {
+    const worker = this.#worker;
+    if (!worker) return;
+    this.#worker = null;
+    worker.terminate();
+  }
+}
+
+/**
+ * The module as the worker is given it: a URL as its href, a relative one resolved against the
+ * page (the worker would resolve it against its own script's).
+ * @param {WorkerWasmSource | undefined} wasm
+ * @returns {Extract<ToWorker, { type: 'init' }>['wasm']}
+ */
+function postable(wasm) {
+  if (wasm instanceof URL) return wasm.href;
+  if (typeof wasm === 'string' && globalThis.location) return new URL(wasm, location.href).href;
+  return wasm;
+}
+
+/**
+ * A failure from the worker, as the error class it was there.
+ * @param {SentError} error
+ * @returns {Error}
+ */
+function revive({ name, message }) {
+  if (name === 'KupcadError') return new KupcadError(message);
+  if (name === 'KupcadCrashError') return new KupcadCrashError(message);
+  if (name === 'ProtocolError') return new ProtocolError(message);
+  const error = new Error(message);
+  error.name = name;
+  return error;
+}

package/src/errors.js

@@ -0,0 +1,25 @@
+// What a call can fail with besides a JavaScript error.
+
+/** The core refused: a script that doesn't parse or run, values it refused, a format it lacks. */
+export class KupcadError extends Error {
+  /** @param {string} message the core's, as get_last_error gives it */
+  constructor(message) {
+    super(message);
+    this.name = 'KupcadError';
+  }
+}
+
+/**
+ * The module stopped (a trap, or an exit): its instance can't be used again. A worker's is
+ * replaced on the next call; a module's own is made anew with `createKupcad`.
+ */
+export class KupcadCrashError extends Error {
+  /**
+   * @param {string} message
+   * @param {{ cause?: unknown }} [options]
+   */
+  constructor(message, options) {
+    super(message, options);
+    this.name = 'KupcadCrashError';
+  }
+}

package/src/files.js

@@ -0,0 +1,33 @@
+// The files a call gives the core, packed into one buffer as the core reads them
+// (core/src/vfs/packed.zig): each file its path, then its content, each with its length first
+// (u32, little-endian), one after another. One buffer crosses into the module's memory, however
+// many files; the core keeps them for that call alone.
+
+/** A length, as written before a path and before a content. */
+const LEN_BYTES = 4;
+
+const encoder = new TextEncoder();
+
+/**
+ * `files` packed: paths as the script names them (`import { } from "./lib.kup"` reads
+ * `lib.kup`; `import_json("data/size.json")` reads `data/size.json`) to their contents.
+ * @param {Record<string, Uint8Array | string>} files
+ * @returns {Uint8Array}
+ */
+export function packFiles(files) {
+  const fields = Object.entries(files).flatMap(([path, content]) => [
+    encoder.encode(path),
+    typeof content === 'string' ? encoder.encode(content) : content,
+  ]);
+  const packed = new Uint8Array(
+    fields.reduce((total, field) => total + LEN_BYTES + field.byteLength, 0),
+  );
+  const view = new DataView(packed.buffer);
+  let at = 0;
+  for (const field of fields) {
+    view.setUint32(at, field.byteLength, true);
+    packed.set(field, at + LEN_BYTES);
+    at += LEN_BYTES + field.byteLength;
+  }
+  return packed;
+}

package/src/index.js

@@ -0,0 +1,6 @@
+// @kupcad/wasm: the core compiled to WebAssembly, in this thread (createKupcad) or in a Web
+// Worker (createKupcadWorker), with one API.
+
+export { createKupcad, Kupcad } from './kupcad.js';
+export { createKupcadWorker } from './client.js';
+export { KupcadCrashError, KupcadError } from './errors.js';