@alibaba-group/opensandbox 0.1.0-dev4 → 0.1.1-dev0

package/src/adapters/sandboxesAdapter.ts

@@ -0,0 +1,187 @@
+// 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 { LifecycleClient } from "../openapi/lifecycleClient.js";
+import { throwOnOpenApiFetchError } from "./openapiError.js";
+import type { paths as LifecyclePaths } from "../api/lifecycle.js";
+import type {
+  Sandboxes,
+} from "../services/sandboxes.js";
+import type {
+  CreateSandboxRequest,
+  CreateSandboxResponse,
+  Endpoint,
+  ListSandboxesParams,
+  ListSandboxesResponse,
+  RenewSandboxExpirationRequest,
+  RenewSandboxExpirationResponse,
+  SandboxId,
+  SandboxInfo,
+} from "../models/sandboxes.js";
+
+type ApiCreateSandboxRequest =
+  LifecyclePaths["/sandboxes"]["post"]["requestBody"]["content"]["application/json"];
+type ApiCreateSandboxOk =
+  LifecyclePaths["/sandboxes"]["post"]["responses"][202]["content"]["application/json"];
+type ApiGetSandboxOk =
+  LifecyclePaths["/sandboxes/{sandboxId}"]["get"]["responses"][200]["content"]["application/json"];
+type ApiListSandboxesOk =
+  LifecyclePaths["/sandboxes"]["get"]["responses"][200]["content"]["application/json"];
+type ApiRenewSandboxExpirationRequest =
+  LifecyclePaths["/sandboxes/{sandboxId}/renew-expiration"]["post"]["requestBody"]["content"]["application/json"];
+type ApiRenewSandboxExpirationOk =
+  LifecyclePaths["/sandboxes/{sandboxId}/renew-expiration"]["post"]["responses"][200]["content"]["application/json"];
+type ApiEndpointOk =
+  LifecyclePaths["/sandboxes/{sandboxId}/endpoints/{port}"]["get"]["responses"][200]["content"]["application/json"];
+
+function encodeMetadataFilter(metadata: Record<string, string>): string {
+  // The Lifecycle API expects a single `metadata` query parameter whose value is `k=v&k2=v2`.
+  // The query serializer will URL-encode the value (e.g. `=` -> %3D and `&` -> %26).
+  const parts: string[] = [];
+  for (const [k, v] of Object.entries(metadata)) {
+    parts.push(`${k}=${v}`);
+  }
+  return parts.join("&");
+}
+
+export class SandboxesAdapter implements Sandboxes {
+  constructor(private readonly client: LifecycleClient) {}
+
+  private parseIsoDate(field: string, v: unknown): Date {
+    if (typeof v !== "string" || !v) {
+      throw new Error(`Invalid ${field}: expected ISO string, got ${typeof v}`);
+    }
+    const d = new Date(v);
+    if (Number.isNaN(d.getTime())) {
+      throw new Error(`Invalid ${field}: ${v}`);
+    }
+    return d;
+  }
+
+  private mapSandboxInfo(raw: ApiGetSandboxOk): SandboxInfo {
+    return {
+      ...(raw ?? {}),
+      createdAt: this.parseIsoDate("createdAt", raw?.createdAt),
+      expiresAt: this.parseIsoDate("expiresAt", raw?.expiresAt),
+    } as SandboxInfo;
+  }
+
+  async createSandbox(req: CreateSandboxRequest): Promise<CreateSandboxResponse> {
+    // Make the OpenAPI contract explicit so backend schema changes surface quickly.
+    const body: ApiCreateSandboxRequest = req as unknown as ApiCreateSandboxRequest;
+    const { data, error, response } = await this.client.POST("/sandboxes", {
+      body,
+    });
+    throwOnOpenApiFetchError({ error, response }, "Create sandbox failed");
+    const raw = data as ApiCreateSandboxOk | undefined;
+    if (!raw || typeof raw !== "object") {
+      throw new Error("Create sandbox failed: unexpected response shape");
+    }
+    return {
+      ...(raw ?? {}),
+      createdAt: this.parseIsoDate("createdAt", raw?.createdAt),
+      expiresAt: this.parseIsoDate("expiresAt", raw?.expiresAt),
+    } as CreateSandboxResponse;
+  }
+
+  async getSandbox(sandboxId: SandboxId): Promise<SandboxInfo> {
+    const { data, error, response } = await this.client.GET("/sandboxes/{sandboxId}", {
+      params: { path: { sandboxId } },
+    });
+    throwOnOpenApiFetchError({ error, response }, "Get sandbox failed");
+    const ok = data as ApiGetSandboxOk | undefined;
+    if (!ok || typeof ok !== "object") {
+      throw new Error("Get sandbox failed: unexpected response shape");
+    }
+    return this.mapSandboxInfo(ok);
+  }
+
+  async listSandboxes(params: ListSandboxesParams = {}): Promise<ListSandboxesResponse> {
+    const query: Record<string, string | number | boolean | undefined | null | (string | number)[]> = {};
+    if (params.states?.length) query.state = params.states;
+    if (params.metadata && Object.keys(params.metadata).length) {
+      query.metadata = encodeMetadataFilter(params.metadata);
+    }
+    if (params.page != null) query.page = params.page;
+    if (params.pageSize != null) query.pageSize = params.pageSize;
+
+    const { data, error, response } = await this.client.GET("/sandboxes", {
+      params: { query },
+    });
+    throwOnOpenApiFetchError({ error, response }, "List sandboxes failed");
+    const raw = data as ApiListSandboxesOk | undefined;
+    if (!raw || typeof raw !== "object") {
+      throw new Error("List sandboxes failed: unexpected response shape");
+    }
+    const itemsRaw = raw.items;
+    if (!Array.isArray(itemsRaw)) throw new Error("List sandboxes failed: unexpected items shape");
+    return {
+      ...(raw ?? {}),
+      items: itemsRaw.map((x) => this.mapSandboxInfo(x)),
+    } as ListSandboxesResponse;
+  }
+
+  async deleteSandbox(sandboxId: SandboxId): Promise<void> {
+    const { error, response } = await this.client.DELETE("/sandboxes/{sandboxId}", {
+      params: { path: { sandboxId } },
+    });
+    throwOnOpenApiFetchError({ error, response }, "Delete sandbox failed");
+  }
+
+  async pauseSandbox(sandboxId: SandboxId): Promise<void> {
+    const { error, response } = await this.client.POST("/sandboxes/{sandboxId}/pause", {
+      params: { path: { sandboxId } },
+    });
+    throwOnOpenApiFetchError({ error, response }, "Pause sandbox failed");
+  }
+
+  async resumeSandbox(sandboxId: SandboxId): Promise<void> {
+    const { error, response } = await this.client.POST("/sandboxes/{sandboxId}/resume", {
+      params: { path: { sandboxId } },
+    });
+    throwOnOpenApiFetchError({ error, response }, "Resume sandbox failed");
+  }
+
+  async renewSandboxExpiration(
+    sandboxId: SandboxId,
+    req: RenewSandboxExpirationRequest,
+  ): Promise<RenewSandboxExpirationResponse> {
+    const body: ApiRenewSandboxExpirationRequest = req as unknown as ApiRenewSandboxExpirationRequest;
+    const { data, error, response } = await this.client.POST("/sandboxes/{sandboxId}/renew-expiration", {
+      params: { path: { sandboxId } },
+      body,
+    });
+    throwOnOpenApiFetchError({ error, response }, "Renew sandbox expiration failed");
+    const raw = data as ApiRenewSandboxExpirationOk | undefined;
+    if (!raw || typeof raw !== "object") {
+      throw new Error("Renew sandbox expiration failed: unexpected response shape");
+    }
+    return {
+      ...(raw ?? {}),
+      expiresAt: raw?.expiresAt ? this.parseIsoDate("expiresAt", raw.expiresAt) : undefined,
+    } as RenewSandboxExpirationResponse;
+  }
+
+  async getSandboxEndpoint(sandboxId: SandboxId, port: number): Promise<Endpoint> {
+    const { data, error, response } = await this.client.GET("/sandboxes/{sandboxId}/endpoints/{port}", {
+      params: { path: { sandboxId, port } },
+    });
+    throwOnOpenApiFetchError({ error, response }, "Get sandbox endpoint failed");
+    const ok = data as ApiEndpointOk | undefined;
+    if (!ok || typeof ok !== "object") {
+      throw new Error("Get sandbox endpoint failed: unexpected response shape");
+    }
+    return ok as unknown as Endpoint;
+  }
+}

package/src/adapters/sse.ts

@@ -0,0 +1,95 @@
+// 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 { SandboxApiException, SandboxError } from "../core/exceptions.js";
+
+function tryParseJson(line: string): unknown | undefined {
+  try {
+    return JSON.parse(line);
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Parses an SSE-like stream that may be either:
+ * - standard SSE frames (`data: {...}\n\n`)
+ * - newline-delimited JSON (one JSON object per line)
+ */
+export async function* parseJsonEventStream<T>(
+  res: Response,
+  opts?: { fallbackErrorMessage?: string },
+): AsyncIterable<T> {
+  if (!res.ok) {
+    const text = await res.text().catch(() => "");
+    const parsed = tryParseJson(text);
+    const err = parsed && typeof parsed === "object" ? (parsed as any) : undefined;
+    const requestId = res.headers.get("x-request-id") ?? undefined;
+    const message = err?.message ?? opts?.fallbackErrorMessage ?? `Stream request failed (status=${res.status})`;
+    const code = err?.code ? String(err.code) : SandboxError.UNEXPECTED_RESPONSE;
+    throw new SandboxApiException({
+      message,
+      statusCode: res.status,
+      requestId,
+      error: new SandboxError(code, err?.message ? String(err.message) : message),
+      rawBody: parsed ?? text,
+    });
+  }
+
+  if (!res.body) {
+    return;
+  }
+
+  const reader = res.body.getReader();
+  const decoder = new TextDecoder("utf-8");
+  let buf = "";
+
+  while (true) {
+    const { value, done } = await reader.read();
+    if (done) break;
+
+    buf += decoder.decode(value, { stream: true });
+    let idx: number;
+
+    while ((idx = buf.indexOf("\n")) >= 0) {
+      const rawLine = buf.slice(0, idx);
+      buf = buf.slice(idx + 1);
+
+      const line = rawLine.trim();
+      if (!line) continue;
+
+      // Support standard SSE "data:" prefix
+      if (line.startsWith(":")) continue;
+      if (line.startsWith("event:") || line.startsWith("id:") || line.startsWith("retry:")) continue;
+
+      const jsonLine = line.startsWith("data:") ? line.slice("data:".length).trim() : line;
+      if (!jsonLine) continue;
+
+      const parsed = tryParseJson(jsonLine);
+      if (!parsed) continue;
+      yield parsed as T;
+    }
+  }
+
+  // Flush any buffered UTF-8 bytes from the decoder.
+  buf += decoder.decode();
+
+  // flush last line if exists
+  const last = buf.trim();
+  if (last) {
+    const jsonLine = last.startsWith("data:") ? last.slice("data:".length).trim() : last;
+    const parsed = tryParseJson(jsonLine);
+    if (parsed) yield parsed as T;
+  }
+}