@superlinked/sie-sdk 0.2.0 → 0.3.1

package/dist/index.cjs

@@ -11,9 +11,11 @@ var SIEError = class extends Error {
   }
 };
 var SIEConnectionError = class extends SIEError {
-  constructor(message) {
+  kind;
+  constructor(message, kind = "other") {
     super(message);
     this.name = "SIEConnectionError";
+    this.kind = kind;
   }
 };
 var RequestError = class extends SIEError {
@@ -85,6 +87,28 @@ var ModelLoadingError = class extends SIEError {
     this.model = model;
   }
 };
+var ModelLoadFailedError = class extends ServerError {
+  /** The model that was requested */
+  model;
+  /**
+   * Server-side classification: one of `GATED`, `OOM`, `DEPENDENCY`,
+   * `NOT_FOUND`, `NETWORK`, `UNKNOWN`. Use this to route to specific
+   * remediation paths (e.g. surface a "set HF_TOKEN" hint for `GATED`).
+   */
+  errorClass;
+  /** Whether the failure is non-retryable per server policy. */
+  permanent;
+  /** How many load attempts the server has logged. */
+  attempts;
+  constructor(message, options) {
+    super(message, "MODEL_LOAD_FAILED", 502);
+    this.name = "ModelLoadFailedError";
+    this.model = options?.model;
+    this.errorClass = options?.errorClass;
+    this.permanent = options?.permanent ?? true;
+    this.attempts = options?.attempts ?? 1;
+  }
+};
 
 // src/internal/constants.ts
 var MSGPACK_CONTENT_TYPE = "application/msgpack";
@@ -105,9 +129,6 @@ var MODEL_LOADING_DEFAULT_DELAY = 5e3;
 var MODEL_LOADING_ERROR_CODE = "MODEL_LOADING";
 var SDK_VERSION_HEADER = "X-SIE-SDK-Version";
 var SERVER_VERSION_HEADER = "X-SIE-Server-Version";
-
-// src/version.ts
-var SDK_VERSION = "0.2.0";
 var EXT_TYPE_NUMPY = 78;
 function parseDtype(dtype) {
   const typeChar = dtype.slice(-2, -1);
@@ -312,7 +333,7 @@ function getRetryAfter2(response) {
   const header = response.headers.get("Retry-After");
   return getRetryAfter(header);
 }
-async function getErrorCode(response) {
+async function getErrorDetail(response) {
   try {
     const contentType = response.headers.get("content-type") ?? "";
     let data;
@@ -323,24 +344,42 @@ async function getErrorCode(response) {
       data = await response.json();
     }
     if (data.error && typeof data.error === "object") {
-      const error = data.error;
-      if (typeof error.code === "string") {
-        return error.code;
-      }
+      return data.error;
     }
     if (data.detail && typeof data.detail === "object") {
-      const detail = data.detail;
-      if (typeof detail.code === "string") {
-        return detail.code;
-      }
+      return data.detail;
     }
     if (typeof data.code === "string") {
-      return data.code;
+      return data;
     }
   } catch {
   }
   return void 0;
 }
+async function getErrorCode(response) {
+  const detail = await getErrorDetail(response);
+  if (!detail) return void 0;
+  const code = detail.code;
+  return typeof code === "string" ? code : void 0;
+}
+async function throwIfModelLoadFailed(response, model) {
+  if (response.status !== 502) return;
+  const detail = await getErrorDetail(response.clone());
+  if (!detail) return;
+  if (detail.code !== "MODEL_LOAD_FAILED") return;
+  const errorClass = typeof detail.error_class === "string" ? detail.error_class : void 0;
+  const permanent = typeof detail.permanent === "boolean" ? detail.permanent : true;
+  const attemptsRaw = detail.attempts;
+  const parsedAttempts = typeof attemptsRaw === "number" ? attemptsRaw : typeof attemptsRaw === "string" ? Number.parseInt(attemptsRaw, 10) : Number.NaN;
+  const attempts = Number.isFinite(parsedAttempts) ? parsedAttempts : 1;
+  const message = typeof detail.message === "string" ? detail.message : `Model '${model ?? "?"}' failed to load`;
+  throw new ModelLoadFailedError(message, {
+    model,
+    errorClass,
+    permanent,
+    attempts
+  });
+}
 async function handleError(response, gpu) {
   const { status } = response;
   let errorBody = {};
@@ -476,6 +515,9 @@ function parseCapacityInfo(data, gpuFilter) {
   };
 }
 
+// src/version.ts
+var SDK_VERSION = "0.3.1";
+
 // src/client.ts
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
@@ -616,9 +658,9 @@ var SIEClient = class {
     };
   }
   /**
-   * Stream real-time status updates from a worker or router.
+   * Stream real-time status updates from a worker or gateway.
    *
-   * @param mode - "cluster" uses router /ws/cluster-status, "worker" uses /ws/status.
+   * @param mode - "cluster" uses gateway /ws/cluster-status, "worker" uses /ws/status.
    *               "auto" detects the endpoint via /health.
    */
   async *watch(mode = "auto") {
@@ -789,7 +831,7 @@ var SIEClient = class {
    * Close the client and cleanup resources.
    *
    * Stops pool lease renewal timers. Note that pools are not deleted
-   * automatically - they are garbage collected by the router after inactivity.
+   * automatically - they are garbage collected by the gateway after inactivity.
    * This allows pool reuse if the client reconnects.
    */
   async close() {
@@ -1046,7 +1088,7 @@ var SIEClient = class {
   /**
    * Get current cluster capacity information.
    *
-   * Queries the router's /health endpoint for cluster state. Useful for
+   * Queries the gateway's /health endpoint for cluster state. Useful for
    * checking if specific GPU types are available before sending requests.
    *
    * @param gpu - Optional filter to check specific GPU type availability
@@ -1068,10 +1110,10 @@ var SIEClient = class {
   async getCapacity(gpu) {
     const response = await this.requestJson("/health");
     const data = await response.json();
-    if (data.type !== "router") {
+    if (data.type !== "gateway") {
       throw new RequestError(
-        "getCapacity() requires a router endpoint. This appears to be a worker.",
-        "not_router",
+        "getCapacity() requires a gateway endpoint. This appears to be a worker.",
+        "not_gateway",
         400
       );
     }
@@ -1080,7 +1122,7 @@ var SIEClient = class {
   /**
    * Wait for GPU capacity to become available.
    *
-   * Polls the router until workers with the specified GPU type are online.
+   * Polls the gateway until workers with the specified GPU type are online.
    * This is useful for pre-warming the cluster before running benchmarks.
    *
    * @param gpu - GPU type to wait for (e.g., "l4", "a100-80gb")
@@ -1126,13 +1168,35 @@ var SIEClient = class {
     }
   }
   /**
-   * Make a msgpack HTTP request with retry logic for 202 and LoRA loading.
+   * Make a msgpack HTTP request with retry logic.
+   *
+   * Retried (only when `waitForCapacity: true`, capped by `provisionTimeout`):
+   *  - 202 Accepted (provisioning)
+   *  - 503 `MODEL_LOADING` / `LORA_LOADING` / no error code (scale-from-zero)
+   *  - `SIEConnectionError` with `kind === "connect"` (issue #95)
+   *
+   * `kind === "timeout"` is NOT retried — would extend the user-visible
+   * timeout from `timeout` to `provisionTimeout`.
    */
   async requestWithRetry(path, body, pool, gpu, waitForCapacity, model) {
     const startTime = Date.now();
     let loraRetries = 0;
     while (true) {
-      const response = await this.request(path, body, pool, gpu);
+      let response;
+      try {
+        response = await this.request(path, body, pool, gpu);
+      } catch (err) {
+        if (waitForCapacity && err instanceof SIEConnectionError && err.kind === "connect") {
+          const elapsed = Date.now() - startTime;
+          if (elapsed < this.provisionTimeout) {
+            const remaining = this.provisionTimeout - elapsed;
+            const delay = Math.min(DEFAULT_RETRY_DELAY, remaining);
+            await sleep(delay);
+            continue;
+          }
+        }
+        throw err;
+      }
       if (response.status === HTTP_ACCEPTED) {
         const retryAfter = getRetryAfter2(response);
         if (!waitForCapacity) {
@@ -1156,6 +1220,7 @@ var SIEClient = class {
         await sleep(actualDelay);
         continue;
       }
+      await throwIfModelLoadFailed(response, model);
       if (response.status === 503) {
         const clonedResponse = response.clone();
         const errorCode = await getErrorCode(clonedResponse);
@@ -1189,6 +1254,17 @@ var SIEClient = class {
           await sleep(actualDelay);
           continue;
         }
+        if (waitForCapacity) {
+          const elapsed = Date.now() - startTime;
+          if (elapsed < this.provisionTimeout) {
+            const retryAfter = getRetryAfter2(response);
+            const delay = retryAfter ?? DEFAULT_RETRY_DELAY;
+            const remaining = this.provisionTimeout - elapsed;
+            const actualDelay = Math.min(delay, remaining);
+            await sleep(actualDelay);
+            continue;
+          }
+        }
       }
       if (!response.ok) {
         await handleError(response, gpu);
@@ -1230,10 +1306,10 @@ var SIEClient = class {
       return response;
     } catch (error) {
       if (error instanceof Error && error.name === "AbortError") {
-        throw new SIEConnectionError(`Request timeout after ${this.timeout}ms`);
+        throw new SIEConnectionError(`Request timeout after ${this.timeout}ms`, "timeout");
       }
       if (error instanceof TypeError) {
-        throw new SIEConnectionError(`Connection failed: ${error.message}`);
+        throw new SIEConnectionError(`Connection failed: ${error.message}`, "connect");
       }
       throw error;
     } finally {
@@ -1267,10 +1343,10 @@ var SIEClient = class {
       return response;
     } catch (error) {
       if (error instanceof Error && error.name === "AbortError") {
-        throw new SIEConnectionError(`Request timeout after ${this.timeout}ms`);
+        throw new SIEConnectionError(`Request timeout after ${this.timeout}ms`, "timeout");
       }
       if (error instanceof TypeError) {
-        throw new SIEConnectionError(`Connection failed: ${error.message}`);
+        throw new SIEConnectionError(`Connection failed: ${error.message}`, "connect");
       }
       throw error;
     } finally {
@@ -1318,7 +1394,7 @@ var SIEClient = class {
         return "worker";
       }
       const data = await response.json();
-      return data.type === "router" ? "cluster" : "worker";
+      return data.type === "gateway" ? "cluster" : "worker";
     } catch {
       return "worker";
     } finally {
@@ -1467,6 +1543,7 @@ function detectImageFormat(bytes) {
 }
 
 exports.LoraLoadingError = LoraLoadingError;
+exports.ModelLoadFailedError = ModelLoadFailedError;
 exports.ModelLoadingError = ModelLoadingError;
 exports.PoolError = PoolError;
 exports.ProvisioningError = ProvisioningError;