@fedify/fedify 2.3.0-dev.1114 → 2.3.0-dev.1131

package/dist/{http-CKCgOPkX.cjs → http-CJfvRL7D.cjs}

@@ -11,7 +11,7 @@ let _opentelemetry_semantic_conventions = require("@opentelemetry/semantic-conve
 let byte_encodings_base64 = require("byte-encodings/base64");
 //#region deno.json
 var name = "@fedify/fedify";
-var version = "2.3.0-dev.1114+15a3316d";
+var version = "2.3.0-dev.1131+553b59b8";
 //#endregion
 //#region src/sig/accept.ts
 /**
@@ -169,6 +169,14 @@ var FederationMetrics = class {
 	queueTaskFailed;
 	queueTaskDuration;
 	queueTaskInFlight;
+	fanoutRecipients;
+	inboxActivity;
+	outboxActivity;
+	keyLookup;
+	keyLookupDuration;
+	documentFetch;
+	documentFetchDuration;
+	documentCache;
 	constructor(meterProvider) {
 		const meter = meterProvider.getMeter(name, version);
 		this.deliverySent = meter.createCounter("activitypub.delivery.sent", {
@@ -263,6 +271,70 @@ var FederationMetrics = class {
 			description: "Queue tasks currently being processed in this Fedify process.",
 			unit: "{task}"
 		});
+		this.fanoutRecipients = meter.createHistogram("activitypub.fanout.recipients", {
+			description: "Number of recipient inboxes produced by an ActivityPub fanout task.",
+			unit: "{recipient}"
+		});
+		this.inboxActivity = meter.createCounter("activitypub.inbox.activity", {
+			description: "ActivityPub activities observed at the inbox lifecycle level: queued, processed, retried, rejected, or abandoned.",
+			unit: "{activity}"
+		});
+		this.outboxActivity = meter.createCounter("activitypub.outbox.activity", {
+			description: "ActivityPub activities observed at the outbox lifecycle level: queued, retried, or abandoned.  Per-recipient delivery counters live on `activitypub.delivery.*`.",
+			unit: "{activity}"
+		});
+		this.keyLookup = meter.createCounter("activitypub.key.lookup", {
+			description: "Public-key lookup attempts performed by Fedify, including both cache hits and remote fetches.",
+			unit: "{lookup}"
+		});
+		this.keyLookupDuration = meter.createHistogram("activitypub.key.lookup.duration", {
+			description: "Duration of public-key lookups performed by Fedify, including any remote fetch.",
+			unit: "ms",
+			advice: { explicitBucketBoundaries: [
+				5,
+				10,
+				25,
+				50,
+				75,
+				100,
+				250,
+				500,
+				750,
+				1e3,
+				2500,
+				5e3,
+				7500,
+				1e4
+			] }
+		});
+		this.documentFetch = meter.createCounter("activitypub.document.fetch", {
+			description: "Remote JSON-LD document loader invocations made by Fedify-wrapped loaders.",
+			unit: "{fetch}"
+		});
+		this.documentFetchDuration = meter.createHistogram("activitypub.document.fetch.duration", {
+			description: "Duration of remote JSON-LD document loader invocations made by Fedify-wrapped loaders.",
+			unit: "ms",
+			advice: { explicitBucketBoundaries: [
+				5,
+				10,
+				25,
+				50,
+				75,
+				100,
+				250,
+				500,
+				750,
+				1e3,
+				2500,
+				5e3,
+				7500,
+				1e4
+			] }
+		});
+		this.documentCache = meter.createCounter("activitypub.document.cache", {
+			description: "KV-backed document loader cache lookups, with `hit` or `miss` classification.",
+			unit: "{lookup}"
+		});
 	}
 	recordDelivery(inbox, durationMs, success, activityType) {
 		const deliveryAttributes = {
@@ -335,7 +407,53 @@ var FederationMetrics = class {
 		else if (result === "failed") this.queueTaskFailed.add(1, attributes);
 		this.queueTaskDuration.record(durationMs, attributes);
 	}
+	recordFanoutRecipients(recipientCount, activityType) {
+		const attributes = {};
+		if (activityType != null) attributes["activitypub.activity.type"] = activityType;
+		this.fanoutRecipients.record(recipientCount, attributes);
+	}
+	recordInboxActivity(result, activityType) {
+		this.inboxActivity.add(1, buildActivityLifecycleAttributes(result, activityType));
+	}
+	recordOutboxActivity(result, activityType) {
+		this.outboxActivity.add(1, buildActivityLifecycleAttributes(result, activityType));
+	}
+	recordKeyLookup(attrs) {
+		const attributes = {
+			"activitypub.lookup.kind": "public_key",
+			"activitypub.lookup.result": attrs.result,
+			"activitypub.cache.enabled": attrs.cacheEnabled
+		};
+		if (attrs.remoteUrl != null) attributes["activitypub.remote.host"] = getRemoteHost(attrs.remoteUrl);
+		if (attrs.statusCode != null) attributes["http.response.status_code"] = attrs.statusCode;
+		this.keyLookup.add(1, attributes);
+		this.keyLookupDuration.record(attrs.durationMs, attributes);
+	}
+	recordDocumentFetch(attrs) {
+		const attributes = {
+			"activitypub.lookup.kind": attrs.kind,
+			"activitypub.lookup.result": attrs.result
+		};
+		if (attrs.remoteUrl != null) attributes["activitypub.remote.host"] = getRemoteHost(attrs.remoteUrl);
+		if (attrs.cacheEnabled != null) attributes["activitypub.cache.enabled"] = attrs.cacheEnabled;
+		if (attrs.statusCode != null) attributes["http.response.status_code"] = attrs.statusCode;
+		this.documentFetch.add(1, attributes);
+		this.documentFetchDuration.record(attrs.durationMs, attributes);
+	}
+	recordDocumentCache(attrs) {
+		const attributes = {
+			"activitypub.lookup.kind": attrs.kind,
+			"activitypub.lookup.result": attrs.result
+		};
+		if (attrs.remoteUrl != null) attributes["activitypub.remote.host"] = getRemoteHost(attrs.remoteUrl);
+		this.documentCache.add(1, attributes);
+	}
 };
+function buildActivityLifecycleAttributes(result, activityType) {
+	const attributes = { "activitypub.processing.result": result };
+	if (activityType != null) attributes["activitypub.activity.type"] = activityType;
+	return attributes;
+}
 function buildQueueTaskAttributes(common) {
 	const attributes = { "fedify.queue.role": common.role };
 	const backend = getQueueBackend(common.queue);
@@ -365,20 +483,176 @@ function getQueueBackend(queue) {
 	return name;
 }
 /**
-* Records `fedify.queue.task.enqueued` for an outgoing outbox enqueue.
+* Records `fedify.queue.task.enqueued` for an outgoing outbox enqueue and,
+* for the initial attempt, also records
+* `activitypub.outbox.activity{queued}`.
 *
 * Both `Context.sendActivity()` and `OutboxContext.forwardActivity()` enqueue
 * outbox messages with the same metric attributes (role, queue, activity
 * type, attempt), so they share this helper rather than each defining a local
-* closure.
+* closure.  Retry enqueues (attempt > 0) intentionally do not record a
+* second `activitypub.outbox.activity{queued}`; retries are reported as
+* `result=retried` from the retry-scheduling site, which has the failure
+* context.
 * @since 2.3.0
 */
 function recordOutboxEnqueue(meterProvider, outboxQueue, message) {
-	getFederationMetrics(meterProvider).recordQueueTaskEnqueued({
+	const metrics = getFederationMetrics(meterProvider);
+	metrics.recordQueueTaskEnqueued({
 		role: "outbox",
 		queue: outboxQueue,
 		activityType: message.activityType
 	}, message.attempt);
+	if (message.attempt === 0) metrics.recordOutboxActivity("queued", message.activityType);
+}
+/**
+* Records `activitypub.fanout.recipients` with the number of recipient
+* inboxes a single fanout produced.  The histogram is unitless count
+* (one measurement per fanout enqueue).  Recipient URLs are deliberately
+* not recorded; only the activity type, when known.
+* @since 2.3.0
+*/
+function recordFanoutRecipients(meterProvider, recipientCount, activityType) {
+	getFederationMetrics(meterProvider).recordFanoutRecipients(recipientCount, activityType);
+}
+/**
+* Records one `activitypub.inbox.activity` measurement.  The
+* `activitypub.processing.result` attribute is always present;
+* `activitypub.activity.type` is recorded only when Fedify already knows
+* the activity type.
+* @since 2.3.0
+*/
+function recordInboxActivity(meterProvider, result, activityType) {
+	getFederationMetrics(meterProvider).recordInboxActivity(result, activityType);
+}
+/**
+* Records one `activitypub.outbox.activity` measurement.  The
+* `activitypub.processing.result` attribute is always present;
+* `activitypub.activity.type` is recorded only when Fedify already knows
+* the activity type (it is always known for outbox lifecycle events).
+* @since 2.3.0
+*/
+function recordOutboxActivity(meterProvider, result, activityType) {
+	getFederationMetrics(meterProvider).recordOutboxActivity(result, activityType);
+}
+/**
+* Records one measurement on `activitypub.key.lookup` (counter) and
+* `activitypub.key.lookup.duration` (histogram) for a public-key lookup.
+*
+* `activitypub.lookup.kind` is always recorded as `public_key`; the result
+* classification, remote host, HTTP status code (when an HTTP response was
+* received), and `activitypub.cache.enabled` are recorded as attributes on
+* both measurements.  Full key URLs and key IDs are deliberately omitted to
+* keep cardinality bounded.
+* @since 2.3.0
+*/
+function recordKeyLookup(meterProvider, attrs) {
+	getFederationMetrics(meterProvider).recordKeyLookup(attrs);
+}
+/**
+* Records one measurement each on `activitypub.document.fetch` (counter)
+* and `activitypub.document.fetch.duration` (histogram) for one remote
+* JSON-LD document loader invocation, with bounded
+* `activitypub.lookup.kind` and `activitypub.lookup.result` attributes
+* plus the optional remote-host, cache-enabled, and HTTP status-code
+* attributes.  Counter and histogram are always recorded together so
+* aggregate rate and latency views stay in sync.
+* @since 2.3.0
+*/
+function recordDocumentFetch(meterProvider, attrs) {
+	getFederationMetrics(meterProvider).recordDocumentFetch(attrs);
+}
+/**
+* Records one `activitypub.document.cache` measurement, classifying the
+* lookup as `hit` (the cache returned an entry) or `miss` (the cache was
+* consulted and returned nothing, prompting a delegate fetch).
+* @since 2.3.0
+*/
+function recordDocumentCache(meterProvider, attrs) {
+	getFederationMetrics(meterProvider).recordDocumentCache(attrs);
+}
+/**
+* Classifies a thrown value from a key or document fetch into the bounded
+* {@link LookupResult} taxonomy and, when an HTTP response was received,
+* surfaces its status code.
+*
+*  -  `FetchError` with a `Response` whose status is `404` or `410`:
+*     `result=not_found` and the response status code.
+*  -  `FetchError` with any other `Response`: `result=error` and the
+*     response status code.
+*  -  `FetchError` without a `Response`: `result=network_error`.
+*  -  An `AbortError` (typically from a cancelled fetch): `result=network_error`.
+*  -  A bare `TypeError` (the shape native `fetch()` raises on DNS, connect,
+*     and TLS failures before any response is observed):
+*     `result=network_error`.
+*  -  Any other value: `result=error`.
+* @since 2.3.0
+*/
+function classifyFetchError(error) {
+	if (error instanceof _fedify_vocab_runtime.FetchError) {
+		if (error.response != null) {
+			const status = error.response.status;
+			return {
+				result: status === 404 || status === 410 ? "not_found" : "error",
+				statusCode: status
+			};
+		}
+		return { result: "network_error" };
+	}
+	if (isAbortError$1(error)) return { result: "network_error" };
+	if (error instanceof TypeError) return { result: "network_error" };
+	return { result: "error" };
+}
+/**
+* Wraps a {@link DocumentLoader} so each invocation records one
+* measurement on `activitypub.document.fetch` (counter) and one on
+* `activitypub.document.fetch.duration` (histogram), classifying the
+* outcome via {@link classifyFetchError} when the wrapped loader throws
+* and as `fetched` on success.  The wrapper rethrows whatever the
+* wrapped loader throws so caller behavior is unchanged.
+*
+* The wrapper records the hostname of the requested URL on
+* `activitypub.remote.host` when the URL parses; full URLs, paths, and
+* query strings are deliberately excluded to keep cardinality bounded.
+* HTTP status codes are recorded only when the failure carries a
+* `Response` (currently, when the wrapped loader throws a
+* {@link FetchError} with a non-`null` `response`).
+* @since 2.3.0
+*/
+function instrumentDocumentLoader(loader, options) {
+	const meterProvider = options.meterProvider;
+	if (meterProvider == null) return loader;
+	return async (url, opts) => {
+		const start = performance.now();
+		let remoteUrl;
+		try {
+			remoteUrl = new URL(url);
+		} catch {
+			remoteUrl = void 0;
+		}
+		try {
+			const result = await loader(url, opts);
+			recordDocumentFetch(meterProvider, {
+				durationMs: getDurationMs(start),
+				kind: options.kind,
+				result: "fetched",
+				remoteUrl,
+				cacheEnabled: options.cacheEnabled
+			});
+			return result;
+		} catch (error) {
+			const classified = classifyFetchError(error);
+			recordDocumentFetch(meterProvider, {
+				durationMs: getDurationMs(start),
+				kind: options.kind,
+				result: classified.result,
+				remoteUrl,
+				cacheEnabled: options.cacheEnabled,
+				statusCode: classified.statusCode
+			});
+			throw error;
+		}
+	};
 }
 /**
 * Times an awaited public key fetch and records exactly one
@@ -760,24 +1034,48 @@ async function resolveFetchedKey(document, cacheKey, keyId, cls, { documentLoade
 	};
 }
 async function fetchKeyWithResult(cacheKey, cls, options, onCachedUnavailable, onFetchError) {
-	const logger = (0, _logtape_logtape.getLogger)([
-		"fedify",
-		"sig",
-		"key"
-	]);
-	const keyId = cacheKey.href;
-	const keyCache = options.keyCache;
-	const cached = await getCachedFetchKey(cacheKey, keyId, cls, keyCache, logger);
-	if (cached?.key === null && cached.cached) return await onCachedUnavailable(cacheKey, keyId, keyCache, logger);
-	if (cached != null) return cached;
-	logger.debug("Fetching key {keyId} to verify signature...", { keyId });
-	let document;
+	const start = performance.now();
+	let outcome = { result: "error" };
 	try {
-		document = (await (options.documentLoader ?? (0, _fedify_vocab_runtime.getDocumentLoader)())(keyId)).document;
-	} catch (error) {
-		return await onFetchError(error, cacheKey, keyId, keyCache, logger);
+		const logger = (0, _logtape_logtape.getLogger)([
+			"fedify",
+			"sig",
+			"key"
+		]);
+		const keyId = cacheKey.href;
+		const keyCache = options.keyCache;
+		const cached = await getCachedFetchKey(cacheKey, keyId, cls, keyCache, logger);
+		if (cached?.key === null && cached.cached) {
+			const cachedUnavailable = await onCachedUnavailable(cacheKey, keyId, keyCache, logger);
+			outcome = { result: "hit" };
+			return cachedUnavailable;
+		}
+		if (cached != null) {
+			outcome = { result: "hit" };
+			return cached;
+		}
+		logger.debug("Fetching key {keyId} to verify signature...", { keyId });
+		let document;
+		try {
+			document = (await (options.documentLoader ?? (0, _fedify_vocab_runtime.getDocumentLoader)())(keyId)).document;
+		} catch (error) {
+			const classified = classifyFetchError(error);
+			const errored = await onFetchError(error, cacheKey, keyId, keyCache, logger);
+			outcome = classified;
+			return errored;
+		}
+		const resolved = await resolveFetchedKey(document, cacheKey, keyId, cls, options, logger);
+		outcome = { result: resolved.key != null ? "fetched" : "invalid" };
+		return resolved;
+	} finally {
+		recordKeyLookup(options.meterProvider, {
+			durationMs: getDurationMs(start),
+			result: outcome.result,
+			remoteUrl: cacheKey,
+			cacheEnabled: options.keyCache != null,
+			statusCode: outcome.statusCode
+		});
 	}
-	return await resolveFetchedKey(document, cacheKey, keyId, cls, options, logger);
 }
 async function fetchKeyInternal(keyId, cls, options = {}) {
 	return await fetchKeyWithResult(typeof keyId === "string" ? new URL(keyId) : keyId, cls, options, (_cacheKey, _keyId, _keyCache, _logger) => {
@@ -1359,7 +1657,8 @@ async function verifyRequestDraft(request, span, metricsContext, { documentLoade
 		documentLoader,
 		contextLoader,
 		keyCache,
-		tracerProvider
+		tracerProvider,
+		meterProvider
 	}));
 	if (fetchError != null) return keyFetchErrorResult(keyIdUrl, fetchError);
 	if (key == null) return invalidSignatureResult(keyIdUrl);
@@ -1574,7 +1873,8 @@ async function verifyRequestRfc9421(request, span, metricsContext, { documentLoa
 			documentLoader,
 			contextLoader,
 			keyCache,
-			tracerProvider
+			tracerProvider,
+			meterProvider
 		}));
 		if (fetchError != null) {
 			setFailure(keyFetchErrorResult(keyId, fetchError));
@@ -1943,6 +2243,12 @@ Object.defineProperty(exports, "importJwk", {
 		return importJwk;
 	}
 });
+Object.defineProperty(exports, "instrumentDocumentLoader", {
+	enumerable: true,
+	get: function() {
+		return instrumentDocumentLoader;
+	}
+});
 Object.defineProperty(exports, "isAbortError", {
 	enumerable: true,
 	get: function() {
@@ -1973,6 +2279,30 @@ Object.defineProperty(exports, "parseRfc9421SignatureInput", {
 		return parseRfc9421SignatureInput;
 	}
 });
+Object.defineProperty(exports, "recordDocumentCache", {
+	enumerable: true,
+	get: function() {
+		return recordDocumentCache;
+	}
+});
+Object.defineProperty(exports, "recordFanoutRecipients", {
+	enumerable: true,
+	get: function() {
+		return recordFanoutRecipients;
+	}
+});
+Object.defineProperty(exports, "recordInboxActivity", {
+	enumerable: true,
+	get: function() {
+		return recordInboxActivity;
+	}
+});
+Object.defineProperty(exports, "recordOutboxActivity", {
+	enumerable: true,
+	get: function() {
+		return recordOutboxActivity;
+	}
+});
 Object.defineProperty(exports, "recordOutboxEnqueue", {
 	enumerable: true,
 	get: function() {

package/dist/{http-BmOZYc-8.mjs → http-IywnQdiX.mjs}

@@ -1,10 +1,10 @@
 import { Temporal } from "@js-temporal/polyfill";
 import "urlpattern-polyfill";
 globalThis.addEventListener = () => {};
-import { n as version, t as name } from "./deno-CF3jMgip.mjs";
-import { a as measureSignatureKeyFetch, n as getFederationMetrics, t as getDurationMs } from "./metrics-ek3ilf6c.mjs";
+import { n as version, t as name } from "./deno--CS-SBS9.mjs";
+import { n as getDurationMs, r as getFederationMetrics, s as measureSignatureKeyFetch } from "./metrics-BTOMkW8C.mjs";
 import { i as validateAcceptSignature, n as fulfillAcceptSignature, r as parseAcceptSignature } from "./accept-CgDcxvjV.mjs";
-import { o as validateCryptoKey, r as fetchKeyDetailed } from "./key-B4I8H5Lc.mjs";
+import { o as validateCryptoKey, r as fetchKeyDetailed } from "./key-Df3tMleh.mjs";
 import { getLogger } from "@logtape/logtape";
 import { CryptographicKey } from "@fedify/vocab";
 import { SpanStatusCode, trace } from "@opentelemetry/api";
@@ -569,7 +569,8 @@ async function verifyRequestDraft(request, span, metricsContext, { documentLoade
 		documentLoader,
 		contextLoader,
 		keyCache,
-		tracerProvider
+		tracerProvider,
+		meterProvider
 	}));
 	if (fetchError != null) return keyFetchErrorResult(keyIdUrl, fetchError);
 	if (key == null) return invalidSignatureResult(keyIdUrl);
@@ -784,7 +785,8 @@ async function verifyRequestRfc9421(request, span, metricsContext, { documentLoa
 			documentLoader,
 			contextLoader,
 			keyCache,
-			tracerProvider
+			tracerProvider,
+			meterProvider
 		}));
 		if (fetchError != null) {
 			setFailure(keyFetchErrorResult(keyId, fetchError));

package/dist/{http-D6LP89UO.d.ts → http-VyDTd4G3.d.cts}

@@ -1,7 +1,7 @@
 /// <reference lib="esnext.temporal" />
 import { CryptographicKey, Multikey } from "@fedify/vocab";
-import { MeterProvider, TracerProvider } from "@opentelemetry/api";
 import { DocumentLoader } from "@fedify/vocab-runtime";
+import { MeterProvider, TracerProvider } from "@opentelemetry/api";
 
 //#region src/sig/key.d.ts
 /**
@@ -52,6 +52,13 @@ interface FetchKeyOptions {
   * @since 1.3.0
   */
   tracerProvider?: TracerProvider;
+  /**
+  * The OpenTelemetry meter provider to use for recording
+  * `activitypub.key.lookup` and `activitypub.key.lookup.duration`.  If
+  * omitted, the global meter provider is used.
+  * @since 2.3.0
+  */
+  meterProvider?: MeterProvider;
 }
 /**
 * The result of {@link fetchKey}.