web_plsql 1.0.0 → 1.2.0

package/src/server/adminContext.js

@@ -0,0 +1,23 @@
+import {StatsManager} from '../util/statsManager.js';
+
+/**
+ * @typedef {import('oracledb').Pool} Pool
+ * @typedef {import('../types.js').configType} configType
+ * @typedef {import('../handler/plsql/procedureNamed.js').argsType} argsType
+ * @typedef {import('../util/cache.js').Cache<unknown>} Cache
+ */
+
+/**
+ * Global Admin Context
+ */
+export const AdminContext = {
+	startTime: new Date(),
+	/** @type {configType | null} */
+	config: null,
+	/** @type {Pool[]} */
+	pools: [],
+	/** @type {Array<{poolName: string, procedureNameCache: Cache, argumentCache: Cache}>} */
+	caches: [],
+	paused: false,
+	statsManager: new StatsManager(),
+};

package/src/server/server.js

@@ -16,7 +16,7 @@ import {handlerWebPlSql} from '../handler/plsql/handlerPlSql.js';
 import {handlerAdmin} from '../handler/handlerAdmin.js';
 import {readFileSyncUtf8, getJsonFile} from '../util/file.js';
 import {showConfig} from './config.js';
-import {Cache} from '../util/cache.js';
+import {AdminContext} from './adminContext.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -35,30 +35,11 @@ const __dirname = path.dirname(__filename);
 
 /**
  * @typedef {import('express').RequestHandler & {
- *   procedureNameCache: Cache<string>;
- *   argumentCache: Cache<argsType>;
+ *   procedureNameCache: import('../util/cache.js').Cache<string>;
+ *   argumentCache: import('../util/cache.js').Cache<argsType>;
  * }} ExtendedRequestHandler
  */
 
-/**
- * Global Admin Context
- */
-export const AdminContext = {
-	startTime: new Date(),
-	/** @type {configType | null} */
-	config: null,
-	/** @type {Pool[]} */
-	pools: [],
-	/** @type {Array<{poolName: string, procedureNameCache: Cache<string>, argumentCache: Cache<argsType>}>} */
-	caches: [],
-	paused: false,
-	metrics: {
-		requestCount: 0,
-		errorCount: 0,
-		totalDuration: 0,
-	},
-};
-
 /**
  * @typedef {object} webServer - Web server interface.
  * @property {configType} config - Configuration object.
@@ -74,42 +55,6 @@ export const AdminContext = {
  * @property {string} certFilename - cert filename.
  */
 
-/**
- * Admin basic auth middleware
- * @param {Request} req - The request.
- * @param {Response} res - The response.
- * @param {NextFunction} next - The next function.
- */
-const adminAuth = (req, res, next) => {
-	const adminRoute = AdminContext.config?.adminRoute ?? '/admin';
-
-	// Simple pause check for all PL/SQL routes (not admin)
-	if (AdminContext.paused && !req.path.startsWith(adminRoute)) {
-		res.status(503).send('Server Paused');
-		return;
-	}
-
-	// Basic Auth for Admin Route
-	if (req.path.startsWith(adminRoute)) {
-		const user = AdminContext.config?.adminUser;
-		const pass = AdminContext.config?.adminPassword;
-
-		if (user && pass) {
-			const auth = {login: user, password: pass};
-			const b64auth = (req.headers.authorization ?? '').split(' ')[1] ?? '';
-			const [login, password] = Buffer.from(b64auth, 'base64').toString().split(':');
-
-			if (login !== auth.login || password !== auth.password) {
-				res.set('WWW-Authenticate', 'Basic realm="Admin Console"');
-				res.status(401).send('Authentication required.');
-				return;
-			}
-		}
-	}
-
-	next();
-};
-
 /**
  * Create HTTPS server.
  * @param {Express} app - express application
@@ -144,8 +89,43 @@ export const startServer = async (config, ssl) => {
 	// Create express app
 	const app = express();
 
+	// Default middleware
+	app.use(handlerUpload(internalConfig.uploadFileSizeLimit));
+	app.use(express.json({limit: '50mb'}));
+	app.use(express.urlencoded({limit: '50mb', extended: true}));
+	app.use(cookieParser());
+	app.use(compression());
+
 	// Pause & Admin Auth middleware
-	app.use(adminAuth);
+	app.use((req, res, next) => {
+		const adminRoute = internalConfig.adminRoute ?? '/admin';
+
+		// Simple pause check for all PL/SQL routes (not admin)
+		if (AdminContext.paused && !req.path.startsWith(adminRoute)) {
+			res.status(503).send('Server Paused');
+			return;
+		}
+
+		// Basic Auth for Admin Route
+		if (req.path.startsWith(adminRoute)) {
+			const user = internalConfig.adminUser;
+			const pass = internalConfig.adminPassword;
+
+			if (user && pass) {
+				const auth = {login: user, password: pass};
+				const b64auth = (req.headers.authorization ?? '').split(' ')[1] ?? '';
+				const [login, password] = Buffer.from(b64auth, 'base64').toString().split(':');
+
+				if (login !== auth.login || password !== auth.password) {
+					res.set('WWW-Authenticate', 'Basic realm="Admin Console"');
+					res.status(401).send('Authentication required.');
+					return;
+				}
+			}
+		}
+
+		next();
+	});
 
 	// Access log
 	if (internalConfig.loggerFilename.length > 0) {
@@ -155,6 +135,17 @@ export const startServer = async (config, ssl) => {
 	// Admin console
 	const adminRoute = internalConfig.adminRoute ?? '/admin';
 	const adminDirectory = path.resolve(__dirname, '../admin');
+
+	// Ensure trailing slash for admin route to support relative paths
+	app.get(adminRoute, (req, res, next) => {
+		const [path] = req.originalUrl.split('?');
+		if (path === adminRoute) {
+			const query = req.originalUrl.split('?')[1];
+			return res.redirect(adminRoute + '/' + (query ? '?' + query : ''));
+		}
+		next();
+	});
+
 	app.use(adminRoute, handlerAdmin);
 	app.use(adminRoute, express.static(adminDirectory));
 
@@ -163,13 +154,6 @@ export const startServer = async (config, ssl) => {
 		app.use(i.route, express.static(i.directoryPath));
 	}
 
-	// Default middleware
-	app.use(handlerUpload(internalConfig.uploadFileSizeLimit));
-	app.use(express.json({limit: '50mb'}));
-	app.use(express.urlencoded({limit: '50mb', extended: true}));
-	app.use(cookieParser());
-	app.use(compression());
-
 	/** @type {Pool[]} */
 	const connectionPools = [];
 	AdminContext.pools = connectionPools;
@@ -191,17 +175,46 @@ export const startServer = async (config, ssl) => {
 		});
 
 		app.use([`${i.route}/:name`, i.route], (req, res, next) => {
-			AdminContext.metrics.requestCount++;
 			const start = process.hrtime();
 			res.on('finish', () => {
 				const diff = process.hrtime(start);
 				const duration = diff[0] * 1000 + diff[1] / 1_000_000;
-				AdminContext.metrics.totalDuration += duration;
+				AdminContext.statsManager.recordRequest(duration, res.statusCode >= 400);
 			});
 			handler(req, res, next);
 		});
 	}
 
+	// Update pools in StatsManager on each rotation
+	const originalRotate = AdminContext.statsManager.rotateBucket.bind(AdminContext.statsManager);
+	AdminContext.statsManager.rotateBucket = () => {
+		const poolSnapshots = AdminContext.pools.map((pool, index) => {
+			const cache = AdminContext.caches[index];
+			const name = cache?.poolName ?? `pool-${index}`;
+			const procStats = cache?.procedureNameCache.getStats();
+			const argStats = cache?.argumentCache.getStats();
+
+			return {
+				name,
+				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,
+					},
+				},
+			};
+		});
+		originalRotate(poolSnapshots);
+	};
+
 	// create server
 	debug('startServer: createServer');
 	const server = createServer(app, ssl);
@@ -226,6 +239,8 @@ export const startServer = async (config, ssl) => {
 	const shutdown = async () => {
 		debug('startServer: onShutdown');
 
+		AdminContext.statsManager.stop();
+
 		await poolsClose(connectionPools);
 
 		server.close(() => {

package/src/types.js

@@ -133,7 +133,7 @@ export const z$configType = z.strictObject({
 
 /**
  * @typedef {object} pageType - The page.
- * @property {string} body - The body of the page.
+ * @property {string | import('node:stream').Readable} body - The body of the page.
  * @property {object} head - The head of the page.
  * @property {cookieType[]} head.cookies - The cookies.
  * @property {string} [head.contentType] - The content type.

package/src/util/statsManager.js

@@ -0,0 +1,368 @@
+import debugModule from 'debug';
+import os from 'node:os';
+
+const debug = debugModule('webplsql:statsManager');
+
+/**
+ * @typedef {object} StatsConfig
+ * @property {number} intervalMs - Duration of each statistical bucket (default: 5000ms).
+ * @property {number} maxHistoryPoints - Number of buckets to keep in the ring buffer (default: 200).
+ * @property {boolean} sampleSystem - Whether to automatically sample CPU/Memory (default: true).
+ * @property {boolean} samplePools - Whether to automatically sample Oracle pool utilization (default: true).
+ * @property {number} percentilePrecision - Max number of samples per bucket for P95/P99 calculation (default: 1000).
+ */
+
+/**
+ * @typedef {object} CacheStats
+ * @property {number} size - Number of entries.
+ * @property {number} hits - Number of hits.
+ * @property {number} misses - Number of misses.
+ */
+
+/**
+ * @typedef {object} PoolCacheSnapshot
+ * @property {CacheStats} procedureName - Procedure name cache stats.
+ * @property {CacheStats} argument - Argument cache stats.
+ */
+
+/**
+ * @typedef {object} PoolSnapshot
+ * @property {string} name - The pool name.
+ * @property {number} connectionsInUse - Number of active connections.
+ * @property {number} connectionsOpen - Number of open connections.
+ * @property {PoolCacheSnapshot} [cache] - Cache statistics.
+ */
+
+/**
+ * @typedef {object} Bucket
+ * @property {number} timestamp - End time of the bucket.
+ * @property {number} requests - Number of requests.
+ * @property {number} errors - Number of errors.
+ * @property {number} durationMin - Minimum duration.
+ * @property {number} durationMax - Maximum duration.
+ * @property {number} durationAvg - Average duration.
+ * @property {number} durationP95 - 95th percentile duration.
+ * @property {number} durationP99 - 99th percentile duration.
+ * @property {object} system - System metrics.
+ * @property {number} system.cpu - CPU usage percentage.
+ * @property {number} system.heapUsed - Heap used in bytes.
+ * @property {number} system.heapTotal - Heap total in bytes.
+ * @property {number} system.rss - RSS in bytes.
+ * @property {number} system.external - External memory in bytes.
+ * @property {PoolSnapshot[]} pools - Pool utilization snapshots.
+ */
+
+/**
+ * @typedef {object} CurrentBucket
+ * @property {number} count - Number of requests.
+ * @property {number} errors - Number of errors.
+ * @property {number} durationSum - Sum of durations.
+ * @property {number} durationMin - Minimum duration.
+ * @property {number} durationMax - Maximum duration.
+ * @property {number[]} durations - List of durations for percentile calculation.
+ */
+
+/**
+ * @typedef {object} MemoryLifetime
+ * @property {number} heapUsedMax - Max heap used.
+ * @property {number} heapTotalMax - Max heap total.
+ * @property {number} rssMax - Max RSS.
+ * @property {number} externalMax - Max external.
+ */
+
+/**
+ * @typedef {object} LifetimeStats
+ * @property {number} totalRequests - Total requests.
+ * @property {number} totalErrors - Total errors.
+ * @property {number} minDuration - Min duration.
+ * @property {number} maxDuration - Max duration.
+ * @property {number} totalDuration - Total duration.
+ * @property {number} maxRequestsPerSecond - Max requests per second.
+ * @property {MemoryLifetime} memory - Memory extremes.
+ * @property {object} cpu - CPU extremes.
+ * @property {number} cpu.max - Max CPU.
+ * @property {number} cpu.userMax - Max user CPU.
+ * @property {number} cpu.systemMax - Max system CPU.
+ */
+
+/**
+ * @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 {MemoryLifetime} maxMemory - Lifetime memory extremes.
+ * @property {object} cpu - CPU extremes.
+ * @property {number} cpu.max - Max CPU usage percentage.
+ * @property {number} cpu.userMax - Max user CPU usage in microseconds.
+ * @property {number} cpu.systemMax - Max system CPU usage in microseconds.
+ */
+
+/**
+ * Manager for statistical data collection and temporal bucketing.
+ */
+export class StatsManager {
+	/**
+	 * @param {Partial<StatsConfig>} config - Configuration.
+	 */
+	constructor(config = {}) {
+		/** @type {StatsConfig} */
+		this.config = {
+			intervalMs: 5000,
+			maxHistoryPoints: 1000,
+			sampleSystem: true,
+			samplePools: true,
+			percentilePrecision: 1000,
+			...config,
+		};
+
+		this.startTime = new Date();
+
+		/** @type {Bucket[]} */
+		this.history = [];
+
+		/** @type {LifetimeStats} */
+		this.lifetime = {
+			totalRequests: 0,
+			totalErrors: 0,
+			minDuration: -1,
+			maxDuration: -1,
+			totalDuration: 0,
+			maxRequestsPerSecond: 0,
+			memory: {
+				heapUsedMax: 0,
+				heapTotalMax: 0,
+				rssMax: 0,
+				externalMax: 0,
+			},
+			cpu: {
+				max: 0,
+				userMax: 0,
+				systemMax: 0,
+			},
+		};
+
+		/** @type {CurrentBucket} */
+		this._currentBucket = {
+			count: 0,
+			errors: 0,
+			durations: [],
+			durationSum: 0,
+			durationMin: -1,
+			durationMax: -1,
+		};
+
+		this._lastCpuTimes = this._getSystemCpuTimes();
+
+		/** @type {ReturnType<typeof setTimeout> | undefined} */
+		this._timer = undefined;
+		if (this.config.sampleSystem) {
+			this._timer = setInterval(() => {
+				this.rotateBucket();
+			}, this.config.intervalMs);
+			if (this._timer && typeof this._timer.unref === 'function') {
+				this._timer.unref();
+			}
+		}
+	}
+
+	/**
+	 * Reset the current bucket accumulator.
+	 * @private
+	 */
+	_resetBucket() {
+		this._currentBucket = {
+			count: 0,
+			errors: 0,
+			durations: [],
+			durationSum: 0,
+			durationMin: -1,
+			durationMax: -1,
+		};
+	}
+
+	/**
+	 * Record a request event.
+	 * @param {number} duration - Duration in milliseconds.
+	 * @param {boolean} isError - Whether the request was an error.
+	 */
+	recordRequest(duration, isError = false) {
+		this.lifetime.totalRequests++;
+		if (isError) {
+			this.lifetime.totalErrors++;
+		}
+
+		this.lifetime.totalDuration += duration;
+		if (this.lifetime.minDuration < 0 || duration < this.lifetime.minDuration) {
+			this.lifetime.minDuration = duration;
+		}
+		if (this.lifetime.maxDuration < 0 || duration > this.lifetime.maxDuration) {
+			this.lifetime.maxDuration = duration;
+		}
+
+		const b = this._currentBucket;
+		b.count++;
+		if (isError) {
+			b.errors++;
+		}
+
+		b.durationSum += duration;
+		if (b.durationMin < 0 || duration < b.durationMin) {
+			b.durationMin = duration;
+		}
+		if (b.durationMax < 0 || duration > b.durationMax) {
+			b.durationMax = duration;
+		}
+
+		if (b.durations.length < this.config.percentilePrecision) {
+			b.durations.push(duration);
+		}
+	}
+
+	/**
+	 * Get system CPU times.
+	 * @private
+	 * @returns {{user: number, nice: number, sys: number, idle: number, irq: number, total: number}} System CPU times.
+	 */
+	_getSystemCpuTimes() {
+		const cpus = os.cpus();
+		let user = 0;
+		let nice = 0;
+		let sys = 0;
+		let idle = 0;
+		let irq = 0;
+
+		for (const cpu of cpus) {
+			user += cpu.times.user;
+			nice += cpu.times.nice;
+			sys += cpu.times.sys;
+			idle += cpu.times.idle;
+			irq += cpu.times.irq;
+		}
+
+		const total = user + nice + sys + idle + irq;
+		return {user, nice, sys, idle, irq, total};
+	}
+
+	/**
+	 * Calculate CPU usage percentage since last call.
+	 * @private
+	 * @returns {number} CPU usage percentage (0-100).
+	 */
+	_calculateCpuUsage() {
+		const current = this._getSystemCpuTimes();
+		const last = this._lastCpuTimes || {user: 0, nice: 0, sys: 0, idle: 0, irq: 0, total: 0};
+
+		const deltaTotal = current.total - last.total;
+		const deltaIdle = current.idle - last.idle;
+
+		this._lastCpuTimes = current;
+
+		if (deltaTotal <= 0) return 0;
+
+		const percent = ((deltaTotal - deltaIdle) / deltaTotal) * 100;
+		return Math.min(100, Math.max(0, percent));
+	}
+
+	/**
+	 * Rotate the current bucket into history and start a new one.
+	 * @param {PoolSnapshot[]} [poolSnapshots] - Optional pool snapshots to include.
+	 */
+	rotateBucket(poolSnapshots = []) {
+		const b = this._currentBucket;
+		const memUsage = process.memoryUsage();
+		const systemMemoryUsed = os.totalmem() - os.freemem();
+		const cpuUsage = process.cpuUsage();
+		const cpu = this._calculateCpuUsage();
+
+		// Update lifetime extremes
+		const reqPerSec = b.count / (this.config.intervalMs / 1000);
+		this.lifetime.maxRequestsPerSecond = Math.max(this.lifetime.maxRequestsPerSecond, reqPerSec);
+		this.lifetime.memory.heapUsedMax = Math.max(this.lifetime.memory.heapUsedMax, memUsage.heapUsed);
+		this.lifetime.memory.heapTotalMax = Math.max(this.lifetime.memory.heapTotalMax, memUsage.heapTotal);
+		this.lifetime.memory.rssMax = Math.max(this.lifetime.memory.rssMax, systemMemoryUsed);
+		this.lifetime.memory.externalMax = Math.max(this.lifetime.memory.externalMax, memUsage.external);
+		this.lifetime.cpu.max = Math.max(this.lifetime.cpu.max, cpu);
+		this.lifetime.cpu.userMax = Math.max(this.lifetime.cpu.userMax, cpuUsage.user);
+		this.lifetime.cpu.systemMax = Math.max(this.lifetime.cpu.systemMax, cpuUsage.system);
+
+		let p95 = 0;
+		let p99 = 0;
+		if (b.durations.length > 0) {
+			const sorted = [...b.durations].sort((x, y) => x - y);
+			const p95Idx = Math.floor(sorted.length * 0.95);
+			const p99Idx = Math.floor(sorted.length * 0.99);
+			const lastIdx = sorted.length - 1;
+
+			p95 = sorted[p95Idx] ?? sorted[lastIdx] ?? 0;
+			p99 = sorted[p99Idx] ?? sorted[lastIdx] ?? 0;
+		}
+
+		/** @type {Bucket} */
+		const bucket = {
+			timestamp: Date.now(),
+			requests: b.count,
+			errors: b.errors,
+			durationMin: b.durationMin < 0 ? 0 : b.durationMin,
+			durationMax: b.durationMax < 0 ? 0 : b.durationMax,
+			durationAvg: b.count > 0 ? b.durationSum / b.count : 0,
+			durationP95: p95,
+			durationP99: p99,
+			system: {
+				cpu,
+				heapUsed: memUsage.heapUsed,
+				heapTotal: memUsage.heapTotal,
+				rss: systemMemoryUsed,
+				external: memUsage.external,
+			},
+			pools: poolSnapshots,
+		};
+
+		this.history.push(bucket);
+		if (this.history.length > this.config.maxHistoryPoints) {
+			this.history.shift();
+		}
+
+		this._resetBucket();
+		debug('Bucket rotated: %j', bucket);
+	}
+
+	/**
+	 * Stop the background timer.
+	 */
+	stop() {
+		if (this._timer) {
+			clearInterval(this._timer);
+			this._timer = undefined;
+		}
+	}
+
+	/**
+	 * Get lifetime summary.
+	 * @returns {StatsSummary} Summary.
+	 */
+	getSummary() {
+		return {
+			startTime: this.startTime,
+			totalRequests: this.lifetime.totalRequests,
+			totalErrors: this.lifetime.totalErrors,
+			avgResponseTime: this.lifetime.totalRequests > 0 ? this.lifetime.totalDuration / this.lifetime.totalRequests : 0,
+			minResponseTime: this.lifetime.minDuration,
+			maxResponseTime: this.lifetime.maxDuration,
+			maxRequestsPerSecond: this.lifetime.maxRequestsPerSecond,
+			maxMemory: this.lifetime.memory,
+			cpu: this.lifetime.cpu,
+		};
+	}
+
+	/**
+	 * Get history buffer.
+	 * @returns {Bucket[]} The history buffer.
+	 */
+	getHistory() {
+		return this.history;
+	}
+}

package/src/util/trace.js

@@ -279,7 +279,8 @@ export const getFormattedMessage = (para) => {
 
 	// header
 	const url = typeof para.req?.originalUrl === 'string' && para.req.originalUrl.length > 0 ? ` on ${para.req.originalUrl}` : '';
-	const header = `${para.type.toUpperCase()} at ${timestamp.toUTCString()}${url}`;
+	const type = (para.type ?? 'trace').toUpperCase();
+	const header = `${type} at ${timestamp.toUTCString()}${url}`;
 	const output = {
 		html: `<h1>${header}</h1>`,
 		text: `\n\n${SEPARATOR_H1}\n== ${header}\n${SEPARATOR_H1}\n`,

package/src/util/traceManager.js

@@ -0,0 +1,68 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * @typedef {import('../admin/js/types.js').TraceEntry} TraceEntry
+ */
+
+class TraceManager {
+	constructor() {
+		this.enabled = false;
+		this.filename = 'trace.json.log';
+		this.maxEntries = 1000;
+	}
+
+	/**
+	 * Toggle tracing
+	 * @param {boolean} enabled - New state
+	 */
+	setEnabled(enabled) {
+		this.enabled = enabled;
+	}
+
+	/**
+	 * Is tracing enabled?
+	 * @returns {boolean} - The state
+	 */
+	isEnabled() {
+		return this.enabled;
+	}
+
+	/**
+	 * Add a trace entry
+	 * @param {object} entry - The trace entry
+	 */
+	addTrace(entry) {
+		if (!this.enabled) return;
+
+		try {
+			const line = JSON.stringify(entry) + '\n';
+			fs.appendFileSync(this.filename, line);
+		} catch (err) {
+			console.error('TraceManager: error writing trace', err);
+		}
+	}
+
+	/**
+	 * Clear all traces
+	 */
+	clear() {
+		try {
+			if (fs.existsSync(this.filename)) {
+				fs.truncateSync(this.filename, 0);
+			}
+		} catch (err) {
+			console.error('TraceManager: error clearing traces', err);
+		}
+	}
+
+	/**
+	 * Get the full path to the trace file
+	 * @returns {string} - The path
+	 */
+	getFilePath() {
+		return path.resolve(this.filename);
+	}
+}
+
+export const traceManager = new TraceManager();

package/src/version.js

@@ -2,4 +2,4 @@
  * Returns the current library version
  * @returns {string} - Version.
  */
-export const getVersion = () => '1.0.0';
+export const getVersion = () => '1.2.0';