From 932908620e8df9fd97f7b2997199313309186b9a Mon Sep 17 00:00:00 2001 From: Connor Tsui Date: Thu, 16 Jul 2026 13:12:09 -0400 Subject: [PATCH] docs(web): clarify CDN stale cache windows --- web/README.md | 40 ++++++++++++++++++++++------------------ 1 file changed, 22 insertions(+), 18 deletions(-) diff --git a/web/README.md b/web/README.md index 870efa3..2f3849e 100644 --- a/web/README.md +++ b/web/README.md @@ -25,25 +25,26 @@ configured. Keep it that way; the CI `test` job builds with no database on purpo Connection config is read by `lib/db.ts`: -| Variable | Required | Meaning | -|---|---|---| -| `BENCH_DB_HOST` | yes | Postgres host. | -| `BENCH_DB_NAME` | yes | Database name. | -| `BENCH_DB_USER` | yes | Role to connect as. | -| `BENCH_DB_PORT` | no (5432) | Port. | -| `BENCH_DB_PASSWORD` | no | Static password. When unset, each new connection authenticates with a freshly minted RDS IAM token instead. | -| `BENCH_DB_REGION` | for IAM | AWS region for the RDS IAM signer; required when no password is set. IAM token signing also needs AWS credentials in the runtime environment. | -| `BENCH_DB_SSL` | no (`verify-full`) | `verify-full` validates the certificate chain and hostname; `disable` is for local non-TLS containers only. Any other value fails loudly. | -| `BENCH_DB_CA` | prod | PEM contents of the Amazon RDS CA bundle; Node's trust store does not include the RDS roots, so `verify-full` against RDS fails without it. | -| `BENCH_DB_POOL_MAX` | no (8) | Max pool connections per serverless instance; the per-render summary fan-out (`SUMMARY_CONCURRENCY`) is sized to this default. | +| Variable | Required | Meaning | +| ------------------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- | +| `BENCH_DB_HOST` | yes | Postgres host. | +| `BENCH_DB_NAME` | yes | Database name. | +| `BENCH_DB_USER` | yes | Role to connect as. | +| `BENCH_DB_PORT` | no (5432) | Port. | +| `BENCH_DB_PASSWORD` | no | Static password. When unset, each new connection authenticates with a freshly minted RDS IAM token instead. | +| `BENCH_DB_REGION` | for IAM | AWS region for the RDS IAM signer; required when no password is set. IAM token signing also needs AWS credentials in the runtime environment. | +| `BENCH_DB_SSL` | no (`verify-full`) | `verify-full` validates the certificate chain and hostname; `disable` is for local non-TLS containers only. Any other value fails loudly. | +| `BENCH_DB_CA` | prod | PEM contents of the Amazon RDS CA bundle; Node's trust store does not include the RDS roots, so `verify-full` against RDS fails without it. | +| `BENCH_DB_POOL_MAX` | no (8) | Max pool connections per serverless instance; the per-render summary fan-out (`SUMMARY_CONCURRENCY`) is sized to this default. | ## CDN caching -The read paths serve traffic through Vercel's CDN with a five-minute freshness window, matching -the v2 site's S3 refresh cadence: +The read paths serve traffic through Vercel's CDN with a five-minute fresh window, matching +the v2 site's S3 refresh cadence, plus bounded stale-while-revalidate windows for low-traffic +warmth: - The data routes (`/api/groups`, `/api/group/*`, `/api/chart/*`) set - `Cache-Control: public, s-maxage=300, stale-while-revalidate=300` on success responses + `Cache-Control: public, s-maxage=300, stale-while-revalidate=3600` on success responses (`lib/cache.ts`); error responses omit the header so they are never CDN-cached. `/api/health` is deliberately uncached so the liveness probe always reflects the live database. - The HTML pages (`/` and `/chart/:slug`) cannot set response headers from a server component, @@ -53,15 +54,18 @@ the v2 site's S3 refresh cadence: precedence, so the CDN caches the rendered pages while browsers still revalidate every load. Verify on a live deployment with `curl -sI | grep -i x-vercel-cache` (expect `MISS` then -`HIT` within five minutes). The deploy workflow runs this probe automatically after each deploy. +`HIT` within the five-minute fresh window). The deploy workflow runs this probe automatically after +each deploy. When deployment protection returns 401/403 on a deployment URL the probe skips with a notice; production avoids that blind spot automatically once `BENCHMARKS_WEB_PROD_URL` is set (the probe then targets the public domain, where a 401/403 fails the run instead), so the manual check is only needed for protected previews and for production while the var is unset. One deliberate divergence from the API routes: the `vercel.json` header rules apply to every response status, -so an unknown `/chart/:slug` 404 can be CDN-cached for up to five minutes, which stays within -the site's five-minute staleness budget (transient 5xx responses are believed not CDN-cacheable -by Vercel; if one ever were, the same five-minute budget would bound it). +so an unknown `/chart/:slug` 404 follows the HTML page rule: five minutes fresh and then eligible +for Vercel's one-day stale-while-revalidate window. That is acceptable for opaque, never-linked +malformed/unknown chart URLs, while real chart pages refresh on the same five-minute fresh cadence +as the landing page (transient 5xx responses are believed not CDN-cacheable by Vercel; if one ever +were, the same HTML page rule would bound it). ## Deploys