mirror of
https://github.com/nomadkaraoke/karaoke-gen.git
synced 2026-11-20 13:07:57 +09:00
## Summary This follows up #1140. While investigating the stall-alert flapping, I found that 18 of the 28 requests that were the first on a new autoscaled instance (each ≥10s) over 4 days came from the tenant portal's Pages Function. Each one was `/api/tenant/config?tenant=…` with no user agent. At 03:55 UTC, something loaded 17 `singa.nomadkaraoke.com` pages at once. All 17 missed the 5-minute edge cache in the same second and called the API. Cloud Run spawned 5 cold instances, and those HTML responses waited 15–17s. ## Changes New `frontend/lib/edge/tenantConfigCache.ts`, used by `functions/[[path]].ts`: - **Stale-while-revalidate:** - Under 5 minutes old, the cached config is served as is. - Older than that, the stale copy is still served and refreshed in the background via `waitUntil`. Copies are stored for 7 days. - Entries cached before this deploy have no timestamp, so they are treated as stale. - **Bounded cold miss:** the backend fetch has a 3s `AbortSignal.timeout`. On timeout or error the HTML is served without injection, and `TenantProvider` falls back to fetching the config client-side, as it already did. - **Single flight:** concurrent misses in one isolate share one fetch. - **Payload shape check:** a malformed 200 response isn't cached for a week. This came from a CodeRabbit finding. Other changes: - `jest.setup.js` guards the `window.matchMedia` mock so `@jest-environment node` tests can run. It's a no-op for jsdom tests. - `docs/ARCHITECTURE.md` has a new section on the edge config cache. **Trade-off:** a branding change now reaches each colo on the first page view after 5 minutes, and that view still shows the old branding. Before, it showed up on the first view after expiry. ## Testing - 10 new Jest tests (node environment): - cold miss; - fresh hit; - stale hit with background refresh; - a 17-request burst makes one fetch; - 503 and timeout return null; - a failed refresh keeps the stale copy; - an entry without a timestamp is treated as stale; - a malformed payload isn't cached. - `wrangler pages functions build` compiles the bundle. - `make test`: all passed. - Local CodeRabbit review: 1 finding, fixed. @coderabbitai ignore 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01DTfrTaaZQfXUUduAhZpLeq Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
145 lines
4.6 KiB
TypeScript
145 lines
4.6 KiB
TypeScript
/**
|
|
* Edge (Cloudflare Pages Function) cache for the tenant portal's config.
|
|
*
|
|
* Stale-while-revalidate: a cached config is served even when older than
|
|
* FRESH_SECONDS, and refreshed in the background. A request only waits on the
|
|
* backend when its colo has never cached the tenant, and then for at most
|
|
* FETCH_TIMEOUT_MS (the client fetches the config itself if it isn't injected).
|
|
*
|
|
* Why (2026-10-13): with a plain 5-min TTL, a crawler loading 17 portal pages at
|
|
* once missed the cache 17 times in the same second. That burst made Cloud Run
|
|
* spawn 5 cold API instances, and the HTML responses waited 15-17s on them.
|
|
*/
|
|
|
|
export interface TenantConfigResponse {
|
|
tenant: {
|
|
id: string
|
|
name: string
|
|
subdomain: string
|
|
is_active: boolean
|
|
branding: {
|
|
primary_color: string
|
|
secondary_color: string
|
|
accent_color: string | null
|
|
background_color: string | null
|
|
favicon_url: string | null
|
|
site_title: string
|
|
}
|
|
} | null
|
|
is_default: boolean
|
|
}
|
|
|
|
export const FRESH_SECONDS = 300 // refresh in the background after 5 minutes
|
|
export const STORE_SECONDS = 7 * 24 * 3600 // keep a stale copy for a week
|
|
export const FETCH_TIMEOUT_MS = 3000
|
|
const FETCHED_AT_HEADER = "X-Fetched-At"
|
|
|
|
interface EdgeCache {
|
|
match(key: string): Promise<Response | undefined>
|
|
put(key: string, response: Response): Promise<void>
|
|
}
|
|
|
|
export interface TenantConfigDeps {
|
|
cache: EdgeCache
|
|
fetchFn: typeof fetch
|
|
waitUntil: (p: Promise<unknown>) => void
|
|
now?: () => number
|
|
apiBaseUrl?: string
|
|
}
|
|
|
|
/** Minimal shape check — a malformed 200 must not be cached for a week. */
|
|
function isTenantConfig(data: unknown): data is TenantConfigResponse {
|
|
if (!data || typeof data !== "object") return false
|
|
const d = data as { tenant?: unknown; is_default?: unknown }
|
|
if (typeof d.is_default !== "boolean") return false
|
|
if (d.tenant === null) return true
|
|
const t = d.tenant as { id?: unknown; branding?: { primary_color?: unknown; secondary_color?: unknown } } | undefined
|
|
return (
|
|
!!t &&
|
|
typeof t.id === "string" &&
|
|
typeof t.branding?.primary_color === "string" &&
|
|
typeof t.branding?.secondary_color === "string"
|
|
)
|
|
}
|
|
|
|
// Concurrent misses inside one isolate share a single backend fetch.
|
|
const inFlight = new Map<string, Promise<TenantConfigResponse | null>>()
|
|
|
|
async function fetchAndStore(
|
|
tenantId: string,
|
|
cacheKey: string,
|
|
deps: TenantConfigDeps
|
|
): Promise<TenantConfigResponse | null> {
|
|
const existing = inFlight.get(cacheKey)
|
|
if (existing) return existing
|
|
|
|
const now = deps.now ?? Date.now
|
|
const base = deps.apiBaseUrl ?? "https://api.nomadkaraoke.com"
|
|
const p = (async () => {
|
|
try {
|
|
const response = await deps.fetchFn(
|
|
`${base}/api/tenant/config?tenant=${encodeURIComponent(tenantId)}`,
|
|
{
|
|
headers: { "Content-Type": "application/json", "X-Tenant-ID": tenantId },
|
|
signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
|
|
}
|
|
)
|
|
if (!response.ok) {
|
|
console.error(`Tenant config fetch failed: ${response.status}`)
|
|
return null
|
|
}
|
|
const data: unknown = await response.json()
|
|
if (!isTenantConfig(data)) {
|
|
console.error("Tenant config fetch returned an unexpected payload")
|
|
return null
|
|
}
|
|
await deps.cache.put(
|
|
cacheKey,
|
|
new Response(JSON.stringify(data), {
|
|
headers: {
|
|
"Content-Type": "application/json",
|
|
"Cache-Control": `s-maxage=${STORE_SECONDS}`,
|
|
[FETCHED_AT_HEADER]: String(now()),
|
|
},
|
|
})
|
|
)
|
|
return data
|
|
} catch (err) {
|
|
console.error("Failed to fetch tenant config:", err)
|
|
return null
|
|
} finally {
|
|
inFlight.delete(cacheKey)
|
|
}
|
|
})()
|
|
inFlight.set(cacheKey, p)
|
|
return p
|
|
}
|
|
|
|
export async function getTenantConfig(
|
|
tenantId: string,
|
|
cacheKey: string,
|
|
deps: TenantConfigDeps
|
|
): Promise<TenantConfigResponse | null> {
|
|
const now = deps.now ?? Date.now
|
|
const cached = await deps.cache.match(cacheKey)
|
|
if (cached) {
|
|
try {
|
|
const fetchedAt = Number(cached.headers.get(FETCHED_AT_HEADER) || 0)
|
|
const data: TenantConfigResponse = await cached.json()
|
|
if (!fetchedAt || now() - fetchedAt > FRESH_SECONDS * 1000) {
|
|
// Stale (or written before this header existed): serve it, refresh behind.
|
|
deps.waitUntil(fetchAndStore(tenantId, cacheKey, deps))
|
|
}
|
|
return data
|
|
} catch {
|
|
// Corrupted cache entry — fall through to a fetch.
|
|
}
|
|
}
|
|
return fetchAndStore(tenantId, cacheKey, deps)
|
|
}
|
|
|
|
/** Test helper: forget in-flight fetches between tests. */
|
|
export function _resetInFlightForTests(): void {
|
|
inFlight.clear()
|
|
}
|