@chidchanun/bcp 0.1.26 → 0.1.28

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

@@ -0,0 +1,374 @@
+import type * as http from "node:http";
+
+export interface ProductionHardeningConfig {
+    requestTimeoutMs: number;
+    headersTimeoutMs: number;
+    keepAliveTimeoutMs: number;
+    shutdownTimeoutMs: number;
+    trustProxy: boolean;
+}
+
+export interface GracefulCloseOptions {
+    timeoutMs?: number;
+}
+
+export interface ShutdownHookOptions {
+    name?: string;
+}
+
+export type ShutdownHook =
+    () => void | Promise<void>;
+
+interface RegisteredShutdownHook {
+    id: number;
+    name: string;
+    hook: ShutdownHook;
+}
+
+const DEFAULT_REQUEST_TIMEOUT_MS =
+    120_000;
+const DEFAULT_HEADERS_TIMEOUT_MS =
+    66_000;
+const DEFAULT_KEEP_ALIVE_TIMEOUT_MS =
+    65_000;
+const DEFAULT_SHUTDOWN_TIMEOUT_MS =
+    10_000;
+
+let nextShutdownHookId =
+    1;
+const shutdownHooks =
+    new Map<
+        number,
+        RegisteredShutdownHook
+    >();
+
+export function getProductionHardeningConfig(
+    environment: NodeJS.ProcessEnv = process.env
+): ProductionHardeningConfig {
+    const keepAliveTimeoutMs =
+        parsePositiveInteger(
+            environment.BCP_KEEP_ALIVE_TIMEOUT_MS,
+            "BCP_KEEP_ALIVE_TIMEOUT_MS"
+        ) ??
+        DEFAULT_KEEP_ALIVE_TIMEOUT_MS;
+    const headersTimeoutMs =
+        parsePositiveInteger(
+            environment.BCP_HEADERS_TIMEOUT_MS,
+            "BCP_HEADERS_TIMEOUT_MS"
+        ) ??
+        DEFAULT_HEADERS_TIMEOUT_MS;
+
+    if (
+        headersTimeoutMs <=
+        keepAliveTimeoutMs
+    ) {
+        throw new Error(
+            "BCP Framework: BCP_HEADERS_TIMEOUT_MS must be greater than BCP_KEEP_ALIVE_TIMEOUT_MS."
+        );
+    }
+
+    return {
+        requestTimeoutMs:
+            parsePositiveInteger(
+                environment.BCP_REQUEST_TIMEOUT_MS,
+                "BCP_REQUEST_TIMEOUT_MS"
+            ) ??
+            DEFAULT_REQUEST_TIMEOUT_MS,
+        headersTimeoutMs,
+        keepAliveTimeoutMs,
+        shutdownTimeoutMs:
+            parsePositiveInteger(
+                environment.BCP_SHUTDOWN_TIMEOUT_MS,
+                "BCP_SHUTDOWN_TIMEOUT_MS"
+            ) ??
+            DEFAULT_SHUTDOWN_TIMEOUT_MS,
+        trustProxy:
+            parseBoolean(
+                environment.BCP_TRUST_PROXY,
+                "BCP_TRUST_PROXY"
+            ) ??
+            false,
+    };
+}
+
+export function applyProductionHttpServerHardening(
+    server: http.Server,
+    config:
+        ProductionHardeningConfig =
+            getProductionHardeningConfig()
+): void {
+    server.requestTimeout =
+        config.requestTimeoutMs;
+    server.headersTimeout =
+        config.headersTimeoutMs;
+    server.keepAliveTimeout =
+        config.keepAliveTimeoutMs;
+}
+
+export async function closeHttpServerGracefully(
+    server: http.Server,
+    options: GracefulCloseOptions = {}
+): Promise<void> {
+    if (!server.listening) {
+        return;
+    }
+
+    const timeoutMs =
+        options.timeoutMs ??
+        getProductionHardeningConfig()
+            .shutdownTimeoutMs;
+
+    if (
+        !Number.isSafeInteger(
+            timeoutMs
+        ) ||
+        timeoutMs <= 0
+    ) {
+        throw new TypeError(
+            "BCP Framework: graceful shutdown timeout must be a positive safe integer."
+        );
+    }
+
+    await new Promise<void>(
+        (
+            resolve,
+            reject
+        ) => {
+            let settled =
+                false;
+            let timer:
+                NodeJS.Timeout | null =
+                null;
+            const settle =
+                (
+                    error?: Error
+                ) => {
+                    if (settled) {
+                        return;
+                    }
+
+                    settled =
+                        true;
+
+                    if (timer) {
+                        clearTimeout(
+                            timer
+                        );
+                        timer =
+                            null;
+                    }
+
+                    if (error) {
+                        reject(
+                            error
+                        );
+                        return;
+                    }
+
+                    resolve();
+                };
+
+            timer =
+                setTimeout(
+                    () => {
+                        try {
+                            server.closeAllConnections?.();
+                        } catch {
+                            // The close callback remains authoritative.
+                        }
+                    },
+                    timeoutMs
+                );
+
+            timer.unref?.();
+
+            try {
+                server.closeIdleConnections?.();
+                server.close(
+                    (error) => {
+                        settle(
+                            error ??
+                            undefined
+                        );
+                    }
+                );
+            } catch (error) {
+                settle(
+                    error instanceof Error
+                        ? error
+                        : new Error(
+                            String(error)
+                        )
+                );
+            }
+        }
+    );
+}
+
+export function registerShutdownHook(
+    hook: ShutdownHook,
+    options: ShutdownHookOptions = {}
+): () => void {
+    if (
+        typeof hook !==
+        "function"
+    ) {
+        throw new TypeError(
+            "BCP Framework: shutdown hook must be a function."
+        );
+    }
+
+    const id =
+        nextShutdownHookId++;
+    const name =
+        normalizeHookName(
+            options.name,
+            id
+        );
+
+    shutdownHooks.set(
+        id,
+        {
+            id,
+            name,
+            hook,
+        }
+    );
+
+    return () => {
+        shutdownHooks.delete(
+            id
+        );
+    };
+}
+
+export async function runShutdownHooks(): Promise<void> {
+    const registered =
+        Array.from(
+            shutdownHooks.values()
+        ).reverse();
+    const failures:
+        Error[] = [];
+
+    shutdownHooks.clear();
+
+    for (const item of registered) {
+        try {
+            await item.hook();
+        } catch (error) {
+            failures.push(
+                new Error(
+                    `BCP Framework: shutdown hook "${item.name}" failed. ${error instanceof Error ? error.message : String(error)}`
+                )
+            );
+        }
+    }
+
+    if (
+        failures.length > 0
+    ) {
+        throw new AggregateError(
+            failures,
+            "BCP Framework: one or more shutdown hooks failed."
+        );
+    }
+}
+
+export function isTrustedProxyEnabled(
+    environment: NodeJS.ProcessEnv = process.env
+): boolean {
+    return getProductionHardeningConfig(
+        environment
+    ).trustProxy;
+}
+
+function normalizeHookName(
+    value: string | undefined,
+    id: number
+): string {
+    const normalized =
+        value?.trim();
+
+    if (!normalized) {
+        return `hook-${id}`;
+    }
+
+    if (
+        normalized.length > 128 ||
+        /[\r\n]/.test(
+            normalized
+        )
+    ) {
+        throw new TypeError(
+            "BCP Framework: shutdown hook name must be at most 128 characters without line breaks."
+        );
+    }
+
+    return normalized;
+}
+
+function parsePositiveInteger(
+    value: string | undefined,
+    name: string
+): number | undefined {
+    if (value === undefined) {
+        return undefined;
+    }
+
+    const normalized =
+        value.trim();
+    const parsed =
+        Number(
+            normalized
+        );
+
+    if (
+        normalized.length === 0 ||
+        !Number.isSafeInteger(
+            parsed
+        ) ||
+        parsed <= 0
+    ) {
+        throw new Error(
+            `BCP Framework: ${name} must be a positive safe integer.`
+        );
+    }
+
+    return parsed;
+}
+
+function parseBoolean(
+    value: string | undefined,
+    name: string
+): boolean | undefined {
+    if (value === undefined) {
+        return undefined;
+    }
+
+    const normalized =
+        value
+            .trim()
+            .toLowerCase();
+
+    if (
+        normalized === "1" ||
+        normalized === "true" ||
+        normalized === "yes" ||
+        normalized === "on"
+    ) {
+        return true;
+    }
+
+    if (
+        normalized === "0" ||
+        normalized === "false" ||
+        normalized === "no" ||
+        normalized === "off"
+    ) {
+        return false;
+    }
+
+    throw new Error(
+        `BCP Framework: ${name} must be one of 1, 0, true, false, yes, no, on or off.`
+    );
+}

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

@@ -0,0 +1,299 @@
+import * as net from "node:net";
+
+import {
+    createHardeningProxy,
+} from "./hardening-proxy.js";
+import {
+    getProductionHardeningConfig,
+    runShutdownHooks,
+} from "./production-hardening.js";
+import {
+    createStandaloneProductionServer as createBaseStandaloneProductionServer,
+    type StandaloneApiRoute,
+    type StandalonePageRoute,
+    type StandaloneProductionServerOptions as BaseStandaloneProductionServerOptions,
+} from "./standalone-production-runtime-v6.js";
+
+export type {
+    StandaloneApiRoute,
+    StandalonePageRoute,
+};
+
+export interface StandaloneProductionServerOptions
+extends BaseStandaloneProductionServerOptions {}
+
+export function createStandaloneProductionServer(
+    options: StandaloneProductionServerOptions
+) {
+    let baseServer:
+        ReturnType<
+            typeof createBaseStandaloneProductionServer
+        > | null =
+        null;
+    let hardeningProxy:
+        ReturnType<
+            typeof createHardeningProxy
+        > | null =
+        null;
+    let started =
+        false;
+    let stopping =
+        false;
+
+    const handleSigterm =
+        () => {
+            void shutdownFromSignal(
+                "SIGTERM"
+            );
+        };
+    const handleSigint =
+        () => {
+            void shutdownFromSignal(
+                "SIGINT"
+            );
+        };
+
+    async function start(): Promise<void> {
+        if (started) {
+            return;
+        }
+
+        const config =
+            getProductionHardeningConfig();
+        const internalPort =
+            await findFreePort();
+
+        baseServer =
+            createBaseStandaloneProductionServer({
+                ...options,
+                port:
+                    internalPort,
+                hostname:
+                    "127.0.0.1",
+            });
+
+        await baseServer.start();
+
+        try {
+            hardeningProxy =
+                createHardeningProxy({
+                    port:
+                        options.port,
+                    hostname:
+                        options.hostname,
+                    upstreamPort:
+                        internalPort,
+                    upstreamHostname:
+                        "127.0.0.1",
+                });
+            await hardeningProxy.start();
+        } catch (error) {
+            await baseServer.stop();
+            baseServer =
+                null;
+            hardeningProxy =
+                null;
+            throw error;
+        }
+
+        process.once(
+            "SIGTERM",
+            handleSigterm
+        );
+        process.once(
+            "SIGINT",
+            handleSigint
+        );
+
+        started =
+            true;
+
+        console.log(
+            `[BCP Runtime] Hardening gateway: http://${options.hostname}:${options.port}`
+        );
+        console.log(
+            `[BCP Runtime] Request timeout: ${config.requestTimeoutMs}ms | Shutdown timeout: ${config.shutdownTimeoutMs}ms | Trust proxy: ${config.trustProxy ? "on" : "off"}`
+        );
+        console.log("");
+    }
+
+    async function stop(): Promise<void> {
+        if (stopping) {
+            return;
+        }
+
+        stopping =
+            true;
+
+        process.off(
+            "SIGTERM",
+            handleSigterm
+        );
+        process.off(
+            "SIGINT",
+            handleSigint
+        );
+
+        const failures:
+            unknown[] = [];
+
+        try {
+            if (hardeningProxy) {
+                await hardeningProxy.stop();
+                hardeningProxy =
+                    null;
+            }
+        } catch (error) {
+            failures.push(
+                error
+            );
+        }
+
+        try {
+            await runShutdownHooks();
+        } catch (error) {
+            failures.push(
+                error
+            );
+        }
+
+        try {
+            if (baseServer) {
+                await baseServer.stop();
+                baseServer =
+                    null;
+            }
+        } catch (error) {
+            failures.push(
+                error
+            );
+        }
+
+        started =
+            false;
+        stopping =
+            false;
+
+        if (
+            failures.length > 0
+        ) {
+            throw new AggregateError(
+                failures,
+                "BCP Framework: production shutdown completed with errors."
+            );
+        }
+    }
+
+    async function shutdownFromSignal(
+        signal: NodeJS.Signals
+    ): Promise<void> {
+        if (stopping) {
+            return;
+        }
+
+        console.log(
+            `[BCP Runtime] ${signal} received. Starting graceful shutdown...`
+        );
+
+        try {
+            await stop();
+            console.log(
+                "[BCP Runtime] Graceful shutdown complete."
+            );
+        } catch (error) {
+            process.exitCode =
+                1;
+            console.error(
+                "[BCP Runtime] Graceful shutdown failed:",
+                error
+            );
+        }
+    }
+
+    return {
+        start,
+        stop,
+    };
+}
+
+async function findFreePort(): Promise<number> {
+    const server =
+        net.createServer();
+
+    try {
+        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(
+                    0,
+                    "127.0.0.1"
+                );
+            }
+        );
+
+        const address =
+            server.address();
+
+        if (
+            !address ||
+            typeof address ===
+                "string"
+        ) {
+            throw new Error(
+                "BCP Framework: could not allocate production hardening port."
+            );
+        }
+
+        return address.port;
+    } finally {
+        if (server.listening) {
+            await new Promise<void>(
+                (
+                    resolve,
+                    reject
+                ) => {
+                    server.close(
+                        (error) => {
+                            if (error) {
+                                reject(
+                                    error
+                                );
+                                return;
+                            }
+                            resolve();
+                        }
+                    );
+                }
+            );
+        }
+    }
+}

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

@@ -3,4 +3,4 @@ export {
     type StandaloneApiRoute,
     type StandalonePageRoute,
     type StandaloneProductionServerOptions,
-} from "./standalone-production-runtime-v6.js";
+} from "./standalone-production-runtime-v7.js";