@fedify/fedify 2.4.0-dev.1490 → 2.4.0-dev.1508

package/dist/{middleware-B3vFLcCh.js → middleware-vQ_ZpgcX.js}

@@ -2,10 +2,10 @@ import { Temporal } from "@js-temporal/polyfill";
 import { URLPattern } from "urlpattern-polyfill";
 import { t as __exportAll } from "./chunk-CRNNMoPX.js";
 import { r as getDefaultActivityTransformers } from "./transformers-BGMIq1cs.js";
-import { A as formatAcceptSignature, D as recordOutboxEnqueue, E as recordOutboxActivity, F as version, O as recordWebFingerHandle, P as name, S as recordCollectionTotalItems, T as recordInboxActivity, a as verifyRequestDetailed, b as recordCollectionPageItems, d as validateCryptoKey, f as getDurationMs, g as isAbortError, h as instrumentDocumentLoader, i as verifyRequest, k as registerQueueDepthGauge, m as getRemoteHost, n as parseRfc9421SignatureInput, o as exportJwk, p as getFederationMetrics, t as doubleKnock, u as importJwk, v as recordCircuitBreakerStateChange, w as recordFanoutRecipients, x as recordCollectionRequest, y as recordCollectionDispatchDuration } from "./http-BqSm-f2G.js";
-import { _ as hasSignatureLike, b as signJsonLd, c as getKeyOwner, f as compactJsonLd, g as hasSignature, h as getNormalizationContextLoader, i as verifyObject, l as InvalidContextReferenceError, m as detachSignature, n as hasProofLike, o as normalizeOutgoingActivityJsonLd, r as signObject, s as doesActorOwnKey, u as assertSafeJsonLd, v as isClearlyMalformedContextReference, w as wrapContextLoaderForJsonLd, x as verifyCompactJsonLd, y as isInvalidUrlTypeError } from "./proof-BhNTn0HE.js";
+import { A as formatAcceptSignature, D as recordOutboxEnqueue, E as recordOutboxActivity, F as version, O as recordWebFingerHandle, P as name, S as recordCollectionTotalItems, T as recordInboxActivity, a as verifyRequestDetailed, b as recordCollectionPageItems, d as validateCryptoKey, f as getDurationMs, g as isAbortError, h as instrumentDocumentLoader, i as verifyRequest, k as registerQueueDepthGauge, m as getRemoteHost, n as parseRfc9421SignatureInput, o as exportJwk, p as getFederationMetrics, t as doubleKnock, u as importJwk, v as recordCircuitBreakerStateChange, w as recordFanoutRecipients, x as recordCollectionRequest, y as recordCollectionDispatchDuration } from "./http-Dv3147TL.js";
+import { _ as hasSignatureLike, b as signJsonLd, c as getKeyOwner, f as compactJsonLd, g as hasSignature, h as getNormalizationContextLoader, i as verifyObject, l as InvalidContextReferenceError, m as detachSignature, n as hasProofLike, o as normalizeOutgoingActivityJsonLd, r as signObject, s as doesActorOwnKey, u as assertSafeJsonLd, v as isClearlyMalformedContextReference, w as wrapContextLoaderForJsonLd, x as verifyCompactJsonLd, y as isInvalidUrlTypeError } from "./proof-CTG9azxN.js";
 import { n as getNodeInfo, t as nodeInfoToJson } from "./types-CAY3OdLq.js";
-import { n as getAuthenticatedDocumentLoader, t as kvCache } from "./kv-cache-Crq8nvSV.js";
+import { n as getAuthenticatedDocumentLoader, t as kvCache } from "./kv-cache-C2oTEXyb.js";
 import { getLogger, withContext } from "@logtape/logtape";
 import { Router, RouterError, assertPath } from "@fedify/uri-template";
 import { Activity, Collection, CollectionPage, CryptographicKey, Link, Multikey, Object as Object$1, OrderedCollection, OrderedCollectionPage, Tombstone, getTypeId, lookupObject, traverseCollection } from "@fedify/vocab";
@@ -17,6 +17,7 @@ import { ATTR_HTTP_REQUEST_HEADER, ATTR_HTTP_REQUEST_METHOD, ATTR_HTTP_RESPONSE_
 import jsonld from "@fedify/vocab-runtime/jsonld";
 import { lookupWebFinger } from "@fedify/webfinger";
 import { DataPointType, MeterProvider as MeterProvider$1, MetricReader } from "@opentelemetry/sdk-metrics";
+import { parse, stringifyAsync } from "devalue";
 import { domainToASCII } from "node:url";
 //#region src/federation/activity-listener.ts
 var ActivityListenerSet = class {
@@ -107,6 +108,7 @@ var FederationBuilderImpl = class {
 	idempotencyStrategy;
 	collectionTypeIds;
 	collectionCallbacks;
+	taskDefinitions;
 	/**
 	* Symbol registry for unique identification of unnamed symbols.
 	*/
@@ -117,6 +119,7 @@ var FederationBuilderImpl = class {
 		this.objectTypeIds = {};
 		this.collectionCallbacks = {};
 		this.collectionTypeIds = {};
+		this.taskDefinitions = /* @__PURE__ */ new Map();
 	}
 	/**
 	* Builds the federation object.
@@ -155,6 +158,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() {
@@ -287,6 +291,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
@@ -1392,7 +1413,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) {
@@ -1430,11 +1451,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;
@@ -1444,11 +1465,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;
@@ -3552,6 +3573,529 @@ function createExponentialBackoffPolicy(options = {}) {
 	};
 }
 //#endregion
+//#region src/federation/tasks/codec.ts
+/**
+* Serializes and deserializes task payloads for the queue, preserving
+* `@fedify/vocab` objects across the wire by reducing them to JSON-LD and
+* rebuilding them on the worker with the bound {@link TaskCodecLoaders}.
+* @internal
+*/
+var TaskCodec = class TaskCodec {
+	options;
+	constructor(options) {
+		this.options = options;
+	}
+	/** Serializes `data`, encoding any vocabulary object as its JSON-LD. */
+	serialize = (data) => stringifyAsync(data, { Vocab: this.#stringifyVocab });
+	/** Deserializes `raw`, rebuilding any encoded vocabulary object. */
+	deserialize = (raw) => this.#revive(/* @__PURE__ */ new Map())(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));
+	/** Validates `data` against `schema`, returning its parsed output. */
+	static validate = async (schema, data) => getValueIfSchema(await schema["~standard"].validate(data));
+	#stringifyVocab = (value) => isVocab(value) && this.#toWire(value);
+	#toWire = async (value) => ({
+		kind: value instanceof 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" ? Link.fromJsonLd(jsonLd, this.options) : Object$1.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 Object$1 || value instanceof 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/mq.ts
+/**
+* A message queue that processes messages in the same process.
+* Do not use this in production as it does neither persist messages nor
+* distribute them across multiple processes.
+*
+* @since 0.5.0
+*/
+var InProcessMessageQueue = class {
+	#messages;
+	#monitors;
+	#pollIntervalMs;
+	#delayedMessages;
+	/**
+	* Tracks which ordering keys are currently being processed to ensure
+	* sequential processing for messages with the same key.
+	*/
+	#processingKeys;
+	/**
+	* In-process message queue does not provide native retry mechanisms.
+	* @since 1.7.0
+	*/
+	nativeRetrial = false;
+	/**
+	* In-process message queue does not deduplicate messages natively.
+	* @since 2.4.0
+	*/
+	nativeDeduplication = false;
+	/**
+	* Constructs a new {@link InProcessMessageQueue} with the given options.
+	* @param options Additional options for the in-process message queue.
+	*/
+	constructor(options = {}) {
+		this.#messages = [];
+		this.#monitors = {};
+		this.#pollIntervalMs = Temporal.Duration.from(options.pollInterval ?? { seconds: 5 }).total("millisecond");
+		this.#delayedMessages = 0;
+		this.#processingKeys = /* @__PURE__ */ new Set();
+	}
+	enqueue(message, options) {
+		const delay = options?.delay == null ? 0 : Math.max(options.delay.total("millisecond"), 0);
+		if (delay > 0) {
+			this.#delayedMessages++;
+			setTimeout(() => {
+				this.#delayedMessages--;
+				this.#enqueueReady(message, options);
+			}, delay);
+			return Promise.resolve();
+		}
+		this.#enqueueReady(message, options);
+		return Promise.resolve();
+	}
+	#enqueueReady(message, options) {
+		const orderingKey = options?.orderingKey ?? null;
+		this.#messages.push({
+			message,
+			orderingKey
+		});
+		this.#notifyMonitors();
+	}
+	#notifyMonitors() {
+		for (const monitorId in this.#monitors) this.#monitors[monitorId]();
+	}
+	enqueueMany(messages, options) {
+		if (messages.length === 0) return Promise.resolve();
+		const delay = options?.delay == null ? 0 : Math.max(options.delay.total("millisecond"), 0);
+		if (delay > 0) {
+			const delayedCount = messages.length;
+			const deferredMessages = [...messages];
+			this.#delayedMessages += delayedCount;
+			setTimeout(() => {
+				this.#delayedMessages -= delayedCount;
+				this.#enqueueManyReady(deferredMessages, options);
+			}, delay);
+			return Promise.resolve();
+		}
+		this.#enqueueManyReady(messages, options);
+		return Promise.resolve();
+	}
+	#enqueueManyReady(messages, options) {
+		const orderingKey = options?.orderingKey ?? null;
+		for (const message of messages) this.#messages.push({
+			message,
+			orderingKey
+		});
+		this.#notifyMonitors();
+	}
+	async listen(handler, options = {}) {
+		const signal = options.signal;
+		while (signal == null || !signal.aborted) {
+			const idx = this.#messages.findIndex((m) => m.orderingKey == null || !this.#processingKeys.has(m.orderingKey));
+			if (idx >= 0) {
+				const { message, orderingKey } = this.#messages.splice(idx, 1)[0];
+				if (orderingKey != null) this.#processingKeys.add(orderingKey);
+				try {
+					await handler(message);
+				} finally {
+					if (orderingKey != null) this.#processingKeys.delete(orderingKey);
+				}
+			} else if (this.#messages.length === 0) await this.#wait(this.#pollIntervalMs, signal);
+			else await this.#wait(10, signal);
+		}
+	}
+	getDepth() {
+		const ready = this.#messages.length;
+		const delayed = this.#delayedMessages;
+		return Promise.resolve({
+			queued: ready + delayed,
+			ready,
+			delayed
+		});
+	}
+	#wait(ms, signal) {
+		let timer = null;
+		return Promise.any([new Promise((resolve) => {
+			signal?.addEventListener("abort", () => {
+				if (timer != null) clearTimeout(timer);
+				resolve();
+			}, { once: true });
+			const monitorId = crypto.randomUUID();
+			this.#monitors[monitorId] = () => {
+				delete this.#monitors[monitorId];
+				if (timer != null) clearTimeout(timer);
+				resolve();
+			};
+		}), new Promise((resolve) => timer = setTimeout(resolve, ms))]);
+	}
+};
+/**
+* A message queue that processes messages in parallel.  It takes another
+* {@link MessageQueue}, and processes messages in parallel up to a certain
+* number of workers.
+*
+* Actually, it's rather a decorator than a queue itself.
+*
+* Note that the workers do not run in truly parallel, in the sense that they
+* are not running in separate threads or processes.  They are running in the
+* same process, but are scheduled to run in parallel.  Hence, this is useful
+* for I/O-bound tasks, but not for CPU-bound tasks, which is okay for Fedify's
+* workloads.
+*
+* When using `ParallelMessageQueue`, the ordering guarantee is preserved
+* *only if* the underlying queue implementation delivers messages in a wrapper
+* format that includes the `__fedify_ordering_key__` property.  Currently,
+* only `DenoKvMessageQueue` and `WorkersMessageQueue` use this format.
+* For other queue implementations (e.g., `InProcessMessageQueue`,
+* `RedisMessageQueue`, `PostgresMessageQueue`, `SqliteMessageQueue`,
+* `AmqpMessageQueue`), the ordering key cannot be detected by
+* `ParallelMessageQueue`, so ordering guarantees are handled by those
+* implementations directly rather than at the `ParallelMessageQueue` level.
+*
+* Messages with the same ordering key will never be processed concurrently
+* by different workers, ensuring sequential processing within each key.
+* Messages with different ordering keys (or no ordering key) can still be
+* processed in parallel.
+*
+* @since 1.0.0
+*/
+var ParallelMessageQueue = class ParallelMessageQueue {
+	queue;
+	workers;
+	/**
+	* Inherits the native retry capability from the wrapped queue.
+	* @since 1.7.0
+	*/
+	nativeRetrial;
+	/**
+	* Inherits the native deduplication capability from the wrapped queue.
+	* @since 2.4.0
+	*/
+	nativeDeduplication;
+	getDepth;
+	/**
+	* Tracks which ordering keys are currently being processed to ensure
+	* sequential processing for messages with the same key.
+	*/
+	#processingKeys = /* @__PURE__ */ new Set();
+	/**
+	* Pending messages waiting for their ordering key to become available.
+	*/
+	#pendingMessages = [];
+	/**
+	* Constructs a new {@link ParallelMessageQueue} with the given queue and
+	* number of workers.
+	* @param queue The message queue to use under the hood.  Note that
+	*              {@link ParallelMessageQueue} cannot be nested.
+	* @param workers The number of workers to process messages in parallel.
+	* @throws {TypeError} If the given queue is an instance of
+	*                     {@link ParallelMessageQueue}.
+	*/
+	constructor(queue, workers) {
+		if (queue instanceof ParallelMessageQueue) throw new TypeError("Cannot nest ParallelMessageQueue.");
+		this.queue = queue;
+		this.workers = workers;
+		this.nativeRetrial = queue.nativeRetrial;
+		this.nativeDeduplication = queue.nativeDeduplication;
+		if (queue.getDepth != null) this.getDepth = () => queue.getDepth();
+	}
+	enqueue(message, options) {
+		return this.queue.enqueue(message, options);
+	}
+	async enqueueMany(messages, options) {
+		if (this.queue.enqueueMany == null) {
+			if (messages.length === 1) {
+				await this.queue.enqueue(messages[0], options);
+				return;
+			}
+			if (options?.deduplicationKey != null) throw new TypeError("Cannot enqueue a batch with a deduplicationKey: the wrapped queue does not implement enqueueMany, so ParallelMessageQueue would have to fan out to individual enqueue() calls that cannot share one deduplicationKey atomically.  Wrap a queue that implements enqueueMany instead.");
+			const errors = (await Promise.allSettled(messages.map((message) => this.queue.enqueue(message, options)))).filter((r) => r.status === "rejected").map((r) => r.reason);
+			if (errors.length > 1) throw new AggregateError(errors, "Failed to enqueue messages.");
+			else if (errors.length === 1) throw errors[0];
+			return;
+		}
+		await this.queue.enqueueMany(messages, options);
+	}
+	/**
+	* Extracts ordering key from a message if present.
+	*
+	* This method only works for queue implementations that deliver messages
+	* in the wrapper format with `__fedify_ordering_key__` property.  Currently,
+	* only `DenoKvMessageQueue` and `WorkersMessageQueue` use this format.
+	*
+	* For other queue implementations (`InProcessMessageQueue`,
+	* `RedisMessageQueue`, `PostgresMessageQueue`, `SqliteMessageQueue`,
+	* `AmqpMessageQueue`), messages are delivered as raw payloads without the
+	* wrapper, so the ordering key cannot be detected here.  Those
+	* implementations handle ordering guarantees internally.
+	*/
+	#extractOrderingKey(message) {
+		if (message != null && typeof message === "object") {
+			if ("__fedify_ordering_key__" in message) return message.__fedify_ordering_key__;
+		}
+	}
+	listen(handler, options = {}) {
+		const workers = /* @__PURE__ */ new Map();
+		return this.queue.listen(async (message) => {
+			while (workers.size >= this.workers) {
+				const consumedId = await Promise.any(workers.values());
+				workers.delete(consumedId);
+			}
+			const workerId = crypto.randomUUID();
+			const orderingKey = this.#extractOrderingKey(message);
+			if (orderingKey != null && this.#processingKeys.has(orderingKey)) await new Promise((resolve) => {
+				this.#pendingMessages.push({
+					message,
+					orderingKey,
+					resolve
+				});
+			});
+			if (orderingKey != null) this.#processingKeys.add(orderingKey);
+			const promise = this.#work(workerId, handler, message, orderingKey);
+			workers.set(workerId, promise);
+		}, options);
+	}
+	async #work(workerId, handler, message, orderingKey) {
+		await this.#sleep(0);
+		try {
+			await handler(message);
+		} finally {
+			if (orderingKey != null) {
+				this.#processingKeys.delete(orderingKey);
+				const pendingIdx = this.#pendingMessages.findIndex((p) => p.orderingKey === orderingKey);
+				if (pendingIdx >= 0) this.#pendingMessages.splice(pendingIdx, 1)[0].resolve();
+			}
+		}
+		return workerId;
+	}
+	#sleep(ms) {
+		return new Promise((resolve) => setTimeout(resolve, ms));
+	}
+};
+//#endregion
+//#region src/federation/tasks/enqueue.ts
+/**
+* The enqueue pipeline for custom background tasks.  `ContextImpl.enqueueTask`
+* and `ContextImpl.enqueueTaskMany` delegate to {@link enqueueTasks} so the
+* handle validation, deduplication planning, payload encoding, and queue
+* dispatch live in one cohesive place instead of one oversized method.
+*
+* @module
+*/
+/**
+* Validates the task handle, plans deduplication, encodes every payload, then
+* dispatches the resulting messages to the queue.  A single item flows through
+* the same pipeline as a batch, so {@link Context.enqueueTask} and
+* {@link Context.enqueueTaskMany} share one implementation.
+* @template TContextData The context data to pass to the {@link Context}.
+* @template TData The type of the task payload, inferred from the task's schema.
+* @param ctx The enqueueing dependencies assembled by `ContextImpl`.
+* @param task The handle returned by `defineTask()`.
+* @param items The payloads to enqueue, in order.
+* @param options The enqueue options governing delay, ordering, and dedup.
+* @internal
+*/
+const enqueueTasks = (ctx) => async function(task, items, options) {
+	const def = ctx.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 = ctx.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 plan = planDeduplication(ctx, queue, task.name, options, items.length);
+	const messages = await Promise.all(items.map(encodeTaskMessage(ctx.codec, ctx.origin, task, options)));
+	const claim = await claimDeduplication(ctx, plan, task.name);
+	if (!claim.proceed) return;
+	if (!ctx.federation.manuallyStartQueue) ctx.federation._startQueueInternal(ctx.data);
+	try {
+		await dispatch(queue, messages, {
+			delay: getDurationIfDefined(options.delay),
+			orderingKey: options.orderingKey,
+			deduplicationKey: claim.forwardedDeduplicationKey
+		});
+	} catch (error) {
+		if (claim.rollback != null) try {
+			await claim.rollback();
+		} catch (rollbackError) {
+			logger$1.warn("Failed to roll back the deduplication marker for task {taskName} after a failed enqueue; it will expire by TTL. {rollbackError}", {
+				taskName: task.name,
+				rollbackError
+			});
+		}
+		throw error;
+	}
+};
+const getDurationIfDefined = (item) => item == null ? void 0 : Temporal.Duration.from(item);
+/**
+* Decides how a `deduplicationKey` (if any) is honored: forwarded to a native
+* queue, claimed via `cas`, or—when neither is available—dropped or rejected
+* per the federation's `taskDeduplicationFallback`.  Throws the fail-fast
+* `TypeError`s so they precede the encode.
+*/
+function planDeduplication(ctx, queue, taskName, options, itemCount) {
+	if (options.deduplicationKey == null) return { kind: "none" };
+	const key = options.deduplicationKey;
+	const native = queue.nativeDeduplication === true;
+	const canCas = ctx.federation.kv.cas != null;
+	const canBatchAtomically = queue.enqueueMany != null && !(queue instanceof ParallelMessageQueue && queue.queue.enqueueMany == null);
+	if (itemCount > 1 && !canBatchAtomically && (native || canCas)) throw new TypeError(`Task ${JSON.stringify(taskName)} was enqueued as a batch with a deduplicationKey, but its message queue does not implement enqueueMany; a multi-item batch cannot be deduplicated atomically without it.  Implement enqueueMany on the queue, or enqueue the tasks individually with enqueueTask().`);
+	if (native) return {
+		kind: "native",
+		key
+	};
+	if (canCas) return {
+		kind: "cas",
+		key
+	};
+	if (ctx.federation.taskDeduplicationFallback === "closed") throw new TypeError("deduplicationKey was set but the message queue does not declare nativeDeduplication and the key-value store exposes no conditional write (cas); set taskDeduplicationFallback to \"open\" to proceed without deduplication, or use a backend that supports it.");
+	return {
+		kind: "open",
+		key
+	};
+}
+/**
+* Executes the planned deduplication once the payloads are encoded.  A native
+* plan forwards its key to the queue; a `cas` plan claims the marker and stops
+* the enqueue when it loses the race; an `open` plan logs and proceeds.
+* @returns Whether to proceed, and the key (if any) to forward to the queue.
+*/
+async function claimDeduplication(ctx, plan, taskName) {
+	switch (plan.kind) {
+		case "native": return {
+			proceed: true,
+			forwardedDeduplicationKey: plan.key
+		};
+		case "cas": {
+			const cacheKey = [...ctx.federation.kvPrefixes.taskDeduplication, plan.key];
+			const token = crypto.randomUUID();
+			if (!await ctx.federation.kv.cas(cacheKey, void 0, token, { ttl: ctx.federation.taskDeduplicationTtl })) return { proceed: false };
+			return {
+				proceed: true,
+				rollback: async () => {
+					await ctx.federation.kv.cas(cacheKey, token, void 0);
+				}
+			};
+		}
+		case "open": logger$1.debug("deduplicationKey {deduplicationKey} for task {taskName} ignored: the message queue declares no nativeDeduplication and the key-value store has no cas; proceeding (taskDeduplicationFallback is \"open\").", {
+			deduplicationKey: plan.key,
+			taskName
+		});
+		case "none": return { proceed: true };
+		default: throw new TypeError(`Unknown deduplication plan: ${JSON.stringify(plan)}`);
+	}
+}
+/**
+* Sends the encoded messages to the queue, picking the bulk path when the
+* queue implements `enqueueMany` and otherwise fanning out parallel single
+* enqueues.  The fan-out drops `deduplicationKey`, which is only ever set for a
+* native plan that the bulk paths already cover.
+*/
+async function dispatch(queue, messages, options) {
+	if (messages.length === 1) await queue.enqueue(messages[0], options);
+	else if (queue.enqueueMany != null) await queue.enqueueMany(messages, options);
+	else {
+		const fanoutOptions = {
+			delay: options.delay,
+			orderingKey: options.orderingKey
+		};
+		await Promise.all(messages.map((m) => queue.enqueue(m, fanoutOptions)));
+	}
+}
+/**
+* Builds the per-payload encoder: validates and serializes the payload, then
+* stamps the message envelope with a fresh id, the context's origin, and the
+* active trace context.  Curried so the batch encode reuses one bound encoder.
+*/
+const encodeTaskMessage = (codec, origin, task, options) => async (data) => {
+	const encoded = await codec.encode(task.schema, data);
+	const carrier = {};
+	propagation.inject(context.active(), carrier);
+	return {
+		type: "task",
+		id: crypto.randomUUID(),
+		baseUrl: origin,
+		taskName: task.name,
+		data: encoded,
+		started: Temporal.Now.instant().toString(),
+		attempt: 0,
+		orderingKey: options.orderingKey,
+		traceContext: carrier
+	};
+};
+const logger$1 = getLogger([
+	"fedify",
+	"federation",
+	"task"
+]);
+//#endregion
 //#region src/federation/webfinger.ts
 const logger = getLogger([
 	"fedify",
@@ -3885,9 +4429,8 @@ var FederationImpl = class extends FederationBuilderImpl {
 	inboxQueue;
 	outboxQueue;
 	fanoutQueue;
-	inboxQueueStarted;
-	outboxQueueStarted;
-	fanoutQueueStarted;
+	taskQueue;
+	startedQueues;
 	manuallyStartQueue;
 	origin;
 	documentLoaderFactory;
@@ -3901,6 +4444,10 @@ var FederationImpl = class extends FederationBuilderImpl {
 	skipSignatureVerification;
 	outboxRetryPolicy;
 	inboxRetryPolicy;
+	taskRetryPolicy;
+	taskQueueResolution;
+	taskDeduplicationTtl;
+	taskDeduplicationFallback;
 	circuitBreaker;
 	activityTransformers;
 	_tracerProvider;
@@ -3940,20 +4487,24 @@ var FederationImpl = class extends FederationBuilderImpl {
 			httpMessageSignaturesSpec: ["_fedify", "httpMessageSignaturesSpec"],
 			acceptSignatureNonce: ["_fedify", "acceptSignatureNonce"],
 			circuitBreaker: ["_fedify", "circuit"],
+			taskDeduplication: ["_fedify", "taskDeduplication"],
 			...options.kvPrefixes ?? {}
 		};
 		if (options.queue == null) {
 			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({
@@ -3974,9 +4525,7 @@ var FederationImpl = class extends FederationBuilderImpl {
 				]).warn("The configured key-value store does not support CAS; outbound delivery circuit breaker updates may race under concurrent workers.");
 			}
 		}
-		this.inboxQueueStarted = false;
-		this.outboxQueueStarted = false;
-		this.fanoutQueueStarted = false;
+		this.startedQueues = /* @__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)}`);
@@ -4058,6 +4607,10 @@ 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.taskDeduplicationTtl = Temporal.Duration.from(options.taskDeduplicationTtl ?? { hours: 1 });
+		this.taskDeduplicationFallback = options.taskDeduplicationFallback ?? "open";
 		this.activityTransformers = options.activityTransformers ?? getDefaultActivityTransformers();
 		this._tracerProvider = options.tracerProvider;
 		if (benchmarkMode) {
@@ -4106,28 +4659,33 @@ var FederationImpl = class extends FederationBuilderImpl {
 	_getTracer() {
 		return this.tracerProvider.getTracer(name, 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 taskQueue = this.taskQueue ?? (this.taskQueueResolution === "fallback" ? this.outboxQueue : void 0);
+		const customQueues = this.taskDefinitions.values().map((def) => ["task", def.queue]);
+		const targets = [
+			["inbox", this.inboxQueue],
+			["outbox", this.outboxQueue],
+			["fanout", this.fanoutQueue],
+			["task", taskQueue],
+			...customQueues
+		];
 		const logger = getLogger([
 			"fedify",
 			"federation",
 			"queue"
 		]);
 		const promises = [];
-		if (this.inboxQueue != null && (queue == null || queue === "inbox") && !this.inboxQueueStarted) {
-			logger.debug("Starting an inbox task worker.");
-			this.inboxQueueStarted = true;
-			promises.push(this.inboxQueue.listen((msg) => this.processQueuedTask(ctxData, msg), { signal }));
-		}
-		if (this.outboxQueue != null && this.outboxQueue !== this.inboxQueue && (queue == null || queue === "outbox") && !this.outboxQueueStarted) {
-			logger.debug("Starting an outbox task worker.");
-			this.outboxQueueStarted = true;
-			promises.push(this.outboxQueue.listen((msg) => this.processQueuedTask(ctxData, msg), { signal }));
-		}
-		if (this.fanoutQueue != null && this.fanoutQueue !== this.inboxQueue && this.fanoutQueue !== this.outboxQueue && (queue == null || queue === "fanout") && !this.fanoutQueueStarted) {
-			logger.debug("Starting a fanout task worker.");
-			this.fanoutQueueStarted = true;
-			promises.push(this.fanoutQueue.listen((msg) => this.processQueuedTask(ctxData, msg), { signal }));
+		for (const [role, target] of targets) {
+			if (target == null || !(queue == null || queue === role)) continue;
+			if (this.startedQueues.has(target)) continue;
+			this.startedQueues.add(target);
+			logger.debug("Starting a {role} queue worker.", { role });
+			promises.push(target.listen((msg) => this.processQueuedTask(ctxData, msg), { signal }));
 		}
 		await Promise.all(promises);
 	}
@@ -4250,7 +4808,7 @@ var FederationImpl = class extends FederationBuilderImpl {
 						}
 					});
 				});
-			}
+			} else if (message.type === "task") await this.#listenTaskMessage(contextData, message);
 		});
 	}
 	async #listenFanoutMessage(data, message) {
@@ -4814,6 +5372,77 @@ var FederationImpl = class extends FederationBuilderImpl {
 			listenerSpan.end();
 		});
 	}
+	async #listenTaskMessage(contextData, message) {
+		const logger = 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);
 	}
@@ -5398,6 +6027,7 @@ var ContextImpl = class ContextImpl {
 	documentLoader;
 	contextLoader;
 	invokedFromActorKeyPairsDispatcher;
+	#codec;
 	constructor({ url, federation, data, documentLoader, contextLoader, invokedFromActorKeyPairsDispatcher }) {
 		this.url = url;
 		this.federation = federation;
@@ -5406,6 +6036,18 @@ 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);
+	}
+	get #enqueueTasks() {
+		return enqueueTasks(this);
+	}
 	clone(data) {
 		return new ContextImpl({
 			url: this.url,
@@ -5724,6 +6366,12 @@ 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);
+	}
 	sendActivity(sender, recipients, activity, options = {}) {
 		return this.tracerProvider.getTracer(name, version).startActiveSpan(this.federation.outboxQueue == null || options.immediate ? "activitypub.outbox" : "activitypub.fanout", {
 			kind: this.federation.outboxQueue == null || options.immediate ? SpanKind.CLIENT : SpanKind.PRODUCER,
@@ -6434,4 +7082,4 @@ function getRequestId(request) {
 	return `req_${Date.now().toString(36)}${Math.random().toString(36).slice(2, 8)}`;
 }
 //#endregion
-export { SendActivityError as a, buildCollectionSynchronizationHeader as c, normalizeCircuitBreakerOptions as d, parseCircuitBreakerKvState as f, createExponentialBackoffPolicy as i, digest as l, middleware_exports as n, respondWithObject as o, createFederationBuilder as p, handleWebFinger as r, respondWithObjectIfAcceptable as s, createFederation as t, CircuitBreaker as u };
+export { ParallelMessageQueue as a, respondWithObject as c, digest as d, CircuitBreaker as f, createFederationBuilder as h, InProcessMessageQueue as i, respondWithObjectIfAcceptable as l, parseCircuitBreakerKvState as m, middleware_exports as n, createExponentialBackoffPolicy as o, normalizeCircuitBreakerOptions as p, handleWebFinger as r, SendActivityError as s, createFederation as t, buildCollectionSynchronizationHeader as u };