withruntime 0.9.0 → 0.10.0

package/dist/snapshots.d.ts

@@ -1,8 +1,7 @@
 import { Page } from "./page.js";
 import type { RequestOptions, Transport } from "./transport.js";
-/** A sandbox's whole machine (files, memory, running processes), kept on its
- * host to start new sandboxes from, and copied off the host so it survives
- * losing that host. */
+/** A sandbox's saved machine or disk, used to start new sandboxes. A verified
+ * off-host copy protects it from host loss once `backedUp` is true. */
 export type Snapshot = {
     id: string;
     kind: "snapshot";
@@ -19,13 +18,19 @@ export type Snapshot = {
         memoryGuarantee: string;
     };
     retentionDays: number;
+    /** True while raw fork memory awaits verified compression. The snapshot
+     * remains ready for starts on its current host, with no storage charge or
+     * off-host copy until final publication. Absent on older servers. */
+    compressionPending?: boolean;
     /** What it stores, and what storage is metered for: the bytes it alone holds. */
     storedBytes: number | null;
+    /** Zero while compression is pending; final bytes once verified. */
     meteredBytes: number | null;
     /** Whether its copy off the host is made and checked. */
     backedUp: boolean;
     /** Where that copy stands. `restoring`: its host was lost and it is being
-     * restored onto another; forks answer `snapshot_restoring` until it is. */
+     * restored onto another; forks answer `snapshot_restoring` until it is.
+     * `none` also covers temporary fork snapshots and pending compression. */
     durability: {
         state: "none" | "pending" | "durable" | "failed" | "restoring";
         durableAt: string | null;

package/dist/sprites/index.js

@@ -4,6 +4,16 @@ import { RuntimeError } from "../errors.js";
 import { all, client, CompatibilityError, create, destroy, execOptions, lookup, only, ready, region, } from "../compat/core.js";
 import { GuestFiles } from "../compat/files.js";
 export { CompatibilityError };
+function validateURLSettings(settings) {
+    only("Sprites URL settings", settings, ["auth"]);
+    if (settings.auth !== "public" && settings.auth !== "sprite")
+        throw new TypeError("auth must be public or sprite");
+}
+function validateLabels(labels) {
+    if (labels !== undefined &&
+        (!Array.isArray(labels) || Array.from(labels).some((label) => typeof label !== "string")))
+        throw new TypeError("labels must be an array of strings");
+}
 export class FilesystemError extends Error {
     code;
     path;
@@ -90,8 +100,9 @@ export class SpritesClient {
         ]);
         if (o.runtime !== undefined)
             throw new CompatibilityError("Sprites", `vendor runtime image ${o.runtime}; import it into Runtime first`);
-        if (o.urlSettings?.privateAccess)
-            throw new CompatibilityError("Sprites", "privateAccess roles");
+        if (o.urlSettings !== undefined)
+            validateURLSettings(o.urlSettings);
+        validateLabels(o.labels);
         const c = o.config ?? {};
         only("Sprites config", c, ["ramMB", "cpus", "region", "storageGB"]);
         const s = await create(this.runtime, "sprites", {
@@ -102,7 +113,7 @@ export class SpritesClient {
             diskMiB: c.storageGB === undefined ? undefined : Math.ceil((c.storageGB * 1e9) / 1048576),
             region: region("Sprites", c.region),
             labels: { "compat.labels": JSON.stringify(o.labels ?? []) },
-        }, o.environment);
+        }, o.environment, undefined, o.waitForCapacity === false ? { waitForCapacityMs: 0 } : {});
         const sprite = new Sprite(name, this);
         sprite.hydrate(s);
         if (o.urlSettings) {
@@ -205,6 +216,8 @@ export class Sprite {
     }
     async execFile(file, args = [], options = {}) {
         options.signal?.throwIfAborted();
+        if (options.timeout !== undefined && (!Number.isFinite(options.timeout) || options.timeout < 0))
+            throw new TypeError("timeout must be a non-negative finite number");
         if (options.encoding &&
             options.encoding !== "buffer" &&
             !Buffer.isEncoding(options.encoding))
@@ -227,29 +240,45 @@ export class Sprite {
             throw new CompatibilityError("Sprites", "control-mode wire protocol");
         const cmd = this.spawn(file, args, options);
         const out = [], err = [];
-        let bytes = 0;
+        const maxBuffer = options.maxBuffer || 10 * 1024 * 1024;
+        let stdoutBytes = 0;
+        let stderrBytes = 0;
         let failure;
-        const capture = (target) => (chunk) => {
-            bytes += chunk.length;
-            if (bytes > (options.maxBuffer ?? 10 * 1024 * 1024)) {
-                failure = new Error("maxBuffer exceeded");
-                cmd.kill("SIGKILL");
-            }
+        let rejectFailure = () => undefined;
+        const failed = new Promise((_resolve, reject) => {
+            rejectFailure = reject;
+        });
+        const cancel = (error) => {
+            if (failure)
+                return;
+            failure = error;
+            cmd.kill("SIGTERM");
+            cmd.close();
+            rejectFailure(error);
+        };
+        const capture = (channel, target) => (chunk) => {
+            if (failure)
+                return;
+            if (channel === "stdout")
+                stdoutBytes += chunk.length;
+            else
+                stderrBytes += chunk.length;
+            if ((channel === "stdout" ? stdoutBytes : stderrBytes) > maxBuffer)
+                cancel(new Error(`${channel} maxBuffer exceeded`));
             else
                 target.push(chunk);
         };
-        cmd.stdout.on("data", capture(out));
-        cmd.stderr.on("data", capture(err));
-        const abort = () => {
-            failure = new Error("Command aborted");
-            cmd.kill("SIGTERM");
-        };
+        cmd.stdout.on("data", capture("stdout", out));
+        cmd.stderr.on("data", capture("stderr", err));
+        const abort = () => cancel(new Error("Command aborted"));
         options.signal?.addEventListener("abort", abort, { once: true });
         if (options.signal?.aborted)
             abort();
-        const timer = options.timeout ? setTimeout(abort, options.timeout) : undefined;
+        const timer = options.timeout
+            ? setTimeout(() => cancel(new Error(`Command timed out after ${options.timeout} ms`)), options.timeout)
+            : undefined;
         try {
-            const exitCode = await cmd.wait();
+            const exitCode = await Promise.race([cmd.wait(), failed]);
             if (failure)
                 throw failure;
             const stdout = Buffer.concat(out), stderr = Buffer.concat(err);
@@ -276,7 +305,9 @@ export class Sprite {
         return this.execFile(file, args, options);
     }
     createSession(command, args = [], options = {}) {
-        return this.spawn(command, args, { ...options, detachable: true });
+        // The pinned SDK's session wrapper forces a terminal, even when a caller
+        // supplies tty:false. Attaching an existing session detects its own PTY.
+        return this.spawn(command, args, { ...options, detachable: true, tty: true });
     }
     attachSession(sessionId, options = {}) {
         return this.spawn("", [], { ...options, sessionId });
@@ -315,14 +346,17 @@ export class Sprite {
         throw new CompatibilityError("Sprites", "filesystem-only checkpoints");
     }
     async updateURLSettings(settings) {
-        only("Sprites URL settings", settings, ["auth"]);
-        if (settings.auth !== "public" && settings.auth !== "sprite")
-            throw new TypeError("auth must be public or sprite");
+        validateURLSettings(settings);
         const p = await (await this.native()).previews.create(8080, { visibility: settings.auth === "public" ? "public" : "private" });
         this.url = p.urlWithToken ?? p.url;
     }
     async update(options) {
         only("Sprites update", options, ["labels", "urlSettings"]);
+        if (options.labels === undefined && options.urlSettings === undefined)
+            throw new TypeError("urlSettings or labels is required");
+        if (options.urlSettings !== undefined)
+            validateURLSettings(options.urlSettings);
+        validateLabels(options.labels);
         const s = await this.native();
         if (options.labels)
             await s.update({
@@ -461,18 +495,20 @@ export class SpriteFilesystem {
         only("Sprites readdir", options, ["withFileTypes", "recursive", "pattern", "encoding"]);
         if (options.encoding && options.encoding !== "utf8")
             throw new CompatibilityError("Sprites", "directory name encodings other than utf8");
-        const s = await this.get();
-        const entries = await s.files.list(this.files.path(path), {
-            hidden: true,
-            glob: options.pattern,
+        if (options.recursive && options.pattern)
+            throw new CompatibilityError("Sprites", "recursive listing with a glob pattern");
+        const entries = await fileOperation(path, "readdir", async () => {
+            const s = await this.get();
+            const entries = await s.files.list(this.files.path(path), {
+                hidden: true,
+                glob: options.pattern,
+            });
+            if (options.recursive)
+                for (let i = 0; i < entries.length; i++)
+                    if (entries[i].type === "directory")
+                        entries.push(...(await s.files.list(entries[i].path, { hidden: true })));
+            return entries;
         });
-        if (options.recursive) {
-            if (options.pattern)
-                throw new CompatibilityError("Sprites", "recursive listing with a glob pattern");
-            for (let i = 0; i < entries.length; i++)
-                if (entries[i].type === "directory")
-                    entries.push(...(await s.files.list(entries[i].path, { hidden: true })));
-        }
         return entries.map((e) => options.withFileTypes
             ? {
                 name: e.name,

package/dist/tar.d.ts

@@ -6,6 +6,8 @@ export declare function packDirectory(root: string): Promise<Uint8Array>;
  * once the whole archive arrived, so an archive cut short leaves nothing
  * behind that could pass for the folder. A target that exists is merged
  * into, files of the same name replaced. */
-export declare function unpackStream(source: AsyncIterable<Uint8Array> | Iterable<Uint8Array>, target: string): Promise<void>;
+export declare function unpackStream(source: AsyncIterable<Uint8Array> | Iterable<Uint8Array>, target: string, options?: {
+    signal?: AbortSignal;
+}): Promise<void>;
 /** Unpacks a whole gzipped tar held in memory, by the same rules. */
 export declare function unpackArchive(archive: Uint8Array, target: string): Promise<void>;

package/dist/tar.js

@@ -1,4 +1,4 @@
-import { chmod, lstat, mkdir, mkdtemp, open, readdir, readFile, realpath, rename, rm, symlink, unlink, } from "node:fs/promises";
+import { chmod, lstat, mkdir, mkdtemp, open, readdir, readFile, readlink, realpath, rename, rm, symlink, unlink, } from "node:fs/promises";
 import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { Readable } from "node:stream";
 import { createGunzip, gzipSync } from "node:zlib";
@@ -126,13 +126,111 @@ function cutShort(cause) {
         ...(cause === undefined ? {} : { cause }),
     });
 }
+function checkSignal(signal) {
+    if (signal?.aborted)
+        throw new RuntimeError({
+            message: "The download was cancelled or ran past its deadline.",
+            code: "timeout",
+            status: 0,
+            cause: signal.reason,
+        });
+}
+/** Linux path names fit well below this generous metadata-only memory bound. */
+const MAX_LONG_NAME_BYTES = 65_536;
+function archiveSize(field) {
+    const text = field.trim();
+    if (text !== "" && !/^[0-7]+$/.test(text))
+        throw new Error("The archive contains an invalid file size.");
+    const size = text === "" ? 0 : parseInt(text, 8);
+    if (!Number.isSafeInteger(size) || size < 0 || size > Number.MAX_SAFE_INTEGER - 511)
+        throw new Error("The archive contains an invalid file size.");
+    return size;
+}
+/** The gzip check protects the compressed bytes; tar's own checksum also
+ * protects the header that determines each file's name, kind and length. */
+function checkHeader(header, field) {
+    const text = field.trim();
+    let unsigned = 0;
+    let signed = 0;
+    for (let index = 0; index < header.length; index++) {
+        const byte = index >= 148 && index < 156 ? 32 : header[index];
+        unsigned += byte;
+        signed += byte < 128 ? byte : byte - 256;
+    }
+    const expected = /^[0-7]+$/.test(text) ? parseInt(text, 8) : NaN;
+    // Older tar implementations used signed bytes for non-ASCII path names.
+    if (expected !== unsigned && expected !== signed)
+        throw new Error("The archive contains an invalid header checksum.");
+}
+/** Validate links against the tree a merge will produce. Staged entries
+ * take precedence; paths absent there retain the existing target's entry.
+ * A link safe in staging may otherwise lead through an old escaping link. */
+async function mergedLinkStaysInside(staging, root, destination, link) {
+    let path = dirname(join(root, relative(staging, destination)));
+    const pending = link.split("/");
+    const followed = new Set();
+    while (pending.length) {
+        const part = pending.shift();
+        if (!part || part === ".")
+            continue;
+        path = part === ".." ? dirname(path) : join(path, part);
+        if (path !== root && !path.startsWith(root + sep))
+            return false;
+        const staged = join(staging, relative(root, path));
+        const stagedKind = await lstat(staged).catch((error) => {
+            if (error.code === "ENOENT" || error.code === "ENOTDIR")
+                return undefined;
+            throw error;
+        });
+        const actual = stagedKind ? staged : path;
+        const kind = stagedKind ??
+            (await lstat(actual).catch((error) => {
+                if (error.code === "ENOENT" || error.code === "ENOTDIR")
+                    return undefined;
+                throw error;
+            }));
+        if (!kind?.isSymbolicLink())
+            continue;
+        if (followed.has(path))
+            return false;
+        followed.add(path);
+        const next = await readlink(actual);
+        if (isAbsolute(next)) {
+            // An existing absolute link is safe only when it stays in this root.
+            if (next !== root && !next.startsWith(root + sep))
+                return false;
+            path = root;
+            pending.unshift(...relative(root, next).split(sep));
+        }
+        else {
+            path = dirname(path);
+            pending.unshift(...next.split("/"));
+        }
+    }
+    return true;
+}
 /** The gzip stream's bytes, decompressed as they arrive. */
-function gunzipped(source) {
+function gunzipped(source, signal) {
     const input = Readable.from(source, { objectMode: false });
     const output = createGunzip();
+    // A filesystem await may precede async iteration; retain early stream
+    // errors for that iterator without an unhandled EventEmitter error.
+    output.on("error", () => undefined);
     input.on("error", (error) => output.destroy(error));
     input.pipe(output);
-    output.on("close", () => input.destroy());
+    const abort = () => {
+        try {
+            checkSignal(signal);
+        }
+        catch (error) {
+            output.destroy(error);
+        }
+    };
+    signal?.addEventListener("abort", abort, { once: true });
+    output.on("close", () => {
+        signal?.removeEventListener("abort", abort);
+        input.destroy();
+    });
     return output;
 }
 /** Exact byte counts from a stream of chunks, holding at most one chunk. */
@@ -189,7 +287,7 @@ class Bytes {
 /** Unpacks a tar stream into `root`, a fresh folder: files and folders as they
  * arrive, links noted to make at the end. Throws unless the archive's end
  * arrived. */
-async function unpackEntries(bytes, root) {
+async function unpackEntries(bytes, root, signal) {
     const links = [];
     const decode = (slice) => {
         const end = slice.indexOf(0);
@@ -198,15 +296,20 @@ async function unpackEntries(bytes, root) {
     let longName;
     let longLink;
     for (;;) {
+        checkSignal(signal);
         const header = await bytes.exactly(512);
         if (!header)
             throw cutShort();
         if (header.every((byte) => byte === 0)) {
+            const terminator = await bytes.exactly(512);
+            if (!terminator || !terminator.every((byte) => byte === 0))
+                throw cutShort();
             await bytes.drain();
             return links;
         }
         const text = (start, length) => decode(header.subarray(start, start + length));
-        const size = parseInt(text(124, 12).trim() || "0", 8);
+        const size = archiveSize(text(124, 12));
+        checkHeader(header, text(148, 8));
         const type = String.fromCharCode(header[156] ?? 48);
         const prefix = text(345, 155);
         let name = longName ?? (prefix ? `${prefix}/${text(0, 100)}` : text(0, 100));
@@ -220,6 +323,8 @@ async function unpackEntries(bytes, root) {
                 ;
         };
         if (type === "L" || type === "K") {
+            if (size > MAX_LONG_NAME_BYTES)
+                throw new Error("The archive contains oversized path metadata.");
             const parts = [];
             for await (const part of bytes.take(size))
                 parts.push(Uint8Array.from(part));
@@ -251,8 +356,16 @@ async function unpackEntries(bytes, root) {
             await mkdir(dirname(destination), { recursive: true });
             const file = await open(destination, "w");
             try {
-                for await (const part of bytes.take(size))
-                    await file.write(part);
+                for await (const part of bytes.take(size)) {
+                    let written = 0;
+                    while (written < part.length) {
+                        checkSignal(signal);
+                        const result = await file.write(part.subarray(written));
+                        if (result.bytesWritten === 0)
+                            throw new Error("The local file accepted no bytes.");
+                        written += result.bytesWritten;
+                    }
+                }
             }
             finally {
                 await file.close();
@@ -267,8 +380,9 @@ async function unpackEntries(bytes, root) {
 }
 /** Moves what was unpacked in `from` into `to`, merging with what is there
  * and replacing files of the same name, never through a link in `to`. */
-async function merge(from, to, root) {
+async function merge(from, to, root, signal) {
     for (const name of await readdir(from)) {
+        checkSignal(signal);
         const source = join(from, name);
         const destination = join(to, name);
         await assertPlain(root, destination, relative(root, destination));
@@ -276,8 +390,9 @@ async function merge(from, to, root) {
             lstat(source),
             lstat(destination).catch(() => undefined),
         ]);
+        checkSignal(signal);
         if (kind.isDirectory() && there?.isDirectory())
-            await merge(source, destination, root);
+            await merge(source, destination, root, signal);
         else
             await rename(source, destination);
     }
@@ -288,30 +403,41 @@ async function merge(from, to, root) {
  * once the whole archive arrived, so an archive cut short leaves nothing
  * behind that could pass for the folder. A target that exists is merged
  * into, files of the same name replaced. */
-export async function unpackStream(source, target) {
+export async function unpackStream(source, target, options = {}) {
+    checkSignal(options.signal);
     const final = resolve(target);
     await mkdir(dirname(final), { recursive: true });
     const staging = await mkdtemp(`${final}.runtime-partial-`);
-    const stream = gunzipped(source);
+    const stream = gunzipped(source, options.signal);
     try {
         const root = await realpath(staging);
-        const links = await unpackEntries(new Bytes(stream), root);
+        const links = await unpackEntries(new Bytes(stream), root, options.signal);
         for (const { destination, link, name } of links) {
+            checkSignal(options.signal);
             await assertPlain(root, destination, name);
             await mkdir(dirname(destination), { recursive: true });
             await symlink(link, destination).catch(() => undefined);
         }
         for (const { destination, link, name } of links) {
+            checkSignal(options.signal);
             if (await linkStaysInside(root, dirname(destination), link))
                 continue;
             await unlink(destination).catch(() => undefined);
             throw new Error(`Refusing an archive link that leads outside the target: ${name} -> ${link}`);
         }
         const there = await lstat(final).catch(() => undefined);
+        checkSignal(options.signal);
         if (!there)
             await rename(staging, final);
-        else
-            await merge(root, await realpath(final), await realpath(final));
+        else {
+            const targetRoot = await realpath(final);
+            for (const { destination, link, name } of links) {
+                checkSignal(options.signal);
+                if (!(await mergedLinkStaysInside(root, targetRoot, destination, link)))
+                    throw new Error(`Refusing an archive link that leads outside the target: ${name} -> ${link}`);
+            }
+            await merge(root, targetRoot, targetRoot, options.signal);
+        }
     }
     finally {
         stream.destroy();

package/dist/transport.d.ts

@@ -1,5 +1,5 @@
 import { RuntimeError } from "./errors.js";
-export declare const VERSION = "0.9.0";
+export declare const VERSION = "0.10.0";
 export declare const DEFAULT_BASE_URL = "https://api.withruntime.com";
 /** Runtime's API as code inside a Runtime sandbox reaches it: the sandbox's
  * own host sends each request on to DEFAULT_BASE_URL over HTTPS. The API runs
@@ -87,12 +87,9 @@ export declare class Transport {
     send(call: Call): Promise<Response>;
     json<T>(call: Call): Promise<T>;
     bytes(call: Call): Promise<Uint8Array>;
-    /** A file's bytes, read whole and checked: the API says a body's length
-     * (x-content-length) and, when small, its SHA-256 (x-content-sha256) before
-     * sending it, and a body that falls short or differs is read again, twice,
-     * then refused. Nothing between the API and here reliably turns a stream
-     * cut part way into an error: on 25 September 2026 a 50 MB file came back
-     * 29 MB long, exit 0. */
+    /** A file's bytes, read whole and checked against its promised length and
+     * SHA-256. A short or different body is read again twice, within the same
+     * call deadline. */
     fileBytes(call: Call): Promise<Uint8Array>;
     /** A file's bytes as they arrive, for files too big to hold. The stream
      * errors with `download_incomplete` if it ends short of the length the API