From b3af26fc0ec4698a224fc4161e320d3ca7067ead Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Sun, 1 Nov 2026 22:17:35 +0900 Subject: [PATCH] =?UTF-8?q?fix(release):=20=EB=B0=B0=ED=8F=AC=EB=90=9C=20c?= =?UTF-8?q?onfig.json=20=EC=82=AC=EB=B3=B8=EC=9D=84=20=EB=B0=94=EA=BE=B8?= =?UTF-8?q?=EA=B8=B0=20=EC=A0=84=EC=97=90=20=EA=B2=80=EC=82=AC=ED=95=9C?= =?UTF-8?q?=EB=8B=A4=20(1101/13-05)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제 .env.example과 운영 문서는 runtime config를 재빌드 없이 바꿀 수 있다고 적는다(SERVICE_WORKER DISABLED, FEATURE_OVERRIDES). 그런데 고친 문서를 검사할 명령이 없다. check:release-admission은 dist/config.json만 읽고, build:profile은 BUILD_ID를 덮어 다시 만든다. 브라우저는 부팅 때 문서를 스키마로 검사하고 BUILD_ID를 HTML과 맞춰 보므로, 오타 하나나 BUILD_ID 변경 하나가 모든 사용자의 BOOT_CONFIG_FAILURE가 된다. FE-RB-001은 세 줄이고 고치는 방법이 없다. 고른 방법 - check-release-admission.ts가 `--config <고친 사본> --original <배포된 원본>`을 받는다. 사본에 기존 검사(스키마, 대상 규칙)를 그대로 돌리고, 원본과 비교해 CAPABILITY_OVERRIDES·FEATURE_OVERRIDES 밖의 필드가 하나라도 바뀌면 거절한다. BUILD_ID·RELEASE_ID 유지는 이 규칙에 들어 있다. `--original` 없이 `--config`만 주면 거절한다(비교 대상 없이 통과시키지 않는다). - 사본 검사는 artifacts/release/deployment-admission.json을 쓰지 않는다. 그 파일은 빌드의 승인 증거(CI artifact)이고 운영자의 사본은 빌드가 아니다. - FE-RB-001에 네 단계(사본 두 개 받기·고치기 → 검사 → 같은 파일시스템에서 rename으로 교체, 되돌리기도 같은 방법 → 깨끗한 세션 부팅 확인)를 적고, release-cache-rollback.md와 browser-file-storage-recovery.md의 스위치 설명이 그 절차를 가리킨다. .env.example 문장을 "비상 스위치만 재빌드 없이 바꾼다"로 좁혔다. - pnpm이 `--`를 넘겨도 되도록 맨 앞 `--`를 버린다. 버린 대안 - `--build-id `로 BUILD_ID만 대조: API_BASE_URL·RELEASE_MANIFEST_URL처럼 빌드가 정한 다른 필드를 바꿔도 통과한다. 원본 전체 비교가 같은 비용으로 더 좁다. - release-manifest.json에서 build id를 읽기: 운영자가 받을 파일이 하나 더 늘고, 여전히 BUILD_ID만 본다. - 비상 스위치도 빌드로만 바꾸기: 장애 대응 시간이 빌드·승격 시간만큼 늘어 스위치의 목적이 사라진다(리뷰 대안 비교). 위험·한계 - 원본과 사본의 중첩 객체 비교는 JSON.stringify라 키 순서만 달라도 "바뀜"으로 거절한다(닫힌 쪽으로 실패). - 실제 서버에서 사본을 바꿔 부팅해 보지 않았다. 바뀐 문서가 release 기록(checksums.txt, 승격 archive)과 달라지는 점은 런북에 적기만 했다. 검증 - RED: node scripts/run-vitest.ts run tests/unit/deployment-admission.test.ts 새 6건 실패. 모두 "release admission refused: dist/config.json is unreadable"(--config를 무시하고 dist를 읽음) - GREEN: 같은 파일 22 passed. 스위치만 바꾼 사본 ADMITTED·기록 없음, SERVICE_WORKER "DISABLE" 오타·BUILD_ID/RELEASE_ID/API_BASE_URL 변경· --original 누락은 exit 1 - runbook-contract, runbook-drill, feature-override-diagnostics 포함 35 passed - 실제 local 빌드에서 인자 없는 기존 경로 ADMITTED(기록 작성), `-- --config dist/config.json --original public/config.json` ADMITTED - tsc(node, test), eslint 바뀐 파일, verify-documentation-readiness PASS_SCOPED Refs: docs/reviews/2026-11-01-maturity-review/13-build-release-supply-chain.md 13-05 --- .env.example | 7 +- .../browser-file-storage-recovery.md | 3 +- docs/operations/release-cache-rollback.md | 4 +- docs/runbooks/FE-RB-001.md | 23 ++++ scripts/check-release-admission.ts | 116 ++++++++++++++---- tests/unit/deployment-admission.test.ts | 70 +++++++++++ 6 files changed, 198 insertions(+), 25 deletions(-) diff --git a/.env.example b/.env.example index 47d62975..80f19b81 100644 --- a/.env.example +++ b/.env.example @@ -5,8 +5,11 @@ # # Runtime configuration — API endpoints, auth mode, telemetry, capability # switches — is NOT here. It lives in `config/runtime/.json` and is -# materialized into `dist/config.json` at build time, so it can be changed -# without rebuilding. See the "Runtime configuration" section of README.md. +# materialized into `dist/config.json` at build time. Only the emergency +# switches (CAPABILITY_OVERRIDES, FEATURE_OVERRIDES) may be changed in a +# deployed config.json without rebuilding, by the checked procedure in +# docs/runbooks/FE-RB-001.md. See the "Runtime configuration" section of +# README.md. # # Copy to `.env.local` (git-ignored) to override locally. diff --git a/docs/operations/browser-file-storage-recovery.md b/docs/operations/browser-file-storage-recovery.md index d7ace2c2..257f0c83 100644 --- a/docs/operations/browser-file-storage-recovery.md +++ b/docs/operations/browser-file-storage-recovery.md @@ -515,7 +515,8 @@ Service Worker를 별도 선택한 조합에서만 추가. 워커의 fetch 가 스위치는 없다. 끄는 경로는 아래 둘이다. - 페이지가 부팅하면: runtime config에 `CAPABILITY_OVERRIDES.SERVICE_WORKER: - "DISABLED"`를 넣는다. 재빌드는 필요 없다. 다음 부팅 때 page controller가 scope와 + "DISABLED"`를 넣는다. 재빌드는 필요 없다. 사본을 고쳐 검사한 뒤 바꾸는 절차는 + `docs/runbooks/FE-RB-001.md`에 있다. 다음 부팅 때 page controller가 scope와 script가 정확히 일치하는 등록만 unregister하고, 새 등록은 하지 않는다 (`src/contracts/runtime-capabilities.ts` `resolveRuntimeCapabilities`, `service-worker-page-controller.ts` `start()`의 `disabledCleanup` 분기). 소유 diff --git a/docs/operations/release-cache-rollback.md b/docs/operations/release-cache-rollback.md index a7c11402..77fae814 100644 --- a/docs/operations/release-cache-rollback.md +++ b/docs/operations/release-cache-rollback.md @@ -173,7 +173,9 @@ same build as the HTML and assets it caches. 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. + This needs a page that boots. Edit a copy and check it with + `check:release-admission --config --original ` 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`, diff --git a/docs/runbooks/FE-RB-001.md b/docs/runbooks/FE-RB-001.md index c40abd1e..42f53c5f 100644 --- a/docs/runbooks/FE-RB-001.md +++ b/docs/runbooks/FE-RB-001.md @@ -7,3 +7,26 @@ the release owner. Close only after a clean-session boot mounts the product root, config validation evidence passes, and repeated boot-error telemetry is absent. + +## Changing an emergency switch without a rebuild + +Only `CAPABILITY_OVERRIDES` and `FEATURE_OVERRIDES` may change in a deployed +`config.json`. Every browser validates the document on boot, so a typo there +causes this runbook's failure for every user. Change it in four steps: + +1. Download the deployed `config.json` twice, as `deployed.json` (keep it as + is) and `edited.json`. Change only the switch in `edited.json`. +2. From a checkout of the deployed commit, run + `RELEASE_TARGET= corepack pnpm check:release-admission --config /abs/edited.json --original /abs/deployed.json` + (absolute paths: pnpm runs it from the repository root). It must print + `ADMITTED`. It refuses a schema error, a target rule, and any changed field + other than the two switches, `BUILD_ID` and `RELEASE_ID` included. +3. Upload `edited.json` next to the live file and rename it over + `config.json` on the same filesystem. Never edit the live file in place. + To undo, rename `deployed.json` back the same way. +4. Boot in a clean session (new browser profile) and see the product root + mount. The switch takes effect on the next boot only. + +The served document then differs from the release record (`checksums.txt`, +the promoted archive). Note the change in the release log, and put it in the +profile (`config/runtime/.json`) for the next build. diff --git a/scripts/check-release-admission.ts b/scripts/check-release-admission.ts index 15e0299b..a5d4d9f9 100644 --- a/scripts/check-release-admission.ts +++ b/scripts/check-release-admission.ts @@ -1,5 +1,6 @@ import { mkdir, readFile, writeFile } from "node:fs/promises"; import process from "node:process"; +import { parseArgs } from "node:util"; import { DEPLOYMENT_TARGETS, @@ -29,7 +30,62 @@ import { COMPILED_PRODUCT_FEATURE_IDS } from "../src/features/installed-product- const RUNTIME_CONFIG_PATH = "dist/config.json"; const RECORD_PATH = "artifacts/release/deployment-admission.json"; +/** + * 1101/13-05. The only fields an operator may change in a deployed config.json + * without a rebuild (docs/runbooks/FE-RB-001.md). Every other field belongs to + * the build: BUILD_ID and RELEASE_ID must still match the deployed HTML and + * release manifest, or every boot stops with CONFIG_BUILD_MISMATCH. + */ +const EMERGENCY_SWITCHES: ReadonlySet = new Set([ + "CAPABILITY_OVERRIDES", + "FEATURE_OVERRIDES", +]); + +function refuse(reason: string): void { + process.stderr.write(`release admission refused: ${reason}\n`); + process.exitCode = 1; +} + +function errorMessage(error: unknown): string { + return error instanceof Error ? error.message : String(error); +} + +async function readRuntimeConfig(file: string): Promise { + let document: unknown; + try { + document = JSON.parse(await readFile(file, "utf8")); + } catch (error) { + refuse(`${file} is unreadable: ${errorMessage(error)}`); + return null; + } + try { + return parseRuntimeConfigArtifact(document) as AdmissionInput; + } catch (error) { + refuse(`${file} is not a valid runtime config: ${errorMessage(error)}`); + return null; + } +} + +function changedBuildFields(original: object, edited: object): string[] { + const before = new Map(Object.entries(original)); + const after = new Map(Object.entries(edited)); + return [...new Set([...before.keys(), ...after.keys()])] + .filter( + (field) => + !EMERGENCY_SWITCHES.has(field) && + JSON.stringify(before.get(field)) !== JSON.stringify(after.get(field)), + ) + .sort(); +} + async function main(): Promise { + // `pnpm check:release-admission -- --config …` may pass the separator through. + const argv = process.argv.slice(2); + if (argv[0] === "--") argv.shift(); + const { values: options } = parseArgs({ + args: argv, + options: { config: { type: "string" }, original: { type: "string" } }, + }); const declared = process.env["RELEASE_TARGET"]; if (!isDeploymentTarget(declared)) { process.stderr.write( @@ -54,30 +110,30 @@ async function main(): Promise { return; } - let document: unknown; - try { - document = JSON.parse(await readFile(RUNTIME_CONFIG_PATH, "utf8")); - } catch (error) { - process.stderr.write( - `release admission refused: ${RUNTIME_CONFIG_PATH} is unreadable: ${ - error instanceof Error ? error.message : String(error) - }\n`, + // 1101/13-05. An edited copy of the deployed document is checked against + // that document, so a changed build field is refused, not just a bad value. + const editedCopy = options.config; + if (editedCopy !== undefined && options.original === undefined) { + refuse( + "--config needs --original ; " + + "BUILD_ID, RELEASE_ID and every other build field are compared with it.", ); - process.exitCode = 1; return; } - - let config: AdmissionInput; - try { - config = parseRuntimeConfigArtifact(document) as AdmissionInput; - } catch (error) { - process.stderr.write( - `release admission refused: ${RUNTIME_CONFIG_PATH} is not a valid runtime config: ${ - error instanceof Error ? error.message : String(error) - }\n`, - ); - process.exitCode = 1; - return; + const configPath = editedCopy ?? RUNTIME_CONFIG_PATH; + const config = await readRuntimeConfig(configPath); + if (config === null) return; + if (options.original !== undefined) { + const original = await readRuntimeConfig(options.original); + if (original === null) return; + const changed = changedBuildFields(original, config); + if (changed.length > 0) { + refuse( + `${configPath} changes ${changed.join(", ")}; without a rebuild only ` + + `${[...EMERGENCY_SWITCHES].join(" and ")} may change.`, + ); + return; + } } const violations = findAdmissionViolations(declared, config); @@ -93,6 +149,24 @@ async function main(): Promise { for (const warning of warnings) { process.stderr.write(`release admission warning: ${warning.field} ${warning.reason}\n`); } + if (editedCopy !== undefined) { + // The record is the build's admission evidence (a CI artifact); an + // operator's edited copy is not the build and does not replace it. + if (violations.length > 0) { + refuse( + `${editedCopy} for ${declared}:\n${violations + .map((violation) => ` ${violation.field}: ${violation.reason}`) + .join("\n")}`, + ); + return; + } + process.stdout.write( + `release admission: ${editedCopy} ADMITTED for ${declared}; no field other than ` + + `${[...EMERGENCY_SWITCHES].join(" and ")} differs from ${options.original}. ` + + "Not recorded: this checks an edited copy, not the build.\n", + ); + return; + } await mkdir("artifacts/release", { recursive: true }); await writeFile( RECORD_PATH, diff --git a/tests/unit/deployment-admission.test.ts b/tests/unit/deployment-admission.test.ts index 64ee6599..98ceb542 100644 --- a/tests/unit/deployment-admission.test.ts +++ b/tests/unit/deployment-admission.test.ts @@ -269,3 +269,73 @@ describe("runtime config profiles", () => { } }); }); + +// 1101/13-05. The emergency switches (CAPABILITY_OVERRIDES, FEATURE_OVERRIDES) +// are changed in the deployed config.json without a rebuild. A typo there stops +// every boot, so the edited copy is checked against the deployed one first. +describe("checking an edited copy of the deployed runtime config", () => { + async function check( + edit: (deployed: Record) => Record, + args: readonly string[] = ["--config", "edited.json", "--original", "deployed.json"], + ) { + const root = await mkdtemp(path.join(tmpdir(), "release-admission-copy-")); + try { + const deployed = await generateRuntimeConfig("production", { + VITE_BUILD_ID: "20260815.42", + RELEASE_ID: "r-2026.08.15-1", + }); + await writeFile(path.join(root, "deployed.json"), JSON.stringify(deployed)); + await writeFile(path.join(root, "edited.json"), JSON.stringify(edit(deployed))); + const result = spawnSync( + process.execPath, + [path.resolve("scripts/check-release-admission.ts"), ...args], + { + cwd: root, + encoding: "utf8", + env: { ...process.env, APP_PROFILE: "production", RELEASE_TARGET: "production" }, + }, + ); + const records = await readdir(path.join(root, "artifacts/release")).catch(() => []); + return { status: result.status, stderr: result.stderr, stdout: result.stdout, records }; + } finally { + await rm(root, { recursive: true, force: true }); + } + } + const withServiceWorker = (deployed: Record, value: string) => ({ + ...deployed, + CAPABILITY_OVERRIDES: { + ...(deployed["CAPABILITY_OVERRIDES"] as Record), + SERVICE_WORKER: value, + }, + }); + + it("admits a copy that only flips an emergency switch, without writing the build's record", async () => { + const result = await check((deployed) => withServiceWorker(deployed, "DISABLED")); + expect(result.status, result.stderr).toBe(0); + expect(result.stdout).toContain("edited.json"); + expect(result.records).toEqual([]); + }); + + it("refuses a typo in a switch value", async () => { + const result = await check((deployed) => withServiceWorker(deployed, "DISABLE")); + expect(result.status).toBe(1); + expect(result.stderr).toMatch(/edited\.json is not a valid runtime config/u); + }); + + // A valid value, so only the comparison with the deployed copy can refuse it. + it.each([ + ["BUILD_ID", "20260815.43"], + ["RELEASE_ID", "r-2026.08.15-2"], + ["API_BASE_URL", "https://other.example.org/"], + ])("refuses a copy that changes %s, which only a build may change", async (field, value) => { + const result = await check((deployed) => ({ ...deployed, [field]: value })); + expect(result.status).toBe(1); + expect(result.stderr).toContain(`edited.json changes ${field}`); + }); + + it("refuses --config without the deployed original to compare with", async () => { + const result = await check((deployed) => deployed, ["--config", "edited.json"]); + expect(result.status).toBe(1); + expect(result.stderr).toContain("--original"); + }); +});