@modelprofile.com/flexharness 11.0.1 → 11.1.0

package/ts/classes.codesandbox.ts

@@ -1,9 +1,17 @@
 import * as plugins from './plugins.js';
 import { FlexHarnessValidationError } from './errors.js';
 import type { IFlexCodeModeLimits, IFlexCodeRunFailure, TJsonValue } from './interfaces.js';
+import type { TCodeWorkerPhase, TCodeWorkerReport, TCodeWorkerRequest } from './classes.codesandbox.worker.js';
+import { maxTransferMetadataBytes, truncateUtf8 } from './utils.transfer.js';
 
-/** What one catalog call of a program comes to: a JSON value, or the error the program sees. */
-export type TFlexCodeCallOutcome = { ok: true; value: TJsonValue } | { ok: false; error: TJsonValue };
+/**
+ * What one catalog call of a program comes to: a JSON value, the error the program sees, or the
+ * host's `callbacks` limit, which stops the program without the call.
+ */
+export type TFlexCodeCallOutcome =
+  | { ok: true; value: TJsonValue }
+  | { ok: false; error: TJsonValue }
+  | { ok: false; limit: 'callbacks'; message: string };
 
 export interface IFlexCodeHost {
   /**
@@ -24,109 +32,28 @@ type TStop =
   | { kind: 'aborted'; message: string }
   | { kind: 'host'; error: unknown };
 
-const programFile = 'program.ts';
 /** How long calls in flight get to settle after their program stopped and their signal aborted. */
 const stopGraceMs = 5_000;
+/**
+ * How long a program may compute past its time before the host ends its worker. QuickJS checks the
+ * time only at its interrupt points, and native work between two of them, such as sorting a large
+ * array many times over, can run far longer.
+ */
+const cpuGraceMs = 250;
 
-/** Evaluating the prelude, the program's text, or running the program. */
-type TPhase = 'prelude' | 'parse' | 'program';
 const programPrefix = 'globalThis.__flexMain = async function () {\n';
 const programSuffix = '\n};';
 
-/**
- * Runs in the context before the program: it takes the host functions off the global object and
- * defines `api`, `ApiError` and `console`. Only strings cross the boundary.
- */
-const prelude = `'use strict';
-(() => {
-  const call = globalThis.__flexCall;
-  const log = globalThis.__flexLog;
-  const done = globalThis.__flexDone;
-  delete globalThis.__flexCall;
-  delete globalThis.__flexLog;
-  delete globalThis.__flexDone;
-  class ApiError extends Error {
-    constructor(details) {
-      const message = details && typeof details.message === 'string' ? details.message : JSON.stringify(details);
-      super(message);
-      this.name = 'ApiError';
-      this.details = details;
-    }
-  }
-  const invoke = (path, args) => {
-    if (!path) return Promise.reject(new TypeError('Call a method as api.<namespace>.<method>(params).'));
-    let params;
-    try {
-      // api.results.get(handle, { page, path }) reads a stored result.
-      const argument = path === 'results.get' && typeof args[0] === 'string'
-        ? Object.assign({}, args[1], { handle: args[0] })
-        : args[0];
-      params = JSON.stringify(args.length === 0 || argument === undefined ? {} : argument);
-    } catch (error) {
-      return Promise.reject(new TypeError('The params of ' + path + ' are not JSON: ' + error.message));
-    }
-    return call(path, params === undefined ? 'null' : params).then((text) => {
-      const outcome = JSON.parse(text);
-      if (outcome.ok) return outcome.value;
-      throw new ApiError(outcome.error);
-    });
-  };
-  const target = (path) => new Proxy(function () {}, {
-    get: (_target, key) => typeof key === 'string' && key !== 'then' ? target(path ? path + '.' + key : key) : undefined,
-    apply: (_target, _this, args) => invoke(path, args),
-    set: () => false,
-    defineProperty: () => false,
-    deleteProperty: () => false,
-  });
-  const format = (value) => {
-    if (typeof value === 'string') return value;
-    try {
-      const text = JSON.stringify(value);
-      return text === undefined ? String(value) : text;
-    } catch {
-      return String(value);
-    }
-  };
-  const writer = (level) => (...values) => { log(level, values.map(format).join(' ')); };
-  const fixed = (value) => ({ value, enumerable: false, writable: false, configurable: false });
-  Object.defineProperty(globalThis, 'api', fixed(target('')));
-  Object.defineProperty(globalThis, 'ApiError', fixed(ApiError));
-  Object.defineProperty(globalThis, 'console', fixed(Object.freeze({
-    log: writer('log'), info: writer('info'), warn: writer('warn'), error: writer('error'), debug: writer('debug'),
-  })));
-  const settle = (value) => {
-    try {
-      const text = JSON.stringify({ ok: true, value: value === undefined ? null : value });
-      return text === undefined ? JSON.stringify({ ok: true, value: null }) : text;
-    } catch (error) {
-      return JSON.stringify({ ok: false, name: 'TypeError', message: 'The return value is not JSON: ' + error.message });
-    }
-  };
-  const fail = (error) => JSON.stringify({
-    ok: false,
-    name: error && typeof error.name === 'string' ? error.name : 'Error',
-    message: error && typeof error.message === 'string' ? error.message : String(error),
-    stack: error && typeof error.stack === 'string' ? error.stack : '',
-    ...(error instanceof ApiError ? { details: error.details } : {}),
-  });
-  Object.defineProperty(globalThis, '__flexStart', {
-    configurable: true,
-    value: () => {
-      const main = globalThis.__flexMain;
-      delete globalThis.__flexStart;
-      delete globalThis.__flexMain;
-      main().then(settle, fail).then(done);
-    },
-  });
-})();
-`;
+/** The worker module beside this one, compiled or, where the package runs uncompiled, its source. */
+const workerUrl = new URL(`./classes.codesandbox.worker${plugins.path.extname(import.meta.url)}`, import.meta.url);
 
 let enginePromise: Promise<plugins.ICodeSandboxEngine> | undefined;
 
 /**
- * Runs `run_code` programs in QuickJS-ng compiled to WebAssembly: every program in a WebAssembly
- * instance of its own, with no globals beyond the language, `api`, `ApiError` and `console`, and
- * every limit of `IFlexCodeModeLimits` enforced. Program types are stripped with amaro first.
+ * Runs `run_code` programs in QuickJS-ng compiled to WebAssembly: every program in a worker thread and
+ * WebAssembly instance of its own, with no globals beyond the language, `api`, `ApiError` and
+ * `console`, and every limit of `IFlexCodeModeLimits` enforced. Program types are stripped with amaro
+ * first.
  */
 export class FlexCodeSandbox {
   private constructor(private readonly engine: plugins.ICodeSandboxEngine) {}
@@ -155,27 +82,26 @@ export class FlexCodeSandbox {
 }
 
 class CodeRun {
-  private runtime?: plugins.IQuickJsRuntime;
-  private vm?: plugins.IQuickJsContext;
-  private readonly deferreds = new Set<plugins.IQuickJsDeferredPromise>();
+  private worker?: plugins.Worker;
+  private terminated?: Promise<unknown>;
+  private program = '';
   private readonly calls = new AbortController();
   private readonly queue: Array<() => void> = [];
   /** Host calls in flight; the run settles only after every one of them did. */
   private readonly inFlight = new Set<Promise<void>>();
   private running = 0;
   private callCount = 0;
+  /** Requests the worker has not finished computing on: while there are any, the watchdog runs. */
+  private busy = 0;
+  /** What the program computed by the worker's last report. */
   private cpuMs = 0;
-  private enteredAt?: number;
+  private watchdog?: ReturnType<typeof setTimeout>;
   private stop?: TStop;
   private logs = '';
-  private logBytes = 0;
-  private logsCut = false;
   private settle!: (result: TFlexCodeRunResult) => void;
   private reject!: (error: unknown) => void;
   /** The outcome is decided; the run waits for its calls in flight, then settles. */
   private closing = false;
-  private finished = false;
-  private broken = false;
   private wallTimer?: ReturnType<typeof setTimeout>;
   private readonly startedAt = performance.now();
 
@@ -212,121 +138,97 @@ class CodeRun {
     const onAbort = () => this.halt({ kind: 'aborted', message: 'The program was stopped.' });
     this.signal?.addEventListener('abort', onAbort, { once: true });
     try {
-      const module = await this.engine.newModule();
-      // QuickJS runs on the host's stack too: start it from a fresh, shallow one.
-      await new Promise<void>((resolve) => setImmediate(resolve));
       if (this.signal?.aborted) onAbort();
-      else {
-        this.armWallTimer();
-        this.boot(module);
-      }
+      else this.spawn();
       return await outcome;
     } finally {
       this.signal?.removeEventListener('abort', onAbort);
-      this.dispose();
+      await this.dispose();
     }
   }
 
-  private program = '';
-
-  private boot(module: plugins.IQuickJsModule): void {
-    const runtime = module.newRuntime();
-    this.runtime = runtime;
-    runtime.setMemoryLimit(this.limits.memoryBytes);
-    runtime.setMaxStackSize(this.limits.stackBytes);
-    runtime.setInterruptHandler(() => this.interrupted());
-    const vm = runtime.newContext();
-    this.vm = vm;
-    this.define('__flexCall', (pathHandle, paramsHandle) => this.bridgeCall(vm.getString(pathHandle), vm.getString(paramsHandle)));
-    this.define('__flexLog', (levelHandle, textHandle) => {
-      this.log(vm.getString(levelHandle), vm.getString(textHandle));
-    });
-    this.define('__flexDone', (textHandle) => {
-      this.complete(vm.getString(textHandle));
+  private spawn(): void {
+    const worker = new plugins.Worker(workerUrl);
+    this.worker = worker;
+    worker.on('message', (report: TCodeWorkerReport) => this.receive(report));
+    worker.on('error', (error: unknown) => this.halt({ kind: 'host', error }));
+    worker.on('exit', (code: number) => {
+      this.halt({ kind: 'host', error: new Error(`The code mode worker exited with code ${code}.`) });
     });
-    if (!this.evaluate(prelude, 'prelude.js', 'prelude')) return;
-    if (!this.evaluate(this.program, programFile, 'parse')) return;
-    if (!this.evaluate('__flexStart();', 'start.js', 'program')) return;
-    this.pump();
   }
 
-  private define(name: string, implementation: (...args: plugins.IQuickJsHandle[]) => plugins.IQuickJsHandle | void): void {
-    const handle = this.vm!.newFunction(name, implementation);
-    this.vm!.setProp(this.vm!.global, name, handle);
-    handle.dispose();
-  }
-
-  private evaluate(code: string, file: string, phase: TPhase): boolean {
-    if (this.closing) return false;
-    let result: plugins.TQuickJsResult;
-    this.enter();
-    try {
-      result = this.vm!.evalCode(code, file);
-    } catch (error) {
-      this.hostThrow(error);
-      return false;
-    } finally {
-      this.leave();
-    }
-    if (result.error) {
-      this.failWith(result.error, phase);
-      return false;
-    }
-    result.value.dispose();
-    return true;
-  }
-
-  /** Runs the program's pending jobs after a call settled or the program started. */
-  private pump(): void {
-    if (this.closing || !this.runtime?.alive) return;
-    let result: { error?: plugins.IQuickJsHandle };
-    this.enter();
-    try {
-      result = this.runtime.executePendingJobs();
-    } catch (error) {
-      this.hostThrow(error);
-      return;
-    } finally {
-      this.leave();
+  private receive(report: TCodeWorkerReport): void {
+    if (this.closing) return;
+    switch (report.kind) {
+      case 'ready':
+        this.armWallTimer();
+        this.send({
+          kind: 'start',
+          program: this.program,
+          limits: {
+            cpuMs: this.limits.cpuMs,
+            memoryBytes: this.limits.memoryBytes,
+            stackBytes: this.limits.stackBytes,
+            maxLogBytes: this.limits.maxLogBytes,
+          },
+        });
+        return;
+      case 'call':
+        this.call(report.id, report.method, report.params);
+        return;
+      case 'log':
+        this.logs += report.text;
+        return;
+      case 'idle':
+        this.idle(report.cpuMs);
+        return;
+      case 'done':
+        this.complete(report.text, report.unawaited);
+        return;
+      case 'failed':
+        if (report.phase === 'prelude') {
+          this.halt({ kind: 'host', error: new Error(`The code mode prelude failed: ${report.dumped}`) });
+          return;
+        }
+        this.done(this.failure(this.classify(report, report.phase)));
+        return;
+      case 'stopped':
+        this.halt(report.limit === 'cpu'
+          ? this.cpuLimit()
+          : { kind: 'limit', limit: 'stack', message: 'The program exceeded its stack.' });
+        return;
     }
-    if (result.error) this.failWith(result.error, 'program');
   }
 
-  /**
-   * An exception out of the WebAssembly instance: the host's stack ran out under deep recursion, or
-   * the instance failed. Its state is not trusted afterwards; `dispose()` abandons it.
-   */
-  private hostThrow(error: unknown): void {
-    this.broken = true;
-    if (error instanceof RangeError) {
-      this.halt({ kind: 'limit', limit: 'stack', message: 'The program exceeded its stack.' });
-      return;
-    }
-    this.halt({ kind: 'host', error });
+  /** Has the worker compute: start the program, or go on with an answer. */
+  private send(request: TCodeWorkerRequest): void {
+    this.busy += 1;
+    this.worker!.postMessage(request);
+    this.armWatchdog();
   }
 
-  private enter(): void {
-    this.enteredAt = performance.now();
+  private idle(cpuMs: number): void {
+    this.cpuMs = cpuMs;
+    this.busy -= 1;
+    clearTimeout(this.watchdog);
+    this.watchdog = undefined;
+    this.armWatchdog();
   }
 
-  private leave(): void {
-    if (this.enteredAt === undefined) return;
-    this.cpuMs += performance.now() - this.enteredAt;
-    this.enteredAt = undefined;
+  /** While the worker computes, ends it once the program's time and `cpuGraceMs` are up. */
+  private armWatchdog(): void {
+    if (this.watchdog || this.busy === 0) return;
+    this.watchdog = setTimeout(
+      () => this.halt(this.cpuLimit()),
+      Math.max(0, this.limits.cpuMs - this.cpuMs) + cpuGraceMs,
+    );
   }
 
-  private interrupted(): boolean {
-    if (this.stop) return true;
-    if (this.enteredAt !== undefined && this.cpuMs + performance.now() - this.enteredAt > this.limits.cpuMs) {
-      this.stop = { kind: 'limit', limit: 'cpu', message: `The program computed for more than ${this.limits.cpuMs} ms.` };
-      return true;
-    }
-    return false;
+  private cpuLimit(): TStop {
+    return { kind: 'limit', limit: 'cpu', message: `The program computed for more than ${this.limits.cpuMs} ms.` };
   }
 
-  private bridgeCall(method: string, paramsText: string): plugins.IQuickJsHandle {
-    const deferred = this.vm!.newPromise();
-    this.deferreds.add(deferred);
+  private call(id: number, method: string, paramsText: string): void {
     this.callCount += 1;
     if (this.callCount > this.limits.maxCalls) {
       this.halt({
@@ -334,7 +236,7 @@ class CodeRun {
         limit: 'calls',
         message: `The program made more than ${this.limits.maxCalls} calls.`,
       });
-      return deferred.handle;
+      return;
     }
     let params: unknown;
     try {
@@ -345,7 +247,7 @@ class CodeRun {
     const run = (): void => {
       if (this.closing) return;
       this.running += 1;
-      // A settled call stops counting before the program sees its answer, which may end the program.
+      // A settled call leaves the calls in flight before its outcome is handled, which may end the run.
       const settled = (): void => {
         this.running -= 1;
         this.inFlight.delete(call);
@@ -353,7 +255,13 @@ class CodeRun {
       const call: Promise<void> = this.host.call(method, params, this.calls.signal).then(
         (outcome) => {
           settled();
-          this.answer(deferred, outcome);
+          if ('limit' in outcome) {
+            // The host did not make the call.
+            this.callCount -= 1;
+            this.halt({ kind: 'limit', limit: outcome.limit, message: outcome.message });
+            return;
+          }
+          this.answer(id, outcome);
         },
         (error: unknown) => {
           settled();
@@ -364,39 +272,20 @@ class CodeRun {
     };
     if (this.running < this.limits.maxConcurrentCalls) run();
     else this.queue.push(run);
-    return deferred.handle;
   }
 
-  private answer(deferred: plugins.IQuickJsDeferredPromise, outcome: TFlexCodeCallOutcome): void {
-    if (this.closing || !deferred.alive) return;
+  private answer(id: number, outcome: TFlexCodeCallOutcome): void {
+    if (this.closing) return;
     let text: string;
     try {
       text = JSON.stringify(outcome);
     } catch {
       text = JSON.stringify({ ok: false, error: { error: 'failed', message: 'The result is not JSON.' } });
     }
-    const value = this.vm!.newString(text);
-    deferred.resolve(value);
-    value.dispose();
-    this.deferreds.delete(deferred);
-    this.pump();
-  }
-
-  private log(level: string, text: string): void {
-    if (this.logsCut || this.closing) return;
-    const line = `${level === 'log' ? '' : `[${level}] `}${text}\n`;
-    const bytes = Buffer.byteLength(line, 'utf8');
-    if (this.logBytes + bytes > this.limits.maxLogBytes) {
-      this.logsCut = true;
-      this.logs += '[console output cut off]\n';
-      return;
-    }
-    this.logBytes += bytes;
-    this.logs += line;
+    this.send({ kind: 'answer', id, text });
   }
 
-  private complete(text: string): void {
-    if (this.closing) return;
+  private complete(text: string, unawaited: number): void {
     let outcome: { ok: boolean; value?: TJsonValue; name?: string; message?: string; stack?: string };
     try {
       outcome = JSON.parse(text);
@@ -404,7 +293,6 @@ class CodeRun {
       outcome = { ok: false, name: 'Error', message: 'The program ended without a result.' };
     }
     if (outcome.ok) {
-      const unawaited = this.running + this.queue.length;
       if (unawaited > 0) {
         // Calls the program did not await are not part of its result: it fails, and proposes nothing.
         this.done(this.failure({
@@ -424,36 +312,13 @@ class CodeRun {
     this.done(this.failure(this.classify(outcome, 'program')));
   }
 
-  private failWith(handle: plugins.IQuickJsHandle, phase: TPhase): void {
-    let dumped: unknown;
-    // Reading the thrown value can run program code, such as a toJSON: it counts as computing.
-    this.enter();
-    try {
-      dumped = this.vm!.dump(handle);
-    } catch (error) {
-      if (!(error instanceof Error) || error instanceof RangeError) this.broken = true;
-      dumped = undefined;
-    } finally {
-      this.leave();
-      if (!this.broken && handle.alive) handle.dispose();
-    }
-    if (phase === 'prelude' && !this.stop) {
-      this.halt({ kind: 'host', error: new Error(`The code mode prelude failed: ${JSON.stringify(dumped)}`) });
-      return;
-    }
-    const error = (dumped && typeof dumped === 'object' ? dumped : { message: String(dumped) }) as {
-      name?: string; message?: string; stack?: string;
-    };
-    this.done(this.failure(this.classify(error, phase)));
-  }
-
   private classify(
     error: { name?: string; message?: string; stack?: string },
-    phase: TPhase,
+    phase: TCodeWorkerPhase,
   ): Omit<IFlexCodeRunFailure, 'calls'> {
-    if (this.stop?.kind === 'limit') return { error: 'limit_exceeded', limit: this.stop.limit, message: this.stop.message };
-    if (this.stop?.kind === 'aborted') return { error: 'aborted', message: this.stop.message };
-    const message = typeof error.message === 'string' ? error.message : 'The program failed.';
+    const message = typeof error.message === 'string'
+      ? truncateUtf8(error.message, maxTransferMetadataBytes)
+      : 'The program failed.';
     if (error.name === 'InternalError' && message === 'out of memory') {
       return { error: 'limit_exceeded', limit: 'memory', message: `The program used more than ${this.limits.memoryBytes} bytes of memory.` };
     }
@@ -463,13 +328,11 @@ class CodeRun {
     ) {
       return { error: 'limit_exceeded', limit: 'stack', message: 'The program exceeded its stack.' };
     }
-    if (error.name === 'InternalError' && message === 'interrupted') {
-      return { error: 'limit_exceeded', limit: 'cpu', message: `The program computed for more than ${this.limits.cpuMs} ms.` };
-    }
+    // The worker evaluates the program's text as program.ts.
     const line = /program\.ts:(\d+)/.exec(error.stack ?? '')?.[1];
     return {
       error: phase === 'parse' && error.name === 'SyntaxError' ? 'syntax_error' : 'program_error',
-      ...(typeof error.name === 'string' ? { name: error.name } : {}),
+      ...(typeof error.name === 'string' ? { name: truncateUtf8(error.name, maxTransferMetadataBytes) } : {}),
       message,
       ...(line && Number(line) > 1 ? { line: Number(line) - 1 } : {}),
     };
@@ -505,16 +368,17 @@ class CodeRun {
   }
 
   /**
-   * Decides the run's outcome. Calls not started yet never start. Calls in flight are told to stop
-   * through their signal, and the outcome is delivered once they settled, so no call runs on after
-   * its program; a host call that ignores its signal gets `stopGraceMs`, and its answer is dropped.
+   * Decides the run's outcome and ends the program's worker. Calls not started yet never start. Calls
+   * in flight are told to stop through their signal, and the outcome is delivered once they settled,
+   * so no call runs on after its program; a host call that ignores its signal gets `stopGraceMs`, and
+   * its answer is dropped.
    */
   private close(deliver: () => void): void {
     if (this.closing) return;
     this.closing = true;
     this.queue.length = 0;
+    void this.terminate();
     if (this.inFlight.size === 0) {
-      this.finished = true;
       deliver();
       return;
     }
@@ -527,7 +391,6 @@ class CodeRun {
       }),
     ]).then(() => {
       clearTimeout(grace);
-      this.finished = true;
       deliver();
     });
   }
@@ -545,25 +408,18 @@ class CodeRun {
     this.wallTimer = setTimeout(check, Math.max(10, Math.min(250, this.limits.wallMs)));
   }
 
-  /**
-   * Frees the program's runtime. An instance that threw, or whose runtime cannot be freed after a
-   * stack overflow left objects behind, is abandoned instead: it is the program's own, and garbage
-   * collection reclaims its memory.
-   */
-  private dispose(): void {
+  /** Ends the program's worker, whatever it computes, which frees its WebAssembly instance with it. */
+  private terminate(): Promise<unknown> {
+    clearTimeout(this.watchdog);
+    this.terminated ??= this.worker?.terminate() ?? Promise.resolve();
+    return this.terminated;
+  }
+
+  private async dispose(): Promise<void> {
     this.closing = true;
-    this.finished = true;
     if (this.wallTimer) clearTimeout(this.wallTimer);
     this.queue.length = 0;
     this.calls.abort();
-    if (this.broken) return;
-    try {
-      for (const deferred of this.deferreds) if (deferred.alive) deferred.dispose();
-      this.deferreds.clear();
-      this.vm?.dispose();
-      if (this.runtime?.alive) this.runtime.dispose();
-    } catch {
-      this.broken = true;
-    }
+    await this.terminate();
   }
 }