cfworkers

@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:

• WorkersKvStore
• WorkersMessageQueue

import { createFederation, type Message } from "@fedify/fedify";
import { WorkersKvStore, WorkersMessageQueue } from "@fedify/cfworkers";

export default {
  async fetch(request, env, ctx) {
    const federation = createFederation({
      kv: new WorkersKvStore(env.KV_BINDING),
      queue: new WorkersMessageQueue(env.QUEUE_BINDING),
      // ... other options
    });

    return federation.fetch(request, { contextData: env });
  },

  async queue(batch, env, ctx) {
    const federation = createFederation({
      kv: new WorkersKvStore(env.KV_BINDING),
      queue: new WorkersMessageQueue(env.QUEUE_BINDING),
      // ... other options
    });

    for (const message of batch.messages) {
      await federation.processQueuedTask(
        env,
        message.body as unknown as Message,
      );
    }
  }
} satisfies ExportedHandler<{
  KV_BINDING: KVNamespace<string>;
  QUEUE_BINDING: Queue;
}>;

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 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 object.

Note

The Cloudflare Queues API does not provide a way to poll messages from the queue, so WorkersMessageQueue.listen() method always throws a TypeError when invoked. Instead, you should define a queue() method in your Cloudflare worker, which will be called by the Cloudflare Queues API when new messages are available in the queue. Inside the queue() method, you need to call Federation.processQueuedTask() method to manually process the messages. The queue() method is the only way to consume messages from the queue in Cloudflare Workers.

Note

If you use orderingKey when enqueueing messages, construct WorkersMessageQueue with an orderingKv namespace and pass each raw queue message through WorkersMessageQueue.processMessage() before calling Federation.processQueuedTask(). This acquires and releases the best-effort ordering lock for that key. You can also customize the lock behavior with the orderingKeyPrefix and orderingLockTtl options.

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