withruntime 0.8.4 → 0.10.0

package/dist/vercel/command.js

@@ -47,18 +47,25 @@ export class Command {
     logs(opts = {}) {
         const abort = new AbortController();
         const forward = () => abort.abort();
-        opts.signal?.addEventListener("abort", forward, { once: true });
+        if (opts.signal?.aborted)
+            abort.abort();
+        else
+            opts.signal?.addEventListener("abort", forward, { once: true });
         const lines = this.init.lines;
         const process = this.init.process;
         const sandboxName = this.init.sandboxName;
         async function* read() {
             try {
+                if (abort.signal.aborted)
+                    return;
                 if (lines) {
                     yield* lines;
                     return;
                 }
                 try {
                     for await (const event of process.output({ signal: abort.signal })) {
+                        if (event.type === "truncated")
+                            throw new StreamError("output_truncated", "Some command output is no longer available.", process.id);
                         if (event.type === "stdout" || event.type === "stderr")
                             yield { stream: event.type, data: event.data };
                         if (event.type === "exit")
@@ -68,6 +75,8 @@ export class Command {
                 catch (error) {
                     if (abort.signal.aborted)
                         return;
+                    if (error instanceof StreamError)
+                        throw error;
                     const translated = translate(error, sandboxName);
                     throw translated instanceof Error && translated !== error
                         ? translated
@@ -94,6 +103,8 @@ export class Command {
         let exit;
         await guard(async () => {
             for await (const event of this.init.process.output(params.signal ? { signal: params.signal } : {})) {
+                if (event.type === "truncated")
+                    throw new StreamError("output_truncated", "Some command output is no longer available.", this.init.process.id);
                 if (event.type === "stdout" || event.type === "stderr")
                     lines.push({ stream: event.type, data: event.data });
                 else if (event.type === "exit")
@@ -125,13 +136,14 @@ export class Command {
         return this.output("stderr", opts);
     }
     /** Sends a signal, SIGTERM by default. */
-    async kill(signal = "SIGTERM", _opts = {}) {
+    async kill(signal = "SIGTERM", opts = {}) {
+        opts.abortSignal?.throwIfAborted();
         if (!this.init.process)
             return;
         const name = typeof signal === "number" ? SIGNAL_NUMBERS[signal] : signal;
         if (!name)
             throw new RangeError(`Signal ${signal} has no name Runtime knows; use SIGTERM, SIGKILL, SIGINT, SIGHUP, SIGQUIT, SIGUSR1 or SIGUSR2.`);
-        await guard(() => this.init.process.kill(name), this.init.sandboxName);
+        await guard(() => this.init.process.kill(name, opts.abortSignal ? { signal: opts.abortSignal } : {}), this.init.sandboxName);
     }
 }
 /** A command that has ended; `exitCode` is set. */

package/dist/vercel/errors.d.ts

@@ -44,8 +44,8 @@ export declare function translate(error: unknown, sandboxName?: string): unknown
 /** Runs `work`, turning any Runtime error into Vercel's. */
 export declare function guard<T>(work: () => Promise<T>, sandboxName?: string): Promise<T>;
 /** A node:fs-style error, as Vercel's `sandbox.fs` throws. */
-export declare function fsError(code: "ENOENT" | "EEXIST" | "EISDIR" | "ENOTDIR", syscall: string, path: string): Error & {
-    code: "ENOENT" | "EEXIST" | "EISDIR" | "ENOTDIR";
+export declare function fsError(code: "ENOENT" | "EEXIST" | "EISDIR" | "ENOTDIR" | "EACCES" | "ENOTEMPTY" | "EINVAL", syscall: string, path: string): Error & {
+    code: "ENOENT" | "ENOTDIR" | "EEXIST" | "EISDIR" | "EACCES" | "ENOTEMPTY" | "EINVAL";
     errno: number;
     syscall: string;
     path: string;

package/dist/vercel/errors.js

@@ -73,7 +73,13 @@ export function translate(error, sandboxName) {
         return new NotSupportedError(error.code.replace(/_unavailable$/, ""), error.hint ?? "", message);
     if (error.status < 200 || error.status > 599)
         return error;
-    const json = { error: { code: error.code, message: error.message } };
+    const json = {
+        error: {
+            code: error.code,
+            message: error.message,
+            ...(error.details ? { details: error.details } : {}),
+        },
+    };
     const out = new APIError(new Response(JSON.stringify(json), {
         status: error.status,
         headers: { "content-type": "application/json" },
@@ -102,8 +108,19 @@ export function fsError(code, syscall, path) {
         EEXIST: "file already exists",
         EISDIR: "illegal operation on a directory",
         ENOTDIR: "not a directory",
+        EACCES: "permission denied",
+        ENOTEMPTY: "directory not empty",
+        EINVAL: "invalid argument",
+    }[code];
+    const errno = {
+        ENOENT: -2,
+        EEXIST: -17,
+        EISDIR: -21,
+        ENOTDIR: -20,
+        EACCES: -13,
+        ENOTEMPTY: -39,
+        EINVAL: -22,
     }[code];
-    const errno = { ENOENT: -2, EEXIST: -17, EISDIR: -21, ENOTDIR: -20 }[code];
     return Object.assign(new Error(`${code}: ${text}, ${syscall} '${path}'`), {
         code,
         errno,

package/dist/vercel/filesystem.d.ts

@@ -5,7 +5,10 @@ export interface FsContext {
     readonly name: string;
     files(): Promise<Files>;
     /** Runs argv without a shell; resolves with the exit code and output. */
-    run(argv: string[]): Promise<{
+    run(argv: string[], options?: {
+        stdin?: Uint8Array;
+        signal?: AbortSignal;
+    }): Promise<{
         exitCode: number | null;
         stdout: string;
         stderr: string;
@@ -28,8 +31,8 @@ export declare class Stats {
     readonly ctimeMs: number;
     readonly birthtime: Date;
     readonly birthtimeMs: number;
-    readonly uid = 0;
-    readonly gid = 0;
+    readonly uid: number;
+    readonly gid: number;
     readonly dev = 0;
     readonly ino = 0;
     readonly nlink = 1;
@@ -86,7 +89,7 @@ export declare class FileSystem {
     mkdir(path: string, options?: {
         recursive?: boolean;
         signal?: AbortSignal;
-    } | number): Promise<string | undefined>;
+    } | number): Promise<void>;
     readdir(path: string, options?: {
         signal?: AbortSignal;
         withFileTypes?: false;
@@ -95,14 +98,14 @@ export declare class FileSystem {
         signal?: AbortSignal;
         withFileTypes: true;
     }): Promise<Dirent[]>;
-    lstat(path: string, _options?: {
+    lstat(path: string, options?: {
         signal?: AbortSignal;
     }): Promise<Stats>;
     /** Follows symbolic links. */
     stat(path: string, options?: {
         signal?: AbortSignal;
     }): Promise<Stats>;
-    unlink(path: string, _options?: {
+    unlink(path: string, options?: {
         signal?: AbortSignal;
     }): Promise<void>;
     rm(path: string, options?: {
@@ -110,40 +113,40 @@ export declare class FileSystem {
         force?: boolean;
         signal?: AbortSignal;
     }): Promise<void>;
-    rmdir(path: string, _options?: {
+    rmdir(path: string, options?: {
         signal?: AbortSignal;
     }): Promise<void>;
-    rename(oldPath: string, newPath: string, _options?: {
+    rename(oldPath: string, newPath: string, options?: {
         signal?: AbortSignal;
     }): Promise<void>;
-    copyFile(src: string, dest: string, _options?: {
+    copyFile(src: string, dest: string, options?: {
         signal?: AbortSignal;
     }): Promise<void>;
-    access(path: string, _options?: {
+    access(path: string, options?: {
         signal?: AbortSignal;
     }): Promise<void>;
-    exists(path: string, _options?: {
+    exists(path: string, options?: {
         signal?: AbortSignal;
     }): Promise<boolean>;
-    chmod(path: string, mode: number | string, _options?: {
+    chmod(path: string, mode: number | string, options?: {
         signal?: AbortSignal;
     }): Promise<void>;
-    chown(path: string, uid: number, gid: number, _options?: {
+    chown(path: string, uid: number, gid: number, options?: {
         signal?: AbortSignal;
     }): Promise<void>;
-    symlink(target: string, path: string, _options?: {
+    symlink(target: string, path: string, options?: {
         signal?: AbortSignal;
     }): Promise<void>;
-    readlink(path: string, _options?: {
+    readlink(path: string, options?: {
         signal?: AbortSignal;
     }): Promise<string>;
-    realpath(path: string, _options?: {
+    realpath(path: string, options?: {
         signal?: AbortSignal;
     }): Promise<string>;
-    truncate(path: string, len?: number, _options?: {
+    truncate(path: string, len?: number, options?: {
         signal?: AbortSignal;
     }): Promise<void>;
-    mkdtemp(prefix: string, _options?: {
+    mkdtemp(prefix: string, options?: {
         signal?: AbortSignal;
     }): Promise<string>;
 }

package/dist/vercel/filesystem.js

@@ -13,8 +13,8 @@ export class Stats {
     ctimeMs;
     birthtime;
     birthtimeMs;
-    uid = 0;
-    gid = 0;
+    uid;
+    gid;
     dev = 0;
     ino = 0;
     nlink = 1;
@@ -24,6 +24,8 @@ export class Stats {
     #type;
     constructor(entry) {
         this.#type = entry.type;
+        this.uid = entry.uid ?? 0;
+        this.gid = entry.gid ?? 0;
         this.size = entry.size;
         const typeBits = entry.type === "directory" ? 0o040000 : entry.type === "symlink" ? 0o120000 : 0o100000;
         this.mode = typeBits | ((parseInt(entry.mode, 8) || 0) & 0o7777);
@@ -61,7 +63,8 @@ export class Dirent {
     #type;
     constructor(entry, parent) {
         this.name = entry.name;
-        this.parentPath = this.path = parent;
+        this.parentPath = parent;
+        this.path = entry.path;
         this.#type = entry.type;
     }
     isFile() {
@@ -111,18 +114,27 @@ export class FileSystem {
         }
     }
     /** Runs a coreutils command; a failure is a Node-style error. */
-    async #run(syscall, path, argv) {
-        const result = await this.#call(syscall, path, () => this.#ctx.run(argv));
+    async #run(syscall, path, argv, options) {
+        options?.signal?.throwIfAborted();
+        const result = await this.#call(syscall, path, () => this.#ctx.run(argv, options));
         if (result.exitCode === 0)
             return result.stdout;
         if (/No such file or directory/.test(result.stderr))
             throw fsError("ENOENT", syscall, path);
+        if (syscall === "unlink" || syscall === "rm")
+            throw fsError("EACCES", syscall, path);
+        if (syscall === "rmdir" && /not empty/i.test(result.stderr))
+            throw fsError("ENOTEMPTY", syscall, path);
+        if (syscall === "readlink")
+            throw fsError("EINVAL", syscall, path);
         if (/File exists/.test(result.stderr))
             throw fsError("EEXIST", syscall, path);
         if (/Is a directory/.test(result.stderr))
             throw fsError("EISDIR", syscall, path);
         if (/Not a directory/.test(result.stderr))
             throw fsError("ENOTDIR", syscall, path);
+        if (/Permission denied/.test(result.stderr))
+            throw fsError("EACCES", syscall, path);
         throw Object.assign(new Error(`${syscall} '${path}' failed: ${result.stderr.trim()}`), {
             code: "EIO",
             syscall,
@@ -131,6 +143,8 @@ export class FileSystem {
     }
     async readFile(path, options) {
         const target = this.#ctx.resolve(path);
+        if (options && typeof options === "object")
+            options.signal?.throwIfAborted();
         const files = await this.#ctx.files();
         const bytes = await this.#call("open", target, () => files.read(target, typeof options === "object" && options?.signal ? { signal: options.signal } : {}));
         const encoding = encodingOf(options);
@@ -139,37 +153,64 @@ export class FileSystem {
     }
     async writeFile(path, data, options) {
         const target = this.#ctx.resolve(path);
+        if (options && typeof options === "object")
+            options.signal?.throwIfAborted();
         const files = await this.#ctx.files();
-        await this.#call("open", target, () => files.write(target, bytesOf(data, encodingOf(options))));
+        await this.#call("open", target, () => files.write(target, bytesOf(data, encodingOf(options)), typeof options === "object" && options.signal ? { signal: options.signal } : {}));
     }
     async appendFile(path, data, options) {
         const target = this.#ctx.resolve(path);
+        // Never read-modify-write: another caller may be appending too. The
+        // shell opens with O_APPEND and cat streams bytes without Python. Exec
+        // stdin is limited to 1 MiB; larger input uses the chunked files API.
+        const bytes = bytesOf(data, encodingOf(options));
+        const signal = typeof options === "object" ? options.signal : undefined;
+        signal?.throwIfAborted();
+        if (bytes.byteLength <= 1_048_576) {
+            await this.#run("open", target, ["sh", "-c", 'cat >> "$1"', "runtime-append", target], {
+                stdin: bytes,
+                ...(signal ? { signal } : {}),
+            });
+            return;
+        }
+        if (options && typeof options === "object")
+            options.signal?.throwIfAborted();
         const files = await this.#ctx.files();
-        const before = await files.read(target).catch((error) => {
-            if (missing(error))
-                return new Uint8Array();
-            throw translate(error, this.#ctx.name);
-        });
-        await this.#call("open", target, () => files.write(target, Buffer.concat([before, bytesOf(data, encodingOf(options))])));
+        const staging = `/workspace/.runtime/append/${crypto.randomUUID()}`;
+        try {
+            await this.#call("open", target, () => files.write(staging, bytes, { mode: 0o600, ...(signal ? { signal } : {}) }));
+            await this.#run("open", target, ["sh", "-c", 'cat "$1" >> "$2"', "runtime-append", staging, target], signal ? { signal } : undefined);
+        }
+        finally {
+            // A cleanup failure must not invite retrying a successful append.
+            await files.remove(staging).catch(() => undefined);
+        }
     }
     async mkdir(path, options) {
         const target = this.#ctx.resolve(path);
         const recursive = typeof options === "object" && options.recursive === true;
-        await this.#run("mkdir", target, recursive ? ["mkdir", "-p", target] : ["mkdir", target]);
-        return recursive ? target : undefined;
+        await this.#run("mkdir", target, recursive ? ["mkdir", "-p", "--", target] : ["mkdir", "--", target], typeof options === "object" ? options : {});
     }
     async readdir(path, options = {}) {
         const target = this.#ctx.resolve(path);
+        if (options && typeof options === "object")
+            options.signal?.throwIfAborted();
         const files = await this.#ctx.files();
-        const entries = await this.#call("scandir", target, () => files.list(target, { depth: 1, hidden: true }));
+        const entries = await this.#call("scandir", target, () => files.list(target, {
+            depth: 1,
+            hidden: options.withFileTypes === true,
+            ...(options.signal ? { signal: options.signal } : {}),
+        }));
         return options.withFileTypes
             ? entries.map((entry) => new Dirent(entry, target))
-            : entries.map((entry) => entry.name);
+            : entries.filter((entry) => !entry.name.startsWith(".")).map((entry) => entry.name);
     }
-    async lstat(path, _options = {}) {
+    async lstat(path, options = {}) {
         const target = this.#ctx.resolve(path);
+        if (options && typeof options === "object")
+            options.signal?.throwIfAborted();
         const files = await this.#ctx.files();
-        const found = await this.#call("lstat", target, () => files.stat(target));
+        const found = await this.#call("lstat", target, () => files.stat(target, options));
         if (!found.exists)
             throw fsError("ENOENT", "lstat", target);
         return new Stats(found);
@@ -180,69 +221,75 @@ export class FileSystem {
         const first = await this.lstat(target, options);
         if (!first.isSymbolicLink())
             return first;
-        return this.lstat(await this.realpath(target), options);
+        return this.lstat(await this.realpath(target, options), options);
     }
-    async unlink(path, _options = {}) {
+    async unlink(path, options = {}) {
         const target = this.#ctx.resolve(path);
-        await this.#run("unlink", target, ["rm", "--", target]);
+        await this.#run("unlink", target, ["rm", "--", target], options);
     }
     async rm(path, options = {}) {
         const target = this.#ctx.resolve(path);
         const flags = `${options.recursive ? "r" : ""}${options.force ? "f" : ""}`;
-        await this.#run("rm", target, flags ? ["rm", `-${flags}`, "--", target] : ["rm", "--", target]);
+        await this.#run("rm", target, flags ? ["rm", `-${flags}`, "--", target] : ["rm", "--", target], options);
     }
-    async rmdir(path, _options = {}) {
+    async rmdir(path, options = {}) {
         const target = this.#ctx.resolve(path);
-        await this.#run("rmdir", target, ["rmdir", "--", target]);
+        await this.#run("rmdir", target, ["rmdir", "--", target], options);
     }
-    async rename(oldPath, newPath, _options = {}) {
+    async rename(oldPath, newPath, options = {}) {
         const from = this.#ctx.resolve(oldPath);
         const to = this.#ctx.resolve(newPath);
+        if (options && typeof options === "object")
+            options.signal?.throwIfAborted();
         const files = await this.#ctx.files();
-        await this.#call("rename", from, () => files.rename(from, to, { overwrite: true }));
+        await this.#call("rename", from, () => files.rename(from, to, { overwrite: true, ...options }));
     }
-    async copyFile(src, dest, _options = {}) {
+    async copyFile(src, dest, options = {}) {
         const from = this.#ctx.resolve(src);
         const to = this.#ctx.resolve(dest);
-        await this.#run("copyfile", from, ["cp", "--", from, to]);
+        await this.#run("copyfile", from, ["cp", "--", from, to], options);
     }
-    async access(path, _options = {}) {
+    async access(path, options = {}) {
         const target = this.#ctx.resolve(path);
-        if (!(await this.exists(target)))
+        if (!(await this.exists(target, options)))
             throw fsError("ENOENT", "access", target);
     }
-    async exists(path, _options = {}) {
+    async exists(path, options = {}) {
         const target = this.#ctx.resolve(path);
-        const files = await this.#ctx.files();
-        return this.#call("access", target, () => files.exists(target));
-    }
-    async chmod(path, mode, _options = {}) {
+        if (options && typeof options === "object")
+            options.signal?.throwIfAborted();
+        // The native stat is lstat: a dangling link exists there. Vercel's public
+        // exists/access follow the target, matching test -e in its published SDK.
+        const result = await this.#call("access", target, () => this.#ctx.run(["test", "-e", target], options));
+        return result.exitCode === 0;
+    }
+    async chmod(path, mode, options = {}) {
         const target = this.#ctx.resolve(path);
         const octal = typeof mode === "number" ? mode.toString(8) : mode;
-        await this.#run("chmod", target, ["chmod", octal, "--", target]);
+        await this.#run("chmod", target, ["chmod", octal, "--", target], options);
     }
-    async chown(path, uid, gid, _options = {}) {
+    async chown(path, uid, gid, options = {}) {
         const target = this.#ctx.resolve(path);
-        await this.#run("chown", target, ["sudo", "chown", `${uid}:${gid}`, "--", target]);
+        await this.#run("chown", target, ["sudo", "chown", `${uid}:${gid}`, "--", target], options);
     }
-    async symlink(target, path, _options = {}) {
+    async symlink(target, path, options = {}) {
         const link = this.#ctx.resolve(path);
-        await this.#run("symlink", link, ["ln", "-s", "--", target, link]);
+        await this.#run("symlink", link, ["ln", "-s", "--", target, link], options);
     }
-    async readlink(path, _options = {}) {
+    async readlink(path, options = {}) {
         const target = this.#ctx.resolve(path);
-        return (await this.#run("readlink", target, ["readlink", "--", target])).replace(/\n$/, "");
+        return (await this.#run("readlink", target, ["readlink", "--", target], options)).replace(/\n$/, "");
     }
-    async realpath(path, _options = {}) {
+    async realpath(path, options = {}) {
         const target = this.#ctx.resolve(path);
-        return (await this.#run("realpath", target, ["realpath", "-e", "--", target])).replace(/\n$/, "");
+        return (await this.#run("realpath", target, ["realpath", "-e", "--", target], options)).replace(/\n$/, "");
     }
-    async truncate(path, len = 0, _options = {}) {
+    async truncate(path, len = 0, options = {}) {
         const target = this.#ctx.resolve(path);
-        await this.#run("open", target, ["truncate", "-s", String(len), "--", target]);
+        await this.#run("open", target, ["truncate", "-s", String(len), "--", target], options);
     }
-    async mkdtemp(prefix, _options = {}) {
+    async mkdtemp(prefix, options = {}) {
         const base = this.#ctx.resolve(prefix);
-        return (await this.#run("mkdtemp", base, ["mktemp", "-d", `${base}XXXXXX`])).replace(/\n$/, "");
+        return (await this.#run("mkdtemp", base, ["mktemp", "-d", `${base}XXXXXX`], options)).replace(/\n$/, "");
     }
 }

package/dist/vercel/sandbox.d.ts

@@ -60,7 +60,7 @@ export interface CreateSandboxParams extends Credentials {
     /** Milliseconds a stopped persistent sandbox is kept, as Runtime's
      * retention (whole days, 1 to 365; 0 is 365). */
     snapshotExpiration?: number;
-    /** Accepted: a paused Runtime sandbox keeps exactly its latest state. */
+    /** Refused: Runtime does not enforce snapshot count or eviction policies. */
     keepLastSnapshots?: {
         count: number;
         expiration?: number;
@@ -198,10 +198,10 @@ export declare class Sandbox {
     }): Promise<Command>;
     runCommand(params: RunCommandParams): Promise<CommandFinished>;
     /** A command started earlier, by its cmdId. */
-    getCommand(cmdId: string, _opts?: {
+    getCommand(cmdId: string, opts?: {
         signal?: AbortSignal;
     }): Promise<Command>;
-    mkDir(path: string, _opts?: {
+    mkDir(path: string, opts?: {
         signal?: AbortSignal;
     }): Promise<void>;
     /** The file's bytes as a Node stream, or null when there is no file. */
@@ -235,7 +235,7 @@ export declare class Sandbox {
         path: string;
         content: string | Uint8Array;
         mode?: number;
-    }[], _opts?: {
+    }[], opts?: {
         signal?: AbortSignal;
     }): Promise<void>;
     /** The public address of a port listed in `ports`, such as
@@ -262,7 +262,7 @@ export declare class Sandbox {
         signal?: AbortSignal;
     }): Promise<void>;
     /** Replaces the network rules; returns the policy given. */
-    updateNetworkPolicy(networkPolicy: NetworkPolicy, _opts?: {
+    updateNetworkPolicy(networkPolicy: NetworkPolicy, opts?: {
         signal?: AbortSignal;
     }): Promise<NetworkPolicy>;
     /** Changes what Runtime can change on a sandbox: `timeout`, `ports`,
@@ -273,11 +273,11 @@ export declare class Sandbox {
         ports?: number[];
         networkPolicy?: NetworkPolicy;
         snapshotExpiration?: number;
-    } & Record<string, unknown>, _opts?: {
+    } & Record<string, unknown>, opts?: {
         signal?: AbortSignal;
     }): Promise<void>;
-    /** Keeps the sandbox's whole machine as a Runtime snapshot (files, memory
-     * and running processes), then stops the sandbox, as Vercel does. Start
+    /** Keeps the sandbox's filesystem as a disk-only snapshot, then stops
+     * the source. Restoring it starts fresh processes, as Vercel does. Start
      * from it with `Sandbox.create({ source: { type: "snapshot", snapshotId } })`. */
     snapshot(opts?: {
         expiration?: number;