withruntime 0.4.0 → 0.5.1

package/dist/vercel/filesystem.d.ts

@@ -0,0 +1,150 @@
+import type { Files } from "../sandbox.js";
+import type { FileEntry } from "../types.js";
+/** What `sandbox.fs` needs from its sandbox. */
+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<{
+        exitCode: number | null;
+        stdout: string;
+        stderr: string;
+    }>;
+    resolve(path: string, cwd?: string): string;
+}
+type WriteFileData = string | Uint8Array;
+type Encoding = "utf8" | "utf-8" | "ascii" | "latin1" | "base64" | "hex" | "binary";
+/** Node's Stats, as far as a sandbox file can answer. uid, gid, ino and the
+ * other inode fields are 0. */
+export declare class Stats {
+    #private;
+    readonly size: number;
+    readonly mode: number;
+    readonly mtime: Date;
+    readonly mtimeMs: number;
+    readonly atime: Date;
+    readonly atimeMs: number;
+    readonly ctime: Date;
+    readonly ctimeMs: number;
+    readonly birthtime: Date;
+    readonly birthtimeMs: number;
+    readonly uid = 0;
+    readonly gid = 0;
+    readonly dev = 0;
+    readonly ino = 0;
+    readonly nlink = 1;
+    readonly rdev = 0;
+    readonly blksize = 4096;
+    readonly blocks: number;
+    constructor(entry: FileEntry);
+    isFile(): boolean;
+    isDirectory(): boolean;
+    isSymbolicLink(): boolean;
+    isBlockDevice(): boolean;
+    isCharacterDevice(): boolean;
+    isFIFO(): boolean;
+    isSocket(): boolean;
+}
+/** Node's Dirent, from a sandbox listing. */
+export declare class Dirent {
+    #private;
+    readonly name: string;
+    readonly parentPath: string;
+    readonly path: string;
+    constructor(entry: FileEntry, parent: string);
+    isFile(): boolean;
+    isDirectory(): boolean;
+    isSymbolicLink(): boolean;
+    isBlockDevice(): boolean;
+    isCharacterDevice(): boolean;
+    isFIFO(): boolean;
+    isSocket(): boolean;
+}
+/** `sandbox.fs`: node:fs/promises over Runtime's files API and a few
+ * commands. Relative paths resolve against the sandbox's working directory,
+ * `/vercel/sandbox`, which is `/workspace` on Runtime. Errors carry Node's
+ * codes: `ENOENT` for a missing path. */
+export declare class FileSystem {
+    #private;
+    constructor(ctx: FsContext);
+    readFile(path: string, options?: {
+        encoding?: null;
+        signal?: AbortSignal;
+    } | null): Promise<Buffer>;
+    readFile(path: string, options: {
+        encoding: Encoding;
+        signal?: AbortSignal;
+    } | Encoding): Promise<string>;
+    writeFile(path: string, data: WriteFileData, options?: {
+        encoding?: Encoding;
+        signal?: AbortSignal;
+    } | Encoding): Promise<void>;
+    appendFile(path: string, data: WriteFileData, options?: {
+        encoding?: Encoding;
+        signal?: AbortSignal;
+    } | Encoding): Promise<void>;
+    mkdir(path: string, options?: {
+        recursive?: boolean;
+        signal?: AbortSignal;
+    } | number): Promise<string | undefined>;
+    readdir(path: string, options?: {
+        signal?: AbortSignal;
+        withFileTypes?: false;
+    }): Promise<string[]>;
+    readdir(path: string, options: {
+        signal?: AbortSignal;
+        withFileTypes: true;
+    }): Promise<Dirent[]>;
+    lstat(path: string, _options?: {
+        signal?: AbortSignal;
+    }): Promise<Stats>;
+    /** Follows symbolic links. */
+    stat(path: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<Stats>;
+    unlink(path: string, _options?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
+    rm(path: string, options?: {
+        recursive?: boolean;
+        force?: boolean;
+        signal?: AbortSignal;
+    }): Promise<void>;
+    rmdir(path: string, _options?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
+    rename(oldPath: string, newPath: string, _options?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
+    copyFile(src: string, dest: string, _options?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
+    access(path: string, _options?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
+    exists(path: string, _options?: {
+        signal?: AbortSignal;
+    }): Promise<boolean>;
+    chmod(path: string, mode: number | string, _options?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
+    chown(path: string, uid: number, gid: number, _options?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
+    symlink(target: string, path: string, _options?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
+    readlink(path: string, _options?: {
+        signal?: AbortSignal;
+    }): Promise<string>;
+    realpath(path: string, _options?: {
+        signal?: AbortSignal;
+    }): Promise<string>;
+    truncate(path: string, len?: number, _options?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
+    mkdtemp(prefix: string, _options?: {
+        signal?: AbortSignal;
+    }): Promise<string>;
+}
+export {};

package/dist/vercel/filesystem.js

@@ -0,0 +1,248 @@
+import { RuntimeError } from "../errors.js";
+import { fsError, translate } from "./errors.js";
+/** Node's Stats, as far as a sandbox file can answer. uid, gid, ino and the
+ * other inode fields are 0. */
+export class Stats {
+    size;
+    mode;
+    mtime;
+    mtimeMs;
+    atime;
+    atimeMs;
+    ctime;
+    ctimeMs;
+    birthtime;
+    birthtimeMs;
+    uid = 0;
+    gid = 0;
+    dev = 0;
+    ino = 0;
+    nlink = 1;
+    rdev = 0;
+    blksize = 4096;
+    blocks;
+    #type;
+    constructor(entry) {
+        this.#type = entry.type;
+        this.size = entry.size;
+        const typeBits = entry.type === "directory" ? 0o040000 : entry.type === "symlink" ? 0o120000 : 0o100000;
+        this.mode = typeBits | ((parseInt(entry.mode, 8) || 0) & 0o7777);
+        this.mtime = this.atime = this.ctime = this.birthtime = new Date(entry.modifiedAt);
+        this.mtimeMs = this.atimeMs = this.ctimeMs = this.birthtimeMs = this.mtime.getTime();
+        this.blocks = Math.ceil(entry.size / 512);
+    }
+    isFile() {
+        return this.#type === "file";
+    }
+    isDirectory() {
+        return this.#type === "directory";
+    }
+    isSymbolicLink() {
+        return this.#type === "symlink";
+    }
+    isBlockDevice() {
+        return false;
+    }
+    isCharacterDevice() {
+        return false;
+    }
+    isFIFO() {
+        return false;
+    }
+    isSocket() {
+        return false;
+    }
+}
+/** Node's Dirent, from a sandbox listing. */
+export class Dirent {
+    name;
+    parentPath;
+    path;
+    #type;
+    constructor(entry, parent) {
+        this.name = entry.name;
+        this.parentPath = this.path = parent;
+        this.#type = entry.type;
+    }
+    isFile() {
+        return this.#type === "file";
+    }
+    isDirectory() {
+        return this.#type === "directory";
+    }
+    isSymbolicLink() {
+        return this.#type === "symlink";
+    }
+    isBlockDevice() {
+        return false;
+    }
+    isCharacterDevice() {
+        return false;
+    }
+    isFIFO() {
+        return false;
+    }
+    isSocket() {
+        return false;
+    }
+}
+const encodingOf = (options) => typeof options === "string" ? options : (options?.encoding ?? null);
+const bytesOf = (data, encoding) => typeof data === "string" ? Buffer.from(data, encoding ?? "utf8") : Buffer.from(data);
+function missing(error) {
+    return error instanceof RuntimeError && (error.code === "file_not_found" || error.status === 404);
+}
+/** `sandbox.fs`: node:fs/promises over Runtime's files API and a few
+ * commands. Relative paths resolve against the sandbox's working directory,
+ * `/vercel/sandbox`, which is `/workspace` on Runtime. Errors carry Node's
+ * codes: `ENOENT` for a missing path. */
+export class FileSystem {
+    #ctx;
+    constructor(ctx) {
+        this.#ctx = ctx;
+    }
+    async #call(syscall, path, work) {
+        try {
+            return await work();
+        }
+        catch (error) {
+            if (missing(error))
+                throw fsError("ENOENT", syscall, path);
+            throw translate(error, this.#ctx.name);
+        }
+    }
+    /** 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));
+        if (result.exitCode === 0)
+            return result.stdout;
+        if (/No such file or directory/.test(result.stderr))
+            throw fsError("ENOENT", 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);
+        throw Object.assign(new Error(`${syscall} '${path}' failed: ${result.stderr.trim()}`), {
+            code: "EIO",
+            syscall,
+            path,
+        });
+    }
+    async readFile(path, options) {
+        const target = this.#ctx.resolve(path);
+        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);
+        const buffer = Buffer.from(bytes);
+        return encoding ? buffer.toString(encoding) : buffer;
+    }
+    async writeFile(path, data, options) {
+        const target = this.#ctx.resolve(path);
+        const files = await this.#ctx.files();
+        await this.#call("open", target, () => files.write(target, bytesOf(data, encodingOf(options))));
+    }
+    async appendFile(path, data, options) {
+        const target = this.#ctx.resolve(path);
+        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))])));
+    }
+    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;
+    }
+    async readdir(path, options = {}) {
+        const target = this.#ctx.resolve(path);
+        const files = await this.#ctx.files();
+        const entries = await this.#call("scandir", target, () => files.list(target, { depth: 1, hidden: true }));
+        return options.withFileTypes
+            ? entries.map((entry) => new Dirent(entry, target))
+            : entries.map((entry) => entry.name);
+    }
+    async lstat(path, _options = {}) {
+        const target = this.#ctx.resolve(path);
+        const files = await this.#ctx.files();
+        const found = await this.#call("lstat", target, () => files.stat(target));
+        if (!found.exists)
+            throw fsError("ENOENT", "lstat", target);
+        return new Stats(found);
+    }
+    /** Follows symbolic links. */
+    async stat(path, options = {}) {
+        const target = this.#ctx.resolve(path);
+        const first = await this.lstat(target, options);
+        if (!first.isSymbolicLink())
+            return first;
+        return this.lstat(await this.realpath(target), options);
+    }
+    async unlink(path, _options = {}) {
+        const target = this.#ctx.resolve(path);
+        await this.#run("unlink", target, ["rm", "--", target]);
+    }
+    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]);
+    }
+    async rmdir(path, _options = {}) {
+        const target = this.#ctx.resolve(path);
+        await this.#run("rmdir", target, ["rmdir", "--", target]);
+    }
+    async rename(oldPath, newPath, _options = {}) {
+        const from = this.#ctx.resolve(oldPath);
+        const to = this.#ctx.resolve(newPath);
+        const files = await this.#ctx.files();
+        await this.#call("rename", from, () => files.rename(from, to, { overwrite: true }));
+    }
+    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]);
+    }
+    async access(path, _options = {}) {
+        const target = this.#ctx.resolve(path);
+        if (!(await this.exists(target)))
+            throw fsError("ENOENT", "access", target);
+    }
+    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 = {}) {
+        const target = this.#ctx.resolve(path);
+        const octal = typeof mode === "number" ? mode.toString(8) : mode;
+        await this.#run("chmod", target, ["chmod", octal, "--", target]);
+    }
+    async chown(path, uid, gid, _options = {}) {
+        const target = this.#ctx.resolve(path);
+        await this.#run("chown", target, ["sudo", "chown", `${uid}:${gid}`, "--", target]);
+    }
+    async symlink(target, path, _options = {}) {
+        const link = this.#ctx.resolve(path);
+        await this.#run("symlink", link, ["ln", "-s", "--", target, link]);
+    }
+    async readlink(path, _options = {}) {
+        const target = this.#ctx.resolve(path);
+        return (await this.#run("readlink", target, ["readlink", "--", target])).replace(/\n$/, "");
+    }
+    async realpath(path, _options = {}) {
+        const target = this.#ctx.resolve(path);
+        return (await this.#run("realpath", target, ["realpath", "-e", "--", target])).replace(/\n$/, "");
+    }
+    async truncate(path, len = 0, _options = {}) {
+        const target = this.#ctx.resolve(path);
+        await this.#run("open", target, ["truncate", "-s", String(len), "--", target]);
+    }
+    async mkdtemp(prefix, _options = {}) {
+        const base = this.#ctx.resolve(prefix);
+        return (await this.#run("mkdtemp", base, ["mktemp", "-d", `${base}XXXXXX`])).replace(/\n$/, "");
+    }
+}

package/dist/vercel/index.d.ts

@@ -0,0 +1,30 @@
+export { Sandbox, DEFAULT_TIMEOUT_MS, DEFAULT_VCPUS, MEMORY_MIB_PER_VCPU, networkRules, toRuntimePath, type CreateSandboxParams, type RunCommandParams, type NetworkPolicy, type SandboxRoute, } from "./sandbox.js";
+export { Command, CommandFinished, type CommandOutput, type LogOutputLine, type Signal, } from "./command.js";
+export { FileSystem, Stats, Dirent } from "./filesystem.js";
+export { Snapshot } from "./snapshot.js";
+export { APIError, StreamError, AuthenticationError, NotSupportedError } from "./errors.js";
+export type { Credentials, WithRuntime } from "./client.js";
+/** Vercel's default region; Runtime runs in one US region. */
+export declare const DEFAULT_SANDBOX_REGION = "iad1";
+export declare const Drive: {
+    (...args: unknown[]): never;
+    new (...args: unknown[]): never;
+    readonly [key: string]: (...args: unknown[]) => never;
+};
+export declare const Session: {
+    (...args: unknown[]): never;
+    new (...args: unknown[]): never;
+    readonly [key: string]: (...args: unknown[]) => never;
+};
+export declare const SandboxUser: {
+    (...args: unknown[]): never;
+    new (...args: unknown[]): never;
+    readonly [key: string]: (...args: unknown[]) => never;
+};
+export declare class SandboxUserAlreadyExistsError extends Error {
+}
+export declare const defineSandboxProxy: {
+    (...args: unknown[]): never;
+    new (...args: unknown[]): never;
+    readonly [key: string]: (...args: unknown[]) => never;
+};

package/dist/vercel/index.js

@@ -0,0 +1,38 @@
+/** Code written for Vercel Sandbox's SDK, on Runtime Cloud. Change the import:
+ *
+ *   import { Sandbox } from "withruntime/vercel"; // was: from "@vercel/sandbox"
+ *
+ * and set RUNTIME_API_KEY, or run `npx withruntime login` once. A Vercel token
+ * is never sent anywhere. What Runtime cannot do the way Vercel does throws
+ * NotSupportedError, naming what to use. */
+import { NotSupportedError } from "./errors.js";
+export { Sandbox, DEFAULT_TIMEOUT_MS, DEFAULT_VCPUS, MEMORY_MIB_PER_VCPU, networkRules, toRuntimePath, } from "./sandbox.js";
+export { Command, CommandFinished, } from "./command.js";
+export { FileSystem, Stats, Dirent } from "./filesystem.js";
+export { Snapshot } from "./snapshot.js";
+export { APIError, StreamError, AuthenticationError, NotSupportedError } from "./errors.js";
+/** Vercel's default region; Runtime runs in one US region. */
+export const DEFAULT_SANDBOX_REGION = "iad1";
+/** A stand-in for a Vercel export Runtime has no counterpart for. Importing it
+ * works, so a module that only mentions it still loads; calling it, building it
+ * or reading anything from it throws NotSupportedError naming the alternative. */
+function unsupportedExport(name, alternative) {
+    const fail = () => {
+        throw new NotSupportedError(`Vercel's ${name}`, alternative);
+    };
+    return new Proxy(function unsupported() { }, {
+        apply: fail,
+        construct: fail,
+        get: (_target, property) => {
+            if (typeof property === "symbol" || property === "then" || property === "prototype")
+                return undefined;
+            return fail();
+        },
+    });
+}
+export const Drive = unsupportedExport("Drive", "Use a Runtime volume (runtime.volumes) and mount it with withruntime: { create: { volumes: [{ volumeId, path }] } }.");
+export const Session = unsupportedExport("Session", "A Runtime sandbox is its own session: call the methods on the sandbox.");
+export const SandboxUser = unsupportedExport("SandboxUser", "Commands run as the sandbox owner with passwordless sudo; create users with `sudo useradd` in runCommand.");
+export class SandboxUserAlreadyExistsError extends Error {
+}
+export const defineSandboxProxy = unsupportedExport("sandbox proxy (defineSandboxProxy)", "Share a port with sandbox.withruntime.previews.create(port) instead.");