@fedify/netlify 2.4.0-dev.0

package/dist/mod.d.cts

@@ -0,0 +1,177 @@
+/// <reference lib="esnext.temporal" />
+import { Federation, KvStore, Message, MessageQueue, MessageQueueEnqueueOptions, MessageQueueListenOptions } from "@fedify/fedify/federation";
+import { AsyncWorkloadEvent, CustomAsyncWorkloadEvent, asyncWorkloadFn } from "@netlify/async-workloads";
+
+//#region src/types.d.ts
+/**
+* The subset of Netlify's `AsyncWorkloadsClient` used by this package.
+*
+* The real `AsyncWorkloadsClient` satisfies this interface.  The narrower
+* interface also makes it possible to supply a test double.
+*
+* @since 2.4.0
+*/
+interface NetlifyAsyncWorkloadsClient {
+  send(eventName: string, options?: {
+    readonly data?: NetlifyQueueEventData;
+    readonly delayUntil?: number | string;
+    readonly priority?: number;
+  }): Promise<{
+    readonly sendStatus: "succeeded" | "failed";
+    readonly eventId: string;
+  }>;
+}
+//#endregion
+//#region src/mq.d.ts
+/**
+* A Fedify queue message wrapped for Netlify Async Workloads.
+*
+* @since 2.4.0
+*/
+interface NetlifyQueueEventData {
+  readonly message: Message;
+  readonly orderingKey?: string;
+  readonly orderingSequence?: number;
+}
+/**
+* Options for {@link NetlifyMessageQueue}.
+*
+* @since 2.4.0
+*/
+interface NetlifyMessageQueueOptions {
+  /** A Netlify Async Workloads client. */
+  readonly client: NetlifyAsyncWorkloadsClient;
+  /**
+  * The Async Workloads event name.  It must match the event configured for
+  * the workload function.  `"fedify:queue"` by default.
+  * @default `"fedify:queue"`
+  */
+  readonly eventName?: string;
+  /**
+  * A CAS-capable key–value store used to serialize messages that have the
+  * same ordering key.  Required when an `orderingKey` is enqueued.
+  */
+  readonly orderingKv?: KvStore;
+  /**
+  * The durable sleep interval used while an earlier ordered message is still
+  * running.  Five seconds by default.
+  * @default `{ seconds: 5 }`
+  */
+  readonly orderingRetryDelay?: Temporal.Duration | Temporal.DurationLike;
+}
+/**
+* An error raised when an event send is not acknowledged.
+*
+* For an ordered event, {@link orderingSequence} remains reserved because the
+* router may already have accepted the event.  It can be passed to
+* {@link NetlifyMessageQueue.skipOrderingSequence} only after an operator has
+* confirmed that the event cannot still be delivered.
+*
+* @since 2.4.0
+*/
+declare class NetlifyMessageQueueSendError extends Error {
+  readonly eventName: string;
+  readonly eventId?: string;
+  readonly orderingKey?: string;
+  readonly orderingSequence?: number;
+  /** Creates a queue send error. @internal */
+  constructor(options: {
+    readonly eventName: string;
+    readonly eventId?: string;
+    readonly orderingKey?: string;
+    readonly orderingSequence?: number;
+    readonly cause?: unknown;
+  });
+}
+/**
+* A message queue that publishes Fedify jobs to Netlify Async Workloads.
+*
+* Async Workloads invokes a separate function for each event, so this queue
+* cannot consume messages through {@link listen}.  Use
+* {@link createNetlifyQueueHandler} in a Netlify Function and set Fedify's
+* `manuallyStartQueue` option to `true`.
+*
+* @since 2.4.0
+*/
+declare class NetlifyMessageQueue implements MessageQueue {
+  #private;
+  readonly eventName: string;
+  readonly nativeRetrial = true;
+  readonly nativeDeduplication = false;
+  /** Creates a Netlify Async Workloads-backed message queue. */
+  constructor(options: NetlifyMessageQueueOptions);
+  /** {@inheritDoc MessageQueue.enqueue} */
+  enqueue(message: Message, options?: MessageQueueEnqueueOptions): Promise<void>;
+  /**
+  * Skips a reserved ordering sequence that can no longer be processed.
+  *
+  * Use this only after confirming that the corresponding Async Workloads
+  * event is permanently dead-lettered or was never accepted.  Skipping an
+  * event that can still be delivered causes that event to be ignored.
+  *
+  * @param orderingKey The ordering key of the blocked sequence.
+  * @param sequence The sequence to skip.
+  */
+  skipOrderingSequence(orderingKey: string, sequence: number): Promise<void>;
+  /** {@inheritDoc MessageQueue.enqueueMany} */
+  enqueueMany(messages: readonly Message[], options?: MessageQueueEnqueueOptions): Promise<void>;
+  /**
+  * This operation is unsupported because Netlify invokes workload functions
+  * for queued events.
+  */
+  listen(_handler: (message: Message) => Promise<void> | void, _options?: MessageQueueListenOptions): Promise<void>;
+}
+//#endregion
+//#region src/handler.d.ts
+/**
+* The Async Workloads event emitted by {@link NetlifyMessageQueue}.
+*
+* @since 2.4.0
+*/
+interface NetlifyQueueEvent extends CustomAsyncWorkloadEvent {
+  readonly eventName: string;
+  readonly eventData: NetlifyQueueEventData;
+}
+/**
+* Options for {@link createNetlifyQueueHandler}.
+*
+* @typeParam TContextData The context data passed to Fedify dispatchers.
+* @since 2.4.0
+*/
+interface NetlifyQueueHandlerOptions<TContextData> {
+  /** The queue that receives events for this handler. */
+  readonly queue: NetlifyMessageQueue;
+  /**
+  * Creates the federation for a workload invocation.  The factory is called
+  * once per event so resources do not have to survive between invocations.
+  */
+  readonly federation: (event: AsyncWorkloadEvent<NetlifyQueueEvent>) => Federation<TContextData> | Promise<Federation<TContextData>>;
+  /**
+  * Creates the context data passed to `Federation.processQueuedTask()`.
+  * When omitted, `undefined` is used.
+  */
+  readonly contextData?: (event: AsyncWorkloadEvent<NetlifyQueueEvent>) => TContextData | Promise<TContextData>;
+  /**
+  * The workload's configured retry count.  This must equal
+  * `asyncWorkloadConfig.maxRetries` so a permanently failed ordered event can
+  * release its sequence.  Four by default, matching Async Workloads.
+  * @default 4
+  */
+  readonly maxRetries?: number;
+}
+type WorkloadFunction = ReturnType<typeof asyncWorkloadFn<NetlifyQueueEvent>>;
+/**
+* Creates a Netlify Async Workloads function that processes Fedify jobs.
+*
+* Export the returned function as the default export of a file under
+* *netlify/functions/*.  The workload's `asyncWorkloadConfig.events` must
+* contain the associated queue's {@link NetlifyMessageQueue.eventName}.
+*
+* @typeParam TContextData The context data passed to Fedify dispatchers.
+* @param options The workload handler options.
+* @returns A function produced by Netlify's `asyncWorkloadFn()`.
+* @since 2.4.0
+*/
+declare function createNetlifyQueueHandler<TContextData>(options: NetlifyQueueHandlerOptions<TContextData>): WorkloadFunction;
+//#endregion
+export { type NetlifyAsyncWorkloadsClient, NetlifyMessageQueue, type NetlifyMessageQueueOptions, NetlifyMessageQueueSendError, type NetlifyQueueEvent, type NetlifyQueueEventData, type NetlifyQueueHandlerOptions, createNetlifyQueueHandler };

package/dist/mod.d.ts

@@ -0,0 +1,177 @@
+/// <reference lib="esnext.temporal" />
+import { AsyncWorkloadEvent, CustomAsyncWorkloadEvent, asyncWorkloadFn } from "@netlify/async-workloads";
+import { Federation, KvStore, Message, MessageQueue, MessageQueueEnqueueOptions, MessageQueueListenOptions } from "@fedify/fedify/federation";
+
+//#region src/types.d.ts
+/**
+* The subset of Netlify's `AsyncWorkloadsClient` used by this package.
+*
+* The real `AsyncWorkloadsClient` satisfies this interface.  The narrower
+* interface also makes it possible to supply a test double.
+*
+* @since 2.4.0
+*/
+interface NetlifyAsyncWorkloadsClient {
+  send(eventName: string, options?: {
+    readonly data?: NetlifyQueueEventData;
+    readonly delayUntil?: number | string;
+    readonly priority?: number;
+  }): Promise<{
+    readonly sendStatus: "succeeded" | "failed";
+    readonly eventId: string;
+  }>;
+}
+//#endregion
+//#region src/mq.d.ts
+/**
+* A Fedify queue message wrapped for Netlify Async Workloads.
+*
+* @since 2.4.0
+*/
+interface NetlifyQueueEventData {
+  readonly message: Message;
+  readonly orderingKey?: string;
+  readonly orderingSequence?: number;
+}
+/**
+* Options for {@link NetlifyMessageQueue}.
+*
+* @since 2.4.0
+*/
+interface NetlifyMessageQueueOptions {
+  /** A Netlify Async Workloads client. */
+  readonly client: NetlifyAsyncWorkloadsClient;
+  /**
+  * The Async Workloads event name.  It must match the event configured for
+  * the workload function.  `"fedify:queue"` by default.
+  * @default `"fedify:queue"`
+  */
+  readonly eventName?: string;
+  /**
+  * A CAS-capable key–value store used to serialize messages that have the
+  * same ordering key.  Required when an `orderingKey` is enqueued.
+  */
+  readonly orderingKv?: KvStore;
+  /**
+  * The durable sleep interval used while an earlier ordered message is still
+  * running.  Five seconds by default.
+  * @default `{ seconds: 5 }`
+  */
+  readonly orderingRetryDelay?: Temporal.Duration | Temporal.DurationLike;
+}
+/**
+* An error raised when an event send is not acknowledged.
+*
+* For an ordered event, {@link orderingSequence} remains reserved because the
+* router may already have accepted the event.  It can be passed to
+* {@link NetlifyMessageQueue.skipOrderingSequence} only after an operator has
+* confirmed that the event cannot still be delivered.
+*
+* @since 2.4.0
+*/
+declare class NetlifyMessageQueueSendError extends Error {
+  readonly eventName: string;
+  readonly eventId?: string;
+  readonly orderingKey?: string;
+  readonly orderingSequence?: number;
+  /** Creates a queue send error. @internal */
+  constructor(options: {
+    readonly eventName: string;
+    readonly eventId?: string;
+    readonly orderingKey?: string;
+    readonly orderingSequence?: number;
+    readonly cause?: unknown;
+  });
+}
+/**
+* A message queue that publishes Fedify jobs to Netlify Async Workloads.
+*
+* Async Workloads invokes a separate function for each event, so this queue
+* cannot consume messages through {@link listen}.  Use
+* {@link createNetlifyQueueHandler} in a Netlify Function and set Fedify's
+* `manuallyStartQueue` option to `true`.
+*
+* @since 2.4.0
+*/
+declare class NetlifyMessageQueue implements MessageQueue {
+  #private;
+  readonly eventName: string;
+  readonly nativeRetrial = true;
+  readonly nativeDeduplication = false;
+  /** Creates a Netlify Async Workloads-backed message queue. */
+  constructor(options: NetlifyMessageQueueOptions);
+  /** {@inheritDoc MessageQueue.enqueue} */
+  enqueue(message: Message, options?: MessageQueueEnqueueOptions): Promise<void>;
+  /**
+  * Skips a reserved ordering sequence that can no longer be processed.
+  *
+  * Use this only after confirming that the corresponding Async Workloads
+  * event is permanently dead-lettered or was never accepted.  Skipping an
+  * event that can still be delivered causes that event to be ignored.
+  *
+  * @param orderingKey The ordering key of the blocked sequence.
+  * @param sequence The sequence to skip.
+  */
+  skipOrderingSequence(orderingKey: string, sequence: number): Promise<void>;
+  /** {@inheritDoc MessageQueue.enqueueMany} */
+  enqueueMany(messages: readonly Message[], options?: MessageQueueEnqueueOptions): Promise<void>;
+  /**
+  * This operation is unsupported because Netlify invokes workload functions
+  * for queued events.
+  */
+  listen(_handler: (message: Message) => Promise<void> | void, _options?: MessageQueueListenOptions): Promise<void>;
+}
+//#endregion
+//#region src/handler.d.ts
+/**
+* The Async Workloads event emitted by {@link NetlifyMessageQueue}.
+*
+* @since 2.4.0
+*/
+interface NetlifyQueueEvent extends CustomAsyncWorkloadEvent {
+  readonly eventName: string;
+  readonly eventData: NetlifyQueueEventData;
+}
+/**
+* Options for {@link createNetlifyQueueHandler}.
+*
+* @typeParam TContextData The context data passed to Fedify dispatchers.
+* @since 2.4.0
+*/
+interface NetlifyQueueHandlerOptions<TContextData> {
+  /** The queue that receives events for this handler. */
+  readonly queue: NetlifyMessageQueue;
+  /**
+  * Creates the federation for a workload invocation.  The factory is called
+  * once per event so resources do not have to survive between invocations.
+  */
+  readonly federation: (event: AsyncWorkloadEvent<NetlifyQueueEvent>) => Federation<TContextData> | Promise<Federation<TContextData>>;
+  /**
+  * Creates the context data passed to `Federation.processQueuedTask()`.
+  * When omitted, `undefined` is used.
+  */
+  readonly contextData?: (event: AsyncWorkloadEvent<NetlifyQueueEvent>) => TContextData | Promise<TContextData>;
+  /**
+  * The workload's configured retry count.  This must equal
+  * `asyncWorkloadConfig.maxRetries` so a permanently failed ordered event can
+  * release its sequence.  Four by default, matching Async Workloads.
+  * @default 4
+  */
+  readonly maxRetries?: number;
+}
+type WorkloadFunction = ReturnType<typeof asyncWorkloadFn<NetlifyQueueEvent>>;
+/**
+* Creates a Netlify Async Workloads function that processes Fedify jobs.
+*
+* Export the returned function as the default export of a file under
+* *netlify/functions/*.  The workload's `asyncWorkloadConfig.events` must
+* contain the associated queue's {@link NetlifyMessageQueue.eventName}.
+*
+* @typeParam TContextData The context data passed to Fedify dispatchers.
+* @param options The workload handler options.
+* @returns A function produced by Netlify's `asyncWorkloadFn()`.
+* @since 2.4.0
+*/
+declare function createNetlifyQueueHandler<TContextData>(options: NetlifyQueueHandlerOptions<TContextData>): WorkloadFunction;
+//#endregion
+export { type NetlifyAsyncWorkloadsClient, NetlifyMessageQueue, type NetlifyMessageQueueOptions, NetlifyMessageQueueSendError, type NetlifyQueueEvent, type NetlifyQueueEventData, type NetlifyQueueHandlerOptions, createNetlifyQueueHandler };

package/dist/mod.js

@@ -0,0 +1,297 @@
+import { Temporal } from "temporal-polyfill";
+import { ErrorDoNotRetry, asyncWorkloadFn } from "@netlify/async-workloads";
+//#region src/mq.ts
+const defaultEventName = "fedify:queue";
+const defaultOrderingRetryDelay = Temporal.Duration.from({ seconds: 5 });
+/**
+* An error raised when an event send is not acknowledged.
+*
+* For an ordered event, {@link orderingSequence} remains reserved because the
+* router may already have accepted the event.  It can be passed to
+* {@link NetlifyMessageQueue.skipOrderingSequence} only after an operator has
+* confirmed that the event cannot still be delivered.
+*
+* @since 2.4.0
+*/
+var NetlifyMessageQueueSendError = class extends Error {
+	eventName;
+	eventId;
+	orderingKey;
+	orderingSequence;
+	/** Creates a queue send error. @internal */
+	constructor(options) {
+		const ordering = options.orderingKey == null || options.orderingSequence == null ? "" : `; ordering key ${options.orderingKey}, sequence ` + options.orderingSequence;
+		super(`Failed to send Netlify Async Workloads event ${options.eventId ?? "without an acknowledgement"} for ${options.eventName}${ordering}.`, { cause: options.cause });
+		this.name = "NetlifyMessageQueueSendError";
+		this.eventName = options.eventName;
+		this.eventId = options.eventId;
+		this.orderingKey = options.orderingKey;
+		this.orderingSequence = options.orderingSequence;
+	}
+};
+const orderingOptions = /* @__PURE__ */ new WeakMap();
+function duration(value, defaultValue, name) {
+	const result = value == null ? defaultValue : Temporal.Duration.from(value);
+	const milliseconds = result.total("milliseconds");
+	if (!Number.isFinite(milliseconds) || milliseconds <= 0) throw new RangeError(`${name} must be a positive finite duration.`);
+	return result;
+}
+function requireCas(kv) {
+	if (kv == null || kv.cas == null) throw new TypeError("Messages with an orderingKey require orderingKv with a cas() method.");
+	return kv;
+}
+/**
+* Gets the queue's ordering configuration for the workload handler.
+* @internal
+*/
+function getOrderingOptions(queue) {
+	const options = orderingOptions.get(queue);
+	if (options == null) throw new TypeError("Invalid NetlifyMessageQueue.");
+	return options;
+}
+/**
+* Ensures that a queue can accept the supplied ordering key.
+* @internal
+*/
+function getOrderingKv(queue, orderingKey) {
+	if (orderingKey.length < 1) throw new TypeError("orderingKey must not be empty.");
+	return requireCas(getOrderingOptions(queue).kv);
+}
+function getOrderingStateKey(orderingKey) {
+	return [
+		"fedify",
+		"netlify",
+		"ordering",
+		orderingKey
+	];
+}
+function compactOrderingState(state) {
+	const cancelled = new Set(state.cancelledSequences);
+	let completedSequence = state.completedSequence;
+	while (cancelled.delete(completedSequence + 1)) completedSequence++;
+	return {
+		nextSequence: state.nextSequence,
+		completedSequence,
+		cancelledSequences: [...cancelled].sort((a, b) => a - b)
+	};
+}
+function validateOrderingState(value) {
+	if (value === void 0) return {
+		nextSequence: 1,
+		completedSequence: 0,
+		cancelledSequences: []
+	};
+	if (typeof value !== "object" || value == null) throw new TypeError("Invalid Netlify queue ordering state.");
+	const nextSequence = "nextSequence" in value ? value.nextSequence : void 0;
+	const completedSequence = "completedSequence" in value ? value.completedSequence : void 0;
+	const cancelledSequences = "cancelledSequences" in value ? value.cancelledSequences : void 0;
+	if (typeof nextSequence !== "number" || !Number.isSafeInteger(nextSequence) || nextSequence < 1 || typeof completedSequence !== "number" || !Number.isSafeInteger(completedSequence) || completedSequence < 0 || !Array.isArray(cancelledSequences) || !cancelledSequences.every((sequence) => Number.isSafeInteger(sequence) && sequence > 0)) throw new TypeError("Invalid Netlify queue ordering state.");
+	return {
+		nextSequence,
+		completedSequence,
+		cancelledSequences
+	};
+}
+async function updateOrderingState(queue, orderingKey, update) {
+	const kv = getOrderingKv(queue, orderingKey);
+	const key = getOrderingStateKey(orderingKey);
+	while (true) {
+		const stored = await kv.get(key);
+		const [updated, result] = update(validateOrderingState(stored));
+		if (await kv.cas(key, stored, updated)) return result;
+	}
+}
+async function reserveOrderingSequence(queue, orderingKey) {
+	return await updateOrderingState(queue, orderingKey, (state) => [{
+		...state,
+		nextSequence: state.nextSequence + 1
+	}, state.nextSequence]);
+}
+async function cancelOrderingSequence(queue, orderingKey, sequence) {
+	await updateOrderingState(queue, orderingKey, (state) => {
+		if (sequence >= state.nextSequence) throw new RangeError(`Netlify queue ordering sequence ${sequence} has not been reserved.`);
+		if (sequence <= state.completedSequence) return [state, void 0];
+		return [compactOrderingState({
+			...state,
+			cancelledSequences: [...state.cancelledSequences, sequence]
+		}), void 0];
+	});
+}
+/** Gets the last completed sequence for an ordering key. @internal */
+async function getCompletedOrderingSequence(queue, orderingKey) {
+	return validateOrderingState(await getOrderingKv(queue, orderingKey).get(getOrderingStateKey(orderingKey))).completedSequence;
+}
+/** Marks an ordered message as completed. @internal */
+async function completeOrderingSequence(queue, orderingKey, sequence) {
+	await updateOrderingState(queue, orderingKey, (state) => {
+		if (state.completedSequence >= sequence) return [state, void 0];
+		if (state.completedSequence !== sequence - 1) throw new Error(`Cannot complete Netlify queue ordering sequence ${sequence} after ${state.completedSequence}.`);
+		return [compactOrderingState({
+			...state,
+			completedSequence: sequence
+		}), void 0];
+	});
+}
+/**
+* A message queue that publishes Fedify jobs to Netlify Async Workloads.
+*
+* Async Workloads invokes a separate function for each event, so this queue
+* cannot consume messages through {@link listen}.  Use
+* {@link createNetlifyQueueHandler} in a Netlify Function and set Fedify's
+* `manuallyStartQueue` option to `true`.
+*
+* @since 2.4.0
+*/
+var NetlifyMessageQueue = class {
+	eventName;
+	nativeRetrial = true;
+	nativeDeduplication = false;
+	#client;
+	/** Creates a Netlify Async Workloads-backed message queue. */
+	constructor(options) {
+		const eventName = options.eventName ?? defaultEventName;
+		if (eventName.trim().length < 1) throw new TypeError("eventName must not be empty.");
+		this.eventName = eventName;
+		this.#client = options.client;
+		orderingOptions.set(this, {
+			kv: options.orderingKv,
+			retryDelay: duration(options.orderingRetryDelay, defaultOrderingRetryDelay, "orderingRetryDelay")
+		});
+	}
+	/** {@inheritDoc MessageQueue.enqueue} */
+	async enqueue(message, options) {
+		const delay = options?.delay?.total("milliseconds");
+		if (delay != null && (!Number.isFinite(delay) || delay < 0)) throw new RangeError("delay must be a non-negative finite duration.");
+		const orderingKey = options?.orderingKey;
+		const orderingSequence = orderingKey == null ? void 0 : await reserveOrderingSequence(this, orderingKey);
+		let result;
+		try {
+			result = await this.#client.send(this.eventName, {
+				data: {
+					message,
+					orderingKey,
+					orderingSequence
+				},
+				...delay == null ? {} : { delayUntil: Date.now() + delay }
+			});
+		} catch (cause) {
+			throw new NetlifyMessageQueueSendError({
+				eventName: this.eventName,
+				orderingKey,
+				orderingSequence,
+				cause
+			});
+		}
+		if (result.sendStatus !== "succeeded") throw new NetlifyMessageQueueSendError({
+			eventName: this.eventName,
+			eventId: result.eventId,
+			orderingKey,
+			orderingSequence
+		});
+	}
+	/**
+	* Skips a reserved ordering sequence that can no longer be processed.
+	*
+	* Use this only after confirming that the corresponding Async Workloads
+	* event is permanently dead-lettered or was never accepted.  Skipping an
+	* event that can still be delivered causes that event to be ignored.
+	*
+	* @param orderingKey The ordering key of the blocked sequence.
+	* @param sequence The sequence to skip.
+	*/
+	async skipOrderingSequence(orderingKey, sequence) {
+		if (!Number.isSafeInteger(sequence) || sequence < 1) throw new RangeError("sequence must be a positive safe integer.");
+		await cancelOrderingSequence(this, orderingKey, sequence);
+	}
+	/** {@inheritDoc MessageQueue.enqueueMany} */
+	async enqueueMany(messages, options) {
+		if (options?.orderingKey == null) await Promise.all(messages.map((message) => this.enqueue(message, options)));
+		else for (const message of messages) await this.enqueue(message, options);
+	}
+	/**
+	* This operation is unsupported because Netlify invokes workload functions
+	* for queued events.
+	*/
+	listen(_handler, _options) {
+		throw new TypeError("NetlifyMessageQueue.listen() is unsupported; use createNetlifyQueueHandler() and set manuallyStartQueue to true.");
+	}
+};
+//#endregion
+//#region src/handler.ts
+const messageTypes = new Set([
+	"fanout",
+	"inbox",
+	"outbox",
+	"task"
+]);
+function isObject(value) {
+	return typeof value === "object" && value != null && !Array.isArray(value);
+}
+function decodeEventData(value) {
+	if (!isObject(value) || !isObject(value.message)) throw new ErrorDoNotRetry("Invalid Fedify queue event envelope.");
+	if (typeof value.message.type !== "string" || !messageTypes.has(value.message.type)) throw new ErrorDoNotRetry("Invalid Fedify queue message type.");
+	if (value.orderingKey !== void 0 && (typeof value.orderingKey !== "string" || value.orderingKey.length < 1)) throw new ErrorDoNotRetry("Invalid Fedify queue ordering key.");
+	const orderingSequence = value.orderingSequence;
+	if (orderingSequence !== void 0 && (typeof orderingSequence !== "number" || !Number.isSafeInteger(orderingSequence) || orderingSequence < 1)) throw new ErrorDoNotRetry("Invalid Fedify queue ordering sequence.");
+	if (value.orderingKey === void 0 !== (orderingSequence === void 0)) throw new ErrorDoNotRetry("Incomplete Fedify queue ordering metadata.");
+	return {
+		message: value.message,
+		orderingKey: value.orderingKey,
+		orderingSequence
+	};
+}
+/**
+* Creates the event callback that processes one Netlify queue event.
+* @internal
+*/
+function createNetlifyQueueEventHandler(options) {
+	const maxRetries = options.maxRetries ?? 4;
+	if (!Number.isSafeInteger(maxRetries) || maxRetries < 0) throw new RangeError("maxRetries must be a non-negative safe integer.");
+	return async (event) => {
+		const data = decodeEventData(event.eventData);
+		const ordering = getOrderingOptions(options.queue);
+		if (data.orderingKey != null && data.orderingSequence != null) {
+			let wait = 0;
+			while (true) {
+				const completed = await getCompletedOrderingSequence(options.queue, data.orderingKey);
+				if (completed >= data.orderingSequence) return;
+				if (completed === data.orderingSequence - 1) break;
+				await event.step.sleep(`fedify-ordering-wait-${wait++}`, ordering.retryDelay.total("milliseconds"));
+			}
+		}
+		try {
+			const federation = await options.federation(event);
+			const contextData = options.contextData == null ? void 0 : await options.contextData(event);
+			await federation.processQueuedTask(contextData, data.message);
+		} catch (error) {
+			if (data.orderingKey != null && data.orderingSequence != null && (error instanceof ErrorDoNotRetry || event.attempt >= maxRetries)) await options.queue.skipOrderingSequence(data.orderingKey, data.orderingSequence);
+			throw error;
+		}
+		if (data.orderingKey != null && data.orderingSequence != null) await completeOrderingSequence(options.queue, data.orderingKey, data.orderingSequence);
+	};
+}
+/**
+* Wraps a queue event callback.  This is exposed for cross-runtime tests; use
+* {@link createNetlifyQueueHandler} in applications.
+* @internal
+*/
+function createNetlifyQueueHandlerWith(wrapper, options) {
+	return wrapper(createNetlifyQueueEventHandler(options));
+}
+/**
+* Creates a Netlify Async Workloads function that processes Fedify jobs.
+*
+* Export the returned function as the default export of a file under
+* *netlify/functions/*.  The workload's `asyncWorkloadConfig.events` must
+* contain the associated queue's {@link NetlifyMessageQueue.eventName}.
+*
+* @typeParam TContextData The context data passed to Fedify dispatchers.
+* @param options The workload handler options.
+* @returns A function produced by Netlify's `asyncWorkloadFn()`.
+* @since 2.4.0
+*/
+function createNetlifyQueueHandler(options) {
+	return createNetlifyQueueHandlerWith(asyncWorkloadFn, options);
+}
+//#endregion
+export { NetlifyMessageQueue, NetlifyMessageQueueSendError, createNetlifyQueueHandler };