@fedify/fedify 2.0.0-dev.1961 → 2.0.0-dev.211

package/dist/otel/mod.cjs

@@ -0,0 +1,256 @@
+
+          const { Temporal } = require("@js-temporal/polyfill");
+          const { URLPattern } = require("urlpattern-polyfill");
+        
+const require_chunk = require('../chunk-DqRYRqnO.cjs');
+const __logtape_logtape = require_chunk.__toESM(require("@logtape/logtape"));
+const __opentelemetry_core = require_chunk.__toESM(require("@opentelemetry/core"));
+
+//#region src/otel/exporter.ts
+/**
+* A SpanExporter that persists ActivityPub activity traces to a
+* {@link KvStore}.  This enables distributed tracing across multiple
+* nodes in a Fedify deployment.
+*
+* The exporter captures activity data from OpenTelemetry span events
+* (`activitypub.activity.received` and `activitypub.activity.sent`)
+* and stores them in the KvStore with trace context preserved.
+*
+* @example Basic usage with MemoryKvStore
+* ```typescript ignore
+* import { MemoryKvStore } from "@fedify/fedify";
+* import { FedifySpanExporter } from "@fedify/fedify/otel";
+* import {
+*   BasicTracerProvider,
+*   SimpleSpanProcessor,
+* } from "@opentelemetry/sdk-trace-base";
+*
+* const kv = new MemoryKvStore();
+* const exporter = new FedifySpanExporter(kv, {
+*   ttl: Temporal.Duration.from({ hours: 1 }),
+* });
+*
+* const provider = new BasicTracerProvider({
+*   spanProcessors: [new SimpleSpanProcessor(exporter)],
+* });
+* ```
+*
+* @example Querying stored traces
+* ```typescript ignore
+* import { MemoryKvStore } from "@fedify/fedify";
+* import { FedifySpanExporter } from "@fedify/fedify/otel";
+*
+* const kv = new MemoryKvStore();
+* const exporter = new FedifySpanExporter(kv);
+* const traceId = "abc123";
+*
+* // Get all activities for a specific trace
+* const activities = await exporter.getActivitiesByTraceId(traceId);
+*
+* // Get recent traces
+* const recentTraces = await exporter.getRecentTraces({ limit: 100 });
+* ```
+*
+* @since 1.10.0
+*/
+var FedifySpanExporter = class {
+	#kv;
+	#ttl;
+	#keyPrefix;
+	/**
+	* Creates a new FedifySpanExporter.
+	*
+	* @param kv The KvStore to persist trace data to.
+	* @param options Configuration options.
+	*/
+	constructor(kv, options) {
+		this.#kv = kv;
+		this.#ttl = options?.ttl;
+		this.#keyPrefix = options?.keyPrefix ?? ["fedify", "traces"];
+	}
+	/**
+	* Exports spans to the KvStore.
+	*
+	* @param spans The spans to export.
+	* @param resultCallback Callback to invoke with the export result.
+	*/
+	export(spans, resultCallback) {
+		this.#exportAsync(spans).then(() => resultCallback({ code: __opentelemetry_core.ExportResultCode.SUCCESS })).catch((error) => {
+			(0, __logtape_logtape.getLogger)([
+				"fedify",
+				"otel",
+				"exporter"
+			]).error("Failed to export spans to KvStore: {error}", { error });
+			resultCallback({ code: __opentelemetry_core.ExportResultCode.FAILED });
+		});
+	}
+	async #exportAsync(spans) {
+		const storeOperations = [];
+		for (const span of spans) {
+			const records = this.#extractRecords(span);
+			for (const record of records) storeOperations.push(this.#storeRecord(record));
+		}
+		const results = await Promise.allSettled(storeOperations);
+		const rejected = results.filter((r) => r.status === "rejected");
+		if (rejected.length > 0) throw new AggregateError(rejected.map((r) => r.reason), "Failed to store one or more trace activity records.");
+	}
+	#extractRecords(span) {
+		const records = [];
+		const spanContext = span.spanContext();
+		const traceId = spanContext.traceId;
+		const spanId = spanContext.spanId;
+		const parentSpanId = span.parentSpanContext?.spanId;
+		for (const event of span.events) if (event.name === "activitypub.activity.received") {
+			const record = this.#extractInboundRecord(event, traceId, spanId, parentSpanId);
+			if (record != null) records.push(record);
+		} else if (event.name === "activitypub.activity.sent") {
+			const record = this.#extractOutboundRecord(event, traceId, spanId, parentSpanId);
+			if (record != null) records.push(record);
+		}
+		return records;
+	}
+	#extractInboundRecord(event, traceId, spanId, parentSpanId) {
+		const attrs = event.attributes;
+		if (attrs == null) return null;
+		const activityJson = attrs["activitypub.activity.json"];
+		if (typeof activityJson !== "string") return null;
+		let activityType = "Unknown";
+		let activityId;
+		let actorId;
+		try {
+			const activity = JSON.parse(activityJson);
+			activityType = activity.type ?? "Unknown";
+			activityId = activity.id;
+			if (typeof activity.actor === "string") actorId = activity.actor;
+			else if (activity.actor != null && typeof activity.actor.id === "string") actorId = activity.actor.id;
+		} catch {}
+		const verified = attrs["activitypub.activity.verified"];
+		const httpSigVerified = attrs["http_signatures.verified"];
+		const httpSigKeyId = attrs["http_signatures.key_id"];
+		const ldSigVerified = attrs["ld_signatures.verified"];
+		let signatureDetails;
+		if (typeof httpSigVerified === "boolean" || typeof ldSigVerified === "boolean") signatureDetails = {
+			httpSignaturesVerified: httpSigVerified === true,
+			httpSignaturesKeyId: typeof httpSigKeyId === "string" && httpSigKeyId !== "" ? httpSigKeyId : void 0,
+			ldSignaturesVerified: ldSigVerified === true
+		};
+		return {
+			traceId,
+			spanId,
+			parentSpanId,
+			direction: "inbound",
+			activityType,
+			activityId,
+			actorId,
+			activityJson,
+			verified: typeof verified === "boolean" ? verified : void 0,
+			signatureDetails,
+			timestamp: (/* @__PURE__ */ new Date(event.time[0] * 1e3 + event.time[1] / 1e6)).toISOString()
+		};
+	}
+	#extractOutboundRecord(event, traceId, spanId, parentSpanId) {
+		const attrs = event.attributes;
+		if (attrs == null) return null;
+		const activityJson = attrs["activitypub.activity.json"];
+		if (typeof activityJson !== "string") return null;
+		let activityType = "Unknown";
+		let activityId;
+		let actorId;
+		try {
+			const activity = JSON.parse(activityJson);
+			activityType = activity.type ?? "Unknown";
+			activityId = activity.id;
+			if (typeof activity.actor === "string") actorId = activity.actor;
+			else if (activity.actor != null && typeof activity.actor.id === "string") actorId = activity.actor.id;
+		} catch {}
+		const inboxUrl = attrs["activitypub.inbox.url"];
+		const explicitActivityId = attrs["activitypub.activity.id"];
+		return {
+			traceId,
+			spanId,
+			parentSpanId,
+			direction: "outbound",
+			activityType,
+			activityId: activityId ?? (typeof explicitActivityId === "string" && explicitActivityId !== "" ? explicitActivityId : void 0),
+			actorId,
+			activityJson,
+			timestamp: (/* @__PURE__ */ new Date(event.time[0] * 1e3 + event.time[1] / 1e6)).toISOString(),
+			inboxUrl: typeof inboxUrl === "string" ? inboxUrl : void 0
+		};
+	}
+	async #storeRecord(record) {
+		const options = this.#ttl != null ? { ttl: this.#ttl } : void 0;
+		const key = [
+			...this.#keyPrefix,
+			record.traceId,
+			record.spanId
+		];
+		await this.#kv.set(key, record, options);
+		await this.#updateTraceSummary(record, options);
+	}
+	async #setWithCasRetry(key, transform, options) {
+		if (this.#kv.cas != null) for (let attempt = 0; attempt < 3; attempt++) {
+			const existing$1 = await this.#kv.get(key);
+			const newValue$1 = transform(existing$1);
+			if (await this.#kv.cas(key, existing$1, newValue$1, options)) return;
+		}
+		const existing = await this.#kv.get(key);
+		const newValue = transform(existing);
+		await this.#kv.set(key, newValue, options);
+	}
+	async #updateTraceSummary(record, options) {
+		const summaryKey = [
+			...this.#keyPrefix,
+			"_summaries",
+			record.traceId
+		];
+		await this.#setWithCasRetry(summaryKey, (existing) => {
+			const activityCount = existing != null ? existing.activityCount + 1 : 1;
+			const activityTypes = existing != null ? existing.activityTypes.includes(record.activityType) ? existing.activityTypes : [...existing.activityTypes, record.activityType] : [record.activityType];
+			return {
+				traceId: existing?.traceId ?? record.traceId,
+				timestamp: existing?.timestamp ?? record.timestamp,
+				activityCount,
+				activityTypes
+			};
+		}, options);
+	}
+	/**
+	* Gets all activity records for a specific trace ID.
+	*
+	* @param traceId The trace ID to query.
+	* @returns An array of activity records belonging to the trace.
+	*/
+	async getActivitiesByTraceId(traceId) {
+		const prefix = [...this.#keyPrefix, traceId];
+		const records = [];
+		for await (const entry of this.#kv.list(prefix)) records.push(entry.value);
+		return records;
+	}
+	/**
+	* Gets recent traces with summary information.
+	*
+	* @param options Options for the query.
+	* @returns An array of trace summaries.
+	*/
+	async getRecentTraces(options) {
+		const summaryPrefix = [...this.#keyPrefix, "_summaries"];
+		const summaries = [];
+		for await (const entry of this.#kv.list(summaryPrefix)) summaries.push(entry.value);
+		summaries.sort((a, b) => b.timestamp.localeCompare(a.timestamp));
+		if (options?.limit != null) return summaries.slice(0, options.limit);
+		return summaries;
+	}
+	/**
+	* Forces the exporter to flush any buffered data.
+	* This is a no-op because we write directly to the KvStore without buffering.
+	*/
+	async forceFlush() {}
+	/**
+	* Shuts down the exporter.
+	*/
+	async shutdown() {}
+};
+
+//#endregion
+exports.FedifySpanExporter = FedifySpanExporter;

package/dist/otel/mod.d.cts

@@ -0,0 +1,230 @@
+import { KvKey, KvStore } from "../kv-B4vFhIYL.cjs";
+import { ReadableSpan, SpanExporter } from "@opentelemetry/sdk-trace-base";
+import { ExportResultCode } from "@opentelemetry/core";
+
+//#region src/otel/exporter.d.ts
+/**
+ * The direction of an activity in the trace.
+ *
+ * @since 1.10.0
+ */
+type ActivityDirection = "inbound" | "outbound";
+/**
+ * Signature verification details for an inbound activity.
+ *
+ * @since 1.10.0
+ */
+interface SignatureVerificationDetails {
+  /**
+   * Whether HTTP Signatures were verified.
+   */
+  readonly httpSignaturesVerified: boolean;
+  /**
+   * The key ID used for HTTP signature verification, if available.
+   */
+  readonly httpSignaturesKeyId?: string;
+  /**
+   * Whether Linked Data Signatures were verified.
+   */
+  readonly ldSignaturesVerified: boolean;
+}
+/**
+ * A record of an activity captured from a trace span.
+ * This interface stores the activity data along with trace context
+ * for distributed tracing support.
+ *
+ * @since 1.10.0
+ */
+interface TraceActivityRecord {
+  /**
+   * The trace ID from OpenTelemetry.
+   */
+  readonly traceId: string;
+  /**
+   * The span ID from OpenTelemetry.
+   */
+  readonly spanId: string;
+  /**
+   * The parent span ID, if any.
+   */
+  readonly parentSpanId?: string;
+  /**
+   * Whether this is an inbound or outbound activity.
+   */
+  readonly direction: ActivityDirection;
+  /**
+   * The ActivityPub activity type (e.g., "Create", "Follow", "Like").
+   */
+  readonly activityType: string;
+  /**
+   * The activity's ID URL, if present.
+   */
+  readonly activityId?: string;
+  /**
+   * The actor ID URL (sender of the activity).
+   */
+  readonly actorId?: string;
+  /**
+   * The full JSON representation of the activity.
+   */
+  readonly activityJson: string;
+  /**
+   * Whether the activity was verified (for inbound activities).
+   */
+  readonly verified?: boolean;
+  /**
+   * Detailed signature verification information (for inbound activities).
+   */
+  readonly signatureDetails?: SignatureVerificationDetails;
+  /**
+   * The timestamp when this record was created (ISO 8601 format).
+   */
+  readonly timestamp: string;
+  /**
+   * The target inbox URL (for outbound activities).
+   */
+  readonly inboxUrl?: string;
+}
+/**
+ * Summary information about a trace.
+ *
+ * @since 1.10.0
+ */
+interface TraceSummary {
+  /**
+   * The trace ID.
+   */
+  readonly traceId: string;
+  /**
+   * The timestamp of the first activity in the trace.
+   */
+  readonly timestamp: string;
+  /**
+   * The number of activities in the trace.
+   */
+  readonly activityCount: number;
+  /**
+   * Activity types present in this trace.
+   */
+  readonly activityTypes: readonly string[];
+}
+/**
+ * Options for configuring the {@link FedifySpanExporter}.
+ *
+ * @since 1.10.0
+ */
+interface FedifySpanExporterOptions {
+  /**
+   * The time-to-live for stored trace data.
+   * If not specified, data will be stored indefinitely
+   * (or until manually deleted).
+   */
+  readonly ttl?: Temporal.Duration;
+  /**
+   * The key prefix for storing trace data in the KvStore.
+   * Defaults to `["fedify", "traces"]`.
+   */
+  readonly keyPrefix?: KvKey;
+}
+/**
+ * Options for the {@link FedifySpanExporter.getRecentTraces} method.
+ *
+ * @since 1.10.0
+ */
+interface GetRecentTracesOptions {
+  /**
+   * Maximum number of traces to return.
+   * If not specified, returns all available traces.
+   */
+  limit?: number;
+}
+/**
+ * A SpanExporter that persists ActivityPub activity traces to a
+ * {@link KvStore}.  This enables distributed tracing across multiple
+ * nodes in a Fedify deployment.
+ *
+ * The exporter captures activity data from OpenTelemetry span events
+ * (`activitypub.activity.received` and `activitypub.activity.sent`)
+ * and stores them in the KvStore with trace context preserved.
+ *
+ * @example Basic usage with MemoryKvStore
+ * ```typescript ignore
+ * import { MemoryKvStore } from "@fedify/fedify";
+ * import { FedifySpanExporter } from "@fedify/fedify/otel";
+ * import {
+ *   BasicTracerProvider,
+ *   SimpleSpanProcessor,
+ * } from "@opentelemetry/sdk-trace-base";
+ *
+ * const kv = new MemoryKvStore();
+ * const exporter = new FedifySpanExporter(kv, {
+ *   ttl: Temporal.Duration.from({ hours: 1 }),
+ * });
+ *
+ * const provider = new BasicTracerProvider({
+ *   spanProcessors: [new SimpleSpanProcessor(exporter)],
+ * });
+ * ```
+ *
+ * @example Querying stored traces
+ * ```typescript ignore
+ * import { MemoryKvStore } from "@fedify/fedify";
+ * import { FedifySpanExporter } from "@fedify/fedify/otel";
+ *
+ * const kv = new MemoryKvStore();
+ * const exporter = new FedifySpanExporter(kv);
+ * const traceId = "abc123";
+ *
+ * // Get all activities for a specific trace
+ * const activities = await exporter.getActivitiesByTraceId(traceId);
+ *
+ * // Get recent traces
+ * const recentTraces = await exporter.getRecentTraces({ limit: 100 });
+ * ```
+ *
+ * @since 1.10.0
+ */
+declare class FedifySpanExporter implements SpanExporter {
+  #private;
+  /**
+   * Creates a new FedifySpanExporter.
+   *
+   * @param kv The KvStore to persist trace data to.
+   * @param options Configuration options.
+   */
+  constructor(kv: KvStore, options?: FedifySpanExporterOptions);
+  /**
+   * Exports spans to the KvStore.
+   *
+   * @param spans The spans to export.
+   * @param resultCallback Callback to invoke with the export result.
+   */
+  export(spans: ReadableSpan[], resultCallback: (result: {
+    code: ExportResultCode;
+  }) => void): void;
+  /**
+   * Gets all activity records for a specific trace ID.
+   *
+   * @param traceId The trace ID to query.
+   * @returns An array of activity records belonging to the trace.
+   */
+  getActivitiesByTraceId(traceId: string): Promise<TraceActivityRecord[]>;
+  /**
+   * Gets recent traces with summary information.
+   *
+   * @param options Options for the query.
+   * @returns An array of trace summaries.
+   */
+  getRecentTraces(options?: GetRecentTracesOptions): Promise<TraceSummary[]>;
+  /**
+   * Forces the exporter to flush any buffered data.
+   * This is a no-op because we write directly to the KvStore without buffering.
+   */
+  forceFlush(): Promise<void>;
+  /**
+   * Shuts down the exporter.
+   */
+  shutdown(): Promise<void>;
+}
+//#endregion
+export { ActivityDirection, FedifySpanExporter, FedifySpanExporterOptions, GetRecentTracesOptions, SignatureVerificationDetails, TraceActivityRecord, TraceSummary };

package/dist/otel/mod.d.ts

@@ -0,0 +1,232 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { URLPattern } from "urlpattern-polyfill";
+import { KvKey, KvStore } from "../kv-CYySNrsn.js";
+import { ExportResultCode } from "@opentelemetry/core";
+import { ReadableSpan, SpanExporter } from "@opentelemetry/sdk-trace-base";
+
+//#region src/otel/exporter.d.ts
+/**
+ * The direction of an activity in the trace.
+ *
+ * @since 1.10.0
+ */
+type ActivityDirection = "inbound" | "outbound";
+/**
+ * Signature verification details for an inbound activity.
+ *
+ * @since 1.10.0
+ */
+interface SignatureVerificationDetails {
+  /**
+   * Whether HTTP Signatures were verified.
+   */
+  readonly httpSignaturesVerified: boolean;
+  /**
+   * The key ID used for HTTP signature verification, if available.
+   */
+  readonly httpSignaturesKeyId?: string;
+  /**
+   * Whether Linked Data Signatures were verified.
+   */
+  readonly ldSignaturesVerified: boolean;
+}
+/**
+ * A record of an activity captured from a trace span.
+ * This interface stores the activity data along with trace context
+ * for distributed tracing support.
+ *
+ * @since 1.10.0
+ */
+interface TraceActivityRecord {
+  /**
+   * The trace ID from OpenTelemetry.
+   */
+  readonly traceId: string;
+  /**
+   * The span ID from OpenTelemetry.
+   */
+  readonly spanId: string;
+  /**
+   * The parent span ID, if any.
+   */
+  readonly parentSpanId?: string;
+  /**
+   * Whether this is an inbound or outbound activity.
+   */
+  readonly direction: ActivityDirection;
+  /**
+   * The ActivityPub activity type (e.g., "Create", "Follow", "Like").
+   */
+  readonly activityType: string;
+  /**
+   * The activity's ID URL, if present.
+   */
+  readonly activityId?: string;
+  /**
+   * The actor ID URL (sender of the activity).
+   */
+  readonly actorId?: string;
+  /**
+   * The full JSON representation of the activity.
+   */
+  readonly activityJson: string;
+  /**
+   * Whether the activity was verified (for inbound activities).
+   */
+  readonly verified?: boolean;
+  /**
+   * Detailed signature verification information (for inbound activities).
+   */
+  readonly signatureDetails?: SignatureVerificationDetails;
+  /**
+   * The timestamp when this record was created (ISO 8601 format).
+   */
+  readonly timestamp: string;
+  /**
+   * The target inbox URL (for outbound activities).
+   */
+  readonly inboxUrl?: string;
+}
+/**
+ * Summary information about a trace.
+ *
+ * @since 1.10.0
+ */
+interface TraceSummary {
+  /**
+   * The trace ID.
+   */
+  readonly traceId: string;
+  /**
+   * The timestamp of the first activity in the trace.
+   */
+  readonly timestamp: string;
+  /**
+   * The number of activities in the trace.
+   */
+  readonly activityCount: number;
+  /**
+   * Activity types present in this trace.
+   */
+  readonly activityTypes: readonly string[];
+}
+/**
+ * Options for configuring the {@link FedifySpanExporter}.
+ *
+ * @since 1.10.0
+ */
+interface FedifySpanExporterOptions {
+  /**
+   * The time-to-live for stored trace data.
+   * If not specified, data will be stored indefinitely
+   * (or until manually deleted).
+   */
+  readonly ttl?: Temporal.Duration;
+  /**
+   * The key prefix for storing trace data in the KvStore.
+   * Defaults to `["fedify", "traces"]`.
+   */
+  readonly keyPrefix?: KvKey;
+}
+/**
+ * Options for the {@link FedifySpanExporter.getRecentTraces} method.
+ *
+ * @since 1.10.0
+ */
+interface GetRecentTracesOptions {
+  /**
+   * Maximum number of traces to return.
+   * If not specified, returns all available traces.
+   */
+  limit?: number;
+}
+/**
+ * A SpanExporter that persists ActivityPub activity traces to a
+ * {@link KvStore}.  This enables distributed tracing across multiple
+ * nodes in a Fedify deployment.
+ *
+ * The exporter captures activity data from OpenTelemetry span events
+ * (`activitypub.activity.received` and `activitypub.activity.sent`)
+ * and stores them in the KvStore with trace context preserved.
+ *
+ * @example Basic usage with MemoryKvStore
+ * ```typescript ignore
+ * import { MemoryKvStore } from "@fedify/fedify";
+ * import { FedifySpanExporter } from "@fedify/fedify/otel";
+ * import {
+ *   BasicTracerProvider,
+ *   SimpleSpanProcessor,
+ * } from "@opentelemetry/sdk-trace-base";
+ *
+ * const kv = new MemoryKvStore();
+ * const exporter = new FedifySpanExporter(kv, {
+ *   ttl: Temporal.Duration.from({ hours: 1 }),
+ * });
+ *
+ * const provider = new BasicTracerProvider({
+ *   spanProcessors: [new SimpleSpanProcessor(exporter)],
+ * });
+ * ```
+ *
+ * @example Querying stored traces
+ * ```typescript ignore
+ * import { MemoryKvStore } from "@fedify/fedify";
+ * import { FedifySpanExporter } from "@fedify/fedify/otel";
+ *
+ * const kv = new MemoryKvStore();
+ * const exporter = new FedifySpanExporter(kv);
+ * const traceId = "abc123";
+ *
+ * // Get all activities for a specific trace
+ * const activities = await exporter.getActivitiesByTraceId(traceId);
+ *
+ * // Get recent traces
+ * const recentTraces = await exporter.getRecentTraces({ limit: 100 });
+ * ```
+ *
+ * @since 1.10.0
+ */
+declare class FedifySpanExporter implements SpanExporter {
+  #private;
+  /**
+   * Creates a new FedifySpanExporter.
+   *
+   * @param kv The KvStore to persist trace data to.
+   * @param options Configuration options.
+   */
+  constructor(kv: KvStore, options?: FedifySpanExporterOptions);
+  /**
+   * Exports spans to the KvStore.
+   *
+   * @param spans The spans to export.
+   * @param resultCallback Callback to invoke with the export result.
+   */
+  export(spans: ReadableSpan[], resultCallback: (result: {
+    code: ExportResultCode;
+  }) => void): void;
+  /**
+   * Gets all activity records for a specific trace ID.
+   *
+   * @param traceId The trace ID to query.
+   * @returns An array of activity records belonging to the trace.
+   */
+  getActivitiesByTraceId(traceId: string): Promise<TraceActivityRecord[]>;
+  /**
+   * Gets recent traces with summary information.
+   *
+   * @param options Options for the query.
+   * @returns An array of trace summaries.
+   */
+  getRecentTraces(options?: GetRecentTracesOptions): Promise<TraceSummary[]>;
+  /**
+   * Forces the exporter to flush any buffered data.
+   * This is a no-op because we write directly to the KvStore without buffering.
+   */
+  forceFlush(): Promise<void>;
+  /**
+   * Shuts down the exporter.
+   */
+  shutdown(): Promise<void>;
+}
+//#endregion
+export { ActivityDirection, FedifySpanExporter, FedifySpanExporterOptions, GetRecentTracesOptions, SignatureVerificationDetails, TraceActivityRecord, TraceSummary };