withruntime 0.3.1 → 0.5.0

package/dist/proxy.js

@@ -0,0 +1,178 @@
+/* Proxies named by the environment: HTTPS_PROXY, HTTP_PROXY and NO_PROXY, in
+   lower or upper case, the lower winning when both are set (as curl reads
+   them). Bun's fetch reads them itself; its WebSocket and Node's fetch and
+   WebSocket do not unless NODE_USE_ENV_PROXY was set before the process
+   started, which a library cannot do for its host. So every call the SDK and
+   the CLI make goes through `envFetch` and `openWebSocket`, which route by the
+   same rule on every runtime:
+
+   - an https:// or wss:// address uses HTTPS_PROXY; an http:// or ws:// one
+     uses HTTP_PROXY. HTTP_PROXY is never used for HTTPS (curl, Bun, Python
+     and Go agree; Node's own env support would fall back to it). A connection
+     error says so when that is why nothing was tried.
+   - NO_PROXY is a list of host names split by commas or spaces. A name
+     covers its subdomains, a leading dot is allowed, host:port limits it to
+     one port, and `*` alone means every host.
+   - A proxy address without a scheme is http://. Only http:// and https://
+     proxies are spoken to.
+
+   On Node the proxy is undici's ProxyAgent: undici is Node's own HTTP client
+   (the code under its fetch and WebSocket), loaded only when a proxy applies.
+   On Bun the proxy is passed to fetch and WebSocket as their `proxy` option. */
+import { RuntimeError } from "./errors.js";
+const processEnv = () => (typeof process === "undefined" ? {} : process.env);
+function variable(env, name) {
+    for (const candidate of [name.toLowerCase(), name.toUpperCase()]) {
+        const value = env[candidate]?.trim();
+        if (value)
+            return { value, name: candidate };
+    }
+    return undefined;
+}
+/** Whether a NO_PROXY list names this host (and port). Returns the entry. */
+export function exemption(list, hostname, port) {
+    const host = hostname
+        .toLowerCase()
+        .replace(/^\[|\]$/g, "")
+        .replace(/\.$/, "");
+    for (const raw of list.split(/[\s,]+/)) {
+        const entry = raw.trim().toLowerCase();
+        if (!entry)
+            continue;
+        if (entry === "*")
+            return entry;
+        const match = /^(.*?)(?::(\d+))?$/.exec(entry.replace(/^\[(.*)\]/, "$1"));
+        const name = match[1].replace(/^\./, "").replace(/\.$/, "");
+        if (!name || (match[2] && match[2] !== port))
+            continue;
+        if (host === name || host.endsWith(`.${name}`))
+            return entry;
+    }
+    return undefined;
+}
+/** The route the SDK takes to `target`, read from the environment now. */
+export function routeFor(target, env = processEnv()) {
+    const url = new URL(target);
+    const secure = url.protocol === "https:" || url.protocol === "wss:";
+    const port = url.port || (secure ? "443" : "80");
+    const found = variable(env, secure ? "https_proxy" : "http_proxy");
+    if (!found) {
+        const http = secure ? variable(env, "http_proxy") : undefined;
+        return http ? { httpOnly: http.name } : {};
+    }
+    const skip = variable(env, "no_proxy");
+    const exempt = skip && exemption(skip.value, url.hostname, port);
+    if (skip && exempt)
+        return { exempt, variable: skip.name };
+    const proxy = /^[a-z][a-z0-9+.-]*:\/\//i.test(found.value)
+        ? found.value
+        : `http://${found.value}`;
+    let parsed;
+    try {
+        parsed = new URL(proxy);
+    }
+    catch {
+        throw invalidProxy(found.name, found.value, "is not an address");
+    }
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:")
+        throw invalidProxy(found.name, `${parsed.protocol}//${parsed.host}`, "is not an HTTP proxy");
+    return { proxy, shown: `${parsed.protocol}//${parsed.host}`, variable: found.name };
+}
+function invalidProxy(name, shown, problem) {
+    return new RuntimeError({
+        message: `${name} (${shown}) ${problem}; Runtime connects through http:// and https:// proxies.`,
+        code: "invalid_proxy",
+        status: 0,
+        hint: `Set ${name} to the proxy's address, for example http://proxy.example.com:3128, or unset it.`,
+    });
+}
+/** Words for a failed connection: the route it took, and what to check.
+ * `cause` is the error fetch threw, or the status a proxy answered with (Bun's
+ * fetch hands a refused tunnel back as a response). */
+export function describeRoute(target, cause, env = processEnv()) {
+    let route;
+    try {
+        route = routeFor(target, env);
+    }
+    catch {
+        return { via: "" };
+    }
+    const url = new URL(target);
+    const port = url.port || (url.protocol === "https:" ? "443" : "80");
+    if (route.proxy) {
+        const status = typeof cause === "number" ? cause : proxyStatus(cause);
+        return {
+            via: ` through the proxy ${route.shown} (${route.variable})${status ? `, which answered HTTP ${status} to the tunnel request` : ""}`,
+            hint: status === 407
+                ? `The proxy wants credentials: put them in ${route.variable}, as http://user:password@host:port.`
+                : `Check that the proxy is running and allows CONNECT to ${url.hostname}:${port}, or list ${url.hostname} in NO_PROXY to connect directly.`,
+        };
+    }
+    if (route.exempt)
+        return {
+            via: ` (directly: ${route.variable} lists ${route.exempt})`,
+            hint: `Check the network, or remove ${route.exempt} from ${route.variable} to go through the proxy.`,
+        };
+    if (route.httpOnly)
+        return {
+            via: " (directly: no HTTPS proxy is set)",
+            hint: `${route.httpOnly} is set but HTTPS_PROXY is not, and ${url.hostname} is HTTPS. Set HTTPS_PROXY to the proxy to use it.`,
+        };
+    return { via: "" };
+}
+/** The status a proxy refused a tunnel with, from undici's or Bun's error. */
+function proxyStatus(cause) {
+    for (let error = cause, depth = 0; error && depth < 5; depth++) {
+        const message = error.message;
+        const text = typeof message === "string" ? message : "";
+        const found = /proxy response \((\d{3})\)|proxy.*?\b(40[37]|50[0-9])\b/i.exec(text);
+        if (found)
+            return Number(found[1] ?? found[2]);
+        error = error.cause;
+    }
+    return undefined;
+}
+const isBun = () => typeof process !== "undefined" && !!process.versions?.bun;
+const isNode = () => typeof process !== "undefined" &&
+    !!process.versions?.node &&
+    !process.versions.bun &&
+    !("Deno" in globalThis);
+const agents = new Map();
+/** One undici ProxyAgent per proxy address, so connections are reused. */
+function undici(proxy) {
+    let agent = agents.get(proxy);
+    if (!agent) {
+        agent = import("undici").then((module) => ({
+            fetch: module.fetch,
+            WebSocket: module.WebSocket,
+            dispatcher: new module.ProxyAgent({ uri: proxy }),
+        }));
+        agent.catch(() => agents.delete(proxy));
+        agents.set(proxy, agent);
+    }
+    return agent;
+}
+/** fetch, through the proxy the environment names for the address. */
+export const envFetch = (async (input, init) => {
+    const target = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
+    const { proxy } = routeFor(target);
+    if (proxy && isBun())
+        return fetch(input, { ...init, proxy });
+    if (proxy && isNode()) {
+        const { fetch: proxied, dispatcher } = await undici(proxy);
+        return (await proxied(target, { ...init, dispatcher }));
+    }
+    return fetch(input, init);
+});
+/** A WebSocket, through the proxy the environment names for the address. */
+export async function openWebSocket(url, headers) {
+    const { proxy } = routeFor(url);
+    if (proxy && isNode()) {
+        const { WebSocket: Proxied, dispatcher } = await undici(proxy);
+        return new Proxied(url, { headers, dispatcher });
+    }
+    const Socket = globalThis.WebSocket;
+    if (!Socket)
+        throw new Error("This runtime has no WebSocket; use Node 22+ or Bun.");
+    return new Socket(url, proxy && isBun() ? { headers, proxy } : { headers });
+}

package/dist/sandbox.d.ts

@@ -1,8 +1,9 @@
 import { Page } from "./page.js";
 import type { RequestOptions, Transport } from "./transport.js";
-import type { CommandResult, ExecOptions, FileEntry, OutputEvent, ProcessInfo, SandboxInfo } from "./types.js";
+import type { CommandResult, ExecOptions, FileEntry, OutputEvent, KeepAliveOptions, ProcessInfo, SandboxInfo, SandboxSettings } from "./types.js";
 import { type SandboxExtensions } from "./products/index.js";
 import type { Snapshot, SnapshotOptions } from "./snapshots.js";
+import { Tunnel, type PortForward } from "./tunnel.js";
 /** A running (or stopped) sandbox. Every method is one API call or a short
  * sequence of them; `await using sbx = await Sandbox.create()` stops it for
  * you at the end of the block. */
@@ -52,6 +53,18 @@ export declare class Sandbox implements AsyncDisposable {
         processId?: string;
         onData?: (data: Uint8Array) => void;
     }): Promise<Terminal>;
+    /** A tunnel into the sandbox: TCP connections to any port on its loopback,
+     * and SSH logins, over one authenticated WebSocket. No port is opened to the
+     * internet. `tunnel.connect(5432)` gives one connection;
+     * `tunnel.forward(5432)` listens locally (Node and Bun). */
+    tunnel(): Promise<Tunnel>;
+    /** Listens on a local port (the same number unless `localPort` says, 0 for
+     * any) and forwards each connection to `port` inside the sandbox, until
+     * `close()`. Node and Bun. */
+    forwardPort(port: number, options?: {
+        localPort?: number;
+        host?: string;
+    }): Promise<PortForward>;
     stop(options?: RequestOptions & {
         wait?: boolean;
     }): Promise<this>;
@@ -65,6 +78,18 @@ export declare class Sandbox implements AsyncDisposable {
     }): Promise<this>;
     /** More time before the lease ends (at most an hour ahead of now). */
     extend(seconds: number, options?: RequestOptions): Promise<this>;
+    /** Changes its name, labels, automatic wake, idle pause or persistence;
+     * fields left out stay as they are. `persistent: true` keeps it running
+     * while credit lasts (paid only). */
+    update(settings: SandboxSettings, options?: RequestOptions): Promise<this>;
+    /** Keeps a running sandbox's lease ahead of now, in the background, until
+     * stop() or the returned function ends it: every `everySeconds` (60) it
+     * extends the lease so that `marginSeconds` (600) remain, never more than
+     * the hour ahead the API allows. Running time is billed as it is used, as
+     * for any extension. A paused sandbox is left paused (a request wakes it,
+     * unless autoWake is off); a stopped one ends the loop. It does not keep a
+     * Node or Bun process alive by itself. */
+    keepAlive(options?: KeepAliveOptions): () => void;
     /** Days a paused sandbox is kept before deletion (1 to 365). */
     setRetention(days: number, options?: RequestOptions): Promise<this>;
     /** Keeps this sandbox's whole machine (files, memory, running processes) as
@@ -74,17 +99,20 @@ export declare class Sandbox implements AsyncDisposable {
     /** Copies of this sandbox as it is now (files, memory, running processes),
      * each its own sandbox, answered once they run. A running sandbox is paused
      * for the moment its snapshot takes, then woken. One without `count`; an
-     * array with it. */
+     * array with it. `funding` is what the copies run on, as for a create;
+     * omitted, they keep this sandbox's. */
     fork(options?: {
         name?: string;
         labels?: Record<string, string>;
         keepSnapshot?: boolean;
+        funding?: "trial" | "paid";
     } & RequestOptions): Promise<Sandbox>;
     fork(options: {
         count: number;
         name?: string;
         labels?: Record<string, string>;
         keepSnapshot?: boolean;
+        funding?: "trial" | "paid";
     } & RequestOptions): Promise<Sandbox[]>;
     /** Starts a stopped persistent sandbox again from its disk (memory is not kept). */
     restart(options?: RequestOptions & {

package/dist/sandbox.js

@@ -1,6 +1,7 @@
 import { CommandError, RuntimeError } from "./errors.js";
 import { Page } from "./page.js";
 import { sandboxFactories } from "./products/index.js";
+import { Tunnel } from "./tunnel.js";
 const CHUNK = 1_048_576;
 const PARALLEL = 4;
 const enc = (id) => encodeURIComponent(id);
@@ -21,6 +22,7 @@ function commandBody(command, options) {
 // eslint-disable-next-line @typescript-eslint/no-unsafe-declaration-merging
 export class Sandbox {
     #info;
+    #keepAlive;
     #t;
     files;
     processes;
@@ -79,6 +81,7 @@ export class Sandbox {
             const out = { stdout: "", stderr: "" };
             let exit;
             let processId;
+            let dropped = false;
             for await (const event of this.execStream(command, options)) {
                 if (event.type === "start")
                     processId = event.processId;
@@ -86,6 +89,8 @@ export class Sandbox {
                     out[event.type] += event.data;
                     (event.type === "stdout" ? options.onStdout : options.onStderr)?.(event.data);
                 }
+                else if (event.type === "truncated")
+                    dropped = true;
                 else if (event.type === "exit")
                     exit = event;
             }
@@ -93,6 +98,7 @@ export class Sandbox {
                 exitCode: exit?.exitCode ?? null,
                 ...out,
                 timedOut: exit?.timedOut ?? false,
+                ...truncation(dropped),
                 ...(exit?.durationMs === undefined ? {} : { durationMs: exit.durationMs }),
                 ...(processId ? { processId } : {}),
             };
@@ -163,7 +169,35 @@ export class Sandbox {
         });
         return Terminal.open(socket, options.onData);
     }
+    /** A tunnel into the sandbox: TCP connections to any port on its loopback,
+     * and SSH logins, over one authenticated WebSocket. No port is opened to the
+     * internet. `tunnel.connect(5432)` gives one connection;
+     * `tunnel.forward(5432)` listens locally (Node and Bun). */
+    async tunnel() {
+        return Tunnel.open(await this.#t.websocket(`/v1/sandboxes/${enc(this.id)}/tunnel`));
+    }
+    /** Listens on a local port (the same number unless `localPort` says, 0 for
+     * any) and forwards each connection to `port` inside the sandbox, until
+     * `close()`. Node and Bun. */
+    async forwardPort(port, options = {}) {
+        const tunnel = await this.tunnel();
+        try {
+            const forward = await tunnel.forward(port, options);
+            return {
+                ...forward,
+                close: async () => {
+                    await forward.close();
+                    tunnel.close();
+                },
+            };
+        }
+        catch (error) {
+            tunnel.close();
+            throw error;
+        }
+    }
     async stop(options = {}) {
+        this.#keepAlive?.();
         return this.#lifecycle("stop", options);
     }
     async pause(options = {}) {
@@ -178,6 +212,58 @@ export class Sandbox {
     async extend(seconds, options = {}) {
         return this.#lifecycle("extend", { ...options, wait: false }, { seconds });
     }
+    /** Changes its name, labels, automatic wake, idle pause or persistence;
+     * fields left out stay as they are. `persistent: true` keeps it running
+     * while credit lasts (paid only). */
+    async update(settings, options = {}) {
+        return this.#lifecycle("update", { ...options, wait: false }, { ...settings });
+    }
+    /** Keeps a running sandbox's lease ahead of now, in the background, until
+     * stop() or the returned function ends it: every `everySeconds` (60) it
+     * extends the lease so that `marginSeconds` (600) remain, never more than
+     * the hour ahead the API allows. Running time is billed as it is used, as
+     * for any extension. A paused sandbox is left paused (a request wakes it,
+     * unless autoWake is off); a stopped one ends the loop. It does not keep a
+     * Node or Bun process alive by itself. */
+    keepAlive(options = {}) {
+        this.#keepAlive?.();
+        const every = Math.max(10, options.everySeconds ?? 60) * 1000;
+        const margin = Math.min(3600, Math.max(60, options.marginSeconds ?? 600));
+        let ended = false;
+        let timer;
+        const end = () => {
+            ended = true;
+            if (timer)
+                clearTimeout(timer);
+            if (this.#keepAlive === end)
+                this.#keepAlive = undefined;
+        };
+        const tick = async () => {
+            if (ended)
+                return;
+            try {
+                await this.refresh();
+                if (this.state === "stopped" || this.state === "stopping")
+                    return end();
+                if (this.state === "running") {
+                    const left = (Date.parse(this.info.expiresAt) - Date.now()) / 1000;
+                    const need = Math.ceil(margin - left);
+                    if (need >= 1)
+                        await this.extend(Math.min(3600, need));
+                }
+            }
+            catch (error) {
+                options.onError?.(error);
+            }
+            if (ended)
+                return;
+            timer = setTimeout(() => void tick(), every);
+            timer.unref?.();
+        };
+        this.#keepAlive = end;
+        void tick();
+        return end;
+    }
     /** Days a paused sandbox is kept before deletion (1 to 365). */
     async setRetention(days, options = {}) {
         return this.#lifecycle("retention", { ...options, wait: false }, { days });
@@ -240,6 +326,7 @@ export class Sandbox {
         return this;
     }
     async [Symbol.asyncDispose]() {
+        this.#keepAlive?.();
         if (this.#info.state === "stopped")
             return;
         await this.stop({ wait: false }).catch(() => undefined);
@@ -248,6 +335,13 @@ export class Sandbox {
         return this.#info;
     }
 }
+/** A streamed command keeps all its output unless the reader fell more than the
+ * process's output buffer behind, which the server marks with a "truncated"
+ * event. That event does not say which stream lost bytes, so both flags carry
+ * it; without one, both are false, as a synchronous result's are. */
+function truncation(dropped) {
+    return { stdoutTruncated: dropped, stderrTruncated: dropped };
+}
 function pick(options) {
     return {
         ...(options.idempotencyKey ? { idempotencyKey: options.idempotencyKey } : {}),
@@ -332,9 +426,12 @@ export class Process {
     async wait(options = {}) {
         const out = { stdout: "", stderr: "" };
         let exit;
+        let dropped = false;
         for await (const event of this.output(options)) {
             if (event.type === "stdout" || event.type === "stderr")
                 out[event.type] += event.data;
+            if (event.type === "truncated")
+                dropped = true;
             if (event.type === "exit")
                 exit = event;
         }
@@ -342,6 +439,7 @@ export class Process {
             exitCode: exit?.exitCode ?? null,
             ...out,
             timedOut: exit?.timedOut ?? false,
+            ...truncation(dropped),
             processId: this.id,
         };
     }
@@ -576,7 +674,9 @@ export class Files {
         }
         const { packDirectory } = await import("./tar.js");
         const archive = await packDirectory(localPath);
-        const staging = `/tmp/.runtime-upload-${crypto.randomUUID()}.tar.gz`;
+        // Large writes go only to /workspace (the server refuses others), so the
+        // archive is staged there and removed after unpacking.
+        const staging = `/workspace/.runtime-upload-${crypto.randomUUID()}.tar.gz`;
         await this.write(staging, archive);
         const result = await new Sandbox(this.t, { id: this.sandboxId }).exec([
             "sh",

package/dist/ssh.d.ts

@@ -0,0 +1,21 @@
+import type { Runtime } from "./client.js";
+import type { Sandbox } from "./sandbox.js";
+type Out = {
+    json: boolean;
+    write: (text: string) => void;
+    error: (text: string) => void;
+};
+export declare const SSH_HELP: (me: string) => string;
+/** This machine's key for Runtime SSH logins, made on first use. Only its
+ * public half ever leaves the machine, and only into the one login it opens. */
+export declare function sshKey(env: NodeJS.ProcessEnv): Promise<{
+    path: string;
+    publicKey: string;
+}>;
+/** A sandbox by id or by its name, as `ssh` hands it over (`<id>.runtime`). */
+export declare function resolveSandbox(runtime: Runtime, target: string): Promise<Sandbox>;
+export declare function sshConfig(env: NodeJS.ProcessEnv): Promise<string>;
+export declare function sshCommand(argv: string[], env: NodeJS.ProcessEnv, out: Out, connect: () => Promise<Runtime>, me: string): Promise<number>;
+/** `runtime sandbox port-forward <id> 5432 8080:3000 ...` */
+export declare function portForwardCommand(argv: string[], out: Out, connect: () => Promise<Runtime>, me: string): Promise<number>;
+export {};