modal 0.5.0 → 0.5.2

package/dist/index.js

@@ -43635,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,
@@ -43666,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 {
@@ -43702,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,
@@ -43709,6 +43750,13 @@ 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.
@@ -43748,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]);
@@ -43811,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)
@@ -43835,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))
@@ -43955,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,
@@ -44333,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 {
@@ -44432,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];
@@ -44506,6 +44583,7 @@ ${result.exception}`
       baseImageId = resp.imageId;
     }
     this.#imageId = baseImageId;
+    this.#client.logger.debug("Image build completed", "image_id", baseImageId);
     return this;
   }
   /**
@@ -44969,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 })
     );
@@ -44983,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);
   }
   /**
@@ -45694,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.
@@ -45954,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() {
@@ -45986,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;
       }
     }
   }
@@ -46251,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)
@@ -46267,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 })
     );
@@ -46319,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);
@@ -46348,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;
 }
@@ -46358,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.
@@ -46395,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.
@@ -46417,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));
       }
     }
@@ -46481,7 +46628,113 @@ var AuthTokenManager = class {
 
 // src/version.ts
 function getSDKVersion() {
-  return true ? "0.5.0" : "0.0.0";
+  return true ? "0.5.2" : "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
@@ -46499,8 +46752,10 @@ var ModalClient = class {
   /** @ignore */
   cpClient;
   profile;
+  logger;
   ipClients;
   authTokenManager = null;
+  customMiddleware;
   constructor(params) {
     checkForRenamedParams(params, { timeout: "timeoutMs" });
     const baseProfile = getProfile(process.env["MODAL_PROFILE"]);
@@ -46510,8 +46765,19 @@ 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.customMiddleware = params?.grpcMiddleware ?? [];
     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);
@@ -46535,16 +46801,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();
@@ -46555,12 +46824,101 @@ 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);
+    let factory = createClientFactory().use(this.authMiddleware(profile)).use(this.retryMiddleware()).use(timeoutMiddleware);
+    for (const middleware of this.customMiddleware) {
+      factory = factory.use(middleware);
+    }
+    return factory.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;
@@ -46650,53 +47008,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() {
@@ -46740,6 +47051,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)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "modal",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "Modal SDK for JavaScript/TypeScript",
   "license": "Apache-2.0",
   "homepage": "https://modal.com/docs/guide/sdk-javascript-go",