@chidchanun/bcp 0.1.9 → 0.1.10

package/packages/server/src/page-guard.ts

@@ -0,0 +1,529 @@
+import fs from "node:fs";
+import path from "node:path";
+import {
+    pathToFileURL,
+} from "node:url";
+
+export const GUARD_DATA_PARAM =
+    "__bcp_guard_data";
+
+export type PageGuardData =
+    Record<string, unknown>;
+
+export interface PageGuardContext {
+    params: Record<string, any>;
+    searchParams: URLSearchParams;
+    guardData: Readonly<PageGuardData>;
+}
+
+export type PageGuard = (
+    context: PageGuardContext
+) =>
+    | void
+    | PageGuardData
+    | Response
+    | Promise<
+        | void
+        | PageGuardData
+        | Response
+    >;
+
+export interface PageGuardExecution {
+    hasGuard: boolean;
+    data: PageGuardData;
+    response: Response | null;
+}
+
+export interface PageGuardDefinition {
+    filePath: string;
+    guard: PageGuard;
+}
+
+export function findPageGuardFiles(
+    appDirectory: string,
+    pageFilePath: string
+): string[] {
+    const appRoot =
+        path.resolve(
+            appDirectory
+        );
+    const pageDirectory =
+        path.dirname(
+            path.resolve(
+                pageFilePath
+            )
+        );
+
+    if (
+        !isInsideDirectory(
+            appRoot,
+            pageDirectory
+        )
+    ) {
+        throw new Error(
+            `BCP Framework: page "${pageFilePath}" is outside app directory "${appDirectory}".`
+        );
+    }
+
+    const directories:
+        string[] = [];
+    let current =
+        pageDirectory;
+
+    while (true) {
+        directories.push(
+            current
+        );
+
+        if (current === appRoot) {
+            break;
+        }
+
+        const parent =
+            path.dirname(
+                current
+            );
+
+        if (
+            parent === current ||
+            !isInsideDirectory(
+                appRoot,
+                parent
+            )
+        ) {
+            break;
+        }
+
+        current =
+            parent;
+    }
+
+    directories.reverse();
+
+    const files:
+        string[] = [];
+
+    for (const directory of directories) {
+        const guardFile =
+            findGuardFileInDirectory(
+                directory
+            );
+
+        if (guardFile) {
+            files.push(
+                guardFile
+            );
+        }
+    }
+
+    return files;
+}
+
+export function routeHasPageGuard(
+    appDirectory: string,
+    pageFilePath: string
+): boolean {
+    return findPageGuardFiles(
+        appDirectory,
+        pageFilePath
+    ).length > 0;
+}
+
+export async function executePageGuards(
+    appDirectory: string,
+    pageFilePath: string,
+    params: Record<string, any>,
+    requestUrl: URL,
+    moduleVersion = 0
+): Promise<PageGuardExecution> {
+    const guardFiles =
+        findPageGuardFiles(
+            appDirectory,
+            pageFilePath
+        );
+
+    if (guardFiles.length === 0) {
+        return emptyGuardExecution();
+    }
+
+    const definitions:
+        PageGuardDefinition[] = [];
+
+    for (const guardFile of guardFiles) {
+        const moduleUrl =
+            pathToFileURL(
+                guardFile
+            );
+
+        moduleUrl.searchParams.set(
+            "bcp-guard",
+            String(
+                moduleVersion
+            )
+        );
+
+        const guardModule =
+            await import(
+                moduleUrl.href
+            ) as {
+                guard?: unknown;
+            };
+
+        if (
+            typeof guardModule.guard !==
+            "function"
+        ) {
+            throw new Error(
+                `BCP Framework: guard "${guardFile}" must export a named guard() function.`
+            );
+        }
+
+        definitions.push({
+            filePath:
+                guardFile,
+            guard:
+                guardModule.guard as PageGuard,
+        });
+    }
+
+    return executePageGuardFunctions(
+        definitions,
+        params,
+        requestUrl
+    );
+}
+
+export async function executePageGuardFunctions(
+    guards: PageGuardDefinition[],
+    params: Record<string, any>,
+    requestUrl: URL
+): Promise<PageGuardExecution> {
+    if (guards.length === 0) {
+        return emptyGuardExecution();
+    }
+
+    const guardData:
+        PageGuardData = {};
+
+    for (const definition of guards) {
+        const result =
+            await definition.guard({
+                params: {
+                    ...params,
+                },
+                searchParams:
+                    new URLSearchParams(
+                        requestUrl.searchParams
+                    ),
+                guardData: {
+                    ...guardData,
+                },
+            });
+
+        if (
+            result instanceof
+            Response
+        ) {
+            return {
+                hasGuard:
+                    true,
+                data:
+                    guardData,
+                response:
+                    result,
+            };
+        }
+
+        if (
+            result === undefined
+        ) {
+            continue;
+        }
+
+        assertGuardData(
+            result,
+            definition.filePath
+        );
+
+        Object.assign(
+            guardData,
+            result
+        );
+    }
+
+    return {
+        hasGuard:
+            true,
+        data:
+            guardData,
+        response:
+            null,
+    };
+}
+
+export function attachGuardDataToParams(
+    params: Record<string, any>,
+    execution: PageGuardExecution
+): Record<string, any> {
+    if (!execution.hasGuard) {
+        return {
+            ...params,
+        };
+    }
+
+    return {
+        ...params,
+        [GUARD_DATA_PARAM]:
+            execution.data,
+    };
+}
+
+function emptyGuardExecution(): PageGuardExecution {
+    return {
+        hasGuard:
+            false,
+        data: {},
+        response:
+            null,
+    };
+}
+
+function findGuardFileInDirectory(
+    directory: string
+): string | null {
+    const tsFile =
+        path.join(
+            directory,
+            "guard.ts"
+        );
+    const tsxFile =
+        path.join(
+            directory,
+            "guard.tsx"
+        );
+    const hasTs =
+        fs.existsSync(
+            tsFile
+        );
+    const hasTsx =
+        fs.existsSync(
+            tsxFile
+        );
+
+    if (hasTs && hasTsx) {
+        throw new Error(
+            `BCP Framework: both guard.ts and guard.tsx exist in "${directory}".`
+        );
+    }
+
+    if (hasTs) {
+        return tsFile;
+    }
+
+    if (hasTsx) {
+        return tsxFile;
+    }
+
+    return null;
+}
+
+function assertGuardData(
+    value: unknown,
+    label: string
+): asserts value is PageGuardData {
+    if (
+        value === null ||
+        Array.isArray(
+            value
+        ) ||
+        typeof value !==
+            "object"
+    ) {
+        throw new Error(
+            `BCP Framework: guard "${label}" must return a plain object, undefined, or a Response.`
+        );
+    }
+
+    const prototype =
+        Object.getPrototypeOf(
+            value
+        );
+
+    if (
+        prototype !==
+            Object.prototype &&
+        prototype !==
+            null
+    ) {
+        throw new Error(
+            `BCP Framework: guard "${label}" must return a plain object, undefined, or a Response.`
+        );
+    }
+
+    const seen =
+        new Set<object>();
+
+    validateJsonValue(
+        value,
+        "$",
+        seen,
+        label
+    );
+}
+
+function validateJsonValue(
+    value: unknown,
+    location: string,
+    seen: Set<object>,
+    guardLabel: string
+): void {
+    if (
+        value === null ||
+        typeof value ===
+            "string" ||
+        typeof value ===
+            "boolean"
+    ) {
+        return;
+    }
+
+    if (
+        typeof value ===
+        "number"
+    ) {
+        if (
+            Number.isFinite(
+                value
+            )
+        ) {
+            return;
+        }
+
+        throwInvalidGuardData(
+            guardLabel,
+            location,
+            "numbers must be finite"
+        );
+    }
+
+    if (
+        typeof value !==
+        "object"
+    ) {
+        throwInvalidGuardData(
+            guardLabel,
+            location,
+            `unsupported ${typeof value} value`
+        );
+    }
+
+    const objectValue =
+        value as object;
+
+    if (seen.has(objectValue)) {
+        throwInvalidGuardData(
+            guardLabel,
+            location,
+            "circular references are not supported"
+        );
+    }
+
+    seen.add(
+        objectValue
+    );
+
+    try {
+        if (Array.isArray(value)) {
+            value.forEach(
+                (
+                    item,
+                    index
+                ) => {
+                    validateJsonValue(
+                        item,
+                        `${location}[${index}]`,
+                        seen,
+                        guardLabel
+                    );
+                }
+            );
+            return;
+        }
+
+        const prototype =
+            Object.getPrototypeOf(
+                value
+            );
+
+        if (
+            prototype !==
+                Object.prototype &&
+            prototype !==
+                null
+        ) {
+            throwInvalidGuardData(
+                guardLabel,
+                location,
+                "only plain objects and arrays are supported"
+            );
+        }
+
+        for (
+            const [
+                key,
+                item,
+            ]
+            of Object.entries(
+                value as Record<
+                    string,
+                    unknown
+                >
+            )
+        ) {
+            validateJsonValue(
+                item,
+                `${location}.${key}`,
+                seen,
+                guardLabel
+            );
+        }
+    } finally {
+        seen.delete(
+            objectValue
+        );
+    }
+}
+
+function throwInvalidGuardData(
+    guardLabel: string,
+    location: string,
+    reason: string
+): never {
+    throw new Error(
+        `BCP Framework: guard "${guardLabel}" returned non-serializable data at ${location}: ${reason}.`
+    );
+}
+
+function isInsideDirectory(
+    rootDirectory: string,
+    candidate: string
+): boolean {
+    const relative =
+        path.relative(
+            rootDirectory,
+            candidate
+        );
+
+    return (
+        relative === "" ||
+        (
+            relative !== ".." &&
+            !relative.startsWith(
+                `..${path.sep}`
+            ) &&
+            !path.isAbsolute(
+                relative
+            )
+        )
+    );
+}