Skip to content

Write HTML. Render video. Built for agents.

8.2 KB
Raw Blame
import { randomUUID } from "node:crypto";
import { readdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
import { lstat, readdir, rm } from "node:fs/promises";
import { tmpdir } from "node:os";
import { dirname, join } from "node:path";
import { isSafePath } from "../helpers/safePath.js";
import { ID_PATH, isHistoryId, readId, readRecord } from "./historyId.js";
import { HistoryBusyError, takeHistoryOwnership } from "./ownerLock.js";

const DAY_MS = 24 * 60 * 60 * 1000;
/** A gone project's history stays this long after its last use, so a moved project reopened in time keeps it. */
export const KEEP_GONE_PROJECT_HISTORY_MS = 14 * DAY_MS;
const PRUNED_PREFIX = ".pruned-";
const LAST_PRUNE_FILE = ".last-prune";

interface PruneOptions {
  now?: number;
  /** Reports what would go, with the same checks, and removes nothing. */
  dryRun?: boolean;
  /** Projects under this folder are scratch: their history goes as soon as they do. */
  tempDir?: string;
  /** One history that could not be checked or removed; the rest are still pruned. */
  onError?: (error: unknown) => void;
  /** Starts no further history after this long; the rest wait for the next run. */
  budgetMs?: number;
}

export interface ProjectHistoryRecord {
  id: string;
  projectDir: string;
  lastUsedMs: number;
}

/** Every history whose project is still in the folder it was recorded for; reads only. */
export function listProjectHistories(historyRoot: string): ProjectHistoryRecord[] {
  return namesIn(historyRoot)
    .filter(isHistoryId)
    .flatMap((id) => {
      const home = join(historyRoot, id);
      const projectDir = readRecord(home)?.dir;
      if (typeof projectDir !== "string" || readId(projectDir) !== id) return [];
      return [{ id, projectDir, lastUsedMs: lastUsed(home) }];
    });
}

function namesIn(historyRoot: string): string[] {
  try {
    return readdirSync(historyRoot);
  } catch (error) {
    if ((error as NodeJS.ErrnoException).code === "ENOENT") return [];
    throw error;
  }
}

export interface PrunedHistory {
  id: string;
  projectDir: string;
  bytes: number;
}

/** Removes the histories whose project is gone and that no live process holds. */
export async function pruneGoneProjectHistories(
  historyRoot: string,
  options: PruneOptions = {},
): Promise<PrunedHistory[]> {
  return (await pruneWithin(historyRoot, options)).pruned;
}

async function pruneWithin(
  historyRoot: string,
  {
    now = Date.now(),
    dryRun = false,
    tempDir = tmpdir(),
    onError = (error) => console.warn("[history] could not prune a history:", error),
    budgetMs = Infinity,
    measure = true,
  }: PruneOptions & { measure?: boolean },
): Promise<{ pruned: PrunedHistory[]; finished: boolean }> {
  const started = performance.now();
  const names = namesIn(historyRoot);
  const pruned: PrunedHistory[] = [];
  for (const name of names) {
    if (performance.now() - started >= budgetMs) return { pruned, finished: false };
    try {
      const gone = await pruneEntry(historyRoot, name, { now, dryRun, tempDir, measure });
      if (gone) pruned.push(gone);
    } catch (error) {
      onError(error);
    }
  }
  return { pruned, finished: true };
}

async function pruneEntry(historyRoot: string, name: string, run: PruneRun) {
  if (name.startsWith(PRUNED_PREFIX)) {
    if (!run.dryRun) await rm(join(historyRoot, name), { recursive: true, force: true });
    return null;
  }
  return isHistoryId(name) ? pruneOne(historyRoot, name, run) : null;
}

type PruneRun = { now: number; dryRun: boolean; tempDir: string; measure: boolean };

async function pruneOne(
  historyRoot: string,
  id: string,
  run: PruneRun,
): Promise<PrunedHistory | null> {
  const home = join(historyRoot, id);
  if (abandonedProject(home, id, run.now, run.tempDir) === null) return null;
  const release = await takeUnlessBusy(home);
  if (!release) return null;
  let taken: { projectDir: string; trash: string | null } | null;
  try {
    taken = recheckAndMoveAway(historyRoot, id, run);
  } catch (error) {
    release();
    throw error;
  }
  if (!taken?.trash) release();
  if (!taken) return null;
  const bytes = await clearAway(taken.trash, home, run.measure);
  return { id, projectDir: taken.projectDir, bytes };
}

/** Removes the moved-away history, if any; its size when asked, measured first. */
async function clearAway(trash: string | null, home: string, measure: boolean): Promise<number> {
  const bytes = measure ? await bytesIn(trash ?? home) : 0;
  if (trash) await rm(trash, { recursive: true, force: true });
  return bytes;
}

async function takeUnlessBusy(home: string): Promise<(() => void) | null> {
  try {
    return await takeHistoryOwnership(home, 0);
  } catch (error) {
    if (error instanceof HistoryBusyError) return null;
    throw error;
  }
}

function recheckAndMoveAway(historyRoot: string, id: string, { now, dryRun, tempDir }: PruneRun) {
  const home = join(historyRoot, id);
  // Re-read under the lock: an open that recorded this project again meanwhile keeps it.
  const projectDir = abandonedProject(home, id, now, tempDir);
  if (projectDir === null) return null;
  if (dryRun) return { projectDir, trash: null };
  // One rename takes the lock along, so an interrupted delete leaves a `.pruned-` folder the next run finishes.
  const trash = join(historyRoot, `${PRUNED_PREFIX}${id}-${randomUUID()}`);
  renameSync(home, trash);
  return { projectDir, trash };
}

/** The folder a history was recorded for, when that project is gone; null while it may still need its history. */
function abandonedProject(home: string, id: string, now: number, tempDir: string): string | null {
  const record = readRecord(home);
  const dir = record?.dir;
  if (typeof dir !== "string") return null;
  if (now - lastUsed(home) < KEEP_GONE_PROJECT_HISTORY_MS && !isSafePath(tempDir, dir)) return null;
  return projectGone(dir, id, record?.dev, tempDir) ? dir : null;
}

function projectGone(dir: string, id: string, dev: unknown, tempDir: string): boolean {
  if (!statSync(join(dir, ID_PATH), { throwIfNoEntry: false }))
    return diskStillHere(dir, dev, tempDir);
  // An id file this version cannot read is refused, never replaced, so its history is still the project's.
  const there = readId(dir);
  return there !== null && there !== id;
}

/** A project without its id is gone only if the disk that held it is here: an unmounted drive or share keeps it. */
function diskStillHere(dir: string, dev: unknown, tempDir: string): boolean {
  let at = dir;
  let stat = statSync(at, { throwIfNoEntry: false });
  while (!stat) {
    if (dirname(at) === at) return false;
    at = dirname(at);
    stat = statSync(at, { throwIfNoEntry: false });
  }
  if (typeof dev === "number") return stat.dev === dev;
  // Recorded before `dev`: a missing folder may sit on an unmounted disk, so only an emptied folder or temp counts.
  return at === dir || isSafePath(tempDir, at);
}

function lastUsed(home: string): number {
  const mtime = (file: string) =>
    statSync(join(home, file), { throwIfNoEntry: false })?.mtimeMs ?? 0;
  return Math.max(mtime("project.json"), mtime("log.jsonl"));
}

async function bytesIn(dir: string): Promise<number> {
  let total = 0;
  for (const entry of await readdir(dir, { withFileTypes: true })) {
    const path = join(dir, entry.name);
    total += entry.isDirectory() ? await bytesIn(path) : (await lstat(path)).size;
  }
  return total;
}

function prunedWithinADay(stamp: string, now: number): boolean {
  try {
    const last = Number(readFileSync(stamp, "utf-8"));
    return last <= now && now - last < DAY_MS;
  } catch {
    return false;
  }
}

const pruning = new Set<string>();

/** Prunes `historyRoot` in the background until one run finishes a day, whichever process opens a history first. */
export function pruneGoneProjectHistoriesDaily(
  historyRoot: string,
  now: number,
  { onError, budgetMs }: Pick<PruneOptions, "onError" | "budgetMs"> = {},
): void {
  const stamp = join(historyRoot, LAST_PRUNE_FILE);
  if (pruning.has(historyRoot) || prunedWithinADay(stamp, now)) return;
  pruning.add(historyRoot);
  setImmediate(() => {
    pruneWithin(historyRoot, { now, onError, budgetMs, measure: false })
      .then(({ finished }) => finished && writeFileSync(stamp, String(now)))
      .catch((error) => onError?.(error))
      .finally(() => pruning.delete(historyRoot));
  });
}