web_plsql 0.18.0 → 1.2.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,293 @@
+import express from 'express';
+import fs from 'node:fs';
+import os from 'node:os';
+import readline from 'node:readline';
+import {AdminContext} from '../server/adminContext.js';
+import {traceManager} from '../util/traceManager.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
+ */
+
+/**
+ * @typedef {import('../util/statsManager.js').Bucket} Bucket
+ */
+
+/**
+ * @typedef {object} StatsSummary
+ * @property {Date} startTime - Server start time.
+ * @property {number} totalRequests - Total requests handled.
+ * @property {number} totalErrors - Total errors encountered.
+ * @property {number} avgResponseTime - Lifetime average response time.
+ * @property {number} minResponseTime - Lifetime minimum response time.
+ * @property {number} maxResponseTime - Lifetime maximum response time.
+ * @property {number} maxRequestsPerSecond - Lifetime maximum requests per second.
+ * @property {object} maxMemory - Lifetime memory extremes.
+ * @property {number} maxMemory.heapUsedMax - Maximum heap used.
+ * @property {number} maxMemory.heapTotalMax - Maximum heap total.
+ * @property {number} maxMemory.rssMax - Maximum RSS.
+ * @property {number} maxMemory.externalMax - Maximum external memory.
+ * @property {object} cpu - Lifetime CPU extremes.
+ * @property {number} cpu.max - Max CPU.
+ * @property {number} cpu.userMax - Max user CPU.
+ * @property {number} cpu.systemMax - Max system CPU.
+ */
+
+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
+ * @param {string} [filter] - Optional filter string
+ * @returns {Promise<string[]>} - The lines
+ */
+const readLastLines = async (filePath, n = 100, filter = '') => {
+	if (!fs.existsSync(filePath)) {
+		return [];
+	}
+
+	const fileStream = fs.createReadStream(filePath);
+	const rl = readline.createInterface({
+		input: fileStream,
+		crlfDelay: Infinity,
+	});
+
+	const filterLower = filter.toLowerCase();
+
+	/** @type {string[]} */
+	const lines = [];
+	for await (const line of rl) {
+		if (!filter || line.toLowerCase().includes(filterLower)) {
+			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 cache = AdminContext.caches[index];
+		const name = cache?.poolName ?? `pool-${index}`;
+		const p = /** @type {import('oracledb').Pool & {getStatistics?: () => Record<string, unknown>}} */ (pool);
+		const procStats = cache?.procedureNameCache.getStats();
+		const argStats = cache?.argumentCache.getStats();
+
+		return {
+			name,
+			stats: typeof p.getStatistics === 'function' ? p.getStatistics() : null,
+			connectionsOpen: pool.connectionsOpen,
+			connectionsInUse: pool.connectionsInUse,
+			cache: {
+				procedureName: {
+					size: cache?.procedureNameCache.keys().length ?? 0,
+					hits: procStats?.hits ?? 0,
+					misses: procStats?.misses ?? 0,
+				},
+				argument: {
+					size: cache?.argumentCache.keys().length ?? 0,
+					hits: argStats?.hits ?? 0,
+					misses: argStats?.misses ?? 0,
+				},
+			},
+		};
+	});
+
+	const memUsage = process.memoryUsage();
+	const systemMemoryUsed = os.totalmem() - os.freemem();
+	const cpuUsage = process.cpuUsage();
+	const summary = /** @type {StatsSummary} */ (AdminContext.statsManager.getSummary());
+
+	res.json({
+		version,
+		status: AdminContext.paused ? 'paused' : 'running',
+		uptime,
+		startTime: AdminContext.startTime,
+		intervalMs: AdminContext.statsManager.config.intervalMs,
+		metrics: {
+			requestCount: summary.totalRequests,
+			errorCount: summary.totalErrors,
+			avgResponseTime: summary.avgResponseTime,
+			minResponseTime: summary.minResponseTime,
+			maxResponseTime: summary.maxResponseTime,
+			maxRequestsPerSecond: summary.maxRequestsPerSecond,
+		},
+		history: AdminContext.statsManager.getHistory(),
+		pools: poolStats,
+		system: {
+			nodeVersion: process.version,
+			platform: process.platform,
+			arch: process.arch,
+			cpuCores: os.cpus().length,
+			memory: {
+				rss: systemMemoryUsed,
+				heapTotal: memUsage.heapTotal,
+				heapUsed: memUsage.heapUsed,
+				external: memUsage.external,
+				totalMemory: os.totalmem(),
+				...summary.maxMemory,
+			},
+			cpu: {
+				user: cpuUsage.user,
+				system: cpuUsage.system,
+				max: summary.cpu.max,
+				userMax: summary.cpu.userMax,
+				systemMax: summary.cpu.systemMax,
+			},
+		},
+		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 filter = typeof req.query.filter === 'string' ? req.query.filter : '';
+		const logFile = 'error.json.log';
+		const lines = await readLastLines(logFile, limit, filter);
+
+		/** @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 filter = typeof req.query.filter === 'string' ? req.query.filter : '';
+		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, filter);
+		res.json(lines.reverse());
+	} catch (err) {
+		res.status(500).json({error: String(err)});
+	}
+});
+
+// GET /api/cache - REMOVED (Merged into /api/status)
+
+// 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'});
+	}
+});
+
+// GET /api/trace/status
+handlerAdmin.get('/api/trace/status', (_req, res) => {
+	res.json({enabled: traceManager.isEnabled()});
+});
+
+// POST /api/trace/toggle
+handlerAdmin.post('/api/trace/toggle', (req, res) => {
+	const body = /** @type {unknown} */ (req.body);
+	const enabled = body && typeof body === 'object' && 'enabled' in body && typeof body.enabled === 'boolean' ? body.enabled : false;
+	traceManager.setEnabled(enabled);
+	res.json({enabled: traceManager.isEnabled()});
+});
+
+// GET /api/trace/logs
+handlerAdmin.get('/api/trace/logs', async (req, res) => {
+	try {
+		const limit = Number(req.query.limit) || 100;
+		const filter = typeof req.query.filter === 'string' ? req.query.filter : '';
+		const logFile = traceManager.getFilePath();
+		const lines = await readLastLines(logFile, limit, filter);
+
+		/** @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)});
+	}
+});
+
+// POST /api/trace/clear
+handlerAdmin.post('/api/trace/clear', (_req, res) => {
+	traceManager.clear();
+	res.json({message: 'Traces cleared'});
+});

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,7 @@ 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';
 
 /**
  * @typedef {import('express').Request} Request
@@ -15,15 +16,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} */
@@ -58,7 +60,7 @@ const getError = (req, error) => {
 		/* v8 ignore stop */
 	}
 
-	return getFormattedMessage({type: 'error', timestamp, message, req, environment, sql, bind});
+	return {type: 'error', timestamp, message, req, environment, sql, bind};
 };
 
 /**
@@ -70,12 +72,35 @@ 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);
+
+	// 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;
 };