문제: (1) live probe는 배포된 release-manifest.json의 buildId·releaseId만 후보와 비교했다. 두 값은 CI run 번호로 만든 이름이라, 같은 run에서 로컬 프로필로 다시 빌드한 release(APP_ENV=local, AUTH_MODE=demo, loopback API)를 올려도 PASS(live)였다(리뷰 실험 E-2c). 공개 대상 승인 (FE-GATE-027)을 받은 것은 후보의 config.json인데, 호스트가 내주는 config.json은 헤더만 보았다. entry script도 호스트의 두 응답끼리만 비교했다. (2) 템플릿은 HTTP/2와 압축을 전제로 초기 청크를 나누고 gzip 바이트로 예산을 재는데, 그 전제가 호스팅 계약에 없고 probe도 보지 않았다. 템플릿 nginx 예시는 http2도 gzip도 켜지 않았다. 고른 방법: - 받은 /config.json을 후보 dist/config.json과 비교한다. 비상 스위치 두 개(CAPABILITY_OVERRIDES, FEATURE_OVERRIDES) 밖의 필드가 다르거나 읽을 수 없으면 FAIL. 규칙은 check-release-admission과 같은 함수 (scripts/lib/runtime-config-switches.ts)로 옮겨 같이 쓴다. - 받은 index.html의 entry script를 후보 index.html의 것과 비교한다. - cache-policy.json에 transport.alpnProtocols(["h2"])와 hashedAsset.contentEncodings(br, gzip, zstd)를 선언한다. probe는 TLS handshake의 ALPN(node:tls, h2와 http/1.1을 제안)과 entry script 응답의 Content-Encoding을 본다. Node fetch는 h2를 지원하는 서버에도 HTTP/1.1로 붙어서 프로토콜은 따로 확인해야 한다. - nginx 예시에 http2 on과 gzip·gzip_types를 넣고, static-delivery.md와 release-cache-rollback.md에 두 전제와 실패 조건을 적었다. 두 수정은 같은 probe 함수와 테스트를 고쳐 한 커밋에 넣었다. 버린 대안: archive SHA를 호스트에 올려 대조하기(호스트에 새 파일 규약이 생기고 일부 파일만 다른 배포는 못 잡는다). HTTP/2를 기록만 하기 (아무도 읽지 않는 경고는 청크를 묶는 결정을 부르지 못한다. 선언을 바꾸면 제품이 끌 수 있다). 위험·한계: HTTP/1.1만 되는 호스트는 이제 FE-GATE-019에서 FAIL한다. 그 제품은 cache-policy.json 선언을 바꾸고 초기 청크를 묶는다. 실제 nginx와 Gitea runner에서는 돌리지 않았다. 슬롯이 후보를 받도록 강제하는 계약 규칙은 다음 커밋(제품 overlay)에 있다. 검증: hosting-probe.test.ts에 같은 이름·다른 config.json → FAIL, 비상 스위치만 다름 → PASS, 읽을 수 없는 config.json → FAIL, 다른 entry → FAIL, ALPN http/1.1·없음 → FAIL, 압축 없는 entry → FAIL, 정책 선언 확인을 더했다(고치기 전 실패). 33건 통과. 로컬 자체 서명 TLS 서버 실험: http2.createSecureServer → "h2", https.createServer → "http/1.1", 인증서 이름 불일치 → ERR_TLS_CERT_ALTNAME_INVALID. verify:hosting-headers(fixture) UNVERIFIED exit 3, deployment-admission 통과. Refs: docs/reviews/2026-11-03-maturity-review/13-build-release-supply-chain.md 13-01, 13-02
200 lines
7.3 KiB
TypeScript
200 lines
7.3 KiB
TypeScript
import { mkdir, readFile, writeFile } from "node:fs/promises";
|
|
import process from "node:process";
|
|
import { parseArgs } from "node:util";
|
|
|
|
import {
|
|
DEPLOYMENT_TARGETS,
|
|
findAdmissionViolations,
|
|
isDeploymentTarget,
|
|
type AdmissionInput,
|
|
} from "../src/contracts/deployment-admission.ts";
|
|
import { unknownProductFeatureOverrides } from "../src/contracts/product-features.ts";
|
|
import { parseRuntimeConfigArtifact } from "../src/contracts/release-artifacts.ts";
|
|
import { EXPECTED_CONTRACT_SET_PACKAGES } from "../src/features/installed-contract-contributions.ts";
|
|
import { COMPILED_PRODUCT_FEATURE_IDS } from "../src/features/installed-product-manifest.ts";
|
|
import {
|
|
changedRuntimeConfigBuildFields,
|
|
RUNTIME_CONFIG_EMERGENCY_SWITCHES,
|
|
} from "./lib/runtime-config-switches.ts";
|
|
|
|
/**
|
|
* §6.4 / FE-GATE-027. Refuses to admit an artifact to an environment it was not
|
|
* built for.
|
|
*
|
|
* Release coherence already proves the artifacts agree with each other. It
|
|
* cannot prove they belong in production, because a local build is coherent
|
|
* with itself: `APP_ENV: local`, `AUTH_MODE: demo` and a loopback API pass
|
|
* every existing gate. This gate closes that by making the destination an
|
|
* explicit, declared input and refusing anything that does not match it.
|
|
*
|
|
* It fails closed in both directions. An undeclared destination is a refusal,
|
|
* not a default, so an artifact can never be admitted by omission; and every
|
|
* rule is stated as a reason to refuse, so an unreadable field cannot pass.
|
|
*/
|
|
|
|
const RUNTIME_CONFIG_PATH = "dist/config.json";
|
|
const RECORD_PATH = "artifacts/release/deployment-admission.json";
|
|
const EMERGENCY_SWITCHES = RUNTIME_CONFIG_EMERGENCY_SWITCHES;
|
|
|
|
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;
|
|
}
|
|
}
|
|
|
|
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(
|
|
"release admission refused: RELEASE_TARGET must be declared as one of " +
|
|
`${DEPLOYMENT_TARGETS.join(", ")}; received ${
|
|
declared === undefined ? "nothing" : declared
|
|
}.\n` +
|
|
"An artifact is never admitted by default — name the environment it is for.\n",
|
|
);
|
|
process.exitCode = 1;
|
|
return;
|
|
}
|
|
// 13-01: the build profile and the admission target are separate repository
|
|
// variables; a profile left on staging must not ship to production.
|
|
const profile = process.env["APP_PROFILE"];
|
|
if (profile !== undefined && profile !== declared) {
|
|
process.stderr.write(
|
|
`release admission refused: the artifact was built with APP_PROFILE=${profile} ` +
|
|
`but RELEASE_TARGET=${declared}. Set both to the same environment.\n`,
|
|
);
|
|
process.exitCode = 1;
|
|
return;
|
|
}
|
|
|
|
// 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.",
|
|
);
|
|
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 = changedRuntimeConfigBuildFields(original, config);
|
|
if (changed.length > 0) {
|
|
refuse(
|
|
`${configPath} changes ${changed.join(", ")}; without a rebuild only ` +
|
|
`${[...EMERGENCY_SWITCHES].join(" and ")} may change.`,
|
|
);
|
|
return;
|
|
}
|
|
}
|
|
|
|
// U7 (decision 2). The packages the build compiled; a placeholder identity
|
|
// from create:feature is refused for staging and production. An edited copy
|
|
// is checked without them: packages are a build field it cannot change, and
|
|
// the build's own admission checked them.
|
|
const violations = findAdmissionViolations(
|
|
declared,
|
|
config,
|
|
editedCopy === undefined ? EXPECTED_CONTRACT_SET_PACKAGES : [],
|
|
);
|
|
// 09-09. Inert by design (a shared document may name another build's
|
|
// features), so this warns instead of refusing.
|
|
const warnings = unknownProductFeatureOverrides(
|
|
COMPILED_PRODUCT_FEATURE_IDS,
|
|
"FEATURE_OVERRIDES" in config ? config.FEATURE_OVERRIDES : undefined,
|
|
).map((featureId) => ({
|
|
field: `FEATURE_OVERRIDES.${featureId}`,
|
|
reason: `names no feature this build declares (${COMPILED_PRODUCT_FEATURE_IDS.join(", ") || "none"}); the override does nothing`,
|
|
}));
|
|
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,
|
|
`${JSON.stringify(
|
|
{
|
|
schemaVersion: 1,
|
|
target: declared,
|
|
appEnv: config.APP_ENV,
|
|
authMode: config.AUTH_MODE,
|
|
apiBaseUrl: config.API_BASE_URL,
|
|
buildId: config.BUILD_ID ?? null,
|
|
releaseId: config.RELEASE_ID ?? null,
|
|
status: violations.length === 0 ? "ADMITTED" : "REFUSED",
|
|
violations,
|
|
warnings,
|
|
},
|
|
null,
|
|
2,
|
|
)}\n`,
|
|
"utf8",
|
|
);
|
|
|
|
if (violations.length > 0) {
|
|
process.stderr.write(
|
|
`release admission refused for ${declared}:\n${violations
|
|
.map((violation) => ` ${violation.field}: ${violation.reason}`)
|
|
.join("\n")}\n`,
|
|
);
|
|
process.exitCode = 1;
|
|
return;
|
|
}
|
|
process.stdout.write(
|
|
`release admission: ${declared} ADMITTED ` +
|
|
`(APP_ENV=${config.APP_ENV}, AUTH_MODE=${config.AUTH_MODE}, ` +
|
|
`API=${config.API_BASE_URL}); record at ${RECORD_PATH}\n`,
|
|
);
|
|
}
|
|
|
|
await main();
|