문제: (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
12 KiB
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).
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.htmland 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.tsisACTIVEorREMOVE_REGISTRATION; thendistholds exactly the selectedservice-worker.js, servedno-cacheso 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).
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.
# /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;
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 (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.
- Rollback N+1 → N. Switching the tuple serves N's
service-worker.js. The browser's update check installs it; the worker never callsskipWaiting()on install (src/adapters/service-worker/service-worker-entry.ts), so it waits until every tab of the scope closes or a page callsrequestActivation(). 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.tsinstallStaticAssets). Tabs still on N+1 keep worker N+1, so N+1's assets stay reachable for the rolling window above. - 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.tsresolveRuntimeCapabilities,service-worker-page-controller.tsstart()). This needs a page that boots. Edit a copy and check it withcheck:release-admission --config <copy> --original <deployed>before it replaces the served file (docs/runbooks/FE-RB-001.md). - A worker stops the page from booting. Deploy a release whose static
selection is
REMOVE_REGISTRATION. It ships a self-unregisteringservice-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. - Removing the worker takes three releases:
REMOVE_REGISTRATION→PURGE_OWNED_RESOURCES(deletes owned caches) →null(src/contracts/service-worker.tsInstalledServiceWorkerSelection).