@postedin/cms-client 0.1.0

package/bin/profile/measure.mjs

@@ -0,0 +1,137 @@
+/**
+ * Reading a profile log, and counting what is in it.
+ *
+ * Both profilers write NDJSON where every record carries a `kind`, and both
+ * reports then ask the same three kinds of question of it: group these records,
+ * rank these numbers, and work out how many requests were open at once. This
+ * is that, once, so `summarize.mjs` and `interference-summary.mjs` cannot drift
+ * apart on the answers.
+ *
+ * Pure. The markdown these numbers end up in is `format.mjs`.
+ */
+
+/**
+ * Every record in an NDJSON log, in order.
+ *
+ * A process killed mid-write leaves a partial last line, and a line that does
+ * not parse is skipped rather than thrown: everything before it is still worth
+ * reading.
+ */
+export function parseNdjson(text) {
+	const records = [];
+
+	for (const line of text.split('\n')) {
+		const trimmed = line.trim();
+
+		if (!trimmed) {
+			continue;
+		}
+
+		try {
+			records.push(JSON.parse(trimmed));
+		} catch {
+			continue;
+		}
+	}
+
+	return records;
+}
+
+export function sum(values) {
+	return values.reduce(
+		(total, value) => total + (typeof value === 'number' ? value : 0),
+		0,
+	);
+}
+
+export function max(values) {
+	return values.reduce(
+		(highest, value) =>
+			typeof value === 'number' && value > highest ? value : highest,
+		0,
+	);
+}
+
+export function group(items, keyOf) {
+	const groups = new Map();
+
+	for (const item of items) {
+		const key = keyOf(item);
+		const existing = groups.get(key);
+
+		if (existing) {
+			existing.members.push(item);
+		} else {
+			groups.set(key, { key, members: [item] });
+		}
+	}
+
+	return groups;
+}
+
+/**
+ * Nearest-rank percentile: the smallest sample at or above the requested
+ * share of the distribution, with no interpolation between two samples.
+ *
+ * A poll run produces tens of samples, not thousands, so an interpolated p95
+ * would be a number that was never measured. This returns one that was.
+ */
+export function percentile(values, share) {
+	const sorted = values
+		.filter((value) => typeof value === 'number')
+		.sort((a, b) => a - b);
+
+	if (!sorted.length) {
+		return null;
+	}
+
+	const rank = Math.ceil(share * sorted.length);
+
+	return sorted[Math.min(Math.max(rank, 1), sorted.length) - 1];
+}
+
+/**
+ * A set of requests as a sorted stream of open and close events, ready to
+ * sweep for how many were in flight at once.
+ *
+ * `from` and `to` clamp the events to a span, so a caller asking about one
+ * moment of a build gets the level inside it rather than the level overall. A
+ * request that closed before the span opened is dropped entirely.
+ */
+export function flightEvents(
+	requests,
+	{ from = -Infinity, to = Infinity } = {},
+) {
+	const events = [];
+
+	for (const request of requests) {
+		const startedAt = request.startedAt;
+		const endedAt = request.endedAt ?? request.startedAt;
+
+		if (typeof startedAt !== 'number' || endedAt < from || startedAt > to) {
+			continue;
+		}
+
+		events.push({ at: Math.max(startedAt, from), delta: 1 });
+		events.push({ at: Math.min(endedAt, to), delta: -1 });
+	}
+
+	// At an identical timestamp, close before opening: two requests that merely
+	// touch at millisecond resolution were not in flight together.
+	events.sort((a, b) => a.at - b.at || a.delta - b.delta);
+
+	return events;
+}
+
+/** The most requests open at once anywhere in `[from, to]`. */
+export function peakInFlight(requests, from, to) {
+	let level = 0;
+	let peak = 0;
+
+	for (const event of flightEvents(requests, { from, to })) {
+		level += event.delta;
+		peak = Math.max(peak, level);
+	}
+
+	return peak;
+}

package/bin/profile/report.mjs

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+/**
+ * Renders a fetch log as Markdown.
+ *
+ *   cms-profile-report                      # newest log in .astro/profile
+ *   cms-profile-report path/to/log.ndjson
+ *   cms-profile-report log.ndjson --out report.md
+ *
+ * `pnpm build:profile` calls `writeReport` directly once its build finishes;
+ * this entry point exists to re-render a log without rebuilding, and to render
+ * one collected somewhere else.
+ */
+
+import {
+	existsSync,
+	readdirSync,
+	readFileSync,
+	realpathSync,
+	statSync,
+	writeFileSync,
+} from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseLog, renderMarkdown, summarize } from './summarize.mjs';
+
+export const LOG_DIR = join('.astro', 'profile');
+
+/** Renders `logPath` and writes the Markdown, returning where it landed. */
+export function writeReport(logPath, outPath = defaultOutPath(logPath)) {
+	const { requests, meta } = parseLog(readFileSync(logPath, 'utf-8'));
+
+	const markdown = renderMarkdown(summarize({ requests, meta }), {
+		logPath,
+		generatedAt: new Date().toISOString(),
+	});
+
+	writeFileSync(outPath, markdown);
+
+	return outPath;
+}
+
+/** The most recently written `.ndjson` in `dir`, or null if there is none. */
+export function newestLog(dir = LOG_DIR) {
+	if (!existsSync(dir)) {
+		return null;
+	}
+
+	const logs = readdirSync(dir)
+		.filter((name) => name.endsWith('.ndjson'))
+		.map((name) => join(dir, name))
+		.map((path) => ({ path, at: statSync(path).mtimeMs }))
+		.sort((a, b) => b.at - a.at);
+
+	return logs.length ? logs[0].path : null;
+}
+
+function defaultOutPath(logPath) {
+	return join(
+		dirname(logPath),
+		`${basename(logPath).replace(/\.ndjson$/, '')}.md`,
+	);
+}
+
+function main(argv) {
+	const out = argv.indexOf('--out');
+	const outPath = out === -1 ? undefined : argv[out + 1];
+	const positional = (out === -1 ? argv : argv.slice(0, out)).filter(
+		(argument) => !argument.startsWith('-'),
+	);
+
+	const logPath = positional[0] ?? newestLog();
+
+	if (!logPath) {
+		console.error(
+			`No fetch log found in ${LOG_DIR}. Run \`pnpm build:profile\` first.`,
+		);
+		process.exit(1);
+	}
+
+	console.log(writeReport(logPath, outPath));
+}
+
+// Through a package bin, `argv[1]` is the path via the site's `node_modules`
+// symlink while `import.meta.url` is the real one, so compare real paths.
+if (
+	process.argv[1] &&
+	realpathSync(resolve(process.argv[1])) === fileURLToPath(import.meta.url)
+) {
+	main(process.argv.slice(2));
+}

package/bin/profile/site-env.mjs

@@ -0,0 +1,16 @@
+import { createRequire } from 'node:module';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+/**
+ * The site's environment, resolved by the site's own Vite, in the directory the
+ * command was run from. The profilers run inside a site but ship in this
+ * package, and the package does not depend on Vite: reading the env files any
+ * other way could resolve a different value than the build about to be profiled.
+ */
+export async function loadSiteEnv(mode) {
+	const require = createRequire(join(process.cwd(), 'package.json'));
+	const { loadEnv } = await import(pathToFileURL(require.resolve('vite')).href);
+
+	return loadEnv(mode, process.cwd(), '');
+}

package/bin/profile/summarize.mjs

@@ -0,0 +1,429 @@
+/**
+ * Turns a fetch log into a report.
+ *
+ * Pure functions over the NDJSON written by `fetch-log.mjs`: no file system, no
+ * clock, no argv, so the whole thing can be checked against a fixture. The CLI
+ * that reads and writes files is `report.mjs`.
+ *
+ * Three questions shape what gets computed, in the order they are worth asking:
+ *
+ * 1. How much does a build ask for at all — requests, bytes, time.
+ * 2. How much of it arrives at once, which is what the CMS feels.
+ * 3. How much of it was already asked for, which is what a missing cache looks
+ *    like from the outside.
+ */
+
+import {
+	bar,
+	bullets,
+	count,
+	duration,
+	escapePipes,
+	offsetSeconds,
+	share,
+	size,
+	table,
+} from './format.mjs';
+import { flightEvents, group, max, parseNdjson, sum } from './measure.mjs';
+
+const TIMELINE_BUCKETS = 24;
+
+/** How many of the build's costliest CMS requests to name individually. */
+const SLOWEST_REQUESTS = 10;
+
+export function parseLog(text) {
+	const requests = [];
+	const meta = [];
+
+	for (const record of parseNdjson(text)) {
+		if (record.kind === 'request') {
+			requests.push(record);
+		} else if (record.kind === 'meta') {
+			meta.push(record);
+		}
+	}
+
+	return { requests, meta };
+}
+
+export function summarize({ requests, meta }) {
+	const cms = requests.filter((request) => request.cms);
+	const other = requests.filter((request) => !request.cms);
+	const window = timeWindow(requests, meta);
+
+	return {
+		cmsOrigin: meta.find((record) => record.cmsOrigin)?.cmsOrigin ?? null,
+		window,
+		totals: {
+			requests: requests.length,
+			cmsRequests: cms.length,
+			otherRequests: other.length,
+			wallMs: window.endedAt - window.startedAt,
+			requestMs: sum(requests.map((request) => request.durationMs)),
+			cmsRequestMs: sum(cms.map((request) => request.durationMs)),
+			bytes: sum(requests.map((request) => request.bytes)),
+			cmsBytes: sum(cms.map((request) => request.bytes)),
+			failed: requests.filter((request) => !isOk(request)).length,
+		},
+		collections: collectionRows(cms),
+		concurrency: concurrency(requests, window),
+		// Fonts and remote images arrive in one burst that dwarfs anything the
+		// CMS is asked, so the overall peak says nothing about the CMS. This is
+		// the number the CMS feels.
+		cmsConcurrency: concurrency(cms, window),
+		repeated: repeatedRows(cms),
+		slowest: slowestRows(cms, window),
+		hosts: hostRows(other),
+	};
+}
+
+/**
+ * The CMS requests that cost the most, each with the CMS's own id for it.
+ *
+ * A collection row says where a build's time went; this says which single
+ * request to go and read. `profileId` is the `x-cms-profile-id` a deployment
+ * running with `CMS_PROFILE=1` returns, and it is the whole point of the row:
+ * without it a slow request is a duration, and with it the CMS can be asked
+ * what the time was spent on.
+ */
+function slowestRows(requests, window) {
+	return [...requests]
+		.filter((request) => typeof request.durationMs === 'number')
+		.sort((a, b) => b.durationMs - a.durationMs)
+		.slice(0, SLOWEST_REQUESTS)
+		.map((request) => ({
+			atMs: (request.startedAt ?? window.startedAt) - window.startedAt,
+			collection: request.collection ?? request.path ?? '-',
+			locale: request.locale ?? '-',
+			depth: request.depth ?? '-',
+			page: request.page ?? '-',
+			durationMs: request.durationMs,
+			status: request.status ?? null,
+			profileId: request.profileId ?? null,
+		}));
+}
+
+/**
+ * CMS requests grouped the way the CMS sees them: which collection, in which
+ * locale, at which depth. Ordered by the time they cost, because that is the
+ * column a reader is looking for.
+ */
+function collectionRows(requests) {
+	const rows = group(requests, (request) =>
+		[
+			request.collection ?? request.path ?? '-',
+			request.locale ?? '-',
+			request.depth ?? '-',
+		].join(' '),
+	);
+
+	return [...rows.values()]
+		.map(({ key, members }) => {
+			const [collection, locale, depth] = key.split(' ');
+
+			return {
+				collection,
+				locale,
+				depth,
+				count: members.length,
+				totalMs: sum(members.map((request) => request.durationMs)),
+				maxMs: max(members.map((request) => request.durationMs)),
+				bytes: sum(members.map((request) => request.bytes)),
+			};
+		})
+		.sort((a, b) => b.totalMs - a.totalMs || b.count - a.count);
+}
+
+/**
+ * The peak number of requests in flight, and where in the build the overlap
+ * sits. Wall time is cut into fixed buckets and each one reports the highest
+ * level reached inside it, so a single burst stays visible instead of being
+ * averaged away.
+ */
+function concurrency(requests, window) {
+	const events = flightEvents(requests);
+
+	const wallMs = Math.max(window.endedAt - window.startedAt, 1);
+	const bucketCount = Math.min(TIMELINE_BUCKETS, Math.max(wallMs, 1));
+	const width = wallMs / bucketCount;
+
+	let level = 0;
+	let peak = 0;
+	let cursor = 0;
+	const timeline = [];
+
+	for (let bucket = 0; bucket < bucketCount; bucket += 1) {
+		const startMs = bucket * width;
+		const endMs = bucket === bucketCount - 1 ? wallMs : startMs + width;
+		let bucketPeak = level;
+
+		while (
+			cursor < events.length &&
+			events[cursor].at - window.startedAt < endMs
+		) {
+			level += events[cursor].delta;
+			bucketPeak = Math.max(bucketPeak, level);
+			peak = Math.max(peak, level);
+			cursor += 1;
+		}
+
+		timeline.push({ startMs, endMs, peak: bucketPeak });
+	}
+
+	// Whatever is left is an event landing exactly on the end of the window.
+	while (cursor < events.length) {
+		level += events[cursor].delta;
+		peak = Math.max(peak, level);
+		cursor += 1;
+	}
+
+	return { peak, timeline };
+}
+
+/**
+ * Requests a build made more than once with the same question: same collection,
+ * same locale, same page, same `where`. One of these per generated page is the
+ * signature of a fetch that should have been cached and was not.
+ */
+function repeatedRows(requests) {
+	const rows = group(requests, (request) =>
+		[
+			request.collection ?? request.path ?? '-',
+			request.locale ?? '-',
+			request.page ?? '-',
+			request.whereHash ?? request.where ?? '-',
+		].join(' '),
+	);
+
+	return [...rows.values()]
+		.filter(({ members }) => members.length > 1)
+		.map(({ key, members }) => {
+			const [collection, locale, page] = key.split(' ');
+
+			return {
+				collection,
+				locale,
+				page,
+				where: members[0].where ?? null,
+				count: members.length,
+				totalMs: sum(members.map((request) => request.durationMs)),
+			};
+		})
+		.sort((a, b) => b.count - a.count || b.totalMs - a.totalMs);
+}
+
+/** Everything that was not the CMS - fonts, media, image sources - by host. */
+function hostRows(requests) {
+	const rows = group(requests, (request) => request.host ?? '-');
+
+	return [...rows.values()]
+		.map(({ key, members }) => ({
+			host: key,
+			count: members.length,
+			totalMs: sum(members.map((request) => request.durationMs)),
+			bytes: sum(members.map((request) => request.bytes)),
+		}))
+		.sort((a, b) => b.count - a.count);
+}
+
+/**
+ * The span the report covers. Meta records bracket the process, but a log
+ * missing them - a build killed before exit, or a hand-run preload - still has
+ * request timestamps to fall back on.
+ */
+function timeWindow(requests, meta) {
+	const starts = [
+		...meta.map((record) => record.startedAt),
+		...requests.map((request) => request.startedAt),
+	].filter((value) => typeof value === 'number');
+
+	const ends = [
+		...meta.map((record) => record.endedAt),
+		...requests.map((request) => request.endedAt ?? request.startedAt),
+	].filter((value) => typeof value === 'number');
+
+	const startedAt = starts.length ? Math.min(...starts) : 0;
+	const endedAt = ends.length ? Math.max(...ends) : startedAt;
+
+	return { startedAt, endedAt };
+}
+
+/** A request the CMS answered, as opposed to one it refused or never saw. */
+function isOk(request) {
+	return (
+		typeof request.status === 'number' &&
+		request.status >= 200 &&
+		request.status < 400
+	);
+}
+
+/**
+ * Why a log holds no CMS request — which is two different facts.
+ *
+ * A request is only the CMS's because its origin matched the one the profiler
+ * was given, so an origin that never resolved moves every request the build
+ * made into "other hosts" and leaves this section empty. That reads exactly
+ * like a build that never called the CMS, and is a misconfigured profiler
+ * rather than a finding, so it has to be said in the report and not only in
+ * the terminal the run scrolled past.
+ */
+function noCmsRequests(summary, { brief = false } = {}) {
+	if (summary.cmsOrigin) {
+		return 'No CMS requests in this log.';
+	}
+
+	return brief
+		? 'No CMS origin was configured, so nothing could be recognised as the CMS.'
+		: 'No CMS origin was configured, so nothing could be recognised as the CMS and every request is counted under Other hosts. Set `API_BASE_URL`, or `PROFILE_CMS_ORIGIN` to profile against another origin.';
+}
+
+export function renderMarkdown(summary, { logPath, generatedAt } = {}) {
+	const { totals, concurrency: overlap } = summary;
+
+	const lines = [
+		'# Build fetch profile',
+		'',
+		...bullets([
+			['Log', logPath ? `\`${logPath}\`` : null],
+			['Generated', generatedAt ?? null],
+			['CMS origin', summary.cmsOrigin ? `\`${summary.cmsOrigin}\`` : null],
+			[
+				'Build started',
+				summary.window.startedAt
+					? new Date(summary.window.startedAt).toISOString()
+					: null,
+			],
+		]),
+		'',
+		'## Totals',
+		'',
+		...table(
+			['Metric', 'Value'],
+			[
+				['Build wall time', duration(totals.wallMs)],
+				['Requests', count(totals.requests)],
+				['To the CMS', count(totals.cmsRequests)],
+				['Elsewhere', count(totals.otherRequests)],
+				['Failed or errored', count(totals.failed)],
+				[
+					'Summed request time',
+					`${duration(totals.requestMs)} (${share(totals.requestMs, totals.wallMs)} of wall time)`,
+				],
+				['Summed CMS request time', duration(totals.cmsRequestMs)],
+				['Peak requests in flight', count(overlap.peak)],
+				['Peak CMS requests in flight', count(summary.cmsConcurrency.peak)],
+				['Response bytes', size(totals.bytes)],
+				['Response bytes from the CMS', size(totals.cmsBytes)],
+			],
+		),
+		'',
+		'## CMS requests by collection',
+		'',
+		...(summary.collections.length
+			? table(
+					['Collection', 'Locale', 'Depth', 'Requests', 'Total', 'Max', 'Size'],
+					summary.collections.map((row) => [
+						`\`${row.collection}\``,
+						row.locale,
+						row.depth,
+						count(row.count),
+						duration(row.totalMs),
+						duration(row.maxMs),
+						size(row.bytes),
+					]),
+				)
+			: [noCmsRequests(summary)]),
+		'',
+		'## Slowest CMS requests',
+		'',
+		...(summary.slowest.length
+			? [
+					...table(
+						[
+							'At',
+							'Collection',
+							'Locale',
+							'Depth',
+							'Page',
+							'Duration',
+							'CMS profile id',
+						],
+						summary.slowest.map((row) => [
+							offsetSeconds(row.atMs),
+							`\`${row.collection}\``,
+							row.locale,
+							row.depth,
+							row.page,
+							duration(row.durationMs),
+							row.profileId ? `\`${row.profileId}\`` : '-',
+						]),
+					),
+					'',
+					...(summary.slowest.some((row) => row.profileId)
+						? [
+								'Each id is one `cms.profile.request` line on the CMS, so a row here can be opened into the commands and hooks that produced it.',
+							]
+						: [
+								'No response carried `x-cms-profile-id`, so these are durations with nothing behind them. Run the target with `CMS_PROFILE=1` to join them to the CMS’s own lines.',
+							]),
+				]
+			: [noCmsRequests(summary, { brief: true })]),
+		'',
+		'## Concurrency',
+		'',
+		`Peak: **${count(overlap.peak)}** request${overlap.peak === 1 ? '' : 's'} in flight at once, and **${count(summary.cmsConcurrency.peak)}** counting only the CMS.`,
+		'',
+		...table(
+			['Window', 'Peak in flight', 'Peak at the CMS', 'CMS overlap'],
+			overlap.timeline.map((bucket, index) => {
+				// Scaled to the CMS peak, not the overall one: one burst of fonts
+				// would otherwise flatten every bar that matters into nothing.
+				const cmsPeak = summary.cmsConcurrency.timeline[index]?.peak ?? 0;
+
+				return [
+					`${offsetSeconds(bucket.startMs)} to ${offsetSeconds(bucket.endMs)}`,
+					count(bucket.peak),
+					count(cmsPeak),
+					bar(cmsPeak, summary.cmsConcurrency.peak),
+				];
+			}),
+		),
+		'',
+		'## Repeated requests',
+		'',
+		...(summary.repeated.length
+			? [
+					'Same collection, locale, page and `where`, asked more than once.',
+					'',
+					...table(
+						['Collection', 'Locale', 'Page', 'Times', 'Total', 'Where'],
+						summary.repeated.map((row) => [
+							`\`${row.collection}\``,
+							row.locale,
+							row.page,
+							count(row.count),
+							duration(row.totalMs),
+							row.where ? `\`${escapePipes(row.where)}\`` : '-',
+						]),
+					),
+				]
+			: ['Nothing was requested twice.']),
+		'',
+		'## Other hosts',
+		'',
+		...(summary.hosts.length
+			? table(
+					['Host', 'Requests', 'Total', 'Size'],
+					summary.hosts.map((row) => [
+						`\`${row.host}\``,
+						count(row.count),
+						duration(row.totalMs),
+						size(row.bytes),
+					]),
+				)
+			: ['Every request went to the CMS.']),
+		'',
+	];
+
+	return `${lines.join('\n')}\n`;
+}