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

package/dist/bench/scenario/normalize.js

@@ -0,0 +1,126 @@
+import "@js-temporal/polyfill";
+import { asList } from "./coerce.js";
+import { parseDuration, parseRate } from "./units.js";
+//#region src/bench/scenario/normalize.ts
+/**
+* Normalizes a validated scenario suite into a fully resolved form the engine
+* can execute: defaults applied, top-level scalar-or-list fields (`recipient`,
+* `collection`, `fault`) coerced to arrays, durations and rates parsed to
+* numbers, and the load model determined.  Nested specs (`activity`, `source`)
+* are passed through and coerced where they are consumed.
+*
+* It also enforces the cross-field rules that the JSON Schema cannot express,
+* notably that the buffered signing modes require the target's signature time
+* window to be off.
+* @since 2.3.0
+* @module
+*/
+const DEFAULT_DURATION_MS = 6e4;
+const DEFAULT_WARMUP_MS = 0;
+const DEFAULT_RATE_PER_SEC = 50;
+const DEFAULT_SIGNING = "pipeline";
+const DEFAULT_RUNS = 1;
+/** An error raised when a suite cannot be normalized. */
+var SuiteNormalizeError = class extends Error {};
+/**
+* Normalizes a validated suite into resolved form.
+* @param suite The validated suite.
+* @param options Normalization options, such as a target override.
+* @returns The resolved suite.
+* @throws {SuiteNormalizeError} If the target is missing or a cross-field rule
+*         is violated.
+*/
+function normalizeSuite(suite, options = {}) {
+	const targetString = options.target ?? suite.target;
+	if (targetString == null || targetString.trim() === "") throw new SuiteNormalizeError("No target URL: set `target` in the suite or pass --target.");
+	let target;
+	try {
+		target = new URL(targetString);
+	} catch {
+		throw new SuiteNormalizeError(`Invalid target URL: ${targetString}.`);
+	}
+	if (target.protocol !== "http:" && target.protocol !== "https:" || target.hostname === "" || target.username !== "" || target.password !== "") throw new SuiteNormalizeError(`Invalid target URL ${JSON.stringify(targetString)}: a benchmark target must be an http: or https: URL with a host and no embedded credentials (for example http://localhost:3000).`);
+	return {
+		target,
+		actors: suite.actors ?? [],
+		scenarios: suite.scenarios.map((scenario) => resolveScenario(scenario, suite))
+	};
+}
+function resolveScenario(scenario, suite) {
+	const defaults = suite.defaults ?? {};
+	const load = resolveLoad(defaults.load, scenario.load);
+	const signing = scenario.signing ?? defaults.signing ?? DEFAULT_SIGNING;
+	const signatureTimeWindow = scenario.signatureTimeWindow ?? defaults.signatureTimeWindow ?? false;
+	if (signing !== "jit" && signatureTimeWindow) throw new SuiteNormalizeError(`Scenario "${scenario.name}": ${signing} signing pre-signs requests, which requires the target's signature time window to be off; use signing: jit for a time-windowed target.`);
+	if (signing === "presign" && load.kind === "closed") throw new SuiteNormalizeError(`Scenario "${scenario.name}": presign signing needs a fixed request count, which a closed-loop (concurrency) load does not have; use an open-loop rate, or signing: pipeline or jit.`);
+	const durationMs = resolveDuration(scenario.duration ?? defaults.duration, DEFAULT_DURATION_MS);
+	const warmupMs = resolveDuration(scenario.warmup ?? defaults.warmup, DEFAULT_WARMUP_MS);
+	if (warmupMs >= durationMs) throw new SuiteNormalizeError(`Scenario "${scenario.name}": warmup (${warmupMs}ms) must be shorter than duration (${durationMs}ms); otherwise no requests are measured.`);
+	const runs = scenario.runs ?? defaults.runs ?? DEFAULT_RUNS;
+	if (runs > 1) throw new SuiteNormalizeError(`Scenario "${scenario.name}": multiple runs (runs > 1) are not yet implemented in fedify bench; set runs to 1.`);
+	return {
+		name: scenario.name,
+		type: scenario.type,
+		load,
+		durationMs,
+		warmupMs,
+		signing,
+		signatureTimeWindow,
+		runs,
+		recipients: asList(scenario.recipient),
+		inbox: scenario.inbox,
+		activity: scenario.activity,
+		authenticated: scenario.authenticated ?? false,
+		collections: asList(scenario.collection),
+		source: scenario.source,
+		sender: scenario.sender,
+		followers: scenario.followers,
+		queueDrainTimeoutMs: scenario.queueDrainTimeout == null ? void 0 : parseDuration(scenario.queueDrainTimeout),
+		faults: asList(scenario.fault),
+		expect: scenario.expect ?? {},
+		raw: scenario
+	};
+}
+/**
+* Resolves the load model from suite defaults and a scenario override.  The
+* scenario's choice of `rate`/`concurrency` wins outright (it selects the
+* model), while compatible fields such as `arrival` and `maxInFlight` are
+* inherited from the defaults when the scenario does not set them.
+*/
+function resolveLoad(defaults, scenario) {
+	const arrival = scenario?.arrival ?? defaults?.arrival ?? "constant";
+	const maxInFlight = scenario?.maxInFlight ?? defaults?.maxInFlight;
+	if (scenario?.concurrency != null) return {
+		kind: "closed",
+		concurrency: scenario.concurrency,
+		maxInFlight
+	};
+	if (scenario?.rate != null) return {
+		kind: "open",
+		ratePerSec: parseRate(scenario.rate),
+		arrival,
+		maxInFlight
+	};
+	if (defaults?.concurrency != null) return {
+		kind: "closed",
+		concurrency: defaults.concurrency,
+		maxInFlight
+	};
+	if (defaults?.rate != null) return {
+		kind: "open",
+		ratePerSec: parseRate(defaults.rate),
+		arrival,
+		maxInFlight
+	};
+	return {
+		kind: "open",
+		ratePerSec: DEFAULT_RATE_PER_SEC,
+		arrival,
+		maxInFlight
+	};
+}
+function resolveDuration(value, fallback) {
+	return value == null ? fallback : parseDuration(value);
+}
+//#endregion
+export { normalizeSuite };

package/dist/bench/scenario/schema.js

@@ -0,0 +1,358 @@
+import "@js-temporal/polyfill";
+//#region src/bench/scenario/schema.ts
+/**
+* The embedded JSON Schema (draft 2020-12) for benchmark scenario suite files.
+*
+* This object is the runtime copy used by the validator; it is published,
+* byte-for-byte, as *schema/bench/scenario-v1.json* and a drift guard keeps the
+* two in sync.  The matching TypeScript types live in {@link ./types.ts}.
+*
+* The schema expresses every scenario type discussed for `fedify bench`
+* (`inbox`, `webfinger`, `actor`, `object`, `fanout`, `collection`, `failure`,
+* `mixed`), even though only `inbox` and `webfinger` have runners in this
+* version.  Three cross-field rules are enforced here rather than in code:
+*
+*  -  exactly one HTTP request signature scheme per actor group
+*     (`contains` + `minContains`/`maxContains`);
+*  -  `rate` XOR `concurrency` in a load block (`oneOf`);
+*  -  the allowed `expect` metrics per scenario type (`if`/`then` +
+*     `propertyNames`).
+* @since 2.3.0
+* @module
+*/
+/** The hosted URL that serves the scenario schema. */
+const SCENARIO_SCHEMA_ID = "https://json-schema.fedify.dev/bench/scenario-v1.json";
+const READ_METRICS = [
+	"successRate",
+	"throughputPerSec",
+	"errors.total",
+	"errors.4xx",
+	"errors.5xx",
+	"latency.p50",
+	"latency.p95",
+	"latency.p99",
+	"latency.mean",
+	"latency.max"
+];
+const INBOX_METRICS = [
+	...READ_METRICS,
+	"signatureVerification.p50",
+	"signatureVerification.p95",
+	"signatureVerification.p99"
+];
+const FANOUT_METRICS = [
+	"successRate",
+	"deliveryThroughput",
+	"errors.total",
+	"errors.4xx",
+	"errors.5xx",
+	"queueDrain.p50",
+	"queueDrain.p95",
+	"queueDrain.p99"
+];
+const MIXED_METRICS = [...new Set([...INBOX_METRICS, ...FANOUT_METRICS])];
+/** The benchmark scenario suite JSON Schema (draft 2020-12). */
+const scenarioSchemaV1 = {
+	$schema: "https://json-schema.org/draft/2020-12/schema",
+	$id: SCENARIO_SCHEMA_ID,
+	title: "Fedify benchmark scenario suite",
+	type: "object",
+	required: ["version", "scenarios"],
+	additionalProperties: false,
+	properties: {
+		$schema: {
+			type: "string",
+			description: "An optional editor hint pointing at this schema."
+		},
+		version: { const: 1 },
+		target: {
+			type: "string",
+			format: "uri",
+			description: "The target base URL; may be overridden by --target."
+		},
+		defaults: { $ref: "#/$defs/defaults" },
+		actors: {
+			type: "array",
+			items: { $ref: "#/$defs/actorGroup" }
+		},
+		scenarios: {
+			type: "array",
+			minItems: 1,
+			items: { $ref: "#/$defs/scenario" }
+		}
+	},
+	$defs: {
+		duration: {
+			type: "string",
+			pattern: "^\\d+(\\.\\d+)?(ms|s|m|h)$",
+			description: "A duration such as 500ms, 30s, 2m, or 1h."
+		},
+		rate: {
+			description: "An open-loop arrival rate such as 200/s, or a number.",
+			oneOf: [{
+				type: "number",
+				exclusiveMinimum: 0
+			}, {
+				type: "string",
+				pattern: "^\\d+(\\.\\d+)?\\s*/\\s*(s|m|h)$"
+			}]
+		},
+		size: {
+			description: "A byte size such as 2KB or a plain number of bytes.",
+			oneOf: [{
+				type: "number",
+				minimum: 0
+			}, {
+				type: "string",
+				pattern: "^\\s*\\d+(\\.\\d+)?\\s*([Bb]|[Kk][Bb]|[Kk][Ii][Bb]|[Mm][Bb]|[Mm][Ii][Bb]|[Gg][Bb]|[Gg][Ii][Bb])?\\s*$"
+			}]
+		},
+		signatureStandard: { enum: [
+			"draft-cavage-http-signatures-12",
+			"rfc9421",
+			"ld-signatures",
+			"fep8b32"
+		] },
+		signingMode: { enum: [
+			"jit",
+			"pipeline",
+			"presign"
+		] },
+		arrival: { enum: ["constant", "poisson"] },
+		scalarOrListString: { oneOf: [{ type: "string" }, {
+			type: "array",
+			items: { type: "string" },
+			minItems: 1
+		}] },
+		load: {
+			type: "object",
+			additionalProperties: false,
+			properties: {
+				rate: { $ref: "#/$defs/rate" },
+				concurrency: {
+					type: "integer",
+					minimum: 1
+				},
+				arrival: { $ref: "#/$defs/arrival" },
+				maxInFlight: {
+					type: "integer",
+					minimum: 1
+				}
+			},
+			not: { required: ["rate", "concurrency"] }
+		},
+		defaults: {
+			type: "object",
+			additionalProperties: false,
+			properties: {
+				duration: { $ref: "#/$defs/duration" },
+				warmup: { $ref: "#/$defs/duration" },
+				load: { $ref: "#/$defs/load" },
+				signing: { $ref: "#/$defs/signingMode" },
+				signatureTimeWindow: { type: "boolean" },
+				runs: {
+					type: "integer",
+					minimum: 1
+				}
+			}
+		},
+		actorGroup: {
+			type: "object",
+			additionalProperties: false,
+			required: ["signatureStandards"],
+			properties: {
+				name: { type: "string" },
+				count: {
+					type: "integer",
+					minimum: 1
+				},
+				signatureStandards: {
+					type: "array",
+					uniqueItems: true,
+					minItems: 1,
+					items: { $ref: "#/$defs/signatureStandard" },
+					contains: { enum: ["draft-cavage-http-signatures-12", "rfc9421"] },
+					minContains: 1,
+					maxContains: 1,
+					description: "Exactly one HTTP request signature scheme, plus optional document signature schemes."
+				}
+			}
+		},
+		generateDirective: {
+			type: "object",
+			additionalProperties: false,
+			required: ["generate"],
+			properties: {
+				generate: { enum: ["lorem"] },
+				size: { $ref: "#/$defs/size" }
+			}
+		},
+		content: { oneOf: [{ type: "string" }, { $ref: "#/$defs/generateDirective" }] },
+		objectSpec: {
+			type: "object",
+			properties: {
+				type: { $ref: "#/$defs/scalarOrListString" },
+				content: { $ref: "#/$defs/content" }
+			}
+		},
+		activitySpec: {
+			type: "object",
+			additionalProperties: false,
+			properties: {
+				type: { $ref: "#/$defs/scalarOrListString" },
+				embedObject: { type: "boolean" },
+				object: { $ref: "#/$defs/objectSpec" }
+			}
+		},
+		objectSource: { oneOf: [{ $ref: "#/$defs/scalarOrListString" }, {
+			type: "object",
+			additionalProperties: false,
+			required: ["seed"],
+			properties: {
+				seed: { $ref: "#/$defs/scalarOrListString" },
+				collection: { $ref: "#/$defs/scalarOrListString" },
+				limit: {
+					type: "integer",
+					minimum: 1
+				},
+				type: { $ref: "#/$defs/scalarOrListString" }
+			}
+		}] },
+		expectSeverity: { enum: ["warn", "fail"] },
+		expectValue: { oneOf: [{
+			type: "string",
+			description: "An assertion such as '>= 99%' or '< 100ms'."
+		}, {
+			type: "object",
+			additionalProperties: false,
+			required: ["assert"],
+			properties: {
+				assert: { type: "string" },
+				severity: { $ref: "#/$defs/expectSeverity" }
+			}
+		}] },
+		mixEntry: {
+			type: "object",
+			additionalProperties: false,
+			required: ["scenario", "weight"],
+			properties: {
+				scenario: { type: "string" },
+				weight: {
+					type: "number",
+					exclusiveMinimum: 0
+				}
+			}
+		},
+		scenario: {
+			type: "object",
+			additionalProperties: false,
+			required: ["name", "type"],
+			properties: {
+				name: { type: "string" },
+				type: { enum: [
+					"inbox",
+					"webfinger",
+					"actor",
+					"object",
+					"fanout",
+					"collection",
+					"failure",
+					"mixed"
+				] },
+				load: { $ref: "#/$defs/load" },
+				duration: { $ref: "#/$defs/duration" },
+				warmup: { $ref: "#/$defs/duration" },
+				signing: { $ref: "#/$defs/signingMode" },
+				signatureTimeWindow: { type: "boolean" },
+				runs: {
+					type: "integer",
+					minimum: 1
+				},
+				expect: {
+					type: "object",
+					additionalProperties: { $ref: "#/$defs/expectValue" }
+				},
+				recipient: { $ref: "#/$defs/scalarOrListString" },
+				inbox: { type: "string" },
+				activity: { $ref: "#/$defs/activitySpec" },
+				authenticated: { type: "boolean" },
+				collection: { $ref: "#/$defs/scalarOrListString" },
+				source: { $ref: "#/$defs/objectSource" },
+				sender: { type: "string" },
+				followers: {
+					type: "integer",
+					minimum: 1
+				},
+				trigger: { type: "object" },
+				sinkBehavior: { type: "object" },
+				queueDrainTimeout: { $ref: "#/$defs/duration" },
+				fault: { $ref: "#/$defs/scalarOrListString" },
+				mix: {
+					type: "array",
+					minItems: 1,
+					items: { $ref: "#/$defs/mixEntry" }
+				}
+			},
+			allOf: [
+				{
+					if: { properties: { type: { const: "inbox" } } },
+					then: {
+						required: ["recipient"],
+						properties: { expect: { propertyNames: { enum: INBOX_METRICS } } }
+					}
+				},
+				{
+					if: { properties: { type: { const: "webfinger" } } },
+					then: {
+						required: ["recipient"],
+						properties: { expect: { propertyNames: { enum: READ_METRICS } } }
+					}
+				},
+				{
+					if: { properties: { type: { const: "actor" } } },
+					then: {
+						required: ["recipient"],
+						properties: { expect: { propertyNames: { enum: INBOX_METRICS } } }
+					}
+				},
+				{
+					if: { properties: { type: { const: "object" } } },
+					then: {
+						required: ["source"],
+						properties: { expect: { propertyNames: { enum: READ_METRICS } } }
+					}
+				},
+				{
+					if: { properties: { type: { const: "collection" } } },
+					then: {
+						required: ["recipient"],
+						properties: { expect: { propertyNames: { enum: READ_METRICS } } }
+					}
+				},
+				{
+					if: { properties: { type: { const: "fanout" } } },
+					then: {
+						required: ["sender"],
+						properties: { expect: { propertyNames: { enum: FANOUT_METRICS } } }
+					}
+				},
+				{
+					if: { properties: { type: { const: "failure" } } },
+					then: {
+						required: ["fault"],
+						properties: { expect: { propertyNames: { enum: READ_METRICS } } }
+					}
+				},
+				{
+					if: { properties: { type: { const: "mixed" } } },
+					then: {
+						required: ["mix"],
+						properties: { expect: { propertyNames: { enum: MIXED_METRICS } } }
+					}
+				}
+			]
+		}
+	}
+};
+//#endregion
+export { scenarioSchemaV1 };

package/dist/bench/scenario/units.js

@@ -0,0 +1,56 @@
+import "@js-temporal/polyfill";
+//#region src/bench/scenario/units.ts
+/**
+* Parsers for the human-friendly duration and rate units used in scenario
+* files.
+* @since 2.3.0
+* @module
+*/
+const DURATION_RE = /^(\d+(?:\.\d+)?)(ms|s|m|h)$/;
+const DURATION_UNITS = {
+	ms: 1,
+	s: 1e3,
+	m: 6e4,
+	h: 36e5
+};
+const RATE_RE = /^(\d+(?:\.\d+)?)\s*\/\s*(s|m|h)$/;
+const RATE_DIVISORS = {
+	s: 1,
+	m: 60,
+	h: 3600
+};
+/**
+* Parses a duration such as `"500ms"`, `"30s"`, `"2m"`, or `"1h"` into
+* milliseconds.
+* @param value The duration string.
+* @returns The duration in milliseconds.
+* @throws {RangeError} If the value cannot be parsed.
+*/
+function parseDuration(value) {
+	const match = value.match(DURATION_RE);
+	if (match == null) throw new RangeError(`Invalid duration: ${JSON.stringify(value)}.`);
+	const ms = Number.parseFloat(match[1]) * DURATION_UNITS[match[2]];
+	if (!Number.isFinite(ms)) throw new RangeError(`Duration out of range: ${JSON.stringify(value)}.`);
+	return ms;
+}
+/**
+* Parses an open-loop arrival rate into requests per second.  A bare number is
+* interpreted as requests per second; a string such as `"200/s"`, `"60/m"`, or
+* `"3600/h"` carries an explicit time unit.
+* @param value The rate string or number.
+* @returns The rate in requests per second.
+* @throws {RangeError} If the value cannot be parsed or is not positive.
+*/
+function parseRate(value) {
+	if (typeof value === "number") {
+		if (!Number.isFinite(value) || value <= 0) throw new RangeError(`Invalid rate: ${value}.`);
+		return value;
+	}
+	const match = value.match(RATE_RE);
+	if (match == null) throw new RangeError(`Invalid rate: ${JSON.stringify(value)}.`);
+	const rate = Number.parseFloat(match[1]) / RATE_DIVISORS[match[2]];
+	if (!Number.isFinite(rate) || rate <= 0) throw new RangeError(`Invalid rate: ${JSON.stringify(value)}.`);
+	return rate;
+}
+//#endregion
+export { parseDuration, parseRate };

package/dist/bench/scenario/validate.js

@@ -0,0 +1,29 @@
+import "@js-temporal/polyfill";
+import { scenarioSchemaV1 } from "./schema.js";
+import { SuiteValidationError } from "./errors.js";
+import { Validator } from "@cfworker/json-schema";
+//#region src/bench/scenario/validate.ts
+/**
+* Runtime validation of scenario suites against the embedded JSON Schema.
+* @since 2.3.0
+* @module
+*/
+let validator;
+function getValidator() {
+	validator ??= new Validator(scenarioSchemaV1, "2020-12");
+	return validator;
+}
+/**
+* Validates a parsed scenario suite against the schema and narrows its type.
+* @param raw The parsed (but untyped) suite value.
+* @param source An optional source label (e.g. a file path) for error messages.
+* @returns The validated suite.
+* @throws {SuiteValidationError} If the value does not satisfy the schema.
+*/
+function validateSuite(raw, source) {
+	const result = getValidator().validate(raw);
+	if (!result.valid) throw new SuiteValidationError(result.errors, source);
+	return raw;
+}
+//#endregion
+export { validateSuite };