[vidiecan]

Change set

Opt-in endpoint that lists what each Node process holds in its SSR page caches (bot + anonymous): entry count vs limit, stale count, HTML bytes per entry, remaining TTL, process RSS/heap. GET /app/cache-stats → JSON.

Config cache.serverSide.stats (env DSPACE_CACHE_SERVERSIDE_STATS_ENABLED / _PORT), default enabled: false:

• port: 0 → served by the Express app on the UI port next to /app/health, only to requests made directly on the host: loopback socket address (req.socket.remoteAddress, not req.ip, because trust proxy honours a spoofable X-Forwarded-For) and none of Forwarded, Via, X-Real-IP or any X-Forwarded-*, so traffic relayed by a same-host reverse proxy is refused too. Everyone else falls through to the catch-all route via next(), so the response is byte-identical to an unknown path. Residual risk: a same-host proxy that adds none of those headers; the config comment says to use a port there. Under pm2 cluster mode an arbitrary worker answers.
• port: N → a separate http server bound to 127.0.0.1:N + NODE_APP_INSTANCE, so each of the 7 pm2 workers in docker/dspace-ui.json is addressable. An invalid port (incl. a YAML string), a clash with the UI port or a failed bind (EADDRINUSE) is logged and does not stop the UI.

src/backend/ssr-cache-stats.ts: snapshot via LRU.dump() (includes expired entries that still occupy memory when allowStale: false; forEach would skip them), has() marks stale; no recency/TTL side effects. Non-GET → 404. botCache / anonymousCache typed LRU<string, SsrCacheEntry> instead of any.

Test: scripts/test-ssr-cache-stats.js (node --test), wired as yarn run test:ssr-cache-stats and a CI step after lint.

Out of scope: aggregating across workers, auth.

Test evidence

yarn run test:ssr-cache-stats     # 7/7 pass (snapshot order/TTL, stale with allowStale:false, no-cache, routes incl. ?query/HEAD/trailing slash, 500 when the snapshot throws, direct-loopback check incl. every proxy header, EADDRINUSE on error event)
yarn run lint --quiet             # All files pass linting
npx madge ... --circular          # No circular dependency found
tsc -p tsconfig.server.json       # 0 errors in project files
tsc -p tsconfig.spec.json         # 0 errors (environment.test.ts carries the new key; the karma suite itself was not run locally)
yarn run build:ssr                # exit 0

node dist/server/main (NODE_ENV=production), three runs:

# A) STATS_ENABLED=true STATS_PORT=0, UI bound to 0.0.0.0:4199
GET http://127.0.0.1:4199/app/cache-stats                  -> 200 application/json {"host":"jm","pid":26080,"instance":0,...,"caches":[...]}
GET http://192.168.88.32:4199/app/cache-stats              -> 404 (LAN address)
same + "X-Forwarded-For: 127.0.0.1"                        -> 404 (spoof ignored)
loopback + X-Forwarded-For / X-Real-IP / Via / Forwarded   -> 404 each (same-host proxy traffic refused)

# B) STATS_ENABLED=true STATS_PORT=4101, NODE_APP_INSTANCE=2
log: "SSR cache stats listening at http://127.0.0.1:4103/app/cache-stats"
GET http://127.0.0.1:4103/app/cache-stats                  -> 200 {"instance":2,...}
GET http://127.0.0.1:4198/app/cache-stats (UI port)        -> normal Angular SSR page (<ds-app>), no stats
second process with STATS_PORT clashing                    -> "SSR cache stats server not started on port 4103: listen EADDRINUSE ..." and the UI still starts

# C) default (enabled: false)
no "cache stats" line in the log; GET /app/cache-stats on the UI port -> normal Angular SSR page

Local Node 24; CI matrix (18/20) covers node --test + global fetch.

Notes / assumptions

• Snapshot cost is O(total cached HTML) per request, synchronous on the SSR event loop. Fine for an operator hitting it by hand; don't poll it every second.
• In Docker: docker exec <ui> wget -qO- http://127.0.0.1:<port>/app/cache-stats.
• Shutdown of the separate server uses server.close(); http-terminator was not used because its bundled @types/node (24.x) clashes with the project's 14.x http.Server type on the explicitly typed stats server.