feat(monitoring): add stats counters API and public status page

Add GET /api/stats exposing cumulative counters (feeds created/deleted, emails received/rejected, recent date-times) plus live values (active feeds, active WebSub subscriptions). Counters persist in a stats:counters KV singleton and are incremented at the email-processing chokepoint and feed create/delete paths. Replace the / → /admin redirect with a public status page rendering these figures with a link to the admin. Co-Authored-By: Claude Opus 4.7 <[email protected]>
2026-05-23 09:50:51 +02:00
1 parent f4d5edda0e
commit b534ce5bf8
@@ -0,0 +1,122 @@
+import { describe, it, expect } from "vitest";
+import { createMockEnv } from "../test/setup";
+import {
+  getCounters,
+  bumpCounters,
+  countKeysByPrefix,
+  getStats,
+} from "./stats";
+import { STATS_KEY, FEEDS_LIST_KEY } from "../config/constants";
+import { Env } from "../types";
+
+describe("stats helper", () => {
+  it("returns zeroed counters when nothing is stored", async () => {
+    const env = createMockEnv() as unknown as Env;
+    const counters = await getCounters(env.EMAIL_STORAGE);
+    expect(counters).toMatchObject({
+      feeds_created: 0,
+      feeds_deleted: 0,
+      emails_received: 0,
+      emails_rejected: 0,
+    });
+    expect(counters.first_seen).toBeUndefined();
+  });
+
+  it("accumulates numeric deltas across bumps", async () => {
+    const env = createMockEnv() as unknown as Env;
+    const kv = env.EMAIL_STORAGE;
+
+    await bumpCounters(kv, { emails_received: 1 });
+    await bumpCounters(kv, { emails_received: 2, emails_rejected: 1 });
+    await bumpCounters(kv, { feeds_created: 1, feeds_deleted: 3 });
+
+    const counters = await getCounters(kv);
+    expect(counters.emails_received).toBe(3);
+    expect(counters.emails_rejected).toBe(1);
+    expect(counters.feeds_created).toBe(1);
+    expect(counters.feeds_deleted).toBe(3);
+  });
+
+  it("overwrites date-time fields and sets first_seen once", async () => {
+    const env = createMockEnv() as unknown as Env;
+    const kv = env.EMAIL_STORAGE;
+
+    await bumpCounters(kv, {
+      emails_received: 1,
+      last_email_at: "2026-01-01T00:00:00.000Z",
+    });
+    const first = await getCounters(kv);
+    const firstSeen = first.first_seen;
+    expect(firstSeen).toBeDefined();
+    expect(first.last_email_at).toBe("2026-01-01T00:00:00.000Z");
+
+    await bumpCounters(kv, {
+      emails_received: 1,
+      last_email_at: "2026-02-02T00:00:00.000Z",
+    });
+    const second = await getCounters(kv);
+    expect(second.last_email_at).toBe("2026-02-02T00:00:00.000Z");
+    expect(second.first_seen).toBe(firstSeen);
+  });
+
+  it("counts keys by prefix", async () => {
+    const env = createMockEnv() as unknown as Env;
+    const kv = env.EMAIL_STORAGE;
+    await kv.put("websub:a:1", "{}");
+    await kv.put("websub:a:2", "{}");
+    await kv.put("feed:x:config", "{}");
+
+    expect(await countKeysByPrefix(kv, "websub:")).toBe(2);
+    expect(await countKeysByPrefix(kv, "missing:")).toBe(0);
+  });
+
+  it("getStats combines persisted counters with live values", async () => {
+    const env = createMockEnv() as unknown as Env;
+    const kv = env.EMAIL_STORAGE;
+
+    await kv.put(
+      FEEDS_LIST_KEY,
+      JSON.stringify({
+        feeds: [
+          { id: "a", title: "A" },
+          { id: "b", title: "B" },
+        ],
+      }),
+    );
+    await kv.put("websub:a:1", "{}");
+    await bumpCounters(kv, { emails_received: 5, feeds_created: 2 });
+
+    const stats = await getStats(env);
+    expect(stats.active_feeds).toBe(2);
+    expect(stats.websub_subscriptions_active).toBe(1);
+    expect(stats.emails_received).toBe(5);
+    expect(stats.feeds_created).toBe(2);
+  });
+
+  it("never throws on a failing KV (counters are best-effort)", async () => {
+    const brokenKv = {
+      get: async () => {
+        throw new Error("kv down");
+      },
+      put: async () => {
+        throw new Error("kv down");
+      },
+    } as unknown as KVNamespace;
+
+    await expect(
+      bumpCounters(brokenKv, { emails_received: 1 }),
+    ).resolves.toBeUndefined();
+    expect(await getCounters(brokenKv)).toMatchObject({ emails_received: 0 });
+    expect(await countKeysByPrefix(brokenKv, "websub:")).toBe(0);
+  });
+
+  it("persists under the stats KV key", async () => {
+    const env = createMockEnv() as unknown as Env;
+    const kv = env.EMAIL_STORAGE;
+    await bumpCounters(kv, { feeds_created: 1 });
+    const raw = (await kv.get(STATS_KEY, { type: "json" })) as {
+      feeds_created: number;
+    };
+    expect(raw.feeds_created).toBe(1);
+  });
+});
@@ -0,0 +1,84 @@
+import { Counters, Env, StatsResponse } from "../types";
+import { STATS_KEY } from "../config/constants";
+import { logger } from "../lib/logger";
+import { listAllFeeds } from "../routes/admin/helpers";
+
+const EMPTY_COUNTERS: Counters = {
+  feeds_created: 0,
+  feeds_deleted: 0,
+  emails_received: 0,
+  emails_rejected: 0,
+};
+
+export async function getCounters(kv: KVNamespace): Promise<Counters> {
+  try {
+    const stored = (await kv.get(STATS_KEY, {
+      type: "json",
+    })) as Counters | null;
+    return { ...EMPTY_COUNTERS, ...(stored || {}) };
+  } catch (error) {
+    logger.error("Error reading counters", { error: String(error) });
+    return { ...EMPTY_COUNTERS };
+  }
+}
+
+/**
+ * Read-modify-write the counters singleton. KV has no atomic increment, so
+ * concurrent invocations can lose updates — accepted given KV's eventual
+ * consistency and this app's low volume (see email-processor.ts storeEmail).
+ * Never throws: counter failures must not break ingestion or admin flows.
+ */
+export async function bumpCounters(
+  kv: KVNamespace,
+  changes: Partial<Omit<Counters, "first_seen">>,
+): Promise<void> {
+  try {
+    const current = await getCounters(kv);
+
+    current.feeds_created += changes.feeds_created ?? 0;
+    current.feeds_deleted += changes.feeds_deleted ?? 0;
+    current.emails_received += changes.emails_received ?? 0;
+    current.emails_rejected += changes.emails_rejected ?? 0;
+    if (changes.last_email_at) current.last_email_at = changes.last_email_at;
+    if (changes.last_feed_created_at)
+      current.last_feed_created_at = changes.last_feed_created_at;
+    if (!current.first_seen) current.first_seen = new Date().toISOString();
+
+    await kv.put(STATS_KEY, JSON.stringify(current));
+  } catch (error) {
+    logger.error("Error updating counters", { error: String(error) });
+  }
+}
+
+export async function countKeysByPrefix(
+  kv: KVNamespace,
+  prefix: string,
+): Promise<number> {
+  let total = 0;
+  let cursor: string | undefined;
+  try {
+    do {
+      const listed = await kv.list({ prefix, cursor, limit: 1000 });
+      total += listed.keys.length;
+      cursor = listed.list_complete ? undefined : listed.cursor;
+    } while (cursor);
+  } catch (error) {
+    logger.error("Error counting keys", { prefix, error: String(error) });
+  }
+  return total;
+}
+
+export async function getStats(env: Env): Promise<StatsResponse> {
+  const kv = env.EMAIL_STORAGE;
+  const [counters, feeds, websubCount] = await Promise.all([
+    getCounters(kv),
+    listAllFeeds(kv),
+    countKeysByPrefix(kv, "websub:"),
+  ]);
+
+  return {
+    ...counters,
+    active_feeds: feeds.length,
+    websub_subscriptions_active: websubCount,
+  };
+}