withruntime 0.11.2 → 0.12.0

package/dist/modal/index.d.ts

@@ -1,25 +1,262 @@
 import type { Runtime } from "../client.js";
 import type { Process, Sandbox as NativeSandbox } from "../sandbox.js";
-import { CompatibilityError, type ClientOptions } from "../compat/core.js";
+import { CompatibilityError, type ClientOptions, type Refused, type RefusedAsync } from "../compat/core.js";
 export { CompatibilityError };
+export declare class TimeoutError extends Error {
+}
+export declare class RemoteError extends Error {
+}
+export declare class ExecutionError extends Error {
+}
+export declare class InternalFailure extends Error {
+}
 export declare class NotFoundError extends Error {
 }
-export declare class TimeoutError extends Error {
+export declare class AlreadyExistsError extends Error {
+}
+export declare class ConflictError extends Error {
+}
+export declare class InvalidError extends Error {
+}
+export declare class ResourceExhaustedError extends Error {
 }
 export declare class SandboxTimeoutError extends TimeoutError {
 }
+export declare class SnapshotCreationError extends Error {
+}
+export declare class ClientClosedError extends Error {
+}
+export declare class SandboxFilesystemError extends Error {
+}
+export declare class SandboxFilesystemDirectoryNotEmptyError extends SandboxFilesystemError {
+}
+export declare class SandboxFilesystemFileTooLargeError extends SandboxFilesystemError {
+}
+export declare class SandboxFilesystemIsADirectoryError extends SandboxFilesystemError {
+}
+export declare class SandboxFilesystemNotADirectoryError extends SandboxFilesystemError {
+}
+export declare class SandboxFilesystemNotFoundError extends SandboxFilesystemError {
+}
+export declare class SandboxFilesystemPathAlreadyExistsError extends SandboxFilesystemError {
+}
+export declare class SandboxFilesystemPermissionError extends SandboxFilesystemError {
+}
 export declare class App {
     readonly appId: string;
     readonly name?: string | undefined;
     readonly environmentName?: string | undefined;
     constructor(appId: string, name?: string | undefined, environmentName?: string | undefined);
 }
+export declare class AppService {
+    private readonly client;
+    constructor(client: ModalClient);
+    fromName(name: string, params?: {
+        createIfMissing?: boolean;
+        environment?: string;
+    }): Promise<App>;
+}
+/** Values the sandbox receives as environment variables, from the caller. */
+export declare class Secret {
+    readonly values: Record<string, string>;
+    readonly name?: string | undefined;
+    readonly secretId: string;
+    constructor(values: Record<string, string>, name?: string | undefined);
+}
+export declare class SecretService {
+    private readonly client;
+    constructor(client: ModalClient);
+    fromObject(entries: Record<string, string>, params?: {
+        environment?: string;
+    }): Promise<Secret>;
+    readonly fromName: RefusedAsync;
+    readonly delete: RefusedAsync;
+}
+export declare class Volume {
+    readonly volumeId: string;
+    readonly name?: string | undefined;
+    readonly readOnly: boolean;
+    constructor(volumeId: string, name?: string | undefined, readOnly?: boolean);
+    withMountOptions(params?: {
+        readOnly?: boolean;
+        subPath?: string;
+    }): Volume;
+    closeEphemeral(): void;
+}
+export declare class VolumeService {
+    private readonly client;
+    constructor(client: ModalClient);
+    private find;
+    fromName(name: string, params?: {
+        createIfMissing?: boolean;
+        environment?: string;
+    }): Promise<Volume>;
+    delete(name: string, params?: {
+        allowMissing?: boolean;
+        environment?: string;
+    }): Promise<void>;
+    readonly ephemeral: RefusedAsync;
+}
+export declare class CloudBucketMount {
+    readonly bucketName: string;
+    readonly readOnly: boolean;
+    readonly bucketEndpointUrl?: string | undefined;
+    readonly keyPrefix?: string | undefined;
+    /** Refused at creation: Runtime mounts public buckets here, keyed ones natively. */
+    readonly secret?: Secret;
+    readonly requesterPays = false;
+    readonly oidcAuthRoleArn?: string;
+    constructor(bucketName: string, readOnly?: boolean, bucketEndpointUrl?: string | undefined, keyPrefix?: string | undefined);
+    readonly toProto: Refused;
+    /** The native mount for `path`: the provider read from the endpoint's host. */
+    native(path: string): {
+        readOnly: boolean;
+        prefix?: string | undefined;
+        accountId: string | undefined;
+        provider: "s3" | "r2" | "gcs";
+        bucket: string;
+        path: string;
+    } | {
+        readOnly: boolean;
+        prefix?: string | undefined;
+        endpoint: string;
+        provider: "s3" | "r2" | "gcs";
+        bucket: string;
+        path: string;
+    } | {
+        readOnly: boolean;
+        prefix?: string | undefined;
+        provider: "s3" | "r2" | "gcs";
+        bucket: string;
+        path: string;
+    };
+}
+export declare class CloudBucketMountService {
+    create(bucketName: string, params?: {
+        secret?: Secret;
+        readOnly?: boolean;
+        requesterPays?: boolean;
+        bucketEndpointUrl?: string;
+        keyPrefix?: string;
+        oidcAuthRoleArn?: string;
+    }): CloudBucketMount;
+}
+export declare class Proxy {
+    readonly proxyId: Refused;
+}
+export declare class ProxyService {
+    readonly fromName: RefusedAsync;
+}
+export declare class ExperimentalOutboundPolicy {
+    readonly withHeaderReplacement: Refused;
+}
+type ProbeSpec = {
+    tcpPort?: number;
+    execArgv?: string[];
+    intervalMs: number;
+};
+export declare class Probe {
+    readonly spec: ProbeSpec;
+    private constructor();
+    private static interval;
+    static withTcp(port: number, params?: {
+        intervalMs: number;
+    }): Probe;
+    static withExec(argv: string[], params?: {
+        intervalMs: number;
+    }): Probe;
+    readonly toProto: Refused;
+}
+export declare class Image {
+    /** Absent only for an Image that is already built. */
+    private readonly runtime;
+    private readonly tag?;
+    private readonly commands;
+    private readonly env;
+    private readonly cache;
+    /** The id is a native disk snapshot (snapshotFilesystem), not an image. */
+    readonly snapshot: boolean;
+    private built?;
+    constructor(
+    /** Absent only for an Image that is already built. */
+    runtime: Runtime | undefined, tag?: string | undefined, id?: string, commands?: string[], env?: Record<string, string>, cache?: boolean, 
+    /** The id is a native disk snapshot (snapshotFilesystem), not an image. */
+    snapshot?: boolean);
+    get imageId(): string;
+    dockerfileCommands(commands: string[], params?: {
+        env?: Record<string, string>;
+        forceBuild?: boolean;
+    }): Image;
+    build(_app?: App): Promise<Image>;
+    readonly publish: RefusedAsync;
+}
+export declare class ImageService {
+    private readonly client;
+    constructor(client: ModalClient);
+    fromRegistry(tag: string, secret?: Secret): Image;
+    fromId(imageId: string): Promise<Image>;
+    fromName(name: string, params?: {
+        environment?: string;
+    }): Promise<Image>;
+    delete(imageId: string, _params?: Record<never, never>): Promise<void>;
+    readonly fromAwsEcr: Refused;
+    readonly fromGcpArtifactRegistry: Refused;
+}
+export declare class SandboxSnapshot {
+    readonly snapshotId: string;
+    constructor(snapshotId: string);
+}
+export declare class SandboxSnapshotService {
+    private readonly client;
+    constructor(client: ModalClient);
+    fromId(snapshotId: string): Promise<SandboxSnapshot>;
+}
+export type ModalClientParams = ClientOptions & {
+    tokenId?: string;
+    tokenSecret?: string;
+    environment?: string;
+    oauthRefreshToken?: string;
+    oauthClientId?: string;
+    oauthClientSecret?: string;
+    oauthJwtKey?: string;
+    endpoint?: string;
+    maxThrottleWaitSecs?: number;
+    logger?: unknown;
+    logLevel?: string;
+    grpcMiddleware?: unknown[];
+    cpClient?: unknown;
+};
+export declare class ModalClient {
+    #private;
+    readonly runtime: Runtime;
+    readonly apps: AppService;
+    readonly images: ImageService;
+    readonly sandboxes: SandboxService;
+    readonly secrets: SecretService;
+    readonly volumes: VolumeService;
+    readonly cloudBucketMounts: CloudBucketMountService;
+    readonly sandboxSnapshots: SandboxSnapshotService;
+    readonly proxies: ProxyService;
+    constructor(options?: ModalClientParams);
+    /** Throws once close() was called, as Modal's client does. */
+    open(): void;
+    environmentName(environment?: string): string;
+    /** The Modal SDK version whose interface this adapter implements. */
+    version(): string;
+    close(): void;
+    readonly cpClient: Refused;
+    readonly ipClient: Refused;
+    readonly profile: Refused;
+    readonly logger: Refused;
+    readonly getImageBuilderVersion: RefusedAsync;
+}
 export type SandboxCreateParams = {
     name?: string;
     cpu?: number;
     cpuLimit?: number;
     memoryMiB?: number;
     memoryLimitMiB?: number;
+    runtime?: "gvisor" | "vm";
     timeoutMs?: number;
     workdir?: string;
     command?: string[];
@@ -33,6 +270,9 @@ export type SandboxCreateParams = {
     gpu?: string;
     pty?: boolean;
     secrets?: Secret[];
+    volumes?: Record<string, Volume>;
+    cloudBucketMounts?: Record<string, CloudBucketMount>;
+    readinessProbe?: Probe;
     experimentalEnableSnapshot?: boolean;
 };
 export type SandboxExecParams = {
@@ -45,59 +285,33 @@ export type SandboxExecParams = {
     pty?: boolean;
     secrets?: Secret[];
 };
-export declare class Secret {
-    readonly values: Record<string, string>;
-    constructor(values: Record<string, string>);
-}
-export declare class ModalClient {
-    readonly runtime: Runtime;
-    readonly apps: {
-        fromName: (name: string, params?: {
-            createIfMissing?: boolean;
-            environment?: string;
-        }) => Promise<App>;
-    };
-    readonly images: {
-        fromRegistry: (tag: string, secret?: Secret) => Image;
-        fromId: (id: string) => Promise<Image>;
-        fromName: (name: string) => Promise<Image>;
-        delete: (id: string) => Promise<import("../products/images.js").Image>;
-    };
-    readonly sandboxes: SandboxService;
-    readonly secrets: {
-        fromObject: (values: Record<string, string>) => Secret;
-    };
-    constructor(options?: ClientOptions & {
-        tokenId?: string;
-        tokenSecret?: string;
-        environment?: string;
-    });
-    close(): void;
-}
-export declare class Image {
-    private readonly runtime;
-    private readonly tag?;
-    private readonly commands;
-    private readonly env;
-    private readonly cache;
-    private built?;
-    constructor(runtime: Runtime, tag?: string | undefined, id?: string, commands?: string[], env?: Record<string, string>, cache?: boolean);
-    get imageId(): string;
-    dockerfileCommands(commands: string[], params?: {
-        env?: Record<string, string>;
-        forceBuild?: boolean;
-    }): Image;
-    build(_app?: App): Promise<Image>;
-}
 export declare class SandboxService {
     private readonly runtime;
-    constructor(runtime: Runtime);
+    private readonly client?;
+    constructor(runtime: Runtime, client?: ModalClient | undefined);
     create(app: App, image: Image, params?: SandboxCreateParams): Promise<Sandbox>;
+    experimentalCreate(app: App, image: Image, params?: SandboxCreateParams): Promise<Sandbox>;
     fromId(id: string): Promise<Sandbox>;
-    fromName(appName: string, name: string): Promise<Sandbox>;
+    fromName(appName: string, name: string, params?: {
+        environment?: string;
+    }): Promise<Sandbox>;
+    experimentalFromName(appName: string, name: string, params?: {
+        environment?: string;
+    }): Promise<Sandbox>;
+    /** A new sandbox continuing a memory snapshot: its files, memory and
+     * running entrypoint, under the snapshot's app and tags. */
+    experimentalFromSnapshot(snapshot: SandboxSnapshot, params?: {
+        name?: string | null;
+    }): Promise<Sandbox>;
     list(params?: {
         appId?: string;
         tags?: Record<string, string>;
+        environment?: string;
+    }): AsyncGenerator<Sandbox, void, unknown>;
+    experimentalList(params?: {
+        appId?: string;
+        tags?: Record<string, string>;
+        environment?: string;
     }): AsyncGenerator<Sandbox, void, unknown>;
 }
 export declare class ModalReadStream<R extends string | Uint8Array = string> extends ReadableStream<R> {
@@ -121,18 +335,57 @@ export declare class ContainerProcess<R extends string | Uint8Array = string> {
     closeStdin(): Promise<void>;
     _poll(): Promise<number | null>;
 }
+/** Host and port of a sandbox port's public HTTPS address. Runtime previews
+ * are HTTPS only, so there is no unencrypted address. */
+export declare class Tunnel {
+    host: string;
+    port: number;
+    unencryptedHost?: string | undefined;
+    unencryptedPort?: number | undefined;
+    constructor(host: string, port: number, unencryptedHost?: string | undefined, unencryptedPort?: number | undefined);
+    get url(): string;
+    get tlsSocket(): [string, number];
+    get tcpSocket(): [string, number];
+}
+export declare class SandboxLogsManager {
+    readonly fetch: Refused;
+    readonly tail: Refused;
+}
+export declare class SidecarService {
+    readonly create: RefusedAsync;
+    readonly get: RefusedAsync;
+    readonly list: Refused;
+}
+export declare class SidecarContainer {
+    readonly containerId: Refused;
+    readonly containerName: Refused;
+    readonly filesystem: Refused;
+    readonly exec: RefusedAsync;
+    readonly mountImage: RefusedAsync;
+    readonly poll: RefusedAsync;
+    readonly reloadVolumes: RefusedAsync;
+    readonly snapshotDirectory: RefusedAsync;
+    readonly snapshotFilesystem: RefusedAsync;
+    readonly terminate: RefusedAsync;
+    readonly unmountImage: RefusedAsync;
+    readonly wait: RefusedAsync;
+}
 export declare class Sandbox {
     readonly native: NativeSandbox;
     private readonly primary;
+    private readonly client?;
     readonly filesystem: SandboxFilesystem;
     readonly stdin: ModalWriteStream<string>;
     readonly stdout: ModalReadStream<string>;
     readonly stderr: ModalReadStream<string>;
+    readonly logs: SandboxLogsManager;
+    readonly experimentalSidecars: SidecarService;
     private detached;
     private lifecycle?;
     monitorEntrypoint(): void;
-    constructor(native: NativeSandbox, primary: ContainerProcess);
+    constructor(native: NativeSandbox, primary: ContainerProcess, client?: ModalClient | undefined);
     get sandboxId(): string;
+    private attached;
     exec(command: string[], params?: SandboxExecParams & {
         mode?: "text";
     }): Promise<ContainerProcess<string>>;
@@ -141,27 +394,43 @@ export declare class Sandbox {
     }): Promise<ContainerProcess<Uint8Array>>;
     setTags(tags: Record<string, string>): Promise<void>;
     getTags(): Promise<Record<string, string>>;
+    /** Names the sandbox so sandboxes.fromName(app, name) finds it. */
+    experimentalSetName(name: string): Promise<void>;
     terminate(params?: {
         wait?: boolean;
     }): Promise<number | undefined>;
     detach(): void;
     wait(): Promise<number>;
     poll(): Promise<number | null>;
-    tunnels(): Promise<{
-        [k: string]: {
-            host: string;
-            port: number;
-            url: string;
-        };
-    }>;
+    /** Runs the sandbox's readinessProbe until it passes. */
+    waitUntilReady(timeoutMs?: number): Promise<void>;
+    tunnels(timeoutMs?: number): Promise<Record<number, Tunnel>>;
     updateNetworkPolicy(params: {
-        outboundCidrAllowlist: string[];
-        outboundDomainAllowlist: string[];
+        outboundCidrAllowlist?: string[];
+        outboundDomainAllowlist?: string[];
     }): Promise<void>;
-    experimentalSnapshot(): Promise<{
-        sandboxSnapshotId: string;
-    }>;
+    /** 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. */
+    reloadVolumes(params?: {
+        timeoutMs?: number;
+    }): Promise<void>;
+    /** The whole sandbox, memory and running processes included. */
+    experimentalSnapshot(): Promise<SandboxSnapshot>;
+    /** The sandbox's files as an Image new sandboxes start from. `ttlMs` is
+     * kept in whole days. */
+    snapshotFilesystem(params?: {
+        timeoutMs?: number;
+        ttlMs?: number | null;
+    }): Promise<Image>;
+    readonly createConnectToken: RefusedAsync;
+    readonly experimentalGetExitSnapshot: RefusedAsync;
+    readonly snapshotDirectory: RefusedAsync;
+    readonly mountImage: RefusedAsync;
+    readonly unmountImage: RefusedAsync;
+    readonly experimentalUpdateOutboundPolicy: RefusedAsync;
 }
+type FileWatchEventType = "Access" | "Create" | "Modify" | "Remove" | "Unknown";
 export declare class SandboxFilesystem {
     private readonly native;
     private readonly files;
@@ -202,4 +471,13 @@ export declare class SandboxFilesystem {
         modifiedTime: number;
         symlinkTarget: string | null;
     }>;
+    /** Changes under `remotePath` until `timeoutMs` passes or the loop stops. */
+    watch(remotePath: string, params?: {
+        filter?: FileWatchEventType[];
+        recursive?: boolean;
+        timeoutMs?: number;
+    }): AsyncIterable<{
+        eventType: FileWatchEventType;
+        paths: string[];
+    }>;
 }