Skip to content

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

3.9 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 type { Endpoint } from "../models/sandboxes.js";

interface CacheEntry {
  endpoint: Endpoint;
  expiresAt: number;
}

/**
 * LRU + TTL endpoint cache with inflight deduplication.
 *
 * JS is single-threaded so no mutex needed — but concurrent async calls
 * can overlap, so inflight dedup uses a shared Promise per key.
 */
export class EndpointCache {
  private readonly cache = new Map<string, CacheEntry>();
  private readonly inflight = new Map<string, Promise<Endpoint>>();
  private readonly maxSize: number;
  private readonly ttlMs: number;

  constructor(opts: { maxSize?: number; ttlMs?: number } = {}) {
    this.maxSize = opts.maxSize ?? 1024;
    this.ttlMs = opts.ttlMs ?? 600_000;
  }

  private cloneEndpoint(ep: Endpoint): Endpoint {
    return { ...ep, headers: ep.headers ? { ...ep.headers } : {} };
  }

  private makeKey(sandboxId: string, port: number, useServerProxy: boolean): string {
    return `${sandboxId}:${port}:${useServerProxy}`;
  }

  get(sandboxId: string, port: number, useServerProxy: boolean): Endpoint | undefined {
    const key = this.makeKey(sandboxId, port, useServerProxy);
    const entry = this.cache.get(key);
    if (!entry) return undefined;
    if (Date.now() >= entry.expiresAt) {
      this.cache.delete(key);
      return undefined;
    }
    // Move to end (most recently used) — delete + re-set.
    this.cache.delete(key);
    this.cache.set(key, entry);
    return this.cloneEndpoint(entry.endpoint);
  }

  put(sandboxId: string, port: number, useServerProxy: boolean, endpoint: Endpoint): void {
    const key = this.makeKey(sandboxId, port, useServerProxy);
    this.cache.delete(key);
    while (this.cache.size >= this.maxSize) {
      const oldest = this.cache.keys().next().value;
      if (oldest !== undefined) this.cache.delete(oldest);
      else break;
    }
    this.cache.set(key, { endpoint: this.cloneEndpoint(endpoint), expiresAt: Date.now() + this.ttlMs });
  }

  invalidate(sandboxId: string): void {
    const prefix = `${sandboxId}:`;
    for (const key of [...this.cache.keys()]) {
      if (key.startsWith(prefix)) {
        this.cache.delete(key);
      }
    }
    for (const key of [...this.inflight.keys()]) {
      if (key.startsWith(prefix)) {
        this.inflight.delete(key);
      }
    }
  }

  async getOrFetch(
    sandboxId: string,
    port: number,
    useServerProxy: boolean,
    fetcher: () => Promise<Endpoint>
  ): Promise<Endpoint> {
    const cached = this.get(sandboxId, port, useServerProxy);
    if (cached) return cached;

    const key = this.makeKey(sandboxId, port, useServerProxy);

    const existing = this.inflight.get(key);
    if (existing) return existing.then((ep) => this.cloneEndpoint(ep));

    const promise = fetcher()
      .then((ep) => {
        // Only the current fetch may populate this key or clear its entry.
        // Invalidating another sandbox must not discard this result.
        if (this.inflight.get(key) === promise) {
          this.put(sandboxId, port, useServerProxy, ep);
          this.inflight.delete(key);
        }
        return this.cloneEndpoint(ep);
      })
      .catch((err) => {
        if (this.inflight.get(key) === promise) {
          this.inflight.delete(key);
        }
        throw err;
      });

    this.inflight.set(key, promise);
    return promise;
  }

  get size(): number {
    return this.cache.size;
  }
}