@coywolf/emdash 0.0.0-stage → 0.35.13

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),
+};

package/src/backups/restore.test.mjs

@@ -0,0 +1,103 @@
+// Unit tests for restoring missing media in batches.
+// Run: node --test src/backups/restore.test.mjs   (Node 22.6+ strips the types from store.ts)
+import assert from "node:assert/strict";
+import { test } from "node:test";
+
+const { restoreMissingMedia, mirrorBucket, pruneBackups } = await import("./store.ts");
+
+/** The slice of an R2 bucket that restoreMissingMedia uses, paging 100 keys at a time like R2's default 1,000. */
+function bucket(entries = {}) {
+	const store = new Map(Object.entries(entries));
+	return {
+		store,
+		async list({ prefix = "", cursor, delimiter } = {}) {
+			const keys = [...store.keys()].filter((k) => k.startsWith(prefix)).sort();
+			if (delimiter) {
+				const dirs = [...new Set(keys.map((k) => k.slice(prefix.length)).filter((k) => k.includes(delimiter)).map((k) => prefix + k.split(delimiter)[0] + delimiter))];
+				return { objects: [], delimitedPrefixes: dirs, truncated: false };
+			}
+			const start = cursor ? Number(cursor) : 0;
+			const page = keys.slice(start, start + 100);
+			const truncated = start + 100 < keys.length;
+			return { objects: page.map((key) => ({ key, etag: `e-${store.get(key)}` })), truncated, cursor: truncated ? String(start + 100) : undefined };
+		},
+		async get(key) {
+			return store.has(key) ? { body: store.get(key), httpMetadata: {} } : null;
+		},
+		async put(key, body) {
+			store.set(key, body);
+		},
+		async delete(keys) {
+			for (const k of [].concat(keys)) store.delete(k);
+		},
+	};
+}
+
+test("restores missing media in batches until nothing is pending, never overwriting", async () => {
+	const mirror = {};
+	for (let i = 0; i < 450; i++) mirror[`media/current/file-${String(i).padStart(3, "0")}.jpg`] = `backup-${i}`;
+	const backups = bucket(mirror);
+	const media = bucket({ "file-000.jpg": "live-0" });
+
+	const runs = [];
+	for (;;) {
+		const result = await restoreMissingMedia(media, backups, 200);
+		runs.push(result);
+		if (!result.pending) break;
+	}
+	assert.deepEqual(runs.map((r) => [r.restored, r.pending]), [[200, 249], [200, 49], [49, 0]]);
+	assert.equal(media.store.size, 450);
+	assert.equal(media.store.get("file-000.jpg"), "live-0", "existing files are left alone");
+	assert.equal(media.store.get("file-449.jpg"), "backup-449");
+	assert.deepEqual(await restoreMissingMedia(media, backups, 200), { restored: 0, checked: 450, pending: 0 });
+});
+
+test("private form uploads mirror to uploads/ and restore from there, separate from media", async () => {
+	const uploads = bucket({ "forms/a.pdf": "A", "forms/b.png": "B" });
+	const backups = bucket({ "media/current/photo.jpg": "P" });
+	const first = await mirrorBucket(uploads, backups, "2020-01-01T0600Z", "uploads");
+	assert.deepEqual(first, { copied: 2, preserved: 0, total: 2, pending: 0 });
+	assert.equal(backups.store.get("uploads/current/forms/a.pdf"), "A");
+
+	// A replaced upload keeps its old copy under uploads/changed/<stamp>/; a deleted one too.
+	uploads.store.set("forms/a.pdf", "A2");
+	uploads.store.delete("forms/b.png");
+	await mirrorBucket(uploads, backups, "2020-01-02T0600Z", "uploads");
+	assert.equal(backups.store.get("uploads/current/forms/a.pdf"), "A2");
+	assert.equal(backups.store.get("uploads/changed/2020-01-02T0600Z/forms/a.pdf"), "A");
+	assert.equal(backups.store.get("uploads/changed/2020-01-02T0600Z/forms/b.png"), "B");
+	assert.ok(!backups.store.has("uploads/current/forms/b.png"));
+	assert.equal(backups.store.get("media/current/photo.jpg"), "P", "media mirror untouched");
+
+	const empty = bucket();
+	const restored = await restoreMissingMedia(empty, backups, 200, "uploads");
+	assert.deepEqual(restored, { restored: 1, checked: 1, pending: 0 });
+	assert.equal(empty.store.get("forms/a.pdf"), "A2");
+	assert.ok(!empty.store.has("photo.jpg"), "media isn't restored into the uploads bucket");
+
+	// Old replaced copies are pruned like media's.
+	assert.equal(await pruneBackups(backups, 1), 0);
+	assert.ok(![...backups.store.keys()].some((k) => k.startsWith("uploads/changed/2020-01-02")), "uploads/changed pruned");
+});
+
+test("the mirror copies a few files at a time, never more than its limit", async () => {
+	const { MIRROR_CONCURRENCY } = await import("./store.ts");
+	const files = {};
+	for (let i = 0; i < 40; i++) files[`f${i}.jpg`] = `v${i}`;
+	const media = bucket(files);
+	const backups = bucket({ "media/current/f0.jpg": "old", "media/current/gone.jpg": "G" });
+	let inFlight = 0;
+	let most = 0;
+	const slowGet = media.get.bind(media);
+	media.get = async (key) => {
+		most = Math.max(most, ++inFlight);
+		await new Promise((resolve) => setTimeout(resolve, 2));
+		inFlight--;
+		return slowGet(key);
+	};
+	const result = await mirrorBucket(media, backups, "2020-01-03T0600Z", "media", 30);
+	assert.equal(most, MIRROR_CONCURRENCY);
+	assert.deepEqual(result, { copied: 30, preserved: 1, total: 40, pending: 11 });
+	assert.equal(backups.store.get("media/changed/2020-01-03T0600Z/f0.jpg"), "old", "a replaced file's old copy is kept before it's overwritten");
+	assert.equal(backups.store.get("media/current/f0.jpg"), "v0");
+});

package/src/backups/restore.ts

@@ -0,0 +1,209 @@
+/**
+ * Restores, through the Cloudflare API (a Worker can't create databases or
+ * time-travel through its D1 binding).
+ *
+ * Rewinding rolls the live database back, including this plugin's own
+ * settings and storage, so everything a restore depends on lives outside the
+ * database: the API token is a Worker secret, the account and database IDs are
+ * plugin options, and undo points are written to the backup bucket.
+ */
+import { PluginRouteError } from "emdash";
+
+import { stampToDate } from "./store.js";
+
+const API = "https://api.cloudflare.com/client/v4";
+/** One file per rewind, newest last: undo pops the most recent, so earlier states stay reachable. */
+const UNDO_PREFIX = "restore/undo/";
+
+export interface RestoreConfig {
+	token: string;
+	accountId: string;
+	databaseId: string;
+}
+
+export interface UndoPoint {
+	/** Bookmark of the database just before the rewind. */
+	bookmark: string;
+	rewoundAt: string;
+	rewoundTo: string;
+}
+
+async function cf<T>(config: RestoreConfig, path: string, init: RequestInit = {}): Promise<T> {
+	const res = await fetch(`${API}/accounts/${config.accountId}${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<{ message: string }> };
+	if (!res.ok || body.success === false) {
+		// Surface the API's message in the admin (plain Errors become a generic 500).
+		throw PluginRouteError.badRequest(
+			`Cloudflare API ${res.status}: ${body.errors?.map((e) => e.message).join("; ") || res.statusText}`,
+		);
+	}
+	return body.result as T;
+}
+
+const db = (config: RestoreConfig) => `/d1/database/${config.databaseId}`;
+
+export async function currentBookmark(config: RestoreConfig): Promise<string> {
+	const result = await cf<{ bookmark: string }>(config, `${db(config)}/time_travel/bookmark`);
+	return result.bookmark;
+}
+
+/** Roll the live database back to a backup's moment, saving an undo point first. */
+export async function rewind(
+	config: RestoreConfig,
+	backups: R2Bucket,
+	target: { stamp: string; bookmark?: string },
+): Promise<UndoPoint> {
+	const query = target.bookmark
+		? `bookmark=${encodeURIComponent(target.bookmark)}`
+		: `timestamp=${encodeURIComponent(stampToDate(target.stamp).toISOString())}`;
+	const before = await currentBookmark(config);
+	const undo: UndoPoint = { bookmark: before, rewoundAt: new Date().toISOString(), rewoundTo: target.stamp };
+	await backups.put(`${UNDO_PREFIX}${undo.rewoundAt}.json`, JSON.stringify(undo), {
+		httpMetadata: { contentType: "application/json" },
+	});
+	await cf(config, `${db(config)}/time_travel/restore?${query}`, { method: "POST" });
+	return undo;
+}
+
+async function latestUndoKey(backups: R2Bucket): Promise<string | null> {
+	const keys: string[] = [];
+	let cursor: string | undefined;
+	do {
+		const page = await backups.list({ prefix: UNDO_PREFIX, cursor });
+		for (const o of page.objects) keys.push(o.key);
+		cursor = page.truncated ? page.cursor : undefined;
+	} while (cursor);
+	return keys.sort().at(-1) ?? null;
+}
+
+/** The most recent rewind that hasn't been undone. */
+export async function getUndo(backups: R2Bucket): Promise<UndoPoint | null> {
+	const key = await latestUndoKey(backups);
+	const object = key ? await backups.get(key) : null;
+	return object ? ((await object.json()) as UndoPoint) : null;
+}
+
+/** Return the database to where it was before the most recent rewind. */
+export async function undoRewind(config: RestoreConfig, backups: R2Bucket): Promise<UndoPoint> {
+	const key = await latestUndoKey(backups);
+	const object = key ? await backups.get(key) : null;
+	if (!key || !object) throw PluginRouteError.badRequest("There is no rewind to undo.");
+	const undo = (await object.json()) as UndoPoint;
+	await cf(config, `${db(config)}/time_travel/restore?bookmark=${encodeURIComponent(undo.bookmark)}`, { method: "POST" });
+	await backups.delete(key);
+	return undo;
+}
+
+async function md5(bytes: Uint8Array<ArrayBuffer>): Promise<string> {
+	// MD5 is what D1's import API uses as the upload ETag (Workers support it in WebCrypto).
+	const digest = await crypto.subtle.digest("MD5", bytes);
+	return [...new Uint8Array(digest)].map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+
+interface ImportStatus {
+	status?: "active" | "complete" | "error";
+	at_bookmark?: string;
+	upload_url?: string;
+	filename?: string;
+	error?: string;
+	success?: boolean;
+}
+
+export interface NewDatabaseRestore {
+	databaseId: string;
+	databaseName: string;
+	tables: number;
+	rows: number;
+	mismatches: Record<string, [number, number | undefined]>;
+}
+
+/**
+ * Import a dump into a brand-new D1 database and verify row counts. The live
+ * site keeps running on its current database until its binding is switched.
+ */
+export async function restoreToNewDatabase(
+	config: RestoreConfig,
+	databaseName: string,
+	sql: string,
+): Promise<NewDatabaseRestore> {
+	const suffix = crypto.randomUUID().slice(0, 6);
+	const created = await cf<{ uuid: string; name: string }>(config, "/d1/database", {
+		method: "POST",
+		body: JSON.stringify({ name: `${databaseName}-${suffix}` }),
+	});
+	const target: RestoreConfig = { ...config, databaseId: created.uuid };
+	try {
+		return await importAndVerify(target, created, sql);
+	} catch (error) {
+		// Don't leave a half-imported database behind.
+		await cf(config, `/d1/database/${created.uuid}`, { method: "DELETE" }).catch(() => undefined);
+		throw error;
+	}
+}
+
+async function importAndVerify(
+	target: RestoreConfig,
+	created: { uuid: string; name: string },
+	sql: string,
+): Promise<NewDatabaseRestore> {
+	const path = `${db(target)}/import`;
+
+	const bytes = new TextEncoder().encode(sql) as Uint8Array<ArrayBuffer>;
+	const etag = await md5(bytes);
+	const init = await cf<ImportStatus>(target, path, { method: "POST", body: JSON.stringify({ action: "init", etag }) });
+	if (init.upload_url) {
+		const put = await fetch(init.upload_url, { method: "PUT", body: bytes });
+		if (!put.ok) throw PluginRouteError.badRequest(`Uploading the dump failed (${put.status})`);
+	}
+	let status = await cf<ImportStatus>(target, path, {
+		method: "POST",
+		body: JSON.stringify({ action: "ingest", etag, filename: init.filename }),
+	});
+	const bookmark = status.at_bookmark;
+	for (let i = 0; status.status !== "complete" && status.status !== "error" && i < 60; i++) {
+		await new Promise((r) => setTimeout(r, 1000));
+		status = await cf<ImportStatus>(target, path, {
+			method: "POST",
+			body: JSON.stringify({ action: "poll", current_bookmark: bookmark }),
+		});
+	}
+	if (status.status !== "complete") {
+		throw PluginRouteError.badRequest(`Import ${status.status ?? "timed out"}: ${status.error ?? "no details"}`);
+	}
+
+	// Verify: rows per table in the dump vs. the new database.
+	const expected = new Map<string, number>();
+	for (const match of sql.matchAll(/^INSERT INTO "((?:[^"]|"")+)"/gm)) {
+		const table = match[1].replace(/""/g, '"');
+		expected.set(table, (expected.get(table) ?? 0) + 1);
+	}
+	const tables = [...expected.keys()];
+	const actual = new Map<string, number>();
+	for (let i = 0; i < tables.length; i += 5) {
+		// D1 allows at most 5 terms in a compound SELECT.
+		const sqlCounts = tables
+			.slice(i, i + 5)
+			.map((t) => `SELECT '${t.replace(/'/g, "''")}' AS t, count(*) AS n FROM "${t.replace(/"/g, '""')}"`)
+			.join(" UNION ALL ");
+		const result = await cf<Array<{ results: Array<{ t: string; n: number }> }>>(target, `${db(target)}/query`, {
+			method: "POST",
+			body: JSON.stringify({ sql: sqlCounts }),
+		});
+		for (const row of result[0]?.results ?? []) actual.set(row.t, row.n);
+	}
+	const mismatches: NewDatabaseRestore["mismatches"] = {};
+	for (const [table, n] of expected) if (actual.get(table) !== n) mismatches[table] = [n, actual.get(table)];
+
+	return {
+		databaseId: created.uuid,
+		databaseName: created.name,
+		tables: tables.length,
+		rows: [...expected.values()].reduce((a, b) => a + b, 0),
+		mismatches,
+	};
+}
+
+export { restoreMissingMedia } from "./store.js";