computesdk 1.11.0 → 1.12.0

package/dist/index.mjs

@@ -1337,13 +1337,38 @@ var Server = class {
     this.updateStatusHandler = handlers.updateStatus;
   }
   /**
-   * Start a new managed server
+   * Start a new managed server with optional supervisor settings
+   *
+   * **Restart Policies:**
+   * - `never` (default): No automatic restart on exit
+   * - `on-failure`: Restart only on non-zero exit code
+   * - `always`: Always restart on exit (including exit code 0)
+   *
+   * **Graceful Shutdown:**
+   * When stopping a server, it first sends SIGTERM and waits for `stop_timeout_ms`
+   * before sending SIGKILL if the process hasn't exited.
+   *
    * @param options - Server configuration
-   * @param options.slug - Unique server slug (URL-safe identifier)
-   * @param options.command - Command to start the server
-   * @param options.path - Working directory (optional)
-   * @param options.env_file - Path to env file (optional)
    * @returns Server info
+   *
+   * @example
+   * ```typescript
+   * // Basic server
+   * const server = await sandbox.server.start({
+   *   slug: 'web',
+   *   command: 'npm run dev',
+   *   path: '/app',
+   * });
+   *
+   * // With supervisor settings
+   * const server = await sandbox.server.start({
+   *   slug: 'api',
+   *   command: 'node server.js',
+   *   environment: { NODE_ENV: 'production' },
+   *   restart_policy: 'always',
+   *   max_restarts: 0, // unlimited
+   * });
+   * ```
    */
   async start(options) {
     const response = await this.startHandler(options);
@@ -2743,8 +2768,40 @@ API request failed (${response.status}): ${error}`
     return this.request("/servers");
   }
   /**
-   * Start a new managed server
+   * Start a new managed server with optional supervisor settings
+   *
    * @param options - Server configuration
+   * @param options.slug - Unique server identifier
+   * @param options.command - Command to start the server
+   * @param options.path - Working directory (optional)
+   * @param options.env_file - Path to .env file relative to path (optional)
+   * @param options.environment - Inline environment variables (merged with env_file if both provided)
+   * @param options.restart_policy - When to automatically restart: 'never' (default), 'on-failure', 'always'
+   * @param options.max_restarts - Maximum restart attempts, 0 = unlimited (default: 0)
+   * @param options.restart_delay_ms - Delay between restart attempts in milliseconds (default: 1000)
+   * @param options.stop_timeout_ms - Graceful shutdown timeout in milliseconds (default: 10000)
+   *
+   * @example
+   * ```typescript
+   * // Basic server
+   * await sandbox.startServer({
+   *   slug: 'web',
+   *   command: 'npm run dev',
+   *   path: '/app',
+   * });
+   *
+   * // With supervisor settings
+   * await sandbox.startServer({
+   *   slug: 'api',
+   *   command: 'node server.js',
+   *   path: '/app',
+   *   environment: { NODE_ENV: 'production', PORT: '3000' },
+   *   restart_policy: 'on-failure',
+   *   max_restarts: 5,
+   *   restart_delay_ms: 2000,
+   *   stop_timeout_ms: 5000,
+   * });
+   * ```
    */
   async startServer(options) {
     return this.request("/servers", {
@@ -3567,6 +3624,34 @@ async function gatewayFetch(url, config, options = {}) {
     throw error;
   }
 }
+async function waitForSandboxStatus(config, endpoint, body, options = {}) {
+  const maxWaitMs = options.maxWaitMs ?? 6e4;
+  const initialDelayMs = 500;
+  const maxDelayMs = 2e3;
+  const backoffFactor = 1.5;
+  const startTime = Date.now();
+  let currentDelay = initialDelayMs;
+  while (Date.now() - startTime < maxWaitMs) {
+    const result = await gatewayFetch(endpoint, config, {
+      method: "POST",
+      body: JSON.stringify(body)
+    });
+    if (!result.success || !result.data) {
+      return result;
+    }
+    if (result.data.status !== "creating") {
+      return result;
+    }
+    if (process.env.COMPUTESDK_DEBUG) {
+      console.log(`[Compute] Sandbox still creating, waiting ${currentDelay}ms...`);
+    }
+    await new Promise((resolve) => setTimeout(resolve, currentDelay));
+    currentDelay = Math.min(currentDelay * backoffFactor, maxDelayMs);
+  }
+  throw new Error(
+    `Sandbox is still being created after ${maxWaitMs}ms. This may indicate the sandbox failed to start. Check your provider dashboard.`
+  );
+}
 var ComputeManager = class {
   constructor() {
     this.config = null;
@@ -3654,14 +3739,15 @@ var ComputeManager = class {
       findOrCreate: async (options) => {
         const config = this.getGatewayConfig();
         const { name, namespace, ...restOptions } = options;
-        const result = await gatewayFetch(`${config.gatewayUrl}/v1/sandboxes/find-or-create`, config, {
-          method: "POST",
-          body: JSON.stringify({
+        const result = await waitForSandboxStatus(
+          config,
+          `${config.gatewayUrl}/v1/sandboxes/find-or-create`,
+          {
             namespace: namespace || "default",
             name,
             ...restOptions
-          })
-        });
+          }
+        );
         if (!result.success || !result.data) {
           throw new Error(`Gateway returned invalid response`);
         }
@@ -3691,13 +3777,14 @@ var ComputeManager = class {
        */
       find: async (options) => {
         const config = this.getGatewayConfig();
-        const result = await gatewayFetch(`${config.gatewayUrl}/v1/sandboxes/find`, config, {
-          method: "POST",
-          body: JSON.stringify({
+        const result = await waitForSandboxStatus(
+          config,
+          `${config.gatewayUrl}/v1/sandboxes/find`,
+          {
             namespace: options.namespace || "default",
             name: options.name
-          })
-        });
+          }
+        );
         if (!result.success || !result.data) {
           return null;
         }