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:
@@ -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,
|
||||
|
||||
Reference in New Issue
Block a user