@postedin/cms-client 0.1.0

package/bin/profile/fetch-log.mjs

@@ -0,0 +1,298 @@
+/**
+ * Logs every HTTP request a build makes, one NDJSON line per request.
+ *
+ * Loaded into a build process with `--import`, before anything else runs, so
+ * the wrapper is in place for config-time fetches (`astro.config.mjs` resolves
+ * redirects, project settings and the favicon before the build starts) as well
+ * as for the ones pages make while they render. Astro builds in a single Node
+ * process, so one wrapper sees both.
+ *
+ * Nothing here is wired into `pnpm build`. `build.mjs` beside this file is what
+ * loads it, and it is what sets the two variables read below:
+ *
+ * - `PROFILE_FETCH_LOG`   where to append. Defaults to `.astro/profile/fetch.ndjson`.
+ * - `PROFILE_CMS_ORIGIN`  the origin that counts as the CMS, so a request can
+ *                         be told apart from a font or a media file. Falls back
+ *                         to `API_BASE_URL` if that happens to be exported.
+ *
+ * Requests are logged when their body finishes arriving, not when their headers
+ * do, so the file is ordered by completion and a request still in flight when
+ * the process exits never gets a line. The `end` meta record counts those.
+ */
+
+import { createHash } from 'node:crypto';
+import { appendFileSync, mkdirSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+
+/** A `where` clause is unbounded; keep the log readable and hash the rest. */
+const WHERE_MAX = 300;
+
+/**
+ * The CMS's own id for the request it just served.
+ *
+ * A deployment running with `CMS_PROFILE=1` logs one `cms.profile.request`
+ * line per request and echoes that line's `id` back on this header. Recording
+ * it is the only way to join a request logged here to the commands and hooks
+ * it caused on the other side; without it the two halves are two lists of
+ * timings that happen to be about the same build. The name is
+ * `PROFILE_ID_HEADER` in the CMS's `src/profiling/requestProfile.ts`.
+ *
+ * It is absent whenever the target is not profiling, which is the normal case,
+ * so a null here is information rather than a fault.
+ */
+const PROFILE_ID_HEADER = 'x-cms-profile-id';
+
+/** Above this declared size, trust `content-length` rather than buffer a copy. */
+const CLONE_LIMIT = 8 * 1024 * 1024;
+
+const logPath = resolve(
+	process.env.PROFILE_FETCH_LOG || join('.astro', 'profile', 'fetch.ndjson'),
+);
+
+const cmsOrigin = originOf(
+	process.env.PROFILE_CMS_ORIGIN || process.env.API_BASE_URL,
+);
+
+const startedAt = Date.now();
+let requests = 0;
+let pending = 0;
+
+mkdirSync(dirname(logPath), { recursive: true });
+
+writeLine({
+	kind: 'meta',
+	event: 'start',
+	pid: process.pid,
+	startedAt,
+	cmsOrigin,
+});
+
+const original = globalThis.fetch;
+
+globalThis.fetch = function profilingFetch(input, init) {
+	const seq = ++requests;
+	const requestStartedAt = Date.now();
+	const mark = performance.now();
+	const shape = describeRequest(urlOf(input), methodOf(input, init));
+
+	pending += 1;
+
+	return original(input, init).then(
+		(response) => {
+			const ttfbMs = round(performance.now() - mark);
+
+			countBytes(response).then((bytes) => {
+				pending -= 1;
+				writeLine({
+					kind: 'request',
+					seq,
+					...shape,
+					status: response.status,
+					profileId: response.headers.get(PROFILE_ID_HEADER),
+					startedAt: requestStartedAt,
+					endedAt: Date.now(),
+					ttfbMs,
+					durationMs: round(performance.now() - mark),
+					bytes,
+				});
+			});
+
+			return response;
+		},
+		(error) => {
+			pending -= 1;
+			writeLine({
+				kind: 'request',
+				seq,
+				...shape,
+				status: null,
+				profileId: null,
+				error: String(error?.message ?? error),
+				startedAt: requestStartedAt,
+				endedAt: Date.now(),
+				ttfbMs: null,
+				durationMs: round(performance.now() - mark),
+				bytes: null,
+			});
+
+			throw error;
+		},
+	);
+};
+
+process.on('exit', () => {
+	const endedAt = Date.now();
+
+	writeLine({
+		kind: 'meta',
+		event: 'end',
+		pid: process.pid,
+		endedAt,
+		wallMs: endedAt - startedAt,
+		requests,
+		pending,
+	});
+});
+
+function writeLine(record) {
+	try {
+		appendFileSync(logPath, `${JSON.stringify(record)}\n`);
+	} catch (error) {
+		// A profiler must never be the reason a build fails.
+		process.emitWarning(
+			`fetch-log: could not append to ${logPath}: ${error.message}`,
+		);
+	}
+}
+
+/**
+ * Everything the report needs to group a request, read off its URL.
+ *
+ * A URL that does not parse still gets a line — with `raw` filled in — because
+ * a request the profiler cannot describe is exactly the kind worth seeing.
+ */
+function describeRequest(rawUrl, method) {
+	let url;
+
+	try {
+		url = new URL(rawUrl);
+	} catch {
+		return { cms: false, method, host: null, path: null, raw: String(rawUrl) };
+	}
+
+	const params = url.searchParams;
+	const where = [];
+
+	for (const [key, value] of params) {
+		if (key === 'where' || key.startsWith('where[')) {
+			where.push(`${key}=${value}`);
+		}
+	}
+
+	const whereQuery = where.join('&');
+
+	return {
+		cms: cmsOrigin !== null && url.origin === cmsOrigin,
+		method,
+		host: url.host,
+		path: url.pathname,
+		collection: collectionOf(url.pathname),
+		locale: params.get('locale'),
+		fallbackLocale: params.get('fallback-locale'),
+		depth: numberOf(params.get('depth')),
+		limit: numberOf(params.get('limit')),
+		page: numberOf(params.get('page')),
+		sort: params.get('sort'),
+		where: truncate(whereQuery, WHERE_MAX),
+		// The truncated `where` is for reading; this is what identifies it. Two
+		// queries that differ only past the cut would otherwise look repeated.
+		whereHash: whereQuery ? hash(whereQuery) : null,
+	};
+}
+
+/**
+ * `/api/posts` → `posts`, `/api/globals/header` → `globals/header`.
+ * Anything outside `/api/` has no collection.
+ */
+function collectionOf(pathname) {
+	const segments = pathname.split('/').filter(Boolean);
+
+	if (segments[0] !== 'api' || segments.length < 2) {
+		return null;
+	}
+
+	if (segments[1] === 'globals') {
+		return segments.slice(1, 3).join('/');
+	}
+
+	return segments[1];
+}
+
+/**
+ * The response size, without taking the body away from the caller.
+ *
+ * `clone()` tees the stream, so the copy can be drained here while whoever
+ * called `fetch` reads the original. That does hold both in memory at once,
+ * which is fine for JSON and not for a 40 MB video — hence the size cap, above
+ * which the declared length is good enough.
+ */
+function countBytes(response) {
+	const header = response.headers.get('content-length');
+	const declared = header === null ? null : Number(header);
+	const fallback = Number.isFinite(declared) ? declared : null;
+
+	if (!response.body) {
+		return Promise.resolve(fallback ?? 0);
+	}
+
+	if (fallback !== null && fallback > CLONE_LIMIT) {
+		return Promise.resolve(fallback);
+	}
+
+	let clone;
+
+	try {
+		clone = response.clone();
+	} catch {
+		return Promise.resolve(fallback);
+	}
+
+	return clone.arrayBuffer().then(
+		(buffer) => buffer.byteLength,
+		() => fallback,
+	);
+}
+
+function urlOf(input) {
+	if (typeof input === 'string') {
+		return input;
+	}
+
+	if (input instanceof URL) {
+		return input.href;
+	}
+
+	return input?.url ?? String(input);
+}
+
+function methodOf(input, init) {
+	return (init?.method ?? input?.method ?? 'GET').toUpperCase();
+}
+
+function originOf(value) {
+	if (!value) {
+		return null;
+	}
+
+	try {
+		return new URL(value).origin;
+	} catch {
+		return null;
+	}
+}
+
+function numberOf(value) {
+	if (value === null) {
+		return null;
+	}
+
+	const parsed = Number(value);
+
+	return Number.isFinite(parsed) ? parsed : null;
+}
+
+function truncate(value, max) {
+	if (!value) {
+		return null;
+	}
+
+	return value.length > max ? `${value.slice(0, max)}…` : value;
+}
+
+function hash(value) {
+	return createHash('sha1').update(value).digest('hex').slice(0, 8);
+}
+
+function round(value) {
+	return Math.round(value * 10) / 10;
+}

package/bin/profile/format.mjs

@@ -0,0 +1,90 @@
+/**
+ * Markdown and units for both profile reports.
+ *
+ * Extracted from `summarize.mjs` when the interference harness needed the same
+ * tables and the same way of printing a duration: two reports that disagree
+ * about what "1.4 s" means are two reports that cannot be read side by side.
+ *
+ * Pure. The numbers that go through here are computed in `measure.mjs`;
+ * anything that knows what a fetch log or a poll log means belongs in the
+ * summarizer that owns it.
+ */
+
+const BAR_WIDTH = 24;
+
+export function bullets(entries) {
+	return entries
+		.filter(([, value]) => value !== null && value !== undefined)
+		.map(([label, value]) => `- ${label}: ${value}`);
+}
+
+export function table(headers, rows) {
+	return [
+		`| ${headers.join(' | ')} |`,
+		`| ${headers.map(() => '---').join(' | ')} |`,
+		...rows.map((cells) => `| ${cells.join(' | ')} |`),
+	];
+}
+
+export function bar(value, peak, width = BAR_WIDTH) {
+	if (!peak || value <= 0) {
+		return '';
+	}
+
+	return '#'.repeat(Math.max(1, Math.round((value / peak) * width)));
+}
+
+export function count(value) {
+	return value.toLocaleString('en-US');
+}
+
+export function duration(ms) {
+	if (ms === null || ms === undefined) {
+		return '-';
+	}
+
+	if (ms >= 10_000) {
+		return `${(ms / 1000).toFixed(1)} s`;
+	}
+
+	return `${Math.round(ms).toLocaleString('en-US')} ms`;
+}
+
+/**
+ * Seconds from the start of a run, for a timeline column.
+ *
+ * A build's timeline is tens of seconds long and reads best in tenths. An
+ * interference run is minutes long, where "115.0s" is a number a reader has to
+ * divide, so that report uses `offsetClock` instead. Both live here so the one
+ * place the two reports deliberately disagree is visible.
+ */
+export function offsetSeconds(ms) {
+	return `${(ms / 1000).toFixed(1)}s`;
+}
+
+/** `m:ss` from the start of a run, for a timeline longer than a minute. */
+export function offsetClock(ms) {
+	const seconds = Math.round(ms / 1000);
+
+	return `${Math.floor(seconds / 60)}:${String(seconds % 60).padStart(2, '0')}`;
+}
+
+export function share(part, whole) {
+	if (!whole) {
+		return 'n/a';
+	}
+
+	return `${Math.round((part / whole) * 100)}%`;
+}
+
+export function size(bytes) {
+	if (bytes >= 1024 * 1024) {
+		return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+	}
+
+	return `${(bytes / 1024).toFixed(1)} KB`;
+}
+
+export function escapePipes(value) {
+	return value.replaceAll('|', '\\|');
+}