@wirebench/engine 2.2.1 → 3.1.0-rc.1

package/dist/script/request-scripts.js

@@ -0,0 +1,160 @@
+/**
+ * A request's scripts in a send (spec §Results): which ones run, the type check before the send,
+ * and the pre-request and post-response runs. The run (`run/run.ts`) and the app's send paths both
+ * go through this, so a script behaves the same in a pipeline and on a click.
+ */
+import { createHash } from 'node:crypto';
+import { WirebenchError } from '../errors.js';
+import { scriptFileName, } from './model.js';
+import { runScript } from './run.js';
+import { scriptDeclarations } from './types/api.js';
+/** The scripts of a request that will run: none when there are none or they are switched off. */
+export function activeScripts(scripts) {
+    if (scripts === undefined || !scripts.enabled || (scripts.pre === undefined && scripts.post === undefined)) {
+        return undefined;
+    }
+    return scripts;
+}
+/**
+ * Refuses a request whose script file is missing or too large: sending it without that script
+ * would be sending something other than what the request says.
+ *
+ * @throws WirebenchError `script-file-missing` | `script-too-large`
+ */
+export function assertScriptsUsable(scripts, path) {
+    for (const [phase, source] of [
+        ['pre', scripts.pre],
+        ['post', scripts.post],
+    ]) {
+        if (source?.problem !== undefined) {
+            const which = phase === 'pre' ? 'pre-request' : 'post-response';
+            throw new WirebenchError(source.problem, source.problem === 'script-file-missing'
+                ? `"${path}": its ${which} script file is missing`
+                : `"${path}": its ${which} script is over the size limit`, { details: { path, phase } });
+        }
+    }
+}
+/** A script failure as the error a send reports, with the script's file and position in it. */
+export function scriptError(failure, filename) {
+    const where = failure.position !== undefined
+        ? `${filename}:${String(failure.position.line)}:${String(failure.position.column)}`
+        : filename;
+    return new WirebenchError(failure.code, `${where}: ${failure.message}`, {
+        details: { file: filename, ...(failure.position !== undefined ? { ...failure.position } : {}) },
+    });
+}
+/** A type-check failure: every error, as `file:line:column: message`. */
+export function typeCheckError(path, errors) {
+    const lines = errors.map(({ file, diagnostic: d }) => `${file}:${String(d.line)}:${String(d.column)}: ${d.message}`);
+    return new WirebenchError('script-type-error', `"${path}" has script type errors:\n${lines.join('\n')}`, {
+        details: {
+            path,
+            errors: errors.map(({ file, diagnostic }) => ({
+                file,
+                line: diagnostic.line,
+                column: diagnostic.column,
+                message: diagnostic.message,
+            })),
+        },
+    });
+}
+/** Runs requests' scripts, caching each script's type check by its text and its types. */
+export class RequestScripting {
+    options;
+    checked = new Map();
+    constructor(options) {
+        this.options = options;
+    }
+    filename(request, phase) {
+        return scriptFileName(request.slug, phase, request.scripts.api);
+    }
+    diagnostics(request, phase, source) {
+        const checker = this.options.checker;
+        if (checker === undefined)
+            return Promise.resolve([]);
+        const declarations = request.scripts.api === 'postman'
+            ? ''
+            : scriptDeclarations(request.protocol, phase, request.scripts.secrets, request.types.generated, this.options.registry);
+        const key = createHash('sha256')
+            .update(request.scripts.api)
+            .update('\0')
+            .update(source.text)
+            .update('\0')
+            .update(declarations)
+            .digest('hex');
+        let found = this.checked.get(key);
+        if (found === undefined) {
+            found = checker.check({ source: source.text, declarations, api: request.scripts.api });
+            found.catch(() => this.checked.delete(key));
+            this.checked.set(key, found);
+        }
+        return found;
+    }
+    /**
+     * Type-checks a request's scripts (syntax only for a Postman one).
+     *
+     * @throws WirebenchError `script-type-error` (or `script-syntax-error` for a Postman script)
+     */
+    async check(request) {
+        assertScriptsUsable(request.scripts, request.path);
+        const errors = [];
+        for (const phase of ['pre', 'post']) {
+            const source = request.scripts[phase];
+            if (source === undefined)
+                continue;
+            const file = this.filename(request, phase);
+            for (const diagnostic of await this.diagnostics(request, phase, source)) {
+                if (diagnostic.severity === 'error')
+                    errors.push({ file, diagnostic });
+            }
+        }
+        if (errors.length > 0) {
+            const error = typeCheckError(request.path, errors);
+            throw request.scripts.api === 'postman'
+                ? new WirebenchError('script-syntax-error', error.message, { details: error.details ?? {} })
+                : error;
+        }
+    }
+    run(request, phase, snapshot, response, values, layer) {
+        const source = request.scripts[phase];
+        if (source === undefined)
+            throw new Error(`No ${phase} script`);
+        return runScript({
+            sandbox: this.options.sandbox,
+            phase,
+            api: request.scripts.api,
+            source: source.text,
+            filename: this.filename(request, phase),
+            ...(request.scripts.timeoutMs !== undefined ? { timeoutMs: request.scripts.timeoutMs } : {}),
+            request: snapshot,
+            ...(response !== undefined ? { response } : {}),
+            vars: values.vars,
+            props: values.props,
+            secrets: values.secrets,
+            requestName: request.name,
+            ...(layer !== undefined ? { layer } : {}),
+            ...(this.options.onSecretValue !== undefined ? { onSecretValue: this.options.onSecretValue } : {}),
+            ...(request.types.binding !== undefined ? { binding: request.types.binding } : {}),
+            ...(this.options.registry !== undefined ? { registry: this.options.registry } : {}),
+        });
+    }
+    /**
+     * The pre-request script's outcome. A failure is thrown: the request is not sent.
+     *
+     * @throws WirebenchError with the script's error code
+     */
+    async pre(request, snapshot, values, layer) {
+        const outcome = await this.run(request, 'pre', snapshot, undefined, values, layer);
+        if (!outcome.ok)
+            throw scriptError(outcome.error, this.filename(request, 'pre'));
+        return outcome;
+    }
+    /** The post-response script's outcome; a failure is returned, since the response is kept. */
+    post(request, sent, response, values, layer) {
+        return this.run(request, 'post', sent, response, values, layer);
+    }
+    /** The file name errors in a phase's script are reported against. */
+    fileOf(request, phase) {
+        return this.filename(request, phase);
+    }
+}

package/dist/script/run.d.ts

@@ -0,0 +1,47 @@
+import type { RequestSnapshotBase, ResponseSnapshotBase } from '../protocol/module.js';
+import type { ProtocolRegistry } from '../protocol/registry.js';
+import type { ResponseSnapshot } from '../protocols.js';
+import { type ScriptApi, type ScriptOutcome, type ScriptPhase } from './model.js';
+import type { ScriptSandbox } from './sandbox/host.js';
+export interface ScriptRunInput {
+    readonly sandbox: ScriptSandbox;
+    readonly phase: ScriptPhase;
+    readonly api: ScriptApi;
+    /** The script as written: TypeScript for the `wirebench` API, JavaScript for `postman`. */
+    readonly source: string;
+    /** The script's file name, which errors are reported against. */
+    readonly filename: string;
+    readonly timeoutMs?: number;
+    /** For a pre-request script, the request it may change; for a post-response one, what was sent. */
+    readonly request: RequestSnapshotBase;
+    /**
+     * Required for a post-response script. Any module's response snapshot; the built-in union is
+     * named only so that a literal of one of its members type-checks.
+     */
+    readonly response?: ResponseSnapshot | ResponseSnapshotBase;
+    /** The run's values so far (spec §Values). */
+    readonly vars: Readonly<Record<string, string>>;
+    /** Resolved properties, secrets excluded. */
+    readonly props: Readonly<Record<string, string>>;
+    /** The values of the secrets `scripts.secrets` lists, and no others. */
+    readonly secrets: Readonly<Record<string, string>>;
+    /** The request's name, for `pm.info.requestName`. */
+    readonly requestName: string;
+    /** An extra layer run after the API and before the script (the Postman one, spec §Postman). */
+    readonly layer?: string;
+    /** Called with each secret value before the script runs, so it is masked wherever it lands. */
+    readonly onSecretValue?: (value: string) => void;
+    /**
+     * What the request's module put on its script types for typed views (`RequestScriptTypes.binding`).
+     * For SOAP: the schema and the operation's elements, which give the script a typed `request.body`
+     * and `response.body`. Without it the body is only reachable as `envelope`.
+     */
+    readonly binding?: unknown;
+    /** Where the request's protocol is looked up; the built-in registry when absent. */
+    readonly registry?: ProtocolRegistry;
+}
+/**
+ * Runs one script. A request whose protocol has no scripting facet in the registry fails with
+ * `script-unsupported`, and nothing runs.
+ */
+export declare function runScript(input: ScriptRunInput): Promise<ScriptOutcome>;

package/dist/script/run.js

@@ -0,0 +1,146 @@
+/**
+ * Runs one pre-request or post-response script and checks what it hands back (spec §API, §Results).
+ *
+ * The caller supplies the request (and, after a send, the response) as a snapshot, the run's values,
+ * the non-secret properties and only the secrets the request file lists. Each of those secrets is
+ * reported to `onSecretValue` before the script runs, so whatever the script does with one — log it,
+ * set it as a value, write it into the request — is masked downstream.
+ */
+import { z } from 'zod';
+import { TRANSFER_NAME_PATTERN } from '../sequence/model.js';
+import { applyRequestChanges } from './apply.js';
+import { buildPrelude } from './api/prelude.js';
+import { POSTMAN_LAYER } from './api/postman.js';
+import { scriptingOf } from './lookup.js';
+import { SCRIPT_OUTPUT_LIMITS, } from './model.js';
+import { StripError, stripTypes } from './strip.js';
+/** A rule's error, raised in the sandbox by name (`api/prelude.ts`), mapped to its code. */
+const CODE_BY_ERROR_NAME = {
+    ScriptSecretDenied: 'script-secret-denied',
+    ScriptValueInvalid: 'script-value-invalid',
+    ScriptUnsupported: 'script-unsupported',
+};
+const outputSchema = z.object({
+    tests: z
+        .array(z.object({ name: z.string(), passed: z.boolean(), message: z.string().optional() }))
+        .max(SCRIPT_OUTPUT_LIMITS.tests),
+    values: z
+        .array(z.object({
+        name: z.string().regex(TRANSFER_NAME_PATTERN),
+        value: z.string().refine((v) => Buffer.byteLength(v, 'utf8') <= SCRIPT_OUTPUT_LIMITS.valueBytes),
+        secret: z.boolean(),
+    }))
+        .max(SCRIPT_OUTPUT_LIMITS.values),
+    request: z.unknown().optional(),
+});
+function failureOf(error) {
+    if (error.code === 'script-error') {
+        const name = /^(\w+):/.exec(error.message)?.[1];
+        const code = name !== undefined ? CODE_BY_ERROR_NAME[name] : undefined;
+        if (code !== undefined) {
+            return { ...error, code, message: error.message.slice((name ?? '').length + 1).trim() };
+        }
+    }
+    return error;
+}
+function readOutput(output) {
+    const parsed = outputSchema.safeParse(output);
+    return parsed.success ? parsed.data : undefined;
+}
+const cleanTests = (tests) => tests.map((t) => ({ name: t.name, passed: t.passed, ...(t.message !== undefined ? { message: t.message } : {}) }));
+/**
+ * Runs one script. A request whose protocol has no scripting facet in the registry fails with
+ * `script-unsupported`, and nothing runs.
+ */
+export async function runScript(input) {
+    const empty = { tests: [], values: [], log: { lines: [], truncated: false } };
+    if (input.phase === 'post' && input.response === undefined) {
+        throw new Error('runScript: a post-response script needs the response');
+    }
+    const scripting = scriptingOf(input.request.protocol, input.registry);
+    if (scripting === undefined) {
+        return {
+            ok: false,
+            error: {
+                code: 'script-unsupported',
+                message: `Requests of the "${input.request.protocol}" protocol cannot have scripts`,
+            },
+            ...empty,
+        };
+    }
+    let code;
+    try {
+        code = input.api === 'wirebench' ? stripTypes(input.source) : input.source;
+    }
+    catch (error) {
+        return {
+            ok: false,
+            error: { code: 'script-syntax-error', message: error instanceof StripError ? error.message : String(error) },
+            ...empty,
+        };
+    }
+    for (const value of Object.values(input.secrets)) {
+        input.onSecretValue?.(value);
+    }
+    // The views read only the binding; a script's generated types are the checker's business.
+    const types = {
+        generated: '',
+        ...(input.binding !== undefined ? { binding: input.binding } : {}),
+    };
+    const request = scripting.views?.request(input.request, types) ?? input.request;
+    const response = input.response === undefined ? undefined : (scripting.views?.response(input.response, types) ?? input.response);
+    const result = await input.sandbox.run({
+        prelude: buildPrelude(scripting, input.phase, input.api, input.layer ?? (input.api === 'postman' ? POSTMAN_LAYER : undefined)),
+        code,
+        filename: input.filename,
+        timeoutMs: input.timeoutMs ?? 0,
+        input: {
+            phase: input.phase,
+            request,
+            ...(response !== undefined ? { response } : {}),
+            vars: input.vars,
+            props: input.props,
+            secrets: input.secrets,
+            info: { requestName: input.requestName },
+        },
+    });
+    const output = readOutput(result.ok ? result.output : result.output);
+    const tests = output !== undefined ? cleanTests(output.tests) : [];
+    const values = output?.values ?? [];
+    if (!result.ok) {
+        return { ok: false, error: failureOf(result.error), tests, values, log: result.log };
+    }
+    if (output === undefined) {
+        return {
+            ok: false,
+            error: { code: 'script-error', message: 'The script handed back something the engine cannot read' },
+            ...empty,
+            log: result.log,
+        };
+    }
+    if (input.phase === 'pre') {
+        const applied = applyRequestChanges(scripting, request, output.request);
+        if (!applied.ok) {
+            return { ok: false, error: applied.error, tests, values, log: result.log };
+        }
+        const written = scripting.views?.writeBack(request, applied.request, types) ?? {
+            ok: true,
+            request: applied.request,
+        };
+        if (!written.ok) {
+            return { ok: false, error: written.error, tests, values, log: result.log };
+        }
+        if (scripting.views === undefined) {
+            return { ok: true, request: written.request, tests, values, log: result.log };
+        }
+        // A view (SOAP's `request.body`) is written back after the rules ran, so what it wrote has not
+        // been checked yet: hold the request that is sent to the rules again, against the one the
+        // script was given. Otherwise a script could name any secret through the view.
+        const checked = applyRequestChanges(scripting, input.request, written.request);
+        if (!checked.ok) {
+            return { ok: false, error: checked.error, tests, values, log: result.log };
+        }
+        return { ok: true, request: checked.request, tests, values, log: result.log };
+    }
+    return { ok: true, tests, values, log: result.log };
+}

package/dist/script/sandbox/execute.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Runs one {@link SandboxJob} in a fresh QuickJS runtime (ADR-0016).
+ *
+ * The runtime gets a memory limit, a stack limit and an interrupt handler with the job's deadline,
+ * and a context holding nothing but the ECMAScript library and `__host`, an object of plain
+ * functions of strings. The prelude builds the script's API from those, the script runs, and
+ * `__finish()` hands back the result as JSON text. Every handle is disposed before this returns, and
+ * the runtime with it: nothing a script did survives into the next job.
+ *
+ * This runs inside the sandbox worker (`worker.ts`). Its stack must be larger than the QuickJS stack
+ * limit, or a deep recursion overflows the host's stack before QuickJS's own check trips; the host
+ * starts the worker with room to spare.
+ */
+import type { QuickJSWASMModule } from 'quickjs-emscripten-core';
+import { type SandboxError, type SandboxJob, type SandboxResult, type ScriptPosition } from './model.js';
+/** What the worker hands back: the result, and whether the runtime ended in a state worth not reusing the worker after. */
+export interface ExecuteOutcome {
+    readonly result: SandboxResult;
+    /** True after a timeout, memory exhaustion or a failed dispose: the host replaces the worker. */
+    readonly recycle: boolean;
+}
+/** The first `file:line:column` of the script's own file in a QuickJS stack. */
+export declare function positionIn(stack: string, filename: string): ScriptPosition | undefined;
+/** Maps what the script threw to the sandbox's error codes. */
+export declare function toSandboxError(value: unknown, filename: string, interrupted: boolean): SandboxError;
+export declare function executeJob(module: QuickJSWASMModule, job: SandboxJob): ExecuteOutcome;

package/dist/script/sandbox/execute.js

@@ -0,0 +1,212 @@
+import { base64, base64url, fromBase64, hash, hmac, HostCallError, LogCollector, urlEncode, uuid, xpathStrings, } from './host-api.js';
+import { SCRIPT_LIMITS } from './model.js';
+const PRELUDE_FILE = '<prelude>';
+const FINISH_FILE = '<finish>';
+function escapeRegExp(text) {
+    return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/** The first `file:line:column` of the script's own file in a QuickJS stack. */
+export function positionIn(stack, filename) {
+    const match = new RegExp(`${escapeRegExp(filename)}:(\\d+):(\\d+)`).exec(stack);
+    if (match === null) {
+        return undefined;
+    }
+    return { line: Number(match[1]), column: Number(match[2]) };
+}
+function describe(value) {
+    if (typeof value === 'object' && value !== null) {
+        const error = value;
+        const name = typeof error.name === 'string' ? error.name : undefined;
+        const message = typeof error.message === 'string' ? error.message : undefined;
+        const stack = typeof error.stack === 'string' ? error.stack : '';
+        if (message !== undefined) {
+            return {
+                text: name !== undefined ? `${name}: ${message}` : message,
+                ...(name !== undefined ? { name } : {}),
+                stack,
+            };
+        }
+    }
+    if (typeof value === 'string') {
+        return { text: value, stack: '' };
+    }
+    let text;
+    try {
+        text = JSON.stringify(value) ?? String(value);
+    }
+    catch {
+        text = String(value);
+    }
+    return { text, stack: '' };
+}
+/** Maps what the script threw to the sandbox's error codes. */
+export function toSandboxError(value, filename, interrupted) {
+    const { text, name, stack } = describe(value);
+    if (interrupted || (name === 'InternalError' && text.endsWith('interrupted'))) {
+        return { code: 'script-timeout', message: 'The script ran past its time limit' };
+    }
+    if (name === 'InternalError' && text.endsWith('out of memory')) {
+        return { code: 'script-memory', message: 'The script ran out of memory' };
+    }
+    const position = positionIn(stack, filename);
+    return { code: 'script-error', message: text, ...(position !== undefined ? { position } : {}) };
+}
+/** A host function's argument as a string; anything else is refused with a message the script sees. */
+function stringArg(context, handle, what) {
+    const value = handle === undefined ? undefined : context.dump(handle);
+    if (typeof value !== 'string') {
+        throw new HostCallError(`${what} must be a string`);
+    }
+    return value;
+}
+function optionalStringArg(context, handle, what) {
+    const value = handle === undefined ? undefined : context.dump(handle);
+    if (value === undefined) {
+        return undefined;
+    }
+    if (typeof value !== 'string') {
+        throw new HostCallError(`${what} must be a string`);
+    }
+    return value;
+}
+/** Installs `__host`: plain functions of strings, and nothing else of the host. */
+function installHost(context, log, inputJson) {
+    const functions = {
+        log: (ctx, args) => {
+            log.add(stringArg(ctx, args[0], 'a log line'));
+            return undefined;
+        },
+        hash: (ctx, args) => ctx.newString(hash(stringArg(ctx, args[0], 'algorithm'), stringArg(ctx, args[1], 'data'), optionalStringArg(ctx, args[2], 'encoding'))),
+        hmac: (ctx, args) => ctx.newString(hmac(stringArg(ctx, args[0], 'algorithm'), stringArg(ctx, args[1], 'key'), stringArg(ctx, args[2], 'data'), optionalStringArg(ctx, args[3], 'encoding'))),
+        uuid: (ctx) => ctx.newString(uuid()),
+        base64: (ctx, args) => ctx.newString(base64(stringArg(ctx, args[0], 'text'))),
+        fromBase64: (ctx, args) => ctx.newString(fromBase64(stringArg(ctx, args[0], 'text'))),
+        base64url: (ctx, args) => ctx.newString(base64url(stringArg(ctx, args[0], 'text'))),
+        urlEncode: (ctx, args) => ctx.newString(urlEncode(stringArg(ctx, args[0], 'text'))),
+        xpath: (ctx, args) => ctx.newString(xpathStrings(stringArg(ctx, args[0], 'xml'), stringArg(ctx, args[1], 'expression'), stringArg(ctx, args[2], 'namespaces'))),
+    };
+    const host = context.newObject();
+    try {
+        for (const [name, implementation] of Object.entries(functions)) {
+            const fn = context.newFunction(name, (...args) => {
+                try {
+                    return implementation(context, args);
+                }
+                catch (error) {
+                    const message = error instanceof HostCallError ? error.message : 'the host function failed';
+                    return { error: context.newError(`${name}: ${message}`) };
+                }
+            });
+            context.setProp(host, name, fn);
+            fn.dispose();
+        }
+        const input = context.newString(inputJson);
+        context.setProp(host, 'inputJson', input);
+        input.dispose();
+        context.setProp(context.global, '__host', host);
+    }
+    finally {
+        host.dispose();
+    }
+}
+/** Evaluates code and returns its value dumped to plain data, or what it threw. */
+function evaluate(context, code, filename) {
+    const result = context.evalCode(code, filename, { type: 'global', strict: true, backtraceBarrier: true });
+    if ('error' in result && result.error !== undefined) {
+        const thrown = context.dump(result.error);
+        result.error.dispose();
+        return { ok: false, thrown };
+    }
+    const value = context.dump(result.value);
+    result.value.dispose();
+    return { ok: true, value };
+}
+/** `__finish()`'s JSON, parsed; refused when it is not text or is past the output cap. */
+function finish(context) {
+    const done = evaluate(context, 'JSON.stringify(__finish())', FINISH_FILE);
+    if (!done.ok) {
+        return { ok: false, error: toSandboxError(done.thrown, FINISH_FILE, false) };
+    }
+    if (typeof done.value !== 'string') {
+        return { ok: true, output: undefined };
+    }
+    if (Buffer.byteLength(done.value, 'utf8') > SCRIPT_LIMITS.outputBytes) {
+        return {
+            ok: false,
+            error: { code: 'script-error', message: 'The script handed back more than its output limit allows' },
+        };
+    }
+    return { ok: true, output: JSON.parse(done.value) };
+}
+export function executeJob(module, job) {
+    const log = new LogCollector();
+    const runtime = module.newRuntime();
+    let interrupted = false;
+    let recycle = false;
+    const deadline = Date.now() + job.timeoutMs;
+    runtime.setMemoryLimit(SCRIPT_LIMITS.memoryBytes);
+    runtime.setMaxStackSize(SCRIPT_LIMITS.stackBytes);
+    runtime.setInterruptHandler(() => {
+        if (Date.now() > deadline) {
+            interrupted = true;
+        }
+        return interrupted;
+    });
+    const context = runtime.newContext();
+    let result;
+    try {
+        installHost(context, log, JSON.stringify(job.input ?? null));
+        const prelude = evaluate(context, job.prelude, PRELUDE_FILE);
+        if (!prelude.ok) {
+            const error = toSandboxError(prelude.thrown, PRELUDE_FILE, interrupted);
+            result = {
+                ok: false,
+                error: error.code === 'script-error'
+                    ? { code: 'script-error', message: `The script API failed to start: ${error.message}` }
+                    : error,
+                log: log.result(),
+            };
+        }
+        else {
+            const ran = evaluate(context, job.code, job.filename);
+            if (ran.ok) {
+                const done = finish(context);
+                result = done.ok
+                    ? { ok: true, output: done.output, log: log.result() }
+                    : { ok: false, error: done.error, log: log.result() };
+            }
+            else {
+                const error = toSandboxError(ran.thrown, job.filename, interrupted);
+                // A script that threw may still have recorded tests before it did; keep them. A script that
+                // ran out of time or memory gets nothing more run on its behalf.
+                const done = error.code === 'script-error' ? finish(context) : undefined;
+                result = {
+                    ok: false,
+                    error,
+                    log: log.result(),
+                    ...(done?.ok === true ? { output: done.output } : {}),
+                };
+            }
+        }
+    }
+    catch (error) {
+        // The host itself failed (for instance the WASM heap was exhausted outside the runtime's limit).
+        recycle = true;
+        result = {
+            ok: false,
+            error: { code: 'script-error', message: error instanceof Error ? error.message : String(error) },
+            log: log.result(),
+        };
+    }
+    if (!result.ok && result.error.code !== 'script-error') {
+        recycle = true;
+    }
+    try {
+        context.dispose();
+        runtime.dispose();
+    }
+    catch {
+        recycle = true;
+    }
+    return { result, recycle };
+}

package/dist/script/sandbox/host-api.d.ts

@@ -0,0 +1,27 @@
+import { type SandboxLog } from './model.js';
+export declare const HASH_ALGORITHMS: readonly ["md5", "sha1", "sha256", "sha512"];
+export declare const HMAC_ALGORITHMS: readonly ["sha1", "sha256", "sha512"];
+export declare const DIGEST_ENCODINGS: readonly ["hex", "base64"];
+/** Thrown into the script (as its message) when a host function is called with something it refuses. */
+export declare class HostCallError extends Error {
+}
+export declare function hash(algorithm: string, data: string, encoding?: string): string;
+export declare function hmac(algorithm: string, key: string, data: string, encoding?: string): string;
+export declare function uuid(): string;
+export declare function base64(text: string): string;
+export declare function fromBase64(text: string): string;
+export declare function base64url(text: string): string;
+export declare function urlEncode(text: string): string;
+/**
+ * The strings an XPath expression selects in `xml`, as JSON text: each node's text, or each value.
+ * `namespacesJson` is a JSON object of prefix to URI.
+ */
+export declare function xpathStrings(xml: string, expression: string, namespacesJson: string): string;
+/** Collects `log(...)` lines within the caps; anything past them is dropped and flagged. */
+export declare class LogCollector {
+    private readonly lines;
+    private bytes;
+    private truncated;
+    add(line: string): void;
+    result(): SandboxLog;
+}