modal 0.3.8 → 0.3.10

package/dist/index.cjs

@@ -46,6 +46,7 @@ __export(index_exports, {
   QueueFullError: () => QueueFullError,
   RemoteError: () => RemoteError,
   Sandbox: () => Sandbox2,
+  SandboxFile: () => SandboxFile,
   Secret: () => Secret
 });
 module.exports = __toCommonJS(index_exports);
@@ -38086,6 +38087,156 @@ ${result.exception}`
   return new Image2(resp.imageId);
 }
 
+// src/errors.ts
+var FunctionTimeoutError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "FunctionTimeoutError";
+  }
+};
+var RemoteError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "RemoteError";
+  }
+};
+var InternalFailure = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "InternalFailure";
+  }
+};
+var NotFoundError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "NotFoundError";
+  }
+};
+var InvalidError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "InvalidError";
+  }
+};
+var QueueEmptyError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "QueueEmptyError";
+  }
+};
+var QueueFullError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "QueueFullError";
+  }
+};
+var SandboxFilesystemError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "SandboxFilesystemError";
+  }
+};
+
+// src/sandbox_filesystem.ts
+var SandboxFile = class {
+  #fileDescriptor;
+  #taskId;
+  /** @ignore */
+  constructor(fileDescriptor, taskId) {
+    this.#fileDescriptor = fileDescriptor;
+    this.#taskId = taskId;
+  }
+  /**
+   * Read data from the file.
+   * @returns Promise that resolves to the read data as Uint8Array
+   */
+  async read() {
+    const resp = await runFilesystemExec({
+      fileReadRequest: {
+        fileDescriptor: this.#fileDescriptor
+      },
+      taskId: this.#taskId
+    });
+    const chunks = resp.chunks;
+    const totalLength = chunks.reduce((acc, chunk) => acc + chunk.length, 0);
+    const result = new Uint8Array(totalLength);
+    let offset = 0;
+    for (const chunk of chunks) {
+      result.set(chunk, offset);
+      offset += chunk.length;
+    }
+    return result;
+  }
+  /**
+   * Write data to the file.
+   * @param data - Data to write (string or Uint8Array)
+   */
+  async write(data) {
+    await runFilesystemExec({
+      fileWriteRequest: {
+        fileDescriptor: this.#fileDescriptor,
+        data
+      },
+      taskId: this.#taskId
+    });
+  }
+  /**
+   * Flush any buffered data to the file.
+   */
+  async flush() {
+    await runFilesystemExec({
+      fileFlushRequest: {
+        fileDescriptor: this.#fileDescriptor
+      },
+      taskId: this.#taskId
+    });
+  }
+  /**
+   * Close the file handle.
+   */
+  async close() {
+    await runFilesystemExec({
+      fileCloseRequest: {
+        fileDescriptor: this.#fileDescriptor
+      },
+      taskId: this.#taskId
+    });
+  }
+};
+async function runFilesystemExec(request) {
+  const response = await client.containerFilesystemExec(request);
+  const chunks = [];
+  let retries = 10;
+  let completed = false;
+  while (!completed) {
+    try {
+      const outputIterator = client.containerFilesystemExecGetOutput({
+        execId: response.execId,
+        timeout: 55
+      });
+      for await (const batch of outputIterator) {
+        chunks.push(...batch.output);
+        if (batch.eof) {
+          completed = true;
+          break;
+        }
+        if (batch.error !== void 0) {
+          if (retries > 0) {
+            retries--;
+            break;
+          }
+          throw new SandboxFilesystemError(batch.error.errorMessage);
+        }
+      }
+    } catch (err) {
+      if (isRetryableGrpc(err) && retries > 0) {
+        retries--;
+      } else throw err;
+    }
+  }
+  return { chunks, response };
+}
+
 // src/streams.ts
 function toModalReadStream(stream) {
   return Object.assign(stream, readMixin);
@@ -38218,28 +38369,52 @@ var Sandbox2 = class {
       ).pipeThrough(new TextDecoderStream())
     );
   }
+  /**
+   * Open a file in the sandbox filesystem.
+   * @param path - Path to the file to open
+   * @param mode - File open mode (r, w, a, r+, w+, a+)
+   * @returns Promise that resolves to a SandboxFile
+   */
+  async open(path2, mode = "r") {
+    const taskId = await this.#getTaskId();
+    const resp = await runFilesystemExec({
+      fileOpenRequest: {
+        path: path2,
+        mode
+      },
+      taskId
+    });
+    const fileDescriptor = resp.response.fileDescriptor;
+    return new SandboxFile(fileDescriptor, taskId);
+  }
   async exec(command, options) {
+    const taskId = await this.#getTaskId();
+    const resp = await client.containerExec({
+      taskId,
+      command,
+      workdir: options?.workdir,
+      timeoutSecs: options?.timeout ? options.timeout / 1e3 : 0
+    });
+    return new ContainerProcess(resp.execId, options);
+  }
+  async #getTaskId() {
     if (this.#taskId === void 0) {
-      const resp2 = await client.sandboxGetTaskId({
+      const resp = await client.sandboxGetTaskId({
         sandboxId: this.sandboxId
       });
-      if (!resp2.taskId) {
+      if (!resp.taskId) {
         throw new Error(
           `Sandbox ${this.sandboxId} does not have a task ID. It may not be running.`
         );
       }
-      if (resp2.taskResult) {
+      if (resp.taskResult) {
         throw new Error(
-          `Sandbox ${this.sandboxId} has already completed with result: ${resp2.taskResult}`
+          `Sandbox ${this.sandboxId} has already completed with result: ${resp.taskResult}`
         );
       }
-      this.#taskId = resp2.taskId;
+      this.#taskId = resp.taskId;
     }
-    const resp = await client.containerExec({
-      taskId: this.#taskId,
-      command
-    });
-    return new ContainerProcess(resp.execId, options);
+    return this.#taskId;
   }
   async terminate() {
     await client.sandboxTerminate({ sandboxId: this.sandboxId });
@@ -38409,50 +38584,6 @@ function encodeIfString(chunk) {
   return typeof chunk === "string" ? new TextEncoder().encode(chunk) : chunk;
 }
 
-// src/errors.ts
-var FunctionTimeoutError = class extends Error {
-  constructor(message) {
-    super(message);
-    this.name = "FunctionTimeoutError";
-  }
-};
-var RemoteError = class extends Error {
-  constructor(message) {
-    super(message);
-    this.name = "RemoteError";
-  }
-};
-var InternalFailure = class extends Error {
-  constructor(message) {
-    super(message);
-    this.name = "InternalFailure";
-  }
-};
-var NotFoundError = class extends Error {
-  constructor(message) {
-    super(message);
-    this.name = "NotFoundError";
-  }
-};
-var InvalidError = class extends Error {
-  constructor(message) {
-    super(message);
-    this.name = "InvalidError";
-  }
-};
-var QueueEmptyError = class extends Error {
-  constructor(message) {
-    super(message);
-    this.name = "QueueEmptyError";
-  }
-};
-var QueueFullError = class extends Error {
-  constructor(message) {
-    super(message);
-    this.name = "QueueFullError";
-  }
-};
-
 // src/secret.ts
 var import_nice_grpc2 = require("nice-grpc");
 var Secret = class _Secret {
@@ -39570,5 +39701,6 @@ var Queue = class _Queue {
   QueueFullError,
   RemoteError,
   Sandbox,
+  SandboxFile,
   Secret
 });

package/dist/index.d.cts

@@ -57,6 +57,36 @@ declare class Image {
     constructor(imageId: string);
 }
 
+/** File open modes supported by the filesystem API. */
+type SandboxFileMode = "r" | "w" | "a" | "r+" | "w+" | "a+";
+/**
+ * SandboxFile represents an open file in the sandbox filesystem.
+ * Provides read/write operations similar to Node.js `fsPromises.FileHandle`.
+ */
+declare class SandboxFile {
+    #private;
+    /** @ignore */
+    constructor(fileDescriptor: string, taskId: string);
+    /**
+     * Read data from the file.
+     * @returns Promise that resolves to the read data as Uint8Array
+     */
+    read(): Promise<Uint8Array>;
+    /**
+     * Write data to the file.
+     * @param data - Data to write (string or Uint8Array)
+     */
+    write(data: Uint8Array): Promise<void>;
+    /**
+     * Flush any buffered data to the file.
+     */
+    flush(): Promise<void>;
+    /**
+     * Close the file handle.
+     */
+    close(): Promise<void>;
+}
+
 /**
  * Wrapper around `ReadableStream` with convenience functions.
  *
@@ -109,9 +139,16 @@ type StdioBehavior = "pipe" | "ignore";
 type StreamMode = "text" | "binary";
 /** Options to configure a `Sandbox.exec()` operation. */
 type ExecOptions = {
+    /** Specifies text or binary encoding for input and output streams. */
     mode?: StreamMode;
+    /** Whether to pipe or ignore standard output. */
     stdout?: StdioBehavior;
+    /** Whether to pipe or ignore standard error. */
     stderr?: StdioBehavior;
+    /** Working directory to run the command in. */
+    workdir?: string;
+    /** Timeout for the process in milliseconds. Defaults to 0 (no timeout). */
+    timeout?: number;
 };
 /** Sandboxes are secure, isolated containers in Modal that boot in seconds. */
 declare class Sandbox {
@@ -122,6 +159,13 @@ declare class Sandbox {
     stderr: ModalReadStream<string>;
     /** @ignore */
     constructor(sandboxId: string);
+    /**
+     * Open a file in the sandbox filesystem.
+     * @param path - Path to the file to open
+     * @param mode - File open mode (r, w, a, r+, w+, a+)
+     * @returns Promise that resolves to a SandboxFile
+     */
+    open(path: string, mode?: SandboxFileMode): Promise<SandboxFile>;
     exec(command: string[], options?: ExecOptions & {
         mode?: "text";
     }): Promise<ContainerProcess<string>>;
@@ -377,4 +421,4 @@ declare class Queue {
     iterate(options?: QueueIterateOptions): AsyncGenerator<any, void, unknown>;
 }
 
-export { App, 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, Secret, type SecretFromNameOptions, type StdioBehavior, type StreamMode };
+export { App, 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, Secret, type SecretFromNameOptions, type StdioBehavior, type StreamMode };

package/dist/index.d.ts

@@ -57,6 +57,36 @@ declare class Image {
     constructor(imageId: string);
 }
 
+/** File open modes supported by the filesystem API. */
+type SandboxFileMode = "r" | "w" | "a" | "r+" | "w+" | "a+";
+/**
+ * SandboxFile represents an open file in the sandbox filesystem.
+ * Provides read/write operations similar to Node.js `fsPromises.FileHandle`.
+ */
+declare class SandboxFile {
+    #private;
+    /** @ignore */
+    constructor(fileDescriptor: string, taskId: string);
+    /**
+     * Read data from the file.
+     * @returns Promise that resolves to the read data as Uint8Array
+     */
+    read(): Promise<Uint8Array>;
+    /**
+     * Write data to the file.
+     * @param data - Data to write (string or Uint8Array)
+     */
+    write(data: Uint8Array): Promise<void>;
+    /**
+     * Flush any buffered data to the file.
+     */
+    flush(): Promise<void>;
+    /**
+     * Close the file handle.
+     */
+    close(): Promise<void>;
+}
+
 /**
  * Wrapper around `ReadableStream` with convenience functions.
  *
@@ -109,9 +139,16 @@ type StdioBehavior = "pipe" | "ignore";
 type StreamMode = "text" | "binary";
 /** Options to configure a `Sandbox.exec()` operation. */
 type ExecOptions = {
+    /** Specifies text or binary encoding for input and output streams. */
     mode?: StreamMode;
+    /** Whether to pipe or ignore standard output. */
     stdout?: StdioBehavior;
+    /** Whether to pipe or ignore standard error. */
     stderr?: StdioBehavior;
+    /** Working directory to run the command in. */
+    workdir?: string;
+    /** Timeout for the process in milliseconds. Defaults to 0 (no timeout). */
+    timeout?: number;
 };
 /** Sandboxes are secure, isolated containers in Modal that boot in seconds. */
 declare class Sandbox {
@@ -122,6 +159,13 @@ declare class Sandbox {
     stderr: ModalReadStream<string>;
     /** @ignore */
     constructor(sandboxId: string);
+    /**
+     * Open a file in the sandbox filesystem.
+     * @param path - Path to the file to open
+     * @param mode - File open mode (r, w, a, r+, w+, a+)
+     * @returns Promise that resolves to a SandboxFile
+     */
+    open(path: string, mode?: SandboxFileMode): Promise<SandboxFile>;
     exec(command: string[], options?: ExecOptions & {
         mode?: "text";
     }): Promise<ContainerProcess<string>>;
@@ -377,4 +421,4 @@ declare class Queue {
     iterate(options?: QueueIterateOptions): AsyncGenerator<any, void, unknown>;
 }
 
-export { App, 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, Secret, type SecretFromNameOptions, type StdioBehavior, type StreamMode };
+export { App, 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, Secret, type SecretFromNameOptions, type StdioBehavior, type StreamMode };

package/dist/index.js

@@ -38040,6 +38040,156 @@ ${result.exception}`
   return new Image2(resp.imageId);
 }
 
+// src/errors.ts
+var FunctionTimeoutError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "FunctionTimeoutError";
+  }
+};
+var RemoteError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "RemoteError";
+  }
+};
+var InternalFailure = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "InternalFailure";
+  }
+};
+var NotFoundError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "NotFoundError";
+  }
+};
+var InvalidError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "InvalidError";
+  }
+};
+var QueueEmptyError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "QueueEmptyError";
+  }
+};
+var QueueFullError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "QueueFullError";
+  }
+};
+var SandboxFilesystemError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "SandboxFilesystemError";
+  }
+};
+
+// src/sandbox_filesystem.ts
+var SandboxFile = class {
+  #fileDescriptor;
+  #taskId;
+  /** @ignore */
+  constructor(fileDescriptor, taskId) {
+    this.#fileDescriptor = fileDescriptor;
+    this.#taskId = taskId;
+  }
+  /**
+   * Read data from the file.
+   * @returns Promise that resolves to the read data as Uint8Array
+   */
+  async read() {
+    const resp = await runFilesystemExec({
+      fileReadRequest: {
+        fileDescriptor: this.#fileDescriptor
+      },
+      taskId: this.#taskId
+    });
+    const chunks = resp.chunks;
+    const totalLength = chunks.reduce((acc, chunk) => acc + chunk.length, 0);
+    const result = new Uint8Array(totalLength);
+    let offset = 0;
+    for (const chunk of chunks) {
+      result.set(chunk, offset);
+      offset += chunk.length;
+    }
+    return result;
+  }
+  /**
+   * Write data to the file.
+   * @param data - Data to write (string or Uint8Array)
+   */
+  async write(data) {
+    await runFilesystemExec({
+      fileWriteRequest: {
+        fileDescriptor: this.#fileDescriptor,
+        data
+      },
+      taskId: this.#taskId
+    });
+  }
+  /**
+   * Flush any buffered data to the file.
+   */
+  async flush() {
+    await runFilesystemExec({
+      fileFlushRequest: {
+        fileDescriptor: this.#fileDescriptor
+      },
+      taskId: this.#taskId
+    });
+  }
+  /**
+   * Close the file handle.
+   */
+  async close() {
+    await runFilesystemExec({
+      fileCloseRequest: {
+        fileDescriptor: this.#fileDescriptor
+      },
+      taskId: this.#taskId
+    });
+  }
+};
+async function runFilesystemExec(request) {
+  const response = await client.containerFilesystemExec(request);
+  const chunks = [];
+  let retries = 10;
+  let completed = false;
+  while (!completed) {
+    try {
+      const outputIterator = client.containerFilesystemExecGetOutput({
+        execId: response.execId,
+        timeout: 55
+      });
+      for await (const batch of outputIterator) {
+        chunks.push(...batch.output);
+        if (batch.eof) {
+          completed = true;
+          break;
+        }
+        if (batch.error !== void 0) {
+          if (retries > 0) {
+            retries--;
+            break;
+          }
+          throw new SandboxFilesystemError(batch.error.errorMessage);
+        }
+      }
+    } catch (err) {
+      if (isRetryableGrpc(err) && retries > 0) {
+        retries--;
+      } else throw err;
+    }
+  }
+  return { chunks, response };
+}
+
 // src/streams.ts
 function toModalReadStream(stream) {
   return Object.assign(stream, readMixin);
@@ -38172,28 +38322,52 @@ var Sandbox2 = class {
       ).pipeThrough(new TextDecoderStream())
     );
   }
+  /**
+   * Open a file in the sandbox filesystem.
+   * @param path - Path to the file to open
+   * @param mode - File open mode (r, w, a, r+, w+, a+)
+   * @returns Promise that resolves to a SandboxFile
+   */
+  async open(path2, mode = "r") {
+    const taskId = await this.#getTaskId();
+    const resp = await runFilesystemExec({
+      fileOpenRequest: {
+        path: path2,
+        mode
+      },
+      taskId
+    });
+    const fileDescriptor = resp.response.fileDescriptor;
+    return new SandboxFile(fileDescriptor, taskId);
+  }
   async exec(command, options) {
+    const taskId = await this.#getTaskId();
+    const resp = await client.containerExec({
+      taskId,
+      command,
+      workdir: options?.workdir,
+      timeoutSecs: options?.timeout ? options.timeout / 1e3 : 0
+    });
+    return new ContainerProcess(resp.execId, options);
+  }
+  async #getTaskId() {
     if (this.#taskId === void 0) {
-      const resp2 = await client.sandboxGetTaskId({
+      const resp = await client.sandboxGetTaskId({
         sandboxId: this.sandboxId
       });
-      if (!resp2.taskId) {
+      if (!resp.taskId) {
         throw new Error(
           `Sandbox ${this.sandboxId} does not have a task ID. It may not be running.`
         );
       }
-      if (resp2.taskResult) {
+      if (resp.taskResult) {
         throw new Error(
-          `Sandbox ${this.sandboxId} has already completed with result: ${resp2.taskResult}`
+          `Sandbox ${this.sandboxId} has already completed with result: ${resp.taskResult}`
         );
       }
-      this.#taskId = resp2.taskId;
+      this.#taskId = resp.taskId;
     }
-    const resp = await client.containerExec({
-      taskId: this.#taskId,
-      command
-    });
-    return new ContainerProcess(resp.execId, options);
+    return this.#taskId;
   }
   async terminate() {
     await client.sandboxTerminate({ sandboxId: this.sandboxId });
@@ -38363,50 +38537,6 @@ function encodeIfString(chunk) {
   return typeof chunk === "string" ? new TextEncoder().encode(chunk) : chunk;
 }
 
-// src/errors.ts
-var FunctionTimeoutError = class extends Error {
-  constructor(message) {
-    super(message);
-    this.name = "FunctionTimeoutError";
-  }
-};
-var RemoteError = class extends Error {
-  constructor(message) {
-    super(message);
-    this.name = "RemoteError";
-  }
-};
-var InternalFailure = class extends Error {
-  constructor(message) {
-    super(message);
-    this.name = "InternalFailure";
-  }
-};
-var NotFoundError = class extends Error {
-  constructor(message) {
-    super(message);
-    this.name = "NotFoundError";
-  }
-};
-var InvalidError = class extends Error {
-  constructor(message) {
-    super(message);
-    this.name = "InvalidError";
-  }
-};
-var QueueEmptyError = class extends Error {
-  constructor(message) {
-    super(message);
-    this.name = "QueueEmptyError";
-  }
-};
-var QueueFullError = class extends Error {
-  constructor(message) {
-    super(message);
-    this.name = "QueueFullError";
-  }
-};
-
 // src/secret.ts
 import { ClientError as ClientError2, Status as Status2 } from "nice-grpc";
 var Secret = class _Secret {
@@ -39523,5 +39653,6 @@ export {
   QueueFullError,
   RemoteError,
   Sandbox2 as Sandbox,
+  SandboxFile,
   Secret
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "modal",
-  "version": "0.3.8",
+  "version": "0.3.10",
   "description": "Modal client library for JavaScript",
   "license": "Apache-2.0",
   "homepage": "https://modal.com/docs",