diff --git a/shared/src/storage/storage.schema.spec.ts b/shared/src/storage/storage.schema.spec.ts index e9e6d5e18..d34be2f91 100644 --- a/shared/src/storage/storage.schema.spec.ts +++ b/shared/src/storage/storage.schema.spec.ts @@ -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); + }); +}); diff --git a/shared/src/storage/storage.schema.ts b/shared/src/storage/storage.schema.ts index 020776650..19041662f 100644 --- a/shared/src/storage/storage.schema.ts +++ b/shared/src/storage/storage.schema.ts @@ -276,6 +276,68 @@ export const storageUsageSchema = z.object({ }); export type StorageUsage = z.infer; +// ── 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; + +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; + +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; + +export const storageReclaimSettingsRequestSchema = z.strictObject({ deleteEnabled: z.boolean() }); +export type StorageReclaimSettingsRequest = z.infer; + +/** `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; + 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. */