feat(backups): tell an empty ledger apart from an empty bucket

On the release that adds the ledger the table is empty, so on a host that has
been uploading nightly for months every account read Never, under a sentence
saying no copy had ever reached the bucket. That sentence is untrue on exactly
the morning an operator opens the new card for the first time, and it is a
claim the host cannot make: what is empty is the record, not the bucket.

The run now records every account it walks, not only the ones an object came
of. A walk that produced nothing moves the attempt instant and leaves the
success columns alone, so the two cases separate: no row at all is no record
yet, a row without a success is never. Never now means what the word says —
a run looked at this account and has never put anything there.

The card names the last check on the never row, so the state is a fact with a
timestamp rather than an assertion. Runbook and all seven bundles carry the
same two sentences. The integration file proves both arms against real
Postgres, including that a failed run leaves the previous good copy on the
row.
This commit is contained in:
Marc-André Bombeck committed 2026-09-10 10:15:31 +02:00
1 parent cfc19a211c
commit 25f0310596
21 files changed
+340 -80

No files matched your search

@@ -109,6 +109,7 @@ describe("off-host backup ledger (real Postgres)", () => {
expect(
classifyOffhostBackup({
lastAttemptAt: row.lastAttemptAt,
lastSuccessAt: row.lastSuccessAt,
now: new Date(),
}).freshness,
@@ -144,12 +145,80 @@ describe("off-host backup ledger (real Postgres)", () => {
});
expect(
classifyOffhostBackup({
lastAttemptAt: row.lastAttemptAt,
lastSuccessAt: row.lastSuccessAt,
now: new Date(),
}).freshness,
).toBe("stale");
});
it("separates an account no run has recorded from one a run found nothing for", async () => {
const prisma = getPrismaClient();
await seedUser("account-one");
// Before any run: the ledger is empty, which is what every account on a
// host that has been uploading for months looks like the moment this
// table ships. It must not read as "nothing has ever reached the bucket".
expect(
classifyOffhostBackup({
lastAttemptAt: null,
lastSuccessAt: null,
now: new Date(),
}).freshness,
).toBe("unknown");
// A run that reaches the account and produces no object records the walk
// and leaves the success columns alone.
const bucket = makeBucket();
bucket.putStream = async () => {
throw new Error("bucket refused the signature");
};
const report = await runOffhostBackup(prisma, bucket, new Date());
expect(report.uploaded).toBe(0);
expect(report.failed).toBe(1);
const row = await prisma.offhostBackupState.findUniqueOrThrow({
where: { userId: "account-one" },
});
expect(row.lastSuccessAt).toBeNull();
expect(row.sizeBytes).toBeNull();
expect(
classifyOffhostBackup({
lastAttemptAt: row.lastAttemptAt,
lastSuccessAt: row.lastSuccessAt,
now: new Date(),
}).freshness,
).toBe("never");
});
it("keeps the last good copy on the row when a later run fails", async () => {
const prisma = getPrismaClient();
await seedUser("account-one");
const bucket = makeBucket();
await runOffhostBackup(prisma, bucket, new Date());
const good = await prisma.offhostBackupState.findUniqueOrThrow({
where: { userId: "account-one" },
});
expect(good.lastSuccessAt).not.toBeNull();
bucket.putStream = async () => {
throw new Error("bucket refused the signature");
};
await runOffhostBackup(prisma, bucket, new Date());
const after = await prisma.offhostBackupState.findUniqueOrThrow({
where: { userId: "account-one" },
});
// The failed run moved the walk instant and nothing else: yesterday's
// copy is still the copy this account has off-host.
expect(after.lastSuccessAt?.getTime()).toBe(good.lastSuccessAt?.getTime());
expect(after.sizeBytes).toBe(good.sizeBytes);
expect(after.lastAttemptAt.getTime()).toBeGreaterThanOrEqual(
good.lastAttemptAt.getTime(),
);
});
it("goes with the account it describes", async () => {
const prisma = getPrismaClient();
await seedUser("account-one");