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:
+5
-2
@@ -5,8 +5,11 @@
|
||||
#
|
||||
# Runtime configuration — API endpoints, auth mode, telemetry, capability
|
||||
# switches — is NOT here. It lives in `config/runtime/<profile>.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.
|
||||
|
||||
|
||||
@@ -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` 분기). 소유
|
||||
|
||||
@@ -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 <copy> --original <deployed>` 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`,
|
||||
|
||||
@@ -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=<environment> 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/<environment>.json`) for the next build.
|
||||
|
||||
@@ -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,
|
||||
|
||||
@@ -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<string, unknown>) => Record<string, unknown>,
|
||||
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<string, unknown>, value: string) => ({
|
||||
...deployed,
|
||||
CAPABILITY_OVERRIDES: {
|
||||
...(deployed["CAPABILITY_OVERRIDES"] as Record<string, unknown>),
|
||||
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");
|
||||
});
|
||||
});
|
||||
|
||||
Reference in New Issue
Block a user