문제
production_gate는 promotion 직후 같은 run에서 시작하고 그 사이에 배포 job이
없다. CI 계약이 job 9개·그래프·env를 정확히 고정해 배포 job을 넣을 자리도
없다. live probe는 헤더만 보고 배포된 release가 승격 후보인지 확인하지
않는다. FE-GATE-019의 명령은 [build, verify-hosting-headers]라서 local
프로필로 다시 빌드한 dist를 검사한다. 그래서 FE-GATE-019 PASS는 "지금 떠
있는 release(대개 이전 것)의 헤더가 맞다"는 거짓 PASS다.
고른 방법 (리뷰 대안 (c), (1)~(3))
(1) live probe가 배포된 release-manifest.json의 buildId·releaseId를 후보와
비교한다. 다르거나 읽을 수 없으면 FAIL(releaseManifest build-id·
release-id). 후보는 검사하는 dist의 release-manifest.json이다.
(2) FE-GATE-019에서 build를 뺀다. verify-hosting-headers가
`--release-root .release/promoted-release`를 받아 후보 dist를 본다.
계약의 13-03 규칙(drill만 --release-root 필수)을 production_gate의 모든
게이트 명령으로 넓혔다. 플래그 없이 돌리면 local dist를 본다.
(3) promotion과 production_gate 사이에 `deployment` job(kind deployment)을
선언한다. 기본은 빈 슬롯이다: deploy 단계 하나가 deployed=false를 job
output으로 낸다. production_gate는 RELEASE_DEPLOYED로 받고, 비어 있으면
FE-GATE-019가 호스트를 probe하지 않고 UNVERIFIED(exit 3)로 끝난다.
프로젝트는 gates.json의 deployment job을 채운다. 계약이 허용하는 것:
checkout·setup-node·frozen-install·download·extract와 마지막 deploy 하나
(`script`는 package 스크립트, 존재·스크립트 그래프 검사를 gate 명령과
같이 받는다). env는 immutable_build의 CANDIDATE_ARCHIVE_SHA256과
vars.*·secrets.*만. 게이트를 소유하지 않아 채워도 계약 기준선이 안
바뀐다.
- ci-contract 보고서 jobCount 9→10, 계약 기준선 commandReferences
103→102(update-ci-contract-baseline, owner frontend-platform).
- verify-hosting-headers가 live가 아닌 모드에서 baseUrl을 null로 적는다.
스키마가 live에만 baseUrl을 허용해서, 비어 있는 슬롯과 기존 invalid-live
(예: http:// URL)는 산출물 쓰기에서 ZodError로 죽었다. 이제 기록을 남기고
각각 UNVERIFIED·FAIL로 끝난다.
버린 대안
- (b) (1)(2)만: 거짓 PASS는 사라지지만 배포 자리가 없어 운영 단계가 항상
FAIL이 된다.
- (d) production_gate를 별도 workflow로 분리: Gitea에서 run 사이 artifact
전달이 검증되지 않았다.
- 슬롯이 비었는지를 HOSTING_BASE_URL 유무로 판단: 변수만 있고 배포가 없으면
이전 release를 probe해 FAIL이 된다. 슬롯이 직접 보고하게 했다.
위험·한계
- Gitea runner가 꺼져 있어 workflow를 실제로 돌리지 않았다. job outputs와
`$GITHUB_OUTPUT`는 immutable_build가 이미 쓰는 방식과 같다.
- 실제 HTTPS 호스트에 이전 release를 띄워 probe하지 않았다. 불일치 판정은
fetcher를 주입한 단위 테스트로만 확인했다.
- 채운 슬롯의 secrets는 그 job의 모든 단계(checkout, download action 포함)
env에 보인다. 프로젝트가 고르는 값이다.
- FE-GATE-019를 수동으로 돌리는 운영자(provider 없는 최소 구성)는 후보
archive를 .release/promoted-release에 풀어야 한다. drill과 같은 전제다.
검증
- RED: node scripts/run-vitest.ts run tests/unit/hosting-probe.test.ts
7 failed / 19 passed(후보 인자 없음, verify가 dist ENOENT로 산출물 없음).
tests/unit/ci-workflow-generation.test.ts 8 failed / 415 passed
("expected [ 'build', 'verify:hosting-headers' ] to deeply equal ...",
"expected -1 to be 6", deployment job 없음)
- GREEN: hosting-probe 26 passed, ci-workflow-generation 423 passed
(스냅샷 1개 갱신)
- check:ci 하위 명령 직접 실행: generate-artifact-schemas --check PASS,
check-ci-contract.ts PASS, generate-ci-workflow --check PASS
- 슬롯을 채운 실험(체크아웃→다운로드→extract→deploy:release, vars·secrets
env, package 스크립트 추가) 뒤 같은 세 명령 PASS. package 스크립트를 빼면
"CI gate contract missing package scripts: deploy:release"로 실패. 실험
뒤 원복
- 관련 테스트 16파일 596 passed(ci-workflow-generation, hosting-probe,
service-worker-build-output, deployment-admission, ungated-*,
supply-chain, removal-fixture, task3-selective-integration,
documentation-readiness, tests/release, tests/platform/release)
- tsc(node, test, app) 0, eslint 바뀐 파일 0,
verify-documentation-readiness PASS_SCOPED
- 미실행: tests/system/ci-runner(pnpm 실행), check:architecture(pnpm)
Refs: docs/reviews/2026-11-01-maturity-review/13-build-release-supply-chain.md 13-01
199 lines
10 KiB
Markdown
199 lines
10 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`.
|
|
|
|
### 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.
|
|
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`).
|