문제: 확장자별 MIME probe(1103/06-03)는 install 조건 일부만 옮겼다. 1. install fetch는 `redirect: "error"`라 redirect가 하나라도 있으면 실패한다. probe는 `redirect: "follow"`로 받고 최종 status와 MIME만 본다. 같은 origin 안 redirect 뒤 200을 주는 호스트가 PASS다(리뷰 06-R1). FE-GATE-019가 PASS인데 워커 install은 매번 실패한다. 2. 워커 없는 빌드에서도 돈다. 주석과 문서는 이유를 워커로만 적는다. 3. live 분기의 호출 줄(`verify-hosting-headers.ts`)을 지키는 테스트가 없다. live 모드는 루프백·http를 거절해 저장소 테스트가 들어갈 수 없다. 호출을 지우는 변이가 44건 통과로 살아남았다(06-R2). 고른 방법: 1. 자산 probe 기본 fetcher를 `redirect: "manual"`로 바꾸고, `response.redirected`이거나 `opaqueredirect`이면 관측 "redirected", 이유 "install fetch가 redirect를 거절"로 FAIL이다. 3xx는 지금처럼 `HTTP 3xx`로 FAIL이다. fetcher가 redirect를 따라가도 `redirected`로 잡으므로 fetcher 방식과 무관하다. 2. 동작은 그대로 두고 의도를 주석과 운영 문서에 적었다. 워커가 없어도 `nosniff` 아래 script·style은 MIME이 틀리면 페이지가 깨지고, 나중에 워커를 켜는 릴리스가 호스팅을 다시 확인하지 않아도 된다. 글꼴·이미지는 페이지에 피해가 없는데 FAIL한다는 것도 적었다. 워커 없는 빌드에서 script·style만 보도록 좁히는 것은 검사를 약하게 하는 정책 결정이라 하지 않았다(결정 대기, 템플릿 소유자). 3. live 분기 전체를 `probeLiveHosting`(release surface + 자산 MIME)으로 빼고 스크립트는 그것만 부른다. 테스트가 fetcher 대역으로 이 함수를 돌려 CSS `text/plain`이 FAIL인지 본다. 자산 probe 호출을 빼면 이 테스트가 실패한다. 스크립트에서 `probeLiveHosting` 호출을 빼면 live 결과가 비어 cache-control 행이 모두 FAIL이라 스스로 드러난다. 버린 대안: 문서에 한계만 적기(리뷰 (b)). 1·3이 그대로다. 위험·한계: 정규 경로 규칙으로 자산을 redirect하는 호스트는 이제 FE-GATE-019에서 FAIL이다. 워커가 없는 제품도 마찬가지다(2의 판단). 실제 호스트로 live 모드를 돌리지는 않았다. 검증: desktop batch에서 확인. - node scripts/run-vitest.ts run tests/unit/hosting-probe.test.ts - RED: "fails an asset the host answers only after a redirect"(옛 probe는 redirect 뒤 200을 PASS), "checks every built asset type besides the release surfaces"(옛 코드에 `probeLiveHosting`이 없음)가 실패한다. - 변이(06-R2 대응): `probeLiveHosting`에서 `probeAssetContentTypes` 결과를 빼면 "checks every built asset type ..."가 실패해야 한다. Refs: 1105/06-02
246 lines
13 KiB
Markdown
246 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`. 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).
|