From 2eeaf57c69ff387456a80a1101ace7944ec21e20 Mon Sep 17 00:00:00 2001 From: Vigneshraj Sekar Babu Date: Wed, 18 Nov 2026 12:18:29 -0800 Subject: [PATCH 1/3] build: replace nginx runtime with a pinned node static server Serve the static export from node:24.22.3-alpine3.24 with a dependency-free server that keeps the raw Markdown, retired route, and 404 contracts. Pin oven/bun 1.4.4 for the builder and CI. --- .dockerignore | 8 ++ .github/workflows/ci.yml | 2 +- .github/workflows/deploy.yml | 2 +- Dockerfile | 29 +++-- default.conf | 30 ----- eslint.config.mjs | 1 + helm/values/app.yaml | 8 +- scripts/validateDocs.ts | 92 --------------- server.mjs | 174 +++++++++++++++++++++++++++++ tests/scripts/validateDocs.test.ts | 138 ----------------------- tests/server.test.ts | 126 +++++++++++++++++++++ 11 files changed, 332 insertions(+), 278 deletions(-) create mode 100644 .dockerignore delete mode 100644 default.conf create mode 100644 server.mjs create mode 100644 tests/server.test.ts diff --git a/.dockerignore b/.dockerignore new file mode 100644 index 00000000..3c598a5a --- /dev/null +++ b/.dockerignore @@ -0,0 +1,8 @@ +node_modules +.next +out +.claude +.husky +.git +Dockerfile +.dockerignore diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 2695a1bd..aaa38120 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -34,6 +34,6 @@ jobs: - name: Setup Bun uses: oven-sh/setup-bun@v2 with: - bun-version: 1.2.8 + bun-version: 1.4.4 - run: bun install --frozen-lockfile - run: bun run verify diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml index 625b91d2..9212b1ff 100644 --- a/.github/workflows/deploy.yml +++ b/.github/workflows/deploy.yml @@ -31,7 +31,7 @@ jobs: - name: Setup Bun uses: oven-sh/setup-bun@v2 with: - bun-version: 1.2.8 + bun-version: 1.4.4 - name: Install dependencies run: bun install --frozen-lockfile diff --git a/Dockerfile b/Dockerfile index d39549f1..77c51d73 100644 --- a/Dockerfile +++ b/Dockerfile @@ -12,25 +12,30 @@ # See the License for the specific language governing permissions and # limitations under the License. -# Stage 1: Build the Nextra app with secrets injection -FROM oven/bun:1.2.8 AS builder +FROM oven/bun:1.4.4-alpine@sha256:4cf82f5686b196504fe119db3fcd9185b191f82ece82c40680e597228ec6070a AS builder WORKDIR /app -# Copy dependency files -COPY package*.json bun.lock* ./ -RUN bun install +COPY package.json bun.lock ./ +RUN bun install --frozen-lockfile COPY . . - RUN bun run build -FROM nginx:1.31.7-alpine -WORKDIR /usr/share/nginx/html +FROM node:24.22.3-alpine3.24@sha256:116b800c3754b440ee0aa3ed2f20f5bf3d99a554bfd9adeea09ea8017f6e85f5 -COPY --from=builder /app/out /usr/share/nginx/html +# The runtime only needs the node binary; npm and yarn ship with the base image and carry their own CVEs. +RUN apk upgrade --no-cache \ + && rm -rf /usr/local/lib/node_modules /usr/local/bin/npm /usr/local/bin/npx \ + /usr/local/bin/corepack /usr/local/bin/yarn /usr/local/bin/yarnpkg /opt/yarn-* -COPY default.conf /etc/nginx/conf.d/default.conf +WORKDIR /app +COPY --chown=node:node server.mjs ./ +COPY --from=builder --chown=node:node /app/out ./public -EXPOSE 80 +ENV NODE_ENV=production \ + PORT=8080 \ + STATIC_ROOT=/app/public +USER node +EXPOSE 8080 -CMD ["nginx", "-g", "daemon off;"] +CMD ["node", "server.mjs"] diff --git a/default.conf b/default.conf deleted file mode 100644 index 7e9ffb00..00000000 --- a/default.conf +++ /dev/null @@ -1,30 +0,0 @@ -server { - listen 80; - server_name localhost; - - root /usr/share/nginx/html; - index index.html; - location = /docs/cm { - return 404; - } - location = /docs/cm.md { - return 404; - } - location ^~ /docs/cm/ { - return 404; - } - location ~ \.md$ { - types {} - default_type "text/markdown; charset=utf-8"; - try_files $uri =404; - } - location / { - try_files $uri.html $uri $uri/ /index.html; - } - location ~* \.(?:ico|css|js|gif|jpe?g|png|woff2?|eot|ttf|otf|svg|map)$ { - expires 6M; - access_log off; - add_header Cache-Control "public"; - } - error_page 404 /404.html; -} diff --git a/eslint.config.mjs b/eslint.config.mjs index d2f3084c..00a71065 100644 --- a/eslint.config.mjs +++ b/eslint.config.mjs @@ -30,6 +30,7 @@ export default [ }, }, }, + { files: ["server.mjs"], languageOptions: { globals: globals.node } }, pluginJs.configs.recommended, ...tseslint.configs.recommended, pluginReact.configs.flat.recommended, diff --git a/helm/values/app.yaml b/helm/values/app.yaml index f1d74a56..72f4a12c 100644 --- a/helm/values/app.yaml +++ b/helm/values/app.yaml @@ -27,7 +27,7 @@ ports: protocol: TCP servicePort: 80 - containerPort: 80 + containerPort: 8080 service: enabled: true @@ -65,7 +65,7 @@ deployment: httpGet: scheme: HTTP path: / - port: 80 + port: 8080 readinessProbe: periodSeconds: 10 @@ -73,7 +73,7 @@ deployment: httpGet: scheme: HTTP path: / - port: 80 + port: 8080 livenessProbe: periodSeconds: 60 @@ -82,7 +82,7 @@ deployment: httpGet: scheme: HTTP path: / - port: 80 + port: 8080 # Slowly rollout new pods during a deployment to # prevent too many being unavailable at any given time diff --git a/scripts/validateDocs.ts b/scripts/validateDocs.ts index c8ba549e..a6993c9f 100644 --- a/scripts/validateDocs.ts +++ b/scripts/validateDocs.ts @@ -64,7 +64,6 @@ type ImageDimensions = { const SCREENSHOT_CATALOG = ".agents/skills/update-lifecycle-docs/references/screenshots.md"; -const RAW_MARKDOWN_SERVER_CONFIG = "default.conf"; const RASTER_EXTENSIONS = new Set([".gif", ".jpeg", ".jpg", ".png", ".webp"]); const NON_SCREENSHOT_RASTERS = new Set(["/logo.png"]); const SCREENSHOT_STATUSES = new Set(["keep", "remove", "replace"]); @@ -267,96 +266,6 @@ function context(rootDir: string): ValidationContext { }; } -export async function validateRawMarkdownDelivery({ - rootDir = process.cwd(), -}: ValidationOptions = {}): Promise { - const resolvedRoot = path.resolve(rootDir); - const configPath = path.join(resolvedRoot, RAW_MARKDOWN_SERVER_CONFIG); - let source: string; - try { - source = await fs.promises.readFile(configPath, "utf8"); - } catch (error) { - return [ - { - file: RAW_MARKDOWN_SERVER_CONFIG, - message: `raw Markdown server configuration is unavailable: ${ - error instanceof Error ? error.message.split("\n")[0] : String(error) - }`, - }, - ]; - } - - const location = source.match( - /location\s+~\s+\\\.md\$\s*\{([\s\S]*?)^\s*\}/m, - )?.[1]; - if (!location) { - return [ - { - file: RAW_MARKDOWN_SERVER_CONFIG, - message: "raw Markdown requires a dedicated .md location", - }, - ]; - } - - const issues: ValidationIssue[] = []; - if (!/\btypes\s*\{\s*\}/.test(location)) { - issues.push({ - file: RAW_MARKDOWN_SERVER_CONFIG, - message: - "raw Markdown must clear inherited MIME mappings before setting its UTF-8 media type", - }); - } - if ( - !/\bdefault_type\s+["']text\/markdown;\s*charset=utf-8["']\s*;/i.test( - location, - ) - ) { - issues.push({ - file: RAW_MARKDOWN_SERVER_CONFIG, - message: - 'raw Markdown must use Content-Type "text/markdown; charset=utf-8"', - }); - } - if (!/\btry_files\s+\$uri\s+=404\s*;/.test(location)) { - issues.push({ - file: RAW_MARKDOWN_SERVER_CONFIG, - message: - "raw Markdown must return 404 for a missing file instead of the HTML fallback", - }); - } - const retiredRouteLocations = [ - /location\s*=\s*\/docs\/cm\s*\{\s*return\s+404\s*;\s*\}/, - /location\s*=\s*\/docs\/cm\.md\s*\{\s*return\s+404\s*;\s*\}/, - /location\s+\^~\s+\/docs\/cm\/\s*\{\s*return\s+404\s*;\s*\}/, - ]; - if (retiredRouteLocations.some((pattern) => !pattern.test(source))) { - issues.push({ - file: RAW_MARKDOWN_SERVER_CONFIG, - message: "retired /docs/cm routes must return 404", - }); - } - if (!/\berror_page\s+404\s+\/404\.html\s*;/.test(source)) { - issues.push({ - file: RAW_MARKDOWN_SERVER_CONFIG, - message: "404 responses must use the exported 404 page", - }); - } - const htmlLocation = source.match(/location\s+\/\s*\{([\s\S]*?)^\s*\}/m)?.[1]; - if ( - !htmlLocation || - !/\btry_files\s+\$uri\.html\s+\$uri(?:\s+\$uri\/)?\s+\/index\.html\s*;/.test( - htmlLocation, - ) - ) { - issues.push({ - file: RAW_MARKDOWN_SERVER_CONFIG, - message: - "HTML routes must prefer the exported .html file before a same-name asset directory", - }); - } - return issues; -} - function routeFor(rootDir: string, file: string): string { const relative = path .relative(path.join(rootDir, "src/pages"), file) @@ -1166,7 +1075,6 @@ export async function validateDocs({ } issues.push(...(await validatePortableGuidance({ rootDir }))); - issues.push(...(await validateRawMarkdownDelivery({ rootDir }))); return issues; } diff --git a/server.mjs b/server.mjs new file mode 100644 index 00000000..a417c8ec --- /dev/null +++ b/server.mjs @@ -0,0 +1,174 @@ +/** + * Copyright 2026 GoodRx, Inc. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +import { createReadStream } from "node:fs"; +import { stat } from "node:fs/promises"; +import { createServer } from "node:http"; +import { extname, join, normalize, resolve, sep } from "node:path"; +import { pathToFileURL } from "node:url"; + +const CONTENT_TYPES = { + ".html": "text/html; charset=utf-8", + ".md": "text/markdown; charset=utf-8", + ".txt": "text/plain; charset=utf-8", + ".js": "text/javascript; charset=utf-8", + ".mjs": "text/javascript; charset=utf-8", + ".css": "text/css; charset=utf-8", + ".json": "application/json; charset=utf-8", + ".xml": "application/xml; charset=utf-8", + ".map": "application/json; charset=utf-8", + ".svg": "image/svg+xml", + ".png": "image/png", + ".jpg": "image/jpeg", + ".jpeg": "image/jpeg", + ".gif": "image/gif", + ".webp": "image/webp", + ".avif": "image/avif", + ".ico": "image/x-icon", + ".woff": "font/woff", + ".woff2": "font/woff2", + ".ttf": "font/ttf", + ".otf": "font/otf", + ".eot": "application/vnd.ms-fontobject", + ".webmanifest": "application/manifest+json", + ".pdf": "application/pdf", + ".mp4": "video/mp4", + ".webm": "video/webm", +}; + +const STATIC_ASSETS = new Set([ + ".ico", + ".css", + ".js", + ".gif", + ".jpg", + ".jpeg", + ".png", + ".woff", + ".woff2", + ".eot", + ".ttf", + ".otf", + ".svg", + ".map", +]); + +const RETIRED_ROUTE = /^\/docs\/cm(?:\.md|\/.*)?$/; + +async function findFile(candidate) { + try { + const info = await stat(candidate); + return info.isFile() ? candidate : null; + } catch { + return null; + } +} + +/** + * Maps a decoded URL path to the file to serve and its status. + * + * Raw Markdown and static assets fail closed with the exported 404 page instead of the HTML shell, so + * agents fetching `.md` never receive HTML. HTML routes prefer `.html` over a same-name asset + * directory, then fall back to `index.html` for client-side routing. + */ +export async function resolveRequest(root, urlPath) { + const notFound = { + file: await findFile(join(root, "404.html")), + status: 404, + }; + if (RETIRED_ROUTE.test(urlPath)) return notFound; + + const base = join(root, normalize(urlPath).replace(/^[/\\]+/, "")); + if (base !== root && !base.startsWith(root + sep)) return notFound; + + const ext = extname(urlPath).toLowerCase(); + if (ext === ".md" || STATIC_ASSETS.has(ext)) { + const file = await findFile(base); + return file ? { file, status: 200 } : notFound; + } + + for (const candidate of [ + `${base}.html`, + base, + join(base, "index.html"), + join(root, "index.html"), + ]) { + const file = await findFile(candidate); + if (file) return { file, status: 200 }; + } + return notFound; +} + +export function createStaticServer(rootDir) { + const root = resolve(rootDir); + return createServer(async (req, res) => { + if (req.method !== "GET" && req.method !== "HEAD") { + res.writeHead(405, { Allow: "GET, HEAD" }).end(); + return; + } + + let urlPath; + try { + urlPath = decodeURIComponent( + new URL(req.url ?? "/", "http://localhost").pathname, + ); + } catch { + res.writeHead(400).end(); + return; + } + + const { file, status } = await resolveRequest(root, urlPath); + if (!file) { + res.writeHead(status).end(); + return; + } + + const { size } = await stat(file); + const ext = extname(file).toLowerCase(); + res.writeHead(status, { + "Content-Type": CONTENT_TYPES[ext] ?? "application/octet-stream", + "Content-Length": size, + "Cache-Control": + status === 200 && STATIC_ASSETS.has(ext) + ? "public, max-age=15552000" + : "no-cache", + "X-Content-Type-Options": "nosniff", + }); + + if (req.method === "HEAD") { + res.end(); + return; + } + createReadStream(file) + .on("error", () => res.destroy()) + .pipe(res); + }); +} + +if ( + process.argv[1] && + import.meta.url === pathToFileURL(resolve(process.argv[1])).href +) { + const root = process.env.STATIC_ROOT ?? "/app/public"; + const port = Number(process.env.PORT ?? 8080); + const server = createStaticServer(root); + server.keepAliveTimeout = 65_000; + server.listen(port, () => console.log(`serving ${root} on :${port}`)); + + for (const signal of ["SIGTERM", "SIGINT"]) { + process.on(signal, () => server.close(() => process.exit(0))); + } +} diff --git a/tests/scripts/validateDocs.test.ts b/tests/scripts/validateDocs.test.ts index d395271d..2584c326 100644 --- a/tests/scripts/validateDocs.test.ts +++ b/tests/scripts/validateDocs.test.ts @@ -21,7 +21,6 @@ import path from "node:path"; import { validateDocs, validatePortableGuidance, - validateRawMarkdownDelivery, validateScreenshots, } from "../../scripts/validateDocs"; @@ -55,25 +54,6 @@ async function temporaryRoot(): Promise { }, }), ); - await write( - root, - "default.conf", - `server { - location = /docs/cm { return 404; } - location = /docs/cm.md { return 404; } - location ^~ /docs/cm/ { return 404; } - location ~ \\.md$ { - types {} - default_type "text/markdown; charset=utf-8"; - try_files $uri =404; - } - location / { - try_files $uri.html $uri $uri/ /index.html; - } - error_page 404 /404.html; -} -`, - ); return root; } @@ -349,124 +329,6 @@ process-local expect(await validateDocs({ rootDir: root })).toEqual([]); }); - - test("requires UTF-8 Markdown delivery and a fail-closed missing route", async () => { - const root = await temporaryRoot(); - await write( - root, - "default.conf", - `server { - location = /docs/cm { return 404; } - location = /docs/cm.md { return 404; } - location ^~ /docs/cm/ { return 404; } - location ~ \\.md$ { - default_type text/markdown; - try_files $uri $uri.html /index.html; - } - location / { - try_files $uri.html $uri $uri/ /index.html; - } - error_page 404 /404.html; -} -`, - ); - - expect( - (await validateRawMarkdownDelivery({ rootDir: root })).map( - (issue) => issue.message, - ), - ).toEqual([ - "raw Markdown must clear inherited MIME mappings before setting its UTF-8 media type", - 'raw Markdown must use Content-Type "text/markdown; charset=utf-8"', - "raw Markdown must return 404 for a missing file instead of the HTML fallback", - ]); - }); - - test("requires explicit 404 responses for the retired /docs/cm routes", async () => { - const root = await temporaryRoot(); - await write( - root, - "default.conf", - `server { - location ~ \\.md$ { - types {} - default_type "text/markdown; charset=utf-8"; - try_files $uri =404; - } - location / { - try_files $uri.html $uri $uri/ /index.html; - } - error_page 404 /404.html; -} -`, - ); - - expect( - (await validateRawMarkdownDelivery({ rootDir: root })).map( - (issue) => issue.message, - ), - ).toEqual(["retired /docs/cm routes must return 404"]); - }); - - test("requires the exported 404 page for missing routes", async () => { - const root = await temporaryRoot(); - await write( - root, - "default.conf", - `server { - location = /docs/cm { return 404; } - location = /docs/cm.md { return 404; } - location ^~ /docs/cm/ { return 404; } - location ~ \\.md$ { - types {} - default_type "text/markdown; charset=utf-8"; - try_files $uri =404; - } - location / { - try_files $uri.html $uri $uri/ /index.html; - } - error_page 404 /index.html; -} -`, - ); - - expect( - (await validateRawMarkdownDelivery({ rootDir: root })).map( - (issue) => issue.message, - ), - ).toEqual(["404 responses must use the exported 404 page"]); - }); - - test("prefers an exported HTML page over a same-name asset directory", async () => { - const root = await temporaryRoot(); - await write( - root, - "default.conf", - `server { - location = /docs/cm { return 404; } - location = /docs/cm.md { return 404; } - location ^~ /docs/cm/ { return 404; } - location ~ \\.md$ { - types {} - default_type "text/markdown; charset=utf-8"; - try_files $uri =404; - } - location / { - try_files $uri $uri.html /index.html; - } - error_page 404 /404.html; -} -`, - ); - - expect( - (await validateRawMarkdownDelivery({ rootDir: root })).map( - (issue) => issue.message, - ), - ).toEqual([ - "HTML routes must prefer the exported .html file before a same-name asset directory", - ]); - }); }); describe("screenshot validation", () => { diff --git a/tests/server.test.ts b/tests/server.test.ts new file mode 100644 index 00000000..0ae04bb0 --- /dev/null +++ b/tests/server.test.ts @@ -0,0 +1,126 @@ +/** + * Copyright 2026 GoodRx, Inc. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +import { afterAll, beforeAll, describe, expect, test } from "bun:test"; +import fs from "node:fs"; +import type { Server } from "node:http"; +import type { AddressInfo } from "node:net"; +import os from "node:os"; +import path from "node:path"; +import { createStaticServer } from "../server.mjs"; + +const files: Record = { + "index.html": "

shell

", + "404.html": "

not found

", + "docs/guide.html": "

guide page

", + "docs/guide/diagram.png": "png", + "docs/guide.md": "# Guide", + "docs/cm.html": "

retired

", + "docs/cm.md": "# Retired", + "docs/cm/old.html": "

retired child

", + "docs/section/index.html": "

section index

", + "_next/static/app.js": "console.log(1)", +}; + +let root: string; +let server: Server; +let baseUrl: string; + +beforeAll(async () => { + root = fs.mkdtempSync(path.join(os.tmpdir(), "lifecycle-docs-server-")); + for (const [relative, contents] of Object.entries(files)) { + fs.mkdirSync(path.dirname(path.join(root, relative)), { recursive: true }); + fs.writeFileSync(path.join(root, relative), contents); + } + server = createStaticServer(root); + await new Promise((done) => server.listen(0, "127.0.0.1", done)); + baseUrl = `http://127.0.0.1:${(server.address() as AddressInfo).port}`; +}); + +afterAll(async () => { + await new Promise((done) => server.close(done)); + fs.rmSync(root, { recursive: true, force: true }); +}); + +async function get(route: string, init?: RequestInit) { + const response = await fetch(`${baseUrl}${route}`, init); + return { + status: response.status, + type: response.headers.get("content-type"), + cache: response.headers.get("cache-control"), + body: await response.text(), + }; +} + +describe("static server", () => { + test("serves raw Markdown as UTF-8 Markdown", async () => { + expect(await get("/docs/guide.md")).toMatchObject({ + status: 200, + type: "text/markdown; charset=utf-8", + body: "# Guide", + }); + }); + + test("returns the exported 404 page for missing Markdown instead of the HTML shell", async () => { + expect(await get("/docs/missing.md")).toMatchObject({ + status: 404, + body: "

not found

", + }); + }); + + test("returns 404 for the retired /docs/cm routes", async () => { + for (const route of ["/docs/cm", "/docs/cm.md", "/docs/cm/old"]) { + expect(await get(route)).toMatchObject({ + status: 404, + body: "

not found

", + }); + } + }); + + test("prefers an exported HTML page over a same-name asset directory", async () => { + expect(await get("/docs/guide")).toMatchObject({ + status: 200, + type: "text/html; charset=utf-8", + body: "

guide page

", + }); + expect((await get("/docs/guide/diagram.png")).body).toBe("png"); + }); + + test("serves directory index pages and falls back to the shell for unknown routes", async () => { + expect((await get("/docs/section")).body).toBe("

section index

"); + expect(await get("/docs/unknown")).toMatchObject({ + status: 200, + body: "

shell

", + }); + }); + + test("caches static assets and 404s missing ones", async () => { + expect(await get("/_next/static/app.js")).toMatchObject({ + status: 200, + cache: "public, max-age=15552000", + }); + expect((await get("/_next/static/missing.js")).status).toBe(404); + }); + + test("does not serve files outside the root", async () => { + const response = await get("/%2e%2e/%2e%2e/etc/passwd"); + expect(response.body).not.toContain("root:"); + }); + + test("rejects methods other than GET and HEAD", async () => { + expect((await get("/", { method: "POST" })).status).toBe(405); + }); +}); From 68edb48d40fa92279c520c2b614cf65fa07b0a22 Mon Sep 17 00:00:00 2001 From: Vigneshraj Sekar Babu Date: Wed, 18 Nov 2026 12:27:12 -0800 Subject: [PATCH 2/3] fix: harden static server routing and smoke-test the image in CI Normalize request paths before routing, never look outside the root for /, add ETag/Last-Modified revalidation, and bound shutdown. CI now builds the image, runs scripts/smokeImage.sh, and fails on fixable High/Critical CVEs. --- .../references/raw-markdown.md | 10 +- .github/workflows/ci.yml | 17 +++ scripts/smokeImage.sh | 78 +++++++++++++ server.mjs | 108 ++++++++++++------ tests/server.test.ts | 62 +++++++++- 5 files changed, 235 insertions(+), 40 deletions(-) create mode 100755 scripts/smokeImage.sh diff --git a/.agents/skills/update-lifecycle-docs/references/raw-markdown.md b/.agents/skills/update-lifecycle-docs/references/raw-markdown.md index ae5ade02..357b774c 100644 --- a/.agents/skills/update-lifecycle-docs/references/raw-markdown.md +++ b/.agents/skills/update-lifecycle-docs/references/raw-markdown.md @@ -13,7 +13,7 @@ copy-page feature copies MDX source rather than a clean Markdown rendering. [Next.js static export](https://nextjs.org/docs/pages/guides/static-exports) does not support a runtime API route or rewrite for this purpose. A pre-build projection into `public/` gives local development, static export, GitHub Pages, -and Nginx the same files. +and the container server the same files. Re-evaluate this decision only during an intentional framework migration. Require the replacement to support clean Markdown, exact `.md` paths, static @@ -96,10 +96,10 @@ edit `public/llms.txt` directly. ## Deployment Next.js copies generated files from `public/` to `out/`. GitHub Pages serves -them from the static export. The repository Nginx configuration gives `.md` -files the `text/markdown; charset=utf-8` media type and returns 404 for a -missing `.md` path. Its HTML fallback checks `$uri.html` before `$uri`. This -order prevents a page asset directory, such as `/docs/guide/`, from hiding the +them from the static export. The container image serves `out/` with +`server.mjs`. It gives `.md` files the `text/markdown; charset=utf-8` media +type and returns 404 for a missing `.md` path. Its HTML fallback checks +`.html` before ``. This order prevents a page asset directory, such as `/docs/guide/`, from hiding the exported `/docs/guide.html` page. After a deployment-path or asset-path change, use the production server diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index aaa38120..ea0161a0 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -37,3 +37,20 @@ jobs: bun-version: 1.4.4 - run: bun install --frozen-lockfile - run: bun run verify + + image: + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v4 + - name: Build image + run: docker build -t lifecycle-docs:ci . + - name: Smoke test image + run: scripts/smokeImage.sh lifecycle-docs:ci + # Fails only on High/Critical findings that already have a fixed release; unfixed upstream + # advisories are reported but do not block. + - name: Scan image for fixable vulnerabilities + run: | + docker run --rm -v /var/run/docker.sock:/var/run/docker.sock \ + anchore/grype:v0.121.0 docker:lifecycle-docs:ci \ + --only-fixed --fail-on high diff --git a/scripts/smokeImage.sh b/scripts/smokeImage.sh new file mode 100755 index 00000000..e8b78bd4 --- /dev/null +++ b/scripts/smokeImage.sh @@ -0,0 +1,78 @@ +#!/usr/bin/env bash +# Copyright 2026 GoodRx, Inc. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +# Runs the built docs image and checks the routing contract the deployment depends on. +# Usage: scripts/smokeImage.sh [host-port] +set -euo pipefail + +image="${1:?usage: smokeImage.sh [host-port]}" +port="${2:-18080}" +name="lifecycle-docs-smoke-$$" +base="http://127.0.0.1:${port}" +failures=0 + +cleanup() { docker rm -f "$name" >/dev/null 2>&1 || true; } +trap cleanup EXIT + +docker run -d --name "$name" -p "127.0.0.1:${port}:8080" "$image" >/dev/null + +for _ in $(seq 1 30); do + curl -fs -o /dev/null "$base/" && break + sleep 1 +done + +check() { + local path="$1" want_status="$2" want_type="$3" + local got + got="$(curl -s --path-as-is -o /dev/null -w '%{http_code} %{content_type}' "$base$path")" + if [[ "$got" == "$want_status $want_type"* ]]; then + echo "ok $path -> $got" + else + echo "FAIL $path -> $got (want $want_status $want_type)" + failures=$((failures + 1)) + fi +} + +check "/" 200 "text/html" +check "/docs" 200 "text/html" +check "/docs.md" 200 "text/markdown; charset=utf-8" +check "/llms.txt" 200 "text/plain" +check "/docs/does-not-exist.md" 404 "text/html" +check "/docs/cm" 404 "text/html" +check "/docs//cm" 404 "text/html" +check "/_next/static/does-not-exist.js" 404 "text/html" +check "/unknown/client/route" 200 "text/html" + +asset="$(curl -s "$base/" | grep -oE '/_next/static/[^"]+\.js' | head -n 1)" +check "$asset" 200 "text/javascript" + +user="$(docker inspect --format '{{.Config.User}}' "$image")" +if [[ -z "$user" || "$user" == "root" || "$user" == "0" ]]; then + echo "FAIL image runs as root" + failures=$((failures + 1)) +fi + +docker stop -t 10 "$name" >/dev/null +exit_code="$(docker inspect --format '{{.State.ExitCode}}' "$name")" +if [[ "$exit_code" != "0" ]]; then + echo "FAIL container exited with $exit_code on SIGTERM" + failures=$((failures + 1)) +fi + +if ((failures > 0)); then + docker logs "$name" || true + exit 1 +fi +echo "image smoke test passed" diff --git a/server.mjs b/server.mjs index a417c8ec..32fc71b8 100644 --- a/server.mjs +++ b/server.mjs @@ -17,7 +17,7 @@ import { createReadStream } from "node:fs"; import { stat } from "node:fs/promises"; import { createServer } from "node:http"; -import { extname, join, normalize, resolve, sep } from "node:path"; +import { extname, join, posix, resolve } from "node:path"; import { pathToFileURL } from "node:url"; const CONTENT_TYPES = { @@ -47,6 +47,11 @@ const CONTENT_TYPES = { ".pdf": "application/pdf", ".mp4": "video/mp4", ".webm": "video/webm", + ".wasm": "application/wasm", + ".htm": "text/html; charset=utf-8", + ".csv": "text/csv; charset=utf-8", + ".rss": "application/rss+xml", + ".atom": "application/atom+xml", }; const STATIC_ASSETS = new Set([ @@ -66,50 +71,81 @@ const STATIC_ASSETS = new Set([ ".map", ]); -const RETIRED_ROUTE = /^\/docs\/cm(?:\.md|\/.*)?$/; +const RETIRED_ROUTE = /^\/docs\/cm(?:\.md|\/[\s\S]*)?$/; +const SHUTDOWN_TIMEOUT_MS = 25_000; async function findFile(candidate) { try { const info = await stat(candidate); - return info.isFile() ? candidate : null; + return info.isFile() ? { path: candidate, info } : null; } catch { return null; } } /** - * Maps a decoded URL path to the file to serve and its status. + * Turns a raw request target into a canonical absolute path, or null when it cannot be served. + * + * Slashes are collapsed and dot segments resolved before any routing rule runs, so `/docs//cm` or + * `/docs/x/..%2fcm` cannot slip past the retired-route check, and no path can climb above the root. + */ +export function canonicalPath(target) { + const raw = (target ?? "/").split(/[?#]/, 1)[0]; + let decoded; + try { + decoded = decodeURIComponent(raw); + } catch { + return null; + } + if (decoded.includes("\0")) return null; + return posix.normalize( + `/${decoded.replace(/\\/g, "/")}`.replace(/\/+/g, "/"), + ); +} + +/** + * Maps a canonical URL path to the file to serve and its status. * * Raw Markdown and static assets fail closed with the exported 404 page instead of the HTML shell, so * agents fetching `.md` never receive HTML. HTML routes prefer `.html` over a same-name asset * directory, then fall back to `index.html` for client-side routing. */ export async function resolveRequest(root, urlPath) { - const notFound = { + const notFound = async () => ({ file: await findFile(join(root, "404.html")), status: 404, - }; - if (RETIRED_ROUTE.test(urlPath)) return notFound; + }); + if (RETIRED_ROUTE.test(urlPath)) return notFound(); - const base = join(root, normalize(urlPath).replace(/^[/\\]+/, "")); - if (base !== root && !base.startsWith(root + sep)) return notFound; + const route = urlPath.replace(/\/+$/, ""); + const base = join(root, route); - const ext = extname(urlPath).toLowerCase(); - if (ext === ".md" || STATIC_ASSETS.has(ext)) { + const ext = extname(route); + if (ext === ".md" || STATIC_ASSETS.has(ext.toLowerCase())) { const file = await findFile(base); - return file ? { file, status: 200 } : notFound; + return file ? { file, status: 200 } : notFound(); } - for (const candidate of [ - `${base}.html`, - base, - join(base, "index.html"), - join(root, "index.html"), - ]) { + const candidates = route + ? [`${base}.html`, base, join(base, "index.html")] + : [join(root, "index.html")]; + for (const candidate of [...candidates, join(root, "index.html")]) { const file = await findFile(candidate); if (file) return { file, status: 200 }; } - return notFound; + return notFound(); +} + +function isNotModified(req, etag, mtime) { + const ifNoneMatch = req.headers["if-none-match"]; + if (ifNoneMatch) { + return ifNoneMatch.split(",").some((tag) => tag.trim() === etag); + } + const ifModifiedSince = Date.parse(req.headers["if-modified-since"] ?? ""); + return ( + !Number.isNaN(ifModifiedSince) && + Math.floor(mtime.getTime() / 1000) <= Math.floor(ifModifiedSince / 1000) + ); } export function createStaticServer(rootDir) { @@ -120,12 +156,8 @@ export function createStaticServer(rootDir) { return; } - let urlPath; - try { - urlPath = decodeURIComponent( - new URL(req.url ?? "/", "http://localhost").pathname, - ); - } catch { + const urlPath = canonicalPath(req.url); + if (!urlPath) { res.writeHead(400).end(); return; } @@ -136,23 +168,31 @@ export function createStaticServer(rootDir) { return; } - const { size } = await stat(file); - const ext = extname(file).toLowerCase(); - res.writeHead(status, { + const { size, mtime } = file.info; + const ext = extname(file.path).toLowerCase(); + const etag = `W/"${size.toString(16)}-${mtime.getTime().toString(16)}"`; + const headers = { "Content-Type": CONTENT_TYPES[ext] ?? "application/octet-stream", - "Content-Length": size, "Cache-Control": status === 200 && STATIC_ASSETS.has(ext) ? "public, max-age=15552000" : "no-cache", + ETag: etag, + "Last-Modified": mtime.toUTCString(), "X-Content-Type-Options": "nosniff", - }); + }; + if (status === 200 && isNotModified(req, etag, mtime)) { + res.writeHead(304, headers).end(); + return; + } + + res.writeHead(status, { ...headers, "Content-Length": size }); if (req.method === "HEAD") { res.end(); return; } - createReadStream(file) + createReadStream(file.path) .on("error", () => res.destroy()) .pipe(res); }); @@ -169,6 +209,10 @@ if ( server.listen(port, () => console.log(`serving ${root} on :${port}`)); for (const signal of ["SIGTERM", "SIGINT"]) { - process.on(signal, () => server.close(() => process.exit(0))); + process.on(signal, () => { + server.close(() => process.exit(0)); + server.closeIdleConnections(); + setTimeout(() => process.exit(0), SHUTDOWN_TIMEOUT_MS).unref(); + }); } } diff --git a/tests/server.test.ts b/tests/server.test.ts index 0ae04bb0..72162595 100644 --- a/tests/server.test.ts +++ b/tests/server.test.ts @@ -112,12 +112,68 @@ describe("static server", () => { status: 200, cache: "public, max-age=15552000", }); - expect((await get("/_next/static/missing.js")).status).toBe(404); + expect(await get("/_next/static/missing.js")).toMatchObject({ + status: 404, + cache: "no-cache", + body: "

not found

", + }); + }); + + test("serves the root index without looking outside the root", async () => { + fs.writeFileSync(`${root}.html`, "outside"); + try { + expect(await get("/")).toMatchObject({ + status: 200, + body: "

shell

", + }); + } finally { + fs.rmSync(`${root}.html`); + } }); test("does not serve files outside the root", async () => { - const response = await get("/%2e%2e/%2e%2e/etc/passwd"); - expect(response.body).not.toContain("root:"); + fs.writeFileSync(`${root}-sibling.md`, "outside"); + try { + for (const route of [ + "/%2e%2e/%2e%2e/etc/passwd", + `/..%2f${path.basename(root)}-sibling.md`, + ]) { + const response = await get(route); + expect(response.body).not.toContain("root:"); + expect(response.body).not.toBe("outside"); + } + } finally { + fs.rmSync(`${root}-sibling.md`); + } + }); + + test("normalizes the path before applying the retired-route rule", async () => { + for (const route of [ + "//docs/cm", + "/docs//cm", + "/docs/x/..%2fcm", + "/docs/cm/%0a%2f..%2f..%2fcm", + ]) { + expect((await get(route)).status).toBe(404); + } + }); + + test("rejects malformed and NUL-containing paths", async () => { + expect((await get("/%ff")).status).toBe(400); + expect((await get("/docs%00.md")).status).toBe(400); + }); + + test("answers HEAD without a body and revalidates with 304", async () => { + const head = await fetch(`${baseUrl}/docs/guide.md`, { method: "HEAD" }); + expect(head.status).toBe(200); + expect(await head.text()).toBe(""); + + const etag = head.headers.get("etag") ?? ""; + expect(etag).not.toBe(""); + const revalidated = await fetch(`${baseUrl}/docs/guide.md`, { + headers: { "If-None-Match": etag }, + }); + expect(revalidated.status).toBe(304); }); test("rejects methods other than GET and HEAD", async () => { From 7ff486d0adf6710e23dd01d8fe57983bddaab724 Mon Sep 17 00:00:00 2001 From: Vigneshraj Sekar Babu Date: Wed, 18 Nov 2026 12:43:15 -0800 Subject: [PATCH 3/3] fix: close retired-route gaps and release streams on client abort --- server.mjs | 102 +++++++++++++++++++++++-------------------- tests/server.test.ts | 9 +++- 2 files changed, 62 insertions(+), 49 deletions(-) diff --git a/server.mjs b/server.mjs index 32fc71b8..0c1d8756 100644 --- a/server.mjs +++ b/server.mjs @@ -17,6 +17,7 @@ import { createReadStream } from "node:fs"; import { stat } from "node:fs/promises"; import { createServer } from "node:http"; +import { pipeline } from "node:stream"; import { extname, join, posix, resolve } from "node:path"; import { pathToFileURL } from "node:url"; @@ -71,7 +72,7 @@ const STATIC_ASSETS = new Set([ ".map", ]); -const RETIRED_ROUTE = /^\/docs\/cm(?:\.md|\/[\s\S]*)?$/; +const RETIRED_ROUTE = /^\/docs\/cm(?:\.md|\.html)?(?:\/[\s\S]*)?$/; const SHUTDOWN_TIMEOUT_MS = 25_000; async function findFile(candidate) { @@ -115,9 +116,8 @@ export async function resolveRequest(root, urlPath) { file: await findFile(join(root, "404.html")), status: 404, }); - if (RETIRED_ROUTE.test(urlPath)) return notFound(); - const route = urlPath.replace(/\/+$/, ""); + if (RETIRED_ROUTE.test(route)) return notFound(); const base = join(root, route); const ext = extname(route); @@ -148,53 +148,59 @@ function isNotModified(req, etag, mtime) { ); } +async function handle(root, req, res) { + if (req.method !== "GET" && req.method !== "HEAD") { + res.writeHead(405, { Allow: "GET, HEAD" }).end(); + return; + } + + const urlPath = canonicalPath(req.url); + if (!urlPath) { + res.writeHead(400).end(); + return; + } + + const { file, status } = await resolveRequest(root, urlPath); + if (!file) { + res.writeHead(status).end(); + return; + } + + const { size, mtime } = file.info; + const ext = extname(file.path).toLowerCase(); + const etag = `W/"${size.toString(16)}-${mtime.getTime().toString(16)}"`; + const headers = { + "Content-Type": CONTENT_TYPES[ext] ?? "application/octet-stream", + "Cache-Control": + status === 200 && STATIC_ASSETS.has(ext) + ? "public, max-age=15552000" + : "no-cache", + ETag: etag, + "Last-Modified": mtime.toUTCString(), + "X-Content-Type-Options": "nosniff", + }; + + if (status === 200 && isNotModified(req, etag, mtime)) { + res.writeHead(304, headers).end(); + return; + } + + res.writeHead(status, { ...headers, "Content-Length": size }); + if (req.method === "HEAD") { + res.end(); + return; + } + pipeline(createReadStream(file.path), res, () => {}); +} + export function createStaticServer(rootDir) { const root = resolve(rootDir); - return createServer(async (req, res) => { - if (req.method !== "GET" && req.method !== "HEAD") { - res.writeHead(405, { Allow: "GET, HEAD" }).end(); - return; - } - - const urlPath = canonicalPath(req.url); - if (!urlPath) { - res.writeHead(400).end(); - return; - } - - const { file, status } = await resolveRequest(root, urlPath); - if (!file) { - res.writeHead(status).end(); - return; - } - - const { size, mtime } = file.info; - const ext = extname(file.path).toLowerCase(); - const etag = `W/"${size.toString(16)}-${mtime.getTime().toString(16)}"`; - const headers = { - "Content-Type": CONTENT_TYPES[ext] ?? "application/octet-stream", - "Cache-Control": - status === 200 && STATIC_ASSETS.has(ext) - ? "public, max-age=15552000" - : "no-cache", - ETag: etag, - "Last-Modified": mtime.toUTCString(), - "X-Content-Type-Options": "nosniff", - }; - - if (status === 200 && isNotModified(req, etag, mtime)) { - res.writeHead(304, headers).end(); - return; - } - - res.writeHead(status, { ...headers, "Content-Length": size }); - if (req.method === "HEAD") { - res.end(); - return; - } - createReadStream(file.path) - .on("error", () => res.destroy()) - .pipe(res); + return createServer((req, res) => { + handle(root, req, res).catch((error) => { + console.error(error); + if (res.headersSent) res.destroy(); + else res.writeHead(500).end(); + }); }); } diff --git a/tests/server.test.ts b/tests/server.test.ts index 72162595..191b698c 100644 --- a/tests/server.test.ts +++ b/tests/server.test.ts @@ -82,7 +82,14 @@ describe("static server", () => { }); test("returns 404 for the retired /docs/cm routes", async () => { - for (const route of ["/docs/cm", "/docs/cm.md", "/docs/cm/old"]) { + for (const route of [ + "/docs/cm", + "/docs/cm.md", + "/docs/cm/old", + "/docs/cm.md/", + "/docs/cm.html", + "/docs/cm.html/", + ]) { expect(await get(route)).toMatchObject({ status: 404, body: "

not found

",