@chidchanun/bcp 0.1.27 → 0.1.28

package/docs/releases/0.1.28.md

@@ -0,0 +1,134 @@
+# BCP Framework 0.1.28
+
+BCP Framework `0.1.28` is the **Production Hardening** milestone.
+
+> Release state: unreleased development target until local validation, RC checks, tagging and npm publication complete.
+
+## Highlights
+
+- Added a public production hardening gateway around the existing standalone runtime.
+- Added configurable request, header, keep-alive and shutdown timeouts.
+- Added graceful `SIGTERM` / `SIGINT` handling for Docker and process managers.
+- Added application shutdown hooks through `registerShutdownHook()`.
+- Added trusted-proxy forwarding-header sanitization with secure default `BCP_TRUST_PROXY=false`.
+- Added force-close fallback after the configured graceful shutdown timeout.
+- Fixed `create-bcp-app --storage local` so generated projects no longer contain an unexplained empty storage directory.
+- Added `storage/README.md` and `storage/.gitkeep` while continuing to ignore runtime storage objects.
+- Added regression coverage for production hardening primitives and Local Server scaffolding.
+
+## Production environment controls
+
+```dotenv
+BCP_REQUEST_TIMEOUT_MS=120000
+BCP_HEADERS_TIMEOUT_MS=66000
+BCP_KEEP_ALIVE_TIMEOUT_MS=65000
+BCP_SHUTDOWN_TIMEOUT_MS=10000
+BCP_TRUST_PROXY=false
+```
+
+Defaults are production-safe and require no configuration for ordinary direct HTTP deployments.
+
+`BCP_HEADERS_TIMEOUT_MS` must be greater than `BCP_KEEP_ALIVE_TIMEOUT_MS`.
+
+## Graceful shutdown
+
+The standalone production runtime now handles:
+
+```text
+SIGTERM
+SIGINT
+```
+
+The runtime first stops/drains the public hardening gateway, then runs application shutdown hooks, then stops internal BCP runtime layers.
+
+After `BCP_SHUTDOWN_TIMEOUT_MS`, remaining public connections are force-closed.
+
+## Public API addition
+
+```ts
+import {
+    getProductionHardeningConfig,
+    registerShutdownHook,
+} from "bcp/server";
+```
+
+Example:
+
+```ts
+registerShutdownHook(
+    () => {
+        storage.destroy();
+    },
+    {
+        name: "storage",
+    }
+);
+```
+
+Hooks run in reverse registration order and can be unregistered with the cleanup function returned by `registerShutdownHook()`.
+
+## Trusted proxy behavior
+
+Trusted proxy mode is disabled by default.
+
+When disabled, BCP strips spoofable incoming forwarding headers at the public hardening gateway and writes forwarding information from the actual connection.
+
+When the application is intentionally deployed behind a trusted reverse proxy/load balancer, enable:
+
+```dotenv
+BCP_TRUST_PROXY=true
+```
+
+Only enable it when direct untrusted traffic cannot bypass the trusted proxy.
+
+## Local Server storage fix
+
+Before `0.1.28`, selecting Local Server generated `lib/storage.ts` and configured `./storage`, but the runtime directory had no explanatory scaffold before the first upload.
+
+`0.1.28` generates:
+
+```text
+storage/
+├─ .gitkeep
+└─ README.md
+```
+
+and uses Git ignore rules:
+
+```gitignore
+storage/*
+!storage/.gitkeep
+!storage/README.md
+```
+
+Runtime uploads and `.bcp-storage-meta` remain untracked while the directory structure is visible in a fresh project.
+
+## Testing
+
+`0.1.28` adds coverage for:
+
+- production timeout parsing,
+- invalid timeout relationships,
+- applying Node HTTP server timeout settings,
+- graceful HTTP server close,
+- shutdown hook ordering/unregistration,
+- generated Local Server storage directory scaffold,
+- generated Local Server Git ignore behavior.
+
+## Remaining release work
+
+Before publication:
+
+1. sync `package-lock.json` to `0.1.28`,
+2. run `npm run typecheck`,
+3. run unit/integration/E2E/package tests,
+4. run `npm run rc:check`,
+5. build a representative BCP application,
+6. run the standalone artifact in Docker,
+7. verify `docker stop` produces graceful shutdown logs,
+8. create the `v0.1.28` tag only after the final release commit is known,
+9. publish and verify npm visibility.
+
+## Next milestone
+
+The planned next milestone is `0.1.29 — Developer Experience`, focused on generators, richer `doctor` / `inspect`, improved diagnostics and create-app workflow improvements.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chidchanun/bcp",
-  "version": "0.1.27",
+  "version": "0.1.28",
   "description": "BCP Framework - a React full-stack framework with file-based routing, SSR, APIs, middleware, islands, caching and standalone production builds.",
   "type": "module",
   "license": "MIT",

package/packages/client/src/server.ts

@@ -30,6 +30,15 @@ export {
     type LoggerOptions,
 } from "../../server/src/logger.js";
 
+export {
+    getProductionHardeningConfig,
+    registerShutdownHook,
+
+    type ProductionHardeningConfig,
+    type ShutdownHook,
+    type ShutdownHookOptions,
+} from "../../server/src/production-hardening.js";
+
 export {
     getUploadedFile,
     parseMultipartFormData,

package/packages/server/src/hardening-proxy.ts

@@ -0,0 +1,393 @@
+import * as http from "node:http";
+
+import {
+    applyProductionHttpServerHardening,
+    closeHttpServerGracefully,
+    getProductionHardeningConfig,
+    type ProductionHardeningConfig,
+} from "./production-hardening.js";
+
+export interface HardeningProxyOptions {
+    port: number;
+    hostname: string;
+    upstreamPort: number;
+    upstreamHostname?: string;
+}
+
+export function createHardeningProxy(
+    options: HardeningProxyOptions
+) {
+    const upstreamHostname =
+        options.upstreamHostname ??
+        "127.0.0.1";
+    const config =
+        getProductionHardeningConfig();
+    let server:
+        http.Server | null =
+        null;
+
+    async function start(): Promise<void> {
+        if (server) {
+            return;
+        }
+
+        server =
+            http.createServer(
+                (
+                    req,
+                    res
+                ) => {
+                    proxyRequest(
+                        req,
+                        res,
+                        upstreamHostname,
+                        options.upstreamPort,
+                        config
+                    );
+                }
+            );
+
+        applyProductionHttpServerHardening(
+            server,
+            config
+        );
+
+        await listen(
+            server,
+            options.port,
+            options.hostname
+        );
+    }
+
+    async function stop(): Promise<void> {
+        if (!server) {
+            return;
+        }
+
+        const current =
+            server;
+        server =
+            null;
+
+        await closeHttpServerGracefully(
+            current,
+            {
+                timeoutMs:
+                    config.shutdownTimeoutMs,
+            }
+        );
+    }
+
+    return {
+        start,
+        stop,
+        config,
+    };
+}
+
+function proxyRequest(
+    req: http.IncomingMessage,
+    res: http.ServerResponse,
+    upstreamHostname: string,
+    upstreamPort: number,
+    config: ProductionHardeningConfig
+): void {
+    const headers =
+        createForwardedHeaders(
+            req,
+            config.trustProxy
+        );
+    const upstream =
+        http.request({
+            hostname:
+                upstreamHostname,
+            port:
+                upstreamPort,
+            method:
+                req.method ??
+                "GET",
+            path:
+                req.url ??
+                "/",
+            headers,
+            timeout:
+                config.requestTimeoutMs,
+        });
+
+    upstream.on(
+        "timeout",
+        () => {
+            upstream.destroy(
+                new Error(
+                    "BCP Framework: upstream request timed out."
+                )
+            );
+        }
+    );
+
+    upstream.on(
+        "response",
+        (upstreamResponse) => {
+            for (
+                const [
+                    name,
+                    value,
+                ]
+                of Object.entries(
+                    upstreamResponse.headers
+                )
+            ) {
+                if (
+                    value !== undefined
+                ) {
+                    res.setHeader(
+                        name,
+                        value
+                    );
+                }
+            }
+
+            res.statusCode =
+                upstreamResponse.statusCode ??
+                502;
+
+            if (
+                upstreamResponse.statusMessage
+            ) {
+                res.statusMessage =
+                    upstreamResponse.statusMessage;
+            }
+
+            upstreamResponse.pipe(
+                res
+            );
+        }
+    );
+
+    upstream.on(
+        "error",
+        (error) => {
+            if (
+                res.headersSent
+            ) {
+                res.destroy(
+                    error
+                );
+                return;
+            }
+
+            res.writeHead(
+                502,
+                {
+                    "Content-Type":
+                        "text/plain; charset=utf-8",
+                    "Cache-Control":
+                        "no-store",
+                }
+            );
+            res.end(
+                "Bad Gateway"
+            );
+        }
+    );
+
+    req.on(
+        "aborted",
+        () => {
+            upstream.destroy();
+        }
+    );
+    req.on(
+        "error",
+        (error) => {
+            upstream.destroy(
+                error
+            );
+        }
+    );
+
+    req.pipe(
+        upstream
+    );
+}
+
+function createForwardedHeaders(
+    req: http.IncomingMessage,
+    trustProxy: boolean
+): http.OutgoingHttpHeaders {
+    const headers:
+        http.OutgoingHttpHeaders = {
+        ...req.headers,
+    };
+    const remoteAddress =
+        normalizeRemoteAddress(
+            req.socket.remoteAddress
+        );
+    const host =
+        firstHeader(
+            req.headers.host
+        );
+
+    if (!trustProxy) {
+        delete headers.forwarded;
+        delete headers[
+            "x-forwarded-for"
+        ];
+        delete headers[
+            "x-forwarded-host"
+        ];
+        delete headers[
+            "x-forwarded-proto"
+        ];
+        delete headers[
+            "x-real-ip"
+        ];
+    }
+
+    if (remoteAddress) {
+        const existingForwardedFor =
+            trustProxy
+                ? firstHeader(
+                    req.headers[
+                        "x-forwarded-for"
+                    ]
+                )
+                : undefined;
+
+        headers[
+            "x-forwarded-for"
+        ] =
+            existingForwardedFor
+                ? `${existingForwardedFor}, ${remoteAddress}`
+                : remoteAddress;
+        headers[
+            "x-real-ip"
+        ] =
+            trustProxy &&
+            firstHeader(
+                req.headers[
+                    "x-real-ip"
+                ]
+            )
+                ? firstHeader(
+                    req.headers[
+                        "x-real-ip"
+                    ]
+                )
+                : remoteAddress;
+    }
+
+    if (host) {
+        headers[
+            "x-forwarded-host"
+        ] =
+            trustProxy &&
+            firstHeader(
+                req.headers[
+                    "x-forwarded-host"
+                ]
+            )
+                ? firstHeader(
+                    req.headers[
+                        "x-forwarded-host"
+                    ]
+                )
+                : host;
+    }
+
+    headers[
+        "x-forwarded-proto"
+    ] =
+        trustProxy &&
+        firstHeader(
+            req.headers[
+                "x-forwarded-proto"
+            ]
+        )
+            ? firstHeader(
+                req.headers[
+                    "x-forwarded-proto"
+                ]
+            )
+            : "http";
+
+    return headers;
+}
+
+function normalizeRemoteAddress(
+    value: string | undefined
+): string | undefined {
+    if (!value) {
+        return undefined;
+    }
+
+    return value.startsWith(
+        "::ffff:"
+    )
+        ? value.slice(
+            "::ffff:".length
+        )
+        : value;
+}
+
+function firstHeader(
+    value:
+        string |
+        string[] |
+        undefined
+): string | undefined {
+    if (
+        Array.isArray(
+            value
+        )
+    ) {
+        return value[0];
+    }
+
+    return value;
+}
+
+function listen(
+    server: http.Server,
+    port: number,
+    hostname: string
+): Promise<void> {
+    return new Promise(
+        (
+            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
+            );
+        }
+    );
+}