@alibaba-group/opensandbox 0.1.4 → 0.1.6

package/src/adapters/commandsAdapter.ts

@@ -33,14 +33,31 @@ function joinUrl(baseUrl: string, pathname: string): string {
   return `${base}${path}`;
 }
 
+/** Request body for POST /command (from generated spec; includes uid, gid, envs). */
 type ApiRunCommandRequest =
   ExecdPaths["/command"]["post"]["requestBody"]["content"]["application/json"];
 type ApiCommandStatusOk =
   ExecdPaths["/command/status/{id}"]["get"]["responses"][200]["content"]["application/json"];
 type ApiCommandLogsOk =
   ExecdPaths["/command/{id}/logs"]["get"]["responses"][200]["content"]["text/plain"];
+type ApiCreateSessionRequest =
+  NonNullable<ExecdPaths["/session"]["post"]["requestBody"]>["content"]["application/json"];
+type ApiCreateSessionOk =
+  ExecdPaths["/session"]["post"]["responses"][200]["content"]["application/json"];
+type ApiRunInSessionRequest =
+  ExecdPaths["/session/{sessionId}/run"]["post"]["requestBody"]["content"]["application/json"];
+
+interface StreamingExecutionSpec<TBody> {
+  pathname: string;
+  body: TBody;
+  fallbackErrorMessage: string;
+}
 
 function toRunCommandRequest(command: string, opts?: RunCommandOpts): ApiRunCommandRequest {
+  if (opts?.gid != null && opts.uid == null) {
+    throw new Error("uid is required when gid is provided");
+  }
+
   const body: ApiRunCommandRequest = {
     command,
     cwd: opts?.workingDirectory,
@@ -49,9 +66,51 @@ function toRunCommandRequest(command: string, opts?: RunCommandOpts): ApiRunComm
   if (opts?.timeoutSeconds != null) {
     body.timeout = Math.round(opts.timeoutSeconds * 1000);
   }
+  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: string,
+  opts?: { workingDirectory?: string; timeoutSeconds?: number },
+): ApiRunInSessionRequest {
+  const body: ApiRunInSessionRequest = {
+    command,
+  };
+  if (opts?.workingDirectory != null) {
+    body.cwd = opts.workingDirectory;
+  }
+  if (opts?.timeoutSeconds != null) {
+    body.timeout = Math.round(opts.timeoutSeconds * 1000);
+  }
   return body;
 }
 
+function inferForegroundExitCode(execution: CommandExecution): number | null {
+  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: string, field: string): void {
+  if (!value.trim()) {
+    throw new Error(`${field} cannot be empty`);
+  }
+}
+
 function parseOptionalDate(value: unknown, field: string): Date | undefined {
   if (value == null) return undefined;
   if (value instanceof Date) return value;
@@ -84,6 +143,79 @@ export class CommandsAdapter implements ExecdCommands {
     this.fetch = opts.fetch ?? fetch;
   }
 
+  private buildRunStreamSpec(
+    command: string,
+    opts?: RunCommandOpts,
+  ): StreamingExecutionSpec<ApiRunCommandRequest> {
+    assertNonBlank(command, "command");
+    return {
+      pathname: "/command",
+      body: toRunCommandRequest(command, opts),
+      fallbackErrorMessage: "Run command failed",
+    };
+  }
+
+  private buildRunInSessionStreamSpec(
+    sessionId: string,
+    command: string,
+    opts?: { workingDirectory?: string; timeoutSeconds?: number },
+  ): StreamingExecutionSpec<ApiRunInSessionRequest> {
+    assertNonBlank(sessionId, "sessionId");
+    assertNonBlank(command, "command");
+    return {
+      pathname: `/session/${encodeURIComponent(sessionId)}/run`,
+      body: toRunInSessionRequest(command, opts),
+      fallbackErrorMessage: "Run in session failed",
+    };
+  }
+
+  private async *streamExecution<TBody>(
+    spec: StreamingExecutionSpec<TBody>,
+    signal?: AbortSignal,
+  ): AsyncIterable<ServerStreamEvent> {
+    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<ServerStreamEvent>(res, {
+      fallbackErrorMessage: spec.fallbackErrorMessage,
+    })) {
+      yield ev;
+    }
+  }
+
+  private async consumeExecutionStream(
+    stream: AsyncIterable<ServerStreamEvent>,
+    handlers?: ExecutionHandlers,
+    inferExitCode = false,
+  ): Promise<CommandExecution> {
+    const execution: CommandExecution = {
+      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 as { text?: string }).text = execution.id;
+      }
+      await dispatcher.dispatch(ev as any);
+    }
+
+    if (inferExitCode) {
+      execution.exitCode = inferForegroundExitCode(execution);
+    }
+
+    return execution;
+  }
+
   async interrupt(sessionId: string): Promise<void> {
     const { error, response } = await this.client.DELETE("/command", {
       params: { query: { id: sessionId } },
@@ -134,21 +266,10 @@ export class CommandsAdapter implements ExecdCommands {
     opts?: RunCommandOpts,
     signal?: AbortSignal,
   ): AsyncIterable<ServerStreamEvent> {
-    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<ServerStreamEvent>(res, { fallbackErrorMessage: "Run command failed" })) {
+    )) {
       yield ev;
     }
   }
@@ -159,19 +280,60 @@ export class CommandsAdapter implements ExecdCommands {
     handlers?: ExecutionHandlers,
     signal?: AbortSignal,
   ): Promise<CommandExecution> {
-    const execution: CommandExecution = {
-      logs: { stdout: [], stderr: [] },
-      result: [],
-    };
-    const dispatcher = new ExecutionEventDispatcher(execution, handlers);
-    for await (const ev of this.runStream(command, opts, signal)) {
-      // Keep legacy behavior: if server sends "init" with empty id, preserve previous id.
-      if (ev.type === "init" && (ev.text ?? "") === "" && execution.id) {
-        (ev as any).text = execution.id;
-      }
-      await dispatcher.dispatch(ev as any);
+    return this.consumeExecutionStream(
+      this.runStream(command, opts, signal),
+      handlers,
+      !opts?.background,
+    );
+  }
+
+  async createSession(options?: { workingDirectory?: string }): Promise<string> {
+    const body: ApiCreateSessionRequest =
+      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 as ApiCreateSessionOk | undefined;
+    if (!ok || typeof (ok as { session_id?: string }).session_id !== "string") {
+      throw new Error("Create session failed: unexpected response shape");
     }
+    return (ok as { session_id: string }).session_id;
+  }
 
-    return execution;
+  async *runInSessionStream(
+    sessionId: string,
+    command: string,
+    opts?: { workingDirectory?: string; timeoutSeconds?: number },
+    signal?: AbortSignal,
+  ): AsyncIterable<ServerStreamEvent> {
+    for await (const ev of this.streamExecution(
+      this.buildRunInSessionStreamSpec(sessionId, command, opts),
+      signal,
+    )) {
+      yield ev;
+    }
+  }
+
+  async runInSession(
+    sessionId: string,
+    command: string,
+    options?: { workingDirectory?: string; timeoutSeconds?: number },
+    handlers?: ExecutionHandlers,
+    signal?: AbortSignal,
+  ): Promise<CommandExecution> {
+    return this.consumeExecutionStream(
+      this.runInSessionStream(sessionId, command, options, signal),
+      handlers,
+      true,
+    );
   }
-}
+
+  async deleteSession(sessionId: string): Promise<void> {
+    const { error, response } = await this.client.DELETE(
+      "/session/{sessionId}",
+      { params: { path: { sessionId } } },
+    );
+    throwOnOpenApiFetchError({ error, response }, "Delete session failed");
+  }
+}

package/src/adapters/egressAdapter.ts

@@ -0,0 +1,46 @@
+// Copyright 2026 Alibaba Group Holding Ltd.
+// 
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+// 
+//     http://www.apache.org/licenses/LICENSE-2.0
+// 
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+import type { EgressClient } from "../openapi/egressClient.js";
+import { throwOnOpenApiFetchError } from "./openapiError.js";
+import type { paths as EgressPaths } from "../api/egress.js";
+import type { NetworkPolicy, NetworkRule } from "../models/sandboxes.js";
+import type { Egress } from "../services/egress.js";
+
+type ApiGetPolicyOk =
+  EgressPaths["/policy"]["get"]["responses"][200]["content"]["application/json"];
+type ApiPatchRulesRequest =
+  EgressPaths["/policy"]["patch"]["requestBody"]["content"]["application/json"];
+
+export class EgressAdapter implements Egress {
+  constructor(private readonly client: EgressClient) {}
+
+  async getPolicy(): Promise<NetworkPolicy> {
+    const { data, error, response } = await this.client.GET("/policy");
+    throwOnOpenApiFetchError({ error, response }, "Get sandbox egress policy failed");
+    const raw = data as ApiGetPolicyOk | undefined;
+    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 as NetworkPolicy;
+  }
+
+  async patchRules(rules: NetworkRule[]): Promise<void> {
+    const body: ApiPatchRulesRequest = rules as unknown as ApiPatchRulesRequest;
+    const { error, response } = await this.client.PATCH("/policy", {
+      body,
+    });
+    throwOnOpenApiFetchError({ error, response }, "Patch sandbox egress rules failed");
+  }
+}

package/src/adapters/sandboxesAdapter.ts

@@ -69,11 +69,16 @@ export class SandboxesAdapter implements Sandboxes {
     return d;
   }
 
+  private parseOptionalIsoDate(field: string, v: unknown): Date | null {
+    if (v == null) return null;
+    return this.parseIsoDate(field, v);
+  }
+
   private mapSandboxInfo(raw: ApiGetSandboxOk): SandboxInfo {
     return {
       ...(raw ?? {}),
       createdAt: this.parseIsoDate("createdAt", raw?.createdAt),
-      expiresAt: this.parseIsoDate("expiresAt", raw?.expiresAt),
+      expiresAt: this.parseOptionalIsoDate("expiresAt", raw?.expiresAt),
     } as SandboxInfo;
   }
 
@@ -91,7 +96,7 @@ export class SandboxesAdapter implements Sandboxes {
     return {
       ...(raw ?? {}),
       createdAt: this.parseIsoDate("createdAt", raw?.createdAt),
-      expiresAt: this.parseIsoDate("expiresAt", raw?.expiresAt),
+      expiresAt: this.parseOptionalIsoDate("expiresAt", raw?.expiresAt),
     } as CreateSandboxResponse;
   }
 
@@ -188,4 +193,4 @@ export class SandboxesAdapter implements Sandboxes {
     }
     return ok as unknown as Endpoint;
   }
-}
+}

package/src/api/egress.ts

@@ -0,0 +1,184 @@
+// Copyright 2026 Alibaba Group Holding Ltd..
+// 
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+// 
+//     http://www.apache.org/licenses/LICENSE-2.0
+// 
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * This file was auto-generated by openapi-typescript.
+ * Do not make direct changes to the file.
+ */
+
+export interface paths {
+    "/policy": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Get current egress policy
+         * @description Returns the currently enforced egress policy and the sidecar's derived
+         *     runtime mode metadata.
+         */
+        get: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description Current policy returned successfully. */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["PolicyStatusResponse"];
+                    };
+                };
+                401: components["responses"]["Unauthorized"];
+                500: components["responses"]["InternalServerError"];
+            };
+        };
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        /**
+         * Patch egress rules
+         * @description Merge incoming egress rules with the currently enforced policy.
+         *
+         *     This endpoint uses merge semantics:
+         *     - Existing rules remain unless overridden by incoming rules.
+         *     - Incoming rules are applied with higher priority than existing rules.
+         *     - If multiple incoming rules refer to the same `target`, the first one wins.
+         */
+        patch: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody: {
+                content: {
+                    "application/json": components["schemas"]["NetworkRule"][];
+                };
+            };
+            responses: {
+                /** @description Patch applied successfully. */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["PolicyStatusResponse"];
+                    };
+                };
+                400: components["responses"]["BadRequest"];
+                401: components["responses"]["Unauthorized"];
+                500: components["responses"]["InternalServerError"];
+            };
+        };
+        trace?: never;
+    };
+}
+export type webhooks = Record<string, never>;
+export interface components {
+    schemas: {
+        PolicyStatusResponse: {
+            /**
+             * @description Operation status reported by the sidecar.
+             * @example ok
+             */
+            status?: string;
+            /**
+             * @description Derived runtime mode for the current policy.
+             * @example deny_all
+             */
+            mode?: string;
+            /**
+             * @description Egress sidecar enforcement backend mode.
+             * @example dns
+             */
+            enforcementMode?: string;
+            /** @description Optional human-readable reason when the sidecar returns extra context. */
+            reason?: string;
+            policy?: components["schemas"]["NetworkPolicy"];
+        };
+        /**
+         * @description Egress network policy matching the sidecar `/policy` request body.
+         *     If `defaultAction` is omitted, the sidecar defaults to "deny"; passing an empty
+         *     object or null results in allow-all behavior at startup.
+         */
+        NetworkPolicy: {
+            /**
+             * @description Default action when no egress rule matches. Defaults to "deny".
+             * @enum {string}
+             */
+            defaultAction?: "allow" | "deny";
+            /** @description List of egress rules evaluated in order. */
+            egress?: components["schemas"]["NetworkRule"][];
+        };
+        NetworkRule: {
+            /**
+             * @description Whether to allow or deny matching targets.
+             * @enum {string}
+             */
+            action: "allow" | "deny";
+            /**
+             * @description FQDN or wildcard domain (e.g., "example.com", "*.example.com").
+             *     IP/CIDR not yet supported in the egress MVP.
+             */
+            target: string;
+        };
+    };
+    responses: {
+        /** @description The request was invalid or malformed. */
+        BadRequest: {
+            headers: {
+                [name: string]: unknown;
+            };
+            content: {
+                "text/plain": string;
+            };
+        };
+        /** @description Authentication failed for the egress sidecar. */
+        Unauthorized: {
+            headers: {
+                [name: string]: unknown;
+            };
+            content: {
+                "text/plain": string;
+            };
+        };
+        /** @description The sidecar failed to apply or fetch policy state. */
+        InternalServerError: {
+            headers: {
+                [name: string]: unknown;
+            };
+            content: {
+                "text/plain": string;
+            };
+        };
+    };
+    parameters: never;
+    requestBodies: never;
+    headers: never;
+    pathItems: never;
+}
+export type $defs = Record<string, never>;
+export type operations = Record<string, never>;