Files
clean-architecture-frontend…/docs/operations/release-cache-rollback.md
T
DongHyeonka 0f58abbd32 fix(hosting): live probe가 사전 캐시 확장자마다 Content-Type을 확인한다
문제
워커 install은 사전 캐시 자산마다 응답 MIME이 manifest 값
(CACHEABLE_ASSET_CONTENT_TYPES: .css .js .mjs .png .svg .webp .woff2)과
정확히 같아야 하고, 하나라도 틀리면 release 전체를 거절한다. 호스팅
live probe는 index가 가리키는 entry script 하나만 요청하고
hashedAsset.contentTypes도 JavaScript뿐이다. 그래서 CSS를 text/plain,
글꼴을 octet-stream으로 보내는 호스트도 게이트는 PASS다. 페이지는
글꼴을 그대로 쓰므로 워커만 조용히 설치되지 않는다.

고른 방법
- probeAssetContentTypes를 더한다. 후보 dist의 assets/에서 확장자마다
  첫 파일(이름순)을 요청하고, 그 확장자의 워커 표 MIME과 비교한다.
  결과는 surface hashedAsset.<ext>, header content-type이다.
  verify-hosting-headers live 모드에서만 부른다.
- 기대 MIME은 워커 표에서 바로 읽는다. .js 계열은 hashedAsset surface와
  같이 application/javascript도 받는다. 두 목록이 같다는 것을 테스트가
  지킨다(acceptedAssetContentTypes(".js") = cache-policy hashedAsset).
- 운영 문서(release-cache-rollback.md)에 새 검사를 적는다.
- 버린 대안: (b) 워커가 비JS 자산 MIME을 느슨하게 받기 — 캐시에서 꺼낸
  응답이 틀린 MIME을 그대로 갖고 설계 §18 확인 순서 4와 어긋난다.
  (c) 사전 캐시를 JS·CSS로 줄이기 — 글꼴 캐시 이득을 잃는다. (d) 문서만
  — 검출이 없다(리뷰 5.2).

위험·한계
- live probe 요청이 확장자 수만큼 는다(지금 빌드는 .js·.css 2개).
- 확장자마다 파일 하나만 본다. 같은 확장자 안에서 경로마다 MIME이
  다른 호스트는 잡지 못한다.
- cache-control은 이 자산들에서 다시 보지 않는다. entry script의
  hashedAsset 검사가 그대로 본다.
- 실제 호스트로 live 모드를 돌리지 않았다. fetcher 대역으로만 확인했다.
- 하위 경로 base는 probe가 아직 거절한다(0929/13-06, 다른 영역). 새
  함수는 base 기준 상대 경로로 요청하므로 그 수정 뒤에도 그대로 쓴다.

검증
- 새 테스트 4건을 옛 코드에 돌림: 4건 실패(RED). 새 코드:
  hosting-probe·service-worker-build-output 테스트 통과.
- CSS를 text/plain으로 보내는 호스트 → hashedAsset.css FAIL.
- check:types:node·check:types:test 통과, 바꾼 파일 eslint 통과.

Refs: docs/reviews/2026-11-03-maturity-review/06-adapters-service-worker-push.md 06-03
2026-11-04 20:26:24 +09:00

10 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/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. 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 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.

# /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;
    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 (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).