@fedify/cli 2.3.0-dev.994 → 2.3.1

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,33 @@
+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, signal) {
+			if (signal?.aborted) return Promise.reject(abortReason(signal));
+			const remaining = timeMs - performance.now();
+			if (remaining <= 0) return Promise.resolve();
+			return new Promise((resolve, reject) => {
+				const timer = setTimeout(() => {
+					cleanup();
+					resolve();
+				}, remaining);
+				const onAbort = () => {
+					clearTimeout(timer);
+					cleanup();
+					reject(abortReason(signal));
+				};
+				const cleanup = () => {
+					signal?.removeEventListener("abort", onAbort);
+				};
+				signal?.addEventListener("abort", onAbort, { once: true });
+			});
+		}
+	};
+}
+function abortReason(signal) {
+	return signal.reason ?? /* @__PURE__ */ new Error("Operation aborted.");
+}
+//#endregion
+export { systemClock };

package/dist/bench/load/generator.js

@@ -0,0 +1,145 @@
+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(), signal) {
+	return plan.load.kind === "open" ? runOpenLoop(plan, plan.load, send, clock, signal) : runClosedLoop(plan, plan.load, send, clock, signal);
+}
+async function runOpenLoop(plan, load, send, clock, signal) {
+	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) {
+		throwIfAborted(signal);
+		await clock.sleepUntil(start + offset, signal);
+		if (await slots.acquire(signal)) saturated = true;
+		if (signal?.aborted) {
+			slots.release();
+			throw abortReason(signal);
+		}
+		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, signal) {
+	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) {
+			throwIfAborted(signal);
+			if (await slots.acquire(signal)) saturated = true;
+			if (signal?.aborted) {
+				slots.release();
+				throw abortReason(signal);
+			}
+			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(signal) {
+			throwIfAborted(signal);
+			if (count < max) {
+				count++;
+				return Promise.resolve(false);
+			}
+			return new Promise((resolve, reject) => {
+				const waiter = () => {
+					cleanup();
+					resolve(true);
+				};
+				const onAbort = () => {
+					const index = queue.indexOf(waiter);
+					if (index >= 0) queue.splice(index, 1);
+					cleanup();
+					reject(abortReason(signal));
+				};
+				const cleanup = () => {
+					signal?.removeEventListener("abort", onAbort);
+				};
+				signal?.addEventListener("abort", onAbort, { once: true });
+				queue.push(waiter);
+			});
+		},
+		release() {
+			const next = queue.shift();
+			if (next != null) next();
+			else count--;
+		}
+	};
+}
+function throwIfAborted(signal) {
+	if (signal?.aborted) throw abortReason(signal);
+}
+function abortReason(signal) {
+	return signal.reason ?? /* @__PURE__ */ new Error("Benchmark load aborted.");
+}
+//#endregion
+export { runLoad };

package/dist/bench/metrics/aggregate.js

@@ -0,0 +1,64 @@
+import "@js-temporal/polyfill";
+import { LogLinearHistogram } from "./histogram.js";
+//#region src/bench/metrics/aggregate.ts
+/**
+* Aggregates samples into the client side of a scenario measurement (the
+* `server` field is left `null` for the runner to fill from the stats endpoint).
+* @param samples The raw samples from the load generator.
+* @param options Aggregation options.
+* @returns The client-side scenario measurement.
+*/
+function aggregateSamples(samples, options) {
+	const measured = samples.filter((s) => !s.warmup);
+	const histogram = new LogLinearHistogram();
+	const errorCounts = /* @__PURE__ */ new Map();
+	let ok = 0;
+	for (const sample of measured) {
+		histogram.record(sample.latencyMs);
+		if (sample.outcome.ok) ok++;
+		else bucketError(errorCounts, sample);
+	}
+	const total = measured.length;
+	const requests = {
+		total,
+		ok,
+		failed: total - ok,
+		successRate: total === 0 ? 1 : ok / total
+	};
+	const windowSec = Math.max(options.measuredWindowMs, 1) / 1e3;
+	const client = { latencyMs: {
+		p50: histogram.percentile(50),
+		p95: histogram.percentile(95),
+		p99: histogram.percentile(99),
+		mean: histogram.mean,
+		max: histogram.max
+	} };
+	const errors = [...errorCounts.values()].sort((a, b) => b.count - a.count);
+	return {
+		requests,
+		throughputPerSec: total / windowSec,
+		client,
+		server: null,
+		errors,
+		...options.includeHistogram ? { histogram: histogram.toJSON() } : {}
+	};
+}
+function bucketError(buckets, sample) {
+	const { status, errorKind, reason } = sample.outcome;
+	const kind = errorKind ?? (status != null ? "http" : "error");
+	const reasonText = reason ?? (status != null ? `status_${status}` : "error");
+	const key = `${kind}|${status ?? ""}|${reasonText}`;
+	const existing = buckets.get(key);
+	if (existing != null) buckets.set(key, {
+		...existing,
+		count: existing.count + 1
+	});
+	else buckets.set(key, {
+		kind,
+		...status != null ? { status } : {},
+		reason: reasonText,
+		count: 1
+	});
+}
+//#endregion
+export { aggregateSamples };

package/dist/bench/metrics/histogram.js

@@ -0,0 +1,141 @@
+import "@js-temporal/polyfill";
+/**
+* A sparse log-linear histogram.
+* @since 2.3.0
+*/
+var LogLinearHistogram = class LogLinearHistogram {
+	subBucketCount;
+	#buckets = /* @__PURE__ */ new Map();
+	#count = 0;
+	#zeroCount = 0;
+	#sum = 0;
+	#min = Number.POSITIVE_INFINITY;
+	#max = Number.NEGATIVE_INFINITY;
+	constructor(options = {}) {
+		const subBucketCount = options.subBucketCount ?? 128;
+		if (!Number.isInteger(subBucketCount) || subBucketCount < 1) throw new RangeError(`subBucketCount must be a positive integer; got ${subBucketCount}.`);
+		this.subBucketCount = subBucketCount;
+	}
+	/** The total number of recorded samples, including zeros. */
+	get count() {
+		return this.#count;
+	}
+	/** The smallest recorded value, or `0` when the histogram is empty. */
+	get min() {
+		return this.#count === 0 ? 0 : this.#min;
+	}
+	/** The largest recorded value, or `0` when the histogram is empty. */
+	get max() {
+		return this.#count === 0 ? 0 : this.#max;
+	}
+	/** The arithmetic mean of all recorded values, or `0` when empty. */
+	get mean() {
+		return this.#count === 0 ? 0 : this.#sum / this.#count;
+	}
+	/** The exact sum of all recorded values. */
+	get sum() {
+		return this.#sum;
+	}
+	/**
+	* Records a single sample.
+	* @param value The value to record.  Non-finite values are ignored; any
+	*              non-positive value (negatives, `0`, and `-0`) is normalized to
+	*              `0` and recorded in the zero bucket, since latency samples are
+	*              never negative.
+	*/
+	record(value) {
+		if (!Number.isFinite(value)) return;
+		const v = value <= 0 ? 0 : value;
+		this.#count++;
+		this.#sum += v;
+		if (v < this.#min) this.#min = v;
+		if (v > this.#max) this.#max = v;
+		if (v === 0) {
+			this.#zeroCount++;
+			return;
+		}
+		const index = this.#indexOf(v);
+		this.#buckets.set(index, (this.#buckets.get(index) ?? 0) + 1);
+	}
+	/**
+	* Computes an estimated percentile.
+	* @param p The percentile to compute, between 0 and 100 inclusive.
+	* @returns The estimated value at the given percentile, or `0` when the
+	*          histogram is empty.
+	*/
+	percentile(p) {
+		if (this.#count === 0) return 0;
+		if (p <= 0) return this.#min;
+		if (p >= 100) return this.#max;
+		const target = Math.ceil(p / 100 * this.#count);
+		let accumulated = this.#zeroCount;
+		if (accumulated >= target) return 0;
+		const indices = [...this.#buckets.keys()].sort((a, b) => a - b);
+		for (const index of indices) {
+			accumulated += this.#buckets.get(index);
+			if (accumulated >= target) return this.#clamp(this.#representativeValue(index));
+		}
+		return this.#max;
+	}
+	/**
+	* Merges another histogram into this one.  Both histograms must use the same
+	* {@link LogLinearHistogram.subBucketCount}.
+	* @param other The histogram to merge in.
+	*/
+	merge(other) {
+		if (other.subBucketCount !== this.subBucketCount) throw new TypeError(`Cannot merge histograms with different subBucketCount (${this.subBucketCount} vs ${other.subBucketCount}).`);
+		if (other.#count === 0) return;
+		for (const [index, count] of other.#buckets) this.#buckets.set(index, (this.#buckets.get(index) ?? 0) + count);
+		this.#count += other.#count;
+		this.#zeroCount += other.#zeroCount;
+		this.#sum += other.#sum;
+		if (other.#min < this.#min) this.#min = other.#min;
+		if (other.#max > this.#max) this.#max = other.#max;
+	}
+	/** Serializes the histogram to a plain JSON-compatible object. */
+	toJSON() {
+		const indices = [...this.#buckets.keys()].sort((a, b) => a - b);
+		return {
+			version: 1,
+			subBucketCount: this.subBucketCount,
+			count: this.#count,
+			zeroCount: this.#zeroCount,
+			min: this.min,
+			max: this.max,
+			sum: this.#sum,
+			indices,
+			counts: indices.map((index) => this.#buckets.get(index))
+		};
+	}
+	/** Reconstructs a histogram from its serialized form. */
+	static fromJSON(json) {
+		if (json.indices.length !== json.counts.length) throw new TypeError("Serialized histogram indices and counts must have equal length.");
+		const histogram = new LogLinearHistogram({ subBucketCount: json.subBucketCount });
+		for (let i = 0; i < json.indices.length; i++) histogram.#buckets.set(json.indices[i], json.counts[i]);
+		histogram.#count = json.count;
+		histogram.#zeroCount = json.zeroCount;
+		histogram.#sum = json.sum;
+		histogram.#min = json.count === 0 ? Number.POSITIVE_INFINITY : json.min;
+		histogram.#max = json.count === 0 ? Number.NEGATIVE_INFINITY : json.max;
+		return histogram;
+	}
+	#indexOf(value) {
+		const octave = Math.floor(Math.log2(value));
+		let sub = Math.floor((value / 2 ** octave - 1) * this.subBucketCount);
+		if (sub < 0) sub = 0;
+		else if (sub >= this.subBucketCount) sub = this.subBucketCount - 1;
+		return octave * this.subBucketCount + sub;
+	}
+	#representativeValue(index) {
+		const octave = Math.floor(index / this.subBucketCount);
+		const sub = index - octave * this.subBucketCount;
+		return 2 ** octave * (1 + (sub + .5) / this.subBucketCount);
+	}
+	#clamp(value) {
+		if (value < this.#min) return this.#min;
+		if (value > this.#max) return this.#max;
+		return value;
+	}
+};
+//#endregion
+export { LogLinearHistogram };