|
| 1 | +// WS1-P1 — cleanup ledger + reaper fixture for real-backend (LIVE) E2E. |
| 2 | +// |
| 3 | +// Plan: docs/sessions/2026-06-04/OBSERVABILITY-AND-INTELLIGENCE-PLAN.md, WS1. |
| 4 | +// Enforces rule 24: a test run NEVER leaks a provisioned (and billable) DO |
| 5 | +// resource. Every entity a LIVE spec creates is recorded here; an afterEach + |
| 6 | +// afterAll reaps them, and a standalone `reap-cohort.ts` re-runs the same |
| 7 | +// deletion in CI teardown so cleanup happens even when the test process dies. |
| 8 | +// |
| 9 | +// Design notes: |
| 10 | +// - The ledger is persisted to disk (E2E_LEDGER_PATH, default |
| 11 | +// e2e/.cleanup-ledger.json) so the OUT-OF-PROCESS reaper can read it after |
| 12 | +// a crash/timeout that skipped the in-process afterAll. |
| 13 | +// - Each entry carries enough to delete it WITHOUT the page: the api base |
| 14 | +// URL, the auth token (if any), the entity kind, and its id/token. |
| 15 | +// - Deletion is best-effort + idempotent: a 404 (already gone) is success; |
| 16 | +// other failures are collected and reported but do not throw past the |
| 17 | +// reaper, so one stuck entity can't strand the rest. |
| 18 | + |
| 19 | +import { existsSync, mkdirSync, readFileSync, writeFileSync, rmSync } from 'node:fs' |
| 20 | +import { dirname } from 'node:path' |
| 21 | + |
| 22 | +import type { APIRequestContext } from '@playwright/test' |
| 23 | + |
| 24 | +export type CohortEntityKind = 'resource' | 'deployment' | 'team' | 'storage-prefix' |
| 25 | + |
| 26 | +export interface CohortEntity { |
| 27 | + /** What to delete. */ |
| 28 | + kind: CohortEntityKind |
| 29 | + /** The id/token used to address the DELETE (resource token, deploy id, etc.). */ |
| 30 | + id: string |
| 31 | + /** Absolute api base URL the entity lives on (e.g. https://staging-api...). */ |
| 32 | + apiUrl: string |
| 33 | + /** Bearer token authorizing the DELETE, when the entity is team-scoped. */ |
| 34 | + token?: string |
| 35 | + /** Free-form, for the reaper log + post-mortem (e.g. resource_type, name). */ |
| 36 | + note?: string |
| 37 | + /** When it was recorded (ISO) — lets the reaper age-out backstop sweeps. */ |
| 38 | + recordedAt: string |
| 39 | +} |
| 40 | + |
| 41 | +export interface ReapResult { |
| 42 | + attempted: number |
| 43 | + deleted: number |
| 44 | + alreadyGone: number |
| 45 | + failed: Array<{ entity: CohortEntity; status: number; error: string }> |
| 46 | +} |
| 47 | + |
| 48 | +const DEFAULT_LEDGER_PATH = 'e2e/.cleanup-ledger.json' |
| 49 | + |
| 50 | +export function ledgerPath(): string { |
| 51 | + return process.env.E2E_LEDGER_PATH || DEFAULT_LEDGER_PATH |
| 52 | +} |
| 53 | + |
| 54 | +function readLedger(path: string): CohortEntity[] { |
| 55 | + if (!existsSync(path)) return [] |
| 56 | + try { |
| 57 | + const raw = readFileSync(path, 'utf8') |
| 58 | + const parsed = JSON.parse(raw) |
| 59 | + return Array.isArray(parsed) ? (parsed as CohortEntity[]) : [] |
| 60 | + } catch { |
| 61 | + // Corrupt/partial ledger: treat as empty rather than crash the reaper. |
| 62 | + return [] |
| 63 | + } |
| 64 | +} |
| 65 | + |
| 66 | +function writeLedger(path: string, entities: CohortEntity[]): void { |
| 67 | + const dir = dirname(path) |
| 68 | + if (dir && dir !== '.' && !existsSync(dir)) mkdirSync(dir, { recursive: true }) |
| 69 | + writeFileSync(path, JSON.stringify(entities, null, 2), 'utf8') |
| 70 | +} |
| 71 | + |
| 72 | +/** |
| 73 | + * Append an entity to the on-disk ledger. Called the instant a LIVE spec |
| 74 | + * creates something, BEFORE any assertion that might throw — so a failed |
| 75 | + * assertion still leaves a reapable record (rule 24). |
| 76 | + */ |
| 77 | +export function recordEntity(entity: Omit<CohortEntity, 'recordedAt'>): void { |
| 78 | + const path = ledgerPath() |
| 79 | + const current = readLedger(path) |
| 80 | + current.push({ ...entity, recordedAt: new Date().toISOString() }) |
| 81 | + writeLedger(path, current) |
| 82 | +} |
| 83 | + |
| 84 | +export function loadLedger(): CohortEntity[] { |
| 85 | + return readLedger(ledgerPath()) |
| 86 | +} |
| 87 | + |
| 88 | +/** Wipe the ledger file (called after a clean reap so the next run starts fresh). */ |
| 89 | +export function clearLedger(): void { |
| 90 | + const path = ledgerPath() |
| 91 | + if (existsSync(path)) rmSync(path) |
| 92 | +} |
| 93 | + |
| 94 | +function deletePath(entity: CohortEntity): string { |
| 95 | + switch (entity.kind) { |
| 96 | + case 'resource': |
| 97 | + return `/api/v1/resources/${entity.id}` |
| 98 | + case 'deployment': |
| 99 | + return `/api/v1/deployments/${entity.id}` |
| 100 | + case 'team': |
| 101 | + return `/api/v1/team/${entity.id}` |
| 102 | + case 'storage-prefix': |
| 103 | + // Storage objects are tenant-prefix-scoped; deleting the owning resource |
| 104 | + // (recorded separately as kind:'resource') reaps the bucket prefix. This |
| 105 | + // entry exists for the reaper LOG only and is skipped in deletion. |
| 106 | + return '' |
| 107 | + } |
| 108 | +} |
| 109 | + |
| 110 | +/** |
| 111 | + * Delete every entity in `entities` against its recorded api base. Idempotent: |
| 112 | + * a 404/410 counts as alreadyGone (success). Never throws — failures are |
| 113 | + * collected so one stuck entity can't strand the rest. The OUT-OF-PROCESS |
| 114 | + * reaper and the in-process afterAll both call this. |
| 115 | + */ |
| 116 | +export async function reapEntities( |
| 117 | + request: APIRequestContext, |
| 118 | + entities: CohortEntity[], |
| 119 | +): Promise<ReapResult> { |
| 120 | + const result: ReapResult = { attempted: 0, deleted: 0, alreadyGone: 0, failed: [] } |
| 121 | + for (const entity of entities) { |
| 122 | + const path = deletePath(entity) |
| 123 | + if (!path) continue // storage-prefix marker: reaped via its owning resource |
| 124 | + result.attempted++ |
| 125 | + const headers: Record<string, string> = {} |
| 126 | + if (entity.token) headers.Authorization = `Bearer ${entity.token}` |
| 127 | + try { |
| 128 | + const resp = await request.fetch(`${entity.apiUrl.replace(/\/$/, '')}${path}`, { |
| 129 | + method: 'DELETE', |
| 130 | + headers, |
| 131 | + failOnStatusCode: false, |
| 132 | + }) |
| 133 | + const status = resp.status() |
| 134 | + if (status === 404 || status === 410) { |
| 135 | + result.alreadyGone++ |
| 136 | + } else if (status >= 200 && status < 300) { |
| 137 | + result.deleted++ |
| 138 | + } else { |
| 139 | + result.failed.push({ |
| 140 | + entity, |
| 141 | + status, |
| 142 | + error: await resp.text().catch(() => '<unreadable>'), |
| 143 | + }) |
| 144 | + } |
| 145 | + } catch (e) { |
| 146 | + result.failed.push({ entity, status: 0, error: String((e as Error)?.message ?? e) }) |
| 147 | + } |
| 148 | + } |
| 149 | + return result |
| 150 | +} |
0 commit comments