feat(admin): add cache management page and endpoints

New GET /admin/cache lists app-owned Redis namespaces (int:* and cache:*)
with key counts; POST /admin/cache/clear scan+unlinks a namespace or all
app prefixes. It deliberately never calls FLUSHDB/FLUSHALL and rejects
out-of-prefix patterns with 400, so an always-on endpoint can't wipe a
shared Redis. Adds a Cache admin page (CacheManager) with per-row and
clear-all actions behind a confirm dialog, plus the sidebar/topbar nav.
Namespace helpers copied from the CLI into apps/api/src/utils.

Author: Medformatik

apps/api/src/routes/__tests__/admin-cache.test.ts

@@ -0,0 +1,208 @@
+import { Readable } from "node:stream";
+import Fastify, { type FastifyInstance } from "fastify";
+import { afterAll, afterEach, beforeAll, describe, expect, it, vi } from "vitest";
+import { mockAdminSession } from "./admin-test-helpers.js";
+
+// Auth guard mock — all three exports required.
+const fakeSession = mockAdminSession();
+const mockRequireAdmin = vi.fn().mockResolvedValue(fakeSession);
+const mockGetAdminSession = vi.fn().mockReturnValue(fakeSession);
+const mockTryAdminSession = vi.fn().mockResolvedValue(fakeSession);
+
+vi.mock("../../utils/require-admin.js", () => ({
+  requireAdmin: (...args: unknown[]) => mockRequireAdmin(...args),
+  getAdminSession: (...args: unknown[]) => mockGetAdminSession(...args),
+  tryAdminSession: (...args: unknown[]) => mockTryAdminSession(...args),
+}));
+
+// Audit log.
+const mockWriteAuditLog = vi.fn().mockResolvedValue(undefined);
+vi.mock("../../utils/audit-log.js", () => ({
+  writeAuditLog: (...args: unknown[]) => mockWriteAuditLog(...args),
+}));
+
+// Fake Redis. `scanStream` returns a stream emitting one array of the keys
+// whose name matches the requested glob prefix. `flushdb` is a spy so the
+// "never wipes the whole DB" guarantee is assertable.
+const cacheStore = new Map<string, string>([
+  ["int:geocoding:a", "1"],
+  ["int:geocoding:b", "1"],
+  ["int:routing:c", "1"],
+  ["cache:geocode:d", "1"],
+  ["session:user:1", "1"], // NOT app-owned — must never be touched.
+]);
+
+function prefixFromGlob(match: string): string {
+  return match.endsWith("*") ? match.slice(0, -1) : match;
+}
+
+const mockScanStream = vi.fn((opts: { match: string }) => {
+  const prefix = prefixFromGlob(opts.match);
+  const keys = [...cacheStore.keys()].filter((k) => k.startsWith(prefix));
+  return Readable.from([keys]);
+});
+
+const mockUnlink = vi.fn((...keys: string[]) => {
+  let removed = 0;
+  for (const k of keys) {
+    if (cacheStore.delete(k)) removed += 1;
+  }
+  return Promise.resolve(removed);
+});
+
+const mockFlushdb = vi.fn(() => Promise.resolve("OK"));
+
+const fakeRedis = {
+  scanStream: mockScanStream,
+  unlink: mockUnlink,
+  flushdb: mockFlushdb,
+};
+
+vi.mock("../../redis.js", () => ({ redis: fakeRedis }));
+
+let app: FastifyInstance;
+
+beforeAll(async () => {
+  const { adminCacheRoute } = await import("../admin-cache.js");
+  app = Fastify({ logger: false });
+  await app.register(adminCacheRoute);
+  await app.ready();
+});
+
+afterAll(() => app.close());
+afterEach(() => {
+  vi.clearAllMocks();
+  // Restore the store between tests so destructive tests don't leak.
+  cacheStore.clear();
+  cacheStore.set("int:geocoding:a", "1");
+  cacheStore.set("int:geocoding:b", "1");
+  cacheStore.set("int:routing:c", "1");
+  cacheStore.set("cache:geocode:d", "1");
+  cacheStore.set("session:user:1", "1");
+});
+
+describe("GET /admin/cache", () => {
+  it("lists app-owned namespaces with key counts", async () => {
+    const res = await app.inject({ method: "GET", url: "/admin/cache" });
+
+    expect(res.statusCode).toBe(200);
+    const body = res.json() as { namespaces: Array<{ namespace: string; keyCount: number }> };
+    expect(Array.isArray(body.namespaces)).toBe(true);
+
+    const byName = Object.fromEntries(body.namespaces.map((n) => [n.namespace, n.keyCount]));
+    expect(byName["int:geocoding"]).toBe(2);
+    expect(byName["int:routing"]).toBe(1);
+    expect(byName["cache:geocode"]).toBe(1);
+    // The non-app-owned `session:*` prefix is never scanned.
+    expect(byName["session:user"]).toBeUndefined();
+  });
+
+  it("rejects unauthenticated requests with 401", async () => {
+    mockRequireAdmin.mockRejectedValueOnce(
+      Object.assign(new Error("Authentication required"), { statusCode: 401 }),
+    );
+    const res = await app.inject({ method: "GET", url: "/admin/cache" });
+    expect(res.statusCode).toBe(401);
+  });
+});
+
+describe("POST /admin/cache/clear", () => {
+  it("clears a single namespace and audit-logs it", async () => {
+    const res = await app.inject({
+      method: "POST",
+      url: "/admin/cache/clear",
+      payload: { namespace: "geocoding" },
+    });
+
+    expect(res.statusCode).toBe(200);
+    expect(res.json()).toEqual({ deleted: 2 });
+    // Only the matching prefix was removed; other keys remain.
+    expect(cacheStore.has("int:routing:c")).toBe(true);
+    expect(cacheStore.has("cache:geocode:d")).toBe(true);
+    expect(cacheStore.has("session:user:1")).toBe(true);
+    expect(mockWriteAuditLog).toHaveBeenCalledWith(
+      expect.objectContaining({
+        action: "cache.clear",
+        targetType: "cache",
+        details: { namespace: "geocoding" },
+      }),
+    );
+    expect(mockFlushdb).not.toHaveBeenCalled();
+  });
+
+  it("clears all app-owned prefixes but never the rest of the DB", async () => {
+    const res = await app.inject({ method: "POST", url: "/admin/cache/clear", payload: {} });
+
+    expect(res.statusCode).toBe(200);
+    // int:* (3) + cache:* (1) removed; session:* untouched.
+    expect(res.json()).toEqual({ deleted: 4 });
+    expect(cacheStore.has("session:user:1")).toBe(true);
+    expect(mockFlushdb).not.toHaveBeenCalled();
+  });
+
+  it('treats namespace "all" the same as an omitted namespace', async () => {
+    const res = await app.inject({
+      method: "POST",
+      url: "/admin/cache/clear",
+      payload: { namespace: "all" },
+    });
+
+    expect(res.statusCode).toBe(200);
+    expect(res.json()).toEqual({ deleted: 4 });
+    expect(mockFlushdb).not.toHaveBeenCalled();
+  });
+
+  it("rejects a namespace that resolves outside the app prefixes with 400", async () => {
+    const res = await app.inject({
+      method: "POST",
+      url: "/admin/cache/clear",
+      payload: { namespace: "*" },
+    });
+
+    expect(res.statusCode).toBe(400);
+    expect(mockUnlink).not.toHaveBeenCalled();
+    expect(mockFlushdb).not.toHaveBeenCalled();
+  });
+
+  it("rejects unauthenticated requests with 401", async () => {
+    mockRequireAdmin.mockRejectedValueOnce(
+      Object.assign(new Error("Authentication required"), { statusCode: 401 }),
+    );
+    const res = await app.inject({ method: "POST", url: "/admin/cache/clear", payload: {} });
+    expect(res.statusCode).toBe(401);
+  });
+});
+
+describe("when Redis is disabled", () => {
+  it("GET returns an empty list and POST reports zero deletions", async () => {
+    vi.resetModules();
+    vi.doMock("../../redis.js", () => ({ redis: null }));
+    vi.doMock("../../utils/require-admin.js", () => ({
+      requireAdmin: (...args: unknown[]) => mockRequireAdmin(...args),
+      getAdminSession: (...args: unknown[]) => mockGetAdminSession(...args),
+      tryAdminSession: (...args: unknown[]) => mockTryAdminSession(...args),
+    }));
+    vi.doMock("../../utils/audit-log.js", () => ({
+      writeAuditLog: (...args: unknown[]) => mockWriteAuditLog(...args),
+    }));
+
+    const { adminCacheRoute } = await import("../admin-cache.js");
+    const nullApp = Fastify({ logger: false });
+    await nullApp.register(adminCacheRoute);
+    await nullApp.ready();
+
+    const listRes = await nullApp.inject({ method: "GET", url: "/admin/cache" });
+    expect(listRes.json()).toEqual({ namespaces: [] });
+
+    const clearRes = await nullApp.inject({
+      method: "POST",
+      url: "/admin/cache/clear",
+      payload: {},
+    });
+    expect(clearRes.json()).toEqual({ deleted: 0 });
+
+    await nullApp.close();
+    vi.doUnmock("../../redis.js");
+    vi.resetModules();
+  });
+});

apps/api/src/routes/admin-cache.ts

@@ -0,0 +1,109 @@
+import type { FastifyInstance } from "fastify";
+import { redis } from "../redis";
+import { writeAuditLog } from "../utils/audit-log";
+import {
+  APP_CACHE_PREFIXES,
+  aggregateNamespaces,
+  isAppCachePattern,
+  resolveCachePattern,
+} from "../utils/cache-namespaces";
+import { getAdminSession, requireAdmin } from "../utils/require-admin";
+
+// Globs covering exactly the app-owned key prefixes. The list + clear-all paths
+// scan these and nothing else, so the endpoint can never touch keys outside the
+// application's cache (the CLI's `--all` FLUSHDB is intentionally NOT mirrored).
+const APP_CACHE_GLOBS = APP_CACHE_PREFIXES.map((prefix) => `${prefix}*`);
+
+const SCAN_COUNT = 500;
+const UNLINK_BATCH = 500;
+
+type RedisClient = NonNullable<typeof redis>;
+
+/** Collect every key matching a glob via a non-blocking SCAN stream. */
+async function scanKeys(client: RedisClient, match: string): Promise<string[]> {
+  const keys: string[] = [];
+  const stream = client.scanStream({ match, count: SCAN_COUNT });
+  for await (const batch of stream as AsyncIterable<string[]>) {
+    keys.push(...batch);
+  }
+  return keys;
+}
+
+/** SCAN + UNLINK the keys matching a glob in batches. Returns the count removed. */
+async function clearPattern(client: RedisClient, match: string): Promise<number> {
+  const keys = await scanKeys(client, match);
+  let deleted = 0;
+  for (let i = 0; i < keys.length; i += UNLINK_BATCH) {
+    const batch = keys.slice(i, i + UNLINK_BATCH);
+    if (batch.length > 0) deleted += await client.unlink(...batch);
+  }
+  return deleted;
+}
+
+export async function adminCacheRoute(app: FastifyInstance): Promise<void> {
+  app.addHook("preHandler", async (request, _reply) => {
+    request.adminSession = await requireAdmin(request);
+  });
+
+  // GET /admin/cache — list app-owned cache namespaces with their key counts.
+  app.get("/admin/cache", async () => {
+    if (!redis) return { namespaces: [] };
+
+    const keys: string[] = [];
+    for (const glob of APP_CACHE_GLOBS) {
+      keys.push(...(await scanKeys(redis, glob)));
+    }
+
+    const namespaces = aggregateNamespaces(keys).map((n) => ({
+      namespace: n.namespace,
+      keyCount: n.count,
+    }));
+    return { namespaces };
+  });
+
+  // POST /admin/cache/clear — scoped clear of the app-owned cache prefixes.
+  // Body: { namespace?: string }. Omitted or "all" clears every app prefix.
+  // NEVER runs FLUSHDB/FLUSHALL — an always-on web endpoint must not be able to
+  // wipe a Redis that may be shared with other tenants.
+  app.post<{ Body: { namespace?: unknown } }>("/admin/cache/clear", async (request, reply) => {
+    const raw = request.body?.namespace;
+    if (raw !== undefined && typeof raw !== "string") {
+      return reply.status(400).send({ error: "namespace must be a string" });
+    }
+    const namespace = typeof raw === "string" ? raw.trim() : undefined;
+    const clearAll = !namespace || namespace === "all";
+
+    // Validate a targeted namespace resolves to an app-owned prefix before we do
+    // anything destructive — reject e.g. `*` that would match unrelated keys.
+    if (!clearAll) {
+      const pattern = resolveCachePattern(namespace as string);
+      if (!isAppCachePattern(pattern)) {
+        return reply.status(400).send({
+          error: "namespace must resolve to an app-owned cache prefix (int:* or cache:*)",
+        });
+      }
+    }
+
+    const adminSession = getAdminSession(request);
+    await writeAuditLog({
+      actorId: adminSession.user.id,
+      targetType: "cache",
+      targetId: clearAll ? "all" : (namespace ?? null),
+      action: "cache.clear",
+      details: { namespace: clearAll ? "all" : namespace },
+      request,
+    });
+
+    if (!redis) return { deleted: 0 };
+
+    let deleted = 0;
+    if (clearAll) {
+      for (const glob of APP_CACHE_GLOBS) {
+        deleted += await clearPattern(redis, glob);
+      }
+    } else {
+      deleted = await clearPattern(redis, resolveCachePattern(namespace as string));
+    }
+    return { deleted };
+  });
+}

apps/api/src/server.ts

@@ -20,6 +20,7 @@ import {
 } from "./integration-host";
 import { redis } from "./redis";
 import { adminRoute } from "./routes/admin";
+import { adminCacheRoute } from "./routes/admin-cache";
 import { registerCapabilityBindingRoutes } from "./routes/admin-capability-bindings";
 import { registerAdminComposeRoutes } from "./routes/admin-compose";
 import { registerAdminServiceReposRoutes } from "./routes/admin-service-repos";
@@ -352,6 +353,7 @@ await server.register(adminServicesRoute, { prefix: "/api" });
 await server.register(dataManagerRoute, { prefix: "/api" });
 await server.register(adminSettingsRoute, { prefix: "/api" });
 await server.register(adminStoreRoute, { prefix: "/api" });
+await server.register(adminCacheRoute, { prefix: "/api" });
 await server.register(attributionRoute, { prefix: "/api" });
 await registerCapabilityBindingRoutes(server);
 await registerAdminServiceReposRoutes(server);

apps/api/src/utils/cache-namespaces.ts

@@ -0,0 +1,47 @@
+/**
+ * Cache key-namespace helpers shared with the CLI's `cache list|clear` logic.
+ *
+ * The grouping + glob-resolution logic mirrors `packages/cli/src/commands/cache.ts`
+ * (`aggregateNamespaces` / `resolveCachePattern`). It is copied here rather than
+ * imported because `@openmapx/cli` exposes no library entry point (only a `bin`)
+ * and pulls in `commander`/docker helpers the API must not depend on. Keep the
+ * two in sync: if the app adds a cache prefix, both must learn it.
+ */
+
+/**
+ * App-owned Redis key prefixes. `int:*` = every integration's `ctx.cache`
+ * writes; `cache:*` = the API's own `withCache` keys. The cache admin endpoint
+ * only ever scans/clears these prefixes — it must never touch the rest of a
+ * (possibly shared) Redis database.
+ */
+export const APP_CACHE_PREFIXES = ["int:", "cache:"] as const;
+
+/**
+ * Turn a `cache clear` target into a Redis key glob. A bare word is treated as
+ * an integration namespace (`geocoding` → `int:geocoding:*`); anything already
+ * containing a `*` is passed through verbatim.
+ */
+export function resolveCachePattern(target: string): string {
+  return target.includes("*") ? target : `int:${target}:*`;
+}
+
+/**
+ * Group Redis keys by namespace (everything up to the last `:` segment) with a
+ * count each, sorted by count desc then name.
+ */
+export function aggregateNamespaces(keys: string[]): Array<{ namespace: string; count: number }> {
+  const counts = new Map<string, number>();
+  for (const key of keys) {
+    const idx = key.lastIndexOf(":");
+    const namespace = idx === -1 ? key : key.slice(0, idx);
+    counts.set(namespace, (counts.get(namespace) ?? 0) + 1);
+  }
+  return [...counts.entries()]
+    .map(([namespace, count]) => ({ namespace, count }))
+    .sort((a, b) => b.count - a.count || a.namespace.localeCompare(b.namespace));
+}
+
+/** True when a resolved glob targets one of the app-owned cache prefixes. */
+export function isAppCachePattern(pattern: string): boolean {
+  return APP_CACHE_PREFIXES.some((prefix) => pattern.startsWith(prefix));
+}

apps/web/src/app/admin/cache/page.tsx

@@ -0,0 +1,8 @@
+import type { Metadata } from "next";
+import { CacheManager } from "@/components/admin/cache/CacheManager";
+
+export const metadata: Metadata = { title: "Cache — Admin — OpenMapX" };
+
+export default function AdminCachePage() {
+  return <CacheManager />;
+}