@thednp/rpc 0.0.13 → 0.1.1

package/dist/index.mjs

@@ -1,260 +1,268 @@
 import { loadConfigFromFile, mergeConfig } from "vite";
-import { resolve } from "node:path";
+import { join, resolve } from "node:path";
 import process from "node:process";
 import { existsSync } from "node:fs";
-import { getClientModules, scanForServerFiles, serverFunctionsMap } from "@thednp/rpc/server";
+import { readdir } from "node:fs/promises";
+import { createRPCMiddleware } from "@thednp/rpc/express";
 //#region src/options.ts
 const defaultRPCOptions = {
 	rpcPrefix: "__rpc",
-	adapter: "express"
-};
-const defaultMiddlewareOptions = {
-	rpcPrefix: void 0,
-	path: void 0,
-	origin: void 0
+	adapter: "express",
+	serverFiles: "exact",
+	scanRoot: void 0
 };
 //#endregion
-//#region src/express/helpers.ts
+//#region src/constants.ts
+const NO_SERVER_FUNCTION_FOUND = "No server function found.";
+const ERROR_LOADING_FILE = "Error loading file:";
+/** Error message when a value fails the safe-identifier validation. @param label - What kind of value was being validated. @param name - The rejected value */
+const INVALID_IDENTIFIER = (label, name) => `Invalid ${label}: "${name}" must match /^[A-Za-z_$][A-Za-z0-9_$]*$/`;
+/** Error message when a value fails the safe-path-segment validation. @param label - What kind of value was being validated. @param segment - The rejected value */
+const INVALID_PATH_SEGMENT = (label, segment) => `Invalid ${label}: "${segment}" must match /^[A-Za-z0-9_$][A-Za-z0-9_$/-]*$/`;
+/** Warning message when a specified RPC config file cannot be resolved on disk. @param configFile - The requested config filename. @param configFilePath - The resolved absolute path */
+const CONFIG_FILE_NOT_FOUND = (configFile, configFilePath) => `  ⚠︎ The specified RPC config file ${configFile} cannot be found at ${configFilePath}, loading the defaults..`;
+const NO_CONFIG_FOUND = ` ⚡︎ No RPC config found, loading the defaults..`;
+const FAILED_LOAD_CONFIG = ` ⚠︎ Failed to load RPC config:`;
+/** Error template for duplicate server function names across files. @param name - The duplicate registered name */
+const DUPLICATE_FUNCTION_NAME = (name) => `Duplicate server function "${name}" detected. Each server function must have a unique name. Remove or rename the duplicate.`;
+//#endregion
+//#region src/functionsMap.ts
+const serverFunctionsMap = /* @__PURE__ */ new Map();
+//#endregion
+//#region src/validate.ts
+const SAFE_IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+const SAFE_PATH_SEGMENT = /^[A-Za-z0-9_$@][A-Za-z0-9_$@/-]*$/;
+const CREDENTIALS_VALUES = [
+	"same-origin",
+	"include",
+	"omit"
+];
 /**
-* Reads and parses the HTTP request body from an Express or Node IncomingMessage.
-* If a body parser middleware (e.g. express.json()) already consumed the stream,
-* uses the pre-parsed body from `req.body`.
-* @param req - Express or Node.js IncomingMessage
-* @returns A promise resolving to the parsed body with its content type
+* Validates that a string is a safe JavaScript identifier.
+* Used to prevent code injection when interpolating export names into generated client code.
+* @param name - The string to validate
+* @param label - Human-readable label for error messages (e.g. "export name")
+* @returns The validated name if it passes
+* @throws Error if the name contains characters outside /^[A-Za-z_$][A-Za-z0-9_$]*$/
 */
-const readBody = (req) => {
-	return new Promise((resolve, reject) => {
-		if (hasPreParsedBody(req) && req.body !== void 0) {
-			const isJSON = (req.headers["content-type"]?.toLowerCase() || "").includes("json");
-			resolve({
-				contentType: isJSON ? "application/json" : "text/plain",
-				data: isJSON ? req.body : String(req.body)
-			});
-			return;
-		}
-		let body = "";
-		const toggleListeners = (add) => {
-			const method = add ? "on" : "off";
-			req[method]("data", onData);
-			req[method]("end", onEnd);
-			req[method]("error", onError);
-		};
-		const onData = (chunk) => {
-			body += chunk.toString();
-		};
-		const onEnd = () => {
-			toggleListeners();
-			const isJSON = (req.headers["content-type"]?.toLowerCase() || "").includes("json");
-			try {
-				const data = JSON.parse(body);
-				resolve({
-					contentType: isJSON ? "application/json" : "text/plain",
-					data
-				});
-			} catch (_e) {
-				resolve({
-					contentType: "text/plain",
-					data: String(body)
-				});
-			}
-		};
-		const onError = (err) => {
-			toggleListeners();
-			reject(err);
-		};
-		toggleListeners(true);
-	});
-};
+function validateIdentifier(name, label) {
+	if (!SAFE_IDENTIFIER.test(name)) throw new Error(INVALID_IDENTIFIER(label, name));
+	return name;
+}
 /**
-* Type guard that checks whether a request is an Express Request (has `originalUrl`).
-* @param req - A Node IncomingMessage or Express Request
-* @returns True if the request is an Express Request
+* Validates that a string is a safe path segment for RPC routing.
+* Allows alphanumeric characters, underscores, dollar signs, at signs, hyphens, and forward slashes.
+* @param segment - The string to validate
+* @param label - Human-readable label for error messages (e.g. "rpcPrefix")
+* @returns The validated segment if it passes
+* @throws Error if the segment contains disallowed characters
 */
-const isExpressRequest = (req) => {
-	return "originalUrl" in req;
-};
+function validatePathSegment(segment, label) {
+	if (!SAFE_PATH_SEGMENT.test(segment)) throw new Error(INVALID_PATH_SEGMENT(label, segment));
+	return segment;
+}
 /**
-* Type guard that checks whether a response is an Express Response (has `json` and `send` methods).
-* @param res - A Node ServerResponse or Express Response
-* @returns True if the response is an Express Response
+* Validates and normalizes the credentials option.
+* Accepts "same-origin", "include", or "omit"; defaults to "same-origin" when undefined.
+* @param value - Credentials value to validate
+* @returns The validated credentials string
+* @throws Error if the value is not one of the accepted credentials
 */
-const isExpressResponse = (res) => {
-	return "json" in res && "send" in res;
-};
+function validateCredentials(value) {
+	const creds = value || "same-origin";
+	if (!CREDENTIALS_VALUES.includes(creds)) throw new Error(`Invalid credentials: "${value}" must be one of ${CREDENTIALS_VALUES.join(", ")}`);
+	return creds;
+}
 /**
-* Type guard that checks whether a request has a pre-parsed body (`body` property).
-* Used to detect if a body-parser middleware already consumed the stream.
-* @param req - A Node IncomingMessage or Express Request
-* @returns True if the request has a body property
+* Validates and normalizes the HTTP method option for a server function.
+* Accepts "GET" or "POST" (case-insensitive); defaults to "POST" when undefined.
+* @param value - Method value to validate
+* @returns The validated uppercase method string
+* @throws Error if the value is not "GET" or "POST"
 */
-const hasPreParsedBody = (req) => {
-	return "body" in req;
-};
+function validateMethod(value) {
+	const method = (value || "POST").toUpperCase();
+	if (method !== "GET" && method !== "POST") throw new Error(`Invalid method: "${value}" must be one of GET, POST`);
+	return method;
+}
+//#endregion
+//#region src/getClientModules.ts
 /**
-* Extracts normalized request details from an Express or Node IncomingMessage.
-* Parses the URL to extract pathname, search string, and search params.
-* @param request - Express or Node.js request object
-* @returns Normalized request details including URL, headers, and method
+* Generates a JavaScript client module string for a single server function.
+* All interpolated values are validated to prevent code injection.
+* @param fnName - Registered RPC function name (validated as path segment)
+* @param fnEntry - Export name used in the generated module (validated as identifier)
+* @param options - Content type, credentials, and RPC prefix settings
+* @returns A string of JavaScript code exporting the client stub
 */
-const getRequestDetails = (request) => {
-	const rawUrl = isExpressRequest(request) ? request.originalUrl : request.url;
-	const url = new URL(rawUrl, "http://localhost");
-	return {
-		url: url.pathname,
-		search: url.search,
-		searchParams: url.searchParams,
-		headers: request.headers,
-		method: request.method
-	};
+const getModule = (fnName, fnEntry, options) => {
+	const safeFnName = validatePathSegment(fnName, "function name");
+	const safeFnEntry = validateIdentifier(fnEntry, "export name");
+	const safePrefix = validatePathSegment(options.rpcPrefix, "rpcPrefix");
+	const credentials = validateCredentials(options.credentials);
+	const method = validateMethod(options.method);
+	let body = "";
+	let headers = "{}";
+	switch (options.contentType) {
+		case "text/plain":
+			body = `args[0]`;
+			headers = `{ 'Content-Type': 'text/plain' }`;
+			break;
+		case "multipart/form-data":
+			body = `args[0]`;
+			headers = `{}`;
+			break;
+		default:
+			body = `JSON.stringify(args)`;
+			headers = `{ 'Content-Type': 'application/json' }`;
+	}
+	if (method === "GET") {
+		body = `JSON.stringify(args)`;
+		headers = `{}`;
+	}
+	return `
+export const ${safeFnEntry} = (...args) => {
+  const body = ${body};
+  const headers = ${headers};
+  const prefix = "${safePrefix}";
+  const name = "${safeFnName}";
+  const credentials = "${credentials}";
+  const method = "${method}";
+  return innerModule(body, headers, credentials, prefix, name, method);
+}`.trim();
 };
 /**
-* Wraps an Express or Node ServerResponse with a uniform API for setting headers,
-* status codes, and sending JSON responses. Handles the Express vs raw Node API differences.
-* @param response - Express or Node.js server response object
-* @returns A ResponseDetails object with setHeader, setStatusCode, and sendResponse helpers
+* Generates the complete client-side module bundle by iterating all registered server functions
+* and producing fetch-based stubs for each. The result is transformed by Vite (or Oxc) during
+* the dev server or production build.
+* @param initialOptions - Plugin options containing rpcPrefix and optional adapter
+* @returns A string of JavaScript code with all client RPC modules and their import dependencies
 */
-const getResponseDetails = (response) => {
-	const isResponseSent = response.headersSent || response.writableEnded;
-	const setHeader = (name, value) => {
-		if (isExpressResponse(response)) response.header(name, value);
-		else response.setHeader(name, value);
-	};
-	const setStatusCode = (code) => {
-		if (isExpressResponse(response)) response.status(code);
-		else response.statusCode = code;
-	};
-	const sendResponse = (code, output) => {
-		setStatusCode(code);
-		setHeader("Content-Type", "application/json");
-		if (isExpressResponse(response)) response.send(JSON.stringify(output));
-		else response.end(JSON.stringify(output));
-	};
-	return {
-		isResponseSent,
-		setHeader,
-		statusCode: response.statusCode,
-		setStatusCode,
-		sendResponse
-	};
+const getClientModules = (initialOptions) => {
+	validatePathSegment(initialOptions.rpcPrefix, "rpcPrefix");
+	return `
+
+import { innerModule } from "@thednp/rpc/helpers";
+${Array.from(serverFunctionsMap.entries()).filter(([, entry]) => entry.exportName).map(([registeredName, entry]) => getModule(registeredName, entry.exportName, {
+		...initialOptions,
+		...entry.options || {}
+	})).join("\n")}`.trim();
 };
 //#endregion
-//#region src/tools.ts
+//#region src/server-helpers.ts
+const GLOB_REGEX = /^.+\.server\.(ts|js|mjs|mts)$/;
 /**
-* Escapes special regex metacharacters in a string.
-* Used to safely embed user-configurable values (like rpcPrefix) into regular expressions,
-* preventing ReDoS and regex injection attacks.
-* @param s - The raw string to escape
-* @returns The escaped string safe for use in new RegExp()
+* Recursively walks `dir` and collects absolute paths to files whose
+* basename matches the `*.server.{ts,js,mjs,mts}` glob pattern.
 */
-function escapeRegExp(s) {
-	return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-}
-//#endregion
-//#region src/constants.ts
-const FUNCTION_NOT_FOUND = "Function not found";
-const METHOD_NOT_ALLOWED = "Method Not Allowed";
-const REQUEST_FORBIDDEN = "Forbidden";
-const INTERNAL_SERVER_ERROR = "Internal Server Error";
-const CLIENT_DISCONNECTED = "client disconnected";
-/** Returns a warning when a middleware name is reused, preventing registration conflicts. @param name - The duplicate middleware name */
-const MIDDLEWARE_NAME_USED = (name) => `The middleware name "${name}" is already used.`;
-/** Warning message when a specified RPC config file cannot be resolved on disk. @param configFile - The requested config filename. @param configFilePath - The resolved absolute path */
-const CONFIG_FILE_NOT_FOUND = (configFile, configFilePath) => `  ⚠︎ The specified RPC config file ${configFile} cannot be found at ${configFilePath}, loading the defaults..`;
-const NO_CONFIG_FOUND = ` ⚡︎ No RPC config found, loading the defaults..`;
-const FAILED_LOAD_CONFIG = ` ⚠︎ Failed to load RPC config:`;
-//#endregion
-//#region src/express/createMiddleware.ts
-let middlewareCount = 0;
-const middlewareStack = /* @__PURE__ */ new Set();
-/**
-* Creates an Express middleware with optional path and rpcPrefix filtering.
-* Middleware names are deduplicated — reusing a name throws an error.
-* Prefix and path regexes are compiled once at creation time (hoisted) for performance.
-* @param initialOptions - Options for rpcPrefix, path matching, and the handler function
-* @returns An Express middleware function
-*/
-const createMiddleware = (initialOptions = {}) => {
-	const options = Object.assign({}, defaultMiddlewareOptions, initialOptions);
-	const middlewareName = options.name;
-	const rpcPrefix = options.rpcPrefix;
-	const path = options.path;
-	const handler = options.handler;
-	let name = middlewareName;
-	if (!name) {
-		name = "viteRPCMiddleware-" + middlewareCount;
-		middlewareCount += 1;
+const walkGlobFiles = async (dir) => {
+	const results = [];
+	const stack = [dir];
+	while (stack.length) {
+		const current = stack.pop();
+		let entries;
+		try {
+			entries = await readdir(current, { withFileTypes: true });
+		} catch (_e) {
+			continue;
+		}
+		for (const entry of entries) {
+			const fullPath = join(current, entry.name);
+			if (entry.isFile() && GLOB_REGEX.test(entry.name)) results.push(fullPath);
+			else if (entry.isDirectory()) stack.push(fullPath);
+		}
 	}
-	if (middlewareStack.has(name)) throw new Error(MIDDLEWARE_NAME_USED(name));
-	middlewareStack.add(name);
-	const prefixRegex = rpcPrefix ? new RegExp(`^/${escapeRegExp(rpcPrefix)}/`) : null;
-	const pathMatcher = path ? typeof path === "string" ? new RegExp(path) : path : null;
-	const middlewareHandler = async (req, res, next) => {
-		const { url } = getRequestDetails(req);
-		if (serverFunctionsMap.size === 0) await scanForServerFiles();
-		if (!handler) return next?.();
-		if (pathMatcher && !pathMatcher.test(url)) return next?.();
-		if (prefixRegex && !prefixRegex.test(url)) return next?.();
-		await handler(req, res, next);
-	};
-	Object.defineProperty(middlewareHandler, "name", { value: name });
-	return middlewareHandler;
+	return results;
 };
+//#endregion
+//#region src/scanForServerFiles.ts
+let isScanned = false;
+/** Absolute ids (normalized) of the scanned server function files. */
+const scannedServerFiles = /* @__PURE__ */ new Set();
+const EXACT_NAMES = [
+	"server.ts",
+	"server.js",
+	"server.mjs",
+	"server.mts"
+];
 /**
-* Creates the Express RPC middleware that routes incoming requests to registered server functions.
-* Reads the request body, dispatches to the matching function via serverFunctionsMap,
-* and sends the JSON-serialized result. Handles client disconnection via abort signals.
-* @param initialOptions - Options including rpcPrefix for URL routing
-* @returns An Express middleware function
+* Scans `src/api/` (or an explicit `scanRoot`) for server function files
+* and populates the global `serverFunctionsMap` with their exported functions.
+* Uses Vite's SSR module loading to resolve and execute each file.
+*
+* Supports two matching modes via `config.serverFiles`:
+*   `"exact"` — classic `server.ts|js|mjs|mts` names in the api directory
+*   `"glob"` — recursively walking `scanRoot` to match `*.server.{ts,js,mjs,mts}`
+* @param initialCfg - Optional Vite config overrides (root, base, server, serverFiles, scanRoot)
+* @param devServer - Optional running Vite dev server instance; when provided, skips creating a new one
 */
-const createRPCMiddleware = (initialOptions = {}) => {
-	const options = Object.assign({}, defaultMiddlewareOptions, { rpcPrefix: defaultRPCOptions.rpcPrefix }, initialOptions);
-	const rpcPrefix = options.rpcPrefix;
-	const prefixRegex = rpcPrefix ? new RegExp(`^/${escapeRegExp(rpcPrefix)}/`) : null;
-	const prefixReplace = `/${rpcPrefix}/`;
-	return createMiddleware({
-		...options,
-		handler: async (req, res, _next) => {
-			const { url: path, searchParams } = getRequestDetails(req);
-			const { sendResponse } = getResponseDetails(res);
-			if (prefixRegex && !prefixRegex.test(path)) return;
-			const origin = options.origin;
-			const requestOrigin = req.headers.origin;
-			if (origin && requestOrigin && requestOrigin !== origin) {
-				sendResponse(403, { error: REQUEST_FORBIDDEN });
-				return;
+const scanForServerFiles = async (initialCfg, devServer) => {
+	if (isScanned && !devServer) return;
+	const { createServer, normalizePath } = await import("vite");
+	const config = !initialCfg && !devServer || !initialCfg ? {
+		root: process.cwd(),
+		base: process.env.BASE || "/",
+		server: { middlewareMode: true }
+	} : { ...initialCfg };
+	let server = devServer;
+	if (!server) server = await createServer({
+		server: {
+			...config.server,
+			ws: false
+		},
+		appType: "custom",
+		base: config.base || "/",
+		root: config.root || process.cwd(),
+		configFile: false,
+		optimizeDeps: { noDiscovery: true },
+		ssr: { optimizeDeps: { noDiscovery: true } }
+	});
+	const root = config.root || process.cwd();
+	const resolvedScanRoot = resolve(root, config.scanRoot ?? join(root, "src", "api"));
+	const serverFiles = config.serverFiles ?? "exact";
+	const seenNames = /* @__PURE__ */ new Set();
+	let files;
+	try {
+		if (serverFiles === "glob") files = await walkGlobFiles(resolvedScanRoot);
+		else files = (await readdir(resolvedScanRoot, { withFileTypes: true })).filter((f) => EXACT_NAMES.includes(f.name)).map((f) => join(resolvedScanRoot, f.name));
+	} catch (_e) {
+		files = [];
+	}
+	try {
+		for (const file of files) {
+			scannedServerFiles.add(normalizePath(file));
+			let moduleExports;
+			try {
+				moduleExports = await server.ssrLoadModule(file);
+			} catch (error) {
+				console.error(ERROR_LOADING_FILE, file, error);
+				continue;
 			}
-			const functionName = path.replace(prefixReplace, "");
-			const serverFunction = serverFunctionsMap.get(functionName);
-			if (!serverFunction) {
-				sendResponse(404, { error: FUNCTION_NOT_FOUND });
+			const moduleEntries = Object.entries(moduleExports);
+			if (!moduleEntries.length) {
+				console.warn(NO_SERVER_FUNCTION_FOUND);
 				return;
 			}
-			try {
-				const method = serverFunction.options?.method || "POST";
-				if (req.method?.toUpperCase() !== method) {
-					sendResponse(405, { error: METHOD_NOT_ALLOWED });
-					return;
-				}
-				let args = [];
-				if (method === "GET") {
-					const raw = searchParams.get("args");
-					if (raw) args = JSON.parse(raw);
-				} else {
-					const body = await readBody(req);
-					args = Array.isArray(body.data) ? body.data : [body.data];
+			for (const [exportName, exportValue] of moduleEntries) {
+				const registeredName = exportValue.name;
+				if (seenNames.has(registeredName)) {
+					if (process.env.NODE_ENV !== "production") throw new Error(DUPLICATE_FUNCTION_NAME(registeredName));
+					console.warn(DUPLICATE_FUNCTION_NAME(registeredName));
+					continue;
 				}
-				const { data, cancel } = serverFunction.handler(...args);
-				const onClose = () => cancel(CLIENT_DISCONNECTED);
-				req.on("close", onClose);
-				const result = await data;
-				req.off("close", onClose);
-				if (!res.headersSent) sendResponse(200, { data: result });
-			} catch (err) {
-				console.error(String(err));
-				sendResponse(500, { error: INTERNAL_SERVER_ERROR });
+				seenNames.add(registeredName);
+				serverFunctionsMap.set(registeredName, {
+					name: registeredName,
+					handler: exportValue,
+					options: exportValue?.options,
+					exportName
+				});
 			}
 		}
-	});
+	} finally {
+		if (!devServer && server) await server.close();
+		isScanned = true;
+	}
 };
 //#endregion
 //#region src/index.ts
@@ -352,7 +360,7 @@ const loadRPCConfig = async (configFile) => {
 * @returns A Vite plugin object
 */
 function rpcPlugin(devOptions = {}) {
-	let options;
+	let options = mergeConfig(defaultRPCOptions, devOptions);
 	let config;
 	let viteServer;
 	let isOxc = true;
@@ -367,18 +375,41 @@ function rpcPlugin(devOptions = {}) {
 		async configureServer(server) {
 			viteServer = server;
 			const { adapter: _adapter, ...rest } = options;
-			if (serverFunctionsMap.size === 0) await scanForServerFiles(config, viteServer);
+			if (serverFunctionsMap.size === 0) {
+				const scanCfg = {
+					...config,
+					serverFiles: options.serverFiles,
+					scanRoot: options.scanRoot
+				};
+				await scanForServerFiles(scanCfg, viteServer);
+			}
 			server.middlewares.use(createRPCMiddleware(rest));
 		},
 		async buildStart() {
 			const viteVersion = this.meta?.viteVersion;
 			isOxc = Number(viteVersion[0]) >= 8;
-			if (!viteServer && config) await scanForServerFiles(config);
+			if (!viteServer && config) {
+				const scanCfg = {
+					...config,
+					serverFiles: options.serverFiles,
+					scanRoot: options.scanRoot
+				};
+				await scanForServerFiles(scanCfg);
+			}
 		},
 		async transform(code, id, ops) {
 			if (!code.includes("createServerFunction") || ops?.ssr || code.includes("createServerFunction") && typeof process === "undefined") return null;
-			if (serverFunctionsMap.size === 0) await scanForServerFiles(config);
 			const vite = await import("vite");
+			if (serverFunctionsMap.size === 0) {
+				const scanCfg = {
+					...config,
+					serverFiles: options.serverFiles,
+					scanRoot: options.scanRoot
+				};
+				await scanForServerFiles(scanCfg);
+			}
+			const idPath = vite.normalizePath(id.split("?")[0]);
+			if (!scannedServerFiles.has(idPath)) return null;
 			const transformer = isOxc ? "transformWithOxc" : "transformWithEsbuild";
 			const langProp = isOxc ? "lang" : "loader";
 			const source = getClientModules({