@fedify/fedify 2.3.0 → 2.4.0-dev.1422

package/dist/{middleware-DXLo-UOS.cjs → middleware-BiCk4wGY.cjs}

@@ -2,10 +2,10 @@ const { Temporal } = require("@js-temporal/polyfill");
 const { URLPattern } = require("urlpattern-polyfill");
 const require_chunk = require("./chunk-DDcVe30Y.cjs");
 const require_transformers = require("./transformers-NeAONrAq.cjs");
-const require_http = require("./http-Q2nW0DHO.cjs");
-const require_proof = require("./proof-CIUSLcHg.cjs");
+const require_http = require("./http-BCSQJ_gv.cjs");
+const require_proof = require("./proof-DA3hLGSO.cjs");
 const require_types = require("./types-KC4QAoxe.cjs");
-const require_kv_cache = require("./kv-cache-QkLiue07.cjs");
+const require_kv_cache = require("./kv-cache-DXwu7BtY.cjs");
 let _logtape_logtape = require("@logtape/logtape");
 let _fedify_uri_template = require("@fedify/uri-template");
 let _fedify_vocab = require("@fedify/vocab");
@@ -18,6 +18,7 @@ let _fedify_vocab_runtime_jsonld = require("@fedify/vocab-runtime/jsonld");
 _fedify_vocab_runtime_jsonld = require_chunk.__toESM(_fedify_vocab_runtime_jsonld, 1);
 let _fedify_webfinger = require("@fedify/webfinger");
 let _opentelemetry_sdk_metrics = require("@opentelemetry/sdk-metrics");
+let devalue = require("devalue");
 let node_url = require("node:url");
 //#region src/federation/activity-listener.ts
 var ActivityListenerSet = class {
@@ -108,6 +109,7 @@ var FederationBuilderImpl = class {
 	idempotencyStrategy;
 	collectionTypeIds;
 	collectionCallbacks;
+	taskDefinitions;
 	/**
 	* Symbol registry for unique identification of unnamed symbols.
 	*/
@@ -118,6 +120,7 @@ var FederationBuilderImpl = class {
 		this.objectTypeIds = {};
 		this.collectionCallbacks = {};
 		this.collectionTypeIds = {};
+		this.taskDefinitions = /* @__PURE__ */ new Map();
 	}
 	/**
 	* Builds the federation object.
@@ -156,6 +159,7 @@ var FederationBuilderImpl = class {
 		f.unverifiedActivityHandler = this.unverifiedActivityHandler;
 		f.outboxPermanentFailureHandler = this.outboxPermanentFailureHandler;
 		f.idempotencyStrategy = this.idempotencyStrategy;
+		f.taskDefinitions = new Map(this.taskDefinitions);
 		return f;
 	}
 	_getTracer() {
@@ -288,6 +292,23 @@ var FederationBuilderImpl = class {
 	setWebFingerLinksDispatcher(dispatcher) {
 		this.webFingerLinksDispatcher = dispatcher;
 	}
+	defineTask(name, options) {
+		if (this.taskDefinitions.has(name)) throw new TypeError(`Task ${JSON.stringify(name)} is already defined.`);
+		const handle = {
+			name,
+			schema: options.schema
+		};
+		this.taskDefinitions.set(name, {
+			name,
+			schema: options.schema,
+			handle,
+			handler: options.handler,
+			onError: options.onError,
+			retryPolicy: options.retryPolicy,
+			queue: options.queue
+		});
+		return handle;
+	}
 	/**
 	* The RFC 6570 template-literal `path` overloads were removed for
 	* type-checking efficiency, so the URI variable types can no longer be
@@ -1393,7 +1414,7 @@ function acceptsJsonLd(request) {
 }
 //#endregion
 //#region src/federation/temporal.ts
-function isPlainObject(value) {
+function isPlainObject$1(value) {
 	return typeof value === "object" && value != null && !Array.isArray(value);
 }
 function normalizeDateTimeLiteral(value) {
@@ -1431,11 +1452,11 @@ const QUESTION_CLOSED_IRI = "https://www.w3.org/ns/activitystreams#closed";
 const XSD_DATE_TIME_IRI = "http://www.w3.org/2001/XMLSchema#dateTime";
 function hasMalformedExpandedDateTimeLiteral(value) {
 	if (Array.isArray(value)) return value.some(hasMalformedExpandedDateTimeLiteral);
-	return isPlainObject(value) && "@value" in value && isMalformedDateTimeLiteral(value["@value"]);
+	return isPlainObject$1(value) && "@value" in value && isMalformedDateTimeLiteral(value["@value"]);
 }
 function hasMalformedExpandedQuestionClosedLiteral(value) {
 	if (Array.isArray(value)) return value.some(hasMalformedExpandedQuestionClosedLiteral);
-	if (!isPlainObject(value) || !("@value" in value)) return false;
+	if (!isPlainObject$1(value) || !("@value" in value)) return false;
 	const literal = value["@value"];
 	if (typeof literal === "boolean") return false;
 	if (typeof literal !== "string") return false;
@@ -1445,11 +1466,11 @@ function hasMalformedExpandedQuestionClosedLiteral(value) {
 }
 function hasMalformedExpandedDurationLiteral(value) {
 	if (Array.isArray(value)) return value.some(hasMalformedExpandedDurationLiteral);
-	return isPlainObject(value) && "@value" in value && isMalformedDurationLiteral(value["@value"]);
+	return isPlainObject$1(value) && "@value" in value && isMalformedDurationLiteral(value["@value"]);
 }
 function hasMalformedKnownTemporalLiteralInternal(value, visited) {
 	if (Array.isArray(value)) return value.some((item) => hasMalformedKnownTemporalLiteralInternal(item, visited));
-	if (!isPlainObject(value)) return false;
+	if (!isPlainObject$1(value)) return false;
 	if (visited.has(value)) return false;
 	visited.add(value);
 	if ("@value" in value) return false;
@@ -3553,6 +3574,94 @@ function createExponentialBackoffPolicy(options = {}) {
 	};
 }
 //#endregion
+//#region src/federation/tasks/codec.ts
+var TaskCodec = class TaskCodec {
+	options;
+	constructor(options) {
+		this.options = options;
+	}
+	serialize = (data) => (0, devalue.stringifyAsync)(data, { Vocab: this.#stringifyVocab });
+	deserialize = (raw) => this.#revive(/* @__PURE__ */ new Map())((0, devalue.parse)(raw, { Vocab: VocabHolder.from }));
+	/** Validates `data` against `schema`, then serializes it. */
+	encode = async (schema, data) => this.serialize(await TaskCodec.validate(schema, data));
+	/** Deserializes `raw`, then validates the result against `schema`. */
+	decode = async (schema, raw) => TaskCodec.validate(schema, await this.deserialize(raw));
+	static validate = async (schema, data) => getValueIfSchema(await schema["~standard"].validate(data));
+	#stringifyVocab = (value) => isVocab(value) && this.#toWire(value);
+	#toWire = async (value) => ({
+		kind: value instanceof _fedify_vocab.Link ? "link" : "object",
+		jsonLd: await value.toJsonLd({
+			format: "expand",
+			...this.options
+		})
+	});
+	#revive = (seen) => {
+		const inner = async (node) => {
+			if (node === null || typeof node !== "object") return node;
+			if (seen.has(node)) return seen.get(node);
+			for (const reviver of this.#classRevivers) {
+				const out = reviver(seen, inner, node);
+				if (out !== void 0) return await out;
+			}
+			return node;
+		};
+		return inner;
+	};
+	#classRevivers = [
+		classReviver(isInstanceOf(VocabHolder), ({ kind, jsonLd }) => kind === "link" ? _fedify_vocab.Link.fromJsonLd(jsonLd, this.options) : _fedify_vocab.Object.fromJsonLd(jsonLd, this.options), () => {}),
+		classReviver(isInstanceOf(Array), () => [], async (revive, node, arr) => {
+			for (const item of await Array.fromAsync(node, revive)) arr.push(item);
+		}),
+		classReviver(isInstanceOf(Map), () => /* @__PURE__ */ new Map(), async (revive, node, map) => {
+			for (const [k, v] of node) map.set(await revive(k), await revive(v));
+		}),
+		classReviver(isInstanceOf(Set), () => /* @__PURE__ */ new Set(), async (revive, node, set) => {
+			for (const v of await Array.fromAsync(node, revive)) set.add(v);
+		}),
+		classReviver(isPlainObject, () => ({}), async (revive, node, obj) => {
+			for (const [k, v] of globalThis.Object.entries(node)) obj[k] = await revive(v);
+		})
+	];
+};
+const isVocab = (value) => value instanceof _fedify_vocab.Object || value instanceof _fedify_vocab.Link;
+const isPlainObject = (value) => value === null || typeof value !== "object" ? false : isObjectPrototype(globalThis.Object.getPrototypeOf(value));
+const isObjectPrototype = (proto) => proto === null || proto === globalThis.Object.prototype;
+const isInstanceOf = (cls) => (v) => v instanceof cls;
+function getValueIfSchema(result) {
+	assertSchema(result);
+	return result.value;
+}
+function assertSchema(result) {
+	if (result.issues && result.issues.length > 0) throw new TypeError(`Task data failed schema validation: ${JSON.stringify(result.issues)}`);
+}
+/**
+* A vocabulary object parked by the synchronous decode reviver, held until
+* the async revive pass can `fromJsonLd()` it back into an instance.
+*/
+var VocabHolder = class VocabHolder {
+	kind;
+	jsonLd;
+	constructor(kind, jsonLd) {
+		this.kind = kind;
+		this.jsonLd = jsonLd;
+	}
+	static from = ({ kind, jsonLd }) => new VocabHolder(kind, jsonLd);
+};
+/**
+* Ties a container filter to its empty-shell `init` and child-filling `set`
+* through one type parameter—a correlation the heterogeneous reviver list
+* cannot carry, which previously forced `@ts-ignore` at the dispatch site.
+*/
+const classReviver = (filter, init, set) => (seen, revive, node) => {
+	if (!filter(node)) return void 0;
+	return (async () => {
+		const out = await init(node);
+		seen.set(node, out);
+		await set(revive, node, out);
+		return out;
+	})();
+};
+//#endregion
 //#region src/federation/webfinger.ts
 const logger = (0, _logtape_logtape.getLogger)([
 	"fedify",
@@ -3877,9 +3986,12 @@ var FederationImpl = class extends FederationBuilderImpl {
 	inboxQueue;
 	outboxQueue;
 	fanoutQueue;
+	taskQueue;
 	inboxQueueStarted;
 	outboxQueueStarted;
 	fanoutQueueStarted;
+	taskQueueStarted;
+	startedTaskQueues;
 	manuallyStartQueue;
 	origin;
 	documentLoaderFactory;
@@ -3893,6 +4005,8 @@ var FederationImpl = class extends FederationBuilderImpl {
 	skipSignatureVerification;
 	outboxRetryPolicy;
 	inboxRetryPolicy;
+	taskRetryPolicy;
+	taskQueueResolution;
 	circuitBreaker;
 	activityTransformers;
 	_tracerProvider;
@@ -3938,14 +4052,17 @@ var FederationImpl = class extends FederationBuilderImpl {
 			this.inboxQueue = void 0;
 			this.outboxQueue = void 0;
 			this.fanoutQueue = void 0;
+			this.taskQueue = void 0;
 		} else if ("enqueue" in options.queue && "listen" in options.queue) {
 			this.inboxQueue = options.queue;
 			this.outboxQueue = options.queue;
 			this.fanoutQueue = options.queue;
+			this.taskQueue = void 0;
 		} else {
 			this.inboxQueue = options.queue.inbox;
 			this.outboxQueue = options.queue.outbox;
 			this.fanoutQueue = options.queue.fanout;
+			this.taskQueue = options.queue.task;
 		}
 		if (options.circuitBreaker !== false && this.outboxQueue != null) {
 			this.circuitBreaker = new CircuitBreaker({
@@ -3969,6 +4086,8 @@ var FederationImpl = class extends FederationBuilderImpl {
 		this.inboxQueueStarted = false;
 		this.outboxQueueStarted = false;
 		this.fanoutQueueStarted = false;
+		this.taskQueueStarted = false;
+		this.startedTaskQueues = /* @__PURE__ */ new Set();
 		this.manuallyStartQueue = options.manuallyStartQueue ?? false;
 		if (options.origin != null) if (typeof options.origin === "string") {
 			if (!URL.canParse(options.origin) || !options.origin.match(/^https?:\/\//)) throw new TypeError(`Invalid origin: ${JSON.stringify(options.origin)}`);
@@ -4050,6 +4169,8 @@ var FederationImpl = class extends FederationBuilderImpl {
 		this.inboxChallengePolicy = options.inboxChallengePolicy;
 		this.outboxRetryPolicy = options.outboxRetryPolicy ?? createExponentialBackoffPolicy();
 		this.inboxRetryPolicy = options.inboxRetryPolicy ?? createExponentialBackoffPolicy();
+		this.taskRetryPolicy = options.taskRetryPolicy ?? createExponentialBackoffPolicy();
+		this.taskQueueResolution = options.taskQueueResolution ?? "fallback";
 		this.activityTransformers = options.activityTransformers ?? require_transformers.getDefaultActivityTransformers();
 		this._tracerProvider = options.tracerProvider;
 		if (benchmarkMode) {
@@ -4098,8 +4219,14 @@ var FederationImpl = class extends FederationBuilderImpl {
 	_getTracer() {
 		return this.tracerProvider.getTracer(require_http.name, require_http.version);
 	}
+	resolveTaskQueue(taskName) {
+		const resolved = this.taskDefinitions.get(taskName)?.queue ?? this.taskQueue;
+		if (resolved != null) return resolved;
+		return this.taskQueueResolution === "strict" ? void 0 : this.outboxQueue;
+	}
 	async _startQueueInternal(ctxData, signal, queue) {
-		if (this.inboxQueue == null && this.outboxQueue == null) return;
+		const hasDedicatedTaskQueue = [...this.taskDefinitions.values()].some((def) => def.queue != null);
+		if (this.inboxQueue == null && this.outboxQueue == null && this.fanoutQueue == null && this.taskQueue == null && !hasDedicatedTaskQueue) return;
 		const logger = (0, _logtape_logtape.getLogger)([
 			"fedify",
 			"federation",
@@ -4121,6 +4248,26 @@ var FederationImpl = class extends FederationBuilderImpl {
 			this.fanoutQueueStarted = true;
 			promises.push(this.fanoutQueue.listen((msg) => this.processQueuedTask(ctxData, msg), { signal }));
 		}
+		if (this.taskQueue != null && this.taskQueue !== this.inboxQueue && this.taskQueue !== this.outboxQueue && this.taskQueue !== this.fanoutQueue && (queue == null || queue === "task") && !this.taskQueueStarted) {
+			logger.debug("Starting a task worker.");
+			this.taskQueueStarted = true;
+			promises.push(this.taskQueue.listen((msg) => this.processQueuedTask(ctxData, msg), { signal }));
+		}
+		if (queue == null || queue === "task") {
+			const standardQueues = new Set([
+				this.inboxQueue,
+				this.outboxQueue,
+				this.fanoutQueue,
+				this.taskQueue
+			].filter((q) => q != null));
+			for (const def of this.taskDefinitions.values()) {
+				const taskQueue = def.queue;
+				if (taskQueue == null || standardQueues.has(taskQueue) || this.startedTaskQueues.has(taskQueue)) continue;
+				logger.debug("Starting a worker for a dedicated per-task queue.");
+				this.startedTaskQueues.add(taskQueue);
+				promises.push(taskQueue.listen((msg) => this.processQueuedTask(ctxData, msg), { signal }));
+			}
+		}
 		await Promise.all(promises);
 	}
 	processQueuedTask(contextData, message) {
@@ -4242,7 +4389,7 @@ var FederationImpl = class extends FederationBuilderImpl {
 						}
 					});
 				});
-			}
+			} else if (message.type === "task") await this.#listenTaskMessage(contextData, message);
 		});
 	}
 	async #listenFanoutMessage(data, message) {
@@ -4806,6 +4953,77 @@ var FederationImpl = class extends FederationBuilderImpl {
 			listenerSpan.end();
 		});
 	}
+	async #listenTaskMessage(contextData, message) {
+		const logger = (0, _logtape_logtape.getLogger)([
+			"fedify",
+			"federation",
+			"task"
+		]);
+		const def = this.taskDefinitions.get(message.taskName);
+		if (def == null) {
+			logger.warn("Received a custom task {taskName} with no registered handler; dropping.", { taskName: message.taskName });
+			return;
+		}
+		const context = this.#createContext(new URL(message.baseUrl), contextData);
+		let data;
+		try {
+			data = await context.codec.decode(def.schema, message.data);
+		} catch (error) {
+			logger.error("Custom task {taskName} payload could not be decoded or validated; dropping:\n{error}", {
+				taskName: message.taskName,
+				error
+			});
+			return;
+		}
+		try {
+			await def.handler(context, data);
+		} catch (error) {
+			if (def.onError != null) try {
+				await def.onError(context, error, data);
+			} catch (onErrorError) {
+				logger.error("onError for custom task {taskName} threw:\n{error}", {
+					taskName: message.taskName,
+					error: onErrorError
+				});
+			}
+			const queue = this.resolveTaskQueue(def.name);
+			if (queue?.nativeRetrial) throw error;
+			const retryPolicy = def.retryPolicy ?? this.taskRetryPolicy;
+			let elapsedTime = Temporal.Duration.from({ seconds: 0 });
+			try {
+				elapsedTime = Temporal.Instant.from(message.started).until(Temporal.Now.instant());
+			} catch (parseError) {
+				logger.error("Custom task {taskName} has an unparsable started time {started}; treating elapsedTime as zero:\n{error}", {
+					taskName: message.taskName,
+					started: message.started,
+					error: parseError
+				});
+			}
+			const delay = retryPolicy({
+				elapsedTime,
+				attempts: message.attempt
+			});
+			if (delay != null && queue != null) {
+				logger.error("Custom task {taskName} failed (attempt #{attempt}); retry...:\n{error}", {
+					taskName: message.taskName,
+					attempt: message.attempt,
+					error
+				});
+				const retryMessage = {
+					...message,
+					attempt: message.attempt + 1
+				};
+				await queue.enqueue(retryMessage, {
+					delay: clampNegativeDelay(delay),
+					orderingKey: message.orderingKey
+				});
+			} else logger.error("Custom task {taskName} failed after {attempt} attempts; giving up:\n{error}", {
+				taskName: message.taskName,
+				attempt: message.attempt,
+				error
+			});
+		}
+	}
 	startQueue(contextData, options = {}) {
 		return this._startQueueInternal(contextData, options.signal, options.queue);
 	}
@@ -5382,6 +5600,7 @@ var ContextImpl = class ContextImpl {
 	documentLoader;
 	contextLoader;
 	invokedFromActorKeyPairsDispatcher;
+	#codec;
 	constructor({ url, federation, data, documentLoader, contextLoader, invokedFromActorKeyPairsDispatcher }) {
 		this.url = url;
 		this.federation = federation;
@@ -5390,6 +5609,15 @@ var ContextImpl = class ContextImpl {
 		this.contextLoader = contextLoader;
 		this.invokedFromActorKeyPairsDispatcher = invokedFromActorKeyPairsDispatcher;
 	}
+	/**
+	* A {@link TaskCodec} bound to this context's loaders, used to encode
+	* and decode custom task payloads.  Lazily created and cached so a context
+	* that never enqueues or dispatches a task pays nothing.
+	* @internal
+	*/
+	get codec() {
+		return this.#codec ??= new TaskCodec(this);
+	}
 	clone(data) {
 		return new ContextImpl({
 			url: this.url,
@@ -5708,6 +5936,45 @@ var ContextImpl = class ContextImpl {
 			allowPrivateAddress: this.federation.allowPrivateAddress
 		});
 	}
+	async enqueueTask(task, data, options = {}) {
+		await this.#enqueueTasks(task, [data], options);
+	}
+	async enqueueTaskMany(task, payloads, options = {}) {
+		await this.#enqueueTasks(task, payloads, options);
+	}
+	async #enqueueTasks(task, items, options) {
+		const def = this.federation.taskDefinitions.get(task.name);
+		if (def == null || def.handle !== task) throw new TypeError(`Task ${JSON.stringify(task.name)} is not defined on this federation; pass a handle returned by its defineTask().`);
+		const queue = this.federation.resolveTaskQueue(task.name);
+		if (queue == null) throw new TypeError("No message queue is configured for tasks; pass `queue` to createFederation() or to defineTask().");
+		if (items.length < 1) return;
+		const delay = options.delay == null ? void 0 : Temporal.Duration.from(options.delay);
+		const messages = await Promise.all(items.map(this.#encodeTaskMessage(task, options)));
+		if (!this.federation.manuallyStartQueue) this.federation._startQueueInternal(this.data);
+		const enqueueOptions = {
+			delay,
+			orderingKey: options.orderingKey
+		};
+		if (messages.length === 1) await queue.enqueue(messages[0], enqueueOptions);
+		else if (queue.enqueueMany != null) await queue.enqueueMany(messages, enqueueOptions);
+		else await Promise.all(messages.map((m) => queue.enqueue(m, enqueueOptions)));
+	}
+	#encodeTaskMessage = (task, options) => async (data) => {
+		const encoded = await this.codec.encode(task.schema, data);
+		const carrier = {};
+		_opentelemetry_api.propagation.inject(_opentelemetry_api.context.active(), carrier);
+		return {
+			type: "task",
+			id: crypto.randomUUID(),
+			baseUrl: this.origin,
+			taskName: task.name,
+			data: encoded,
+			started: Temporal.Now.instant().toString(),
+			attempt: 0,
+			orderingKey: options.orderingKey,
+			traceContext: carrier
+		};
+	};
 	sendActivity(sender, recipients, activity, options = {}) {
 		return this.tracerProvider.getTracer(require_http.name, require_http.version).startActiveSpan(this.federation.outboxQueue == null || options.immediate ? "activitypub.outbox" : "activitypub.fanout", {
 			kind: this.federation.outboxQueue == null || options.immediate ? _opentelemetry_api.SpanKind.CLIENT : _opentelemetry_api.SpanKind.PRODUCER,

package/dist/{middleware-BIctkZ9S.mjs → middleware-Dq-HhJHd.mjs}

@@ -1,5 +1,5 @@
 import "@js-temporal/polyfill";
 import "urlpattern-polyfill";
 globalThis.addEventListener = () => {};
-import { n as FederationImpl } from "./middleware-CwJv5KxX.mjs";
+import { n as FederationImpl } from "./middleware-PZaroDUk.mjs";
 export { FederationImpl };