Files
tech-log-frontend/scripts/generate-nginx-config.ts
T
DongHyeonkaandClaude Opus 5 a936444dfc fix: 릴리스 노트를 목록으로 제대로 읽고 robots.txt 를 서빙한다
릴리스 노트의 각 칸은 Markdown 인데 줄을 쪼개 `- ` 만 떼는 것이 전부였다.
그래서 작성자가 소제목으로 쓴 `## 작성` 이 항목 하나로 섞였고, `:::note`
와 `---`, `![대체](/...)` 도 글자 그대로 목록에 나왔다. 그 노트의 내용이
하필 "본문의 표·코드·callout·그림이 렌더링됩니다" 였다.

소제목·수평선·블록 울타리는 항목이 아니므로 버린다. 소제목까지 살리려면
화면이 절을 나눠야 하는데 이 칸은 「무엇이 바뀌었나」 아래의 한 목록이다.
번호 목록도 항목으로 읽는다. 백틱은 남겨 두고 화면이 코드로 그린다.

robots.txt 가 404 였다. 파일은 이미지에 들어 있었지만 nginx 설정이 서빙할
파일을 하나씩 명시하는 구조라 등록되지 않은 것은 SPA 폴백으로 떨어진다 —
크롤러가 index.html 을 규칙으로 읽을 수는 없으므로 규칙이 없는 것과 같았다.

설명(meta)에서 백틱을 지운다. 본문에서는 코드가 되지만 검색 결과에는 그
문자가 그대로 나간다.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011nAjrqNHGPNngN4aUbcyvJ
2026-08-31 09:09:57 +09:00

240 lines
8.6 KiB
TypeScript

import { readFile, writeFile } from "node:fs/promises";
import path from "node:path";
/**
* Emits the nginx configuration the deployed frontend is served with.
*
* Generated rather than hand-written because three files already decide what it
* must say, and a copy of them would drift: `dist/tech-log-serving-contract.json`
* (which paths are SPA routes and what a miss answers with),
* `config/hosting/security-headers.json`, and `config/hosting/cache-policy.json`.
* The repository had no frontend deployment artifact at all — no Dockerfile, no
* server config — so those two hosting files described a contract nothing
* fulfilled: `dist/server.mjs` applies neither, answering `no-cache` for hashed
* assets and sending no security headers.
*
* This serves static files only. TLS and the BFF paths belong to the edge: the
* deployment's own nginx terminates HTTPS and sends `/api`, the OIDC redirect
* chain and the identity provider to the backend directly (in Kubernetes,
* Traefik does). A second proxy hop here would only add a place for the two
* routing tables to disagree.
*
* The base path comes from `VITE_ROUTER_BASE_PATH`, the same value the bundle is
* built with: served under a prefix, every route and asset lives under it too.
*/
const DIST = "dist";
const OUT = path.join(DIST, "nginx.conf");
type ServingContract = Readonly<{
publicSpaPathPatterns: readonly string[];
studioPathPrefix: string;
studioSpaPathPatterns: readonly string[];
notFound: Readonly<{ status: number; contentType: string; body: string }>;
}>;
type HostingHeaders = Readonly<{ headers: Readonly<Record<string, string>> }>;
type CachePolicy = Readonly<{
surfaces: Readonly<
Record<
string,
Readonly<{
path?: string;
pathPattern?: string;
cacheControl?: string;
securityHeaders?: boolean;
}>
>
>;
}>;
async function readJson<T>(file: string): Promise<T> {
return JSON.parse(await readFile(file, "utf8")) as T;
}
/** nginx location matching is not regex-escaped for us; only `=` exact paths are literal. */
function exactLocation(pathname: string): string {
return pathname;
}
/**
* A JS regex from the contract translated for nginx. Both use PCRE-ish syntax
* for what the contract uses (`^`, `$`, `[^/]+`, alternation), so the pattern
* carries over unchanged — asserted rather than assumed, because a pattern that
* silently failed to translate would open a Studio route to the 404 branch.
*/
function studioRegex(pattern: string): string {
// nginx uses PCRE, so anchors, character classes, alternation and plain groups
// carry over as written. Lookaround and backreferences do not translate the
// same way and would silently change which paths match, so they are refused.
if (/\(\?[=!<]|\\[1-9]/.test(pattern)) {
throw new Error(
`studio SPA pattern uses a construct this generator does not translate: ${pattern}`,
);
}
return pattern;
}
function headerDirectives(
headers: Readonly<Record<string, string>>,
indent: string,
): string {
return Object.entries(headers)
.map(([name, value]) => `${indent}add_header ${name} "${value}" always;`)
.join("\n");
}
async function main(): Promise<void> {
const contract = await readJson<ServingContract>(
path.join(DIST, "tech-log-serving-contract.json"),
);
const security = await readJson<HostingHeaders>(
"config/hosting/security-headers.json",
);
const cache = await readJson<CachePolicy>("config/hosting/cache-policy.json");
const surfaces = cache.surfaces;
const indexCache = surfaces["index"]?.cacheControl ?? "no-cache";
const configCache = surfaces["runtimeConfig"]?.cacheControl ?? "no-store";
const manifestCache = surfaces["releaseManifest"]?.cacheControl ?? "no-store";
const assetCache = surfaces["hashedAsset"]?.cacheControl ?? "no-cache";
const secure = headerDirectives(security.headers, " ");
// The bundle's own base path. `/` for a deployment at the domain root, `/dev/`
// for one served under a prefix — the routes below have to carry it or nginx
// matches paths the browser never asks for.
const rawBase = process.env["VITE_ROUTER_BASE_PATH"] ?? "/";
const basePath = rawBase.endsWith("/") ? rawBase.slice(0, -1) : rawBase;
const [notFoundType, notFoundCharsetParam] = contract.notFound.contentType
.split(";")
.map((part) => part.trim());
const notFoundCharset = (notFoundCharsetParam ?? "charset=utf-8")
.replace(/^charset=/i, "")
.toLowerCase();
// Regex locations now, matching the Studio half: the contract declares which
// paths the router serves, not which ones the fixture happened to contain, so
// a record published after this build is served instead of 404ed at the edge.
const publicLocations = contract.publicSpaPathPatterns
.map(
(pattern: string) => ` location ~ ^${basePath}${studioRegex(pattern).slice(1)} {
${secure}
add_header Cache-Control "${indexCache}" always;
try_files /index.html =404;
}`,
)
.join("\n\n");
const studioLocations = contract.studioSpaPathPatterns
.map(
(pattern) => ` location ~ ^${basePath}${studioRegex(pattern).slice(1)} {
${secure}
add_header Cache-Control "${indexCache}" always;
try_files /index.html =404;
}`,
)
.join("\n\n");
const conf = `# Generated by scripts/generate-nginx-config.ts — do not edit.
# Sources: dist/tech-log-serving-contract.json, config/hosting/security-headers.json,
# config/hosting/cache-policy.json
#
# Plain HTTP on purpose: the edge terminates TLS and this container is only ever
# reached from inside the deployment network.
server {
listen 80;
server_name _;
root /usr/share/nginx/html;
index index.html;
# The bundle is small and already compressed at rest by the build; gzip here
# covers the JSON surfaces and index.html.
gzip on;
gzip_types text/css application/javascript text/javascript application/json;
gzip_min_length 1024;
# Static surfaces, per config/hosting/cache-policy.json
# ---------------------------------------------------------------------------
location = ${basePath}/config.json {
alias /usr/share/nginx/html/config.json;
${secure}
add_header Cache-Control "${configCache}" always;
}
location = ${basePath}/release-manifest.json {
alias /usr/share/nginx/html/release-manifest.json;
${secure}
add_header Cache-Control "${manifestCache}" always;
}
# Content-hashed filenames, so the long TTL is safe and revalidation is waste.
location ${basePath}/assets/ {
# alias, not root + URI: under a base path the request is /dev/assets/x.js
# while the file is dist/assets/x.js, so root would look for
# dist/dev/assets/x.js and answer 404 for every script on the page.
alias /usr/share/nginx/html/assets/;
add_header Cache-Control "${assetCache}" always;
}
# Source maps are not published (cache-policy sourceMap.public = false).
location ~ \\.map$ {
return 404;
}
# ---------------------------------------------------------------------------
# SPA routes. Enumerated from the serving contract rather than a catch-all:
# a path that is not a real route answers 404 instead of a 200 shell, which is
# what tells a crawler the difference.
# ---------------------------------------------------------------------------
${publicLocations}
${studioLocations}
location = ${basePath}/favicon.svg {
alias /usr/share/nginx/html/favicon.svg;
add_header Cache-Control "${assetCache}" always;
}
# 크롤러가 처음 찾는 파일이다. 여기 없으면 SPA 폴백이 index.html 을 주고,
# 크롤러는 그것을 규칙으로 읽을 수 없어 결국 아무 규칙도 없는 것과 같아진다.
location = ${basePath}/robots.txt {
alias /usr/share/nginx/html/robots.txt;
default_type text/plain;
add_header Cache-Control "${indexCache}" always;
}
location = ${basePath}/media/ {
return 404;
}
location ${basePath}/media/ {
alias /usr/share/nginx/html/media/;
add_header Cache-Control "${assetCache}" always;
}
# Anything else is not a route this deployment serves.
location / {
# The contract states the content type with its charset attached
# (text/plain;charset=UTF-8), but nginx takes the two separately —
# default_type rejects a parameter outright.
default_type ${notFoundType};
charset ${notFoundCharset};
return ${contract.notFound.status} "${contract.notFound.body}";
}
}
`;
await writeFile(OUT, conf, "utf8");
process.stdout.write(
`nginx config: ${OUT} (${contract.publicSpaPathPatterns.length} public routes, ` +
`${contract.studioSpaPathPatterns.length} studio patterns)\n`,
);
}
await main();