withruntime 0.11.2 → 0.12.0

package/dist/modal/index.js

@@ -1,12 +1,99 @@
-import { all, client, CompatibilityError, create, destroy, execOptions, only, region, } from "../compat/core.js";
+import { ConflictError as NativeConflictError, InvalidRequestError, NotFoundError as NativeNotFoundError, RateLimitError, RuntimeError, ServiceUnavailableError, } from "../errors.js";
+import { all, client, CompatibilityError, create, destroy, execOptions, only, refuse, region, } from "../compat/core.js";
 import { GuestFiles } from "../compat/files.js";
 export { CompatibilityError };
+// Errors ----------------------------------------------------------------------
+export class TimeoutError extends Error {
+}
+export class RemoteError extends Error {
+}
+export class ExecutionError extends Error {
+}
+export class InternalFailure extends Error {
+}
 export class NotFoundError extends Error {
 }
-export class TimeoutError extends Error {
+export class AlreadyExistsError extends Error {
+}
+export class ConflictError extends Error {
+}
+export class InvalidError extends Error {
+}
+export class ResourceExhaustedError extends Error {
 }
 export class SandboxTimeoutError extends TimeoutError {
 }
+export class SnapshotCreationError extends Error {
+}
+export class ClientClosedError extends Error {
+}
+export class SandboxFilesystemError extends Error {
+}
+export class SandboxFilesystemDirectoryNotEmptyError extends SandboxFilesystemError {
+}
+export class SandboxFilesystemFileTooLargeError extends SandboxFilesystemError {
+}
+export class SandboxFilesystemIsADirectoryError extends SandboxFilesystemError {
+}
+export class SandboxFilesystemNotADirectoryError extends SandboxFilesystemError {
+}
+export class SandboxFilesystemNotFoundError extends SandboxFilesystemError {
+}
+export class SandboxFilesystemPathAlreadyExistsError extends SandboxFilesystemError {
+}
+export class SandboxFilesystemPermissionError extends SandboxFilesystemError {
+}
+/** A Runtime failure as the Modal error a caller catches. */
+function modalError(error) {
+    if (!(error instanceof RuntimeError))
+        return error;
+    if (error.code === "name_taken")
+        return new AlreadyExistsError(error.message);
+    if (error instanceof NativeNotFoundError)
+        return new NotFoundError(error.message);
+    if (error instanceof NativeConflictError)
+        return new ConflictError(error.message);
+    if (error instanceof InvalidRequestError)
+        return new InvalidError(error.message);
+    if (error instanceof RateLimitError || error.code === "quota_exceeded")
+        return new ResourceExhaustedError(error.message);
+    if (error instanceof ServiceUnavailableError || error.status >= 500)
+        return new InternalFailure(error.message);
+    return error;
+}
+async function modal(run) {
+    try {
+        return await run();
+    }
+    catch (error) {
+        throw modalError(error);
+    }
+}
+const FILE_ERRORS = {
+    file_not_found: SandboxFilesystemNotFoundError,
+    path_not_found: SandboxFilesystemNotFoundError,
+    is_a_directory: SandboxFilesystemIsADirectoryError,
+    not_a_directory: SandboxFilesystemNotADirectoryError,
+    directory_not_empty: SandboxFilesystemDirectoryNotEmptyError,
+    already_exists: SandboxFilesystemPathAlreadyExistsError,
+    permission_denied: SandboxFilesystemPermissionError,
+    file_too_large: SandboxFilesystemFileTooLargeError,
+    too_large: SandboxFilesystemFileTooLargeError,
+};
+async function fileCall(path, run) {
+    try {
+        return await run();
+    }
+    catch (error) {
+        if (!(error instanceof RuntimeError))
+            throw error;
+        const Mapped = FILE_ERRORS[error.code] ?? (error.status === 404 ? SandboxFilesystemNotFoundError : null);
+        if (!Mapped)
+            throw error;
+        throw new Mapped(`${path}: ${error.message}`);
+    }
+}
+// Apps, secrets, volumes, bucket mounts -----------------------------------------
 export class App {
     appId;
     name;
@@ -17,72 +104,225 @@ export class App {
         this.environmentName = environmentName;
     }
 }
+export class AppService {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    async fromName(name, params = {}) {
+        this.client.open();
+        only("Modal app", params, ["createIfMissing", "environment"]);
+        if (params.environment)
+            throw new CompatibilityError("Modal", "named Modal environments");
+        if (!params.createIfMissing &&
+            !(await all(this.client.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);
+    }
+}
+/** Values the sandbox receives as environment variables, from the caller. */
 export class Secret {
     values;
-    constructor(values) {
+    name;
+    secretId;
+    constructor(values, name) {
         this.values = values;
+        this.name = name;
+        this.secretId = `st-${crypto.randomUUID()}`;
     }
 }
-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),
+const RUNTIME_SECRETS = "Runtime secrets are used without being seen: runtime.secrets.set({ value, hosts }); or pass values with secrets.fromObject";
+export class SecretService {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    async fromObject(entries, params = {}) {
+        this.client.open();
+        only("Modal secret", params, ["environment"]);
+        if (params.environment)
+            throw new CompatibilityError("Modal", "named Modal environments");
+        for (const [key, value] of Object.entries(entries))
+            if (typeof value !== "string")
+                throw new InvalidError(`Secret value for ${key} must be a string`);
+        return new Secret({ ...entries });
+    }
+}
+refuse("Modal", "SecretService", SecretService, {
+    fromName: RUNTIME_SECRETS,
+    delete: RUNTIME_SECRETS,
+});
+const FIXED_SIZE = "Runtime volumes have a fixed size: create one with runtime.volumes.create({ name, sizeMiB })";
+export class Volume {
+    volumeId;
+    name;
+    readOnly;
+    constructor(volumeId, name, readOnly = false) {
+        this.volumeId = volumeId;
+        this.name = name;
+        this.readOnly = readOnly;
+    }
+    withMountOptions(params = {}) {
+        only("Modal volume mount", params, ["readOnly", "subPath"]);
+        if (params.subPath)
+            throw new CompatibilityError("Modal", "subPath; mount the whole volume");
+        return new Volume(this.volumeId, this.name, params.readOnly ?? this.readOnly);
+    }
+    closeEphemeral() {
+        throw new InvalidError(`Volume ${this.name ?? this.volumeId} is not ephemeral`);
+    }
+}
+export class VolumeService {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    async find(name) {
+        const page = await modal(() => this.client.runtime.volumes.list({ name, limit: 100 }));
+        return page.data.find((v) => v.name === name && v.state !== "deleted");
+    }
+    async fromName(name, params = {}) {
+        this.client.open();
+        only("Modal volume", params, ["createIfMissing", "environment"]);
+        if (params.environment)
+            throw new CompatibilityError("Modal", "named Modal environments");
+        const found = await this.find(name);
+        if (found)
+            return new Volume(found.id, name);
+        if (params.createIfMissing)
+            throw new CompatibilityError("Modal", `createIfMissing; ${FIXED_SIZE}`);
+        throw new NotFoundError(`Volume ${name} not found`);
+    }
+    async delete(name, params = {}) {
+        this.client.open();
+        only("Modal volume delete", params, ["allowMissing", "environment"]);
+        if (params.environment)
+            throw new CompatibilityError("Modal", "named Modal environments");
+        const found = await this.find(name);
+        if (!found) {
+            if (params.allowMissing)
+                return;
+            throw new NotFoundError(`Volume ${name} not found`);
+        }
+        await modal(() => this.client.runtime.volumes.delete(found.id));
+    }
+}
+refuse("Modal", "VolumeService", VolumeService, { ephemeral: FIXED_SIZE });
+const BUCKET_KEYS = "store the bucket key with runtime.secrets.set and mount it with the native sandbox's mounts.add";
+export class CloudBucketMount {
+    bucketName;
+    readOnly;
+    bucketEndpointUrl;
+    keyPrefix;
+    /** Refused at creation: Runtime mounts public buckets here, keyed ones natively. */
+    secret;
+    requesterPays = false;
+    oidcAuthRoleArn;
+    constructor(bucketName, readOnly = false, bucketEndpointUrl, keyPrefix) {
+        this.bucketName = bucketName;
+        this.readOnly = readOnly;
+        this.bucketEndpointUrl = bucketEndpointUrl;
+        this.keyPrefix = keyPrefix;
+    }
+    /** The native mount for `path`: the provider read from the endpoint's host. */
+    native(path) {
+        const host = this.bucketEndpointUrl ? new URL(this.bucketEndpointUrl).hostname : undefined;
+        const r2 = host?.match(/^([0-9a-f]+)\.r2\.cloudflarestorage\.com$/);
+        return {
+            provider: r2
+                ? "r2"
+                : host === "storage.googleapis.com"
+                    ? "gcs"
+                    : "s3",
+            bucket: this.bucketName,
+            path,
+            ...(r2 ? { accountId: r2[1] } : host ? { endpoint: host } : {}),
+            ...(this.keyPrefix ? { prefix: this.keyPrefix } : {}),
+            readOnly: this.readOnly,
         };
-        this.sandboxes = new SandboxService(runtime);
     }
-    close() {
-        /* Transport has no owned background connection to close. */
+}
+refuse("Modal", "CloudBucketMount", CloudBucketMount, { toProto: "pass it in cloudBucketMounts" }, { sync: true });
+export class CloudBucketMountService {
+    create(bucketName, params = {}) {
+        only("Modal bucket mount", params, [
+            "secret",
+            "readOnly",
+            "requesterPays",
+            "bucketEndpointUrl",
+            "keyPrefix",
+            "oidcAuthRoleArn",
+        ]);
+        if (params.secret)
+            throw new CompatibilityError("Modal", `bucket secret; ${BUCKET_KEYS}`);
+        if (params.requesterPays || params.oidcAuthRoleArn)
+            throw new CompatibilityError("Modal", `requesterPays and oidcAuthRoleArn; ${BUCKET_KEYS}`);
+        if (params.bucketEndpointUrl)
+            new URL(params.bucketEndpointUrl);
+        return new CloudBucketMount(bucketName, params.readOnly ?? false, params.bucketEndpointUrl, params.keyPrefix);
     }
 }
+export class Proxy {
+}
+export class ProxyService {
+}
+const STATIC_IPS = "Runtime static egress IPs: runtime.ips";
+refuse("Modal", "Proxy", Proxy, { proxyId: STATIC_IPS }, { sync: true });
+refuse("Modal", "ProxyService", ProxyService, { fromName: STATIC_IPS });
+export class ExperimentalOutboundPolicy {
+}
+refuse("Modal", "ExperimentalOutboundPolicy", ExperimentalOutboundPolicy, {
+    withHeaderReplacement: "Runtime secrets set the header on the way out: runtime.secrets.set({ value, hosts, header })",
+}, { sync: true });
+export class Probe {
+    spec;
+    constructor(spec) {
+        this.spec = spec;
+    }
+    static interval(name, intervalMs) {
+        if (!Number.isInteger(intervalMs))
+            throw new InvalidError(`${name}() expects an integer \`intervalMs\``);
+        if (intervalMs <= 0)
+            throw new InvalidError(`${name}() expects \`intervalMs\` > 0, got ${String(intervalMs)}`);
+    }
+    static withTcp(port, params = { intervalMs: 100 }) {
+        if (!Number.isInteger(port))
+            throw new InvalidError("Probe.withTcp() expects an integer `port`");
+        if (port <= 0 || port > 65535)
+            throw new InvalidError(`Probe.withTcp() expects \`port\` in [1, 65535], got ${port}`);
+        Probe.interval("Probe.withTcp", params.intervalMs);
+        return new Probe({ tcpPort: port, intervalMs: params.intervalMs });
+    }
+    static withExec(argv, params = { intervalMs: 100 }) {
+        if (!Array.isArray(argv) || argv.length === 0)
+            throw new InvalidError("Probe.withExec() requires at least one argument");
+        if (!argv.every((arg) => typeof arg === "string"))
+            throw new InvalidError("Probe.withExec() expects all arguments to be strings");
+        Probe.interval("Probe.withExec", params.intervalMs);
+        return new Probe({ execArgv: [...argv], intervalMs: params.intervalMs });
+    }
+}
+refuse("Modal", "Probe", Probe, { toProto: "pass it as readinessProbe" }, { sync: true });
+// Images ------------------------------------------------------------------------
 export class Image {
     runtime;
     tag;
     commands;
     env;
     cache;
+    snapshot;
     built;
-    constructor(runtime, tag, id, commands = [], env = {}, cache = true) {
+    constructor(
+    /** Absent only for an Image that is already built. */
+    runtime, tag, id, commands = [], env = {}, cache = true, 
+    /** The id is a native disk snapshot (snapshotFilesystem), not an image. */
+    snapshot = false) {
         this.runtime = runtime;
         this.tag = tag;
         this.commands = commands;
         this.env = env;
         this.cache = cache;
+        this.snapshot = snapshot;
         this.built = id;
     }
     get imageId() {
@@ -98,47 +338,199 @@ export class Image {
     }
     async build(_app) {
         if (!this.built) {
-            const built = this.commands.length
-                ? await this.runtime.images.build({
+            const built = await modal(() => this.commands.length
+                ? 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.runtime.images.build({ image: this.tag, env: this.env, cache: this.cache }));
             this.built = built.id;
         }
         return this;
     }
 }
+refuse("Modal", "Image", Image, {
+    publish: "build it under a name: runtime.images.build({ name }), then images.fromName",
+});
+const REGISTRY_LOGIN = "store the registry login with runtime.images.registries, then use images.fromRegistry";
+export class ImageService {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    fromRegistry(tag, secret) {
+        this.client.open();
+        if (secret)
+            throw new CompatibilityError("Modal", `registry Secret; ${REGISTRY_LOGIN}`);
+        return new Image(this.client.runtime, tag);
+    }
+    async fromId(imageId) {
+        this.client.open();
+        return new Image(this.client.runtime, undefined, (await modal(() => this.client.runtime.images.get(imageId))).id);
+    }
+    async fromName(name, params = {}) {
+        this.client.open();
+        only("Modal image name", params, ["environment"]);
+        if (params.environment)
+            throw new CompatibilityError("Modal", "named Modal environments");
+        return new Image(this.client.runtime, undefined, (await modal(() => this.client.runtime.images.resolve(name))).id);
+    }
+    async delete(imageId, _params = {}) {
+        this.client.open();
+        await modal(() => this.client.runtime.images.delete(imageId));
+    }
+}
+refuse("Modal", "ImageService", ImageService, { fromAwsEcr: REGISTRY_LOGIN, fromGcpArtifactRegistry: REGISTRY_LOGIN }, { sync: true });
+// Snapshots ---------------------------------------------------------------------
+export class SandboxSnapshot {
+    snapshotId;
+    constructor(snapshotId) {
+        this.snapshotId = snapshotId;
+    }
+}
+export class SandboxSnapshotService {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    async fromId(snapshotId) {
+        this.client.open();
+        const snapshot = await modal(() => this.client.runtime.snapshots.get(snapshotId));
+        if (snapshot.state === "deleted" || snapshot.state === "deleting")
+            throw new NotFoundError(`Sandbox snapshot ${snapshotId} not found`);
+        return new SandboxSnapshot(snapshot.id);
+    }
+}
+export class ModalClient {
+    runtime;
+    apps;
+    images;
+    sandboxes;
+    secrets;
+    volumes;
+    cloudBucketMounts = new CloudBucketMountService();
+    sandboxSnapshots;
+    proxies = new ProxyService();
+    #closed = false;
+    constructor(options = {}) {
+        if (options.endpoint !== undefined ||
+            options.oauthRefreshToken !== undefined ||
+            options.oauthClientId !== undefined ||
+            options.oauthClientSecret !== undefined ||
+            options.oauthJwtKey !== undefined ||
+            options.maxThrottleWaitSecs !== undefined ||
+            options.logger !== undefined ||
+            options.logLevel !== undefined ||
+            options.grpcMiddleware !== undefined ||
+            options.cpClient !== undefined)
+            throw new CompatibilityError("Modal", "Modal endpoints, OAuth, gRPC and logger options; set RUNTIME_API_KEY or pass apiKey");
+        only("Modal client", options, [
+            "apiKey",
+            "baseUrl",
+            "fetch",
+            "client",
+            "timeoutMs",
+            "maxRetries",
+            "tokenId",
+            "tokenSecret",
+            "environment",
+        ]);
+        if (options.environment)
+            throw new CompatibilityError("Modal", "named Modal environments");
+        this.runtime = client(options);
+        this.apps = new AppService(this);
+        this.images = new ImageService(this);
+        this.sandboxes = new SandboxService(this.runtime, this);
+        this.secrets = new SecretService(this);
+        this.volumes = new VolumeService(this);
+        this.sandboxSnapshots = new SandboxSnapshotService(this);
+    }
+    /** Throws once close() was called, as Modal's client does. */
+    open() {
+        if (this.#closed)
+            throw new ClientClosedError("The Modal client was closed");
+    }
+    environmentName(environment) {
+        if (environment)
+            throw new CompatibilityError("Modal", "named Modal environments");
+        return "";
+    }
+    /** The Modal SDK version whose interface this adapter implements. */
+    version() {
+        return "0.11.0";
+    }
+    close() {
+        // The transport owns no background connection; later calls fail as Modal's do.
+        this.#closed = true;
+    }
+}
+const NO_MODAL_SERVER = "Runtime has no Modal control plane; use the native client at modal.runtime";
+refuse("Modal", "ModalClient", ModalClient, {
+    cpClient: NO_MODAL_SERVER,
+    ipClient: NO_MODAL_SERVER,
+    profile: NO_MODAL_SERVER,
+    logger: NO_MODAL_SERVER,
+}, { sync: true });
+refuse("Modal", "ModalClient", ModalClient, {
+    getImageBuilderVersion: "Runtime images record theirs: (await runtime.images.get(id)).build.builderVersion",
+});
+/** Modal's outbound allowlists as Runtime network rules, never wider than
+ * Modal's: a missing list or a wildcard entry allows everything, an empty
+ * list blocks all egress. Runtime's rules are one list a connection matches
+ * any entry of, so a domain list and a CIDR list that both narrow are
+ * refused rather than joined into a wider rule. */
+function egress(domains, cidrs) {
+    if (domains?.length === 0 || cidrs?.length === 0)
+        return { internet: false };
+    const anyDomain = !domains || domains.includes("*");
+    const anyCidr = !cidrs || cidrs.some((c) => c === "0.0.0.0/0" || c === "::/0");
+    if (anyDomain && anyCidr)
+        return { internet: true };
+    if (!anyDomain && !anyCidr)
+        throw new CompatibilityError("Modal", "a domain allowlist and a CIDR allowlist at once; pass one list of domains and CIDR ranges to sandbox.native.network.set({ internet: true, allow })");
+    return { internet: true, allow: anyDomain ? cidrs : domains };
+}
+const ENVIRONMENTS = "named Modal environments";
+const CREATE_OPTIONS = [
+    "name",
+    "cpu",
+    "cpuLimit",
+    "memoryMiB",
+    "memoryLimitMiB",
+    "runtime",
+    "timeoutMs",
+    "workdir",
+    "command",
+    "env",
+    "encryptedPorts",
+    "blockNetwork",
+    "outboundDomainAllowlist",
+    "outboundCidrAllowlist",
+    "tags",
+    "regions",
+    "gpu",
+    "pty",
+    "secrets",
+    "volumes",
+    "cloudBucketMounts",
+    "readinessProbe",
+    "experimentalEnableSnapshot",
+];
 export class SandboxService {
     runtime;
-    constructor(runtime) {
+    client;
+    constructor(runtime, client) {
         this.runtime = runtime;
+        this.client = client;
     }
     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",
-        ]);
+        this.client?.open();
+        only("Modal sandbox", params, CREATE_OPTIONS);
         if (params.gpu)
             throw new CompatibilityError("Modal", "GPU allocation");
+        if (params.runtime === "gvisor")
+            throw new CompatibilityError("Modal", 'gVisor; Runtime sandboxes are Firecracker VMs (runtime: "vm")');
         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)
@@ -147,23 +539,49 @@ export class SandboxService {
             throw new CompatibilityError("Modal", "multiple region placement");
         if (params.cpu !== undefined && !Number.isInteger(params.cpu))
             throw new CompatibilityError("Modal", "fractional CPU reservations");
+        if (image.snapshot && (params.cpu !== undefined || params.memoryMiB !== undefined))
+            throw new CompatibilityError("Modal", "cpu or memoryMiB with a snapshot image; it keeps the snapshot's shape, resize it after");
         if (params.blockNetwork && (params.outboundDomainAllowlist || params.outboundCidrAllowlist))
             throw new TypeError("blockNetwork cannot be combined with allowlists");
+        if (params.runtime !== undefined && params.runtime !== "vm")
+            throw new InvalidError(`Unknown sandbox runtime ${String(params.runtime)}`);
+        const network = params.blockNetwork
+            ? { internet: false }
+            : egress(params.outboundDomainAllowlist, params.outboundCidrAllowlist);
         const placement = region("Modal", params.regions?.[0]);
         const built = await image.build(app);
+        const volumes = Object.entries(params.volumes ?? {}).map(([path, v]) => {
+            if (!(v instanceof Volume))
+                throw new InvalidError(`volumes[${path}] must be a Volume`);
+            return {
+                volumeId: v.volumeId,
+                path,
+                mode: v.readOnly ? "snapshot" : "rw",
+            };
+        });
+        const mounts = Object.entries(params.cloudBucketMounts ?? {}).map(([path, m]) => {
+            if (!(m instanceof CloudBucketMount))
+                throw new InvalidError(`cloudBucketMounts[${path}] must be a CloudBucketMount`);
+            return m.native(path);
+        });
         let primary;
-        const s = await create(this.runtime, "modal", {
+        const input = {
             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 ?? {}),
+                ...(params.readinessProbe
+                    ? { "modal.probe": JSON.stringify(params.readinessProbe.spec) }
+                    : {}),
+                ...(volumes.some((v) => v.mode === "snapshot") ? { "modal.readonly": "1" } : {}),
             },
-            image: built.imageId,
-            cpu: "reserved",
-            vcpu: params.cpu,
-            memoryMiB: params.memoryMiB,
+            ...(image.snapshot ? { snapshot: built.imageId } : { image: built.imageId }),
+            ...(image.snapshot
+                ? {}
+                : { cpu: "reserved", vcpu: params.cpu, memoryMiB: params.memoryMiB }),
             region: placement,
+            ...(volumes.length ? { volumes } : {}),
             // A timeout is the customer's limit, and the sandbox never pauses
             // for idleness before it. None is no time limit (0300): it runs while
             // it works and pauses when idle.
@@ -171,14 +589,11 @@ export class SandboxService {
                 ? {}
                 : { timeoutSeconds: Math.ceil(params.timeoutMs / 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) => {
+            network,
+        };
+        const s = await modal(() => create(this.runtime, "modal", input, Object.assign({}, ...(params.secrets?.map((s) => s.values) ?? []), params.env ?? {}), async (s) => {
+            for (const mount of mounts)
+                await s.mounts.add(mount);
             primary = await s.spawn(params.command ?? ["sleep", "infinity"], {
                 ...(await execOptions(s, { cwd: params.workdir })),
                 stdin: "pipe",
@@ -187,19 +602,28 @@ export class SandboxService {
             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"));
+        }));
+        const sandbox = new Sandbox(s, new ContainerProcess(primary, "text"), this.client);
         sandbox.monitorEntrypoint();
         return sandbox;
     }
+    async experimentalCreate(app, image, params = {}) {
+        only("Modal sandbox", params, CREATE_OPTIONS);
+        return this.create(app, image, params);
+    }
     async fromId(id) {
-        const s = await this.runtime.sandboxes.get(id);
+        this.client?.open();
+        const s = await modal(() => 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"));
+        return new Sandbox(s, new ContainerProcess(await modal(() => s.processes.get(p)), "text"), this.client);
     }
-    async fromName(appName, name) {
+    async fromName(appName, name, params = {}) {
+        this.client?.open();
+        only("Modal sandbox name", params, ["environment"]);
+        if (params.environment)
+            throw new CompatibilityError("Modal", ENVIRONMENTS);
         const s = (await all(this.runtime, "modal")).find((s) => s.info.labels["modal.app"] === appName &&
             s.info.labels["modal.name"] === name &&
             s.state === "running");
@@ -207,14 +631,55 @@ export class SandboxService {
             throw new NotFoundError(`Sandbox ${name} not found`);
         return this.fromId(s.id);
     }
+    experimentalFromName(appName, name, params = {}) {
+        return this.fromName(appName, name, params);
+    }
+    /** A new sandbox continuing a memory snapshot: its files, memory and
+     * running entrypoint, under the snapshot's app and tags. */
+    async experimentalFromSnapshot(snapshot, params = {}) {
+        this.client?.open();
+        only("Modal snapshot restore", params, ["name"]);
+        const saved = await modal(() => this.runtime.snapshots.get(snapshot.snapshotId));
+        const labels = (saved.labels ?? {});
+        const entrypoint = labels["modal.entrypoint"];
+        if (!entrypoint || saved.mode === "disk")
+            throw new InvalidError(`Snapshot ${snapshot.snapshotId} was not taken with sandbox.experimentalSnapshot()`);
+        const app = labels["modal.app"];
+        const s = await modal(() => create(this.runtime, "modal", {
+            snapshot: saved.id,
+            ...(params.name ? { name: `${app}-${params.name}` } : {}),
+            labels: {
+                ...Object.fromEntries(Object.entries(labels).filter(([k]) => k.startsWith("modal."))),
+                ...(params.name ? { "modal.name": params.name } : {}),
+            },
+            onLeaseEnd: "stop",
+        }));
+        let process;
+        try {
+            process = await s.processes.get(entrypoint);
+        }
+        catch (error) {
+            await destroy(s);
+            throw modalError(error);
+        }
+        const sandbox = new Sandbox(s, new ContainerProcess(process, "text"), this.client);
+        sandbox.monitorEntrypoint();
+        return sandbox;
+    }
     async *list(params = {}) {
-        only("Modal list", params, ["appId", "tags"]);
+        this.client?.open();
+        only("Modal list", params, ["appId", "tags", "environment"]);
+        if (params.environment)
+            throw new CompatibilityError("Modal", ENVIRONMENTS);
         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);
     }
+    experimentalList(params = {}) {
+        return this.list(params);
+    }
 }
 export class ModalReadStream extends ReadableStream {
     constructor(process, channel, mode, ignore = false) {
@@ -328,13 +793,67 @@ export class ContainerProcess {
         return p.state === "running" ? null : p.exitCode;
     }
 }
+/** Host and port of a sandbox port's public HTTPS address. Runtime previews
+ * are HTTPS only, so there is no unencrypted address. */
+export class Tunnel {
+    host;
+    port;
+    unencryptedHost;
+    unencryptedPort;
+    constructor(host, port, unencryptedHost, unencryptedPort) {
+        this.host = host;
+        this.port = port;
+        this.unencryptedHost = unencryptedHost;
+        this.unencryptedPort = unencryptedPort;
+    }
+    get url() {
+        return this.port === 443 ? `https://${this.host}` : `https://${this.host}:${this.port}`;
+    }
+    get tlsSocket() {
+        return [this.host, this.port];
+    }
+    get tcpSocket() {
+        if (!this.unencryptedHost || this.unencryptedPort === undefined)
+            throw new InvalidError("This tunnel is not configured for unencrypted TCP.");
+        return [this.unencryptedHost, this.unencryptedPort];
+    }
+}
+const NEW_SANDBOX_FROM_SNAPSHOT = "take sandbox.snapshotFilesystem() and start a new sandbox from that image";
+export class SandboxLogsManager {
+}
+refuse("Modal", "SandboxLogsManager", SandboxLogsManager, {
+    fetch: "read sandbox.stdout and sandbox.stderr",
+    tail: "read sandbox.stdout and sandbox.stderr",
+}, { sync: true });
+const SECOND_SANDBOX = "start a second Runtime sandbox and join both to a private network";
+export class SidecarService {
+}
+refuse("Modal", "SidecarService", SidecarService, { create: SECOND_SANDBOX, get: SECOND_SANDBOX });
+refuse("Modal", "SidecarService", SidecarService, { list: SECOND_SANDBOX }, { sync: true });
+export class SidecarContainer {
+}
+refuse("Modal", "SidecarContainer", SidecarContainer, { containerId: SECOND_SANDBOX, containerName: SECOND_SANDBOX, filesystem: SECOND_SANDBOX }, { sync: true });
+refuse("Modal", "SidecarContainer", SidecarContainer, Object.fromEntries([
+    "exec",
+    "mountImage",
+    "poll",
+    "reloadVolumes",
+    "snapshotDirectory",
+    "snapshotFilesystem",
+    "terminate",
+    "unmountImage",
+    "wait",
+].map((m) => [m, SECOND_SANDBOX])));
 export class Sandbox {
     native;
     primary;
+    client;
     filesystem;
     stdin;
     stdout;
     stderr;
+    logs = new SandboxLogsManager();
+    experimentalSidecars = new SidecarService();
     detached = false;
     lifecycle;
     monitorEntrypoint() {
@@ -344,9 +863,10 @@ export class Sandbox {
         });
         this.lifecycle.catch(() => undefined);
     }
-    constructor(native, primary) {
+    constructor(native, primary, client) {
         this.native = native;
         this.primary = primary;
+        this.client = client;
         this.filesystem = new SandboxFilesystem(native);
         this.stdin = primary.stdin;
         this.stdout = primary.stdout;
@@ -355,9 +875,13 @@ export class Sandbox {
     get sandboxId() {
         return this.native.id;
     }
-    async exec(command, params = {}) {
+    attached() {
+        this.client?.open();
         if (this.detached)
-            throw new Error("Sandbox is detached");
+            throw new ClientClosedError("Sandbox is detached");
+    }
+    async exec(command, params = {}) {
+        this.attached();
         only("Modal exec", params, [
             "mode",
             "stdout",
@@ -381,8 +905,7 @@ export class Sandbox {
         return new ContainerProcess(p, params.mode ?? "text", params);
     }
     async setTags(tags) {
-        if (this.detached)
-            throw new Error("Sandbox is detached");
+        this.attached();
         await this.native.update({
             labels: {
                 ...Object.fromEntries(Object.entries(this.native.info.labels).filter(([k]) => k.startsWith("modal.") || k === "compat.provider")),
@@ -391,11 +914,21 @@ export class Sandbox {
         });
     }
     async getTags() {
-        if (this.detached)
-            throw new Error("Sandbox is detached");
+        this.attached();
         await this.native.refresh();
         return JSON.parse(this.native.info.labels["modal.tags"] ?? "{}");
     }
+    /** Names the sandbox so sandboxes.fromName(app, name) finds it. */
+    async experimentalSetName(name) {
+        this.attached();
+        if (!name)
+            throw new InvalidError("Sandbox name must not be empty");
+        const app = this.native.info.labels["modal.app"];
+        await modal(() => this.native.update({
+            name: `${app}-${name}`,
+            labels: { ...this.native.info.labels, "modal.name": name },
+        }));
+    }
     async terminate(params = {}) {
         await destroy(this.native);
         return params.wait ? this.primary.wait() : undefined;
@@ -413,23 +946,99 @@ export class Sandbox {
     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 },
-        ]));
+    /** Runs the sandbox's readinessProbe until it passes. */
+    async waitUntilReady(timeoutMs = 300_000) {
+        this.attached();
+        if (timeoutMs <= 0)
+            throw new InvalidError(`timeoutMs must be positive, got ${timeoutMs}`);
+        const raw = this.native.info.labels["modal.probe"];
+        if (!raw)
+            throw new InvalidError("Sandbox has no readinessProbe");
+        const probe = JSON.parse(raw);
+        const argv = probe.execArgv ?? ["bash", "-c", `exec 3<>/dev/tcp/127.0.0.1/${probe.tcpPort}`];
+        const until = performance.now() + timeoutMs;
+        while (true) {
+            const left = Math.ceil(until - performance.now());
+            if (left <= 0)
+                throw new TimeoutError("Timeout expired");
+            const result = await this.native.exec(argv, { timeoutMs: left });
+            if (result.exitCode === 0)
+                return;
+            await new Promise((resolve) => setTimeout(resolve, Math.min(probe.intervalMs, left)));
+        }
+    }
+    async tunnels(timeoutMs = 50_000) {
+        this.attached();
+        const tunnels = {};
+        for (const p of await this.native.previews.list({ timeoutMs }))
+            tunnels[p.port] = new Tunnel(new URL(p.url).hostname, 443);
+        return tunnels;
     }
     async updateNetworkPolicy(params) {
-        await this.native.network.set({
-            internet: true,
-            allow: [...params.outboundCidrAllowlist, ...params.outboundDomainAllowlist],
-        });
+        this.attached();
+        only("Modal network policy", params, ["outboundCidrAllowlist", "outboundDomainAllowlist"]);
+        if (!params.outboundCidrAllowlist || !params.outboundDomainAllowlist)
+            throw new InvalidError("Both outboundCidrAllowlist and outboundDomainAllowlist must be provided");
+        await this.native.network.set(egress(params.outboundDomainAllowlist, params.outboundCidrAllowlist));
     }
+    /** Runtime volumes are block devices with one writer: a read-write mount
+     * always shows the latest writes. A read-only mount is a copy taken at
+     * start, which cannot reload. */
+    async reloadVolumes(params = {}) {
+        this.attached();
+        only("Modal reload volumes", params, ["timeoutMs"]);
+        if (this.native.info.labels["modal.readonly"])
+            throw new CompatibilityError("Modal", "reloading a read-only volume; it is a copy taken at start");
+    }
+    /** The whole sandbox, memory and running processes included. */
     async experimentalSnapshot() {
-        const snapshot = await this.native.snapshot();
-        return { sandboxSnapshotId: snapshot.id };
+        this.attached();
+        const snapshot = await modal(() => this.native.snapshot({
+            labels: Object.fromEntries(Object.entries(this.native.info.labels).filter(([k]) => k.startsWith("modal."))),
+        })).catch((error) => {
+            throw error instanceof Error && !(error instanceof NotFoundError)
+                ? new SnapshotCreationError(error.message)
+                : error;
+        });
+        return new SandboxSnapshot(snapshot.id);
+    }
+    /** The sandbox's files as an Image new sandboxes start from. `ttlMs` is
+     * kept in whole days. */
+    async snapshotFilesystem(params = {}) {
+        this.attached();
+        only("Modal filesystem snapshot", params, ["timeoutMs", "ttlMs"]);
+        const day = 86_400_000;
+        if (params.ttlMs === null ||
+            (params.ttlMs !== undefined && (!Number.isInteger(params.ttlMs / day) || params.ttlMs <= 0)))
+            throw new CompatibilityError("Modal", "ttlMs that is null or not whole days; Runtime keeps snapshots for a number of days");
+        const snapshot = await this.native
+            .snapshot({
+            mode: "disk",
+            ...(params.ttlMs === undefined ? {} : { retentionDays: params.ttlMs / day }),
+            ...(params.timeoutMs === undefined ? {} : { timeoutMs: params.timeoutMs }),
+        })
+            .catch((error) => {
+            throw error instanceof RuntimeError && error.code === "timeout"
+                ? new TimeoutError(error.message)
+                : new SnapshotCreationError(error instanceof Error ? error.message : String(error));
+        });
+        return new Image(undefined, undefined, snapshot.id, [], {}, true, true);
     }
 }
+refuse("Modal", "Sandbox", Sandbox, {
+    createConnectToken: "a private preview: sandbox.native.previews.create(port), sending its token as x-runtime-preview-token",
+    experimentalGetExitSnapshot: NEW_SANDBOX_FROM_SNAPSHOT,
+    snapshotDirectory: NEW_SANDBOX_FROM_SNAPSHOT,
+    mountImage: NEW_SANDBOX_FROM_SNAPSHOT,
+    unmountImage: NEW_SANDBOX_FROM_SNAPSHOT,
+    experimentalUpdateOutboundPolicy: "updateNetworkPolicy for allowlists; runtime.secrets.set({ value, hosts, header }) for header replacement",
+});
+const WATCHED = {
+    Access: ["access"],
+    Create: ["create"],
+    Modify: ["write", "chmod", "rename"],
+    Remove: ["remove"],
+};
 export class SandboxFilesystem {
     native;
     files;
@@ -438,36 +1047,35 @@ export class SandboxFilesystem {
         this.files = new GuestFiles(async () => native, "/");
     }
     readBytes(path) {
-        return this.files.readFile(path);
+        return fileCall(path, () => this.files.readFile(path));
     }
     readText(path) {
-        return this.files.readTextFile(path);
+        return fileCall(path, () => this.files.readTextFile(path));
     }
     writeBytes(content, path) {
-        return this.files.writeFile(path, content instanceof Uint8Array ? content : new Uint8Array(content));
+        return fileCall(path, () => this.files.writeFile(path, content instanceof Uint8Array ? content : new Uint8Array(content)));
     }
     writeText(content, path) {
-        return this.files.writeTextFile(path, content);
+        return fileCall(path, () => this.files.writeTextFile(path, content));
     }
     makeDirectory(path, options = {}) {
-        return this.files.mkdir(path, options.createParents ?? true);
+        return fileCall(path, () => this.files.mkdir(path, options.createParents ?? true));
     }
     remove(path, options = {}) {
-        return this.files.remove(path, options.recursive);
+        return fileCall(path, () => this.files.remove(path, options.recursive));
     }
     copyFromLocal(localPath, remotePath) {
-        return this.native.files.upload(localPath, remotePath);
+        return fileCall(remotePath, () => this.native.files.upload(localPath, remotePath));
     }
     copyToLocal(remotePath, localPath) {
-        return this.native.files.download(remotePath, localPath);
+        return fileCall(remotePath, () => 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)));
+        const entries = await fileCall(path, () => this.files.readdir(path));
+        return Promise.all(entries.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 e = await fileCall(path, () => this.files.stat(path));
         const r = await this.native.exec(["stat", "-c", "%U:%G", "--", this.files.path(path)], {
             check: true,
         });
@@ -487,4 +1095,56 @@ export class SandboxFilesystem {
                 : null,
         };
     }
+    /** Changes under `remotePath` until `timeoutMs` passes or the loop stops. */
+    async *watch(remotePath, params = {}) {
+        only("Modal watch", params, ["filter", "recursive", "timeoutMs"]);
+        if (!remotePath.startsWith("/"))
+            throw new InvalidError(`watch() expects an absolute path, got ${remotePath}`);
+        const types = (params.filter ?? ["Access", "Create", "Modify", "Remove"]).flatMap((t) => (t === "Unknown" ? [] : WATCHED[t]));
+        const queue = [];
+        let ended = false;
+        let wake;
+        const notify = () => {
+            wake?.();
+            wake = undefined;
+        };
+        const handle = await fileCall(remotePath, () => this.native.files.watch(remotePath, undefined, {
+            recursive: params.recursive ?? false,
+            events: [...new Set(types)],
+            timeoutMs: params.timeoutMs ?? 0,
+            onBatch: (events) => {
+                for (const e of events)
+                    queue.push({
+                        eventType: e.type === "create"
+                            ? "Create"
+                            : e.type === "remove"
+                                ? "Remove"
+                                : e.type === "access"
+                                    ? "Access"
+                                    : "Modify",
+                        paths: e.type === "rename" && e.oldPath ? [e.oldPath, e.path] : [e.path],
+                    });
+                notify();
+            },
+            onExit: () => {
+                ended = true;
+                notify();
+            },
+        }));
+        try {
+            while (true) {
+                const next = queue.shift();
+                if (next)
+                    yield next;
+                else if (ended)
+                    return;
+                else
+                    await new Promise((resolve) => (wake = resolve));
+            }
+        }
+        finally {
+            if (!ended)
+                await handle.stop().catch(() => undefined);
+        }
+    }
 }