withruntime 0.4.0 → 0.5.0

package/dist/types.d.ts

@@ -16,6 +16,16 @@ export type SandboxInfo = {
     cpuFloorMillis: number;
     pausable: boolean;
     timeoutSeconds: number;
+    /** Pauses after this many idle seconds; 0 is never. */
+    idlePauseSeconds?: number;
+    /** True for the default idle pause, which pauses only a sandbox nothing has used yet. */
+    idlePauseUnusedOnly?: boolean;
+    /** A request (exec, files, terminal, a visit to a shared port) wakes it when paused. */
+    autoWake?: boolean;
+    /** Its lease renews itself while credit lasts, and its disk is kept after a stop. */
+    persistent?: boolean;
+    /** The last exec, file, terminal, desktop or preview request, to within a minute. */
+    lastActiveAt?: string | null;
     onLeaseEnd: "pause" | "stop";
     createdAt: string;
     readyAt: string | null;
@@ -28,6 +38,16 @@ export type SandboxInfo = {
     heldMicros: number;
     simulated?: boolean;
     replayed?: boolean;
+    /** On a create from an image with a start command: whether it started,
+     * became ready (readyMs), timed out, or exited first. */
+    start?: {
+        state: "started" | "ready" | "timeout" | "exited" | "not_running";
+        processId?: string;
+        exitCode?: number | null;
+        readyMs?: number;
+    };
+    /** Present and true when getOrCreate answered a sandbox that already held the name. */
+    reused?: boolean;
     [key: string]: unknown;
 };
 export type CreateSandbox = {
@@ -46,6 +66,18 @@ export type CreateSandbox = {
     pausable?: boolean;
     /** What happens when timeoutSeconds runs out: "pause" (default) or "stop". */
     onLeaseEnd?: "pause" | "stop";
+    /** Pause after this many seconds with no exec, file, terminal, desktop or
+     * preview request (60 to 86400; 0 never). A request wakes it again. */
+    idlePauseSeconds?: number;
+    /** A request to a paused sandbox wakes it. Default true. */
+    autoWake?: boolean;
+    /** Keep it running while credit lasts (its lease renews itself) and keep its
+     * disk after a stop, for restart(). Paid only. */
+    persistent?: boolean;
+    /** The most it may cost over its whole life, in microdollars. */
+    maxTotalCostMicros?: number;
+    /** With name: return the sandbox that already has the name, woken if paused. */
+    getOrCreate?: boolean;
     maxCostMicros?: number;
     /** Network rules from the first start; the same shape as sandbox.network.set.
      * Omit for the public web on ports 80 and 443. */
@@ -55,7 +87,9 @@ export type CreateSandbox = {
         deny?: string[];
         connect?: string[];
     };
-    /** A ready image's id (runtime.images.build); the sandbox starts from it. */
+    /** A ready image (runtime.images.build): its id, name (its latest tag),
+     * name:tag or name@version. When the image has a start command, create
+     * answers once its ready check passes and says how in `start`. */
     image?: string;
     /** A ready snapshot's id: the sandbox starts as a copy of it, with its shape. Not with image. */
     snapshot?: string;
@@ -173,3 +207,25 @@ export type Usage = {
     [key: string]: unknown;
 };
 export type FeedbackKind = "bug" | "missing_feature" | "competitor_gap" | "migration_blocker" | "docs" | "pricing" | "praise" | "other";
+/** What `sandbox.update()` changes; fields left out stay as they are. */
+export type SandboxSettings = {
+    name?: string;
+    labels?: Record<string, string>;
+    /** A request to a paused sandbox wakes it. */
+    autoWake?: boolean;
+    /** Pause after this many seconds with no activity, counted from now; 0 never. */
+    idlePauseSeconds?: number;
+    /** Keep it running while credit lasts and keep its disk after a stop. Paid only. */
+    persistent?: boolean;
+    /** Lifetime cap in microdollars; null removes it. */
+    maxTotalCostMicros?: number | null;
+};
+/** How `sandbox.keepAlive()` extends the lease. */
+export type KeepAliveOptions = {
+    /** How often it checks, in seconds. Default 60. */
+    everySeconds?: number;
+    /** How much lease it keeps ahead of now, in seconds (60 to 3600). Default 600. */
+    marginSeconds?: number;
+    /** Called with an error an extension met; the loop carries on. */
+    onError?: (error: unknown) => void;
+};

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,
+    });
+}