문제: `HOSTING_BASE_URL`의 경로가 `/`가 아니면 probe가 거절해, 하위 경로 (`VITE_ROUTER_BASE_PATH=/app/`)로 배포한 release는 live 확인을 쓸 수 없었다. surface 경로(`/config.json`)도 늘 origin 루트로 풀었다. 고친 것: 기준 URL은 `/`로 끝나는 경로면 받는다(query·fragment는 거절). `config/hosting/cache-policy.json`의 surface 경로는 기준 URL 아래로 푼다 (`surfaceUrl`). 진입 script는 index.html이 적은 그대로 요청한다. 후보의 진입 script가 기준 경로 아래에 있는지(`deployment base-path`)도 보아, 다른 경로로 빌드한 후보를 잘못된 기준 URL로 재면 실패한다. 검증: desktop `node scripts/run-vitest.ts run tests/unit/hosting-probe.test.ts` 46건 통과(`/app/` 기준 요청 경로, 경로 불일치 실패, URL 분류). 기준 커밋에서는 새 시험이 실패한다. Refs: 0929/13-06
234 lines
18 KiB
Markdown
234 lines
18 KiB
Markdown
# Release·캐시·롤백 계약
|
|
|
|
배포 하나는 바꿀 수 없는 `releases/<releaseId>/` 산출물 묶음이다. provider adapter는
|
|
활성 HTML 포인터를 원자적으로 바꾸기 전에 asset, release manifest, runtime config를
|
|
올리고 asset에 닿는지 확인해야 한다. 바꾼 뒤 boot, route, API, telemetry, 새로 고침
|
|
반복(reload loop) smoke check를 통과해야 배포가 끝난다.
|
|
|
|
롤백은 이전 release 묶음(tuple)을 고른다. 그 묶음의 asset과 runtime/API 호환성을
|
|
확인하고, 묶음 전체를 원자적으로 바꾸고, provider의 캐시 조치를 하고, smoke check를
|
|
다시 돈다. 옛 commit을 다시 빌드하는 것, HTML만 바꾸는 것, 캐시 purge가 끝났다는 것만으로
|
|
복구를 선언하는 것은 금지다. 복구는 옛 release와 새 release에 닿는지 보는 probe로
|
|
확인한다.
|
|
|
|
승격(promotion)한 release를 나중에 배포하거나 그 release로 롤백하기 전에는 승격
|
|
묶음(`promotion` job이 올린 파일 다섯 개)을 archived 모드로 다시 검증한다(리뷰 0925/13-04).
|
|
provider evidence는 발급 두 시간 뒤 만료된다. 그래서 일반 모드는 그보다 먼저 승격한
|
|
release를 모두 거절한다. archived 모드도 서명, digest, 정확한 다섯 member를 검사한다.
|
|
다만 신선도는 release에 기록된 승격 시각으로 판단한다
|
|
(`promotion-verification.json` `verifiedAt`, 미래 시각이면 안 된다).
|
|
새 승격에는 이 모드를 쓰지 않는다(`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>
|
|
```
|
|
|
|
기대값은 묶음이 아니라 release 기록에서 가져온다. 그다음 drill은 로컬 빌드가 아니라
|
|
그 release의 build/config/manifest 묶음과 asset을 검사한다. provider 전환과 smoke는 이
|
|
repo 밖에서 일어난다. 그래서 그 결과가 기록될 때까지 drill은 `UNVERIFIED`로 끝난다.
|
|
|
|
provider와 상관없는 캐시 기본값은 아래와 같다.
|
|
|
|
- hashed asset: `public, max-age=31536000, immutable`
|
|
- HTML: `no-cache`
|
|
- 앱 경로: router가 browser history를 쓴다. 그래서 빌드에 파일이 없는 모든 경로(새로
|
|
고침, 북마크, 공유 링크)에는 그 release의 `index.html`과 HTML 헤더로 답한다(SPA
|
|
fallback). 없는 hashed asset은 404로 남고, HTML로 대신 답하지 않는다
|
|
- runtime config와 release manifest: `no-store`
|
|
- 공개 소스맵: 끔
|
|
- Service Worker/offline 캐시: 끔. 단
|
|
`src/features/product-capabilities.ts`의 정적 선택이 `ACTIVE`나
|
|
`REMOVE_REGISTRATION`이면 `dist`에 선택한 `service-worker.js` 하나만 들어간다. 이
|
|
파일은 `no-cache`로 내보내서 브라우저의 업데이트 검사가 release마다 그 worker를 보게
|
|
한다
|
|
|
|
HTML, JSON config/manifest, hashed JavaScript의 MIME type도 선언한 허용 목록(allowlist)과
|
|
비교한다. 캐시 헤더가 맞아도 `Content-Type`이 다르면 hosting gate는 실패한다.
|
|
|
|
`HOSTING_BASE_URL`이 없으면 `corepack pnpm verify:hosting-headers`는 선언한 헤더를
|
|
결정적(deterministic) fixture와 비교한다. 이것은 선언끼리 서로 맞는다는 것만 보여 준다.
|
|
그래서 결과는 `PASS`가 아니라 `UNVERIFIED`(exit 3)다
|
|
(리뷰 0925/13-05, `scripts/lib/hosting-probe.ts` `hostingVerdict`). 통과할 수 있는 것은
|
|
`mode: "live"`뿐이다. live 대상은 loopback이 아닌 정식(canonical) HTTPS 루트 URL이어야
|
|
한다. 필요한 surface마다 그 origin을 벗어나지 않고 HTTP 200을 돌려줘야 한다. 그래야 그
|
|
surface의 캐시, content-type, 보안 헤더를 배포 증거로 셀 수 있다. probe가 요청하는
|
|
hashed asset은 호스트가 내준 `index.html`이 가리키는 진입 스크립트다. 그래서 실제로
|
|
배포된 release를 검사한다. probe는 `appRoute`(`/__probe/deep-link`, 어느 빌드에도 파일이
|
|
없는 경로)도 요청한다. 호스트는 200과 함께 같은 `index.html`(같은 진입 스크립트)과 HTML
|
|
헤더로 답해야 한다. 그래서 SPA fallback이 없는 호스트는 실패한다(리뷰 1101/13-04).
|
|
빌드가 worker를 실으면 probe는 `/service-worker.js`를 요청하고 `no-cache`를 기대한다.
|
|
redirect는 origin 안의 것도 하나도 허용하지 않는다. 브라우저는 worker 스크립트를
|
|
redirect 모드 `error`로 가져온다. 그래서 redirect가 하나라도 끼면 등록, 모든 업데이트
|
|
검사, `REMOVE_REGISTRATION` kill switch가 실패한다(리뷰 1106/06-01). surface와 그
|
|
헤더는 `config/hosting/cache-policy.json`에 선언한다. release의 `assets/` 아래에 있는
|
|
캐시 가능한 확장자(`.css`, `.js`, `.woff2`와 그 밖의
|
|
`CACHEABLE_ASSET_CONTENT_TYPES`)마다 probe는 첫 파일 하나를 요청하고 정확히 그 type을
|
|
기대한다(`hashedAsset.css` 등). precache한 asset 하나라도 type이 다르면 worker의
|
|
install은 release 전체를 거절한다. 반면 페이지는 `application/octet-stream`으로 받은
|
|
font도 그대로 쓴다(리뷰 1103/06-03). install fetch는 redirect도 모두 거절한다. 그래서
|
|
호스트가 redirect를 거친 뒤에야 답하는 asset은 최종 응답이 올바른 200이어도 실패한다
|
|
(리뷰 1105/06-02). 이 asset 검사는 worker가 없는 빌드에서도 돈다. `nosniff`에서는 type이
|
|
다른 script나 style이 어차피 페이지를 깬다. 또 나중에 worker를 켜는 release가 새 hosting
|
|
검사를 받지 않아도 된다. type이 다른 font나 image는 worker 없는 페이지에서는 그래도
|
|
로드되지만, 이 검사에서는 실패한다.
|
|
|
|
호스트가 내준 `release-manifest.json`은 검사하는 release의 `buildId`와 `releaseId`를
|
|
담아야 한다. 이전 release의 헤더가 맞아도 이번 release의 증거는 아니다(리뷰 1101/13-01).
|
|
검사하는 release는 `-- --release-root <extracted archive>`를 주면
|
|
`<release-root>/dist`다(FE-GATE-019는 승격한 archive를 넘긴다). 주지 않으면 로컬
|
|
`dist`다.
|
|
|
|
두 이름은 CI run에서 온다. 그래서 같은 run에서 다시 빌드한 release도 같은 이름을 갖는다.
|
|
따라서 호스트가 내준 `config.json`은 release의 `dist/config.json`과 모든 칸이 같아야
|
|
한다. 이 파일은 release admission(FE-GATE-027)이 승인한 문서다. 예외는 두 긴급 스위치
|
|
`CAPABILITY_OVERRIDES`와 `FEATURE_OVERRIDES`(FE-RB-001)뿐이다. 호스트가 내준
|
|
`index.html`도 release의 진입 스크립트를 가리켜야 한다(리뷰 1103/13-01).
|
|
|
|
probe는 번들 예산과 나뉜 초기 chunk가 기대는 두 가지 전송 전제도 검사한다(리뷰
|
|
1103/13-02). 첫째, 진입 스크립트가 `hashedAsset.contentEncodings`에 있는
|
|
`Content-Encoding`으로 온다. 예산은 gzip 바이트를 센다. 압축하지 않으면 초기
|
|
JavaScript는 약 세 배 크다. 둘째, TLS handshake가 `transport.alpnProtocols`에 있는
|
|
프로토콜(`h2`)을 맺는다. HTTP/1.1에서는 초기 파일이 연결 여섯 개를 기다리며 줄을 선다.
|
|
이 전제를 지키지 못하는 호스트는 FE-GATE-019에서 실패한다. 그렇게 내보낼 수밖에 없는
|
|
제품은 초기 chunk를 묶는 변경에서 `config/hosting/cache-policy.json`의 선언도 함께
|
|
바꾼다([`performance-evidence.md`](performance-evidence.md)의 "초기 청크 수와 HTTP/1.1").
|
|
|
|
그래서 FE-GATE-019는 production 단계 gate다(`production_gate` job,
|
|
`PROD_PROMOTION_READY`). 이 gate는 `promotion` 뒤, 그리고 `deployment` job 뒤에 돈다.
|
|
그 job은 프로젝트의 배포 슬롯이고, 이 repo에서는 비어 있다. release 업로드,
|
|
활성 포인터 전환, 전환 뒤 smoke는 프로젝트의 provider adapter가 맡는다. 이 adapter는
|
|
hosting provider를 고를 때 함께 정한다. 슬롯이 비어 있는 동안 FE-GATE-019는 호스트를
|
|
probe하지 않고 `UNVERIFIED`로 끝난다. 슬롯을 채우는 방법은
|
|
[`ci-quality-gates.md`](ci-quality-gates.md)에 있다(리뷰 1101/13-01).
|
|
|
|
내린 release의 hashed asset은 열린 탭이 아직 요청할 수 있는 동안 닿을 수 있게 둔다.
|
|
최소한 다음 release가 활성인 동안 이전 release 하나는 남긴다
|
|
(`tests/release/release-fixture.ts`가 모형으로 만든 rolling window). 보관 기간은 제품이
|
|
지원하는 가장 긴 세션에 맞춘다. 그보다 오래된 탭은 한 번 새로 고치는 복구(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의 루트(`/`)나 빌드한 하위 경로(`VITE_ROUTER_BASE_PATH`, 예 `/app/`)에서
|
|
내보낸다. 인증서가 유효하고, 어느 surface도 그 origin 밖으로 redirect하지 않는다. —
|
|
FE-GATE-019가 잰다. `HOSTING_BASE_URL`은 release의 기준 URL(루트 또는 `/`로 끝나는 그
|
|
하위 경로, query·fragment 없음)이다. probe는 surface 경로(`config/hosting/cache-policy.json`)를
|
|
그 아래에서 요청하고, 후보의 진입 script가 그 경로 아래에 있는지와 surface마다 최종
|
|
origin을 본다.
|
|
2. TLS에서 HTTP/2를 맺는다(ALPN `h2`). — FE-GATE-019가 잰다(`transport.alpnProtocols`).
|
|
|
|
**surface별 응답** (surface: probe가 요청하는 경로 하나)
|
|
|
|
3. `index.html`은 `Cache-Control: no-cache`와 `text/html`로 준다. — FE-GATE-019가
|
|
`/`로 잰다(`surfaces.index`).
|
|
4. 빌드에 파일이 없는 모든 앱 경로(새로 고침, 북마크, 공유 링크)에는 200으로 그 release의
|
|
`index.html`을 3과 같은 헤더로 준다(SPA fallback). — FE-GATE-019가 잰다
|
|
(`surfaces.appRoute`, `/__probe/deep-link`).
|
|
5. `config.json`과 `release-manifest.json`은 `Cache-Control: no-store`와
|
|
`application/json`으로 준다. — FE-GATE-019가 잰다(`surfaces.runtimeConfig`,
|
|
`surfaces.releaseManifest`).
|
|
6. 3~5의 응답에는 `config/hosting/security-headers.json`의 헤더를 모두 그 값 그대로
|
|
붙인다. — FE-GATE-019가 잰다(`securityHeaders`가 참인 surface).
|
|
7. 오류 응답(404, 5xx)에도 6의 보안 헤더를 붙인다. — 아무도 재지 않는다. probe는 200
|
|
응답만 본다.
|
|
8. `assets/` 아래 hashed 파일은
|
|
`Cache-Control: public, max-age=31536000, immutable`로 준다. — 진입 스크립트 하나는
|
|
FE-GATE-019가 잰다(`surfaces.hashedAsset`). 나머지 파일의 `Cache-Control`은 아무도 재지
|
|
않는다.
|
|
9. hashed 파일은 redirect 없이 200으로, 확장자에 맞는 `Content-Type`으로 준다. —
|
|
FE-GATE-019가 확장자마다 첫 파일 하나를 잰다(위 단락, `CACHEABLE_ASSET_CONTENT_TYPES`).
|
|
10. JavaScript는 압축해서 보낸다(`br`, `gzip`, `zstd` 중 하나). 번들 예산이 gzip 크기를
|
|
센다. — 진입 스크립트는 FE-GATE-019가 잰다(`hashedAsset.contentEncodings`). 나머지
|
|
청크는 아무도 재지 않는다. CSS·JSON·SVG 압축은 예산이 기대지 않고, 아무도 재지 않는다.
|
|
11. 압축한 응답에는 `Vary: Accept-Encoding`을 붙인다. 공유 캐시가 압축한 본문을 압축을 받지
|
|
못하는 클라이언트에 주지 않게 한다. — 아무도 재지 않는다.
|
|
12. 없는 hashed 파일을 요청하면 404로 답한다. `index.html`로 대신 답하지 않는다. 옛 탭은
|
|
그 실패를 봐야 한 번 새로 고친다(FE-RB-002). — 아무도 재지 않는다.
|
|
13. 404 같은 오류 응답에는 `immutable` 캐시 헤더를 붙이지 않는다. 붙이면 브라우저와 CDN이
|
|
그 실패를 hashed 파일처럼 오래 저장한다. — 아무도 재지 않는다.
|
|
14. 빌드가 Service Worker를 실으면 `/service-worker.js`는 redirect 없이 200,
|
|
`Cache-Control: no-cache`, JavaScript `Content-Type`으로 준다. — FE-GATE-019가 잰다
|
|
(`surfaces.serviceWorker`).
|
|
15. 빌드가 worker를 싣지 않으면 `/service-worker.js`는 404로 답한다. SPA fallback이
|
|
`index.html`로 대신 답하지 않는다(아래 「Service Worker 절차」 4). — 아무도 재지 않는다.
|
|
worker가 없는 빌드에서는 probe가 이 경로를 요청하지 않는다.
|
|
16. 소스맵을 공개하지 않는다. — release의 `dist`에 `.map`이 없는지는 FE-GATE-019가
|
|
잰다(`surfaces.sourceMap`). 호스트가 `.map` 요청을 404로 막는지는 아무도 재지 않는다.
|
|
|
|
**배포와 롤백**
|
|
|
|
17. release 묶음(`index.html`, `config.json`, `release-manifest.json`,
|
|
`service-worker.js`)을 한 번에 바꾼다. 옛 파일과 새 파일이 섞여 보이는 순간이 없다. —
|
|
바꾼 뒤 `release-manifest.json`·`config.json`·`index.html`이 이 release의 것인지는
|
|
FE-GATE-019가 잰다. 바꾸는 도중에 섞이지 않는지는 아무도 재지 않는다.
|
|
18. 지난 release의 hashed 파일을 release를 바꿀 때 지우지 않는다. 이름이 겹치지 않으므로 한
|
|
곳에 모아 둘 수 있고, 보관 기간(위 단락)이 지난 것만 지운다. — 호스트에서는 아무도
|
|
재지 않는다. 템플릿 안의 호스트 모형(`tests/release/release-fixture.ts`)은
|
|
`tests/release/old-asset-reachability.test.ts`가 시험한다.
|
|
19. 롤백은 지난 release의 묶음(17)을 그대로 다시 내보낸다. 옛 commit을 다시 빌드하거나
|
|
HTML만 바꾸지 않는다(맨 위 단락). 18 덕분에 그 release의 hashed 파일은 남아 있다. —
|
|
되돌릴 release의 묶음과 파일은 바꾸기 전에 `drill:runbook -- FE-RB-005`가 확인한다.
|
|
호스트에서 바꾼 결과는 아무도 재지 않는다. 그 drill은 `UNVERIFIED`로 끝난다(위 단락).
|
|
|
|
## Service Worker 절차 (정적 선택이 `null`이 아닐 때만)
|
|
|
|
worker는 release 묶음의 일부다. `service-worker.js`는 그것이 캐시하는 HTML, asset과 같은
|
|
빌드에서 나온다.
|
|
|
|
1. **롤백 N+1 → N.** 묶음을 바꾸면 N의 `service-worker.js`를 내보낸다. 브라우저의
|
|
업데이트 검사가 그것을 설치한다. worker는 install 때 `skipWaiting()`을 부르지 않는다
|
|
(`src/adapters/service-worker/service-worker-entry.ts`). 그래서 scope의 모든 탭이
|
|
닫히거나 페이지가 `requestActivation()`을 부를 때까지 기다린다. 템플릿에는 그것을
|
|
부르는 페이지가 없다. 캐시 이름은 asset 묶음의 digest다. 그래서 N의 캐시가 남겨 둔
|
|
이전 캐시로 아직 있으면 install은 그것을 다시 쓰고, 실패해도 지우지 않는다
|
|
(`service-worker-static-assets.ts` `installStaticAssets`). 아직 N+1에 있는 탭은
|
|
worker N+1을 유지한다. 그래서 N+1의 asset은 위의 rolling window 동안 닿을 수 있다.
|
|
owned cache를 지우는 것은 activation뿐이다. activation은 현재 캐시와 가장 높게 표시된
|
|
이전 캐시 하나를 남긴다. worker가 기다리는 동안에는 기다리는 worker를 바꾸는
|
|
release마다 자기 캐시를 남긴다. 그래서 scope의 탭이 닫힐 때까지 release마다 precache가
|
|
하나씩 쌓인다(리뷰 1103/06-04; `docs/operations/browser-file-storage-recovery.md` §8).
|
|
2. **다시 빌드하지 않고 worker 끄기.** runtime config에
|
|
`CAPABILITY_OVERRIDES.SERVICE_WORKER: "DISABLED"`를 넣는다. 다음 boot는 owned
|
|
registration을 해제하고 아무것도 등록하지 않는다. owned cache는 남는다
|
|
(`src/contracts/runtime-capabilities.ts` `resolveRuntimeCapabilities`,
|
|
`service-worker-page-controller.ts` `start()`). 이 방법은 페이지가 boot할 수 있어야
|
|
쓴다. 사본을 고치고, 호스트가 내주는 파일을 바꾸기 전에
|
|
`check:release-admission --config <copy> --original <deployed>`로 검사한다
|
|
(`docs/runbooks/FE-RB-001.md`).
|
|
3. **worker 때문에 페이지가 boot하지 못할 때.** 정적 선택이 `REMOVE_REGISTRATION`인
|
|
release를 배포한다. 이 release는 스스로 등록을 해제하는 `service-worker.js`를 싣는다
|
|
(`scripts/build-frontend.ts`, `scripts/lib/self-unregistering-service-worker.ts`).
|
|
업데이트 검사가 그것을 고장 난 worker 위에 설치한다. 그 worker는 대기하지 않고(skip
|
|
waiting), activation 때 등록을 해제하며, 어떤 fetch에도 답하지 않는다. 다음 로드는
|
|
worker의 제어를 받지 않는다(`tests/e2e/service-worker-recovery.spec.ts`). runbook:
|
|
`docs/operations/browser-file-storage-recovery.md` §8.
|
|
4. **worker 제거**는 release 세 번이 걸린다.
|
|
`REMOVE_REGISTRATION` → `PURGE_OWNED_RESOURCES`(owned cache 삭제) →
|
|
`null`(`src/contracts/service-worker.ts` `InstalledServiceWorkerSelection`).
|
|
스스로 등록을 해제하는 `service-worker.js`는 `REMOVE_REGISTRATION` release만 싣는다.
|
|
이 release는 사용자가 가장 오래 접속하지 않을 수 있는 기간 이상 배포해 둔다. 그 뒤
|
|
release에는 worker 파일이 없어서 업데이트 검사가 404로 실패한다.
|
|
`PURGE_OWNED_RESOURCES`에서는 boot하는 페이지만 옛 worker 등록을 해제하고, `null`에서는
|
|
아무것도 해제하지 않는다(리뷰 0929/06-06).
|