@fedify/cli 2.3.0-dev.1214 → 2.3.0-dev.1258

package/dist/bench/action.js

@@ -0,0 +1,203 @@
+import "@js-temporal/polyfill";
+import { getContextLoader, getDocumentLoader } from "../docloader.js";
+import { buildFleet } from "./actor/fleet.js";
+import { validateExpectBlock } from "./result/expect/evaluate.js";
+import { buildReport, buildScenarioResult, configHash, detectEnvironment } from "./result/build.js";
+import { probeBenchmarkMode } from "./discovery/probe.js";
+import { renderReport } from "./render/index.js";
+import { loadSuiteFile, renderSuiteTemplates } from "./scenario/load.js";
+import { normalizeSuite } from "./scenario/normalize.js";
+import { validateSuite } from "./scenario/validate.js";
+import { classifyTarget } from "./safety/tiers.js";
+import { UnsafeTargetError, assertInboxDestinationAllowed, assertTargetAllowed } from "./safety/gate.js";
+import { runnerFor } from "./scenarios/registry.js";
+import { resolveAdvertiseHost, spawnSyntheticServer } from "./server/synthetic.js";
+import { writeFile } from "node:fs/promises";
+import process from "node:process";
+//#region src/bench/action.ts
+/** The scenario types that need the synthetic actor/key server. */
+const SIGNED_TYPES = new Set(["inbox"]);
+/**
+* Runs the `fedify bench` command: load and validate the suite, gate the
+* target, run each scenario, and render the report.  The process exits 0 when
+* every `expect` gate passes and 1 otherwise; configuration and safety errors
+* exit 2.
+* @param command The parsed `bench` command options.
+* @param deps Injectable dependencies for testing.
+*/
+async function runBench(command, deps = {}) {
+	const exit = deps.exit ?? ((code) => {
+		process.exitCode = code;
+	});
+	const writeOutput = deps.writeOutput ?? defaultWriteOutput;
+	const log = deps.log ?? ((message) => process.stderr.write(`${message}\n`));
+	const fetchImpl = withUserAgent(deps.fetch ?? fetch, command.userAgent);
+	let validated;
+	let suite;
+	try {
+		validated = validateSuite(renderSuiteTemplates(await loadSuiteFile(command.scenario), command.target), command.scenario);
+		suite = normalizeSuite(validated, { target: command.target });
+	} catch (error) {
+		log(error instanceof Error ? error.message : String(error));
+		exit(2);
+		return;
+	}
+	let runners;
+	try {
+		runners = suite.scenarios.map((scenario) => {
+			const runner = runnerFor(scenario.type);
+			runner.validate?.(scenario);
+			validateExpectBlock(scenario.expect);
+			return runner;
+		});
+		if (command.advertiseHost != null) resolveAdvertiseHost(command.advertiseHost);
+	} catch (error) {
+		log(error instanceof Error ? error.message : String(error));
+		exit(2);
+		return;
+	}
+	if (command.dryRun) {
+		await writeOutput(renderPlan(suite), command.output);
+		exit(0);
+		return;
+	}
+	const tier = classifyTarget(suite.target);
+	const probe = await probeBenchmarkMode(suite.target, fetchImpl);
+	try {
+		assertTargetAllowed({
+			tier,
+			benchmarkMode: probe.benchmarkMode,
+			allowUnsafe: command.allowUnsafeTarget,
+			dryRun: false
+		});
+	} catch (error) {
+		if (error instanceof UnsafeTargetError) {
+			log(error.message);
+			exit(2);
+			return;
+		}
+		throw error;
+	}
+	if (tier !== "loopback" && command.advertiseHost == null && suite.scenarios.some((s) => SIGNED_TYPES.has(s.type))) {
+		log("Signed scenarios (inbox) need the benchmark's synthetic actor server to be reachable from the target.  A loopback target reaches it automatically; for a non-loopback target, pass --advertise-host with an address the target can reach (the synthetic server then binds all interfaces), or use a read scenario such as webfinger.");
+		exit(2);
+		return;
+	}
+	const allowPrivateAddress = tier !== "public";
+	const documentLoader = await getDocumentLoader({
+		allowPrivateAddress,
+		userAgent: command.userAgent
+	});
+	const contextLoader = await getContextLoader({
+		allowPrivateAddress,
+		userAgent: command.userAgent
+	});
+	const assertDestinationAllowed = (url) => assertInboxDestinationAllowed(url, {
+		targetOrigin: suite.target.origin,
+		targetBenchmarkMode: probe.benchmarkMode,
+		allowUnsafe: command.allowUnsafeTarget,
+		advertised: command.advertiseHost != null
+	});
+	let fleet;
+	const startedAt = (/* @__PURE__ */ new Date()).toISOString();
+	try {
+		if (suite.scenarios.some((s) => SIGNED_TYPES.has(s.type))) fleet = await spawnSyntheticServer(await buildFleet(suite.actors), { advertiseHost: command.advertiseHost });
+		const results = [];
+		for (let i = 0; i < suite.scenarios.length; i++) {
+			const scenario = suite.scenarios[i];
+			log(`Running scenario "${scenario.name}" (${scenario.type})…`);
+			const measurement = await runners[i].run({
+				scenario,
+				target: suite.target,
+				documentLoader,
+				contextLoader,
+				allowPrivateAddress,
+				fleet: fleet ?? null,
+				fetch: fetchImpl,
+				assertDestinationAllowed
+			});
+			results.push(buildScenarioResult(scenario, measurement));
+		}
+		const report = buildReport({
+			scenarios: results,
+			environment: detectEnvironment(),
+			target: {
+				url: suite.target.href,
+				fedifyVersion: probe.fedifyVersion,
+				statsAvailable: probe.benchmarkMode
+			},
+			startedAt,
+			finishedAt: (/* @__PURE__ */ new Date()).toISOString(),
+			suite: { configHash: configHash({
+				suite: validated,
+				target: suite.target.href
+			}) }
+		});
+		await writeOutput(renderReport(report, command.format), command.output);
+		exit(report.passed ? 0 : 1);
+		return;
+	} catch (error) {
+		if (error instanceof UnsafeTargetError) {
+			log(error.message);
+			exit(2);
+			return;
+		}
+		throw error;
+	} finally {
+		await fleet?.close();
+	}
+}
+/**
+* Wraps a fetch implementation so every request carries the given User-Agent,
+* unless the caller already set one.  A prebuilt {@link Request} (the signed
+* inbox delivery, a WebFinger GET) is mutated in place rather than recloned, so
+* an already-signed body and its digest are left untouched; the User-Agent is
+* not part of the signed header set, so adding it does not affect verification.
+* @param fetchImpl The underlying fetch implementation.
+* @param userAgent The User-Agent header value to apply.
+* @returns A fetch implementation that injects the User-Agent.
+*/
+function withUserAgent(fetchImpl, userAgent) {
+	return ((input, init) => {
+		if (input instanceof Request && init === void 0) {
+			if (input.headers.has("user-agent")) return fetchImpl(input);
+			try {
+				input.headers.set("user-agent", userAgent);
+				return fetchImpl(input);
+			} catch {
+				const headers = new Headers(input.headers);
+				headers.set("user-agent", userAgent);
+				return fetchImpl(new Request(input, { headers }));
+			}
+		}
+		const headers = new Headers(init?.headers ?? (input instanceof Request ? input.headers : void 0));
+		if (!headers.has("user-agent")) headers.set("user-agent", userAgent);
+		return fetchImpl(input, {
+			...init,
+			headers
+		});
+	});
+}
+async function defaultWriteOutput(content, outputPath) {
+	if (outputPath == null) {
+		process.stdout.write(content.endsWith("\n") ? content : `${content}\n`);
+		return;
+	}
+	await writeFile(outputPath, content, { encoding: "utf-8" });
+}
+function renderPlan(suite) {
+	const lines = [
+		"Fedify benchmark plan (dry run)",
+		"",
+		`Target: ${suite.target.href}`,
+		""
+	];
+	for (const scenario of suite.scenarios) lines.push(`- ${scenario.name} (${scenario.type}): ${describePlan(scenario)}`);
+	lines.push("", "No requests were sent.");
+	return `${lines.join("\n")}\n`;
+}
+function describePlan(scenario) {
+	return `${scenario.load.kind === "open" ? `open-loop ${scenario.load.ratePerSec}/s ${scenario.load.arrival}` : `closed-loop concurrency ${scenario.load.concurrency}`}, duration ${scenario.durationMs}ms, signing ${scenario.signing}`;
+}
+//#endregion
+export { runBench as default };

package/dist/bench/actor/documents.js

@@ -0,0 +1,39 @@
+import "@js-temporal/polyfill";
+import { Application, CryptographicKey, Multikey } from "@fedify/vocab";
+//#region src/bench/actor/documents.ts
+/**
+* Building the ActivityPub actor documents the synthetic key server serves.
+*
+* The target dereferences a signature's `keyId` during verification; serving a
+* normal actor document with an embedded `publicKey` (RSA, for HTTP and LD
+* Signatures) and `assertionMethod` (Ed25519 Multikey, for FEP-8b32) is exactly
+* what a real actor exposes, so verification resolves the key the same way.
+* @since 2.3.0
+* @module
+*/
+/**
+* Renders a synthetic actor as a compact JSON-LD actor document.
+* @param actor The synthetic actor, with its URLs and keys.
+* @param options The context loader used to compact the document.
+* @returns The JSON-LD actor document.
+*/
+async function actorDocument(actor, options) {
+	return await new Application({
+		id: actor.id,
+		preferredUsername: `bench-${actor.index}`,
+		name: actor.name ?? `Benchmark actor ${actor.index}`,
+		inbox: new URL(`${actor.id.href}/inbox`),
+		publicKey: actor.keys.rsa == null ? void 0 : new CryptographicKey({
+			id: actor.rsaKeyId,
+			owner: actor.id,
+			publicKey: actor.keys.rsa.publicKey
+		}),
+		assertionMethods: actor.keys.ed25519 == null ? [] : [new Multikey({
+			id: actor.ed25519KeyId,
+			controller: actor.id,
+			publicKey: actor.keys.ed25519.publicKey
+		})]
+	}).toJsonLd({ contextLoader: options.contextLoader });
+}
+//#endregion
+export { actorDocument };

package/dist/bench/actor/fleet.js

@@ -0,0 +1,39 @@
+import "@js-temporal/polyfill";
+import { generateActorKeys } from "./keys.js";
+//#region src/bench/actor/fleet.ts
+function httpStandardOf(standards) {
+	const http = standards.filter((s) => s === "draft-cavage-http-signatures-12" || s === "rfc9421");
+	if (http.length === 0) throw new TypeError("Every actor group must declare exactly one HTTP request signature standard.");
+	if (http.length > 1) throw new TypeError(`Every actor group must declare exactly one HTTP request signature standard, but multiple were given: ${http.join(", ")}.`);
+	return http[0];
+}
+/**
+* Builds the fleet from the suite's actor groups, generating each actor's keys.
+* When no groups are declared, a single default actor using
+* `draft-cavage-http-signatures-12` is created.
+* @param groups The suite's actor groups.
+* @returns The fleet members, with keys generated.
+*/
+async function buildFleet(groups) {
+	const effective = groups.length > 0 ? groups : [{ signatureStandards: ["draft-cavage-http-signatures-12"] }];
+	const members = [];
+	let index = 0;
+	for (const group of effective) {
+		const count = group.count ?? 1;
+		const standards = group.signatureStandards;
+		const httpStandard = httpStandardOf(standards);
+		for (let i = 0; i < count; i++) {
+			members.push({
+				index,
+				name: group.name,
+				standards,
+				keys: await generateActorKeys(standards),
+				httpStandard
+			});
+			index++;
+		}
+	}
+	return members;
+}
+//#endregion
+export { buildFleet };

package/dist/bench/actor/keys.js

@@ -0,0 +1,35 @@
+import "@js-temporal/polyfill";
+import { generateCryptoKeyPair } from "@fedify/fedify";
+//#region src/bench/actor/keys.ts
+/**
+* Key-pair generation for synthetic benchmark actors.
+*
+* An author picks signature standards, not key algorithms; the key set is
+* derived from the chosen standards, mirroring how a real Fedify actor exposes
+* keys.  HTTP request signatures and LD Signatures share one RSA key pair;
+* FEP-8b32 object integrity proofs use an Ed25519 key pair.
+* @since 2.3.0
+* @module
+*/
+/** Whether a set of standards needs an RSA key pair. */
+function needsRsa(standards) {
+	return standards.some((s) => s === "draft-cavage-http-signatures-12" || s === "rfc9421" || s === "ld-signatures");
+}
+/** Whether a set of standards needs an Ed25519 key pair. */
+function needsEd25519(standards) {
+	return standards.includes("fep8b32");
+}
+/**
+* Generates the key pairs an actor needs for its signature standards.
+* @param standards The actor's signature standards.
+* @returns The derived key pairs.
+*/
+async function generateActorKeys(standards) {
+	const [rsa, ed25519] = await Promise.all([needsRsa(standards) ? generateCryptoKeyPair("RSASSA-PKCS1-v1_5") : Promise.resolve(void 0), needsEd25519(standards) ? generateCryptoKeyPair("Ed25519") : Promise.resolve(void 0)]);
+	return {
+		rsa,
+		ed25519
+	};
+}
+//#endregion
+export { generateActorKeys };

package/dist/bench/command.js

@@ -0,0 +1,42 @@
+import "@js-temporal/polyfill";
+import { configContext } from "../config.js";
+import { userAgentOption } from "../options.js";
+import { argument, choice, command, constant, flag, group, merge, message, object, option, optional, string, withDefault } from "@optique/core";
+import { bindConfig } from "@optique/config";
+//#region src/bench/command.ts
+const formatOption = bindConfig(option("-f", "--format", choice([
+	"text",
+	"json",
+	"markdown"
+], { metavar: "FORMAT" }), { description: message`The output format for the benchmark report.` }), {
+	context: configContext,
+	key: (config) => config.bench?.format ?? "text",
+	default: "text"
+});
+const allowUnsafeTarget = withDefault(flag("--allow-unsafe-target", { description: message`Allow benchmarking a public target that does not advertise \
+benchmark mode.  Must be given on the command line for each run; it cannot be \
+set in a configuration file.` }), false);
+const benchCommand = command("bench", merge("Benchmark options", object({
+	command: constant("bench"),
+	scenario: group("Arguments", argument(string({ metavar: "SCENARIO_FILE" }), { description: message`Path to the benchmark suite file (YAML or JSON).` })),
+	target: optional(option("-t", "--target", string({ metavar: "URL" }), { description: message`Override the target URL declared in the suite.` })),
+	format: formatOption,
+	output: optional(option("-o", "--output", string({ metavar: "OUTPUT_PATH" }), { description: message`Write the report to a file instead of standard output.` })),
+	dryRun: withDefault(flag("--dry-run", { description: message`Print the normalized plan without contacting the target or \
+sending load.` }), false),
+	advertiseHost: optional(option("--advertise-host", string({ metavar: "HOST" }), { description: message`Host (name or IP) a non-loopback target can reach the \
+benchmark's synthetic actor server at.  Required for signed scenarios against a \
+non-loopback target; binds the synthetic server on all interfaces and uses this \
+host in the actor and key URLs the target dereferences.` })),
+	allowUnsafeTarget
+}), userAgentOption), {
+	brief: message`Benchmark a Fedify federation workload.`,
+	description: message`Run an ActivityPub-specific load benchmark against a \
+cooperative Fedify target running in benchmark mode.
+
+The suite file declares the target, actors, and scenarios.  Only the \`inbox\` \
+and \`webfinger\` scenario types are executed in this version; the format \
+itself can express every scenario type.`
+});
+//#endregion
+export { benchCommand };

package/dist/bench/discovery/discover.js

@@ -0,0 +1,67 @@
+import "@js-temporal/polyfill";
+import { getContextLoader, getDocumentLoader } from "../../docloader.js";
+import { convertUrlIfHandle } from "../../webfinger/lib.js";
+import { isActor, lookupObject } from "@fedify/vocab";
+//#region src/bench/discovery/discover.ts
+/**
+* Recipient discovery: resolving a handle or actor URI to the inbox URL a real
+* peer would deliver to.
+*
+* Discovery mirrors how a remote server finds an inbox: WebFinger on a handle
+* yields the actor URI, then the actor document yields its personal `inbox` and
+* its shared inbox endpoint.  `lookupObject()` performs the WebFinger step for
+* `acct:` identifiers automatically.
+* @since 2.3.0
+* @module
+*/
+/** An error raised when a recipient cannot be discovered. */
+var DiscoveryError = class extends Error {};
+/**
+* Discovers a recipient's inbox URLs from a handle or actor URI.
+* @param recipient A handle (`acct:alice@host` or `@alice@host`) or actor URI.
+* @param options Document/context loaders (use a private-address-allowing
+*                loader for loopback targets).
+* @returns The actor URI and its personal and shared inbox URLs.
+* @throws {DiscoveryError} If the recipient does not resolve to an actor with
+*         an inbox.
+*/
+async function discoverInbox(recipient, options = {}) {
+	const identifier = convertUrlIfHandle(recipient);
+	const { lookup = lookupObject, allowPrivateAddress } = options;
+	const documentLoader = options.documentLoader ?? (allowPrivateAddress ? await getDocumentLoader({ allowPrivateAddress: true }) : void 0);
+	const contextLoader = options.contextLoader ?? (allowPrivateAddress ? await getContextLoader({ allowPrivateAddress: true }) : void 0);
+	let object;
+	try {
+		object = await lookup(identifier, {
+			documentLoader,
+			contextLoader,
+			allowPrivateAddress
+		});
+	} catch (error) {
+		throw new DiscoveryError(`Failed to resolve recipient ${recipient}: ${error}`);
+	}
+	if (!isActor(object)) throw new DiscoveryError(`Recipient ${recipient} did not resolve to an actor.`);
+	if (object.inboxId == null) throw new DiscoveryError(`Actor ${recipient} has no inbox.`);
+	return {
+		actorUri: object.id ?? identifier,
+		personalInbox: object.inboxId,
+		sharedInbox: object.endpoints?.sharedInbox ?? null
+	};
+}
+/**
+* Chooses the inbox URL to deliver to for a scenario's `inbox` mode.
+*
+* `"shared"` (the default) prefers the shared inbox and falls back to the
+* personal one; `"personal"` uses the personal inbox; any other value is an
+* explicit inbox URL that skips discovery selection.
+* @param discovered The discovered inbox URLs.
+* @param mode The scenario's `inbox` value.
+* @returns The inbox URL to deliver to.
+*/
+function selectInbox(discovered, mode) {
+	if (mode != null && mode !== "shared" && mode !== "personal") return new URL(mode);
+	if (mode === "personal") return discovered.personalInbox;
+	return discovered.sharedInbox ?? discovered.personalInbox;
+}
+//#endregion
+export { discoverInbox, selectInbox };

package/dist/bench/discovery/probe.js

@@ -0,0 +1,50 @@
+import "@js-temporal/polyfill";
+//#region src/bench/discovery/probe.ts
+/** The path of the cooperative benchmark stats endpoint. */
+const STATS_PATH = "/.well-known/fedify/bench/stats";
+/**
+* Probes a target for benchmark mode.
+* @param target The target base URL.
+* @param fetchImpl The fetch implementation (overridable for tests).
+* @returns Whether benchmark mode is advertised and the target's Fedify
+*          version.  Never throws; a failed probe reports `benchmarkMode:
+*          false`.
+*/
+async function probeBenchmarkMode(target, fetchImpl = fetch) {
+	try {
+		const response = await fetchImpl(new URL(STATS_PATH, target), {
+			headers: { accept: "application/json" },
+			redirect: "manual"
+		});
+		if (!response.ok) return notAdvertised();
+		const json = await response.json();
+		if (json?.version === 1 && json?.source === "server") return {
+			benchmarkMode: true,
+			fedifyVersion: extractFedifyVersion(json)
+		};
+		return notAdvertised();
+	} catch {
+		return notAdvertised();
+	}
+}
+function notAdvertised() {
+	return {
+		benchmarkMode: false,
+		fedifyVersion: null
+	};
+}
+function extractFedifyVersion(json) {
+	try {
+		const scopes = Array.isArray(json.scopeMetrics) ? json.scopeMetrics : [];
+		for (const entry of scopes) {
+			if (entry == null || typeof entry !== "object") continue;
+			const descriptor = entry.scope;
+			if (descriptor == null || typeof descriptor !== "object") continue;
+			const { name, version } = descriptor;
+			if (name === "@fedify/fedify") return typeof version === "string" ? version : null;
+		}
+	} catch {}
+	return null;
+}
+//#endregion
+export { STATS_PATH, probeBenchmarkMode };

package/dist/bench/load/arrival.js

@@ -0,0 +1,27 @@
+import "@js-temporal/polyfill";
+//#region src/bench/load/arrival.ts
+/**
+* Lazily yields the scheduled arrival offsets (milliseconds from the start) for
+* a load run.  Yielding rather than materializing keeps memory flat for long,
+* high-rate runs.
+* @param options The scheduling options.
+* @yields Arrival offsets within `[0, durationMs)`, in increasing order.
+*/
+function* scheduleArrivals(options) {
+	const { ratePerSec, durationMs, arrival } = options;
+	if (ratePerSec <= 0 || durationMs <= 0) return;
+	const meanGapMs = 1e3 / ratePerSec;
+	if (arrival === "constant") {
+		for (let t = 0; t < durationMs; t += meanGapMs) yield t;
+		return;
+	}
+	const rng = options.rng ?? Math.random;
+	let t = 0;
+	for (;;) {
+		t += -Math.log(1 - rng()) * meanGapMs;
+		if (t >= durationMs) break;
+		yield t;
+	}
+}
+//#endregion
+export { scheduleArrivals };

package/dist/bench/load/clock.js

@@ -0,0 +1,15 @@
+import "@js-temporal/polyfill";
+//#region src/bench/load/clock.ts
+/** Returns a clock backed by `performance.now()` and `setTimeout`. */
+function systemClock() {
+	return {
+		now: () => performance.now(),
+		sleepUntil(timeMs) {
+			const remaining = timeMs - performance.now();
+			if (remaining <= 0) return Promise.resolve();
+			return new Promise((resolve) => setTimeout(resolve, remaining));
+		}
+	};
+}
+//#endregion
+export { systemClock };

package/dist/bench/load/generator.js

@@ -0,0 +1,112 @@
+import "@js-temporal/polyfill";
+import { scheduleArrivals } from "./arrival.js";
+import { systemClock } from "./clock.js";
+//#region src/bench/load/generator.ts
+/**
+* Runs a load plan against a send function.
+* @param plan The load plan.
+* @param send The function that performs one send.
+* @param clock The clock (overridable for tests); defaults to the system clock.
+* @returns The recorded samples and run metadata.
+*/
+function runLoad(plan, send, clock = systemClock()) {
+	return plan.load.kind === "open" ? runOpenLoop(plan, plan.load, send, clock) : runClosedLoop(plan, plan.load, send, clock);
+}
+async function runOpenLoop(plan, load, send, clock) {
+	const arrivals = scheduleArrivals({
+		ratePerSec: load.ratePerSec,
+		durationMs: plan.durationMs,
+		arrival: load.arrival,
+		rng: plan.rng
+	});
+	const samples = [];
+	const slots = createSemaphore(load.maxInFlight);
+	let saturated = false;
+	const start = clock.now();
+	const active = /* @__PURE__ */ new Set();
+	for (const offset of arrivals) {
+		await clock.sleepUntil(start + offset);
+		if (await slots.acquire()) saturated = true;
+		const dispatched = dispatch(send, offset, start, plan.warmupMs, clock, samples).finally(() => {
+			slots.release();
+			active.delete(dispatched);
+		});
+		active.add(dispatched);
+	}
+	await Promise.all(active);
+	return {
+		samples,
+		saturated,
+		wallDurationMs: clock.now() - start
+	};
+}
+async function runClosedLoop(plan, load, send, clock) {
+	const samples = [];
+	const slots = createSemaphore(load.maxInFlight);
+	let saturated = false;
+	const start = clock.now();
+	const deadline = start + plan.durationMs;
+	async function worker() {
+		while (clock.now() < deadline) {
+			if (await slots.acquire()) saturated = true;
+			if (clock.now() >= deadline) {
+				slots.release();
+				break;
+			}
+			const offset = clock.now() - start;
+			try {
+				await dispatch(send, offset, start, plan.warmupMs, clock, samples);
+			} finally {
+				slots.release();
+			}
+		}
+	}
+	await Promise.all(Array.from({ length: load.concurrency }, () => worker()));
+	return {
+		samples,
+		saturated,
+		wallDurationMs: clock.now() - start
+	};
+}
+async function dispatch(send, offset, start, warmupMs, clock, samples) {
+	let outcome;
+	try {
+		outcome = await send(offset);
+	} catch (error) {
+		outcome = {
+			ok: false,
+			errorKind: "exception",
+			reason: String(error)
+		};
+	}
+	samples.push({
+		scheduledAtMs: offset,
+		latencyMs: clock.now() - (start + offset),
+		warmup: offset < warmupMs,
+		outcome
+	});
+}
+function createSemaphore(max) {
+	if (max == null) return {
+		acquire: () => Promise.resolve(false),
+		release: () => {}
+	};
+	let count = 0;
+	const queue = [];
+	return {
+		acquire() {
+			if (count < max) {
+				count++;
+				return Promise.resolve(false);
+			}
+			return new Promise((resolve) => queue.push(() => resolve(true)));
+		},
+		release() {
+			const next = queue.shift();
+			if (next != null) next();
+			else count--;
+		}
+	};
+}
+//#endregion
+export { runLoad };