backup-health-decisions.ts

backup-health-decisions.tsscripts/backup-health-decisions.tsraw ← scripts4,169 B← Back to the app
1/**
2 * AI Software Factory — the PURE decision logic for the backup/DR health gate
3 * (`scripts/backup-health.ts`). Extracted so the release-pipeline VERDICT can
4 * be unit-tested without booting S3/OpenSearch (NFR-B1…B7: RPO ≤ 5 min,
5 * RTO ≤ 1 h — the gate that fails the release when a backup stopped working).
6 *
7 * No I/O, no env reads, no top-level execution → safe to import from a test
8 * (the live script keeps its top-level `main()`, which is exactly why the
9 * logic lives here rather than in the script). `backup-health.ts` owns the
10 * live S3/OpenSearch checks + env; it delegates EVERY verdict decision to
11 * these functions so there is a single source of truth.
12 *
13 * The contract under test (documented in the script header + §8 runbook):
14 *   - REACHABLE-but-STALE marker        → FAIL in EVERY mode (exit 1)
15 *   - AUTH error (403 / bad creds)      → FAIL in EVERY mode (never silent)
16 *   - UNREACHABLE (dev laptop, no stack)→ SKIP, report-only, exit 0 (NOT a pass)
17 *   - UNREACHABLE (strict/staging)      → FAIL, exit 1 (the stack is expected up)
18 */
19 
20export interface CheckResult {
21  label: string;
22  status: "PASS" | "FAIL" | "SKIP";
23  detail: string;
24  ageMs: number | null;
25}
26 
27/** Milliseconds between an ISO timestamp and `now` (negative if in the future). */
28export function ageMsSince(iso: string, now: Date): number {
29  return now.getTime() - new Date(iso).getTime();
30}
31 
32/** Human age: whole minutes under an hour, one-decimal hours above it. */
33export function fmtAge(ms: number): string {
34  const min = Math.round(ms / 60000);
35  if (min < 60) return `${min}m`;
36  const h = ms / 3600000;
37  return `${h.toFixed(1)}h`;
38}
39 
40/**
41 * A mis-credentialed backup identity is a real bug, never silent — in ANY
42 * mode (a dev who mis-set the key should see a loud FAIL, not a quiet skip).
43 * Matches the S3/OS error strings the live checks surface.
44 */
45export function isAuthError(msg: string): boolean {
46  return /HTTP 403|SignatureDoesNotMatch|AccessDenied|InvalidAccessKey|InvalidClientTokenId|Credentials|unauthorized/i.test(
47    msg,
48  );
49}
50 
51/**
52 * Classify a check error and record its verdict:
53 *   - AUTH            → FAIL (every mode)
54 *   - unreachable     → FAIL (strict/staging) | SKIP (dev, report-only)
55 * The `strict` flag is the mode, threaded from the caller (the script's
56 * module-level `STRICT`) so the same function is testable in both.
57 */
58export function recordUnavailable(
59  results: CheckResult[],
60  label: string,
61  err: unknown,
62  limit: string,
63  strict: boolean,
64): void {
65  const msg = err instanceof Error ? err.message : String(err);
66  if (isAuthError(msg)) {
67    results.push({ label, status: "FAIL", ageMs: null, detail: `AUTH ERROR: ${msg} (limit ${limit})` });
68    return;
69  }
70  if (strict) {
71    results.push({ label, status: "FAIL", ageMs: null, detail: `UNAVAILABLE (strict): ${msg} (limit ${limit})` });
72    return;
73  }
74  results.push({
75    label,
76    status: "SKIP",
77    ageMs: null,
78    detail: `UNAVAILABLE — report-only skip (dev, NOT a pass): ${msg} (limit ${limit})`,
79  });
80}
81 
82export interface Verdict {
83  exitCode: number;
84  message: string;
85  failures: CheckResult[];
86  skips: CheckResult[];
87}
88 
89/**
90 * The exit-code mapping (the gate's contract):
91 *   - any FAIL  → exit 1  (a stopped backup is a hard release failure)
92 *   - SKIPs only→ exit 0  (dev, report-only; loud warning, never a pass)
93 *   - all PASS  → exit 0
94 * `message` is the `backup-health: <message>` tail the script prints.
95 */
96export function verdictFor(results: CheckResult[]): Verdict {
97  const failures = results.filter((r) => r.status === "FAIL");
98  const skips = results.filter((r) => r.status === "SKIP");
99  if (failures.length > 0) {
100    return {
101      exitCode: 1,
102      message: `FAIL — ${failures.length} check(s) not healthy`,
103      failures,
104      skips,
105    };
106  }
107  if (skips.length > 0) {
108    return {
109      exitCode: 0,
110      message: `OK with ${skips.length} report-only skip(s) (unreachable — dev mode). No failures.`,
111      failures,
112      skips,
113    };
114  }
115  return {
116    exitCode: 0,
117    message: `OK — all ${results.length} checks healthy`,
118    failures,
119    skips,
120  };
121}
122