Files
DongHyeonka 06ffafa25e docs: 살아 있는 문서의 낡은 문장을 지금 코드와 정본에 맞춘다
2026-11-07~08의 정리(문서 이동, 참조 기능 삭제, CI 재편) 뒤 살아 있는
문서가 지금 코드와 다른 말을 한다.

- 현재 계약 문서 둘과 스타터 문서가 기록(docs/design/)을 정본으로
  가리킨다. 정본을 frontend-application-foundation.md·src/bootstrap/,
  패턴 표·계층 규칙으로 바꾸고 설계서는 배경으로 둔다(1112/02-06).
- 실시간 대응표 둘(짝 백엔드 출구, poll attempt 결과)이 기록에만 있었다.
  optional-adapter-recipes.md로 옮기고 코드 주석·매뉴얼 03·설계서 머리
  블록이 옮긴 곳을 가리킨다(1112/09-02).
- 실행 격리 변수 목록을 설계 기록이 아니라 scripts/lib/run-isolation.ts로
  가리킨다(1112/08-17).
- 계약 소유 절 이름(「판단 규칙」), pin 대조 시험의 게이트(005·007),
  drift 검사 범위(1112/02-07). INVENTORY 머리의 손 숫자와 지킬 수 없는
  꼬리 문장(1112/02-08).
- 검증 안내: 검사기를 바꾸면 FE-GATE-029, 문서면 desktop
  verify:documentation(1112/08-05, 08-04). FE-GATE-012는 merge 단계다
  (08-16). N6이 알리는 파일을 좁혀 적는다(08-10). 한 파일 시험은
  verify.sh exec(08-11). 문서 검사 범위의 손 사본을 정본 한 곳으로(08-07).
- create:feature 참조의 Next: 3과 되돌리기(08-08), 손으로 옮긴 숫자
  (08-19), 라운드 없는 리뷰 ID 17곳에 0925를 붙인다(08-15).
- secret scan 범위 설명(1112/07-03), lab이 기능 라우트를 읽는 문장
  (1103/16-06), README 동기화 기준점·제품 소유 파일·선택 기능 결함 몫
  (0929/14-02, 14-03, 13-10), 커밋을 다시 지은 모든 통합의 해시 대조
  (1106/14-02).

고른 방법: 문장을 코드에 맞춘다. 표는 옮기고 숫자는 정본을 가리킨다.
버린 대안: 기록 문서 본문 고치기(기록은 머리 블록만 고친다).

위험·한계: 문서 검사 범위 목록을 지운 ci-quality-gates.md는 이제
docs/README.md 5절과 gates.md 7절을 읽어야 한다. 매뉴얼 02 7절 업로드
예의 declare module 문제(1112/09-01)는 고치는 방향이 check:architecture
규칙과 부딪쳐 결정 대기로 남긴다.

검증: scripts/verify.sh docs(노트북) 통과. desktop verify:documentation과
FE-GATE-005(문서를 읽는 시험)는 PR 본문에 적는다.

Refs: 1112/02-06, 1112/02-07, 1112/02-08, 1112/07-03, 1112/08-04,
 1112/08-05, 1112/08-07, 1112/08-08, 1112/08-10, 1112/08-11, 1112/08-15,
 1112/08-16, 1112/08-17, 1112/08-19, 1112/09-02, 1103/16-06, 0929/14-02,
 0929/14-03, 0929/13-10, 1106/14-02
2026-11-12 23:36:14 +09:00

231 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의 루트(`/`)에서 내보낸다. 인증서가 유효하고, 어느 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가 요청하는 경로 하나)
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).