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

package/src/config/connection.ts

@@ -0,0 +1,377 @@
+// 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.
+
+export type ConnectionProtocol = "http" | "https";
+
+/**
+ * Options for {@link ConnectionConfig}.
+ *
+ * Most users only need `domain`, `protocol`, and `apiKey`.
+ */
+export interface ConnectionConfigOptions {
+  /**
+   * API server domain (host[:port]) without scheme.
+   * Examples:
+   * - "localhost:8080"
+   * - "api.opensandbox.io"
+   *
+   * You may also pass a full URL (e.g. "http://localhost:8080" or "https://api.example.com").
+   * If the URL includes a path, it will be preserved and `/v1` will be appended automatically.
+   */
+  domain?: string;
+  protocol?: ConnectionProtocol;
+  apiKey?: string;
+  headers?: Record<string, string>;
+
+  /**
+   * Request timeout applied to all SDK HTTP calls (best-effort; wraps fetch).
+   * Defaults to 30 seconds.
+   */
+  requestTimeoutSeconds?: number;
+  /**
+   * Enable basic debug logging for HTTP requests (best-effort).
+   */
+  debug?: boolean;
+}
+
+function isNodeRuntime(): boolean {
+  const p = (globalThis as any)?.process;
+  return !!p?.versions?.node;
+}
+
+function redactHeaders(
+  headers: Record<string, string>
+): Record<string, string> {
+  const out: Record<string, string> = { ...headers };
+  for (const k of Object.keys(out)) {
+    if (k.toLowerCase() === "open-sandbox-api-key") out[k] = "***";
+  }
+  return out;
+}
+
+function readEnv(name: string): string | undefined {
+  const env = (globalThis as any)?.process?.env;
+  const v = env?.[name];
+  return typeof v === "string" && v.length ? v : undefined;
+}
+
+function stripTrailingSlashes(s: string): string {
+  return s.replace(/\/+$/, "");
+}
+
+function stripV1Suffix(s: string): string {
+  const trimmed = stripTrailingSlashes(s);
+  return trimmed.endsWith("/v1") ? trimmed.slice(0, -3) : trimmed;
+}
+
+const DEFAULT_KEEPALIVE_TIMEOUT_MS = 30_000;
+
+function normalizeDomainBase(input: string): {
+  protocol?: ConnectionProtocol;
+  domainBase: string;
+} {
+  // Accept a full URL and preserve its path prefix (if any).
+  if (input.startsWith("http://") || input.startsWith("https://")) {
+    const u = new URL(input);
+    const proto = u.protocol === "https:" ? "https" : "http";
+    // Keep origin + pathname, drop query/hash.
+    const base = `${u.origin}${u.pathname}`;
+    return { protocol: proto, domainBase: stripV1Suffix(base) };
+  }
+
+  // No scheme: treat as "host[:port]" or "host[:port]/prefix" and normalize trailing "/v1" or "/".
+  return { domainBase: stripV1Suffix(input) };
+}
+
+function createNodeFetch(): {
+  fetch: typeof fetch;
+  close: () => Promise<void>;
+} {
+  if (!isNodeRuntime()) {
+    return {
+      fetch,
+      close: async () => {
+        // Browser fetch has no pooled dispatcher to close.
+      },
+    };
+  }
+
+  const baseFetch = fetch;
+  let dispatcher: unknown | undefined;
+  let dispatcherPromise: Promise<unknown> | null = null;
+
+  const nodeFetch: typeof fetch = async (input: RequestInfo | URL, init?: RequestInit) => {
+    dispatcherPromise ??= (async () => {
+      try {
+        const mod = await import("undici");
+        const Agent = (mod as { Agent?: new (...args: any[]) => unknown }).Agent;
+        if (!Agent) {
+          return undefined;
+        }
+        dispatcher = new Agent({
+          keepAliveTimeout: DEFAULT_KEEPALIVE_TIMEOUT_MS,
+          keepAliveMaxTimeout: DEFAULT_KEEPALIVE_TIMEOUT_MS,
+        });
+        return dispatcher;
+      } catch {
+        return undefined;
+      }
+    })();
+
+    if (dispatcherPromise) {
+      await dispatcherPromise;
+    }
+
+    if (dispatcher) {
+      const mergedInit = { ...(init ?? {}), dispatcher } as RequestInit & {
+        dispatcher?: unknown;
+      };
+      return baseFetch(input, mergedInit as RequestInit);
+    }
+
+    return baseFetch(input, init);
+  };
+
+  return {
+    fetch: nodeFetch,
+    close: async () => {
+      if (dispatcherPromise) {
+        await dispatcherPromise.catch(() => undefined);
+      }
+      if (
+        dispatcher &&
+        typeof dispatcher === "object" &&
+        typeof (dispatcher as any).close === "function"
+      ) {
+        try {
+          await (dispatcher as any).close();
+        } catch {
+          // swallow close errors
+        }
+      }
+    },
+  };
+}
+
+function createTimedFetch(opts: {
+  baseFetch: typeof fetch;
+  timeoutSeconds: number;
+  debug: boolean;
+  defaultHeaders?: Record<string, string>;
+  label: string;
+}): typeof fetch {
+  const baseFetch = opts.baseFetch;
+  const timeoutSeconds = opts.timeoutSeconds;
+  const debug = opts.debug;
+  const defaultHeaders = opts.defaultHeaders ?? {};
+  const label = opts.label;
+
+  return async (input: RequestInfo | URL, init?: RequestInit) => {
+    const method = init?.method ?? "GET";
+    const url =
+      typeof input === "string"
+        ? input
+        : (input as any)?.toString?.() ?? String(input);
+
+    const ac = new AbortController();
+    const timeoutMs = Math.floor(timeoutSeconds * 1000);
+    const t =
+      Number.isFinite(timeoutMs) && timeoutMs > 0
+        ? setTimeout(
+            () =>
+              ac.abort(
+                new Error(
+                  `[${label}] Request timed out (timeoutSeconds=${timeoutSeconds})`
+                )
+              ),
+            timeoutMs
+          )
+        : undefined;
+
+    const onAbort = () =>
+      ac.abort((init?.signal as any)?.reason ?? new Error("Aborted"));
+    if (init?.signal) {
+      if (init.signal.aborted) onAbort();
+      else
+        init.signal.addEventListener("abort", onAbort, { once: true } as any);
+    }
+
+    const mergedInit: RequestInit = {
+      ...init,
+      signal: ac.signal,
+    };
+
+    if (debug) {
+      const mergedHeaders = {
+        ...defaultHeaders,
+        ...((init?.headers ?? {}) as any),
+      };
+      // eslint-disable-next-line no-console
+      console.log(
+        `[opensandbox:${label}] ->`,
+        method,
+        url,
+        redactHeaders(mergedHeaders)
+      );
+    }
+
+    try {
+      const res = await baseFetch(input, mergedInit);
+      if (debug) {
+        // eslint-disable-next-line no-console
+        console.log(`[opensandbox:${label}] <-`, method, url, res.status);
+      }
+      return res;
+    } finally {
+      if (t) clearTimeout(t);
+      if (init?.signal)
+        init.signal.removeEventListener("abort", onAbort as any);
+    }
+  };
+}
+
+export class ConnectionConfig {
+  readonly protocol: ConnectionProtocol;
+  readonly domain: string;
+  readonly apiKey?: string;
+  readonly headers: Record<string, string>;
+  private _fetch: typeof fetch | null;
+  private _sseFetch: typeof fetch | null;
+  readonly requestTimeoutSeconds: number;
+  readonly debug: boolean;
+  readonly userAgent: string = "OpenSandbox-JS-SDK/0.1.1";
+  private _closeTransport: () => Promise<void>;
+  private _closePromise: Promise<void> | null = null;
+  private _transportInitialized = false;
+
+  /**
+   * Create a connection configuration.
+   *
+   * Environment variables (optional):
+   * - `OPEN_SANDBOX_DOMAIN` (default: `localhost:8080`)
+   * - `OPEN_SANDBOX_API_KEY`
+   */
+  constructor(opts: ConnectionConfigOptions = {}) {
+    const envDomain = readEnv("OPEN_SANDBOX_DOMAIN");
+    const envApiKey = readEnv("OPEN_SANDBOX_API_KEY");
+
+    const rawDomain = opts.domain ?? envDomain ?? "localhost:8080";
+    const normalized = normalizeDomainBase(rawDomain);
+
+    // If the domain includes a scheme, it overrides `protocol`.
+    this.protocol = normalized.protocol ?? opts.protocol ?? "http";
+    this.domain = normalized.domainBase;
+    this.apiKey = opts.apiKey ?? envApiKey;
+    this.requestTimeoutSeconds =
+      typeof opts.requestTimeoutSeconds === "number"
+        ? opts.requestTimeoutSeconds
+        : 30;
+    this.debug = !!opts.debug;
+
+    const headers: Record<string, string> = { ...(opts.headers ?? {}) };
+    // Attach API key via header unless the user already provided one.
+    if (this.apiKey && !headers["OPEN-SANDBOX-API-KEY"]) {
+      headers["OPEN-SANDBOX-API-KEY"] = this.apiKey;
+    }
+    // Best-effort user-agent (Node only).
+    if (
+      isNodeRuntime() &&
+      this.userAgent &&
+      !headers["user-agent"] &&
+      !headers["User-Agent"]
+    ) {
+      headers["user-agent"] = this.userAgent;
+    }
+    this.headers = headers;
+    this._fetch = null;
+    this._sseFetch = null;
+    this._closeTransport = async () => {
+      // Init with empty close call
+    };
+    this._transportInitialized = false;
+  }
+
+  get fetch(): typeof fetch {
+    return this._fetch ?? fetch;
+  }
+
+  get sseFetch(): typeof fetch {
+    return this._sseFetch ?? fetch;
+  }
+
+  getBaseUrl(): string {
+    // If `domain` already contains a scheme, treat it as a full base URL prefix.
+    if (
+      this.domain.startsWith("http://") ||
+      this.domain.startsWith("https://")
+    ) {
+      return `${stripV1Suffix(this.domain)}/v1`;
+    }
+    return `${this.protocol}://${stripV1Suffix(this.domain)}/v1`;
+  }
+
+  private initializeTransport(): void {
+    if (this._transportInitialized) return;
+
+    const { fetch: baseFetch, close } = createNodeFetch();
+    this._fetch = createTimedFetch({
+      baseFetch,
+      timeoutSeconds: this.requestTimeoutSeconds,
+      debug: this.debug,
+      defaultHeaders: this.headers,
+      label: "http",
+    });
+    this._sseFetch = createTimedFetch({
+      baseFetch,
+      timeoutSeconds: 0,
+      debug: this.debug,
+      defaultHeaders: this.headers,
+      label: "sse",
+    });
+    this._closeTransport = close;
+    this._transportInitialized = true;
+  }
+  /**
+   * Ensure this configuration has transport helpers (fetch/SSE) allocated.
+   *
+   * On Node.js this creates a dedicated `undici` dispatcher; on browsers it
+   * simply reuses the global fetch. Returns either `this` or a cloned config
+   * with the transport initialized.
+   */
+  withTransportIfMissing(): ConnectionConfig {
+    if (this._transportInitialized) {
+      return this;
+    }
+
+    const clone = new ConnectionConfig({
+      domain: this.domain,
+      protocol: this.protocol,
+      apiKey: this.apiKey,
+      headers: { ...this.headers },
+      requestTimeoutSeconds: this.requestTimeoutSeconds,
+      debug: this.debug,
+    });
+    clone.initializeTransport();
+    return clone;
+  }
+
+  /**
+   * Close the Node.js agent owned by this configuration.
+   */
+  async closeTransport(): Promise<void> {
+    if (!this._transportInitialized) return;
+    this._closePromise ??= this._closeTransport();
+    await this._closePromise;
+  }
+}

package/src/core/constants.ts

@@ -0,0 +1,29 @@
+// 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.
+
+export const DEFAULT_EXECD_PORT = 44772;
+
+export const DEFAULT_ENTRYPOINT: string[] = ["tail", "-f", "/dev/null"];
+
+export const DEFAULT_RESOURCE_LIMITS: Record<string, string> = {
+  cpu: "1",
+  memory: "2Gi",
+};
+
+export const DEFAULT_TIMEOUT_SECONDS = 600;
+export const DEFAULT_READY_TIMEOUT_SECONDS = 30;
+export const DEFAULT_HEALTH_CHECK_POLLING_INTERVAL_MILLIS = 200;
+
+export const DEFAULT_REQUEST_TIMEOUT_SECONDS = 30;
+export const DEFAULT_USER_AGENT = "OpenSandbox-JS-SDK/0.1.0";

package/src/core/exceptions.ts

@@ -0,0 +1,134 @@
+// 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.
+
+export type SandboxErrorCode =
+  | "INTERNAL_UNKNOWN_ERROR"
+  | "READY_TIMEOUT"
+  | "UNHEALTHY"
+  | "INVALID_ARGUMENT"
+  | "UNEXPECTED_RESPONSE"
+  // Allow server-defined codes as well.
+  | (string & {});
+
+/**
+ * Structured error payload carried by {@link SandboxException}.
+ *
+ * - `code`: stable programmatic identifier
+ * - `message`: optional human-readable message
+ */
+export class SandboxError {
+  static readonly INTERNAL_UNKNOWN_ERROR: SandboxErrorCode = "INTERNAL_UNKNOWN_ERROR";
+  static readonly READY_TIMEOUT: SandboxErrorCode = "READY_TIMEOUT";
+  static readonly UNHEALTHY: SandboxErrorCode = "UNHEALTHY";
+  static readonly INVALID_ARGUMENT: SandboxErrorCode = "INVALID_ARGUMENT";
+  static readonly UNEXPECTED_RESPONSE: SandboxErrorCode = "UNEXPECTED_RESPONSE";
+
+  constructor(
+    readonly code: SandboxErrorCode,
+    readonly message?: string,
+  ) {}
+}
+
+interface SandboxExceptionOpts {
+  message?: string;
+  cause?: unknown;
+  error?: SandboxError;
+}
+
+/**
+ * Base exception class for all SDK errors.
+ *
+ * All errors thrown by this SDK are subclasses of {@link SandboxException}.
+ */
+export class SandboxException extends Error {
+  readonly name: string = "SandboxException";
+  readonly error: SandboxError;
+  readonly cause?: unknown;
+
+  constructor(opts: SandboxExceptionOpts = {}) {
+    super(opts.message);
+    this.cause = opts.cause;
+    this.error = opts.error ?? new SandboxError(SandboxError.INTERNAL_UNKNOWN_ERROR);
+  }
+}
+
+export class SandboxApiException extends SandboxException {
+  readonly name: string = "SandboxApiException";
+  readonly statusCode?: number;
+  readonly requestId?: string;
+  readonly rawBody?: unknown;
+
+  constructor(opts: SandboxExceptionOpts & {
+    statusCode?: number;
+    requestId?: string;
+    rawBody?: unknown;
+  }) {
+    super({
+      message: opts.message,
+      cause: opts.cause,
+      error: opts.error ?? new SandboxError(SandboxError.UNEXPECTED_RESPONSE, opts.message),
+    });
+    this.statusCode = opts.statusCode;
+    this.requestId = opts.requestId;
+    this.rawBody = opts.rawBody;
+  }
+}
+
+export class SandboxInternalException extends SandboxException {
+  readonly name: string = "SandboxInternalException";
+
+  constructor(opts: { message?: string; cause?: unknown }) {
+    super({
+      message: opts.message,
+      cause: opts.cause,
+      error: new SandboxError(SandboxError.INTERNAL_UNKNOWN_ERROR, opts.message),
+    });
+  }
+}
+
+export class SandboxUnhealthyException extends SandboxException {
+  readonly name: string = "SandboxUnhealthyException";
+
+  constructor(opts: { message?: string; cause?: unknown }) {
+    super({
+      message: opts.message,
+      cause: opts.cause,
+      error: new SandboxError(SandboxError.UNHEALTHY, opts.message),
+    });
+  }
+}
+
+export class SandboxReadyTimeoutException extends SandboxException {
+  readonly name: string = "SandboxReadyTimeoutException";
+
+  constructor(opts: { message?: string; cause?: unknown }) {
+    super({
+      message: opts.message,
+      cause: opts.cause,
+      error: new SandboxError(SandboxError.READY_TIMEOUT, opts.message),
+    });
+  }
+}
+
+export class InvalidArgumentException extends SandboxException {
+  readonly name: string = "InvalidArgumentException";
+
+  constructor(opts: { message?: string; cause?: unknown }) {
+    super({
+      message: opts.message,
+      cause: opts.cause,
+      error: new SandboxError(SandboxError.INVALID_ARGUMENT, opts.message),
+    });
+  }
+}

package/src/factory/adapterFactory.ts

@@ -0,0 +1,51 @@
+// 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 { ConnectionConfig } from "../config/connection.js";
+import type { SandboxFiles } from "../services/filesystem.js";
+import type { ExecdCommands } from "../services/execdCommands.js";
+import type { ExecdHealth } from "../services/execdHealth.js";
+import type { ExecdMetrics } from "../services/execdMetrics.js";
+import type { Sandboxes } from "../services/sandboxes.js";
+
+export interface CreateLifecycleStackOptions {
+  connectionConfig: ConnectionConfig;
+  lifecycleBaseUrl: string;
+}
+
+export interface LifecycleStack {
+  sandboxes: Sandboxes;
+}
+
+export interface CreateExecdStackOptions {
+  connectionConfig: ConnectionConfig;
+  execdBaseUrl: string;
+}
+
+export interface ExecdStack {
+  commands: ExecdCommands;
+  files: SandboxFiles;
+  health: ExecdHealth;
+  metrics: ExecdMetrics;
+}
+
+/**
+ * Factory abstraction to keep `Sandbox` and `SandboxManager` decoupled from concrete adapter implementations.
+ *
+ * This is primarily useful for advanced integrations (custom transports, dependency injection, testing).
+ */
+export interface AdapterFactory {
+  createLifecycleStack(opts: CreateLifecycleStackOptions): LifecycleStack;
+  createExecdStack(opts: CreateExecdStackOptions): ExecdStack;
+}

package/src/factory/defaultAdapterFactory.ts

@@ -0,0 +1,69 @@
+// 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 { createExecdClient } from "../openapi/execdClient.js";
+import { createLifecycleClient } from "../openapi/lifecycleClient.js";
+
+import { CommandsAdapter } from "../adapters/commandsAdapter.js";
+import { FilesystemAdapter } from "../adapters/filesystemAdapter.js";
+import { HealthAdapter } from "../adapters/healthAdapter.js";
+import { MetricsAdapter } from "../adapters/metricsAdapter.js";
+import { SandboxesAdapter } from "../adapters/sandboxesAdapter.js";
+
+import type { AdapterFactory, CreateExecdStackOptions, CreateLifecycleStackOptions, ExecdStack, LifecycleStack } from "./adapterFactory.js";
+
+export class DefaultAdapterFactory implements AdapterFactory {
+  createLifecycleStack(opts: CreateLifecycleStackOptions): LifecycleStack {
+    const lifecycleClient = createLifecycleClient({
+      baseUrl: opts.lifecycleBaseUrl,
+      apiKey: opts.connectionConfig.apiKey,
+      headers: opts.connectionConfig.headers,
+      fetch: opts.connectionConfig.fetch,
+    });
+    const sandboxes = new SandboxesAdapter(lifecycleClient);
+    return { sandboxes };
+  }
+
+  createExecdStack(opts: CreateExecdStackOptions): ExecdStack {
+    const execdClient = createExecdClient({
+      baseUrl: opts.execdBaseUrl,
+      headers: opts.connectionConfig.headers,
+      fetch: opts.connectionConfig.fetch,
+    });
+
+    const health = new HealthAdapter(execdClient);
+    const metrics = new MetricsAdapter(execdClient);
+    const files = new FilesystemAdapter(execdClient, {
+      baseUrl: opts.execdBaseUrl,
+      fetch: opts.connectionConfig.fetch,
+      headers: opts.connectionConfig.headers,
+    });
+    const commands = new CommandsAdapter(execdClient, {
+      baseUrl: opts.execdBaseUrl,
+      fetch: opts.connectionConfig.sseFetch,
+      headers: opts.connectionConfig.headers,
+    });
+
+    return {
+      commands,
+      files,
+      health,
+      metrics,
+    };
+  }
+}
+
+export function createDefaultAdapterFactory(): AdapterFactory {
+  return new DefaultAdapterFactory();
+}