withruntime 0.8.4 → 0.10.0

package/dist/blaxel/preview.js

@@ -1,8 +1,5 @@
 import { guard, isNotFound, NotSupportedError, responseError } from "./errors.js";
 import { PREVIEW } from "./lookup.js";
-/** Runtime's shortest and longest token, in seconds. */
-const TOKEN_MIN = 60;
-const TOKEN_MAX = 7 * 86_400;
 function checkName(name) {
     if (!/^[A-Za-z0-9._-]{1,48}$/.test(name))
         throw new NotSupportedError(`The preview name "${name}"`, "Use 1 to 48 letters, digits, dots, dashes or underscores.");
@@ -56,19 +53,24 @@ export class SandboxPreviewTokens {
     get resourceName() {
         return this.#ctx.sandboxName;
     }
-    /** A token that lasts until `expiresAt` (at least a minute, at most a week). */
+    /** A token bounded by `expiresAt`; native signing floors milliseconds and
+     * caps it to the caller's session. Older servers refuse without a TTL fallback. */
     async create(expiresAt) {
-        const seconds = Math.ceil((expiresAt.getTime() - Date.now()) / 1000);
-        if (seconds > TOKEN_MAX)
-            throw new NotSupportedError("A preview token lasting more than a week", "Create one for at most seven days, and a new one when it runs out.");
-        const port = this.#preview.spec.port;
-        const got = await this.#ctx.run((runtime) => runtime.previews.get(port, Math.max(TOKEN_MIN, seconds)));
+        const requested = expiresAt.getTime();
+        if (!Number.isFinite(requested))
+            throw responseError(400, "A preview token needs a valid expiration date.");
+        const remaining = requested - Date.now();
+        if (remaining < 60_000 || remaining > 7 * 86_400_000)
+            throw new NotSupportedError("A preview token lasting less than a minute or more than a week", "Request an expiration at least one minute and at most seven days away.");
+        const got = await this.#ctx.run((runtime) => runtime.previews.get(this.#preview.spec.port, undefined, {
+            expiresAt: expiresAt.toISOString(),
+        }));
+        const actual = got.tokenExpiresAt === null ? Number.NaN : Date.parse(got.tokenExpiresAt);
+        if (!got.token || !Number.isFinite(actual) || actual > requested)
+            throw new NotSupportedError("A preview token with the requested expiration", "The server must issue a token that never outlives the requested expiration; no duration-based fallback was requested.");
         return new SandboxPreviewToken({
             metadata: { name: `token-${Date.now()}`, previewName: this.previewName },
-            spec: {
-                ...(got.token ? { token: got.token } : {}),
-                ...(got.tokenExpiresAt ? { expiresAt: got.tokenExpiresAt } : {}),
-            },
+            spec: { token: got.token, expiresAt: got.tokenExpiresAt },
         });
     }
     list() {
@@ -193,7 +195,7 @@ export class SandboxPreviews {
         const found = await this.#ctx.run((runtime) => runtime.previews.get(port));
         return new SandboxPreview(modelOf(found, previewName, this.sandboxName), this.#ctx);
     }
-    /** Stops sharing the port; open connections close within seconds. */
+    /** Stops sharing the port; its open connections are closed before this returns. */
     async delete(previewName) {
         const port = this.#portOf(previewName);
         if (port === undefined)

package/dist/blaxel/process.d.ts

@@ -87,7 +87,7 @@ export declare class SandboxProcess {
      * process running; with it, once the process ends, with its output. */
     exec(request: ProcessRequest | ProcessRequestWithLog): Promise<PostProcessResponse | ProcessResponseWithLog>;
     /** The process, with the output it has written so far. */
-    get(identifier: string, _options?: {
+    get(identifier: string, options?: {
         signal?: AbortSignal;
         retry?: boolean;
     }): Promise<GetProcessByIdentifierResponse>;

package/dist/blaxel/process.js

@@ -152,14 +152,17 @@ export class SandboxProcess {
     }
     /** A call that found the sandbox paused (autoWake off) is made again once,
      * after a wake: it never started, so it cannot run twice. */
-    async #retryPaused(work) {
+    async #retryPaused(work, signal) {
+        signal?.throwIfAborted();
         try {
             return await work();
         }
         catch (error) {
+            signal?.throwIfAborted();
             if (codeOf(error) !== "sandbox_paused")
                 throw translate(error);
             await this.#ctx.wake();
+            signal?.throwIfAborted();
             return guard(work);
         }
     }
@@ -182,6 +185,8 @@ export class SandboxProcess {
         const startedAt = new Date().toISOString();
         const run = async () => {
             for await (const event of runtime.execStream(line, { ...options, signal: abort.signal })) {
+                if (event.type === "truncated")
+                    throw responseError(502, "Some command output is no longer available.");
                 if (event.type === "start") {
                     id = event.processId;
                     this.#remember(id, meta);
@@ -279,16 +284,20 @@ export class SandboxProcess {
         };
     }
     /** A process by pid or name: the registry first, then Runtime's list. */
-    async #find(identifier) {
+    async #find(identifier, signal) {
+        signal?.throwIfAborted();
         const runtime = await this.#ctx.live();
+        signal?.throwIfAborted();
         const registry = this.#registry;
         const known = registry.byName.get(identifier) ?? (registry.meta.has(identifier) ? identifier : undefined);
         if (known !== undefined) {
-            const process = await this.#retryPaused(() => runtime.processes.get(known));
+            const process = await this.#retryPaused(() => runtime.processes.get(known, { signal }), signal);
+            signal?.throwIfAborted();
             registry.processes.set(known, process);
             return { id: known, info: process.info, process };
         }
-        const all = await this.#retryPaused(() => runtime.processes.list());
+        const all = await this.#retryPaused(() => runtime.processes.list({ signal }), signal);
+        signal?.throwIfAborted();
         let found;
         for (const info of all) {
             const parsed = parseProcessLine(info.command);
@@ -321,15 +330,20 @@ export class SandboxProcess {
         const running = found.info.state === "running";
         if (running && !untilExit && found.info.outputBytes <= found.info.firstOffset)
             return out;
+        signal?.throwIfAborted();
         const runtime = await this.#ctx.live();
+        signal?.throwIfAborted();
         const abort = new AbortController();
         const forward = () => abort.abort();
+        signal?.throwIfAborted();
         signal?.addEventListener("abort", forward, { once: true });
         try {
             for await (const event of runtime.processes.follow(found.id, {
                 cursor: 0,
                 signal: abort.signal,
             })) {
+                if (event.type === "truncated")
+                    throw responseError(502, "Some command output is no longer available.");
                 if (event.type === "stdout" || event.type === "stderr") {
                     out[event.type] += event.data;
                     out.logs += event.data;
@@ -362,10 +376,32 @@ export class SandboxProcess {
         return out;
     }
     /** The process, with the output it has written so far. */
-    async get(identifier, _options = {}) {
-        const found = await this.#find(identifier);
-        const out = await this.#output(found, false);
-        return this.#settled(this.#response(found.info, this.#registry.meta.get(found.id), out));
+    async get(identifier, options = {}) {
+        options.signal?.throwIfAborted();
+        const signal = options.signal;
+        let onAbort;
+        const interrupted = new Promise((_, reject) => {
+            onAbort = () => reject(new Error("Process read was interrupted.", { cause: signal?.reason }));
+            signal?.addEventListener("abort", onAbort, { once: true });
+        });
+        try {
+            const reading = (async () => {
+                const found = await this.#find(identifier, signal);
+                const out = await this.#output(found, false, signal);
+                signal?.throwIfAborted();
+                return this.#settled(this.#response(found.info, this.#registry.meta.get(found.id), out));
+            })();
+            return await Promise.race([reading, interrupted]);
+        }
+        catch (error) {
+            if (signal?.aborted)
+                throw signal.reason ?? error;
+            throw error;
+        }
+        finally {
+            if (onAbort)
+                signal?.removeEventListener("abort", onAbort);
+        }
     }
     /** Waits for the process to end (at most `maxWait` ms, -1 for no limit) and
      * answers it with its output. The process is never stopped by the wait. */
@@ -381,12 +417,27 @@ export class SandboxProcess {
             throw late();
         const abort = new AbortController();
         const forward = () => abort.abort(signal?.reason);
+        signal?.throwIfAborted();
         signal?.addEventListener("abort", forward, { once: true });
         const timer = maxWait === -1 ? undefined : setTimeout(() => abort.abort(late()), maxWait);
+        let onAbort;
+        const interrupted = new Promise((_, reject) => {
+            onAbort = () => {
+                const reason = abort.signal.reason;
+                reject(reason instanceof Error
+                    ? reason
+                    : new Error("Process wait was interrupted.", { cause: reason }));
+            };
+            abort.signal.addEventListener("abort", onAbort, { once: true });
+        });
         try {
-            const found = await this.#find(identifier);
-            const out = await this.#output(found, true, abort.signal);
-            return await this.#settled(this.#response(found.info, this.#registry.meta.get(found.id), out));
+            const result = (async () => {
+                const found = await this.#find(identifier, abort.signal);
+                const out = await this.#output(found, true, abort.signal);
+                abort.signal.throwIfAborted();
+                return await this.#settled(this.#response(found.info, this.#registry.meta.get(found.id), out));
+            })();
+            return await Promise.race([result, interrupted]);
         }
         catch (error) {
             if (abort.signal.aborted)
@@ -395,6 +446,8 @@ export class SandboxProcess {
         }
         finally {
             clearTimeout(timer);
+            if (onAbort)
+                abort.signal.removeEventListener("abort", onAbort);
             signal?.removeEventListener("abort", forward);
         }
     }
@@ -476,6 +529,8 @@ export class SandboxProcess {
                     cursor: 0,
                     signal: abort.signal,
                 })) {
+                    if (event.type === "truncated")
+                        throw responseError(502, "Some command output is no longer available.");
                     if (event.type === "stdout" || event.type === "stderr") {
                         const lines = (partial[event.type] + event.data).split(/\r?\n/);
                         partial[event.type] = lines.pop();

package/dist/blaxel/sandbox.d.ts

@@ -32,6 +32,8 @@ export type SandboxForkOptions = {
     /** A snapshot's id or, of this sandbox's snapshots, its name. */
     snapshotId?: string;
     envs?: Env[];
+    /** Blaxel's fork override; Runtime cannot enforce this override during a fork. */
+    lifecycle?: SandboxLifecycle;
 };
 export type SandboxArchiveOptions = {
     wait?: boolean;

package/dist/blaxel/sandbox.js

@@ -750,6 +750,8 @@ export class SandboxInstance {
      * (files, memory and running processes), or started from a snapshot with
      * `snapshotId`. `envs` are added over this sandbox's. */
     async fork(targetName, options = {}) {
+        if (options.lifecycle !== undefined)
+            throw new NotSupportedError("Overriding lifecycle during a fork", "Omit lifecycle to use the existing Runtime fork behavior.");
         refuseApplication(options);
         const envs = envRecord(options.envs);
         checkEnvNames(Object.keys(envs));

package/dist/blaxel/snapshot.js

@@ -22,13 +22,11 @@ export function snapshotModel(snapshot, sandboxName) {
 }
 /** Envs as a record; a nameless one is refused. */
 export function envRecord(envs) {
-    const out = {};
-    for (const env of envs ?? []) {
+    return Object.fromEntries((envs ?? []).map((env) => {
         if (!env.name)
             throw responseError(400, "every env needs a name");
-        out[env.name] = env.value ?? "";
-    }
-    return out;
+        return [env.name, env.value ?? ""];
+    }));
 }
 /** Appends envs to a sandbox's env file: they win over the ones it has. */
 export async function appendEnvs(runtime, envs) {

package/dist/cli-words.d.ts

@@ -0,0 +1,27 @@
+import type { RuntimeError } from "./errors.js";
+import type { SandboxMetrics } from "./products/observability.js";
+/** A refusal of what a command sent, reworded for the command line: every
+ * issue named by its option, since the CLI never prints details.issues, and
+ * a hint that names the options rather than the request's fields. Anything
+ * else is left as the API said it. */
+export declare function cliRefusal(error: RuntimeError): {
+    message: string;
+    hint?: string;
+};
+/** A resource read as one fact a line, as `sandbox get` prints: a list
+ * joined, a nested record as its own facts, nothing as `-`. */
+export declare function describeRecord(record: Record<string, unknown>, table: (rows: string[][]) => string): string;
+/** The newest CPU reading the metrics hold, and how old it is. `latest` is
+ * the last sample, which can carry no CPU figure (the first after a wake has
+ * nothing to compare with), while the points before it do; "no reading"
+ * above a sparkline of readings contradicted itself. */
+export declare function newestCpu(m: SandboxMetrics, now?: number): {
+    percent: number;
+    cores: number | null;
+    ago: string | null;
+} | null;
+/** The lines of the top-level help about one command, `  feedback ...` and
+ * the lines that continue it, or null when it has none. `runtime feedback
+ * help` filed "help" as feedback, and `runtime support help` sent it to
+ * support, until 30 September 2026. */
+export declare function topicHelp(help: string, command: string): string | null;

package/dist/cli-words.js

@@ -0,0 +1,135 @@
+/* What the CLI says in its own words where the API's would mislead: the
+   option a refusal is about rather than the request field it was sent as,
+   one fact a line for a resource read, and the newest CPU reading a
+   sandbox's metrics hold. Kept out of cli.ts, which many hands edit. */
+/** The request fields a command line sets, by the option that sets them.
+ * An amount in microdollars is typed in dollars. */
+const OPTIONS = {
+    name: { flag: "--name" },
+    labels: { flag: "--label" },
+    env: { flag: "--env" },
+    region: { flag: "--region" },
+    vcpu: { flag: "--vcpu" },
+    memoryMiB: { flag: "--memory" },
+    diskMiB: { flag: "--disk" },
+    cpu: { flag: "--cpu" },
+    cpuFloorMillis: { flag: "--cpu-floor" },
+    timeoutSeconds: { flag: "--timeout" },
+    onLeaseEnd: { flag: "--on-timeout" },
+    idlePauseSeconds: { flag: "--idle-pause" },
+    autoWake: { flag: "--no-auto-wake / --auto-wake" },
+    persistent: { flag: "--persistent" },
+    funding: { flag: "--trial / --paid" },
+    image: { flag: "--image" },
+    snapshot: { flag: "--snapshot" },
+    volumes: { flag: "--volume" },
+    network: { flag: "--allow / --deny / --connect / --no-internet" },
+    maxCostMicros: { flag: "--max-cost", micros: true },
+    maxTotalCostMicros: { flag: "--max-total-cost", micros: true },
+};
+const usd = (micros) => `$${(micros / 1e6).toLocaleString("en-US", { maximumFractionDigits: 6 })}`;
+/** One issue the API found in a request, in the command line's words:
+ * `body.timeoutSeconds must be at least 60` is `--timeout must be at least 60`. */
+function issueWords(path, message) {
+    const field = /^(?:\$\.)?body\.([A-Za-z]+)/.exec(path)?.[1];
+    const option = field && Object.hasOwn(OPTIONS, field) ? OPTIONS[field] : undefined;
+    if (!option) {
+        const where = path.replace(/^\$\.?/, "").replace(/^(body|query|path)\./, "") || "the request";
+        return `${where} ${message}`;
+    }
+    const said = option.micros ? message.replace(/-?\d+(?:\.\d+)?/g, (n) => usd(Number(n))) : message;
+    return `${option.flag} ${said}`;
+}
+/** A refusal of what a command sent, reworded for the command line: every
+ * issue named by its option, since the CLI never prints details.issues, and
+ * a hint that names the options rather than the request's fields. Anything
+ * else is left as the API said it. */
+export function cliRefusal(error) {
+    const issues = error.details?.issues;
+    if (error.code === "invalid_request" && Array.isArray(issues) && issues.length) {
+        const lines = issues
+            .filter((i) => typeof i.path === "string" && typeof i.message === "string")
+            .map((i) => issueWords(i.path, i.message));
+        if (lines.length)
+            return {
+                message: lines.length === 1 ? `${lines[0]}.` : lines.map((l) => `\n  ${l}`).join(""),
+                hint: "Change what is named above and run the command again.",
+            };
+    }
+    const field = typeof error.details?.field === "string" ? error.details.field : "";
+    const option = Object.hasOwn(OPTIONS, field) ? OPTIONS[field] : undefined;
+    if (option && !option.micros && error.message.includes(field)) {
+        const named = new RegExp(`\\b${field}\\b`, "g");
+        return {
+            message: error.message.replace(named, option.flag),
+            ...(error.hint ? { hint: error.hint.replace(named, option.flag) } : {}),
+        };
+    }
+    return { message: error.message, ...(error.hint ? { hint: error.hint } : {}) };
+}
+/** A resource read as one fact a line, as `sandbox get` prints: a list
+ * joined, a nested record as its own facts, nothing as `-`. */
+export function describeRecord(record, table) {
+    const rows = [];
+    const cell = (value) => {
+        if (value === null || value === undefined || value === "")
+            return "-";
+        if (Array.isArray(value))
+            return value.length
+                ? value.map((v) => (v && typeof v === "object" ? JSON.stringify(v) : String(v))).join(", ")
+                : "-";
+        // A string as it is; a number, a boolean or a record as JSON writes it.
+        return typeof value === "string" ? value : JSON.stringify(value);
+    };
+    const add = (prefix, value) => {
+        for (const [key, v] of Object.entries(value)) {
+            const name = prefix ? `${prefix}.${key}` : key;
+            if (v && typeof v === "object" && !Array.isArray(v) && Object.keys(v).length <= 8)
+                add(name, v);
+            else
+                rows.push([name, cell(v)]);
+        }
+    };
+    add("", record);
+    return table(rows);
+}
+/** The newest CPU reading the metrics hold, and how old it is. `latest` is
+ * the last sample, which can carry no CPU figure (the first after a wake has
+ * nothing to compare with), while the points before it do; "no reading"
+ * above a sparkline of readings contradicted itself. */
+export function newestCpu(m, now = Date.now()) {
+    if (m.latest?.cpuPercent != null)
+        return { percent: m.latest.cpuPercent, cores: m.latest.cpuCores, ago: null };
+    for (let i = m.points.length - 1; i >= 0; i--) {
+        const p = m.points[i];
+        if (p.cpuPercent == null)
+            continue;
+        const seconds = Math.max(0, Math.round((now - Date.parse(p.at)) / 1000));
+        const ago = seconds < 90
+            ? `${seconds} s ago`
+            : seconds < 5400
+                ? `${Math.round(seconds / 60)} min ago`
+                : `${Math.round(seconds / 3600)} h ago`;
+        return { percent: p.cpuPercent, cores: p.cpuCores, ago };
+    }
+    return null;
+}
+/** The lines of the top-level help about one command, `  feedback ...` and
+ * the lines that continue it, or null when it has none. `runtime feedback
+ * help` filed "help" as feedback, and `runtime support help` sent it to
+ * support, until 30 September 2026. */
+export function topicHelp(help, command) {
+    const lines = help.split("\n");
+    const out = [];
+    let inside = false;
+    for (const line of lines) {
+        const starts = line.startsWith(`  ${command} `) || line === `  ${command}`;
+        if (starts)
+            inside = true;
+        else if (inside && !/^ {3,}\S/.test(line))
+            inside = false;
+        if (inside)
+            out.push(line);
+    }
+    return out.length ? out.join("\n") : null;
+}

package/dist/cli.d.ts

@@ -7,6 +7,8 @@ type Out = {
     json: boolean;
     write: (text: string) => void;
     error: (text: string) => void;
+    /** Wait when an output pipe cannot accept another page yet. */
+    drain?: () => Promise<void>;
 };
 type Args = {
     positional: string[];