refactor(domain): introduce FeedRepository as the single KV access layer

Centralise the KV key schema and all get/put access behind a FeedRepository class under src/domain/. Every feed/email/list/icon/websub/counter key was previously inlined across ~12 modules with two divergent storeEmail and addFeedToList implementations; the dead src/utils/storage.ts write path is removed and the email key convention unified on feed:<id>:<ts>. Behaviour-preserving: existing tests pass unchanged in logic, plus a new feed-repository.test.ts covering CRUD, key builders, list ops and counters. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-06-21 06:13:48 +00:00 · 2026-05-23 23:56:44 +02:00
parent a0eaebe749
commit 2b3f00f7e3
22 changed files with 616 additions and 539 deletions
@@ -1,17 +1,12 @@
 import { Hono } from "hono";
-import {
-  Env,
-  FeedConfig,
-  FeedMetadata,
-  EmailData,
-  EmailMetadata,
-} from "../../types";
+import { Env, EmailMetadata } from "../../types";
 import { logger } from "../../lib/logger";
 import { Layout, clampText } from "./ui";
 import {
  deleteAttachmentsForEmails,
  deleteKeysWithConcurrency,
 } from "./helpers";
+import { FeedRepository } from "../../domain/feed-repository";
 import { feedRssUrl, feedAtomUrl, feedEmailAddress } from "../../utils/urls";
 import { formatBytes } from "../../utils/format";
 import { emailsPageScript } from "../../scripts/generated/emails-page";
@@ -156,17 +151,13 @@ const SenderField = ({ from, feedId }: SenderFieldProps) => {

 emailsRouter.get("/feeds/:feedId/emails", async (c) => {
  const env = c.env;
-  const emailStorage = env.EMAIL_STORAGE;
+  const repo = FeedRepository.from(env);
  const feedId = c.req.param("feedId");
  const message = c.req.query("message");
  const count = Number(c.req.query("count") || "0");

-  const feedConfig = (await emailStorage.get(`feed:${feedId}:config`, {
-    type: "json",
-  })) as FeedConfig | null;
-  const feedMetadata = (await emailStorage.get(`feed:${feedId}:metadata`, {
-    type: "json",
-  })) as FeedMetadata | null;
+  const feedConfig = await repo.getConfig(feedId);
+  const feedMetadata = await repo.getMetadata(feedId);

  if (!feedConfig || !feedMetadata) {
    return c.text("Feed not found", 404);
@@ -461,16 +452,14 @@ emailsRouter.get("/feeds/:feedId/emails", async (c) => {

 emailsRouter.get("/emails/:emailKey", async (c) => {
  const env = c.env;
-  const emailStorage = env.EMAIL_STORAGE;
+  const repo = FeedRepository.from(env);
  const emailKey = c.req.param("emailKey");

-  const emailData = (await emailStorage.get(emailKey, {
-    type: "json",
-  })) as EmailData | null;
+  const emailData = await repo.getEmail(emailKey);

  if (!emailData) return c.text("Email not found", 404);

-  const feedId = emailKey.split(":")[1];
+  const feedId = repo.feedIdFromEmailKey(emailKey);
  const attachments = emailData.attachments ?? [];

  const htmlContent = `<!DOCTYPE html><html><head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><style>body{font-family:-apple-system,BlinkMacSystemFont,'SF Pro Text','SF Pro Display','Helvetica Neue',Arial,sans-serif;line-height:1.5;padding:16px;margin:0;color:#333;box-sizing:border-box}img{max-width:100%;height:auto}a{color:#0070f3}@media(prefers-color-scheme:dark){body{background-color:#1c1c1e;color:#ffffff}a{color:#0a84ff}}</style></head><body>${emailData.content}</body></html>`;
@@ -652,7 +641,7 @@ emailsRouter.get("/emails/:emailKey", async (c) => {

 emailsRouter.post("/emails/:emailKey/delete", async (c) => {
  const env = c.env;
-  const emailStorage = env.EMAIL_STORAGE;
+  const repo = FeedRepository.from(env);
  const emailKey = c.req.param("emailKey");
  const wantsJson = (c.req.header("Accept") || "").includes("application/json");

@@ -664,12 +653,9 @@ emailsRouter.post("/emails/:emailKey/delete", async (c) => {
      return c.text("Feed ID is required", 400);
    }

-    const feedMetadataKey = `feed:${feedId}:metadata`;
-    const feedMetadata = (await emailStorage.get(feedMetadataKey, {
-      type: "json",
-    })) as FeedMetadata | null;
+    const feedMetadata = await repo.getMetadata(feedId);

-    await emailStorage.delete(emailKey);
+    await repo.deleteEmail(emailKey);
    await deleteAttachmentsForEmails(env, feedMetadata?.emails ?? [], [
      emailKey,
    ]);
@@ -678,7 +664,7 @@ emailsRouter.post("/emails/:emailKey/delete", async (c) => {
      feedMetadata.emails = feedMetadata.emails.filter(
        (email) => email.key !== emailKey,
      );
-      await emailStorage.put(feedMetadataKey, JSON.stringify(feedMetadata));
+      await repo.putMetadata(feedId, feedMetadata);
    }

    if (wantsJson) return c.json({ ok: true, emailKey, feedId });
@@ -699,6 +685,7 @@ emailsRouter.post("/emails/:emailKey/delete", async (c) => {
 emailsRouter.post("/feeds/:feedId/emails/bulk-delete", async (c) => {
  const env = c.env;
  const emailStorage = env.EMAIL_STORAGE;
+  const repo = new FeedRepository(emailStorage);
  const feedId = c.req.param("feedId");
  const contentType = c.req.header("Content-Type") || "";
  const wantsJson =
@@ -706,10 +693,7 @@ emailsRouter.post("/feeds/:feedId/emails/bulk-delete", async (c) => {
    (c.req.header("Accept") || "").includes("application/json");

  try {
-    const feedMetadataKey = `feed:${feedId}:metadata`;
-    const feedMetadata = (await emailStorage.get(feedMetadataKey, {
-      type: "json",
-    })) as FeedMetadata | null;
+    const feedMetadata = await repo.getMetadata(feedId);

    if (!feedMetadata) {
      return wantsJson
@@ -753,7 +737,7 @@ emailsRouter.post("/feeds/:feedId/emails/bulk-delete", async (c) => {
      feedMetadata.emails = feedMetadata.emails.filter(
        (email) => !deletedSet.has(email.key),
      );
-      await emailStorage.put(feedMetadataKey, JSON.stringify(feedMetadata));
+      await repo.putMetadata(feedId, feedMetadata);

      return c.json({
        ok: failedEmailKeys.length === 0,
@@ -784,7 +768,7 @@ emailsRouter.post("/feeds/:feedId/emails/bulk-delete", async (c) => {
    feedMetadata.emails = feedMetadata.emails.filter(
      (email) => !deletedSet.has(email.key),
    );
-    await emailStorage.put(feedMetadataKey, JSON.stringify(feedMetadata));
+    await repo.putMetadata(feedId, feedMetadata);

    return c.redirect(
      `/admin/feeds/${feedId}/emails?message=bulkDeleted&count=${deletedOk.length}`,
@@ -1,6 +1,6 @@
 import { Hono } from "hono";
 import { z } from "zod";
-import { Env, FeedConfig } from "../../types";
+import { Env } from "../../types";
 import { bumpCounters } from "../../utils/stats";
 import { waitUntilSafe } from "../../utils/worker";
 import { feedRssUrl, feedEmailAddress } from "../../utils/urls";
@@ -8,11 +8,8 @@ import { logger } from "../../lib/logger";
 import { sendUnsubscribes } from "../../utils/unsubscribe";
 import { getAttachmentBucket } from "../../utils/attachments";
 import { Layout } from "./ui";
-import {
-  removeFeedsFromListBulk,
-  purgeFeedKeysStep,
-  collectUnsubscribeUrls,
-} from "./helpers";
+import { purgeFeedKeysStep, collectUnsubscribeUrls } from "./helpers";
+import { FeedRepository } from "../../domain/feed-repository";
 import {
  createFeedRecord,
  updateFeedRecord,
@@ -149,12 +146,9 @@ feedsRouter.post("/create", async (c) => {

 feedsRouter.get("/:feedId/edit", async (c) => {
  const env = c.env;
-  const emailStorage = env.EMAIL_STORAGE;
  const feedId = c.req.param("feedId");

-  const feedConfig = (await emailStorage.get(`feed:${feedId}:config`, {
-    type: "json",
-  })) as FeedConfig | null;
+  const feedConfig = await FeedRepository.from(env).getConfig(feedId);

  if (!feedConfig) {
    return c.text("Feed not found", 404);
@@ -365,7 +359,7 @@ feedsRouter.post("/:feedId/edit", async (c) => {
 feedsRouter.post("/:feedId/sender-filter", async (c) => {
  const env = c.env;
  const feedId = c.req.param("feedId");
-  const feedConfigKey = `feed:${feedId}:config`;
+  const repo = FeedRepository.from(env);

  const body = await c.req.json().catch(() => null);
  const parsed = senderFilterSchema.safeParse(body);
@@ -376,9 +370,7 @@ feedsRouter.post("/:feedId/sender-filter", async (c) => {
  const { action, value } = parsed.data;
  const normalized = value.trim().toLowerCase();

-  const feedConfig = (await env.EMAIL_STORAGE.get(feedConfigKey, {
-    type: "json",
-  })) as FeedConfig | null;
+  const feedConfig = await repo.getConfig(feedId);
  if (!feedConfig) return c.json({ ok: false, error: "Feed not found" }, 404);

  const allowedSenders = (feedConfig.allowed_senders || []).map((s) =>
@@ -405,15 +397,12 @@ feedsRouter.post("/:feedId/sender-filter", async (c) => {

  if (!targetList.includes(normalized)) {
    targetList.push(normalized);
-    await env.EMAIL_STORAGE.put(
-      feedConfigKey,
-      JSON.stringify({
-        ...feedConfig,
-        allowed_senders: allowedSenders,
-        blocked_senders: blockedSenders,
-        updated_at: Date.now(),
-      }),
-    );
+    await repo.putConfig(feedId, {
+      ...feedConfig,
+      allowed_senders: allowedSenders,
+      blocked_senders: blockedSenders,
+      updated_at: Date.now(),
+    });
  }

  return c.json({ ok: true });
@@ -552,7 +541,9 @@ feedsRouter.post("/bulk-delete", async (c) => {
        }
      }

-      const deletedFeedIds = await removeFeedsFromListBulk(emailStorage, okIds);
+      const deletedFeedIds = await new FeedRepository(
+        emailStorage,
+      ).removeFromListBulk(okIds);
      if (deletedFeedIds.length > 0) {
        await bumpCounters(emailStorage, {
          feeds_deleted: deletedFeedIds.length,
@@ -616,7 +607,9 @@ feedsRouter.post("/bulk-delete", async (c) => {
      }
    }

-    const deletedFeedIds = await removeFeedsFromListBulk(emailStorage, okIds);
+    const deletedFeedIds = await new FeedRepository(
+      emailStorage,
+    ).removeFromListBulk(okIds);
    if (deletedFeedIds.length > 0) {
      await bumpCounters(emailStorage, {
        feeds_deleted: deletedFeedIds.length,
@@ -1,14 +1,7 @@
-import {
-  EmailData,
-  EmailMetadata,
-  Env,
-  FeedList,
-  FeedListItem,
-  FeedMetadata,
-} from "../../types";
-import { FEEDS_LIST_KEY } from "../../config/constants";
+import { EmailData, EmailMetadata, Env } from "../../types";
 import { logger } from "../../lib/logger";
 import { getAttachmentBucket } from "../../utils/attachments";
+import { FeedRepository } from "../../domain/feed-repository";

 // Delete the R2 attachments belonging to the given email keys. Call before the
 // emails are removed from feed metadata, while `emails` still carries their
@@ -58,108 +51,6 @@ export async function deleteKeysWithConcurrency(
  return { ok, failed };
 }

-export async function listAllFeeds(
-  emailStorage: KVNamespace,
-): Promise<FeedListItem[]> {
-  try {
-    const feedList = (await emailStorage.get(FEEDS_LIST_KEY, {
-      type: "json",
-    })) as FeedList | null;
-    return feedList?.feeds || [];
-  } catch (error) {
-    logger.error("Error listing feeds", { error: String(error) });
-    return [];
-  }
-}
-
-export async function addFeedToList(
-  emailStorage: KVNamespace,
-  feedId: string,
-  title: string,
-  description?: string,
-  expires_at?: number,
-): Promise<void> {
-  try {
-    const feedList = ((await emailStorage.get(FEEDS_LIST_KEY, {
-      type: "json",
-    })) as FeedList | null) || { feeds: [] };
-
-    feedList.feeds.push({ id: feedId, title, description, expires_at });
-    await emailStorage.put(FEEDS_LIST_KEY, JSON.stringify(feedList));
-  } catch (error) {
-    logger.error("Error adding feed to list", { feedId, error: String(error) });
-  }
-}
-
-export async function updateFeedInList(
-  emailStorage: KVNamespace,
-  feedId: string,
-  title: string,
-  description?: string,
-  expires_at?: number,
-): Promise<void> {
-  try {
-    const feedList = ((await emailStorage.get(FEEDS_LIST_KEY, {
-      type: "json",
-    })) as FeedList | null) || { feeds: [] };
-
-    const feedIndex = feedList.feeds.findIndex((feed) => feed.id === feedId);
-    if (feedIndex !== -1) {
-      feedList.feeds[feedIndex].title = title;
-      feedList.feeds[feedIndex].description = description;
-      feedList.feeds[feedIndex].expires_at = expires_at;
-      await emailStorage.put(FEEDS_LIST_KEY, JSON.stringify(feedList));
-    }
-  } catch (error) {
-    logger.error("Error updating feed in list", {
-      feedId,
-      error: String(error),
-    });
-  }
-}
-
-export async function removeFeedsFromListBulk(
-  emailStorage: KVNamespace,
-  feedIds: string[],
-): Promise<string[]> {
-  try {
-    const feedList = ((await emailStorage.get(FEEDS_LIST_KEY, {
-      type: "json",
-    })) as FeedList | null) || { feeds: [] };
-
-    const toRemove = new Set(feedIds.filter(Boolean));
-    if (toRemove.size === 0) return [];
-
-    const removed: string[] = [];
-    const nextFeeds: FeedListItem[] = [];
-
-    for (const feed of feedList.feeds) {
-      if (toRemove.has(feed.id)) {
-        removed.push(feed.id);
-        continue;
-      }
-      nextFeeds.push(feed);
-    }
-
-    if (removed.length === 0) return [];
-
-    feedList.feeds = nextFeeds;
-    await emailStorage.put(FEEDS_LIST_KEY, JSON.stringify(feedList));
-    return removed;
-  } catch (error) {
-    logger.error("Error removing feeds from list", { error: String(error) });
-    return [];
-  }
-}
-
-export async function removeFeedFromList(
-  emailStorage: KVNamespace,
-  feedId: string,
-): Promise<boolean> {
-  const removed = await removeFeedsFromListBulk(emailStorage, [feedId]);
-  return removed.includes(feedId);
-}
-
 /**
 * Read a feed's stored RFC 8058 one-click unsubscribe URLs (one per sender).
 * Must be called before the feed metadata is deleted. Never throws.
@@ -169,9 +60,7 @@ export async function collectUnsubscribeUrls(
  feedId: string,
 ): Promise<string[]> {
  try {
-    const metadata = (await emailStorage.get(`feed:${feedId}:metadata`, {
-      type: "json",
-    })) as FeedMetadata | null;
+    const metadata = await new FeedRepository(emailStorage).getMetadata(feedId);
    return Object.values(metadata?.unsubscribe ?? {});
  } catch (error) {
    logger.error("Error reading unsubscribe URLs", {
@@ -192,24 +81,18 @@ export async function purgeFeedKeysStep(
  cursor: string;
  listComplete: boolean;
 }> {
-  const prefix = `feed:${feedId}:`;
-  const limit = Math.min(1000, Math.max(1, Math.floor(options.limit || 100)));
-  const cursor = options.cursor || undefined;
-
-  const listed = await emailStorage.list({ prefix, cursor, limit });
-  const keys = (listed.keys || []).map((k) => k.name);
+  const repo = new FeedRepository(emailStorage);
+  const listed = await repo.listFeedKeys(feedId, {
+    cursor: options.cursor,
+    limit: options.limit,
+  });
+  const keys = listed.names;

  if (options.bucket && keys.length > 0) {
-    const emailKeys = keys.filter((k) => {
-      const suffix = k.slice(prefix.length);
-      return suffix !== "config" && suffix !== "metadata";
-    });
+    const emailKeys = keys.filter((k) => repo.isEmailKey(feedId, k));
    if (emailKeys.length > 0) {
      const emailDataResults = await Promise.allSettled(
-        emailKeys.map(
-          (k) =>
-            emailStorage.get(k, { type: "json" }) as Promise<EmailData | null>,
-        ),
+        emailKeys.map((k) => repo.getEmail(k)),
      );
      const attachmentIds = emailDataResults
        .filter(
@@ -234,8 +117,8 @@ export async function purgeFeedKeysStep(
  return {
    deletedKeys: ok,
    failedKeys: failed,
-    cursor: listed.cursor || "",
-    listComplete: !!listed.list_complete,
+    cursor: listed.cursor,
+    listComplete: listed.listComplete,
  };
 }