Files
clean-architecture-frontend…/tests/unit/hosting-probe.test.ts
T
DongHyeonka de379ea78d ci(release): FE-GATE-019가 승격 후보를 배포된 release와 대조한다 (1101/13-01)
문제
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
2026-11-03 00:56:00 +09:00

273 lines
11 KiB
TypeScript

import { spawnSync } from "node:child_process";
import { copyFile, mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
import { tmpdir } from "node:os";
import path from "node:path";
import { describe, expect, it } from "vitest";
import {
checkPublicServiceWorkers,
classifyLiveHostingBaseUrl,
hostingVerdict,
probeLiveRelease,
servedEntryScript,
} from "../../scripts/lib/hosting-probe.ts";
import { SERVICE_WORKER_SCRIPT_PATH } from "../../src/contracts/service-worker.ts";
describe("public service worker in dist", () => {
const app = ["index.html", "config.json", "assets/index-abc.js"];
const active = {
mode: "ACTIVE",
scriptPath: "service-worker.js",
handlers: ["PWA_STATIC_ASSETS"],
} as const;
const removal = { mode: "REMOVE_REGISTRATION", scriptPath: "service-worker.js" } as const;
const purge = { mode: "PURGE_OWNED_RESOURCES", scriptPath: "service-worker.js" } as const;
it("accepts the selected worker when the selection is ACTIVE", () => {
expect(
checkPublicServiceWorkers([...app, "service-worker.js"], active),
).toMatchObject({ expected: true, observed: true, passed: true });
});
// 06-03 (D-5). REMOVE_REGISTRATION ships the self-unregistering worker.
it("accepts the selected worker when the selection is REMOVE_REGISTRATION", () => {
expect(
checkPublicServiceWorkers([...app, "service-worker.js"], removal),
).toMatchObject({ expected: true, observed: true, passed: true });
});
it("accepts a worker-free dist when no worker is selected", () => {
expect(checkPublicServiceWorkers(app, null)).toMatchObject({
expected: false,
passed: true,
});
});
it.each([
["no selection", [...app, "service-worker.js"], null],
["a PURGE_OWNED_RESOURCES selection", [...app, "service-worker.js"], purge],
["REMOVE_REGISTRATION without the worker", app, removal],
["ACTIVE without the worker", app, active],
["ACTIVE with an extra worker", [...app, "service-worker.js", "assets/sw.js"], active],
["ACTIVE with the worker off the root", [...app, "assets/service-worker.js"], active],
] as const)("rejects %s", (_, files, selection) => {
expect(checkPublicServiceWorkers(files, selection)).toMatchObject({
passed: false,
reason: expect.stringContaining("dist worker scripts"),
});
});
});
describe("live hosting evidence target", () => {
it("accepts a canonical production HTTPS root", () => {
expect(
classifyLiveHostingBaseUrl("https://frontend.example.test/"),
).toMatchObject({
passed: true,
observedOrigin: "https://frontend.example.test",
});
});
it.each([
["http://frontend.example.test/", "requires HTTPS"],
["https://localhost:4173/", "not live deployment evidence"],
["https://127.0.0.1/", "not live deployment evidence"],
["https://frontend.example.test/app/", "canonical root URL"],
["https://user:secret@frontend.example.test/", "must not contain credentials"],
])("rejects %s", (url, reason) => {
expect(classifyLiveHostingBaseUrl(url)).toMatchObject({
passed: false,
reason: expect.stringContaining(reason),
});
});
});
// 13-05 (D-14). The declared-header fixture proves nothing about hosting, so it
// is UNVERIFIED, and a live probe checks the release actually served.
describe("hosting header verdict", () => {
it("passes only a live probe of the deployed release", () => {
expect(hostingVerdict("live", true)).toBe("PASS");
expect(hostingVerdict("fixture", true)).toBe("UNVERIFIED");
expect(hostingVerdict("fixture", false)).toBe("FAIL");
expect(hostingVerdict("invalid-live", false)).toBe("FAIL");
expect(hostingVerdict("live", false)).toBe("FAIL");
});
it("probes the entry script named by the served index.html", () => {
expect(
servedEntryScript(
'<head><link rel="modulepreload" href="/assets/a-1.js"><script type="module" crossorigin src="/app/assets/index-Dpjd89Th.js"></script></head>',
),
).toBe("/app/assets/index-Dpjd89Th.js");
expect(servedEntryScript("<html><body>maintenance</body></html>")).toBeNull();
});
});
// 1101/13-04. The router uses browser history, so a reload or a shared link of
// any route reaches the host as a path the build has no file for. The host has
// to answer it with the release's index.html; without that fallback `/` still
// opens and only deep links are 404, which no other check sees.
describe("SPA fallback and worker script surfaces (1101/13-04)", () => {
type Surface = Partial<{
path: string;
cacheControl: string;
contentTypes: string[];
securityHeaders: boolean;
requiredWhen: string;
}>;
const surfaces = async () =>
(JSON.parse(await readFile("config/hosting/cache-policy.json", "utf8")) as {
surfaces: Record<string, Surface | undefined>;
}).surfaces;
it("declares an app route the build has no file for, served like index.html", async () => {
const { appRoute, index } = await surfaces();
expect(appRoute).toMatchObject({
cacheControl: index?.cacheControl,
contentTypes: index?.contentTypes,
securityHeaders: true,
});
expect(appRoute?.path).toMatch(/^\/[^.]+$/u);
const { responses } = JSON.parse(
await readFile("config/hosting/response-headers.fixture.json", "utf8"),
) as { responses: Record<string, unknown> };
expect(responses["appRoute"]).toEqual(responses["index"]);
});
it("declares the worker script, served no-cache, only for a build that ships it", async () => {
expect((await surfaces())["serviceWorker"]).toMatchObject({
path: `/${SERVICE_WORKER_SCRIPT_PATH}`,
cacheControl: "no-cache",
requiredWhen: "service-worker-shipped",
});
});
const INDEX = '<script type="module" src="/assets/index-A1.js"></script>';
const PATHS = {
index: "/",
runtimeConfig: "/config.json",
releaseManifest: "/release-manifest.json",
appRoute: "/__probe/deep-link",
};
const CANDIDATE = { buildId: "gitea-42-1", releaseId: "refs/tags/v1.2.0-42-1" };
const RELEASE: Record<string, [number, string]> = {
"/": [200, INDEX],
"/config.json": [200, "{}"],
"/release-manifest.json": [200, JSON.stringify({ schemaVersion: 2, ...CANDIDATE })],
"/assets/index-A1.js": [200, ""],
};
const host = (routes: Record<string, [number, string]>) => async (url: URL) => {
const [status, body] = routes[url.pathname] ?? [404, "Not Found"];
const response = new Response(body, { status, headers: { "cache-control": "no-cache" } });
Object.defineProperty(response, "url", { value: url.href });
return response;
};
const base = new URL("https://frontend.example.test/");
const failed = async (routes: Record<string, [number, string]>) =>
(await probeLiveRelease(base, PATHS, CANDIDATE, host(routes))).results
.filter((result) => !result.passed)
.map((result) => `${result.surface} ${result.header}`);
it("passes a host that answers every route with the release's index.html", async () => {
expect(await failed({ ...RELEASE, "/__probe/deep-link": [200, INDEX] })).toEqual([]);
});
it("fails a host without the fallback", async () => {
expect(await failed(RELEASE)).toEqual(["appRoute http-status", "appRoute entry-script"]);
});
it("fails a fallback that answers 200 with a page that is not the release's index.html", async () => {
expect(
await failed({ ...RELEASE, "/__probe/deep-link": [200, "<h1>Not found</h1>"] }),
).toEqual(["appRoute entry-script"]);
});
// 1101/13-01. Headers alone pass for whatever release the host serves,
// usually the previous one when nothing deployed this candidate.
it("fails a host that still serves an earlier release", async () => {
const earlier = JSON.stringify({ schemaVersion: 2, buildId: "gitea-41-1", releaseId: "refs/tags/v1.1.0-41-1" });
expect(
await failed({
...RELEASE,
"/__probe/deep-link": [200, INDEX],
"/release-manifest.json": [200, earlier],
}),
).toEqual(["releaseManifest build-id", "releaseManifest release-id"]);
});
it("fails when the served release manifest is unreadable", async () => {
expect(
await failed({
...RELEASE,
"/__probe/deep-link": [200, INDEX],
"/release-manifest.json": [200, "<html>maintenance</html>"],
}),
).toEqual(["releaseManifest build-id", "releaseManifest release-id"]);
});
});
// 1101/13-01. FE-GATE-019 checks the promoted candidate it downloaded, not a
// local rebuild, and an empty deployment slot proves nothing about the host.
describe("verify-hosting-headers on a promoted release root (1101/13-01)", () => {
async function verify(
distFiles: Readonly<Record<string, string>>,
env: Readonly<Record<string, string>> = {},
) {
const root = await mkdtemp(path.join(tmpdir(), "hosting-release-root-"));
try {
await mkdir(path.join(root, "config/hosting"), { recursive: true });
for (const file of ["cache-policy.json", "security-headers.json", "response-headers.fixture.json"]) {
await copyFile(`config/hosting/${file}`, path.join(root, "config/hosting", file));
}
for (const [file, content] of Object.entries(distFiles)) {
await mkdir(path.dirname(path.join(root, "candidate/dist", file)), { recursive: true });
await writeFile(path.join(root, "candidate/dist", file), content);
}
const environment: NodeJS.ProcessEnv = { ...process.env, ...env };
if (!("HOSTING_BASE_URL" in env)) delete environment["HOSTING_BASE_URL"];
if (!("RELEASE_DEPLOYED" in env)) delete environment["RELEASE_DEPLOYED"];
const result = spawnSync(
process.execPath,
[path.resolve("scripts/verify-hosting-headers.ts"), "--", "--release-root", "candidate"],
{ cwd: root, encoding: "utf8", env: environment },
);
const record = JSON.parse(
await readFile(path.join(root, "artifacts/release/hosting-headers.json"), "utf8"),
) as { mode: string; results: { surface: string; header: string; passed: boolean }[] };
return {
status: result.status,
stderr: result.stderr,
mode: record.mode,
failed: record.results
.filter((entry) => !entry.passed)
.map((entry) => `${entry.surface} ${entry.header}`),
};
} finally {
await rm(root, { recursive: true, force: true });
}
}
const DIST = {
"index.html": '<script type="module" src="/assets/index-A1.js"></script>',
"release-manifest.json": JSON.stringify({ buildId: "gitea-42-1", releaseId: "r-42" }),
"assets/index-A1.js": "",
};
it("checks the dist inside --release-root, with no local build present", async () => {
const result = await verify({ ...DIST, "assets/index-A1.js.map": "{}" });
expect(result.failed, result.stderr).toEqual(["sourceMap public"]);
expect(result.status).toBe(1);
});
it("ends UNVERIFIED without probing the host when the deployment slot is empty", async () => {
const result = await verify(DIST, {
HOSTING_BASE_URL: "https://frontend.example.test/",
RELEASE_DEPLOYED: "false",
});
expect(result.failed, result.stderr).toEqual([]);
expect(result.mode).toBe("fixture");
expect(result.status).toBe(3);
expect(result.stderr).toContain("deployment slot");
});
});