Skip to content

Never stop coding. Free MIT AI gateway: one endpoint, 375 providers (150+ free), 1,400+ models Kimi, Claude, GPT, Gemini, GLM, DeepSeek, MiniMax. Works with Claude Code, Codex, Cursor, OpenCode, Cline & Copilot. Quota-aware auto-fallback, RTK+Caveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 900+ contributors

11.9 KB
Raw Blame
/**
 * Backup retention primitives — pure filesystem work, no `core.ts` dependency.
 *
 * `backup.ts` (manual/API/auto backups) resolves the operator's settings from the
 * database and delegates pure family pruning here. The migration runner deliberately
 * does not prune during its concurrent safety window: its snapshots are content-addressed
 * and reused for an identical DB state, while manual/scheduled cleanup remains the single
 * retention boundary. Before #10421, repeated failed starts created distinct timestamped
 * snapshots and `db_backups/` grew without bound (observed: 48,999 files / 204 GB).
 */

import fs from "fs";
import path from "path";

import { portableSnapshotFile, portableSnapshotId } from "./backupPaths";
import type { SqliteAdapter } from "./adapters/types";

export const MAX_DB_BACKUPS = 20;
export const DEFAULT_DB_BACKUP_RETENTION_DAYS = 0;
// #3834: the "Keep latest backups" UI value is persisted here so it survives a page
// refresh. A dedicated namespace avoids cross-talk with the databaseSettings key_value
// store (which rewrites all of its own keys on every update).
export const DB_BACKUP_SETTINGS_NAMESPACE = "dbBackup";
export const DB_BACKUP_MAX_FILES_KEY = "maxFiles";
export const DB_BACKUP_RETENTION_DAYS_KEY = "retentionDays";

export function parsePositiveInt(value: string | undefined, fallback: number) {
  if (!value) return fallback;
  const parsed = Number.parseInt(value, 10);
  return Number.isInteger(parsed) && parsed > 0 ? parsed : fallback;
}

export function parseNonNegativeInt(value: string | undefined, fallback: number) {
  if (value === undefined) return fallback;
  const parsed = Number.parseInt(value, 10);
  return Number.isInteger(parsed) && parsed >= 0 ? parsed : fallback;
}

function getStoredInteger(
  db: Pick<SqliteAdapter, "prepare">,
  key: string,
  min: number
): number | undefined {
  try {
    const row = db
      .prepare("SELECT value FROM key_value WHERE namespace = ? AND key = ?")
      .get(DB_BACKUP_SETTINGS_NAMESPACE, key) as { value?: string } | undefined;
    if (!row?.value) return undefined;
    const parsed = JSON.parse(row.value);
    return Number.isInteger(parsed) && parsed >= min ? parsed : undefined;
  } catch {
    return undefined;
  }
}

function getDatabaseSettingsKeepLastNBackups(
  db: Pick<SqliteAdapter, "prepare">
): number | undefined {
  try {
    const rows = db
      .prepare(
        "SELECT namespace, key, value FROM key_value WHERE (namespace = 'databaseSettings' AND key IN ('backup.keepLastNBackups', 'keepLastNBackups')) OR (namespace = 'settings' AND key = 'databaseSettings')"
      )
      .all() as Array<{ namespace: string; key: string; value: string }>;

    let fromSettingsNested: number | undefined = undefined;
    let fromDbFlat: number | undefined = undefined;
    let fromDbNested: number | undefined = undefined;

    for (const row of rows) {
      if (!row.value) continue;
      let parsed: unknown;
      try {
        parsed = JSON.parse(row.value);
      } catch {
        continue;
      }

      if (row.namespace === "settings") {
        if (row.key === "databaseSettings" && typeof parsed === "object" && parsed !== null) {
          const backup = (parsed as Record<string, unknown>).backup;
          if (typeof backup === "object" && backup !== null) {
            const val = (backup as Record<string, unknown>).keepLastNBackups;
            if (typeof val === "number" && Number.isInteger(val) && val >= 1) {
              fromSettingsNested = val;
            }
          }
        }
      } else if (row.namespace === "databaseSettings") {
        if (row.key === "backup.keepLastNBackups") {
          if (typeof parsed === "number" && Number.isInteger(parsed) && parsed >= 1) {
            fromDbNested = parsed;
          }
        } else if (row.key === "keepLastNBackups") {
          if (typeof parsed === "number" && Number.isInteger(parsed) && parsed >= 1) {
            fromDbFlat = parsed;
          }
        }
      }
    }

    if (fromDbNested !== undefined) return fromDbNested;
    if (fromSettingsNested !== undefined) return fromSettingsNested;

    // Legacy flat key: migration 046 seeded uncustomized '3' into key_value
    // for all fresh installations. A fresh installation with nothing set by the
    // operator must fall through to MAX_DB_BACKUPS (20) (#13308).
    // Therefore, only honor the legacy flat key if it differs from the migration 046 default.
    if (fromDbFlat !== undefined && fromDbFlat !== 3) {
      return fromDbFlat;
    }

    return undefined;
  } catch {
    return undefined;
  }
}

/**
 * Resolve the operator's backup retention settings with the same precedence
 * `backup.ts` uses for manual/API/auto backups:
 * 1. env override (ops)
 * 2. persisted Storage-page setting (`dbBackup.maxFiles`)
 * 3. persisted Database-page setting (`databaseSettings.backup.keepLastNBackups`) (#15550)
 * 4. default `MAX_DB_BACKUPS`
 */
export function resolveDbBackupRetention(
  db: Pick<SqliteAdapter, "prepare">,
  env: NodeJS.ProcessEnv = process.env
): { maxFiles: number; retentionDays: number } {
  const maxFiles =
    (env.DB_BACKUP_MAX_FILES
      ? parsePositiveInt(env.DB_BACKUP_MAX_FILES, MAX_DB_BACKUPS)
      : undefined) ??
    getStoredInteger(db, DB_BACKUP_MAX_FILES_KEY, 1) ??
    getDatabaseSettingsKeepLastNBackups(db) ??
    MAX_DB_BACKUPS;

  return {
    maxFiles,
    retentionDays: env.DB_BACKUP_RETENTION_DAYS
      ? parseNonNegativeInt(env.DB_BACKUP_RETENTION_DAYS, DEFAULT_DB_BACKUP_RETENTION_DAYS)
      : (getStoredInteger(db, DB_BACKUP_RETENTION_DAYS_KEY, 0) ?? DEFAULT_DB_BACKUP_RETENTION_DAYS),
  };
}

/**
 * A backup "family" is the primary `.sqlite` file plus its SQLite sidecars
 * (`-wal` / `-shm` / `-journal`). Retention operates on families so a sidecar is never
 * orphaned from — or outlives — the snapshot it belongs to.
 */
export function getBackupFamilyBase(filename: string) {
  if (filename.endsWith("-wal") || filename.endsWith("-shm")) return filename.slice(0, -4);
  if (filename.endsWith("-journal")) return filename.slice(0, -8);
  return filename;
}

export type BackupFamily = {
  base: string;
  hasPrimary: boolean;
  primaryMtimeMs: number;
  latestMtimeMs: number;
  files: string[];
  directory?: string;
};

function collectPortableFamily(backupDir: string, name: string): BackupFamily | null {
  const base = portableSnapshotId(name);
  if (!base) return null;
  try {
    const file = portableSnapshotFile(path.join(backupDir, name));
    const stat = fs.statSync(file);
    return {
      base,
      hasPrimary: true,
      primaryMtimeMs: stat.mtimeMs,
      latestMtimeMs: stat.mtimeMs,
      files: [path.join(name, "snapshot.sqlite")],
      directory: name,
    };
  } catch {
    // Invalid/foreign directories and symlinks are never retention authority.
    return null;
  }
}

export function collectBackupFamilies(backupDir: string): BackupFamily[] {
  if (!fs.existsSync(backupDir)) return [];

  const families = new Map<string, BackupFamily>();

  for (const name of fs.readdirSync(backupDir)) {
    if (!name.startsWith("db_")) continue;
    if (portableSnapshotId(name)) {
      const family = collectPortableFamily(backupDir, name);
      if (family) families.set(name, family);
      continue;
    }
    const base = getBackupFamilyBase(name);
    const filePath = path.join(backupDir, name);

    let stat;
    try {
      stat = fs.statSync(filePath);
    } catch {
      continue;
    }

    const family = families.get(base) || {
      base,
      hasPrimary: false,
      primaryMtimeMs: 0,
      latestMtimeMs: 0,
      files: [],
    };

    family.files.push(name);
    family.latestMtimeMs = Math.max(family.latestMtimeMs, stat.mtimeMs);
    if (name === base && name.endsWith(".sqlite")) {
      family.hasPrimary = true;
      family.primaryMtimeMs = stat.mtimeMs;
    }

    families.set(base, family);
  }

  return [...families.values()];
}

export type PruneResult = {
  deletedBackupFamilies: number;
  deletedFiles: number;
  keptBackupFamilies: number;
  maxFiles: number;
  retentionDays: number;
};

function syncSleep(ms: number): void {
  if (typeof SharedArrayBuffer !== "undefined" && typeof Atomics !== "undefined") {
    try {
      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
      return;
    } catch {
      // Atomics.wait may throw on restricted runtimes — fall through to busy-wait
    }
  }
  const deadline = Date.now() + ms;
  while (Date.now() < deadline) {
    /* busy-wait */
  }
}

/**
 * Synchronous file unlinker with retry backoff for Windows EBUSY / EPERM locks (#15550).
 * Avoids crashing the process or swallowing permanent failures silently while keeping
 * `pruneBackupDirectory()` completely synchronous.
 */
export function unlinkSyncWithRetry(
  filePath: string,
  options?: { maxAttempts?: number; baseDelayMs?: number }
): boolean {
  const maxAttempts = Math.max(1, options?.maxAttempts ?? 5);
  const baseDelayMs = Math.max(0, options?.baseDelayMs ?? 25);

  for (let attempt = 0; attempt < maxAttempts; attempt++) {
    try {
      if (fs.existsSync(filePath)) {
        fs.unlinkSync(filePath);
      }
      return true;
    } catch (err: unknown) {
      const code =
        err && typeof err === "object" && "code" in err ? (err as NodeJS.ErrnoException).code : "";
      if (code === "ENOENT") return true;
      if ((code === "EBUSY" || code === "EPERM") && attempt < maxAttempts - 1) {
        syncSleep(baseDelayMs * (attempt + 1));
      } else {
        return false;
      }
    }
  }
  return false;
}

function removeEmptyPortableDirectory(backupDir: string, directory?: string): void {
  if (!directory) return;
  try {
    // Never recursively remove published directories: preserve any foreign content.
    fs.rmdirSync(path.join(backupDir, directory));
  } catch {
    // A concurrent writer or unrelated entry keeps the directory in place.
  }
}

/**
 * Delete backup families beyond `maxFiles` (newest kept), older than `retentionDays`
 * (0 disables the age rule), or orphaned (sidecars whose primary is already gone).
 * Families in `exemptBases` skip the age rule only; `maxFiles` and orphan rules
 * still apply to them.
 */
export function pruneBackupDirectory(options: {
  backupDir: string;
  maxFiles: number;
  retentionDays: number;
  exemptBases?: Set<string>;
}): PruneResult {
  const { backupDir } = options;
  const maxFiles = Math.max(1, options.maxFiles);
  const retentionDays = Math.max(0, options.retentionDays);

  if (!fs.existsSync(backupDir)) {
    return {
      deletedBackupFamilies: 0,
      deletedFiles: 0,
      keptBackupFamilies: 0,
      maxFiles,
      retentionDays,
    };
  }

  const cutoffMs = retentionDays > 0 ? Date.now() - retentionDays * 24 * 60 * 60 * 1000 : 0;
  const families = collectBackupFamilies(backupDir);
  const primaryFamilies = families
    .filter((family) => family.hasPrimary)
    .sort((a, b) => b.primaryMtimeMs - a.primaryMtimeMs);
  const keepPrimaryBases = new Set(primaryFamilies.slice(0, maxFiles).map((family) => family.base));

  let deletedBackupFamilies = 0;
  let deletedFiles = 0;

  for (const family of families) {
    const isOverflowPrimary = family.hasPrimary && !keepPrimaryBases.has(family.base);
    const isExempt = options.exemptBases?.has(family.base) ?? false;
    const isExpired = retentionDays > 0 && !isExempt && family.latestMtimeMs < cutoffMs;
    const isOrphan = !family.hasPrimary;
    if (!isOverflowPrimary && !isExpired && !isOrphan) continue;

    let anyDeletedInFamily = false;
    for (const name of family.files) {
      const deleted = unlinkSyncWithRetry(path.join(backupDir, name));
      if (deleted) {
        deletedFiles += 1;
        anyDeletedInFamily = true;
      }
    }
    if (anyDeletedInFamily) {
      removeEmptyPortableDirectory(backupDir, family.directory);
      deletedBackupFamilies += 1;
    }
  }

  return {
    deletedBackupFamilies,
    deletedFiles,
    keptBackupFamilies: collectBackupFamilies(backupDir).filter((family) => family.hasPrimary)
      .length,
    maxFiles,
    retentionDays,
  };
}