modal 0.3.16 → 0.3.18

package/dist/index.d.cts

@@ -15,6 +15,15 @@ declare enum ParameterType {
     PARAM_TYPE_BOOL = 9,
     UNRECOGNIZED = -1
 }
+declare enum RegistryAuthType {
+    /** REGISTRY_AUTH_TYPE_UNSPECIFIED - Older clients send this instead of "public". */
+    REGISTRY_AUTH_TYPE_UNSPECIFIED = 0,
+    REGISTRY_AUTH_TYPE_AWS = 1,
+    REGISTRY_AUTH_TYPE_GCP = 2,
+    REGISTRY_AUTH_TYPE_PUBLIC = 3,
+    REGISTRY_AUTH_TYPE_STATIC_CREDS = 4,
+    UNRECOGNIZED = -1
+}
 /** TODO: rename into NamedPayloadType or similar */
 interface ClassParameterSpec {
     name: string;
@@ -37,6 +46,11 @@ interface GenericPayloadType {
     subTypes: GenericPayloadType[];
 }
 declare const GenericPayloadType: MessageFns<GenericPayloadType>;
+interface ImageRegistryConfig {
+    registryAuthType: RegistryAuthType;
+    secretId: string;
+}
+declare const ImageRegistryConfig: MessageFns<ImageRegistryConfig>;
 type Builtin = Date | Function | Uint8Array | string | number | boolean | undefined;
 type DeepPartial<T> = T extends Builtin ? T : T extends globalThis.Array<infer U> ? globalThis.Array<DeepPartial<U>> : T extends ReadonlyArray<infer U> ? ReadonlyArray<DeepPartial<U>> : T extends {} ? {
     [K in keyof T]?: DeepPartial<T[K]>;
@@ -50,11 +64,64 @@ interface MessageFns<T> {
     fromPartial(object: DeepPartial<T>): T;
 }
 
+/** Options for `Secret.fromName()`. */
+type SecretFromNameOptions = {
+    environment?: string;
+    requiredKeys?: string[];
+};
+/** Secrets provide a dictionary of environment variables for images. */
+declare class Secret {
+    readonly secretId: string;
+    readonly name?: string;
+    /** @ignore */
+    constructor(secretId: string, name?: string);
+    /** Reference a Secret by its name. */
+    static fromName(name: string, options?: SecretFromNameOptions): Promise<Secret>;
+    /** Create a Secret from a plain object of key-value pairs. */
+    static fromObject(entries: Record<string, string>, options?: {
+        environment?: string;
+    }): Promise<Secret>;
+}
+
 /** A container image, used for starting sandboxes. */
 declare class Image {
-    readonly imageId: string;
+    #private;
     /** @ignore */
-    constructor(imageId: string);
+    constructor(imageId: string, tag: string, imageRegistryConfig?: ImageRegistryConfig);
+    get imageId(): string;
+    /**
+     * Creates an `Image` instance from an image id
+     *
+     * @param imageId - Image id.
+     */
+    static fromId(imageId: string): Image;
+    /**
+     * Creates an `Image` instance from a raw registry tag, optionally using a secret for authentication.
+     *
+     * @param tag - The registry tag for the image.
+     * @param secret - Optional. A `Secret` instance containing credentials for registry authentication.
+     */
+    static fromRegistry(tag: string, secret?: Secret): Image;
+    /**
+     * Creates an `Image` instance from a raw registry tag, optionally using a secret for authentication.
+     *
+     * @param tag - The registry tag for the image.
+     * @param secret - A `Secret` instance containing credentials for registry authentication.
+     */
+    static fromAwsEcr(tag: string, secret: Secret): Image;
+    /**
+     * Creates an `Image` instance from a raw registry tag, optionally using a secret for authentication.
+     *
+     * @param tag - The registry tag for the image.
+     * @param secret - A `Secret` instance containing credentials for registry authentication.
+     */
+    static fromGcpArtifactRegistry(tag: string, secret: Secret): Image;
+    /**
+     * Eagerly builds an `Image` on Modal.
+     *
+     * @param app - App to use to build image.
+     */
+    build(app: App): Promise<Image>;
 }
 
 /** File open modes supported by the filesystem API. */
@@ -124,20 +191,6 @@ interface ModalWriteStream<R = any> extends WritableStream<R> {
     writeBytes(bytes: Uint8Array): Promise<void>;
 }
 
-/** Options for `Secret.fromName()`. */
-type SecretFromNameOptions = {
-    environment?: string;
-    requiredKeys?: string[];
-};
-/** Secrets provide a dictionary of environment variables for images. */
-declare class Secret {
-    readonly secretId: string;
-    /** @ignore */
-    constructor(secretId: string);
-    /** Reference a Secret by its name. */
-    static fromName(name: string, options?: SecretFromNameOptions): Promise<Secret>;
-}
-
 /**
  * Stdin is always present, but this option allow you to drop stdout or stderr
  * if you don't need them. The default is "pipe", matching Node.js behavior.
@@ -151,6 +204,15 @@ type StdioBehavior = "pipe" | "ignore";
  * means the data will be read as raw bytes (Uint8Array).
  */
 type StreamMode = "text" | "binary";
+/** Options for `Sandbox.list()`. */
+type SandboxListOptions = {
+    /** Filter sandboxes for a specific app. */
+    appId?: string;
+    /** Only return sandboxes that include all specified tags. */
+    tags?: Record<string, string>;
+    /** Override environment for the request; defaults to current profile. */
+    environment?: string;
+};
 /** Options to configure a `Sandbox.exec()` operation. */
 type ExecOptions = {
     /** Specifies text or binary encoding for input and output streams. */
@@ -190,11 +252,24 @@ declare class Sandbox {
     stderr: ModalReadStream<string>;
     /** @ignore */
     constructor(sandboxId: string);
+    /** Set tags (key-value pairs) on the Sandbox. Tags can be used to filter results in `Sandbox.list`. */
+    setTags(tags: Record<string, string>): Promise<void>;
     /** Returns a running Sandbox object from an ID.
      *
      * @returns Sandbox with ID
      */
     static fromId(sandboxId: string): Promise<Sandbox>;
+    /** Get a running Sandbox by name from a deployed App.
+     *
+     * Raises a NotFoundError if no running Sandbox is found with the given name.
+     * A Sandbox's name is the `name` argument passed to `App.createSandbox`.
+     *
+     * @param appName - Name of the deployed app
+     * @param name - Name of the sandbox
+     * @param environment - Optional override for the environment
+     * @returns Promise that resolves to a Sandbox
+     */
+    static fromName(appName: string, name: string, environment?: string): Promise<Sandbox>;
     /**
      * Open a file in the sandbox filesystem.
      * @param path - Path to the file to open
@@ -232,6 +307,11 @@ declare class Sandbox {
      * Returns `null` if the Sandbox is still running, else returns the exit code.
      */
     poll(): Promise<number | null>;
+    /**
+     * List all Sandboxes for the current Environment or App ID (if specified).
+     * If tags are specified, only Sandboxes that have at least those tags are returned.
+     */
+    static list(options?: SandboxListOptions): AsyncGenerator<Sandbox, void, unknown>;
 }
 declare class ContainerProcess<R extends string | Uint8Array = any> {
     #private;
@@ -244,6 +324,15 @@ declare class ContainerProcess<R extends string | Uint8Array = any> {
     wait(): Promise<number>;
 }
 
+type HeartbeatFunction = () => Promise<any>;
+declare class EphemeralHeartbeatManager {
+    private readonly heartbeatFn;
+    private readonly abortController;
+    constructor(heartbeatFn: HeartbeatFunction);
+    private start;
+    stop(): void;
+}
+
 /** Options for `Volume.fromName()`. */
 type VolumeFromNameOptions = {
     environment?: string;
@@ -251,10 +340,55 @@ type VolumeFromNameOptions = {
 };
 /** Volumes provide persistent storage that can be mounted in Modal functions. */
 declare class Volume {
+    #private;
     readonly volumeId: string;
+    readonly name?: string;
+    private _readOnly;
     /** @ignore */
-    constructor(volumeId: string);
+    constructor(volumeId: string, name?: string, readOnly?: boolean, ephemeralHbManager?: EphemeralHeartbeatManager);
     static fromName(name: string, options?: VolumeFromNameOptions): Promise<Volume>;
+    /** Configure Volume to mount as read-only. */
+    readOnly(): Volume;
+    get isReadOnly(): boolean;
+    /**
+     * Create a nameless, temporary volume.
+     * You will need to call `closeEphemeral()` to delete the volume.
+     */
+    static ephemeral(options?: EphemeralOptions): Promise<Volume>;
+    /** Delete the ephemeral volume. Only usable with `Volume.ephemeral()`. */
+    closeEphemeral(): void;
+}
+
+/** Options for `Proxy.fromName()`. */
+type ProxyFromNameOptions = {
+    environment?: string;
+};
+/** Proxy objects give your Modal containers a static outbound IP address. */
+declare class Proxy {
+    readonly proxyId: string;
+    /** @ignore */
+    constructor(proxyId: string);
+    /** Reference a Proxy by its name. */
+    static fromName(name: string, options?: ProxyFromNameOptions): Promise<Proxy>;
+}
+
+/** Cloud bucket mounts provide access to cloud storage buckets within Modal functions. */
+declare class CloudBucketMount {
+    readonly bucketName: string;
+    readonly secret?: Secret;
+    readonly readOnly: boolean;
+    readonly requesterPays: boolean;
+    readonly bucketEndpointUrl?: string;
+    readonly keyPrefix?: string;
+    readonly oidcAuthRoleArn?: string;
+    constructor(bucketName: string, options?: {
+        secret?: Secret;
+        readOnly?: boolean;
+        requesterPays?: boolean;
+        bucketEndpointUrl?: string;
+        keyPrefix?: string;
+        oidcAuthRoleArn?: string;
+    });
 }
 
 /** Options for functions that find deployed Modal objects. */
@@ -276,8 +410,12 @@ type SandboxCreateOptions = {
     cpu?: number;
     /** Reservation of memory in MiB. */
     memory?: number;
+    /** GPU reservation for the sandbox (e.g. "A100", "T4:2", "A100-80GB:4"). */
+    gpu?: string;
     /** Timeout of the sandbox container, defaults to 10 minutes. */
     timeout?: number;
+    /** Working directory of the sandbox. */
+    workdir?: string;
     /**
      * Sequence of program arguments for the main process.
      * Default behavior is to sleep indefinitely until timeout or termination.
@@ -287,23 +425,49 @@ type SandboxCreateOptions = {
     secrets?: Secret[];
     /** Mount points for Modal Volumes. */
     volumes?: Record<string, Volume>;
+    /** Mount points for cloud buckets. */
+    cloudBucketMounts?: Record<string, CloudBucketMount>;
     /** List of ports to tunnel into the sandbox. Encrypted ports are tunneled with TLS. */
     encryptedPorts?: number[];
     /** List of encrypted ports to tunnel into the sandbox, using HTTP/2. */
     h2Ports?: number[];
     /** List of ports to tunnel into the sandbox without encryption. */
     unencryptedPorts?: number[];
+    /** Whether to block all network access from the sandbox. */
+    blockNetwork?: boolean;
+    /** List of CIDRs the sandbox is allowed to access. If None, all CIDRs are allowed. Cannot be used with blockNetwork. */
+    cidrAllowlist?: string[];
+    /** Cloud provider to run the sandbox on. */
+    cloud?: string;
+    /** Region(s) to run the sandbox on. */
+    regions?: string[];
+    /** Enable verbose logging. */
+    verbose?: boolean;
+    /** Reference to a Modal Proxy to use in front of this Sandbox. */
+    proxy?: Proxy;
+    /** Optional name for the sandbox. Unique within an app. */
+    name?: string;
 };
 /** Represents a deployed Modal App. */
 declare class App {
     readonly appId: string;
+    readonly name?: string;
     /** @ignore */
-    constructor(appId: string);
+    constructor(appId: string, name?: string);
     /** Lookup a deployed app by name, or create if it does not exist. */
     static lookup(name: string, options?: LookupOptions): Promise<App>;
     createSandbox(image: Image, options?: SandboxCreateOptions): Promise<Sandbox>;
+    /**
+     * @deprecated Use `Image.fromRegistry` instead.
+     */
     imageFromRegistry(tag: string, secret?: Secret): Promise<Image>;
+    /**
+     * @deprecated Use `Image.fromAwsEcr` instead.
+     */
     imageFromAwsEcr(tag: string, secret: Secret): Promise<Image>;
+    /**
+     * @deprecated Use `Image.fromGcpArtifactRegistry` instead.
+     */
     imageFromGcpArtifactRegistry(tag: string, secret: Secret): Promise<Image>;
 }
 
@@ -346,26 +510,91 @@ declare class FunctionCall {
     cancel(options?: FunctionCallCancelOptions): Promise<void>;
 }
 
+/** Simple data structure storing stats for a running Function. */
+interface FunctionStats {
+    backlog: number;
+    numTotalRunners: number;
+}
+/** Options for overriding a Function's autoscaler behavior. */
+interface UpdateAutoscalerOptions {
+    minContainers?: number;
+    maxContainers?: number;
+    bufferContainers?: number;
+    scaledownWindow?: number;
+}
 /** Represents a deployed Modal Function, which can be invoked remotely. */
 declare class Function_ {
     #private;
     readonly functionId: string;
     readonly methodName?: string;
     /** @ignore */
-    constructor(functionId: string, methodName?: string, inputPlaneUrl?: string);
+    constructor(functionId: string, methodName?: string, inputPlaneUrl?: string, webUrl?: string);
     static lookup(appName: string, name: string, options?: LookupOptions): Promise<Function_>;
     remote(args?: any[], kwargs?: Record<string, any>): Promise<any>;
     spawn(args?: any[], kwargs?: Record<string, any>): Promise<FunctionCall>;
+    getCurrentStats(): Promise<FunctionStats>;
+    updateAutoscaler(options: UpdateAutoscalerOptions): Promise<void>;
+    /**
+     * URL of a Function running as a web endpoint.
+     * @returns The web URL if this function is a web endpoint, otherwise undefined
+     */
+    getWebUrl(): Promise<string | undefined>;
+}
+
+/** Retry policy configuration for a Modal Function/Cls. */
+declare class Retries {
+    readonly maxRetries: number;
+    readonly backoffCoefficient: number;
+    readonly initialDelayMs: number;
+    readonly maxDelayMs: number;
+    constructor(options: {
+        maxRetries: number;
+        backoffCoefficient?: number;
+        initialDelayMs?: number;
+        maxDelayMs?: number;
+    });
 }
 
+type ClsOptions = {
+    cpu?: number;
+    memory?: number;
+    gpu?: string;
+    secrets?: Secret[];
+    volumes?: Record<string, Volume>;
+    retries?: number | Retries;
+    maxContainers?: number;
+    bufferContainers?: number;
+    scaledownWindow?: number;
+    timeout?: number;
+};
+type ClsConcurrencyOptions = {
+    maxInputs: number;
+    targetInputs?: number;
+};
+type ClsBatchingOptions = {
+    maxBatchSize: number;
+    waitMs: number;
+};
+type ServiceOptions = ClsOptions & {
+    maxConcurrentInputs?: number;
+    targetConcurrentInputs?: number;
+    batchMaxSize?: number;
+    batchWaitMs?: number;
+};
 /** Represents a deployed Modal Cls. */
 declare class Cls {
     #private;
     /** @ignore */
-    constructor(serviceFunctionId: string, schema: ClassParameterSpec[], methodNames: string[], inputPlaneUrl?: string);
+    constructor(serviceFunctionId: string, schema: ClassParameterSpec[], methodNames: string[], inputPlaneUrl?: string, options?: ServiceOptions);
     static lookup(appName: string, name: string, options?: LookupOptions): Promise<Cls>;
-    /** Create a new instance of the Cls with parameters. */
+    /** Create a new instance of the Cls with parameters and/or runtime options. */
     instance(params?: Record<string, any>): Promise<ClsInstance>;
+    /** Override the static Function configuration at runtime. */
+    withOptions(options: ClsOptions): Cls;
+    /** Create an instance of the Cls with input concurrency enabled or overridden with new values. */
+    withConcurrency(options: ClsConcurrencyOptions): Cls;
+    /** Create an instance of the Cls with dynamic batching enabled or overridden with new values. */
+    withBatching(options: ClsBatchingOptions): Cls;
 }
 /** Represents an instance of a deployed Modal Cls, optionally with parameters. */
 declare class ClsInstance {
@@ -390,6 +619,10 @@ declare class InternalFailure extends Error {
 declare class NotFoundError extends Error {
     constructor(message: string);
 }
+/** A resource already exists. */
+declare class AlreadyExistsError extends Error {
+    constructor(message: string);
+}
 /** A request or other operation was invalid. */
 declare class InvalidError extends Error {
     constructor(message: string);
@@ -450,8 +683,9 @@ type QueueIterateOptions = {
 declare class Queue {
     #private;
     readonly queueId: string;
+    readonly name?: string;
     /** @ignore */
-    constructor(queueId: string, ephemeral?: boolean);
+    constructor(queueId: string, name?: string, ephemeralHbManager?: EphemeralHeartbeatManager);
     /**
      * Create a nameless, temporary queue.
      * You will need to call `closeEphemeral()` to delete the queue.
@@ -507,4 +741,4 @@ declare class Queue {
     iterate(options?: QueueIterateOptions): AsyncGenerator<any, void, unknown>;
 }
 
-export { App, type ClientOptions, Cls, ClsInstance, ContainerProcess, type DeleteOptions, type EphemeralOptions, type ExecOptions, FunctionCall, type FunctionCallCancelOptions, type FunctionCallGetOptions, FunctionTimeoutError, Function_, Image, InternalFailure, InvalidError, type LookupOptions, type ModalReadStream, type ModalWriteStream, NotFoundError, Queue, type QueueClearOptions, QueueEmptyError, QueueFullError, type QueueGetOptions, type QueueIterateOptions, type QueueLenOptions, type QueuePutOptions, RemoteError, Sandbox, type SandboxCreateOptions, SandboxFile, type SandboxFileMode, SandboxTimeoutError, Secret, type SecretFromNameOptions, type StdioBehavior, type StreamMode, Tunnel, Volume, type VolumeFromNameOptions, initializeClient };
+export { AlreadyExistsError, App, type ClientOptions, CloudBucketMount, Cls, type ClsBatchingOptions, type ClsConcurrencyOptions, ClsInstance, type ClsOptions, ContainerProcess, type DeleteOptions, type EphemeralOptions, type ExecOptions, FunctionCall, type FunctionCallCancelOptions, type FunctionCallGetOptions, type FunctionStats, FunctionTimeoutError, Function_, Image, InternalFailure, InvalidError, type LookupOptions, type ModalReadStream, type ModalWriteStream, NotFoundError, Proxy, type ProxyFromNameOptions, Queue, type QueueClearOptions, QueueEmptyError, QueueFullError, type QueueGetOptions, type QueueIterateOptions, type QueueLenOptions, type QueuePutOptions, RemoteError, Retries, Sandbox, type SandboxCreateOptions, SandboxFile, type SandboxFileMode, type SandboxListOptions, SandboxTimeoutError, Secret, type SecretFromNameOptions, type StdioBehavior, type StreamMode, Tunnel, type UpdateAutoscalerOptions, Volume, type VolumeFromNameOptions, initializeClient };