@coywolf/emdash 0.0.0-stage → 0.35.13

package/src/images/pending.ts

@@ -0,0 +1,37 @@
+/**
+ * Stopgap renders: a page that showed an image (or video poster) from a
+ * temporary source, because its stored copy isn't made yet, is marked so the
+ * pack middleware caches it for minutes, not days. The next render, once the
+ * copy exists, uses it. No imports, so tests can load it.
+ */
+
+/** Astro.locals key: this request rendered media whose stored copy is still being made. */
+export const PENDING_MEDIA_LOCAL = "__cwPendingPoster";
+/**
+ * Per isolate: stopgap renders for callers that didn't pass `locals`. The
+ * middleware compares it before and after a render; a concurrent render in the
+ * same isolate can shorten another page's lifetime too, which only costs a
+ * re-render.
+ */
+let pendingRenders = 0;
+
+/** Note that this render used a stopgap for an image or poster whose stored copy isn't made yet. */
+export function markPendingMedia(locals?: object | null): void {
+	if (locals && typeof locals === "object") (locals as Record<string, unknown>)[PENDING_MEDIA_LOCAL] = true;
+	else pendingRenders++;
+}
+
+/** How many stopgap renders this isolate has made without `locals` (see markPendingMedia). */
+export function pendingMediaRenders(): number {
+	return pendingRenders;
+}
+
+/** Whether a request rendered a stopgap: flagged on its locals, or counted since `before`. */
+export function renderedPendingMedia(locals: unknown, before: number): boolean {
+	return Boolean((locals as Record<string, unknown> | undefined)?.[PENDING_MEDIA_LOCAL]) || pendingRenders !== before;
+}
+
+/** Reset the count (tests). */
+export function resetPendingMedia(): void {
+	pendingRenders = 0;
+}

package/src/images/settings.ts

@@ -0,0 +1,48 @@
+/**
+ * The media host saved on the Clean Image URLs page, read outside the plugin
+ * context (theme code, middleware, the page:metadata hook) from D1 in the
+ * feature switches' query, sharing their per-isolate cache. Applied to the
+ * pure helpers in lib.ts, where it overrides the astro.config.mjs option.
+ */
+import { invalidateFeatures, readSiteSetting, registerSiteSetting, rememberSiteSetting, siteSetting } from "../core/features.js";
+import { setSavedImageCdn } from "./lib.js";
+
+/** Plain settings (edited on the Clean Image URLs page). The API token is a secret, declared in src/core/secrets.ts. */
+export const IMAGES_SETTINGS = {
+	host: "imagesMediaHost",
+	accountId: "imagesAccountId",
+	bucket: "imagesBucketName",
+	token: "imagesApiToken",
+	/** Make stored sizes for existing images too (the backfill). Off until an admin turns it on: it costs transformations. */
+	bulk: "imagesVariantsBulk",
+} as const;
+
+registerSiteSetting(IMAGES_SETTINGS.host);
+registerSiteSetting(IMAGES_SETTINGS.bulk);
+let database = "DB";
+
+export function configureMediaHostDatabase(name: string | undefined): void {
+	database = name ?? "DB";
+}
+
+/** Forget the cached value (call after saving it), optionally applying the new one right away. */
+export function invalidateMediaHost(value?: string | null): void {
+	if (value === undefined) {
+		invalidateFeatures();
+		return;
+	}
+	setSavedImageCdn(value);
+	rememberSiteSetting(IMAGES_SETTINGS.host, value);
+}
+
+/** Apply the saved media host (from the feature switches' 30-second cache). Keeps the last value if D1 can't be read. */
+export async function refreshMediaHost(): Promise<void> {
+	const read = await readSiteSetting(IMAGES_SETTINGS.host, database).catch(() => null);
+	// Not on Cloudflare, or no database: the option (if any) stays in use.
+	if (read) setSavedImageCdn(typeof read.value === "string" ? read.value : null);
+}
+
+/** Whether the site turned on stored sizes for existing images (read with the feature switches: no extra query). */
+export async function variantsBulkOn(): Promise<boolean> {
+	return (await siteSetting<boolean>(IMAGES_SETTINGS.bulk, database).catch(() => null)) === true;
+}

package/src/images/setup.ts

@@ -0,0 +1,192 @@
+/**
+ * Media host setup on Cloudflare: the zone's URL-rewrite rules and a pure
+ * planner that compares what's there with what's needed. No I/O and no
+ * imports, so tests can load it directly; the API calls are in cloudflare.ts.
+ *
+ * The three steps, each skipped when already done:
+ *   1. Image Transformations on for the zone (zone setting `transformations`).
+ *   2. The media host as a custom domain on the media bucket (R2).
+ *   3. Two URL-rewrite rules (phase http_request_transform) mapping
+ *      /s/<w>x<h>/<file> and /s/<w>/<file> to /cdn-cgi/image/… on that host.
+ *      Other rules in the phase are kept as they are.
+ */
+
+/** A rule in a ruleset, as the API returns it (only the fields we read or send back). */
+export interface RulesetRule {
+	id?: string;
+	ref?: string;
+	description?: string;
+	expression?: string;
+	action?: string;
+	action_parameters?: Record<string, unknown>;
+	enabled?: boolean;
+	logging?: unknown;
+	[key: string]: unknown;
+}
+
+export interface CustomDomain {
+	domain: string;
+	enabled?: boolean;
+	zoneId?: string;
+	zoneName?: string;
+	status?: { ownership?: string; ssl?: string };
+}
+
+/** What's on Cloudflare now. `rules` is null when the zone has no http_request_transform ruleset yet. */
+export interface SetupState {
+	transformations: string | null;
+	domains: CustomDomain[];
+	rules: RulesetRule[] | null;
+	/** Smart Tiered Cache ("on"/"off"), or null when it couldn't be read (the step then tries to turn it on). */
+	tieredCache?: string | null;
+}
+
+export type StepAction = "none" | "enable" | "add" | "update";
+
+export interface SetupStep {
+	id: "transformations" | "domain" | "rules" | "tieredCache";
+	action: StepAction;
+	/** Plain-language summary, e.g. "Turn on Image Transformations for example.com". */
+	label: string;
+}
+
+export interface SetupPlan {
+	host: string;
+	steps: SetupStep[];
+	/** The full rule list to PUT when the rules step isn't "none" (unrelated rules first, in their order). */
+	rules: RulesetRule[];
+	/** True when nothing needs to change. */
+	done: boolean;
+}
+
+const TAG = "(Coywolf Pack clean image URLs)";
+
+/** The two URL-rewrite rules for a media host name (e.g. "media.example.com"). */
+export function mediaHostRules(hostname: string): RulesetRule[] {
+	const host = `http.host eq "${hostname}"`;
+	return [
+		{
+			description: `${hostname}: /s/<W>x<H>/<file> → cropped resize ${TAG}`,
+			expression: `(${host} and http.request.uri.path wildcard "/s/*x*/*")`,
+			action: "rewrite",
+			action_parameters: {
+				uri: { path: { expression: 'wildcard_replace(http.request.uri.path, "/s/*x*/*", "/cdn-cgi/image/width=${1},height=${2},fit=cover,format=auto,quality=85/${3}")' } },
+			},
+			enabled: true,
+		},
+		{
+			description: `${hostname}: /s/<W>/<file> → resize to width ${TAG}`,
+			expression: `(${host} and http.request.uri.path wildcard "/s/*/*" and not http.request.uri.path wildcard "/s/*x*/*")`,
+			action: "rewrite",
+			action_parameters: {
+				uri: { path: { expression: 'wildcard_replace(http.request.uri.path, "/s/*/*", "/cdn-cgi/image/width=${1},format=auto,quality=85/${2}")' } },
+			},
+			enabled: true,
+		},
+	];
+}
+
+/** Is this one of our rules for `hostname` (matched by description)? */
+export function isOurRule(rule: RulesetRule, hostname: string): boolean {
+	const d = rule.description ?? "";
+	return d.startsWith(`${hostname}: `) && d.endsWith(TAG);
+}
+
+/** Fields the API accepts back for a rule we keep (it rejects or ignores read-only ones like version and last_updated). */
+const KEEP_FIELDS = ["id", "ref", "action", "action_parameters", "description", "enabled", "expression", "logging", "ratelimit", "exposed_credential_check"];
+
+export function sendableRule(rule: RulesetRule): RulesetRule {
+	const out: RulesetRule = {};
+	for (const key of KEEP_FIELDS) if (rule[key] !== undefined) out[key] = rule[key];
+	return out;
+}
+
+const pathExpression = (rule: RulesetRule) =>
+	((rule.action_parameters as { uri?: { path?: { expression?: string } } } | undefined)?.uri?.path?.expression ?? "").trim();
+
+function sameRule(a: RulesetRule, b: RulesetRule): boolean {
+	return (
+		a.description === b.description &&
+		(a.expression ?? "").trim() === (b.expression ?? "").trim() &&
+		a.action === b.action &&
+		pathExpression(a) === pathExpression(b) &&
+		a.enabled !== false
+	);
+}
+
+/** The host name of a media host origin or bare name ("https://media.example.com" → "media.example.com"). */
+export function hostnameOf(host: string): string {
+	return host.replace(/^https?:\/\//i, "").replace(/\/.*$/, "").toLowerCase();
+}
+
+/**
+ * Zone names to try for a host, most specific first: media.blog.example.co.uk →
+ * blog.example.co.uk, example.co.uk, co.uk. (The API answers only for zones
+ * in the account, so the first match is the zone.)
+ */
+export function zoneCandidates(hostname: string): string[] {
+	const labels = hostname.split(".");
+	const out: string[] = [];
+	for (let i = 1; i < labels.length - 1; i++) out.push(labels.slice(i).join("."));
+	return out;
+}
+
+/** Compare the current state with what the media host needs. */
+export function planMediaHostSetup(state: SetupState, input: { host: string; zoneName: string; bucket: string }): SetupPlan {
+	const hostname = hostnameOf(input.host);
+	const steps: SetupStep[] = [];
+
+	steps.push(
+		state.transformations === "on"
+			? { id: "transformations", action: "none", label: `Image Transformations are already on for ${input.zoneName}.` }
+			: { id: "transformations", action: "enable", label: `Turn on Image Transformations for ${input.zoneName}.` },
+	);
+
+	const domain = state.domains.find((d) => d.domain.toLowerCase() === hostname);
+	steps.push(
+		!domain
+			? { id: "domain", action: "add", label: `Connect ${hostname} to the R2 bucket ${input.bucket} as a custom domain.` }
+			: domain.enabled === false
+				? { id: "domain", action: "enable", label: `Turn on ${hostname}, already connected to the R2 bucket ${input.bucket}.` }
+				: { id: "domain", action: "none", label: `${hostname} is already connected to the R2 bucket ${input.bucket}.` },
+	);
+
+	const wanted = mediaHostRules(hostname);
+	const existing = state.rules ?? [];
+	const ours = existing.filter((r) => isOurRule(r, hostname));
+	const upToDate = ours.length === wanted.length && wanted.every((w) => ours.some((o) => sameRule(o, w)));
+	let rules: RulesetRule[] = [];
+	if (upToDate) {
+		steps.push({ id: "rules", action: "none", label: `The 2 URL rewrite rules for ${hostname} are already in place.` });
+	} else {
+		// Keep every unrelated rule where it is; ours go where the first old one of ours was, or at the end.
+		const firstOurs = existing.findIndex((r) => isOurRule(r, hostname));
+		const others = existing.filter((r) => !isOurRule(r, hostname)).map(sendableRule);
+		const at = firstOurs === -1 ? others.length : existing.slice(0, firstOurs).filter((r) => !isOurRule(r, hostname)).length;
+		rules = [...others.slice(0, at), ...wanted, ...others.slice(at)];
+		steps.push(
+			ours.length
+				? { id: "rules", action: "update", label: `Update the URL rewrite rules for ${hostname} (other rules stay as they are).` }
+				: {
+						id: "rules",
+						action: "add",
+						label: `Add 2 URL rewrite rules for ${hostname}${others.length ? ` (the zone's ${others.length} other rule${others.length === 1 ? "" : "s"} stay as they are)` : ""}.`,
+					},
+		);
+	}
+
+	// Smart Tiered Cache: a data center that hasn't cached an image yet asks a nearby upper-tier
+	// Cloudflare cache (placed near the R2 bucket) before going back to R2. Free on every plan.
+	// (Pages don't need it: Workers Cache is always tiered.) Only ever turned on, never off.
+	steps.push(
+		state.tieredCache === "on"
+			? { id: "tieredCache", action: "none", label: `Smart Tiered Cache is already on for ${input.zoneName}.` }
+			: {
+					id: "tieredCache",
+					action: "enable",
+					label: `Turn on Smart Tiered Cache for ${input.zoneName}, so a data center that hasn't cached an image yet gets it from a nearby Cloudflare cache instead of R2.`,
+				},
+	);
+
+	return { host: hostname, steps, rules, done: steps.every((s) => s.action === "none") };
+}

package/src/images/variants-estimate.ts

@@ -0,0 +1,162 @@
+/**
+ * Cost estimate for stored image sizes (Clean Image URLs page): what making
+ * them for the existing library costs once, what storing them costs a month,
+ * and what serving the same sizes through the media host's /s/ resizing would
+ * cost a month instead. Pure functions (the admin page computes everything
+ * after one fetch); they plan each image with the generator's own rules.
+ *
+ * Cloudflare bills a "unique transformation" once per calendar month per
+ * image and set of options: 5,000 free a month, then $0.50 per 1,000 (Images
+ * Paid). For /s/ URLs the format is chosen per visitor (format=auto), which
+ * counts once, so each size of each image costs one transformation a month.
+ * A stored size is made once with explicit formats: WebP and AVIF count as
+ * two (AVIF isn't made beyond 1,200 pixels, so those sizes count once).
+ */
+import { avifEncoded, eligible, plannedWidths, scaledHeight } from "./variants.js";
+
+export const PRICE_PER_TRANSFORM = 0.5 / 1000;
+export const FREE_TRANSFORMS = 5000;
+/** R2 Standard storage, per GB-month (10 GB a month are free). */
+export const R2_PER_GB_MONTH = 0.015;
+/** Rough average file size of one stored copy (WebP or AVIF) at each width, in bytes. */
+export const AVERAGE_FILE_BYTES: Record<number, number> = { 400: 25_000, 640: 50_000, 800: 75_000, 1200: 140_000, 1600: 230_000 };
+/** Different sizes of one image a visitor's device typically asks for (phones, tablets, desktops). */
+export const SIZES_PER_VISITED_IMAGE = 3;
+/** Share of a site's pages that search engines fetch in a month (an assumption). */
+export const CRAWLED_SHARE = 0.8;
+
+/** What storing one image's widths takes: sizes, files, one-time transformations, and bytes. */
+export function planImage(width: number, height: number | null | undefined): { sizes: number; files: number; transforms: number; bytes: number } {
+	const widths = plannedWidths(width);
+	let transforms = 0;
+	let bytes = 0;
+	for (const w of widths) {
+		transforms += avifEncoded(w, scaledHeight(w, width, height)) ? 2 : 1;
+		bytes += 2 * (AVERAGE_FILE_BYTES[w] ?? 100_000);
+	}
+	return { sizes: widths.length, files: widths.length * 2, transforms, bytes };
+}
+
+export interface LibraryRow {
+	mime_type: string | null;
+	width: number | null;
+	height: number | null;
+	size: number | null;
+	/** 1 when the image already has its stored sizes. */
+	current: number;
+}
+
+export interface LibrarySummary {
+	/** Images that can get stored sizes. */
+	images: number;
+	/** Of those, how many already have them. */
+	done: number;
+	/** Sizes (widths) of all eligible images: what /s/ could be asked for each month. */
+	sizes: number;
+	/** Files stored for all eligible images (two per size). */
+	files: number;
+	/** Bytes stored for all eligible images (about). */
+	bytes: number;
+	/** One-time transformations still to make (images without their sizes yet). */
+	transforms: number;
+	/** Files still to make. */
+	filesLeft: number;
+}
+
+export function summarizeLibrary(rows: LibraryRow[]): LibrarySummary {
+	const out: LibrarySummary = { images: 0, done: 0, sizes: 0, files: 0, bytes: 0, transforms: 0, filesLeft: 0 };
+	for (const row of rows) {
+		if (!eligible(row.mime_type, row.width, row.size)) continue;
+		const plan = planImage(row.width as number, row.height);
+		out.images++;
+		out.sizes += plan.sizes;
+		out.files += plan.files;
+		out.bytes += plan.bytes;
+		if (row.current) out.done++;
+		else {
+			out.transforms += plan.transforms;
+			out.filesLeft += plan.files;
+		}
+	}
+	return out;
+}
+
+/** Cost of transformations made in one month: `free` of them are free (0 when the month's free ones are already used). */
+export function transformCost(transforms: number, free = FREE_TRANSFORMS): number {
+	return Math.max(0, transforms - free) * PRICE_PER_TRANSFORM;
+}
+
+/** The one-time fee: from "all 5,000 free ones still available" to "none left this month". */
+export function oneTimeCost(transforms: number): { min: number; max: number } {
+	return { min: transformCost(transforms), max: transformCost(transforms, 0) };
+}
+
+/** Storage a month for `bytes` (before R2's free 10 GB). */
+export function storageCost(bytes: number): number {
+	return (bytes / 1e9) * R2_PER_GB_MONTH;
+}
+
+export interface TrafficInput {
+	/** Page views a month. */
+	views: number;
+	/** Published pages. */
+	pages: number;
+	/** Images that can get stored sizes. */
+	images: number;
+	/** Sizes those images have in total (summary.sizes). */
+	sizes: number;
+	/** Bytes of all stored sizes (summary.bytes). */
+	bytes: number;
+	/** Search engines fetch most pages each month. */
+	crawlers: boolean;
+}
+
+export interface TrafficEstimate {
+	/** Different pages visited in a month. */
+	pagesVisited: number;
+	/** Different images shown in a month. */
+	imagesShown: number;
+	/** Transformations a month without stored sizes (each size shown, plus one Open Graph image per page). */
+	withoutTransforms: number;
+	withoutCost: number;
+	/** Transformations a month with stored sizes (only the Open Graph image per page). */
+	withTransforms: number;
+	/** Their cost plus storage. */
+	withCost: number;
+	/** Saved a month. */
+	savings: number;
+}
+
+/**
+ * A month of traffic, roughly: with V views spread evenly over P pages, about
+ * P × (1 − e^(−V/P)) different pages are seen (real traffic favors some pages,
+ * so fewer); search engines that crawl the site fetch at least 80% of them.
+ * Images are spread evenly over pages; each image shown is asked for in about
+ * three sizes (fewer when it has fewer).
+ */
+export function trafficEstimate(input: TrafficInput): TrafficEstimate {
+	const pages = Math.max(0, input.pages);
+	const views = Math.max(0, input.views);
+	let pagesVisited = pages ? pages * (1 - Math.exp(-views / pages)) : 0;
+	if (input.crawlers) pagesVisited = Math.max(pagesVisited, CRAWLED_SHARE * pages);
+	pagesVisited = Math.round(Math.min(pages, pagesVisited));
+	const imagesShown = pages ? Math.round(Math.min(input.images, (input.images * pagesVisited) / pages)) : 0;
+	const perImage = input.images ? Math.min(SIZES_PER_VISITED_IMAGE, input.sizes / input.images) : 0;
+	const withTransforms = pagesVisited;
+	const withoutTransforms = Math.round(imagesShown * perImage) + pagesVisited;
+	const withoutCost = transformCost(withoutTransforms);
+	const withCost = transformCost(withTransforms) + storageCost(input.bytes);
+	return { pagesVisited, imagesShown, withoutTransforms, withoutCost, withTransforms, withCost, savings: withoutCost - withCost };
+}
+
+/** Months until the one-time fee is paid back by `savings` a month: 1 means the first month; null when it never is. */
+export function paybackMonths(oneTime: number, savings: number): number | null {
+	if (oneTime <= 0) return 1;
+	if (savings <= 0) return null;
+	return Math.max(1, Math.ceil(oneTime / savings));
+}
+
+/** Most a month without stored sizes: every size of every image asked for once that month. */
+export function monthlyWithoutMax(sizes: number): number {
+	return transformCost(sizes);
+}