@fedify/cfworkers 2.0.0-dev.241 → 2.0.0-dev.323

package/dist/mod.d.ts

@@ -3,6 +3,30 @@ import { KvKey, KvStore, KvStoreListEntry, KvStoreSetOptions, MessageQueue, Mess
 
 //#region src/mod.d.ts
 
+/**
+ * Result from {@link WorkersMessageQueue.processMessage}.
+ * @since 2.0.0
+ */
+interface ProcessMessageResult {
+  /**
+   * Whether the message should be processed.  If `false`, the message has not
+   * been processed (for example, because an ordering key lock is still held)
+   * and the caller is responsible for re-enqueuing or retrying it when
+   * appropriate.
+   */
+  readonly shouldProcess: boolean;
+  /**
+   * The unwrapped message payload to process.
+   * Only present when `shouldProcess` is `true`.
+   */
+  readonly message?: any;
+  /**
+   * A cleanup function that must be called after processing the message.
+   * This releases the ordering key lock.  Only present when `shouldProcess`
+   * is `true` and the message had an ordering key.
+   */
+  readonly release?: () => Promise<void>;
+}
 /**
  * Implementation of the {@link KvStore} interface for Cloudflare Workers KV
  * binding.  This class provides a wrapper around Cloudflare's KV namespace to
@@ -26,6 +50,33 @@ declare class WorkersKvStore implements KvStore {
    */
   list(prefix?: KvKey): AsyncIterable<KvStoreListEntry>;
 }
+/**
+ * Options for {@link WorkersMessageQueue}.
+ * @since 2.0.0
+ */
+interface WorkersMessageQueueOptions {
+  /**
+   * The KV namespace to use for ordering key locks.  If not provided, ordering
+   * keys will not be supported.
+   *
+   * Note: Cloudflare Workers KV has eventual consistency, so ordering key
+   * guarantees are best-effort.  For strict ordering requirements, consider
+   * using Durable Objects.
+   */
+  readonly orderingKv?: KVNamespace<string>;
+  /**
+   * The prefix for ordering key lock keys.  Defaults to `"__fedify_ordering_"`.
+   * @default `"__fedify_ordering_"`
+   */
+  readonly orderingKeyPrefix?: string;
+  /**
+   * The TTL (time-to-live) for ordering key locks in seconds.
+   * Defaults to 60 seconds.  Must be at least 60 seconds due to
+   * Cloudflare KV minimum TTL requirement.
+   * @default 60
+   */
+  readonly orderingLockTtl?: number;
+}
 /**
  * Implementation of the {@link MessageQueue} interface for Cloudflare
  * Workers Queues binding.  This class provides a wrapper around Cloudflare's
@@ -34,8 +85,8 @@ declare class WorkersKvStore implements KvStore {
  * Note that this implementation does not support the `listen()` method,
  * as Cloudflare Workers Queues do not support message consumption in the same
  * way as other message queue systems.  Instead, you should use
- * the {@link Federation.processQueuedTask} method to process messages
- * passed to the queue.
+ * the {@link WorkersMessageQueue.processMessage} method to handle ordering key
+ * locks before calling {@link Federation.processQueuedTask}.
  * @since 1.9.0
  */
 declare class WorkersMessageQueue implements MessageQueue {
@@ -46,10 +97,53 @@ declare class WorkersMessageQueue implements MessageQueue {
    * @since 1.7.0
    */
   readonly nativeRetrial = true;
-  constructor(queue: Queue);
+  /**
+   * Constructs a new {@link WorkersMessageQueue} with the given queue and
+   * optional ordering key configuration.
+   * @param queue The Cloudflare Queue binding.
+   * @param options Options for ordering key support.
+   */
+  constructor(queue: Queue, options?: WorkersMessageQueueOptions);
   enqueue(message: any, options?: MessageQueueEnqueueOptions): Promise<void>;
   enqueueMany(messages: readonly any[], options?: MessageQueueEnqueueOptions): Promise<void>;
+  /**
+   * Processes a message from the queue, handling ordering key locks.
+   * Call this method before {@link Federation.processQueuedTask} to ensure
+   * ordering key semantics are respected.
+   *
+   * Example usage in a Cloudflare Worker queue handler:
+   *
+   * ```typescript ignore
+   * export default {
+   *   async queue(batch, env, ctx) {
+   *     const queue = new WorkersMessageQueue(env.QUEUE, {
+   *       orderingKv: env.ORDERING_KV,
+   *     });
+   *     for (const msg of batch.messages) {
+   *       const result = await queue.processMessage(msg.body);
+   *       if (!result.shouldProcess) {
+   *         msg.retry();  // Re-enqueue to wait for lock
+   *         continue;
+   *       }
+   *       try {
+   *         await federation.processQueuedTask(ctx, result.message);
+   *         msg.ack();
+   *       } catch (e) {
+   *         msg.retry();
+   *       } finally {
+   *         await result.release?.();
+   *       }
+   *     }
+   *   }
+   * };
+   * ```
+   *
+   * @param rawMessage The raw message body from the queue.
+   * @returns A result object indicating whether to process the message.
+   * @since 2.0.0
+   */
+  processMessage(rawMessage: any): Promise<ProcessMessageResult>;
   listen(_handler: (message: any) => Promise<void> | void, _options?: MessageQueueListenOptions): Promise<void>;
 }
 //#endregion
-export { WorkersKvStore, WorkersMessageQueue };
+export { ProcessMessageResult, WorkersKvStore, WorkersMessageQueue, WorkersMessageQueueOptions };

package/dist/mod.js

@@ -81,33 +81,112 @@ var WorkersKvStore = class {
 * Note that this implementation does not support the `listen()` method,
 * as Cloudflare Workers Queues do not support message consumption in the same
 * way as other message queue systems.  Instead, you should use
-* the {@link Federation.processQueuedTask} method to process messages
-* passed to the queue.
+* the {@link WorkersMessageQueue.processMessage} method to handle ordering key
+* locks before calling {@link Federation.processQueuedTask}.
 * @since 1.9.0
 */
 var WorkersMessageQueue = class {
 	#queue;
+	#orderingKv;
+	#orderingKeyPrefix;
+	#orderingLockTtl;
 	/**
 	* Cloudflare Queues provide automatic retry with exponential backoff
 	* and Dead Letter Queues.
 	* @since 1.7.0
 	*/
 	nativeRetrial = true;
-	constructor(queue) {
+	/**
+	* Constructs a new {@link WorkersMessageQueue} with the given queue and
+	* optional ordering key configuration.
+	* @param queue The Cloudflare Queue binding.
+	* @param options Options for ordering key support.
+	*/
+	constructor(queue, options = {}) {
 		this.#queue = queue;
+		this.#orderingKv = options.orderingKv;
+		this.#orderingKeyPrefix = options.orderingKeyPrefix ?? "__fedify_ordering_";
+		this.#orderingLockTtl = Math.max(options.orderingLockTtl ?? 60, 60);
+	}
+	#getOrderingLockKey(orderingKey) {
+		return `${this.#orderingKeyPrefix}${orderingKey}`;
 	}
-	enqueue(message, options) {
-		return this.#queue.send(message, {
+	async enqueue(message, options) {
+		const wrapped = {
+			__fedify_ordering_key__: options?.orderingKey,
+			__fedify_payload__: message
+		};
+		await this.#queue.send(wrapped, {
 			contentType: "json",
 			delaySeconds: options?.delay?.total("seconds") ?? 0
 		});
 	}
-	enqueueMany(messages, options) {
+	async enqueueMany(messages, options) {
 		const requests = messages.map((msg) => ({
-			body: msg,
+			body: {
+				__fedify_ordering_key__: options?.orderingKey,
+				__fedify_payload__: msg
+			},
 			contentType: "json"
 		}));
-		return this.#queue.sendBatch(requests, { delaySeconds: options?.delay?.total("seconds") ?? 0 });
+		await this.#queue.sendBatch(requests, { delaySeconds: options?.delay?.total("seconds") ?? 0 });
+	}
+	/**
+	* Processes a message from the queue, handling ordering key locks.
+	* Call this method before {@link Federation.processQueuedTask} to ensure
+	* ordering key semantics are respected.
+	*
+	* Example usage in a Cloudflare Worker queue handler:
+	*
+	* ```typescript ignore
+	* export default {
+	*   async queue(batch, env, ctx) {
+	*     const queue = new WorkersMessageQueue(env.QUEUE, {
+	*       orderingKv: env.ORDERING_KV,
+	*     });
+	*     for (const msg of batch.messages) {
+	*       const result = await queue.processMessage(msg.body);
+	*       if (!result.shouldProcess) {
+	*         msg.retry();  // Re-enqueue to wait for lock
+	*         continue;
+	*       }
+	*       try {
+	*         await federation.processQueuedTask(ctx, result.message);
+	*         msg.ack();
+	*       } catch (e) {
+	*         msg.retry();
+	*       } finally {
+	*         await result.release?.();
+	*       }
+	*     }
+	*   }
+	* };
+	* ```
+	*
+	* @param rawMessage The raw message body from the queue.
+	* @returns A result object indicating whether to process the message.
+	* @since 2.0.0
+	*/
+	async processMessage(rawMessage) {
+		const wrapped = rawMessage;
+		const orderingKey = wrapped.__fedify_ordering_key__;
+		const message = "__fedify_payload__" in wrapped ? wrapped.__fedify_payload__ : rawMessage;
+		if (orderingKey == null || this.#orderingKv == null) return {
+			shouldProcess: true,
+			message
+		};
+		const lockKey = this.#getOrderingLockKey(orderingKey);
+		const existing = await this.#orderingKv.get(lockKey);
+		if (existing != null) return { shouldProcess: false };
+		await this.#orderingKv.put(lockKey, Date.now().toString(), { expirationTtl: this.#orderingLockTtl });
+		const release = async () => {
+			await this.#orderingKv.delete(lockKey);
+		};
+		return {
+			shouldProcess: true,
+			message,
+			release
+		};
 	}
 	listen(_handler, _options) {
 		throw new TypeError("WorkersMessageQueue does not support listen().  Use Federation.processQueuedTask() method instead.");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fedify/cfworkers",
-  "version": "2.0.0-dev.241+58c8126c",
+  "version": "2.0.0-dev.323+1d796545",
   "description": "Adapt Fedify with Cloudflare Workers",
   "keywords": [
     "Fedify",
@@ -52,7 +52,7 @@
   ],
   "peerDependencies": {
     "@cloudflare/workers-types": "^4.20250906.0",
-    "@fedify/fedify": "^2.0.0-dev.241+58c8126c"
+    "@fedify/fedify": "^2.0.0-dev.323+1d796545"
   },
   "devDependencies": {
     "@cloudflare/vitest-pool-workers": "^0.8.31",