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( '', ), ).toBe("/app/assets/index-Dpjd89Th.js"); expect(servedEntryScript("maintenance")).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; }).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 }; 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 = ''; 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 = { "/": [200, INDEX], "/config.json": [200, CONFIG], "/release-manifest.json": [200, JSON.stringify({ schemaVersion: 2, ...IDENTITY })], "/assets/index-A1.js": [200, ""], }; const host = (routes: Record) => 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, alpn: string | null = "h2") => probeLiveRelease(base, PATHS, CANDIDATE, { fetcher: host(routes), negotiateAlpn: async () => alpn, alpnProtocols: ["h2"], }); const failed = async (routes: Record, 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, "

Not found

"] }), ).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. 1105/14-01: the feature ID is the // test-only one (tests/helpers/fixture-feature.tsx). It named the example // screens' feature, so a copy that deleted them as the CHANGELOG says kept // this file as residue and failed that feature's removal drill. 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: { "fixture-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, ""] }), ).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 = ''; 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 = { ...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, "maintenance"], }), ).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>, 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 = ''; 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 = { "/": [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 }), ); }); // 1106/06-01. Browsers fetch the worker script with redirect mode "error", // so a same-origin redirect breaks registration, every update check and the // REMOVE_REGISTRATION kill switch, while the followed answer is a 200 with // the right headers. A page may still follow such a redirect. it("fails a worker script the host answers only after a same-origin redirect", async () => { const served: Record = { "/": [INDEX, "text/html"], "/release-manifest.json": [JSON.stringify(IDENTITY), "application/json"], "/service-worker.js": ["", "text/javascript"], "/assets/index-A1.js": ["", "text/javascript"], "/assets/index-C3.css": ["", "text/css"], }; // Each path in `redirected` is answered after a redirect to `/v2/...` on the same origin. const failing = async (redirected: readonly string[]) => { const { results } = await probeLiveHosting( base, { ...PATHS, serviceWorker: "/service-worker.js" }, 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] } : {}, }); const moved = redirected.includes(url.pathname); Object.defineProperty(response, "url", { value: moved ? new URL(`/v2${url.pathname}`, url).href : url.href, }); Object.defineProperty(response, "redirected", { value: moved }); return response; }, }, ); return results.filter((result) => !result.passed); }; expect(await failing([])).toEqual([]); expect(await failing(["/", "/service-worker.js"])).toEqual([ expect.objectContaining({ surface: "serviceWorker", header: "redirect", observed: true, reason: expect.stringContaining("redirect"), }), ]); }); }); // 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>, env: Readonly> = {}, editFixture?: (responses: Record>) => 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>; }; 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": '', "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; }; 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); }); });