hightjs 1.0.7 → 1.1.0

package/dist/client/client.d.ts

@@ -1,3 +1,4 @@
 export { Link } from '../components/Link';
 export { RouteConfig, Metadata } from "../types";
 export { router } from './clientRouter';
+export { importServer } from './rpc';

package/dist/client/client.js

@@ -16,9 +16,12 @@
  * limitations under the License.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.router = exports.Link = void 0;
+exports.importServer = exports.router = exports.Link = void 0;
 // Este arquivo exporta apenas código seguro para o cliente (navegador)
 var Link_1 = require("../components/Link");
 Object.defineProperty(exports, "Link", { enumerable: true, get: function () { return Link_1.Link; } });
 var clientRouter_1 = require("./clientRouter");
 Object.defineProperty(exports, "router", { enumerable: true, get: function () { return clientRouter_1.router; } });
+// RPC (client-side)
+var rpc_1 = require("./rpc");
+Object.defineProperty(exports, "importServer", { enumerable: true, get: function () { return rpc_1.importServer; } });

package/dist/client/entry.client.js

@@ -422,7 +422,6 @@ function initializeClient() {
         return;
     }
     const initialData = deobfuscateData(obfuscated);
-    console.log(initialData);
     if (!initialData) {
         console.error('[hweb] Failed to parse initial data.');
         return;

package/dist/client/rpc.d.ts

@@ -0,0 +1,8 @@
+/**
+ * `importServer("src/backend/index.ts")` returns a Proxy where every property is
+ * a function that performs a POST to `/api/rpc`.
+ *
+ * Security note: the server will still validate allowlisted directories.
+ * @param {string} file
+ */
+export declare function importServer<T extends Record<string, any> = Record<string, any>>(file: string): T;

package/dist/client/rpc.js

@@ -0,0 +1,97 @@
+"use strict";
+/*
+ * This file is part of the HightJS Project.
+ * Copyright (c) 2025 itsmuzin
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.importServer = importServer;
+const types_1 = require("../rpc/types");
+function asErrorMessage(err) {
+    if (err instanceof Error)
+        return err.message;
+    try {
+        return String(err);
+    }
+    catch {
+        return 'Unknown error';
+    }
+}
+/**
+ * `importServer("src/backend/index.ts")` returns a Proxy where every property is
+ * a function that performs a POST to `/api/rpc`.
+ *
+ * Security note: the server will still validate allowlisted directories.
+ * @param {string} file
+ */
+function importServer(file) {
+    if (!file) {
+        throw new Error('importServer(file) requires a non-empty string');
+    }
+    const handler = {
+        get(_target, prop) {
+            // allow tooling & debugging
+            if (prop === '__file')
+                return file;
+            if (prop === 'then')
+                return undefined; // prevent await Proxy issues
+            const fnName = String(prop);
+            return async (...args) => {
+                const payload = {
+                    file,
+                    fn: fnName,
+                    args,
+                    request: {
+                        url: typeof window !== 'undefined' ? window.location.href : undefined,
+                        method: 'RPC',
+                        headers: {
+                            // useful for server-side auth/session logic
+                            ...(typeof navigator !== 'undefined' ? { 'user-agent': navigator.userAgent } : {}),
+                            // forward cookies so server can reconstruct request.cookies if needed
+                            ...(typeof document !== 'undefined' ? { cookie: document.cookie } : {})
+                        }
+                    }
+                };
+                let res;
+                try {
+                    res = await fetch(types_1.RPC_ENDPOINT, {
+                        method: 'POST',
+                        headers: {
+                            'Content-Type': 'application/json'
+                        },
+                        body: JSON.stringify(payload)
+                    });
+                }
+                catch (err) {
+                    throw new Error(asErrorMessage(err));
+                }
+                let data;
+                try {
+                    data = (await res.json());
+                }
+                catch {
+                    throw new Error('Invalid JSON response from RPC');
+                }
+                if (!data || typeof data !== 'object' || typeof data.success !== 'boolean') {
+                    throw new Error('Invalid RPC response shape');
+                }
+                if (data.success) {
+                    return data.return;
+                }
+                throw new Error(data.error || 'RPC Error');
+            };
+        }
+    };
+    return new Proxy({}, handler);
+}

package/dist/index.js

@@ -66,6 +66,9 @@ Object.defineProperty(exports, "HightJSResponse", { enumerable: true, get: funct
 const hotReload_1 = require("./hotReload");
 const factory_1 = require("./adapters/factory");
 const console_1 = __importStar(require("./api/console"));
+// RPC
+const server_1 = require("./rpc/server");
+const types_1 = require("./rpc/types");
 // Exporta os adapters para uso manual se necessário
 var express_2 = require("./adapters/express");
 Object.defineProperty(exports, "ExpressAdapter", { enumerable: true, get: function () { return express_2.ExpressAdapter; } });
@@ -330,15 +333,33 @@ function hweb(options) {
         },
         getRequestHandler: () => {
             return async (req, res) => {
-                // Detecta automaticamente o framework e cria o adapter apropriado
+                // Detecta o framework e cria request/response genéricos
                 const adapter = factory_1.FrameworkAdapterFactory.detectFramework(req, res);
                 const genericReq = adapter.parseRequest(req);
                 const genericRes = adapter.createResponse(res);
                 // Adiciona informações do hweb na requisição genérica
                 genericReq.hwebDev = dev;
                 genericReq.hotReloadManager = hotReloadManager;
-                const { pathname } = new URL(genericReq.url, `http://${genericReq.headers.host || 'localhost'}`);
-                const method = genericReq.method.toUpperCase();
+                const { hostname } = req.headers;
+                const method = (genericReq.method || 'GET').toUpperCase();
+                const pathname = new URL(genericReq.url, `http://${hostname}:${port}`).pathname;
+                // RPC endpoint (antes das rotas de backend)
+                if (pathname === types_1.RPC_ENDPOINT && method === 'POST') {
+                    try {
+                        const result = await (0, server_1.executeRpc)({
+                            projectDir: dir,
+                            request: genericReq
+                        }, genericReq.body);
+                        genericRes.header('Content-Type', 'application/json');
+                        genericRes.status(200).send(JSON.stringify(result));
+                        return;
+                    }
+                    catch (error) {
+                        genericRes.header('Content-Type', 'application/json');
+                        genericRes.status(200).send(JSON.stringify({ success: false, error: 'Internal RPC error' }));
+                        return;
+                    }
+                }
                 // 1. Verifica se é WebSocket upgrade para hot reload
                 if (pathname === '/hweb-hotreload/' && genericReq.headers.upgrade === 'websocket' && hotReloadManager) {
                     // Framework vai chamar o evento 'upgrade' do servidor HTTP

package/dist/rpc/server.d.ts

@@ -0,0 +1,11 @@
+import { RpcResponsePayload } from './types';
+import type { GenericRequest } from '../types/framework';
+export interface RpcExecutionContext {
+    /** absolute project root (same as options.dir in start()) */
+    projectDir: string;
+    /** allow override for tests */
+    allowedServerDirs?: string[];
+    /** real incoming request (so cookies/headers/session work) */
+    request?: GenericRequest;
+}
+export declare function executeRpc(ctx: RpcExecutionContext, payload: any): Promise<RpcResponsePayload>;

package/dist/rpc/server.js

@@ -0,0 +1,167 @@
+"use strict";
+/*
+ * This file is part of the HightJS Project.
+ * Copyright (c) 2025 itsmuzin
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.executeRpc = executeRpc;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const http_1 = require("../api/http");
+const DEFAULT_ALLOWED_SERVER_DIRS = ['src/backend'];
+function normalizeToPosix(p) {
+    return p.replace(/\\/g, '/');
+}
+function isDisallowedPathInput(file) {
+    if (!file)
+        return true;
+    if (file.includes('\u0000'))
+        return true;
+    // disallow protocol-like or absolute paths (Windows drive letters included)
+    if (/^[a-zA-Z]+:/.test(file))
+        return true;
+    if (file.startsWith('/') || file.startsWith('\\'))
+        return true;
+    return false;
+}
+function validatePayload(payload) {
+    return (payload &&
+        typeof payload === 'object' &&
+        typeof payload.file === 'string' &&
+        typeof payload.fn === 'string' &&
+        Array.isArray(payload.args));
+}
+function tryResolveWithinAllowedDirs(projectDir, allowedDirs, requestedFile) {
+    const req = requestedFile.replace(/\\/g, '/').replace(/^\.(?:\/|\\)/, '');
+    for (const d of allowedDirs) {
+        const baseAbs = path_1.default.resolve(projectDir, d);
+        // Interpret client path as relative to src/web (where it's typically authored)
+        const fromWebAbs = path_1.default.resolve(projectDir, 'src/web', req);
+        // Map: <project>/src/backend/*  (coming from ../../backend/* from web code)
+        const mappedFromWebAbs = fromWebAbs.replace(path_1.default.resolve(projectDir, 'backend') + path_1.default.sep, path_1.default.resolve(projectDir, 'src', 'backend') + path_1.default.sep);
+        // Also accept callers passing a backend-relative path like "./auth" or "auth"
+        const fromBackendAbs = path_1.default.resolve(baseAbs, req);
+        const candidateAbsList = [mappedFromWebAbs, fromBackendAbs];
+        for (const candidateAbs of candidateAbsList) {
+            const baseWithSep = baseAbs.endsWith(path_1.default.sep) ? baseAbs : baseAbs + path_1.default.sep;
+            if (!candidateAbs.startsWith(baseWithSep) && candidateAbs !== baseAbs)
+                continue;
+            if (!fs_1.default.existsSync(baseAbs))
+                continue;
+            return candidateAbs;
+        }
+    }
+    return null;
+}
+function toCookies(cookieHeader) {
+    if (!cookieHeader)
+        return {};
+    const out = {};
+    for (const part of cookieHeader.split(';')) {
+        const idx = part.indexOf('=');
+        if (idx === -1)
+            continue;
+        const k = part.slice(0, idx).trim();
+        const v = part.slice(idx + 1).trim();
+        if (k)
+            out[k] = v;
+    }
+    return out;
+}
+// Keep this for fallback when ctx.request isn't provided
+function buildRpcRequestFromPayload(payload) {
+    const headers = {};
+    const rawHeaders = payload.request?.headers || {};
+    for (const [k, v] of Object.entries(rawHeaders)) {
+        headers[k.toLowerCase()] = v;
+    }
+    const cookieHeader = headers['cookie'] ?? undefined;
+    const req = {
+        method: payload.request?.method || 'RPC',
+        // HightJSRequest validates URLs; keep it safe & local.
+        url: payload.request?.url || 'http://localhost/_rpc',
+        headers,
+        body: null,
+        query: {},
+        params: {},
+        cookies: payload.request?.cookies || toCookies(cookieHeader),
+        raw: null
+    };
+    return new http_1.HightJSRequest(req);
+}
+async function executeRpc(ctx, payload) {
+    try {
+        if (!validatePayload(payload)) {
+            return { success: false, error: 'Invalid RPC payload' };
+        }
+        const fileInput = payload.file;
+        if (isDisallowedPathInput(fileInput)) {
+            return { success: false, error: 'Invalid file path' };
+        }
+        const allowedDirs = (ctx.allowedServerDirs || [...DEFAULT_ALLOWED_SERVER_DIRS]).map(normalizeToPosix);
+        const absFile = tryResolveWithinAllowedDirs(ctx.projectDir, allowedDirs, fileInput);
+        if (!absFile) {
+            return { success: false, error: 'File not allowed for RPC' };
+        }
+        if (!absFile.startsWith(path_1.default.resolve(ctx.projectDir) + path_1.default.sep)) {
+            return { success: false, error: 'Invalid file path' };
+        }
+        // Ensure fresh code in dev
+        try {
+            const resolved = require.resolve(absFile);
+            if (require.cache[resolved])
+                delete require.cache[resolved];
+        }
+        catch {
+            // ignore
+        }
+        let mod;
+        try {
+            mod = require(absFile);
+        }
+        catch {
+            // try again letting require do extension resolution from absFile without explicit extension
+            try {
+                mod = require(absFile);
+            }
+            catch {
+                return { success: false, error: 'RPC file not found' };
+            }
+        }
+        // Support multiple TS/CJS interop shapes:
+        // - module.exports.fn
+        // - exports.fn
+        // - module.exports.default (function)
+        // - module.exports.default.fn
+        const fnName = payload.fn;
+        const fnValue = (mod && typeof mod[fnName] === 'function' && mod[fnName]) ||
+            (mod?.default && typeof mod.default === 'function' && fnName === 'default' && mod.default) ||
+            (mod?.default && typeof mod.default[fnName] === 'function' && mod.default[fnName]) ||
+            undefined;
+        if (typeof fnValue !== 'function') {
+            return { success: false, error: `RPC function not found: ${fnName}` };
+        }
+        const rpcRequest = ctx.request ? new http_1.HightJSRequest(ctx.request) : buildRpcRequestFromPayload(payload);
+        const result = await fnValue(rpcRequest, ...payload.args);
+        return { success: true, return: result };
+    }
+    catch (err) {
+        const message = typeof err?.message === 'string' ? err.message : 'Unknown RPC error';
+        return { success: false, error: message };
+    }
+}

package/dist/rpc/types.d.ts

@@ -0,0 +1,23 @@
+export declare const RPC_ENDPOINT: "/api/rpc";
+export type RpcArgs = unknown[];
+export interface RpcRequestPayload {
+    file: string;
+    fn: string;
+    args: RpcArgs;
+    /** Optional: minimal request data so server can provide a HightJSRequest to the called function */
+    request?: {
+        url?: string;
+        method?: string;
+        headers?: Record<string, string>;
+        cookies?: Record<string, string>;
+    };
+}
+export type RpcSuccessResponse = {
+    success: true;
+    return: unknown;
+};
+export type RpcErrorResponse = {
+    success: false;
+    error: string;
+};
+export type RpcResponsePayload = RpcSuccessResponse | RpcErrorResponse;

package/dist/rpc/types.js

@@ -0,0 +1,20 @@
+"use strict";
+/*
+ * This file is part of the HightJS Project.
+ * Copyright (c) 2025 itsmuzin
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RPC_ENDPOINT = void 0;
+exports.RPC_ENDPOINT = '/api/rpc';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hightjs",
-  "version": "1.0.7",
+  "version": "1.1.0",
   "description": "HightJS is a high-level framework for building web applications with ease and speed. It provides a robust set of tools and features to streamline development and enhance productivity.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -72,11 +72,15 @@
     "@types/react": "^19.2.0",
     "@types/react-dom": "^19.2.0",
     "@types/ws": "^8.18.1",
+    "jest": "^30.1.3",
+    "ts-jest": "^29.4.4",
+    "@types/jest": "^30.0.0",
     "ts-loader": "^9.5.4",
     "ts-node": "^10.9.2",
     "typescript": "^5.9.3"
   },
   "scripts": {
-    "build": "tsc"
+    "build": "tsc",
+    "test": "jest"
   }
 }

package/src/client/client.ts

@@ -20,6 +20,5 @@ export { Link } from '../components/Link';
 export { RouteConfig, Metadata } from "../types";
 export { router } from './clientRouter';
 
-
-
-
+// RPC (client-side)
+export { importServer } from './rpc';

package/src/client/entry.client.tsx

@@ -481,7 +481,7 @@ function initializeClient() {
         }
 
         const initialData = deobfuscateData(obfuscated);
-        console.log(initialData)
+
         if (!initialData) {
             console.error('[hweb] Failed to parse initial data.');
             return;

package/src/client/rpc.ts

@@ -0,0 +1,101 @@
+/*
+ * This file is part of the HightJS Project.
+ * Copyright (c) 2025 itsmuzin
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import type { RpcRequestPayload, RpcResponsePayload } from '../rpc/types';
+import { RPC_ENDPOINT } from '../rpc/types';
+
+function asErrorMessage(err: unknown): string {
+    if (err instanceof Error) return err.message;
+    try {
+        return String(err);
+    } catch {
+        return 'Unknown error';
+    }
+}
+
+/**
+ * `importServer("src/backend/index.ts")` returns a Proxy where every property is
+ * a function that performs a POST to `/api/rpc`.
+ *
+ * Security note: the server will still validate allowlisted directories.
+ * @param {string} file
+ */
+export function importServer<T extends Record<string, any> = Record<string, any>>(file: string): T {
+    if (!file) {
+        throw new Error('importServer(file) requires a non-empty string');
+    }
+
+    const handler: ProxyHandler<any> = {
+        get(_target, prop) {
+            // allow tooling & debugging
+            if (prop === '__file') return file;
+            if (prop === 'then') return undefined; // prevent await Proxy issues
+
+            const fnName = String(prop);
+
+            return async (...args: any[]) => {
+                const payload: RpcRequestPayload = {
+                    file,
+                    fn: fnName,
+                    args,
+                    request: {
+                        url: typeof window !== 'undefined' ? window.location.href : undefined,
+                        method: 'RPC',
+                        headers: {
+                            // useful for server-side auth/session logic
+                            ...(typeof navigator !== 'undefined' ? { 'user-agent': navigator.userAgent } : {}),
+                            // forward cookies so server can reconstruct request.cookies if needed
+                            ...(typeof document !== 'undefined' ? { cookie: document.cookie } : {})
+                        }
+                    }
+                };
+
+                let res: Response;
+                try {
+                    res = await fetch(RPC_ENDPOINT, {
+                        method: 'POST',
+                        headers: {
+                            'Content-Type': 'application/json'
+                        },
+                        body: JSON.stringify(payload)
+                    });
+                } catch (err) {
+                    throw new Error(asErrorMessage(err));
+                }
+
+                let data: RpcResponsePayload;
+                try {
+                    data = (await res.json()) as RpcResponsePayload;
+                } catch {
+                    throw new Error('Invalid JSON response from RPC');
+                }
+
+                if (!data || typeof data !== 'object' || typeof (data as any).success !== 'boolean') {
+                    throw new Error('Invalid RPC response shape');
+                }
+
+                if (data.success) {
+                    return (data as any).return;
+                }
+
+                throw new Error((data as any).error || 'RPC Error');
+            };
+        }
+    };
+
+    return new Proxy({}, handler) as T;
+}

package/src/index.ts

@@ -46,6 +46,10 @@ import {FrameworkAdapterFactory} from './adapters/factory';
 import {GenericRequest, GenericResponse} from './types/framework';
 import Console, {Colors} from "./api/console"
 
+// RPC
+import { executeRpc } from './rpc/server';
+import { RPC_ENDPOINT } from './rpc/types';
+
 // Exporta apenas os tipos e classes para o backend
 export { HightJSRequest, HightJSResponse };
 export type { BackendRouteConfig, BackendHandler };
@@ -369,17 +373,38 @@ export default function hweb(options: HightJSOptions) {
         },
         getRequestHandler: (): RequestHandler => {
             return async (req: any, res: any) => {
-                // Detecta automaticamente o framework e cria o adapter apropriado
+                // Detecta o framework e cria request/response genéricos
                 const adapter = FrameworkAdapterFactory.detectFramework(req, res);
-                const genericReq = adapter.parseRequest(req);
-                const genericRes = adapter.createResponse(res);
+                const genericReq: GenericRequest = adapter.parseRequest(req);
+                const genericRes: GenericResponse = adapter.createResponse(res);
 
                 // Adiciona informações do hweb na requisição genérica
                 (genericReq as any).hwebDev = dev;
                 (genericReq as any).hotReloadManager = hotReloadManager;
 
-                const {pathname} = new URL(genericReq.url, `http://${genericReq.headers.host || 'localhost'}`);
-                const method = genericReq.method.toUpperCase();
+                const {hostname} = req.headers;
+                const method = (genericReq.method || 'GET').toUpperCase();
+                const pathname = new URL(genericReq.url, `http://${hostname}:${port}`).pathname;
+
+                // RPC endpoint (antes das rotas de backend)
+                if (pathname === RPC_ENDPOINT && method === 'POST') {
+                    try {
+                        const result = await executeRpc(
+                            {
+                                projectDir: dir,
+                                request: genericReq
+                            },
+                            genericReq.body
+                        );
+                        genericRes.header('Content-Type', 'application/json');
+                        genericRes.status(200).send(JSON.stringify(result));
+                        return;
+                    } catch (error) {
+                        genericRes.header('Content-Type', 'application/json');
+                        genericRes.status(200).send(JSON.stringify({ success: false, error: 'Internal RPC error' }));
+                        return;
+                    }
+                }
 
                 // 1. Verifica se é WebSocket upgrade para hot reload
                 if (pathname === '/hweb-hotreload/' && genericReq.headers.upgrade === 'websocket' && hotReloadManager) {

package/src/rpc/server.ts

@@ -0,0 +1,191 @@
+/*
+ * This file is part of the HightJS Project.
+ * Copyright (c) 2025 itsmuzin
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { RpcRequestPayload, RpcResponsePayload } from './types';
+import { HightJSRequest } from '../api/http';
+import type { GenericRequest } from '../types/framework';
+
+const DEFAULT_ALLOWED_SERVER_DIRS = ['src/backend'] as const;
+
+function normalizeToPosix(p: string): string {
+    return p.replace(/\\/g, '/');
+}
+
+function isDisallowedPathInput(file: string): boolean {
+    if (!file) return true;
+    if (file.includes('\u0000')) return true;
+    // disallow protocol-like or absolute paths (Windows drive letters included)
+    if (/^[a-zA-Z]+:/.test(file)) return true;
+    if (file.startsWith('/') || file.startsWith('\\')) return true;
+    return false;
+}
+
+function validatePayload(payload: any): payload is RpcRequestPayload {
+    return (
+        payload &&
+        typeof payload === 'object' &&
+        typeof payload.file === 'string' &&
+        typeof payload.fn === 'string' &&
+        Array.isArray(payload.args)
+    );
+}
+
+export interface RpcExecutionContext {
+    /** absolute project root (same as options.dir in start()) */
+    projectDir: string;
+    /** allow override for tests */
+    allowedServerDirs?: string[];
+    /** real incoming request (so cookies/headers/session work) */
+    request?: GenericRequest;
+}
+
+function tryResolveWithinAllowedDirs(projectDir: string, allowedDirs: string[], requestedFile: string): string | null {
+    const req = requestedFile.replace(/\\/g, '/').replace(/^\.(?:\/|\\)/, '');
+
+    for (const d of allowedDirs) {
+        const baseAbs = path.resolve(projectDir, d);
+
+        // Interpret client path as relative to src/web (where it's typically authored)
+        const fromWebAbs = path.resolve(projectDir, 'src/web', req);
+
+        // Map: <project>/src/backend/*  (coming from ../../backend/* from web code)
+        const mappedFromWebAbs = fromWebAbs.replace(
+            path.resolve(projectDir, 'backend') + path.sep,
+            path.resolve(projectDir, 'src', 'backend') + path.sep
+        );
+
+        // Also accept callers passing a backend-relative path like "./auth" or "auth"
+        const fromBackendAbs = path.resolve(baseAbs, req);
+
+        const candidateAbsList = [mappedFromWebAbs, fromBackendAbs];
+
+        for (const candidateAbs of candidateAbsList) {
+            const baseWithSep = baseAbs.endsWith(path.sep) ? baseAbs : baseAbs + path.sep;
+            if (!candidateAbs.startsWith(baseWithSep) && candidateAbs !== baseAbs) continue;
+            if (!fs.existsSync(baseAbs)) continue;
+            return candidateAbs;
+        }
+    }
+
+    return null;
+}
+
+function toCookies(cookieHeader: string | undefined): Record<string, string> {
+    if (!cookieHeader) return {};
+    const out: Record<string, string> = {};
+    for (const part of cookieHeader.split(';')) {
+        const idx = part.indexOf('=');
+        if (idx === -1) continue;
+        const k = part.slice(0, idx).trim();
+        const v = part.slice(idx + 1).trim();
+        if (k) out[k] = v;
+    }
+    return out;
+}
+
+// Keep this for fallback when ctx.request isn't provided
+function buildRpcRequestFromPayload(payload: RpcRequestPayload): HightJSRequest {
+    const headers: Record<string, string | string[]> = {};
+    const rawHeaders = payload.request?.headers || {};
+    for (const [k, v] of Object.entries(rawHeaders)) {
+        headers[k.toLowerCase()] = v;
+    }
+
+    const cookieHeader = (headers['cookie'] as string | undefined) ?? undefined;
+
+    const req: GenericRequest = {
+        method: payload.request?.method || 'RPC',
+        // HightJSRequest validates URLs; keep it safe & local.
+        url: payload.request?.url || 'http://localhost/_rpc',
+        headers,
+        body: null,
+        query: {},
+        params: {},
+        cookies: payload.request?.cookies || toCookies(cookieHeader),
+        raw: null
+    };
+
+    return new HightJSRequest(req);
+}
+
+export async function executeRpc(ctx: RpcExecutionContext, payload: any): Promise<RpcResponsePayload> {
+    try {
+        if (!validatePayload(payload)) {
+            return { success: false, error: 'Invalid RPC payload' };
+        }
+
+        const fileInput = payload.file;
+        if (isDisallowedPathInput(fileInput)) {
+            return { success: false, error: 'Invalid file path' };
+        }
+
+        const allowedDirs = (ctx.allowedServerDirs || [...DEFAULT_ALLOWED_SERVER_DIRS]).map(normalizeToPosix);
+        const absFile = tryResolveWithinAllowedDirs(ctx.projectDir, allowedDirs, fileInput);
+        if (!absFile) {
+            return { success: false, error: 'File not allowed for RPC' };
+        }
+
+        if (!absFile.startsWith(path.resolve(ctx.projectDir) + path.sep)) {
+            return { success: false, error: 'Invalid file path' };
+        }
+
+        // Ensure fresh code in dev
+        try {
+            const resolved = require.resolve(absFile);
+            if (require.cache[resolved]) delete require.cache[resolved];
+        } catch {
+            // ignore
+        }
+
+        let mod: any;
+        try {
+            mod = require(absFile);
+        } catch {
+            // try again letting require do extension resolution from absFile without explicit extension
+            try {
+                mod = require(absFile);
+            } catch {
+                return { success: false, error: 'RPC file not found' };
+            }
+        }
+
+        // Support multiple TS/CJS interop shapes:
+        // - module.exports.fn
+        // - exports.fn
+        // - module.exports.default (function)
+        // - module.exports.default.fn
+        const fnName = payload.fn;
+        const fnValue =
+            (mod && typeof mod[fnName] === 'function' && mod[fnName]) ||
+            (mod?.default && typeof mod.default === 'function' && fnName === 'default' && mod.default) ||
+            (mod?.default && typeof mod.default[fnName] === 'function' && mod.default[fnName]) ||
+            undefined;
+
+        if (typeof fnValue !== 'function') {
+            return { success: false, error: `RPC function not found: ${fnName}` };
+        }
+
+        const rpcRequest = ctx.request ? new HightJSRequest(ctx.request) : buildRpcRequestFromPayload(payload);
+        const result = await fnValue(rpcRequest, ...payload.args);
+        return { success: true, return: result };
+    } catch (err: any) {
+        const message = typeof err?.message === 'string' ? err.message : 'Unknown RPC error';
+        return { success: false, error: message };
+    }
+}

package/src/rpc/types.ts

@@ -0,0 +1,45 @@
+/*
+ * This file is part of the HightJS Project.
+ * Copyright (c) 2025 itsmuzin
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+export const RPC_ENDPOINT = '/api/rpc' as const;
+
+export type RpcArgs = unknown[];
+
+export interface RpcRequestPayload {
+    file: string;
+    fn: string;
+    args: RpcArgs;
+    /** Optional: minimal request data so server can provide a HightJSRequest to the called function */
+    request?: {
+        url?: string;
+        method?: string;
+        headers?: Record<string, string>;
+        cookies?: Record<string, string>;
+    };
+}
+
+export type RpcSuccessResponse = {
+    success: true;
+    return: unknown;
+};
+
+export type RpcErrorResponse = {
+    success: false;
+    error: string;
+};
+
+export type RpcResponsePayload = RpcSuccessResponse | RpcErrorResponse;