web_plsql 0.17.1 → 1.0.0

package/src/bin/load-test.js

@@ -0,0 +1,202 @@
+/**
+ * @file Load testing CLI tool for web_plsql.
+ * This tool simulates parallel traffic to the middleware and provides real-time statistics.
+ */
+
+import {performance} from 'node:perf_hooks';
+
+/**
+ * @typedef {object} Metrics
+ * @property {number} total Total requests made.
+ * @property {number} success Number of successful requests (2xx).
+ * @property {number} error Number of failed requests.
+ * @property {number} minLatency Minimum latency in milliseconds.
+ * @property {number} maxLatency Maximum latency in milliseconds.
+ * @property {number} sumLatency Sum of all latencies for average calculation.
+ * @property {Map<string|number, number>} statusCodes Frequency of status codes.
+ */
+
+/** @type {Metrics} */
+const metrics = {
+	total: 0,
+	success: 0,
+	error: 0,
+	minLatency: Number.MAX_SAFE_INTEGER,
+	maxLatency: 0,
+	sumLatency: 0,
+	statusCodes: new Map(),
+};
+
+let stopped = false;
+
+/**
+ * Parse CLI arguments.
+ * @returns {{ url: string, concurrency: number, duration: number }} Options object.
+ */
+function parseArgs() {
+	const args = process.argv.slice(2);
+	const options = {
+		url: '',
+		concurrency: 10,
+		duration: 30,
+	};
+
+	for (let i = 0; i < args.length; i++) {
+		const arg = args[i];
+		const nextArg = args[i + 1] ?? '';
+
+		if (arg === '--url' || arg === '-u') {
+			options.url = nextArg;
+			i++;
+		} else if (arg === '--concurrency' || arg === '-c') {
+			options.concurrency = parseInt(nextArg, 10);
+			i++;
+		} else if (arg === '--duration' || arg === '-d') {
+			options.duration = parseInt(nextArg, 10);
+			i++;
+		}
+	}
+
+	if (!options.url) {
+		console.error('Usage: node src/bin/load-test.js --url <url> [-c concurrency] [-d duration]');
+		process.exit(1);
+	}
+
+	return options;
+}
+
+/**
+ * Record a single request's result.
+ * @param {boolean} ok Whether the request succeeded.
+ * @param {number} latency Latency in milliseconds.
+ * @param {number|string} status Status code or error string.
+ */
+function recordMetrics(ok, latency, status) {
+	metrics.total++;
+	if (ok) {
+		metrics.success++;
+	} else {
+		metrics.error++;
+	}
+
+	metrics.minLatency = Math.min(metrics.minLatency, latency);
+	metrics.maxLatency = Math.max(metrics.maxLatency, latency);
+	metrics.sumLatency += latency;
+
+	const count = metrics.statusCodes.get(status) ?? 0;
+	metrics.statusCodes.set(status, count + 1);
+}
+
+/**
+ * Clear the console and move cursor to the top.
+ */
+function clearConsole() {
+	process.stdout.write('\x1b[2J\x1b[0;0H');
+}
+
+/**
+ * Render the dashboard.
+ * @param {number} elapsed Elapsed time in seconds.
+ * @param {number} duration Total duration in seconds.
+ * @param {string} url Target URL.
+ * @param {number} concurrency Concurrency level.
+ */
+function renderDashboard(elapsed, duration, url, concurrency) {
+	clearConsole();
+	const rps = elapsed > 0 ? (metrics.total / elapsed).toFixed(1) : '0.0';
+	const avgLatency = metrics.total > 0 ? (metrics.sumLatency / metrics.total).toFixed(1) : '0.0';
+	const progress = Math.min(100, (elapsed / duration) * 100).toFixed(1);
+	const barWidth = 30;
+	const filledWidth = Math.floor((barWidth * parseFloat(progress)) / 100);
+	const bar = '='.repeat(filledWidth) + '>'.padEnd(barWidth - filledWidth, ' ');
+
+	console.log('\x1b[1m\x1b[36mWeb PL/SQL Load Test\x1b[0m');
+	console.log('='.repeat(40));
+	console.log(`\x1b[33mURL:\x1b[0m         ${url}`);
+	console.log(`\x1b[33mConcurrency:\x1b[0m ${concurrency}`);
+	console.log(`\x1b[33mDuration:\x1b[0m    ${duration}s`);
+	console.log('='.repeat(40));
+	console.log(`\x1b[32mProgress:\x1b[0m    [${bar}] ${progress}% (${elapsed.toFixed(1)}s)`);
+	console.log(`\x1b[32mRPS:\x1b[0m         ${rps}`);
+	console.log(`\x1b[32mTotal:\x1b[0m       ${metrics.total}`);
+	console.log(`\x1b[32mSuccess:\x1b[0m     ${metrics.success}`);
+	console.log(`\x1b[31mErrors:\x1b[0m      ${metrics.error}`);
+	console.log('='.repeat(40));
+	console.log('\x1b[1mLatency (ms)\x1b[0m');
+	console.log(`\x1b[34mAvg:\x1b[0m ${avgLatency.padStart(8)}`);
+	console.log(`\x1b[34mMin:\x1b[0m ${(metrics.minLatency === Number.MAX_SAFE_INTEGER ? 0 : metrics.minLatency).toFixed(1).padStart(8)}`);
+	console.log(`\x1b[34mMax:\x1b[0m ${metrics.maxLatency.toFixed(1).padStart(8)}`);
+	console.log('='.repeat(40));
+
+	if (metrics.statusCodes.size > 0) {
+		console.log('\x1b[1mStatus Codes\x1b[0m');
+		for (const [code, count] of metrics.statusCodes.entries()) {
+			const numericCode = typeof code === 'number' ? code : 0;
+			const color = numericCode >= 200 && numericCode < 300 ? '\x1b[32m' : '\x1b[31m';
+			console.log(`${color}${code}\x1b[0m: ${count}`);
+		}
+	}
+}
+
+/**
+ * Worker function to maintain concurrency.
+ * @param {string} url The target URL.
+ * @param {number} endTime The end time in milliseconds.
+ */
+async function runWorker(url, endTime) {
+	while (performance.now() < endTime && !stopped) {
+		const start = performance.now();
+		try {
+			const res = await fetch(url, {
+				signal: AbortSignal.timeout(10000), // 10s timeout
+			});
+			const latency = performance.now() - start;
+			recordMetrics(res.ok, latency, res.status);
+			// Consume body to free up connection
+			await res.arrayBuffer();
+		} catch (err) {
+			const latency = performance.now() - start;
+			const errorName = err instanceof Error ? err.name : 'UnknownError';
+			recordMetrics(false, latency, errorName === 'TimeoutError' ? 'Timeout' : 'NetworkErr');
+		}
+	}
+}
+
+/**
+ * Main function.
+ */
+async function main() {
+	const options = parseArgs();
+	const startTime = performance.now();
+	const endTime = startTime + options.duration * 1000;
+
+	console.log(`Starting load test on ${options.url}...`);
+
+	// Start workers
+	const workers = Array.from({length: options.concurrency}, () => runWorker(options.url, endTime));
+
+	// Dashboard refresh interval
+	const uiInterval = setInterval(() => {
+		const elapsed = (performance.now() - startTime) / 1000;
+		renderDashboard(elapsed, options.duration, options.url, options.concurrency);
+	}, 200);
+
+	// Handle Ctrl+C
+	process.on('SIGINT', () => {
+		stopped = true;
+		console.log('\nStopping...');
+	});
+
+	await Promise.all(workers);
+	clearInterval(uiInterval);
+
+	// Final render
+	const finalElapsed = (performance.now() - startTime) / 1000;
+	renderDashboard(finalElapsed, options.duration, options.url, options.concurrency);
+	console.log('\n\x1b[1m\x1b[32mTest Complete!\x1b[0m\n');
+}
+
+main().catch((/** @type {unknown} */ err) => {
+	console.error('Fatal error:', err);
+	process.exit(1);
+});

package/src/handler/handlerAdmin.js

@@ -0,0 +1,198 @@
+import express from 'express';
+import fs from 'node:fs';
+import readline from 'node:readline';
+import {AdminContext} from '../server/server.js';
+import {getVersion} from '../version.js';
+
+const version = getVersion();
+import {forceShutdown} from '../util/shutdown.js';
+
+/**
+ * @typedef {import('express').Request} Request
+ * @typedef {import('express').Response} Response
+ * @typedef {import('express').NextFunction} NextFunction
+ */
+
+export const handlerAdmin = express.Router();
+
+/**
+ * Helper to read last N lines of a file
+ * @param {string} filePath - Path to file
+ * @param {number} n - Number of lines
+ * @returns {Promise<string[]>} - The lines
+ */
+const readLastLines = async (filePath, n = 100) => {
+	if (!fs.existsSync(filePath)) {
+		return [];
+	}
+
+	const fileStream = fs.createReadStream(filePath);
+	const rl = readline.createInterface({
+		input: fileStream,
+		crlfDelay: Infinity,
+	});
+
+	/** @type {string[]} */
+	const lines = [];
+	for await (const line of rl) {
+		lines.push(line);
+		if (lines.length > n) {
+			lines.shift();
+		}
+	}
+	return lines;
+};
+
+// GET /api/status
+handlerAdmin.get('/api/status', (_req, res) => {
+	const uptime = (new Date().getTime() - AdminContext.startTime.getTime()) / 1000;
+
+	const poolStats = AdminContext.pools.map((pool, index) => {
+		const name = AdminContext.caches[index]?.poolName ?? `pool-${index}`;
+		const p = /** @type {import('oracledb').Pool & {getStatistics?: () => Record<string, unknown>}} */ (pool);
+		return {
+			name,
+			stats: typeof p.getStatistics === 'function' ? p.getStatistics() : null,
+			connectionsOpen: pool.connectionsOpen,
+			connectionsInUse: pool.connectionsInUse,
+		};
+	});
+
+	const memUsage = process.memoryUsage();
+	const cpuUsage = process.cpuUsage();
+
+	res.json({
+		version,
+		status: AdminContext.paused ? 'paused' : 'running',
+		uptime,
+		startTime: AdminContext.startTime,
+		metrics: {
+			...AdminContext.metrics,
+			avgResponseTime: AdminContext.metrics.requestCount > 0 ? AdminContext.metrics.totalDuration / AdminContext.metrics.requestCount : 0,
+		},
+		pools: poolStats,
+		system: {
+			nodeVersion: process.version,
+			platform: process.platform,
+			arch: process.arch,
+			memory: {
+				rss: memUsage.rss,
+				heapTotal: memUsage.heapTotal,
+				heapUsed: memUsage.heapUsed,
+				external: memUsage.external,
+			},
+			cpu: {
+				user: cpuUsage.user,
+				system: cpuUsage.system,
+			},
+		},
+		config: AdminContext.config
+			? {
+					...AdminContext.config,
+					adminPassword: AdminContext.config.adminPassword ? '********' : undefined,
+					routePlSql: AdminContext.config.routePlSql.map((p) => ({
+						...p,
+						password: '********',
+					})),
+				}
+			: null,
+	});
+});
+
+// GET /api/logs/error
+handlerAdmin.get('/api/logs/error', async (req, res) => {
+	try {
+		const limit = Number(req.query.limit) || 100;
+		const logFile = 'error.json.log';
+		const lines = await readLastLines(logFile, limit);
+
+		/** @type {Record<string, unknown>[]} */
+		const logs = [];
+		for (const line of lines) {
+			try {
+				const parsed = /** @type {unknown} */ (JSON.parse(line));
+				if (parsed && typeof parsed === 'object') {
+					logs.push(/** @type {Record<string, unknown>} */ (parsed));
+				}
+			} catch (e) {
+				// ignore
+			}
+		}
+
+		res.json(logs.reverse());
+	} catch (err) {
+		res.status(500).json({error: String(err)});
+	}
+});
+
+// GET /api/logs/access
+handlerAdmin.get('/api/logs/access', async (req, res) => {
+	try {
+		const limit = Number(req.query.limit) || 100;
+		const logFile = AdminContext.config?.loggerFilename ?? 'access.log';
+
+		if (!AdminContext.config?.loggerFilename) {
+			res.json({message: 'Access logging not enabled'});
+			return;
+		}
+
+		const lines = await readLastLines(logFile, limit);
+		res.json(lines.reverse());
+	} catch (err) {
+		res.status(500).json({error: String(err)});
+	}
+});
+
+// GET /api/cache
+handlerAdmin.get('/api/cache', (_req, res) => {
+	const caches = AdminContext.caches.map((c) => ({
+		poolName: c.poolName,
+		procedureNameCache: {
+			size: c.procedureNameCache.keys().length,
+			stats: c.procedureNameCache.getStats(),
+		},
+		argumentCache: {
+			size: c.argumentCache.keys().length,
+			stats: c.argumentCache.getStats(),
+		},
+	}));
+	res.json(caches);
+});
+
+// POST /api/cache/clear
+handlerAdmin.post('/api/cache/clear', (req, res) => {
+	const body = /** @type {unknown} */ (req.body);
+	const poolName = body && typeof body === 'object' && 'poolName' in body && typeof body.poolName === 'string' ? body.poolName : undefined;
+
+	let cleared = 0;
+	AdminContext.caches.forEach((c) => {
+		if (!poolName || c.poolName === poolName) {
+			c.procedureNameCache.clear();
+			cleared++;
+			c.argumentCache.clear();
+			cleared++;
+		}
+	});
+
+	res.json({message: `Cleared ${cleared} caches`});
+});
+
+// POST /api/server/:action
+handlerAdmin.post('/api/server/:action', (req, res) => {
+	const action = req.params.action;
+
+	if (action === 'stop') {
+		res.json({message: 'Server shutting down...'});
+		setTimeout(() => {
+			forceShutdown();
+		}, 100);
+	} else if (action === 'pause') {
+		AdminContext.paused = true;
+		res.json({message: 'Server paused', status: 'paused'});
+	} else if (action === 'resume') {
+		AdminContext.paused = false;
+		res.json({message: 'Server resumed', status: 'running'});
+	} else {
+		res.status(400).json({error: 'Invalid action'});
+	}
+});

package/src/handler/plsql/cgi.js

@@ -109,7 +109,7 @@ export const getCGI = (req, doctable, cgi) => {
 	const CGI = {
 		SERVER_PORT: typeof req.socket.localPort === 'number' ? req.socket.localPort.toString() : '',
 		REQUEST_METHOD: req.method,
-		PATH_INFO: Array.isArray(req.params.name) ? req.params.name[0] : req.params.name,
+		PATH_INFO: Array.isArray(req.params.name) ? (req.params.name[0] ?? '') : (req.params.name ?? ''),
 		SCRIPT_NAME: PATH.script,
 		REMOTE_ADDR: (req.ip ?? '').replace('::ffff:', ''),
 		SERVER_PROTOCOL: `${PROTOCOL}/${req.httpVersion}`,

package/src/handler/plsql/errorPage.js

@@ -7,6 +7,8 @@ import {RequestError} from './requestError.js';
 import {getFormattedMessage, logToFile} from '../../util/trace.js';
 import {errorToString} from '../../util/errorToString.js';
 import {getHtmlPage} from '../../util/html.js';
+import {jsonLogger} from '../../util/jsonLogger.js';
+import {AdminContext} from '../../server/server.js';
 
 /**
  * @typedef {import('express').Request} Request
@@ -15,15 +17,16 @@ import {getHtmlPage} from '../../util/html.js';
  * @typedef {import('../../types.js').environmentType} environmentType
  * @typedef {import('../../types.js').configPlSqlHandlerType} configPlSqlHandlerType
  * @typedef {{html: string; text: string}} outputType
+ * @typedef {import('../../util/trace.js').messageType} messageType
  */
 
 /**
- *	Show an error page
+ *	Get error data
  *	@param {Request} req - The req object represents the HTTP request.
  *	@param {unknown} error - The error.
- *	@returns {outputType} - The output.
+ *	@returns {messageType} - The output.
  */
-const getError = (req, error) => {
+const getErrorData = (req, error) => {
 	let timestamp = new Date();
 	let message = '';
 	/** @type {environmentType | null} */
@@ -36,33 +39,29 @@ const getError = (req, error) => {
 	// what type of Error did we receive
 	if (error instanceof ProcedureError) {
 		timestamp = error.timestamp;
-		/* istanbul ignore next */
 		message = error.stack ?? '';
 		environment = error.environment;
 		sql = error.sql;
 		bind = error.bind;
 	} else if (error instanceof RequestError) {
 		timestamp = error.timestamp;
-		/* istanbul ignore next */
 		message = error.stack ?? '';
 	} else if (error instanceof Error) {
-		/* istanbul ignore next */
 		message = errorToString(error);
 	} else {
 		if (typeof error === 'string') {
-			/* istanbul ignore next */
 			message = `${error}\n`;
 		}
+		/* v8 ignore start - unreachable code: creating Error without throwing */
 		try {
-			/* istanbul ignore next */
 			new Error();
 		} catch (err) {
-			/* istanbul ignore next */
 			message += errorToString(err);
 		}
+		/* v8 ignore stop */
 	}
 
-	return getFormattedMessage({type: 'error', timestamp, message, req, environment, sql, bind});
+	return {type: 'error', timestamp, message, req, environment, sql, bind};
 };
 
 /**
@@ -74,12 +73,38 @@ const getError = (req, error) => {
  * @param {unknown} error - The error.
  */
 export const errorPage = (req, res, options, error) => {
-	// get error message
-	const {html, text} = getError(req, error);
+	// get error data
+	const errorData = getErrorData(req, error);
+
+	// Update metrics
+	AdminContext.metrics.errorCount++;
+
+	// get formatted message
+	const {html, text} = getFormattedMessage(errorData);
 
 	// trace to file
 	logToFile(text);
 
+	// json log
+	const firstLine = errorData.message.split('\n')[0];
+	jsonLogger.log({
+		timestamp: errorData.timestamp?.toISOString() ?? new Date().toISOString(),
+		type: 'error',
+		message: firstLine ?? '',
+		req: {
+			method: req.method,
+			url: req.originalUrl,
+			ip: req.ip ?? '',
+			userAgent: req.get('user-agent') ?? '',
+		},
+		details: {
+			fullMessage: errorData.message,
+			sql: errorData.sql,
+			bind: errorData.bind,
+			environment: errorData.environment,
+		},
+	});
+
 	// console
 	console.error(text);
 

package/src/handler/plsql/handlerPlSql.js

@@ -9,6 +9,7 @@ import url from 'node:url';
 import {processRequest} from './request.js';
 import {RequestError} from './requestError.js';
 import {errorPage} from './errorPage.js';
+import {Cache} from '../../util/cache.js';
 
 /**
  * @typedef {import('express').RequestHandler} RequestHandler
@@ -24,11 +25,13 @@ import {errorPage} from './errorPage.js';
  * express.Request handler
  * @param {Request} req - The req object represents the HTTP request.
  * @param {Response} res - The res object represents the HTTP response that an Express app sends when it gets an HTTP request.
- * @param {NextFunction} next - The next function.
+ * @param {NextFunction} _next - The next function.
  * @param {Pool} connectionPool - The connection pool.
  * @param {configPlSqlHandlerType} options - the options for the middleware.
+ * @param {Cache<string>} procedureNameCache - The procedure name cache.
+ * @param {Cache<import('./procedureNamed.js').argsType>} argumentCache - The argument cache.
  */
-const requestHandler = async (req, res, next, connectionPool, options) => {
+const requestHandler = async (req, res, _next, connectionPool, options, procedureNameCache, argumentCache) => {
 	try {
 		// should we switch to the default page if there is one defined
 		if (typeof req.params.name !== 'string' || req.params.name.length === 0) {
@@ -41,24 +44,47 @@ const requestHandler = async (req, res, next, connectionPool, options) => {
 			}
 		} else {
 			// request handler
-			await processRequest(req, res, options, connectionPool);
+			await processRequest(req, res, options, connectionPool, procedureNameCache, argumentCache);
 		}
 	} catch (err) {
 		errorPage(req, res, options, err);
 	}
 };
 
+/**
+ * @typedef {import('express').RequestHandler & {
+ *   procedureNameCache: Cache<string>;
+ *   argumentCache: Cache<import('./procedureNamed.js').argsType>;
+ * }} WebPlSqlRequestHandler
+ */
+
 /**
  * Express middleware.
  *
  * @param {Pool} connectionPool - The connection pool.
  * @param {configPlSqlHandlerType} config - The configuration options.
- * @returns {RequestHandler} - The handler.
+ * @returns {WebPlSqlRequestHandler} - The handler.
  */
 export const handlerWebPlSql = (connectionPool, config) => {
 	debug('options', config);
 
-	return (req, res, next) => {
-		void requestHandler(req, res, next, connectionPool, config);
+	/** @type {Cache<string>} */
+	const procedureNameCache = new Cache();
+	/** @type {Cache<import('./procedureNamed.js').argsType>} */
+	const argumentCache = new Cache();
+
+	/**
+	 * @param {Request} req - The request.
+	 * @param {Response} res - The response.
+	 * @param {NextFunction} next - The next function.
+	 */
+	const handler = (req, res, next) => {
+		void requestHandler(req, res, next, connectionPool, config, procedureNameCache, argumentCache);
 	};
+
+	// Expose caches for Admin Console
+	handler.procedureNameCache = procedureNameCache;
+	handler.argumentCache = argumentCache;
+
+	return handler;
 };

package/src/handler/plsql/parsePage.js

@@ -55,7 +55,7 @@ export const parsePage = (text) => {
 					{
 						const cookie = parseCookie(header.value);
 						debug(`oracle header "set-cookie" with value "${header.value}" was received has been parsed to ${JSON.stringify(cookie)}`);
-						/* istanbul ignore else */
+						/* v8 ignore else - parseCookie validation ensures non-null */
 						if (cookie !== null) {
 							page.head.cookies.push(cookie);
 						} else {
@@ -72,7 +72,7 @@ export const parsePage = (text) => {
 				case 'x-db-content-length':
 					{
 						const contentLength = parseInt(header.value, 10);
-						/* istanbul ignore else */
+						/* v8 ignore else - parseInt validation */
 						if (!Number.isNaN(contentLength)) {
 							page.head.contentLength = contentLength;
 							debug(`oracle header "x-db-content-length" with value "${page.head.contentLength}" was parsed`);
@@ -85,12 +85,12 @@ export const parsePage = (text) => {
 				case 'status':
 					{
 						const statusCode = parseInt(header.value, 10);
-						/* istanbul ignore else */
+						/* v8 ignore else - parseInt validation */
 						if (!Number.isNaN(statusCode)) {
 							page.head.statusCode = statusCode;
 							debug(`oracle header "status" with value "${page.head.statusCode}" was parsed`);
 							const index = header.value.indexOf(' ');
-							/* istanbul ignore else */
+							/* v8 ignore else - status code may not have description */
 							if (index !== -1) {
 								page.head.statusDescription = header.value.substring(index + 1);
 							}
@@ -143,7 +143,7 @@ const getHeader = (line) => {
  */
 const parseCookie = (text) => {
 	// validate
-	/* istanbul ignore next */
+	/* v8 ignore next - input validation */
 	if (typeof text !== 'string' || text.trim().length === 0) {
 		return null;
 	}
@@ -155,8 +155,12 @@ const parseCookie = (text) => {
 	cookieElements = cookieElements.map((element) => element.trim());
 
 	// get name and value
-	const index = cookieElements[0].indexOf('=');
-	/* istanbul ignore next */
+	const firstElement = cookieElements[0];
+	if (!firstElement) {
+		return null;
+	}
+	const index = firstElement.indexOf('=');
+	/* v8 ignore next - cookie format validation */
 	if (index <= 0) {
 		// if the index is -1, there is no equal sign and if it's 0 the name is empty
 		return null;
@@ -164,8 +168,8 @@ const parseCookie = (text) => {
 
 	/** @type {cookieType} */
 	const cookie = {
-		name: cookieElements[0].substring(0, index).trim(),
-		value: cookieElements[0].substring(index + 1).trim(),
+		name: firstElement.substring(0, index).trim(),
+		value: firstElement.substring(index + 1).trim(),
 		options: {},
 	};
 
@@ -179,7 +183,7 @@ const parseCookie = (text) => {
 		} else if (element.toLowerCase().startsWith('domain=')) {
 			cookie.options.domain = element.substring(7);
 		} else if (element.toLowerCase().startsWith('secure=')) {
-			/* istanbul ignore next */
+			/* v8 ignore next - secure cookie attribute */
 			cookie.options.secure = true;
 		} else if (element.toLowerCase().startsWith('expires=')) {
 			const date = tryDecodeDate(element.substring(8));
@@ -203,7 +207,7 @@ const tryDecodeDate = (value) => {
 	try {
 		return new Date(value);
 	} catch (err) {
-		/* istanbul ignore next */
+		/* v8 ignore next - invalid date format */
 		return null;
 	}
 };