@alchemy.run/modal 0.0.0 → 2.0.0-beta.87

package/lib/SandboxClient.js

@@ -0,0 +1,710 @@
+import * as persistent from "@distilled.cloud/modal/persistent";
+import * as sandbox from "@distilled.cloud/modal/sandbox";
+import * as router from "@distilled.cloud/modal/task_command_router";
+import * as Sandbox from "alchemy/Sandbox";
+import * as SecureRandom from "effect/crypto/SecureRandom";
+import * as Data from "effect/Data";
+import * as DateTime from "effect/DateTime";
+import * as Effect from "effect/Effect";
+import * as HttpClient from "effect/http/HttpClient";
+import * as HttpClientRequest from "effect/http/HttpClientRequest";
+import * as Schedule from "effect/Schedule";
+import * as Stream from "effect/Stream";
+import { buildImage, gpuConfig, ImageBuildOps } from "./ImageBuild.js";
+import { environmentOf, operations, seconds } from "./internal.js";
+import { connectTcp } from "./internal/TcpConnect.js";
+import { streamRouter, withRouter } from "./ModalBindings.js";
+import { modalMountsOf } from "./Mounts.js";
+/** A sandbox ended (or never became ready) before the call could finish. */
+export class SandboxNotRunning extends Data.TaggedError("Modal.SandboxNotRunning") {
+}
+/** A Modal call returned without the field the client needs. */
+export class SandboxUnexpectedResponse extends Data.TaggedError("Modal.SandboxUnexpectedResponse") {
+}
+/** A filesystem operation inside the sandbox failed (missing path, permissions). */
+export class SandboxFilesystemError extends Data.TaggedError("Modal.SandboxFilesystemError") {
+}
+/** Modal's task command router has no call to resize a running PTY. */
+export class SandboxPtyResizeUnsupported extends Data.TaggedError("Modal.SandboxPtyResizeUnsupported") {
+}
+/** The text of a command's output stream, from its router read chunks. */
+const streamText = (chunks) => Buffer.concat(chunks.map((chunk) => Buffer.from(chunk.data ?? "", "base64"))).toString("utf8");
+const decodeBase64 = (data) => Effect.sync(() => new Uint8Array(Buffer.from(data, "base64")));
+const encodeBase64 = (data) => Effect.sync(() => typeof data === "string"
+    ? Buffer.from(data, "utf8").toString("base64")
+    : Buffer.from(data).toString("base64"));
+const tunnelTypeOf = (h2) => h2 ? "TUNNEL_TYPE_H2" : undefined;
+/** Modal's `Sandbox` definition for {@link SandboxCreateOptions}. */
+const definitionOf = (imageId, options, mounts) => ({
+    imageId,
+    entrypointArgs: options.command ? [...options.command] : ["sleep", "infinity"],
+    workdir: options.workdir,
+    environmentVariables: options.env,
+    secretIds: options.secrets?.map((s) => s.secretId),
+    volumeMounts: mounts.volumeMounts,
+    cloudBucketMounts: mounts.cloudBucketMounts,
+    resources: {
+        milliCpu: options.cpu !== undefined ? Math.round(options.cpu * 1000) : undefined,
+        memoryMb: options.memory,
+        gpuConfig: gpuConfig(options.gpu),
+        ephemeralDiskMb: options.ephemeralDisk,
+    },
+    timeoutSecs: seconds(options.timeout),
+    idleTimeoutSecs: seconds(options.idleTimeout),
+    name: options.name,
+    schedulerPlacement: options.regions ? { regions: [...options.regions] } : undefined,
+    blockNetwork: options.blockNetwork,
+    networkAccess: networkAccessOf(options),
+    inboundCidrAllowlist: options.inboundCidrAllowlist
+        ? [...options.inboundCidrAllowlist]
+        : undefined,
+    outboundPolicy: options.outboundPolicy ? outboundPolicyOf(options.outboundPolicy) : undefined,
+    proxyId: options.proxy?.proxyId,
+    includeOidcIdentityToken: options.includeOidcIdentityToken,
+    includeX509Svid: options.includeX509Svid,
+    openPorts: {
+        ports: [
+            ...(options.encryptedPorts ?? []).map((port) => ({ port })),
+            ...(options.unencryptedPorts ?? []).map((port) => ({ port, unencrypted: true })),
+            ...(options.h2Ports ?? []).map((port) => ({ port, tunnelType: tunnelTypeOf(true) })),
+        ],
+    },
+    enableSnapshot: options.enableSnapshot,
+    customDomain: options.customDomain,
+});
+const networkAccessOf = (options) => options.blockNetwork
+    ? { networkAccessType: "BLOCKED" }
+    : options.cidrAllowlist !== undefined || options.allowedDomains !== undefined
+        ? {
+            networkAccessType: "ALLOWLIST",
+            allowedCidrs: options.cidrAllowlist ? [...options.cidrAllowlist] : [],
+            allowedDomains: options.allowedDomains ? [...options.allowedDomains] : [],
+        }
+        : undefined;
+/**
+ * The policy for a sandbox that is already running. Modal's task router
+ * accepts only an allow-list here: an empty one blocks everything, and
+ * `0.0.0.0/0` opens the network.
+ */
+const runningNetworkAccessOf = (access) => {
+    const open = access.cidrAllowlist === undefined && access.allowedDomains === undefined;
+    return {
+        networkAccessType: "ALLOWLIST",
+        allowedCidrs: access.blockNetwork
+            ? []
+            : open
+                ? ["0.0.0.0/0"]
+                : [...(access.cidrAllowlist ?? [])],
+        allowedDomains: access.blockNetwork ? [] : [...(access.allowedDomains ?? [])],
+    };
+};
+const portsOf = (ports) => ports?.map((port) => (typeof port === "number" ? { start: port, end: port } : port));
+const transportOf = (transport) => transport === undefined ? undefined : `TRANSPORT_${transport.toUpperCase()}`;
+const redirectOf = (redirect) => redirect === undefined
+    ? undefined
+    : redirect === "block"
+        ? { block: {} }
+        : "proxy" in redirect
+            ? { viaProxy: { proxyId: redirect.proxy.proxyId } }
+            : { viaSidecar: { sidecarName: redirect.sidecar } };
+const outboundPolicyOf = (policy) => ({
+    tlsDecryption: {
+        allowed: policy.tlsDecryption ?? policy.routes.some((route) => "https" in route),
+    },
+    routes: policy.routes.map((route) => {
+        if ("ip" in route) {
+            return {
+                ip: {
+                    cidrs: [...route.ip.cidrs],
+                    ports: portsOf(route.ip.ports),
+                    transport: transportOf(route.ip.transport),
+                    redirect: redirectOf(route.ip.redirect),
+                },
+            };
+        }
+        if ("tls" in route) {
+            return {
+                tls: {
+                    domains: [...route.tls.domains],
+                    ports: portsOf(route.tls.ports),
+                    redirect: redirectOf(route.tls.redirect),
+                },
+            };
+        }
+        if ("https" in route) {
+            return {
+                https: {
+                    domains: [...route.https.domains],
+                    ports: portsOf(route.https.ports),
+                    headerReplacements: route.https.headerReplacements?.map((r) => ({
+                        secretId: r.secret?.secretId,
+                        headers: r.headers,
+                    })),
+                    redirect: redirectOf(route.https.redirect),
+                },
+            };
+        }
+        return { any: { redirect: redirectOf(route.any.redirect) } };
+    }),
+});
+/**
+ * The operations sandbox clients call, resolved once by
+ * `ModalBindings.withCredentials` (or at deploy, with the deployer's).
+ */
+export const SandboxOps = operations({
+    create: sandbox.sandboxCreateV2,
+    getFromName: sandbox.sandboxGetFromNameV2,
+    list: sandbox.sandboxListV2,
+    restore: sandbox.sandboxRestoreV2,
+    getTaskId: sandbox.sandboxGetTaskIdV2,
+    getCommandRouterAccess: sandbox.sandboxGetCommandRouterAccess,
+    getTunnels: sandbox.sandboxGetTunnelsV2,
+    createConnectToken: sandbox.sandboxCreateConnectTokenV2,
+    setOutboundPolicy: sandbox.sandboxSetOutboundPolicyV2,
+    setTags: sandbox.sandboxTagsSetV2,
+    getTags: sandbox.sandboxTagsGetV2,
+    setName: sandbox.sandboxSetName,
+    getResourceUsage: sandbox.sandboxGetResourceUsage,
+    wait: sandbox.sandboxWaitV2,
+    terminate: sandbox.sandboxTerminateV2,
+    usage: sandbox.sandboxGetTimeRangeStats,
+    createPersistent: persistent.createPersistentSandbox,
+    getPersistent: persistent.getPersistentSandbox,
+    resumePersistent: persistent.resumePersistentSandbox,
+    terminatePersistent: persistent.terminatePersistentSandbox,
+    images: ImageBuildOps,
+    http: HttpClient.HttpClient,
+});
+/** Task command router operations, resolved per sandbox with its router access. */
+const routerOps = {
+    execStart: withRouter(router.taskExecStart),
+    execStdinWrite: withRouter(router.taskExecStdinWrite),
+    execStdioRead: withRouter(router.taskExecStdioRead),
+    execWait: withRouter(router.taskExecWait),
+    // A running command's output, each chunk as the router sends it; the
+    // stream ends when the command closes the descriptor.
+    execStdioFollow: streamRouter(router.taskExecStdioRead),
+    snapshotFilesystem: withRouter(router.taskSnapshotFilesystem),
+    snapshotMemory: withRouter(router.taskSnapshotMemory),
+    snapshotDirectory: withRouter(router.taskSnapshotDirectory),
+    mountDirectory: withRouter(router.taskMountDirectory),
+    setNetworkAccess: withRouter(router.taskSetNetworkAccess),
+    // The sandbox's own program's output (V2 sandboxes serve it here, not
+    // through the control plane's sandboxGetLogs).
+    mainStdio: streamRouter(router.sandboxStdioReadV2),
+};
+/**
+ * The image to boot: a `Modal.Image`'s id, or a registry ref built (and
+ * cached by Modal) into an image in the target app.
+ */
+export const resolveSandboxImage = Effect.fn(function* (ops, target, image) {
+    if (image !== undefined && typeof image !== "string")
+        return image.imageId;
+    if (image === undefined && target.imageId !== undefined)
+        return target.imageId;
+    const spec = { dockerTag: image ?? "debian:bookworm-slim", commands: [] };
+    return yield* buildImage(ops.images, target.appId, spec);
+});
+/** The handle for an existing sandbox id. */
+export const sandboxHandle = (ops, sandboxId, target) => {
+    let cachedTaskId;
+    const taskId = Effect.gen(function* () {
+        if (cachedTaskId !== undefined)
+            return cachedTaskId;
+        for (let attempt = 0; attempt < 10; attempt++) {
+            const response = yield* ops.getTaskId({
+                sandboxId,
+                timeout: 55,
+                waitUntilReady: true,
+            });
+            if (response.taskId) {
+                cachedTaskId = response.taskId;
+                return response.taskId;
+            }
+            if (response.taskResult?.status &&
+                response.taskResult.status !== "GENERIC_STATUS_UNSPECIFIED") {
+                return yield* new SandboxNotRunning({
+                    sandboxId,
+                    message: `Sandbox ${sandboxId} finished with ${response.taskResult.status}`,
+                });
+            }
+        }
+        return yield* new SandboxNotRunning({
+            sandboxId,
+            message: `Sandbox ${sandboxId} wasn't scheduled within 9 minutes`,
+        });
+    });
+    const viaRouter = (resolve, f) => Effect.gen(function* () {
+        const id = yield* taskId;
+        const access = yield* ops.getCommandRouterAccess({ taskId: id });
+        if (!access.url || !access.jwt) {
+            return yield* new SandboxUnexpectedResponse({
+                message: `Modal returned no command router for sandbox ${sandboxId}`,
+            });
+        }
+        const op = yield* resolve({ url: access.url, jwt: access.jwt });
+        return yield* f(op, id);
+    });
+    /**
+     * Run a filesystem command with `sh` (every image Modal boots has one) and
+     * fail with {@link SandboxFilesystemError} on a non-zero exit.
+     */
+    const fsExec = (path, script, stdin) => Effect.flatMap(exec(["sh", "-c", script, "sh", path], stdin === undefined ? {} : { stdin }), (result) => result.exitCode === 0
+        ? Effect.succeed(result.stdout)
+        : Effect.fail(new SandboxFilesystemError({
+            path,
+            message: result.stderr.trim() || `exit code ${result.exitCode}`,
+        })));
+    const exec = Effect.fn(function* (command, options = {}) {
+        // V2 sandboxes run commands through the task command router: start the
+        // command under an id we choose, then read its output streams while
+        // waiting for it to exit.
+        const id = yield* taskId;
+        const access = yield* ops.getCommandRouterAccess({ taskId: id });
+        if (!access.url || !access.jwt) {
+            return yield* new SandboxUnexpectedResponse({
+                message: `Modal returned no command router for sandbox ${sandboxId}`,
+            });
+        }
+        const at = { url: access.url, jwt: access.jwt };
+        const start = yield* routerOps.execStart(at);
+        const stdinWrite = yield* routerOps.execStdinWrite(at);
+        const stdioRead = yield* routerOps.execStdioRead(at);
+        const wait = yield* routerOps.execWait(at);
+        const execId = yield* Effect.sync(() => SecureRandom.uuidV4Unsafe());
+        yield* start({
+            taskId: id,
+            execId,
+            commandArgs: typeof command === "string" ? ["sh", "-c", command] : [...command],
+            workdir: options.cwd,
+            timeoutSecs: seconds(options.timeout),
+            secretIds: options.secrets?.map((s) => s.secretId),
+            env: options.env,
+            stdoutConfig: "TASK_EXEC_STDOUT_CONFIG_PIPE",
+            stderrConfig: "TASK_EXEC_STDERR_CONFIG_PIPE",
+        });
+        if (options.stdin !== undefined) {
+            yield* stdinWrite({
+                taskId: id,
+                execId,
+                offset: "0",
+                data: yield* encodeBase64(options.stdin),
+                eof: true,
+            });
+        }
+        const read = (fileDescriptor) => stdioRead({ taskId: id, execId, offset: "0", fileDescriptor }).pipe(Effect.map(({ items }) => streamText(items)));
+        const [stdout, stderr, exit] = yield* Effect.all([
+            read("TASK_EXEC_STDIO_FILE_DESCRIPTOR_STDOUT"),
+            read("TASK_EXEC_STDIO_FILE_DESCRIPTOR_STDERR"),
+            wait({ taskId: id, execId }),
+        ], { concurrency: "unbounded" });
+        return {
+            exitCode: exit.code ?? (exit.signal !== undefined ? 128 + exit.signal : -1),
+            stdout,
+            stderr,
+        };
+    });
+    /** The task and its router access, for the router calls of one command. */
+    const routerAccess = Effect.gen(function* () {
+        const id = yield* taskId;
+        const access = yield* ops.getCommandRouterAccess({ taskId: id });
+        if (!access.url || !access.jwt) {
+            return yield* new SandboxUnexpectedResponse({
+                message: `Modal returned no command router for sandbox ${sandboxId}`,
+            });
+        }
+        return { taskId: id, at: { url: access.url, jwt: access.jwt } };
+    });
+    /**
+     * Start a command (on a PTY with `pty`) and return how to follow it: a
+     * stream per output, stdin writes from a running offset, and its exit.
+     */
+    const startExec = Effect.fn(function* (commandArgs, options, pty) {
+        const { taskId: id, at } = yield* routerAccess;
+        const begin = yield* routerOps.execStart(at);
+        const stdinWrite = yield* routerOps.execStdinWrite(at);
+        const follow = yield* routerOps.execStdioFollow(at);
+        const wait = yield* routerOps.execWait(at);
+        const execId = yield* Effect.sync(() => SecureRandom.uuidV4Unsafe());
+        yield* begin({
+            taskId: id,
+            execId,
+            commandArgs: [...commandArgs],
+            workdir: options.cwd,
+            timeoutSecs: seconds(options.timeout),
+            secretIds: options.secrets?.map((s) => s.secretId),
+            env: options.env,
+            stdoutConfig: "TASK_EXEC_STDOUT_CONFIG_PIPE",
+            stderrConfig: pty ? undefined : "TASK_EXEC_STDERR_CONFIG_PIPE",
+            ptyInfo: pty,
+        });
+        let stdinOffset = 0;
+        const write = (data, eof = false) => Effect.gen(function* () {
+            const bytes = typeof data === "string" ? new TextEncoder().encode(data) : data;
+            const offset = stdinOffset;
+            stdinOffset += bytes.length;
+            yield* stdinWrite({
+                taskId: id,
+                execId,
+                offset: String(offset),
+                data: yield* encodeBase64(bytes),
+                eof,
+            });
+        });
+        /** One output of the command, each chunk as it arrives. */
+        const output = (fileDescriptor) => follow({ taskId: id, execId, offset: "0", fileDescriptor }).pipe(Stream.map((item) => new Uint8Array(Buffer.from(item.data, "base64"))), Stream.filter((bytes) => bytes.length > 0));
+        if (options.stdin !== undefined)
+            yield* write(options.stdin, true);
+        return {
+            execId,
+            write,
+            output,
+            wait: Effect.map(wait({ taskId: id, execId }), (exit) => ({
+                exitCode: exit.code ?? (exit.signal !== undefined ? 128 + exit.signal : -1),
+            })),
+        };
+    });
+    const argvOf = (command) => typeof command === "string" ? ["sh", "-c", command] : command;
+    const start = (command, options = {}) => Effect.gen(function* () {
+        // The router has no signal call: the command records its pid, and
+        // `kill` signals it with a second command.
+        const pidFile = `/tmp/.alchemy-exec-${yield* Effect.sync(() => SecureRandom.uuidV4Unsafe())}.pid`;
+        const running = yield* startExec(["sh", "-c", 'echo $$ > "$0"; exec "$@"', pidFile, ...argvOf(command)], options);
+        return {
+            id: running.execId,
+            output: Stream.merge(Stream.map(running.output("TASK_EXEC_STDIO_FILE_DESCRIPTOR_STDOUT"), (data) => ({
+                fd: "stdout",
+                data,
+            })), Stream.map(running.output("TASK_EXEC_STDIO_FILE_DESCRIPTOR_STDERR"), (data) => ({
+                fd: "stderr",
+                data,
+            }))),
+            write: (data) => running.write(data),
+            kill: (signal = "SIGTERM") => Effect.asVoid(exec(["sh", "-c", `kill -s ${signal.slice(3)} "$(cat "$0")"`, pidFile])),
+            wait: running.wait,
+        };
+    });
+    const pty = {
+        open: (options) => Effect.gen(function* () {
+            const running = yield* startExec(options.command
+                ? ["sh", "-c", options.command]
+                : ["sh", "-c", "exec bash -l 2>/dev/null || exec sh -l"], { cwd: options.cwd, env: options.env, secrets: options.secrets }, {
+                enabled: true,
+                winszRows: options.rows,
+                winszCols: options.cols,
+                envTerm: "xterm-256color",
+                ptyType: "PTY_TYPE_SHELL",
+                noTerminateOnIdleStdin: true,
+            });
+            return {
+                id: running.execId,
+                output: running.output("TASK_EXEC_STDIO_FILE_DESCRIPTOR_STDOUT"),
+                write: (data) => running.write(data),
+                resize: () => Effect.fail(new SandboxPtyResizeUnsupported({
+                    message: "Modal's task command router can't resize a running PTY",
+                })),
+            };
+        }),
+    };
+    const read = Effect.fn(function* (path) {
+        // base64 keeps binary content intact through the text output stream.
+        const encoded = yield* fsExec(path, 'base64 < "$1" | tr -d "\\n"');
+        return yield* decodeBase64(encoded);
+    });
+    const typeOf = (letter) => letter === "d" ? "directory" : letter === "l" ? "symlink" : letter === "f" ? "file" : "other";
+    const files = {
+        read,
+        readText: (path) => read(path).pipe(Effect.map((bytes) => new TextDecoder().decode(bytes))),
+        write: Effect.fn(function* (path, data) {
+            const encoded = yield* encodeBase64(data);
+            yield* fsExec(path, 'mkdir -p "$(dirname "$1")" && base64 -d > "$1"', encoded);
+        }),
+        list: Effect.fn(function* (path) {
+            const output = yield* fsExec(path, 'cd "$1" && for f in * .[!.]* ..?*; do [ -e "$f" ] || [ -L "$f" ] || continue; if [ -L "$f" ]; then echo "l $f"; elif [ -d "$f" ]; then echo "d $f"; elif [ -f "$f" ]; then echo "f $f"; else echo "o $f"; fi; done');
+            return output
+                .split("\n")
+                .filter((line) => line.length > 2)
+                .map((line) => ({
+                path: `${path.replace(/\/$/, "")}/${line.slice(2)}`,
+                type: typeOf(line[0]),
+            }));
+        }),
+        stat: Effect.fn(function* (path) {
+            // `%F` is GNU stat's type name; busybox prints the same names.
+            const output = yield* fsExec(path, 'stat -c "%F|%s|%Y" "$1"');
+            const [kind = "", size = "0", mtime = "0"] = output.trim().split("|");
+            return {
+                path,
+                type: kind.includes("directory")
+                    ? "directory"
+                    : kind.includes("symbolic link")
+                        ? "symlink"
+                        : kind.includes("regular")
+                            ? "file"
+                            : "other",
+                size: Number(size),
+                modifiedAt: DateTime.makeUnsafe(Number(mtime) * 1000),
+            };
+        }),
+        remove: Effect.fn(function* (path, options = {}) {
+            yield* fsExec(path, options.recursive ? 'rm -r "$1"' : 'rm "$1"');
+        }),
+        makeDir: Effect.fn(function* (path) {
+            yield* fsExec(path, 'mkdir -p "$1"');
+        }),
+    };
+    const tunnelsOf = Effect.fn(function* (timeout) {
+        const { tunnels } = yield* ops.getTunnels({
+            sandboxId,
+            timeout: seconds(timeout) ?? 50,
+        });
+        const out = {};
+        for (const tunnel of tunnels ?? []) {
+            if (tunnel.containerPort === undefined)
+                continue;
+            const encrypted = tunnel.host !== undefined && tunnel.host !== "";
+            const host = (encrypted ? tunnel.host : tunnel.unencryptedHost) ?? "";
+            const port = (encrypted ? tunnel.port : tunnel.unencryptedPort) ?? 443;
+            out[tunnel.containerPort] = {
+                host,
+                port,
+                url: encrypted
+                    ? `https://${host}${port === 443 ? "" : `:${port}`}`
+                    : `tcp://${host}:${port}`,
+            };
+        }
+        return out;
+    });
+    const getTcpPort = Effect.fn(function* (port = target.program?.port) {
+        if (port === undefined) {
+            return yield* new SandboxUnexpectedResponse({
+                message: "getTcpPort needs a port: create the sandbox from a Modal.Sandbox, or pass one",
+            });
+        }
+        const tunnel = (yield* tunnelsOf(50))[port];
+        if (!tunnel) {
+            return yield* new SandboxUnexpectedResponse({
+                message: `Port ${port} of sandbox ${sandboxId} has no tunnel; open it with encryptedPorts`,
+            });
+        }
+        const tls = tunnel.url.startsWith("https:");
+        // An unencrypted tunnel carries plain TCP, so HTTP to it is cleartext.
+        const origin = tls ? tunnel.url : `http://${tunnel.host}:${tunnel.port}`;
+        const sandboxPort = {
+            ...tunnel,
+            // The user's own program, reached through its tunnel (allowed raw HTTP).
+            fetch: Sandbox.portFetch((request) => {
+                const url = new URL(request.url, "http://sandbox");
+                // The tunnel routes by host, so a proxied request's own `host` goes.
+                return ops.http.execute(HttpClientRequest.setUrl(HttpClientRequest.removeHeader(request, "host"), `${origin}${url.pathname}${url.search}`));
+            }),
+            connect: () => connectTcp({ host: tunnel.host, port: tunnel.port, tls }),
+        };
+        return sandboxPort;
+    });
+    const handle = {
+        sandboxId,
+        exec,
+        start,
+        pty,
+        files,
+        tunnels: tunnelsOf,
+        connectToken: Effect.fn(function* (options = {}) {
+            const response = yield* ops.createConnectToken({
+                sandboxId,
+                port: options.port,
+                userMetadata: options.userMetadata,
+            });
+            if (!response.url || !response.token) {
+                return yield* new SandboxUnexpectedResponse({ message: "Modal returned no connect token" });
+            }
+            return { url: response.url, token: response.token };
+        }),
+        snapshotFilesystem: (_timeout) => viaRouter(routerOps.snapshotFilesystem, (op, task) => Effect.flatMap(Effect.sync(() => SecureRandom.uuidV4Unsafe()), 
+        // -1: the snapshot image never expires.
+        (snapshotId) => op({ taskId: task, snapshotId, ttlSeconds: "-1" }))).pipe(Effect.flatMap((response) => response.imageId
+            ? Effect.succeed({ imageId: response.imageId })
+            : Effect.fail(new SandboxUnexpectedResponse({
+                message: `Filesystem snapshot of ${sandboxId} returned no image`,
+            })))),
+        snapshotMemory: () => viaRouter(routerOps.snapshotMemory, (op, task) => Effect.flatMap(Effect.sync(() => SecureRandom.uuidV4Unsafe()), (idempotencyKey) => op({ taskId: task, idempotencyKey }))).pipe(Effect.flatMap((response) => response.snapshotId
+            ? Effect.succeed({ snapshotId: response.snapshotId })
+            : Effect.fail(new SandboxUnexpectedResponse({ message: "No snapshot id" })))),
+        snapshotDirectory: (path) => viaRouter(routerOps.snapshotDirectory, (op, task) => op({ taskId: task, path })).pipe(Effect.flatMap((response) => response.imageId
+            ? Effect.succeed({ imageId: response.imageId })
+            : Effect.fail(new SandboxUnexpectedResponse({ message: `No image for ${path}` })))),
+        mountDirectory: (path, snapshot) => viaRouter(routerOps.mountDirectory, (op, task) => op({ taskId: task, path, imageId: snapshot.imageId })).pipe(Effect.asVoid),
+        setNetworkAccess: (access) => viaRouter(routerOps.setNetworkAccess, (op, task) => op({ taskId: task, networkAccess: runningNetworkAccessOf(access) })).pipe(Effect.asVoid),
+        setOutboundPolicy: Effect.fn(function* (policy) {
+            yield* ops.setOutboundPolicy({
+                sandboxId,
+                outboundPolicy: outboundPolicyOf(policy),
+            });
+        }),
+        setTags: Effect.fn(function* (tags) {
+            yield* ops.setTags({
+                sandboxId,
+                environmentName: environmentOf(target.environment),
+                tags: Object.entries(tags).map(([tagName, tagValue]) => ({ tagName, tagValue })),
+            });
+        }),
+        getTags: Effect.fn(function* () {
+            const { tags } = yield* ops.getTags({ sandboxId });
+            return Object.fromEntries((tags ?? []).map((t) => [t.tagName ?? "", t.tagValue ?? ""]));
+        }),
+        setName: Effect.fn(function* (name) {
+            yield* ops.setName({ sandboxId, name });
+        }),
+        resourceUsage: Effect.fn(function* () {
+            const usage = yield* ops.getResourceUsage({ sandboxId });
+            return {
+                cpuSeconds: Number(usage.cpuCoreNanosecs ?? 0) / 1e9,
+                memoryGibSeconds: Number(usage.memGibNanosecs ?? 0) / 1e9,
+                gpuSeconds: Number(usage.gpuNanosecs ?? 0) / 1e9,
+            };
+        }),
+        logs: Effect.fn(function* (options = {}) {
+            const { taskId: id, at } = yield* routerAccess;
+            const read = yield* routerOps.mainStdio(at);
+            const chunks = yield* read({
+                taskId: id,
+                offset: "0",
+                fileDescriptor: "SANDBOX_STDIO_FILE_DESCRIPTOR_STDOUT",
+            }).pipe(Stream.map((item) => Buffer.from(item.data, "base64")), Stream.interruptWhen(Effect.sleep(`${seconds(options.timeout) ?? 5} seconds`)), Stream.runCollect);
+            return Buffer.concat(chunks).toString("utf8");
+        }),
+        wait: Effect.fn(function* (timeout) {
+            const { result } = yield* ops.wait({
+                sandboxId,
+                timeout: seconds(timeout) ?? 0,
+            });
+            return {
+                exitCode: result?.exitcode,
+                status: result?.status ?? "GENERIC_STATUS_UNSPECIFIED",
+            };
+        }),
+        getTcpPort,
+        terminate: Effect.fn(function* () {
+            yield* ops
+                .terminate({ sandboxId })
+                .pipe(Effect.catchTag("SandboxNotFound", () => Effect.void));
+        }),
+    };
+    return handle;
+};
+/**
+ * Create a sandbox in `target`'s app and return its handle. The one
+ * implementation behind `CreateSandbox` and warm-base image builds.
+ */
+export const createSandbox = Effect.fn(function* (ops, target, options = {}) {
+    const imageId = yield* resolveSandboxImage(ops, target, options.image);
+    const program = target.program;
+    const withProgram = program
+        ? {
+            ...options,
+            command: options.command ?? program.command,
+            secrets: [{ secretId: program.secretId }, ...(options.secrets ?? [])],
+            encryptedPorts: [...new Set([program.port, ...(options.encryptedPorts ?? [])])],
+        }
+        : options;
+    const own = yield* modalMountsOf(options.mounts);
+    const mounts = {
+        volumeMounts: [...(program?.mounts?.volumeMounts ?? []), ...own.volumeMounts],
+        cloudBucketMounts: [...(program?.mounts?.cloudBucketMounts ?? []), ...own.cloudBucketMounts],
+    };
+    const created = yield* ops.create({
+        appId: target.appId,
+        definition: definitionOf(imageId, withProgram, mounts),
+        tags: Object.entries(options.tags ?? {}).map(([tagName, tagValue]) => ({ tagName, tagValue })),
+    });
+    if (!created.sandboxId) {
+        return yield* new SandboxUnexpectedResponse({ message: "Modal returned no sandbox id" });
+    }
+    return sandboxHandle(ops, created.sandboxId, target);
+});
+/** A running sandbox of `target`'s app by name, or `undefined`. */
+export const sandboxFromName = Effect.fn(function* (ops, target, name) {
+    const found = yield* ops
+        .getFromName({
+        sandboxName: name,
+        appName: target.appName,
+        environmentName: environmentOf(target.environment),
+    })
+        .pipe(Effect.catchTag("SandboxNotFound", () => Effect.undefined));
+    return found?.sandboxId ? sandboxHandle(ops, found.sandboxId, target) : undefined;
+});
+/** Running sandboxes of `target`'s app, optionally filtered by tags. */
+export const listSandboxes = Effect.fn(function* (ops, target, options = {}) {
+    const { sandboxes } = yield* ops.list({
+        appId: target.appId,
+        environmentName: environmentOf(target.environment),
+        includeFinished: options.includeFinished ?? false,
+        tags: Object.entries(options.tags ?? {}).map(([tagName, tagValue]) => ({ tagName, tagValue })),
+    });
+    return (sandboxes ?? []).flatMap((info) => info.id
+        ? [
+            {
+                sandboxId: info.id,
+                name: info.name || undefined,
+                createdAt: info.createdAt,
+                tags: Object.fromEntries((info.tags ?? []).map((t) => [t.tagName ?? "", t.tagValue ?? ""])),
+            },
+        ]
+        : []);
+});
+/** Restore a memory snapshot into a new sandbox. */
+export const restoreSandbox = Effect.fn(function* (ops, target, snapshot, options = {}) {
+    const restored = yield* ops.restore({
+        snapshotId: snapshot.snapshotId,
+        sandboxNameOverride: options.name,
+        sandboxNameOverrideType: options.name ? "SANDBOX_NAME_OVERRIDE_TYPE_STRING" : undefined,
+    });
+    if (!restored.sandboxId) {
+        return yield* new SandboxUnexpectedResponse({ message: "Modal returned no restored sandbox" });
+    }
+    return sandboxHandle(ops, restored.sandboxId, target);
+});
+/** Modal's session limits for persistent sandboxes. */
+const PERSISTENT_SESSION = { timeout: 60 * 60, idleTimeout: 5 * 60 };
+/** The handle for an existing persistent sandbox id. */
+export const persistentSandboxHandle = (ops, persistentSandboxId, target) => ({
+    persistentSandboxId,
+    session: Effect.fn(function* () {
+        const running = yield* ops.getPersistent({ persistentSandboxId });
+        if (running.sandboxId)
+            return sandboxHandle(ops, running.sandboxId, target);
+        // A paused box resumes from its last session's filesystem. Modal answers
+        // busy while the previous session is still saving it.
+        const resumed = yield* ops.resumePersistent({ persistentSandboxId }).pipe(Effect.retry({
+            while: (error) => error._tag === "PersistentSandboxBusy",
+            schedule: Schedule.spaced("1 second"),
+            times: 60,
+        }));
+        if (!resumed.sandboxId) {
+            return yield* new SandboxUnexpectedResponse({
+                message: `Modal returned no session for persistent sandbox ${persistentSandboxId}`,
+            });
+        }
+        return sandboxHandle(ops, resumed.sandboxId, target);
+    }),
+    terminate: Effect.fn(function* () {
+        yield* ops
+            .terminatePersistent({ persistentSandboxId })
+            .pipe(Effect.catchTag("PersistentSandboxNotFound", () => Effect.void));
+    }),
+});
+/** Create a persistent sandbox in `target`'s app. */
+export const createPersistentSandbox = Effect.fn(function* (ops, target, options = {}) {
+    const imageId = yield* resolveSandboxImage(ops, target, options.image);
+    const created = yield* ops.createPersistent({
+        appId: target.appId,
+        definition: definitionOf(imageId, { ...options, ...PERSISTENT_SESSION }, yield* modalMountsOf(options.mounts)),
+    });
+    if (!created.persistentSandboxId) {
+        return yield* new SandboxUnexpectedResponse({
+            message: "Modal returned no persistent sandbox id",
+        });
+    }
+    return persistentSandboxHandle(ops, created.persistentSandboxId, target);
+});
+//# sourceMappingURL=SandboxClient.js.map