Files
clean-architecture-frontend…/docs/operations/release-cache-rollback.md
T
DongHyeonka 121e11250a docs(operations): nginx 설정 예시를 지우고 호스트가 지킬 조건만 남긴다
문제: docs/operations/release-cache-rollback.md에 nginx 설정이 통째로
있다(보안 헤더 snippet과 server 블록, 「Example: nginx on a single
server」 절). CI는 그것을 돌리지 않고, 호스트 설정은 개발 repo의 일이
아니다(소유자 2026-11-07). ci-quality-gates.md의 runner 요구 절에도
호스트를 바꾸는 절차(AppArmor profile 본문, sysctl 명령)가 있다.

고른 방법:
- nginx 절을 지우고 같은 문서에 「운영 환경이 지켜야 할 조건」 19개를
  문장으로 쓴다. 조건마다 재는 쪽을 적었다: FE-GATE-019가 잰다(live
  모드, 값은 config/hosting/*.json) / 아무도 재지 않는다. 백엔드와 같은
  절 이름·같은 언어(한국어)다.
- 지운 설정을 한 줄씩 대조했다. snippet 6줄 → 6(값), always → 7;
  listen 443 ssl·server_name·인증서 → 1; http2 → 2; gzip·gzip_types →
  10, gzip_vary → 11; root current와 원자적 symlink 전환 → 17;
  index.html → 3·6; try_files fallback → 4·6; config.json·
  release-manifest.json → 5·6; 공유 /assets/·기간으로 지우기 → 18;
  없는 청크 404 → 12; immutable → 8; service-worker.js → 14·15;
  .map 404 → 16; Cache-Control에 always 없음 → 13; 기본 base path / →
  1; mime.types에 맡긴 Content-Type → 3·5·9·14. 롤백 때 동작은 19.
- static-delivery.md의 "nginx example" 문장은 이 절을 가리키게 고친다.
- ci-quality-gates.md: runner 요구(바이너리, systemd, cgroup, 비특권
  user namespace)는 게이트가 runner에 요구하는 조건이라 남긴다. 고치는
  방법 목록과 AppArmor profile 본문만 지우고 "고치는 방법은
  scripts/check-system-test-prerequisites.ts가 실패할 때 출력한다"로
  바꾼다. 그 스크립트가 같은 세 방법을 출력한다.
버린 대안: nginx 설정을 project-infra나 cicd-platform으로 복사하기.
아무도 시험하지 않는 복사본이 다른 repo에 생긴다(백엔드도 지웠다).

위험·한계: 아무도 재지 않는 부분이 있는 조건이 11개다(7, 8의 나머지 파일,
10의 나머지 청크와 CSS·JSON·SVG, 11, 12, 13, 15, 16의 호스트 쪽, 17의
전환 도중, 18, 19의 호스트 쪽). 지운 nginx 예시도 CI가 돌리지 않았으니
재지 않는 범위는 넓어지지 않았다. AppArmor profile 본문은 이 repo에서
없어진다. 필요하면 runner를 만드는 쪽 인프라 repo가 갖는다.

검증: git grep -n '^```nginx' 0줄. desktop(이 커밋 30a379f 트리, 로그
~/l1-layout-cleanup-logs/): verify:documentation PASS_SCOPED(새 절의
경로·script 이름·FE-GATE ID와 static-delivery.md의 링크 포함),
test:unit 3091 tests 통과.

Refs: design-docs repo-structure/04-frontend-layout.md 4절 I-3·I-4·I-11
2026-11-07 19:02:47 +09:00

16 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.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 and no redirect at all, not even one inside the origin: browsers fetch the worker script with redirect mode error, so registration, every update check and the REMOVE_REGISTRATION kill switch fail behind one (review 1106/06-01). 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).

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).

운영 환경이 지켜야 할 조건

이 repo는 호스트 설정 파일(nginx 등)을 두지 않는다(2026-11-07 소유자 결정). 그 파일은 서비스를 배포하는 쪽의 인프라 repo가 갖는다. 그 호스트가 지켜야 할 조건은 아래다. 값의 정본은 config/hosting/cache-policy.json과 config/hosting/security-headers.json이다.

조건마다 끝에 누가 재는지 적었다.

  • FE-GATE-019가 잰다: verify:hosting-headers의 live 모드가 배포된 호스트에 요청해 확인한다. 배포 슬롯이 이 release를 배포했을 때만 돈다. 슬롯이 비면 호스트를 재지 않고 UNVERIFIED로 끝난다(위 단락).
  • 아무도 재지 않는다: 계약 파일에도 검사에도 없다. 호스트를 맡은 쪽이 직접 확인한다.

주소와 연결

  1. 앱은 HTTPS origin의 루트(/)에서 내보낸다. 인증서가 유효하고, 어느 surface도 그 origin 밖으로 redirect하지 않는다. — FE-GATE-019가 잰다. HOSTING_BASE_URL은 경로 없는 HTTPS 루트 URL이어야 하고, surface마다 최종 origin을 본다.
  2. TLS에서 HTTP/2를 맺는다(ALPN h2). — FE-GATE-019가 잰다(transport.alpnProtocols).

surface별 응답 (surface: probe가 요청하는 경로 하나)

  1. index.html은 Cache-Control: no-cache와 text/html로 준다. — FE-GATE-019가 /로 잰다(surfaces.index).
  2. 빌드에 파일이 없는 모든 앱 경로(새로 고침, 북마크, 공유 링크)에는 200으로 그 release의 index.html을 3과 같은 헤더로 준다(SPA fallback). — FE-GATE-019가 잰다 (surfaces.appRoute, /__probe/deep-link).
  3. config.json과 release-manifest.json은 Cache-Control: no-store와 application/json으로 준다. — FE-GATE-019가 잰다(surfaces.runtimeConfig, surfaces.releaseManifest).
  4. 3~5의 응답에는 config/hosting/security-headers.json의 헤더를 모두 그 값 그대로 붙인다. — FE-GATE-019가 잰다(securityHeaders가 참인 surface).
  5. 오류 응답(404, 5xx)에도 6의 보안 헤더를 붙인다. — 아무도 재지 않는다. probe는 200 응답만 본다.
  6. assets/ 아래 hashed 파일은 Cache-Control: public, max-age=31536000, immutable로 준다. — 진입 스크립트 하나는 FE-GATE-019가 잰다(surfaces.hashedAsset). 나머지 파일의 Cache-Control은 아무도 재지 않는다.
  7. hashed 파일은 redirect 없이 200으로, 확장자에 맞는 Content-Type으로 준다. — FE-GATE-019가 확장자마다 첫 파일 하나를 잰다(위 단락, CACHEABLE_ASSET_CONTENT_TYPES).
  8. JavaScript는 압축해서 보낸다(br, gzip, zstd 중 하나). 번들 예산이 gzip 크기를 센다. — 진입 스크립트는 FE-GATE-019가 잰다(hashedAsset.contentEncodings). 나머지 청크는 아무도 재지 않는다. CSS·JSON·SVG 압축은 예산이 기대지 않고, 아무도 재지 않는다.
  9. 압축한 응답에는 Vary: Accept-Encoding을 붙인다. 공유 캐시가 압축한 본문을 압축을 받지 못하는 클라이언트에 주지 않게 한다. — 아무도 재지 않는다.
  10. 없는 hashed 파일을 요청하면 404로 답한다. index.html로 대신 답하지 않는다. 옛 탭은 그 실패를 봐야 한 번 새로 고친다(FE-RB-002). — 아무도 재지 않는다.
  11. 404 같은 오류 응답에는 immutable 캐시 헤더를 붙이지 않는다. 붙이면 브라우저와 CDN이 그 실패를 hashed 파일처럼 오래 저장한다. — 아무도 재지 않는다.
  12. 빌드가 Service Worker를 실으면 /service-worker.js는 redirect 없이 200, Cache-Control: no-cache, JavaScript Content-Type으로 준다. — FE-GATE-019가 잰다 (surfaces.serviceWorker).
  13. 빌드가 worker를 싣지 않으면 /service-worker.js는 404로 답한다. SPA fallback이 index.html로 대신 답하지 않는다(아래 「Service Worker steps」 4). — 아무도 재지 않는다. worker가 없는 빌드에서는 probe가 이 경로를 요청하지 않는다.
  14. 소스맵을 공개하지 않는다. — release의 dist에 .map이 없는지는 FE-GATE-019가 잰다(surfaces.sourceMap). 호스트가 .map 요청을 404로 막는지는 아무도 재지 않는다.

배포와 롤백

  1. release 묶음(index.html, config.json, release-manifest.json, service-worker.js)을 한 번에 바꾼다. 옛 파일과 새 파일이 섞여 보이는 순간이 없다. — 바꾼 뒤 release-manifest.json·config.json·index.html이 이 release의 것인지는 FE-GATE-019가 잰다. 바꾸는 도중에 섞이지 않는지는 아무도 재지 않는다.
  2. 지난 release의 hashed 파일을 release를 바꿀 때 지우지 않는다. 이름이 겹치지 않으므로 한 곳에 모아 둘 수 있고, 보관 기간(위 단락)이 지난 것만 지운다. — 호스트에서는 아무도 재지 않는다. 템플릿 안의 호스트 모형(tests/release/release-fixture.ts)은 tests/release/old-asset-reachability.test.ts가 시험한다.
  3. 롤백은 지난 release의 묶음(17)을 그대로 다시 내보낸다. 옛 commit을 다시 빌드하거나 HTML만 바꾸지 않는다(맨 위 단락). 18 덕분에 그 release의 hashed 파일은 남아 있다. — 되돌릴 release의 묶음과 파일은 바꾸기 전에 drill:runbook -- FE-RB-005가 확인한다. 호스트에서 바꾼 결과는 아무도 재지 않는다. 그 drill은 UNVERIFIED로 끝난다(위 단락).

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).