@fedify/cfworkers 2.0.0-pr.490.2 → 2.0.0-pr.559.4

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright 2024–2025 Hong Minhee
+Copyright 2024–2026 Hong Minhee
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of
 this software and associated documentation files (the "Software"), to deal in

package/README.md

@@ -1,7 +1,7 @@
 <!-- deno-fmt-ignore-file -->
 
 @fedify/cfworkers: Adapt Fedify with Cloudflare Workers
-======================================================
+=======================================================
 
 [![JSR][JSR badge]][JSR]
 [![npm][npm badge]][npm]
@@ -47,6 +47,20 @@ export default {
 }>;
 ~~~~
 
+[JSR badge]: https://jsr.io/badges/@fedify/cfworkers
+[JSR]: https://jsr.io/@fedify/cfworkers
+[npm badge]: https://img.shields.io/npm/v/@fedify/cfworkers?logo=npm
+[npm]: https://www.npmjs.com/package/@fedify/cfworkers
+[@fedify@hollo.social badge]: https://fedi-badge.deno.dev/@fedify@hollo.social/followers.svg
+[@fedify@hollo.social]: https://hollo.social/@fedify
+[Fedify]: https://fedify.dev/
+[`KvStore`]: https://jsr.io/@fedify/fedify/doc/federation/~/KvStore
+[`MessageQueue`]: https://jsr.io/@fedify/fedify/doc/federation/~/MessageQueue
+[Cloudflare Workers]: https://workers.cloudflare.com/
+[`WorkersKvStore`]: https://jsr.io/@fedify/cfworkers/doc/~/WorkersKvStore
+[`WorkersMessageQueue`]: https://jsr.io/@fedify/cfworkers/doc/~/WorkersMessageQueue
+
+
 `WorkersKvStore`
 ----------------
 
@@ -55,6 +69,9 @@ that uses Cloudflare's built-in [Cloudflare Workers KV] API.  It provides
 persistent storage and good performance for Cloudflare Workers environments.
 It's suitable for production use in Cloudflare Workers applications.
 
+[Cloudflare Workers KV]: https://developers.cloudflare.com/kv/
+
+
 `WorkersMessageQueue`
 ---------------------
 
@@ -65,9 +82,10 @@ Cloudflare Workers environments.  It requires a Cloudflare Queues setup and
 management.
 
 > [!NOTE]
-> Since your `KVNamespace` and `Queue` are not bound to global variables, but rather
-> passed as arguments to the `fetch()` and `queue()` methods, you need to instantiate
-> your `Federation` object inside these methods, rather than at the top level.
+> Since your `KVNamespace` and `Queue` are not bound to global variables, but
+> rather passed as arguments to the `fetch()` and `queue()` methods, you need
+> to instantiate your `Federation` object inside these methods, rather than at
+> the top level.
 >
 > For better organization, you probably want to use a builder pattern to
 > register your dispatchers and listeners before instantiating the `Federation`
@@ -83,6 +101,9 @@ management.
 > process the messages.  The `queue()` method is the only way to consume
 > messages from the queue in Cloudflare Workers.
 
+[Cloudflare Queues]: https://developers.cloudflare.com/queues/
+
+
 Installation
 ------------
 
@@ -93,18 +114,3 @@ pnpm add     @fedify/cfworkers  # pnpm
 yarn add     @fedify/cfworkers  # Yarn
 bun  add     @fedify/cfworkers  # Bun
 ~~~~
-
-[JSR]: https://jsr.io/@fedify/cfworkers
-[JSR badge]: https://jsr.io/badges/@fedify/cfworkers
-[npm]: https://www.npmjs.com/package/@fedify/cfworkers
-[npm badge]: https://img.shields.io/npm/v/@fedify/cfworkers?logo=npm
-[@fedify@hollo.social badge]: https://fedi-badge.deno.dev/@fedify@hollo.social/followers.svg
-[@fedify@hollo.social]: https://hollo.social/@fedify
-[Fedify]: https://fedify.dev/
-[`KvStore`]: https://jsr.io/@fedify/fedify/doc/federation/~/KvStore
-[`MessageQueue`]: https://jsr.io/@fedify/fedify/doc/federation/~/MessageQueue
-[`WorkersKvStore`]: https://jsr.io/@fedify/cfworkers/doc/~/WorkersKvStore
-[`WorkersMessageQueue`]: https://jsr.io/@fedify/cfworkers/doc/~/WorkersMessageQueue
-[Cloudflare Workers]: https://workers.cloudflare.com/
-[Cloudflare Workers KV]: https://developers.cloudflare.com/kv/
-[Cloudflare Queues]: https://developers.cloudflare.com/queues/

package/dist/mod.d.ts

@@ -1,8 +1,32 @@
 import { KVNamespace, Queue } from "@cloudflare/workers-types/experimental";
-import { KvKey, KvStore, KvStoreSetOptions, MessageQueue, MessageQueueEnqueueOptions, MessageQueueListenOptions } from "@fedify/fedify/federation";
+import { KvKey, KvStore, KvStoreListEntry, KvStoreSetOptions, MessageQueue, MessageQueueEnqueueOptions, MessageQueueListenOptions } from "@fedify/fedify/federation";
 
 //#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
@@ -20,6 +44,38 @@ declare class WorkersKvStore implements KvStore {
   get<T = unknown>(key: KvKey): Promise<T | undefined>;
   set(key: KvKey, value: unknown, options?: KvStoreSetOptions): Promise<void>;
   delete(key: KvKey): Promise<void>;
+  /**
+   * {@inheritDoc KvStore.list}
+   * @since 1.10.0
+   */
+  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
@@ -29,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 {
@@ -41,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: 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

@@ -34,6 +34,44 @@ var WorkersKvStore = class {
 	delete(key) {
 		return this.#namespace.delete(this.#encodeKey(key));
 	}
+	/**
+	* {@inheritDoc KvStore.list}
+	* @since 1.10.0
+	*/
+	async *list(prefix) {
+		let pattern;
+		let exactKey = null;
+		if (prefix == null || prefix.length === 0) pattern = "[";
+		else {
+			exactKey = this.#encodeKey(prefix);
+			pattern = JSON.stringify(prefix).slice(0, -1) + ",";
+		}
+		if (exactKey != null) {
+			const { value, metadata } = await this.#namespace.getWithMetadata(exactKey, "json");
+			if (value != null && (metadata == null || metadata.expires == null || metadata.expires >= Date.now())) yield {
+				key: prefix,
+				value
+			};
+		}
+		let cursor;
+		do {
+			const result = await this.#namespace.list({
+				prefix: pattern,
+				cursor
+			});
+			cursor = result.list_complete ? void 0 : result.cursor;
+			for (const keyInfo of result.keys) {
+				const metadata = keyInfo.metadata;
+				if (metadata?.expires != null && metadata.expires < Date.now()) continue;
+				const value = await this.#namespace.get(keyInfo.name, "json");
+				if (value == null) continue;
+				yield {
+					key: JSON.parse(keyInfo.name),
+					value
+				};
+			}
+		} while (cursor != null);
+	}
 };
 /**
 * Implementation of the {@link MessageQueue} interface for Cloudflare
@@ -43,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);
 	}
-	enqueue(message, options) {
-		return this.#queue.send(message, {
+	#getOrderingLockKey(orderingKey) {
+		return `${this.#orderingKeyPrefix}${orderingKey}`;
+	}
+	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-pr.490.2+99a396d5",
+  "version": "2.0.0-pr.559.4+6357309b",
   "description": "Adapt Fedify with Cloudflare Workers",
   "keywords": [
     "Fedify",
@@ -51,16 +51,20 @@
     "package.json"
   ],
   "peerDependencies": {
-    "@cloudflare/workers-types": "^4.20250529.0",
-    "@fedify/fedify": "^2.0.0-pr.490.2+99a396d5"
+    "@cloudflare/workers-types": "^4.20250906.0",
+    "@fedify/fedify": "^2.0.0-pr.559.4+6357309b"
   },
   "devDependencies": {
+    "@cloudflare/vitest-pool-workers": "^0.8.31",
     "tsdown": "^0.12.9",
-    "typescript": "^5.9.3"
+    "typescript": "^5.9.3",
+    "vitest": "~3.2.0",
+    "wrangler": "^4.21.1"
   },
   "scripts": {
-    "build": "tsdown",
-    "prepublish": "tsdown",
-    "test": "deno task codegen && tsdown && cd dist/ && node --test"
+    "build:self": "tsdown",
+    "build": "pnpm --filter @fedify/cfworkers... run build:self",
+    "prepublish": "pnpm build",
+    "test": "vitest run"
   }
 }