@fedify/cfworkers: Adapt Fedify with Cloudflare Workers
This package is available since Fedify 1.9.0.
This package provides Fedify's KvStore and MessageQueue
implementations for Cloudflare Workers:
import { createFederation, type Message } from "@fedify/fedify";
import { WorkersKvStore, WorkersMessageQueue } from "@fedify/cfworkers";
type Env = {
KV_BINDING: KVNamespace<string>;
QUEUE_BINDING: Queue;
};
export default {
async fetch(request: Request, env: Env): Promise<Response> {
const federation = createFederation<Env>({
kv: new WorkersKvStore(env.KV_BINDING),
queue: new WorkersMessageQueue(env.QUEUE_BINDING),
// Cloudflare Queues cannot be polled, so the queue() handler below
// consumes the messages instead of Federation.startQueue():
manuallyStartQueue: true,
// ... other options
});
return await federation.fetch(request, { contextData: env });
},
async queue(batch: MessageBatch<unknown>, env: Env): Promise<void> {
const federation = createFederation<Env>({
kv: new WorkersKvStore(env.KV_BINDING),
queue: new WorkersMessageQueue(env.QUEUE_BINDING),
// Inbox listeners run inside processQueuedTask() and may call
// ctx.sendActivity(), which would otherwise start the queue workers
// automatically:
manuallyStartQueue: true,
// ... other options
});
for (const message of batch.messages) {
await federation.processQueuedTask(env, message.body as Message);
}
},
} satisfies ExportedHandler<Env>;
WorkersKvStore
WorkersKvStore is a key–value store implementation for Cloudflare Workers
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.
WorkersMessageQueue
WorkersMessageQueue is a message queue implementation for Cloudflare Workers
that uses Cloudflare's built-in Cloudflare Queues API. It provides
scalability and high performance, making it suitable for production use in
Cloudflare Workers environments. It requires a Cloudflare Queues setup and
management.
[!NOTE] Since your
KVNamespaceandQueueare not bound to global variables, but rather passed as arguments to thefetch()andqueue()methods, you need to instantiate yourFederationobject 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
Federationobject.
[!NOTE] The Cloudflare Queues API does not provide a way to poll messages from the queue, so
WorkersMessageQueue.listen()method always throws aTypeErrorwhen invoked. Instead, you should define aqueue()method in your Cloudflare worker, which will be called by the Cloudflare Queues API when new messages are available in the queue. Inside thequeue()method, you need to callFederation.processQueuedTask()method to manually process the messages. Thequeue()method is the only way to consume messages from the queue in Cloudflare Workers. SetmanuallyStartQueuetotrueas well; otherwise Fedify tries to start the workers automatically, and sincelisten()throws, it logs a warning that they could not be started.
Installation
deno add jsr:@fedify/cfworkers # Deno
npm add @fedify/cfworkers # npm
pnpm add @fedify/cfworkers # pnpm
yarn add @fedify/cfworkers # Yarn
bun add @fedify/cfworkers # Bun