fix(release): 배포된 config.json 사본을 바꾸기 전에 검사한다 (1101/13-05)

문제
.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 <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
This commit is contained in:
DongHyeonka
2026-11-01 22:49:13 +09:00
parent 629c8f045e
commit b3af26fc0e
6 changed files with 198 additions and 25 deletions
+95 -21
View File
@@ -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<string> = 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<AdmissionInput | null> {
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<void> {
// `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<void> {
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 <the deployed config.json before the edit>; " +
"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<void> {
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,