@fedify/cli 2.3.0-dev.994 → 2.3.0

package/dist/bench/scenarios/read.js

@@ -0,0 +1,108 @@
+import "@js-temporal/polyfill";
+import { runLoad } from "../load/generator.js";
+import { aggregateSamples } from "../metrics/aggregate.js";
+import { diffSnapshots, fetchServerSnapshot, snapshotToMetrics } from "../metrics/stats-client.js";
+import { createSigningPipeline } from "../signing/pipeline.js";
+import { assertBareHttpUrl, estimateTotal, loadPlanOf, measuredWindowMs, sendRequest, withMeasuredWindowStart } from "./runner.js";
+import { signRequest } from "@fedify/fedify";
+//#region src/bench/scenarios/read.ts
+/**
+* Shared helpers for read-only benchmark scenarios.
+* @since 2.3.0
+* @module
+*/
+const READ_GATE_CONCURRENCY = 16;
+/**
+* Runs a read-only GET workload and aggregates client/server measurements.
+* @param context The scenario run context.
+* @param options Read workload options.
+* @returns The scenario measurement.
+*/
+async function runReadLoad(context, options) {
+	if (options.urls.length < 1) throw new Error(`Scenario "${context.scenario.name}" did not resolve any URLs to fetch.`);
+	const fetchImpl = context.fetch ?? fetch;
+	const actors = context.fleet?.actors ?? [];
+	if (options.authenticated && actors.length < 1) throw new Error(`Scenario "${context.scenario.name}" requires the synthetic actor server for authenticated fetches.`);
+	for (const url of options.urls) assertBareHttpUrl(context.scenario.name, "read URL", url);
+	await mapWithConcurrency(options.urls, READ_GATE_CONCURRENCY, async (url) => {
+		if (options.authenticated) await context.assertDestinationAllowed?.(url);
+		else await context.assertReadDestinationAllowed?.(url);
+	});
+	function unsignedRequest(index) {
+		const url = options.urls[index % options.urls.length];
+		return new Request(url, {
+			headers: { accept: "application/activity+json, application/ld+json" },
+			redirect: "manual"
+		});
+	}
+	let pipeline = null;
+	if (options.authenticated) {
+		let signIndex = 0;
+		pipeline = createSigningPipeline(context.scenario.signing, async () => {
+			const i = signIndex++;
+			return await signGetRequest(unsignedRequest(i), actors[i % actors.length]);
+		}, { total: estimateTotal(context.scenario) });
+	}
+	let index = 0;
+	const rawSend = async () => {
+		let request;
+		if (pipeline != null) try {
+			request = await pipeline.next();
+		} catch (error) {
+			return {
+				ok: false,
+				errorKind: "client",
+				reason: String(error)
+			};
+		}
+		else request = unsignedRequest(index++);
+		return await sendRequest(request, fetchImpl);
+	};
+	let baseline = null;
+	let baselineTaken = false;
+	const send = withMeasuredWindowStart(context.scenario.warmupMs, async () => {
+		baseline = await fetchServerSnapshot(context.target, fetchImpl);
+		baselineTaken = true;
+	}, rawSend);
+	try {
+		await pipeline?.prime();
+		const measurement = aggregateSamples((await runLoad(loadPlanOf(context.scenario, context.rng), send, context.clock, context.signal)).samples, {
+			measuredWindowMs: measuredWindowMs(context.scenario),
+			includeHistogram: true
+		});
+		const end = await fetchServerSnapshot(context.target, fetchImpl);
+		const server = baselineTaken && baseline != null && end != null ? snapshotToMetrics(diffSnapshots(baseline, end)) : null;
+		return {
+			...measurement,
+			server
+		};
+	} finally {
+		await pipeline?.close();
+	}
+}
+async function mapWithConcurrency(items, concurrency, callback) {
+	let next = 0;
+	let firstError;
+	let hasError = false;
+	const workers = Array.from({ length: Math.min(concurrency, items.length) }, async () => {
+		while (next < items.length && !hasError) {
+			const item = items[next++];
+			try {
+				await callback(item);
+			} catch (error) {
+				if (!hasError) {
+					hasError = true;
+					firstError = error;
+				}
+			}
+		}
+	});
+	await Promise.all(workers);
+	if (hasError) throw firstError;
+}
+async function signGetRequest(request, actor) {
+	if (actor.keys?.rsa == null || actor.rsaKeyId == null) throw new TypeError("Actor is missing the RSA key required for authenticated fetch signing.");
+	return await signRequest(request, actor.keys.rsa.privateKey, actor.rsaKeyId, { spec: actor.httpStandard });
+}
+//#endregion
+export { runReadLoad };

package/dist/bench/scenarios/registry.js

@@ -0,0 +1,39 @@
+import "@js-temporal/polyfill";
+import { actorRunner } from "./actor.js";
+import { fanoutRunner } from "./fanout.js";
+import { failureRunner } from "./failure.js";
+import { inboxRunner } from "./inbox.js";
+import { objectRunner } from "./object.js";
+import { webfingerRunner } from "./webfinger.js";
+import { mixedRunner } from "./mixed.js";
+//#region src/bench/scenarios/registry.ts
+/** The scenario types that have runners in this version. */
+const IMPLEMENTED_SCENARIO_TYPES = [
+	"inbox",
+	"webfinger",
+	"actor",
+	"object",
+	"fanout",
+	"failure",
+	"mixed"
+];
+/**
+* Returns the runner for a scenario type.
+* @param type The scenario type.
+* @returns The runner.
+* @throws {Error} If the type has no runner in this version.
+*/
+function runnerFor(type) {
+	switch (type) {
+		case "inbox": return inboxRunner;
+		case "webfinger": return webfingerRunner;
+		case "actor": return actorRunner;
+		case "object": return objectRunner;
+		case "fanout": return fanoutRunner;
+		case "failure": return failureRunner;
+		case "mixed": return mixedRunner;
+		default: throw new Error(`The "${type}" scenario type is not implemented in this version of fedify bench; supported types: ${IMPLEMENTED_SCENARIO_TYPES.join(", ")}.`);
+	}
+}
+//#endregion
+export { runnerFor };

package/dist/bench/scenarios/runner.js

@@ -0,0 +1,96 @@
+import "@js-temporal/polyfill";
+//#region src/bench/scenarios/runner.ts
+/** Performs one HTTP send and classifies the result as a send outcome. */
+async function sendRequest(request, fetchImpl) {
+	const noFollow = request.redirect === "manual" ? request : new Request(request, { redirect: "manual" });
+	try {
+		const response = await fetchImpl(noFollow);
+		await response.arrayBuffer().catch(() => {});
+		if (response.type === "opaqueredirect" || response.status >= 300 && response.status < 400) return {
+			ok: false,
+			status: response.status === 0 ? void 0 : response.status,
+			reason: "redirect"
+		};
+		if (response.ok) return {
+			ok: true,
+			status: response.status
+		};
+		return {
+			ok: false,
+			status: response.status,
+			reason: `status_${response.status}`
+		};
+	} catch (error) {
+		return {
+			ok: false,
+			errorKind: "network",
+			reason: String(error)
+		};
+	}
+}
+/** Builds the load plan for a resolved scenario. */
+function loadPlanOf(scenario, rng) {
+	return {
+		load: scenario.load,
+		durationMs: scenario.durationMs,
+		warmupMs: scenario.warmupMs,
+		rng
+	};
+}
+/** The measured window (excluding warm-up) used for throughput, in ms. */
+function measuredWindowMs(scenario) {
+	return Math.max(scenario.durationMs - scenario.warmupMs, 1);
+}
+/** Estimates the total request count, for presigning open-loop runs. */
+function estimateTotal(scenario) {
+	if (scenario.load.kind !== "open") return void 0;
+	return Math.ceil(scenario.load.ratePerSec * (scenario.durationMs / 1e3));
+}
+/** Returns whether a URL is fetchable by benchmark runners without surprises. */
+function isBareHttpUrl(url) {
+	return (url.protocol === "http:" || url.protocol === "https:") && url.hostname !== "" && url.username === "" && url.password === "";
+}
+/** Rejects URLs that are not bare http(s) URLs with a host and no credentials. */
+function assertBareHttpUrl(scenarioName, label, url) {
+	if (isBareHttpUrl(url)) return;
+	throw new Error(`Scenario "${scenarioName}": ${label} must be a bare http(s) URL with a host and no credentials; got ${JSON.stringify(url.href)}.`);
+}
+/** Validates an inbox selector or explicit inbox URL. */
+function validateInboxSelector(scenarioName, inbox) {
+	if (inbox == null || inbox === "shared" || inbox === "personal") return;
+	let url;
+	try {
+		url = new URL(inbox);
+	} catch {
+		throw new Error(`Scenario "${scenarioName}": inbox must be "shared", "personal", or an http(s) URL; got ${JSON.stringify(inbox)}.`);
+	}
+	assertBareHttpUrl(scenarioName, "inbox URL", url);
+}
+/**
+* Wraps a send function so that `onMeasuredWindowStart` runs exactly once, at
+* the warm-up boundary, and *every* measured request waits for it to settle
+* before being sent.  Runners use this to snapshot a server-side baseline so
+* reported server metrics cover only the measured window rather than the
+* target's cumulative lifetime; awaiting it on every measured send guarantees
+* the baseline is taken before any measured traffic reaches the target, so no
+* measured request can leak into the baseline.
+*
+* The barrier is cheap: only the handful of requests scheduled while the
+* baseline snapshot is in flight wait for it (recording that wait as their own
+* latency, the coordinated-omission-correct outcome); once it settles, later
+* waits resolve immediately.
+* @param warmupMs The warm-up window length, in milliseconds.
+* @param onMeasuredWindowStart The one-shot callback, run at the boundary.
+* @param send The underlying send function.
+* @returns A send function that gates measured sends on the callback.
+*/
+function withMeasuredWindowStart(warmupMs, onMeasuredWindowStart, send) {
+	let started;
+	return (scheduledAtMs) => {
+		if (scheduledAtMs < warmupMs) return send(scheduledAtMs);
+		started ??= Promise.resolve().then(onMeasuredWindowStart);
+		return started.then(() => send(scheduledAtMs));
+	};
+}
+//#endregion
+export { assertBareHttpUrl, estimateTotal, isBareHttpUrl, loadPlanOf, measuredWindowMs, sendRequest, validateInboxSelector, withMeasuredWindowStart };

package/dist/bench/scenarios/webfinger.js

@@ -0,0 +1,44 @@
+import "@js-temporal/polyfill";
+import { convertUrlIfHandle } from "../../webfinger/lib.js";
+import { runLoad } from "../load/generator.js";
+import { aggregateSamples } from "../metrics/aggregate.js";
+import { diffSnapshots, fetchServerSnapshot, snapshotToMetrics } from "../metrics/stats-client.js";
+import { loadPlanOf, measuredWindowMs, sendRequest, withMeasuredWindowStart } from "./runner.js";
+//#region src/bench/scenarios/webfinger.ts
+/**
+* The `webfinger` scenario runner: drives WebFinger handle-resolution lookups,
+* the discovery primitive every other scenario reuses.
+* @since 2.3.0
+* @module
+*/
+function webfingerUrl(target, recipient) {
+	const resource = convertUrlIfHandle(recipient).href;
+	const url = new URL("/.well-known/webfinger", target);
+	url.searchParams.set("resource", resource);
+	return url;
+}
+/** The `webfinger` scenario runner. */
+const webfingerRunner = { async run(context) {
+	const fetchImpl = context.fetch ?? fetch;
+	const urls = (context.scenario.recipients.length > 0 ? context.scenario.recipients : [context.target.href]).map((r) => webfingerUrl(context.target, r));
+	let index = 0;
+	const rawSend = () => sendRequest(new Request(urls[index++ % urls.length], { redirect: "manual" }), fetchImpl);
+	let baseline = null;
+	let baselineTaken = false;
+	const send = withMeasuredWindowStart(context.scenario.warmupMs, async () => {
+		baseline = await fetchServerSnapshot(context.target, fetchImpl);
+		baselineTaken = true;
+	}, rawSend);
+	const measurement = aggregateSamples((await runLoad(loadPlanOf(context.scenario, context.rng), send, context.clock, context.signal)).samples, {
+		measuredWindowMs: measuredWindowMs(context.scenario),
+		includeHistogram: true
+	});
+	const end = await fetchServerSnapshot(context.target, fetchImpl);
+	const server = baselineTaken && baseline != null && end != null ? snapshotToMetrics(diffSnapshots(baseline, end)) : null;
+	return {
+		...measurement,
+		server
+	};
+} };
+//#endregion
+export { webfingerRunner };

package/dist/bench/server/synthetic.js

@@ -0,0 +1,118 @@
+import "@js-temporal/polyfill";
+import { getContextLoader } from "../../docloader.js";
+import { actorDocument } from "../actor/documents.js";
+import { serve } from "srvx";
+//#region src/bench/server/synthetic.ts
+/**
+* The benchmark's own synthetic actor/key server.
+*
+* It serves the actor documents (with embedded keys) that the target
+* dereferences while verifying signatures, over plain HTTP — which works
+* because `benchmarkMode` enables `allowPrivateAddress` on the target.  By
+* default it binds loopback and advertises a `127.0.0.1` base URL, which a
+* same-machine (loopback) target can reach.  For a non-loopback target, pass
+* `advertiseHost`: the server then binds every interface and advertises that
+* host in the actor/key URLs, so the remote target can dereference them.
+* @since 2.3.0
+* @module
+*/
+/**
+* Starts the synthetic actor/key server and serves each fleet member's actor
+* document.
+* @param members The fleet members (with keys) to serve.
+* @param options Server options.
+* @returns The running server, including the actors with their assigned URLs.
+*/
+async function spawnSyntheticServer(members, options = {}) {
+	const advertised = options.advertiseHost == null ? null : resolveAdvertiseHost(options.advertiseHost);
+	const routes = /* @__PURE__ */ new Map();
+	const server = serve({
+		port: 0,
+		hostname: advertised?.bindHost ?? "127.0.0.1",
+		silent: true,
+		fetch(request) {
+			const { pathname } = new URL(request.url);
+			const body = routes.get(pathname);
+			if (body == null) return new Response("Not found", { status: 404 });
+			return new Response(body, {
+				status: 200,
+				headers: { "content-type": "application/activity+json" }
+			});
+		}
+	});
+	await server.ready();
+	const actors = [];
+	try {
+		const bound = new URL(server.url);
+		const base = advertised == null ? bound : new URL(`http://${advertised.urlHost}:${bound.port}/`);
+		const contextLoader = options.contextLoader ?? await getContextLoader({ allowPrivateAddress: true });
+		for (const member of members) {
+			const id = new URL(`/actors/${member.index}`, base);
+			const actor = {
+				...member,
+				id,
+				rsaKeyId: member.keys.rsa == null ? void 0 : new URL("#main-key", id),
+				ed25519KeyId: member.keys.ed25519 == null ? void 0 : new URL("#ed25519-key", id)
+			};
+			const document = await actorDocument(actor, { contextLoader });
+			routes.set(`/actors/${member.index}`, JSON.stringify(document));
+			actors.push(actor);
+		}
+		return {
+			url: base,
+			actors,
+			async close() {
+				await server.close(true);
+			}
+		};
+	} catch (error) {
+		await server.close(true);
+		throw error;
+	}
+}
+/** An error raised when `--advertise-host` is not a usable bare host. */
+var AdvertiseHostError = class extends Error {};
+/**
+* Validates and normalizes an `--advertise-host` value into a bind address and a
+* URL-authority host.  It must be a bare host name, IPv4 address, or IPv6
+* literal (bracketed or not); a scheme, port, path, or other URL syntax is
+* rejected, since the synthetic server's chosen port is appended automatically.
+* An IPv6 host binds every IPv6 interface (`::`); anything else binds every IPv4
+* interface (`0.0.0.0`).
+* @param host The raw `--advertise-host` value.
+* @returns The bind address and the URL-authority host.
+* @throws {AdvertiseHostError} If the value is not a usable bare host.
+*/
+function resolveAdvertiseHost(host) {
+	const trimmed = host.trim();
+	if (trimmed === "") throw new AdvertiseHostError("--advertise-host must not be empty.");
+	if (/[\s/\\@?#]/.test(trimmed) || trimmed.includes("://")) throw new AdvertiseHostError(`Invalid --advertise-host ${JSON.stringify(host)}: give a bare host name or IP address, with no scheme, path, or whitespace.`);
+	let urlHost;
+	let bindHost;
+	if (trimmed.startsWith("[")) {
+		if (!trimmed.endsWith("]")) throw new AdvertiseHostError(`Invalid --advertise-host ${JSON.stringify(host)}: unbalanced brackets around the IPv6 address.`);
+		urlHost = trimmed;
+		bindHost = "::";
+	} else {
+		const colons = (trimmed.match(/:/g) ?? []).length;
+		if (colons === 1) throw new AdvertiseHostError(`Invalid --advertise-host ${JSON.stringify(host)}: omit the port; the synthetic server's chosen port is appended automatically.`);
+		if (colons >= 2) {
+			urlHost = `[${trimmed}]`;
+			bindHost = "::";
+		} else {
+			urlHost = trimmed;
+			bindHost = /^\d{1,3}(?:\.\d{1,3}){3}$/.test(trimmed) ? "0.0.0.0" : "::";
+		}
+	}
+	try {
+		new URL(`http://${urlHost}/`);
+	} catch {
+		throw new AdvertiseHostError(`Invalid --advertise-host ${JSON.stringify(host)}: not a valid host name or IP address.`);
+	}
+	return {
+		bindHost,
+		urlHost
+	};
+}
+//#endregion
+export { resolveAdvertiseHost, spawnSyntheticServer };

package/dist/bench/signing/activity-id.js

@@ -0,0 +1,18 @@
+import "@js-temporal/polyfill";
+//#region src/bench/signing/activity-id.ts
+/**
+* Creates a minter that produces unique activity ids under a base URL.  Ids
+* combine a per-run random component with a monotonic counter, so they are
+* unique within a run and across runs.
+* @param base The base URL (typically the synthetic server's URL).
+* @returns A new minter.
+*/
+function createActivityIdMinter(base) {
+	const run = crypto.randomUUID();
+	let counter = 0;
+	return { next() {
+		return new URL(`/activities/${run}/${counter++}`, base);
+	} };
+}
+//#endregion
+export { createActivityIdMinter };

package/dist/bench/signing/pipeline.js

@@ -0,0 +1,134 @@
+import "@js-temporal/polyfill";
+//#region src/bench/signing/pipeline.ts
+/** An error used to release consumers waiting on a closed pipeline. */
+var PipelineClosedError = class extends Error {};
+const DEFAULT_BUFFER_SIZE = 256;
+const DEFAULT_SIGNERS = 4;
+/**
+* After this many signing failures with no successful sign in between, the
+* pipeline gives up so a deterministic signing error fails fast instead of
+* spinning forever.
+*/
+const FATAL_FAILURE_THRESHOLD = 8;
+/**
+* Creates a signing pipeline for the given mode.
+* @param mode The lookahead mode.
+* @param factory The per-request signing factory.
+* @param options Buffer, total, and concurrency options.
+* @returns The signing pipeline.
+*/
+function createSigningPipeline(mode, factory, options = {}) {
+	if (mode === "jit") return createJit(factory);
+	const signers = options.signers ?? DEFAULT_SIGNERS;
+	if (mode === "presign") {
+		const total = options.total ?? DEFAULT_BUFFER_SIZE;
+		return createBuffered(factory, {
+			bufferSize: total,
+			fillTarget: total,
+			signers,
+			countStarvation: false,
+			maxProduced: total
+		});
+	}
+	const bufferSize = options.bufferSize ?? DEFAULT_BUFFER_SIZE;
+	return createBuffered(factory, {
+		bufferSize,
+		fillTarget: bufferSize,
+		signers,
+		countStarvation: true
+	});
+}
+function createJit(factory) {
+	return {
+		next: factory,
+		prime: () => Promise.resolve(),
+		starvationCount: 0,
+		close: () => Promise.resolve()
+	};
+}
+function createBuffered(factory, options) {
+	const ready = [];
+	const waiters = [];
+	const maxProduced = options.maxProduced ?? Infinity;
+	let produced = 0;
+	let starvationCount = 0;
+	let inFlight = 0;
+	let closed = false;
+	let consecutiveFailures = 0;
+	let fatalError = null;
+	const CLOSED = Symbol("closed");
+	let signalClose;
+	const closeSignal = new Promise((resolve) => {
+		signalClose = () => resolve(CLOSED);
+	});
+	function deliver(request) {
+		const waiter = waiters.shift();
+		if (waiter != null) waiter.resolve(request);
+		else ready.push(request);
+	}
+	function fail(error) {
+		fatalError = error;
+		closed = true;
+		signalClose();
+		ready.length = 0;
+		while (waiters.length > 0) waiters.shift().reject(error);
+	}
+	async function producer() {
+		while (!closed) {
+			if (produced + inFlight >= maxProduced) break;
+			if (waiters.length === 0 && ready.length + inFlight >= options.bufferSize) {
+				await Promise.race([delay(), closeSignal]);
+				continue;
+			}
+			inFlight++;
+			try {
+				const pending = Promise.resolve().then(factory);
+				pending.catch(() => {});
+				const result = await Promise.race([pending, closeSignal]);
+				if (result === CLOSED || closed) break;
+				consecutiveFailures = 0;
+				produced++;
+				deliver(result);
+			} catch (error) {
+				if (++consecutiveFailures >= FATAL_FAILURE_THRESHOLD) fail(error);
+			} finally {
+				inFlight--;
+			}
+		}
+	}
+	const producers = Array.from({ length: options.signers }, () => producer());
+	return {
+		get starvationCount() {
+			return starvationCount;
+		},
+		next() {
+			const buffered = ready.shift();
+			if (buffered != null) return Promise.resolve(buffered);
+			if (fatalError != null) return Promise.reject(fatalError);
+			if (closed) return Promise.reject(new PipelineClosedError("closed"));
+			if (produced >= maxProduced) return Promise.resolve().then(factory);
+			if (options.countStarvation) starvationCount++;
+			return new Promise((resolve, reject) => {
+				waiters.push({
+					resolve,
+					reject
+				});
+			});
+		},
+		async prime() {
+			while (!closed && ready.length < options.fillTarget) await Promise.race([delay(), closeSignal]);
+			if (fatalError != null) throw fatalError;
+		},
+		async close() {
+			closed = true;
+			signalClose();
+			while (waiters.length > 0) waiters.shift().reject(new PipelineClosedError("closed"));
+			await Promise.allSettled(producers);
+		}
+	};
+}
+function delay() {
+	return new Promise((resolve) => setTimeout(resolve, 1));
+}
+//#endregion
+export { createSigningPipeline };

package/dist/bench/signing/signer.js

@@ -0,0 +1,39 @@
+import "@js-temporal/polyfill";
+import { signJsonLd, signObject, signRequest } from "@fedify/fedify";
+//#region src/bench/signing/signer.ts
+/**
+* Signing one inbox delivery, reusing the `@fedify/fedify` signers so the
+* client pays realistic crypto cost.
+*
+* Document signatures are applied first (FEP-8b32 object proof, then LD
+* Signature on the serialized document), then the HTTP request signature is
+* applied to the final body, matching how a real sender composes a request.
+* @since 2.3.0
+* @module
+*/
+/**
+* Signs an inbox delivery and returns a ready-to-send `Request`.
+* @param options The delivery options.
+* @returns The signed POST request.
+* @throws {TypeError} If the actor lacks the RSA key required for HTTP signing.
+*/
+async function signInboxDelivery(options) {
+	const { actor, inbox, contextLoader } = options;
+	if (actor.keys.rsa == null || actor.rsaKeyId == null) throw new TypeError("Actor is missing the RSA key required for HTTP request signing.");
+	let activity = options.activity;
+	if (actor.standards.includes("fep8b32") && actor.keys.ed25519 != null && actor.ed25519KeyId != null) activity = await signObject(activity, actor.keys.ed25519.privateKey, actor.ed25519KeyId, { contextLoader });
+	let document = await activity.toJsonLd({ contextLoader });
+	if (actor.standards.includes("ld-signatures")) document = await signJsonLd(document, actor.keys.rsa.privateKey, actor.rsaKeyId, { contextLoader });
+	const body = new TextEncoder().encode(JSON.stringify(document));
+	return await signRequest(new Request(inbox, {
+		method: "POST",
+		headers: { "content-type": "application/activity+json" },
+		body,
+		redirect: "manual"
+	}), actor.keys.rsa.privateKey, actor.rsaKeyId, {
+		spec: actor.httpStandard,
+		body: body.buffer.slice(body.byteOffset, body.byteOffset + body.byteLength)
+	});
+}
+//#endregion
+export { signInboxDelivery };