문제
production_gate는 promotion 직후 같은 run에서 시작하고 그 사이에 배포 job이
없다. CI 계약이 job 9개·그래프·env를 정확히 고정해 배포 job을 넣을 자리도
없다. live probe는 헤더만 보고 배포된 release가 승격 후보인지 확인하지
않는다. FE-GATE-019의 명령은 [build, verify-hosting-headers]라서 local
프로필로 다시 빌드한 dist를 검사한다. 그래서 FE-GATE-019 PASS는 "지금 떠
있는 release(대개 이전 것)의 헤더가 맞다"는 거짓 PASS다.
고른 방법 (리뷰 대안 (c), (1)~(3))
(1) live probe가 배포된 release-manifest.json의 buildId·releaseId를 후보와
비교한다. 다르거나 읽을 수 없으면 FAIL(releaseManifest build-id·
release-id). 후보는 검사하는 dist의 release-manifest.json이다.
(2) FE-GATE-019에서 build를 뺀다. verify-hosting-headers가
`--release-root .release/promoted-release`를 받아 후보 dist를 본다.
계약의 13-03 규칙(drill만 --release-root 필수)을 production_gate의 모든
게이트 명령으로 넓혔다. 플래그 없이 돌리면 local dist를 본다.
(3) promotion과 production_gate 사이에 `deployment` job(kind deployment)을
선언한다. 기본은 빈 슬롯이다: deploy 단계 하나가 deployed=false를 job
output으로 낸다. production_gate는 RELEASE_DEPLOYED로 받고, 비어 있으면
FE-GATE-019가 호스트를 probe하지 않고 UNVERIFIED(exit 3)로 끝난다.
프로젝트는 gates.json의 deployment job을 채운다. 계약이 허용하는 것:
checkout·setup-node·frozen-install·download·extract와 마지막 deploy 하나
(`script`는 package 스크립트, 존재·스크립트 그래프 검사를 gate 명령과
같이 받는다). env는 immutable_build의 CANDIDATE_ARCHIVE_SHA256과
vars.*·secrets.*만. 게이트를 소유하지 않아 채워도 계약 기준선이 안
바뀐다.
- ci-contract 보고서 jobCount 9→10, 계약 기준선 commandReferences
103→102(update-ci-contract-baseline, owner frontend-platform).
- verify-hosting-headers가 live가 아닌 모드에서 baseUrl을 null로 적는다.
스키마가 live에만 baseUrl을 허용해서, 비어 있는 슬롯과 기존 invalid-live
(예: http:// URL)는 산출물 쓰기에서 ZodError로 죽었다. 이제 기록을 남기고
각각 UNVERIFIED·FAIL로 끝난다.
버린 대안
- (b) (1)(2)만: 거짓 PASS는 사라지지만 배포 자리가 없어 운영 단계가 항상
FAIL이 된다.
- (d) production_gate를 별도 workflow로 분리: Gitea에서 run 사이 artifact
전달이 검증되지 않았다.
- 슬롯이 비었는지를 HOSTING_BASE_URL 유무로 판단: 변수만 있고 배포가 없으면
이전 release를 probe해 FAIL이 된다. 슬롯이 직접 보고하게 했다.
위험·한계
- Gitea runner가 꺼져 있어 workflow를 실제로 돌리지 않았다. job outputs와
`$GITHUB_OUTPUT`는 immutable_build가 이미 쓰는 방식과 같다.
- 실제 HTTPS 호스트에 이전 release를 띄워 probe하지 않았다. 불일치 판정은
fetcher를 주입한 단위 테스트로만 확인했다.
- 채운 슬롯의 secrets는 그 job의 모든 단계(checkout, download action 포함)
env에 보인다. 프로젝트가 고르는 값이다.
- FE-GATE-019를 수동으로 돌리는 운영자(provider 없는 최소 구성)는 후보
archive를 .release/promoted-release에 풀어야 한다. drill과 같은 전제다.
검증
- RED: node scripts/run-vitest.ts run tests/unit/hosting-probe.test.ts
7 failed / 19 passed(후보 인자 없음, verify가 dist ENOENT로 산출물 없음).
tests/unit/ci-workflow-generation.test.ts 8 failed / 415 passed
("expected [ 'build', 'verify:hosting-headers' ] to deeply equal ...",
"expected -1 to be 6", deployment job 없음)
- GREEN: hosting-probe 26 passed, ci-workflow-generation 423 passed
(스냅샷 1개 갱신)
- check:ci 하위 명령 직접 실행: generate-artifact-schemas --check PASS,
check-ci-contract.ts PASS, generate-ci-workflow --check PASS
- 슬롯을 채운 실험(체크아웃→다운로드→extract→deploy:release, vars·secrets
env, package 스크립트 추가) 뒤 같은 세 명령 PASS. package 스크립트를 빼면
"CI gate contract missing package scripts: deploy:release"로 실패. 실험
뒤 원복
- 관련 테스트 16파일 596 passed(ci-workflow-generation, hosting-probe,
service-worker-build-output, deployment-admission, ungated-*,
supply-chain, removal-fixture, task3-selective-integration,
documentation-readiness, tests/release, tests/platform/release)
- tsc(node, test, app) 0, eslint 바뀐 파일 0,
verify-documentation-readiness PASS_SCOPED
- 미실행: tests/system/ci-runner(pnpm 실행), check:architecture(pnpm)
Refs: docs/reviews/2026-11-01-maturity-review/13-build-release-supply-chain.md 13-01
255 lines
8.0 KiB
TypeScript
255 lines
8.0 KiB
TypeScript
import type { InstalledServiceWorkerSelection } from "../../src/contracts/service-worker.ts";
|
|
|
|
const LOOPBACK_IPV4 = /^127(?:\.\d{1,3}){3}$/;
|
|
|
|
export type HostingMode = "live" | "invalid-live" | "fixture";
|
|
export type HostingVerdict = "PASS" | "FAIL" | "UNVERIFIED";
|
|
|
|
/**
|
|
* 13-05 (D-14). The fixture compares the declared headers with a copy of
|
|
* themselves, so it can only find a contradiction, never prove hosting. Only a
|
|
* live probe of the deployed release can PASS.
|
|
*/
|
|
export function hostingVerdict(mode: HostingMode, passed: boolean): HostingVerdict {
|
|
if (!passed) return "FAIL";
|
|
return mode === "live" ? "PASS" : "UNVERIFIED";
|
|
}
|
|
|
|
/**
|
|
* 13-05. The live probe requests the entry script the served index.html names,
|
|
* so it checks the release that is deployed rather than the first asset of a
|
|
* local build, which the deployed release may not contain.
|
|
*/
|
|
export function servedEntryScript(indexHtml: string): string | null {
|
|
for (const tag of indexHtml.match(/<script\b[^>]*>/gu) ?? []) {
|
|
if (!/\btype=["']module["']/u.test(tag)) continue;
|
|
const source = /\bsrc=["']([^"']+\.js)["']/u.exec(tag)?.[1];
|
|
if (source) return source;
|
|
}
|
|
return null;
|
|
}
|
|
export type ProbeResult = Readonly<{
|
|
surface: string;
|
|
header: string;
|
|
expected: unknown;
|
|
observed: unknown;
|
|
reason?: string;
|
|
passed: boolean;
|
|
}>;
|
|
export type ResponseHeaders = Record<string, Record<string, string>>;
|
|
export type HostingFetcher = (url: URL) => Promise<Response>;
|
|
export type ReleaseIdentity = Readonly<{ buildId: string; releaseId: string }>;
|
|
|
|
/** `buildId` and `releaseId` of a release-manifest.json text, or null. */
|
|
export function releaseIdentity(manifest: string | null): ReleaseIdentity | null {
|
|
try {
|
|
const { buildId, releaseId } = JSON.parse(manifest ?? "") as Record<string, unknown>;
|
|
return typeof buildId === "string" && typeof releaseId === "string"
|
|
? { buildId, releaseId }
|
|
: null;
|
|
} catch {
|
|
return null;
|
|
}
|
|
}
|
|
|
|
/**
|
|
* 13-05 (D-14). Runs after the promoted release is deployed. Every surface must
|
|
* answer 200 without leaving the probed origin, and the hashed asset it
|
|
* requests is the entry script the served index.html names.
|
|
*
|
|
* 1101/13-04. `appRoute` is a path the build has no file for. The router uses
|
|
* browser history, so a reload or a shared link of any route reaches the host
|
|
* as such a path, and the host must answer it with the same index.html (SPA
|
|
* fallback). A 404 or any other page there fails, although `/` still works.
|
|
*
|
|
* 1101/13-01. The served release manifest must name the candidate's build and
|
|
* release. Correct headers on an earlier release are not evidence for this one.
|
|
*/
|
|
export async function probeLiveRelease(
|
|
base: URL,
|
|
paths: Readonly<Record<string, string>>,
|
|
candidate: ReleaseIdentity,
|
|
fetcher: HostingFetcher = (url) => fetch(url, { redirect: "follow" }),
|
|
): Promise<{ responses: ResponseHeaders; results: ProbeResult[] }> {
|
|
const responses: ResponseHeaders = {};
|
|
const results: ProbeResult[] = [];
|
|
const probe = async (surface: string, pathname: string): Promise<string | null> => {
|
|
try {
|
|
const response = await fetcher(new URL(pathname, base));
|
|
const finalOrigin = new URL(response.url).origin;
|
|
results.push(
|
|
{
|
|
surface,
|
|
header: "http-status",
|
|
expected: 200,
|
|
observed: response.status,
|
|
passed: response.status === 200,
|
|
},
|
|
{
|
|
surface,
|
|
header: "final-origin",
|
|
expected: base.origin,
|
|
observed: finalOrigin,
|
|
passed: finalOrigin === base.origin,
|
|
},
|
|
);
|
|
responses[surface] = Object.fromEntries(
|
|
[...response.headers.entries()].map(([name, value]) => [name.toLowerCase(), value]),
|
|
);
|
|
return await response.text();
|
|
} catch (error: unknown) {
|
|
results.push({
|
|
surface,
|
|
header: "transport",
|
|
expected: "reachable",
|
|
observed: error instanceof Error ? error.name : "UnknownError",
|
|
passed: false,
|
|
});
|
|
return null;
|
|
}
|
|
};
|
|
|
|
const bodies: Record<string, string | null> = {};
|
|
for (const [surface, pathname] of Object.entries(paths)) {
|
|
bodies[surface] = await probe(surface, pathname);
|
|
}
|
|
const entryScript = servedEntryScript(bodies["index"] ?? "");
|
|
if (entryScript) {
|
|
await probe("hashedAsset", entryScript);
|
|
} else {
|
|
results.push({
|
|
surface: "hashedAsset",
|
|
header: "entry-script",
|
|
expected: "a module script named by the served index.html",
|
|
observed: null,
|
|
passed: false,
|
|
});
|
|
}
|
|
const served = releaseIdentity(bodies["releaseManifest"] ?? null);
|
|
for (const [field, header] of [["buildId", "build-id"], ["releaseId", "release-id"]] as const) {
|
|
results.push({
|
|
surface: "releaseManifest",
|
|
header,
|
|
expected: candidate[field],
|
|
observed: served?.[field] ?? null,
|
|
passed: served?.[field] === candidate[field],
|
|
});
|
|
}
|
|
if ("appRoute" in paths) {
|
|
const observed = servedEntryScript(bodies["appRoute"] ?? "");
|
|
results.push({
|
|
surface: "appRoute",
|
|
header: "entry-script",
|
|
expected: entryScript,
|
|
observed,
|
|
passed: entryScript !== null && observed === entryScript,
|
|
});
|
|
}
|
|
return { responses, results };
|
|
}
|
|
|
|
/** A build ships a worker script for these selections (06-03: REMOVE_REGISTRATION ships the self-unregistering one). */
|
|
export function shipsServiceWorker(selection: InstalledServiceWorkerSelection | null): boolean {
|
|
return selection?.mode === "ACTIVE" || selection?.mode === "REMOVE_REGISTRATION";
|
|
}
|
|
|
|
const PUBLIC_SERVICE_WORKER = /(?:^|\/)(?:service-worker|sw)(?:[.-][^/]*)?\.js$/i;
|
|
|
|
/**
|
|
* A built `dist` may ship a worker script only when the static selection is
|
|
* `ACTIVE` or `REMOVE_REGISTRATION` (the self-unregistering worker, 06-03), and
|
|
* then only the selected script at the app root.
|
|
*/
|
|
export function checkPublicServiceWorkers(
|
|
distFiles: readonly string[],
|
|
selection: InstalledServiceWorkerSelection | null,
|
|
) {
|
|
const found = distFiles.filter((file) => PUBLIC_SERVICE_WORKER.test(file));
|
|
const allowed: string[] =
|
|
selection && shipsServiceWorker(selection) ? [selection.scriptPath] : [];
|
|
const passed =
|
|
found.length === allowed.length &&
|
|
found.every((file) => allowed.includes(file));
|
|
return {
|
|
surface: "serviceWorker",
|
|
header: "enabled",
|
|
expected: allowed.length > 0,
|
|
observed: found.length > 0,
|
|
passed,
|
|
...(passed ? {} : { reason: `dist worker scripts: ${found.join(", ") || "none"}` }),
|
|
};
|
|
}
|
|
|
|
/**
|
|
* A release gate must not promote a local preview server as live hosting
|
|
* evidence.
|
|
*
|
|
*/
|
|
export function classifyLiveHostingBaseUrl(value: string):
|
|
| {
|
|
passed: true;
|
|
reason: null;
|
|
url: URL;
|
|
observedOrigin: string;
|
|
}
|
|
| {
|
|
passed: false;
|
|
reason: string;
|
|
url: URL | null;
|
|
observedOrigin: string | null;
|
|
} {
|
|
let url: URL;
|
|
try {
|
|
url = new URL(value);
|
|
} catch {
|
|
return {
|
|
passed: false,
|
|
reason: "HOSTING_BASE_URL must be an absolute URL",
|
|
url: null,
|
|
observedOrigin: null,
|
|
};
|
|
}
|
|
|
|
const observedOrigin = url.origin;
|
|
const hostname = url.hostname.toLowerCase().replace(/^\[|\]$/g, "");
|
|
if (url.protocol !== "https:") {
|
|
return {
|
|
passed: false,
|
|
reason: "live hosting evidence requires HTTPS",
|
|
url,
|
|
observedOrigin,
|
|
};
|
|
}
|
|
if (url.username || url.password) {
|
|
return {
|
|
passed: false,
|
|
reason: "HOSTING_BASE_URL must not contain credentials",
|
|
url,
|
|
observedOrigin,
|
|
};
|
|
}
|
|
if (
|
|
hostname === "localhost" ||
|
|
hostname.endsWith(".localhost") ||
|
|
hostname === "::1" ||
|
|
hostname === "0.0.0.0" ||
|
|
LOOPBACK_IPV4.test(hostname)
|
|
) {
|
|
return {
|
|
passed: false,
|
|
reason: "local or loopback hosts are not live deployment evidence",
|
|
url,
|
|
observedOrigin,
|
|
};
|
|
}
|
|
if (url.pathname !== "/" || url.search || url.hash) {
|
|
return {
|
|
passed: false,
|
|
reason: "HOSTING_BASE_URL must be the canonical root URL",
|
|
url,
|
|
observedOrigin,
|
|
};
|
|
}
|
|
return { passed: true, reason: null, url, observedOrigin };
|
|
}
|