Files
clean-architecture-frontend…/tests/unit/hosting-probe.test.ts
T
DongHyeonka 4d6f254438 fix(hosting): 자산 MIME probe가 redirect를 거절하고 live 분기를 테스트한다
문제: 확장자별 MIME probe(1103/06-03)는 install 조건 일부만 옮겼다.
1. install fetch는 `redirect: "error"`라 redirect가 하나라도 있으면
   실패한다. probe는 `redirect: "follow"`로 받고 최종 status와 MIME만
   본다. 같은 origin 안 redirect 뒤 200을 주는 호스트가 PASS다(리뷰
   06-R1). FE-GATE-019가 PASS인데 워커 install은 매번 실패한다.
2. 워커 없는 빌드에서도 돈다. 주석과 문서는 이유를 워커로만 적는다.
3. live 분기의 호출 줄(`verify-hosting-headers.ts`)을 지키는 테스트가
   없다. live 모드는 루프백·http를 거절해 저장소 테스트가 들어갈 수
   없다. 호출을 지우는 변이가 44건 통과로 살아남았다(06-R2).

고른 방법:
1. 자산 probe 기본 fetcher를 `redirect: "manual"`로 바꾸고,
   `response.redirected`이거나 `opaqueredirect`이면 관측 "redirected",
   이유 "install fetch가 redirect를 거절"로 FAIL이다. 3xx는 지금처럼
   `HTTP 3xx`로 FAIL이다. fetcher가 redirect를 따라가도 `redirected`로
   잡으므로 fetcher 방식과 무관하다.
2. 동작은 그대로 두고 의도를 주석과 운영 문서에 적었다. 워커가 없어도
   `nosniff` 아래 script·style은 MIME이 틀리면 페이지가 깨지고, 나중에
   워커를 켜는 릴리스가 호스팅을 다시 확인하지 않아도 된다. 글꼴·이미지는
   페이지에 피해가 없는데 FAIL한다는 것도 적었다. 워커 없는 빌드에서
   script·style만 보도록 좁히는 것은 검사를 약하게 하는 정책 결정이라
   하지 않았다(결정 대기, 템플릿 소유자).
3. live 분기 전체를 `probeLiveHosting`(release surface +
   자산 MIME)으로 빼고 스크립트는 그것만 부른다. 테스트가 fetcher
   대역으로 이 함수를 돌려 CSS `text/plain`이 FAIL인지 본다. 자산 probe
   호출을 빼면 이 테스트가 실패한다. 스크립트에서 `probeLiveHosting`
   호출을 빼면 live 결과가 비어 cache-control 행이 모두 FAIL이라 스스로
   드러난다.
버린 대안: 문서에 한계만 적기(리뷰 (b)). 1·3이 그대로다.

위험·한계: 정규 경로 규칙으로 자산을 redirect하는 호스트는 이제
FE-GATE-019에서 FAIL이다. 워커가 없는 제품도 마찬가지다(2의 판단).
실제 호스트로 live 모드를 돌리지는 않았다.

검증: desktop batch에서 확인.
- node scripts/run-vitest.ts run tests/unit/hosting-probe.test.ts
- RED: "fails an asset the host answers only after a redirect"(옛 probe는
  redirect 뒤 200을 PASS), "checks every built asset type besides the
  release surfaces"(옛 코드에 `probeLiveHosting`이 없음)가 실패한다.
- 변이(06-R2 대응): `probeLiveHosting`에서 `probeAssetContentTypes` 결과를
  빼면 "checks every built asset type ..."가 실패해야 한다.

Refs: 1105/06-02
2026-11-05 22:11:49 +09:00

543 lines
22 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 {
acceptedAssetContentTypes,
checkPublicServiceWorkers,
classifyLiveHostingBaseUrl,
hostingVerdict,
probeAssetContentTypes,
probeLiveHosting,
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 IDENTITY = { buildId: "gitea-42-1", releaseId: "refs/tags/v1.2.0-42-1" };
const CONFIG = JSON.stringify({
APP_ENV: "production",
AUTH_MODE: "external",
API_BASE_URL: "https://api.frontend.example.test/",
BUILD_ID: IDENTITY.buildId,
RELEASE_ID: IDENTITY.releaseId,
CAPABILITY_OVERRIDES: {},
FEATURE_OVERRIDES: {},
});
const CANDIDATE = { ...IDENTITY, runtimeConfig: CONFIG, indexHtml: INDEX };
const RELEASE: Record<string, [number, string]> = {
"/": [200, INDEX],
"/config.json": [200, CONFIG],
"/release-manifest.json": [200, JSON.stringify({ schemaVersion: 2, ...IDENTITY })],
"/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 probe = (routes: Record<string, [number, string]>, alpn: string | null = "h2") =>
probeLiveRelease(base, PATHS, CANDIDATE, {
fetcher: host(routes),
negotiateAlpn: async () => alpn,
alpnProtocols: ["h2"],
});
const failed = async (routes: Record<string, [number, string]>, alpn?: string | null) =>
(await probe(routes, alpn)).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"]);
});
// 1103/13-01. The manifest names come from the CI run, so a release rebuilt
// in the same run with the local profile (APP_ENV=local, AUTH_MODE=demo, a
// loopback API) passed. The candidate's config.json is the one release
// admission (FE-GATE-027) admitted, so the served one must equal it.
it("fails a host whose config.json is not the candidate's", async () => {
const local = JSON.stringify({
...JSON.parse(CONFIG),
APP_ENV: "local",
AUTH_MODE: "demo",
API_BASE_URL: "http://localhost:8080/",
});
const { results } = await probe({
...RELEASE,
"/__probe/deep-link": [200, INDEX],
"/config.json": [200, local],
});
expect(results.filter(({ passed }) => !passed)).toEqual([
expect.objectContaining({
surface: "runtimeConfig",
header: "build-fields",
observed: ["API_BASE_URL", "APP_ENV", "AUTH_MODE"],
}),
]);
});
// FE-RB-001 changes the two emergency switches without a rebuild; the
// probe after it must still pass.
it("passes a host whose config.json differs only in the emergency switches", async () => {
const switched = JSON.stringify({
...JSON.parse(CONFIG),
CAPABILITY_OVERRIDES: { realtime: "DISABLED" },
FEATURE_OVERRIDES: { "platform-examples-feature": false },
});
expect(
await failed({ ...RELEASE, "/__probe/deep-link": [200, INDEX], "/config.json": [200, switched] }),
).toEqual([]);
});
it("fails a host whose config.json is unreadable", async () => {
expect(
await failed({ ...RELEASE, "/__probe/deep-link": [200, INDEX], "/config.json": [200, "<html>"] }),
).toEqual(["runtimeConfig build-fields"]);
});
// 1103/13-01. A build of other sources under the same run names serves its
// own entry script; the fallback check compared the host only with itself.
it("fails a host whose index.html names another entry script than the candidate's", async () => {
const other = '<script type="module" src="/assets/index-B2.js"></script>';
expect(
await failed({
...RELEASE,
"/": [200, other],
"/__probe/deep-link": [200, other],
"/assets/index-B2.js": [200, ""],
}),
).toEqual(["index candidate-entry-script"]);
});
// 1103/13-02. The split initial chunks assume HTTP/2
// (docs/architecture/static-delivery.md); over HTTP/1.1 they queue.
it("fails a host that does not negotiate a declared protocol", async () => {
const release: Record<string, [number, string]> = { ...RELEASE, "/__probe/deep-link": [200, INDEX] };
expect(await failed(release, "http/1.1")).toEqual(["transport alpn"]);
expect(await failed(release, null)).toEqual(["transport alpn"]);
});
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"]);
});
});
// 1103/06-03. The worker's install requires each precached asset's exact
// Content-Type (CACHEABLE_ASSET_CONTENT_TYPES) and refuses the whole release on
// one mismatch. A page still uses a font served as octet-stream, so only the
// worker notices. The live probe requests one built asset per extension.
describe("hashed asset content types (1103/06-03)", () => {
const base = new URL("https://frontend.example.test/");
const DIST_FILES = [
"index.html",
"config.json",
"assets/index-A1.js",
"assets/chunk-B2.js",
"assets/index-C3.css",
"assets/inter-D4.woff2",
"assets/notes-E5.txt",
"robots.txt",
];
const host =
(types: Readonly<Record<string, string>>, requested: string[] = []) =>
async (url: URL) => {
requested.push(url.pathname);
const extension = /\.[^./]+$/u.exec(url.pathname)?.[0] ?? "";
const type = types[extension];
const response = new Response("", {
status: type ? 200 : 404,
headers: type ? { "content-type": type } : {},
});
Object.defineProperty(response, "url", { value: url.href });
return response;
};
const CORRECT = {
".js": "text/javascript; charset=utf-8",
".css": "text/css",
".woff2": "font/woff2",
};
it("requests one built asset per cacheable extension and passes correct types", async () => {
const requested: string[] = [];
const results = await probeAssetContentTypes(base, DIST_FILES, host(CORRECT, requested));
expect(requested).toEqual([
"/assets/index-C3.css",
"/assets/chunk-B2.js",
"/assets/inter-D4.woff2",
]);
expect(results.map((result) => [result.surface, result.passed])).toEqual([
["hashedAsset.css", true],
["hashedAsset.js", true],
["hashedAsset.woff2", true],
]);
});
it("fails a host that serves CSS as text/plain", async () => {
const results = await probeAssetContentTypes(
base,
DIST_FILES,
host({ ...CORRECT, ".css": "text/plain" }),
);
expect(results.filter((result) => !result.passed)).toEqual([
expect.objectContaining({
surface: "hashedAsset.css",
header: "content-type",
expected: ["text/css"],
observed: "text/plain",
}),
]);
});
it("fails a font served as octet-stream and an asset the host does not serve", async () => {
const results = await probeAssetContentTypes(
base,
DIST_FILES,
host({ ".js": "application/javascript", ".woff2": "application/octet-stream" }),
);
expect(
results.filter((result) => !result.passed).map((result) => [result.surface, result.observed]),
).toEqual([
["hashedAsset.css", "HTTP 404"],
["hashedAsset.woff2", "application/octet-stream"],
]);
});
// 1105/06-02. The worker's install fetch uses `redirect: "error"`: a host
// that redirects a hashed asset, even to the same origin, fails every
// install although the final answer is a 200 with the right type.
it("fails an asset the host answers only after a redirect", async () => {
const results = await probeAssetContentTypes(
base,
["assets/index-A1.js", "assets/index-C3.css"],
async (url) => {
const response = new Response("", {
status: url.pathname.endsWith(".js") ? 200 : 301,
headers: { "content-type": url.pathname.endsWith(".js") ? "text/javascript" : "text/html" },
});
Object.defineProperty(response, "url", { value: `${url.href}?moved=1` });
Object.defineProperty(response, "redirected", { value: url.pathname.endsWith(".js") });
return response;
},
);
expect(results.map((result) => [result.surface, result.observed, result.passed])).toEqual([
["hashedAsset.css", "HTTP 301", false],
["hashedAsset.js", "redirected", false],
]);
expect(results[1]).toMatchObject({ reason: expect.stringContaining("redirect") });
});
it("accepts for JavaScript what the hashedAsset surface declares", async () => {
const policy = JSON.parse(await readFile("config/hosting/cache-policy.json", "utf8")) as {
surfaces: { hashedAsset: { contentTypes: string[] } };
};
expect(acceptedAssetContentTypes(".js")).toEqual(policy.surfaces.hashedAsset.contentTypes);
expect(acceptedAssetContentTypes(".woff2")).toEqual(["font/woff2"]);
});
});
// 1105/06-02. Live mode of verify-hosting-headers refuses loopback and plain
// http, so no test can run the script against a host. Its whole live branch is
// probeLiveHosting; dropping the asset type probe from it fails here.
describe("live hosting probe (1105/06-02)", () => {
const base = new URL("https://frontend.example.test/");
const INDEX = '<script type="module" src="/assets/index-A1.js"></script>';
const IDENTITY = { buildId: "gitea-42-1", releaseId: "r-42" };
const PATHS = { index: "/", releaseManifest: "/release-manifest.json" };
const CANDIDATE = { ...IDENTITY, runtimeConfig: "{}", indexHtml: INDEX };
const DIST_FILES = ["index.html", "release-manifest.json", "assets/index-A1.js", "assets/index-C3.css"];
it("checks every built asset type besides the release surfaces", async () => {
const served: Record<string, readonly [string, string]> = {
"/": [INDEX, "text/html"],
"/release-manifest.json": [JSON.stringify(IDENTITY), "application/json"],
"/assets/index-A1.js": ["", "text/javascript"],
"/assets/index-C3.css": ["", "text/plain"],
};
const { results } = await probeLiveHosting(base, PATHS, CANDIDATE, DIST_FILES, {
fetcher: async (url) => {
const entry = served[url.pathname];
const response = new Response(entry?.[0] ?? "Not Found", {
status: entry ? 200 : 404,
headers: entry ? { "content-type": entry[1] } : {},
});
Object.defineProperty(response, "url", { value: url.href });
return response;
},
});
expect(
results.filter((result) => !result.passed).map((result) => `${result.surface} ${result.header}`),
).toEqual(["hashedAsset.css content-type"]);
expect(results).toContainEqual(
expect.objectContaining({ surface: "hashedAsset.js", header: "content-type", passed: true }),
);
expect(results).toContainEqual(
expect.objectContaining({ surface: "releaseManifest", header: "build-id", passed: true }),
);
});
});
// 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>> = {},
editFixture?: (responses: Record<string, Record<string, string>>) => void,
) {
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));
}
if (editFixture) {
const fixturePath = path.join(root, "config/hosting/response-headers.fixture.json");
const fixture = JSON.parse(await readFile(fixturePath, "utf8")) as {
responses: Record<string, Record<string, string>>;
};
editFixture(fixture.responses);
await writeFile(fixturePath, JSON.stringify(fixture));
}
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");
});
// 1103/13-02. The bundle budget counts gzip bytes; an uncompressed entry
// script means about three times as many bytes on the wire.
it("declares compression for hashed assets and HTTP/2 for the host", async () => {
const policy = JSON.parse(await readFile("config/hosting/cache-policy.json", "utf8")) as {
transport?: { alpnProtocols?: string[] };
surfaces: Record<string, { contentEncodings?: string[] }>;
};
expect(policy.transport?.alpnProtocols).toEqual(["h2"]);
expect(policy.surfaces["hashedAsset"]?.contentEncodings).toEqual(
expect.arrayContaining(["br", "gzip"]),
);
});
it("fails a hashed asset served without a declared content encoding", async () => {
const result = await verify(DIST, {}, (responses) => {
delete responses["hashedAsset"]?.["content-encoding"];
});
expect(result.failed, result.stderr).toEqual(["hashedAsset content-encoding"]);
expect(result.status).toBe(1);
});
});