@fedify/cfworkers 1.9.0-dev.1461

package/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright 2024–2025 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
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,110 @@
+<!-- deno-fmt-ignore-file -->
+
+@fedify/cfworkers: Adapt Fedify with Cloudflare Workers
+======================================================
+
+[![JSR][JSR badge]][JSR]
+[![npm][npm badge]][npm]
+[![Follow @fedify@hollo.social][@fedify@hollo.social badge]][@fedify@hollo.social]
+
+*This package is available since Fedify 1.9.0.*
+
+This package provides [Fedify]'s [`KvStore`] and [`MessageQueue`]
+implementations for [Cloudflare Workers]:
+
+ -  [`WorkersKvStore`]
+ -  [`WorkersMessageQueue`]
+
+~~~~ typescript
+import type { Federation } 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.handle(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(message.body);
+    }
+  }
+} 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.
+
+Installation
+------------
+
+~~~~ sh
+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
+~~~~
+
+[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

@@ -0,0 +1,50 @@
+import { KVNamespace, Queue } from "@cloudflare/workers-types/experimental";
+import { KvKey, KvStore, KvStoreSetOptions, MessageQueue, MessageQueueEnqueueOptions, MessageQueueListenOptions } from "@fedify/fedify/federation";
+
+//#region src/mod.d.ts
+
+/**
+ * Implementation of the {@link KvStore} interface for Cloudflare Workers KV
+ * binding.  This class provides a wrapper around Cloudflare's KV namespace to
+ * store and retrieve JSON-serializable values using structured keys.
+ *
+ * Note that this implementation does not support the {@link KvStore.cas}
+ * operation, as Cloudflare Workers KV does not support atomic compare-and-swap
+ * operations.  If you need this functionality, consider using a different
+ * key–value store that supports atomic operations.
+ * @since 1.9.0
+ */
+declare class WorkersKvStore implements KvStore {
+  #private;
+  constructor(namespace: KVNamespace<string>);
+  get<T = unknown>(key: KvKey): Promise<T | undefined>;
+  set(key: KvKey, value: unknown, options?: KvStoreSetOptions): Promise<void>;
+  delete(key: KvKey): Promise<void>;
+}
+/**
+ * Implementation of the {@link MessageQueue} interface for Cloudflare
+ * Workers Queues binding.  This class provides a wrapper around Cloudflare's
+ * Queues to send messages to a queue.
+ *
+ * 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.
+ * @since 1.9.0
+ */
+declare class WorkersMessageQueue implements MessageQueue {
+  #private;
+  /**
+   * Cloudflare Queues provide automatic retry with exponential backoff
+   * and Dead Letter Queues.
+   * @since 1.7.0
+   */
+  readonly nativeRetrial = true;
+  constructor(queue: Queue);
+  enqueue(message: any, options?: MessageQueueEnqueueOptions): Promise<void>;
+  enqueueMany(messages: any[], options?: MessageQueueEnqueueOptions): Promise<void>;
+  listen(_handler: (message: any) => Promise<void> | void, _options?: MessageQueueListenOptions): Promise<void>;
+}
+//#endregion
+export { WorkersKvStore, WorkersMessageQueue };

package/dist/mod.js

@@ -0,0 +1,80 @@
+//#region src/mod.ts
+/**
+* Implementation of the {@link KvStore} interface for Cloudflare Workers KV
+* binding.  This class provides a wrapper around Cloudflare's KV namespace to
+* store and retrieve JSON-serializable values using structured keys.
+*
+* Note that this implementation does not support the {@link KvStore.cas}
+* operation, as Cloudflare Workers KV does not support atomic compare-and-swap
+* operations.  If you need this functionality, consider using a different
+* key–value store that supports atomic operations.
+* @since 1.9.0
+*/
+var WorkersKvStore = class {
+	#namespace;
+	constructor(namespace) {
+		this.#namespace = namespace;
+	}
+	#encodeKey(key) {
+		return JSON.stringify(key);
+	}
+	async get(key) {
+		const encodedKey = this.#encodeKey(key);
+		const { value, metadata } = await this.#namespace.getWithMetadata(encodedKey, "json");
+		return metadata == null || metadata.expires < Date.now() ? void 0 : value;
+	}
+	async set(key, value, options) {
+		const encodedKey = this.#encodeKey(key);
+		const metadata = options?.ttl == null ? {} : { expires: Date.now() + options.ttl.total("milliseconds") };
+		await this.#namespace.put(encodedKey, JSON.stringify(value), options?.ttl == null ? { metadata } : {
+			expirationTtl: Math.max(options.ttl.total("seconds"), 60),
+			metadata
+		});
+	}
+	delete(key) {
+		return this.#namespace.delete(this.#encodeKey(key));
+	}
+};
+/**
+* Implementation of the {@link MessageQueue} interface for Cloudflare
+* Workers Queues binding.  This class provides a wrapper around Cloudflare's
+* Queues to send messages to a queue.
+*
+* 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.
+* @since 1.9.0
+*/
+var WorkersMessageQueue = class {
+	#queue;
+	/**
+	* Cloudflare Queues provide automatic retry with exponential backoff
+	* and Dead Letter Queues.
+	* @since 1.7.0
+	*/
+	nativeRetrial = true;
+	constructor(queue) {
+		this.#queue = queue;
+	}
+	enqueue(message, options) {
+		return this.#queue.send(message, {
+			contentType: "json",
+			delaySeconds: options?.delay?.total("seconds") ?? 0
+		});
+	}
+	enqueueMany(messages, options) {
+		const requests = messages.map((msg) => ({
+			body: msg,
+			contentType: "json"
+		}));
+		return this.#queue.sendBatch(requests, { delaySeconds: options?.delay?.total("seconds") ?? 0 });
+	}
+	listen(_handler, _options) {
+		throw new TypeError("WorkersMessageQueue does not support listen().  Use Federation.processQueuedTask() method instead.");
+	}
+};
+
+//#endregion
+export { WorkersKvStore, WorkersMessageQueue };

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@fedify/cfworkers",
+  "version": "1.9.0-dev.1461+7957aafe",
+  "description": "Adapt Fedify with Cloudflare Workers",
+  "keywords": [
+    "Fedify",
+    "ActivityPub",
+    "Fediverse",
+    "Cloudflare Workers"
+  ],
+  "author": {
+    "name": "Hong Minhee",
+    "email": "hong@minhee.org",
+    "url": "https://hongminhee.org/"
+  },
+  "homepage": "https://fedify.dev/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fedify-dev/fedify.git",
+    "directory": "packages/cfworkers"
+  },
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/fedify-dev/fedify/issues"
+  },
+  "funding": [
+    "https://opencollective.com/fedify",
+    "https://github.com/sponsors/dahlia"
+  ],
+  "type": "module",
+  "main": "./dist/mod.js",
+  "module": "./dist/mod.js",
+  "types": "./dist/mod.d.ts",
+  "exports": {
+    ".": {
+      "require": {
+        "types": "./dist/mod.d.ts",
+        "import": "./dist/mod.js",
+        "default": "./dist/mod.js"
+      },
+      "import": {
+        "types": "./dist/mod.d.ts",
+        "import": "./dist/mod.js",
+        "default": "./dist/mod.js"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist/",
+    "package.json"
+  ],
+  "peerDependencies": {
+    "@cloudflare/workers-types": "^4.20250529.0",
+    "@fedify/fedify": "1.9.0-dev.1461+7957aafe"
+  },
+  "devDependencies": {
+    "tsdown": "^0.12.9",
+    "typescript": "^5.9.2"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "prepublish": "tsdown",
+    "test": "deno task codegen && tsdown && cd dist/ && node --test"
+  }
+}