modal 0.5.0-dev.7 → 0.5.1

package/dist/index.js

@@ -43349,7 +43349,7 @@ function cborDecode(data) {
 }
 
 // src/invocation.ts
-var outputsTimeout = 55 * 1e3;
+var outputsTimeoutMs = 55 * 1e3;
 var ControlPlaneInvocation = class _ControlPlaneInvocation {
   cpClient;
   functionCallId;
@@ -43385,19 +43385,18 @@ var ControlPlaneInvocation = class _ControlPlaneInvocation {
   static fromFunctionCallId(client2, functionCallId) {
     return new _ControlPlaneInvocation(client2.cpClient, functionCallId);
   }
-  async awaitOutput(timeout) {
+  async awaitOutput(timeoutMs) {
     return await pollFunctionOutput(
       this.cpClient,
-      (timeoutMillis) => this.#getOutput(timeoutMillis),
-      timeout
+      (timeoutMs2) => this.#getOutput(timeoutMs2),
+      timeoutMs
     );
   }
-  async #getOutput(timeoutMillis) {
+  async #getOutput(timeoutMs) {
     const response = await this.cpClient.functionGetOutputs({
       functionCallId: this.functionCallId,
       maxValues: 1,
-      timeout: timeoutMillis / 1e3,
-      // Backend needs seconds
+      timeout: timeoutMs / 1e3,
       lastEntryId: "0-0",
       clearOnSuccess: true,
       requestedAt: timeNowSeconds()
@@ -43451,18 +43450,18 @@ var InputPlaneInvocation = class _InputPlaneInvocation {
       attemptStartResponse.attemptToken
     );
   }
-  async awaitOutput(timeout) {
+  async awaitOutput(timeoutMs) {
     return await pollFunctionOutput(
       this.cpClient,
-      (timeoutMillis) => this.#getOutput(timeoutMillis),
-      timeout
+      (timeoutMs2) => this.#getOutput(timeoutMs2),
+      timeoutMs
     );
   }
-  async #getOutput(timeoutMillis) {
+  async #getOutput(timeoutMs) {
     const response = await this.ipClient.attemptAwait({
       attemptToken: this.attemptToken,
       requestedAt: timeNowSeconds(),
-      timeoutSecs: timeoutMillis / 1e3
+      timeoutSecs: timeoutMs / 1e3
     });
     return response.output;
   }
@@ -43478,24 +43477,24 @@ var InputPlaneInvocation = class _InputPlaneInvocation {
 function timeNowSeconds() {
   return Date.now() / 1e3;
 }
-async function pollFunctionOutput(cpClient, getOutput, timeout) {
+async function pollFunctionOutput(cpClient, getOutput, timeoutMs) {
   const startTime = Date.now();
-  let pollTimeout = outputsTimeout;
-  if (timeout !== void 0) {
-    pollTimeout = Math.min(timeout, outputsTimeout);
+  let pollTimeoutMs = outputsTimeoutMs;
+  if (timeoutMs !== void 0) {
+    pollTimeoutMs = Math.min(timeoutMs, outputsTimeoutMs);
   }
   while (true) {
-    const output = await getOutput(pollTimeout);
+    const output = await getOutput(pollTimeoutMs);
     if (output) {
       return await processResult(cpClient, output.result, output.dataFormat);
     }
-    if (timeout !== void 0) {
-      const remainingTime = timeout - (Date.now() - startTime);
-      if (remainingTime <= 0) {
-        const message = `Timeout exceeded: ${(timeout / 1e3).toFixed(1)}s`;
+    if (timeoutMs !== void 0) {
+      const remainingMs = timeoutMs - (Date.now() - startTime);
+      if (remainingMs <= 0) {
+        const message = `Timeout exceeded: ${timeoutMs}ms`;
         throw new FunctionTimeoutError(message);
       }
-      pollTimeout = Math.min(outputsTimeout, remainingTime);
+      pollTimeoutMs = Math.min(outputsTimeoutMs, remainingMs);
     }
   }
 }
@@ -43550,6 +43549,18 @@ function deserializeDataFormat(data, dataFormat) {
   }
 }
 
+// src/validation.ts
+function checkForRenamedParams(params, renames) {
+  if (!params) return;
+  for (const [oldName, newName] of Object.entries(renames)) {
+    if (oldName in params) {
+      throw new Error(
+        `Parameter '${oldName}' has been renamed to '${newName}'.`
+      );
+    }
+  }
+}
+
 // src/function_call.ts
 var FunctionCallService = class {
   #client;
@@ -43579,12 +43590,12 @@ var FunctionCall = class _FunctionCall {
   }
   /** Get the result of a FunctionCall, optionally waiting with a timeout. */
   async get(params = {}) {
-    const timeout = params.timeout;
+    checkForRenamedParams(params, { timeout: "timeoutMs" });
     const invocation = ControlPlaneInvocation.fromFunctionCallId(
       this.#client || getDefaultClient(),
       this.functionCallId
     );
-    return invocation.awaitOutput(timeout);
+    return invocation.awaitOutput(params.timeoutMs);
   }
   /** Cancel a running FunctionCall. */
   async cancel(params = {}) {
@@ -43624,6 +43635,15 @@ var FunctionService = class {
         objectTag: name,
         environmentName: this.#client.environmentName(params.environment)
       });
+      this.#client.logger.debug(
+        "Retrieved Function",
+        "function_id",
+        resp.functionId,
+        "app_name",
+        appName,
+        "function_name",
+        name
+      );
       return new Function_(
         this.#client,
         resp.functionId,
@@ -43655,16 +43675,42 @@ var Function_ = class {
   static async lookup(appName, name, params = {}) {
     return await getDefaultClient().functions.fromName(appName, name, params);
   }
+  #checkNoWebUrl(fnName) {
+    if (this.#handleMetadata?.webUrl) {
+      throw new InvalidError(
+        `A webhook Function cannot be invoked for remote execution with '.${fnName}'. Invoke this Function via its web url '${this.#handleMetadata.webUrl}' instead.`
+      );
+    }
+  }
   // Execute a single input into a remote Function.
   async remote(args = [], kwargs = {}) {
+    this.#client.logger.debug(
+      "Executing function call",
+      "function_id",
+      this.functionId
+    );
+    this.#checkNoWebUrl("remote");
     const input = await this.#createInput(args, kwargs);
     const invocation = await this.#createRemoteInvocation(input);
     let retryCount = 0;
     while (true) {
       try {
-        return await invocation.awaitOutput();
+        const result = await invocation.awaitOutput();
+        this.#client.logger.debug(
+          "Function call completed",
+          "function_id",
+          this.functionId
+        );
+        return result;
       } catch (err) {
         if (err instanceof InternalFailure && retryCount <= maxSystemRetries) {
+          this.#client.logger.debug(
+            "Retrying function call due to internal failure",
+            "function_id",
+            this.functionId,
+            "retry_count",
+            retryCount
+          );
           await invocation.retry(retryCount);
           retryCount++;
         } else {
@@ -43691,6 +43737,12 @@ var Function_ = class {
   }
   // Spawn a single input into a remote Function.
   async spawn(args = [], kwargs = {}) {
+    this.#client.logger.debug(
+      "Spawning function call",
+      "function_id",
+      this.functionId
+    );
+    this.#checkNoWebUrl("spawn");
     const input = await this.#createInput(args, kwargs);
     const invocation = await ControlPlaneInvocation.create(
       this.#client,
@@ -43698,13 +43750,20 @@ var Function_ = class {
       input,
       3 /* FUNCTION_CALL_INVOCATION_TYPE_ASYNC */
     );
+    this.#client.logger.debug(
+      "Function call spawned",
+      "function_id",
+      this.functionId,
+      "function_call_id",
+      invocation.functionCallId
+    );
     return new FunctionCall(this.#client, invocation.functionCallId);
   }
   // Returns statistics about the Function.
   async getCurrentStats() {
     const resp = await this.#client.cpClient.functionGetCurrentStats(
       { functionId: this.functionId },
-      { timeout: 1e4 }
+      { timeoutMs: 1e4 }
     );
     return {
       backlog: resp.backlog,
@@ -43713,6 +43772,7 @@ var Function_ = class {
   }
   // Overrides the current autoscaler behavior for this Function.
   async updateAutoscaler(params) {
+    checkForRenamedParams(params, { scaledownWindow: "scaledownWindowMs" });
     await this.#client.cpClient.functionUpdateSchedulingParams({
       functionId: this.functionId,
       warmPoolSizeOverride: 0,
@@ -43721,7 +43781,7 @@ var Function_ = class {
         minContainers: params.minContainers,
         maxContainers: params.maxContainers,
         bufferContainers: params.bufferContainers,
-        scaledownWindow: params.scaledownWindow
+        scaledownWindow: params.scaledownWindowMs !== void 0 ? Math.trunc(params.scaledownWindowMs / 1e3) : void 0
       }
     });
   }
@@ -43736,7 +43796,7 @@ var Function_ = class {
     const supported_input_formats = this.#handleMetadata?.supportedInputFormats?.length ? this.#handleMetadata.supportedInputFormats : [1 /* DATA_FORMAT_PICKLE */];
     if (!supported_input_formats.includes(4 /* DATA_FORMAT_CBOR */)) {
       throw new InvalidError(
-        "the deployed Function does not support libmodal - please redeploy it using Modal Python SDK version >= 1.2"
+        "cannot call Modal Function from JS SDK since it was deployed with an incompatible Python SDK version. Redeploy with Modal Python SDK >= 1.2"
       );
     }
     const payload = cborEncode([args, kwargs]);
@@ -43799,6 +43859,13 @@ var SecretService = class {
         environmentName: this.#client.environmentName(params?.environment),
         requiredKeys: params?.requiredKeys ?? []
       });
+      this.#client.logger.debug(
+        "Retrieved Secret",
+        "secret_id",
+        resp.secretId,
+        "secret_name",
+        name
+      );
       return new Secret(resp.secretId, name);
     } catch (err) {
       if (err instanceof ClientError2 && err.code === Status2.NOT_FOUND)
@@ -43823,6 +43890,11 @@ var SecretService = class {
         envDict: entries,
         environmentName: this.#client.environmentName(params?.environment)
       });
+      this.#client.logger.debug(
+        "Created ephemeral Secret",
+        "secret_id",
+        resp.secretId
+      );
       return new Secret(resp.secretId);
     } catch (err) {
       if (err instanceof ClientError2 && (err.code === Status2.INVALID_ARGUMENT || err.code === Status2.FAILED_PRECONDITION))
@@ -43943,6 +44015,15 @@ var ClsService = class {
           `Unsupported parameter format: ${parameterInfo?.format}`
         );
       }
+      this.#client.logger.debug(
+        "Retrieved Cls",
+        "function_id",
+        serviceFunction.functionId,
+        "app_name",
+        appName,
+        "cls_name",
+        name
+      );
       return new Cls(
         this.#client,
         serviceFunction.functionId,
@@ -44073,10 +44154,58 @@ function mergeServiceOptions(base, diff) {
 async function buildFunctionOptionsProto(options) {
   if (!options) return void 0;
   const o = options ?? {};
+  checkForRenamedParams(o, {
+    memory: "memoryMiB",
+    memoryLimit: "memoryLimitMiB",
+    scaledownWindow: "scaledownWindowMs",
+    timeout: "timeoutMs"
+  });
   const gpuConfig = parseGpuConfig(o.gpu);
-  const resources = o.cpu !== void 0 || o.memory !== void 0 || gpuConfig ? {
-    milliCpu: o.cpu !== void 0 ? Math.round(1e3 * o.cpu) : void 0,
-    memoryMb: o.memory,
+  let milliCpu = void 0;
+  let milliCpuMax = void 0;
+  if (o.cpu === void 0 && o.cpuLimit !== void 0) {
+    throw new Error("must also specify cpu when cpuLimit is specified");
+  }
+  if (o.cpu !== void 0) {
+    if (o.cpu <= 0) {
+      throw new Error(`cpu (${o.cpu}) must be a positive number`);
+    }
+    milliCpu = Math.trunc(1e3 * o.cpu);
+    if (o.cpuLimit !== void 0) {
+      if (o.cpuLimit < o.cpu) {
+        throw new Error(
+          `cpu (${o.cpu}) cannot be higher than cpuLimit (${o.cpuLimit})`
+        );
+      }
+      milliCpuMax = Math.trunc(1e3 * o.cpuLimit);
+    }
+  }
+  let memoryMb = void 0;
+  let memoryMbMax = void 0;
+  if (o.memoryMiB === void 0 && o.memoryLimitMiB !== void 0) {
+    throw new Error(
+      "must also specify memoryMiB when memoryLimitMiB is specified"
+    );
+  }
+  if (o.memoryMiB !== void 0) {
+    if (o.memoryMiB <= 0) {
+      throw new Error(`memoryMiB (${o.memoryMiB}) must be a positive number`);
+    }
+    memoryMb = o.memoryMiB;
+    if (o.memoryLimitMiB !== void 0) {
+      if (o.memoryLimitMiB < o.memoryMiB) {
+        throw new Error(
+          `memoryMiB (${o.memoryMiB}) cannot be higher than memoryLimitMiB (${o.memoryLimitMiB})`
+        );
+      }
+      memoryMbMax = o.memoryLimitMiB;
+    }
+  }
+  const resources = milliCpu !== void 0 || milliCpuMax !== void 0 || memoryMb !== void 0 || memoryMbMax !== void 0 || gpuConfig ? {
+    milliCpu,
+    milliCpuMax,
+    memoryMb,
+    memoryMbMax,
     gpuConfig
   } : void 0;
   const secretIds = (o.secrets || []).map((s) => s.secretId);
@@ -44093,13 +44222,15 @@ async function buildFunctionOptionsProto(options) {
     initialDelayMs: parsedRetries.initialDelayMs,
     maxDelayMs: parsedRetries.maxDelayMs
   } : void 0;
-  if (o.scaledownWindow !== void 0 && o.scaledownWindow % 1e3 !== 0) {
+  if (o.scaledownWindowMs !== void 0 && o.scaledownWindowMs % 1e3 !== 0) {
     throw new Error(
-      `scaledownWindow must be a multiple of 1000ms, got ${o.scaledownWindow}`
+      `scaledownWindowMs must be a multiple of 1000ms, got ${o.scaledownWindowMs}`
     );
   }
-  if (o.timeout !== void 0 && o.timeout % 1e3 !== 0) {
-    throw new Error(`timeout must be a multiple of 1000ms, got ${o.timeout}`);
+  if (o.timeoutMs !== void 0 && o.timeoutMs % 1e3 !== 0) {
+    throw new Error(
+      `timeoutMs must be a multiple of 1000ms, got ${o.timeoutMs}`
+    );
   }
   const functionOptions = FunctionOptions.create({
     secretIds,
@@ -44110,8 +44241,8 @@ async function buildFunctionOptionsProto(options) {
     retryPolicy,
     concurrencyLimit: o.maxContainers,
     bufferContainers: o.bufferContainers,
-    taskIdleTimeoutSecs: o.scaledownWindow !== void 0 ? o.scaledownWindow / 1e3 : void 0,
-    timeoutSecs: o.timeout !== void 0 ? o.timeout / 1e3 : void 0,
+    taskIdleTimeoutSecs: o.scaledownWindowMs !== void 0 ? o.scaledownWindowMs / 1e3 : void 0,
+    timeoutSecs: o.timeoutMs !== void 0 ? o.timeoutMs / 1e3 : void 0,
     maxConcurrentInputs: o.maxConcurrentInputs,
     targetConcurrentInputs: o.targetConcurrentInputs,
     batchMaxSize: o.batchMaxSize,
@@ -44271,8 +44402,15 @@ var ImageService = class {
    * Delete an {@link Image} by ID. Warning: This removes an *entire Image*, and cannot be undone.
    */
   async delete(imageId, _ = {}) {
-    const image = await this.fromId(imageId);
-    await this.#client.cpClient.imageDelete({ imageId: image.imageId });
+    try {
+      await this.#client.cpClient.imageDelete({ imageId });
+    } catch (err) {
+      if (err instanceof ClientError4 && err.code === Status4.NOT_FOUND)
+        throw new NotFoundError(err.details);
+      if (err instanceof ClientError4 && err.code === Status4.FAILED_PRECONDITION && err.details.includes("Could not find image with ID"))
+        throw new NotFoundError(err.details);
+      throw err;
+    }
   }
 };
 var Image2 = class _Image {
@@ -44370,6 +44508,7 @@ var Image2 = class _Image {
     if (this.imageId !== "") {
       return this;
     }
+    this.#client.logger.debug("Building image", "app_id", app.appId);
     let baseImageId;
     for (let i = 0; i < this.#layers.length; i++) {
       const layer = this.#layers[i];
@@ -44444,6 +44583,7 @@ ${result.exception}`
       baseImageId = resp.imageId;
     }
     this.#imageId = baseImageId;
+    this.#client.logger.debug("Image build completed", "image_id", baseImageId);
     return this;
   }
   /**
@@ -44891,8 +45031,8 @@ var EphemeralHeartbeatManager = class {
 };
 
 // src/queue.ts
-var queueInitialPutBackoff = 100;
-var queueDefaultPartitionTtl = 24 * 3600 * 1e3;
+var queueInitialPutBackoffMs = 100;
+var queueDefaultPartitionTtlMs = 24 * 3600 * 1e3;
 var QueueService = class {
   #client;
   constructor(client2) {
@@ -44907,6 +45047,11 @@ var QueueService = class {
       objectCreationType: 5 /* OBJECT_CREATION_TYPE_EPHEMERAL */,
       environmentName: this.#client.environmentName(params.environment)
     });
+    this.#client.logger.debug(
+      "Created ephemeral Queue",
+      "queue_id",
+      resp.queueId
+    );
     const ephemeralHbManager = new EphemeralHeartbeatManager(
       () => this.#client.cpClient.queueHeartbeat({ queueId: resp.queueId })
     );
@@ -44921,6 +45066,13 @@ var QueueService = class {
       objectCreationType: params.createIfMissing ? 1 /* OBJECT_CREATION_TYPE_CREATE_IF_MISSING */ : void 0,
       environmentName: this.#client.environmentName(params.environment)
     });
+    this.#client.logger.debug(
+      "Retrieved Queue",
+      "queue_id",
+      resp.queueId,
+      "queue_name",
+      name
+    );
     return new Queue(this.#client, resp.queueId, name);
   }
   /**
@@ -44996,30 +45148,30 @@ var Queue = class _Queue {
       allPartitions: params.all
     });
   }
-  async #get(n, partition, timeout) {
+  async #get(n, partition, timeoutMs) {
     const partitionKey = _Queue.#validatePartitionKey(partition);
     const startTime = Date.now();
-    let pollTimeout = 5e4;
-    if (timeout !== void 0) {
-      pollTimeout = Math.min(pollTimeout, timeout);
+    let pollTimeoutMs = 5e4;
+    if (timeoutMs !== void 0) {
+      pollTimeoutMs = Math.min(pollTimeoutMs, timeoutMs);
     }
     while (true) {
       const response = await this.#client.cpClient.queueGet({
         queueId: this.queueId,
         partitionKey,
-        timeout: pollTimeout / 1e3,
+        timeout: pollTimeoutMs / 1e3,
         nValues: n
       });
       if (response.values && response.values.length > 0) {
         return response.values.map((value) => loads(value));
       }
-      if (timeout !== void 0) {
-        const remaining = timeout - (Date.now() - startTime);
-        if (remaining <= 0) {
-          const message = `Queue ${this.queueId} did not return values within ${timeout}ms.`;
+      if (timeoutMs !== void 0) {
+        const remainingMs = timeoutMs - (Date.now() - startTime);
+        if (remainingMs <= 0) {
+          const message = `Queue ${this.queueId} did not return values within ${timeoutMs}ms.`;
           throw new QueueEmptyError(message);
         }
-        pollTimeout = Math.min(pollTimeout, remaining);
+        pollTimeoutMs = Math.min(pollTimeoutMs, remainingMs);
       }
     }
   }
@@ -45027,35 +45179,37 @@ var Queue = class _Queue {
    * Remove and return the next object from the Queue.
    *
    * By default, this will wait until at least one item is present in the Queue.
-   * If `timeout` is set, raises `QueueEmptyError` if no items are available
+   * If `timeoutMs` is set, raises `QueueEmptyError` if no items are available
    * within that timeout in milliseconds.
    */
   async get(params = {}) {
-    const values = await this.#get(1, params.partition, params.timeout);
+    checkForRenamedParams(params, { timeout: "timeoutMs" });
+    const values = await this.#get(1, params.partition, params.timeoutMs);
     return values[0];
   }
   /**
    * Remove and return up to `n` objects from the Queue.
    *
    * By default, this will wait until at least one item is present in the Queue.
-   * If `timeout` is set, raises `QueueEmptyError` if no items are available
+   * If `timeoutMs` is set, raises `QueueEmptyError` if no items are available
    * within that timeout in milliseconds.
    */
   async getMany(n, params = {}) {
-    return await this.#get(n, params.partition, params.timeout);
+    checkForRenamedParams(params, { timeout: "timeoutMs" });
+    return await this.#get(n, params.partition, params.timeoutMs);
   }
-  async #put(values, timeout, partition, partitionTtl) {
+  async #put(values, timeoutMs, partition, partitionTtlMs) {
     const valuesEncoded = values.map((v) => dumps(v));
     const partitionKey = _Queue.#validatePartitionKey(partition);
-    let delay = queueInitialPutBackoff;
-    const deadline = timeout ? Date.now() + timeout : void 0;
+    let delay = queueInitialPutBackoffMs;
+    const deadline = timeoutMs ? Date.now() + timeoutMs : void 0;
     while (true) {
       try {
         await this.#client.cpClient.queuePut({
           queueId: this.queueId,
           values: valuesEncoded,
           partitionKey,
-          partitionTtlSeconds: (partitionTtl || queueDefaultPartitionTtl) / 1e3
+          partitionTtlSeconds: (partitionTtlMs || queueDefaultPartitionTtlMs) / 1e3
         });
         break;
       } catch (e) {
@@ -45078,25 +45232,38 @@ var Queue = class _Queue {
    * Add an item to the end of the Queue.
    *
    * If the Queue is full, this will retry with exponential backoff until the
-   * provided `timeout` is reached, or indefinitely if `timeout` is not set.
+   * provided `timeoutMs` is reached, or indefinitely if `timeoutMs` is not set.
    * Raises {@link QueueFullError} if the Queue is still full after the timeout.
    */
   async put(v, params = {}) {
-    await this.#put([v], params.timeout, params.partition, params.partitionTtl);
+    checkForRenamedParams(params, {
+      timeout: "timeoutMs",
+      partitionTtl: "partitionTtlMs"
+    });
+    await this.#put(
+      [v],
+      params.timeoutMs,
+      params.partition,
+      params.partitionTtlMs
+    );
   }
   /**
    * Add several items to the end of the Queue.
    *
    * If the Queue is full, this will retry with exponential backoff until the
-   * provided `timeout` is reached, or indefinitely if `timeout` is not set.
+   * provided `timeoutMs` is reached, or indefinitely if `timeoutMs` is not set.
    * Raises {@link QueueFullError} if the Queue is still full after the timeout.
    */
   async putMany(values, params = {}) {
+    checkForRenamedParams(params, {
+      timeout: "timeoutMs",
+      partitionTtl: "partitionTtlMs"
+    });
     await this.#put(
       values,
-      params.timeout,
+      params.timeoutMs,
       params.partition,
-      params.partitionTtl
+      params.partitionTtlMs
     );
   }
   /** Return the number of objects in the Queue. */
@@ -45115,20 +45282,21 @@ var Queue = class _Queue {
   }
   /** Iterate through items in a Queue without mutation. */
   async *iterate(params = {}) {
-    const { partition, itemPollTimeout = 0 } = params;
+    checkForRenamedParams(params, { itemPollTimeout: "itemPollTimeoutMs" });
+    const { partition, itemPollTimeoutMs = 0 } = params;
     let lastEntryId = void 0;
     const validatedPartitionKey = _Queue.#validatePartitionKey(partition);
-    let fetchDeadline = Date.now() + itemPollTimeout;
-    const maxPollDuration = 3e4;
+    let fetchDeadline = Date.now() + itemPollTimeoutMs;
+    const maxPollDurationMs = 3e4;
     while (true) {
-      const pollDuration = Math.max(
+      const pollDurationMs = Math.max(
         0,
-        Math.min(maxPollDuration, fetchDeadline - Date.now())
+        Math.min(maxPollDurationMs, fetchDeadline - Date.now())
       );
       const request = {
         queueId: this.queueId,
         partitionKey: validatedPartitionKey,
-        itemPollTimeout: pollDuration / 1e3,
+        itemPollTimeout: pollDurationMs / 1e3,
         lastEntryId: lastEntryId || ""
       };
       const response = await this.#client.cpClient.queueNextItems(request);
@@ -45137,7 +45305,7 @@ var Queue = class _Queue {
           yield loads(item.value);
           lastEntryId = item.entryId;
         }
-        fetchDeadline = Date.now() + itemPollTimeout;
+        fetchDeadline = Date.now() + itemPollTimeoutMs;
       } else if (Date.now() > fetchDeadline) {
         break;
       }
@@ -45424,15 +45592,21 @@ function cloudBucketMountToProto(mount, mountPath) {
 
 // src/sandbox.ts
 async function buildSandboxCreateRequestProto(appId, imageId, params = {}) {
+  checkForRenamedParams(params, {
+    memory: "memoryMiB",
+    memoryLimit: "memoryLimitMiB",
+    timeout: "timeoutMs",
+    idleTimeout: "idleTimeoutMs"
+  });
   const gpuConfig = parseGpuConfig(params.gpu);
-  if (params.timeout && params.timeout % 1e3 !== 0) {
+  if (params.timeoutMs && params.timeoutMs % 1e3 !== 0) {
     throw new Error(
-      `timeout must be a multiple of 1000ms, got ${params.timeout}`
+      `timeoutMs must be a multiple of 1000ms, got ${params.timeoutMs}`
     );
   }
-  if (params.idleTimeout && params.idleTimeout % 1e3 !== 0) {
+  if (params.idleTimeoutMs && params.idleTimeoutMs % 1e3 !== 0) {
     throw new Error(
-      `idleTimeout must be a multiple of 1000ms, got ${params.idleTimeout}`
+      `idleTimeoutMs must be a multiple of 1000ms, got ${params.idleTimeoutMs}`
     );
   }
   if (params.workdir && !params.workdir.startsWith("/")) {
@@ -45503,20 +45677,63 @@ async function buildSandboxCreateRequestProto(appId, imageId, params = {}) {
   if (params.pty) {
     ptyInfo = defaultSandboxPTYInfo();
   }
+  let milliCpu = void 0;
+  let milliCpuMax = void 0;
+  if (params.cpu === void 0 && params.cpuLimit !== void 0) {
+    throw new Error("must also specify cpu when cpuLimit is specified");
+  }
+  if (params.cpu !== void 0) {
+    if (params.cpu <= 0) {
+      throw new Error(`cpu (${params.cpu}) must be a positive number`);
+    }
+    milliCpu = Math.trunc(1e3 * params.cpu);
+    if (params.cpuLimit !== void 0) {
+      if (params.cpuLimit < params.cpu) {
+        throw new Error(
+          `cpu (${params.cpu}) cannot be higher than cpuLimit (${params.cpuLimit})`
+        );
+      }
+      milliCpuMax = Math.trunc(1e3 * params.cpuLimit);
+    }
+  }
+  let memoryMb = void 0;
+  let memoryMbMax = void 0;
+  if (params.memoryMiB === void 0 && params.memoryLimitMiB !== void 0) {
+    throw new Error(
+      "must also specify memoryMiB when memoryLimitMiB is specified"
+    );
+  }
+  if (params.memoryMiB !== void 0) {
+    if (params.memoryMiB <= 0) {
+      throw new Error(
+        `the memoryMiB request (${params.memoryMiB}) must be a positive number`
+      );
+    }
+    memoryMb = params.memoryMiB;
+    if (params.memoryLimitMiB !== void 0) {
+      if (params.memoryLimitMiB < params.memoryMiB) {
+        throw new Error(
+          `the memoryMiB request (${params.memoryMiB}) cannot be higher than memoryLimitMiB (${params.memoryLimitMiB})`
+        );
+      }
+      memoryMbMax = params.memoryLimitMiB;
+    }
+  }
   return SandboxCreateRequest.create({
     appId,
     definition: {
       // Sleep default is implicit in image builder version <=2024.10
       entrypointArgs: params.command ?? ["sleep", "48h"],
       imageId,
-      timeoutSecs: params.timeout != void 0 ? params.timeout / 1e3 : 600,
-      idleTimeoutSecs: params.idleTimeout != void 0 ? params.idleTimeout / 1e3 : void 0,
+      timeoutSecs: params.timeoutMs != void 0 ? params.timeoutMs / 1e3 : 600,
+      idleTimeoutSecs: params.idleTimeoutMs != void 0 ? params.idleTimeoutMs / 1e3 : void 0,
       workdir: params.workdir ?? void 0,
       networkAccess,
       resources: {
-        // https://modal.com/docs/guide/resources
-        milliCpu: Math.round(1e3 * (params.cpu ?? 0.125)),
-        memoryMb: params.memory ?? 128,
+        milliCpu,
+        milliCpuMax,
+        memoryMb,
+        memoryMbMax,
         gpuConfig
       },
       volumeMounts,
@@ -45567,6 +45784,11 @@ var SandboxService = class {
       }
       throw err;
     }
+    this.#client.logger.debug(
+      "Created Sandbox",
+      "sandbox_id",
+      createResp.sandboxId
+    );
     return new Sandbox2(this.#client, createResp.sandboxId);
   }
   /** Returns a running {@link Sandbox} object from an ID.
@@ -45691,6 +45913,7 @@ function defaultSandboxPTYInfo() {
   });
 }
 async function buildContainerExecRequestProto(taskId, command, params) {
+  checkForRenamedParams(params, { timeout: "timeoutMs" });
   const secretIds = (params?.secrets || []).map((secret) => secret.secretId);
   let ptyInfo;
   if (params?.pty) {
@@ -45700,7 +45923,7 @@ async function buildContainerExecRequestProto(taskId, command, params) {
     taskId,
     command,
     workdir: params?.workdir,
-    timeoutSecs: params?.timeout ? params.timeout / 1e3 : 0,
+    timeoutSecs: params?.timeoutMs ? params.timeoutMs / 1e3 : 0,
     secretIds,
     ptyInfo
   });
@@ -45826,6 +46049,15 @@ var Sandbox2 = class _Sandbox {
       mergedParams
     );
     const resp = await this.#client.cpClient.containerExec(req);
+    this.#client.logger.debug(
+      "Created ContainerProcess",
+      "exec_id",
+      resp.execId,
+      "sandbox_id",
+      this.sandboxId,
+      "command",
+      command
+    );
     return new ContainerProcess(this.#client, resp.execId, params);
   }
   async #getTaskId() {
@@ -45858,7 +46090,17 @@ var Sandbox2 = class _Sandbox {
         timeout: 10
       });
       if (resp.result) {
-        return _Sandbox.#getReturnCode(resp.result);
+        const returnCode = _Sandbox.#getReturnCode(resp.result);
+        this.#client.logger.debug(
+          "Sandbox wait completed",
+          "sandbox_id",
+          this.sandboxId,
+          "status",
+          resp.result.status,
+          "return_code",
+          returnCode
+        );
+        return returnCode;
       }
     }
   }
@@ -45868,14 +46110,13 @@ var Sandbox2 = class _Sandbox {
    *
    * @returns A dictionary of {@link Tunnel} objects which are keyed by the container port.
    */
-  async tunnels(timeout = 5e4) {
+  async tunnels(timeoutMs = 5e4) {
     if (this.#tunnels) {
       return this.#tunnels;
     }
     const resp = await this.#client.cpClient.sandboxGetTunnels({
       sandboxId: this.sandboxId,
-      timeout: timeout / 1e3
-      // Convert to seconds
+      timeout: timeoutMs / 1e3
     });
     if (resp.result?.status === 4 /* GENERIC_STATUS_TIMEOUT */) {
       throw new SandboxTimeoutError();
@@ -45896,13 +46137,13 @@ var Sandbox2 = class _Sandbox {
    *
    * Returns an {@link Image} object which can be used to spawn a new Sandbox with the same filesystem.
    *
-   * @param timeout - Timeout for the snapshot operation in milliseconds
+   * @param timeoutMs - Timeout for the snapshot operation in milliseconds
    * @returns Promise that resolves to an {@link Image}
    */
-  async snapshotFilesystem(timeout = 55e3) {
+  async snapshotFilesystem(timeoutMs = 55e3) {
     const resp = await this.#client.cpClient.sandboxSnapshotFs({
       sandboxId: this.sandboxId,
-      timeout: timeout / 1e3
+      timeout: timeoutMs / 1e3
     });
     if (resp.result?.status !== 1 /* GENERIC_STATUS_SUCCESS */) {
       throw new Error(
@@ -46124,6 +46365,13 @@ var VolumeService = class {
         environmentName: this.#client.environmentName(params?.environment),
         objectCreationType: params?.createIfMissing ? 1 /* OBJECT_CREATION_TYPE_CREATE_IF_MISSING */ : 0 /* OBJECT_CREATION_TYPE_UNSPECIFIED */
       });
+      this.#client.logger.debug(
+        "Retrieved Volume",
+        "volume_id",
+        resp.volumeId,
+        "volume_name",
+        name
+      );
       return new Volume(resp.volumeId, name);
     } catch (err) {
       if (err instanceof ClientError8 && err.code === Status8.NOT_FOUND)
@@ -46140,6 +46388,11 @@ var VolumeService = class {
       objectCreationType: 5 /* OBJECT_CREATION_TYPE_EPHEMERAL */,
       environmentName: this.#client.environmentName(params.environment)
     });
+    this.#client.logger.debug(
+      "Created ephemeral Volume",
+      "volume_id",
+      resp.volumeId
+    );
     const ephemeralHbManager = new EphemeralHeartbeatManager(
       () => this.#client.cpClient.volumeHeartbeat({ volumeId: resp.volumeId })
     );
@@ -46192,9 +46445,17 @@ import { readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import path from "node:path";
 import { parse as parseToml } from "smol-toml";
+function configFilePath() {
+  const configPath = process.env["MODAL_CONFIG_PATH"];
+  if (configPath && configPath !== "") {
+    return configPath;
+  }
+  return path.join(homedir(), ".modal.toml");
+}
 function readConfigFile() {
   try {
-    const configContent = readFileSync(path.join(homedir(), ".modal.toml"), {
+    const configPath = configFilePath();
+    const configContent = readFileSync(configPath, {
       encoding: "utf-8"
     });
     return parseToml(configContent);
@@ -46221,7 +46482,8 @@ function getProfile(profileName) {
     tokenId: process.env["MODAL_TOKEN_ID"] || profileData.token_id,
     tokenSecret: process.env["MODAL_TOKEN_SECRET"] || profileData.token_secret,
     environment: process.env["MODAL_ENVIRONMENT"] || profileData.environment,
-    imageBuilderVersion: process.env["MODAL_IMAGE_BUILDER_VERSION"] || profileData.imageBuilderVersion
+    imageBuilderVersion: process.env["MODAL_IMAGE_BUILDER_VERSION"] || profileData.imageBuilderVersion,
+    logLevel: process.env["MODAL_LOGLEVEL"] || profileData.loglevel
   };
   return profile;
 }
@@ -46231,13 +46493,15 @@ var REFRESH_WINDOW = 5 * 60;
 var DEFAULT_EXPIRY_OFFSET = 20 * 60;
 var AuthTokenManager = class {
   client;
+  logger;
   currentToken = "";
   tokenExpiry = 0;
   stopped = false;
   timeoutId = null;
   initialTokenPromise = null;
-  constructor(client2) {
+  constructor(client2, logger) {
     this.client = client2;
+    this.logger = logger;
   }
   /**
    * Returns the current cached token.
@@ -46268,9 +46532,19 @@ var AuthTokenManager = class {
     if (exp > 0) {
       this.tokenExpiry = exp;
     } else {
-      console.warn("Failed to decode x-modal-auth-token exp field");
+      this.logger.warn("x-modal-auth-token does not contain exp field");
       this.tokenExpiry = Math.floor(Date.now() / 1e3) + DEFAULT_EXPIRY_OFFSET;
     }
+    const now = Math.floor(Date.now() / 1e3);
+    const expiresIn = this.tokenExpiry - now;
+    const refreshIn = this.tokenExpiry - now - REFRESH_WINDOW;
+    this.logger.debug(
+      "Fetched auth token",
+      "expires_in",
+      `${expiresIn}s`,
+      "refresh_in",
+      `${refreshIn}s`
+    );
   }
   /**
    * Background loop that refreshes tokens REFRESH_WINDOW seconds before they expire.
@@ -46290,7 +46564,7 @@ var AuthTokenManager = class {
       try {
         await this.fetchToken();
       } catch (error) {
-        console.error("Failed to refresh auth token:", error);
+        this.logger.error("Failed to refresh auth token", "error", error);
         await new Promise((resolve) => setTimeout(resolve, 5e3));
       }
     }
@@ -46354,7 +46628,113 @@ var AuthTokenManager = class {
 
 // src/version.ts
 function getSDKVersion() {
-  return true ? "0.5.0-dev.7" : "0.0.0";
+  return true ? "0.5.1" : "0.0.0";
+}
+
+// src/logger.ts
+var LOG_LEVELS = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3
+};
+function parseLogLevel(level) {
+  if (!level) {
+    return "warn";
+  }
+  const normalized = level.toLowerCase();
+  if (normalized === "debug" || normalized === "info" || normalized === "warn" || normalized === "warning" || normalized === "error") {
+    return normalized === "warning" ? "warn" : normalized;
+  }
+  throw new Error(
+    `Invalid log level value: "${level}" (must be debug, info, warn, or error)`
+  );
+}
+var DefaultLogger = class {
+  levelValue;
+  constructor(level = "warn") {
+    this.levelValue = LOG_LEVELS[level];
+  }
+  debug(message, ...args) {
+    if (this.levelValue <= LOG_LEVELS.debug) {
+      console.log(this.formatMessage("DEBUG", message, args));
+    }
+  }
+  info(message, ...args) {
+    if (this.levelValue <= LOG_LEVELS.info) {
+      console.log(this.formatMessage("INFO", message, args));
+    }
+  }
+  warn(message, ...args) {
+    if (this.levelValue <= LOG_LEVELS.warn) {
+      console.warn(this.formatMessage("WARN", message, args));
+    }
+  }
+  error(message, ...args) {
+    if (this.levelValue <= LOG_LEVELS.error) {
+      console.error(this.formatMessage("ERROR", message, args));
+    }
+  }
+  formatMessage(level, message, args) {
+    const timestamp = (/* @__PURE__ */ new Date()).toISOString();
+    let formatted = `time=${timestamp} level=${level} msg="${message}"`;
+    if (args.length > 0) {
+      for (let i = 0; i < args.length; i += 2) {
+        if (i + 1 < args.length) {
+          const key = args[i];
+          const value = args[i + 1];
+          formatted += ` ${key}=${this.formatValue(value)}`;
+        }
+      }
+    }
+    return formatted;
+  }
+  formatValue(value) {
+    if (typeof value === "string") {
+      return value.includes(" ") ? `"${value}"` : value;
+    }
+    if (value instanceof Error) {
+      return `"${value.message}"`;
+    }
+    if (Array.isArray(value)) {
+      return `[${value.join(",")}]`;
+    }
+    return String(value);
+  }
+};
+var FilteredLogger = class {
+  constructor(logger, level) {
+    this.logger = logger;
+    this.levelValue = LOG_LEVELS[level];
+  }
+  levelValue;
+  debug(message, ...args) {
+    if (this.levelValue <= LOG_LEVELS.debug) {
+      this.logger.debug(message, ...args);
+    }
+  }
+  info(message, ...args) {
+    if (this.levelValue <= LOG_LEVELS.info) {
+      this.logger.info(message, ...args);
+    }
+  }
+  warn(message, ...args) {
+    if (this.levelValue <= LOG_LEVELS.warn) {
+      this.logger.warn(message, ...args);
+    }
+  }
+  error(message, ...args) {
+    if (this.levelValue <= LOG_LEVELS.error) {
+      this.logger.error(message, ...args);
+    }
+  }
+};
+function createLogger(logger, logLevel = "") {
+  const level = parseLogLevel(logLevel);
+  if (logger) {
+    return new FilteredLogger(logger, level);
+  }
+  return new DefaultLogger(level);
 }
 
 // src/client.ts
@@ -46372,9 +46752,11 @@ var ModalClient = class {
   /** @ignore */
   cpClient;
   profile;
+  logger;
   ipClients;
   authTokenManager = null;
   constructor(params) {
+    checkForRenamedParams(params, { timeout: "timeoutMs" });
     const baseProfile = getProfile(process.env["MODAL_PROFILE"]);
     this.profile = {
       ...baseProfile,
@@ -46382,8 +46764,18 @@ var ModalClient = class {
       ...params?.tokenSecret && { tokenSecret: params.tokenSecret },
       ...params?.environment && { environment: params.environment }
     };
+    const logLevelValue = params?.logLevel || this.profile.logLevel || "";
+    this.logger = createLogger(params?.logger, logLevelValue);
+    this.logger.debug(
+      "Initializing Modal client",
+      "version",
+      getSDKVersion(),
+      "server_url",
+      this.profile.serverUrl
+    );
     this.ipClients = /* @__PURE__ */ new Map();
     this.cpClient = params?.cpClient ?? this.createClient(this.profile);
+    this.logger.debug("Modal client initialized successfully");
     this.apps = new AppService(this);
     this.cls = new ClsService(this);
     this.functions = new FunctionService(this);
@@ -46407,16 +46799,19 @@ var ModalClient = class {
     if (existing) {
       return existing;
     }
+    this.logger.debug("Creating input plane client", "server_url", serverUrl);
     const profile = { ...this.profile, serverUrl };
     const newClient = this.createClient(profile);
     this.ipClients.set(serverUrl, newClient);
     return newClient;
   }
   close() {
+    this.logger.debug("Closing Modal client");
     if (this.authTokenManager) {
       this.authTokenManager.stop();
       this.authTokenManager = null;
     }
+    this.logger.debug("Modal client closed");
   }
   version() {
     return getSDKVersion();
@@ -46427,12 +46822,97 @@ var ModalClient = class {
       "grpc.max_send_message_length": 100 * 1024 * 1024,
       "grpc-node.flow_control_window": 64 * 1024 * 1024
     });
-    return createClientFactory().use(this.authMiddleware(profile)).use(retryMiddleware).use(timeoutMiddleware).create(ModalClientDefinition, channel);
+    return createClientFactory().use(this.authMiddleware(profile)).use(this.retryMiddleware()).use(timeoutMiddleware).create(ModalClientDefinition, channel);
+  }
+  /** Middleware to retry transient errors and timeouts for unary requests. */
+  retryMiddleware() {
+    const logger = this.logger;
+    return async function* retryMiddleware(call, options) {
+      const {
+        retries = 3,
+        baseDelay = 100,
+        maxDelay = 1e3,
+        delayFactor = 2,
+        additionalStatusCodes = [],
+        signal,
+        ...restOptions
+      } = options;
+      if (call.requestStream || call.responseStream || !retries) {
+        return yield* call.next(call.request, restOptions);
+      }
+      const retryableCodes = /* @__PURE__ */ new Set([
+        ...retryableGrpcStatusCodes,
+        ...additionalStatusCodes
+      ]);
+      const idempotencyKey = uuidv4();
+      const startTime = Date.now();
+      let attempt = 0;
+      let delayMs = baseDelay;
+      logger.debug("Sending gRPC request", "method", call.method.path);
+      while (true) {
+        const metadata = new Metadata(restOptions.metadata ?? {});
+        metadata.set("x-idempotency-key", idempotencyKey);
+        metadata.set("x-retry-attempt", String(attempt));
+        if (attempt > 0) {
+          metadata.set(
+            "x-retry-delay",
+            ((Date.now() - startTime) / 1e3).toFixed(3)
+          );
+        }
+        try {
+          return yield* call.next(call.request, {
+            ...restOptions,
+            metadata,
+            signal
+          });
+        } catch (err) {
+          if (!(err instanceof ClientError9) || !retryableCodes.has(err.code) || attempt >= retries) {
+            if (attempt === retries && attempt > 0) {
+              logger.debug(
+                "Final retry attempt failed",
+                "error",
+                err,
+                "retries",
+                attempt,
+                "delay",
+                delayMs,
+                "method",
+                call.method.path,
+                "idempotency_key",
+                idempotencyKey.substring(0, 8)
+              );
+            }
+            throw err;
+          }
+          if (attempt > 0) {
+            logger.debug(
+              "Retryable failure",
+              "error",
+              err,
+              "retries",
+              attempt,
+              "delay",
+              delayMs,
+              "method",
+              call.method.path,
+              "idempotency_key",
+              idempotencyKey.substring(0, 8)
+            );
+          }
+          await sleep(delayMs, signal);
+          delayMs = Math.min(delayMs * delayFactor, maxDelay);
+          attempt += 1;
+        }
+      }
+    };
   }
   authMiddleware(profile) {
     const getOrCreateAuthTokenManager = () => {
       if (!this.authTokenManager) {
-        this.authTokenManager = new AuthTokenManager(this.cpClient);
+        this.authTokenManager = new AuthTokenManager(
+          this.cpClient,
+          this.logger
+        );
         this.authTokenManager.start();
       }
       return this.authTokenManager;
@@ -46468,10 +46948,10 @@ var ModalClient = class {
   }
 };
 var timeoutMiddleware = async function* timeoutMiddleware2(call, options) {
-  if (!options.timeout || options.signal?.aborted) {
+  if (!options.timeoutMs || options.signal?.aborted) {
     return yield* call.next(call.request, options);
   }
-  const { timeout, signal: origSignal, ...restOptions } = options;
+  const { timeoutMs, signal: origSignal, ...restOptions } = options;
   const abortController = new AbortController();
   const abortListener = () => abortController.abort();
   origSignal?.addEventListener("abort", abortListener);
@@ -46479,7 +46959,7 @@ var timeoutMiddleware = async function* timeoutMiddleware2(call, options) {
   const timer = setTimeout(() => {
     timedOut = true;
     abortController.abort();
-  }, timeout);
+  }, timeoutMs);
   try {
     return yield* call.next(call.request, {
       ...restOptions,
@@ -46492,7 +46972,7 @@ var timeoutMiddleware = async function* timeoutMiddleware2(call, options) {
       throw new ClientError9(
         call.method.path,
         Status9.DEADLINE_EXCEEDED,
-        `Timed out after ${timeout}ms`
+        `Timed out after ${timeoutMs}ms`
       );
     }
   }
@@ -46522,53 +47002,6 @@ var sleep = (ms, signal) => new Promise((resolve, reject) => {
     { once: true }
   );
 });
-var retryMiddleware = async function* retryMiddleware2(call, options) {
-  const {
-    retries = 3,
-    baseDelay = 100,
-    maxDelay = 1e3,
-    delayFactor = 2,
-    additionalStatusCodes = [],
-    signal,
-    ...restOptions
-  } = options;
-  if (call.requestStream || call.responseStream || !retries) {
-    return yield* call.next(call.request, restOptions);
-  }
-  const retryableCodes = /* @__PURE__ */ new Set([
-    ...retryableGrpcStatusCodes,
-    ...additionalStatusCodes
-  ]);
-  const idempotencyKey = uuidv4();
-  const startTime = Date.now();
-  let attempt = 0;
-  let delayMs = baseDelay;
-  while (true) {
-    const metadata = new Metadata(restOptions.metadata ?? {});
-    metadata.set("x-idempotency-key", idempotencyKey);
-    metadata.set("x-retry-attempt", String(attempt));
-    if (attempt > 0) {
-      metadata.set(
-        "x-retry-delay",
-        ((Date.now() - startTime) / 1e3).toFixed(3)
-      );
-    }
-    try {
-      return yield* call.next(call.request, {
-        ...restOptions,
-        metadata,
-        signal
-      });
-    } catch (err) {
-      if (!(err instanceof ClientError9) || !retryableCodes.has(err.code) || attempt >= retries) {
-        throw err;
-      }
-      await sleep(delayMs, signal);
-      delayMs = Math.min(delayMs * delayFactor, maxDelay);
-      attempt += 1;
-    }
-  }
-};
 var defaultClient;
 var defaultClientOptions;
 function getDefaultClient() {
@@ -46612,6 +47045,13 @@ var AppService = class {
         environmentName: this.#client.environmentName(params.environment),
         objectCreationType: params.createIfMissing ? 1 /* OBJECT_CREATION_TYPE_CREATE_IF_MISSING */ : 0 /* OBJECT_CREATION_TYPE_UNSPECIFIED */
       });
+      this.#client.logger.debug(
+        "Retrieved App",
+        "app_id",
+        resp.appId,
+        "app_name",
+        name
+      );
       return new App2(resp.appId, name);
     } catch (err) {
       if (err instanceof ClientError10 && err.code === Status10.NOT_FOUND)
@@ -46718,6 +47158,7 @@ export {
   SecretService,
   Volume,
   VolumeService,
+  checkForRenamedParams,
   close,
   initializeClient
 };