@coywolf/emdash 0.0.0-stage → 0.35.13

package/src/images/lib.ts

@@ -0,0 +1,221 @@
+/**
+ * Clean image URLs: resized copies of media-library images at
+ *
+ *   /media/<file id>-<width>x<height>.<format>     (cropped to fill)
+ *   /media/<file id>-<width>w.<format>              (width only, keeps the ratio)
+ *
+ * instead of Astro's /_image?href=…&w=…&h=… endpoint. Pure helpers (no
+ * imports) so tests can load them; the middleware is in pack.ts.
+ *
+ * With a media host configured (`images: { cdn: "https://media.example.com" }`:
+ * an R2 custom domain on the media bucket, with Cloudflare Image
+ * Transformations and the zone's /s/ rewrite rules), URLs point there instead
+ * and never touch the Worker:
+ *
+ *   https://media.example.com/<file>              the original file
+ *   https://media.example.com/s/<w>x<h>/<file>    cropped to fill
+ *   https://media.example.com/s/<w>/<file>        width only, keeps the ratio
+ *
+ * The media host picks WebP or AVIF for browsers that accept them.
+ */
+
+export const IMAGE_PATH = "/media/";
+/**
+ * Media library files: /_emdash/api/media/file/<key> (EmDash's media route),
+ * where the key is <stem>.<ext>. The stem is EmDash's file ULID (not the media
+ * id), and since EmDash 1.1 uploads it can hold a dot (<ulid>.<attempt ulid>),
+ * so a stem is anything up to the last dot.
+ */
+const MEDIA_FILE = /^(?:https?:\/\/[^/]+)?\/_emdash\/api\/media\/file\/([A-Za-z0-9_.-]+)\.([a-z0-9]{2,5})(?:[?#].*)?$/i;
+const CLEAN = /^\/media\/([A-Za-z0-9_.-]+)-(?:(\d{1,4})x(\d{1,4})|(\d{1,4})w)\.(webp|avif|jpe?g|png)$/i;
+export const MAX_DIMENSION = 2560;
+/**
+ * Worker-route sizes are multiples of this many pixels, so anyone requesting
+ * /media/ URLs can't make the Worker run (and bill) a new transform for every
+ * pixel. 10 keeps the sizes themes ask for (50, 100, 400, 640, 800, 1200x630)
+ * exact; anything else rounds up.
+ */
+export const SIZE_STEP = 10;
+
+/** Round a size up to the Worker route's grid (at most MAX_DIMENSION). */
+export function snapDimension(n: number): number {
+	return Math.min(MAX_DIMENSION, Math.ceil(n / SIZE_STEP) * SIZE_STEP);
+}
+export const FORMATS: Record<string, string> = { webp: "image/webp", avif: "image/avif", jpg: "image/jpeg", jpeg: "image/jpeg", png: "image/png" };
+
+/** MIME types of original files by extension (for og:image:type on media-host URLs). */
+export const EXT_MIME: Record<string, string> = { ...FORMATS, gif: "image/gif", svg: "image/svg+xml" };
+/** Originals the media host (Cloudflare Image Transformations) can resize. */
+const CDN_RESIZABLE = new Set(["jpg", "jpeg", "png", "gif", "webp", "svg", "heic"]);
+
+/** The MIME type of a file extension, or undefined when unknown. */
+export function mimeForExt(ext: string | null | undefined): string | undefined {
+	return EXT_MIME[String(ext ?? "").toLowerCase()];
+}
+
+/**
+ * Normalize a media host to its https origin ("media.example.com",
+ * "https://media.example.com/" → "https://media.example.com"). Null for
+ * anything that isn't a plain https host name (no path, query, user or port
+ * other than the default).
+ */
+export function normalizeMediaHost(input: string | null | undefined): string | null {
+	let v = String(input ?? "").trim();
+	if (!v) return null;
+	if (!/^[a-z][a-z0-9+.-]*:\/\//i.test(v)) v = `https://${v}`;
+	v = v.replace(/\/+$/, "");
+	const m = /^https:\/\/([a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)+)$/i.exec(v);
+	return m ? `https://${m[1].toLowerCase()}` : null;
+}
+
+/** The media host set in astro.config.mjs (`images.cdn`), and the one saved on the Clean Image URLs page (wins when set). */
+let optionBase: string | null = null;
+let savedBase: string | null = null;
+
+/** Set (or clear) the media host from the plugin option. Anything but an https origin is ignored. */
+export function setImageCdn(url: string | null | undefined): void {
+	optionBase = normalizeMediaHost(url);
+}
+
+/** Set (or clear) the media host saved in the admin. It overrides the plugin option while set. */
+export function setSavedImageCdn(url: string | null | undefined): void {
+	savedBase = normalizeMediaHost(url);
+}
+
+/** The media host in use (https origin, no trailing slash), or null for the Worker's /media/ route. */
+export function imageCdn(): string | null {
+	return savedBase ?? optionBase;
+}
+
+/**
+ * Add `Link: <media host>; rel=preconnect` to a page (HTML) response, so the
+ * browser opens the connection to the media host (DNS, TCP, TLS) while the
+ * page is still arriving instead of when it reaches the first image. No
+ * `crossorigin`: images are fetched without CORS, so that's the connection
+ * they use. Returns the response unchanged without a host, for anything but
+ * HTML, or when it already has a preconnect to the host.
+ */
+export function withMediaPreconnect(response: Response, host: string | null = imageCdn()): Response {
+	if (!host || !(response.headers.get("content-type") ?? "").startsWith("text/html")) return response;
+	const link = response.headers.get("link") ?? "";
+	if (link.includes(`<${host}>`) && /rel="?preconnect/i.test(link)) return response;
+	const value = `<${host}>; rel=preconnect`;
+	try {
+		response.headers.append("link", value);
+		return response;
+	} catch {
+		// Immutable headers (a response passed through from fetch): copy it.
+		const copy = new Response(response.body, response);
+		copy.headers.append("link", value);
+		return copy;
+	}
+}
+
+/** Where the media host comes from: the admin setting, the plugin option, or nowhere. */
+export function imageCdnSource(): { host: string | null; option: string | null; saved: string | null } {
+	return { host: imageCdn(), option: optionBase, saved: savedBase };
+}
+
+export interface ImageRequest {
+	id: string;
+	width: number;
+	height?: number;
+	format: string;
+}
+
+/** The file id and extension of a media-library URL, or null for anything else. */
+export function mediaFile(src: string | null | undefined): { id: string; ext: string } | null {
+	const m = MEDIA_FILE.exec(String(src ?? "").trim());
+	return m ? { id: m[1], ext: m[2].toLowerCase() } : null;
+}
+
+/** The original file on the media host, or null when there's no host or `src` isn't a media-library file. */
+export function cdnOriginalUrl(src: string | null | undefined): string | null {
+	const cdn = imageCdn();
+	if (!cdn) return null;
+	const file = mediaFile(src);
+	if (file) return `${cdn}/${file.id}.${file.ext}`;
+	// Already on the media host: its original.
+	const onHost = parseCdnUrl(String(src ?? "").trim());
+	return onHost ? `${cdn}/${onHost.id}.${onHost.ext}` : null;
+}
+
+/**
+ * Build a clean URL; null when `src` isn't a media-library file or the size is
+ * out of range. On the media host when one is set (format chosen by the host),
+ * otherwise the Worker's /media/ route.
+ */
+export function cleanImagePath(src: string | null | undefined, options: { width: number; height?: number; format?: string }): string | null {
+	const file = mediaFile(src);
+	if (!file) return null;
+	const width = Math.round(options.width);
+	const height = options.height === undefined ? undefined : Math.round(options.height);
+	if (!(width >= 1 && width <= MAX_DIMENSION) || (height !== undefined && !(height >= 1 && height <= MAX_DIMENSION))) return null;
+	const cdn = imageCdn();
+	if (cdn) {
+		// Cloudflare's resizer reads JPEG, PNG, GIF, WebP, SVG and HEIC, not AVIF (it answers 415).
+		if (!CDN_RESIZABLE.has(file.ext)) return null;
+		return `${cdn}/s/${height === undefined ? width : `${width}x${height}`}/${file.id}.${file.ext}`;
+	}
+	const format = (options.format ?? "webp").toLowerCase();
+	if (!FORMATS[format]) return null;
+	return imagePath({ id: file.id, width: snapDimension(width), height: height === undefined ? undefined : snapDimension(height), format });
+}
+
+/** The Worker-route path of a request, as given (no snapping). */
+function imagePath(request: ImageRequest): string {
+	return `${IMAGE_PATH}${request.id}-${request.height === undefined ? `${request.width}w` : `${request.width}x${request.height}`}.${request.format}`;
+}
+
+/**
+ * The on-grid path for a Worker-route request whose size is off the grid
+ * (see SIZE_STEP), or null when it's already on it. The middleware answers
+ * off-grid requests with a redirect there instead of resizing.
+ */
+export function snappedImagePath(request: ImageRequest): string | null {
+	const width = snapDimension(request.width);
+	const height = request.height === undefined ? undefined : snapDimension(request.height);
+	if (width === request.width && height === request.height) return null;
+	return imagePath({ ...request, width, height });
+}
+
+/** Parse a clean URL path; null when it isn't one (or the size is out of range). */
+export function parseImagePath(pathname: string): ImageRequest | null {
+	const m = CLEAN.exec(pathname);
+	if (!m) return null;
+	const width = Number(m[2] ?? m[4]);
+	const height = m[3] ? Number(m[3]) : undefined;
+	if (!(width >= 1 && width <= MAX_DIMENSION) || (height !== undefined && !(height >= 1 && height <= MAX_DIMENSION))) return null;
+	return { id: m[1], width, height, format: m[5].toLowerCase() };
+}
+
+/**
+ * Parse a media-host URL (absolute, on the configured host): the file and the
+ * requested size (none for the original). Null for anything else.
+ */
+export function parseCdnUrl(url: string | null | undefined): { id: string; ext: string; width?: number; height?: number } | null {
+	const cdn = imageCdn();
+	const value = String(url ?? "");
+	if (!cdn || !value.startsWith(`${cdn}/`)) return null;
+	const path = value.slice(cdn.length).split(/[?#]/)[0];
+	const m = /^\/(?:s\/(\d{1,4})(?:x(\d{1,4}))?\/)?([A-Za-z0-9_.-]+)\.([a-z0-9]{2,5})$/i.exec(path);
+	if (!m) return null;
+	const width = m[1] ? Number(m[1]) : undefined;
+	const height = m[2] ? Number(m[2]) : undefined;
+	if ((width !== undefined && !(width >= 1 && width <= MAX_DIMENSION)) || (height !== undefined && !(height >= 1 && height <= MAX_DIMENSION))) return null;
+	return { id: m[3], ext: m[4].toLowerCase(), width, height };
+}
+
+/** A media-library file's bucket key as stored by EmDash (<id>.<ext>). */
+const KEY = /^[A-Za-z0-9_.-]+\.[a-z0-9]{2,5}$/i;
+
+/**
+ * Where an old Worker-route URL (/media/<id>-<w>x<h>.<format>) lives on the
+ * media host, given the file's bucket key: the same size, format chosen by
+ * the host. Null without a media host or for a malformed key.
+ */
+export function cdnRedirectUrl(request: Pick<ImageRequest, "width" | "height">, key: string): string | null {
+	const cdn = imageCdn();
+	if (!cdn || !KEY.test(key)) return null;
+	return `${cdn}/s/${request.height === undefined ? request.width : `${request.width}x${request.height}`}/${key}`;
+}

package/src/images/module.ts

@@ -0,0 +1,372 @@
+/**
+ * Clean Image URLs admin routes: the media host setting, a live check of the
+ * media host, and the optional one-click Cloudflare setup (plan, then apply).
+ *
+ * The Cloudflare API token comes from the request (typed on the page, not
+ * stored unless saved), the saved secret, or a Worker secret
+ * (IMAGES_API_TOKEN, then CLOUDFLARE_API_TOKEN). It's only sent to
+ * api.cloudflare.com, never logged or returned.
+ */
+import type { PluginContext } from "emdash";
+import { PluginRouteError, definePluginRoute } from "emdash";
+import { z } from "zod";
+
+import { requireFeature } from "../core/features.js";
+import { afterResponse, parseInput, secret, workerEnv } from "../shared.js";
+import { CloudflareApiError, type CloudflareConfig, applySetup, checkMediaHost, planSetup, purgeHost } from "./cloudflare.js";
+import { imageCdn, imageCdnSource, normalizeMediaHost } from "./lib.js";
+import { rememberSiteSetting } from "../core/features.js";
+import { IMAGES_SETTINGS, invalidateMediaHost, refreshMediaHost } from "./settings.js";
+import { type BackfillDeps, type VariantsState, estimateRows, publicState, publishedCount, readVariantsState, startVariantsRun, variantCounts } from "./variants-store.js";
+import { summarizeLibrary } from "./variants-estimate.js";
+import { imageCrops } from "./variants.js";
+
+const F = "images";
+
+export const QUOTA_NOTE =
+	"Cloudflare's Free plan includes 5,000 unique image transformations a month (each new size of each image counts once a month; repeat views are served from the cache). Stored sizes are made once per image (each width and crop, as WebP and AVIF) and then served as plain files, so they don't count again. Beyond the free amount, transformations need a paid Cloudflare Images plan; without one, new sizes stop being made until the next month while existing ones keep working.";
+
+export const VARIANTS_FALLBACK_NOTE =
+	"New uploads get their sizes right away. Images without stored sizes (existing images until you turn them on, and images over 20 MB, GIFs and SVGs) keep using the media host's /s/ resizing. Crops (thumbnails, avatars) are made the first time a page shows them; pages shown while a new upload's sizes or a crop are being made are cached for minutes instead of days, so they pick them up. Pages keep their normal caching while existing images wait for their sizes; when a run finishes, the page cache is cleared once (and warmed again, with cache warming on) so every page uses them.";
+
+const hostInput = z
+	.string()
+	.max(253)
+	.optional()
+	.transform((v, zctx) => {
+		if (v === undefined) return undefined;
+		if (!v.trim()) return "";
+		const host = normalizeMediaHost(v);
+		if (!host) {
+			zctx.addIssue({ code: "custom", message: "The media host must be an https address like https://media.example.com (no path)." });
+			return z.NEVER;
+		}
+		return host;
+	});
+const accountInput = z
+	.string()
+	.trim()
+	.max(64)
+	.regex(/^([0-9a-f]{32})?$/i, "The account ID is 32 letters and numbers (0-9, a-f).")
+	.optional();
+const bucketInput = z
+	.string()
+	.trim()
+	.max(63)
+	.regex(/^([a-z0-9][a-z0-9-]{1,61}[a-z0-9])?$/, "Bucket names use lowercase letters, numbers and hyphens (3-63 characters).")
+	.optional();
+
+const settingsInput = z.object({
+	host: hostInput,
+	accountId: accountInput,
+	bucket: bucketInput,
+	token: z.string().trim().max(400).optional(),
+	clearToken: z.boolean().optional(),
+});
+
+const setupInput = z.object({
+	host: hostInput,
+	accountId: accountInput,
+	bucket: bucketInput,
+	token: z.string().trim().max(400).optional(),
+});
+
+async function env(): Promise<Record<string, unknown>> {
+	try {
+		return await workerEnv();
+	} catch {
+		return {};
+	}
+}
+
+async function adminSettings(ctx: PluginContext) {
+	const [host, accountId, bucket, token] = await Promise.all([
+		ctx.settings.get<string>(IMAGES_SETTINGS.host),
+		ctx.settings.get<string>(IMAGES_SETTINGS.accountId),
+		ctx.settings.get<string>(IMAGES_SETTINGS.bucket),
+		ctx.settings.get<string>(IMAGES_SETTINGS.token).catch(() => null),
+	]);
+	const e = await env();
+	invalidateMediaHost(host ?? null);
+	const source = imageCdnSource();
+	return {
+		host: host ?? "",
+		optionHost: source.option ?? "",
+		activeHost: source.host ?? "",
+		accountId: accountId ?? "",
+		bucket: bucket ?? "",
+		tokenSet: Boolean(token?.trim()),
+		envToken: Boolean(secret(e, "IMAGES_API_TOKEN") || secret(e, "CLOUDFLARE_API_TOKEN")),
+		envAccountId: Boolean(secret(e, "CF_ACCOUNT_ID") || secret(e, "CLOUDFLARE_ACCOUNT_ID")),
+		siteHost: siteHostname(ctx),
+		quotaNote: QUOTA_NOTE,
+	};
+}
+
+function siteHostname(ctx: PluginContext): string {
+	try {
+		return ctx.site?.url ? new URL(ctx.site.url).hostname.replace(/^www\./, "") : "";
+	} catch {
+		return "";
+	}
+}
+
+/** Credentials for the setup: the request's, then the saved ones, then Worker variables. */
+async function credentials(ctx: PluginContext, input: z.infer<typeof setupInput>): Promise<CloudflareConfig & { bucket: string; host: string }> {
+	const e = await env();
+	const savedToken = await ctx.settings.get<string>(IMAGES_SETTINGS.token).catch(() => null);
+	const token = input.token || savedToken?.trim() || secret(e, "IMAGES_API_TOKEN") || secret(e, "CLOUDFLARE_API_TOKEN");
+	const accountId =
+		input.accountId || (await ctx.settings.get<string>(IMAGES_SETTINGS.accountId))?.trim() || secret(e, "CF_ACCOUNT_ID") || secret(e, "CLOUDFLARE_ACCOUNT_ID");
+	const bucket = input.bucket || (await ctx.settings.get<string>(IMAGES_SETTINGS.bucket))?.trim() || "";
+	const host = input.host || imageCdn() || "";
+	const missing = [!host && "media host", !accountId && "Cloudflare account ID", !bucket && "R2 bucket name", !token && "Cloudflare API token"].filter(Boolean);
+	if (missing.length) throw PluginRouteError.badRequest(`Enter the ${missing.join(", ")} first.`);
+	const doFetch = ctx.http ? (ctx.http.fetch.bind(ctx.http) as CloudflareConfig["fetch"]) : undefined;
+	return { token: token as string, accountId: accountId as string, bucket, host, fetch: doFetch };
+}
+
+/**
+ * The media host and the Cloudflare API access for it (the token and account
+ * saved on this page, else the IMAGES_API_TOKEN / CLOUDFLARE_API_TOKEN and
+ * CF_ACCOUNT_ID Worker secrets). `reason` says what's missing instead.
+ */
+export async function mediaApiAccess(
+	ctx: PluginContext,
+): Promise<{ hostname: string; config: CloudflareConfig } | { hostname: string | null; reason: string }> {
+	await refreshMediaHost();
+	const host = imageCdn();
+	if (!host) return { hostname: null, reason: "No media host is set (Clean Image URLs)." };
+	const hostname = new URL(host).hostname;
+	const e = await env();
+	const savedToken = await ctx.settings.get<string>(IMAGES_SETTINGS.token).catch(() => null);
+	const token = savedToken?.trim() || secret(e, "IMAGES_API_TOKEN") || secret(e, "CLOUDFLARE_API_TOKEN");
+	const accountId = (await ctx.settings.get<string>(IMAGES_SETTINGS.accountId))?.trim() || secret(e, "CF_ACCOUNT_ID") || secret(e, "CLOUDFLARE_ACCOUNT_ID");
+	if (!token || !accountId) {
+		return { hostname, reason: "Add a Cloudflare API token and account ID on the Clean Image URLs page." };
+	}
+	const doFetch = ctx.http ? (ctx.http.fetch.bind(ctx.http) as CloudflareConfig["fetch"]) : undefined;
+	return { hostname, config: { token, accountId, fetch: doFetch } };
+}
+
+/** Clear the media host's images from Cloudflare's zone cache. Says why when it can't, instead of throwing. */
+export async function purgeMediaHost(ctx: PluginContext): Promise<{ purged: boolean; host: string | null; message?: string }> {
+	const access = await mediaApiAccess(ctx);
+	if (!("config" in access)) {
+		return { purged: false, host: access.hostname, message: access.hostname ? `Images on ${access.hostname} weren't cleared. ${access.reason} The token needs Zone → Cache Purge → Purge.` : access.reason };
+	}
+	try {
+		await purgeHost(access.config, access.hostname);
+		return { purged: true, host: access.hostname };
+	} catch (error) {
+		return { purged: false, host: access.hostname, message: `Images on ${access.hostname} weren't cleared. ${error instanceof Error ? error.message : String(error)}` };
+	}
+}
+
+function apiError(error: unknown): never {
+	if (error instanceof CloudflareApiError) throw PluginRouteError.badRequest(error.message);
+	throw error;
+}
+
+/** A recent image in the media library to check with (SVGs aren't resized). */
+async function sampleFile(database: string): Promise<string | null> {
+	const e = await env();
+	const db = e[database] as D1Database | undefined;
+	if (!db) return null;
+	const row = await db
+		.prepare(
+			"SELECT storage_key FROM media WHERE mime_type LIKE 'image/%' AND mime_type NOT LIKE '%svg%' AND (status IS NULL OR status = 'ready') ORDER BY created_at DESC LIMIT 1",
+		)
+		.first<{ storage_key: string }>()
+		.catch(() => null);
+	return row?.storage_key && /^[A-Za-z0-9_.-]+\.[a-z0-9]{2,5}$/i.test(row.storage_key) ? row.storage_key : null;
+}
+
+async function runCheck(host: string, database: string) {
+	const file = await sampleFile(database);
+	if (!file) throw PluginRouteError.badRequest("Upload an image to the media library first: the check fetches one from the media host.");
+	const items = await checkMediaHost(host, file);
+	return { host, file, ok: items.filter((i) => i.id !== "cached").every((i) => i.ok), items, quotaNote: QUOTA_NOTE };
+}
+
+interface VariantsHooks {
+	/** Start the backfill's chain of steps (a new run with `force`); it works in the background. */
+	start(origin: string, force?: boolean): Promise<VariantsState | null>;
+	/** The bindings, or null when something is missing. */
+	deps(): Promise<BackfillDeps | null>;
+}
+
+/** The stored-sizes status for the admin; `bulk`: sizes for existing images are on. */
+async function variantsStatus(variants: VariantsHooks, bulk: boolean) {
+	const deps = await variants.deps();
+	if (!deps) {
+		return {
+			available: false,
+			reason: "Stored sizes need a media host, and the MEDIA bucket, IMAGES and DB bindings.",
+			bulk,
+			crops: imageCrops(),
+			fallbackNote: VARIANTS_FALLBACK_NOTE,
+		};
+	}
+	const [counts, { state }] = await Promise.all([variantCounts(deps.db), readVariantsState(deps.db)]);
+	return { available: true, bulk, ...counts, state: publicState(state), perHour: state ? imagesPerHour(state) : null, crops: imageCrops(), fallbackNote: VARIANTS_FALLBACK_NOTE };
+}
+
+/** Images a running backfill handles an hour, from its start (null when it's not running or just started). */
+export function imagesPerHour(state: VariantsState, now = Date.now()): number | null {
+	if (state.phase !== "running") return null;
+	const hours = (now - Date.parse(state.startedAt)) / 3_600_000;
+	const handled = state.done + state.skipped + state.failed;
+	return hours >= 2 / 60 && handled > 0 ? Math.round(handled / hours) : null;
+}
+
+/** Origin of a route's request (the chain's steps are posted there). */
+const requestOrigin = (ctx: { request: Request }) => new URL(ctx.request.url).origin;
+
+const bulkSetting = async (ctx: PluginContext) => (await ctx.settings.get<boolean>(IMAGES_SETTINGS.bulk)) === true;
+
+export function imagesModule(options: { database?: string; variants: VariantsHooks }) {
+	const database = options.database ?? "DB";
+	const variants = options.variants;
+	return {
+		routes: {
+			"images/settings": {
+				permission: "plugins:manage" as const,
+				handler: async (ctx: PluginContext) => {
+					await requireFeature(ctx, F);
+					return adminSettings(ctx);
+				},
+			},
+
+			"images/settings/save": definePluginRoute({
+				permission: "plugins:manage",
+				methods: ["POST"],
+				request: { body: "json" },
+				handler: async (ctx) => {
+					await requireFeature(ctx, F);
+					const input = parseInput(settingsInput, ctx.input);
+					if (input.host !== undefined) await ctx.settings.set(IMAGES_SETTINGS.host, input.host);
+					if (input.accountId !== undefined) await ctx.settings.set(IMAGES_SETTINGS.accountId, input.accountId);
+					if (input.bucket !== undefined) await ctx.settings.set(IMAGES_SETTINGS.bucket, input.bucket);
+					if (input.clearToken) await ctx.settings.delete(IMAGES_SETTINGS.token);
+					else if (input.token) await ctx.settings.set(IMAGES_SETTINGS.token, input.token);
+					ctx.log.info("Clean image URLs settings saved", { tokenChanged: Boolean(input.clearToken || input.token) });
+					return adminSettings(ctx);
+				},
+			}),
+
+			"images/check": definePluginRoute({
+				permission: "plugins:manage",
+				methods: ["POST"],
+				request: { body: "json" },
+				handler: async (ctx) => {
+					await requireFeature(ctx, F);
+					const { host } = parseInput(z.object({ host: hostInput }), ctx.input ?? {});
+					await refreshMediaHost();
+					const target = host || imageCdn();
+					if (!target) throw PluginRouteError.badRequest("Enter a media host to check.");
+					return runCheck(target, database);
+				},
+			}),
+
+			"images/variants/settings": {
+				permission: "plugins:manage" as const,
+				handler: async (ctx: PluginContext) => {
+					await requireFeature(ctx, F);
+					return variantsStatus(variants, await bulkSetting(ctx));
+				},
+			},
+
+			/** What stored sizes for the existing library would take: counts for the page's cost estimate (computed there). */
+			"images/variants/estimate": {
+				permission: "plugins:manage" as const,
+				handler: async (ctx: PluginContext) => {
+					await requireFeature(ctx, F);
+					const deps = await variants.deps();
+					if (!deps) throw PluginRouteError.badRequest("Stored sizes need a media host, and the MEDIA bucket, IMAGES and DB bindings.");
+					const [rows, pages] = await Promise.all([estimateRows(deps.db), publishedCount(deps.db)]);
+					return { ...summarizeLibrary(rows), pages };
+				},
+			},
+
+			/** Turn stored sizes for existing images on (after the page showed the estimate) or off. On starts a run. */
+			"images/variants/bulk": definePluginRoute({
+				permission: "plugins:manage",
+				methods: ["POST"],
+				request: { body: "json" },
+				handler: async (ctx) => {
+					await requireFeature(ctx, F);
+					const { on } = parseInput(z.object({ on: z.boolean() }), ctx.input ?? {});
+					const deps = await variants.deps();
+					if (on && !deps) throw PluginRouteError.badRequest("Stored sizes need a media host, and the MEDIA bucket, IMAGES and DB bindings.");
+					await ctx.settings.set(IMAGES_SETTINGS.bulk, on);
+					rememberSiteSetting(IMAGES_SETTINGS.bulk, on);
+					if (on && deps) {
+						await startVariantsRun(deps.db, { force: true });
+						// The run's steps follow in the background (a chain of requests of their own).
+						await afterResponse(variants.start(requestOrigin(ctx)).catch((error) => console.error("coywolf-pack images: couldn't start the backfill", error)));
+					}
+					ctx.log.info(on ? "Stored sizes for existing images turned on" : "Stored sizes for existing images turned off");
+					return variantsStatus(variants, on);
+				},
+			}),
+
+			/**
+			 * "Make missing sizes now" (only with sizes for existing images on): starts the backfill's chain
+			 * (a new run with `start`), unless one is already working, and reports. The work goes on in the
+			 * background; the page polls images/variants/settings for progress.
+			 */
+			"images/variants/run": definePluginRoute({
+				permission: "plugins:manage",
+				methods: ["POST"],
+				request: { body: "json" },
+				handler: async (ctx) => {
+					await requireFeature(ctx, F);
+					const deps = await variants.deps();
+					if (!deps) throw PluginRouteError.badRequest("Stored sizes need a media host, and the MEDIA bucket, IMAGES and DB bindings.");
+					if (!(await bulkSetting(ctx))) throw PluginRouteError.badRequest("Turn on stored sizes for existing images first.");
+					const { start } = parseInput(z.object({ start: z.boolean().optional() }), ctx.input ?? {});
+					if (start) await startVariantsRun(deps.db, { force: true });
+					await afterResponse(variants.start(requestOrigin(ctx)).catch((error) => console.error("coywolf-pack images: couldn't start the backfill", error)));
+					return variantsStatus(variants, true);
+				},
+			}),
+
+			"images/setup/plan": definePluginRoute({
+				permission: "plugins:manage",
+				methods: ["POST"],
+				request: { body: "json" },
+				handler: async (ctx) => {
+					await requireFeature(ctx, F);
+					const config = await credentials(ctx, parseInput(setupInput, ctx.input ?? {}));
+					try {
+						const { zone, plan } = await planSetup(config, { host: config.host, bucket: config.bucket });
+						return { zone: zone.name, plan: { host: plan.host, steps: plan.steps, done: plan.done }, quotaNote: QUOTA_NOTE };
+					} catch (error) {
+						apiError(error);
+					}
+				},
+			}),
+
+			"images/setup/apply": definePluginRoute({
+				permission: "plugins:manage",
+				methods: ["POST"],
+				request: { body: "json" },
+				handler: async (ctx) => {
+					await requireFeature(ctx, F);
+					const config = await credentials(ctx, parseInput(setupInput, ctx.input ?? {}));
+					let applied: Awaited<ReturnType<typeof applySetup>>;
+					try {
+						applied = await applySetup(config, { host: config.host, bucket: config.bucket });
+					} catch (error) {
+						apiError(error);
+					}
+					ctx.log.info("Media host setup applied", { zone: applied.zone, steps: applied.results.map((r) => `${r.id}:${r.ok ? "ok" : "failed"}`) });
+					const host = normalizeMediaHost(config.host) as string;
+					const check = applied.results.every((r) => r.ok) ? await runCheck(host, database).catch(() => null) : null;
+					return { zone: applied.zone, results: applied.results, check };
+				},
+			}),
+		},
+	};
+}