Files
clean-architecture-frontend…/docs/operations/release-cache-rollback.md
T
DongHyeonka 2a78169c58 fix(hosting): live probe가 redirect된 워커 스크립트를 거절한다
문제
워커를 싣는 빌드에서 live probe는 `/service-worker.js`를 기본 fetcher
`redirect: "follow"`로 받고, 최종 응답의 status와 origin만 본다
(`scripts/lib/hosting-probe.ts` `probeLiveRelease`). 같은 origin 안
redirect 뒤에 200·`no-cache`·JS MIME이 오면 FE-GATE-019가 PASS다.
브라우저는 워커 스크립트를 redirect mode "error"로 받는다(Service
Worker Update 알고리즘). 그런 호스트에서는 첫 등록, update 검사,
`REMOVE_REGISTRATION` kill switch가 모두 실패한다.

고른 방법과 버린 대안
- `serviceWorker` surface에만 `redirect` 행을 더한다.
  `response.redirected`이거나 `opaqueredirect`이면 FAIL이다. 자산
  probe(1105/06-02)와 같은 판정식이라 fetcher가 redirect를 따라가든
  manual이든 잡는다. 3xx 응답은 지금처럼 `http-status` 행이 FAIL로 본다.
- redirect가 없으면 이 행은 PASS로 남는다. 산출물에 이 검사를 했다는
  기록이 된다.
- 버린 대안: 모든 surface에서 redirect를 FAIL로 보기(리뷰 (b)).
  `index`·`appRoute`의 정상 redirect(끝 슬래시 정규화 등)까지 막는다.
  문서에만 적기(리뷰 (c))는 게이트가 그대로 PASS다.
- 운영 문서 두 곳에 "redirect 없이"를 적었다. release-cache-rollback.md의
  live probe 설명과 browser-file-storage-recovery.md의 kill switch
  전제다.

위험·한계
- 워커 스크립트를 redirect하던 호스트는 이제 FE-GATE-019에서 FAIL이다.
  그런 호스트에서는 지금도 워커가 동작하지 않는다.
- 브라우저 거절은 명세와 Chromium 오류 문구에 기댄 것이다. redirect하는
  호스트로 실제 등록을 돌려 보지 않았고, live 모드도 실제 호스트로 돌리지
  않았다(리뷰 §5 미검증 그대로).

검증
- desktop batch에서 확인:
  node scripts/run-vitest.ts run tests/unit/hosting-probe.test.ts
- RED: "live hosting probe (1105/06-02) > fails a worker script the host
  answers only after a same-origin redirect"가 실패한다. 옛 probe에는
  redirect 행이 없어 실패 행이 비어 있다.
- 함께: check:types, lint, verify:documentation

Refs: 1106/06-01
2026-11-06 05:17:04 +09:00

249 lines
13 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` and no redirect at all, not even
one inside the origin: browsers fetch the worker script with redirect mode
`error`, so registration, every update check and the `REMOVE_REGISTRATION`
kill switch fail behind one (review 1106/06-01). 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 install fetch also refuses any redirect, so an asset the host answers only
after a redirect fails even when the final answer is a correct 200 (review
1105/06-02). This asset check runs for a build without a worker too: under
`nosniff` a script or style of another type breaks the page anyway, and a later
release that turns the worker on then needs no new hosting check. A font or
image of another type fails it although a worker-free page still loads it.
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`.
Those two names come from the CI run, so a release rebuilt in the same run
carries them as well. The served `config.json` must therefore equal the
release's `dist/config.json`, the document release admission (FE-GATE-027)
admitted, in every field except the two emergency switches
`CAPABILITY_OVERRIDES` and `FEATURE_OVERRIDES` (FE-RB-001), and the served
`index.html` must name the release's entry script (review 1103/13-01).
The probe also checks the two serving premises the bundle budget and the split
initial chunks rest on (review 1103/13-02): the entry script arrives with a
`Content-Encoding` from `hashedAsset.contentEncodings` (the budget counts gzip
bytes; uncompressed, the initial JavaScript is about three times larger), and
the TLS handshake negotiates a protocol from `transport.alpnProtocols` (`h2`;
over HTTP/1.1 the initial files queue for six connections). A host that cannot
meet them fails FE-GATE-019; a product that has to serve that way changes the
declaration in `config/hosting/cache-policy.json` in the same change that
groups its initial chunks ("초기 청크 수와 HTTP/1.1" in
[`performance-evidence.md`](performance-evidence.md)).
### 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;
# nginx 1.25.1 and later; before it, `listen 443 ssl http2;`.
http2 on;
server_name app.example.com;
# ssl_certificate / ssl_certificate_key ...
# The bundle budget counts gzip bytes, and FE-GATE-019 fails an
# uncompressed entry script (cache-policy.json `hashedAsset`). nginx
# compresses only text/html unless gzip_types names the rest.
gzip on;
gzip_vary on;
gzip_types text/javascript application/javascript application/json text/css image/svg+xml;
# 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).