@coywolf/emdash 0.0.0-stage → 0.35.14

package/src/images/cloudflare.ts

@@ -0,0 +1,329 @@
+/**
+ * Media host setup and checks through the Cloudflare API, plus the live check
+ * of a media host. The API token is only ever sent to api.cloudflare.com: it
+ * is never logged, returned, or included in error messages.
+ */
+import { type CustomDomain, type RulesetRule, type SetupPlan, type SetupState, hostnameOf, planMediaHostSetup, zoneCandidates } from "./setup.js";
+
+export const CLOUDFLARE_API_HOST = "api.cloudflare.com";
+const API = `https://${CLOUDFLARE_API_HOST}/client/v4`;
+
+type Fetch = (url: string, init?: RequestInit) => Promise<Response>;
+
+export interface CloudflareConfig {
+	token: string;
+	accountId: string;
+	fetch?: Fetch;
+}
+
+export class CloudflareApiError extends Error {
+	readonly status: number;
+	constructor(message: string, status: number) {
+		super(message);
+		this.status = status;
+	}
+}
+
+/** What each step of the setup needs, for error messages when the token lacks it. */
+const PERMISSION_HINT: Record<string, string> = {
+	zone: "Zone → Zone → Read",
+	transformations: "Zone → Zone Settings → Edit",
+	domain: "Account → Workers R2 Storage → Edit and Zone → DNS → Edit",
+	rules: "Zone → Transform Rules → Edit (and Account → Account Rulesets → Read)",
+	purge: "Zone → Cache Purge → Purge",
+	cacheRules: "Zone → Cache Rules → Edit",
+	tieredCache: "Zone → Zone Settings → Edit",
+};
+
+async function cf<T>(config: CloudflareConfig, path: string, init: RequestInit = {}, step?: string): Promise<{ status: number; result: T | null }> {
+	const doFetch = config.fetch ?? fetch;
+	const res = await doFetch(`${API}${path}`, {
+		...init,
+		headers: { Authorization: `Bearer ${config.token}`, "Content-Type": "application/json", ...(init.headers ?? {}) },
+	});
+	const body = (await res.json().catch(() => ({}))) as { success?: boolean; result?: T; errors?: Array<{ code?: number; message?: string }> };
+	if (!res.ok || body.success === false) {
+		const detail = body.errors?.map((e) => e.message).filter(Boolean).join("; ") || res.statusText;
+		const hint = (res.status === 401 || res.status === 403) && step ? ` The API token needs ${PERMISSION_HINT[step]}.` : "";
+		throw new CloudflareApiError(`Cloudflare API ${res.status}: ${detail}.${hint}`, res.status);
+	}
+	return { status: res.status, result: body.result ?? null };
+}
+
+/**
+ * Clear everything Cloudflare's zone cache holds for one host name (the media
+ * host: originals and resized copies). Purge by hostname works on every plan.
+ */
+export async function purgeHost(config: CloudflareConfig, hostname: string): Promise<void> {
+	const zone = await findZone(config, hostname);
+	await cf(config, `/zones/${zone.id}/purge_cache`, { method: "POST", body: JSON.stringify({ hosts: [hostname] }) }, "purge");
+}
+
+/** Description that marks the media host's cache rule as the pack's own. */
+export const MEDIA_CACHE_RULE = "Coywolf Pack: media host";
+const YEAR = 31536000;
+
+interface CacheRule {
+	id?: string;
+	description?: string;
+	expression?: string;
+	action?: string;
+	action_parameters?: { cache?: boolean; edge_ttl?: { default?: number }; browser_ttl?: { default?: number } };
+	enabled?: boolean;
+}
+
+function mediaCacheRule(hostname: string): CacheRule {
+	return {
+		description: `${MEDIA_CACHE_RULE} (file names never change)`,
+		expression: `(http.host eq "${hostname}")`,
+		action: "set_cache_settings",
+		action_parameters: { cache: true, edge_ttl: { mode: "override_origin", default: YEAR }, browser_ttl: { mode: "override_origin", default: YEAR } } as CacheRule["action_parameters"],
+		enabled: true,
+	};
+}
+
+/**
+ * The media host's Cache Rule, if any: a zone cache rule for exactly this host
+ * name that caches it (made by the pack or by hand).
+ */
+export async function readMediaCacheRule(config: CloudflareConfig, hostname: string): Promise<{ zone: string; rule: { edgeTtl?: number; browserTtl?: number; enabled: boolean } | null }> {
+	const zone = await findZone(config, hostname);
+	let rules: CacheRule[] = [];
+	try {
+		const { result } = await cf<{ rules?: CacheRule[] }>(config, `/zones/${zone.id}/rulesets/phases/http_request_cache_settings/entrypoint`, {}, "cacheRules");
+		rules = result?.rules ?? [];
+	} catch (error) {
+		if (!(error instanceof CloudflareApiError && error.status === 404)) throw error;
+	}
+	const rule = rules.find((r) => r.action === "set_cache_settings" && r.action_parameters?.cache === true && r.expression?.includes(`"${hostname}"`));
+	return {
+		zone: zone.name,
+		rule: rule ? { edgeTtl: rule.action_parameters?.edge_ttl?.default, browserTtl: rule.action_parameters?.browser_ttl?.default, enabled: rule.enabled !== false } : null,
+	};
+}
+
+/**
+ * Cache the media host at the edge and in browsers for a year (its file names
+ * are unique, so a changed file always has a new name). Adds the rule to the
+ * zone's cache rules, or updates the pack's earlier one; other rules are kept.
+ */
+export async function applyMediaCacheRule(config: CloudflareConfig, hostname: string): Promise<string> {
+	const zone = await findZone(config, hostname);
+	const phase = `/zones/${zone.id}/rulesets/phases/http_request_cache_settings/entrypoint`;
+	let ruleset: { id: string; rules?: CacheRule[] } | null = null;
+	try {
+		ruleset = (await cf<{ id: string; rules?: CacheRule[] }>(config, phase, {}, "cacheRules")).result;
+	} catch (error) {
+		if (!(error instanceof CloudflareApiError && error.status === 404)) throw error;
+	}
+	const rule = mediaCacheRule(hostname);
+	if (!ruleset) {
+		await cf(config, phase, { method: "PUT", body: JSON.stringify({ rules: [rule] }) }, "cacheRules");
+		return zone.name;
+	}
+	const existing = ruleset.rules?.find((r) => r.description?.startsWith(MEDIA_CACHE_RULE) && r.expression?.includes(`"${hostname}"`));
+	if (existing?.id) {
+		await cf(config, `/zones/${zone.id}/rulesets/${ruleset.id}/rules/${existing.id}`, { method: "PATCH", body: JSON.stringify(rule) }, "cacheRules");
+	} else {
+		await cf(config, `/zones/${zone.id}/rulesets/${ruleset.id}/rules`, { method: "POST", body: JSON.stringify(rule) }, "cacheRules");
+	}
+	return zone.name;
+}
+
+/** The zone that holds a host name, looked up in the account (most specific name first). */
+export async function findZone(config: CloudflareConfig, hostname: string): Promise<{ id: string; name: string; plan?: string }> {
+	for (const name of zoneCandidates(hostname)) {
+		const { result } = await cf<Array<{ id: string; name: string; plan?: { name?: string } }>>(
+			config,
+			`/zones?name=${encodeURIComponent(name)}&account.id=${encodeURIComponent(config.accountId)}`,
+			{},
+			"zone",
+		);
+		const zone = result?.find((z) => z.name === name);
+		if (zone) return { id: zone.id, name: zone.name, plan: zone.plan?.name };
+	}
+	throw new CloudflareApiError(
+		`No zone for ${hostname} in this Cloudflare account. Add the site's domain to the account, or check the account ID. The API token needs ${PERMISSION_HINT.zone}.`,
+		404,
+	);
+}
+
+async function readRules(config: CloudflareConfig, zoneId: string): Promise<RulesetRule[] | null> {
+	try {
+		const { result } = await cf<{ rules?: RulesetRule[] }>(config, `/zones/${zoneId}/rulesets/phases/http_request_transform/entrypoint`, {}, "rules");
+		return result?.rules ?? [];
+	} catch (error) {
+		if (error instanceof CloudflareApiError && error.status === 404) return null;
+		throw error;
+	}
+}
+
+export interface SetupTarget {
+	host: string;
+	bucket: string;
+}
+
+export interface SetupContext {
+	zone: { id: string; name: string; plan?: string };
+	state: SetupState;
+	plan: SetupPlan;
+}
+
+/** Read the current state and plan the setup (changes nothing). */
+export async function planSetup(config: CloudflareConfig, target: SetupTarget): Promise<SetupContext> {
+	const hostname = hostnameOf(target.host);
+	const zone = await findZone(config, hostname);
+	const [transformations, domains, rules, tieredCache] = await Promise.all([
+		cf<{ value?: string }>(config, `/zones/${zone.id}/settings/transformations`, {}, "transformations").then((r) => r.result?.value ?? null),
+		cf<{ domains?: CustomDomain[] }>(config, `/accounts/${config.accountId}/r2/buckets/${encodeURIComponent(target.bucket)}/domains/custom`, {}, "domain").then(
+			(r) => r.result?.domains ?? [],
+		),
+		readRules(config, zone.id),
+		// Read only to show the step; a token without the permission still gets the rest of the setup.
+		cf<{ value?: string }>(config, `/zones/${zone.id}/cache/tiered_cache_smart_topology_enable`, {}, "tieredCache")
+			.then((r) => r.result?.value ?? null)
+			.catch(() => null),
+	]);
+	const state: SetupState = { transformations, domains, rules, tieredCache };
+	return { zone, state, plan: planMediaHostSetup(state, { host: hostname, zoneName: zone.name, bucket: target.bucket }) };
+}
+
+export interface StepResult {
+	id: string;
+	ok: boolean;
+	message: string;
+}
+
+/** Apply the steps that need it, in order; stops at the first failure. */
+export async function applySetup(config: CloudflareConfig, target: SetupTarget): Promise<{ zone: string; results: StepResult[] }> {
+	const { zone, plan } = await planSetup(config, target);
+	const bucket = encodeURIComponent(target.bucket);
+	const results: StepResult[] = [];
+	for (const step of plan.steps) {
+		if (step.action === "none") {
+			results.push({ id: step.id, ok: true, message: step.label });
+			continue;
+		}
+		try {
+			if (step.id === "transformations") {
+				await cf(config, `/zones/${zone.id}/settings/transformations`, { method: "PATCH", body: JSON.stringify({ value: "on" }) }, "transformations");
+				results.push({ id: step.id, ok: true, message: `Turned on Image Transformations for ${zone.name}.` });
+			} else if (step.id === "domain" && step.action === "add") {
+				await cf(
+					config,
+					`/accounts/${config.accountId}/r2/buckets/${bucket}/domains/custom`,
+					{ method: "POST", body: JSON.stringify({ domain: plan.host, zoneId: zone.id, enabled: true, minTLS: "1.2" }) },
+					"domain",
+				);
+				results.push({ id: step.id, ok: true, message: `Connected ${plan.host} to ${target.bucket}. Its certificate can take a few minutes.` });
+			} else if (step.id === "domain") {
+				await cf(
+					config,
+					`/accounts/${config.accountId}/r2/buckets/${bucket}/domains/custom/${encodeURIComponent(plan.host)}`,
+					{ method: "PUT", body: JSON.stringify({ enabled: true, minTLS: "1.2" }) },
+					"domain",
+				);
+				results.push({ id: step.id, ok: true, message: `Turned on ${plan.host} for ${target.bucket}.` });
+			} else if (step.id === "rules") {
+				await cf(
+					config,
+					`/zones/${zone.id}/rulesets/phases/http_request_transform/entrypoint`,
+					{ method: "PUT", body: JSON.stringify({ rules: plan.rules }) },
+					"rules",
+				);
+				results.push({ id: step.id, ok: true, message: `Saved the URL rewrite rules for ${plan.host}.` });
+			} else if (step.id === "tieredCache") {
+				await cf(config, `/zones/${zone.id}/cache/tiered_cache_smart_topology_enable`, { method: "PATCH", body: JSON.stringify({ value: "on" }) }, "tieredCache");
+				results.push({ id: step.id, ok: true, message: `Turned on Smart Tiered Cache for ${zone.name}.` });
+			}
+		} catch (error) {
+			results.push({ id: step.id, ok: false, message: error instanceof Error ? error.message : "Failed." });
+			break;
+		}
+	}
+	return { zone: zone.name, results };
+}
+
+// ── Live check of a media host ───────────────────────────────────
+
+export interface CheckItem {
+	id: "reachable" | "original" | "resize" | "cached";
+	ok: boolean;
+	label: string;
+	detail: string;
+}
+
+/** Pure: turn the two fetches' outcomes into check items (exported for tests). */
+export function checkItems(input: {
+	file: string;
+	original: { status: number; type: string } | { error: string };
+	resized: { status: number; type: string; cfResized: string | null; cache: string | null } | { error: string };
+}): CheckItem[] {
+	const items: CheckItem[] = [];
+	const o = input.original;
+	const r = input.resized;
+	const reached = !("error" in o) || !("error" in r);
+	items.push({
+		id: "reachable",
+		ok: reached,
+		label: "Host reachable",
+		detail: reached ? "The media host answered." : `Couldn't connect: ${"error" in o ? o.error : ""}. Check the custom domain on the bucket and its DNS.`,
+	});
+	const originalOk = !("error" in o) && o.status === 200 && o.type.startsWith("image/");
+	items.push({
+		id: "original",
+		ok: originalOk,
+		label: "Original served",
+		detail:
+			"error" in o
+				? "No answer."
+				: originalOk
+					? `${input.file} (${o.type}).`
+					: o.status === 404
+						? `${input.file} wasn't found (404). Is the custom domain on the bucket bound as MEDIA?`
+						: `Answered ${o.status}${o.type ? ` (${o.type})` : ""}.`,
+	});
+	const resizeOk = !("error" in r) && r.status === 200 && (Boolean(r.cfResized) || r.type.startsWith("image/"));
+	items.push({
+		id: "resize",
+		ok: resizeOk,
+		label: "Resize works",
+		detail:
+			"error" in r
+				? "No answer."
+				: resizeOk
+					? `/s/64x64/ answered ${r.type || "an image"}${r.cfResized ? " (resized by Cloudflare)" : ""}.`
+					: r.status === 404
+						? originalOk
+							? "/s/64x64/ wasn't found (404) from inside the Worker. A check from the Worker isn't conclusive for a media host on the site's own zone, so this alone doesn't mean the URL rewrite rules are missing: the Clean Image URLs page checks again from your browser."
+							: "/s/64x64/ wasn't found (404): the URL rewrite rules are missing, or don't match this host."
+						: `/s/64x64/ answered ${r.status}. Are Image Transformations on for the zone?`,
+	});
+	const cache = "error" in r ? null : (r.cache ?? "").toUpperCase();
+	const cached = cache === "HIT" || cache === "REVALIDATED" || cache === "STALE" || cache === "UPDATING";
+	items.push({
+		id: "cached",
+		ok: cached,
+		label: "Cached at the edge",
+		detail: cache ? `Second request: cf-cache-status ${cache}.` : "No cf-cache-status header (normal for the first few requests after setup).",
+	});
+	return items;
+}
+
+/** Fetch a file and a 64×64 copy from the media host (the copy twice, to see the cache). */
+export async function checkMediaHost(host: string, file: string, doFetch: Fetch = fetch): Promise<CheckItem[]> {
+	const accept = "image/avif,image/webp,image/*,*/*;q=0.8";
+	const get = async (url: string) => {
+		try {
+			const res = await doFetch(url, { headers: { Accept: accept }, redirect: "follow" });
+			await res.body?.cancel().catch(() => undefined);
+			return { status: res.status, type: (res.headers.get("content-type") ?? "").split(";")[0].trim(), cfResized: res.headers.get("cf-resized"), cache: res.headers.get("cf-cache-status") };
+		} catch (error) {
+			return { error: error instanceof Error ? error.message : "network error" };
+		}
+	};
+	const original = await get(`${host}/${file}`);
+	const first = await get(`${host}/s/64x64/${file}`);
+	const resized = "error" in first || first.status !== 200 ? first : await get(`${host}/s/64x64/${file}`);
+	return checkItems({ file, original, resized });
+}

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}`;
+}