Refs: docs/reviews/2026-11-03-maturity-review/README.md 09-01 09-02 09-05 09-07~09-10 08-02~08-04
213 lines
11 KiB
Markdown
213 lines
11 KiB
Markdown
# Release, cache, and rollback contract
|
|
|
|
Each deployment is an immutable `releases/<releaseId>/` artifact set. The
|
|
provider adapter must upload assets, release manifest, runtime config, and
|
|
verify asset reachability before atomically switching the active HTML pointer.
|
|
The post-switch boot, route, API, telemetry, and reload-loop smoke checks close
|
|
the deployment.
|
|
|
|
Rollback selects a prior release tuple, confirms its assets and runtime/API
|
|
compatibility, atomically switches the complete set, performs the provider
|
|
cache action, and repeats the smoke checks. Rebuilding an old commit, replacing
|
|
HTML alone, or declaring recovery from cache-purge completion is prohibited.
|
|
Recovery is established by old/new reachability probes.
|
|
|
|
Before deploying a promoted release later, or rolling back to one, re-verify
|
|
its promoted bundle (the five files uploaded by the `promotion` job) with the
|
|
archived mode (review 13-04). Provider evidence expires two hours after issue,
|
|
so the normal mode refuses any release promoted before that. The archived mode
|
|
still checks signatures, digests and the exact five members, and judges
|
|
freshness at the release's recorded promotion time
|
|
(`promotion-verification.json` `verifiedAt`, which may not lie in the future).
|
|
New promotion never uses it (`scripts/lib/exact-promotion-bundle.ts`).
|
|
|
|
```bash
|
|
VULNERABILITY_PUBLIC_KEY_PATH=... VULNERABILITY_KEY_ID=... \
|
|
PROVENANCE_PUBLIC_KEY_PATH=... PROVENANCE_KEY_ID=... \
|
|
EXPECTED_PROMOTION_RUN_ID=<run id> EXPECTED_PROMOTION_RUN_ATTEMPT=<attempt> \
|
|
EXPECTED_PROMOTION_SOURCE_REVISION=<commit> \
|
|
EXPECTED_PROMOTION_ARCHIVE_SHA256=<archive sha256> \
|
|
corepack pnpm verify:promotion -- --root <promoted bundle directory> --archived
|
|
|
|
mkdir <release dir> && tar -xzf <promoted bundle directory>/release-candidate.tar.gz -C <release dir>
|
|
corepack pnpm drill:runbook -- FE-RB-005 --release-root <release dir>
|
|
```
|
|
|
|
The expected values come from the release record, not from the bundle. The
|
|
drill then checks that release's build/config/manifest tuple and its assets,
|
|
not the local build. It ends `UNVERIFIED` until the provider switch and smoke
|
|
are recorded, because those happen outside this repository.
|
|
|
|
The provider-independent cache defaults are:
|
|
|
|
- hashed assets: `public, max-age=31536000, immutable`
|
|
- HTML: `no-cache`
|
|
- app routes: the router uses browser history, so every path the build has
|
|
no file for (a reload, a bookmark, a shared link) is answered with the
|
|
release's `index.html` and the HTML headers (SPA fallback). A missing
|
|
hashed asset stays a 404; it never falls back to HTML
|
|
- runtime config and release manifest: `no-store`
|
|
- public source maps: disabled
|
|
- service worker/offline cache: disabled, unless the static selection in
|
|
`src/features/product-capabilities.ts` is `ACTIVE` or
|
|
`REMOVE_REGISTRATION`; then `dist` holds exactly the selected
|
|
`service-worker.js`, served `no-cache` so the browser's update check sees
|
|
each release's worker
|
|
|
|
HTML, JSON config/manifest, and hashed JavaScript MIME types are also compared
|
|
to the declared allowlist; a cache-correct response with a mismatched
|
|
`Content-Type` still fails the hosting gate.
|
|
|
|
`corepack pnpm verify:hosting-headers` compares the declared headers with a
|
|
deterministic fixture when `HOSTING_BASE_URL` is unset. That only shows the
|
|
declarations agree with each other, so its result is `UNVERIFIED` (exit 3), not
|
|
`PASS` (review 13-05, `scripts/lib/hosting-probe.ts` `hostingVerdict`). Only
|
|
`mode: "live"` can pass. The live target must be its canonical, non-loopback
|
|
HTTPS root URL. Each required surface must return HTTP 200 without leaving that
|
|
origin before its cache, content-type, and security headers can count as
|
|
deployment evidence. The hashed asset it requests is the entry script named by
|
|
the served `index.html`, so it checks the release that is actually deployed.
|
|
It also requests `appRoute` (`/__probe/deep-link`, a path no build has a file
|
|
for): the host must answer 200 with the same `index.html` (the same entry
|
|
script) and the HTML headers, so a host without the SPA fallback fails
|
|
(review 1101/13-04). When the build ships a worker it requests
|
|
`/service-worker.js` and expects `no-cache`. The surfaces and their headers are
|
|
declared in `config/hosting/cache-policy.json`. For each cacheable extension the
|
|
release has under `assets/` (`.css`, `.js`, `.woff2` and the rest of
|
|
`CACHEABLE_ASSET_CONTENT_TYPES`) it requests the first such file and expects
|
|
exactly that type (`hashedAsset.css` and so on). The worker's install refuses
|
|
the whole release when one precached asset has another type, while a page
|
|
still uses a font served as `application/octet-stream` (review 1103/06-03).
|
|
|
|
The served `release-manifest.json` must name the `buildId` and `releaseId` of
|
|
the release being checked: correct headers on an earlier release are not
|
|
evidence for this one (review 1101/13-01). That release is
|
|
`<release-root>/dist` with `-- --release-root <extracted archive>` (FE-GATE-019
|
|
passes the promoted archive), otherwise the local `dist`.
|
|
|
|
### Example: nginx on a single server
|
|
|
|
Written by hand for the default base path `/`; nothing in CI runs it. The live
|
|
probe above is what checks the host. `add_header` in a `location` replaces the
|
|
ones inherited from `server`, so the security headers
|
|
(`config/hosting/security-headers.json`) are an include repeated in each block.
|
|
|
|
```nginx
|
|
# /etc/nginx/snippets/frontend-security-headers.conf
|
|
add_header Content-Security-Policy "default-src 'self'; base-uri 'self'; object-src 'none'; frame-ancestors 'none'; form-action 'self'; script-src 'self'; style-src 'self'; img-src 'self' data:; connect-src 'self' https:; font-src 'self'; upgrade-insecure-requests" always;
|
|
add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
|
|
add_header X-Frame-Options "DENY" always;
|
|
add_header Referrer-Policy "strict-origin-when-cross-origin" always;
|
|
add_header X-Content-Type-Options "nosniff" always;
|
|
add_header Permissions-Policy "camera=(), microphone=(), geolocation=()" always;
|
|
```
|
|
|
|
```nginx
|
|
server {
|
|
listen 443 ssl;
|
|
server_name app.example.com;
|
|
# ssl_certificate / ssl_certificate_key ...
|
|
|
|
# The active release directory. Switch it with an atomic symlink rename.
|
|
root /srv/frontend/current;
|
|
|
|
# index.html, and every app route through the fallback below.
|
|
location = /index.html {
|
|
add_header Cache-Control "no-cache";
|
|
include snippets/frontend-security-headers.conf;
|
|
}
|
|
location / {
|
|
try_files $uri /index.html;
|
|
include snippets/frontend-security-headers.conf;
|
|
}
|
|
|
|
location = /config.json {
|
|
add_header Cache-Control "no-store";
|
|
include snippets/frontend-security-headers.conf;
|
|
}
|
|
location = /release-manifest.json {
|
|
add_header Cache-Control "no-store";
|
|
include snippets/frontend-security-headers.conf;
|
|
}
|
|
|
|
# Hashed files of every retained release in one directory (names never
|
|
# collide). Prune by age, not on switch. A missing chunk is a 404, never
|
|
# index.html: an old tab has to see the failure to reload once (FE-RB-002).
|
|
location /assets/ {
|
|
root /srv/frontend/shared;
|
|
add_header Cache-Control "public, max-age=31536000, immutable";
|
|
try_files $uri =404;
|
|
}
|
|
|
|
# Only when the build ships a worker (cache-policy.json `serviceWorker`).
|
|
location = /service-worker.js {
|
|
add_header Cache-Control "no-cache";
|
|
try_files $uri =404;
|
|
}
|
|
|
|
location ~ \.map$ {
|
|
return 404;
|
|
}
|
|
}
|
|
```
|
|
|
|
`Cache-Control` has no `always`, so a 404 is never stored as immutable.
|
|
|
|
FE-GATE-019 is therefore a production-stage gate (`production_gate` job,
|
|
`PROD_PROMOTION_READY`). It runs after `promotion` and after the `deployment`
|
|
job. That job is the project's deployment slot and is empty in this
|
|
repository: uploading the release, switching the active pointer, and the
|
|
post-switch smoke are the project's provider adapter, chosen with the hosting
|
|
provider. While the slot is empty FE-GATE-019 does not probe the host and ends
|
|
`UNVERIFIED`. How to fill it is in
|
|
[`ci-quality-gates.md`](ci-quality-gates.md) (review 1101/13-01).
|
|
|
|
Keep a retired release's hashed assets reachable while any open tab may still
|
|
request them. The minimum is the previous release while the next one is
|
|
active (the rolling window modeled in `tests/release/release-fixture.ts`).
|
|
Size it to the longest session the product supports; a tab older than that
|
|
depends on the reload-once recovery (FE-RB-002).
|
|
|
|
## Service Worker steps (only when the static selection is not `null`)
|
|
|
|
The worker is part of the release tuple: `service-worker.js` comes from the
|
|
same build as the HTML and assets it caches.
|
|
|
|
1. **Rollback N+1 → N.** Switching the tuple serves N's `service-worker.js`.
|
|
The browser's update check installs it; the worker never calls
|
|
`skipWaiting()` on install (`src/adapters/service-worker/service-worker-entry.ts`),
|
|
so it waits until every tab of the scope closes or a page calls
|
|
`requestActivation()`. The template has no page that calls it. The cache
|
|
name is the asset-set digest, so if N's cache is still there as the
|
|
retained previous cache, the install reuses it and never deletes it on
|
|
failure (`service-worker-static-assets.ts` `installStaticAssets`). Tabs still on N+1 keep worker N+1, so N+1's assets
|
|
stay reachable for the rolling window above. Only activation deletes owned
|
|
caches (current plus the highest-marked previous one). While a worker
|
|
waits, every release that replaces the waiting worker leaves its cache
|
|
behind, so a scope holds one precache per release until its tabs close
|
|
(review 1103/06-04; `docs/operations/browser-file-storage-recovery.md` §8).
|
|
2. **Turn the worker off without a rebuild.** Set
|
|
`CAPABILITY_OVERRIDES.SERVICE_WORKER: "DISABLED"` in the runtime config. The
|
|
next boot unregisters the owned registration and registers nothing; owned
|
|
caches stay (`src/contracts/runtime-capabilities.ts`
|
|
`resolveRuntimeCapabilities`, `service-worker-page-controller.ts` `start()`).
|
|
This needs a page that boots. Edit a copy and check it with
|
|
`check:release-admission --config <copy> --original <deployed>` before it
|
|
replaces the served file (`docs/runbooks/FE-RB-001.md`).
|
|
3. **A worker stops the page from booting.** Deploy a release whose static
|
|
selection is `REMOVE_REGISTRATION`. It ships a self-unregistering
|
|
`service-worker.js` (`scripts/build-frontend.ts`,
|
|
`scripts/lib/self-unregistering-service-worker.ts`): the update check
|
|
installs it over the broken worker, it skips waiting, unregisters on
|
|
activation and answers no fetch. The next load is uncontrolled
|
|
(`tests/e2e/service-worker-recovery.spec.ts`). Runbook:
|
|
`docs/operations/browser-file-storage-recovery.md` §8.
|
|
4. **Removing the worker** takes three releases:
|
|
`REMOVE_REGISTRATION` → `PURGE_OWNED_RESOURCES` (deletes owned caches) →
|
|
`null` (`src/contracts/service-worker.ts` `InstalledServiceWorkerSelection`).
|
|
Only the `REMOVE_REGISTRATION` release ships the self-unregistering
|
|
`service-worker.js`. Keep it deployed for at least the longest time a user
|
|
may stay away. A later release has no worker file, so the update check
|
|
fails with 404: on `PURGE_OWNED_RESOURCES` only a page that boots
|
|
unregisters the old worker, and on `null` nothing does (review 0929/06-06).
|