Skip to content

Secure, Fast, and Extensible Sandbox runtime for AI agents.

7.4 KB
Raw Blame
// Copyright 2026 The OpenSandbox Authors
//
// 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 { ConnectionConfig, type ConnectionConfigOptions } from "./config/connection.js";
import {
  PoolDestroyIncompleteException,
  PoolDestroyedException,
} from "./core/exceptions.js";
import { SandboxManager } from "./manager.js";
import type { AdapterFactory } from "./factory/adapterFactory.js";
import {
  PoolDestroyState,
  PoolDestroyStrategy,
  type PoolDestroyOptions,
  type PoolDestroyResult,
  type PoolLogger,
  type PoolStateStore,
} from "./poolTypes.js";

const DEFAULT_TOMBSTONE_TTL_SECONDS = 7 * 24 * 60 * 60;
const DEFAULT_DRAIN_TIMEOUT_SECONDS = 30;

export interface SandboxPoolManagerOptions {
  stateStore: PoolStateStore;
  connectionConfig: ConnectionConfig | ConnectionConfigOptions;
  ownerId?: string;
  logger?: PoolLogger;
  /** Advanced transport override, primarily for custom runtimes and tests. */
  adapterFactory?: AdapterFactory;
}

function makeOwnerId(): string {
  const random = globalThis.crypto?.randomUUID?.() ?? Math.random().toString(16).slice(2);
  return `pool-manager-${random}`;
}

function cloneConnectionConfig(config: ConnectionConfig): ConnectionConfig {
  return new ConnectionConfig({
    domain: config.domain,
    protocol: config.protocol,
    apiKey: config.apiKey,
    headers: { ...config.headers },
    requestTimeoutSeconds: config.requestTimeoutSeconds,
    debug: config.debug,
    useServerProxy: config.useServerProxy,
    endpointCacheTtlMs: config.endpointCacheTtlMs,
    endpointCacheSize: config.endpointCacheSize,
    endpointCacheDisabled: config.endpointCacheDisabled,
    disableMetrics: config.disableMetrics,
    enableTracing: config.enableTracing,
  });
}

/** Administrative operations for a shared sandbox-pool namespace. */
export class SandboxPoolManager {
  private readonly stateStore: PoolStateStore;
  private readonly connectionConfig: ConnectionConfig;
  private readonly ownerId: string;
  private readonly logger?: PoolLogger;
  private readonly adapterFactory?: AdapterFactory;

  constructor(options: SandboxPoolManagerOptions) {
    if (options.ownerId !== undefined && !options.ownerId.trim()) {
      throw new Error("ownerId must not be blank");
    }
    this.stateStore = options.stateStore;
    this.connectionConfig =
      options.connectionConfig instanceof ConnectionConfig
        ? cloneConnectionConfig(options.connectionConfig)
        : new ConnectionConfig(options.connectionConfig);
    this.ownerId = options.ownerId?.trim() ?? makeOwnerId();
    this.logger = options.logger;
    this.adapterFactory = options.adapterFactory;
  }

  static create(options: SandboxPoolManagerOptions): SandboxPoolManager {
    return new SandboxPoolManager(options);
  }

  async destroy(poolName: string, options: PoolDestroyOptions = {}): Promise<PoolDestroyResult> {
    if (!poolName.trim()) throw new Error("poolName must not be blank");
    const strategy = options.strategy ?? PoolDestroyStrategy.FORCE;
    if (strategy !== PoolDestroyStrategy.FORCE) throw new Error("Only FORCE destroy is supported");
    const drainTimeoutSeconds = options.drainTimeoutSeconds ?? DEFAULT_DRAIN_TIMEOUT_SECONDS;
    const tombstoneTtlSeconds =
      options.tombstoneTtlSeconds === undefined
        ? DEFAULT_TOMBSTONE_TTL_SECONDS
        : options.tombstoneTtlSeconds;
    if (!Number.isFinite(drainTimeoutSeconds) || drainTimeoutSeconds < 0) {
      throw new Error("drainTimeoutSeconds must be non-negative");
    }
    if (tombstoneTtlSeconds != null && (!Number.isFinite(tombstoneTtlSeconds) || tombstoneTtlSeconds <= 0)) {
      throw new Error("tombstoneTtlSeconds must be positive when set");
    }

    if ((await this.stateStore.getDestroyState(poolName)) === PoolDestroyState.DESTROYED) {
      return this.destroyedResult(poolName);
    }

    const manager = SandboxManager.create({
      connectionConfig: this.connectionConfig,
      adapterFactory: this.adapterFactory,
    });
    let drainedIdleCount = 0;
    let killedIdleCount = 0;
    try {
      try {
        await this.stateStore.beginDestroy(poolName, this.ownerId);
      } catch (error) {
        if (error instanceof PoolDestroyedException) return this.destroyedResult(poolName);
        throw error;
      }
      const deadline =
        drainTimeoutSeconds > 0
          ? Date.now() + drainTimeoutSeconds * 1000
          : undefined;
      while (true) {
        this.throwIfDrainDeadlineReached(poolName, deadline);
        const sandboxId = await this.stateStore.tryTakeIdle(poolName);
        if (!sandboxId) break;
        drainedIdleCount += 1;
        try {
          await this.killSandboxWithinDeadline(
            manager,
            sandboxId,
            poolName,
            deadline,
          );
          killedIdleCount += 1;
        } catch (error) {
          if (error instanceof PoolDestroyIncompleteException) throw error;
          this.logger?.warn?.("pool destroy failed to kill idle sandbox", {
            poolName,
            sandboxId,
            error,
          });
        }
      }
      try {
        await this.stateStore.clearPoolState(poolName);
        await this.stateStore.markDestroyed(poolName, this.ownerId, tombstoneTtlSeconds);
      } catch (error) {
        throw new PoolDestroyIncompleteException(poolName, error);
      }
      return {
        poolName,
        state: PoolDestroyState.DESTROYED,
        drainedIdleCount,
        killedIdleCount,
        persistentStateCleared: true,
      };
    } finally {
      await manager.close().catch(() => undefined);
    }
  }

  private throwIfDrainDeadlineReached(
    poolName: string,
    deadline: number | undefined,
  ): void {
    if (deadline !== undefined && Date.now() >= deadline) {
      throw new PoolDestroyIncompleteException(poolName);
    }
  }

  private async killSandboxWithinDeadline(
    manager: SandboxManager,
    sandboxId: string,
    poolName: string,
    deadline: number | undefined,
  ): Promise<void> {
    if (deadline === undefined) {
      await manager.killSandbox(sandboxId);
      return;
    }

    const remainingMs = deadline - Date.now();
    if (remainingMs <= 0) throw new PoolDestroyIncompleteException(poolName);

    const controller = new AbortController();
    let timer: ReturnType<typeof setTimeout> | undefined;
    const timeout = new Promise<never>((_, reject) => {
      timer = setTimeout(() => {
        const error = new PoolDestroyIncompleteException(poolName);
        controller.abort(error);
        reject(error);
      }, remainingMs);
    });
    try {
      await Promise.race([
        manager.killSandbox(sandboxId, controller.signal),
        timeout,
      ]);
    } finally {
      if (timer !== undefined) clearTimeout(timer);
    }
  }

  private destroyedResult(poolName: string): PoolDestroyResult {
    return {
      poolName,
      state: PoolDestroyState.DESTROYED,
      drainedIdleCount: 0,
      killedIdleCount: 0,
      persistentStateCleared: false,
    };
  }
}