@coywolf/emdash 0.0.0-stage → 0.35.13

package/src/redirects/removed.ts

@@ -0,0 +1,293 @@
+/**
+ * "Removed content" (feature "redirects.trashPrompt"): when a published entry
+ * is deleted or unpublished, record its former URL as a pending decision in
+ * plugin storage. The Redirects admin page lists them with Redirect to…,
+ * Return 410 Gone, and Dismiss; the admin also prompts right after a trash or
+ * unpublish (src/admin/trash-prompt.tsx). Republishing or restoring the entry
+ * clears it and undoes a rule its decision created.
+ */
+import type { PluginContext } from "emdash";
+import { PluginRouteError, definePluginRoute } from "emdash";
+import { z } from "zod";
+
+import { COLLECTION_SLUG, entryUrl, readCollections } from "../core/content-url.js";
+import { requireFeature } from "../core/features.js";
+import { REDIRECTS_TAG, purgePageCache } from "../pageCache/lib.js";
+import { parseInput, workerEnv } from "../shared.js";
+import { invalidateRedirectCache } from "./middleware.js";
+import {
+	type AppliedRule,
+	type EntrySnapshot,
+	type PendingDecision,
+	type RemovalReason,
+	appliedStillOurs,
+	buildPending,
+	idsByCollection,
+	pendingId,
+	snapshotFromContent,
+	shouldDropApplied,
+	snapshotFromRow,
+} from "./removed-core.js";
+import { RedirectValidationError, deleteRule, findExactRuleAny, getRule, saveRule } from "./rules.js";
+
+export const TRASH_PROMPT_FEATURE = "redirects.trashPrompt";
+const STORE = "redirects_removed";
+/** Rules created from decisions, so restoring or republishing the entry can undo them. */
+const APPLIED = "redirects_applied";
+
+export const removedStorage = { [STORE]: { indexes: ["at"] }, [APPLIED]: { indexes: ["at"] } };
+
+interface Options {
+	database?: string;
+}
+
+// biome-ignore lint/suspicious/noExplicitAny: plugin storage collections are untyped here.
+const store = (ctx: PluginContext) => (ctx.storage as Record<string, any>)[STORE] as {
+	get(id: string): Promise<PendingDecision | null>;
+	put(id: string, data: PendingDecision): Promise<void>;
+	delete(id: string): Promise<boolean>;
+	query(o: { orderBy?: Record<string, "asc" | "desc">; limit?: number }): Promise<{ items: Array<{ id: string; data: PendingDecision }> }>;
+};
+
+// biome-ignore lint/suspicious/noExplicitAny: plugin storage collections are untyped here.
+const applied = (ctx: PluginContext) => (ctx.storage as Record<string, any>)[APPLIED] as {
+	get(id: string): Promise<AppliedRule | null>;
+	put(id: string, data: AppliedRule): Promise<void>;
+	delete(id: string): Promise<boolean>;
+};
+
+/** A snapshot plus its former path, resolved while the row and its terms still exist. */
+interface Taken {
+	entry: EntrySnapshot;
+	urlPattern: string | null;
+	url: string | null;
+}
+
+/** Snapshots taken in content:beforeDelete, while the row still exists (a permanent delete removes it). */
+const beforeDelete = new Map<string, Taken>();
+
+export function removedModule(options: Options) {
+	async function db(): Promise<D1Database | undefined> {
+		try {
+			return (await workerEnv())[options.database ?? "DB"] as D1Database | undefined;
+		} catch {
+			return undefined;
+		}
+	}
+
+	async function snapshot(collection: string, id: string) {
+		const d1 = await db();
+		if (!d1 || !COLLECTION_SLUG.test(collection)) return null;
+		const info = (await readCollections(d1, [collection])).get(collection);
+		const row = await d1.prepare(`SELECT * FROM "ec_${collection}" WHERE id = ?`).bind(id).first<Record<string, unknown>>();
+		if (!row) return null;
+		const entry = snapshotFromRow(row, info?.titleField ?? null);
+		return { entry, urlPattern: info?.urlPattern ?? null, url: await formerUrl(d1, collection, entry) };
+	}
+
+	/** The entry's public path via the pack-wide resolver (honors the site's `urls` overrides). */
+	async function formerUrl(d1: D1Database, collection: string, entry: EntrySnapshot): Promise<string | null> {
+		if (!entry.slug) return null;
+		return entryUrl(d1, collection, { id: entry.id, slug: entry.slug, publishedAt: entry.publishedAt, locale: entry.locale }).catch(() => null);
+	}
+
+	async function record(ctx: PluginContext, collection: string, reason: RemovalReason, taken: Taken | null) {
+		if (!taken) return;
+		const pending = buildPending(collection, taken.entry, { url: taken.url, urlPattern: taken.urlPattern }, reason);
+		if (!pending) return;
+		const existing = await store(ctx).get(pending.id);
+		if (existing) return; // Keep the first record (e.g. trashed, then permanently deleted).
+		await store(ctx).put(pending.id, pending);
+		ctx.log.info("Removed content recorded", { url: pending.url, reason });
+	}
+
+	/**
+	 * The entry is back (restored, or republished): drop its pending decision,
+	 * and delete the rule its decision created while that rule is still ours
+	 * and, on publish, the entry is back at the same URL. A rule kept because
+	 * the entry came back at another URL stays remembered, so a later publish
+	 * back at the old URL still undoes it.
+	 */
+	async function comeBack(ctx: PluginContext, collection: string, content: Record<string, unknown>, reason: "restore" | "publish") {
+		const id = pendingId(collection, String(content.id));
+		await store(ctx).delete(id);
+		const done = await applied(ctx).get(id);
+		if (!done) return;
+		const d1 = await db();
+		if (!d1) return;
+		const rule = await getRule(d1, done.ruleId);
+		if (!appliedStillOurs(done, rule)) {
+			await applied(ctx).delete(id); // Edited, replaced, or deleted since: no longer ours to undo.
+			return;
+		}
+		let currentUrl: string | null = null;
+		if (reason === "publish") {
+			const info = (await readCollections(d1, [collection])).get(collection);
+			currentUrl = await formerUrl(d1, collection, snapshotFromContent(content, info?.titleField ?? null));
+		}
+		if (!shouldDropApplied(done, rule, currentUrl, reason)) return;
+		await applied(ctx).delete(id);
+		await deleteRule(d1, done.ruleId);
+		invalidateRedirectCache();
+		await purgePageCache({ tags: [REDIRECTS_TAG] });
+		ctx.log.info("Removed content rule undone", { url: done.url, reason });
+	}
+
+	/**
+	 * Ids of these pending entries that are live after all (published, not in
+	 * the trash): a trash that failed after it was recorded, or a decision
+	 * recorded for an entry that was brought back without the hooks firing.
+	 * One query per collection; a collection that can't be read counts as
+	 * not live.
+	 */
+	async function liveIds(d1: D1Database, items: PendingDecision[]): Promise<Set<string>> {
+		const live = new Set<string>();
+		for (const [collection, ids] of idsByCollection(items)) {
+			if (!COLLECTION_SLUG.test(collection)) continue;
+			try {
+				const { results } = await d1
+					.prepare(`SELECT id FROM "ec_${collection}" WHERE status = 'published' AND deleted_at IS NULL AND id IN (${ids.map(() => "?").join(", ")})`)
+					.bind(...ids)
+					.all<{ id: string }>();
+				for (const row of results) live.add(pendingId(collection, String(row.id)));
+			} catch {
+				// Collection gone or renamed: nothing there is live.
+			}
+		}
+		return live;
+	}
+
+	/** Forget pending decisions whose entries are live again; the rest, in order. */
+	async function dropLive(ctx: PluginContext, items: PendingDecision[]): Promise<PendingDecision[]> {
+		if (!items.length) return items;
+		const d1 = await db();
+		if (!d1) return items;
+		const live = await liveIds(d1, items);
+		if (!live.size) return items;
+		for (const id of live) await store(ctx).delete(id);
+		ctx.log.info("Removed content forgotten: entries are live", { ids: [...live] });
+		return items.filter((item) => !live.has(item.id));
+	}
+
+	const describeRule = (rule: { type: number; target: string; enabled: boolean }) =>
+		`${rule.type === 410 ? "410 Gone" : `${rule.type} → ${rule.target}`}${rule.enabled ? "" : ", disabled"}`;
+
+	const hooks = {
+		"content:beforeDelete": async (event: { id: string; collection: string }, ctx: PluginContext) => {
+			try {
+				const taken = await snapshot(event.collection, event.id);
+				if (beforeDelete.size > 500) beforeDelete.clear(); // Deletes that never completed.
+				if (taken) beforeDelete.set(pendingId(event.collection, event.id), taken);
+				// Record now, before the delete's response, so the admin's prompt finds it at once.
+				await record(ctx, event.collection, "deleted", taken);
+			} catch {
+				// Never block a delete.
+			}
+			return undefined;
+		},
+
+		"content:afterDelete": async (event: { id: string; collection: string; permanent: boolean }, ctx: PluginContext) => {
+			const key = pendingId(event.collection, event.id);
+			const taken = beforeDelete.get(key) ?? (await snapshot(event.collection, event.id));
+			beforeDelete.delete(key);
+			await record(ctx, event.collection, "deleted", taken);
+		},
+
+		"content:afterUnpublish": async (event: { content: Record<string, unknown>; collection: string }, ctx: PluginContext) => {
+			const d1 = await db();
+			const info = d1 ? (await readCollections(d1, [event.collection])).get(event.collection) : undefined;
+			const entry = snapshotFromContent(event.content, info?.titleField ?? null);
+			await record(ctx, event.collection, "unpublished", {
+				entry,
+				urlPattern: info?.urlPattern ?? null,
+				url: d1 ? await formerUrl(d1, event.collection, entry) : null,
+			});
+		},
+
+		"content:afterPublish": async (event: { content: Record<string, unknown>; collection: string }, ctx: PluginContext) => {
+			await comeBack(ctx, event.collection, event.content, "publish");
+		},
+
+		// Restored entries come back as drafts; restoring says the content is coming back, so drop the decision and its rule.
+		"content:afterRestore": async (event: { content: Record<string, unknown>; collection: string }, ctx: PluginContext) => {
+			await comeBack(ctx, event.collection, event.content, "restore");
+		},
+	};
+
+	const routes = {
+		"redirects/removed": {
+			permission: "plugins:manage" as const,
+			handler: async (ctx: PluginContext) => {
+				await requireFeature(ctx, TRASH_PROMPT_FEATURE);
+				const { items } = await store(ctx).query({ orderBy: { at: "desc" }, limit: 100 });
+				return {
+					items: await dropLive(
+						ctx,
+						items.map((i) => i.data),
+					),
+				};
+			},
+		},
+
+		"redirects/removed/resolve": definePluginRoute({
+			permission: "plugins:manage",
+			methods: ["POST"],
+			request: { body: "json" },
+			handler: async (ctx) => {
+				await requireFeature(ctx, TRASH_PROMPT_FEATURE);
+				const input = parseInput(
+					z.object({
+						id: z.string().max(300),
+						action: z.enum(["redirect", "gone", "dismiss"]),
+						target: z.string().max(2000).optional(),
+						type: z.number().int().optional(),
+					}),
+					ctx.input,
+				);
+				const pending = await store(ctx).get(input.id);
+				if (!pending) throw PluginRouteError.notFound("That removed entry is no longer pending.");
+				let rule = null;
+				if (input.action !== "dismiss") {
+					const d1 = await db();
+					if (!d1) throw PluginRouteError.badRequest("Redirects: missing database binding.");
+					if (!(await dropLive(ctx, [pending])).length) {
+						throw PluginRouteError.conflict(`“${pending.title}” is live again at ${pending.url}; there is nothing to redirect.`);
+					}
+					// Never overwrite a rule someone made for this path (and never adopt it: a restore would delete it).
+					const existing = await findExactRuleAny(d1, pending.url);
+					if (existing) {
+						throw PluginRouteError.conflict(
+							`A redirect already exists for ${existing.source} (${describeRule(existing)}). Keep it and dismiss this entry under Redirects → Removed content, or change it under Redirects.`,
+						);
+					}
+					try {
+						rule = await saveRule(d1, {
+							source: pending.url,
+							target: input.action === "gone" ? "" : input.target,
+							type: input.action === "gone" ? 410 : (input.type ?? 301),
+							note: `Removed: ${pending.title}`.slice(0, 500),
+						});
+					} catch (error) {
+						if (error instanceof RedirectValidationError) throw PluginRouteError.badRequest(error.message);
+						throw error;
+					}
+					invalidateRedirectCache();
+					await applied(ctx).put(pending.id, {
+						id: pending.id,
+						collection: pending.collection,
+						entryId: pending.entryId,
+						url: pending.url,
+						ruleId: rule.id,
+						action: input.action,
+						at: new Date().toISOString(),
+					});
+				}
+				await store(ctx).delete(pending.id);
+				ctx.log.info("Removed content resolved", { url: pending.url, action: input.action });
+				return { resolved: pending.id, rule };
+			},
+		}),
+	};
+
+	return { hooks, routes, storage: removedStorage };
+}

package/src/redirects/rules.ts

@@ -0,0 +1,355 @@
+/**
+ * Redirect rules: storage (a table in the site's D1 database, so backups and
+ * rewinds include it), validation, and matching. Shared by the plugin routes
+ * and the site middleware.
+ *
+ * Complements EmDash's built-in redirects, which only accept site-relative
+ * destinations and skip any path with a file extension.
+ */
+
+import { batchedAll } from "../core/d1-batch.js";
+
+export const REDIRECT_TYPES = [301, 302, 307, 308, 410] as const;
+export type RedirectType = (typeof REDIRECT_TYPES)[number];
+
+export interface RedirectRule {
+	id: string;
+	source: string;
+	target: string;
+	type: RedirectType;
+	isRegex: boolean;
+	enabled: boolean;
+	hits: number;
+	lastHit: string | null;
+	note: string | null;
+	createdAt: string;
+	updatedAt: string;
+}
+
+export interface RedirectInput {
+	source: string;
+	target?: string;
+	type?: number;
+	isRegex?: boolean;
+	enabled?: boolean;
+	note?: string | null;
+}
+
+const TABLE = "coywolf_redirects";
+
+const SCHEMA = [
+	`CREATE TABLE IF NOT EXISTS ${TABLE} (
+		id TEXT PRIMARY KEY,
+		source TEXT NOT NULL,
+		target TEXT NOT NULL DEFAULT '',
+		type INTEGER NOT NULL DEFAULT 301,
+		is_regex INTEGER NOT NULL DEFAULT 0,
+		enabled INTEGER NOT NULL DEFAULT 1,
+		hits INTEGER NOT NULL DEFAULT 0,
+		last_hit TEXT,
+		note TEXT,
+		created_at TEXT NOT NULL,
+		updated_at TEXT NOT NULL
+	)`,
+	`CREATE UNIQUE INDEX IF NOT EXISTS ${TABLE}_source ON ${TABLE} (source, is_regex)`,
+	// The site middleware reads the (few) pattern rules without scanning the exact ones.
+	`CREATE INDEX IF NOT EXISTS ${TABLE}_patterns ON ${TABLE} (source) WHERE is_regex = 1`,
+];
+
+export async function ensureTable(db: D1Database): Promise<void> {
+	await db.batch(SCHEMA.map((sql) => db.prepare(sql)));
+}
+
+interface Row {
+	id: string;
+	source: string;
+	target: string;
+	type: number;
+	is_regex: number;
+	enabled: number;
+	hits: number;
+	last_hit: string | null;
+	note: string | null;
+	created_at: string;
+	updated_at: string;
+}
+
+const toRule = (r: Row): RedirectRule => ({
+	id: r.id,
+	source: r.source,
+	target: r.target,
+	type: r.type as RedirectType,
+	isRegex: r.is_regex === 1,
+	enabled: r.enabled === 1,
+	hits: r.hits,
+	lastHit: r.last_hit,
+	note: r.note,
+	createdAt: r.created_at,
+	updatedAt: r.updated_at,
+});
+
+/** Exact sources match with or without a trailing slash, so store them without one. */
+export function normalizePath(path: string): string {
+	return path.length > 1 ? path.replace(/\/+$/, "") : path;
+}
+
+export class RedirectValidationError extends Error {}
+
+/** Validate and normalize a rule; throws RedirectValidationError with a readable message. */
+export function validate(input: RedirectInput): Omit<RedirectInput, "type"> & { type: RedirectType; target: string } {
+	const source = (input.source ?? "").trim();
+	const target = (input.target ?? "").trim();
+	const type = (input.type ?? 301) as RedirectType;
+	const isRegex = input.isRegex === true;
+
+	if (!REDIRECT_TYPES.includes(type)) throw new RedirectValidationError(`Type must be one of ${REDIRECT_TYPES.join(", ")}.`);
+	if (isRegex) {
+		if (!source) throw new RedirectValidationError("Enter a pattern.");
+		try {
+			new RegExp(source);
+		} catch (error) {
+			throw new RedirectValidationError(`Invalid pattern: ${(error as Error).message}`);
+		}
+	} else if (!source.startsWith("/") || source.startsWith("//")) {
+		throw new RedirectValidationError("The source must be a path starting with /.");
+	}
+	if (type !== 410) {
+		if (!target) throw new RedirectValidationError("Enter a destination.");
+		const sitePath = target.startsWith("/") && !target.startsWith("//");
+		if (!sitePath && !/^https?:\/\/[^\s]+$/i.test(target)) {
+			throw new RedirectValidationError("The destination must be a path starting with / or an http(s) URL.");
+		}
+		if (!isRegex && sitePath && normalizePath(target.split("?")[0]) === normalizePath(source)) {
+			throw new RedirectValidationError("A redirect can't point to itself.");
+		}
+	}
+	return {
+		source: isRegex ? source : normalizePath(source),
+		target: type === 410 ? "" : target,
+		type,
+		isRegex,
+		enabled: input.enabled !== false,
+		note: input.note?.trim() || null,
+	};
+}
+
+/** The table is created once per isolate; concurrent first callers share the one batch. */
+let tableReady: Promise<void> | null = null;
+
+function ensureTableOnce(db: D1Database): Promise<void> {
+	tableReady ??= ensureTable(db).catch((error) => {
+		tableReady = null;
+		throw error;
+	});
+	return tableReady;
+}
+
+export async function listRules(db: D1Database): Promise<RedirectRule[]> {
+	await ensureTableOnce(db);
+	const read = () => db.prepare(`SELECT * FROM ${TABLE} ORDER BY is_regex, source`).all<Row>();
+	let results: Row[];
+	try {
+		({ results } = await read());
+	} catch (error) {
+		// A restore can drop the table after this isolate created it; recreate and retry once.
+		if (!isMissingTable(error)) throw error;
+		tableReady = null;
+		await ensureTableOnce(db);
+		({ results } = await read());
+	}
+	return results.map(toRule);
+}
+
+const isMissingTable = (error: unknown) => /no such table/i.test(String((error as Error)?.message ?? error));
+
+type MatchRow = Pick<Row, "id" | "source" | "target" | "type" | "is_regex">;
+
+/**
+ * Enabled rules, only the columns matching needs, for the site middleware.
+ * Never writes: the table is created by admin writes (saveRule, listRules);
+ * until then there are no rules. Read with the pack's other reads of this
+ * tick, in one D1 batch.
+ */
+async function readMatchRules(db: D1Database, statement: D1PreparedStatement): Promise<RedirectRule[]> {
+	let results: MatchRow[];
+	try {
+		results = await batchedAll<MatchRow>(db, statement);
+	} catch (error) {
+		if (isMissingTable(error)) return [];
+		throw error;
+	}
+	return results.map((r) => ({
+		id: r.id,
+		source: r.source,
+		target: r.target,
+		type: r.type as RedirectType,
+		isRegex: r.is_regex === 1,
+		enabled: true,
+		hits: 0,
+		lastHit: null,
+		note: null,
+		createdAt: "",
+		updatedAt: "",
+	}));
+}
+
+const MATCH_COLUMNS = "id, source, target, type, is_regex";
+
+/** The enabled exact rule for a request path, if any: one row through the (source, is_regex) index. */
+export async function findExactRule(db: D1Database, pathname: string): Promise<RedirectRule | null> {
+	const statement = db
+		.prepare(`SELECT ${MATCH_COLUMNS} FROM ${TABLE} WHERE source = ? AND is_regex = 0 AND enabled = 1`)
+		.bind(normalizePath(pathname));
+	return (await readMatchRules(db, statement))[0] ?? null;
+}
+
+/** The enabled pattern rules, in source order (the order they're tried); read through the patterns index. */
+export function loadPatternRules(db: D1Database): Promise<RedirectRule[]> {
+	return readMatchRules(db, db.prepare(`SELECT ${MATCH_COLUMNS} FROM ${TABLE} WHERE is_regex = 1 AND enabled = 1 ORDER BY source`));
+}
+
+/** Create or update (by id, or by source when importing). Returns the saved rule. */
+export async function saveRule(db: D1Database, input: RedirectInput & { id?: string }): Promise<RedirectRule> {
+	await ensureTable(db);
+	const rule = validate(input);
+	const now = new Date().toISOString();
+	const existing = input.id
+		? await db.prepare(`SELECT id FROM ${TABLE} WHERE id = ?`).bind(input.id).first<{ id: string }>()
+		: await db
+				.prepare(`SELECT id FROM ${TABLE} WHERE source = ? AND is_regex = ?`)
+				.bind(rule.source, rule.isRegex ? 1 : 0)
+				.first<{ id: string }>();
+	const id = existing?.id ?? input.id ?? crypto.randomUUID();
+	if (existing) {
+		await db
+			.prepare(
+				`UPDATE ${TABLE} SET source = ?, target = ?, type = ?, is_regex = ?, enabled = ?, note = ?, updated_at = ? WHERE id = ?`,
+			)
+			.bind(rule.source, rule.target, rule.type, rule.isRegex ? 1 : 0, rule.enabled ? 1 : 0, rule.note, now, id)
+			.run();
+	} else {
+		await db
+			.prepare(
+				`INSERT INTO ${TABLE} (id, source, target, type, is_regex, enabled, note, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+			)
+			.bind(id, rule.source, rule.target, rule.type, rule.isRegex ? 1 : 0, rule.enabled ? 1 : 0, rule.note, now, now)
+			.run();
+	}
+	const saved = await db.prepare(`SELECT * FROM ${TABLE} WHERE id = ?`).bind(id).first<Row>();
+	return toRule(saved!);
+}
+
+/** One rule by id, or null (also when the table doesn't exist yet). */
+export async function getRule(db: D1Database, id: string): Promise<RedirectRule | null> {
+	try {
+		const row = await db.prepare(`SELECT * FROM ${TABLE} WHERE id = ?`).bind(id).first<Row>();
+		return row ? toRule(row) : null;
+	} catch (error) {
+		if (isMissingTable(error)) return null;
+		throw error;
+	}
+}
+
+/** The exact (non-pattern) rule for a path, enabled or not, or null (also when the table doesn't exist yet). */
+export async function findExactRuleAny(db: D1Database, pathname: string): Promise<RedirectRule | null> {
+	try {
+		const row = await db.prepare(`SELECT * FROM ${TABLE} WHERE source = ? AND is_regex = 0`).bind(normalizePath(pathname)).first<Row>();
+		return row ? toRule(row) : null;
+	} catch (error) {
+		if (isMissingTable(error)) return null;
+		throw error;
+	}
+}
+
+export async function deleteRule(db: D1Database, id: string): Promise<boolean> {
+	await ensureTable(db);
+	const result = await db.prepare(`DELETE FROM ${TABLE} WHERE id = ?`).bind(id).run();
+	return result.meta.changes > 0;
+}
+
+// ─── Matching ───────────────────────────────────────────────────────────────
+
+export interface CompiledRules {
+	exact: Map<string, RedirectRule>;
+	patterns: Array<{ rule: RedirectRule; regex: RegExp }>;
+}
+
+export function compile(rules: RedirectRule[]): CompiledRules {
+	const exact = new Map<string, RedirectRule>();
+	const patterns: CompiledRules["patterns"] = [];
+	for (const rule of rules) {
+		if (!rule.enabled) continue;
+		if (rule.isRegex) {
+			try {
+				patterns.push({ rule, regex: new RegExp(rule.source) });
+			} catch {
+				// Saved rules are validated; skip anything unparseable rather than fail every request.
+			}
+		} else {
+			exact.set(rule.source, rule);
+		}
+	}
+	return { exact, patterns };
+}
+
+const isSitePath = (target: string): boolean => target.startsWith("/") && !target.startsWith("//");
+
+/**
+ * A capture group must not move a redirect to another site. A site-relative
+ * target collapses leading slashes after substitution (in match), so "/$1" with
+ * "/evil.com" stays "/evil.com" rather than becoming "//evil.com". An absolute
+ * target whose host is written out must keep that host, so "https://example.com$1"
+ * can't become "https://example.com.evil.com/".
+ */
+function keepsHost(target: string, location: string): boolean {
+	// The written-out part of the host: up to the first path, query, fragment, or capture.
+	const authority = /^https?:\/\/[^/?#$]*/i.exec(target)?.[0];
+	// A host that is (or starts with) a capture, like "https://$1/", is the site owner's choice.
+	if (!authority || !authority.slice(authority.indexOf("//") + 2).includes(".")) return true;
+	try {
+		const fixed = new URL(authority);
+		const result = new URL(location);
+		return result.protocol === fixed.protocol && result.host === fixed.host;
+	} catch {
+		return false;
+	}
+}
+
+export interface Match {
+	rule: RedirectRule;
+	/** Absolute or site-relative URL; empty for 410. */
+	location: string;
+}
+
+/**
+ * Find the rule for a request path. Exact rules win over patterns; patterns are
+ * tried in source order. `$1`…`$9` in a pattern's target are replaced with its
+ * capture groups. The request's query string is kept unless the target has one.
+ */
+export function match(compiled: CompiledRules, pathname: string, search: string): Match | null {
+	let rule = compiled.exact.get(normalizePath(pathname));
+	let location = rule?.target ?? "";
+	if (!rule) {
+		for (const candidate of compiled.patterns) {
+			const m = pathname.match(candidate.regex);
+			if (!m) continue;
+			rule = candidate.rule;
+			location = rule.target.replace(/\$(\d)/g, (_, n: string) => m[Number(n)] ?? "");
+			break;
+		}
+		if (rule && rule.type !== 410) {
+			if (isSitePath(rule.target)) location = location.replace(/^[/\\]+/, "/");
+			else if (!keepsHost(rule.target, location)) return null;
+		}
+	}
+	if (!rule) return null;
+	if (rule.type !== 410 && search && !location.includes("?")) location += search;
+	return { rule, location };
+}
+
+export async function recordHit(db: D1Database, id: string): Promise<void> {
+	await db
+		.prepare(`UPDATE ${TABLE} SET hits = hits + 1, last_hit = ? WHERE id = ?`)
+		.bind(new Date().toISOString(), id)
+		.run();
+}