문제
라우터는 browser history를 쓴다. 호스트가 앱 경로에 index.html을 주지
않으면 `/`는 열리고 새로고침·북마크·공유 링크만 404가 된다. 호스팅 계약
(config/hosting/cache-policy.json)에 앱 경로 표면이 없고, live probe는
`/`, config, manifest, entry script만 요청해서 FE-GATE-019가 그대로
PASS한다. 운영 문서가 no-cache로 서빙하라는 service-worker.js도 선언과
검사에 없다. e2e는 fallback을 기본으로 하는 vite preview라 드러나지 않는다.
고른 방법
- cache-policy.json에 표면 두 개를 더한다.
- appRoute: 빌드에 파일이 없는 경로 `/__probe/deep-link`. index와 같은
Cache-Control, content-type, 보안 헤더를 요구한다.
- serviceWorker: `/service-worker.js`, no-cache, JS MIME.
`requiredWhen: "service-worker-shipped"`로 워커를 싣는 빌드
(ACTIVE, REMOVE_REGISTRATION)에서만 요구한다. 이 판정은
checkPublicServiceWorkers와 같은 함수(shipsServiceWorker)를 쓴다.
- live probe를 scripts/lib/hosting-probe.ts의 probeLiveRelease로 옮겨
fetcher를 주입해 단위 테스트한다. 요청 경로는 정책의 path에서 읽는다.
appRoute는 200이어야 하고, 응답이 index.html과 같은 entry script를
가리켜야 한다. 그래서 404와, 200으로 답하는 다른 페이지(soft 404)를
모두 FAIL로 잡는다.
- release-cache-rollback.md에 fallback 규칙과 desktop 서버용 nginx 예시를
적는다. 예시는 손으로 썼고, 빠진 hashed asset은 index.html이 아니라
404여야 한다는 점(구 탭 재적재, FE-RB-002)과 add_header 상속 함정을
적었다.
버린 대안
- createHashRouter로 바꿔 fallback 자체를 없애기: URL과 기존 경로 계약·
테스트가 모두 바뀐다(리뷰 대안 비교에서 기각).
- 정책 이름(serviceWorker)으로 스크립트가 조건을 아는 방식: 정책 파일만
읽는 운영자가 항상 필요한 표면으로 오해한다. 조건을 JSON에 적었다.
- 리다이렉트 뒤 최종 경로까지 비교: 이번 완료 기준(404 FAIL) 밖이라 넣지
않았다.
위험·한계
- nginx 예시는 이 머신에 nginx가 없어 실행하지 않았다. CI도 돌리지 않는다.
호스트가 실제로 무엇을 주는지는 live probe가 확인한다.
- 이미 배포한 호스트에 fallback이나 SW 헤더가 없으면 FE-GATE-019가 새로
실패한다(의도).
- 앱 base path가 `/`가 아닌 배포는 기존 probe와 같이 다루지 않는다.
검증
- RED: node scripts/run-vitest.ts run tests/unit/hosting-probe.test.ts
5 failed. "expected undefined to match object { cacheControl:
'no-cache', …}"(정책에 appRoute·serviceWorker 없음),
"probeLiveRelease is not a function"
- GREEN: 같은 파일 22 passed. fallback 없는 호스트에서
["appRoute http-status", "appRoute entry-script"]가 실패로 나온다
- node scripts/run-vitest.ts run tests/unit/hosting-probe.test.ts
tests/platform/release tests/release tests/unit/ci-workflow-generation.test.ts:
483 passed
- build-frontend.ts 뒤 verify-hosting-headers.ts(fixture): UNVERIFIED rc=3,
결과 36건(appRoute 8건 포함), SW null이라 serviceWorker 헤더 검사는 건너뜀
- tsc(node, test), eslint 바뀐 파일, verify-documentation-readiness
PASS_SCOPED, check-ci-contract PASS
Refs: docs/reviews/2026-11-01-maturity-review/13-build-release-supply-chain.md 13-04
188 lines
9.3 KiB
Markdown
188 lines
9.3 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/installed-runtime-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`.
|
|
|
|
### 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 project has
|
|
deployed the promoted release. This repository's workflow stops at promotion:
|
|
uploading the release, switching the active pointer, and the post-switch smoke
|
|
are the project's provider adapter, chosen with the hosting provider.
|
|
|
|
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.
|
|
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.
|
|
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`).
|