dorfteich/apps/api/src/health/backup-freshness.ts

import { existsSync, readFileSync } from 'node:fs';
import { join } from 'node:path';

import {
  BACKUP_FRESH_MAX_AGE_HOURS,
  BACKUP_REMOTE_WEEKLY_MAX_AGE_HOURS,
  BACKUP_STATUS_FILE,
  type BackupStatus,
} from '@dorfteich/shared';

import type { ReadinessCheck } from './readiness.service';

/**
 * Backup freshness for readyz (issue #85, operations.md §Health): reads the
 * sidecar's `status.json` from the shared backups volume. Always
 * warning-level — a stale or missing backup degrades the instance so
 * monitors alert, but the api keeps serving (503 is reserved for the
 * database/migrations hard failures).
 */
export function backupFreshnessCheck(backupsDir: string, now: Date): ReadinessCheck {
  const path = join(backupsDir, BACKUP_STATUS_FILE);
  if (!existsSync(path)) {
    return { name: 'backup', status: 'warn', detail: 'no backup status recorded yet' };
  }

  let status: BackupStatus;
  try {
    status = JSON.parse(readFileSync(path, 'utf8')) as BackupStatus;
  } catch {
    return { name: 'backup', status: 'warn', detail: 'backup status file is unreadable' };
  }

  if (!status.lastSuccess) {
    const error = status.lastRun?.error;
    return {
      name: 'backup',
      status: 'warn',
      detail: error ? `no successful backup yet — last run: ${error}` : 'no successful backup yet',
    };
  }

  const ageHours = (now.getTime() - new Date(status.lastSuccess.finishedAt).getTime()) / 3_600_000;
  if (!Number.isFinite(ageHours) || ageHours > BACKUP_FRESH_MAX_AGE_HOURS) {
    return {
      name: 'backup',
      status: 'warn',
      detail: `last successful backup ${status.lastSuccess.backupId} is ${Math.round(ageHours)} h old (max ${BACKUP_FRESH_MAX_AGE_HOURS} h)`,
    };
  }

  // Fresh success; still surface a failed newer run so operators see it
  // before the freshness window runs out.
  if (status.lastRun.outcome === 'failed') {
    return {
      name: 'backup',
      status: 'ok',
      detail: `fresh, but the last run failed: ${status.lastRun.error ?? 'unknown error'}`,
    };
  }
  return { name: 'backup', status: 'ok' };
}

/**
 * Off-host copy freshness (issue #103) — evaluated only while a Nextcloud
 * target is configured. Like the local check it is always warning-level.
 * With schedule `off` (manual uploads only) there is no cadence to hold the
 * instance to, so the check reports ok with a detail.
 */
export function backupRemoteFreshnessCheck(
  backupsDir: string,
  now: Date,
  schedule: 'off' | 'daily' | 'weekly',
): ReadinessCheck {
  const name = 'backup_remote';
  if (schedule === 'off') {
    return { name, status: 'ok', detail: 'manual uploads only (schedule off)' };
  }
  const maxAgeHours =
    schedule === 'weekly' ? BACKUP_REMOTE_WEEKLY_MAX_AGE_HOURS : BACKUP_FRESH_MAX_AGE_HOURS;

  const path = join(backupsDir, BACKUP_STATUS_FILE);
  let status: BackupStatus | null = null;
  if (existsSync(path)) {
    try {
      status = JSON.parse(readFileSync(path, 'utf8')) as BackupStatus;
    } catch {
      status = null;
    }
  }
  if (!status) {
    return { name, status: 'warn', detail: 'no backup status recorded yet' };
  }
  if (!status.remote?.lastSuccessfulUpload) {
    const error = status.remote?.lastUpload?.error;
    return {
      name,
      status: 'warn',
      detail: error
        ? `no successful off-host upload yet — last attempt: ${error}`
        : 'no successful off-host upload yet',
    };
  }

  const upload = status.remote.lastSuccessfulUpload;
  const ageHours = (now.getTime() - new Date(upload.finishedAt).getTime()) / 3_600_000;
  if (!Number.isFinite(ageHours) || ageHours > maxAgeHours) {
    return {
      name,
      status: 'warn',
      detail: `last off-host copy ${upload.backupId} is ${Math.round(ageHours)} h old (max ${maxAgeHours} h)`,
    };
  }
  if (status.remote.lastUpload.outcome === 'failed') {
    return {
      name,
      status: 'ok',
      detail: `fresh, but the last upload failed: ${status.remote.lastUpload.error ?? 'unknown error'}`,
    };
  }
  return { name, status: 'ok' };
}