@coywolf/emdash 0.0.0-stage → 0.35.14

package/src/backups/dump.ts

@@ -0,0 +1,288 @@
+/**
+ * Restorable SQL dump of a D1 database, built from inside the Worker.
+ *
+ * Same output order as scripts/backup/d1-backup.sh, so either kind of dump
+ * restores with scripts/backup/d1-restore.sh:
+ *
+ *   1. CREATE TABLE for every regular table
+ *   2. FTS5 search tables and the triggers that maintain them
+ *   3. INSERT rows, one statement per line (the search triggers re-index
+ *      content rows as they load)
+ *   4. indexes and the remaining triggers
+ *
+ * FTS5 shadow tables are skipped: SQLite recreates them with the virtual table.
+ *
+ * D1 rejects any statement over 100 KB (SQLITE_TOOBIG), but the site writes
+ * rows with bound parameters, so a long post can be bigger than that. A row
+ * whose INSERT would be too long is written with its long text values cut
+ * short, followed by UPDATEs that append the rest in pieces under the limit.
+ */
+
+interface MasterRow {
+	type: string;
+	name: string;
+	tbl_name: string;
+	sql: string | null;
+}
+
+const PAGE_SIZE = 500;
+/**
+ * About how much a read of rows should return. D1 refuses query results over 50 MB (from
+ * November 4, 2026); 500 rows of a table with very large rows (long posts, revisions) could
+ * pass that, so each read is sized from the bytes the previous one returned.
+ */
+export const PAGE_TARGET_BYTES = 8 * 1024 * 1024;
+/** How D1 words a result over its size limit (its message has said "too large", "exceeds" or "limit" with a size). */
+const RESULT_TOO_LARGE = /too large|too big|exceed|size limit|limit.*(bytes|MB)|SQLITE_TOOBIG/i;
+
+/** Rows to ask for next, from the size of the rows just read. */
+export function nextPageSize(pageBytes: number, rows: number): number {
+	if (rows <= 0) return PAGE_SIZE;
+	const perRow = Math.max(1, pageBytes / rows);
+	return Math.max(1, Math.min(PAGE_SIZE, Math.floor(PAGE_TARGET_BYTES / perRow)));
+}
+const SEARCH_PREFIX = "_emdash_fts_";
+/** Longest statement written, in UTF-8 bytes; D1's limit is 100,000. */
+export const MAX_STATEMENT_BYTES = 90_000;
+/** Most UTF-8 bytes of escaped text per piece of a split value. */
+const PIECE_BYTES = 60_000;
+/** In a row too long for one INSERT, text values longer than this are appended separately. */
+const SHORT_BYTES = 2_000;
+/**
+ * Line breaks are written as '||char(10)||', two operators each, and SQLite
+ * refuses expressions deeper than 1,000: at most this many per statement.
+ */
+const MAX_BREAKS = 400;
+const breaks = (s: string) => s.match(/[\r\n]/g)?.length ?? 0;
+/** Option rows that the plugin rebuilds on demand; not worth backing up. */
+const SKIP_OPTION = /^plugin:coywolf-pack:cache:/;
+
+function isInternal(name: string): boolean {
+	return name.startsWith("sqlite_") || name.startsWith("_cf_");
+}
+
+function quoteIdent(name: string): string {
+	return `"${name.replace(/"/g, '""')}"`;
+}
+
+/** SQL literal for a D1 value, keeping every statement on one line (like sqlite3 .dump). */
+export function sqlLiteral(value: unknown): string {
+	if (value === null || value === undefined) return "NULL";
+	if (typeof value === "number") return Number.isFinite(value) ? String(value) : "NULL";
+	if (typeof value === "bigint") return value.toString();
+	if (typeof value === "boolean") return value ? "1" : "0";
+	if (value instanceof ArrayBuffer || ArrayBuffer.isView(value) || Array.isArray(value)) {
+		const bytes =
+			value instanceof ArrayBuffer
+				? new Uint8Array(value)
+				: Array.isArray(value)
+					? Uint8Array.from(value as number[])
+					: new Uint8Array((value as ArrayBufferView).buffer, (value as ArrayBufferView).byteOffset, (value as ArrayBufferView).byteLength);
+		let hex = "";
+		for (const b of bytes) hex += b.toString(16).padStart(2, "0");
+		return `X'${hex}'`;
+	}
+	// Newlines become ||char(10)|| so each INSERT stays on one line.
+	return `'${escapeText(String(value))}'`;
+}
+
+function escapeText(text: string): string {
+	return text.replace(/'/g, "''").replace(/\r/g, "'||char(13)||'").replace(/\n/g, "'||char(10)||'");
+}
+
+const utf8 = new TextEncoder();
+const bytes = (s: string) => utf8.encode(s).length;
+
+/** Split text into pieces whose escaped form stays under PIECE_BYTES (never inside a surrogate pair). */
+export function splitText(text: string): string[] {
+	const pieces: string[] = [];
+	let start = 0;
+	let size = 0;
+	let lines = 0;
+	for (let i = 0; i < text.length; i++) {
+		const code = text.charCodeAt(i);
+		const pair = code >= 0xd800 && code <= 0xdbff && i + 1 < text.length;
+		const char = pair ? text.slice(i, i + 2) : text[i];
+		const cost = bytes(escapeText(char));
+		const isBreak = char === "\n" || char === "\r";
+		if ((size + cost > PIECE_BYTES || (isBreak && lines >= MAX_BREAKS)) && i > start) {
+			pieces.push(text.slice(start, i));
+			start = i;
+			size = 0;
+			lines = 0;
+		}
+		size += cost;
+		if (isBreak) lines++;
+		if (pair) i++;
+	}
+	pieces.push(text.slice(start));
+	return pieces;
+}
+
+/**
+ * One row as statements: a single INSERT when it fits, otherwise an INSERT
+ * with each long text value's first piece, then UPDATEs appending the rest.
+ * `key` names the columns that identify the row (primary key, or rowid).
+ */
+export function rowStatements(table: string, row: Record<string, unknown>, key: Record<string, unknown>): string[] {
+	const columns = Object.keys(row).filter((c) => c !== ROWID);
+	const insert = (values: Record<string, unknown>) =>
+		`INSERT INTO ${table} (${columns.map(quoteIdent).join(",")}) VALUES(${columns.map((c) => sqlLiteral(values[c])).join(",")});`;
+	const whole = insert(row);
+	const lineCount = columns.reduce((n, c) => n + (typeof row[c] === "string" ? breaks(row[c] as string) : 0), 0);
+	if (bytes(whole) <= MAX_STATEMENT_BYTES && lineCount <= MAX_BREAKS) return [whole];
+
+	// Long text values start empty and are appended piece by piece, so the
+	// INSERT holds only short values however many long columns the row has.
+	const first: Record<string, unknown> = { ...row };
+	const rest: Array<[string, string]> = [];
+	for (const c of columns) {
+		const value = row[c];
+		if (typeof value !== "string" || (bytes(sqlLiteral(value)) <= SHORT_BYTES && breaks(value) <= 20)) continue;
+		first[c] = "";
+		for (const piece of splitText(value)) rest.push([c, piece]);
+	}
+	const where = Object.entries(key)
+		.map(([c, v]) => `${c === ROWID ? "rowid" : quoteIdent(c)}=${sqlLiteral(v)}`)
+		.join(" AND ");
+	return [
+		insert(first),
+		...rest.map(([c, piece]) => `UPDATE ${table} SET ${quoteIdent(c)}=${quoteIdent(c)}||${sqlLiteral(piece)} WHERE ${where};`),
+	];
+}
+
+/** Alias for rowid in dump queries of tables without a primary key. */
+const ROWID = "__coywolf_rowid";
+
+/**
+ * Parents before children. D1 may apply a large import in several batches, so
+ * PRAGMA defer_foreign_keys can't be relied on to cover forward references.
+ */
+async function orderByForeignKeys(db: D1Database, tables: MasterRow[]): Promise<MasterRow[]> {
+	const names = new Set(tables.map((t) => t.name));
+	const parents = new Map<string, Set<string>>();
+	for (const t of tables) {
+		const { results } = await db.prepare(`PRAGMA foreign_key_list(${quoteIdent(t.name)})`).all<{ table: string }>();
+		parents.set(t.name, new Set(results.map((r) => r.table).filter((p) => p !== t.name && names.has(p))));
+	}
+	const ordered: MasterRow[] = [];
+	const done = new Set<string>();
+	const visiting = new Set<string>();
+	const byName = new Map(tables.map((t) => [t.name, t]));
+	const visit = (name: string) => {
+		if (done.has(name) || visiting.has(name)) return; // a cycle falls back to name order
+		visiting.add(name);
+		for (const parent of parents.get(name) ?? []) visit(parent);
+		visiting.delete(name);
+		done.add(name);
+		ordered.push(byName.get(name)!);
+	};
+	for (const t of tables) visit(t.name);
+	return ordered;
+}
+
+export interface DumpResult {
+	sql: string;
+	tables: number;
+	rows: number;
+}
+
+/** The whole dump as one string (tests, small databases). Backups stream dumpLines instead. */
+export async function dumpDatabase(db: D1Database): Promise<DumpResult> {
+	const counts = { tables: 0, rows: 0 };
+	const out: string[] = [];
+	for await (const line of dumpLines(db, counts)) out.push(line);
+	return { sql: `${out.join("\n")}\n`, ...counts };
+}
+
+/** Columns that, when a table declares them, hide the real rowid from `rowid` in queries. */
+const ROWID_NAMES = new Set(["rowid", "_rowid_", "oid"]);
+
+/**
+ * The dump, one statement per item (no trailing newline), read a page of rows
+ * at a time so memory stays bounded however big the database is. `counts` is
+ * filled in as it goes (complete once the iteration ends). Tables with a
+ * rowid are paged by rowid (`WHERE rowid > ?`), which stays fast on big
+ * tables where OFFSET rescans every earlier row; WITHOUT ROWID tables use OFFSET.
+ */
+export async function* dumpLines(db: D1Database, counts: { tables: number; rows: number } = { tables: 0, rows: 0 }): AsyncGenerator<string> {
+	const { results: master } = await db
+		.prepare("SELECT type, name, tbl_name, sql FROM sqlite_master WHERE sql IS NOT NULL ORDER BY name")
+		.all<MasterRow>();
+
+	const isSearch = (row: MasterRow) =>
+		row.name.startsWith(SEARCH_PREFIX) || row.tbl_name.startsWith(SEARCH_PREFIX) || (row.sql ?? "").includes(SEARCH_PREFIX);
+
+	const tables = master.filter((r) => r.type === "table" && !isInternal(r.name) && !r.name.startsWith(SEARCH_PREFIX));
+	const searchTables = master.filter(
+		(r) => r.type === "table" && r.name.startsWith(SEARCH_PREFIX) && /^CREATE VIRTUAL TABLE/i.test(r.sql ?? ""),
+	);
+	const searchTriggers = master.filter((r) => r.type === "trigger" && r.name.startsWith(SEARCH_PREFIX));
+	const indexes = master.filter((r) => r.type === "index" && !isInternal(r.name) && !isSearch(r));
+	const triggers = master.filter((r) => r.type === "trigger" && !isSearch(r));
+
+	const ordered = await orderByForeignKeys(db, tables);
+
+	const statement = (sql: string) => `${sql.trim().replace(/;$/, "")};`;
+	counts.tables = tables.length;
+	yield "PRAGMA defer_foreign_keys=TRUE;";
+
+	for (const t of tables) yield statement((t.sql ?? "").replace(/^CREATE TABLE /i, "CREATE TABLE IF NOT EXISTS "));
+	for (const t of searchTables) yield statement(t.sql ?? "");
+	for (const t of searchTriggers) yield statement(t.sql ?? "");
+
+	for (const t of ordered) {
+		const table = quoteIdent(t.name);
+		const { results: info } = await db.prepare(`PRAGMA table_info(${table})`).all<{ name: string; pk: number }>();
+		const withRowid = !/WITHOUT\s+ROWID/i.test(t.sql ?? "");
+		// A column named rowid (or oid) shadows the real one: page that table by OFFSET.
+		const byRowid = withRowid && !info.some((c) => ROWID_NAMES.has(c.name.toLowerCase()));
+		const pk = info.filter((c) => c.pk > 0).map((c) => c.name);
+		// Rows are identified by primary key for split values; tables without one by rowid.
+		const keyColumns = pk.length || !withRowid ? pk : [ROWID];
+		// The rowid alias is never written out (rowStatements skips it); it's the paging cursor.
+		const select = byRowid || (withRowid && !pk.length) ? `rowid AS ${ROWID}, *` : "*";
+		const order = withRowid ? " ORDER BY rowid" : "";
+		let after: unknown = null;
+		let offset = 0;
+		let limit = PAGE_SIZE;
+		for (;;) {
+			let results: Record<string, unknown>[];
+			try {
+				({ results } = byRowid
+					? await db
+							.prepare(`SELECT ${select} FROM ${table}${after === null ? "" : ` WHERE rowid > ?`}${order} LIMIT ?`)
+							.bind(...(after === null ? [limit] : [after, limit]))
+							.all<Record<string, unknown>>()
+					: await db
+							.prepare(`SELECT ${select} FROM ${table}${order} LIMIT ? OFFSET ?`)
+							.bind(limit, offset)
+							.all<Record<string, unknown>>());
+			} catch (error) {
+				// D1 refuses results over 50 MB (from November 4, 2026). Ask again for fewer rows, down to one.
+				// Any other error (an outage, a bad query) goes straight up instead of being retried.
+				if (limit === 1 || !RESULT_TOO_LARGE.test(String(error))) throw error;
+				limit = Math.max(1, Math.floor(limit / 4));
+				continue;
+			}
+			let pageBytes = 0;
+			for (const row of results) {
+				if (t.name === "options" && typeof row.name === "string" && SKIP_OPTION.test(row.name)) continue;
+				const key = Object.fromEntries(keyColumns.map((c) => [c, row[c]]));
+				for (const sql of rowStatements(table, row, key)) {
+					pageBytes += sql.length;
+					yield sql;
+				}
+				counts.rows++;
+			}
+			if (results.length < limit) break;
+			offset += results.length;
+			if (byRowid) after = results[results.length - 1][ROWID];
+			// Size the next read from this one: about PAGE_TARGET_BYTES, never more than PAGE_SIZE rows.
+			limit = nextPageSize(pageBytes, results.length);
+		}
+	}
+
+	for (const i of indexes) yield statement(i.sql ?? "");
+	for (const t of triggers) yield statement(t.sql ?? "");
+}

package/src/backups/module.ts

@@ -0,0 +1,276 @@
+/**
+ * Backups module: D1 dumps + R2 media mirror, with rewind (D1 Time Travel),
+ * undo, restore to a new database, and missing-media restore.
+ */
+import { PluginRouteError, definePluginRoute } from "emdash";
+import { z } from "zod";
+
+import { type CronScheduler, type SettingsReader, parseInput, secret, workerEnv } from "../shared.js";
+import { createDownloadLink } from "./download.js";
+import { dumpLines } from "./dump.js";
+import {
+	type RestoreConfig,
+	currentBookmark,
+	getUndo,
+	restoreMissingMedia,
+	restoreToNewDatabase,
+	rewind,
+	undoRewind,
+} from "./restore.js";
+import { FILE, type Manifest, STAMP, listBackups, makeStamp, mirrorBucket, mirrorMedia, pruneBackups, writeDumpStream, writeManifest } from "./store.js";
+
+export interface BackupsOptions {
+	/** D1 binding of the site database. Default "DB". */
+	database?: string;
+	/** R2 binding of the media bucket. Default "MEDIA". */
+	media?: string;
+	/** R2 binding of the backup bucket (use a separate, private bucket). Default "BACKUPS". */
+	backups?: string;
+	/**
+	 * R2 binding of the private form uploads bucket (Coywolf Pack → Private form
+	 * uploads), mirrored to uploads/ in the backup bucket. Default "FORM_UPLOADS";
+	 * skipped when the site has no such binding. false leaves uploads out.
+	 */
+	uploads?: string | false;
+	/** Dump file name prefix (e.g. "mysite" -> mysite.sql.gz). Default "database". */
+	name?: string;
+	/**
+	 * Restore via the Cloudflare API: the account and D1 database IDs, plus a
+	 * Worker secret with an API token (Account → D1 → Edit). These live outside
+	 * the database on purpose: a rewind rolls back plugin settings too.
+	 */
+	restore?: { accountId: string; databaseId: string; tokenSecret?: string };
+}
+
+/**
+ * Schedule and retention, edited on the Backups page. Not in the plugin's
+ * settingsSchema (that holds secrets only), so every read supplies its default.
+ */
+export const BACKUPS_DEFAULTS = { scheduled: false, retentionDays: 30, staleAfterHours: 36 } as const;
+
+const backupsSettingsInput = z.object({
+	scheduled: z.boolean(),
+	retentionDays: z.number().int().min(1, "Keep backups for at least 1 day.").max(365, "Keep backups for at most 365 days."),
+	staleAfterHours: z.number().int().min(1, "Warn after at least 1 hour.").max(720, "Warn after at most 720 hours (30 days)."),
+});
+
+async function settings(ctx: SettingsReader) {
+	return {
+		scheduled: (await ctx.settings.get<boolean>("backupsScheduled")) ?? BACKUPS_DEFAULTS.scheduled,
+		retentionDays: (await ctx.settings.get<number>("backupsRetentionDays")) ?? BACKUPS_DEFAULTS.retentionDays,
+		staleAfterHours: (await ctx.settings.get<number>("backupsStaleAfterHours")) ?? BACKUPS_DEFAULTS.staleAfterHours,
+	};
+}
+
+/** Daily task for scheduled backups and retention. schedule() is an upsert, so it's safe to repeat. */
+export const BACKUPS_TASK = "backups-daily";
+export async function ensureBackupsTask(ctx: CronScheduler) {
+	await ctx.cron?.schedule(BACKUPS_TASK, { schedule: "@daily" });
+}
+
+const confirmed = (word: string) => z.literal(word, { message: `Type ${word} to confirm.` });
+
+export function backupsModule(options: BackupsOptions) {
+	const name = options.name ?? "database";
+
+	async function bindings() {
+		const env = await workerEnv();
+		const db = env[options.database ?? "DB"] as D1Database | undefined;
+		const media = env[options.media ?? "MEDIA"] as R2Bucket | undefined;
+		const backups = env[options.backups ?? "BACKUPS"] as R2Bucket | undefined;
+		const uploads = options.uploads === false ? undefined : (env[options.uploads ?? "FORM_UPLOADS"] as R2Bucket | undefined);
+		const missing = [!db && "database", !media && "media", !backups && "backups"].filter(Boolean);
+		if (missing.length) throw PluginRouteError.badRequest(`Backups: missing ${missing.join(", ")} binding (see README).`);
+		const tokenName = options.restore?.tokenSecret ?? "BACKUPS_API_TOKEN";
+		const token = secret(env, tokenName);
+		const restore: RestoreConfig | null =
+			options.restore && token ? { token, accountId: options.restore.accountId, databaseId: options.restore.databaseId } : null;
+		const restoreStatus = restore
+			? { enabled: true as const }
+			: {
+					enabled: false as const,
+					reason: options.restore
+						? `Set the ${tokenName} Worker secret to an API token with D1 Edit permission.`
+						: "Add the backups.restore option (accountId, databaseId) in astro.config.mjs.",
+				};
+		return { db: db!, media: media!, backups: backups!, uploads, restore, restoreStatus };
+	}
+
+	async function readDump(backups: R2Bucket, stamp: string): Promise<{ manifest: Manifest; sql: string }> {
+		const manifestObject = await backups.get(`d1/${stamp}/manifest.json`);
+		if (!manifestObject) throw PluginRouteError.notFound("Backup not found");
+		const manifest = (await manifestObject.json()) as Manifest;
+		const dump = await backups.get(`d1/${stamp}/${manifest.file}`);
+		if (!dump) throw PluginRouteError.notFound("Backup file not found");
+		return { manifest, sql: await new Response(dump.body.pipeThrough(new DecompressionStream("gzip"))).text() };
+	}
+
+	async function runBackup(source: "admin" | "scheduled") {
+		const { db, media, backups, uploads, restore } = await bindings();
+		const stamp = makeStamp();
+		const timeTravelBookmark = restore ? await currentBookmark(restore).catch(() => undefined) : undefined;
+		const file = `${name}.sql.gz`;
+		// Streamed: rows are read a page at a time and gzipped straight into the bucket.
+		const counts = { tables: 0, rows: 0 };
+		const written = await writeDumpStream(backups, stamp, file, dumpLines(db, counts));
+		const extra = { database: name, source, timeTravelBookmark, tables: counts.tables, rows: counts.rows };
+		// Save the database first so a media problem can't cost the dump.
+		const manifest = await writeManifest(backups, stamp, file, written, extra);
+		let result = manifest;
+		try {
+			const mediaResult = await mirrorMedia(media, backups, stamp);
+			result = await writeManifest(backups, stamp, file, written, { ...extra, media: mediaResult });
+		} catch (error) {
+			console.error("coywolf backups: media mirror failed; the database backup was saved", error);
+		}
+		if (uploads) {
+			try {
+				const uploadsResult = await mirrorBucket(uploads, backups, stamp, "uploads");
+				result = await writeManifest(backups, stamp, file, written, { ...result, uploads: uploadsResult });
+			} catch (error) {
+				console.error("coywolf backups: form uploads mirror failed; the database backup was saved", error);
+			}
+		}
+		return result;
+	}
+
+	async function daily(ctx: SettingsReader & { log: { info(msg: string, data?: unknown): void } }) {
+		const s = await settings(ctx);
+		if (s.scheduled) {
+			const manifest = await runBackup("scheduled");
+			ctx.log.info("Scheduled backup complete", { stamp: manifest.stamp, bytes: manifest.bytes });
+		}
+		const { backups } = await bindings();
+		const pruned = await pruneBackups(backups, s.retentionDays);
+		if (pruned) ctx.log.info("Pruned old backups", { pruned });
+	}
+
+	const routes = {
+		"backups/list": {
+			permission: "plugins:manage" as const,
+			handler: async (ctx: SettingsReader & CronScheduler) => {
+				await ensureBackupsTask(ctx);
+				const { backups, restoreStatus } = await bindings();
+				return { items: await listBackups(backups), ...(await settings(ctx)), restore: restoreStatus, undo: await getUndo(backups) };
+			},
+		},
+
+		/** Schedule and retention (the Backups page's Settings section). */
+		"backups/settings/save": definePluginRoute({
+			permission: "plugins:manage",
+			methods: ["POST"],
+			request: { body: "json" },
+			handler: async (ctx) => {
+				const input = parseInput(backupsSettingsInput, ctx.input);
+				await ctx.settings.set("backupsScheduled", input.scheduled);
+				await ctx.settings.set("backupsRetentionDays", input.retentionDays);
+				await ctx.settings.set("backupsStaleAfterHours", input.staleAfterHours);
+				await ensureBackupsTask(ctx);
+				ctx.log.info("Backup settings saved", input);
+				return settings(ctx);
+			},
+		}),
+
+		"backups/run": definePluginRoute({
+			permission: "plugins:manage",
+			methods: ["POST"],
+			request: { body: "none" },
+			handler: async (ctx) => {
+				await ensureBackupsTask(ctx);
+				const manifest = await runBackup("admin");
+				ctx.log.info("Backup complete", { stamp: manifest.stamp, bytes: manifest.bytes });
+				const { backups } = await bindings();
+				await pruneBackups(backups, (await settings(ctx)).retentionDays);
+				return manifest;
+			},
+		}),
+
+		"backups/rewind": definePluginRoute({
+			permission: "plugins:manage",
+			methods: ["POST"],
+			request: { body: "json" },
+			handler: async (ctx) => {
+				const input = parseInput(z.object({ stamp: z.string().regex(STAMP), confirm: confirmed("REWIND") }), ctx.input);
+				const { backups, restore } = await bindings();
+				if (!restore) throw PluginRouteError.badRequest("Restore isn't configured.");
+				const manifestObject = await backups.get(`d1/${input.stamp}/manifest.json`);
+				const manifest = manifestObject ? ((await manifestObject.json()) as Manifest) : undefined;
+				const undo = await rewind(restore, backups, { stamp: input.stamp, bookmark: manifest?.timeTravelBookmark });
+				ctx.log.warn("Database rewound", { to: input.stamp, undoBookmark: undo.bookmark });
+				return undo;
+			},
+		}),
+
+		"backups/undo": definePluginRoute({
+			permission: "plugins:manage",
+			methods: ["POST"],
+			request: { body: "json" },
+			handler: async (ctx) => {
+				parseInput(z.object({ confirm: confirmed("UNDO") }), ctx.input);
+				const { backups, restore } = await bindings();
+				if (!restore) throw PluginRouteError.badRequest("Restore isn't configured.");
+				const undo = await undoRewind(restore, backups);
+				ctx.log.warn("Rewind undone", { bookmark: undo.bookmark });
+				return undo;
+			},
+		}),
+
+		"backups/restore-new": definePluginRoute({
+			permission: "plugins:manage",
+			methods: ["POST"],
+			request: { body: "json" },
+			handler: async (ctx) => {
+				const input = parseInput(z.object({ stamp: z.string().regex(STAMP), confirm: confirmed("RESTORE") }), ctx.input);
+				const { backups, restore } = await bindings();
+				if (!restore) throw PluginRouteError.badRequest("Restore isn't configured.");
+				const { sql } = await readDump(backups, input.stamp);
+				const result = await restoreToNewDatabase(restore, `${name}-restore-${input.stamp.toLowerCase()}`, sql);
+				ctx.log.warn("Backup restored to a new database", { stamp: input.stamp, database: result.databaseName });
+				return result;
+			},
+		}),
+
+		"backups/restore-media": definePluginRoute({
+			permission: "plugins:manage",
+			methods: ["POST"],
+			request: { body: "none" },
+			handler: async (ctx) => {
+				// Media first, then private form uploads, in batches; the admin calls again while anything is pending.
+				const { media, backups, uploads } = await bindings();
+				const result = await restoreMissingMedia(media, backups);
+				const fromUploads =
+					uploads && !result.pending ? await restoreMissingMedia(uploads, backups, 200, "uploads") : { restored: 0, checked: 0, pending: 0 };
+				const combined = {
+					restored: result.restored + fromUploads.restored,
+					checked: result.checked + fromUploads.checked,
+					// Uploads aren't looked at until media is done, so count them as pending meanwhile.
+					pending: result.pending + (uploads && result.pending ? 1 : fromUploads.pending),
+					media: result,
+					uploads: uploads ? fromUploads : undefined,
+				};
+				ctx.log.info("Missing media restored", combined);
+				return combined;
+			},
+		}),
+
+		/**
+		 * A ten-minute link that streams one backup file (see ./download.ts).
+		 * The file is a gzipped SQL dump that restores into any D1 database.
+		 */
+		"backups/download-link": definePluginRoute({
+			permission: "plugins:manage",
+			methods: ["POST"],
+			request: { body: "json" },
+			handler: async (ctx) => {
+				const input = parseInput(z.object({ stamp: z.string().regex(STAMP), file: z.string().regex(FILE) }), ctx.input);
+				const { backups } = await bindings();
+				const link = await createDownloadLink(backups, input.stamp, input.file);
+				if (!link) throw PluginRouteError.notFound("Backup file not found");
+				ctx.log.info("Backup download link created", { stamp: input.stamp, file: input.file });
+				return link;
+			},
+		}),
+	};
+
+	return { routes, daily };
+}

package/src/backups/pack.ts

@@ -0,0 +1,33 @@
+import type { PluginContext } from "emdash";
+
+import { registerFeatures } from "../core/features.js";
+import type { PackMiddleware, PackModule } from "../core/module.js";
+import { configureBackupDownloads, serveBackupDownload } from "./download.js";
+import { BACKUPS_TASK, type BackupsOptions, backupsModule } from "./module.js";
+
+const FEATURES = [
+	{ id: "backups", label: "Backups", description: "Database and media backups, rewind, and restore.", default: true },
+];
+registerFeatures(FEATURES);
+
+export function backupsPack(options: BackupsOptions): PackModule {
+	// Module-level so the site middleware can find the backup bucket (createPlugin() runs at isolate start).
+	configureBackupDownloads(options);
+	const backups = backupsModule(options);
+	return {
+		id: "backups",
+		label: "Backups",
+		features: FEATURES,
+		routes: backups.routes,
+		tasks: [{ name: BACKUPS_TASK, schedule: "@daily", handler: (ctx: PluginContext) => backups.daily(ctx) }],
+		adminPages: [{ path: "/backups", label: "Backups", icon: "database" }],
+		widgets: [{ id: "backup-status", title: "Backups", size: "third" }],
+	};
+}
+
+/** Streams backup downloads at the links the Backups page creates (see ./download.ts). */
+export const backupsDownloadMiddleware: PackMiddleware = {
+	module: "backups",
+	feature: "backups",
+	handle: (context, env) => serveBackupDownload(context.request, context.url, env),
+};