문제: (1) live probe는 배포된 release-manifest.json의 buildId·releaseId만 후보와 비교했다. 두 값은 CI run 번호로 만든 이름이라, 같은 run에서 로컬 프로필로 다시 빌드한 release(APP_ENV=local, AUTH_MODE=demo, loopback API)를 올려도 PASS(live)였다(리뷰 실험 E-2c). 공개 대상 승인 (FE-GATE-027)을 받은 것은 후보의 config.json인데, 호스트가 내주는 config.json은 헤더만 보았다. entry script도 호스트의 두 응답끼리만 비교했다. (2) 템플릿은 HTTP/2와 압축을 전제로 초기 청크를 나누고 gzip 바이트로 예산을 재는데, 그 전제가 호스팅 계약에 없고 probe도 보지 않았다. 템플릿 nginx 예시는 http2도 gzip도 켜지 않았다. 고른 방법: - 받은 /config.json을 후보 dist/config.json과 비교한다. 비상 스위치 두 개(CAPABILITY_OVERRIDES, FEATURE_OVERRIDES) 밖의 필드가 다르거나 읽을 수 없으면 FAIL. 규칙은 check-release-admission과 같은 함수 (scripts/lib/runtime-config-switches.ts)로 옮겨 같이 쓴다. - 받은 index.html의 entry script를 후보 index.html의 것과 비교한다. - cache-policy.json에 transport.alpnProtocols(["h2"])와 hashedAsset.contentEncodings(br, gzip, zstd)를 선언한다. probe는 TLS handshake의 ALPN(node:tls, h2와 http/1.1을 제안)과 entry script 응답의 Content-Encoding을 본다. Node fetch는 h2를 지원하는 서버에도 HTTP/1.1로 붙어서 프로토콜은 따로 확인해야 한다. - nginx 예시에 http2 on과 gzip·gzip_types를 넣고, static-delivery.md와 release-cache-rollback.md에 두 전제와 실패 조건을 적었다. 두 수정은 같은 probe 함수와 테스트를 고쳐 한 커밋에 넣었다. 버린 대안: archive SHA를 호스트에 올려 대조하기(호스트에 새 파일 규약이 생기고 일부 파일만 다른 배포는 못 잡는다). HTTP/2를 기록만 하기 (아무도 읽지 않는 경고는 청크를 묶는 결정을 부르지 못한다. 선언을 바꾸면 제품이 끌 수 있다). 위험·한계: HTTP/1.1만 되는 호스트는 이제 FE-GATE-019에서 FAIL한다. 그 제품은 cache-policy.json 선언을 바꾸고 초기 청크를 묶는다. 실제 nginx와 Gitea runner에서는 돌리지 않았다. 슬롯이 후보를 받도록 강제하는 계약 규칙은 다음 커밋(제품 overlay)에 있다. 검증: hosting-probe.test.ts에 같은 이름·다른 config.json → FAIL, 비상 스위치만 다름 → PASS, 읽을 수 없는 config.json → FAIL, 다른 entry → FAIL, ALPN http/1.1·없음 → FAIL, 압축 없는 entry → FAIL, 정책 선언 확인을 더했다(고치기 전 실패). 33건 통과. 로컬 자체 서명 TLS 서버 실험: http2.createSecureServer → "h2", https.createServer → "http/1.1", 인증서 이름 불일치 → ERR_TLS_CERT_ALTNAME_INVALID. verify:hosting-headers(fixture) UNVERIFIED exit 3, deployment-admission 통과. Refs: docs/reviews/2026-11-03-maturity-review/13-build-release-supply-chain.md 13-01, 13-02
226 lines
12 KiB
Markdown
226 lines
12 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`.
|
|
|
|
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.
|
|
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`).
|