refactor(core): message tracker abstraction and formatter plugin registry

server/lib/core/dispatch.ts

@@ -5,6 +5,7 @@ import { matchRoute, eventOwners } from "../events/match";
 import { log } from "../lib/log";
 import { loadTranslations, t as translate, type Translations } from "../lib/i18n";
 import { recordSend } from "../lib/send-log";
+import { kvMessageTracker } from "../lib/message-tracker";
 import {
   loadGroups,
   groupAcceptsOwners,
@@ -35,6 +36,7 @@ export async function dispatchEvent(
 ): Promise<DispatchSummary> {
   const loadedGroups = groups ?? (await loadGroups(env.KV));
   const groupById = new Map(loadedGroups.map((g) => [g.id, g]));
+  const tracker = kvMessageTracker(env.KV);
 
   // Message language is configured per group (Group.lang), not per route.
   const langs = [...new Set(loadedGroups.map((g) => g.lang ?? "en"))];
@@ -209,7 +211,8 @@ export async function dispatchEvent(
         let result: SendResult;
         if (message.updateKey) {
           const groupPrefix = route.groupId ? `${route.groupId}:` : "";
-          const kvKey = `msg:${groupPrefix}${route.id}:${message.updateKey}:${targetStr}`;
+          const eventId = `${groupPrefix}${route.id}:${message.updateKey}`;
+          const kvKey = `msg:${eventId}:${targetStr}`;
           const lockKey = `msg:lock:${kvKey}`;
 
           // Acquire a short-lived lock so concurrent events for the same
@@ -220,7 +223,7 @@ export async function dispatchEvent(
           for (let attempt = 0; attempt < 3; attempt++) {
             const holder = await env.KV.get(lockKey);
             if (holder) {
-              const existing = await env.KV.get(kvKey);
+              const existing = await tracker.get(eventId, targetStr);
               if (existing) {
                 result = await driver.edit(message, target, env, existing);
                 if (result.ok || /not modified/i.test(result.error ?? "")) {
@@ -242,10 +245,10 @@ export async function dispatchEvent(
                     durationMs: Date.now() - started,
                     errorCode: result.errorCode,
                   });
-                  if (!ok) await env.KV.delete(kvKey);
+                  if (!ok) await tracker.delete(eventId, targetStr);
                   continue;
                 }
-                await env.KV.delete(kvKey);
+                await tracker.delete(eventId, targetStr);
                 break;
               }
               await new Promise((r) => setTimeout(r, 50 * (attempt + 1)));
@@ -257,7 +260,7 @@ export async function dispatchEvent(
           }
 
           try {
-            const existingId = await env.KV.get(kvKey);
+            const existingId = await tracker.get(eventId, targetStr);
             if (existingId) {
               result = await driver.edit(message, target, env, existingId);
               if (result.ok) {
@@ -300,11 +303,11 @@ export async function dispatchEvent(
                 });
                 continue;
               }
-              await env.KV.delete(kvKey);
+              await tracker.delete(eventId, targetStr);
             }
             result = await driver.send(message, target, env);
             if (result.ok && result.messageId) {
-              await env.KV.put(kvKey, result.messageId, { expirationTtl: 604800 });
+              await tracker.set(eventId, targetStr, result.messageId);
             }
           } finally {
             if (locked) await env.KV.delete(lockKey);

server/lib/formatters/index.ts

@@ -1,27 +1,9 @@
 import type { Route, WebhookEvent, NeutralMessage, NeutralAuthor } from "../types";
 import type { Translations } from "../lib/i18n";
 import { makeT, senderProfileUrl, type T } from "./helpers";
-import { formatPush } from "./push";
-import { formatPullRequest } from "./pull-request";
-import { formatPullRequestReview, formatPullRequestReviewComment } from "./review";
-import { formatIssues } from "./issues";
-import { formatIssueComment } from "./comments";
-import { formatWorkflowRun, formatWorkflowJob } from "./workflow";
-import { formatRelease } from "./release";
-import { formatCreate, formatDelete } from "./create";
-import { formatStar, formatFork } from "./repo";
-import { formatCheckRun, formatCheckSuite, formatStatus } from "./check";
-import { formatCommitComment } from "./commit-comment";
-import { formatDeployment, formatDeploymentStatus } from "./deployment";
-import { formatMember } from "./member";
-import { formatLabel } from "./label";
-import { formatMilestone } from "./milestone";
-import { formatDiscussion, formatDiscussionComment } from "./discussion";
-import { formatRepository } from "./repository";
-import { formatCodeScanningAlert, formatDependabotAlert } from "./security";
 import { formatGeneric } from "./generic";
-import { formatPing } from "./ping";
-import { formatCustom } from "./custom";
+import type { FormatContext } from "./types";
+import { findFormatter } from "./registry";
 
 export function formatEvent(
   route: Route,
@@ -44,66 +26,10 @@ export function formatEvent(
     url: senderUrl ?? (sender ? senderProfileUrl(repoUrl, sender) : undefined),
   };
 
-  switch (eventType) {
-    case "push":
-      return formatPush(payload, repo, author, t, showEmoji);
-    case "pull_request":
-      return formatPullRequest(payload, repo, author, t, showEmoji);
-    case "pull_request_review":
-      return formatPullRequestReview(payload, repo, author, t, showEmoji);
-    case "pull_request_review_comment":
-      return formatPullRequestReviewComment(payload, repo, author, t, showEmoji);
-    case "issues":
-      return formatIssues(payload, repo, author, t, showEmoji);
-    case "issue_comment":
-      return formatIssueComment(payload, repo, author, t, showEmoji);
-    case "workflow_run":
-      return formatWorkflowRun(payload, repo, author, t, showEmoji);
-    case "workflow_job":
-      return formatWorkflowJob(payload, repo, author, t, showEmoji);
-    case "status":
-      return formatStatus(payload, repo, author, t, showEmoji);
-    case "deployment":
-      return formatDeployment(payload, repo, author, t, showEmoji);
-    case "ping":
-      return formatPing(payload, repo, author, t, showEmoji);
-    case "release":
-      return formatRelease(payload, repo, author, t, showEmoji);
-    case "create":
-      return formatCreate(payload, repo, author, t, showEmoji);
-    case "delete":
-      return formatDelete(payload, repo, author, t, showEmoji);
-    case "star":
-      return formatStar(payload, repo, repoUrl, author, t, showEmoji);
-    case "fork":
-      return formatFork(payload, repo, repoUrl, author, t, showEmoji);
-    case "check_run":
-      return formatCheckRun(payload, repo, author, t, showEmoji);
-    case "check_suite":
-      return formatCheckSuite(payload, repo, author, t, showEmoji);
-    case "commit_comment":
-      return formatCommitComment(payload, repo, author, t, showEmoji);
-    case "deployment_status":
-      return formatDeploymentStatus(payload, repo, author, t, showEmoji);
-    case "member":
-      return formatMember(payload, repo, author, t, showEmoji);
-    case "label":
-      return formatLabel(payload, repo, author, t, showEmoji);
-    case "milestone":
-      return formatMilestone(payload, repo, author, t, showEmoji);
-    case "discussion":
-      return formatDiscussion(payload, repo, author, t, showEmoji);
-    case "discussion_comment":
-      return formatDiscussionComment(payload, repo, author, t, showEmoji);
-    case "repository":
-      return formatRepository(payload, repo, repoUrl, author, t, showEmoji);
-    case "code_scanning_alert":
-      return formatCodeScanningAlert(payload, repo, author, t, showEmoji);
-    case "dependabot_alert":
-      return formatDependabotAlert(payload, repo, author, t, showEmoji);
-    case "custom":
-      return formatCustom(payload, repo, author, t, showEmoji);
-    default:
-      return formatGeneric(eventType, payload, repo, author, t, showEmoji);
-  }
+  const ctx: FormatContext = { payload, repo, repoUrl, author, t, showEmoji };
+
+  return (
+    findFormatter(eventType)?.format(ctx) ??
+    formatGeneric(eventType, payload, repo, author, t, showEmoji)
+  );
 }

server/lib/formatters/registry.ts

@@ -0,0 +1,135 @@
+import type { EventFormatter } from "./types";
+import { formatPush } from "./push";
+import { formatPullRequest } from "./pull-request";
+import { formatPullRequestReview, formatPullRequestReviewComment } from "./review";
+import { formatIssues } from "./issues";
+import { formatIssueComment } from "./comments";
+import { formatWorkflowRun, formatWorkflowJob } from "./workflow";
+import { formatRelease } from "./release";
+import { formatCreate, formatDelete } from "./create";
+import { formatStar, formatFork } from "./repo";
+import { formatCheckRun, formatCheckSuite, formatStatus } from "./check";
+import { formatCommitComment } from "./commit-comment";
+import { formatDeployment, formatDeploymentStatus } from "./deployment";
+import { formatMember } from "./member";
+import { formatLabel } from "./label";
+import { formatMilestone } from "./milestone";
+import { formatDiscussion, formatDiscussionComment } from "./discussion";
+import { formatRepository } from "./repository";
+import { formatCodeScanningAlert, formatDependabotAlert } from "./security";
+import { formatPing } from "./ping";
+import { formatCustom } from "./custom";
+
+export const eventFormatters: EventFormatter[] = [
+  { events: ["push"], format: (c) => formatPush(c.payload, c.repo, c.author, c.t, c.showEmoji) },
+  {
+    events: ["pull_request"],
+    format: (c) => formatPullRequest(c.payload, c.repo, c.author, c.t, c.showEmoji),
+  },
+  {
+    events: ["pull_request_review"],
+    format: (c) => formatPullRequestReview(c.payload, c.repo, c.author, c.t, c.showEmoji),
+  },
+  {
+    events: ["pull_request_review_comment"],
+    format: (c) => formatPullRequestReviewComment(c.payload, c.repo, c.author, c.t, c.showEmoji),
+  },
+  {
+    events: ["issues"],
+    format: (c) => formatIssues(c.payload, c.repo, c.author, c.t, c.showEmoji),
+  },
+  {
+    events: ["issue_comment"],
+    format: (c) => formatIssueComment(c.payload, c.repo, c.author, c.t, c.showEmoji),
+  },
+  {
+    events: ["workflow_run"],
+    format: (c) => formatWorkflowRun(c.payload, c.repo, c.author, c.t, c.showEmoji),
+  },
+  {
+    events: ["workflow_job"],
+    format: (c) => formatWorkflowJob(c.payload, c.repo, c.author, c.t, c.showEmoji),
+  },
+  {
+    events: ["status"],
+    format: (c) => formatStatus(c.payload, c.repo, c.author, c.t, c.showEmoji),
+  },
+  {
+    events: ["deployment"],
+    format: (c) => formatDeployment(c.payload, c.repo, c.author, c.t, c.showEmoji),
+  },
+  { events: ["ping"], format: (c) => formatPing(c.payload, c.repo, c.author, c.t, c.showEmoji) },
+  {
+    events: ["release"],
+    format: (c) => formatRelease(c.payload, c.repo, c.author, c.t, c.showEmoji),
+  },
+  {
+    events: ["create"],
+    format: (c) => formatCreate(c.payload, c.repo, c.author, c.t, c.showEmoji),
+  },
+  {
+    events: ["delete"],
+    format: (c) => formatDelete(c.payload, c.repo, c.author, c.t, c.showEmoji),
+  },
+  {
+    events: ["star"],
+    format: (c) => formatStar(c.payload, c.repo, c.repoUrl, c.author, c.t, c.showEmoji),
+  },
+  {
+    events: ["fork"],
+    format: (c) => formatFork(c.payload, c.repo, c.repoUrl, c.author, c.t, c.showEmoji),
+  },
+  {
+    events: ["check_run"],
+    format: (c) => formatCheckRun(c.payload, c.repo, c.author, c.t, c.showEmoji),
+  },
+  {
+    events: ["check_suite"],
+    format: (c) => formatCheckSuite(c.payload, c.repo, c.author, c.t, c.showEmoji),
+  },
+  {
+    events: ["commit_comment"],
+    format: (c) => formatCommitComment(c.payload, c.repo, c.author, c.t, c.showEmoji),
+  },
+  {
+    events: ["deployment_status"],
+    format: (c) => formatDeploymentStatus(c.payload, c.repo, c.author, c.t, c.showEmoji),
+  },
+  {
+    events: ["member"],
+    format: (c) => formatMember(c.payload, c.repo, c.author, c.t, c.showEmoji),
+  },
+  { events: ["label"], format: (c) => formatLabel(c.payload, c.repo, c.author, c.t, c.showEmoji) },
+  {
+    events: ["milestone"],
+    format: (c) => formatMilestone(c.payload, c.repo, c.author, c.t, c.showEmoji),
+  },
+  {
+    events: ["discussion"],
+    format: (c) => formatDiscussion(c.payload, c.repo, c.author, c.t, c.showEmoji),
+  },
+  {
+    events: ["discussion_comment"],
+    format: (c) => formatDiscussionComment(c.payload, c.repo, c.author, c.t, c.showEmoji),
+  },
+  {
+    events: ["repository"],
+    format: (c) => formatRepository(c.payload, c.repo, c.repoUrl, c.author, c.t, c.showEmoji),
+  },
+  {
+    events: ["code_scanning_alert"],
+    format: (c) => formatCodeScanningAlert(c.payload, c.repo, c.author, c.t, c.showEmoji),
+  },
+  {
+    events: ["dependabot_alert"],
+    format: (c) => formatDependabotAlert(c.payload, c.repo, c.author, c.t, c.showEmoji),
+  },
+  {
+    events: ["custom"],
+    format: (c) => formatCustom(c.payload, c.repo, c.author, c.t, c.showEmoji),
+  },
+];
+
+export function findFormatter(eventType: string): EventFormatter | undefined {
+  return eventFormatters.find((f) => f.events.includes(eventType));
+}

server/lib/formatters/types.ts

@@ -0,0 +1,16 @@
+import type { NeutralAuthor, NeutralMessage } from "../types";
+import type { T } from "./helpers";
+
+export interface FormatContext {
+  payload: Record<string, unknown>;
+  repo?: string;
+  repoUrl?: string;
+  author: NeutralAuthor;
+  t: T;
+  showEmoji: boolean;
+}
+
+export interface EventFormatter {
+  readonly events: readonly string[];
+  format(ctx: FormatContext): NeutralMessage;
+}

server/lib/lib/message-tracker.ts

@@ -0,0 +1,24 @@
+export interface MessageTracker {
+  get(eventId: string, targetId: string): Promise<string | null>;
+  set(eventId: string, targetId: string, messageId: string): Promise<void>;
+  delete(eventId: string, targetId: string): Promise<void>;
+}
+
+const MESSAGE_KEY_TTL_SECONDS = 604800;
+
+export function kvMessageTracker(kv: KVNamespace): MessageTracker {
+  const key = (eventId: string, targetId: string): string => `msg:${eventId}:${targetId}`;
+  return {
+    async get(eventId: string, targetId: string): Promise<string | null> {
+      return kv.get(key(eventId, targetId));
+    },
+    async set(eventId: string, targetId: string, messageId: string): Promise<void> {
+      await kv.put(key(eventId, targetId), messageId, {
+        expirationTtl: MESSAGE_KEY_TTL_SECONDS,
+      });
+    },
+    async delete(eventId: string, targetId: string): Promise<void> {
+      await kv.delete(key(eventId, targetId));
+    },
+  };
+}

server/lib/types.ts

@@ -169,6 +169,22 @@ export interface WebhookEvent {
   installationId?: number;
 }
 
+/**
+ * A forge-agnostic webhook event after provider verification and
+ * normalization: the canonical shape every provider's `parse` output conforms
+ * to, plus the tenant scope (`groupId`) and receipt time carried through the
+ * delivery pipeline.
+ */
+export interface NormalizedWebhook {
+  provider: WebhookProvider;
+  deliveryId: string;
+  event: string;
+  groupId?: string;
+  payload: Record<string, unknown>;
+  installationId?: number;
+  receivedAt: number;
+}
+
 export interface NeutralAuthor {
   name: string;
   iconUrl?: string;