Skip to content

Write HTML. Render video. Built for agents.

5.5 KB
Raw Blame
import { existsSync, readdirSync, statSync, unlinkSync } from "node:fs";
import { extname, join } from "node:path";
import { PROXY_VARIANT_CONFIG } from "./mediaCodecMap.js";

const DEFAULT_MAX_BYTES = 10 * 1024 * 1024 * 1024;
const DEFAULT_STALE_TEMP_MS = 60 * 60 * 1000;
const DEFAULT_MIN_SWEEP_INTERVAL_MS = 5 * 60 * 1000;
const PROXY_EXTENSIONS: ReadonlySet<string> = new Set(
  Object.values(PROXY_VARIANT_CONFIG).map(({ extension }) => extension),
);
const TRANSCODER_PROXY_NAME = /^[0-9a-f]{64}\.\w+$/;
const TRANSCODER_TEMP_NAME = /^\.tmp-[0-9a-f-]{36}-[0-9a-f]{64}\.\w+$/;

export interface ProxyCacheCleanupOptions {
  maxBytes?: number;
  maxIdleMs?: number;
  staleTempMs?: number;
  minSweepIntervalMs?: number;
  protectedPaths?: ReadonlySet<string>;
  now?: number;
  dryRun?: boolean;
}

export interface ProxyCacheCleanupResult {
  removed: string[];
  bytesBefore: number;
  bytesAfter: number;
  skipped: boolean;
}

interface CacheEntry {
  path: string;
  size: number;
  modifiedAt: number;
  protected: boolean;
}

const lastSweepAt = new Map<string, number>();

function positiveEnvNumber(name: string, fallback: number): number {
  const parsed = Number(process.env[name]);
  return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
}

function proxyCacheCleanupDefaults(): Required<
  Pick<ProxyCacheCleanupOptions, "maxBytes" | "maxIdleMs" | "staleTempMs" | "minSweepIntervalMs">
> {
  return {
    maxBytes: positiveEnvNumber("HYPERFRAMES_PROXY_CACHE_MAX_BYTES", DEFAULT_MAX_BYTES),
    maxIdleMs: positiveEnvNumber("HYPERFRAMES_PROXY_CACHE_MAX_IDLE_DAYS", 30) * 24 * 60 * 60 * 1000,
    staleTempMs: positiveEnvNumber("HYPERFRAMES_PROXY_CACHE_STALE_TEMP_MS", DEFAULT_STALE_TEMP_MS),
    minSweepIntervalMs: positiveEnvNumber(
      "HYPERFRAMES_PROXY_CACHE_SWEEP_INTERVAL_MS",
      DEFAULT_MIN_SWEEP_INTERVAL_MS,
    ),
  };
}

function shouldSkipSweep(cacheDir: string, now: number, minSweepIntervalMs: number): boolean {
  const previousSweep = lastSweepAt.get(cacheDir);
  if (previousSweep !== undefined && now - previousSweep < minSweepIntervalMs) return true;
  lastSweepAt.set(cacheDir, now);
  return false;
}

function readCacheInventory(
  cacheDir: string,
  protectedPaths: ReadonlySet<string>,
  now: number,
  staleTempMs: number,
): { entries: CacheEntry[]; staleTemps: CacheEntry[] } {
  const entries: CacheEntry[] = [];
  const staleTemps: CacheEntry[] = [];
  for (const dirent of readdirSync(cacheDir, { withFileTypes: true })) {
    if (!dirent.isFile()) continue;
    const path = join(cacheDir, dirent.name);
    const stat = statSync(path);
    const entry = {
      path,
      size: stat.size,
      modifiedAt: stat.mtimeMs,
      protected: protectedPaths.has(path),
    };
    if (TRANSCODER_TEMP_NAME.test(dirent.name)) {
      if (now - stat.mtimeMs >= staleTempMs) staleTemps.push(entry);
    } else if (
      TRANSCODER_PROXY_NAME.test(dirent.name) &&
      PROXY_EXTENSIONS.has(extname(dirent.name))
    ) {
      entries.push(entry);
    }
  }
  const oldestFirst = (a: CacheEntry, b: CacheEntry): number =>
    a.modifiedAt - b.modifiedAt || a.path.localeCompare(b.path);
  entries.sort(oldestFirst);
  staleTemps.sort(oldestFirst);
  return { entries, staleTemps };
}

function evictCacheEntries(
  entries: CacheEntry[],
  staleTemps: CacheEntry[],
  now: number,
  maxIdleMs: number,
  maxBytes: number,
  dryRun: boolean,
): Omit<ProxyCacheCleanupResult, "skipped"> {
  const bytesBefore = entries.reduce((total, entry) => total + entry.size, 0);
  let bytesAfter = bytesBefore;
  const removed: string[] = [];
  const remove = (entry: CacheEntry, countsTowardBudget: boolean): void => {
    if (!dryRun) unlinkSync(entry.path);
    removed.push(entry.path);
    if (countsTowardBudget) bytesAfter -= entry.size;
  };

  for (const entry of staleTemps) remove(entry, false);
  const kept: CacheEntry[] = [];
  for (const entry of entries) {
    if (!entry.protected && now - entry.modifiedAt >= maxIdleMs) remove(entry, true);
    else kept.push(entry);
  }
  for (const entry of kept) {
    if (bytesAfter <= maxBytes) break;
    if (!entry.protected && existsSync(entry.path)) remove(entry, true);
  }
  return { removed, bytesBefore, bytesAfter };
}

/**
 * Opportunistically bounds a project's transparent-proxy cache. Cleanup is
 * synchronous because callers already perform filesystem bookkeeping on the
 * preview request path, but rate limiting keeps the directory scan off the
 * hot path. Errors intentionally bubble so callers can warn without turning
 * a cache-maintenance failure into a preview failure.
 */
export function cleanupProxyCache(
  cacheDir: string,
  options: ProxyCacheCleanupOptions = {},
): ProxyCacheCleanupResult {
  const defaults = proxyCacheCleanupDefaults();
  const now = options.now ?? Date.now();
  const minSweepIntervalMs = options.minSweepIntervalMs ?? defaults.minSweepIntervalMs;
  if (shouldSkipSweep(cacheDir, now, minSweepIntervalMs)) {
    return { removed: [], bytesBefore: 0, bytesAfter: 0, skipped: true };
  }
  if (!existsSync(cacheDir)) {
    return { removed: [], bytesBefore: 0, bytesAfter: 0, skipped: false };
  }

  const maxBytes = options.maxBytes ?? defaults.maxBytes;
  const maxIdleMs = options.maxIdleMs ?? defaults.maxIdleMs;
  const staleTempMs = options.staleTempMs ?? defaults.staleTempMs;
  const protectedPaths = options.protectedPaths ?? new Set<string>();
  const { entries, staleTemps } = readCacheInventory(cacheDir, protectedPaths, now, staleTempMs);
  return {
    ...evictCacheEntries(entries, staleTemps, now, maxIdleMs, maxBytes, options.dryRun ?? false),
    skipped: false,
  };
}