@fedify/cli 2.3.0-dev.994 → 2.4.0-dev.1417

package/dist/bench/result/schema.js

@@ -0,0 +1,365 @@
+import "@js-temporal/polyfill";
+//#region src/bench/result/schema.ts
+/**
+* The embedded JSON Schema (draft 2020-12) for benchmark report output.
+*
+* Like the scenario schema, this object is the runtime copy and is published,
+* byte-for-byte, as files under *schema/bench/*; a drift guard keeps the two in
+* sync.  The matching TypeScript types live in {@link ./model.ts}.
+* @since 2.3.0
+* @module
+*/
+/** The hosted URL that serves the report schema. */
+const REPORT_SCHEMA_ID = "https://json-schema.fedify.dev/bench/report-v3.json";
+/** The hosted URL for the version 2 report schema. */
+const REPORT_SCHEMA_V2_ID = "https://json-schema.fedify.dev/bench/report-v2.json";
+/** The benchmark report JSON Schema (draft 2020-12). */
+const reportSchemaV1 = {
+	$schema: "https://json-schema.org/draft/2020-12/schema",
+	$id: "https://json-schema.fedify.dev/bench/report-v1.json",
+	title: "Fedify benchmark report",
+	type: "object",
+	additionalProperties: false,
+	required: [
+		"schemaVersion",
+		"tool",
+		"environment",
+		"target",
+		"startedAt",
+		"finishedAt",
+		"suite",
+		"passed",
+		"scenarios"
+	],
+	properties: {
+		$schema: { type: "string" },
+		schemaVersion: { const: 1 },
+		tool: {
+			type: "object",
+			additionalProperties: false,
+			required: ["name", "version"],
+			properties: {
+				name: { type: "string" },
+				version: { type: "string" }
+			}
+		},
+		environment: {
+			type: "object",
+			additionalProperties: false,
+			required: [
+				"runtime",
+				"runtimeVersion",
+				"os",
+				"cpuCount"
+			],
+			properties: {
+				runtime: { type: "string" },
+				runtimeVersion: { type: "string" },
+				os: { type: "string" },
+				cpuCount: {
+					type: "integer",
+					minimum: 0
+				}
+			}
+		},
+		target: {
+			type: "object",
+			additionalProperties: false,
+			required: ["url", "statsAvailable"],
+			properties: {
+				url: { type: "string" },
+				fedifyVersion: { type: ["string", "null"] },
+				statsAvailable: { type: "boolean" }
+			}
+		},
+		startedAt: { type: "string" },
+		finishedAt: { type: "string" },
+		suite: {
+			type: "object",
+			additionalProperties: false,
+			required: ["configHash"],
+			properties: {
+				name: { type: "string" },
+				configHash: { type: "string" }
+			}
+		},
+		passed: { type: "boolean" },
+		scenarios: {
+			type: "array",
+			items: { $ref: "#/$defs/scenarioResult" }
+		}
+	},
+	$defs: {
+		latencyMs: {
+			type: "object",
+			additionalProperties: false,
+			required: [
+				"p50",
+				"p95",
+				"p99",
+				"mean",
+				"max"
+			],
+			properties: {
+				p50: { type: "number" },
+				p95: { type: "number" },
+				p99: { type: "number" },
+				mean: { type: "number" },
+				max: { type: "number" }
+			}
+		},
+		partialLatencyMs: {
+			type: "object",
+			additionalProperties: false,
+			properties: {
+				p50: { type: "number" },
+				p95: { type: "number" },
+				p99: { type: "number" }
+			}
+		},
+		loadSummary: {
+			type: "object",
+			additionalProperties: false,
+			required: [
+				"model",
+				"durationMs",
+				"warmupMs"
+			],
+			properties: {
+				model: { enum: ["open", "closed"] },
+				ratePerSec: { type: "number" },
+				arrival: { type: "string" },
+				concurrency: { type: "integer" },
+				durationMs: { type: "number" },
+				warmupMs: { type: "number" },
+				maxInFlight: { type: "integer" }
+			},
+			oneOf: [{
+				properties: { model: { const: "open" } },
+				required: ["ratePerSec", "arrival"],
+				not: { required: ["concurrency"] }
+			}, {
+				properties: { model: { const: "closed" } },
+				required: ["concurrency"],
+				not: { anyOf: [{ required: ["ratePerSec"] }, { required: ["arrival"] }] }
+			}]
+		},
+		requestSummary: {
+			type: "object",
+			additionalProperties: false,
+			required: [
+				"total",
+				"ok",
+				"failed",
+				"successRate"
+			],
+			properties: {
+				total: {
+					type: "integer",
+					minimum: 0
+				},
+				ok: {
+					type: "integer",
+					minimum: 0
+				},
+				failed: {
+					type: "integer",
+					minimum: 0
+				},
+				successRate: {
+					type: "number",
+					minimum: 0,
+					maximum: 1
+				}
+			}
+		},
+		clientMetrics: {
+			type: "object",
+			additionalProperties: false,
+			required: ["latencyMs"],
+			properties: { latencyMs: { $ref: "#/$defs/latencyMs" } }
+		},
+		serverMetrics: {
+			type: "object",
+			additionalProperties: false,
+			properties: {
+				signatureVerificationMs: {
+					type: "object",
+					additionalProperties: false,
+					required: ["overall"],
+					properties: {
+						overall: { $ref: "#/$defs/partialLatencyMs" },
+						byStandard: {
+							type: "object",
+							additionalProperties: { $ref: "#/$defs/partialLatencyMs" }
+						}
+					}
+				},
+				queue: {
+					type: "object",
+					additionalProperties: false,
+					properties: {
+						drainMs: { $ref: "#/$defs/partialLatencyMs" },
+						depthMax: { type: "number" }
+					}
+				}
+			}
+		},
+		errorBucket: {
+			type: "object",
+			additionalProperties: false,
+			required: [
+				"kind",
+				"reason",
+				"count"
+			],
+			properties: {
+				kind: { type: "string" },
+				status: { type: "integer" },
+				reason: { type: "string" },
+				count: {
+					type: "integer",
+					minimum: 0
+				}
+			}
+		},
+		expectResult: {
+			type: "object",
+			additionalProperties: false,
+			required: [
+				"metric",
+				"op",
+				"threshold",
+				"unit",
+				"actual",
+				"severity",
+				"pass"
+			],
+			properties: {
+				metric: { type: "string" },
+				op: { enum: [
+					"lt",
+					"lte",
+					"gt",
+					"gte",
+					"eq"
+				] },
+				threshold: { type: "number" },
+				unit: { type: ["string", "null"] },
+				actual: { type: ["number", "null"] },
+				severity: { enum: ["warn", "fail"] },
+				pass: { type: "boolean" }
+			}
+		},
+		scenarioResult: {
+			type: "object",
+			additionalProperties: false,
+			required: [
+				"name",
+				"type",
+				"load",
+				"requests",
+				"throughputPerSec",
+				"client",
+				"server",
+				"errors",
+				"expectations",
+				"passed"
+			],
+			properties: {
+				name: { type: "string" },
+				type: { enum: [
+					"inbox",
+					"webfinger",
+					"actor",
+					"object",
+					"fanout",
+					"collection",
+					"failure",
+					"mixed"
+				] },
+				load: { $ref: "#/$defs/loadSummary" },
+				requests: { $ref: "#/$defs/requestSummary" },
+				throughputPerSec: { type: "number" },
+				client: { $ref: "#/$defs/clientMetrics" },
+				server: { anyOf: [{ $ref: "#/$defs/serverMetrics" }, { type: "null" }] },
+				errors: {
+					type: "array",
+					items: { $ref: "#/$defs/errorBucket" }
+				},
+				expectations: {
+					type: "array",
+					items: { $ref: "#/$defs/expectResult" }
+				},
+				passed: { type: "boolean" },
+				histogram: { $ref: "#/$defs/serializedHistogram" }
+			}
+		},
+		serializedHistogram: {
+			type: "object",
+			additionalProperties: false,
+			required: [
+				"version",
+				"subBucketCount",
+				"count",
+				"zeroCount",
+				"min",
+				"max",
+				"sum",
+				"indices",
+				"counts"
+			],
+			properties: {
+				version: { const: 1 },
+				subBucketCount: {
+					type: "integer",
+					minimum: 1
+				},
+				count: {
+					type: "integer",
+					minimum: 0
+				},
+				zeroCount: {
+					type: "integer",
+					minimum: 0
+				},
+				min: { type: "number" },
+				max: { type: "number" },
+				sum: { type: "number" },
+				indices: {
+					type: "array",
+					items: { type: "integer" }
+				},
+				counts: {
+					type: "array",
+					items: {
+						type: "integer",
+						minimum: 0
+					}
+				}
+			}
+		}
+	}
+};
+/** The benchmark report JSON Schema (draft 2020-12). */
+const reportSchemaV2 = {
+	...reportSchemaV1,
+	$id: REPORT_SCHEMA_V2_ID,
+	properties: {
+		...reportSchemaV1.properties,
+		schemaVersion: { const: 2 }
+	},
+	$defs: {
+		...reportSchemaV1.$defs,
+		scenarioResult: {
+			...reportSchemaV1.$defs.scenarioResult,
+			properties: {
+				...reportSchemaV1.$defs.scenarioResult.properties,
+				deliveryThroughputPerSec: { type: "number" }
+			}
+		}
+	}
+};
+({ ...reportSchemaV2 }), { ...reportSchemaV2.properties }, { ...reportSchemaV2.$defs }, { ...reportSchemaV2.$defs.scenarioResult }, [...reportSchemaV2.$defs.scenarioResult.required], { ...reportSchemaV2.$defs.scenarioResult.properties };
+//#endregion
+export { REPORT_SCHEMA_ID };

package/dist/bench/safety/gate.js

@@ -0,0 +1,62 @@
+import "@js-temporal/polyfill";
+//#region src/bench/safety/gate.ts
+/** An error raised when a target is refused by the safety gate. */
+var UnsafeTargetError = class extends Error {};
+/**
+* Asserts that a target may be benchmarked, throwing otherwise.
+* @param context The gate decision inputs.
+* @throws {UnsafeTargetError} If the target is public, does not advertise
+*         benchmark mode, and `--allow-unsafe-target` was not given.
+*/
+function assertTargetAllowed(context) {
+	if (context.dryRun) return;
+	if (context.tier !== "public") return;
+	if (context.benchmarkMode) return;
+	if (context.allowUnsafe) return;
+	throw new UnsafeTargetError("Refusing to benchmark a public target that does not advertise benchmark mode.  If you control this target, pass --allow-unsafe-target (mandatory in CI and any non-interactive context).");
+}
+/**
+* Asserts that an unsafe public-target override is specific and bounded.
+*
+* The override is only meaningful for a public target that does not advertise
+* benchmark mode.  In that caution tier, the operator must name the target on
+* the command line for this run and must explicitly set load, duration, and
+* runs, so the built-in defaults cannot accidentally create a long public
+* benchmark.
+* @param context The unsafe override decision inputs.
+* @throws {UnsafeTargetError} If the unsafe override is too broad.
+*/
+function assertUnsafeOverrideAllowed(context) {
+	if (context.tier !== "public" || context.benchmarkMode || !context.allowUnsafe) return;
+	if (!context.explicitCliTarget) throw new UnsafeTargetError("The --allow-unsafe-target override must be paired with an explicit --target for this run.");
+	for (const scenario of context.scenarios) {
+		if (!scenario.explicitLoad) throw new UnsafeTargetError(`Scenario "${scenario.name}" uses the built-in benchmark load default.  Set rate or concurrency explicitly before using --allow-unsafe-target against a public target.`);
+		if (!scenario.explicitDuration) throw new UnsafeTargetError(`Scenario "${scenario.name}" uses the built-in benchmark duration default.  Set duration explicitly before using --allow-unsafe-target against a public target.`);
+		if (!scenario.explicitRuns) throw new UnsafeTargetError(`Scenario "${scenario.name}" uses the built-in benchmark runs default.  Set runs explicitly before using --allow-unsafe-target against a public target.`);
+	}
+}
+/**
+* Asserts that a resolved inbox URL — the actual destination of signed
+* benchmark load — may be sent to.  The suite's `target` is gated separately by
+* {@link assertTargetAllowed}; this catches a destination that differs from it
+* (a public `recipient`, or an explicit `inbox:` URL), so production cannot be
+* benchmarked through the back door.
+*
+* A destination is allowed when it is loopback or private, or shares the gated
+* target's host while the target advertises benchmark mode (inheriting its
+* gate), or `--allow-unsafe-target` is given.  Because the destination's server
+* dereferences the synthetic actor while verifying signatures, a non-loopback
+* destination additionally requires an advertised, reachable synthetic host.
+* @param url The resolved inbox URL.
+* @param context The destination gate inputs.
+* @throws {UnsafeTargetError} If the destination is refused.
+*/
+function assertInboxDestinationAllowed(url, context) {
+	const sameOrigin = url.origin === context.targetOrigin;
+	const tier = sameOrigin ? context.targetTier : context.destinationTier;
+	const inheritsTargetGate = sameOrigin && context.targetBenchmarkMode;
+	if (tier === "public" && !inheritsTargetGate && !context.allowUnsafe) throw new UnsafeTargetError(`Refusing to send benchmark load to ${url.href}: it is a public inbox that is neither part of the benchmarked target nor covered by benchmark mode.  Pass --allow-unsafe-target to override.`);
+	if (tier !== "loopback" && !context.advertised) throw new UnsafeTargetError(`Refusing to send signed benchmark load to ${url.href}: the synthetic actor server is unreachable from a non-loopback inbox.  Pass --advertise-host with an address it can reach.`);
+}
+//#endregion
+export { UnsafeTargetError, assertInboxDestinationAllowed, assertTargetAllowed, assertUnsafeOverrideAllowed };

package/dist/bench/safety/tiers.js

@@ -0,0 +1,97 @@
+import "@js-temporal/polyfill";
+import { lookup } from "node:dns/promises";
+//#region src/bench/safety/tiers.ts
+/**
+* Target risk classification.
+*
+* A target is `loopback` or `private` when it is clearly one of the operator's
+* own boxes, and `public` otherwise.  Classification is conservative: a host
+* that is not obviously loopback or private is treated as `public` (the gated
+* tier), since the tool cannot tell staging from production without resolving
+* and trusting DNS.
+* @since 2.3.0
+* @module
+*/
+/**
+* Classifies a target URL into a risk tier from its host.
+* @param target The target URL.
+* @returns The risk tier.
+*/
+function classifyTarget(target) {
+	let host = target.hostname.replace(/^\[/, "").replace(/\]$/, "").toLowerCase();
+	if (host.endsWith(".")) host = host.slice(0, -1);
+	if (host === "localhost" || host.endsWith(".localhost")) return "loopback";
+	if (host.endsWith(".local")) return "private";
+	if (isIpv4(host)) return classifyIpv4(host);
+	if (host.includes(":")) return classifyIpv6(host);
+	return "public";
+}
+/**
+* Classifies a target URL, resolving DNS for public-looking hostnames.
+*
+* Literal addresses and known local hostname suffixes are classified directly.
+* Other hostnames are resolved and classified from their addresses; any public
+* address in the answer keeps the target public, and DNS failure is treated as
+* public so the safety gate remains conservative.
+* @param target The target URL.
+* @param resolveAddresses Hostname resolver, overridable for tests.
+* @returns The resolved target tier.
+*/
+async function classifyResolvedTarget(target, resolveAddresses = defaultResolveTargetAddresses) {
+	const host = normalizedHost(target);
+	const direct = classifyTarget(target);
+	if (direct !== "public" || isIpLiteral(host)) return direct;
+	try {
+		const resolved = await resolveAddresses(host);
+		if (!Array.isArray(resolved) || resolved.length < 1) return "public";
+		let aggregate = "loopback";
+		for (const address of resolved) {
+			const tier = classifyTarget(new URL(`http://${hostForAddress(address)}/`));
+			if (tier === "public") return "public";
+			if (tier === "private") aggregate = "private";
+		}
+		return aggregate;
+	} catch {
+		return "public";
+	}
+}
+/** Resolves a hostname with the platform DNS resolver. */
+async function defaultResolveTargetAddresses(hostname) {
+	return (await lookup(hostname, { all: true })).map((entry) => entry.address);
+}
+function normalizedHost(target) {
+	let host = target.hostname.replace(/^\[/, "").replace(/\]$/, "").toLowerCase();
+	if (host.endsWith(".")) host = host.slice(0, -1);
+	return host;
+}
+function isIpLiteral(host) {
+	return isIpv4(host) || host.includes(":");
+}
+function hostForAddress(address) {
+	return address.includes(":") ? `[${address}]` : address;
+}
+function isIpv4(host) {
+	const match = host.match(/^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/);
+	return match != null && match.slice(1).every((octet) => Number(octet) <= 255);
+}
+function classifyIpv4(host) {
+	if (host === "0.0.0.0" || /^127\./.test(host)) return "loopback";
+	if (/^10\./.test(host) || /^192\.168\./.test(host) || /^172\.(1[6-9]|2\d|3[01])\./.test(host) || /^169\.254\./.test(host)) return "private";
+	return "public";
+}
+function classifyIpv6(host) {
+	if (host === "::1") return "loopback";
+	const dotted = host.match(/^::ffff:(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/);
+	if (dotted != null && isIpv4(dotted[1])) return classifyIpv4(dotted[1]);
+	const hex = host.match(/^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/);
+	if (hex != null) {
+		const hi = Number.parseInt(hex[1], 16);
+		const lo = Number.parseInt(hex[2], 16);
+		return classifyIpv4(`${hi >> 8 & 255}.${hi & 255}.${lo >> 8 & 255}.${lo & 255}`);
+	}
+	if (/^f[cd][0-9a-f]*:/.test(host)) return "private";
+	if (/^fe[89ab][0-9a-f]*:/.test(host)) return "private";
+	return "public";
+}
+//#endregion
+export { classifyResolvedTarget };

package/dist/bench/scenario/coerce.js

@@ -0,0 +1,24 @@
+import "@js-temporal/polyfill";
+//#region src/bench/scenario/coerce.ts
+/**
+* Scalar-or-list coercion used throughout the scenario format, where many
+* fields (`recipient`, `seed`, `collection`, `type`, and so on) accept either a
+* single value or a list of values so the common single-value case stays terse.
+* @since 2.3.0
+* @module
+*/
+/**
+* Normalizes a scalar-or-list value into an array.
+*
+* A single value becomes a one-element array, an array is shallow-copied, and
+* `null`/`undefined` becomes an empty array.
+* @typeParam T The element type.
+* @param value A single value, a list of values, or nothing.
+* @returns A new array of values.
+*/
+function asList(value) {
+	if (value == null) return [];
+	return Array.isArray(value) ? [...value] : [value];
+}
+//#endregion
+export { asList };

package/dist/bench/scenario/errors.js

@@ -0,0 +1,36 @@
+import "@js-temporal/polyfill";
+//#region src/bench/scenario/errors.ts
+/** An error raised when a scenario suite fails schema validation. */
+var SuiteValidationError = class extends Error {
+	/** The individual validation problems, most specific first. */
+	problems;
+	constructor(problems, source) {
+		super(formatMessage(problems, source));
+		this.name = "SuiteValidationError";
+		this.problems = problems;
+	}
+};
+function formatMessage(problems, source) {
+	const where = source == null ? "scenario suite" : source;
+	if (problems.length === 0) return `Invalid ${where}.`;
+	return `Invalid ${where}:\n${dedupe(problems).map((problem) => {
+		return `  - ${problem.instanceLocation === "#" || problem.instanceLocation === "" ? "(root)" : problem.instanceLocation.replace(/^#/, "")}: ${problem.error}`;
+	}).join("\n")}`;
+}
+function dedupe(problems) {
+	const seen = /* @__PURE__ */ new Set();
+	const result = [];
+	const sorted = [...problems].sort((a, b) => depth(b.instanceLocation) - depth(a.instanceLocation));
+	for (const problem of sorted) {
+		const key = JSON.stringify([problem.instanceLocation, problem.error]);
+		if (seen.has(key)) continue;
+		seen.add(key);
+		result.push(problem);
+	}
+	return result;
+}
+function depth(instanceLocation) {
+	return (instanceLocation.match(/\//g) ?? []).length;
+}
+//#endregion
+export { SuiteValidationError };

package/dist/bench/scenario/load.js

@@ -0,0 +1,69 @@
+import "@js-temporal/polyfill";
+import { defaultHelpers } from "../template/helpers.js";
+import { renderTemplates } from "../template/template.js";
+import { readFile } from "node:fs/promises";
+import { parse } from "yaml";
+//#region src/bench/scenario/load.ts
+/**
+* Reading and parsing scenario suite files.
+*
+* Files may be written in YAML or JSON; because YAML is a superset of JSON, a
+* single YAML parser handles both, and YAML anchors/aliases are available for
+* in-document reuse.
+* @since 2.3.0
+* @module
+*/
+/**
+* Parses scenario suite text (YAML or JSON) into an untyped value.
+* @param text The file contents.
+* @returns The parsed value, to be validated with `validateSuite()`.
+*/
+function parseSuiteText(text) {
+	return parse(text);
+}
+/**
+* Reads and parses a scenario suite file.
+* @param path The path to the suite file.
+* @returns The parsed value, to be validated with `validateSuite()`.
+*/
+async function loadSuiteFile(path) {
+	return parseSuiteText(await readFile(path, { encoding: "utf-8" }));
+}
+/**
+* Expands `${{ ... }}` templates in a parsed suite.
+*
+* The context exposes `target` (its `host`, `hostname`, `port`, `origin`,
+* `href`, and `protocol`) plus the default helpers.  The target comes from the
+* `--target` override or the suite's own `target`, neither of which is
+* templated.
+* @param raw The parsed suite value.
+* @param targetOverride A target URL from `--target`, if any.
+* @returns The suite with templates expanded.
+*/
+function renderSuiteTemplates(raw, targetOverride) {
+	const target = targetOverride ?? suiteTarget(raw);
+	const values = {};
+	if (target != null) try {
+		const url = new URL(target);
+		values.target = {
+			host: url.host,
+			hostname: url.hostname,
+			port: url.port,
+			origin: url.origin,
+			href: url.href,
+			protocol: url.protocol.replace(/:$/, "")
+		};
+	} catch {}
+	return renderTemplates(raw, {
+		values,
+		helpers: defaultHelpers()
+	});
+}
+function suiteTarget(raw) {
+	if (raw != null && typeof raw === "object" && "target" in raw) {
+		const target = raw.target;
+		return typeof target === "string" ? target : void 0;
+	}
+}
+//#endregion
+export { loadSuiteFile, renderSuiteTemplates };