@miosa/sdk 3.2.3 → 3.2.4

package/dist/index.d.ts

@@ -7468,30 +7468,39 @@ declare class Sandbox {
     /** Check readiness of the sandbox (GET /sandboxes/:id/readiness). */
     readiness(): Promise<Record<string, unknown>>;
     /**
-     * Block until the sandbox reports ready, or *timeout* seconds elapse.
+     * Block until the sandbox reports ready, or the caller's *timeout* seconds
+     * (the full deadline budget) elapse.
      *
-     * When `stream` is `true` (the default) this opens an SSE connection
-     * to `GET /sandboxes/:id/readiness/stream` and waits for an
-     * `event: ready` frame. The server emits `ready` immediately if the
-     * sandbox is already ready, otherwise as soon as the readiness PubSub
-     * message fires.
+     * When `stream` is `true` (the default) this opens an SSE connection to
+     * `GET /sandboxes/:id/readiness/stream?timeout=<window>` and waits for an
+     * `event: ready` frame. `<window>` is the caller's remaining budget clamped
+     * to {@link READINESS_STREAM_MAX_TIMEOUT_SEC}, the server's own maximum
+     * lease for a single stream connection — a long-restoring persistent
+     * sandbox (e.g. Docker restore, 60-90 s) legitimately outlives one lease.
+     * The server emits `ready` immediately if the sandbox is already ready,
+     * `event: timeout` when *that connection's* window elapses without a
+     * verdict, and `event: error` on a terminal boot failure.
      *
-     * Returns `true` once the sandbox is ready, `false` on `event: timeout`
-     * or when the local timeout elapses before ready.
+     * An `event: timeout` (or the stream closing without a verdict) is NOT
+     * treated as the final answer while the caller's overall deadline still has
+     * budget left — that would silently truncate a 180 s wait down to the
+     * server's lease window and return `false` while the sandbox was still
+     * mid-restore. Instead this reconnects the stream (or falls back to
+     * polling) for the remaining budget. `false` is only returned once the
+     * caller's full deadline has elapsed.
      *
      * Throws {@link MiosaError} with code `SANDBOX_BOOT_FAILED` as soon as the
      * sandbox is observed in a terminal failure state (`error` or `destroyed`)
      * while waiting, instead of silently exhausting the timeout and returning
      * `false` — a permanent boot failure and "still booting, keep waiting" must
-     * never look the same to the caller. The readiness SSE stream itself has no
-     * dedicated failure event today (the server only ever emits
-     * `ready`/`status`/`timeout`), so on `event: timeout` this makes one
-     * authoritative {@link readiness} check before giving up, to catch a
-     * failure that landed right at the boundary.
+     * never look the same to the caller. On each `event: timeout` boundary this
+     * also makes one authoritative {@link readiness} check before deciding to
+     * reconnect or stop, to catch a failure that landed right at the boundary.
      *
      * If the SSE endpoint returns 404 (server pre-dates the streaming
      * endpoint) this transparently falls back to polling {@link readiness}
-     * every 10 ms until ready, timeout, or terminal failure.
+     * every 10 ms until ready, the caller's deadline elapses, or terminal
+     * failure.
      */
     waitUntilReady(options?: {
         timeout?: number;
@@ -7522,6 +7531,15 @@ declare class Sandbox {
      * stream endpoint is unavailable (404 or transport error) so callers
      * can fall back to polling.
      */
+    /**
+     * Opens one readiness SSE connection for at most *windowSec* seconds (this
+     * is a single lease, not the caller's overall {@link waitUntilReady}
+     * budget — see there for how leases are chained). *windowSec* is sent to
+     * the server as `?timeout=<seconds>` so the server's own stream deadline
+     * matches what was actually requested instead of always falling back to
+     * its 30 s default, which is what let a 180 s `waitUntilReady` call get
+     * cut short at 30 s.
+     */
     private tryReadinessStream;
     destroy(): Promise<void>;
     delete(): Promise<void>;

package/dist/index.js

@@ -174,7 +174,7 @@ var TokenRefreshFailedError = class extends MiosaError {
 };
 
 // src/version.ts
-var SDK_VERSION = "3.2.3";
+var SDK_VERSION = "3.2.4";
 var SDK_USER_AGENT = `@miosa/sdk/${SDK_VERSION}`;
 
 // src/http.ts
@@ -8517,6 +8517,7 @@ function isCommandReady(payload) {
     return status === "ready";
   });
 }
+var READINESS_STREAM_MAX_TIMEOUT_SEC = 120;
 var SANDBOX_TEMPLATE = "miosa-sandbox";
 var SANDBOX_TIER_BY_CPU = {
   1: { size: "xs", memoryMb: 2048 },
@@ -9565,47 +9566,66 @@ var Sandbox = class _Sandbox {
     );
   }
   /**
-   * Block until the sandbox reports ready, or *timeout* seconds elapse.
+   * Block until the sandbox reports ready, or the caller's *timeout* seconds
+   * (the full deadline budget) elapse.
    *
-   * When `stream` is `true` (the default) this opens an SSE connection
-   * to `GET /sandboxes/:id/readiness/stream` and waits for an
-   * `event: ready` frame. The server emits `ready` immediately if the
-   * sandbox is already ready, otherwise as soon as the readiness PubSub
-   * message fires.
+   * When `stream` is `true` (the default) this opens an SSE connection to
+   * `GET /sandboxes/:id/readiness/stream?timeout=<window>` and waits for an
+   * `event: ready` frame. `<window>` is the caller's remaining budget clamped
+   * to {@link READINESS_STREAM_MAX_TIMEOUT_SEC}, the server's own maximum
+   * lease for a single stream connection — a long-restoring persistent
+   * sandbox (e.g. Docker restore, 60-90 s) legitimately outlives one lease.
+   * The server emits `ready` immediately if the sandbox is already ready,
+   * `event: timeout` when *that connection's* window elapses without a
+   * verdict, and `event: error` on a terminal boot failure.
    *
-   * Returns `true` once the sandbox is ready, `false` on `event: timeout`
-   * or when the local timeout elapses before ready.
+   * An `event: timeout` (or the stream closing without a verdict) is NOT
+   * treated as the final answer while the caller's overall deadline still has
+   * budget left — that would silently truncate a 180 s wait down to the
+   * server's lease window and return `false` while the sandbox was still
+   * mid-restore. Instead this reconnects the stream (or falls back to
+   * polling) for the remaining budget. `false` is only returned once the
+   * caller's full deadline has elapsed.
    *
    * Throws {@link MiosaError} with code `SANDBOX_BOOT_FAILED` as soon as the
    * sandbox is observed in a terminal failure state (`error` or `destroyed`)
    * while waiting, instead of silently exhausting the timeout and returning
    * `false` — a permanent boot failure and "still booting, keep waiting" must
-   * never look the same to the caller. The readiness SSE stream itself has no
-   * dedicated failure event today (the server only ever emits
-   * `ready`/`status`/`timeout`), so on `event: timeout` this makes one
-   * authoritative {@link readiness} check before giving up, to catch a
-   * failure that landed right at the boundary.
+   * never look the same to the caller. On each `event: timeout` boundary this
+   * also makes one authoritative {@link readiness} check before deciding to
+   * reconnect or stop, to catch a failure that landed right at the boundary.
    *
    * If the SSE endpoint returns 404 (server pre-dates the streaming
    * endpoint) this transparently falls back to polling {@link readiness}
-   * every 10 ms until ready, timeout, or terminal failure.
+   * every 10 ms until ready, the caller's deadline elapses, or terminal
+   * failure.
    */
   async waitUntilReady(options = {}) {
     const timeout = options.timeout ?? 30;
     const stream = options.stream ?? true;
     const requireCommandReady = options.requireCommandReady ?? true;
+    const deadlineMs = Date.now() + timeout * 1e3;
     if (stream) {
-      const sseResult = await this.tryReadinessStream(timeout);
-      if (sseResult === true) {
-        await this.adoptReadyState();
-        return true;
-      }
-      if (sseResult === false) {
-        await this.throwIfTerminallyFailed();
-        return false;
+      while (true) {
+        const remainingMs = deadlineMs - Date.now();
+        if (remainingMs <= 0) return false;
+        const remainingSec = remainingMs / 1e3;
+        const clamped = remainingSec > READINESS_STREAM_MAX_TIMEOUT_SEC;
+        const windowSec = clamped ? READINESS_STREAM_MAX_TIMEOUT_SEC : remainingSec;
+        const sseResult = await this.tryReadinessStream(windowSec);
+        if (sseResult === true) {
+          await this.adoptReadyState();
+          return true;
+        }
+        if (sseResult === false) {
+          await this.throwIfTerminallyFailed();
+          if (!clamped || Date.now() >= deadlineMs) return false;
+          continue;
+        }
+        break;
       }
+      if (Date.now() >= deadlineMs) return false;
     }
-    const deadlineMs = Date.now() + timeout * 1e3;
     while (Date.now() < deadlineMs) {
       try {
         const data = await this.readiness();
@@ -9669,9 +9689,25 @@ var Sandbox = class _Sandbox {
    * stream endpoint is unavailable (404 or transport error) so callers
    * can fall back to polling.
    */
-  async tryReadinessStream(timeoutSec) {
+  /**
+   * Opens one readiness SSE connection for at most *windowSec* seconds (this
+   * is a single lease, not the caller's overall {@link waitUntilReady}
+   * budget — see there for how leases are chained). *windowSec* is sent to
+   * the server as `?timeout=<seconds>` so the server's own stream deadline
+   * matches what was actually requested instead of always falling back to
+   * its 30 s default, which is what let a 180 s `waitUntilReady` call get
+   * cut short at 30 s.
+   */
+  async tryReadinessStream(windowSec) {
+    const clampedWindowSec = Math.max(
+      1,
+      Math.min(windowSec, READINESS_STREAM_MAX_TIMEOUT_SEC)
+    );
     const abort = new AbortController();
-    const timer = setTimeout(() => abort.abort(), (timeoutSec + 5) * 1e3);
+    const timer = setTimeout(
+      () => abort.abort(),
+      (clampedWindowSec + 5) * 1e3
+    );
     try {
       const headers = {
         Authorization: `Bearer ${this.http.apiKey}`,
@@ -9683,7 +9719,7 @@ var Sandbox = class _Sandbox {
         "User-Agent": SDK_USER_AGENT
       };
       const response = await fetch(
-        `${this.http.baseUrl}/sandboxes/${this.id}/readiness/stream`,
+        `${this.http.baseUrl}/sandboxes/${this.id}/readiness/stream?timeout=${clampedWindowSec}`,
         { method: "GET", headers, signal: abort.signal }
       );
       if (response.status === 404) return null;
@@ -9704,6 +9740,7 @@ var Sandbox = class _Sandbox {
               const evt = line.slice(6).trim();
               if (evt === "ready") return true;
               if (evt === "timeout") return false;
+              if (evt === "error") throw this.bootFailedError("error");
             }
           }
         }
@@ -9714,7 +9751,10 @@ var Sandbox = class _Sandbox {
         }
       }
       return null;
-    } catch {
+    } catch (err) {
+      if (err instanceof MiosaError && err.code === "SANDBOX_BOOT_FAILED") {
+        throw err;
+      }
       return null;
     } finally {
       clearTimeout(timer);