@chidchanun/bcp 0.1.0

package/packages/config/src/index.ts

@@ -0,0 +1,1038 @@
+import fs from "node:fs";
+import path from "node:path";
+import {
+    pathToFileURL,
+} from "node:url";
+
+export interface BcpServerConfig {
+    port?: number;
+    hostname?: string;
+    bodyLimit?: number;
+}
+
+export interface BcpBuildConfig {
+    minify?: boolean;
+    sourceMaps?: boolean;
+}
+
+export interface BcpCacheConfig {
+    response?: boolean;
+}
+
+export interface BcpExperimentalConfig {
+    partialHydration?: boolean;
+    islands?: boolean;
+}
+
+export interface BcpSecurityConfig {
+    poweredByHeader?: boolean;
+    contentSecurityPolicy?: string | false;
+    frameOptions?: "DENY" | "SAMEORIGIN" | false;
+    referrerPolicy?: string;
+    permissionsPolicy?: string | false;
+}
+
+export interface BcpConfig {
+    server?: BcpServerConfig;
+    compression?: boolean;
+    build?: BcpBuildConfig;
+    cache?: BcpCacheConfig;
+    experimental?: BcpExperimentalConfig;
+    security?: BcpSecurityConfig;
+}
+
+export interface ResolvedBcpConfig {
+    server: {
+        port: number;
+        hostname: string;
+        bodyLimit: number;
+    };
+    compression: boolean;
+    build: {
+        minify: boolean;
+        sourceMaps: boolean;
+    };
+    cache: {
+        response: boolean;
+    };
+    experimental: {
+        partialHydration: boolean;
+        islands: boolean;
+    };
+    security: {
+        poweredByHeader: boolean;
+        contentSecurityPolicy: string | false;
+        frameOptions: "DENY" | "SAMEORIGIN" | false;
+        referrerPolicy: string;
+        permissionsPolicy: string | false;
+    };
+}
+
+export interface ResolveBcpConfigOverrides {
+    port?: number;
+    hostname?: string;
+}
+
+export interface LoadedBcpConfig {
+    file: string | null;
+    config: BcpConfig;
+}
+
+const CONFIG_FILES = [
+    "bcp.config.ts",
+    "bcp.config.mts",
+    "bcp.config.js",
+    "bcp.config.mjs",
+] as const;
+
+export const defaultBcpConfig: ResolvedBcpConfig = {
+    server: {
+        port: 3000,
+        hostname: "localhost",
+        bodyLimit:
+            1024 * 1024,
+    },
+    compression: true,
+    build: {
+        minify: true,
+        sourceMaps: false,
+    },
+    cache: {
+        response: true,
+    },
+    experimental: {
+        partialHydration: true,
+        islands: true,
+    },
+    security: {
+        poweredByHeader: false,
+        contentSecurityPolicy: false,
+        frameOptions:
+            "SAMEORIGIN",
+        referrerPolicy:
+            "strict-origin-when-cross-origin",
+        permissionsPolicy:
+            "camera=(), microphone=(), geolocation=()",
+    },
+};
+
+export function defineConfig<
+    T extends BcpConfig
+>(
+    config: T
+): T {
+    return config;
+}
+
+export function getConfigFileNames(): string[] {
+    return [
+        ...CONFIG_FILES,
+    ];
+}
+
+export async function loadBcpConfig(
+    rootDirectory: string
+): Promise<LoadedBcpConfig> {
+    const matches =
+        CONFIG_FILES
+            .map(
+                (fileName) =>
+                    path.join(
+                        rootDirectory,
+                        fileName
+                    )
+            )
+            .filter(
+                (filePath) =>
+                    fs.existsSync(
+                        filePath
+                    )
+            );
+
+    if (
+        matches.length > 1
+    ) {
+        throw new Error(
+            `BCP Framework: multiple config files found: ${matches.map((file) => path.basename(file)).join(", ")}. Keep only one bcp.config file.`
+        );
+    }
+
+    if (
+        matches.length === 0
+    ) {
+        return {
+            file: null,
+            config: {},
+        };
+    }
+
+    const file =
+        matches[0];
+    const url =
+        pathToFileURL(
+            file
+        );
+
+    url.searchParams.set(
+        "bcp-config",
+        `${Date.now()}-${Math.random()}`
+    );
+
+    const module =
+        await import(
+            url.href
+        );
+
+    const config =
+        module.default;
+
+    if (
+        config === undefined
+    ) {
+        throw new Error(
+            `BCP Framework: ${path.basename(file)} must export a default config object.`
+        );
+    }
+
+    assertConfig(
+        config,
+        path.basename(file)
+    );
+
+    return {
+        file,
+        config,
+    };
+}
+
+export async function resolveBcpConfig(
+    rootDirectory: string,
+    overrides: ResolveBcpConfigOverrides = {},
+    environment: NodeJS.ProcessEnv = process.env
+): Promise<{
+    file: string | null;
+    config: ResolvedBcpConfig;
+}> {
+    const loaded =
+        await loadBcpConfig(
+            rootDirectory
+        );
+
+    const config =
+        loaded.config;
+
+    const resolved:
+        ResolvedBcpConfig = {
+        server: {
+            port:
+                overrides.port ??
+                parseEnvironmentPort(
+                    environment.BCP_PORT
+                ) ??
+                config.server?.port ??
+                defaultBcpConfig.server.port,
+            hostname:
+                overrides.hostname ??
+                nonEmptyEnvironmentValue(
+                    environment.BCP_HOSTNAME
+                ) ??
+                config.server?.hostname ??
+                defaultBcpConfig.server.hostname,
+            bodyLimit:
+                parsePositiveInteger(
+                    environment.BCP_BODY_LIMIT,
+                    "BCP_BODY_LIMIT"
+                ) ??
+                config.server?.bodyLimit ??
+                defaultBcpConfig.server.bodyLimit,
+        },
+        compression:
+            parseEnvironmentBoolean(
+                environment.BCP_COMPRESSION,
+                "BCP_COMPRESSION"
+            ) ??
+            config.compression ??
+            defaultBcpConfig.compression,
+        build: {
+            minify:
+                parseEnvironmentBoolean(
+                    environment.BCP_BUILD_MINIFY,
+                    "BCP_BUILD_MINIFY"
+                ) ??
+                config.build?.minify ??
+                defaultBcpConfig.build.minify,
+            sourceMaps:
+                parseEnvironmentBoolean(
+                    environment.BCP_BUILD_SOURCE_MAPS,
+                    "BCP_BUILD_SOURCE_MAPS"
+                ) ??
+                config.build?.sourceMaps ??
+                defaultBcpConfig.build.sourceMaps,
+        },
+        cache: {
+            response:
+                parseEnvironmentBoolean(
+                    environment.BCP_RESPONSE_CACHE,
+                    "BCP_RESPONSE_CACHE"
+                ) ??
+                config.cache?.response ??
+                defaultBcpConfig.cache.response,
+        },
+        experimental: {
+            partialHydration:
+                parseEnvironmentBoolean(
+                    environment.BCP_EXPERIMENTAL_PARTIAL_HYDRATION,
+                    "BCP_EXPERIMENTAL_PARTIAL_HYDRATION"
+                ) ??
+                config.experimental?.partialHydration ??
+                defaultBcpConfig.experimental.partialHydration,
+            islands:
+                parseEnvironmentBoolean(
+                    environment.BCP_EXPERIMENTAL_ISLANDS,
+                    "BCP_EXPERIMENTAL_ISLANDS"
+                ) ??
+                config.experimental?.islands ??
+                defaultBcpConfig.experimental.islands,
+        },
+        security: {
+            poweredByHeader:
+                parseEnvironmentBoolean(
+                    environment.BCP_POWERED_BY_HEADER,
+                    "BCP_POWERED_BY_HEADER"
+                ) ??
+                config.security?.poweredByHeader ??
+                defaultBcpConfig.security.poweredByHeader,
+            contentSecurityPolicy:
+                parseOptionalHeaderEnvironment(
+                    environment.BCP_SECURITY_CSP,
+                    "BCP_SECURITY_CSP"
+                ) ??
+                config.security?.contentSecurityPolicy ??
+                defaultBcpConfig.security.contentSecurityPolicy,
+            frameOptions:
+                parseFrameOptionsEnvironment(
+                    environment.BCP_SECURITY_FRAME_OPTIONS
+                ) ??
+                config.security?.frameOptions ??
+                defaultBcpConfig.security.frameOptions,
+            referrerPolicy:
+                nonEmptyEnvironmentValue(
+                    environment.BCP_SECURITY_REFERRER_POLICY
+                ) ??
+                config.security?.referrerPolicy ??
+                defaultBcpConfig.security.referrerPolicy,
+            permissionsPolicy:
+                parseOptionalHeaderEnvironment(
+                    environment.BCP_SECURITY_PERMISSIONS_POLICY,
+                    "BCP_SECURITY_PERMISSIONS_POLICY"
+                ) ??
+                config.security?.permissionsPolicy ??
+                defaultBcpConfig.security.permissionsPolicy,
+        },
+    };
+
+    validateResolvedConfig(
+        resolved
+    );
+
+    return {
+        file:
+            loaded.file,
+        config:
+            resolved,
+    };
+}
+
+export function applyResolvedBcpConfig(
+    config: ResolvedBcpConfig
+): void {
+    process.env.BCP_RESOLVED_CONFIG =
+        JSON.stringify(
+            config
+        );
+    process.env.BCP_COMPRESSION =
+        config.compression
+            ? "1"
+            : "0";
+    process.env.BCP_BODY_LIMIT =
+        String(
+            config.server.bodyLimit
+        );
+    process.env.BCP_BUILD_MINIFY =
+        config.build.minify
+            ? "1"
+            : "0";
+    process.env.BCP_BUILD_SOURCE_MAPS =
+        config.build.sourceMaps
+            ? "1"
+            : "0";
+    process.env.BCP_RESPONSE_CACHE =
+        config.cache.response
+            ? "1"
+            : "0";
+    process.env.BCP_EXPERIMENTAL_PARTIAL_HYDRATION =
+        config.experimental.partialHydration
+            ? "1"
+            : "0";
+    process.env.BCP_EXPERIMENTAL_ISLANDS =
+        config.experimental.islands
+            ? "1"
+            : "0";
+    process.env.BCP_POWERED_BY_HEADER =
+        config.security.poweredByHeader
+            ? "1"
+            : "0";
+    process.env.BCP_SECURITY_CSP =
+        config.security.contentSecurityPolicy === false
+            ? "0"
+            : config.security.contentSecurityPolicy;
+    process.env.BCP_SECURITY_FRAME_OPTIONS =
+        config.security.frameOptions === false
+            ? "0"
+            : config.security.frameOptions;
+    process.env.BCP_SECURITY_REFERRER_POLICY =
+        config.security.referrerPolicy;
+    process.env.BCP_SECURITY_PERMISSIONS_POLICY =
+        config.security.permissionsPolicy === false
+            ? "0"
+            : config.security.permissionsPolicy;
+}
+
+export function readResolvedBcpConfig(): ResolvedBcpConfig {
+    const serialized =
+        process.env.BCP_RESOLVED_CONFIG;
+
+    if (!serialized) {
+        return structuredClone(
+            defaultBcpConfig
+        );
+    }
+
+    try {
+        const value =
+            JSON.parse(
+                serialized
+            ) as ResolvedBcpConfig;
+
+        validateResolvedConfig(
+            value
+        );
+
+        return value;
+    } catch (error) {
+        throw new Error(
+            `BCP Framework: invalid resolved configuration state. ${error instanceof Error ? error.message : String(error)}`
+        );
+    }
+}
+
+function assertConfig(
+    value: unknown,
+    label: string
+): asserts value is BcpConfig {
+    if (
+        !isPlainObject(
+            value
+        )
+    ) {
+        throw new Error(
+            `BCP Framework: ${label} must export an object.`
+        );
+    }
+
+    const allowed =
+        new Set([
+            "server",
+            "compression",
+            "build",
+            "cache",
+            "experimental",
+            "security",
+        ]);
+
+    for (
+        const key
+        of Object.keys(
+            value
+        )
+    ) {
+        if (
+            !allowed.has(
+                key
+            )
+        ) {
+            throw new Error(
+                `BCP Framework: unknown config option "${key}" in ${label}.`
+            );
+        }
+    }
+
+    if (
+        value.server !== undefined
+    ) {
+        assertObjectKeys(
+            value.server,
+            "server",
+            [
+                "port",
+                "hostname",
+                "bodyLimit",
+            ]
+        );
+
+        if (
+            value.server.port !== undefined
+        ) {
+            assertPort(
+                value.server.port,
+                "server.port"
+            );
+        }
+
+        if (
+            value.server.hostname !== undefined &&
+            (
+                typeof value.server.hostname !== "string" ||
+                value.server.hostname.trim() === ""
+            )
+        ) {
+            throw new Error(
+                "BCP Framework: server.hostname must be a non-empty string."
+            );
+        }
+
+        if (
+            value.server.bodyLimit !== undefined
+        ) {
+            assertPositiveInteger(
+                value.server.bodyLimit,
+                "server.bodyLimit"
+            );
+        }
+    }
+
+    assertOptionalBoolean(
+        value.compression,
+        "compression"
+    );
+
+    if (
+        value.build !== undefined
+    ) {
+        assertObjectKeys(
+            value.build,
+            "build",
+            [
+                "minify",
+                "sourceMaps",
+            ]
+        );
+        assertOptionalBoolean(
+            value.build.minify,
+            "build.minify"
+        );
+        assertOptionalBoolean(
+            value.build.sourceMaps,
+            "build.sourceMaps"
+        );
+    }
+
+    if (
+        value.cache !== undefined
+    ) {
+        assertObjectKeys(
+            value.cache,
+            "cache",
+            [
+                "response",
+            ]
+        );
+        assertOptionalBoolean(
+            value.cache.response,
+            "cache.response"
+        );
+    }
+
+    if (
+        value.experimental !== undefined
+    ) {
+        assertObjectKeys(
+            value.experimental,
+            "experimental",
+            [
+                "partialHydration",
+                "islands",
+            ]
+        );
+        assertOptionalBoolean(
+            value.experimental.partialHydration,
+            "experimental.partialHydration"
+        );
+        assertOptionalBoolean(
+            value.experimental.islands,
+            "experimental.islands"
+        );
+    }
+
+    if (
+        value.security !== undefined
+    ) {
+        assertObjectKeys(
+            value.security,
+            "security",
+            [
+                "poweredByHeader",
+                "contentSecurityPolicy",
+                "frameOptions",
+                "referrerPolicy",
+                "permissionsPolicy",
+            ]
+        );
+        assertOptionalBoolean(
+            value.security.poweredByHeader,
+            "security.poweredByHeader"
+        );
+        assertOptionalHeaderOrFalse(
+            value.security.contentSecurityPolicy,
+            "security.contentSecurityPolicy"
+        );
+        assertFrameOptions(
+            value.security.frameOptions,
+            "security.frameOptions"
+        );
+        assertOptionalHeaderString(
+            value.security.referrerPolicy,
+            "security.referrerPolicy"
+        );
+        assertOptionalHeaderOrFalse(
+            value.security.permissionsPolicy,
+            "security.permissionsPolicy"
+        );
+    }
+}
+
+function validateResolvedConfig(
+    value: ResolvedBcpConfig
+): void {
+    if (
+        !value ||
+        !value.server ||
+        !value.build ||
+        !value.cache ||
+        !value.experimental ||
+        !value.security
+    ) {
+        throw new Error(
+            "Resolved config is incomplete."
+        );
+    }
+
+    assertPort(
+        value.server.port,
+        "server.port"
+    );
+    assertPositiveInteger(
+        value.server.bodyLimit,
+        "server.bodyLimit"
+    );
+
+    if (
+        typeof value.server.hostname !== "string" ||
+        value.server.hostname.trim() === ""
+    ) {
+        throw new Error(
+            "server.hostname must be a non-empty string."
+        );
+    }
+
+    for (
+        const [
+            label,
+            item,
+        ]
+        of [
+            ["compression", value.compression],
+            ["build.minify", value.build.minify],
+            ["build.sourceMaps", value.build.sourceMaps],
+            ["cache.response", value.cache.response],
+            ["experimental.partialHydration", value.experimental.partialHydration],
+            ["experimental.islands", value.experimental.islands],
+            ["security.poweredByHeader", value.security.poweredByHeader],
+        ] as const
+    ) {
+        if (
+            typeof item !== "boolean"
+        ) {
+            throw new Error(
+                `${label} must be boolean.`
+            );
+        }
+    }
+
+    assertHeaderOrFalse(
+        value.security.contentSecurityPolicy,
+        "security.contentSecurityPolicy"
+    );
+    assertFrameOptions(
+        value.security.frameOptions,
+        "security.frameOptions"
+    );
+    assertHeaderString(
+        value.security.referrerPolicy,
+        "security.referrerPolicy"
+    );
+    assertHeaderOrFalse(
+        value.security.permissionsPolicy,
+        "security.permissionsPolicy"
+    );
+}
+
+function assertObjectKeys(
+    value: unknown,
+    label: string,
+    keys: string[]
+): asserts value is Record<string, any> {
+    if (
+        !isPlainObject(
+            value
+        )
+    ) {
+        throw new Error(
+            `BCP Framework: ${label} must be an object.`
+        );
+    }
+
+    const allowed =
+        new Set(
+            keys
+        );
+
+    for (
+        const key
+        of Object.keys(
+            value
+        )
+    ) {
+        if (
+            !allowed.has(
+                key
+            )
+        ) {
+            throw new Error(
+                `BCP Framework: unknown config option "${label}.${key}".`
+            );
+        }
+    }
+}
+
+function assertOptionalBoolean(
+    value: unknown,
+    label: string
+): void {
+    if (
+        value !== undefined &&
+        typeof value !== "boolean"
+    ) {
+        throw new Error(
+            `BCP Framework: ${label} must be boolean.`
+        );
+    }
+}
+
+function assertPort(
+    value: unknown,
+    label: string
+): asserts value is number {
+    if (
+        !Number.isInteger(
+            value
+        ) ||
+        Number(value) < 1 ||
+        Number(value) > 65535
+    ) {
+        throw new Error(
+            `BCP Framework: ${label} must be an integer between 1 and 65535.`
+        );
+    }
+}
+
+function assertPositiveInteger(
+    value: unknown,
+    label: string
+): asserts value is number {
+    if (
+        !Number.isInteger(
+            value
+        ) ||
+        Number(value) < 1
+    ) {
+        throw new Error(
+            `BCP Framework: ${label} must be a positive integer.`
+        );
+    }
+}
+
+function assertOptionalHeaderOrFalse(
+    value: unknown,
+    label: string
+): void {
+    if (
+        value === undefined
+    ) {
+        return;
+    }
+
+    assertHeaderOrFalse(
+        value,
+        label
+    );
+}
+
+function assertHeaderOrFalse(
+    value: unknown,
+    label: string
+): asserts value is string | false {
+    if (
+        value === false
+    ) {
+        return;
+    }
+
+    assertHeaderString(
+        value,
+        label
+    );
+}
+
+function assertOptionalHeaderString(
+    value: unknown,
+    label: string
+): void {
+    if (
+        value === undefined
+    ) {
+        return;
+    }
+
+    assertHeaderString(
+        value,
+        label
+    );
+}
+
+function assertHeaderString(
+    value: unknown,
+    label: string
+): asserts value is string {
+    if (
+        typeof value !== "string" ||
+        value.trim() === ""
+    ) {
+        throw new Error(
+            `BCP Framework: ${label} must be a non-empty string.`
+        );
+    }
+
+    if (
+        value.includes("\r") ||
+        value.includes("\n") ||
+        value.includes("\0")
+    ) {
+        throw new Error(
+            `BCP Framework: ${label} must not contain control characters.`
+        );
+    }
+}
+
+function assertFrameOptions(
+    value: unknown,
+    label: string
+): asserts value is "DENY" | "SAMEORIGIN" | false | undefined {
+    if (
+        value === undefined ||
+        value === false ||
+        value === "DENY" ||
+        value === "SAMEORIGIN"
+    ) {
+        return;
+    }
+
+    throw new Error(
+        `BCP Framework: ${label} must be "DENY", "SAMEORIGIN", or false.`
+    );
+}
+
+function parseEnvironmentPort(
+    value: string | undefined
+): number | undefined {
+    if (
+        value === undefined ||
+        value.trim() === ""
+    ) {
+        return undefined;
+    }
+
+    const port =
+        Number(
+            value
+        );
+
+    assertPort(
+        port,
+        "BCP_PORT"
+    );
+
+    return port;
+}
+
+function parsePositiveInteger(
+    value: string | undefined,
+    label: string
+): number | undefined {
+    if (
+        value === undefined ||
+        value.trim() === ""
+    ) {
+        return undefined;
+    }
+
+    const parsed =
+        Number(
+            value
+        );
+
+    assertPositiveInteger(
+        parsed,
+        label
+    );
+
+    return parsed;
+}
+
+function parseEnvironmentBoolean(
+    value: string | undefined,
+    label: string
+): boolean | undefined {
+    if (
+        value === undefined ||
+        value.trim() === ""
+    ) {
+        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: ${label} must be a boolean value (true/false, 1/0, yes/no, on/off).`
+    );
+}
+
+function parseOptionalHeaderEnvironment(
+    value: string | undefined,
+    label: string
+): string | false | undefined {
+    if (
+        value === undefined ||
+        value.trim() === ""
+    ) {
+        return undefined;
+    }
+
+    const normalized =
+        value.trim();
+    const lowered =
+        normalized.toLowerCase();
+
+    if (
+        lowered === "0" ||
+        lowered === "false" ||
+        lowered === "off"
+    ) {
+        return false;
+    }
+
+    assertHeaderString(
+        normalized,
+        label
+    );
+    return normalized;
+}
+
+function parseFrameOptionsEnvironment(
+    value: string | undefined
+): "DENY" | "SAMEORIGIN" | false | undefined {
+    if (
+        value === undefined ||
+        value.trim() === ""
+    ) {
+        return undefined;
+    }
+
+    const normalized =
+        value
+            .trim()
+            .toUpperCase();
+
+    if (
+        normalized === "0" ||
+        normalized === "FALSE" ||
+        normalized === "OFF"
+    ) {
+        return false;
+    }
+
+    if (
+        normalized === "DENY" ||
+        normalized === "SAMEORIGIN"
+    ) {
+        return normalized;
+    }
+
+    throw new Error(
+        "BCP Framework: BCP_SECURITY_FRAME_OPTIONS must be DENY, SAMEORIGIN, or off."
+    );
+}
+
+function nonEmptyEnvironmentValue(
+    value: string | undefined
+): string | undefined {
+    const normalized =
+        value?.trim();
+
+    return normalized
+        ? normalized
+        : undefined;
+}
+
+function isPlainObject(
+    value: unknown
+): value is Record<string, any> {
+    return (
+        typeof value === "object" &&
+        value !== null &&
+        !Array.isArray(
+            value
+        )
+    );
+}