@alibaba-group/opensandbox 0.1.4 → 0.1.6

package/dist/cjs/index.cjs

@@ -31,6 +31,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   ConnectionConfig: () => ConnectionConfig,
+  DEFAULT_EGRESS_PORT: () => DEFAULT_EGRESS_PORT,
   DEFAULT_ENTRYPOINT: () => DEFAULT_ENTRYPOINT,
   DEFAULT_EXECD_PORT: () => DEFAULT_EXECD_PORT,
   DEFAULT_HEALTH_CHECK_POLLING_INTERVAL_MILLIS: () => DEFAULT_HEALTH_CHECK_POLLING_INTERVAL_MILLIS,
@@ -69,25 +70,26 @@ var SandboxException = class extends Error {
   name = "SandboxException";
   error;
   cause;
+  requestId;
   constructor(opts = {}) {
     super(opts.message);
     this.cause = opts.cause;
     this.error = opts.error ?? new SandboxError(SandboxError.INTERNAL_UNKNOWN_ERROR);
+    this.requestId = opts.requestId;
   }
 };
 var SandboxApiException = class extends SandboxException {
   name = "SandboxApiException";
   statusCode;
-  requestId;
   rawBody;
   constructor(opts) {
     super({
       message: opts.message,
       cause: opts.cause,
-      error: opts.error ?? new SandboxError(SandboxError.UNEXPECTED_RESPONSE, opts.message)
+      error: opts.error ?? new SandboxError(SandboxError.UNEXPECTED_RESPONSE, opts.message),
+      requestId: opts.requestId
     });
     this.statusCode = opts.statusCode;
-    this.requestId = opts.requestId;
     this.rawBody = opts.rawBody;
   }
 };
@@ -143,8 +145,19 @@ function createExecdClient(opts) {
   });
 }
 
-// src/openapi/lifecycleClient.ts
+// src/openapi/egressClient.ts
 var import_openapi_fetch2 = __toESM(require("openapi-fetch"), 1);
+function createEgressClient(opts) {
+  const createClientFn = import_openapi_fetch2.default.default ?? import_openapi_fetch2.default;
+  return createClientFn({
+    baseUrl: opts.baseUrl,
+    headers: opts.headers,
+    fetch: opts.fetch
+  });
+}
+
+// src/openapi/lifecycleClient.ts
+var import_openapi_fetch3 = __toESM(require("openapi-fetch"), 1);
 function readEnvApiKey() {
   const env = globalThis?.process?.env;
   const v = env?.OPEN_SANDBOX_API_KEY;
@@ -158,7 +171,7 @@ function createLifecycleClient(opts = {}) {
   if (apiKey && !headers["OPEN-SANDBOX-API-KEY"]) {
     headers["OPEN-SANDBOX-API-KEY"] = apiKey;
   }
-  const createClientFn = import_openapi_fetch2.default.default ?? import_openapi_fetch2.default;
+  const createClientFn = import_openapi_fetch3.default.default ?? import_openapi_fetch3.default;
   return createClientFn({
     baseUrl: opts.baseUrl ?? "http://localhost:8080/v1",
     headers,
@@ -322,6 +335,9 @@ function joinUrl(baseUrl, pathname) {
   return `${base}${path}`;
 }
 function toRunCommandRequest(command, opts) {
+  if (opts?.gid != null && opts.uid == null) {
+    throw new Error("uid is required when gid is provided");
+  }
   const body = {
     command,
     cwd: opts?.workingDirectory,
@@ -330,8 +346,39 @@ function toRunCommandRequest(command, opts) {
   if (opts?.timeoutSeconds != null) {
     body.timeout = Math.round(opts.timeoutSeconds * 1e3);
   }
+  if (opts?.uid != null) {
+    body.uid = opts.uid;
+  }
+  if (opts?.gid != null) {
+    body.gid = opts.gid;
+  }
+  if (opts?.envs != null) {
+    body.envs = opts.envs;
+  }
   return body;
 }
+function toRunInSessionRequest(command, opts) {
+  const body = {
+    command
+  };
+  if (opts?.workingDirectory != null) {
+    body.cwd = opts.workingDirectory;
+  }
+  if (opts?.timeoutSeconds != null) {
+    body.timeout = Math.round(opts.timeoutSeconds * 1e3);
+  }
+  return body;
+}
+function inferForegroundExitCode(execution) {
+  const errorValue = execution.error?.value?.trim();
+  const parsedExitCode = errorValue && /^-?\d+$/.test(errorValue) ? Number(errorValue) : Number.NaN;
+  return execution.error != null ? Number.isFinite(parsedExitCode) ? parsedExitCode : null : execution.complete ? 0 : null;
+}
+function assertNonBlank(value, field) {
+  if (!value.trim()) {
+    throw new Error(`${field} cannot be empty`);
+  }
+}
 function parseOptionalDate(value, field) {
   if (value == null) return void 0;
   if (value instanceof Date) return value;
@@ -351,6 +398,58 @@ var CommandsAdapter = class {
     this.fetch = opts.fetch ?? fetch;
   }
   fetch;
+  buildRunStreamSpec(command, opts) {
+    assertNonBlank(command, "command");
+    return {
+      pathname: "/command",
+      body: toRunCommandRequest(command, opts),
+      fallbackErrorMessage: "Run command failed"
+    };
+  }
+  buildRunInSessionStreamSpec(sessionId, command, opts) {
+    assertNonBlank(sessionId, "sessionId");
+    assertNonBlank(command, "command");
+    return {
+      pathname: `/session/${encodeURIComponent(sessionId)}/run`,
+      body: toRunInSessionRequest(command, opts),
+      fallbackErrorMessage: "Run in session failed"
+    };
+  }
+  async *streamExecution(spec, signal) {
+    const url = joinUrl(this.opts.baseUrl, spec.pathname);
+    const res = await this.fetch(url, {
+      method: "POST",
+      headers: {
+        accept: "text/event-stream",
+        "content-type": "application/json",
+        ...this.opts.headers ?? {}
+      },
+      body: JSON.stringify(spec.body),
+      signal
+    });
+    for await (const ev of parseJsonEventStream(res, {
+      fallbackErrorMessage: spec.fallbackErrorMessage
+    })) {
+      yield ev;
+    }
+  }
+  async consumeExecutionStream(stream, handlers, inferExitCode = false) {
+    const execution = {
+      logs: { stdout: [], stderr: [] },
+      result: []
+    };
+    const dispatcher = new ExecutionEventDispatcher(execution, handlers);
+    for await (const ev of stream) {
+      if (ev.type === "init" && (ev.text ?? "") === "" && execution.id) {
+        ev.text = execution.id;
+      }
+      await dispatcher.dispatch(ev);
+    }
+    if (inferExitCode) {
+      execution.exitCode = inferForegroundExitCode(execution);
+    }
+    return execution;
+  }
   async interrupt(sessionId) {
     const { error, response } = await this.client.DELETE("/command", {
       params: { query: { id: sessionId } }
@@ -394,35 +493,76 @@ var CommandsAdapter = class {
     };
   }
   async *runStream(command, opts, signal) {
-    const url = joinUrl(this.opts.baseUrl, "/command");
-    const body = JSON.stringify(toRunCommandRequest(command, opts));
-    const res = await this.fetch(url, {
-      method: "POST",
-      headers: {
-        "accept": "text/event-stream",
-        "content-type": "application/json",
-        ...this.opts.headers ?? {}
-      },
-      body,
+    for await (const ev of this.streamExecution(
+      this.buildRunStreamSpec(command, opts),
       signal
-    });
-    for await (const ev of parseJsonEventStream(res, { fallbackErrorMessage: "Run command failed" })) {
+    )) {
       yield ev;
     }
   }
   async run(command, opts, handlers, signal) {
-    const execution = {
-      logs: { stdout: [], stderr: [] },
-      result: []
-    };
-    const dispatcher = new ExecutionEventDispatcher(execution, handlers);
-    for await (const ev of this.runStream(command, opts, signal)) {
-      if (ev.type === "init" && (ev.text ?? "") === "" && execution.id) {
-        ev.text = execution.id;
-      }
-      await dispatcher.dispatch(ev);
+    return this.consumeExecutionStream(
+      this.runStream(command, opts, signal),
+      handlers,
+      !opts?.background
+    );
+  }
+  async createSession(options) {
+    const body = options?.workingDirectory != null ? { cwd: options.workingDirectory } : {};
+    const { data, error, response } = await this.client.POST("/session", {
+      body
+    });
+    throwOnOpenApiFetchError({ error, response }, "Create session failed");
+    const ok = data;
+    if (!ok || typeof ok.session_id !== "string") {
+      throw new Error("Create session failed: unexpected response shape");
     }
-    return execution;
+    return ok.session_id;
+  }
+  async *runInSessionStream(sessionId, command, opts, signal) {
+    for await (const ev of this.streamExecution(
+      this.buildRunInSessionStreamSpec(sessionId, command, opts),
+      signal
+    )) {
+      yield ev;
+    }
+  }
+  async runInSession(sessionId, command, options, handlers, signal) {
+    return this.consumeExecutionStream(
+      this.runInSessionStream(sessionId, command, options, signal),
+      handlers,
+      true
+    );
+  }
+  async deleteSession(sessionId) {
+    const { error, response } = await this.client.DELETE(
+      "/session/{sessionId}",
+      { params: { path: { sessionId } } }
+    );
+    throwOnOpenApiFetchError({ error, response }, "Delete session failed");
+  }
+};
+
+// src/adapters/egressAdapter.ts
+var EgressAdapter = class {
+  constructor(client) {
+    this.client = client;
+  }
+  async getPolicy() {
+    const { data, error, response } = await this.client.GET("/policy");
+    throwOnOpenApiFetchError({ error, response }, "Get sandbox egress policy failed");
+    const raw = data;
+    if (!raw || typeof raw !== "object" || !raw.policy || typeof raw.policy !== "object") {
+      throw new Error("Get sandbox egress policy failed: unexpected response shape");
+    }
+    return raw.policy;
+  }
+  async patchRules(rules) {
+    const body = rules;
+    const { error, response } = await this.client.PATCH("/policy", {
+      body
+    });
+    throwOnOpenApiFetchError({ error, response }, "Patch sandbox egress rules failed");
   }
 };
 
@@ -911,11 +1051,15 @@ var SandboxesAdapter = class {
     }
     return d;
   }
+  parseOptionalIsoDate(field, v) {
+    if (v == null) return null;
+    return this.parseIsoDate(field, v);
+  }
   mapSandboxInfo(raw) {
     return {
       ...raw ?? {},
       createdAt: this.parseIsoDate("createdAt", raw?.createdAt),
-      expiresAt: this.parseIsoDate("expiresAt", raw?.expiresAt)
+      expiresAt: this.parseOptionalIsoDate("expiresAt", raw?.expiresAt)
     };
   }
   async createSandbox(req) {
@@ -931,7 +1075,7 @@ var SandboxesAdapter = class {
     return {
       ...raw ?? {},
       createdAt: this.parseIsoDate("createdAt", raw?.createdAt),
-      expiresAt: this.parseIsoDate("expiresAt", raw?.expiresAt)
+      expiresAt: this.parseOptionalIsoDate("expiresAt", raw?.expiresAt)
     };
   }
   async getSandbox(sandboxId) {
@@ -1056,6 +1200,20 @@ var DefaultAdapterFactory = class {
       metrics
     };
   }
+  createEgressStack(opts) {
+    const headers = {
+      ...opts.connectionConfig.headers ?? {},
+      ...opts.endpointHeaders ?? {}
+    };
+    const egressClient = createEgressClient({
+      baseUrl: opts.egressBaseUrl,
+      headers,
+      fetch: opts.connectionConfig.fetch
+    });
+    return {
+      egress: new EgressAdapter(egressClient)
+    };
+  }
 };
 function createDefaultAdapterFactory() {
   return new DefaultAdapterFactory();
@@ -1063,6 +1221,7 @@ function createDefaultAdapterFactory() {
 
 // src/core/constants.ts
 var DEFAULT_EXECD_PORT = 44772;
+var DEFAULT_EGRESS_PORT = 18080;
 var DEFAULT_ENTRYPOINT = ["tail", "-f", "/dev/null"];
 var DEFAULT_RESOURCE_LIMITS = {
   cpu: "1",
@@ -1072,7 +1231,7 @@ var DEFAULT_TIMEOUT_SECONDS = 600;
 var DEFAULT_READY_TIMEOUT_SECONDS = 30;
 var DEFAULT_HEALTH_CHECK_POLLING_INTERVAL_MILLIS = 200;
 var DEFAULT_REQUEST_TIMEOUT_SECONDS = 30;
-var DEFAULT_USER_AGENT = "OpenSandbox-JS-SDK/0.1.4";
+var DEFAULT_USER_AGENT = "OpenSandbox-JS-SDK/0.1.6";
 
 // src/config/connection.ts
 function isNodeRuntime2() {
@@ -1393,6 +1552,7 @@ var SandboxManager = class _SandboxManager {
 };
 
 // src/sandbox.ts
+var HOST_PATH_PATTERN = /^([/]|[A-Za-z]:[\\/])/;
 function sleep(ms) {
   return new Promise((r) => setTimeout(r, ms));
 }
@@ -1429,7 +1589,8 @@ var Sandbox = class _Sandbox {
     _Sandbox._priv.set(this, {
       adapterFactory: opts.adapterFactory,
       lifecycleBaseUrl: opts.lifecycleBaseUrl,
-      execdBaseUrl: opts.execdBaseUrl
+      execdBaseUrl: opts.execdBaseUrl,
+      egress: opts.egress
     });
     this.sandboxes = opts.sandboxes;
     this.commands = opts.commands;
@@ -1438,6 +1599,26 @@ var Sandbox = class _Sandbox {
     this.metrics = opts.metrics;
   }
   static async create(opts) {
+    if (opts.volumes) {
+      for (const vol of opts.volumes) {
+        const backendsSpecified = [vol.host, vol.pvc, vol.ossfs].filter((b) => b != null).length;
+        if (backendsSpecified === 0) {
+          throw new Error(
+            `Volume '${vol.name}' must specify exactly one backend (host, pvc, ossfs), but none was provided.`
+          );
+        }
+        if (backendsSpecified > 1) {
+          throw new Error(
+            `Volume '${vol.name}' must specify exactly one backend (host, pvc, ossfs), but multiple were provided.`
+          );
+        }
+        if (vol.host && !HOST_PATH_PATTERN.test(vol.host.path)) {
+          throw new Error(
+            "Host path must be an absolute path starting with '/' or a Windows drive letter (e.g. 'C:\\' or 'D:/')"
+          );
+        }
+      }
+    }
     const baseConnectionConfig = opts.connectionConfig instanceof ConnectionConfig ? opts.connectionConfig : new ConnectionConfig(opts.connectionConfig);
     const connectionConfig = baseConnectionConfig.withTransportIfMissing();
     const lifecycleBaseUrl = connectionConfig.getBaseUrl();
@@ -1452,25 +1633,16 @@ var Sandbox = class _Sandbox {
       await connectionConfig.closeTransport();
       throw err;
     }
-    if (opts.volumes) {
-      for (const vol of opts.volumes) {
-        const backendsSpecified = [vol.host, vol.pvc].filter((b) => b !== void 0).length;
-        if (backendsSpecified === 0) {
-          throw new Error(
-            `Volume '${vol.name}' must specify exactly one backend (host, pvc), but none was provided.`
-          );
-        }
-        if (backendsSpecified > 1) {
-          throw new Error(
-            `Volume '${vol.name}' must specify exactly one backend (host, pvc), but multiple were provided.`
-          );
-        }
-      }
+    const rawTimeout = opts.timeoutSeconds ?? DEFAULT_TIMEOUT_SECONDS;
+    const timeoutSeconds = opts.timeoutSeconds === null ? null : Math.floor(rawTimeout);
+    if (timeoutSeconds !== null && !Number.isFinite(timeoutSeconds)) {
+      throw new Error(
+        `timeoutSeconds must be a finite number, got ${opts.timeoutSeconds}`
+      );
     }
     const req = {
       image: toImageSpec(opts.image),
       entrypoint: opts.entrypoint ?? DEFAULT_ENTRYPOINT,
-      timeout: Math.floor(opts.timeoutSeconds ?? DEFAULT_TIMEOUT_SECONDS),
       resourceLimits: opts.resource ?? DEFAULT_RESOURCE_LIMITS,
       env: opts.env ?? {},
       metadata: opts.metadata ?? {},
@@ -1481,6 +1653,9 @@ var Sandbox = class _Sandbox {
       volumes: opts.volumes,
       extensions: opts.extensions ?? {}
     };
+    if (timeoutSeconds !== null) {
+      req.timeout = timeoutSeconds;
+    }
     let sandboxId;
     try {
       const created = await sandboxes.createSandbox(req);
@@ -1490,12 +1665,23 @@ var Sandbox = class _Sandbox {
         DEFAULT_EXECD_PORT,
         connectionConfig.useServerProxy
       );
+      const egressEndpoint = await sandboxes.getSandboxEndpoint(
+        sandboxId,
+        DEFAULT_EGRESS_PORT,
+        connectionConfig.useServerProxy
+      );
       const execdBaseUrl = `${connectionConfig.protocol}://${endpoint.endpoint}`;
+      const egressBaseUrl = `${connectionConfig.protocol}://${egressEndpoint.endpoint}`;
       const { commands, files, health, metrics } = adapterFactory.createExecdStack({
         connectionConfig,
         execdBaseUrl,
         endpointHeaders: endpoint.headers
       });
+      const { egress } = adapterFactory.createEgressStack({
+        connectionConfig,
+        egressBaseUrl,
+        endpointHeaders: egressEndpoint.headers
+      });
       const sbx = new _Sandbox({
         id: sandboxId,
         connectionConfig,
@@ -1506,7 +1692,8 @@ var Sandbox = class _Sandbox {
         commands,
         files,
         health,
-        metrics
+        metrics,
+        egress
       });
       if (!(opts.skipHealthCheck ?? false)) {
         await sbx.waitUntilReady({
@@ -1548,12 +1735,23 @@ var Sandbox = class _Sandbox {
         DEFAULT_EXECD_PORT,
         connectionConfig.useServerProxy
       );
+      const egressEndpoint = await sandboxes.getSandboxEndpoint(
+        opts.sandboxId,
+        DEFAULT_EGRESS_PORT,
+        connectionConfig.useServerProxy
+      );
       const execdBaseUrl = `${connectionConfig.protocol}://${endpoint.endpoint}`;
+      const egressBaseUrl = `${connectionConfig.protocol}://${egressEndpoint.endpoint}`;
       const { commands, files, health, metrics } = adapterFactory.createExecdStack({
         connectionConfig,
         execdBaseUrl,
         endpointHeaders: endpoint.headers
       });
+      const { egress } = adapterFactory.createEgressStack({
+        connectionConfig,
+        egressBaseUrl,
+        endpointHeaders: egressEndpoint.headers
+      });
       const sbx = new _Sandbox({
         id: opts.sandboxId,
         connectionConfig,
@@ -1564,7 +1762,8 @@ var Sandbox = class _Sandbox {
         commands,
         files,
         health,
-        metrics
+        metrics,
+        egress
       });
       if (!(opts.skipHealthCheck ?? false)) {
         await sbx.waitUntilReady({
@@ -1652,6 +1851,12 @@ var Sandbox = class _Sandbox {
     ).toISOString();
     return await this.sandboxes.renewSandboxExpiration(this.id, { expiresAt });
   }
+  async getEgressPolicy() {
+    return await _Sandbox._priv.get(this).egress.getPolicy();
+  }
+  async patchEgressRules(rules) {
+    await _Sandbox._priv.get(this).egress.patchRules(rules);
+  }
   /**
    * Get sandbox endpoint for a port (STRICT: no scheme), e.g. "localhost:44772" or "domain/route/.../44772".
    */
@@ -1671,21 +1876,39 @@ var Sandbox = class _Sandbox {
   }
   async waitUntilReady(opts) {
     const deadline = Date.now() + opts.readyTimeoutSeconds * 1e3;
+    let attempt = 0;
+    let errorDetail = "Health check returned false continuously.";
+    const buildTimeoutMessage = () => {
+      const context = `domain=${this.connectionConfig.domain}, useServerProxy=${this.connectionConfig.useServerProxy}`;
+      let suggestion = "If this sandbox runs in Docker bridge or remote-network mode, consider enabling useServerProxy=true.";
+      if (!this.connectionConfig.useServerProxy) {
+        suggestion += " You can also configure server-side [docker].host_ip for direct endpoint access.";
+      }
+      return `Sandbox health check timed out after ${opts.readyTimeoutSeconds}s (${attempt} attempts). ${errorDetail} Connection context: ${context}. ${suggestion}`;
+    };
     while (true) {
       if (Date.now() > deadline) {
         throw new SandboxReadyTimeoutException({
-          message: `Sandbox not ready: timed out waiting for health check (timeoutSeconds=${opts.readyTimeoutSeconds})`
+          message: buildTimeoutMessage()
         });
       }
+      attempt++;
       try {
         if (opts.healthCheck) {
           const ok = await opts.healthCheck(this);
-          if (ok) return;
+          if (ok) {
+            return;
+          }
         } else {
           const ok = await this.health.ping();
-          if (ok) return;
+          if (ok) {
+            return;
+          }
         }
-      } catch {
+        errorDetail = "Health check returned false continuously.";
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        errorDetail = `Last health check error: ${message}`;
       }
       await sleep(opts.pollingIntervalMillis);
     }
@@ -1694,6 +1917,7 @@ var Sandbox = class _Sandbox {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ConnectionConfig,
+  DEFAULT_EGRESS_PORT,
   DEFAULT_ENTRYPOINT,
   DEFAULT_EXECD_PORT,
   DEFAULT_HEALTH_CHECK_POLLING_INTERVAL_MILLIS,