feat(storage): describe the reclaim report, its switch and the run request in the shared contract

The admin state now carries the reclaim switch and the last pass's report.
A report covers every served category, the legacy photos folder included,
with the objects a pass looked at, the unreferenced, eligible and deleted
counts and bytes, and the reason a category was skipped.
This commit is contained in:
Maurice
2026-11-01 13:37:37 +01:00
parent 04debce79e
commit 630f15b5ea
2 changed files with 108 additions and 0 deletions
+44
View File
@@ -2,9 +2,14 @@ import {
STORAGE_BACKEND_TYPES,
STORAGE_BACKEND_TYPE_IDS,
STORAGE_CATEGORIES,
STORAGE_RECLAIM_CATEGORIES,
storageAdminStateSchema,
storageBackfillStatusSchema,
storageConfigSchema,
storageReclaimReportSchema,
storageReclaimRunRequestSchema,
storageReclaimSettingsRequestSchema,
storageReclaimStateSchema,
storageSecretFields,
storageUsageSchema,
type StorageBackendTypeId,
@@ -183,3 +188,42 @@ describe('backfill + usage wire shapes', () => {
expect(stateShape.parse({ usage: null, backfills: [] })).toEqual({ usage: null, backfills: [] });
});
});
describe('the reclaim contract', () => {
const counts = { objects: 0, bytes: 0 };
const perCategory = { objects: 3, unreferenced: counts, eligible: counts, deleted: counts, skipped: null };
const report = {
startedAt: 1_700_000_000_000,
finishedAt: 1_700_000_001_000,
mode: 'report',
stopped: null,
categories: Object.fromEntries(STORAGE_RECLAIM_CATEGORIES.map((c) => [c, perCategory])),
};
it('covers every configurable category and the legacy photos folder', () => {
expect(STORAGE_RECLAIM_CATEGORIES).toEqual([...STORAGE_CATEGORIES, 'photos']);
expect(storageReclaimReportSchema.parse(report)).toEqual(report);
});
it('a report missing a category, or naming an unknown skip reason, is refused', () => {
const { photos: _photos, ...withoutPhotos } = report.categories;
expect(storageReclaimReportSchema.safeParse({ ...report, categories: withoutPhotos }).success).toBe(false);
const odd = { ...report, categories: { ...report.categories, covers: { ...perCategory, skipped: 'tired' } } };
expect(storageReclaimReportSchema.safeParse(odd).success).toBe(false);
});
it('the admin state carries the switch and a nullable last run', () => {
const shape = storageAdminStateSchema.pick({ reclaim: true });
expect(shape.parse({ reclaim: { deleteEnabled: false, lastRun: null } })).toEqual({
reclaim: { deleteEnabled: false, lastRun: null },
});
expect(storageReclaimStateSchema.safeParse({ deleteEnabled: 'yes', lastRun: null }).success).toBe(false);
});
it('the requests are closed objects', () => {
expect(storageReclaimSettingsRequestSchema.parse({ deleteEnabled: true })).toEqual({ deleteEnabled: true });
expect(storageReclaimSettingsRequestSchema.safeParse({ deleteEnabled: true, extra: 1 }).success).toBe(false);
expect(storageReclaimRunRequestSchema.parse({})).toEqual({});
expect(storageReclaimRunRequestSchema.safeParse({ reportOnly: 'no' }).success).toBe(false);
});
});
+64
View File
@@ -276,6 +276,68 @@ export const storageUsageSchema = z.object({
});
export type StorageUsage = z.infer<typeof storageUsageSchema>;
// ── Reclaim: objects no row names any more ────────────────────────────────────
/** Every category the byte-paths serve, the legacy `photos` folder included: the reclaim report covers each. */
export const STORAGE_RECLAIM_CATEGORIES = [...STORAGE_CATEGORIES, 'photos'] as const;
export const storageReclaimCategorySchema = z.enum(STORAGE_RECLAIM_CATEGORIES);
/**
* Why a category deleted nothing on a pass, whatever the switch says:
* - `not_reclaimed`: the category is never reclaimed (a cache, the backups, the legacy photos folder);
* - `sources_missing`: a domain whose rows can name its objects did not answer, so nothing can be proven unreferenced;
* - `shared_location`: its objects sit where another category's do, or where they cannot be told apart;
* - `too_many_unreferenced`: more than a fifth of its objects look unreferenced, which points at a shared bucket;
* - `list_failed` / `source_failed`: the listing or a reference lookup failed, so the pass stopped there.
*/
export const STORAGE_RECLAIM_SKIP_REASONS = [
'not_reclaimed',
'sources_missing',
'shared_location',
'too_many_unreferenced',
'list_failed',
'source_failed',
] as const;
const storageObjectCountSchema = z.object({ objects: z.number().int().nonnegative(), bytes: z.number().nonnegative() });
export const storageReclaimCategoryReportSchema = z.object({
/** Objects the pass looked at; 0 when the category was skipped before it was listed. */
objects: z.number().int().nonnegative(),
/** Older than a day and named by no row. */
unreferenced: storageObjectCountSchema,
/** Unreferenced on every pass for at least a week: what a pass with deletion on removes. */
eligible: storageObjectCountSchema,
deleted: storageObjectCountSchema,
skipped: z.enum(STORAGE_RECLAIM_SKIP_REASONS).nullable(),
});
export type StorageReclaimCategoryReport = z.infer<typeof storageReclaimCategoryReportSchema>;
export const storageReclaimReportSchema = z.object({
startedAt: z.number(),
finishedAt: z.number(),
/** `delete` only when the admin switched deletion on and the pass was not asked to only report. */
mode: z.enum(['report', 'delete']),
/** Why the pass stopped before the end: the database was swapped under it (a restore). Null when it ran through. */
stopped: z.enum(['database_reopened']).nullable(),
categories: z.record(storageReclaimCategorySchema, storageReclaimCategoryReportSchema),
});
export type StorageReclaimReport = z.infer<typeof storageReclaimReportSchema>;
export const storageReclaimStateSchema = z.object({
/** Off after install and upgrade: a pass then only reports. */
deleteEnabled: z.boolean(),
lastRun: storageReclaimReportSchema.nullable(),
});
export type StorageReclaimState = z.infer<typeof storageReclaimStateSchema>;
export const storageReclaimSettingsRequestSchema = z.strictObject({ deleteEnabled: z.boolean() });
export type StorageReclaimSettingsRequest = z.infer<typeof storageReclaimSettingsRequestSchema>;
/** `reportOnly` runs a pass that deletes nothing even with deletion switched on. */
export const storageReclaimRunRequestSchema = z.strictObject({ reportOnly: z.boolean().optional() });
export type StorageReclaimRunRequest = z.infer<typeof storageReclaimRunRequestSchema>;
export const storageAdminStateSchema = z.object({
backends: z.array(
z.object({
@@ -295,6 +357,8 @@ export const storageAdminStateSchema = z.object({
health: z.object({ replicaFailures: z.array(storageReplicaFailureSchema) }),
seedFilePresent: z.boolean(),
usage: storageUsageSchema.nullable(),
/** The reclaim switch and the last pass's report (null before the first pass). */
reclaim: storageReclaimStateSchema,
backfills: z.array(storageBackfillStatusSchema),
migrations: z.array(storageMigrationStatusSchema),
/** Optimistic-concurrency counter for the two settings rows (audit #7) — echo it back on the next PUT. */