diff --git a/docs/architecture/static-delivery.md b/docs/architecture/static-delivery.md index 66caf133..bcf8c6d1 100644 --- a/docs/architecture/static-delivery.md +++ b/docs/architecture/static-delivery.md @@ -56,7 +56,7 @@ Serve JavaScript compressed (gzip, brotli or zstd). The bundle budget counts gzip bytes; uncompressed, the initial JavaScript is about three times larger. Both premises are declared in `config/hosting/cache-policy.json` (`transport.alpnProtocols`, `hashedAsset.contentEncodings`), and the live probe -of FE-GATE-019 fails a host that does not meet them (review 1103/13-02). The -nginx example in -[`release-cache-rollback.md`](../operations/release-cache-rollback.md) turns -both on. +of FE-GATE-019 fails a host that does not meet them (review 1103/13-02). Every +condition the host has to meet, and what checks each one, is in 「운영 환경이 +지켜야 할 조건」 in +[`release-cache-rollback.md`](../operations/release-cache-rollback.md#운영-환경이-지켜야-할-조건). diff --git a/docs/operations/ci-quality-gates.md b/docs/operations/ci-quality-gates.md index ebb83275..e65b6c49 100644 --- a/docs/operations/ci-quality-gates.md +++ b/docs/operations/ci-quality-gates.md @@ -218,26 +218,9 @@ sandbox는 `bwrap --unshare-pid --unshare-ipc --unshare-uts --unshare-net`으로 namespaces"와 bwrap의 stderr, 위 sysctl 값, 고치는 방법을 적고 exit 1로 멈춘다. 전에는 이 검사가 PASS를 낸 뒤 provider 테스트가 bwrap 원문 오류로 실패했다(2026-11-05 desktop에서 114건 중 18건). -- 고치는 방법은 셋 중 하나다. 호스트의 보안 설정을 바꾸는 일이므로 호스트 - 소유자가 고른다. - 1. `/usr/bin/bwrap`에 `userns`를 허용하는 AppArmor profile을 둔다. Ubuntu - 문서가 안내하는 형태는 아래와 같다. `/etc/apparmor.d/bwrap`에 두고 - `sudo apparmor_parser -r /etc/apparmor.d/bwrap`으로 읽게 한다. - 2. 직접 관리하는 호스트라면 sysctl - `kernel.apparmor_restrict_unprivileged_userns=0`으로 제한을 끈다. 이 설정이 - 없는 커널에서는 `kernel.unprivileged_userns_clone=1`이 같은 역할이다. - 3. 비특권 user namespace를 허용하는 다른 runner에서 FE-GATE-013과 provider - job을 돌린다. - -```text -abi , -include - -profile bwrap /usr/bin/bwrap flags=(unconfined) { - userns, - include if exists -} -``` +- 고치는 방법은 `scripts/check-system-test-prerequisites.ts`가 실패할 때 + 출력한다. 호스트의 보안 설정을 바꾸는 일이므로 호스트 소유자가 고른다. + 호스트를 바꾸는 설정 파일과 명령은 runner를 만드는 쪽의 인프라 repo가 갖는다. 각 provider는 고유한 collected user scope에서 실행된다. Supervisor는 실행 전에 실제 cgroup membership과 `memory.max=1073741824`, `memory.swap.max=0`, diff --git a/docs/operations/release-cache-rollback.md b/docs/operations/release-cache-rollback.md index 5d782079..a997ec55 100644 --- a/docs/operations/release-cache-rollback.md +++ b/docs/operations/release-cache-rollback.md @@ -112,83 +112,6 @@ declaration in `config/hosting/cache-policy.json` in the same change that groups its initial chunks ("초기 청크 수와 HTTP/1.1" in [`performance-evidence.md`](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. - -```nginx -# /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; -``` - -```nginx -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 @@ -204,6 +127,79 @@ 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가 요청하는 경로 하나) + +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 steps」 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 steps (only when the static selection is not `null`) The worker is part of the release tuple: `service-worker.js` comes from the