withruntime 0.3.1 → 0.5.0

package/dist/vercel/client.d.ts

@@ -0,0 +1,40 @@
+import { Runtime } from "../client.js";
+/** The Runtime sandbox the adapter drives. */
+export type RuntimeSandbox = Awaited<ReturnType<Runtime["sandboxes"]["create"]>>;
+/** What `Sandbox.create` sends to Runtime. */
+export type RuntimeCreate = NonNullable<Parameters<Runtime["sandboxes"]["create"]>[0]>;
+/** Vercel's credentials. A Vercel token is never sent anywhere: only a
+ * Runtime key (`rtcloud_...`) given as `token` is used. */
+export interface Credentials {
+    token?: string;
+    teamId?: string;
+    projectId?: string;
+}
+/** Runtime-only options, for code that has been through the switch. The key
+ * is `withruntime` because Vercel's own `runtime` field names a Node.js or
+ * Python version. */
+export interface WithRuntime {
+    /** A Runtime client to use instead of one made from the key. */
+    client?: Runtime;
+    /** Fields sent as they are with the create, over the adapter's own: for
+     * example `{ funding: "trial" }` or `{ memoryMiB: 8192 }`. */
+    create?: Partial<RuntimeCreate>;
+}
+/** The key to use: a Runtime key given as `token`, then RUNTIME_API_KEY, then
+ * the key `npx withruntime login` saved (undefined lets the Runtime SDK find
+ * it). A Vercel token passed as `token` is refused, never sent. */
+export declare function pickKey(token?: string): string | undefined;
+/** The Runtime client for these options: an explicit client, else one per key,
+ * made once and reused so its connections stay open. */
+export declare function clientFor(opts?: Credentials & {
+    withruntime?: WithRuntime;
+}): Runtime;
+/** Test hook: forget the cached clients. */
+export declare function resetClients(): void;
+export declare function signalOf(opts?: {
+    signal?: AbortSignal;
+}): {
+    signal: AbortSignal;
+} | {
+    signal?: undefined;
+};

package/dist/vercel/client.js

@@ -0,0 +1,39 @@
+import { Runtime } from "../client.js";
+import { AuthenticationError } from "./errors.js";
+const env = (name) => typeof process === "undefined" ? undefined : process.env[name];
+const isRuntimeKey = (key) => key.startsWith("rtcloud_");
+const clients = new Map();
+/** The key to use: a Runtime key given as `token`, then RUNTIME_API_KEY, then
+ * the key `npx withruntime login` saved (undefined lets the Runtime SDK find
+ * it). A Vercel token passed as `token` is refused, never sent. */
+export function pickKey(token) {
+    if (token !== undefined && isRuntimeKey(token))
+        return token;
+    const runtimeKey = env("RUNTIME_API_KEY");
+    if (runtimeKey)
+        return runtimeKey;
+    if (token !== undefined && token !== "")
+        throw new AuthenticationError("The token passed is a Vercel token, and it was not sent. Set RUNTIME_API_KEY to a Runtime key " +
+            "(https://withruntime.com/account/keys, or run `npx withruntime login`), or pass the Runtime key as token.");
+    return undefined;
+}
+/** The Runtime client for these options: an explicit client, else one per key,
+ * made once and reused so its connections stay open. */
+export function clientFor(opts = {}) {
+    if (opts.withruntime?.client)
+        return opts.withruntime.client;
+    const key = pickKey(opts.token);
+    let client = clients.get(key ?? "");
+    if (!client) {
+        client = new Runtime(key ? { apiKey: key } : {});
+        clients.set(key ?? "", client);
+    }
+    return client;
+}
+/** Test hook: forget the cached clients. */
+export function resetClients() {
+    clients.clear();
+}
+export function signalOf(opts) {
+    return opts?.signal ? { signal: opts.signal } : {};
+}

package/dist/vercel/command.d.ts

@@ -0,0 +1,70 @@
+import type { Process } from "../sandbox.js";
+/** One piece of a command's output, as Vercel's `logs()` yields it. */
+export type LogOutputLine = {
+    stream: "stdout" | "stderr";
+    data: string;
+};
+/** Cached output from a command, as in Vercel. */
+export interface CommandOutput {
+    stdout: string;
+    stderr: string;
+}
+export type Signal = "SIGTERM" | "SIGKILL" | "SIGINT" | "SIGHUP" | "SIGQUIT" | "SIGUSR1" | "SIGUSR2" | number;
+/** A command killed by a signal has no exit code on Runtime. One killed at
+ * its `timeoutMs` (SIGKILL) reports 137, as a shell does; any other signal
+ * reports -1. */
+export declare function exitCodeOf(exitCode: number | null, timedOut: boolean): number;
+type Init = {
+    id: string;
+    cwd: string;
+    startedAt: number;
+    sandboxName: string;
+    process?: Process;
+    lines?: LogOutputLine[];
+};
+/** A command in a sandbox, as Vercel's `Command`. A detached one runs on:
+ * `wait()` for its end, `logs()` for its output as it happens. `cmdId` is
+ * Runtime's process id. */
+export declare class Command {
+    #private;
+    exitCode: number | null;
+    durationMs?: number;
+    protected readonly init: Init;
+    constructor(init: Init);
+    get cmdId(): string;
+    get cwd(): string;
+    get startedAt(): number;
+    /** The command's output from its start, as it happens:
+     * `for await (const log of cmd.logs()) process.stdout.write(log.data)`. */
+    logs(opts?: {
+        signal?: AbortSignal;
+    }): AsyncGenerator<LogOutputLine, void, void> & Disposable & {
+        close(): void;
+    };
+    /** Waits for the command to end. */
+    wait(params?: {
+        signal?: AbortSignal;
+    }): Promise<CommandFinished>;
+    /** stdout, stderr, or both in the order they were written. For a detached
+     * command this waits for it to end. */
+    output(stream?: "stdout" | "stderr" | "both", opts?: {
+        signal?: AbortSignal;
+    }): Promise<string>;
+    stdout(opts?: {
+        signal?: AbortSignal;
+    }): Promise<string>;
+    stderr(opts?: {
+        signal?: AbortSignal;
+    }): Promise<string>;
+    /** Sends a signal, SIGTERM by default. */
+    kill(signal?: Signal, _opts?: {
+        abortSignal?: AbortSignal;
+    }): Promise<void>;
+}
+/** A command that has ended; `exitCode` is set. */
+export declare class CommandFinished extends Command {
+    exitCode: number;
+    constructor(init: Init, exitCode: number, durationMs?: number);
+    wait(): Promise<CommandFinished>;
+}
+export {};

package/dist/vercel/command.js

@@ -0,0 +1,148 @@
+import { guard, StreamError, translate } from "./errors.js";
+const SIGNAL_NUMBERS = {
+    1: "SIGHUP",
+    2: "SIGINT",
+    3: "SIGQUIT",
+    9: "SIGKILL",
+    10: "SIGUSR1",
+    12: "SIGUSR2",
+    15: "SIGTERM",
+};
+/** A command killed by a signal has no exit code on Runtime. One killed at
+ * its `timeoutMs` (SIGKILL) reports 137, as a shell does; any other signal
+ * reports -1. */
+export function exitCodeOf(exitCode, timedOut) {
+    if (exitCode !== null)
+        return exitCode;
+    return timedOut ? 137 : -1;
+}
+function join(lines, stream) {
+    return lines
+        .filter((line) => stream === "both" || line.stream === stream)
+        .map((line) => line.data)
+        .join("");
+}
+/** A command in a sandbox, as Vercel's `Command`. A detached one runs on:
+ * `wait()` for its end, `logs()` for its output as it happens. `cmdId` is
+ * Runtime's process id. */
+export class Command {
+    exitCode = null;
+    durationMs;
+    init;
+    #finished;
+    constructor(init) {
+        this.init = init;
+    }
+    get cmdId() {
+        return this.init.id;
+    }
+    get cwd() {
+        return this.init.cwd;
+    }
+    get startedAt() {
+        return this.init.startedAt;
+    }
+    /** The command's output from its start, as it happens:
+     * `for await (const log of cmd.logs()) process.stdout.write(log.data)`. */
+    logs(opts = {}) {
+        const abort = new AbortController();
+        const forward = () => abort.abort();
+        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 (lines) {
+                    yield* lines;
+                    return;
+                }
+                try {
+                    for await (const event of process.output({ signal: abort.signal })) {
+                        if (event.type === "stdout" || event.type === "stderr")
+                            yield { stream: event.type, data: event.data };
+                        if (event.type === "exit")
+                            return;
+                    }
+                }
+                catch (error) {
+                    if (abort.signal.aborted)
+                        return;
+                    const translated = translate(error, sandboxName);
+                    throw translated instanceof Error && translated !== error
+                        ? translated
+                        : new StreamError("stream_failed", String(error.message ?? error), process.id);
+                }
+            }
+            finally {
+                opts.signal?.removeEventListener("abort", forward);
+            }
+        }
+        const generator = read();
+        return Object.assign(generator, {
+            close: () => abort.abort(),
+            [Symbol.dispose]: () => abort.abort(),
+        });
+    }
+    /** Waits for the command to end. */
+    wait(params = {}) {
+        this.#finished ??= this.#follow(params);
+        return this.#finished;
+    }
+    async #follow(params) {
+        const lines = [];
+        let exit;
+        await guard(async () => {
+            for await (const event of this.init.process.output(params.signal ? { signal: params.signal } : {})) {
+                if (event.type === "stdout" || event.type === "stderr")
+                    lines.push({ stream: event.type, data: event.data });
+                else if (event.type === "exit")
+                    exit = {
+                        exitCode: event.exitCode,
+                        timedOut: event.timedOut,
+                        ...(event.durationMs === undefined ? {} : { durationMs: event.durationMs }),
+                    };
+            }
+        }, this.init.sandboxName);
+        if (!exit)
+            throw new StreamError("stream_ended", "The command's output ended before it exited.", this.init.process.id);
+        this.exitCode = exitCodeOf(exit.exitCode, exit.timedOut);
+        if (exit.durationMs !== undefined)
+            this.durationMs = exit.durationMs;
+        return new CommandFinished({ ...this.init, lines }, this.exitCode, exit.durationMs ?? undefined);
+    }
+    /** stdout, stderr, or both in the order they were written. For a detached
+     * command this waits for it to end. */
+    async output(stream = "both", opts = {}) {
+        if (this.init.lines)
+            return join(this.init.lines, stream);
+        return (await this.wait(opts)).output(stream);
+    }
+    stdout(opts = {}) {
+        return this.output("stdout", opts);
+    }
+    stderr(opts = {}) {
+        return this.output("stderr", opts);
+    }
+    /** Sends a signal, SIGTERM by default. */
+    async kill(signal = "SIGTERM", _opts = {}) {
+        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);
+    }
+}
+/** A command that has ended; `exitCode` is set. */
+export class CommandFinished extends Command {
+    constructor(init, exitCode, durationMs) {
+        super(init);
+        this.exitCode = exitCode;
+        if (durationMs !== undefined)
+            this.durationMs = durationMs;
+    }
+    wait() {
+        return Promise.resolve(this);
+    }
+}

package/dist/vercel/errors.d.ts

@@ -0,0 +1,53 @@
+interface Options<ErrorData> {
+    message?: string;
+    json?: ErrorData;
+    text?: string;
+    sandboxName?: string;
+    sessionId?: string;
+}
+/** An error answer from the API. `response.status` is the HTTP status, and
+ * `json` is `{ error: { code, message } }` as Vercel's is. */
+export declare class APIError<ErrorData = unknown> extends Error {
+    response: Response;
+    json?: ErrorData;
+    text?: string;
+    sandboxName?: string;
+    sessionId?: string;
+    code?: string;
+    hint?: string;
+    requestId?: string;
+    constructor(response: Response, options?: Options<ErrorData>);
+}
+/** A command's output stream failed, as Vercel's StreamError. */
+export declare class StreamError extends Error {
+    code: string;
+    sessionId: string;
+    constructor(code: string, message: string, sessionId: string);
+}
+/** A Vercel token was given where a Runtime key is needed. */
+export declare class AuthenticationError extends Error {
+    constructor(message: string);
+}
+/** A call that Vercel Sandbox supports and Runtime does not, or not in the
+ * same way. Thrown before anything is done, never after doing something
+ * different. `feature` names what was asked for; `alternative` says what to
+ * use on Runtime instead. */
+export declare class NotSupportedError extends Error {
+    readonly code = "not_supported";
+    readonly feature: string;
+    readonly alternative: string;
+    constructor(feature: string, alternative: string, message?: string);
+}
+/** A Runtime SDK error as Vercel's APIError, or NotSupportedError for a
+ * product Runtime has switched off. Anything else passes through unchanged. */
+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";
+    errno: number;
+    syscall: string;
+    path: string;
+};
+export {};

package/dist/vercel/errors.js

@@ -0,0 +1,113 @@
+import { RuntimeError } from "../errors.js";
+/** An error answer from the API. `response.status` is the HTTP status, and
+ * `json` is `{ error: { code, message } }` as Vercel's is. */
+export class APIError extends Error {
+    response;
+    json;
+    text;
+    sandboxName;
+    sessionId;
+    code;
+    hint;
+    requestId;
+    constructor(response, options = {}) {
+        super(options.message ?? `Status code ${response.status} is not ok`);
+        this.name = new.target.name;
+        this.response = response;
+        if (options.json !== undefined)
+            this.json = options.json;
+        if (options.text !== undefined)
+            this.text = options.text;
+        if (options.sandboxName !== undefined)
+            this.sandboxName = options.sandboxName;
+        if (options.sessionId !== undefined)
+            this.sessionId = options.sessionId;
+    }
+}
+/** A command's output stream failed, as Vercel's StreamError. */
+export class StreamError extends Error {
+    code;
+    sessionId;
+    constructor(code, message, sessionId) {
+        super(message);
+        this.name = new.target.name;
+        this.code = code;
+        this.sessionId = sessionId;
+    }
+}
+/** A Vercel token was given where a Runtime key is needed. */
+export class AuthenticationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = new.target.name;
+    }
+}
+/** A call that Vercel Sandbox supports and Runtime does not, or not in the
+ * same way. Thrown before anything is done, never after doing something
+ * different. `feature` names what was asked for; `alternative` says what to
+ * use on Runtime instead. */
+export class NotSupportedError extends Error {
+    code = "not_supported";
+    feature;
+    alternative;
+    constructor(feature, alternative, message) {
+        super(message ?? `${feature} is not supported on Runtime. ${alternative}`);
+        this.name = new.target.name;
+        this.feature = feature;
+        this.alternative = alternative;
+    }
+}
+/** A Runtime SDK error as Vercel's APIError, or NotSupportedError for a
+ * product Runtime has switched off. Anything else passes through unchanged. */
+export function translate(error, sandboxName) {
+    if (!(error instanceof RuntimeError))
+        return error;
+    const message = [
+        error.message,
+        error.hint ? `Hint: ${error.hint}` : "",
+        error.requestId ? `Request: ${error.requestId}` : "",
+    ]
+        .filter(Boolean)
+        .join("\n");
+    if (error.status === 503 && error.code.endsWith("_unavailable"))
+        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 out = new APIError(new Response(JSON.stringify(json), {
+        status: error.status,
+        headers: { "content-type": "application/json" },
+    }), { message, json, text: JSON.stringify(json), ...(sandboxName ? { sandboxName } : {}) });
+    out.code = error.code;
+    if (error.hint)
+        out.hint = error.hint;
+    if (error.requestId)
+        out.requestId = error.requestId;
+    out.cause = error;
+    return out;
+}
+/** Runs `work`, turning any Runtime error into Vercel's. */
+export async function guard(work, sandboxName) {
+    try {
+        return await work();
+    }
+    catch (error) {
+        throw translate(error, sandboxName);
+    }
+}
+/** A node:fs-style error, as Vercel's `sandbox.fs` throws. */
+export function fsError(code, syscall, path) {
+    const text = {
+        ENOENT: "no such file or directory",
+        EEXIST: "file already exists",
+        EISDIR: "illegal operation on a directory",
+        ENOTDIR: "not a directory",
+    }[code];
+    const errno = { ENOENT: -2, EEXIST: -17, EISDIR: -21, ENOTDIR: -20 }[code];
+    return Object.assign(new Error(`${code}: ${text}, ${syscall} '${path}'`), {
+        code,
+        errno,
+        syscall,
+        path,
+    });
+}

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 {};