@chidchanun/bcp 0.1.0

package/packages/server/src/index.ts

@@ -0,0 +1,2265 @@
+import * as http from "node:http";
+
+import path from "node:path";
+
+import {
+    pathToFileURL,
+} from "node:url";
+
+import chokidar from "chokidar";
+
+import {
+    createElement,
+    type ComponentType,
+    type ReactElement,
+} from "react";
+
+import {
+    renderToString,
+} from "react-dom/server";
+
+import {
+    assertNoPageApiConflicts,
+    matchApiRoute,
+    matchRoute,
+    scanApiRoutes,
+    scanRoutes,
+    type ApiRoute,
+    type Route,
+} from "../../router/src/index.js";
+
+import {
+    buildDevAssets,
+    DEV_RUNTIME_PATH,
+    DevClientBundler,
+    type ClientBundle,
+    type DevAsset,
+} from "../../bundler/src/index.js";
+
+import {
+    DEV_EVENTS_PATH,
+    DevHmrServer,
+} from "./dev-hmr.js";
+
+/*
+ * =====================================
+ * Constants
+ * =====================================
+ */
+
+const REBUILD_DEBOUNCE_MS =
+    100;
+
+/*
+ * =====================================
+ * Types
+ * =====================================
+ */
+
+export interface DevServerOptions {
+    port?: number;
+
+    hostname?: string;
+
+    rootDirectory?: string;
+}
+
+interface FrameworkData {
+    route: string;
+
+    params: Record<
+        string,
+        string
+    >;
+}
+
+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];
+
+type FileEvent =
+    | "add"
+    | "change"
+    | "unlink";
+
+/*
+ * =====================================
+ * Server
+ * =====================================
+ */
+
+export function createDevServer(
+    options: DevServerOptions = {}
+) {
+    const port =
+        options.port ?? 3000;
+
+    const hostname =
+        options.hostname ??
+        "localhost";
+
+    const rootDirectory =
+        options.rootDirectory ??
+        process.cwd();
+
+    const appDirectory =
+        path.join(
+            rootDirectory,
+            "app"
+        );
+
+    /*
+     * =====================================
+     * Framework State
+     * =====================================
+     */
+
+    let routes:
+        Route[] = [];
+
+    let apiRoutes:
+        ApiRoute[] = [];
+
+    let clientBundles:
+        ClientBundle[] = [];
+
+    let devAssets:
+        DevAsset[] = [];
+
+    let clientBundler:
+        DevClientBundler | null =
+        null;
+
+    /*
+     * Server module cache version
+     */
+    let moduleVersion =
+        0;
+
+    /*
+     * Browser bundle version
+     */
+    let clientVersion =
+        0;
+
+    const hmr =
+        new DevHmrServer();
+
+    /*
+     * =====================================
+     * Watcher State
+     * =====================================
+     */
+
+    let watcher:
+        ReturnType<
+            typeof chokidar.watch
+        > | null = null;
+
+    let rebuildTimer:
+        NodeJS.Timeout | null =
+        null;
+
+    let rebuildRunning =
+        false;
+
+    let rebuildQueued =
+        false;
+
+    /*
+     * Step 8/9 เก็บ change ล่าสุดแค่ 1 file
+     *
+     * Step 10:
+     * เก็บทุกไฟล์ที่เปลี่ยนใน debounce window
+     */
+    const pendingChanges =
+        new Map<
+            string,
+            FileEvent
+        >();
+
+    /*
+     * =====================================
+     * Routes
+     * =====================================
+     */
+
+    function scanAllRoutes() {
+        const nextRoutes =
+            scanRoutes(
+                appDirectory
+            );
+
+        const nextApiRoutes =
+            scanApiRoutes(
+                appDirectory
+            );
+
+        assertNoPageApiConflicts(
+            nextRoutes,
+            nextApiRoutes
+        );
+
+        return {
+            routes:
+                nextRoutes,
+
+            apiRoutes:
+                nextApiRoutes,
+        };
+    }
+
+    function loadInitialRoutes() {
+        const result =
+            scanAllRoutes();
+
+        routes =
+            result.routes;
+
+        apiRoutes =
+            result.apiRoutes;
+
+        printRoutes();
+    }
+
+    function printRoutes() {
+        console.log("");
+        console.log(
+            "Page Routes:"
+        );
+
+        if (
+            routes.length === 0
+        ) {
+            console.log(
+                "  (none)"
+            );
+        }
+
+        for (
+            const route
+            of routes
+        ) {
+            console.log(
+                `  ${route.pathname}`
+            );
+
+            console.log(
+                `    Page: ${route.filePath}`
+            );
+
+            for (
+                const layout
+                of route.layouts
+            ) {
+                console.log(
+                    `    Layout: ${layout}`
+                );
+            }
+        }
+
+        console.log("");
+        console.log(
+            "API Routes:"
+        );
+
+        if (
+            apiRoutes.length === 0
+        ) {
+            console.log(
+                "  (none)"
+            );
+        }
+
+        for (
+            const route
+            of apiRoutes
+        ) {
+            console.log(
+                `  ${route.pathname}`
+            );
+
+            console.log(
+                `    Handler: ${route.filePath}`
+            );
+        }
+    }
+
+    loadInitialRoutes();
+
+    /*
+     * =====================================
+     * HTTP
+     * =====================================
+     */
+
+    const server =
+        http.createServer(
+            async (
+                req,
+                res
+            ) => {
+                const startedAt =
+                    performance.now();
+
+                let pathname =
+                    "/";
+
+                try {
+                    const host =
+                        req.headers.host ??
+                        `${hostname}:${port}`;
+
+                    const requestUrl =
+                        new URL(
+                            req.url ?? "/",
+                            `http://${host}`
+                        );
+
+                    pathname =
+                        normalizePathname(
+                            requestUrl.pathname
+                        );
+
+                    /*
+                     * =================================
+                     * HMR Event Stream
+                     * =================================
+                     */
+
+                    if (
+                        pathname ===
+                        DEV_EVENTS_PATH
+                    ) {
+                        hmr.connect(
+                            req,
+                            res
+                        );
+
+                        return;
+                    }
+
+                    /*
+                     * =================================
+                     * HTTP Log
+                     * =================================
+                     */
+
+                    res.once(
+                        "finish",
+                        () => {
+                            const duration =
+                                performance.now() -
+                                startedAt;
+
+                            console.log(
+                                `${req.method ?? "GET"} ${pathname} ${res.statusCode} ${duration.toFixed(2)}ms`
+                            );
+                        }
+                    );
+
+                    /*
+                     * =================================
+                     * Dev Assets
+                     * =================================
+                     */
+
+                    const devAsset =
+                        devAssets.find(
+                            (asset) =>
+                                asset.publicPath ===
+                                pathname
+                        );
+
+                    if (
+                        devAsset
+                    ) {
+                        sendDevAsset(
+                            res,
+                            devAsset
+                        );
+
+                        return;
+                    }
+
+                    /*
+                     * =================================
+                     * Client Bundles
+                     * =================================
+                     */
+
+                    const requestedBundle =
+                        clientBundles.find(
+                            (bundle) =>
+                                bundle.publicPath ===
+                                pathname
+                        );
+
+                    if (
+                        requestedBundle
+                    ) {
+                        sendJavaScript(
+                            res,
+                            requestedBundle
+                                .content
+                        );
+
+                        return;
+                    }
+
+                    /*
+                     * =================================
+                     * API
+                     * =================================
+                     */
+
+                    const apiMatch =
+                        matchApiRoute(
+                            apiRoutes,
+                            pathname
+                        );
+
+                    if (
+                        apiMatch
+                    ) {
+                        await handleApiRoute(
+                            req,
+                            res,
+                            requestUrl,
+                            apiMatch.route,
+                            apiMatch.params,
+                            moduleVersion
+                        );
+
+                        return;
+                    }
+
+                    /*
+                     * =================================
+                     * Page
+                     * =================================
+                     */
+
+                    const match =
+                        matchRoute(
+                            routes,
+                            pathname
+                        );
+
+                    if (
+                        !match
+                    ) {
+                        sendNotFound(
+                            res
+                        );
+
+                        return;
+                    }
+
+                    const {
+                        route,
+                        params,
+                    } = match;
+
+                    const pageClientBundle =
+                        clientBundles.find(
+                            (bundle) =>
+                                bundle.pathname ===
+                                route.pathname
+                        );
+
+                    if (
+                        !pageClientBundle
+                    ) {
+                        throw new Error(
+                            `Client bundle was not found for route "${route.pathname}".`
+                        );
+                    }
+
+                    /*
+                     * =================================
+                     * Server Components Import
+                     * =================================
+                     */
+
+                    const importStartedAt =
+                        performance.now();
+
+                    const Page =
+                        await importComponent(
+                            route.filePath,
+                            "Page",
+                            moduleVersion
+                        );
+
+                    const Layouts:
+                        ComponentType<any>[] =
+                        [];
+
+                    for (
+                        const layoutFile
+                        of route.layouts
+                    ) {
+                        const Layout =
+                            await importComponent(
+                                layoutFile,
+                                "Layout",
+                                moduleVersion
+                            );
+
+                        Layouts.push(
+                            Layout
+                        );
+                    }
+
+                    console.log(
+                        `Import: ${(performance.now() - importStartedAt).toFixed(2)}ms`
+                    );
+
+                    /*
+                     * =================================
+                     * React Tree
+                     * =================================
+                     */
+
+                    const renderStartedAt =
+                        performance.now();
+
+                    let element:
+                        ReactElement =
+                        createElement(
+                            Page,
+                            {
+                                params,
+                            }
+                        );
+
+                    for (
+                        let index =
+                            Layouts.length -
+                            1;
+
+                        index >= 0;
+
+                        index--
+                    ) {
+                        const Layout =
+                            Layouts[index];
+
+                        element =
+                            createElement(
+                                Layout,
+                                {
+                                    params,
+                                },
+                                element
+                            );
+                    }
+
+                    const content =
+                        renderToString(
+                            element
+                        );
+
+                    console.log(
+                        `SSR: ${(performance.now() - renderStartedAt).toFixed(2)}ms`
+                    );
+
+                    /*
+                     * =================================
+                     * Framework Data
+                     * =================================
+                     */
+
+                    const frameworkData:
+                        FrameworkData = {
+                        route:
+                            route.pathname,
+
+                        params,
+                    };
+
+                    const html =
+                        renderDocument(
+                            content,
+
+                            pageClientBundle
+                                .publicPath,
+
+                            frameworkData,
+
+                            clientVersion
+                        );
+
+                    sendHtml(
+                        res,
+                        html
+                    );
+                } catch (error) {
+                    console.error("");
+                    console.error(
+                        "BCP Framework Error:"
+                    );
+
+                    console.error(
+                        error
+                    );
+
+                    if (
+                        res.headersSent
+                    ) {
+                        res.end();
+                        return;
+                    }
+
+                    sendInternalServerError(
+                        res,
+                        error
+                    );
+                }
+            }
+        );
+
+    /*
+     * =====================================
+     * Watcher
+     * =====================================
+     */
+
+    function startWatcher() {
+        console.log("");
+        console.log(
+            "Starting file watcher..."
+        );
+
+        watcher =
+            chokidar.watch(
+                rootDirectory,
+                {
+                    persistent:
+                        true,
+
+                    ignoreInitial:
+                        true,
+
+                    atomic:
+                        true,
+
+                    ignored: (
+                        watchedPath,
+                        stats
+                    ) => {
+                        const relative =
+                            path.relative(
+                                rootDirectory,
+                                watchedPath
+                            );
+
+                        const normalized =
+                            relative.replace(
+                                /\\/g,
+                                "/"
+                            );
+
+                        if (
+                            normalized ===
+                            "node_modules" ||
+                            normalized.startsWith(
+                                "node_modules/"
+                            ) ||
+                            normalized ===
+                            ".bcp-framework" ||
+                            normalized.startsWith(
+                                ".bcp-framework/"
+                            ) ||
+                            normalized ===
+                            "dist" ||
+                            normalized.startsWith(
+                                "dist/"
+                            )
+                        ) {
+                            return true;
+                        }
+
+                        if (
+                            stats?.isDirectory()
+                        ) {
+                            return false;
+                        }
+
+                        if (
+                            !stats
+                        ) {
+                            return false;
+                        }
+
+                        return !/\.[jt]sx?$/.test(
+                            watchedPath
+                        );
+                    },
+                }
+            );
+
+        watcher.on(
+            "add",
+            (filePath) => {
+                scheduleRebuild(
+                    "add",
+                    filePath
+                );
+            }
+        );
+
+        watcher.on(
+            "change",
+            (filePath) => {
+                scheduleRebuild(
+                    "change",
+                    filePath
+                );
+            }
+        );
+
+        watcher.on(
+            "unlink",
+            (filePath) => {
+                scheduleRebuild(
+                    "unlink",
+                    filePath
+                );
+            }
+        );
+
+        watcher.on(
+            "error",
+            (error) => {
+                console.error(
+                    "[dev] Watcher error:",
+                    error
+                );
+            }
+        );
+
+        watcher.on(
+            "ready",
+            () => {
+                console.log(
+                    "File watcher ready."
+                );
+
+                console.log("");
+            }
+        );
+    }
+
+    /*
+     * =====================================
+     * Schedule
+     * =====================================
+     */
+
+    function scheduleRebuild(
+        event: FileEvent,
+        filePath: string
+    ) {
+        const existing =
+            pendingChanges.get(
+                filePath
+            );
+
+        /*
+         * add/unlink สำคัญกว่า change
+         *
+         * อย่าให้ change ที่ตามหลัง
+         * overwrite structural event
+         */
+        if (
+            existing !==
+            "add" &&
+            existing !==
+            "unlink"
+        ) {
+            pendingChanges.set(
+                filePath,
+                event
+            );
+        }
+
+        if (
+            rebuildRunning
+        ) {
+            rebuildQueued =
+                true;
+
+            return;
+        }
+
+        if (
+            rebuildTimer
+        ) {
+            clearTimeout(
+                rebuildTimer
+            );
+        }
+
+        rebuildTimer =
+            setTimeout(
+                () => {
+                    rebuildTimer =
+                        null;
+
+                    void rebuildDevServer();
+                },
+                REBUILD_DEBOUNCE_MS
+            );
+    }
+
+    /*
+     * =====================================
+     * Development Rebuild
+     * =====================================
+     */
+
+    async function rebuildDevServer() {
+        if (
+            rebuildRunning
+        ) {
+            rebuildQueued =
+                true;
+
+            return;
+        }
+
+        rebuildRunning =
+            true;
+
+        /*
+         * Snapshot pending changes
+         */
+        const changes =
+            Array.from(
+                pendingChanges.entries()
+            ).map(
+                (
+                    [
+                        filePath,
+                        event,
+                    ]
+                ) => ({
+                    filePath,
+                    event,
+                })
+            );
+
+        pendingChanges.clear();
+
+        const startedAt =
+            performance.now();
+
+        try {
+            console.log("");
+
+            for (
+                const change
+                of changes
+            ) {
+                console.log(
+                    `[dev] ${change.event} ${path.relative(
+                        rootDirectory,
+                        change.filePath
+                    )}`
+                );
+            }
+
+            /*
+             * Routes scan ใหม่
+             *
+             * ทำเพื่อ detect conflict
+             * และ route additions/deletions
+             */
+            const nextRouteState =
+                scanAllRoutes();
+
+            const hasStructuralChange =
+                changes.some(
+                    (change) =>
+                        change.event ===
+                        "add" ||
+                        change.event ===
+                        "unlink"
+                );
+
+            /*
+             * =================================
+             * Structural Change
+             * =================================
+             *
+             * add/delete:
+             *
+             * page.tsx
+             * layout.tsx
+             * route.ts
+             *
+             * route graph อาจเปลี่ยน
+             *
+             * สร้าง bundler ชุดใหม่
+             */
+            if (
+                hasStructuralChange
+            ) {
+                console.log(
+                    "[dev] route structure changed"
+                );
+
+                const nextBundler =
+                    await DevClientBundler
+                        .create(
+                            nextRouteState
+                                .routes,
+
+                            rootDirectory,
+
+                            {
+                                fastRefresh:
+                                    true,
+                            }
+                        );
+
+                const oldBundler =
+                    clientBundler;
+
+                /*
+                 * Build ผ่านแล้ว
+                 * ค่อย swap
+                 */
+                routes =
+                    nextRouteState.routes;
+
+                apiRoutes =
+                    nextRouteState.apiRoutes;
+
+                clientBundler =
+                    nextBundler;
+
+                clientBundles =
+                    nextBundler
+                        .getBundles();
+
+                moduleVersion++;
+
+                clientVersion++;
+
+                /*
+                 * Dispose old contexts
+                 */
+                if (
+                    oldBundler
+                ) {
+                    await oldBundler
+                        .dispose();
+                }
+
+                const duration =
+                    performance.now() -
+                    startedAt;
+
+                console.log(
+                    `[dev] full client rebuild in ${duration.toFixed(2)}ms`
+                );
+
+                hmr.reload(
+                    clientVersion
+                );
+
+                return;
+            }
+
+            /*
+             * =================================
+             * Normal File Changes
+             * =================================
+             */
+
+            routes =
+                nextRouteState.routes;
+
+            apiRoutes =
+                nextRouteState.apiRoutes;
+
+            /*
+             * Server-side direct modules
+             */
+            moduleVersion++;
+
+            if (
+                !clientBundler
+            ) {
+                throw new Error(
+                    "BCP Framework: client bundler is not initialized."
+                );
+            }
+
+            const changedFiles =
+                changes.map(
+                    (change) =>
+                        change.filePath
+                );
+
+            /*
+             * Debug dependency graph
+             */
+            for (
+                const filePath
+                of changedFiles
+            ) {
+                clientBundler
+                    .printAffectedRoutes(
+                        filePath
+                    );
+            }
+
+            /*
+             * =================================
+             * Incremental Rebuild
+             * =================================
+             */
+
+            const affectedRoutes =
+                await clientBundler
+                    .rebuildAffected(
+                        changedFiles
+                    );
+
+            /*
+             * ไม่มี client route ใช้ไฟล์นี้
+             *
+             * เช่น:
+             *
+             * app/api/users/route.ts
+             */
+            if (
+                affectedRoutes.length ===
+                0
+            ) {
+                const duration =
+                    performance.now() -
+                    startedAt;
+
+                console.log(
+                    `[dev] server-only update in ${duration.toFixed(2)}ms`
+                );
+
+                return;
+            }
+
+            /*
+             * Update RAM bundle references
+             */
+            clientBundles =
+                clientBundler
+                    .getBundles();
+
+            clientVersion++;
+
+            const duration =
+                performance.now() -
+                    startedAt;
+
+            console.log(
+                `[dev] rebuilt ${affectedRoutes.length}/${routes.length} client route(s) in ${duration.toFixed(2)}ms`
+            );
+
+            console.log(
+                `[dev] affected: ${affectedRoutes.join(", ")}`
+            );
+
+            /*
+             * Fast Refresh เฉพาะ
+             * affected routes
+             */
+            hmr.refresh(
+                clientVersion,
+                affectedRoutes
+            );
+        } catch (error) {
+            console.error("");
+            console.error(
+                "[dev] rebuild failed:"
+            );
+
+            console.error(
+                error
+            );
+
+            console.error("");
+        } finally {
+            rebuildRunning =
+                false;
+
+            /*
+             * มี save เกิดขึ้น
+             * ระหว่าง rebuild
+             */
+            if (
+                rebuildQueued ||
+                pendingChanges.size >
+                0
+            ) {
+                rebuildQueued =
+                    false;
+
+                if (
+                    rebuildTimer
+                ) {
+                    clearTimeout(
+                        rebuildTimer
+                    );
+                }
+
+                rebuildTimer =
+                    setTimeout(
+                        () => {
+                            rebuildTimer =
+                                null;
+
+                            void rebuildDevServer();
+                        },
+                        REBUILD_DEBOUNCE_MS
+                    );
+            }
+        }
+    }
+
+    /*
+     * =====================================
+     * Public Server API
+     * =====================================
+     */
+
+    return {
+        async start() {
+            console.log("");
+
+            /*
+             * =================================
+             * Dev Runtime
+             * =================================
+             */
+
+            console.log(
+                "Building React dev runtime..."
+            );
+
+            devAssets =
+                await buildDevAssets(
+                    rootDirectory
+                );
+
+            /*
+             * =================================
+             * Incremental Client Bundler
+             * =================================
+             */
+
+            console.log(
+                "Creating incremental client bundler..."
+            );
+
+            clientBundler =
+                await DevClientBundler
+                    .create(
+                        routes,
+
+                        rootDirectory,
+
+                        {
+                            fastRefresh:
+                                true,
+                        }
+                    );
+
+            clientBundles =
+                clientBundler
+                    .getBundles();
+
+            for (
+                const bundle
+                of clientBundles
+            ) {
+                console.log(
+                    `  ${bundle.pathname} -> ${bundle.publicPath}`
+                );
+            }
+
+            /*
+             * =================================
+             * HTTP
+             * =================================
+             */
+
+            await new Promise<void>(
+                (
+                    resolve,
+                    reject
+                ) => {
+                    server.once(
+                        "error",
+                        reject
+                    );
+
+                    server.listen(
+                        port,
+                        hostname,
+                        () => {
+                            server.off(
+                                "error",
+                                reject
+                            );
+
+                            console.log("");
+                            console.log(
+                                "BCP Framework"
+                            );
+
+                            console.log(
+                                `Local: http://${hostname}:${port}`
+                            );
+
+                            console.log("");
+
+                            resolve();
+                        }
+                    );
+                }
+            );
+
+            startWatcher();
+        },
+
+        /*
+         * =================================
+         * Stop
+         * =================================
+         */
+
+        async stop() {
+            if (
+                rebuildTimer
+            ) {
+                clearTimeout(
+                    rebuildTimer
+                );
+
+                rebuildTimer =
+                    null;
+            }
+
+            if (
+                watcher
+            ) {
+                await watcher.close();
+
+                watcher =
+                    null;
+            }
+
+            hmr.close();
+
+            /*
+             * esbuild contexts
+             */
+            if (
+                clientBundler
+            ) {
+                await clientBundler
+                    .dispose();
+
+                clientBundler =
+                    null;
+            }
+
+            if (
+                !server.listening
+            ) {
+                return;
+            }
+
+            await new Promise<void>(
+                (
+                    resolve,
+                    reject
+                ) => {
+                    server.close(
+                        (error) => {
+                            if (
+                                error
+                            ) {
+                                reject(
+                                    error
+                                );
+
+                                return;
+                            }
+
+                            resolve();
+                        }
+                    );
+                }
+            );
+        },
+    };
+}
+
+/*
+ * =====================================
+ * API Route
+ * =====================================
+ */
+
+async function handleApiRoute(
+    req: http.IncomingMessage,
+
+    res: http.ServerResponse,
+
+    requestUrl: URL,
+
+    route: ApiRoute,
+
+    params: Record<
+        string,
+        string
+    >,
+
+    moduleVersion: number
+) {
+    const moduleUrl =
+        createVersionedModuleUrl(
+            route.filePath,
+            moduleVersion
+        );
+
+    const apiModule =
+        await import(
+            moduleUrl
+        );
+
+    const method =
+        normalizeHttpMethod(
+            req.method
+        );
+
+    const allowedMethods =
+        getAllowedMethods(
+            apiModule
+        );
+
+    /*
+     * Automatic OPTIONS
+     */
+    if (
+        method ===
+        "OPTIONS" &&
+        !getApiHandler(
+            apiModule,
+            "OPTIONS"
+        )
+    ) {
+        res.writeHead(
+            204,
+            {
+                Allow:
+                    allowedMethods.join(
+                        ", "
+                    ),
+            }
+        );
+
+        res.end();
+
+        return;
+    }
+
+    let handler =
+        getApiHandler(
+            apiModule,
+            method
+        );
+
+    /*
+     * HEAD -> GET
+     */
+    if (
+        !handler &&
+        method ===
+        "HEAD"
+    ) {
+        handler =
+            getApiHandler(
+                apiModule,
+                "GET"
+            );
+    }
+
+    if (
+        !handler
+    ) {
+        sendMethodNotAllowed(
+            res,
+            allowedMethods
+        );
+
+        return;
+    }
+
+    const request =
+        await createWebRequest(
+            req,
+            requestUrl
+        );
+
+    const response =
+        await handler(
+            request,
+            {
+                params,
+            }
+        );
+
+    if (
+        !(
+            response instanceof
+            Response
+        )
+    ) {
+        throw new Error(
+            `API handler "${method} ${route.pathname}" must return a Response object.`
+        );
+    }
+
+    await sendWebResponse(
+        res,
+        response,
+        method === "HEAD"
+    );
+}
+
+/*
+ * =====================================
+ * API Helpers
+ * =====================================
+ */
+
+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
+        ];
+
+    if (
+        typeof value !==
+        "function"
+    ) {
+        return undefined;
+    }
+
+    return (
+        value as ApiHandler
+    );
+}
+
+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;
+}
+
+/*
+ * =====================================
+ * Node Request → Web Request
+ * =====================================
+ */
+
+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
+                );
+            }
+
+            continue;
+        }
+
+        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
+    );
+}
+
+/*
+ * =====================================
+ * Web Response → Node Response
+ * =====================================
+ */
+
+async function sendWebResponse(
+    res: http.ServerResponse,
+
+    response: Response,
+
+    isHead: boolean
+) {
+    res.statusCode =
+        response.status;
+
+    response.headers.forEach(
+        (
+            value,
+            key
+        ) => {
+            if (
+                key.toLowerCase() ===
+                "set-cookie"
+            ) {
+                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 arrayBuffer =
+        await response
+            .arrayBuffer();
+
+    const body =
+        Buffer.from(
+            arrayBuffer
+        );
+
+    if (
+        !res.hasHeader(
+            "Content-Length"
+        )
+    ) {
+        res.setHeader(
+            "Content-Length",
+            body.length
+        );
+    }
+
+    if (
+        isHead
+    ) {
+        res.end();
+
+        return;
+    }
+
+    res.end(
+        body
+    );
+}
+
+/*
+ * =====================================
+ * React Server Import
+ * =====================================
+ */
+
+async function importComponent(
+    filePath: string,
+
+    componentType: string,
+
+    moduleVersion: number
+): Promise<
+    ComponentType<any>
+> {
+    const moduleUrl =
+        createVersionedModuleUrl(
+            filePath,
+            moduleVersion
+        );
+
+    const module =
+        await import(
+            moduleUrl
+        );
+
+    const Component =
+        module.default;
+
+    if (
+        typeof Component !==
+        "function"
+    ) {
+        throw new Error(
+            `${componentType} "${filePath}" does not export a default React component.`
+        );
+    }
+
+    return Component;
+}
+
+/*
+ * =====================================
+ * Server Cache Busting
+ * =====================================
+ */
+
+function createVersionedModuleUrl(
+    filePath: string,
+    version: number
+): string {
+    const url =
+        pathToFileURL(
+            filePath
+        );
+
+    url.searchParams.set(
+        "bcpv",
+        String(
+            version
+        )
+    );
+
+    return url.href;
+}
+
+/*
+ * =====================================
+ * URL
+ * =====================================
+ */
+
+function normalizePathname(
+    pathname: string
+): string {
+    if (
+        pathname.length >
+        1 &&
+        pathname.endsWith(
+            "/"
+        )
+    ) {
+        return pathname.slice(
+            0,
+            -1
+        );
+    }
+
+    return pathname;
+}
+
+/*
+ * =====================================
+ * HTML
+ * =====================================
+ */
+
+function renderDocument(
+    content: string,
+
+    clientScript: string,
+
+    frameworkData:
+        FrameworkData,
+
+    clientVersion: number
+): string {
+    const serializedData =
+        serializeFrameworkData(
+            frameworkData
+        );
+
+    const devConfig =
+        JSON.stringify({
+            eventsPath:
+                DEV_EVENTS_PATH,
+
+            clientScript,
+
+            /*
+             * Route pattern
+             *
+             * เช่น:
+             *
+             * /users/[id]
+             */
+            route:
+                frameworkData.route,
+
+            version:
+                clientVersion,
+        })
+            .replace(
+                /</g,
+                "\\u003c"
+            );
+
+    const runtimeUrl =
+        `${DEV_RUNTIME_PATH}?v=${clientVersion}`;
+
+    const clientUrl =
+        `${clientScript}?v=${clientVersion}`;
+
+    return `
+<!DOCTYPE html>
+
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+
+    <meta
+      name="viewport"
+      content="width=device-width, initial-scale=1.0"
+    />
+
+    <title>
+      BCP Framework
+    </title>
+  </head>
+
+  <body>
+    <div id="root">${content}</div>
+
+    <script
+      id="__BCP_DATA__"
+      type="application/json"
+    >${serializedData}</script>
+
+    <script>
+      globalThis.__BCP_DEV_CONFIG__ =
+        ${devConfig};
+    </script>
+
+    <script
+      type="module"
+      data-bcp-bootstrap
+    >
+      const runtimeUrl =
+        ${JSON.stringify(runtimeUrl)};
+
+      const clientUrl =
+        ${JSON.stringify(clientUrl)};
+
+      const bootstrap =
+        async () => {
+          try {
+            /*
+             * Keep React Refresh ordering intact while
+             * removing the external classic script from
+             * the parser's critical rendering path.
+             */
+            await import(
+              runtimeUrl
+            );
+
+            await import(
+              clientUrl
+            );
+          } catch (error) {
+            console.error(
+              "[BCP] Client bootstrap failed:",
+              error
+            );
+          }
+        };
+
+      requestAnimationFrame(
+        () => {
+          void bootstrap();
+        }
+      );
+    </script>
+  </body>
+</html>
+  `.trim();
+}
+
+function serializeFrameworkData(
+    data:
+        FrameworkData
+): string {
+    return JSON.stringify(
+        data
+    )
+        .replace(
+            /</g,
+            "\\u003c"
+        )
+        .replace(
+            /\u2028/g,
+            "\\u2028"
+        )
+        .replace(
+            /\u2029/g,
+            "\\u2029"
+        );
+}
+
+/*
+ * =====================================
+ * Responses
+ * =====================================
+ */
+
+function sendHtml(
+    res:
+        http.ServerResponse,
+
+    html: string
+) {
+    res.writeHead(
+        200,
+        {
+            "Content-Type":
+                "text/html; charset=utf-8",
+
+            "Cache-Control":
+                "no-store",
+        }
+    );
+
+    res.end(
+        html
+    );
+}
+
+function sendJavaScript(
+    res:
+        http.ServerResponse,
+
+    content: Buffer
+) {
+    res.writeHead(
+        200,
+        {
+            "Content-Type":
+                "text/javascript; charset=utf-8",
+
+            "Cache-Control":
+                "no-store",
+
+            "Content-Length":
+                content.length,
+        }
+    );
+
+    res.end(
+        content
+    );
+}
+
+function sendDevAsset(
+    res:
+        http.ServerResponse,
+
+    asset:
+        DevAsset
+) {
+    res.writeHead(
+        200,
+        {
+            "Content-Type":
+                asset.contentType,
+
+            "Cache-Control":
+                "no-store",
+
+            "Content-Length":
+                asset.content
+                    .length,
+        }
+    );
+
+    res.end(
+        asset.content
+    );
+}
+
+function sendMethodNotAllowed(
+    res:
+        http.ServerResponse,
+
+    methods:
+        string[]
+) {
+    const body =
+        JSON.stringify({
+            error:
+                "Method Not Allowed",
+
+            allowedMethods:
+                methods,
+        });
+
+    res.writeHead(
+        405,
+        {
+            "Content-Type":
+                "application/json; charset=utf-8",
+
+            Allow:
+                methods.join(
+                    ", "
+                ),
+
+            "Content-Length":
+                Buffer.byteLength(
+                    body
+                ),
+        }
+    );
+
+    res.end(
+        body
+    );
+}
+
+function sendNotFound(
+    res:
+        http.ServerResponse
+) {
+    const html = `
+<!DOCTYPE html>
+
+<html lang="en">
+  <body>
+    <h1>
+      404
+    </h1>
+
+    <p>
+      Page Not Found
+    </p>
+  </body>
+</html>
+  `.trim();
+
+    res.writeHead(
+        404,
+        {
+            "Content-Type":
+                "text/html; charset=utf-8",
+
+            "Cache-Control":
+                "no-store",
+        }
+    );
+
+    res.end(
+        html
+    );
+}
+
+function sendInternalServerError(
+    res:
+        http.ServerResponse,
+
+    error:
+        unknown
+) {
+    const message =
+        error instanceof
+            Error
+            ? error.message
+            : "Unknown error";
+
+    const html = `
+<!DOCTYPE html>
+
+<html lang="en">
+  <body>
+    <h1>
+      500
+    </h1>
+
+    <p>
+      Internal Server Error
+    </p>
+
+    <pre>${escapeHtml(message)}</pre>
+  </body>
+</html>
+  `.trim();
+
+    res.writeHead(
+        500,
+        {
+            "Content-Type":
+                "text/html; charset=utf-8",
+
+            "Cache-Control":
+                "no-store",
+        }
+    );
+
+    res.end(
+        html
+    );
+}
+
+/*
+ * =====================================
+ * Security
+ * =====================================
+ */
+
+function escapeHtml(
+    value:
+        string
+): string {
+    return value
+        .replaceAll(
+            "&",
+            "&amp;"
+        )
+        .replaceAll(
+            "<",
+            "&lt;"
+        )
+        .replaceAll(
+            ">",
+            "&gt;"
+        )
+        .replaceAll(
+            '"',
+            "&quot;"
+        )
+        .replaceAll(
+            "'",
+            "&#039;"
+        );
+}