modal 0.3.17 → 0.3.19

package/dist/index.d.cts

@@ -89,6 +89,12 @@ declare class Image {
     /** @ignore */
     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.
      *
@@ -111,10 +117,11 @@ declare class Image {
      */
     static fromGcpArtifactRegistry(tag: string, secret: Secret): Image;
     /**
-     * @internal
-     * Build image object
+     * Eagerly builds an `Image` on Modal.
+     *
+     * @param app - App to use to build image.
      */
-    _build(appId: string): Promise<Image>;
+    build(app: App): Promise<Image>;
 }
 
 /** File open modes supported by the filesystem API. */
@@ -219,7 +226,7 @@ type ExecOptions = {
     /** Timeout for the process in milliseconds. Defaults to 0 (no timeout). */
     timeout?: number;
     /** Secrets with environment variables for the command. */
-    secrets?: [Secret];
+    secrets?: Secret[];
 };
 /** A port forwarded from within a running Modal sandbox. */
 declare class Tunnel {
@@ -252,6 +259,17 @@ declare class Sandbox {
      * @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
@@ -306,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;
@@ -313,15 +340,23 @@ 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, name?: string, readOnly?: boolean);
+    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()`. */
@@ -410,6 +445,8 @@ type SandboxCreateOptions = {
     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 {
@@ -504,14 +541,60 @@ declare class Function_ {
     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 {
@@ -536,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);
@@ -598,7 +685,7 @@ declare class Queue {
     readonly queueId: string;
     readonly name?: string;
     /** @ignore */
-    constructor(queueId: string, name?: 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.
@@ -654,4 +741,4 @@ declare class Queue {
     iterate(options?: QueueIterateOptions): AsyncGenerator<any, void, unknown>;
 }
 
-export { App, type ClientOptions, CloudBucketMount, Cls, ClsInstance, 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, Sandbox, type SandboxCreateOptions, SandboxFile, type SandboxFileMode, type SandboxListOptions, SandboxTimeoutError, Secret, type SecretFromNameOptions, type StdioBehavior, type StreamMode, Tunnel, type UpdateAutoscalerOptions, 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 };

package/dist/index.d.ts

@@ -89,6 +89,12 @@ declare class Image {
     /** @ignore */
     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.
      *
@@ -111,10 +117,11 @@ declare class Image {
      */
     static fromGcpArtifactRegistry(tag: string, secret: Secret): Image;
     /**
-     * @internal
-     * Build image object
+     * Eagerly builds an `Image` on Modal.
+     *
+     * @param app - App to use to build image.
      */
-    _build(appId: string): Promise<Image>;
+    build(app: App): Promise<Image>;
 }
 
 /** File open modes supported by the filesystem API. */
@@ -219,7 +226,7 @@ type ExecOptions = {
     /** Timeout for the process in milliseconds. Defaults to 0 (no timeout). */
     timeout?: number;
     /** Secrets with environment variables for the command. */
-    secrets?: [Secret];
+    secrets?: Secret[];
 };
 /** A port forwarded from within a running Modal sandbox. */
 declare class Tunnel {
@@ -252,6 +259,17 @@ declare class Sandbox {
      * @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
@@ -306,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;
@@ -313,15 +340,23 @@ 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, name?: string, readOnly?: boolean);
+    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()`. */
@@ -410,6 +445,8 @@ type SandboxCreateOptions = {
     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 {
@@ -504,14 +541,60 @@ declare class Function_ {
     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 {
@@ -536,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);
@@ -598,7 +685,7 @@ declare class Queue {
     readonly queueId: string;
     readonly name?: string;
     /** @ignore */
-    constructor(queueId: string, name?: 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.
@@ -654,4 +741,4 @@ declare class Queue {
     iterate(options?: QueueIterateOptions): AsyncGenerator<any, void, unknown>;
 }
 
-export { App, type ClientOptions, CloudBucketMount, Cls, ClsInstance, 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, Sandbox, type SandboxCreateOptions, SandboxFile, type SandboxFileMode, type SandboxListOptions, SandboxTimeoutError, Secret, type SecretFromNameOptions, type StdioBehavior, type StreamMode, Tunnel, type UpdateAutoscalerOptions, 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 };