withruntime 0.8.4 → 0.10.0

package/dist/modal/index.js

@@ -0,0 +1,486 @@
+import { all, client, CompatibilityError, create, destroy, execOptions, only, region, } from "../compat/core.js";
+import { GuestFiles } from "../compat/files.js";
+export { CompatibilityError };
+export class NotFoundError extends Error {
+}
+export class TimeoutError extends Error {
+}
+export class SandboxTimeoutError extends TimeoutError {
+}
+export class App {
+    appId;
+    name;
+    environmentName;
+    constructor(appId, name, environmentName) {
+        this.appId = appId;
+        this.name = name;
+        this.environmentName = environmentName;
+    }
+}
+export class Secret {
+    values;
+    constructor(values) {
+        this.values = values;
+    }
+}
+export class ModalClient {
+    runtime;
+    apps;
+    images;
+    sandboxes;
+    secrets = { fromObject: (values) => new Secret(values) };
+    constructor(options = {}) {
+        only("Modal client", options, [
+            "apiKey",
+            "baseUrl",
+            "fetch",
+            "client",
+            "timeoutMs",
+            "maxRetries",
+            "tokenId",
+            "tokenSecret",
+            "environment",
+        ]);
+        this.runtime = client(options);
+        const runtime = this.runtime;
+        this.apps = {
+            fromName: async (name, params = {}) => {
+                only("Modal app", params, ["createIfMissing", "environment"]);
+                if (params.environment || options.environment)
+                    throw new CompatibilityError("Modal", "named Modal environments");
+                if (!params.createIfMissing &&
+                    !(await all(runtime, "modal")).some((s) => s.info.labels["modal.app"] === name))
+                    throw new NotFoundError(`App ${name} has no Runtime sandboxes; pass createIfMissing: true.`);
+                return new App(name, name);
+            },
+        };
+        this.images = {
+            fromRegistry: (tag, secret) => {
+                if (secret)
+                    throw new CompatibilityError("Modal", "registry Secret; configure Runtime image registry credentials");
+                return new Image(runtime, tag);
+            },
+            fromId: async (id) => new Image(runtime, undefined, (await runtime.images.get(id)).id),
+            fromName: async (name) => new Image(runtime, undefined, (await runtime.images.resolve(name)).id),
+            delete: (id) => runtime.images.delete(id),
+        };
+        this.sandboxes = new SandboxService(runtime);
+    }
+    close() {
+        /* Transport has no owned background connection to close. */
+    }
+}
+export class Image {
+    runtime;
+    tag;
+    commands;
+    env;
+    cache;
+    built;
+    constructor(runtime, tag, id, commands = [], env = {}, cache = true) {
+        this.runtime = runtime;
+        this.tag = tag;
+        this.commands = commands;
+        this.env = env;
+        this.cache = cache;
+        this.built = id;
+    }
+    get imageId() {
+        if (!this.built)
+            throw new Error("Image is not built; await image.build(app) first.");
+        return this.built;
+    }
+    dockerfileCommands(commands, params = {}) {
+        only("Modal image", params, ["env", "forceBuild"]);
+        if (!this.tag)
+            throw new CompatibilityError("Modal", "extending a prebuilt Runtime image through Dockerfile layers");
+        return new Image(this.runtime, this.tag, undefined, [...this.commands, ...commands], { ...this.env, ...params.env }, params.forceBuild ? false : this.cache);
+    }
+    async build(_app) {
+        if (!this.built) {
+            const built = this.commands.length
+                ? await this.runtime.images.build({
+                    dockerfile: [`FROM ${this.tag}`, ...this.commands].join("\n"),
+                    env: this.env,
+                    cache: this.cache,
+                })
+                : await this.runtime.images.build({ image: this.tag, env: this.env, cache: this.cache });
+            this.built = built.id;
+        }
+        return this;
+    }
+}
+export class SandboxService {
+    runtime;
+    constructor(runtime) {
+        this.runtime = runtime;
+    }
+    async create(app, image, params = {}) {
+        only("Modal sandbox", params, [
+            "name",
+            "cpu",
+            "cpuLimit",
+            "memoryMiB",
+            "memoryLimitMiB",
+            "timeoutMs",
+            "workdir",
+            "command",
+            "env",
+            "encryptedPorts",
+            "blockNetwork",
+            "outboundDomainAllowlist",
+            "outboundCidrAllowlist",
+            "tags",
+            "regions",
+            "gpu",
+            "pty",
+            "secrets",
+            "experimentalEnableSnapshot",
+        ]);
+        if (params.gpu)
+            throw new CompatibilityError("Modal", "GPU allocation");
+        if (params.cpuLimit !== undefined && params.cpuLimit !== params.cpu)
+            throw new CompatibilityError("Modal", "separate CPU reservation and hard limit");
+        if (params.memoryLimitMiB !== undefined && params.memoryLimitMiB !== params.memoryMiB)
+            throw new CompatibilityError("Modal", "separate memory reservation and hard limit");
+        if (params.regions && params.regions.length !== 1)
+            throw new CompatibilityError("Modal", "multiple region placement");
+        if (params.cpu !== undefined && !Number.isInteger(params.cpu))
+            throw new CompatibilityError("Modal", "fractional CPU reservations");
+        if (params.blockNetwork && (params.outboundDomainAllowlist || params.outboundCidrAllowlist))
+            throw new TypeError("blockNetwork cannot be combined with allowlists");
+        const placement = region("Modal", params.regions?.[0]);
+        const built = await image.build(app);
+        let primary;
+        const s = await create(this.runtime, "modal", {
+            name: params.name ? `${app.name ?? app.appId}-${params.name}` : undefined,
+            labels: {
+                "modal.app": app.name ?? app.appId,
+                ...(params.name ? { "modal.name": params.name } : {}),
+                "modal.tags": JSON.stringify(params.tags ?? {}),
+            },
+            image: built.imageId,
+            cpu: "reserved",
+            vcpu: params.cpu,
+            memoryMiB: params.memoryMiB,
+            region: placement,
+            timeoutSeconds: Math.ceil((params.timeoutMs ?? 300_000) / 1000),
+            idlePauseSeconds: 0,
+            onLeaseEnd: "stop",
+            network: {
+                internet: !params.blockNetwork,
+                allow: [
+                    ...(params.outboundDomainAllowlist ?? []),
+                    ...(params.outboundCidrAllowlist ?? []),
+                ],
+            },
+        }, Object.assign({}, ...(params.secrets?.map((s) => s.values) ?? []), params.env ?? {}), async (s) => {
+            primary = await s.spawn(params.command ?? ["sleep", "infinity"], {
+                ...(await execOptions(s, { cwd: params.workdir })),
+                stdin: "pipe",
+                pty: params.pty ? {} : undefined,
+            });
+            await s.update({ labels: { ...s.info.labels, "modal.entrypoint": primary.id } });
+            for (const port of params.encryptedPorts ?? [])
+                await s.previews.create(port, { visibility: "public" });
+        });
+        const sandbox = new Sandbox(s, new ContainerProcess(primary, "text"));
+        sandbox.monitorEntrypoint();
+        return sandbox;
+    }
+    async fromId(id) {
+        const s = await this.runtime.sandboxes.get(id);
+        const p = s.info.labels["modal.entrypoint"];
+        if (!p)
+            throw new NotFoundError("Sandbox is not a Modal-compatible sandbox");
+        return new Sandbox(s, new ContainerProcess(await s.processes.get(p), "text"));
+    }
+    async fromName(appName, name) {
+        const s = (await all(this.runtime, "modal")).find((s) => s.info.labels["modal.app"] === appName &&
+            s.info.labels["modal.name"] === name &&
+            s.state === "running");
+        if (!s)
+            throw new NotFoundError(`Sandbox ${name} not found`);
+        return this.fromId(s.id);
+    }
+    async *list(params = {}) {
+        only("Modal list", params, ["appId", "tags"]);
+        for (const s of await all(this.runtime, "modal"))
+            if (s.state === "running" &&
+                (!params.appId || s.info.labels["modal.app"] === params.appId) &&
+                Object.entries(params.tags ?? {}).every(([k, v]) => JSON.parse(s.info.labels["modal.tags"] ?? "{}")[k] === v))
+                yield await this.fromId(s.id);
+    }
+}
+export class ModalReadStream extends ReadableStream {
+    constructor(process, channel, mode, ignore = false) {
+        const iterator = mode === "binary" ? process.outputBytes() : process.output();
+        super({
+            async pull(controller) {
+                if (ignore) {
+                    controller.close();
+                    return;
+                }
+                try {
+                    while (true) {
+                        const next = await iterator.next();
+                        if (next.done) {
+                            controller.close();
+                            return;
+                        }
+                        if (next.value.type === "truncated")
+                            throw new Error("Process output was truncated");
+                        if (next.value.type === channel) {
+                            controller.enqueue(next.value.data);
+                            return;
+                        }
+                    }
+                }
+                catch (error) {
+                    controller.error(error);
+                }
+            },
+            async cancel() {
+                await iterator.return(undefined);
+            },
+        });
+    }
+    async readBytes() {
+        const reader = this.getReader();
+        const chunks = [];
+        let size = 0;
+        try {
+            while (true) {
+                const next = await reader.read();
+                if (next.done)
+                    break;
+                const bytes = typeof next.value === "string" ? new TextEncoder().encode(next.value) : next.value;
+                chunks.push(bytes);
+                size += bytes.length;
+            }
+        }
+        finally {
+            reader.releaseLock();
+        }
+        const output = new Uint8Array(size);
+        let offset = 0;
+        for (const chunk of chunks) {
+            output.set(chunk, offset);
+            offset += chunk.length;
+        }
+        return output;
+    }
+    async readText() {
+        return new TextDecoder().decode(await this.readBytes());
+    }
+}
+export class ModalWriteStream extends WritableStream {
+    process;
+    constructor(process) {
+        super({ write: (data) => process.write(data), close: () => process.write("", { eof: true }) });
+        this.process = process;
+    }
+    async writeText(text) {
+        const writer = this.getWriter();
+        try {
+            await writer.write(text);
+        }
+        finally {
+            writer.releaseLock();
+        }
+    }
+    async writeBytes(bytes) {
+        const writer = this.getWriter();
+        try {
+            await writer.write(bytes);
+        }
+        finally {
+            writer.releaseLock();
+        }
+    }
+}
+export class ContainerProcess {
+    native;
+    stdin;
+    stdout;
+    stderr;
+    constructor(native, mode, params = {}) {
+        this.native = native;
+        this.stdin = new ModalWriteStream(native);
+        this.stdout = new ModalReadStream(native, "stdout", mode, params.stdout === "ignore");
+        this.stderr = new ModalReadStream(native, "stderr", mode, params.stderr === "ignore");
+    }
+    async wait() {
+        const r = await this.native.wait();
+        if (r.timedOut)
+            throw new SandboxTimeoutError("Process timed out");
+        return r.exitCode ?? -1;
+    }
+    closeStdin() {
+        return this.native.write("", { eof: true });
+    }
+    async _poll() {
+        const p = await this.native.refresh();
+        return p.state === "running" ? null : p.exitCode;
+    }
+}
+export class Sandbox {
+    native;
+    primary;
+    filesystem;
+    stdin;
+    stdout;
+    stderr;
+    detached = false;
+    lifecycle;
+    monitorEntrypoint() {
+        this.lifecycle = this.primary.wait().then(async (code) => {
+            await destroy(this.native);
+            return code;
+        });
+        this.lifecycle.catch(() => undefined);
+    }
+    constructor(native, primary) {
+        this.native = native;
+        this.primary = primary;
+        this.filesystem = new SandboxFilesystem(native);
+        this.stdin = primary.stdin;
+        this.stdout = primary.stdout;
+        this.stderr = primary.stderr;
+    }
+    get sandboxId() {
+        return this.native.id;
+    }
+    async exec(command, params = {}) {
+        if (this.detached)
+            throw new Error("Sandbox is detached");
+        only("Modal exec", params, [
+            "mode",
+            "stdout",
+            "stderr",
+            "workdir",
+            "timeoutMs",
+            "env",
+            "pty",
+            "secrets",
+        ]);
+        const p = await this.native.spawn(command, {
+            ...(await execOptions(this.native, {
+                cwd: params.workdir,
+                timeoutMs: params.timeoutMs === 0 ? 86_400_000 : params.timeoutMs,
+                env: Object.assign({}, ...(params.secrets?.map((s) => s.values) ?? []), params.env ?? {}),
+            })),
+            stdin: "pipe",
+            ...(params.mode === "binary" ? { outputEncoding: "base64" } : {}),
+            pty: params.pty ? {} : undefined,
+        });
+        return new ContainerProcess(p, params.mode ?? "text", params);
+    }
+    async setTags(tags) {
+        if (this.detached)
+            throw new Error("Sandbox is detached");
+        await this.native.update({
+            labels: {
+                ...Object.fromEntries(Object.entries(this.native.info.labels).filter(([k]) => k.startsWith("modal.") || k === "compat.provider")),
+                "modal.tags": JSON.stringify(tags),
+            },
+        });
+    }
+    async getTags() {
+        if (this.detached)
+            throw new Error("Sandbox is detached");
+        await this.native.refresh();
+        return JSON.parse(this.native.info.labels["modal.tags"] ?? "{}");
+    }
+    async terminate(params = {}) {
+        await destroy(this.native);
+        return params.wait ? this.primary.wait() : undefined;
+    }
+    detach() {
+        this.detached = true;
+    }
+    async wait() {
+        if (this.lifecycle)
+            return this.lifecycle;
+        const code = await this.primary.wait();
+        await destroy(this.native);
+        return code;
+    }
+    poll() {
+        return this.primary._poll();
+    }
+    async tunnels() {
+        return Object.fromEntries((await this.native.previews.list()).map((p) => [
+            p.port,
+            { host: new URL(p.url).hostname, port: 443, url: p.urlWithToken ?? p.url },
+        ]));
+    }
+    async updateNetworkPolicy(params) {
+        await this.native.network.set({
+            internet: true,
+            allow: [...params.outboundCidrAllowlist, ...params.outboundDomainAllowlist],
+        });
+    }
+    async experimentalSnapshot() {
+        const snapshot = await this.native.snapshot();
+        return { sandboxSnapshotId: snapshot.id };
+    }
+}
+export class SandboxFilesystem {
+    native;
+    files;
+    constructor(native) {
+        this.native = native;
+        this.files = new GuestFiles(async () => native, "/");
+    }
+    readBytes(path) {
+        return this.files.readFile(path);
+    }
+    readText(path) {
+        return this.files.readTextFile(path);
+    }
+    writeBytes(content, path) {
+        return this.files.writeFile(path, content instanceof Uint8Array ? content : new Uint8Array(content));
+    }
+    writeText(content, path) {
+        return this.files.writeTextFile(path, content);
+    }
+    makeDirectory(path, options = {}) {
+        return this.files.mkdir(path, options.createParents ?? true);
+    }
+    remove(path, options = {}) {
+        return this.files.remove(path, options.recursive);
+    }
+    copyFromLocal(localPath, remotePath) {
+        return this.native.files.upload(localPath, remotePath);
+    }
+    copyToLocal(remotePath, localPath) {
+        return this.native.files.download(remotePath, localPath);
+    }
+    async listFiles(path) {
+        return Promise.all((await this.files.readdir(path))
+            .sort((a, b) => a.name.localeCompare(b.name))
+            .map((e) => this.stat(e.path)));
+    }
+    async stat(path) {
+        const e = await this.files.stat(path);
+        const r = await this.native.exec(["stat", "-c", "%U:%G", "--", this.files.path(path)], {
+            check: true,
+        });
+        const [owner, group] = r.stdout.trim().split(":");
+        return {
+            name: e.name,
+            path: e.path,
+            type: e.type,
+            size: e.size,
+            mode: parseInt(e.mode, 8),
+            permissions: e.mode,
+            owner: owner,
+            group: group,
+            modifiedTime: Date.parse(e.modifiedAt) / 1000,
+            symlinkTarget: e.type === "symlink"
+                ? (await this.native.exec(["readlink", "--", this.files.path(path)], { check: true })).stdout.trimEnd()
+                : null,
+        };
+    }
+}

package/dist/network-cli.js

@@ -1,4 +1,7 @@
-import { chmod, writeFile } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { lstat, open, rename, unlink } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
 import { RuntimeError } from "./errors.js";
 import { named } from "./cli-name.js";
 import { generateWireGuardKeyPair } from "./wireguard.js";
@@ -30,7 +33,7 @@ export const NETWORK_HELP = {
                                          Redis, a game server, anything that is not HTTP
                                          Prints address:port for your client
   ls [--sandbox <id>]                    Your open ports
-  close <portId>                         Close one; open connections end within seconds
+  close <portId>                         Close one, its open connections too
   Paid accounts only. TCP, carried as it is: use your service's own password and TLS.
 `,
     address: `runtime address <command>
@@ -92,15 +95,63 @@ function portNumber(product, text) {
         throw usage(product, "Give a port from 1 to 65535.");
     return value;
 }
+/** A fresh private inode prevents disclosure through permissive files, symlinks
+ * and hard links. Rename publishes complete contents without a readable window. */
+async function privateOutput(path, text) {
+    const temporary = join(dirname(path), `.${basename(path)}.${randomUUID()}.tmp`);
+    try {
+        const handle = await open(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | (constants.O_NOFOLLOW ?? 0), 0o600);
+        try {
+            await handle.writeFile(text);
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        return temporary;
+    }
+    catch (error) {
+        await unlink(temporary).catch(() => undefined);
+        throw error;
+    }
+}
+/** Check and stage before changing a remote peer. If the request or final write
+ * fails, this private draft preserves the newly generated key for recovery. */
+async function prepareOutput(path, privateKey) {
+    try {
+        const info = await lstat(path);
+        if (!info.isFile() || info.isSymbolicLink())
+            throw usage("tunnel", "The output must be a regular file, not a directory or symbolic link.");
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    const recovery = await privateOutput(path, `# DRAFT: request or output incomplete. Keep this file for recovery.\n[Interface]\nPrivateKey = ${privateKey ?? "<your private key>"}\n`);
+    return {
+        recovery,
+        async publish(config) {
+            const temporary = await privateOutput(path, config);
+            try {
+                await rename(temporary, path);
+            }
+            finally {
+                await unlink(temporary).catch(() => undefined);
+            }
+            await unlink(recovery);
+        },
+    };
+}
 /** Writes a wg-quick file readable by its owner alone, or prints it. */
-async function deliver(out, config, path, hint, ready = true) {
+async function deliver(out, config, path, hint, ready = true, prepared) {
     if (!config) {
         out.error(hint);
         return;
     }
     if (path) {
-        await writeFile(path, config, { mode: 0o600 });
-        await chmod(path, 0o600);
+        if (!prepared)
+            throw new Error("Tunnel output was not prepared.");
+        await prepared.publish(config);
         out.error(ready
             ? `Wrote ${path}. Bring it up with: sudo wg-quick up ${path.startsWith("/") ? path : `./${path}`}`
             : `Wrote ${path}. ${hint}`);
@@ -276,52 +327,69 @@ export async function networkProductCommand(product, argv, args, out, client) {
             case "peers": {
                 const action = rest[0];
                 if (action === "add" || action === "rotate") {
+                    const argument = need(rest[1], action === "add" ? "the peer's name, such as office" : "a peer id");
                     // The pair is made here unless a key is given: the private key never
                     // leaves this machine, and goes only into the file written below.
                     const given = flag("public-key");
                     const pair = given ? undefined : generateWireGuardKeyPair();
                     const publicKey = given ?? pair.publicKey;
-                    const answer = action === "add"
-                        ? await runtime.tunnel.addPeer({
-                            name: need(rest[1], "the peer's name, such as office"),
-                            publicKey,
-                            routes: args.flags.get("route") ?? [],
-                        })
-                        : await runtime.tunnel.rotatePeer(need(rest[1], "a peer id"), { publicKey });
-                    const configReady = answer.configReady ?? !!answer.config;
-                    const draftHint = "Keep this file: it preserves your private key. Read runtime tunnel get when the gateway is ready, replace PublicKey in [Peer] with gatewayPublicKey, then run wg-quick up.";
-                    // Older servers returned no config while the gateway was starting.
-                    // Preserve the locally generated key in a draft rather than discard it.
-                    const supplied = answer.config ??
-                        [
-                            "# DRAFT: gateway key missing. Keep this file; it preserves your private key.",
-                            "[Interface]",
-                            `PrivateKey = ${pair?.privateKey ?? "<your private key>"}`,
-                            `Address = ${answer.peer.address}/32`,
-                            "",
-                            "[Peer]",
-                            `PublicKey = ${answer.tunnel.gatewayPublicKey ?? "<gatewayPublicKey from runtime tunnel get>"}`,
-                            `Endpoint = ${answer.tunnel.endpoint}`,
-                            `AllowedIPs = ${answer.tunnel.subnet}`,
-                            "PersistentKeepalive = 25",
-                            "",
-                        ].join("\n");
-                    const config = pair
-                        ? supplied.replace(/^PrivateKey = .*$/m, `PrivateKey = ${pair.privateKey}`)
-                        : supplied;
-                    if (out.json) {
-                        print("", {
-                            ...answer,
-                            config,
-                            configReady,
-                            ...(!configReady ? { hint: draftHint } : {}),
-                        });
+                    const path = out.json ? undefined : (flag("out") ?? (pair ? "runtime.conf" : undefined));
+                    const prepared = path ? await prepareOutput(path, pair?.privateKey) : undefined;
+                    try {
+                        const answer = action === "add"
+                            ? await runtime.tunnel.addPeer({
+                                name: argument,
+                                publicKey,
+                                routes: args.flags.get("route") ?? [],
+                            })
+                            : await runtime.tunnel.rotatePeer(argument, { publicKey });
+                        const configReady = answer.configReady ?? !!answer.config;
+                        const draftHint = "Keep this file: it preserves your private key. Read runtime tunnel get when the gateway is ready, replace PublicKey in [Peer] with gatewayPublicKey, then run wg-quick up.";
+                        // Older servers returned no config while the gateway was starting.
+                        // Preserve the locally generated key in a draft rather than discard it.
+                        const supplied = answer.config ??
+                            [
+                                "# DRAFT: gateway key missing. Keep this file; it preserves your private key.",
+                                "[Interface]",
+                                `PrivateKey = ${pair?.privateKey ?? "<your private key>"}`,
+                                `Address = ${answer.peer.address}/32`,
+                                "",
+                                "[Peer]",
+                                `PublicKey = ${answer.tunnel.gatewayPublicKey ?? "<gatewayPublicKey from runtime tunnel get>"}`,
+                                `Endpoint = ${answer.tunnel.endpoint}`,
+                                `AllowedIPs = ${answer.tunnel.subnet}`,
+                                "PersistentKeepalive = 25",
+                                "",
+                            ].join("\n");
+                        const privateKeyRow = /^[ \t]*PrivateKey[ \t]*=[^\r\n]*$/gm;
+                        if (pair && (supplied.match(privateKeyRow)?.length ?? 0) !== 1)
+                            throw new RuntimeError({
+                                code: "invalid_response",
+                                status: 0,
+                                message: "Runtime returned a tunnel configuration without exactly one private-key field.",
+                            });
+                        const config = pair
+                            ? supplied.replace(privateKeyRow, `PrivateKey = ${pair.privateKey}`)
+                            : supplied;
+                        if (out.json) {
+                            print("", {
+                                ...answer,
+                                config,
+                                configReady,
+                                ...(!configReady ? { hint: draftHint } : {}),
+                            });
+                            return 0;
+                        }
+                        if (answer.tunnel.funded === false)
+                            out.error(fundingState(answer.tunnel));
+                        await deliver(out, config, path, configReady ? answer.hint : draftHint, configReady, prepared);
                         return 0;
                     }
-                    if (answer.tunnel.funded === false)
-                        out.error(fundingState(answer.tunnel));
-                    await deliver(out, config, flag("out") ?? (pair ? "runtime.conf" : undefined), configReady ? answer.hint : draftHint, configReady);
-                    return 0;
+                    catch (error) {
+                        if (prepared)
+                            out.error(`The peer request or output did not finish. Your private draft is saved at ${prepared.recovery}; keep it for recovery.`);
+                        throw error;
+                    }
                 }
                 if (action === "rm" || action === "remove") {
                     const after = await runtime.tunnel.removePeer(need(rest[1], "a peer id"));