From 814290d5b7333fdf41060bdfbb9eb150c123ba01 Mon Sep 17 00:00:00 2001 From: Anvarbek Date: Fri, 13 Nov 2026 10:00:50 +0900 Subject: [PATCH 1/2] Warn that the in-process queue fails on Workers Copying InProcessMessageQueue into a Cloudflare Worker accepts activities that are never processed. The delayed enqueue uses a timer the isolate can terminate, and listen() only polls memory that does not survive between requests. Document that limitation next to the queue and in the Workers deployment guide, and point readers to WorkersMessageQueue. Changelog: none --- docs/manual/deploy.md | 9 +++++++++ docs/manual/mq.md | 11 +++++++++++ 2 files changed, 20 insertions(+) diff --git a/docs/manual/deploy.md b/docs/manual/deploy.md index a46afc7a8..add605e87 100644 --- a/docs/manual/deploy.md +++ b/docs/manual/deploy.md @@ -927,6 +927,15 @@ does not. See the [*`WorkersD1KvStore`*](./kv.md#workersd1kvstore-cloudflare-workers-only) section for details. +> [!WARNING] +> Do not use `InProcessMessageQueue` on Cloudflare Workers. A delayed +> enqueue depends on `setTimeout()`, which may never run after the isolate +> exits, and `listen()` polls memory that does not survive between requests. +> Each isolate also has its own queue, so a message accepted in one request +> is not visible to the next. Use `WorkersMessageQueue` and a `queue()` +> handler, as shown in [Manual queue processing](#manual-queue-processing), +> or configure another durable queue. + #### Node.js compatibility Fedify depends on Node.js APIs for cryptography and DNS, so Workers need diff --git a/docs/manual/mq.md b/docs/manual/mq.md index 1a6498fda..f88519a7f 100644 --- a/docs/manual/mq.md +++ b/docs/manual/mq.md @@ -44,6 +44,17 @@ Cons : Not suitable for production, doesn't persist messages between restarts, no native retry mechanism. +> [!WARNING] +> `InProcessMessageQueue` cannot run on [Cloudflare Workers]. A delayed +> `enqueue()` schedules a `setTimeout()` and resolves immediately, but a +> Worker isolate can terminate after the response, so the timer may never +> run and the message may never enter the queue. `listen()` only polls +> in-memory state. Workers have no process that survives between requests, +> and each isolate has its own queue. Use +> [`WorkersMessageQueue`](#workersmessagequeue-cloudflare-workers-only) with +> a `queue()` handler, or another durable queue. Do not treat a delayed +> enqueue as reliable on Workers. + ~~~~ typescript twoslash import type { KvStore } from "@fedify/fedify"; // ---cut-before--- From 886798a36791a0cbb6c4226632e9f728b839f6af Mon Sep 17 00:00:00 2001 From: Anvarbek Date: Fri, 13 Nov 2026 10:09:43 +0900 Subject: [PATCH 2/2] Soften the Workers isolate-memory warning A Worker can reuse one isolate for a later request, so in-process queue memory is not guaranteed to disappear or to be shared. Say that instead of claiming the next request cannot see the message. Changelog: none --- docs/manual/deploy.md | 5 ++--- docs/manual/mq.md | 4 ++-- 2 files changed, 4 insertions(+), 5 deletions(-) diff --git a/docs/manual/deploy.md b/docs/manual/deploy.md index add605e87..ffa1d152d 100644 --- a/docs/manual/deploy.md +++ b/docs/manual/deploy.md @@ -930,9 +930,8 @@ section for details. > [!WARNING] > Do not use `InProcessMessageQueue` on Cloudflare Workers. A delayed > enqueue depends on `setTimeout()`, which may never run after the isolate -> exits, and `listen()` polls memory that does not survive between requests. -> Each isolate also has its own queue, so a message accepted in one request -> is not visible to the next. Use `WorkersMessageQueue` and a `queue()` +> exits, and `listen()` polls memory that is not guaranteed to survive or +> be shared across requests. Use `WorkersMessageQueue` and a `queue()` > handler, as shown in [Manual queue processing](#manual-queue-processing), > or configure another durable queue. diff --git a/docs/manual/mq.md b/docs/manual/mq.md index f88519a7f..b75dd22bf 100644 --- a/docs/manual/mq.md +++ b/docs/manual/mq.md @@ -49,8 +49,8 @@ Cons > `enqueue()` schedules a `setTimeout()` and resolves immediately, but a > Worker isolate can terminate after the response, so the timer may never > run and the message may never enter the queue. `listen()` only polls -> in-memory state. Workers have no process that survives between requests, -> and each isolate has its own queue. Use +> in-memory state, which is not guaranteed to survive or be shared across +> requests. Use > [`WorkersMessageQueue`](#workersmessagequeue-cloudflare-workers-only) with > a `queue()` handler, or another durable queue. Do not treat a delayed > enqueue as reliable on Workers.