@chidchanun/bcp 0.1.0

package/packages/server/src/standalone-production-runtime-v2.ts

@@ -0,0 +1,2047 @@
+import {
+    createHash,
+} from "node:crypto";
+import fs from "node:fs/promises";
+import * as http from "node:http";
+import path from "node:path";
+
+import {
+    createElement,
+    type ComponentType,
+    type ReactElement,
+} from "react";
+
+import {
+    renderToStaticMarkup,
+    renderToString,
+} from "react-dom/server";
+
+import type {
+    ProductionRouteAsset,
+} from "../../bundler/src/production.js";
+
+import {
+    createMetadataHeadEntries,
+    type ResolvedMetadata,
+} from "../../client/src/metadata.js";
+
+import {
+    isNotFoundError,
+} from "../../client/src/not-found.js";
+
+import {
+    matchApiRoute,
+    matchRoute,
+    type ApiRoute,
+    type Route,
+    type RouteSegment,
+} from "../../router/src/index.js";
+
+import {
+    appendVary,
+    compressDynamicContent,
+    isCompressibleContentType,
+    selectContentEncoding,
+} from "./compression.js";
+
+import {
+    resolveRouteMetadata,
+    type MetadataSource,
+} from "./metadata.js";
+
+import {
+    getContentType,
+    readPublicAsset,
+    type StaticAsset,
+} from "./static-assets.js";
+
+export interface StandalonePageRoute {
+    pathname: string;
+    segments: RouteSegment[];
+    page: ComponentType<any>;
+    layouts: ComponentType<any>[];
+    loading: ComponentType<any> | null;
+    error: ComponentType<any> | null;
+    notFound: ComponentType<any> | null;
+    metadataSources: MetadataSource[];
+    client: ProductionRouteAsset;
+}
+
+export interface StandaloneApiRoute {
+    pathname: string;
+    segments: RouteSegment[];
+    handlers: Record<string, unknown>;
+}
+
+export interface StandaloneProductionServerOptions {
+    port: number;
+    hostname: string;
+    buildDirectory: string;
+    buildId: string;
+    version: number;
+    routes: StandalonePageRoute[];
+    apiRoutes: StandaloneApiRoute[];
+    globalNotFound?: ComponentType<any> | null;
+    globalNotFoundLayouts?: ComponentType<any>[];
+}
+
+interface ApiContext {
+    params: Record<string, string>;
+}
+
+type ApiHandler = (
+    request: Request,
+    context: ApiContext
+) => Response | Promise<Response>;
+
+const HTTP_METHODS = [
+    "GET",
+    "POST",
+    "PUT",
+    "PATCH",
+    "DELETE",
+    "HEAD",
+    "OPTIONS",
+] as const;
+
+type HttpMethod =
+    typeof HTTP_METHODS[number];
+
+export function createStandaloneProductionServer(
+    options: StandaloneProductionServerOptions
+) {
+    const port =
+        options.port;
+    const hostname =
+        options.hostname;
+    const buildDirectory =
+        path.resolve(
+            options.buildDirectory
+        );
+    const clientDirectory =
+        path.join(
+            buildDirectory,
+            "client"
+        );
+
+    const routeByPathname =
+        new Map(
+            options.routes.map(
+                (route) => [
+                    route.pathname,
+                    route,
+                ]
+            )
+        );
+
+    const apiByPathname =
+        new Map(
+            options.apiRoutes.map(
+                (route) => [
+                    route.pathname,
+                    route,
+                ]
+            )
+        );
+
+    const routePatterns:
+        Route[] =
+        options.routes.map(
+            (route) => ({
+                pathname:
+                    route.pathname,
+                segments:
+                    route.segments,
+                filePath:
+                    route.pathname,
+                layouts: [],
+            })
+        );
+
+    const apiPatterns:
+        ApiRoute[] =
+        options.apiRoutes.map(
+            (route) => ({
+                pathname:
+                    route.pathname,
+                segments:
+                    route.segments,
+                filePath:
+                    route.pathname,
+            })
+        );
+
+    const server =
+        http.createServer(
+            async (
+                req,
+                res
+            ) => {
+                const startedAt =
+                    performance.now();
+                let pathname =
+                    "/";
+
+                try {
+                    const requestUrl =
+                        new URL(
+                            req.url ?? "/",
+                            `http://${
+                                req.headers.host ??
+                                `${hostname}:${port}`
+                            }`
+                        );
+
+                    pathname =
+                        normalizePathname(
+                            requestUrl.pathname
+                        );
+
+                    res.once(
+                        "finish",
+                        () => {
+                            const duration =
+                                performance.now() -
+                                startedAt;
+
+                            console.log(
+                                `${req.method ?? "GET"} ${pathname} ${res.statusCode} ${duration.toFixed(2)}ms`
+                            );
+                        }
+                    );
+
+                    if (
+                        pathname ===
+                        "/_bcp/navigation"
+                    ) {
+                        await handleNavigation(
+                            req,
+                            res,
+                            requestUrl,
+                            routePatterns,
+                            routeByPathname,
+                            options.version
+                        );
+                        return;
+                    }
+
+                    if (
+                        pathname.startsWith(
+                            "/_bcp/client/"
+                        )
+                    ) {
+                        const served =
+                            await serveBuildAsset(
+                                req,
+                                res,
+                                clientDirectory,
+                                pathname
+                            );
+
+                        if (!served) {
+                            sendSimpleNotFound(
+                                req,
+                                res
+                            );
+                        }
+                        return;
+                    }
+
+                    const apiMatch =
+                        matchApiRoute(
+                            apiPatterns,
+                            pathname
+                        );
+
+                    if (apiMatch) {
+                        const definition =
+                            apiByPathname.get(
+                                apiMatch.route.pathname
+                            );
+
+                        if (!definition) {
+                            throw new Error(
+                                `BCP Framework: standalone API definition missing for "${apiMatch.route.pathname}".`
+                            );
+                        }
+
+                        try {
+                            await handleApiRoute(
+                                req,
+                                res,
+                                requestUrl,
+                                definition,
+                                apiMatch.params
+                            );
+                        } catch (error) {
+                            console.error(
+                                `[BCP API Error] ${req.method ?? "GET"} ${pathname}:`,
+                                error
+                            );
+
+                            if (!res.headersSent) {
+                                sendJson(
+                                    req,
+                                    res,
+                                    500,
+                                    {
+                                        error:
+                                            "Internal Server Error",
+                                    }
+                                );
+                            } else {
+                                res.end();
+                            }
+                        }
+                        return;
+                    }
+
+                    const publicAsset =
+                        await readPublicAsset(
+                            buildDirectory,
+                            pathname
+                        );
+
+                    if (publicAsset) {
+                        sendPublicAsset(
+                            req,
+                            res,
+                            publicAsset
+                        );
+                        return;
+                    }
+
+                    const match =
+                        matchRoute(
+                            routePatterns,
+                            pathname
+                        );
+
+                    if (!match) {
+                        sendGlobalNotFound(
+                            req,
+                            res,
+                            options
+                        );
+                        return;
+                    }
+
+                    const definition =
+                        routeByPathname.get(
+                            match.route.pathname
+                        );
+
+                    if (!definition) {
+                        throw new Error(
+                            `BCP Framework: standalone page definition missing for "${match.route.pathname}".`
+                        );
+                    }
+
+                    await sendPage(
+                        req,
+                        res,
+                        definition,
+                        match.params,
+                        options
+                    );
+                } catch (error) {
+                    console.error(
+                        "BCP Standalone Production Error:",
+                        error
+                    );
+
+                    if (res.headersSent) {
+                        res.end();
+                        return;
+                    }
+
+                    sendInternalServerError(
+                        req,
+                        res,
+                        error
+                    );
+                }
+            }
+        );
+
+    return {
+        async start() {
+            process.env.NODE_ENV =
+                "production";
+
+            await new Promise<void>(
+                (
+                    resolve,
+                    reject
+                ) => {
+                    const onError =
+                        (error: Error) => {
+                            server.off(
+                                "listening",
+                                onListening
+                            );
+                            reject(error);
+                        };
+
+                    const onListening =
+                        () => {
+                            server.off(
+                                "error",
+                                onError
+                            );
+                            resolve();
+                        };
+
+                    server.once(
+                        "error",
+                        onError
+                    );
+                    server.once(
+                        "listening",
+                        onListening
+                    );
+                    server.listen(
+                        port,
+                        hostname
+                    );
+                }
+            );
+
+            console.log("");
+            console.log(
+                "BCP Framework Standalone Production"
+            );
+            console.log(
+                `Local: http://${hostname}:${port}`
+            );
+            console.log(
+                `Build: ${options.buildId}`
+            );
+            console.log("");
+        },
+
+        async stop() {
+            if (!server.listening) {
+                return;
+            }
+
+            await new Promise<void>(
+                (
+                    resolve,
+                    reject
+                ) => {
+                    server.close(
+                        (error) => {
+                            if (error) {
+                                reject(error);
+                                return;
+                            }
+                            resolve();
+                        }
+                    );
+                }
+            );
+        },
+    };
+}
+
+async function sendPage(
+    req: http.IncomingMessage,
+    res: http.ServerResponse,
+    definition: StandalonePageRoute,
+    params: Record<string, string>,
+    options: StandaloneProductionServerOptions
+): Promise<void> {
+    try {
+        const metadata =
+            await resolveRouteMetadata(
+                definition.metadataSources,
+                params
+            );
+
+        const html =
+            renderPageDocument(
+                definition,
+                params,
+                metadata
+            );
+
+        sendHtml(
+            req,
+            res,
+            200,
+            html
+        );
+    } catch (error) {
+        if (isNotFoundError(error)) {
+            const NotFoundComponent =
+                definition.notFound ??
+                options.globalNotFound ??
+                null;
+
+            const html =
+                renderFallbackDocument(
+                    NotFoundComponent,
+                    definition.layouts,
+                    params,
+                    {
+                        kind:
+                            "not-found",
+                    }
+                );
+
+            sendHtml(
+                req,
+                res,
+                404,
+                html
+            );
+            return;
+        }
+
+        console.error(
+            `[BCP Page Error] ${definition.pathname}:`,
+            error
+        );
+
+        const html =
+            renderFallbackDocument(
+                definition.error,
+                definition.layouts,
+                params,
+                {
+                    kind:
+                        "error",
+                    error:
+                        createPublicServerError(
+                            error
+                        ),
+                }
+            );
+
+        sendHtml(
+            req,
+            res,
+            500,
+            html
+        );
+    }
+}
+
+function sendGlobalNotFound(
+    req: http.IncomingMessage,
+    res: http.ServerResponse,
+    options: StandaloneProductionServerOptions
+): void {
+    const html =
+        renderFallbackDocument(
+            options.globalNotFound ??
+                null,
+            options.globalNotFoundLayouts ??
+                [],
+            {},
+            {
+                kind:
+                    "not-found",
+            }
+        );
+
+    sendHtml(
+        req,
+        res,
+        404,
+        html
+    );
+}
+
+function renderPageDocument(
+    definition: StandalonePageRoute,
+    params: Record<string, string>,
+    metadata: ResolvedMetadata
+): string {
+    const element =
+        wrapWithLayouts(
+            createElement(
+                definition.page,
+                {
+                    params,
+                }
+            ),
+            definition.layouts,
+            params
+        );
+
+    const content =
+        renderToString(
+            element
+        );
+
+    return renderDocument({
+        content,
+        route:
+            definition.pathname,
+        params,
+        client:
+            definition.client,
+        metadata,
+    });
+}
+
+function renderFallbackDocument(
+    Component: ComponentType<any> | null,
+    layouts: ComponentType<any>[],
+    params: Record<string, string>,
+    fallback:
+        | {
+            kind: "not-found";
+        }
+        | {
+            kind: "error";
+            error: Error;
+        }
+): string {
+    const metadata =
+        fallback.kind ===
+            "not-found"
+            ? createFallbackMetadata(
+                "Page Not Found"
+            )
+            : createFallbackMetadata(
+                "Internal Server Error"
+            );
+
+    if (!Component) {
+        return fallback.kind ===
+            "not-found"
+            ? genericNotFoundDocument()
+            : genericErrorDocument(
+                getErrorDigest(
+                    fallback.error
+                )
+            );
+    }
+
+    const props =
+        fallback.kind ===
+            "error"
+            ? {
+                error:
+                    fallback.error,
+                reset:
+                    () => undefined,
+            }
+            : {};
+
+    try {
+        const content =
+            renderToString(
+                wrapWithLayouts(
+                    createElement(
+                        Component,
+                        props
+                    ),
+                    layouts,
+                    params
+                )
+            );
+
+        return renderDocument({
+            content,
+            route: null,
+            params: null,
+            client: null,
+            metadata,
+        });
+    } catch (fallbackError) {
+        console.error(
+            `[BCP ${fallback.kind} fallback error]:`,
+            fallbackError
+        );
+
+        try {
+            const content =
+                renderToString(
+                    createElement(
+                        Component,
+                        props
+                    )
+                );
+
+            return renderDocument({
+                content,
+                route: null,
+                params: null,
+                client: null,
+                metadata,
+            });
+        } catch (componentError) {
+            console.error(
+                `[BCP ${fallback.kind} component error]:`,
+                componentError
+            );
+
+            return fallback.kind ===
+                "not-found"
+                ? genericNotFoundDocument()
+                : genericErrorDocument(
+                    getErrorDigest(
+                        fallback.error
+                    )
+                );
+        }
+    }
+}
+
+function wrapWithLayouts(
+    child: ReactElement,
+    layouts: ComponentType<any>[],
+    params: Record<string, string>
+): ReactElement {
+    let element =
+        child;
+
+    for (
+        let index =
+            layouts.length - 1;
+        index >= 0;
+        index--
+    ) {
+        element =
+            createElement(
+                layouts[index],
+                {
+                    params,
+                },
+                element
+            );
+    }
+
+    return element;
+}
+
+function renderDocument(
+    input: {
+        content: string;
+        route: string | null;
+        params: Record<string, string> | null;
+        client: ProductionRouteAsset | null;
+        metadata: ResolvedMetadata;
+    }
+): string {
+    const modulePreloads =
+        input.client
+            ? input.client.imports
+                .map(
+                    (importPath) =>
+                        `    <link rel="modulepreload" href="${escapeHtmlAttribute(
+                            importPath
+                        )}" />`
+                )
+                .join("\n")
+            : "";
+
+    const metadataTags =
+        renderMetadataTags(
+            input.metadata
+        );
+
+    const frameworkData =
+        input.route !== null &&
+        input.params !== null
+            ? serializeFrameworkData({
+                route:
+                    input.route,
+                params:
+                    input.params,
+                metadata:
+                    input.metadata,
+            })
+            : null;
+
+    const clientRuntime =
+        input.client &&
+        frameworkData !== null
+            ? `
+    <script
+      id="__BCP_DATA__"
+      type="application/json"
+    >${frameworkData}</script>
+
+    <script
+      data-bcp-client
+      type="module"
+      src="${escapeHtmlAttribute(
+          input.client.entry
+      )}"
+    ></script>`
+            : "";
+
+    return `
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta
+      name="viewport"
+      content="width=device-width, initial-scale=1.0"
+    />
+    <title>${escapeHtml(
+        input.metadata.title
+    )}</title>
+${metadataTags}${metadataTags ? "\n" : ""}${modulePreloads}
+  </head>
+  <body>
+    <div id="root">${input.content}</div>
+${clientRuntime}
+  </body>
+</html>
+    `.trim();
+}
+
+function renderMetadataTags(
+    metadata: ResolvedMetadata
+): string {
+    return createMetadataHeadEntries(
+        metadata
+    )
+        .map(
+            (entry) => {
+                const attributes = {
+                    "data-bcp-metadata":
+                        entry.key,
+                    ...entry.attributes,
+                };
+
+                const serialized =
+                    Object.entries(
+                        attributes
+                    )
+                        .map(
+                            ([name, value]) =>
+                                `${name}="${escapeHtmlAttribute(
+                                    value
+                                )}"`
+                        )
+                        .join(" ");
+
+                return `    <${entry.tag} ${serialized} />`;
+            }
+        )
+        .join("\n");
+}
+
+function createFallbackMetadata(
+    title: string
+): ResolvedMetadata {
+    return {
+        title,
+        description: null,
+        robots:
+            "noindex, nofollow",
+        canonical: null,
+        openGraph: null,
+        icons: {
+            icon: null,
+            shortcut: null,
+            apple: null,
+        },
+    };
+}
+
+function createPublicServerError(
+    error: unknown
+): Error {
+    const digest =
+        createErrorDigest(
+            error
+        );
+
+    const publicError =
+        new Error(
+            "An unexpected server error occurred."
+        ) as Error & {
+            digest?: string;
+        };
+
+    publicError.name =
+        "BcpServerError";
+    publicError.digest =
+        digest;
+
+    return publicError;
+}
+
+function createErrorDigest(
+    error: unknown
+): string {
+    const source =
+        error instanceof Error
+            ? `${error.name}\n${error.message}\n${error.stack ?? ""}`
+            : String(error);
+
+    return createHash(
+        "sha256"
+    )
+        .update(
+            source
+        )
+        .digest(
+            "hex"
+        )
+        .slice(
+            0,
+            12
+        );
+}
+
+function getErrorDigest(
+    error: Error
+): string {
+    const value =
+        error as Error & {
+            digest?: string;
+        };
+
+    return value.digest ??
+        "unknown";
+}
+
+async function handleNavigation(
+    req: http.IncomingMessage,
+    res: http.ServerResponse,
+    requestUrl: URL,
+    routes: Route[],
+    routeByPathname: Map<
+        string,
+        StandalonePageRoute
+    >,
+    version: number
+): Promise<void> {
+    if (req.method !== "GET") {
+        sendJson(
+            req,
+            res,
+            405,
+            {
+                error:
+                    "Method Not Allowed",
+            }
+        );
+        return;
+    }
+
+    const targetPath =
+        requestUrl.searchParams.get(
+            "url"
+        );
+
+    if (!targetPath) {
+        sendJson(
+            req,
+            res,
+            400,
+            {
+                error:
+                    "Missing navigation target.",
+            }
+        );
+        return;
+    }
+
+    let target: URL;
+
+    try {
+        target =
+            new URL(
+                targetPath,
+                requestUrl.origin
+            );
+    } catch {
+        sendJson(
+            req,
+            res,
+            400,
+            {
+                error:
+                    "Invalid navigation target.",
+            }
+        );
+        return;
+    }
+
+    if (
+        target.origin !==
+        requestUrl.origin
+    ) {
+        sendJson(
+            req,
+            res,
+            400,
+            {
+                error:
+                    "Cross-origin navigation is not allowed.",
+            }
+        );
+        return;
+    }
+
+    const match =
+        matchRoute(
+            routes,
+            normalizePathname(
+                target.pathname
+            )
+        );
+
+    if (!match) {
+        sendJson(
+            req,
+            res,
+            404,
+            {
+                error:
+                    "Route not found.",
+            }
+        );
+        return;
+    }
+
+    const definition =
+        routeByPathname.get(
+            match.route.pathname
+        );
+
+    if (!definition) {
+        sendJson(
+            req,
+            res,
+            404,
+            {
+                error:
+                    "Route not found.",
+            }
+        );
+        return;
+    }
+
+    let metadata:
+        ResolvedMetadata;
+
+    try {
+        metadata =
+            await resolveRouteMetadata(
+                definition.metadataSources,
+                match.params
+            );
+    } catch (error) {
+        if (isNotFoundError(error)) {
+            sendJson(
+                req,
+                res,
+                404,
+                {
+                    error:
+                        "Route not found.",
+                }
+            );
+            return;
+        }
+
+        console.error(
+            `[BCP Metadata Error] ${definition.pathname}:`,
+            error
+        );
+
+        sendJson(
+            req,
+            res,
+            500,
+            {
+                error:
+                    "Internal Server Error",
+            }
+        );
+        return;
+    }
+
+    const loadingHtml =
+        definition.loading
+            ? renderToStaticMarkup(
+                createElement(
+                    definition.loading,
+                    {
+                        params:
+                            match.params,
+                    }
+                )
+            )
+            : null;
+
+    sendJson(
+        req,
+        res,
+        200,
+        {
+            route:
+                definition.pathname,
+            params:
+                match.params,
+            clientScript:
+                definition.client.entry,
+            clientImports:
+                definition.client.imports,
+            title:
+                metadata.title,
+            metadata,
+            version,
+            loadingHtml,
+        }
+    );
+}
+
+async function serveBuildAsset(
+    req: http.IncomingMessage,
+    res: http.ServerResponse,
+    clientDirectory: string,
+    pathname: string
+): Promise<boolean> {
+    const encodedRelative =
+        pathname.slice(
+            "/_bcp/client/".length
+        );
+
+    let relativePath: string;
+
+    try {
+        relativePath =
+            decodeURIComponent(
+                encodedRelative
+            );
+    } catch {
+        return false;
+    }
+
+    if (
+        !relativePath ||
+        relativePath.includes(
+            "\0"
+        )
+    ) {
+        return false;
+    }
+
+    const root =
+        path.resolve(
+            clientDirectory
+        );
+    const candidate =
+        path.resolve(
+            root,
+            relativePath.replaceAll(
+                "/",
+                path.sep
+            )
+        );
+
+    if (!isPathInside(root, candidate)) {
+        return false;
+    }
+
+    let stat:
+        Awaited<
+            ReturnType<typeof fs.stat>
+        >;
+
+    try {
+        stat =
+            await fs.stat(
+                candidate
+            );
+    } catch {
+        return false;
+    }
+
+    if (!stat.isFile()) {
+        return false;
+    }
+
+    const contentType =
+        getContentType(
+            candidate
+        );
+
+    const encoding =
+        selectContentEncoding(
+            req,
+            contentType,
+            stat.size,
+            {
+                br:
+                    await fileExists(
+                        `${candidate}.br`
+                    ),
+                gzip:
+                    await fileExists(
+                        `${candidate}.gz`
+                    ),
+            }
+        );
+
+    const sourceFile =
+        encoding === "br"
+            ? `${candidate}.br`
+            : encoding === "gzip"
+                ? `${candidate}.gz`
+                : candidate;
+
+    const content =
+        await fs.readFile(
+            sourceFile
+        );
+
+    const headers:
+        Record<string, string | number> = {
+        "Content-Type":
+            contentType,
+        "Cache-Control":
+            "public, max-age=31536000, immutable",
+        "X-Content-Type-Options":
+            "nosniff",
+        "Content-Length":
+            content.length,
+        Vary:
+            "Accept-Encoding",
+    };
+
+    if (encoding) {
+        headers[
+            "Content-Encoding"
+        ] =
+            encoding;
+    }
+
+    res.writeHead(
+        200,
+        headers
+    );
+
+    if (req.method === "HEAD") {
+        res.end();
+        return true;
+    }
+
+    res.end(
+        content
+    );
+    return true;
+}
+
+async function fileExists(
+    filePath: string
+): Promise<boolean> {
+    try {
+        const stat =
+            await fs.stat(
+                filePath
+            );
+        return stat.isFile();
+    } catch {
+        return false;
+    }
+}
+
+function sendPublicAsset(
+    req: http.IncomingMessage,
+    res: http.ServerResponse,
+    asset: StaticAsset
+): void {
+    const encoding =
+        selectContentEncoding(
+            req,
+            asset.contentType,
+            asset.content.length
+        );
+
+    const content =
+        compressDynamicContent(
+            asset.content,
+            encoding
+        );
+
+    const etag =
+        createVariantEtag(
+            asset.etag,
+            encoding
+        );
+
+    const ifNoneMatch =
+        req.headers[
+            "if-none-match"
+        ];
+
+    const values =
+        Array.isArray(
+            ifNoneMatch
+        )
+            ? ifNoneMatch
+            : ifNoneMatch
+                ? ifNoneMatch.split(",")
+                : [];
+
+    if (
+        values
+            .map(
+                (value) =>
+                    value.trim()
+            )
+            .includes(
+                etag
+            )
+    ) {
+        res.writeHead(
+            304,
+            {
+                ETag:
+                    etag,
+                "Cache-Control":
+                    "public, max-age=0, must-revalidate",
+                Vary:
+                    "Accept-Encoding",
+            }
+        );
+        res.end();
+        return;
+    }
+
+    const headers:
+        Record<string, string | number> = {
+        "Content-Type":
+            asset.contentType,
+        "Content-Length":
+            content.length,
+        ETag:
+            etag,
+        "Last-Modified":
+            asset.lastModified,
+        "Cache-Control":
+            "public, max-age=0, must-revalidate",
+        "X-Content-Type-Options":
+            "nosniff",
+    };
+
+    if (
+        isCompressibleContentType(
+            asset.contentType
+        )
+    ) {
+        headers.Vary =
+            "Accept-Encoding";
+    }
+
+    if (encoding) {
+        headers[
+            "Content-Encoding"
+        ] =
+            encoding;
+    }
+
+    res.writeHead(
+        200,
+        headers
+    );
+
+    if (req.method === "HEAD") {
+        res.end();
+        return;
+    }
+
+    res.end(
+        content
+    );
+}
+
+async function handleApiRoute(
+    req: http.IncomingMessage,
+    res: http.ServerResponse,
+    requestUrl: URL,
+    definition: StandaloneApiRoute,
+    params: Record<string, string>
+): Promise<void> {
+    const method =
+        normalizeHttpMethod(
+            req.method
+        );
+
+    const allowedMethods =
+        getAllowedMethods(
+            definition.handlers
+        );
+
+    if (
+        method === "OPTIONS" &&
+        !getApiHandler(
+            definition.handlers,
+            "OPTIONS"
+        )
+    ) {
+        res.writeHead(
+            204,
+            {
+                Allow:
+                    allowedMethods.join(
+                        ", "
+                    ),
+            }
+        );
+        res.end();
+        return;
+    }
+
+    let handler =
+        getApiHandler(
+            definition.handlers,
+            method
+        );
+
+    if (
+        !handler &&
+        method === "HEAD"
+    ) {
+        handler =
+            getApiHandler(
+                definition.handlers,
+                "GET"
+            );
+    }
+
+    if (!handler) {
+        sendJson(
+            req,
+            res,
+            405,
+            {
+                error:
+                    "Method Not Allowed",
+                allowedMethods,
+            },
+            {
+                Allow:
+                    allowedMethods.join(
+                        ", "
+                    ),
+            }
+        );
+        return;
+    }
+
+    const response =
+        await handler(
+            await createWebRequest(
+                req,
+                requestUrl
+            ),
+            {
+                params,
+            }
+        );
+
+    if (!(response instanceof Response)) {
+        throw new Error(
+            `API handler "${method} ${definition.pathname}" must return a Response object.`
+        );
+    }
+
+    await sendWebResponse(
+        req,
+        res,
+        response,
+        method === "HEAD"
+    );
+}
+
+function normalizeHttpMethod(
+    method: string | undefined
+): HttpMethod {
+    return (
+        (
+            method ??
+            "GET"
+        ).toUpperCase() as
+        HttpMethod
+    );
+}
+
+function getApiHandler(
+    module: Record<string, unknown>,
+    method: string
+): ApiHandler | undefined {
+    const value =
+        module[
+            method
+        ];
+
+    return typeof value ===
+        "function"
+        ? value as ApiHandler
+        : undefined;
+}
+
+function getAllowedMethods(
+    module: Record<string, unknown>
+): string[] {
+    const allowed:
+        string[] = [];
+
+    for (const method of HTTP_METHODS) {
+        if (method === "OPTIONS") {
+            continue;
+        }
+
+        if (method === "HEAD") {
+            if (
+                getApiHandler(
+                    module,
+                    "HEAD"
+                ) ||
+                getApiHandler(
+                    module,
+                    "GET"
+                )
+            ) {
+                allowed.push(
+                    "HEAD"
+                );
+            }
+            continue;
+        }
+
+        if (
+            getApiHandler(
+                module,
+                method
+            )
+        ) {
+            allowed.push(
+                method
+            );
+        }
+    }
+
+    allowed.push(
+        "OPTIONS"
+    );
+    return allowed;
+}
+
+async function createWebRequest(
+    req: http.IncomingMessage,
+    url: URL
+): Promise<Request> {
+    const headers =
+        new Headers();
+
+    for (
+        const [key, value]
+        of Object.entries(
+            req.headers
+        )
+    ) {
+        if (value === undefined) {
+            continue;
+        }
+
+        if (Array.isArray(value)) {
+            for (const item of value) {
+                headers.append(
+                    key,
+                    item
+                );
+            }
+        } else {
+            headers.set(
+                key,
+                value
+            );
+        }
+    }
+
+    const method =
+        (
+            req.method ??
+            "GET"
+        ).toUpperCase();
+
+    const init:
+        RequestInit = {
+        method,
+        headers,
+    };
+
+    if (
+        method !== "GET" &&
+        method !== "HEAD"
+    ) {
+        const body =
+            await readRequestBody(
+                req
+            );
+
+        if (body.length > 0) {
+            init.body =
+                body as unknown as
+                BodyInit;
+        }
+    }
+
+    return new Request(
+        url,
+        init
+    );
+}
+
+async function readRequestBody(
+    req: http.IncomingMessage
+): Promise<Buffer> {
+    const chunks:
+        Buffer[] = [];
+
+    for await (const chunk of req) {
+        chunks.push(
+            Buffer.isBuffer(
+                chunk
+            )
+                ? chunk
+                : Buffer.from(
+                    chunk
+                )
+        );
+    }
+
+    return Buffer.concat(
+        chunks
+    );
+}
+
+async function sendWebResponse(
+    req: http.IncomingMessage,
+    res: http.ServerResponse,
+    response: Response,
+    isHead: boolean
+): Promise<void> {
+    res.statusCode =
+        response.status;
+
+    response.headers.forEach(
+        (
+            value,
+            key
+        ) => {
+            const normalized =
+                key.toLowerCase();
+
+            if (
+                normalized ===
+                    "set-cookie" ||
+                normalized ===
+                    "content-length"
+            ) {
+                return;
+            }
+
+            res.setHeader(
+                key,
+                value
+            );
+        }
+    );
+
+    const responseHeaders =
+        response.headers as
+        Headers & {
+            getSetCookie?: () =>
+                string[];
+        };
+
+    const cookies =
+        responseHeaders
+            .getSetCookie?.();
+
+    if (
+        cookies &&
+        cookies.length > 0
+    ) {
+        res.setHeader(
+            "Set-Cookie",
+            cookies
+        );
+    }
+
+    if (
+        response.status === 204 ||
+        response.status === 304
+    ) {
+        res.end();
+        return;
+    }
+
+    const rawBody =
+        Buffer.from(
+            await response.arrayBuffer()
+        );
+
+    const contentType =
+        response.headers.get(
+            "content-type"
+        ) ??
+        "application/octet-stream";
+
+    const existingEncoding =
+        response.headers.get(
+            "content-encoding"
+        );
+
+    const encoding =
+        existingEncoding
+            ? null
+            : selectContentEncoding(
+                req,
+                contentType,
+                rawBody.length
+            );
+
+    const body =
+        existingEncoding
+            ? rawBody
+            : compressDynamicContent(
+                rawBody,
+                encoding
+            );
+
+    if (encoding) {
+        res.setHeader(
+            "Content-Encoding",
+            encoding
+        );
+        res.setHeader(
+            "Vary",
+            appendVary(
+                res.getHeader(
+                    "Vary"
+                )?.toString(),
+                "Accept-Encoding"
+            )
+        );
+    }
+
+    res.setHeader(
+        "Content-Length",
+        body.length
+    );
+
+    if (isHead) {
+        res.end();
+        return;
+    }
+
+    res.end(
+        body
+    );
+}
+
+function sendJson(
+    req: http.IncomingMessage,
+    res: http.ServerResponse,
+    statusCode: number,
+    value: unknown,
+    extraHeaders: Record<string, string> = {}
+): void {
+    sendCompressedBody(
+        req,
+        res,
+        statusCode,
+        "application/json; charset=utf-8",
+        Buffer.from(
+            JSON.stringify(
+                value
+            )
+        ),
+        {
+            "Cache-Control":
+                "no-store",
+            "X-Content-Type-Options":
+                "nosniff",
+            ...extraHeaders,
+        }
+    );
+}
+
+function sendHtml(
+    req: http.IncomingMessage,
+    res: http.ServerResponse,
+    statusCode: number,
+    html: string
+): void {
+    sendCompressedBody(
+        req,
+        res,
+        statusCode,
+        "text/html; charset=utf-8",
+        Buffer.from(
+            html
+        ),
+        {
+            "Cache-Control":
+                "no-store",
+        }
+    );
+}
+
+function sendCompressedBody(
+    req: http.IncomingMessage,
+    res: http.ServerResponse,
+    statusCode: number,
+    contentType: string,
+    rawBody: Buffer,
+    extraHeaders: Record<string, string> = {}
+): void {
+    const encoding =
+        selectContentEncoding(
+            req,
+            contentType,
+            rawBody.length
+        );
+
+    const body =
+        compressDynamicContent(
+            rawBody,
+            encoding
+        );
+
+    const headers:
+        Record<string, string | number> = {
+        "Content-Type":
+            contentType,
+        "Content-Length":
+            body.length,
+        ...extraHeaders,
+    };
+
+    if (
+        isCompressibleContentType(
+            contentType
+        )
+    ) {
+        headers.Vary =
+            appendVary(
+                typeof headers.Vary ===
+                    "string"
+                    ? headers.Vary
+                    : undefined,
+                "Accept-Encoding"
+            );
+    }
+
+    if (encoding) {
+        headers[
+            "Content-Encoding"
+        ] =
+            encoding;
+    }
+
+    res.writeHead(
+        statusCode,
+        headers
+    );
+
+    if (req.method === "HEAD") {
+        res.end();
+        return;
+    }
+
+    res.end(
+        body
+    );
+}
+
+function sendSimpleNotFound(
+    req: http.IncomingMessage,
+    res: http.ServerResponse
+): void {
+    sendHtml(
+        req,
+        res,
+        404,
+        genericNotFoundDocument()
+    );
+}
+
+function sendInternalServerError(
+    req: http.IncomingMessage,
+    res: http.ServerResponse,
+    error: unknown
+): void {
+    sendHtml(
+        req,
+        res,
+        500,
+        genericErrorDocument(
+            createErrorDigest(
+                error
+            )
+        )
+    );
+}
+
+function genericNotFoundDocument(): string {
+    return renderDocument({
+        content:
+            "<main><h1>404</h1><p>Page Not Found</p></main>",
+        route: null,
+        params: null,
+        client: null,
+        metadata:
+            createFallbackMetadata(
+                "Page Not Found"
+            ),
+    });
+}
+
+function genericErrorDocument(
+    digest: string
+): string {
+    return renderDocument({
+        content:
+            `<main><h1>500</h1><p>Internal Server Error</p><p>Error ID: ${escapeHtml(
+                digest
+            )}</p></main>`,
+        route: null,
+        params: null,
+        client: null,
+        metadata:
+            createFallbackMetadata(
+                "Internal Server Error"
+            ),
+    });
+}
+
+function createVariantEtag(
+    etag: string,
+    encoding: "br" | "gzip" | null
+): string {
+    if (!encoding) {
+        return etag;
+    }
+
+    const value =
+        etag.replace(
+            /^W\//,
+            ""
+        );
+
+    const unquoted =
+        value.startsWith('"') &&
+        value.endsWith('"')
+            ? value.slice(
+                1,
+                -1
+            )
+            : value;
+
+    return `"${unquoted}-${encoding}"`;
+}
+
+function serializeFrameworkData(
+    value: unknown
+): string {
+    return JSON.stringify(
+        value
+    )
+        .replace(
+            /</g,
+            "\\u003c"
+        )
+        .replace(
+            /\u2028/g,
+            "\\u2028"
+        )
+        .replace(
+            /\u2029/g,
+            "\\u2029"
+        );
+}
+
+function normalizePathname(
+    pathname: string
+): string {
+    if (
+        pathname.length > 1 &&
+        pathname.endsWith(
+            "/"
+        )
+    ) {
+        return pathname.slice(
+            0,
+            -1
+        );
+    }
+
+    return pathname || "/";
+}
+
+function isPathInside(
+    root: string,
+    candidate: string
+): boolean {
+    const relative =
+        path.relative(
+            root,
+            candidate
+        );
+
+    return (
+        relative === "" ||
+        (
+            relative !== ".." &&
+            !relative.startsWith(
+                `..${path.sep}`
+            ) &&
+            !path.isAbsolute(
+                relative
+            )
+        )
+    );
+}
+
+function escapeHtml(
+    value: string
+): string {
+    return value
+        .replaceAll(
+            "&",
+            "&amp;"
+        )
+        .replaceAll(
+            "<",
+            "&lt;"
+        )
+        .replaceAll(
+            ">",
+            "&gt;"
+        )
+        .replaceAll(
+            '"',
+            "&quot;"
+        )
+        .replaceAll(
+            "'",
+            "&#039;"
+        );
+}
+
+function escapeHtmlAttribute(
+    value: string
+): string {
+    return escapeHtml(
+        value
+    );
+}