diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 7b9cd24a..2c23ff74 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -818,6 +818,14 @@ window.__TENANT_CONFIG__ = { id: "vocalstar", branding: { ... }, features: { ... The frontend's `TenantProvider` reads `window.__TENANT_CONFIG__` on startup (no API round-trip needed for initial render). This approach works for both custom domains (`vocalstar.nomadkaraoke.com`) and the shared tenant portal domain. +**Edge config cache** (`frontend/lib/edge/tenantConfigCache.ts`, v0.268.6). The edge cache works as stale-while-revalidate: +- A config fetched under 5 minutes ago is served as is. +- An older copy is still served, and a background refresh runs via `waitUntil`. Copies are kept up to 7 days. +- A colo that has never cached the tenant waits on `/api/tenant/config` for at most 3s. On timeout or error the HTML goes out without injection, and `TenantProvider` fetches the config itself. +- Concurrent misses in one isolate share a single backend fetch. + +Before this, a crawler loading 17 portal pages at once caused 17 simultaneous cache misses. Cloud Run spawned 5 cold instances, and the HTML waited 15-17s (2026-10-13). Branding changes still reach the edge within about 5 minutes, plus one page view to trigger the refresh. + **Magic link emails**: When a tenant user requests a magic link, the email uses the tenant-specific URL (e.g., `https://vocalstar.nomadkaraoke.com/auth/verify?token=...`) rather than the main app URL. The `job_notification_service.py` resolves the correct base URL from the tenant config's `subdomain` field. **Admin preview**: Admins can preview any tenant's branding in the main app by appending `?preview_tenant=` to any URL. This bypasses subdomain detection and loads the specified tenant config, useful for verifying branding before DNS cutover. diff --git a/frontend/__tests__/edge-tenant-config-cache.test.ts b/frontend/__tests__/edge-tenant-config-cache.test.ts new file mode 100644 index 00000000..3a4d611f --- /dev/null +++ b/frontend/__tests__/edge-tenant-config-cache.test.ts @@ -0,0 +1,155 @@ +/** + * @jest-environment node + */ +import { + getTenantConfig, + _resetInFlightForTests, + FRESH_SECONDS, + type TenantConfigResponse, +} from "@/lib/edge/tenantConfigCache" + +const CONFIG: TenantConfigResponse = { + tenant: { + id: "singa", + name: "Singa", + subdomain: "singa", + is_active: true, + branding: { + primary_color: "#ff0000", + secondary_color: "#00ff00", + accent_color: null, + background_color: null, + favicon_url: null, + site_title: "Singa", + }, + }, + is_default: false, +} + +class MemCache { + store = new Map() + async match(key: string) { + const r = this.store.get(key) + return r ? r.clone() : undefined + } + async put(key: string, r: Response) { + this.store.set(key, r) + } +} + +function setup(fetchImpl?: jest.Mock) { + const cache = new MemCache() + const fetchFn = + fetchImpl ?? + jest.fn(async () => new Response(JSON.stringify(CONFIG), { status: 200 })) + const background: Promise[] = [] + let now = 1_000_000 + const deps = { + cache, + fetchFn: fetchFn as unknown as typeof fetch, + waitUntil: (p: Promise) => { + background.push(p) + }, + now: () => now, + } + return { cache, fetchFn, background, deps, advance: (ms: number) => (now += ms) } +} + +const KEY = "https://singa.nomadkaraoke.com/__tenant_config__/singa" + +beforeEach(() => _resetInFlightForTests()) + +describe("getTenantConfig (edge stale-while-revalidate)", () => { + it("fetches on a cold miss and caches the result", async () => { + const { fetchFn, cache, deps } = setup() + expect(await getTenantConfig("singa", KEY, deps)).toEqual(CONFIG) + expect(fetchFn).toHaveBeenCalledTimes(1) + expect(cache.store.has(KEY)).toBe(true) + }) + + it("serves a fresh cache hit without touching the backend", async () => { + const { fetchFn, deps, background, advance } = setup() + await getTenantConfig("singa", KEY, deps) + advance(60_000) + expect(await getTenantConfig("singa", KEY, deps)).toEqual(CONFIG) + expect(fetchFn).toHaveBeenCalledTimes(1) + expect(background).toHaveLength(0) + }) + + it("serves a stale hit immediately and refreshes in the background", async () => { + const { fetchFn, deps, background, advance } = setup() + await getTenantConfig("singa", KEY, deps) + advance((FRESH_SECONDS + 1) * 1000) + expect(await getTenantConfig("singa", KEY, deps)).toEqual(CONFIG) + expect(background).toHaveLength(1) + await Promise.all(background) + expect(fetchFn).toHaveBeenCalledTimes(2) + }) + + it("collapses a burst of concurrent cold misses into one backend call", async () => { + let release!: () => void + const gate = new Promise((r) => (release = r)) + const fetchFn = jest.fn(async () => { + await gate + return new Response(JSON.stringify(CONFIG), { status: 200 }) + }) + const { deps } = setup(fetchFn) + const burst = Array.from({ length: 17 }, () => getTenantConfig("singa", KEY, deps)) + release() + const results = await Promise.all(burst) + expect(results.every((r) => r?.tenant?.id === "singa")).toBe(true) + expect(fetchFn).toHaveBeenCalledTimes(1) + }) + + it("returns null on a backend error so the HTML is served uninjected", async () => { + const fetchFn = jest.fn(async () => new Response("nope", { status: 503 })) + const { deps, cache } = setup(fetchFn) + expect(await getTenantConfig("singa", KEY, deps)).toBeNull() + expect(cache.store.has(KEY)).toBe(false) + }) + + it("does not cache a malformed 200 payload", async () => { + const fetchFn = jest.fn( + async () => new Response(JSON.stringify({ tenant: { id: "singa" }, is_default: false }), { status: 200 }) + ) + const { deps, cache } = setup(fetchFn) + expect(await getTenantConfig("singa", KEY, deps)).toBeNull() + expect(cache.store.has(KEY)).toBe(false) + }) + + it("passes a timeout signal so a cold backend can't hold the page", async () => { + const { fetchFn, deps } = setup() + await getTenantConfig("singa", KEY, deps) + const init = (fetchFn.mock.calls[0] as unknown[])[1] as RequestInit + expect(init.signal).toBeInstanceOf(AbortSignal) + }) + + it("returns null when the fetch aborts (timeout)", async () => { + const fetchFn = jest.fn(async () => { + throw new DOMException("The operation timed out.", "TimeoutError") + }) + const { deps } = setup(fetchFn) + expect(await getTenantConfig("singa", KEY, deps)).toBeNull() + }) + + it("keeps serving the stale copy when the background refresh fails", async () => { + const responses = [ + new Response(JSON.stringify(CONFIG), { status: 200 }), + new Response("down", { status: 500 }), + ] + const fetchFn = jest.fn(async () => responses.shift()!) + const { deps, background, advance } = setup(fetchFn) + await getTenantConfig("singa", KEY, deps) + advance((FRESH_SECONDS + 1) * 1000) + await getTenantConfig("singa", KEY, deps) + await Promise.all(background) + expect(await getTenantConfig("singa", KEY, deps)).toEqual(CONFIG) + }) + + it("treats entries without a fetched-at stamp (pre-deploy cache) as stale", async () => { + const { cache, deps, background } = setup() + await cache.put(KEY, new Response(JSON.stringify(CONFIG))) + expect(await getTenantConfig("singa", KEY, deps)).toEqual(CONFIG) + expect(background).toHaveLength(1) + }) +}) diff --git a/frontend/functions/[[path]].ts b/frontend/functions/[[path]].ts index a57f56ac..6dec8050 100644 --- a/frontend/functions/[[path]].ts +++ b/frontend/functions/[[path]].ts @@ -10,30 +10,7 @@ * Non-HTML requests (JS, CSS, images) pass through unmodified. */ -interface TenantBranding { - primary_color: string - secondary_color: string - accent_color: string | null - background_color: string | null - favicon_url: string | null - site_title: string -} - -interface TenantPublicConfig { - id: string - name: string - subdomain: string - is_active: boolean - branding: TenantBranding -} - -interface TenantConfigResponse { - tenant: TenantPublicConfig | null - is_default: boolean -} - -const API_BASE_URL = "https://api.nomadkaraoke.com" -const CACHE_TTL_SECONDS = 300 // 5 minutes +import { getTenantConfig } from "../lib/edge/tenantConfigCache" /** * Compute a contrasting foreground color (black or white) for a given hex color. @@ -71,60 +48,6 @@ function extractTenantFromHost(hostname: string): string | null { return null } -/** - * Fetch tenant config from backend with Cloudflare Cache API caching. - */ -async function fetchTenantConfigCached( - tenantId: string, - cacheKey: string -): Promise { - // Try cache first - const cache = caches.default - const cachedResponse = await cache.match(cacheKey) - if (cachedResponse) { - try { - return await cachedResponse.json() - } catch { - // Cache corrupted, proceed to fetch - } - } - - // Fetch from backend - try { - const response = await fetch( - `${API_BASE_URL}/api/tenant/config?tenant=${encodeURIComponent(tenantId)}`, - { - headers: { - "Content-Type": "application/json", - "X-Tenant-ID": tenantId, - }, - } - ) - - if (!response.ok) { - console.error(`Tenant config fetch failed: ${response.status}`) - return null - } - - const data: TenantConfigResponse = await response.json() - - // Cache the response - const cacheResponse = new Response(JSON.stringify(data), { - headers: { - "Content-Type": "application/json", - "Cache-Control": `s-maxage=${CACHE_TTL_SECONDS}`, - }, - }) - // Don't await — fire-and-forget cache put - cache.put(cacheKey, cacheResponse) - - return data - } catch (err) { - console.error("Failed to fetch tenant config:", err) - return null - } -} - /** * Escape a string for safe injection into an HTML or