@coywolf/emdash 0.0.0-stage → 0.35.13

package/src/astro/videos/CoywolfVideo.astro

@@ -0,0 +1,448 @@
+---
+/**
+ * Coywolf Video: a Cloudflare Stream player in a <figure>, sized by the
+ * video's aspect ratio (no layout shift), with an optional caption and
+ * plays/likes/date row. Schema comes from the page:metadata hook, not from here.
+ *
+ * Light embed (the default; Videos → Player): the page shows only the poster,
+ * sized for the screen, and loads Stream's player (~350 KB of JavaScript) when
+ * someone presses play, or for autoplaying videos on the visitor's first
+ * interaction once the video is on screen. Without it a video near the top of a page loaded
+ * with the page and, on a slow phone connection, became the page's largest
+ * paint several seconds late. Without JavaScript the player loads as before.
+ *
+ * Used for `coywolf-video` Portable Text blocks, and usable directly from a
+ * theme: <CoywolfVideo node={{ uid, preset: "gif" }} />. Also accepts the
+ * WordPress cloudflare-stream marker attributes (id, host, aspect, name,
+ * description, seconds), which default to the GIF preset.
+ *
+ * Moving pictures can always be stopped (WCAG 2.2.2): autoplaying videos
+ * without controls (the GIF preset) get a pause/play button, and visitors who
+ * ask for reduced motion get the poster and a play button instead of autoplay.
+ *
+ * What shows under the video (name, description, views, likes, date) follows
+ * the site defaults on the Videos settings tab unless the block says Show or
+ * Hide; the look comes from the same tab as custom properties (render.ts).
+ * The CSS is printed once per page.
+ */
+import { getPublicPluginApiRouteHandler } from "emdash/plugin-utils";
+
+import { PLUGIN_ID, siteFeatureOn } from "../../core/features.js";
+import { noteReadFailure, routeFailed } from "../../core/read-failures.js";
+import {
+	type VideoBlock,
+	aspectRatio,
+	isUid,
+	normalizeCustomerHost,
+	playerConfig,
+	playerSrc,
+} from "../../videos/lib.js";
+import { hostedPosterImage } from "../../videos/poster.js";
+import { DISPLAY_DEFAULTS, VIDEO_CSS, blockDisplay, type VideoDisplay, captionHtml, displayVars, metaHtml, schemeClass } from "../../videos/render.js";
+
+interface Props {
+	node: VideoBlock;
+}
+
+interface EmbedData {
+	host: string | null;
+	accent: string | null;
+	background: string | null;
+	lightEmbed?: boolean;
+	display?: VideoDisplay;
+	engagement: boolean;
+	video: {
+		name: string | null;
+		description: string | null;
+		duration: number;
+		created: string | null;
+		width: number;
+		height: number;
+		posterTime: number | null;
+		posterImage: string | null;
+	} | null;
+	counts: { plays: number; likes: number } | null;
+}
+
+const { node } = Astro.props;
+const uid = isUid(node?.uid) ? node.uid : isUid(node?.id) ? node.id : null;
+const on = await siteFeatureOn("videos");
+
+let data: EmbedData | null = null;
+if (on && uid) {
+	const handler = getPublicPluginApiRouteHandler(Astro.locals as Parameters<typeof getPublicPluginApiRouteHandler>[0]);
+	if (handler) {
+		try {
+			const res = (await handler(
+				PLUGIN_ID,
+				"POST",
+				"/videos/embed",
+				new Request(new URL(`/_emdash/api/plugins/${PLUGIN_ID}/videos/embed`, Astro.url), {
+					method: "POST",
+					headers: { "Content-Type": "application/json" },
+					body: JSON.stringify({ uid }),
+				}),
+			)) as { success?: boolean; data?: EmbedData; status?: number; error?: { code?: string } };
+			data = res?.success && res.data ? res.data : null;
+			// A server error (a read that failed): the player renders with defaults, so the page isn't edge-cached.
+			if (routeFailed(res)) noteReadFailure("video embed data");
+		} catch (error) {
+			console.warn("coywolf-pack: video embed data failed", error);
+			noteReadFailure("video embed data");
+		}
+	}
+}
+
+const host = normalizeCustomerHost(node?.host) ?? data?.host ?? null;
+const video = data?.video ?? null;
+const display = data?.display ?? DISPLAY_DEFAULTS;
+const cfg = playerConfig(node ?? {}, display);
+const str = (v: unknown) => (typeof v === "string" && v.trim() ? v.trim() : undefined);
+const num = (v: unknown) => (typeof v === "number" && Number.isFinite(v) && v >= 0 ? v : undefined);
+const name = str(node?.title) ?? str(node?.name) ?? video?.name ?? "Video";
+const description = str(node?.caption) ?? str(node?.description) ?? video?.description ?? "";
+const block = { posterTime: num(node?.posterTime), posterImage: str(node?.posterImage) };
+const posterFallback = { posterTime: video?.posterTime ?? (node?.host ? 1 : undefined), posterImage: video?.posterImage ?? undefined };
+// From the media host when there is one (copied from Stream once), else Stream's thumbnails.
+const hostedPoster = uid ? await hostedPosterImage(host, uid, block, posterFallback, Astro.url.origin, Astro.locals as Record<string, unknown>) : null;
+const poster = hostedPoster?.full;
+const playerExtra = { startTime: num(node?.startTime), poster, accent: data?.accent ?? undefined, background: data?.background ?? undefined };
+const src = uid ? playerSrc(host, uid, cfg, playerExtra) : "";
+// Light embed: the poster now, the player later. Pressing play starts it at once.
+const light = Boolean(uid) && data?.lightEmbed !== false;
+const playSrc = uid && light && !cfg.autoplay ? playerSrc(host, uid, { ...cfg, autoplay: true }, playerExtra) : src;
+const posterImg = light ? hostedPoster : null;
+// The theme names the block that's the page's largest early paint (Astro.locals.coywolfPriorityKey):
+// its poster loads at once and first, not lazily.
+const priority = Boolean(node?._key) && (Astro.locals as { coywolfPriorityKey?: string }).coywolfPriorityKey === node?._key;
+const ratio = aspectRatio(video?.width, video?.height, num(node?.aspect));
+const maxWidth = node?.sizeMode === "maxwidth" && num(node?.maxWidth) ? Math.max(100, Math.round(node.maxWidth as number)) : null;
+const counts = data?.engagement ? data.counts : null;
+const captionMarkup = captionHtml(name, description, { name: cfg.showName, description: cfg.showDescription });
+const metaMarkup = uid
+	? metaHtml({
+			uid,
+			likes: cfg.showLikes && counts !== null ? counts.likes : null,
+			showLikeCount: cfg.showLikeCount,
+			likeIcon: display.likeIcon,
+			plays: cfg.showPlays && counts !== null && !cfg.autoplay ? counts.plays : null,
+			date: cfg.showDate ? (video?.created ?? null) : null,
+			dateStyle: display.dateStyle,
+		})
+	: "";
+const track = data?.engagement && !cfg.autoplay;
+// Autoplaying without controls: our own pause/play button is the only way to stop it.
+const pausable = cfg.autoplay && !cfg.controls;
+const fallbackHref = /^https?:\/\//i.test(str(node?.url) ?? "") ? str(node?.url) : undefined;
+const style = [`--cw-video-ratio:${ratio}`, maxWidth ? `max-width:${maxWidth}px` : "", ...displayVars(blockDisplay(display, node as Record<string, unknown>), data?.background)].filter(Boolean).join(";");
+// The figure's CSS, once per page.
+const locals = (Astro.locals ?? {}) as Record<string, unknown>;
+const css = on && uid && !locals.__cwVideoCss ? VIDEO_CSS : "";
+if (css) locals.__cwVideoCss = true;
+---
+
+{css && <style is:inline set:html={css} />}
+{on && uid ? (
+	<figure class:list={["cw-video", cfg.gif && "cw-video--gif", schemeClass(display.scheme)]} style={style} data-cw-video={uid} data-cw-track={track ? "" : undefined} data-cw-autoplay={cfg.autoplay ? "" : undefined}>
+		{light && posterImg ? (
+			<div class="cw-video__frame" data-cw-player={playSrc} data-cw-title={name} data-cw-auto={cfg.autoplay ? "" : undefined}>
+				{posterImg.avif ? (
+					<picture>
+						<source type="image/avif" srcset={posterImg.avif} sizes="(min-width: 50rem) 768px, 100vw" />
+						<img class="cw-video__poster" src={posterImg.src} srcset={posterImg.srcset} sizes="(min-width: 50rem) 768px, 100vw" alt="" loading={priority ? "eager" : "lazy"} fetchpriority={priority ? "high" : undefined} decoding="async" />
+					</picture>
+				) : (
+					<img class="cw-video__poster" src={posterImg.src} srcset={posterImg.srcset} sizes="(min-width: 50rem) 768px, 100vw" alt="" loading={priority ? "eager" : "lazy"} fetchpriority={priority ? "high" : undefined} decoding="async" />
+				)}
+				{/* Autoplaying videos with controls keep this hidden unless the visitor prefers reduced motion. */}
+				{!pausable && (
+					<button type="button" class="cw-video__play" data-cw-play aria-label={`Play video: ${name}`} hidden={cfg.autoplay}>
+						<svg viewBox="0 0 24 24" width="28" height="28" aria-hidden="true" focusable="false"><path d="M8 5v14l11-7z" fill="currentColor" /></svg>
+					</button>
+				)}
+				{pausable && (
+					<button type="button" class="cw-video__toggle" data-cw-toggle data-cw-name={name} aria-label={`Pause video: ${name}`}>
+						<svg class="cw-video__pause" viewBox="0 0 24 24" width="20" height="20" aria-hidden="true" focusable="false"><path d="M6 5h4v14H6zm8 0h4v14h-4z" fill="currentColor" /></svg>
+						<svg class="cw-video__resume" viewBox="0 0 24 24" width="20" height="20" aria-hidden="true" focusable="false"><path d="M8 5v14l11-7z" fill="currentColor" /></svg>
+					</button>
+				)}
+				<noscript>
+					<iframe src={src} title={name} loading="lazy" allow="accelerometer; gyroscope; autoplay; encrypted-media; picture-in-picture;" allowfullscreen></iframe>
+				</noscript>
+			</div>
+		) : (
+			<div class="cw-video__frame">
+				<iframe
+					src={src}
+					title={name}
+					loading="lazy"
+					allow="accelerometer; gyroscope; autoplay; encrypted-media; picture-in-picture;"
+					allowfullscreen
+				></iframe>
+				{pausable && (
+					<button type="button" class="cw-video__toggle" data-cw-toggle data-cw-name={name} aria-label={`Pause video: ${name}`}>
+						<svg class="cw-video__pause" viewBox="0 0 24 24" width="20" height="20" aria-hidden="true" focusable="false"><path d="M6 5h4v14H6zm8 0h4v14h-4z" fill="currentColor" /></svg>
+						<svg class="cw-video__resume" viewBox="0 0 24 24" width="20" height="20" aria-hidden="true" focusable="false"><path d="M8 5v14l11-7z" fill="currentColor" /></svg>
+					</button>
+				)}
+			</div>
+		)}
+		{captionMarkup && <Fragment set:html={captionMarkup} />}
+		{metaMarkup && <Fragment set:html={metaMarkup} />}
+	</figure>
+) : on && fallbackHref ? (
+	<p class="cw-video-link"><a href={fallbackHref}>{str(node?.title) ?? "Watch the video"}</a></p>
+) : null}
+
+<script>
+	// Light embed (poster first, player on demand), pause/play for autoplaying
+	// videos without controls, plays (once per session, after 2 seconds of
+	// playback) and likes. Stream's player SDK is loaded only to count plays or
+	// to pause and play, and only once a player exists.
+	import { relativeDate } from "../../videos/date.js";
+	import { playerControl } from "../../videos/pause.js";
+
+	const API = "/_emdash/api/plugins/coywolf-pack/videos/";
+	// X-Coywolf-Video: likes are refused without it, so other sites can't send them.
+	const post = (path: string, body: { uid: string; liked?: boolean }) =>
+		fetch(API + path, { method: "POST", headers: { "Content-Type": "application/json", "X-Coywolf-Video": "1" }, body: JSON.stringify(body) })
+			.then((r) => (r.ok ? (r.json() as Promise<{ data?: { plays?: number; likes?: number; liked?: boolean } }>) : null))
+			.then((r) => r?.data ?? null)
+			.catch(() => null);
+	const store = {
+		get: (k: string) => { try { return sessionStorage.getItem(k) ?? localStorage.getItem(k); } catch { return null; } },
+		session: (k: string) => { try { sessionStorage.setItem(k, "1"); } catch { /* private mode */ } },
+		like: (k: string, on: boolean) => { try { on ? localStorage.setItem(k, "1") : localStorage.removeItem(k); } catch { /* private mode */ } },
+	};
+
+	type StreamPlayer = { addEventListener(e: string, f: () => void): void; currentTime: number; play(): unknown; pause(): unknown };
+	let sdk: Promise<((el: HTMLIFrameElement) => StreamPlayer) | null> | null = null;
+	const loadSdk = () =>
+		(sdk ??= new Promise((resolve) => {
+			const s = document.createElement("script");
+			s.src = "https://embed.cloudflarestream.com/embed/sdk.latest.js";
+			s.async = true;
+			s.onload = () => resolve((window as unknown as { Stream?: (el: HTMLIFrameElement) => StreamPlayer }).Stream ?? null);
+			s.onerror = () => resolve(null);
+			document.head.appendChild(s);
+		}));
+	const players = new WeakMap<HTMLIFrameElement, Promise<StreamPlayer | null>>();
+	const playerFor = (frame: HTMLIFrameElement) => {
+		let player = players.get(frame);
+		if (!player) {
+			player = loadSdk().then((Stream) => (Stream ? Stream(frame) : null));
+			players.set(frame, player);
+		}
+		return player;
+	};
+	/** Pause/play that holds to the visitor's choice until the player is ready (see videos/pause.ts). */
+	const controls = new WeakMap<HTMLIFrameElement, (playing: boolean) => void>();
+	const controlFor = (frame: HTMLIFrameElement) => {
+		let control = controls.get(frame);
+		if (!control) {
+			control = playerControl(playerFor(frame));
+			controls.set(frame, control);
+		}
+		return control;
+	};
+	const reduceMotion = matchMedia("(prefers-reduced-motion: reduce)").matches;
+
+	/** Count a play (once per session) after 2 seconds of playback in this figure's player. */
+	const track = (fig: HTMLElement, frame: HTMLIFrameElement) => {
+		const uid = fig.dataset.cwVideo as string;
+		if (!fig.hasAttribute("data-cw-track") || store.get(`cw-video-play-${uid}`)) return;
+		void playerFor(frame).then((player) => {
+			if (!player) return;
+			let done = false;
+			player.addEventListener("timeupdate", () => {
+				if (done || player.currentTime < 2) return;
+				done = true;
+				store.session(`cw-video-play-${uid}`);
+				void post("play", { uid }).then((r) => {
+					const el = fig.querySelector<HTMLElement>("[data-cw-plays]");
+					if (el && r && typeof r.plays === "number" && r.plays > 0) el.textContent = `${r.plays.toLocaleString("en-US")} ${r.plays === 1 ? "view" : "views"}`;
+				});
+			});
+		});
+	};
+
+	/** Light embed: replace the poster with Stream's player. */
+	const load = (frameEl: HTMLElement, focus: boolean) => {
+		if (frameEl.querySelector("iframe")) return;
+		const frame = document.createElement("iframe");
+		frame.src = frameEl.dataset.cwPlayer as string;
+		frame.title = frameEl.dataset.cwTitle ?? "Video";
+		frame.allow = "accelerometer; gyroscope; autoplay; encrypted-media; picture-in-picture;";
+		frame.allowFullscreen = true;
+		frameEl.querySelector("[data-cw-play]")?.remove();
+		frameEl.appendChild(frame);
+		// The poster stays underneath until the player has painted, so nothing flashes.
+		frame.addEventListener("load", () => {
+			const poster = frameEl.querySelector(".cw-video__poster");
+			(poster?.parentElement?.tagName === "PICTURE" ? poster.parentElement : poster)?.remove();
+		}, { once: true });
+		if (focus) frame.focus();
+		const fig = frameEl.closest<HTMLElement>("[data-cw-video]");
+		if (fig) track(fig, frame);
+	};
+
+	document.querySelectorAll<HTMLElement>("[data-cw-player]").forEach((frameEl) => {
+		frameEl.querySelector<HTMLButtonElement>("[data-cw-play]")?.addEventListener("click", () => load(frameEl, true));
+	});
+
+	// Reduced motion: no autoplay. Light embeds keep their poster (data-cw-held) with a play
+	// button; players rendered with the page lose their autoplay parameter.
+	if (reduceMotion) {
+		document.querySelectorAll<HTMLElement>("[data-cw-player][data-cw-auto]").forEach((frameEl) => {
+			frameEl.setAttribute("data-cw-held", "");
+			const play = frameEl.querySelector<HTMLButtonElement>("[data-cw-play]");
+			if (play) play.hidden = false;
+		});
+		document.querySelectorAll<HTMLIFrameElement>("[data-cw-autoplay] .cw-video__frame:not([data-cw-player]) iframe").forEach((frame) => {
+			try {
+				const url = new URL(frame.src);
+				if (!url.searchParams.has("autoplay")) return;
+				url.searchParams.delete("autoplay");
+				frame.src = url.href;
+			} catch {
+				// Leave it as it is.
+			}
+		});
+	}
+
+	// Pause/play for autoplaying videos without controls. Before a light embed's player has
+	// loaded, pausing keeps the poster (the video doesn't autoplay) and playing loads it.
+	document.querySelectorAll<HTMLButtonElement>("[data-cw-toggle]").forEach((btn) => {
+		const frameEl = btn.closest<HTMLElement>(".cw-video__frame");
+		if (!frameEl) return;
+		const name = btn.dataset.cwName ?? "";
+		let playing = !reduceMotion;
+		const show = () => {
+			btn.setAttribute("aria-label", `${playing ? "Pause" : "Play"} video: ${name}`);
+			btn.toggleAttribute("data-paused", !playing);
+		};
+		if (!playing) frameEl.setAttribute("data-cw-held", "");
+		show();
+		btn.addEventListener("click", () => {
+			playing = !playing;
+			show();
+			const want = playing;
+			const frame = frameEl.querySelector<HTMLIFrameElement>("iframe");
+			if (frame) {
+				// Applied once the SDK and player are ready, and again if autoplay starts after a pause.
+				controlFor(frame)(want);
+			} else if (want) {
+				frameEl.removeAttribute("data-cw-held");
+				load(frameEl, false);
+			} else {
+				frameEl.setAttribute("data-cw-held", "");
+			}
+		});
+	});
+
+	// Autoplaying videos: on the visitor's first interaction (scroll, touch, pointer or
+	// key), once the video is (nearly) on screen. Loading on idle instead still ran
+	// Stream's player (about 1.5 s of script on a mid-range phone) inside the page's
+	// load window, which PageSpeed counts as blocking time.
+	const autos = document.querySelectorAll<HTMLElement>("[data-cw-player][data-cw-auto]");
+	if (autos.length && !reduceMotion) {
+		let interacted = false;
+		// A first interaction on a video's pause/play button: that video waits for the button's
+		// click (which, from the start, pauses it and keeps the poster) instead of autoplaying.
+		let pressing: HTMLElement | null = null;
+		const visible = new Set<HTMLElement>();
+		const flush = () => {
+			if (!interacted) return;
+			visible.forEach((el) => {
+				if (el === pressing && !el.hasAttribute("data-cw-held")) return;
+				visible.delete(el);
+				// Paused before its player loaded (data-cw-held): keep the poster.
+				if (!el.hasAttribute("data-cw-held")) load(el, false);
+			});
+		};
+		const events = ["scroll", "pointermove", "pointerdown", "touchstart", "keydown", "wheel"] as const;
+		const onFirst = (event: Event) => {
+			interacted = true;
+			const toggle = event.target instanceof Element ? event.target.closest("[data-cw-toggle]") : null;
+			pressing = toggle?.closest<HTMLElement>("[data-cw-player][data-cw-auto]") ?? null;
+			if (pressing) {
+				// The click decides; if it never comes (pointer dragged away), load it as usual.
+				const settle = () => {
+					pressing = null;
+					flush();
+				};
+				addEventListener("click", () => setTimeout(settle), { once: true, capture: true });
+				setTimeout(settle, 1000);
+			}
+			events.forEach((e) => removeEventListener(e, onFirst));
+			flush();
+		};
+		events.forEach((e) => addEventListener(e, onFirst, { passive: true, once: true }));
+		if ("IntersectionObserver" in window) {
+			const seen = new IntersectionObserver((entries) => {
+				for (const entry of entries) {
+					if (!entry.isIntersecting) continue;
+					seen.unobserve(entry.target);
+					visible.add(entry.target as HTMLElement);
+				}
+				flush();
+			}, { rootMargin: "200px" });
+			autos.forEach((el) => seen.observe(el));
+		} else {
+			autos.forEach((el) => visible.add(el));
+		}
+	}
+
+	// Players rendered with the page (light embed off): count plays once they're near the screen.
+	const tracked = document.querySelectorAll<HTMLElement>("[data-cw-video][data-cw-track]");
+	const io = "IntersectionObserver" in window
+		? new IntersectionObserver((entries) => {
+				for (const entry of entries) {
+					if (!entry.isIntersecting) continue;
+					io?.unobserve(entry.target);
+					const fig = entry.target as HTMLElement;
+					const frame = fig.querySelector<HTMLIFrameElement>(".cw-video__frame:not([data-cw-player]) iframe");
+					if (frame) track(fig, frame);
+				}
+			}, { rootMargin: "200px" })
+		: null;
+	tracked.forEach((fig) => io?.observe(fig));
+
+	// Relative upload dates ("7 months ago"): pages can be served from a cache for days.
+	document.querySelectorAll<HTMLTimeElement>("time[data-cw-relative]").forEach((el) => {
+		const text = relativeDate(el.dateTime);
+		if (text) el.textContent = text;
+	});
+
+	document.querySelectorAll<HTMLButtonElement>("[data-cw-like]").forEach((btn) => {
+		const uid = btn.dataset.cwLike as string;
+		const key = `cw-video-liked-${uid}`;
+		if (store.get(key)) btn.setAttribute("aria-pressed", "true");
+		let busy = false;
+		// After a click the new state holds (no hover preview of the other state) until the pointer or focus leaves.
+		const release = () => btn.removeAttribute("data-held");
+		btn.addEventListener("mouseleave", release);
+		btn.addEventListener("blur", release);
+		btn.addEventListener("animationend", () => btn.removeAttribute("data-pop"));
+		btn.addEventListener("click", () => {
+			if (busy) return;
+			busy = true;
+			const next = btn.getAttribute("aria-pressed") !== "true";
+			btn.setAttribute("aria-pressed", String(next));
+			btn.setAttribute("data-held", "");
+			// Restart the pop (CSS skips it for reduced motion).
+			btn.removeAttribute("data-pop");
+			void btn.offsetWidth;
+			btn.setAttribute("data-pop", "");
+			// The wanted state, not a toggle: visitors sharing an address share a like.
+			void post("like", { uid, liked: next }).then((r) => {
+				busy = false;
+				if (!r) return;
+				btn.setAttribute("aria-pressed", String(Boolean(r.liked)));
+				store.like(key, Boolean(r.liked));
+				const count = btn.querySelector("[data-cw-likes]");
+				if (count && typeof r.likes === "number") count.textContent = r.likes > 0 ? r.likes.toLocaleString("en-US") : "";
+			});
+		});
+	});
+</script>

package/src/backups/download.ts

@@ -0,0 +1,112 @@
+/**
+ * Backup downloads. Plugin routes can only answer with a body held in memory,
+ * and a database dump can be larger than a Worker should buffer, so the
+ * Backups page asks the backups/download-link route (admins only) for a
+ * short-lived link, and the pack middleware streams the file from R2 at that
+ * link:
+ *
+ *   /_coywolf-pack/backup/<token>/<file name>
+ *
+ * The token is random (192 bits) and names a ticket in the backup bucket,
+ * downloads/<token>.json, that says which file it opens and until when. A
+ * ticket works for ten minutes (so a browser can retry or resume), and old
+ * tickets are deleted whenever a new one is made.
+ */
+import { contentDisposition } from "../files/format.js";
+import { FILE, STAMP } from "./store.js";
+
+export const DOWNLOAD_PATH = "/_coywolf-pack/backup/";
+const TICKET_PREFIX = "downloads/";
+const TICKET_TTL_MS = 10 * 60_000;
+const TOKEN = /^[a-f0-9]{48}$/;
+
+interface Ticket {
+	key: string;
+	filename: string;
+	expires: string;
+}
+
+/** Set by backupsPack() when the module is configured; the middleware does nothing without it. */
+let config: { backups: string } | null = null;
+
+export function configureBackupDownloads(options: { backups?: string }) {
+	config = { backups: options.backups ?? "BACKUPS" };
+}
+
+function newToken(): string {
+	return [...crypto.getRandomValues(new Uint8Array(24))].map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+
+/** The file name a download is saved as: mysite-2026-10-03T1802Z.sql.gz. */
+export function downloadFilename(file: string, stamp: string): string {
+	const match = /^(.*?)(\.sql\.gz|\.gz|\.sql)?$/i.exec(file);
+	return `${match?.[1] || "database"}-${stamp}${match?.[2] ?? ""}`;
+}
+
+/** Delete tickets that have expired (by upload time, so no ticket has to be read). */
+async function pruneTickets(bucket: R2Bucket) {
+	const cutoff = Date.now() - TICKET_TTL_MS;
+	let cursor: string | undefined;
+	do {
+		const page = await bucket.list({ prefix: TICKET_PREFIX, cursor });
+		const old = page.objects.filter((o) => o.uploaded.getTime() < cutoff).map((o) => o.key);
+		if (old.length) await bucket.delete(old);
+		cursor = page.truncated ? page.cursor : undefined;
+	} while (cursor);
+}
+
+/** Make a download link for one backup file, or null when it doesn't exist. */
+export async function createDownloadLink(bucket: R2Bucket, stamp: string, file: string): Promise<{ url: string; filename: string; bytes: number; expires: string } | null> {
+	if (!STAMP.test(stamp) || !FILE.test(file)) return null;
+	const key = `d1/${stamp}/${file}`;
+	const head = await bucket.head(key);
+	if (!head) return null;
+	await pruneTickets(bucket).catch(() => undefined);
+	const token = newToken();
+	const filename = downloadFilename(file, stamp);
+	const ticket: Ticket = { key, filename, expires: new Date(Date.now() + TICKET_TTL_MS).toISOString() };
+	await bucket.put(`${TICKET_PREFIX}${token}.json`, JSON.stringify(ticket), { httpMetadata: { contentType: "application/json" } });
+	return { url: `${DOWNLOAD_PATH}${token}/${encodeURIComponent(filename)}`, filename, bytes: head.size, expires: ticket.expires };
+}
+
+const NOT_FOUND = () =>
+	new Response("This download link has expired. Download the backup again from the Backups page.", {
+		status: 404,
+		headers: { "Content-Type": "text/plain; charset=utf-8", "Cache-Control": "no-store", "X-Robots-Tag": "noindex" },
+	});
+
+/** Middleware: stream a backup file for a valid ticket. Returns undefined for any other URL. */
+export async function serveBackupDownload(request: Request, url: URL, env: Record<string, unknown>): Promise<Response | undefined> {
+	if (!config || !url.pathname.startsWith(DOWNLOAD_PATH)) return undefined;
+	if (request.method !== "GET" && request.method !== "HEAD") return new Response(null, { status: 405, headers: { Allow: "GET, HEAD" } });
+	const token = url.pathname.slice(DOWNLOAD_PATH.length).split("/")[0];
+	if (!TOKEN.test(token)) return NOT_FOUND();
+	const bucket = env[config.backups] as R2Bucket | undefined;
+	if (!bucket) return NOT_FOUND();
+
+	const ticketObject = await bucket.get(`${TICKET_PREFIX}${token}.json`);
+	if (!ticketObject) return NOT_FOUND();
+	const ticket = (await ticketObject.json()) as Ticket;
+	if (!(Date.parse(ticket.expires) > Date.now()) || !ticket.key.startsWith("d1/")) return NOT_FOUND();
+
+	const headers = new Headers({
+		"Content-Type": "application/gzip",
+		"Content-Disposition": contentDisposition(ticket.filename),
+		"Cache-Control": "private, no-store",
+		"Referrer-Policy": "no-referrer",
+		"X-Content-Type-Options": "nosniff",
+		"X-Robots-Tag": "noindex",
+	});
+	if (request.method === "HEAD") {
+		const head = await bucket.head(ticket.key);
+		if (!head) return NOT_FOUND();
+		headers.set("Content-Length", String(head.size));
+		return new Response(null, { headers });
+	}
+	const object = await bucket.get(ticket.key);
+	if (!object) return NOT_FOUND();
+	headers.set("Content-Length", String(object.size));
+	headers.set("ETag", object.httpEtag);
+	// Streamed straight from R2: the Worker never holds the whole file.
+	return new Response(object.body, { headers });
+}