WorkersKvStore class

dahlia · dahlia · commit 161d4f5e59e2 · 2025-05-31T11:45:20.000+09:00
diff --git a/CHANGES.md b/CHANGES.md
@@ -39,13 +39,18 @@ To be released.  Note that 1.6.0 was skipped due to a mistake in the versioning.
      -  Added `HttpMessageSignaturesSpecDeterminer` interface.
      -  Added `--first-knock` option to `fedify lookup` command.
 
+ -  Added `WorkersKvStore` class.  [[#233], [#241], [#242]]
+
  -  The minimum supported version of Node.js is now 22.0.0.
 
 [RFC 9421]: https://www.rfc-editor.org/rfc/rfc9421
 [#208]: https://github.com/fedify-dev/fedify/issues/208
 [#227]: https://github.com/fedify-dev/fedify/issues/227
+[#233]: https://github.com/fedify-dev/fedify/issues/233
 [#235]: https://github.com/fedify-dev/fedify/pull/235
 [#237]: https://github.com/fedify-dev/fedify/pull/237
+[#241]: https://github.com/fedify-dev/fedify/issues/241
+[#242]: https://github.com/fedify-dev/fedify/pull/242
 
 
 Version 1.5.3
diff --git a/fedify/cfworkers/client.ts b/fedify/cfworkers/client.ts
@@ -11,6 +11,7 @@ const mf = new Miniflare({
   modules: [
     { type: "ESModule", path: join(import.meta.dirname ?? ".", "server.js") },
   ],
+  kvNamespaces: ["KV1", "KV2", "KV3"],
   async outboundService(request: Request) {
     const url = new URL(request.url);
     if (url.hostname.endsWith(".test")) {
diff --git a/fedify/cfworkers/server.ts b/fedify/cfworkers/server.ts
@@ -1,7 +1,7 @@
 import {
-  ansiColorFormatter,
-  configure,
-  type LogRecord,
+        ansiColorFormatter,
+        configure,
+        type LogRecord,
 } from "@logtape/logtape";
 import { AsyncLocalStorage } from "node:async_hooks";
 // @ts-ignore: The following code is generated
@@ -33,7 +33,7 @@ await configure({
 });
 
 export default {
-  async fetch(request: Request): Promise<Response> {
+  async fetch(request: Request, env: unknown): Promise<Response> {
     if (request.method === "GET") {
       return new Response(
         JSON.stringify(tests.map(({ name }) => name)),
@@ -98,7 +98,7 @@ export default {
       }
       logs.splice(0, logs.length); // Clear logs
       try {
-        await fn({ name, origin: "", step });
+        await fn({ name, origin: "", step, env });
       } catch (e) {
         failed ??= e;
       }
diff --git a/fedify/deno.json b/fedify/deno.json
@@ -11,13 +11,15 @@
     "./sig": "./sig/mod.ts",
     "./vocab": "./vocab/mod.ts",
     "./webfinger": "./webfinger/mod.ts",
+    "./x/cfworkers": "./x/cfworkers.ts",
     "./x/denokv": "./x/denokv.ts",
     "./x/fresh": "./x/fresh.ts",
     "./x/hono": "./x/hono.ts",
     "./x/sveltekit": "./x/sveltekit.ts"
   },
   "imports": {
     "@cfworker/json-schema": "npm:@cfworker/json-schema@^4.1.1",
+    "@cloudflare/workers-types": "npm:@cloudflare/workers-types@^4.20250529.0",
     "@es-toolkit/es-toolkit": "jsr:@es-toolkit/es-toolkit@^1.38.0",
     "@hongminhee/deno-mock-fetch": "jsr:@hongminhee/deno-mock-fetch@^0.3.2",
     "@hugoalh/http-header-link": "jsr:@hugoalh/http-header-link@^1.0.2",
diff --git a/fedify/federation/handler.test.ts b/fedify/federation/handler.test.ts
@@ -1233,7 +1233,7 @@ test("handleInbox()", async () => {
 
   onNotFoundCalled = null;
   const signedRequest = await signRequest(
-    unsignedRequest.clone(),
+    unsignedRequest.clone() as Request,
     rsaPrivateKey3,
     rsaPublicKey3.id!,
   );
diff --git a/fedify/federation/middleware.test.ts b/fedify/federation/middleware.test.ts
@@ -1303,7 +1303,7 @@ test("FederationImpl.sendActivity()", async (t) => {
   let request: Request | null = null;
   fetchMock.post("https://example.com/inbox", async (cl) => {
     verified = [];
-    request = cl.request!.clone();
+    request = cl.request!.clone() as Request;
     const options = {
       documentLoader: mockDocumentLoader,
       contextLoader: mockDocumentLoader,
@@ -1485,7 +1485,7 @@ test("ContextImpl.sendActivity()", async (t) => {
   let collectionSyncHeader: string | null = null;
   fetchMock.post("https://example.com/inbox", async (cl) => {
     verified = [];
-    request = cl.request!.clone();
+    request = cl.request!.clone() as Request;
     collectionSyncHeader = cl.request!.headers.get(
       "Collection-Synchronization",
     );
@@ -2072,7 +2072,7 @@ test("InboxContextImpl.forwardActivity()", async (t) => {
   let request: Request | null = null;
   fetchMock.post("https://example.com/inbox", async (cl) => {
     verified = [];
-    request = cl.request!.clone();
+    request = cl.request!.clone() as Request;
     const options = {
       documentLoader: mockDocumentLoader,
       contextLoader: mockDocumentLoader,
diff --git a/fedify/federation/send.test.ts b/fedify/federation/send.test.ts
@@ -169,7 +169,7 @@ test("sendActivity()", async (t) => {
     "https://example.com/inbox",
     async (cl) => {
       httpSigVerified = false;
-      request = cl.request!.clone();
+      request = cl.request!.clone() as Request;
       const options = {
         documentLoader: mockDocumentLoader,
         contextLoader: mockDocumentLoader,
diff --git a/fedify/package.json b/fedify/package.json
@@ -68,6 +68,10 @@
       "types": "./dist/webfinger/mod.d.ts",
       "import": "./dist/webfinger/mod.js"
     },
+    "./x/cfworkers": {
+      "types": "./dist/x/cfworkers.d.ts",
+      "import": "./dist/x/cfworkers.js"
+    },
     "./x/hono": {
       "types": "./dist/x/hono.d.ts",
       "import": "./dist/x/hono.js"
@@ -99,6 +103,7 @@
     "urlpattern-polyfill": "^10.1.0"
   },
   "devDependencies": {
+    "@cloudflare/workers-types": "^4.20250529.0",
     "@hongminhee/deno-mock-fetch": "jsr:^0.3.2",
     "@std/assert": "jsr:^0.226.0",
     "@std/path": "jsr:^1.0.9",
diff --git a/fedify/pnpm-lock.yaml b/fedify/pnpm-lock.yaml
diff --git a/fedify/sig/http.ts b/fedify/sig/http.ts
@@ -610,7 +610,7 @@ async function verifyRequestDraft(
     return null;
   }
   const originalRequest = request;
-  request = request.clone();
+  request = request.clone() as Request;
   const dateHeader = request.headers.get("Date");
   if (dateHeader == null) {
     logger.debug(
@@ -909,7 +909,7 @@ async function verifyRequestRfc9421(
   }
 
   const originalRequest = request;
-  request = request.clone();
+  request = request.clone() as Request;
 
   // Check for required headers
   const signatureInputHeader = request.headers.get("Signature-Input");
diff --git a/fedify/tsdown.config.ts b/fedify/tsdown.config.ts
@@ -13,6 +13,7 @@ export default defineConfig({
     "./testing/mod.ts",
     "./vocab/mod.ts",
     "./webfinger/mod.ts",
+    "./x/cfworkers.ts",
     "./x/hono.ts",
     "./x/sveltekit.ts",
     ...(await Array.fromAsync(glob(`**/*.test.ts`)))
diff --git a/fedify/x/cfworkers.test.ts b/fedify/x/cfworkers.test.ts
@@ -0,0 +1,25 @@
+import type { KVNamespace } from "@cloudflare/workers-types/experimental";
+import { assertEquals } from "@std/assert";
+import { test } from "../testing/mod.ts";
+import { WorkersKvStore } from "./cfworkers.ts";
+
+test("WorkersKvStore", async (t) => {
+  const { env } = t as unknown as { env: Record<string, KVNamespace<string>> };
+  const store = new WorkersKvStore(env.KV1);
+
+  await t.step("set() & get()", async () => {
+    await store.set(["foo", "bar"], { foo: 1, bar: 2 });
+    assertEquals(await store.get(["foo", "bar"]), { foo: 1, bar: 2 });
+    assertEquals(await store.get(["foo"]), undefined);
+
+    await store.set(["foo", "baz"], "baz", {
+      ttl: Temporal.Duration.from({ seconds: 0 }),
+    });
+    assertEquals(await store.get(["foo", "baz"]), undefined);
+  });
+
+  await t.step("delete()", async () => {
+    await store.delete(["foo", "bar"]);
+    assertEquals(await store.get(["foo", "bar"]), undefined);
+  });
+});
diff --git a/fedify/x/cfworkers.ts b/fedify/x/cfworkers.ts
@@ -0,0 +1,60 @@
+import type { KVNamespace } from "@cloudflare/workers-types/experimental";
+import type { KvKey, KvStore, KvStoreSetOptions } from "../federation/kv.ts";
+
+interface KvMetadata {
+  expires?: number;
+}
+
+/**
+ * Implementation of the 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.
+ * @since 1.6.0
+ */
+export class WorkersKvStore implements KvStore {
+  #namespace: KVNamespace<string>;
+
+  constructor(namespace: KVNamespace<string>) {
+    this.#namespace = namespace;
+  }
+
+  #encodeKey(key: KvKey): string {
+    return JSON.stringify(key);
+  }
+
+  async get<T = unknown>(key: KvKey): Promise<T | undefined> {
+    const encodedKey = this.#encodeKey(key);
+    const { value, metadata } = await this.#namespace.getWithMetadata(
+      encodedKey,
+      "json",
+    );
+    return metadata == null || metadata.expires < Date.now()
+      ? undefined
+      : value as T;
+  }
+
+  async set(
+    key: KvKey,
+    value: unknown,
+    options?: KvStoreSetOptions,
+  ): Promise<void> {
+    const encodedKey = this.#encodeKey(key);
+    const metadata: KvMetadata = options?.ttl == null ? {} : {
+      expires: Date.now() + options.ttl.total("milliseconds"),
+    };
+    await this.#namespace.put(
+      encodedKey,
+      JSON.stringify(value),
+      options?.ttl == null ? { metadata } : {
+        // According to Cloudflare Workers KV documentation,
+        // the minimum TTL is 60 seconds:
+        expirationTtl: Math.max(options.ttl.total("seconds"), 60),
+        metadata,
+      },
+    );
+  }
+
+  delete(key: KvKey): Promise<void> {
+    return this.#namespace.delete(this.#encodeKey(key));
+  }
+}
