feat: image variants cache panel

docs/api.md

@@ -62,7 +62,7 @@ never changes the response or the change itself.
 | Category | Actions |
 | --- | --- |
 | `articles` | `article.create`, `article.edit`, `article.publish`, `article.unpublish`, `article.delete` |
-| `media` | `media.upload`, `media.rename`, `media.delete`, `media.merge`, `media.purge`, `media.variant_create`, `media.variant_update`, `media.variant_delete`, `media.variant_enable`, `media.variant_disable`, `media.variant_purge`, `media.variant_generate_all`, `media.variant_purge_image` |
+| `media` | `media.upload`, `media.rename`, `media.delete`, `media.merge`, `media.purge`, `media.variant_create`, `media.variant_update`, `media.variant_delete`, `media.variant_enable`, `media.variant_disable`, `media.variant_purge`, `media.variant_generate_all`, `media.variant_purge_image`, `media.variant_purge_all`, `media.variant_purge_unused` |
 | `users` | `user.register`, `user.verify`, `user.update_profile`, `invite.create`, `invite.cancel`, `invite.renew`, `invite.accept` |
 | `system` | `system.media_purge` (scheduled), `system.update_checked`, `system.update_downloaded`, `system.restart_requested`, `system.activity_cleanup`, `system.activity_retention_changed` |
 
@@ -77,6 +77,10 @@ name) records nothing. Params: `media.merge` and `media.purge` and `system.media
 `unsupported_format` or `failed`) and is `failed` only when nothing was generated and something failed;
 `media.variant_purge_image` carries `purged_files` and `purged_bytes`; both have an `image` target
 and are recorded only when files were generated or removed;
+`media.variant_purge_all` and `media.variant_purge_unused` (no target) carry `purged_files` and
+`purged_bytes`, the latter also `older_than_days`; a partial purge adds `failed_files` and stays
+`success`, and a purge that removed nothing while some files failed is `failed`; nothing is recorded
+when no file was removed or failed;
 `system.update_checked` carries `update_available`; `system.restart_requested` carries `kind` and,
 for an update, `tag` (it has no target). `system.update_downloaded` is recorded when the job reaches
 `ready` or `failed`, with the origin captured at request time; a refusal at the start is recorded
@@ -110,6 +114,8 @@ this." Behaviour, caching and the public `?v=<name>` contract are in [image-vari
 | `PATCH /v1/image-variants/{name}` | `{ "enabled": true }` or `{ "enabled": false }`. Keeps the generated files. |
 | `DELETE /v1/image-variants/{name}` | 204. Removes the definition and its generated files. |
 | `POST /v1/image-variants/{name}/purge` | `{ "purged_files", "purged_bytes" }`. Keeps the definition. |
+| `GET /v1/image-variants/cache` | Cache statistics, see below. |
+| `POST /v1/image-variants/cache/purge` | Purge generated files by scope, see below. |
 
 A variant is `{ name, width, height, fit, format, quality, generate_on_upload, enabled,
 generated_files, cache_size, created_at, updated_at }`. `width` and `height` are 1 to 8000 or `null`
@@ -122,6 +128,27 @@ Errors are plain text: 400 for a body that is not valid JSON, 404 "Variant not f
 named “thumb” already exists. Choose another name." and 422 with one sentence for the first invalid
 field (name, width and height, fit, format, quality).
 
+### Cache statistics and purge by scope
+
+`GET /v1/image-variants/cache` answers `{ generated_files, disk_used, variants_defined,
+variants_enabled, variants_disabled, rejected_requests, rejected_window_days, unused: { files, bytes,
+days }, by_variant: [{ name, enabled, files, bytes }], top_images: [{ id, filename, url, files, bytes }] }`.
+`by_variant` lists every defined variant by bytes descending then name; `top_images` lists the ten
+images using the most variant bytes (ties by id, images that no longer exist are skipped). `unused`
+counts the files of enabled variants whose reference time (the last public request, or the creation
+time when never requested) is older than 30 days. `rejected_requests` counts the public requests
+refused with 400 over today and the six previous UTC days. Pending request tracking is flushed before
+the read. Arrays are never `null`.
+
+`POST /v1/image-variants/cache/purge` takes `{ "scope": "all" | "unused" | "variant" | "image",
+"variant": "<name>", "image_id": <id> }` (`variant` for the scope `variant`, `image_id` for `image`; a
+target given for another scope is ignored) and answers `{ scope, purged_files, purged_bytes,
+failed_files }`. A purge that fails on some files still answers 200 with `failed_files` above 0; the
+failed rows are kept so the same request can be sent again. Errors are plain text: 400 for a body that
+is not valid JSON, 422 "Scope must be all, unused, variant or image." or "A variant name or an image
+id is required for this scope.", 404 "Variant not found" or "Image not found", 500 when the rows
+cannot be listed.
+
 ### Variants of one image
 Owners and admins only, session only: a request with an API key is 401. All ids are image ids.