web_plsql 0.18.0 → 1.2.0

package/src/server/config.js

@@ -17,6 +17,7 @@ export const showConfig = (config) => {
 	console.log(LINE);
 
 	console.log(`Server port:            ${config.port}`);
+	console.log(`Admin route:            ${config.adminRoute ?? '/admin'}${config.adminUser ? ' (authenticated)' : ''}`);
 	console.log(`Access log:             ${config.loggerFilename.length > 0 ? config.loggerFilename : ''}`);
 	console.log(`Upload file size limit: ${typeof config.uploadFileSizeLimit === 'number' ? `${config.uploadFileSizeLimit} bytes` : 'any'}`);
 

package/src/server/server.js

@@ -2,6 +2,8 @@ import debugModule from 'debug';
 const debug = debugModule('webplsql:server');
 import http from 'node:http';
 import https from 'node:https';
+import path from 'node:path';
+import {fileURLToPath} from 'node:url';
 import express from 'express';
 import cookieParser from 'cookie-parser';
 import compression from 'compression';
@@ -11,8 +13,13 @@ import {poolCreate, poolsClose} from '../util/oracle.js';
 import {handlerUpload} from '../handler/handlerUpload.js';
 import {handlerLogger} from '../handler/handlerLogger.js';
 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 {AdminContext} from './adminContext.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
 
 /**
  * @typedef {import('node:net').Socket} Socket
@@ -23,6 +30,14 @@ import {showConfig} from './config.js';
  * @typedef {import('oracledb').Pool} Pool
  * @typedef {import('../types.js').environmentType} environmentType
  * @typedef {import('../types.js').configType} configType
+ * @typedef {import('../handler/plsql/procedureNamed.js').argsType} argsType
+ */
+
+/**
+ * @typedef {import('express').RequestHandler & {
+ *   procedureNameCache: import('../util/cache.js').Cache<string>;
+ *   argumentCache: import('../util/cache.js').Cache<argsType>;
+ * }} ExtendedRequestHandler
  */
 
 /**
@@ -67,31 +82,82 @@ export const startServer = async (config, ssl) => {
 	debug('startServer: BEGIN', config, ssl);
 
 	const internalConfig = /** @type {configType} */ (z$configType.parse(config));
+	AdminContext.config = internalConfig;
 
 	showConfig(internalConfig);
 
 	// 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((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) {
 		app.use(handlerLogger(internalConfig.loggerFilename));
 	}
 
+	// 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));
+
 	// Serving static files
 	for (const i of internalConfig.routeStatic) {
 		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;
+	AdminContext.caches = [];
 
 	// Oracle pl/sql express middleware
 	for (const i of internalConfig.routePlSql) {
@@ -99,9 +165,56 @@ export const startServer = async (config, ssl) => {
 		const pool = await poolCreate(i.user, i.password, i.connectString);
 		connectionPools.push(pool);
 
-		app.use([`${i.route}/:name`, i.route], handlerWebPlSql(pool, i));
+		const handler = handlerWebPlSql(pool, i);
+
+		// Capture caches for admin console
+		AdminContext.caches.push({
+			poolName: i.route,
+			procedureNameCache: handler.procedureNameCache,
+			argumentCache: handler.argumentCache,
+		});
+
+		app.use([`${i.route}/:name`, i.route], (req, res, next) => {
+			const start = process.hrtime();
+			res.on('finish', () => {
+				const diff = process.hrtime(start);
+				const duration = diff[0] * 1000 + diff[1] / 1_000_000;
+				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);
@@ -126,6 +239,8 @@ export const startServer = async (config, ssl) => {
 	const shutdown = async () => {
 		debug('startServer: onShutdown');
 
+		AdminContext.statsManager.stop();
+
 		await poolsClose(connectionPools);
 
 		server.close(() => {
@@ -150,7 +265,13 @@ export const startServer = async (config, ssl) => {
 					resolve();
 				})
 				.on('error', (err) => {
-					console.error(err);
+					if ('code' in err) {
+						if (err.code === 'EADDRINUSE') {
+							err.message = `Port ${internalConfig.port} is already in use`;
+						} else if (err.code === 'EACCES') {
+							err.message = `Port ${internalConfig.port} requires elevated privileges`;
+						}
+					}
 					reject(err);
 				});
 		})

package/src/types.js

@@ -82,6 +82,9 @@ export const z$configPlSqlType = z.strictObject({
  * @property {configPlSqlType[]} routePlSql - The PL/SQL routes.
  * @property {number} [uploadFileSizeLimit] - Maximum size of each uploaded file in bytes or no limit if omitted.
  * @property {string} loggerFilename - name of the request logger filename or '' if not required.
+ * @property {string} [adminRoute] - Optional route for the admin console (defaults to /admin).
+ * @property {string} [adminUser] - Optional username for admin console basic auth.
+ * @property {string} [adminPassword] - Optional password for admin console basic auth.
  */
 export const z$configType = z.strictObject({
 	port: z.number(),
@@ -89,6 +92,9 @@ export const z$configType = z.strictObject({
 	routePlSql: z.array(z$configPlSqlType),
 	uploadFileSizeLimit: z.number().optional(),
 	loggerFilename: z.string(),
+	adminRoute: z.string().optional(),
+	adminUser: z.string().optional(),
+	adminPassword: z.string().optional(),
 });
 
 /**
@@ -127,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/cache.js

@@ -0,0 +1,123 @@
+/**
+ * @template T
+ * @typedef {{hitCount: number, value: T}} cacheEntryType
+ */
+
+/**
+ * Generic Cache class with LFU (Least Frequently Used) eviction policy.
+ * @template T
+ */
+export class Cache {
+	/**
+	 * @param {number} maxSize - Maximum number of entries in the cache.
+	 */
+	constructor(maxSize = 10000) {
+		/** @type {Map<string, cacheEntryType<T>>} */
+		this.cache = new Map();
+		this.maxSize = maxSize;
+		this.hits = 0;
+		this.misses = 0;
+	}
+
+	/**
+	 * Get an entry from the cache.
+	 * @param {string} key - The key.
+	 * @returns {T | undefined} - The value or undefined if not found.
+	 */
+	get(key) {
+		const entry = this.cache.get(key);
+		if (entry) {
+			entry.hitCount++;
+			this.hits++;
+			return entry.value;
+		}
+		this.misses++;
+		return undefined;
+	}
+
+	/**
+	 * Set an entry in the cache.
+	 * @param {string} key - The key.
+	 * @param {T} value - The value.
+	 */
+	set(key, value) {
+		// If updating an existing key, preserve its hitCount?
+		// Typically LFU implies resetting or keeping.
+		// For simplicity and avoiding complex aging, if we set it again, we reset hitCount or keep it?
+		// The requirement is "cache invalidation" (delete) or "cache loading" (set).
+		// If we overwrite, it's usually a new value. Let's reset hitCount to 0 for a fresh start or 1.
+
+		// Ensure we have space
+		if (this.cache.size >= this.maxSize && !this.cache.has(key)) {
+			this.prune();
+		}
+
+		this.cache.set(key, {hitCount: 0, value});
+	}
+
+	/**
+	 * Delete an entry from the cache.
+	 * @param {string} key - The key.
+	 */
+	delete(key) {
+		this.cache.delete(key);
+	}
+
+	/**
+	 * Clear the cache.
+	 */
+	clear() {
+		this.cache.clear();
+		this.hits = 0;
+		this.misses = 0;
+	}
+
+	/**
+	 * Prune the cache by removing the least frequently used entries.
+	 * Removes 10% of the cache size.
+	 */
+	prune() {
+		// Convert cache entries to an array
+		const entries = Array.from(this.cache.entries());
+
+		// Sort entries by hitCount in ascending order
+		entries.sort((a, b) => a[1].hitCount - b[1].hitCount);
+
+		// Remove the bottom 10%
+		const removeCount = Math.max(1, Math.floor(this.maxSize * 0.1));
+		const keysToRemove = entries.slice(0, removeCount).map(([key]) => key);
+
+		for (const key of keysToRemove) {
+			this.cache.delete(key);
+		}
+	}
+
+	/**
+	 * Get the size of the cache.
+	 * @returns {number} - The size.
+	 */
+	get size() {
+		return this.cache.size;
+	}
+
+	/**
+	 * Get all keys in the cache.
+	 * @returns {string[]} - The keys.
+	 */
+	keys() {
+		return Array.from(this.cache.keys());
+	}
+
+	/**
+	 * Get cache statistics.
+	 * @returns {{size: number, maxSize: number, hits: number, misses: number}} - The statistics.
+	 */
+	getStats() {
+		return {
+			size: this.cache.size,
+			maxSize: this.maxSize,
+			hits: this.hits,
+			misses: this.misses,
+		};
+	}
+}

package/src/util/jsonLogger.js

@@ -0,0 +1,47 @@
+import * as rotatingFileStream from 'rotating-file-stream';
+
+/**
+ * @typedef {object} LogEntry
+ * @property {string} timestamp - ISO string
+ * @property {'error'|'info'|'warning'} type - Log level
+ * @property {string} message - Error message
+ * @property {object} [req] - Request details
+ * @property {object} [details] - Additional details (stack, sql, etc)
+ */
+
+export class JsonLogger {
+	constructor(filename = 'error.json.log') {
+		this.stream = rotatingFileStream.createStream(filename, {
+			size: '10M', // rotate every 10 MegaBytes written
+			interval: '1d', // rotate daily
+			maxFiles: 10, // maximum number of rotated files to keep
+			compress: 'gzip', // compress rotated files
+		});
+	}
+
+	/**
+	 * Log an entry as NDJSON.
+	 * @param {LogEntry} entry - The entry to log.
+	 */
+	log(entry) {
+		try {
+			// Ensure timestamp exists
+			if (!entry.timestamp) {
+				entry.timestamp = new Date().toISOString();
+			}
+			const line = JSON.stringify(entry);
+			this.stream.write(line + '\n');
+		} catch (err) {
+			console.error('JsonLogger: Failed to write log', err);
+		}
+	}
+
+	/**
+	 * Close the stream.
+	 */
+	close() {
+		this.stream.end();
+	}
+}
+
+export const jsonLogger = new JsonLogger();

package/src/util/shutdown.js

@@ -12,8 +12,12 @@ export const installShutdown = (handler) => {
 	/*
 	 *	The 'unhandledRejection' event is emitted whenever a Promise is rejected and no error handler is attached to the promise within a turn of the event loop.
 	 */
-	process.on('unhandledRejection', (reason, p) => {
-		console.log('\nUnhandled promise rejection. Graceful shutdown...', reason, p);
+	process.on('unhandledRejection', (reason) => {
+		if (reason instanceof Error) {
+			console.error(`\n${reason.message}. Graceful shutdown...`);
+		} else {
+			console.error('\nUnhandled promise rejection. Graceful shutdown...', reason);
+		}
 		void handler();
 	});