@chidchanun/bcp 0.1.10 → 0.1.11

package/packages/server/src/form-action.ts

@@ -0,0 +1,493 @@
+import fs from "node:fs";
+import path from "node:path";
+import {
+    pathToFileURL,
+} from "node:url";
+
+import {
+    executePageGuards,
+    type PageGuardData,
+} from "./page-guard.js";
+
+export const PAGE_ACTION_METHODS = [
+    "POST",
+    "PUT",
+    "PATCH",
+    "DELETE",
+] as const;
+
+export type PageActionMethod =
+    typeof PAGE_ACTION_METHODS[number];
+
+export interface PageActionContext {
+    params: Record<string, any>;
+    searchParams: URLSearchParams;
+    guardData: Readonly<PageGuardData>;
+    method: PageActionMethod;
+}
+
+export type PageAction = (
+    formData: FormData,
+    context: PageActionContext
+) =>
+    | unknown
+    | Promise<unknown>;
+
+export interface PageActionExecution {
+    hasGuard: boolean;
+    guardData: PageGuardData;
+    data: unknown;
+    response: Response | null;
+}
+
+const ACTION_NAME_PATTERN =
+    /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+
+const BLOCKED_ACTION_NAMES =
+    new Set([
+        "default",
+        "__proto__",
+        "prototype",
+        "constructor",
+    ]);
+
+export function findPageActionFile(
+    pageFilePath: string
+): string | null {
+    const directory =
+        path.dirname(
+            pageFilePath
+        );
+    const tsFile =
+        path.join(
+            directory,
+            "actions.ts"
+        );
+    const tsxFile =
+        path.join(
+            directory,
+            "actions.tsx"
+        );
+    const hasTs =
+        fs.existsSync(
+            tsFile
+        );
+    const hasTsx =
+        fs.existsSync(
+            tsxFile
+        );
+
+    if (hasTs && hasTsx) {
+        throw new Error(
+            `BCP Framework: both actions.ts and actions.tsx exist in "${directory}".`
+        );
+    }
+
+    if (hasTs) {
+        return tsFile;
+    }
+
+    if (hasTsx) {
+        return tsxFile;
+    }
+
+    return null;
+}
+
+export function routeHasPageActions(
+    pageFilePath: string
+): boolean {
+    return findPageActionFile(
+        pageFilePath
+    ) !== null;
+}
+
+export function normalizePageActionMethod(
+    value: string | null | undefined
+): PageActionMethod {
+    const method =
+        (value ?? "POST")
+            .trim()
+            .toUpperCase();
+
+    if (
+        !PAGE_ACTION_METHODS.includes(
+            method as PageActionMethod
+        )
+    ) {
+        throw new Error(
+            `BCP Framework: unsupported form action method "${method || String(value)}". Use POST, PUT, PATCH, or DELETE.`
+        );
+    }
+
+    return method as PageActionMethod;
+}
+
+export function assertPageActionName(
+    name: string
+): void {
+    if (
+        !ACTION_NAME_PATTERN.test(
+            name
+        ) ||
+        BLOCKED_ACTION_NAMES.has(
+            name
+        )
+    ) {
+        throw new Error(
+            `BCP Framework: invalid form action name "${name}".`
+        );
+    }
+}
+
+export async function executePageAction(
+    pageFilePath: string,
+    actionName: string,
+    method: PageActionMethod,
+    formData: FormData,
+    params: Record<string, any>,
+    requestUrl: URL,
+    moduleVersion = 0
+): Promise<PageActionExecution> {
+    assertPageActionName(
+        actionName
+    );
+
+    const appDirectory =
+        findAppDirectory(
+            pageFilePath
+        );
+    const guardExecution =
+        await executePageGuards(
+            appDirectory,
+            pageFilePath,
+            params,
+            requestUrl,
+            moduleVersion
+        );
+
+    if (
+        guardExecution.response
+    ) {
+        return {
+            hasGuard:
+                guardExecution.hasGuard,
+            guardData: {
+                ...guardExecution.data,
+            },
+            data:
+                null,
+            response:
+                guardExecution.response,
+        };
+    }
+
+    const actionFile =
+        findPageActionFile(
+            pageFilePath
+        );
+
+    if (!actionFile) {
+        throw new Error(
+            `BCP Framework: route "${pageFilePath}" has no actions.ts file.`
+        );
+    }
+
+    const moduleUrl =
+        pathToFileURL(
+            actionFile
+        );
+
+    moduleUrl.searchParams.set(
+        "bcp-action",
+        String(
+            moduleVersion
+        )
+    );
+
+    const actionModule =
+        await import(
+            moduleUrl.href
+        ) as Record<
+            string,
+            unknown
+        >;
+    const candidate =
+        actionModule[
+            actionName
+        ];
+
+    if (
+        typeof candidate !==
+        "function"
+    ) {
+        throw new Error(
+            `BCP Framework: action "${actionName}" was not exported as a function from "${actionFile}".`
+        );
+    }
+
+    return executePageActionFunction(
+        candidate as PageAction,
+        actionName,
+        method,
+        formData,
+        params,
+        requestUrl,
+        guardExecution.data,
+        guardExecution.hasGuard,
+        actionFile
+    );
+}
+
+export async function executePageActionFunction(
+    action: PageAction,
+    actionName: string,
+    method: PageActionMethod,
+    formData: FormData,
+    params: Record<string, any>,
+    requestUrl: URL,
+    guardData: PageGuardData = {},
+    hasGuard = false,
+    label = "actions.ts"
+): Promise<PageActionExecution> {
+    assertPageActionName(
+        actionName
+    );
+
+    const result =
+        await action(
+            formData,
+            {
+                params: {
+                    ...params,
+                },
+                searchParams:
+                    new URLSearchParams(
+                        requestUrl.searchParams
+                    ),
+                guardData: {
+                    ...guardData,
+                },
+                method,
+            }
+        );
+
+    if (
+        result instanceof
+        Response
+    ) {
+        return {
+            hasGuard,
+            guardData: {
+                ...guardData,
+            },
+            data:
+                null,
+            response:
+                result,
+        };
+    }
+
+    const data =
+        result === undefined
+            ? null
+            : result;
+
+    assertActionData(
+        data,
+        `${label}#${actionName}`
+    );
+
+    return {
+        hasGuard,
+        guardData: {
+            ...guardData,
+        },
+        data,
+        response:
+            null,
+    };
+}
+
+export function assertActionData(
+    value: unknown,
+    actionLabel = "action"
+): void {
+    const seen =
+        new Set<object>();
+
+    validateJsonValue(
+        value,
+        "$",
+        seen,
+        actionLabel
+    );
+}
+
+function findAppDirectory(
+    pageFilePath: string
+): string {
+    let current =
+        path.dirname(
+            path.resolve(
+                pageFilePath
+            )
+        );
+
+    while (true) {
+        if (
+            path.basename(
+                current
+            ) === "app"
+        ) {
+            return current;
+        }
+
+        const parent =
+            path.dirname(
+                current
+            );
+
+        if (parent === current) {
+            throw new Error(
+                `BCP Framework: could not resolve app directory for page "${pageFilePath}".`
+            );
+        }
+
+        current =
+            parent;
+    }
+}
+
+function validateJsonValue(
+    value: unknown,
+    location: string,
+    seen: Set<object>,
+    actionLabel: string
+): void {
+    if (
+        value === null ||
+        typeof value ===
+            "string" ||
+        typeof value ===
+            "boolean"
+    ) {
+        return;
+    }
+
+    if (
+        typeof value ===
+        "number"
+    ) {
+        if (
+            Number.isFinite(
+                value
+            )
+        ) {
+            return;
+        }
+
+        throwInvalidActionData(
+            actionLabel,
+            location,
+            "numbers must be finite"
+        );
+    }
+
+    if (
+        typeof value !==
+        "object"
+    ) {
+        throwInvalidActionData(
+            actionLabel,
+            location,
+            `unsupported ${typeof value} value`
+        );
+    }
+
+    const objectValue =
+        value as object;
+
+    if (seen.has(objectValue)) {
+        throwInvalidActionData(
+            actionLabel,
+            location,
+            "circular references are not supported"
+        );
+    }
+
+    seen.add(
+        objectValue
+    );
+
+    try {
+        if (Array.isArray(value)) {
+            value.forEach(
+                (
+                    item,
+                    index
+                ) => {
+                    validateJsonValue(
+                        item,
+                        `${location}[${index}]`,
+                        seen,
+                        actionLabel
+                    );
+                }
+            );
+            return;
+        }
+
+        const prototype =
+            Object.getPrototypeOf(
+                value
+            );
+
+        if (
+            prototype !==
+                Object.prototype &&
+            prototype !==
+                null
+        ) {
+            throwInvalidActionData(
+                actionLabel,
+                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,
+                actionLabel
+            );
+        }
+    } finally {
+        seen.delete(
+            objectValue
+        );
+    }
+}
+
+function throwInvalidActionData(
+    actionLabel: string,
+    location: string,
+    reason: string
+): never {
+    throw new Error(
+        `BCP Framework: action "${actionLabel}" returned non-serializable data at ${location}: ${reason}.`
+    );
+}

package/packages/server/src/middleware-dev-server.ts

@@ -9,6 +9,10 @@ import {
     createCriticalCssProxy,
 } from "./critical-css-proxy.js";
 
+import {
+    createFormActionDevProxy,
+} from "./form-action-dev-proxy.js";
+
 import {
     loadProjectMiddleware,
 } from "./middleware-loader.js";
@@ -48,6 +52,12 @@ export function createMiddlewareDevServer(
         > | null =
         null;
 
+    let actionGateway:
+        ReturnType<
+            typeof createFormActionDevProxy
+        > | null =
+        null;
+
     let middlewareGateway:
         ReturnType<
             typeof createMiddlewareProxy
@@ -76,6 +86,8 @@ export function createMiddlewareDevServer(
 
         const applicationPort =
             await findFreePort();
+        const actionPort =
+            await findFreePort();
         const middlewarePort =
             await findFreePort();
         const securityPort =
@@ -93,6 +105,30 @@ export function createMiddlewareDevServer(
 
         await internalServer.start();
 
+        actionGateway =
+            createFormActionDevProxy({
+                port:
+                    actionPort,
+                hostname:
+                    "127.0.0.1",
+                upstreamPort:
+                    applicationPort,
+                upstreamHostname:
+                    "127.0.0.1",
+                rootDirectory,
+            });
+
+        try {
+            await actionGateway.start();
+        } catch (error) {
+            await internalServer.stop();
+            internalServer =
+                null;
+            actionGateway =
+                null;
+            throw error;
+        }
+
         middlewareGateway =
             createMiddlewareProxy({
                 port:
@@ -100,7 +136,7 @@ export function createMiddlewareDevServer(
                 hostname:
                     "127.0.0.1",
                 upstreamPort:
-                    applicationPort,
+                    actionPort,
                 upstreamHostname:
                     "127.0.0.1",
                 getMiddleware:
@@ -113,9 +149,12 @@ export function createMiddlewareDevServer(
         try {
             await middlewareGateway.start();
         } catch (error) {
+            await actionGateway.stop();
             await internalServer.stop();
             internalServer =
                 null;
+            actionGateway =
+                null;
             middlewareGateway =
                 null;
             throw error;
@@ -137,9 +176,12 @@ export function createMiddlewareDevServer(
             await securityGateway.start();
         } catch (error) {
             await middlewareGateway.stop();
+            await actionGateway.stop();
             await internalServer.stop();
             internalServer =
                 null;
+            actionGateway =
+                null;
             middlewareGateway =
                 null;
             securityGateway =
@@ -168,9 +210,12 @@ export function createMiddlewareDevServer(
         } catch (error) {
             await securityGateway.stop();
             await middlewareGateway.stop();
+            await actionGateway.stop();
             await internalServer.stop();
             internalServer =
                 null;
+            actionGateway =
+                null;
             middlewareGateway =
                 null;
             securityGateway =
@@ -186,6 +231,9 @@ export function createMiddlewareDevServer(
         console.log(
             `[BCP Security] Dev gateway: http://${hostname}:${port}`
         );
+        console.log(
+            `[BCP Actions] Endpoint: /_bcp/action`
+        );
         console.log(
             `[BCP CSS] Inline /bcp.css when <= 8 KiB and allowed by CSP.`
         );
@@ -214,6 +262,12 @@ export function createMiddlewareDevServer(
                 null;
         }
 
+        if (actionGateway) {
+            await actionGateway.stop();
+            actionGateway =
+                null;
+        }
+
         if (internalServer) {
             await internalServer.stop();
             internalServer =
@@ -313,4 +367,4 @@ async function findFreePort(): Promise<number> {
             );
         }
     }
-}
+}