Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript
16.2 KB
Raw Blame
import { app, session } from 'electron'
import fs from 'node:fs/promises'
import path from 'node:path'

/**
 * Sandbox-ui partition garbage collection.
 *
 * Runs once at Desktop App launch (before any sandbox-ui view is
 * mounted) so it can safely rm partition data without racing the
 * Electron Session that owns it.
 *
 *   1. Enumerate `userData/Partitions/sandbox-ui-${envKey}-*` directories on
 *      disk (the ACTIVE environment only — spec §5.2).
 *   2. Fetch the user's current sandbox-ui ACL via `GET /apps`.
 *   3. Wipe every on-disk partition (in this env) whose recipe isn't in the ACL.
 *   4. If remaining ACL-aligned partitions sum to > 1 GiB, evict the
 *      oldest by `lastAccessAt` until total is back under cap.
 *
 * The size cap is applied PER ENVIRONMENT since GC is env-scoped; total
 * sandbox-ui storage across N environments can reach up to N × the cap.
 *
 * `lastAccessAt` is tracked per `appRef` in a JSON file under userData
 * and updated by `touchSandboxUiPartition` whenever the driver mounts
 * a view.
 */

export const SANDBOX_UI_PARTITION_PREFIX = 'sandbox-ui-'
export const SANDBOX_UI_MAX_TOTAL_BYTES = 1024 * 1024 * 1024
export const SANDBOX_UI_STATE_FILENAME = 'sandbox-ui-partition-state.json'

/**
 * Marker file (under userData) recording that the one-shot pre-`envKey`
 * partition wipe ran. Mirrors ChatStore's `.env-scoped` marker
 * (`chatStoreBinding.ts`) so the destructive scan happens exactly once.
 */
export const SANDBOX_UI_PRE_ENV_MIGRATION_MARKER = '.sandbox-ui-env-scoped'

/**
 * Leading segment of an env-scoped partition, right after the `sandbox-ui-`
 * prefix. An env partition is `sandbox-ui-<envKey>-<ns>-<name>` where
 * `envKey = <slug>-<12 hex>` (see `resolveEnvKey` in `config.ts`: slug is
 * `[a-z0-9_]+`, hash is 12 hex). So a valid env partition's remainder starts
 * with `<slug>-<12hex>-`; a pre-env partition (`sandbox-ui-<ns>-<name>`) does
 * not. The trailing `-` matters: it rules out a legacy `<name>` that is itself
 * exactly 12 hex from being read as an envKey.
 */
const ENV_KEY_LEADING_SEGMENT_RE = /^[a-z0-9_]+-[0-9a-f]{12}-/

export type SandboxUiPartitionState = {
  lastAccessAt: Record<string, number>
}

export function emptySandboxUiPartitionState(): SandboxUiPartitionState {
  return { lastAccessAt: {} }
}

export function partitionDirNameFor(envKey: string, recipeNs: string, recipeName: string): string {
  return `${SANDBOX_UI_PARTITION_PREFIX}${envKey}-${recipeNs}-${recipeName}`
}

/**
 * True when `dirName` is a sandbox-ui partition of any vintage (env-scoped or
 * the pre-env layout). The base predicate — reused by
 * `isPreEnvSandboxUiPartitionDirName` to gate the one-shot legacy wipe.
 */
export function isSandboxUiPartitionDirName(dirName: string): boolean {
  return (
    dirName.startsWith(SANDBOX_UI_PARTITION_PREFIX) &&
    dirName.length > SANDBOX_UI_PARTITION_PREFIX.length
  )
}

/**
 * True when `dirName` is a sandbox-ui partition created BEFORE env-scoping
 * (`sandbox-ui-<ns>-<name>`, no `<envKey>-` segment). These no longer match any
 * environment's GC scan (`isSandboxUiPartitionDirNameForEnv`, §5.2) — new mounts
 * use `sandbox-ui-<envKey>-…` — so their now-dead KasmVNC cookies would leak on
 * disk forever and never count against the LRU cap. Detected by the ABSENCE of a
 * valid leading envKey segment. Best-effort heuristic (same class as ChatStore's
 * shape check): a legacy `<name>` shaped exactly like `<12hex>-…` is left alone,
 * leaking at most that one dir.
 */
export function isPreEnvSandboxUiPartitionDirName(dirName: string): boolean {
  if (!isSandboxUiPartitionDirName(dirName)) return false
  const rest = dirName.slice(SANDBOX_UI_PARTITION_PREFIX.length)
  return !ENV_KEY_LEADING_SEGMENT_RE.test(rest)
}

/**
 * True when `dirName` is a sandbox-ui partition for `envKey` (spec §5.2). GC is
 * scoped to the CURRENT environment: other environments' partitions must be
 * neither wiped nor counted against this env's LRU cap.
 */
export function isSandboxUiPartitionDirNameForEnv(dirName: string, envKey: string): boolean {
  return dirName.startsWith(`${SANDBOX_UI_PARTITION_PREFIX}${envKey}-`)
}

export type GcPlan = {
  /** Dirs to wipe because their recipe isn't in the ACL. */
  wipe: string[]
  /** Dirs to evict to get under the LRU cap. Includes appRef so the
   *  caller can also clean up that key from `lastAccessAt`. */
  evict: { appRef: string; dirName: string }[]
}

export type GcPlanInput = {
  diskPartitionDirs: string[]
  aclEntries: { appRef: string; dirName: string }[]
  diskUsageByDir: Map<string, number>
  lastAccessAt: Record<string, number>
  maxTotalBytes: number
}

/**
 * Pure planner: given a snapshot of (disk, ACL, sizes, lastAccessAt),
 * decide what to wipe and what to LRU-evict. No I/O so it's testable
 * without Electron.
 */
export function planSandboxUiPartitionGc(input: GcPlanInput): GcPlan {
  const aclByDir = new Map<string, string>() // dirName → appRef
  for (const { appRef, dirName } of input.aclEntries) {
    aclByDir.set(dirName, appRef)
  }

  const wipe: string[] = []
  const aclDirsOnDisk: string[] = []
  for (const dir of input.diskPartitionDirs) {
    if (aclByDir.has(dir)) aclDirsOnDisk.push(dir)
    else wipe.push(dir)
  }

  let total = 0
  const surviving: { dirName: string; appRef: string; bytes: number; lastAccess: number }[] = []
  for (const dir of aclDirsOnDisk) {
    const appRef = aclByDir.get(dir)!
    const bytes = input.diskUsageByDir.get(dir) ?? 0
    const lastAccess = input.lastAccessAt[appRef] ?? 0
    total += bytes
    surviving.push({ dirName: dir, appRef, bytes, lastAccess })
  }

  const evict: { appRef: string; dirName: string }[] = []
  if (total > input.maxTotalBytes) {
    surviving.sort((a, b) => a.lastAccess - b.lastAccess)
    let remaining = total
    for (const entry of surviving) {
      if (remaining <= input.maxTotalBytes) break
      evict.push({ appRef: entry.appRef, dirName: entry.dirName })
      remaining -= entry.bytes
    }
  }

  return { wipe, evict }
}

// ─── State file (lastAccessAt) ────────────────────────────────────

let cachedState: SandboxUiPartitionState | null = null

async function readStateFile(stateFilePath: string): Promise<SandboxUiPartitionState> {
  if (cachedState) return cachedState
  try {
    const raw = await fs.readFile(stateFilePath, 'utf-8')
    const parsed = JSON.parse(raw) as unknown
    if (
      parsed &&
      typeof parsed === 'object' &&
      'lastAccessAt' in parsed &&
      typeof (parsed as { lastAccessAt: unknown }).lastAccessAt === 'object'
    ) {
      const m = (parsed as { lastAccessAt: Record<string, unknown> }).lastAccessAt
      const cleaned: Record<string, number> = {}
      for (const [k, v] of Object.entries(m)) {
        if (typeof v === 'number' && Number.isFinite(v) && v >= 0) cleaned[k] = v
      }
      cachedState = { lastAccessAt: cleaned }
      return cachedState
    }
  } catch {
    // missing / unreadable / malformed JSON — start fresh, don't crash
    // launch over a corrupted state file.
  }
  cachedState = emptySandboxUiPartitionState()
  return cachedState
}

async function writeStateFile(
  stateFilePath: string,
  state: SandboxUiPartitionState
): Promise<void> {
  await fs.mkdir(path.dirname(stateFilePath), { recursive: true })
  await fs.writeFile(stateFilePath, JSON.stringify(state, null, 2))
}

/**
 * Update `lastAccessAt[appRef]` to now. Called from the driver each
 * time a view mounts so the LRU has fresh data on the next launch.
 */
export async function touchSandboxUiPartition(appRef: string): Promise<void> {
  const userDataDir = app.getPath('userData')
  const stateFilePath = path.join(userDataDir, SANDBOX_UI_STATE_FILENAME)
  const state = await readStateFile(stateFilePath)
  state.lastAccessAt[appRef] = Date.now()
  cachedState = state
  await writeStateFile(stateFilePath, state)
}

// ─── Disk usage ───────────────────────────────────────────────────

async function diskUsageOfDir(dir: string): Promise<number> {
  let total = 0
  let entries: import('node:fs').Dirent[]
  try {
    entries = await fs.readdir(dir, { withFileTypes: true })
  } catch {
    return 0
  }
  for (const entry of entries) {
    const full = path.join(dir, entry.name)
    if (entry.isDirectory()) {
      total += await diskUsageOfDir(full)
    } else if (entry.isFile()) {
      try {
        const stat = await fs.stat(full)
        total += stat.size
      } catch {
        // file vanished mid-walk — best-effort accounting
      }
    }
  }
  return total
}

async function clearAndRemovePartition(dirName: string, partitionsRoot: string): Promise<void> {
  const partitionId = `persist:${dirName}`
  try {
    const ses = session.fromPartition(partitionId)
    await ses.clearStorageData()
  } catch (err) {
    console.warn(`[SandboxUI] clearStorageData failed for ${partitionId}:`, err)
  }
  try {
    await fs.rm(path.join(partitionsRoot, dirName), { recursive: true, force: true })
  } catch (err) {
    console.warn(`[SandboxUI] rm partition dir failed for ${dirName}:`, err)
  }
}

// ─── One-shot pre-envKey legacy wipe ─────────────────────────────

async function writePreEnvMigrationMarker(markerPath: string): Promise<void> {
  try {
    await fs.mkdir(path.dirname(markerPath), { recursive: true })
    await fs.writeFile(markerPath, new Date().toISOString(), { mode: 0o600 })
  } catch (err) {
    // Non-fatal: worst case the one-shot scan reruns next launch (idempotent).
    console.warn('[SandboxUI] Failed to persist pre-envKey partition marker:', err)
  }
}

/**
 * One-shot wipe of the pre-`envKey` partition layout (spec §5.2). Before this
 * feature partitions were `sandbox-ui-<ns>-<name>`; they are now
 * `sandbox-ui-<envKey>-<ns>-<name>`. The env-scoped GC below only matches the
 * new naming, so old partitions would otherwise leak forever. This scans the
 * partitions root ONCE (marker-guarded, like ChatStore's `.env-scoped` wipe),
 * env-independently, and removes every dir that is a sandbox-ui partition
 * WITHOUT a valid envKey segment. Returns the wiped dir names (for logging).
 */
export async function maybeWipePreEnvSandboxUiPartitions(userDataDir: string): Promise<string[]> {
  const partitionsRoot = path.join(userDataDir, 'Partitions')
  const markerPath = path.join(userDataDir, SANDBOX_UI_PRE_ENV_MIGRATION_MARKER)

  try {
    await fs.access(markerPath)
    return [] // already migrated
  } catch {
    // marker absent → run the one-shot below
  }

  let entries: import('node:fs').Dirent[]
  try {
    entries = await fs.readdir(partitionsRoot, { withFileTypes: true })
  } catch (err) {
    if ((err as NodeJS.ErrnoException).code === 'ENOENT') {
      // No Partitions dir yet (fresh install / nothing ever mounted). Nothing
      // legacy to wipe and nowhere stable to drop the marker; the next launch
      // reruns this cheaply once the dir exists.
      return []
    }
    throw err
  }

  const wiped: string[] = []
  for (const entry of entries) {
    // Names come from readdir of partitionsRoot ⇒ single path components (no
    // separators), so `clearAndRemovePartition`'s join can't escape the root.
    if (!entry.isDirectory()) continue
    if (!isPreEnvSandboxUiPartitionDirName(entry.name)) continue
    console.warn(`[SandboxUI] Wiping pre-envKey legacy partition "${entry.name}"`)
    await clearAndRemovePartition(entry.name, partitionsRoot)
    wiped.push(entry.name)
  }

  await writePreEnvMigrationMarker(markerPath)
  return wiped
}

// ─── Orchestrator ────────────────────────────────────────────────

export type RunSandboxUiPartitionGcArgs = {
  userDataDir: string
  /** Namespacing key of the ACTIVE environment (spec §5.2). GC only touches
   *  this env's `sandbox-ui-${envKey}-*` partitions. */
  envKey: string
  /** Returns the user's current sandbox-ui ACL. The orchestrator only
   *  needs `appRef`. Failure here aborts GC for this launch (better to
   *  keep stale data than to wipe a partition the user still has). */
  listAccessibleApps: () => Promise<{ apps: { appRef: string }[] }>
  /** Test seam — defaults to SANDBOX_UI_MAX_TOTAL_BYTES (1 GiB). */
  maxTotalBytes?: number
}

export type RunSandboxUiPartitionGcResult = {
  wiped: string[]
  evicted: string[]
}

export async function runSandboxUiPartitionGc(
  args: RunSandboxUiPartitionGcArgs
): Promise<RunSandboxUiPartitionGcResult> {
  const partitionsRoot = path.join(args.userDataDir, 'Partitions')
  const stateFilePath = path.join(args.userDataDir, SANDBOX_UI_STATE_FILENAME)
  const maxTotalBytes = args.maxTotalBytes ?? SANDBOX_UI_MAX_TOTAL_BYTES

  // One-shot, env-independent cleanup of pre-`envKey` partitions. Runs before
  // the env-scoped scan below (which by design only matches this env's
  // `sandbox-ui-${envKey}-*` dirs) so legacy partitions can't leak forever.
  await maybeWipePreEnvSandboxUiPartitions(args.userDataDir)

  let diskDirs: string[]
  try {
    const entries = await fs.readdir(partitionsRoot, { withFileTypes: true })
    // Scope to the ACTIVE env only — other environments' partitions are left
    // intact (they GC when their env is active). Prevents an env switch from
    // wiping another cluster's KasmVNC storage (spec §5.2).
    diskDirs = entries
      .filter(e => e.isDirectory() && isSandboxUiPartitionDirNameForEnv(e.name, args.envKey))
      .map(e => e.name)
  } catch {
    // userData/Partitions doesn't exist yet — nothing to GC.
    return { wiped: [], evicted: [] }
  }

  if (diskDirs.length === 0) {
    return { wiped: [], evicted: [] }
  }

  let aclEntries: { appRef: string; dirName: string }[]
  try {
    const result = await args.listAccessibleApps()
    aclEntries = []
    for (const a of result.apps) {
      const [ns, name] = a.appRef.split('/', 2)
      if (ns && name) {
        aclEntries.push({ appRef: a.appRef, dirName: partitionDirNameFor(args.envKey, ns, name) })
      }
    }
  } catch (err) {
    console.warn('[SandboxUI] partition GC: failed to fetch ACL, skipping:', err)
    return { wiped: [], evicted: [] }
  }

  const state = await readStateFile(stateFilePath)
  const aclDirSet = new Set(aclEntries.map(e => e.dirName))

  // Only walk size on ACL-aligned partitions; we wipe non-ACL ones
  // unconditionally so their size doesn't matter.
  const diskUsageByDir = new Map<string, number>()
  for (const dir of diskDirs) {
    if (aclDirSet.has(dir)) {
      diskUsageByDir.set(dir, await diskUsageOfDir(path.join(partitionsRoot, dir)))
    }
  }

  const plan = planSandboxUiPartitionGc({
    diskPartitionDirs: diskDirs,
    aclEntries,
    diskUsageByDir,
    lastAccessAt: state.lastAccessAt,
    maxTotalBytes,
  })

  for (const dirName of plan.wipe) {
    await clearAndRemovePartition(dirName, partitionsRoot)
  }
  for (const { dirName, appRef } of plan.evict) {
    await clearAndRemovePartition(dirName, partitionsRoot)
    delete state.lastAccessAt[appRef]
  }

  // Drop lastAccessAt entries for appRefs that lost ACL access AND have no
  // surviving on-disk partition in THIS env. Scoped to the active env so an
  // env switch doesn't discard another cluster's LRU timestamps (self-healing
  // metadata regardless — the next mount re-touches it).
  const envDiskDirSet = new Set(diskDirs)
  for (const appRef of Object.keys(state.lastAccessAt)) {
    const [ns, name] = appRef.split('/', 2)
    if (!ns || !name) {
      delete state.lastAccessAt[appRef]
      continue
    }
    const dirName = partitionDirNameFor(args.envKey, ns, name)
    // Prune only timestamps this pass just invalidated: the recipe had a
    // current-env partition on disk that is NOT in the current ACL (so it was
    // wiped above). An appRef with no current-env dir belongs to another env —
    // leave its timestamp for that env's own GC pass.
    if (envDiskDirSet.has(dirName) && !aclDirSet.has(dirName)) {
      delete state.lastAccessAt[appRef]
    }
  }

  cachedState = state
  await writeStateFile(stateFilePath, state)

  return {
    wiped: plan.wipe,
    evicted: plan.evict.map(e => e.dirName),
  }
}

/** ONLY for tests — drop the in-memory state file cache. */
export function _resetSandboxUiPartitionStateCacheForTests(): void {
  cachedState = null
}